} attribution
+ * @param {string} rootPath
+ * @param {string | null} weight
+ */
+export function routingFor(weights, attribution, rootPath, weight) {
+ return {
+ weight,
+ rootPath,
+ ownerOf: (sessionIds) => owningFile(sessionIds, weights, attribution),
+ };
+}
diff --git a/src/prompts/analysis-trace-only.md b/src/prompts/analysis-trace-only.md
index 7d31a156..8d0bbb6e 100644
--- a/src/prompts/analysis-trace-only.md
+++ b/src/prompts/analysis-trace-only.md
@@ -8,7 +8,7 @@ have prevented. This is the loss signal for a backward pass over the memory file
Each instruction has a stable id in [brackets]. Refer to instructions ONLY by these ids.
-{{INSTRUCTION_INDEX}}
+{{INSTRUCTION_INDEX}}{{ALSO_LOADED}}
## Project skills (load-on-trigger)
diff --git a/src/prompts/analysis.md b/src/prompts/analysis.md
index 040901ab..3bbda0ca 100644
--- a/src/prompts/analysis.md
+++ b/src/prompts/analysis.md
@@ -8,7 +8,7 @@ have prevented. This is the loss signal for a backward pass over the memory file
Each instruction has a stable id in [brackets]. Refer to instructions ONLY by these ids.
-{{INSTRUCTION_INDEX}}
+{{INSTRUCTION_INDEX}}{{ALSO_LOADED}}
## Project skills (load-on-trigger)
diff --git a/src/prompts/synthesis.md b/src/prompts/synthesis.md
index 68c31923..7a0becfd 100644
--- a/src/prompts/synthesis.md
+++ b/src/prompts/synthesis.md
@@ -22,8 +22,7 @@ paste the edited text into your reply; backpass measures what you changed in the
## Current memory file: {{MEMORY_PATH}}
Budget: {{CURRENT_TOKENS}} / {{BUDGET_TOKENS}} estimated always-loaded tokens
-({{BUDGET_STATE}}). The count is this file PLUS every skill's `description:` line;
-skill bodies are free until triggered.
+({{BUDGET_STATE}}). {{BUDGET_COUNT}}
Every always-loaded token is paid on every future session, forever, and instruction
following dilutes as the file grows. The budget is the constraint you optimize under.
diff --git a/src/proposal.js b/src/proposal.js
index af8179fa..96d24b06 100644
--- a/src/proposal.js
+++ b/src/proposal.js
@@ -1,9 +1,12 @@
+import path from "node:path";
+
import { renderHunkLines } from "./diff.js";
import { normalizeSourceLabel } from "./gap-ledger.js";
import { mixFromCounts } from "./interaction.js";
import { memoryTextHash } from "./memory.js";
import { editSkills, loadedCopies, parseFrontmatter, skillDescriptionTokens } from "./skills.js";
import { budgetGateKind, budgetStatus, estimateTokens } from "./tokens.js";
+import { rootOwnsGap } from "./nested.js";
import { isSkillFilePath, normalizeRecoveryLine, recoveredLineCounts } from "./workspace.js";
/**
@@ -295,18 +298,52 @@ export function renderChangesForPrompt(measured, memoryFile) {
.join("\n\n");
}
+function evidenceQuoteKey(item) {
+ return `${item.source || ""}\n${item.text || ""}`;
+}
+
+function ledgerIdsOfGap(gap) {
+ if (Array.isArray(gap?.ids) && gap.ids.length) return gap.ids.map(String).filter(Boolean);
+ return gap?.id ? [String(gap.id)] : [];
+}
+
/**
- * Validate the annotated, measured changes against the mechanical gates. Returns
- * `{ proposal, violations }`; the caller decides whether to re-prompt or fail loudly.
- *
- * `context.measured` is the workspace measurement (`measureWorkspace`); `rawResult` is
- * the model's annotation. Nothing textual is taken from the model: the hunks, their
- * deltas, the projected budget, and even whether an edit is an addition are measured.
+ * Ledger ids for gap clusters whose catalog quotes uniquely match this edit's evidence.
+ * Exact `source + text` against `summary.gaps` quotes - the same join
+ * `countedEvidenceProjects` uses. A quote that hits two clusters is not unique and is
+ * skipped, so a shared sentence cannot weld two gaps into one suppression identity.
+ */
+function uniqueMatchingGapIds(edit, summary) {
+ const ids = new Set();
+ for (const item of edit.evidence || []) {
+ const key = evidenceQuoteKey(item);
+ const matching = (summary?.gaps || []).filter((gap) =>
+ (gap.quotes || []).some((quote) => evidenceQuoteKey(quote) === key),
+ );
+ if (matching.length !== 1) continue;
+ for (const id of ledgerIdsOfGap(matching[0])) ids.add(id);
+ }
+ return [...ids];
+}
+
+/**
+ * Content hashes of the instruction units the memory-file hunks actually touch, using the
+ * same range intersection as removal evidence. Positional aliases shift whenever a unit
+ * is added above, so they never persist. Annotate `instructions` never widen this set.
*/
+function measuredInstructionIds(memoryHunks, memoryFile) {
+ const measured = new Set();
+ if (!memoryFile?.units) return [];
+ for (const hunk of memoryHunks) {
+ for (const unit of unitsRemovedBy(hunk, memoryFile)) measured.add(unit.hash);
+ }
+ return [...measured];
+}
+
function countedEvidenceProjects(edit, summary) {
- const quoted = new Set(edit.evidence.map((item) => `${item.source || ""}\n${item.text || ""}`));
+ const quoted = new Set(edit.evidence.map((item) => evidenceQuoteKey(item)));
const byGap = (summary?.gaps || [])
- .filter((gap) => gap.quotes?.some((quote) => quoted.has(`${quote.source || ""}\n${quote.text || ""}`)))
+ .filter((gap) => gap.quotes?.some((quote) => quoted.has(evidenceQuoteKey(quote))))
.map((gap) => gap.projects || 0);
// Gap clusters carry their own project count, but an edit that rewrites or reinforces
// an existing instruction quotes instruction-row evidence, which carries none. The fold
@@ -320,6 +357,14 @@ function countedEvidenceProjects(edit, summary) {
return Math.max(0, byQuoteSource.size, ...byGap);
}
+/**
+ * Validate the annotated, measured changes against the mechanical gates. Returns
+ * `{ proposal, violations }`; the caller decides whether to re-prompt or fail loudly.
+ *
+ * `context.measured` is the workspace measurement (`measureWorkspace`); `rawResult` is
+ * the model's annotation. Nothing textual is taken from the model: the hunks, their
+ * deltas, the projected budget, and even whether an edit is an addition are measured.
+ */
export function buildProposal(rawResult, context) {
const {
memoryFile,
@@ -334,6 +379,7 @@ export function buildProposal(rawResult, context) {
scope = null,
target = { kind: "surface" },
provenance = null,
+ routing = null,
} = context;
const violations = [];
@@ -581,6 +627,36 @@ export function buildProposal(rawResult, context) {
continue;
}
+ // With nested memory files named, a new instruction lands in the most specific file
+ // whose directory every session behind it worked in (`src/nested.js`). Measured from
+ // the edit's own quote sources, like the floor above; a rewrite or removal stays with
+ // the file whose text it changes.
+ if (routing && !preservesAlwaysLoaded(edit.kind) && hunks.some((h) => h.added > 0 && h.removed === 0)) {
+ const sessions = [
+ ...new Set(
+ edit.evidence.map((item) => summary?.sourceSessions?.[normalizeSourceLabel(item.source)]).filter(Boolean),
+ ),
+ ];
+ const sightings = edit.evidence.map((item) => ({
+ sessionId: summary?.sourceSessions?.[normalizeSourceLabel(item.source)],
+ quote: item.text,
+ }));
+ const owner = rootOwnsGap(sightings, routing.rootOwnedGaps)
+ ? routing.rootPath
+ : (routing.ownerOf(sessions) ?? routing.rootPath);
+ const here = routing.weight ?? routing.rootPath;
+ if (owner !== here) {
+ violations.push(
+ owner === routing.rootPath
+ ? `edit ${edit.id} ("${edit.title}") adds an instruction backed by sessions that did not all work ` +
+ `under ${path.posix.dirname(here)}/; cross-cutting evidence belongs in ${owner}, not ${here} - revert it`
+ : `edit ${edit.id} ("${edit.title}") adds an instruction backed only by sessions that worked under ` +
+ `${path.posix.dirname(owner)}/; it belongs in ${owner}, which its own pass trains - revert it`,
+ );
+ continue;
+ }
+ }
+
// A removal is measured the same way: a hunk that only deletes text, outside an
// extraction or move, deletes instructions - whatever the edit's kind says. Deleting
// an instruction needs the same corroboration adding one does, and only negatives the
@@ -638,6 +714,8 @@ export function buildProposal(rawResult, context) {
title: edit.title,
rationale: edit.rationale,
instructions: edit.instructions,
+ gapIds: uniqueMatchingGapIds(edit, summary),
+ instructionIds: measuredInstructionIds(memoryHunks, memoryFile),
evidence: edit.evidence,
transcripts: edit.transcripts,
...(evidenceProjects != null ? { projects: evidenceProjects } : {}),
@@ -740,7 +818,7 @@ export function buildProposal(rawResult, context) {
`applying every proposed edit leaves ${surfaceLabel} at ${budget.projected} tokens, ` +
`${budget.over} over the ${config.budgetTokens}-token budget`,
);
- } else if (gate === "shrink") {
+ } else if (gate === "shrink" && !(routing?.allowUnchangedRoot && accepted.length === 0)) {
violations.push(
`${surfaceLabel} is already ${budget.current - config.budgetTokens} tokens over the ` +
`${config.budgetTokens}-token budget, so this run must shrink it, but the proposed edits ` +
diff --git a/src/run-context.js b/src/run-context.js
index fe361d43..30f8cb78 100644
--- a/src/run-context.js
+++ b/src/run-context.js
@@ -4,6 +4,7 @@ import path from "node:path";
import { UserError } from "./logger.js";
import { pointerImportPath, resolveMemoryFiles } from "./memory.js";
+import { resolveNestedMemoryFiles } from "./nested.js";
import { selectedCorpusDigest, assertSourceCurrent } from "./provenance.js";
import { loadProjectSkills, resolveOverflowTarget } from "./skills.js";
import { userClaudeSkillsDir } from "./config.js";
@@ -26,7 +27,14 @@ export function inputInventory(ctx) {
allowExternal: userScope,
});
const skills = loadProjectSkills(repo.root, overflow.dir, config.skillsDirs || [], { exact: userScope });
- const approvedMemory = new Set(resolved.all.map((file) => path.resolve(file.absolute)));
+ const nestedFiles = resolveNestedMemoryFiles(repo.root, config);
+ const memoryFiles = [...resolved.all, ...nestedFiles.flatMap((weight) => weight.all)];
+ const primaryTargets = new Set(
+ [resolved.primary, ...nestedFiles.map((weight) => weight.file)]
+ .filter(Boolean)
+ .map((file) => fs.realpathSync(file.absolute)),
+ );
+ const approvedMemory = new Set(memoryFiles.map((file) => path.resolve(file.absolute)));
const entries = [];
const add = (kind, logicalPath, absolute, pointerTarget = null) => {
const target = fs.realpathSync(absolute);
@@ -36,13 +44,13 @@ export function inputInventory(ctx) {
const bytes = fs.readFileSync(absolute);
entries.push({ kind, path: logicalPath, target, bytes: bytes.length, digest: digest(bytes), pointerTarget });
};
- for (const file of resolved.all) {
+ for (const file of memoryFiles) {
const pointerTarget = pointerImportPath(file.text, { fromDir: path.dirname(file.absolute) });
if (ctx.flags["child-env"] === "restricted" && pointerTarget) {
if (!approvedMemory.has(path.resolve(pointerTarget)) || !fs.existsSync(pointerTarget)) {
throw new UserError(`unapproved memory pointer: ${file.path} -> ${pointerTarget}`);
}
- if (fs.realpathSync(pointerTarget) !== fs.realpathSync(resolved.primary.absolute)) {
+ if (!primaryTargets.has(fs.realpathSync(pointerTarget))) {
throw new UserError(`unapproved memory pointer: ${file.path} -> ${pointerTarget}`);
}
}
diff --git a/src/scope.js b/src/scope.js
index 3d75a5c7..a0d9267c 100644
--- a/src/scope.js
+++ b/src/scope.js
@@ -4,6 +4,7 @@ import path from "node:path";
import { expandHomePath, parseScopeKind, userStateDir } from "./config.js";
import { associate as associateProject, associateRemote, globToRegExp } from "./discovery/association.js";
+import { localPath } from "./discovery/paths.js";
import { UserError, info } from "./logger.js";
import { gitProjectIdentity, gitToplevel, listWorktrees, normalizeRemote } from "./repo.js";
import { assertPrivatePath } from "./state.js";
@@ -62,12 +63,16 @@ function realpathOrResolve(p) {
* tier 1 live git toplevel (passes --strict)
* tier 2 recorded remote, for deleted worktrees (codex, grok)
* tier 3 cwd string; excluded by --strict
+ *
+ * A cwd this machine cannot spell (`localPath`) is keyed by its recorded string, never
+ * resolved against the process cwd.
*/
export function associateUser(descriptor, { strict = false } = {}) {
const cwd = descriptor?.cwd;
if (!cwd) return null;
+ const local = localPath(cwd);
- const liveRoot = gitToplevel(cwd);
+ const liveRoot = local ? gitToplevel(local) : null;
if (liveRoot) {
return {
tier: 1,
@@ -91,7 +96,7 @@ export function associateUser(descriptor, { strict = false } = {}) {
if (strict) return null;
- const key = realpathOrResolve(cwd);
+ const key = local ? realpathOrResolve(local) : cwd;
return {
tier: 3,
confidence: "cwd",
@@ -227,6 +232,7 @@ function resolveProjectScope(repo, config, flags, cwd, home) {
explicitStateDir(flags?.["state-dir"], cwd, "project", repo.root, home) || path.join(repo.root, ".backpass"),
modelCwd: repo.root,
memoryFiles: config.memoryFiles,
+ nestedMemoryFiles: config.nestedMemoryFiles || [],
skillDirs: config.skillsDirs || [],
skillSearchPaths: (config.skillSearchPaths || []).map((p) => expandUserPath(p)),
overflowDir: config.skillsDir,
@@ -287,9 +293,14 @@ function resolveUserScope(
};
const normalizeProjects = (transcripts) => {
for (const transcript of transcripts) {
- if (transcript.host || transcript.sourceHostAlias || transcript.association?.tier !== 3 || !transcript.cwd)
+ if (
+ transcript.host ||
+ transcript.sourceHostAlias ||
+ transcript.association?.tier !== 3 ||
+ !localPath(transcript.cwd)
+ )
continue;
- const cwdPath = realpathOrResolve(transcript.cwd);
+ const cwdPath = realpathOrResolve(localPath(transcript.cwd));
const match = [...knownWorktrees.entries()]
.filter(([worktree]) => cwdPath === worktree || cwdPath.startsWith(`${worktree}${path.sep}`))
.sort(([a], [b]) => b.length - a.length)[0];
diff --git a/src/state.js b/src/state.js
index e965333a..7e1b5372 100644
--- a/src/state.js
+++ b/src/state.js
@@ -1,4 +1,5 @@
import fs from "node:fs";
+import os from "node:os";
import path from "node:path";
import crypto from "node:crypto";
@@ -22,9 +23,12 @@ export const STATE_EXCLUDE_LINE = `${STATE_DIRNAME}/`;
* evidence-summary.json folded evidence (stage 2)
* proposal.json latest parseable tier-2 synthesis; absent if none was produced (stage 3)
* rejections.json edits the human rejected, and the evidence weight behind them
+ * (hunk key always; add/rewrite/remove also remember gap and
+ * instruction identities so a reworded proposal stays suppressed)
* gap-ledger.json gap observations by gap and session, accumulated across runs (src/gap-ledger.js)
* agent-probe-cache.json TTL'd availability/auth verdicts per agent|model (src/agents.js)
* prompts/ the exact prompts of the last run, one file per model turn
+ * raw/ a SQLite-store session's events while its analysis call runs (src/analyze.js)
* synthesis/ the staging copy the synthesis agent edits natively (src/workspace.js)
* apply/ the rendered Lavish apply surface
*/
@@ -67,8 +71,20 @@ export class State {
`could not secure state directory ${this.root} as mode ${this.dirMode.toString(8)}: ${err.message}`,
);
}
+ // Windows has no POSIX mode bits: chmod only toggles the read-only attribute and stat
+ // always reports 0o666, so this check cannot pass there. On Windows the directory's
+ // privacy comes from the NTFS ACL it inherits from the user profile instead - but only
+ // when the directory actually resolves under that profile (e.g. XDG_CONFIG_HOME left at
+ // its default). A redirected location (a synced or network folder) inherits no such ACL,
+ // so that case proceeds with a warning instead of an unverifiable pass or a hard failure.
const actualMode = fs.statSync(this.root).mode & 0o777;
- if (actualMode !== this.dirMode) {
+ if (process.platform === "win32") {
+ if (!isInsideUserProfile(this.root)) {
+ warn(
+ `state directory ${this.root} is outside your Windows user profile; its privacy can't be verified there (it won't inherit the profile's ACL) - restrict access to it yourself`,
+ );
+ }
+ } else if (actualMode !== this.dirMode) {
throw new UserError(
`could not secure state directory ${this.root} as mode ${this.dirMode.toString(8)} (got ${actualMode.toString(8)})`,
);
@@ -318,6 +334,13 @@ function pathEntryExists(file) {
}
}
+/** Windows paths are case-insensitive, so compare resolved paths lowercased. */
+function isInsideUserProfile(dir) {
+ const resolvedDir = path.resolve(dir).toLowerCase();
+ const home = path.resolve(os.homedir()).toLowerCase();
+ return resolvedDir === home || resolvedDir.startsWith(`${home}${path.sep}`);
+}
+
export function safeFileName(id) {
return String(id)
.replace(/[^A-Za-z0-9._-]/g, "_")
@@ -336,7 +359,7 @@ function migrateEvidenceRecord(record, transcript, identity) {
};
}
-export const ANALYSIS_INDEX_VERSION = 5;
+export const ANALYSIS_INDEX_VERSION = 6;
/**
* Cache key for a transcript's analysis. Source revision, evidence policy, distiller,
@@ -374,10 +397,32 @@ export function isEvidenceFresh(evidence, transcript, memoryHash, route = null)
return evidence.key === evidenceKey(transcript, memoryHash, route ?? evidence.route ?? null);
}
+/** Optional reject-reason tokens the apply surface may attach. Unknown tokens are dropped. */
+export const REJECT_REASONS = ["wrong-evidence", "already-covered", "too-narrow", "too-broad", "disagree"];
+
+const IDENTITY_KINDS = new Set(["add", "rewrite", "remove"]);
+
+export function normalizeRejectReason(reason) {
+ const token = String(reason || "")
+ .trim()
+ .toLowerCase();
+ return REJECT_REASONS.includes(token) ? token : undefined;
+}
+
+function intersects(left, right) {
+ if (!Array.isArray(left) || !Array.isArray(right) || !left.length || !right.length) return false;
+ const other = new Set(right);
+ return left.some((id) => other.has(id));
+}
+
/**
* A rejected edit stays rejected until materially new evidence arrives - the design's
* replacement for a DEFER button (captain tweak 3). "Materially new" means the edit is
- * backed by strictly more transcripts than when it was turned down.
+ * backed by strictly more transcripts than when it was turned down. Add, rewrite, and
+ * remove also match on measured gap and instruction identities, so a later proposal of
+ * the same decision in different bytes stays suppressed. Extract and move stay hunk-key
+ * only: repositioning or paying for a skill is not the same decision as changing instruction
+ * text. A reason code never revives an edit, and neither does a model-reported count.
*/
export function rejectionKey(edit) {
let body;
@@ -397,19 +442,36 @@ export function rejectionKey(edit) {
}
export function isSuppressedByRejection(edit, rejections) {
- const prior = rejections.entries[rejectionKey(edit)];
- if (!prior) return false;
- return (edit.transcripts || 0) <= (prior.transcripts || 0);
+ const entries = rejections?.entries || {};
+ const transcripts = edit.transcripts || 0;
+ const prior = entries[rejectionKey(edit)];
+ if (prior && transcripts <= (prior.transcripts || 0)) return true;
+ if (!IDENTITY_KINDS.has(edit.kind)) return false;
+ for (const remembered of Object.values(entries)) {
+ if (remembered.kind !== edit.kind || remembered.file !== edit.file) continue;
+ if (transcripts > (remembered.transcripts || 0)) continue;
+ if (intersects(edit.gapIds, remembered.gapIds) || intersects(edit.instructionIds, remembered.instructionIds)) {
+ return true;
+ }
+ }
+ return false;
}
-export function recordRejection(edit, rejections, at = new Date().toISOString(), provenance = null) {
- rejections.entries[rejectionKey(edit)] = {
+export function recordRejection(edit, rejections, at = new Date().toISOString(), reason, provenance = null) {
+ const normalized = normalizeRejectReason(reason);
+ const entry = {
kind: edit.kind,
file: edit.file,
title: edit.title,
transcripts: edit.transcripts || 0,
rejectedAt: at,
...(provenance ? { provenance } : {}),
+ ...(Array.isArray(edit.gapIds) && edit.gapIds.length ? { gapIds: [...edit.gapIds] } : {}),
+ ...(Array.isArray(edit.instructionIds) && edit.instructionIds.length
+ ? { instructionIds: [...edit.instructionIds] }
+ : {}),
+ ...(normalized ? { reason: normalized } : {}),
};
+ rejections.entries[rejectionKey(edit)] = entry;
return rejections;
}
diff --git a/src/synthesize.js b/src/synthesize.js
index 969e84ce..350a41fd 100644
--- a/src/synthesize.js
+++ b/src/synthesize.js
@@ -86,11 +86,20 @@ const EDIT_EMPTY_VIOLATION =
* (`buildProposal`). Framing one number and gating another would set the model up to
* fail a gate it was never told about.
*/
-function budgetRule(memoryFile, config, maxEdits, descriptionTokens = 0) {
+function budgetRule(memoryFile, config, maxEdits, descriptionTokens = 0, { extraction = true } = {}) {
const remaining = config.budgetTokens - memoryFile.tokens - descriptionTokens;
const counted = descriptionTokens
? ` The budget counts this file plus every skill description line (${descriptionTokens} tok of descriptions today); skill bodies stay free until triggered.`
: "";
+ if (remaining <= 0 && !extraction) {
+ return (
+ `This file is ALREADY ${Math.abs(remaining)} tokens OVER its budget, so this run is a SHRINK PLAN. ` +
+ `You are NOT expected to reach ${config.budgetTokens} tokens in one run - the ${maxEdits}-edit cap ` +
+ `makes that impossible and later runs continue the work. What is required is real progress: the edit ` +
+ `set MUST be net-negative. Remove what has its harm-evidence floor, tighten what the evidence ` +
+ `supports rewriting, and make any addition name the removal that pays for it.`
+ );
+ }
if (remaining <= 0) {
return (
`The always-loaded surface is ALREADY ${Math.abs(remaining)} tokens OVER budget, so this run is a SHRINK ` +
@@ -109,7 +118,7 @@ function budgetRule(memoryFile, config, maxEdits, descriptionTokens = 0) {
if (remaining < config.budgetTokens * 0.15) {
return (
`Only ${remaining} tokens of headroom remain. Treat this as zero-sum: every addition must ` +
- `name its offsetting removal or skill extraction. The post-edit always-loaded surface must stay at or below ` +
+ `name its offsetting removal${extraction ? " or skill extraction" : ""}. The post-edit always-loaded surface must stay at or below ` +
`${config.budgetTokens} tokens.` +
counted
);
@@ -127,14 +136,17 @@ function budgetState(memoryFile, config, descriptionTokens = 0) {
return "within budget";
}
-function renderRejections(rejections) {
+export function renderRejections(rejections) {
const entries = Object.values(rejections.entries || {});
if (!entries.length) return "(none)";
return entries
- .map(
- (e) =>
- `- [${e.kind}] ${e.title} (rejected ${e.rejectedAt.slice(0, 10)} with ${e.transcripts} session(s) of evidence)`,
- )
+ .map((e) => {
+ const bits = [`rejected ${e.rejectedAt.slice(0, 10)} with ${e.transcripts} session(s) of evidence`];
+ const ids = [...(e.gapIds || []), ...(e.instructionIds || [])];
+ if (ids.length) bits.push(`ids ${ids.join(", ")}`);
+ if (e.reason) bits.push(`reason ${e.reason}`);
+ return `- [${e.kind}] ${e.title} (${bits.join("; ")})`;
+ })
.join("\n");
}
@@ -195,6 +207,16 @@ function assertRepoUntouched(repo, before, workspaceRoot) {
}
function targetRule(target, memoryPath, skillsDir, stagedTargetPath = null, unstageable = []) {
+ if (target.nested) {
+ const dir = path.posix.dirname(memoryPath);
+ return (
+ `0. **This run trains the nested memory file \`./${memoryPath}\` only.** Harnesses load it on top of ` +
+ `the root memory file, and only when a session works under \`${dir}/\`; every session in the evidence ` +
+ `below worked there. Skills belong to the root surface: do not create, extend, or edit a skill, and do ` +
+ `not extract - the extraction rules and the placement table below do not apply to this run. A lesson ` +
+ `that is not specific to \`${dir}/\` belongs in the root memory file, which its own pass trains.\n`
+ );
+ }
if (target.kind === "skill") {
return (
`0. **This run targets \`./${stagedTargetPath || workspacePathFor(target.path)}\` only.** It is the one staged file. ` +
@@ -222,7 +244,16 @@ function targetRule(target, memoryPath, skillsDir, stagedTargetPath = null, unst
* Everything the edit and annotation turns need: prompt values, the `buildProposal`
* context, and the overflow target.
*/
-function synthesisSetup({ memoryFile, summary, config, repo, harnessCounts, scope = null, provenance = null }) {
+function synthesisSetup({
+ memoryFile,
+ summary,
+ config,
+ repo,
+ harnessCounts,
+ scope = null,
+ provenance = null,
+ routing = null,
+}) {
const state = config.state;
const rejections = state.readRejections();
if (provenance?.source.kind === "external") {
@@ -233,13 +264,20 @@ function synthesisSetup({ memoryFile, summary, config, repo, harnessCounts, scop
);
}
const userScope = scope?.kind === "user";
+ // A nested memory file is trained on its own: skills belong to the root surface, so
+ // none is staged, billed, or offered as an extraction target (`src/nested.js`).
+ const nested = config.target?.nested === true;
const overflow = resolveOverflowTarget(repo.root, config.skillsDir, {
claudeSkillsDir: userScope ? userClaudeSkillsDir() : undefined,
allowExternal: userScope,
});
- for (const w of overflow.warnings) warn(w);
- const skillDirs = resolveProjectSkillDirs(repo.root, overflow.dir, config.skillsDirs || [], { exact: userScope });
- const skillFiles = loadProjectSkills(repo.root, overflow.dir, config.skillsDirs || [], { exact: userScope });
+ if (!nested) for (const w of overflow.warnings) warn(w);
+ const skillDirs = nested
+ ? []
+ : resolveProjectSkillDirs(repo.root, overflow.dir, config.skillsDirs || [], { exact: userScope });
+ const skillFiles = nested
+ ? []
+ : loadProjectSkills(repo.root, overflow.dir, config.skillsDirs || [], { exact: userScope });
// `skillSearchPaths` rides `skillDirs` for awareness (config.js), but staging must
// refuse it unconditionally - unlike the rest of `skillDirs`, it is never writable, in
// no scope, so `prepareWorkspace` needs the raw roots to enforce that independently of
@@ -253,7 +291,7 @@ function synthesisSetup({ memoryFile, summary, config, repo, harnessCounts, scop
const common = {
MEMORY_PATH: workspacePathFor(memoryFile.path),
- BUDGET_RULE: budgetRule(memoryFile, config, maxEdits, descriptionTokens),
+ BUDGET_RULE: budgetRule(memoryFile, config, maxEdits, descriptionTokens, { extraction: !nested }),
MAX_EDITS: String(maxEdits),
MIN_GAP_EVIDENCE: String(config.minGapEvidence),
};
@@ -270,6 +308,7 @@ function synthesisSetup({ memoryFile, summary, config, repo, harnessCounts, scop
skillFiles,
target,
provenance,
+ routing,
};
const promptDir = path.join(state.root, "prompts");
@@ -283,6 +322,7 @@ function synthesisSetup({ memoryFile, summary, config, repo, harnessCounts, scop
skillFiles,
searchPathRoots,
target,
+ nested,
descriptionTokens,
maxEdits,
common,
@@ -512,6 +552,7 @@ export async function synthesizeProposal({
runNote = "",
scope = null,
provenance = null,
+ routing = null,
}) {
config.state.clearProposal();
const harnessCounts = harnessCountsOf(transcripts);
@@ -523,6 +564,7 @@ export async function synthesizeProposal({
skillFiles,
searchPathRoots,
target,
+ nested,
descriptionTokens,
maxEdits,
common,
@@ -536,6 +578,7 @@ export async function synthesizeProposal({
harnessCounts,
scope,
provenance,
+ routing,
});
// Staging holds only the write surface: every skill on a surface run, none of them on
@@ -588,7 +631,12 @@ export async function synthesizeProposal({
BUDGET_STATE: budgetState(memoryFile, config, descriptionTokens),
INSTRUCTION_INDEX: renderInstructionIndex(memoryFile),
SKILLS_DIR: stagedSkillsDir,
- SKILL_INDEX: renderSkillIndex(stagedSkillFiles),
+ SKILL_INDEX: nested
+ ? "(skills belong to the root surface; a nested memory file run does not edit them)"
+ : renderSkillIndex(stagedSkillFiles),
+ BUDGET_COUNT: nested
+ ? "The count is this file alone: it loads on top of the root memory\nfile, which has a budget of its own."
+ : "The count is this file PLUS every skill's `description:` line;\nskill bodies are free until triggered.",
EVIDENCE: renderEvidenceForPrompt(summary),
REJECTIONS: renderRejections(rejections),
};
@@ -602,7 +650,9 @@ export async function synthesizeProposal({
// (design note above `assertRepoUntouched`). It stays in the fingerprint so a change
// there still fails the run loudly.
const fingerprint = repoFingerprint(repo, [
- memoryFile.path,
+ ...new Set(
+ [memoryFile.path, ...config.memoryFiles, ...(config.nestedMemoryFiles || []), routing?.rootPath].filter(Boolean),
+ ),
...skillFiles
.filter((skill) => {
const reason = readOnlyReason(skill.path);
@@ -623,7 +673,7 @@ export async function synthesizeProposal({
const pick = await config.agents.resolve("synthesis");
info(
- `${color.cyan("·")} synthesizing with ${pick.agent}` +
+ `${color.cyan("·")} synthesizing ${nested ? `${memoryFile.path} (nested) ` : ""}with ${pick.agent}` +
`${pick.model ? ` (${pick.model})` : ""}` +
`${pick.effort ? ` effort=${pick.effort}` : ""}`,
);
diff --git a/src/target.js b/src/target.js
index 8b35d7ef..b5936596 100644
--- a/src/target.js
+++ b/src/target.js
@@ -84,6 +84,12 @@ export function resolveTarget(spec, scope) {
}
return { kind: "skill", path: skill.path, name: skill.name };
}
+ if ((scope.nestedMemoryFiles || []).includes(normalized)) {
+ throw new UserError(
+ `--target ${spec} is a nested memory file, which a run over the whole surface trains`,
+ "run backpass without --target: each nested memory file learns from the sessions that worked under its directory",
+ );
+ }
const memoryList = scope.memoryFiles.length ? scope.memoryFiles.join(", ") : "(none configured)";
const skillList = skills.length ? skills.map((skill) => skill.name).join(", ") : "(none)";
throw new UserError(
diff --git a/src/tui/render.js b/src/tui/render.js
index 17a0b310..d1813b21 100644
--- a/src/tui/render.js
+++ b/src/tui/render.js
@@ -339,7 +339,7 @@ function discoverDetail(state, theme, width, spin) {
const scanned = `${formatCount(h.scanned)} sessions`;
const fresh = h.newCount > 0 || h.scanned > 0 ? ` · ${formatCount(h.newCount)} new` : "";
const self = h.self > 0 ? ` · ${formatCount(h.self)} self` : "";
- const query = harness === "opencode" || harness === "hermes" ? "1 sqlite query" : `${scanned}${fresh}${self}`;
+ const query = harness === "opencode" || harness === "hermes" ? "sqlite store" : `${scanned}${fresh}${self}`;
activity = theme.paint(fitPlain(query, activityWidth), "dim");
count = padVis(
`${theme.paint(formatCount(h.matched), "text", { bold: true })} ${theme.paint("this repo", "faint")}`,
diff --git a/templates/apply.html b/templates/apply.html
index 95dd7da0..4e70c3a7 100644
--- a/templates/apply.html
+++ b/templates/apply.html
@@ -391,6 +391,11 @@
margin-right: 6px;
vertical-align: middle;
}
+ .gauge-nested .gauge-head {
+ margin-top: 18px;
+ padding-top: 14px;
+ border-top: 1px dashed var(--line-soft);
+ }
/* ---------- section titles ---------- */
.sect {
@@ -641,6 +646,34 @@
color: var(--reject);
background: var(--reject-dim);
}
+ .reject-reasons {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 6px;
+ margin-top: 8px;
+ }
+ .reject-reasons[hidden] {
+ display: none !important;
+ }
+ .reason-chip {
+ font-family: var(--mono);
+ font-size: 10.5px;
+ letter-spacing: 0.06em;
+ padding: 4px 9px;
+ background: transparent;
+ border: 1px solid var(--line);
+ color: var(--faint);
+ cursor: pointer;
+ }
+ .reason-chip:hover {
+ border-color: var(--dim);
+ color: var(--text);
+ }
+ .reason-chip.on {
+ border-color: var(--reject);
+ color: var(--reject);
+ background: var(--reject-dim);
+ }
.skillprev {
border: 1px solid var(--line-soft);
@@ -794,7 +827,7 @@ backpass apply
Funnel · this run
+ >Funnel · this run
existing instructionmissing instructionbackpass apply
projected after apply
+
@@ -856,6 +890,8 @@
Notes from this run
var edits = P.edits || [];
var budget = P.budget || { current: 0, capTokens: 0 };
var decisions = {};
+ var rejectReasons = {};
+ var REJECT_REASONS = ["wrong-evidence", "already-covered", "too-narrow", "too-broad", "disagree"];
edits.forEach(function (e) {
decisions[e.id] = "accepted";
});
@@ -923,7 +959,11 @@ Notes from this run
// gate. The three parts are the only outcomes a cluster can have.
var distinctGaps = eligible + reportOnly + singletons;
var candidates = s.instructionsWithNegatives;
- var adds = edits.filter(function (e) {
+ // The funnel is the root file's run; a nested file's edits are counted on its gauge.
+ var rootEdits = edits.filter(function (e) {
+ return !e.nestedMemoryFile;
+ });
+ var adds = rootEdits.filter(function (e) {
return (
e.hunks.length > 0 &&
e.hunks.every(function (hunk) {
@@ -934,7 +974,7 @@ Notes from this run
return {
floor: Number((P.config || {}).minGapEvidence) || 2,
projectFloor: Number((P.config || {}).minGapProjects) || 1,
- cap: Number((P.config || {}).maxEditsPerRun) || edits.length,
+ cap: Number((P.config || {}).maxEditsPerRun) || rootEdits.length,
findings: [(s.positive || 0) + (s.negative || 0), s.gapSightings],
followed: s.positive || 0,
// A finding is not a candidate: several negatives can name one instruction,
@@ -949,7 +989,7 @@ Notes from this run
leftAlone: s.instructionsLeftAlone || 0,
leftAloneMaxSessions: s.leftAloneMaxSessions,
suppressed: s.instructionsSuppressed || 0,
- proposed: [edits.length - adds, adds],
+ proposed: [rootEdits.length - adds, adds],
sighted: s.gapSightings,
eligible: eligible,
dropped: singletons,
@@ -1008,6 +1048,9 @@ Notes from this run
host.appendChild(line);
}
var funnelNote = null;
+ if ((P.nested || []).length) {
+ document.getElementById("funnel-scope").textContent = " · " + (P.memoryFile.path || "");
+ }
var funnel = funnelCounts();
if (funnel) {
var bars = document.getElementById("funnel-bars");
@@ -1123,10 +1166,41 @@ Notes from this run
document.getElementById("cap-label").textContent = fmt(budget.capTokens) + " tok cap";
document.getElementById("gauge-now").style.width = pct(budget.current, budget.capTokens) + "%";
+ // A nested memory file has a budget of its own: one gauge per file that has edits.
+ var nestedGauges = (P.nested || [])
+ .filter(function (n) {
+ return (n.edits || []).length > 0;
+ })
+ .map(function (n) {
+ var head = el("div", "gauge-head");
+ head.appendChild(el("span", "t", "Nested budget · " + n.memoryFile.path + " · loads under " + n.dir + "/"));
+ var readout = el("span", "readout num");
+ head.appendChild(readout);
+ var gauge = el("div", "gauge");
+ var now = el("div", "fill-now");
+ now.style.width = pct(n.budget.current, n.budget.capTokens) + "%";
+ var after = el("div", "fill-after");
+ gauge.appendChild(now);
+ gauge.appendChild(after);
+ gauge.appendChild(el("div", "cap"));
+ var box = document.getElementById("gauge-nested");
+ box.appendChild(head);
+ box.appendChild(gauge);
+ return { entry: n, readout: readout, after: after };
+ });
+
// ---- edit cards ----
var host = document.getElementById("edits");
+ var editCap =
+ ((P.config || {}).maxEditsPerRun || 0) +
+ (P.nested || []).reduce(function (sum, n) {
+ return sum + (n.maxEdits || 0);
+ }, 0);
document.getElementById("editcount").textContent =
- edits.length + " of " + ((P.config || {}).maxEditsPerRun || edits.length) + " (learning-rate cap)";
+ edits.length +
+ " of " +
+ (editCap || edits.length) +
+ ((P.nested || []).length ? " (learning-rate cap, per file)" : " (learning-rate cap)");
if (!edits.length) {
var eligibleWithoutEdits = Number((P.stats || {}).gapClusters) || 0;
@@ -1165,7 +1239,11 @@ Notes from this run
);
}
head.appendChild(
- edit.targetsMemoryFile ? deltaNode("memory", delta) : deltaNode("on trigger", delta - descriptionDelta),
+ edit.nestedMemoryFile
+ ? deltaNode(edit.nestedMemoryFile, delta)
+ : edit.targetsMemoryFile
+ ? deltaNode("memory", delta)
+ : deltaNode("on trigger", delta - descriptionDelta),
);
if (descriptionDelta) head.appendChild(deltaNode("description (always-loaded)", descriptionDelta));
card.appendChild(head);
@@ -1230,6 +1308,8 @@ Notes from this run
}
var decide = el("div", "decide");
+ var reasons = el("div", "reject-reasons");
+ reasons.hidden = true;
["accept", "reject"].forEach(function (choice) {
var btn = el("button", choice === "accept" ? "on-accept" : "", choice.toUpperCase());
btn.type = "button";
@@ -1240,11 +1320,41 @@ Notes from this run
b.className = "";
});
btn.className = "on-" + choice;
+ if (choice === "accept") {
+ delete rejectReasons[edit.id];
+ reasons.hidden = true;
+ Array.prototype.forEach.call(reasons.children, function (chip) {
+ chip.className = "reason-chip";
+ });
+ } else {
+ reasons.hidden = false;
+ }
recompute();
});
decide.appendChild(btn);
});
+ REJECT_REASONS.forEach(function (token) {
+ var chip = el("button", "reason-chip", token);
+ chip.type = "button";
+ chip.setAttribute("data-reason", token);
+ chip.addEventListener("click", function () {
+ if (decisions[edit.id] !== "rejected") return;
+ if (rejectReasons[edit.id] === token) {
+ delete rejectReasons[edit.id];
+ chip.className = "reason-chip";
+ } else {
+ rejectReasons[edit.id] = token;
+ Array.prototype.forEach.call(reasons.children, function (other) {
+ other.className = "reason-chip";
+ });
+ chip.className = "reason-chip on";
+ }
+ recompute();
+ });
+ reasons.appendChild(chip);
+ });
body.appendChild(decide);
+ body.appendChild(reasons);
card.appendChild(body);
host.appendChild(card);
});
@@ -1361,6 +1471,26 @@ Notes from this run
after.style.width = pct(tok, budget.capTokens) + "%";
after.className = "fill-after" + (over ? " over" : "");
+ nestedGauges.forEach(function (g) {
+ var nestedTok = g.entry.budget.current;
+ edits.forEach(function (e) {
+ if (decisions[e.id] === "accepted" && e.nestedMemoryFile === g.entry.memoryFile.path) {
+ nestedTok += e.deltaTokens || 0;
+ }
+ });
+ var nestedCap = g.entry.budget.capTokens;
+ var nestedOver =
+ g.entry.budget.current > nestedCap ? nestedTok >= g.entry.budget.current : nestedTok > nestedCap;
+ g.readout.textContent = "";
+ g.readout.appendChild(
+ document.createTextNode("now " + fmt(g.entry.budget.current) + " tok -> if accepted "),
+ );
+ g.readout.appendChild(el("b", nestedOver ? "over" : null, fmt(nestedTok) + " tok"));
+ g.readout.appendChild(document.createTextNode(" / " + fmt(nestedCap) + " cap"));
+ g.after.style.width = pct(nestedTok, nestedCap) + "%";
+ g.after.className = "fill-after" + (nestedTok > nestedCap ? " over" : "");
+ });
+
var proj = document.getElementById("projline");
proj.textContent = "";
proj.appendChild(document.createTextNode("projected: "));
@@ -1377,7 +1507,9 @@ Notes from this run
document.getElementById("btn-apply").addEventListener("click", function () {
var vector = edits
.map(function (e) {
- return e.id + "=" + decisions[e.id];
+ var value = decisions[e.id];
+ if (value === "rejected" && rejectReasons[e.id]) value += ":" + rejectReasons[e.id];
+ return e.id + "=" + value;
})
.join(" ");
var message = "BACKPASS_DECISIONS " + vector;
@@ -1385,7 +1517,7 @@ Notes from this run
window.lavish.queuePrompt(message, {
tag: "choice",
text: vector,
- data: { question: "backpass-apply-decisions", decisions: decisions },
+ data: { question: "backpass-apply-decisions", decisions: decisions, rejectReasons: rejectReasons },
queueKey: "backpass-apply-decisions",
});
this.textContent = "QUEUED - SEND FROM THE PANEL";
diff --git a/test/acpx-exec-timeout.test.js b/test/acpx-exec-timeout.test.js
index 05ed7975..f692320b 100644
--- a/test/acpx-exec-timeout.test.js
+++ b/test/acpx-exec-timeout.test.js
@@ -35,7 +35,11 @@ if (argv.includes("config") && argv.includes("show")) {
// Session management calls succeed silently, as acpx's do.
if (argv.includes("sessions") || argv.includes("set") || argv.includes("set-mode")) process.exit(0);
// The one model turn: an exec one-shot or a session prompt, both carrying --file.
-if (argv.includes("--file") && process.env.FAKE_ACPX_MODE === "budget-blank") {
+if (argv.includes("--file") && process.env.FAKE_ACPX_MODE === "timeout-exit") {
+ // acpx >= 0.19 ends a turn at its --timeout budget itself and exits EXIT_CODES.TIMEOUT.
+ process.stderr.write(process.env.FAKE_ACPX_STDERR || "");
+ process.exit(3);
+} else if (argv.includes("--file") && process.env.FAKE_ACPX_MODE === "budget-blank") {
const budgetMs = Number(argv[argv.indexOf("--timeout") + 1]) * 1000;
if (Number.isFinite(budgetMs) && budgetMs > 0) setTimeout(() => process.exit(0), budgetMs);
else process.exit(0);
@@ -48,7 +52,7 @@ fs.chmodSync(fakeAcpx, 0o755);
process.env.BACKPASS_ACPX_BIN = fakeAcpx;
process.env.FAKE_ACPX_MODE = "budget-blank";
-const { AcpxError, assertNonEmptyOutput, classifyAcpxFailure, execOneShot, sessionPrompt } =
+const { ACPX_EXIT_TIMEOUT, AcpxError, assertNonEmptyOutput, classifyAcpxFailure, execOneShot, sessionPrompt } =
await import("../src/acpx.js");
test.after(() => {
@@ -139,3 +143,57 @@ test("a blank session prompt clearly short of the budget keeps the empty-output
process.env.FAKE_ACPX_MODE = "budget-blank";
}
});
+
+// acpx >= 0.19 no longer exits clean at its budget: it ends the turn and exits with its
+// TIMEOUT code (3). Read generically, a pinned agent's long prompt stopped a whole run
+// as "failed unexpectedly (exit 3)"; named a timeout, it fails only that transcript.
+for (const [scenario, stderr, detail] of [
+ ["empty stderr", "", ""],
+ ["accounting only", "[acpx] tokens: input=0 output=0 total=0\n", ""],
+ ["adapter error", "\nadapter startup timed out\nextra detail\n", ": adapter startup timed out"],
+ [
+ "quiet-mode error after accounting",
+ "[acpx] tokens: input=0 output=0 total=0\n[acpx] error: TIMEOUT GEMINI_ACP_STARTUP_TIMEOUT adapter startup timed out\n",
+ ": [acpx] error: TIMEOUT GEMINI_ACP_STARTUP_TIMEOUT adapter startup timed out",
+ ],
+ [
+ "noise before adapter error",
+ "[acpx] tokens: input=0 output=0 total=0\n[acpx] session closed\nadapter startup timed out\nextra detail\n",
+ ": adapter startup timed out",
+ ],
+]) {
+ test(`acpx timeout exit identifies both model-turn routes without noise: ${scenario}`, async () => {
+ process.env.FAKE_ACPX_MODE = "timeout-exit";
+ process.env.FAKE_ACPX_STDERR = stderr;
+ try {
+ const named = (label) => (err) => {
+ assert.ok(err instanceof AcpxError, String(err));
+ assert.equal(err.message, `acpx codex ${label} ended at its own timeout (exit 3)${detail}`);
+ assert.equal(err.timedOut, true);
+ assert.equal(err.code, ACPX_EXIT_TIMEOUT);
+ assert.equal(err.stderr, stderr);
+ assert.equal(classifyAcpxFailure(err), null, "a timeout on real work never falls through the ladder");
+ return true;
+ };
+ await assert.rejects(
+ () => execOneShot({ agent: "codex", promptFile, cwd: fixtureDir, timeoutSeconds: 2 }),
+ named("exec"),
+ );
+ await assert.rejects(
+ () =>
+ sessionPrompt({
+ agent: "codex",
+ effort: "medium",
+ sessionName: "backpass-exec-timeout-exit",
+ promptFile,
+ cwd: fixtureDir,
+ timeoutSeconds: 2,
+ }),
+ named("session prompt"),
+ );
+ } finally {
+ process.env.FAKE_ACPX_MODE = "budget-blank";
+ delete process.env.FAKE_ACPX_STDERR;
+ }
+ });
+}
diff --git a/test/acpx-session-create-timeout.test.js b/test/acpx-session-create-timeout.test.js
index 84ba8f2a..50ed2022 100644
--- a/test/acpx-session-create-timeout.test.js
+++ b/test/acpx-session-create-timeout.test.js
@@ -39,6 +39,10 @@ if (argv.includes("config") && argv.includes("show")) {
const creating = argv.includes("sessions") && argv.includes("new");
const status = argv.includes("status");
const closing = argv.includes("sessions") && argv.includes("close");
+if (creating && process.env.FAKE_ACPX_MODE === "timeout-exit") {
+ process.stderr.write(process.env.FAKE_ACPX_STDERR || "");
+ process.exit(3);
+}
if (creating && process.env.FAKE_ACPX_MODE === "no-sessions") {
process.stderr.write("error: unknown command 'sessions'\\n");
process.exit(2);
@@ -103,6 +107,47 @@ test("a stalled harness no longer claims the effort override is unsupported", as
);
});
+for (const [scenario, stderr, detail] of [
+ ["empty stderr", "", ""],
+ ["accounting only", "[acpx] tokens: input=0 output=0 total=0\n", ""],
+ ["adapter error", "\nadapter startup timed out\nextra detail\n", ": adapter startup timed out"],
+ [
+ "quiet-mode error after accounting",
+ "[acpx] tokens: input=0 output=0 total=0\n[acpx] error: TIMEOUT GEMINI_ACP_STARTUP_TIMEOUT adapter startup timed out\n",
+ ": [acpx] error: TIMEOUT GEMINI_ACP_STARTUP_TIMEOUT adapter startup timed out",
+ ],
+ [
+ "noise before adapter error",
+ "[acpx] tokens: input=0 output=0 total=0\n[acpx] session closed\nadapter startup timed out\nextra detail\n",
+ ": adapter startup timed out",
+ ],
+]) {
+ test(`acpx timeout exit identifies session creation and probing without noise: ${scenario}`, async () => {
+ process.env.FAKE_ACPX_MODE = "timeout-exit";
+ process.env.FAKE_ACPX_STDERR = stderr;
+ try {
+ const options = { agent: "codex", sessionName: "backpass-create-timeout-exit", cwd: fixtureDir };
+ const message = `acpx codex session create ended at its own timeout (exit 3)${detail}`;
+ const named = (err) => {
+ assert.ok(err instanceof UserError, String(err));
+ assert.equal(err.message, message);
+ assert.equal(err.hint, "check with: acpx --verbose codex sessions new --name backpass-probe");
+ return true;
+ };
+ await assert.rejects(() => openSession(options), named);
+ await assert.rejects(() => sessionPrompt({ ...options, effort: "medium", promptFile }), named);
+ assert.deepEqual(await probeSession(options), {
+ verdict: "timeout",
+ detail: `acpx codex probe ended at its own timeout (exit 3)${detail}`,
+ availableModels: [],
+ });
+ } finally {
+ process.env.FAKE_ACPX_MODE = "hang";
+ delete process.env.FAKE_ACPX_STDERR;
+ }
+ });
+}
+
test("an adapter that really rejects sessions still reports missing session support", async () => {
process.env.FAKE_ACPX_MODE = "no-sessions";
try {
diff --git a/test/acpx-session-setup-timeout.test.js b/test/acpx-session-setup-timeout.test.js
new file mode 100644
index 00000000..6bfb5213
--- /dev/null
+++ b/test/acpx-session-setup-timeout.test.js
@@ -0,0 +1,95 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-acpx-setup-timeout-"));
+const promptFile = path.join(fixtureDir, "prompt.md");
+const logFile = path.join(fixtureDir, "calls.jsonl");
+const fakeAcpx = path.join(fixtureDir, "acpx");
+fs.writeFileSync(promptFile, "analyze this\n");
+fs.writeFileSync(
+ fakeAcpx,
+ `#!${process.execPath}
+const fs = require("node:fs");
+const args = process.argv.slice(2);
+const operation = args.includes("config") ? "config"
+ : args.includes("sessions") ? (args.includes("new") ? "new" : "close")
+ : args.includes("set-mode") ? "set-mode"
+ : args.includes("set") ? "set" : "prompt";
+fs.appendFileSync(${JSON.stringify(logFile)}, JSON.stringify(operation) + "\\n");
+if (operation === "config") process.stdout.write('{"agents":{}}');
+if (operation === process.env.FAKE_SETUP_OPERATION && process.env.FAKE_SETUP_EXIT !== "0") {
+ process.stderr.write("[acpx] error: TIMEOUT CLAUDE_ACP_SESSION_CREATE_TIMEOUT adapter startup timed out\\n");
+ process.exit(Number(process.env.FAKE_SETUP_EXIT));
+}
+if (operation === "prompt") process.stdout.write("done");
+`,
+ { mode: 0o755 },
+);
+process.env.BACKPASS_ACPX_BIN = fakeAcpx;
+const { AcpxError, openSession, sessionPrompt } = await import("../src/acpx.js");
+const { AgentResolver } = await import("../src/agents.js");
+const { UserError } = await import("../src/logger.js");
+
+test.after(() => {
+ delete process.env.FAKE_SETUP_OPERATION;
+ delete process.env.FAKE_SETUP_EXIT;
+ fs.rmSync(fixtureDir, { recursive: true, force: true });
+});
+
+for (const [agent, operation] of [
+ ["codex", "set"],
+ ["claude", "set"],
+ ["opencode", "set"],
+ ["codex", "set-mode"],
+]) {
+ for (const code of [0, 1, 3]) {
+ test(`${agent} ${operation} exit ${code} preserves pinned setup semantics and closes the session`, async () => {
+ process.env.FAKE_SETUP_OPERATION = operation;
+ process.env.FAKE_SETUP_EXIT = String(code);
+ fs.writeFileSync(logFile, "");
+ const effort = operation === "set" ? "medium" : null;
+ const resolver = new AgentResolver({ analysis: { agent, effort } });
+ let attempts = 0;
+ const call = () =>
+ resolver.withFallthrough("analysis", async (pick) => {
+ attempts += 1;
+ const options = { agent: pick.agent, effort, sessionName: "setup-timeout", cwd: fixtureDir };
+ if (operation === "set") return sessionPrompt({ ...options, promptFile });
+ const session = await openSession({ ...options, writeAccess: true });
+ try {
+ return await session.prompt({ promptFile });
+ } finally {
+ await session.close();
+ }
+ });
+ if (code === 0) {
+ assert.equal((await call()).text, "done");
+ } else {
+ await assert.rejects(call, (err) => {
+ if (code === 3) {
+ assert.ok(err instanceof AcpxError, String(err));
+ assert.equal(err.timedOut, true);
+ assert.equal(err.code, 3);
+ assert.match(err.message, /: timed out$/);
+ assert.match(err.stderr, /CLAUDE_ACP_SESSION_CREATE_TIMEOUT/);
+ } else {
+ assert.ok(err instanceof UserError, String(err));
+ assert.match(err.message, /pinned analysis agent .* failed unexpectedly/);
+ }
+ return true;
+ });
+ }
+ assert.equal(attempts, 1);
+ assert.equal((await resolver.resolve("analysis")).agent, agent);
+ const calls = fs
+ .readFileSync(logFile, "utf8")
+ .trim()
+ .split("\n")
+ .map((line) => JSON.parse(line));
+ assert.deepEqual(calls, ["config", "new", operation, ...(code === 0 ? ["prompt"] : []), "close"]);
+ });
+ }
+}
diff --git a/test/adapters.test.js b/test/adapters.test.js
index e73bdfd3..d95bacd9 100644
--- a/test/adapters.test.js
+++ b/test/adapters.test.js
@@ -5,6 +5,7 @@ import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { DatabaseSync } from "node:sqlite";
+import { execFileSync } from "node:child_process";
import * as claude from "../src/discovery/adapters/claude.js";
import * as codex from "../src/discovery/adapters/codex.js";
@@ -12,8 +13,12 @@ import * as pi from "../src/discovery/adapters/pi.js";
import * as grok from "../src/discovery/adapters/grok.js";
import * as cursorCli from "../src/discovery/adapters/cursor-cli.js";
import * as hermes from "../src/discovery/adapters/hermes.js";
+import * as opencode from "../src/discovery/adapters/opencode.js";
import { statOrNull } from "../src/discovery/adapters/shared.js";
import { associate } from "../src/discovery/association.js";
+import { discoverTranscripts } from "../src/discovery/index.js";
+import { associateUser } from "../src/scope.js";
+import { readOpencodeFixture, withOpencodeHome, writeOpencodeStore } from "./helpers/opencode.js";
const FIXTURES = path.join(path.dirname(fileURLToPath(import.meta.url)), "fixtures");
@@ -644,7 +649,7 @@ test("hermes adapter recovers cli/acp cwd, skips gateway, converts seconds to ms
});
});
-test("hermes adapter recovers v26 cli cwd from sessions.cwd when system_prompt is null, and still skips cron", async () => {
+test("hermes adapter collects v26 interactive sessions with trustworthy cwd and skips shared sources", async () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-hermes-v26-"));
writeHermesDb(dir, {
cwdColumn: true,
@@ -663,6 +668,25 @@ test("hermes adapter recovers v26 cli cwd from sessions.cwd when system_prompt i
model_config: JSON.stringify({ cwd: "/repo/demo" }),
started_at: 1_700_000_100,
},
+ {
+ id: "tui-v26",
+ source: "tui",
+ cwd: "/repo/demo",
+ started_at: 1_700_000_150,
+ },
+ {
+ id: "tui-relative",
+ source: "tui",
+ cwd: "repo/demo",
+ system_prompt: "Current working directory: /repo/demo\n",
+ started_at: 1_700_000_160,
+ },
+ {
+ id: "tui-no-cwd",
+ source: "tui",
+ model_config: JSON.stringify({ cwd: "/repo/demo" }),
+ started_at: 1_700_000_170,
+ },
{
id: "cron-v26",
source: "cron",
@@ -670,6 +694,12 @@ test("hermes adapter recovers v26 cli cwd from sessions.cwd when system_prompt i
system_prompt: "Current working directory: /repo/demo\n",
started_at: 1_700_000_200,
},
+ {
+ id: "gateway-v26",
+ source: "gateway",
+ cwd: "/repo/demo",
+ started_at: 1_700_000_210,
+ },
],
messages: [
{ id: 1, session_id: "cli-v26", role: "user", content: "hello from v26 cli" },
@@ -701,13 +731,16 @@ test("hermes adapter recovers v26 cli cwd from sessions.cwd when system_prompt i
const found = await hermes.discover();
assert.deepEqual(
found.map((row) => row.id).sort(),
- ["acp-v26", "cli-v26"],
- "v26 cli/acp are kept; cron is skipped even when sessions.cwd is set",
+ ["acp-v26", "cli-v26", "tui-v26"],
+ "v26 TUI needs absolute sessions.cwd; shared sources remain excluded",
);
const cli = found.find((row) => row.id === "cli-v26");
const acp = found.find((row) => row.id === "acp-v26");
+ const tui = found.find((row) => row.id === "tui-v26");
assert.equal(cli.cwd, "/repo/demo");
assert.equal(acp.cwd, "/repo/demo");
+ assert.equal(tui.cwd, "/repo/demo");
+ assert.equal(tui.extra.source, "tui");
assert.equal(cli.startedAt, 1_700_000_000_000);
const { events, model } = await hermes.read(cli);
@@ -722,3 +755,268 @@ test("hermes adapter recovers v26 cli cwd from sessions.cwd when system_prompt i
assert.equal(toolCall.result, "/repo/demo");
});
});
+
+test("normal discovery associates only trustworthy Hermes TUI sessions in project and user scope", async () => {
+ const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "backpass-hermes-scope-")));
+ const repoRoot = path.join(dir, "project");
+ const otherRoot = path.join(dir, "other");
+ fs.mkdirSync(repoRoot);
+ fs.mkdirSync(otherRoot);
+ execFileSync("git", ["init", "-q", repoRoot]);
+ execFileSync("git", ["init", "-q", otherRoot]);
+ writeHermesDb(path.join(dir, "hermes"), {
+ cwdColumn: true,
+ sessions: [
+ { id: "tui-project", source: "tui", cwd: repoRoot, started_at: 1_700_000_000 },
+ { id: "tui-other", source: "tui", cwd: otherRoot, started_at: 1_700_000_001 },
+ { id: "tui-relative", source: "tui", cwd: "project", started_at: 1_700_000_002 },
+ {
+ id: "tui-fallback",
+ source: "tui",
+ model_config: JSON.stringify({ cwd: repoRoot }),
+ started_at: 1_700_000_003,
+ },
+ { id: "gateway-project", source: "gateway", cwd: repoRoot, started_at: 1_700_000_004 },
+ { id: "cron-project", source: "cron", cwd: repoRoot, started_at: 1_700_000_005 },
+ { id: "whatsapp-project", source: "whatsapp", cwd: repoRoot, started_at: 1_700_000_006 },
+ ],
+ });
+ const config = {
+ discovery: { since: "all", harnesses: ["hermes"], worktreeGlobs: [] },
+ state: { root: path.join(dir, "state"), readScanCache: () => ({}) },
+ };
+ const repo = { name: "project", worktrees: [repoRoot], remotes: [] };
+
+ try {
+ await withHermesHome(path.join(dir, "hermes"), async () => {
+ const project = await discoverTranscripts({ repo, config, strict: true });
+ assert.deepEqual(
+ project.transcripts.map((row) => row.nativeId),
+ ["tui-project"],
+ );
+ assert.equal(project.transcripts[0].association.tier, 1);
+ assert.equal(project.transcripts[0].interaction, "interactive");
+
+ const user = await discoverTranscripts({
+ repo,
+ config,
+ strict: true,
+ scope: { kind: "user", associate: associateUser },
+ });
+ assert.deepEqual(user.transcripts.map((row) => row.nativeId).sort(), ["tui-other", "tui-project"]);
+ assert.deepEqual(new Set(user.transcripts.map((row) => row.project)), new Set([repoRoot, otherRoot]));
+ assert.ok(user.transcripts.every((row) => row.association.tier === 1));
+ });
+ } finally {
+ fs.rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("opencode test homes are removed and HOME restored on success and failure", async () => {
+ const original = process.env.HOME;
+ try {
+ for (const previous of [undefined, FIXTURES]) {
+ for (const failure of [null, "build", "callback"]) {
+ if (previous === undefined) delete process.env.HOME;
+ else process.env.HOME = previous;
+ let temporaryHome;
+ const error = new Error("fixture failure");
+ const result = withOpencodeHome(
+ (dbFile) => {
+ temporaryHome = path.resolve(dbFile, "../../../..");
+ assert.ok(fs.existsSync(temporaryHome));
+ if (failure === "build") throw error;
+ },
+ async () => {
+ assert.equal(process.env.HOME, temporaryHome);
+ if (failure === "callback") throw error;
+ return "done";
+ },
+ );
+ if (failure) await assert.rejects(result, (caught) => caught === error);
+ else assert.equal(await result, "done");
+ assert.equal(process.env.HOME, previous);
+ assert.equal(fs.existsSync(temporaryHome), false);
+ }
+ }
+ } finally {
+ if (original === undefined) delete process.env.HOME;
+ else process.env.HOME = original;
+ }
+});
+
+const V2_PARENT = "ses_f17ca477affeM7vJpYuwLTunDK";
+const V2_CHILD = "ses_f17c42540ffeM0ZIydCm19byyr";
+const V2_SELF = "ses_f139e87ceffeqUsW26A55Cc7W1";
+const V2_SELF_CHILD = "ses_f139e880dffeSelfChildSess01";
+const V2_RESUMED = "ses_f0a1b2c3dffeResumedSession01";
+
+test("opencode adapter lists an OpenCode 2 store by session_v2, dated by its newest message", async () => {
+ await withOpencodeHome(
+ (dbFile) => writeOpencodeStore(dbFile, readOpencodeFixture("opencode-v2-store.json")),
+ async (dbFile) => {
+ const rows = await opencode.discover({ cutoffMs: null });
+ const byId = new Map(rows.map((row) => /** @type {[string, any]} */ ([row.id, row])));
+ assert.deepEqual([...byId.keys()].sort(), [V2_RESUMED, V2_SELF, V2_SELF_CHILD, V2_CHILD, V2_PARENT].sort());
+ assert.ok(!byId.has("ses_f1378472bffeProbeEmptySess1"), "a session with no messages recorded nothing");
+ const parent = byId.get(V2_PARENT);
+ assert.equal(parent.cwd, "/repo/demo");
+ assert.equal(parent.gitRoot, "/repo/demo");
+ assert.equal(parent.path, dbFile);
+ assert.equal(parent.title, "Parser fix");
+ assert.equal(parent.startedAt, 1790600000000);
+ assert.equal(parent.mtimeMs, 1790600020800, "session_v2.time_updated does not move; the newest message does");
+ assert.deepEqual(parent.extra, { sessionId: V2_PARENT, layout: "v2" });
+ assert.equal(byId.get(V2_CHILD).interactionSignals.parentId, V2_PARENT, "a subagent session is a child");
+ assert.equal(byId.get(V2_CHILD).self, false, "a genuine session's subagent is genuine too");
+ assert.equal(byId.get(V2_SELF).self, true, "an acpx prompt opens with the sentinel");
+ assert.equal(byId.get(V2_SELF_CHILD).self, true, "work backpass's own agent delegated is backpass's too");
+ assert.equal(parent.self, false);
+
+ const resumed = await opencode.discover({ cutoffMs: 1790600100000 });
+ assert.ok(
+ resumed.some((row) => row.id === V2_RESUMED),
+ "a session created long ago but written to recently passes the window",
+ );
+ assert.ok(!resumed.some((row) => row.id === V2_PARENT));
+ assert.deepEqual(await opencode.discover({ cutoffMs: 1790600300000 }), []);
+ },
+ );
+});
+
+test("opencode adapter counts epoch-dated messages as recorded", async () => {
+ const fixture = readOpencodeFixture("opencode-v2-store.json");
+ for (const message of fixture.rows.session_message) message.time_updated = 0;
+ await withOpencodeHome(
+ (dbFile) => writeOpencodeStore(dbFile, fixture),
+ async () => {
+ const rows = await opencode.discover({ cutoffMs: null });
+ assert.deepEqual(
+ rows.map((row) => row.id).sort(),
+ [V2_RESUMED, V2_SELF, V2_SELF_CHILD, V2_CHILD, V2_PARENT].sort(),
+ );
+ },
+ );
+});
+
+test("opencode adapter reads an OpenCode 2 session: turns and calls in order, harness text left out", async () => {
+ await withOpencodeHome(
+ (dbFile) => writeOpencodeStore(dbFile, readOpencodeFixture("opencode-v2-store.json")),
+ async () => {
+ const [parent] = (await opencode.discover({ cutoffMs: null })).filter((row) => row.id === V2_PARENT);
+ const { events, model } = await opencode.read(parent);
+ assert.equal(model, "claude-opus-5.5");
+ assert.deepEqual(
+ events.map((event) =>
+ event.kind === "message"
+ ? `${event.role}: ${event.text}`
+ : `tool ${event.name} ${JSON.stringify(event.input)} [${event.status}] -> ${event.result ?? ""}`,
+ ),
+ [
+ "user: Open a PR for the parser fix.",
+ "assistant: I'll run the tests first.",
+ 'tool shell {"command":"npm test","workdir":"/repo/demo"} [completed] -> 2 passing',
+ 'tool read {"path":"/repo/demo/src/parser.ts"} [completed] -> Read file /repo/demo/src/parser.ts, lines 1-1\n1: export function parse() {}',
+ 'tool subagent {"agent":"general","description":"Review the parser fix","background":true,"prompt":"You are a subagent spawned by another session.\\nReview src/parser.ts."} [completed] -> \nNo blocking findings.\n',
+ "assistant: Opened PR #2731.",
+ 'tool edit {"path":"/repo/demo/CHANGELOG.md","oldString":"## Unreleased","newString":"## 1.2.0"} [error] -> oldString not found in content',
+ 'tool shell {"command":"git status --short"} [completed] -> nothing to commit',
+ 'tool skill {"name":"release"} [completed] -> ',
+ "user: Thanks, ship it.",
+ "assistant: Building the release.",
+ 'tool shell {"command":"npm run build","background":true} [error] -> \nbuild failed: missing dist/\n',
+ "assistant: The build failed; I will fix dist/ first.",
+ ],
+ );
+ const raw = JSON.stringify(events);
+ for (const harnessText of [
+ "Instructions from",
+ "Today's date",
+ "The previous response was interrupted",
+ "The following shell command was executed by the user",
+ "## Objective",
+ "Tag from main only",
+ "internal reasoning",
+ "OPAQUE",
+ ]) {
+ assert.ok(!raw.includes(harnessText), `${harnessText} is harness text, not session signal`);
+ }
+
+ const byRef = await opencode.read({ id: V2_PARENT });
+ assert.deepEqual(byRef.events, events, "a ref recorded before the layout was is looked up the same way");
+ },
+ );
+});
+
+test("opencode adapter still reads an OpenCode 1.x store, which leaves session_message empty", async () => {
+ await withOpencodeHome(
+ (dbFile) => writeOpencodeStore(dbFile, readOpencodeFixture("opencode-v1-store.json")),
+ async () => {
+ const [row, ...rest] = await opencode.discover({ cutoffMs: null });
+ assert.deepEqual(rest, []);
+ assert.equal(row.id, "ses_f16e2d036ffeZd4lFcWRZCBMYV");
+ assert.deepEqual(row.extra, { sessionId: row.id, layout: "v1" });
+ assert.equal(row.mtimeMs, 1790605324420);
+ assert.equal(row.self, false);
+ const { events, model } = await opencode.read(row);
+ assert.equal(model, "gpt-5.6-terra");
+ assert.deepEqual(
+ events.map((event) => (event.kind === "message" ? `${event.role}: ${event.text}` : `tool ${event.name}`)),
+ [
+ "user: Open a PR for the parser fix.",
+ "tool bash",
+ "assistant: I'll run the tests first.",
+ "assistant: Opened PR #2731.",
+ ],
+ );
+ const [call] = tools(events);
+ assert.equal(call.input.command, "npm test");
+ assert.equal(call.result, "2 passing\n");
+ assert.ok(!JSON.stringify(events).includes("internal reasoning"));
+ },
+ );
+});
+
+test("an upgraded opencode store is read from session_v2, where each copied session continues", async () => {
+ const v1 = readOpencodeFixture("opencode-v1-store.json");
+ const v2 = readOpencodeFixture("opencode-v2-store.json");
+ await withOpencodeHome(
+ (dbFile) => {
+ writeOpencodeStore(dbFile, v2);
+ // What the upgrade leaves behind: the 1.x tables, holding a copy of a session that
+ // now lives in session_v2 and one that was never copied.
+ const projectId = v2.rows.project[0].id;
+ const sessions = v1.rows.session.map((row) => ({ ...row, project_id: projectId }));
+ sessions.push({ ...sessions[0], id: V2_PARENT, title: "stale 1.x copy" });
+ writeOpencodeStore(
+ dbFile,
+ { schema: v1.schema, rows: { session: sessions, message: v1.rows.message, part: v1.rows.part } },
+ { skipTables: ["project", "session_message"] },
+ );
+ },
+ async () => {
+ const rows = await opencode.discover({ cutoffMs: null });
+ const layouts = Object.fromEntries(rows.map((row) => [row.id, row.extra.layout]));
+ assert.equal(rows.filter((row) => row.id === V2_PARENT).length, 1, "one session, listed once");
+ assert.equal(layouts[V2_PARENT], "v2");
+ assert.equal(layouts["ses_f16e2d036ffeZd4lFcWRZCBMYV"], "v1");
+ const parent = rows.find((row) => row.id === V2_PARENT);
+ assert.equal(parent.title, "Parser fix");
+ assert.equal(messages((await opencode.read(parent)).events)[0].text, "Open a PR for the parser fix.");
+ },
+ );
+});
+
+test("an opencode store with neither session table is named as drifted, never read as empty", async () => {
+ await withOpencodeHome(
+ (dbFile) => {
+ fs.mkdirSync(path.dirname(dbFile), { recursive: true });
+ const db = new DatabaseSync(dbFile);
+ db.exec("CREATE TABLE unrelated (id INTEGER)");
+ db.close();
+ },
+ async () => {
+ await assert.rejects(opencode.discover({ cutoffMs: null }), /unrecognised opencode store/);
+ },
+ );
+});
diff --git a/test/agents.test.js b/test/agents.test.js
index 1714a78c..51e540c2 100644
--- a/test/agents.test.js
+++ b/test/agents.test.js
@@ -81,6 +81,10 @@ import os from "node:os";
import path from "node:path";
import { CONFIG_FILENAME } from "../src/config.js";
+// `loadConfig` merges ~/.config/backpass/config.json; a host with its own `ladders` there
+// would replace the default ladders these tests assert against.
+process.env.XDG_CONFIG_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-agents-config-"));
+
function tmpRepo(config) {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-agents-"));
if (config) fs.writeFileSync(path.join(dir, CONFIG_FILENAME), JSON.stringify(config));
@@ -477,6 +481,24 @@ test("only classifiable failures fall through; real-work errors propagate unchan
(err) => err === timeout,
);
assert.equal((await resolver.resolve("analysis")).agent, "pi", "a timeout on real work does not demote");
+ const authTimeout = new AcpxError("acpx pi session prompt timed out after 300s", {
+ timedOut: true,
+ stderr: "AUTH_REQUIRED",
+ });
+ let calls = 0;
+ await assert.rejects(
+ resolver.withFallthrough("analysis", async () => {
+ calls++;
+ throw authTimeout;
+ }),
+ (err) => err === authTimeout,
+ );
+ assert.equal(calls, 1);
+ assert.equal(
+ (await resolver.resolve("analysis")).agent,
+ "pi",
+ "a timeout whose stderr looks classifiable still does not demote",
+ );
await assert.rejects(
resolver.withFallthrough("analysis", async () => {
throw new Error("analysis returned no parseable JSON");
@@ -577,6 +599,33 @@ test("explicit config or CLI flags pin the role and skip the ladder entirely", a
return true;
},
);
+
+ // A timeout on real work is not the pinned agent's verdict: it propagates unchanged.
+ const timedOut = new AcpxError("acpx claude session prompt timed out after 600s", { timedOut: true });
+ await assert.rejects(
+ resolver.withFallthrough("synthesis", async () => {
+ throw timedOut;
+ }),
+ (err) => {
+ assert.equal(err, timedOut);
+ return true;
+ },
+ );
+
+ // Even when its stderr carries a classifiable diagnostic, a pinned timeout is not retried.
+ const authTimeout = new AcpxError("acpx claude session prompt timed out after 600s", {
+ timedOut: true,
+ stderr: "AUTH_REQUIRED",
+ });
+ let pinnedCalls = 0;
+ await assert.rejects(
+ resolver.withFallthrough("synthesis", async () => {
+ pinnedCalls++;
+ throw authTimeout;
+ }),
+ (err) => err === authTimeout,
+ );
+ assert.equal(pinnedCalls, 1, "a pinned timeout is not retried");
});
test("a pinned agent that returns no output gets a provider-account hint, not a login one", async () => {
@@ -1125,6 +1174,13 @@ test("acpx failure classification and the per-adapter tables", () => {
classifyAcpxFailure({ stderr: 'Cannot apply --model "x": the ACP agent did not advertise that model.' }),
"model-unavailable",
);
+ assert.equal(
+ classifyAcpxFailure({
+ stderr:
+ "[acpx] error: RUNTIME QUEUE_RUNTIME_PROMPT_FAILED Internal error: API Error: 400 Claude Code 2.1.215 does not support this model; version 2.1.280 or newer is required.",
+ }),
+ "model-unavailable",
+ );
assert.equal(classifyAcpxFailure({ spawnError: { code: "ENOENT" } }), "unreachable");
assert.equal(classifyAcpxFailure({ stderr: "[acpx] error: TIMEOUT prompt exceeded 300s" }), null);
assert.equal(classifyAcpxFailure({ stderr: "" }), null);
diff --git a/test/analyze-sqlite-raw.test.js b/test/analyze-sqlite-raw.test.js
new file mode 100644
index 00000000..c2d3b244
--- /dev/null
+++ b/test/analyze-sqlite-raw.test.js
@@ -0,0 +1,571 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+import { DatabaseSync } from "node:sqlite";
+import { randomUUID } from "node:crypto";
+
+import { analyzeTranscripts, reclaimExpiredRawFiles } from "../src/analyze.js";
+import { State } from "../src/state.js";
+import { nestedContext } from "../src/nested.js";
+
+/**
+ * The raw-transcript escape hatch for a session in a SQLite store (opencode here).
+ *
+ * The trace footer names a raw transcript the analysis agent may open when a claim needs
+ * the full text. For a file-backed store that is the session's own file; an opencode
+ * session's path is the store's one database, holding every session of every repository.
+ * This drives the real CLI against a fake acpx that reads the analysis prompt, follows
+ * the footer, and records what it found there: the analysis must name a file holding
+ * this one session's events, and that file must be gone once the call has returned.
+ */
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const CLI = path.join(ROOT, "bin", "backpass.js");
+/** Just beyond the 24-hour raw-file lease. */
+const RAW_LEASE_EXPIRED_MS = 24 * 60 * 60_000 + 60_000;
+
+const binDir = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-sqlite-raw-bin-"));
+const fakePi = path.join(binDir, "pi");
+const fakeAcpx = path.join(binDir, "acpx");
+const seenLog = path.join(binDir, "seen.json");
+
+fs.writeFileSync(fakePi, `#!${process.execPath}\nprocess.exit(0);\n`);
+fs.chmodSync(fakePi, 0o755);
+fs.writeFileSync(
+ fakeAcpx,
+ `#!${process.execPath}
+const fs = require("node:fs");
+const argv = process.argv.slice(2);
+if (argv.includes("config") && argv.includes("show")) {
+ process.stdout.write(JSON.stringify({ agents: {} }) + "\\n");
+ process.exit(0);
+}
+if (argv.includes("--file")) {
+ const prompt = fs.readFileSync(argv[argv.indexOf("--file") + 1], "utf8");
+ const rawPath = /^raw transcript: (.+)$/m.exec(prompt)[1];
+ const seen = { rawPath, exists: fs.existsSync(rawPath), mode: fs.statSync(rawPath).mode & 0o777, lines: [] };
+ if (seen.exists) seen.lines = fs.readFileSync(rawPath, "utf8").trim().split("\\n").map((line) => JSON.parse(line));
+ fs.writeFileSync(${JSON.stringify(seenLog)}, JSON.stringify(seen));
+ if (process.env.RAW_TEST_SIGNAL && (!process.env.RAW_TEST_SIGNAL_MATCH || rawPath.includes(process.env.RAW_TEST_SIGNAL_MATCH))) {
+ process.kill(process.ppid, process.env.RAW_TEST_SIGNAL);
+ setTimeout(() => process.exit(0), 100);
+ } else {
+ process.stdout.write(process.env.RAW_TEST_INVALID ? "not JSON" : JSON.stringify({ positive: [], negative: [], gaps: [] }));
+ process.exit(0);
+ }
+} else {
+ process.exit(0);
+}
+`,
+);
+fs.chmodSync(fakeAcpx, 0o755);
+
+function git(args, cwd) {
+ spawnSync("git", args, { cwd, stdio: "ignore" });
+}
+
+function initRepo() {
+ const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "backpass-sqlite-raw-repo-")));
+ git(["init", "--quiet", "-b", "main"], dir);
+ git(["config", "user.email", "test@example.com"], dir);
+ git(["config", "user.name", "test"], dir);
+ fs.writeFileSync(path.join(dir, "AGENTS.md"), "# Agent instructions\n\n- Run `make build` before every push.\n");
+ git(["add", "-A"], dir);
+ git(["commit", "-q", "-m", "memory"], dir);
+ return dir;
+}
+
+/** An opencode 1.x store with this repo's session and one from somewhere else. */
+function writeStore(home, repoDir, sessionDir = repoDir) {
+ const store = path.join(home, ".local", "share", "opencode");
+ fs.mkdirSync(store, { recursive: true });
+ const db = new DatabaseSync(path.join(store, "opencode.db"));
+ db.exec(`
+ CREATE TABLE project (id TEXT PRIMARY KEY, worktree TEXT NOT NULL);
+ CREATE TABLE session (
+ id TEXT PRIMARY KEY, project_id TEXT NOT NULL, parent_id TEXT, directory TEXT NOT NULL,
+ title TEXT NOT NULL, time_created INTEGER NOT NULL, time_updated INTEGER NOT NULL
+ );
+ CREATE TABLE message (id TEXT PRIMARY KEY, session_id TEXT NOT NULL, time_created INTEGER NOT NULL, data TEXT NOT NULL);
+ CREATE TABLE part (
+ id TEXT PRIMARY KEY, message_id TEXT NOT NULL, session_id TEXT NOT NULL,
+ time_created INTEGER NOT NULL, data TEXT NOT NULL
+ );
+ `);
+ const now = Date.now();
+ const sessions = [
+ { id: "ses_here", directory: sessionDir, turns: ["Please build the project.", "Now run the tests too."] },
+ { id: "ses_elsewhere", directory: "/somewhere/else", turns: ["An unrelated secret plan."] },
+ ];
+ db.prepare("INSERT INTO project (id, worktree) VALUES ('p1', ?)").run(repoDir);
+ for (const session of sessions) {
+ db.prepare(
+ "INSERT INTO session (id, project_id, directory, title, time_created, time_updated) VALUES (?, 'p1', ?, ?, ?, ?)",
+ ).run(session.id, session.directory, session.id, now, now);
+ session.turns.forEach((text, index) => {
+ const turns = [
+ { id: `${session.id}_u${index}`, role: "user", parts: [{ type: "text", text }] },
+ {
+ id: `${session.id}_a${index}`,
+ role: "assistant",
+ parts: [
+ { type: "text", text: `Done: ${text}` },
+ {
+ type: "tool",
+ tool: "bash",
+ state: { status: "completed", input: { command: "make build" }, output: "ok" },
+ },
+ ],
+ },
+ ];
+ turns.forEach((turn, offset) => {
+ const at = now + index * 10 + offset;
+ db.prepare("INSERT INTO message (id, session_id, time_created, data) VALUES (?, ?, ?, ?)").run(
+ turn.id,
+ session.id,
+ at,
+ JSON.stringify({ role: turn.role }),
+ );
+ turn.parts.forEach((part, partIndex) => {
+ db.prepare("INSERT INTO part (id, message_id, session_id, time_created, data) VALUES (?, ?, ?, ?, ?)").run(
+ `${turn.id}_p${partIndex}`,
+ turn.id,
+ session.id,
+ at,
+ JSON.stringify(part),
+ );
+ });
+ });
+ });
+ }
+ db.close();
+ return path.join(store, "opencode.db");
+}
+
+function analyze(dir, home, env = {}, extraArgs = []) {
+ return spawnSync(
+ process.execPath,
+ [
+ CLI,
+ "analyze",
+ "--harness",
+ "opencode",
+ "--since",
+ "all",
+ "--analysis-agent",
+ "pi",
+ "--jobs",
+ "1",
+ "--json",
+ ...extraArgs,
+ ],
+ {
+ cwd: dir,
+ env: {
+ ...process.env,
+ HOME: home,
+ USERPROFILE: home,
+ PATH: `${binDir}${path.delimiter}${process.env.PATH}`,
+ BACKPASS_ACPX_BIN: fakeAcpx,
+ NO_COLOR: "1",
+ ...env,
+ },
+ encoding: "utf8",
+ timeout: 20000,
+ },
+ );
+}
+
+test("a SQLite session's escape hatch is a file of its own events, removed after the call", () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-sqlite-raw-home-"));
+ const dir = initRepo();
+ const database = writeStore(home, dir);
+ const result = analyze(dir, home);
+ assert.equal(result.status, 0, `${result.stdout}${result.stderr}`);
+ assert.equal(JSON.parse(result.stdout).summary.analyzed, 1);
+
+ const seen = JSON.parse(fs.readFileSync(seenLog, "utf8"));
+ assert.notEqual(seen.rawPath, database, "the footer never names the whole database");
+ assert.equal(path.dirname(seen.rawPath), path.join(dir, ".backpass", "raw"));
+ assert.equal(seen.exists, true, "the file is there for the length of the call");
+ if (process.platform !== "win32") assert.equal(seen.mode, 0o600);
+ const [header, ...events] = seen.lines;
+ assert.deepEqual(header, { harness: "opencode", session: "ses_here", model: null });
+ assert.deepEqual(
+ events.filter((event) => event.kind === "message" && event.role === "user").map((event) => event.text),
+ ["Please build the project.", "Now run the tests too."],
+ );
+ assert.ok(!JSON.stringify(seen.lines).includes("unrelated secret"), "no other session reaches the agent");
+ assert.equal(fs.existsSync(seen.rawPath), false, "the file is removed once the call has returned");
+
+ fs.rmSync(seenLog);
+ fs.rmdirSync(path.dirname(seen.rawPath));
+ const cached = analyze(dir, home);
+ assert.equal(cached.status, 0, `${cached.stdout}${cached.stderr}`);
+ assert.equal(JSON.parse(cached.stdout).summary.cached, 1);
+ assert.equal(fs.existsSync(seenLog), false);
+ assert.equal(fs.existsSync(path.dirname(seen.rawPath)), false);
+});
+
+for (const signal of ["SIGINT", "SIGTERM", "SIGKILL"]) {
+ for (const nested of [false, true]) {
+ test(
+ `a SQLite raw file is removed ${signal === "SIGKILL" ? "once its lease runs out" : "at exit"} when ${nested ? "nested" : "root"} analysis receives ${signal}`,
+ { skip: process.platform === "win32" },
+ () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-sqlite-raw-home-"));
+ const dir = initRepo();
+ const sessionDir = nested ? path.join(dir, "apps", "api") : dir;
+ if (nested) {
+ fs.mkdirSync(sessionDir, { recursive: true });
+ fs.writeFileSync(path.join(sessionDir, "AGENTS.md"), "# API instructions\n\n- Run API tests.\n");
+ fs.writeFileSync(
+ path.join(dir, ".backpassrc.json"),
+ JSON.stringify({ nestedMemoryFiles: ["apps/api/AGENTS.md"] }),
+ );
+ }
+ const database = writeStore(home, dir, sessionDir);
+ fs.rmSync(seenLog, { force: true });
+ const result = analyze(dir, home, {
+ RAW_TEST_SIGNAL: signal,
+ RAW_TEST_SIGNAL_MATCH: nested ? path.join(".backpass", "nested") : "",
+ });
+ if (signal === "SIGKILL") {
+ assert.equal(result.signal, "SIGKILL", `${result.stdout}${result.stderr}`);
+ } else {
+ assert.equal(result.status, signal === "SIGINT" ? 130 : 143, `${result.stdout}${result.stderr}`);
+ }
+ const seen = JSON.parse(fs.readFileSync(seenLog, "utf8"));
+ assert.equal(seen.exists, true);
+ assert.equal(seen.rawPath.includes(path.join(".backpass", "nested")), nested);
+ if (signal === "SIGKILL") {
+ assert.equal(fs.existsSync(seen.rawPath), true, "SIGKILL cannot run exit cleanup");
+ const liveFile = path.join(path.dirname(seen.rawPath), `${randomUUID()}.jsonl`);
+ fs.writeFileSync(liveFile, "live analysis events\n", { mode: 0o600 });
+ fs.rmSync(database);
+ const early = analyze(dir, home);
+ assert.equal(early.status, 0, `${early.stdout}${early.stderr}`);
+ assert.equal(fs.existsSync(seen.rawPath), true, "a lease that has not run out is left alone");
+ const expired = new Date(Date.now() - RAW_LEASE_EXPIRED_MS);
+ fs.utimesSync(seen.rawPath, expired, expired);
+ const recovered = analyze(dir, home);
+ assert.equal(recovered.status, 0, `${recovered.stdout}${recovered.stderr}`);
+ assert.equal(JSON.parse(recovered.stdout).summary, null);
+ assert.equal(fs.readFileSync(liveFile, "utf8"), "live analysis events\n");
+ }
+ assert.equal(fs.existsSync(seen.rawPath), false);
+ },
+ );
+ }
+}
+
+test(
+ "cached analysis reclaims another run's raw file only once its lease runs out",
+ {
+ skip: process.platform === "win32",
+ },
+ () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-sqlite-raw-home-"));
+ const dir = initRepo();
+ writeStore(home, dir);
+ const initial = analyze(dir, home);
+ assert.equal(initial.status, 0, `${initial.stdout}${initial.stderr}`);
+ const killed = analyze(dir, home, { RAW_TEST_SIGNAL: "SIGKILL" }, ["--force"]);
+ assert.equal(killed.signal, "SIGKILL", `${killed.stdout}${killed.stderr}`);
+ const seen = JSON.parse(fs.readFileSync(seenLog, "utf8"));
+ assert.equal(fs.existsSync(seen.rawPath), true);
+ fs.rmSync(seenLog);
+ const cached = analyze(dir, home);
+ assert.equal(cached.status, 0, `${cached.stdout}${cached.stderr}`);
+ assert.equal(JSON.parse(cached.stdout).summary.cached, 1);
+ assert.equal(fs.existsSync(seenLog), false, "a cache hit must not require another model call");
+ assert.equal(fs.existsSync(seen.rawPath), true);
+ const expired = new Date(Date.now() - RAW_LEASE_EXPIRED_MS);
+ fs.utimesSync(seen.rawPath, expired, expired);
+ const later = analyze(dir, home);
+ assert.equal(later.status, 0, `${later.stdout}${later.stderr}`);
+ assert.equal(JSON.parse(later.stdout).summary.cached, 1);
+ assert.equal(fs.existsSync(seen.rawPath), false);
+ },
+);
+
+test("analysis tolerates hours of clock skew in root and nested leases and reclaims day-old leftovers", () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-sqlite-raw-home-"));
+ const dir = initRepo();
+ const preload = path.join(binDir, "raw-leases.mjs");
+ const filesLog = path.join(binDir, "raw-files.json");
+ fs.writeFileSync(
+ preload,
+ `import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+if (process.argv[1] === ${JSON.stringify(CLI)}) {
+ const files = ["raw", "nested/previous/raw"].flatMap((subdir) => {
+ const rawDir = path.join(process.cwd(), ".backpass", subdir);
+ fs.mkdirSync(rawDir, { recursive: true });
+ return [0, -6 * 60 * 60_000, 6 * 60 * 60_000, 24 * 60 * 60_000 - 60_000, ${RAW_LEASE_EXPIRED_MS}].map((age) => {
+ const file = path.join(rawDir, randomUUID() + ".jsonl");
+ fs.writeFileSync(file, "analysis events\\n", { mode: 0o600 });
+ const at = new Date(Date.now() - age);
+ fs.utimesSync(file, at, at);
+ return { file, expired: age === ${RAW_LEASE_EXPIRED_MS} };
+ });
+ });
+ fs.writeFileSync(${JSON.stringify(filesLog)}, JSON.stringify(files));
+}
+`,
+ );
+ const result = analyze(dir, home, {
+ NODE_OPTIONS: `${process.env.NODE_OPTIONS || ""} --import=${JSON.stringify(pathToFileURL(preload).href)}`,
+ });
+ assert.equal(result.status, 0, `${result.stdout}${result.stderr}`);
+ assert.equal(JSON.parse(result.stdout).summary, null);
+ const files = JSON.parse(fs.readFileSync(filesLog, "utf8"));
+ assert.equal(files.length, 10);
+ for (const { file, expired } of files) {
+ assert.equal(fs.existsSync(file), !expired, `${expired ? "kept expired" : "deleted live"} ${file}`);
+ }
+});
+
+for (const cached of [false, true]) {
+ for (const subdir of ["nested", "raw", "nested/previous/raw"]) {
+ for (const fault of ["unreadable-stat", "unreadable-list", "vanished", "not-directory"]) {
+ test(`${cached ? "cached" : "empty"} analysis skips ${fault} ${subdir} with one warning`, () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-sqlite-raw-home-"));
+ const dir = initRepo();
+ if (cached) {
+ writeStore(home, dir);
+ const initial = analyze(dir, home);
+ assert.equal(initial.status, 0, `${initial.stdout}${initial.stderr}`);
+ }
+ const badDir = path.join(dir, ".backpass", subdir);
+ fs.mkdirSync(badDir, { recursive: true });
+ if (fault === "not-directory") {
+ fs.rmdirSync(badDir);
+ fs.writeFileSync(badDir, "not a directory\n");
+ }
+ const healthyDir = path.join(dir, ".backpass", subdir === "nested" ? "raw" : "nested/healthy/raw");
+ fs.mkdirSync(healthyDir, { recursive: true });
+ const expiredFile = path.join(healthyDir, `${randomUUID()}.jsonl`);
+ fs.writeFileSync(expiredFile, "abandoned events\n");
+ const expired = new Date(Date.now() - RAW_LEASE_EXPIRED_MS);
+ fs.utimesSync(expiredFile, expired, expired);
+ const preload = path.join(binDir, "raw-directory-fault.mjs");
+ fs.writeFileSync(
+ preload,
+ `import fs from "node:fs";
+import path from "node:path";
+if (process.argv[1] === ${JSON.stringify(CLI)} && ${JSON.stringify(fault)} !== "not-directory") {
+ const method = ${JSON.stringify(fault === "unreadable-stat" ? "lstatSync" : "readdirSync")};
+ const original = fs[method];
+ fs[method] = function (file, ...args) {
+ if (path.resolve(String(file)) === ${JSON.stringify(badDir)}) {
+ const code = ${JSON.stringify(fault === "vanished" ? "ENOENT" : "EACCES")};
+ throw Object.assign(new Error(code + ": injected directory failure"), { code });
+ }
+ return original.call(this, file, ...args);
+ };
+}
+`,
+ );
+ const result = analyze(dir, home, {
+ NODE_OPTIONS: `${process.env.NODE_OPTIONS || ""} --import=${JSON.stringify(pathToFileURL(preload).href)}`,
+ });
+ assert.equal(result.status, 0, `${result.stdout}${result.stderr}`);
+ const { summary } = JSON.parse(result.stdout);
+ if (cached) assert.equal(summary.cached, 1);
+ else assert.equal(summary, null);
+ const warnings = result.stderr
+ .split("\n")
+ .filter((line) => line.includes("could not reclaim raw transcripts in"));
+ assert.equal(warnings.length, 1, result.stderr);
+ assert.ok(warnings[0].includes(badDir), result.stderr);
+ assert.equal(fs.existsSync(expiredFile), false, "healthy sibling cleanup still runs");
+ });
+ }
+ }
+}
+
+test("a running call renews its raw file's lease", async (t) => {
+ t.mock.timers.enable({ apis: ["setInterval"] });
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-sqlite-raw-home-"));
+ const dir = initRepo();
+ const database = writeStore(home, dir);
+ t.mock.method(os, "homedir", () => home);
+ const stateDir = path.join(dir, ".backpass");
+ const state = new State(dir, { stateDir: path.relative(process.cwd(), stateDir), exclude: false }).ensure();
+ let file = "";
+ let age = Infinity;
+ const summary = await analyzeTranscripts({
+ transcripts: [{ harness: "opencode", id: "ses_here", nativeId: "ses_here", path: database }],
+ memoryFile: { path: "AGENTS.md", units: [] },
+ memoryHash: "test-memory",
+ repo: { root: dir },
+ config: {
+ state,
+ jobs: 1,
+ discovery: { minUserTurns: 2 },
+ agents: {
+ resolve: async () => ({ agent: "pi" }),
+ withFallthrough: async () => {
+ const [name] = fs.readdirSync(path.join(stateDir, "raw"));
+ file = path.join(stateDir, "raw", name);
+ const expired = new Date(Date.now() - RAW_LEASE_EXPIRED_MS);
+ fs.utimesSync(file, expired, expired);
+ t.mock.timers.tick(60_000);
+ age = Date.now() - fs.statSync(file).mtimeMs;
+ return { text: JSON.stringify({ positive: [], negative: [], gaps: [] }) };
+ },
+ },
+ },
+ });
+ assert.equal(summary.analyzed, 1);
+ assert.ok(age < 10_000, `the lease was last renewed ${age}ms ago`);
+ assert.equal(fs.existsSync(file), false);
+});
+
+for (const nested of [false, true]) {
+ test(`reclamation preserves this process's active ${nested ? "nested" : "root"} raw file`, async (t) => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-sqlite-raw-home-"));
+ const dir = initRepo();
+ const database = writeStore(home, dir);
+ t.mock.method(os, "homedir", () => home);
+ const rootStateDir = path.join(dir, ".backpass");
+ const stateDir = nested ? path.join(rootStateDir, "nested", "active") : rootStateDir;
+ const state = new State(dir, { stateDir: path.relative(process.cwd(), stateDir), exclude: false }).ensure();
+ let activeFile;
+ const summary = await analyzeTranscripts({
+ transcripts: [{ harness: "opencode", id: "ses_here", nativeId: "ses_here", path: database }],
+ memoryFile: { path: "AGENTS.md", units: [] },
+ memoryHash: "test-memory",
+ repo: { root: dir },
+ config: {
+ state,
+ jobs: 1,
+ discovery: { minUserTurns: 2 },
+ agents: {
+ resolve: async () => ({ agent: "pi" }),
+ withFallthrough: async () => {
+ const files = fs.readdirSync(path.join(stateDir, "raw"));
+ assert.equal(files.length, 1);
+ activeFile = path.join(stateDir, "raw", files[0]);
+ const before = fs.readFileSync(activeFile, "utf8");
+ for (const root of [rootStateDir, stateDir, state.root]) {
+ const expiredFile = path.join(stateDir, "raw", `${randomUUID()}.jsonl`);
+ fs.writeFileSync(expiredFile, "expired analysis events\n");
+ const expired = new Date(Date.now() - RAW_LEASE_EXPIRED_MS);
+ fs.utimesSync(expiredFile, expired, expired);
+ reclaimExpiredRawFiles(root);
+ assert.equal(fs.existsSync(expiredFile), false);
+ assert.equal(fs.readFileSync(activeFile, "utf8"), before);
+ }
+ return { text: JSON.stringify({ positive: [], negative: [], gaps: [] }) };
+ },
+ },
+ },
+ });
+ assert.equal(summary.analyzed, 1);
+ assert.equal(summary.failed, 0);
+ assert.ok(activeFile);
+ assert.equal(fs.existsSync(activeFile), false);
+ });
+}
+
+test("trivial SQLite sessions never materialize raw events", () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-sqlite-raw-home-"));
+ const dir = initRepo();
+ writeStore(home, dir);
+ fs.writeFileSync(path.join(dir, ".backpassrc.json"), JSON.stringify({ discovery: { minUserTurns: 3 } }));
+ fs.rmSync(seenLog, { force: true });
+ const result = analyze(dir, home);
+ assert.equal(result.status, 0, `${result.stdout}${result.stderr}`);
+ assert.equal(JSON.parse(result.stdout).summary.skipped, 2);
+ assert.equal(fs.existsSync(seenLog), false);
+ assert.equal(fs.existsSync(path.join(dir, ".backpass", "raw")), false);
+});
+
+test("a SQLite raw file is removed when the analysis response is invalid", () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-sqlite-raw-home-"));
+ const dir = initRepo();
+ writeStore(home, dir);
+ fs.rmSync(seenLog, { force: true });
+ const result = analyze(dir, home, { RAW_TEST_INVALID: "1" });
+ assert.equal(result.status, 0, `${result.stdout}${result.stderr}`);
+ assert.equal(JSON.parse(result.stdout).summary.failed, 1);
+ const seen = JSON.parse(fs.readFileSync(seenLog, "utf8"));
+ assert.equal(fs.existsSync(seen.rawPath), false);
+});
+
+for (const bound of [false, true]) {
+ for (const nested of [false, true]) {
+ for (const linked of bound ? [false, true] : [true]) {
+ test(
+ `${bound ? "bound" : "unbound"} ${nested ? "nested" : "root"} SQLite analysis ${bound && linked ? "refuses" : "preserves"} ${linked ? "linked" : "private"} raw directories`,
+ { skip: process.platform === "win32" },
+ async (t) => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-sqlite-private-home-"));
+ const dir = initRepo();
+ const database = writeStore(home, dir);
+ t.mock.method(os, "homedir", () => home);
+ const rootState = new State(dir, {
+ stateDir: path.join(dir, "isolated-state"),
+ exclude: false,
+ ...(bound ? { mode: 0o700, binding: { kind: "project", root: dir } } : {}),
+ }).ensure();
+ const state = nested
+ ? nestedContext(
+ { repo: { root: dir }, config: { state: rootState, budgetTokens: 5000 } },
+ { path: "apps/api/AGENTS.md" },
+ ).config.state
+ : rootState;
+ const outside = path.join(dir, "outside-raw");
+ fs.mkdirSync(outside, { mode: 0o700 });
+ const rawDir = path.join(state.root, "raw");
+ if (linked) fs.symlinkSync(outside, rawDir, "dir");
+ let calls = 0;
+ let observedEvents = [];
+ const analyze = () =>
+ analyzeTranscripts({
+ transcripts: [{ harness: "opencode", id: "ses_here", nativeId: "ses_here", path: database }],
+ memoryFile: { path: "AGENTS.md", units: [] },
+ memoryHash: "private-raw",
+ repo: { root: dir },
+ config: {
+ state,
+ jobs: 1,
+ discovery: { minUserTurns: 2 },
+ agents: {
+ resolve: async () => ({ agent: "pi" }),
+ withFallthrough: async () => {
+ calls += 1;
+ const [file] = fs.readdirSync(rawDir);
+ observedEvents = fs
+ .readFileSync(path.join(rawDir, file), "utf8")
+ .trim()
+ .split("\n")
+ .map((line) => JSON.parse(line));
+ return { text: JSON.stringify({ positive: [], negative: [], gaps: [] }) };
+ },
+ },
+ },
+ });
+ if (bound && linked) {
+ await assert.rejects(analyze(), /unsafe private state path/);
+ assert.equal(calls, 0);
+ } else {
+ const summary = await analyze();
+ assert.equal(summary.analyzed, 1);
+ assert.equal(calls, 1);
+ assert.ok(observedEvents.some((event) => event.text === "Please build the project."));
+ assert.deepEqual(fs.readdirSync(rawDir), []);
+ }
+ assert.deepEqual(fs.readdirSync(outside), []);
+ },
+ );
+ }
+ }
+}
diff --git a/test/analyze-stop-on-fatal.test.js b/test/analyze-stop-on-fatal.test.js
new file mode 100644
index 00000000..52ec228b
--- /dev/null
+++ b/test/analyze-stop-on-fatal.test.js
@@ -0,0 +1,135 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { State } from "../src/state.js";
+
+/**
+ * A fatal analysis error stops the run from starting more model calls.
+ *
+ * Per-transcript failures (a timeout, unparseable output) are recorded and the run goes
+ * on; an error that fails the run - here a pinned agent failing in a way nothing can
+ * classify - used to stop only the worker that hit it. The run reported the failure while
+ * every other worker kept taking transcripts and paying for model calls. This drives the
+ * real CLI with two jobs over five sessions: the call that fails and the one already in
+ * flight run, the healthy call's evidence is saved, and no third call starts.
+ */
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const CLI = path.join(ROOT, "bin", "backpass.js");
+
+const binDir = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-stop-bin-"));
+const fakePi = path.join(binDir, "pi");
+const fakeAcpx = path.join(binDir, "acpx");
+const callLog = path.join(binDir, "calls.log");
+const gap = {
+ mistake: "Tests needed a user reminder.",
+ proposedInstruction: "Run tests before declaring the work complete.",
+ recurrenceRisk: "high",
+ quote: "Now run the tests too.",
+ domain: "project",
+};
+
+fs.writeFileSync(fakePi, `#!${process.execPath}\nprocess.exit(0);\n`);
+fs.chmodSync(fakePi, 0o755);
+fs.writeFileSync(
+ fakeAcpx,
+ `#!${process.execPath}
+const fs = require("node:fs");
+const argv = process.argv.slice(2);
+if (argv.includes("config") && argv.includes("show")) {
+ process.stdout.write(JSON.stringify({ agents: {} }) + "\\n");
+ process.exit(0);
+}
+if (argv.includes("--file")) {
+ const prompt = fs.readFileSync(argv[argv.indexOf("--file") + 1], "utf8");
+ const session = /Do the (\\S+) work\\./.exec(prompt)[1];
+ fs.appendFileSync(${JSON.stringify(callLog)}, session + "\\n");
+ if (session === "doomed") {
+ process.stderr.write("adapter crashed\\n");
+ process.exit(1);
+ }
+ setTimeout(() => {
+ process.stdout.write(JSON.stringify({ positive: [], negative: [], gaps: [${JSON.stringify(gap)}] }) + "\\n");
+ process.exit(0);
+ }, 1500);
+} else {
+ process.exit(0);
+}
+`,
+);
+fs.chmodSync(fakeAcpx, 0o755);
+
+function git(args, cwd) {
+ spawnSync("git", args, { cwd, stdio: "ignore" });
+}
+
+function initRepo() {
+ const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "backpass-stop-repo-")));
+ git(["init", "--quiet", "-b", "main"], dir);
+ git(["config", "user.email", "test@example.com"], dir);
+ git(["config", "user.name", "test"], dir);
+ fs.writeFileSync(path.join(dir, "AGENTS.md"), "# Agent instructions\n\n- Run `make build` before every push.\n");
+ git(["add", "-A"], dir);
+ git(["commit", "-q", "-m", "memory"], dir);
+ return dir;
+}
+
+/** A Pi session, non-trivial, whose modification time orders it among the others. */
+function writeSession(home, id, cwd, ageSeconds) {
+ const dir = path.join(home, ".pi", "agent", "sessions", id);
+ fs.mkdirSync(dir, { recursive: true });
+ const entries = [
+ { type: "session", version: 3, id, timestamp: new Date().toISOString(), cwd },
+ { type: "message", message: { role: "user", content: `Do the ${id} work.` } },
+ { type: "message", message: { role: "assistant", content: "Working on it." } },
+ { type: "message", message: { role: "user", content: "Now run the tests too." } },
+ { type: "message", message: { role: "assistant", content: "Tests pass." } },
+ ];
+ const file = path.join(dir, `${id}.jsonl`);
+ fs.writeFileSync(file, `${entries.map((e) => JSON.stringify(e)).join("\n")}\n`);
+ const at = new Date(Date.now() - ageSeconds * 1000);
+ fs.utimesSync(file, at, at);
+}
+
+test("a fatal analysis error stops the run from starting more model calls", () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-stop-home-"));
+ const dir = initRepo();
+ // Newest first: the doomed session and one healthy session are the first two taken.
+ ["doomed", "second", "third", "fourth", "fifth"].forEach((id, index) =>
+ writeSession(home, id, dir, 60 * (index + 1)),
+ );
+
+ const result = spawnSync(
+ process.execPath,
+ [CLI, "analyze", "--harness", "pi", "--since", "all", "--analysis-agent", "pi", "--jobs", "2"],
+ {
+ cwd: dir,
+ env: {
+ ...process.env,
+ HOME: home,
+ USERPROFILE: home,
+ PATH: `${binDir}${path.delimiter}${process.env.PATH}`,
+ BACKPASS_ACPX_BIN: fakeAcpx,
+ NO_COLOR: "1",
+ },
+ encoding: "utf8",
+ timeout: 30000,
+ },
+ );
+ const output = `${result.stdout}${result.stderr}`;
+ assert.notEqual(result.status, 0, output);
+ assert.match(output, /pinned analysis agent pi/, output);
+ const calls = fs.readFileSync(callLog, "utf8").trim().split("\n").sort();
+ assert.deepEqual(calls, ["doomed", "second"], "only the calls already in flight ran");
+
+ // Read the persisted analysis contract after the CLI has exited, not its model output.
+ const evidence = new State(dir).listEvidence();
+ assert.equal(evidence.length, 1, "only the healthy in-flight session saved evidence");
+ assert.equal(path.basename(evidence[0].transcript.path), "second.jsonl");
+ assert.equal(evidence[0].status, "ok", "the in-flight analysis succeeded despite the fatal error");
+ assert.deepEqual(evidence[0].gaps, [gap], "the healthy call's evidence survives shutdown");
+});
diff --git a/test/apply-cli.test.js b/test/apply-cli.test.js
index 234654d2..4165daaa 100644
--- a/test/apply-cli.test.js
+++ b/test/apply-cli.test.js
@@ -626,3 +626,141 @@ test("a skillsDir mismatch failure prints its message without a placeholder loca
assert.doesNotMatch(applied.output, /undefined/, "a run-level failure must not print a placeholder location");
assert.match(applied.output, /this proposal was generated with skillsDir=/);
});
+
+/** `backpass apply --decisions`, with no terminal and no review surface to fall back on. */
+function runDecided(dir, vector, extraArgs = []) {
+ const result = spawnSync(process.execPath, [CLI, "apply", "--decisions", vector, ...extraArgs], {
+ cwd: dir,
+ encoding: "utf8",
+ env: { ...process.env, NO_COLOR: "1", BACKPASS_LAVISH_BIN: path.join(dir, "no-such-lavish") },
+ });
+ return { ...result, output: `${result.stdout}${result.stderr}` };
+}
+
+function rejectionsOf(dir) {
+ const file = path.join(dir, ".backpass", "rejections.json");
+ return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")).entries : {};
+}
+
+test("--decisions writes accepted edits and remembers a rejection with its reason", () => {
+ const dir = initRepo();
+ const [accepted, rejected] = proposeExtractions(dir).edits;
+
+ const applied = runDecided(dir, `${accepted.id}=accepted ${rejected.id}=rejected:too-narrow`);
+
+ assert.equal(applied.status, 0, `apply should succeed:\n${applied.output}`);
+ assert.match(applied.output, /1 accepted · 1 rejected/);
+ const memory = fs.readFileSync(path.join(dir, "AGENTS.md"), "utf8");
+ assert.match(memory, /- Load `ci-details` for this topic\./);
+ assert.doesNotMatch(memory, /release-details/);
+ assert.equal(fs.existsSync(path.join(dir, ".agents/skills/release-details")), false);
+ assert.deepEqual(
+ Object.values(rejectionsOf(dir)).map((entry) => [entry.title, entry.reason]),
+ [[rejected.title, "too-narrow"]],
+ );
+});
+
+test("repeated --decisions apply one combined vector and preserve reject reasons", () => {
+ for (const [first, second] of [
+ ["e1=accepted", "e2=rejected:too-narrow"],
+ ["e2=rejected:too-narrow", "e1=accepted"],
+ ]) {
+ const dir = initRepo();
+ const [, rejected] = proposeExtractions(dir).edits;
+
+ const applied = runDecided(dir, first, ["--decisions", second]);
+
+ assert.equal(applied.status, 0, applied.output);
+ assert.match(applied.output, /1 accepted · 1 rejected/);
+ const memory = fs.readFileSync(path.join(dir, "AGENTS.md"), "utf8");
+ assert.match(memory, /- Load `ci-details` for this topic\./);
+ assert.doesNotMatch(memory, /release-details/);
+ assert.equal(fs.existsSync(path.join(dir, ".agents/skills/ci-details/SKILL.md")), true);
+ assert.equal(fs.existsSync(path.join(dir, ".agents/skills/release-details")), false);
+ assert.deepEqual(
+ Object.values(rejectionsOf(dir)).map((entry) => [entry.title, entry.reason]),
+ [[rejected.title, "too-narrow"]],
+ );
+ }
+});
+
+test("--decisions leaves an edit it does not name undecided", () => {
+ const dir = initRepo();
+ const [unnamed, accepted] = proposeExtractions(dir).edits;
+
+ const applied = runDecided(dir, `${accepted.id}=accepted`);
+
+ assert.equal(applied.status, 0, `apply should succeed:\n${applied.output}`);
+ const memory = fs.readFileSync(path.join(dir, "AGENTS.md"), "utf8");
+ assert.match(memory, /- Load `release-details` for this topic\./);
+ assert.doesNotMatch(memory, /ci-details/, `${unnamed.id} was never decided`);
+ assert.deepEqual(rejectionsOf(dir), {}, "an undecided edit is not a rejection");
+});
+
+test("a --decisions vector that does not decide cleanly writes nothing", () => {
+ const dir = initRepo();
+ proposeExtractions(dir);
+ const memory = path.join(dir, "AGENTS.md");
+ const before = fs.readFileSync(memory, "utf8");
+
+ for (const { vector, message } of [
+ { vector: "e1=accepted e9=rejected", message: /e9 is not an edit of this proposal/ },
+ { vector: "e1=acepted", message: /"e1=acepted" is not =accepted or =rejected\[:\]/ },
+ { vector: "e1=rejected:nope", message: /carries a reason that is not a reject reason/ },
+ { vector: "e1=accepted:disagree", message: /carries a reason that is not a reject reason/ },
+ { vector: "e1=accepted e1=rejected", message: /e1 is decided twice/ },
+ { vector: " ", message: /--decisions names no edit/ },
+ ]) {
+ const applied = runDecided(dir, vector);
+ assert.equal(applied.status, 1, `${vector}:\n${applied.output}`);
+ assert.match(applied.output, message, vector);
+ assert.equal(fs.readFileSync(memory, "utf8"), before, vector);
+ assert.equal(porcelain(dir), "", vector);
+ assert.deepEqual(rejectionsOf(dir), {}, vector);
+ }
+
+ const both = runDecided(dir, "e1=accepted", ["--no-ui"]);
+ assert.equal(both.status, 1, both.output);
+ assert.match(both.output, /--decisions and --no-ui both decide the edits/);
+ assert.equal(fs.readFileSync(memory, "utf8"), before);
+});
+
+test("repeated --decisions validate every vector before writing anything", () => {
+ for (const { first, second, message } of [
+ { first: "e1=acepted", second: "e2=accepted", message: /"e1=acepted" is not =accepted/ },
+ { first: "e1=accepted", second: "e2=acepted", message: /"e2=acepted" is not =accepted/ },
+ { first: "e9=rejected", second: "e2=accepted", message: /e9 is not an edit of this proposal/ },
+ { first: "e1=rejected:nope", second: "e2=accepted", message: /carries a reason that is not a reject reason/ },
+ { first: "e1=accepted", second: "e1=accepted", message: /e1 is decided twice/ },
+ { first: "e1=accepted", second: "e1=rejected:too-narrow", message: /e1 is decided twice/ },
+ { first: "e1=rejected:too-narrow", second: "e1=accepted", message: /e1 is decided twice/ },
+ { first: " ", second: " ", message: /--decisions names no edit/ },
+ { first: " ", second: "e1=accepted", message: /--decisions names no edit/ },
+ { first: "e1=accepted", second: "", message: /--decisions names no edit/ },
+ ]) {
+ const dir = initRepo();
+ proposeExtractions(dir);
+ const proposalFile = path.join(dir, ".backpass", "proposal.json");
+ const before = fs.readFileSync(proposalFile, "utf8");
+
+ const applied = runDecided(dir, first, ["--decisions", second]);
+
+ assert.equal(applied.status, 1, applied.output);
+ assert.match(applied.output, message);
+ assert.equal(fs.readFileSync(path.join(dir, "AGENTS.md"), "utf8"), MEMORY_TEXT);
+ assert.equal(porcelain(dir), "");
+ assert.deepEqual(rejectionsOf(dir), {});
+ assert.equal(fs.readFileSync(proposalFile, "utf8"), before, "the saved proposal is unchanged");
+ }
+});
+
+test("--decisions belongs to apply alone", () => {
+ const dir = initRepo();
+ const result = spawnSync(process.execPath, [CLI, "status", "--decisions", "e1=accepted"], {
+ cwd: dir,
+ encoding: "utf8",
+ env: { ...process.env, NO_COLOR: "1" },
+ });
+ assert.equal(result.status, 1, `${result.stdout}${result.stderr}`);
+ assert.match(`${result.stdout}${result.stderr}`, /--decisions does not apply to status/);
+});
diff --git a/test/apply-surface.test.js b/test/apply-surface.test.js
index d591f6c3..4cb84756 100644
--- a/test/apply-surface.test.js
+++ b/test/apply-surface.test.js
@@ -15,7 +15,8 @@ process.env.BACKPASS_LAVISH_BIN = path.join(
"fake-lavish",
"lavish-axi",
);
-const { extractUrl, openApplySurface, pollDecisions } = await import("../src/apply/lavish.js");
+const { extractUrl, openApplySurface, parseDecisions, parseRejectReasons, pollDecisions } =
+ await import("../src/apply/lavish.js");
const LAYOUT_REPORT = [
"prompts[1]{uid,prompt,selector,tag,text}:",
@@ -25,6 +26,14 @@ const DECISIONS = [
"prompts[1]{uid,prompt,selector,tag,text}:",
' "1","BACKPASS_DECISIONS e1=accepted e2=rejected",button#btn-apply,choice,e1=accepted e2=rejected',
].join("\n");
+const DECISIONS_WITH_REASON = [
+ "prompts[1]{uid,prompt,selector,tag,text}:",
+ ' "1","BACKPASS_DECISIONS e1=accepted e2=rejected:too-narrow e3=rejected:not-a-reason",button#btn-apply,choice,e1=accepted e2=rejected:too-narrow e3=rejected:not-a-reason',
+].join("\n");
+const ACCEPTED_REJECTED = {
+ decisions: { e1: "accepted", e2: "rejected" },
+ reasons: {},
+};
function scenario(polls, extra = {}) {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-lavish-"));
@@ -60,7 +69,7 @@ test("the wait line prints once, not once per poll cycle", async (t) => {
const decisions = await pollDecisions(surface, ["e1", "e2"], { delayMs: 0 });
- assert.deepEqual(decisions, { e1: "accepted", e2: "rejected" });
+ assert.deepEqual(decisions, ACCEPTED_REJECTED);
const waiting = lines.filter((l) => l.includes("waiting for your decisions"));
const noted = lines.filter((l) => l.includes("without a decision vector"));
assert.equal(waiting.length, 1, `wait line repeated:\n${lines.join("\n")}`);
@@ -72,7 +81,7 @@ test("a decision vector on the first poll returns with only the wait line", asyn
const lines = captureLog(t);
const surface = scenario([DECISIONS]);
const decisions = await pollDecisions(surface, ["e1", "e2"], { delayMs: 0 });
- assert.deepEqual(decisions, { e1: "accepted", e2: "rejected" });
+ assert.deepEqual(decisions, ACCEPTED_REJECTED);
assert.equal(lines.length, 1);
});
@@ -86,10 +95,7 @@ test("end-state-looking feedback does not stop polling a live session", async (t
captureLog(t);
const fieldLikeFeedback = "prompts:\n status: ended\n session_ended: true";
const surface = scenario([fieldLikeFeedback, DECISIONS]);
- assert.deepEqual(await pollDecisions(surface, ["e1", "e2"], { delayMs: 0 }), {
- e1: "accepted",
- e2: "rejected",
- });
+ assert.deepEqual(await pollDecisions(surface, ["e1", "e2"], { delayMs: 0 }), ACCEPTED_REJECTED);
});
// Only the leading `session:` block is session metadata. Everything past it - the queued
@@ -100,10 +106,7 @@ test("end fields printed at top level after the session block never end a live s
captureLog(t);
const layoutReportThenEndFields = `${LAYOUT_REPORT}\nsession_ended: true\nstatus: ended`;
const surface = scenario([layoutReportThenEndFields, DECISIONS]);
- assert.deepEqual(await pollDecisions(surface, ["e1", "e2"], { delayMs: 0 }), {
- e1: "accepted",
- e2: "rejected",
- });
+ assert.deepEqual(await pollDecisions(surface, ["e1", "e2"], { delayMs: 0 }), ACCEPTED_REJECTED);
});
test("end fields on stderr never end a live session", async (t) => {
@@ -112,19 +115,13 @@ test("end fields on stderr never end a live session", async (t) => {
{ body: LAYOUT_REPORT, stderr: "[lavish-axi] long-polling\nstatus: ended\nsession_ended: true\n" },
DECISIONS,
]);
- assert.deepEqual(await pollDecisions(surface, ["e1", "e2"], { delayMs: 0 }), {
- e1: "accepted",
- e2: "rejected",
- });
+ assert.deepEqual(await pollDecisions(surface, ["e1", "e2"], { delayMs: 0 }), ACCEPTED_REJECTED);
});
test("a `Send & End` that carries the decision vector still applies it", async (t) => {
captureLog(t);
const surface = scenario([`ENDING:${DECISIONS}`]);
- assert.deepEqual(await pollDecisions(surface, ["e1", "e2"], { delayMs: 0 }), {
- e1: "accepted",
- e2: "rejected",
- });
+ assert.deepEqual(await pollDecisions(surface, ["e1", "e2"], { delayMs: 0 }), ACCEPTED_REJECTED);
});
test("a `Send & End` with no decision vector stops rather than spinning", async (t) => {
@@ -179,3 +176,28 @@ test("headless and opted-out environments print the URL only", () => {
assert.equal(canOpenBrowser({ platform: "darwin", env: { BACKPASS_NO_BROWSER: "1" } }), false);
assert.equal(openInBrowser("http://h/s/1", { platform: "linux", env: {}, spawnFn }), false);
});
+
+test("parseDecisions accepts optional reject reasons and ignores unknown tokens", () => {
+ const ids = ["e1", "e2", "e3"];
+ const withReason = "BACKPASS_DECISIONS e1=accepted e2=rejected:too-narrow e3=rejected:not-a-reason";
+ assert.deepEqual(parseDecisions(withReason, ids), {
+ e1: "accepted",
+ e2: "rejected",
+ e3: "rejected",
+ });
+ assert.deepEqual(parseRejectReasons(withReason, ids), { e2: "too-narrow" });
+ assert.deepEqual(parseDecisions("BACKPASS_DECISIONS e1=accepted e2=rejected", ids), {
+ e1: "accepted",
+ e2: "rejected",
+ });
+ assert.deepEqual(parseRejectReasons("BACKPASS_DECISIONS e1=accepted e2=rejected", ids), {});
+});
+
+test("pollDecisions returns valid reject reasons beside the verdict map", async (t) => {
+ captureLog(t);
+ const surface = scenario([DECISIONS_WITH_REASON]);
+ assert.deepEqual(await pollDecisions(surface, ["e1", "e2", "e3"], { delayMs: 0 }), {
+ decisions: { e1: "accepted", e2: "rejected", e3: "rejected" },
+ reasons: { e2: "too-narrow" },
+ });
+});
diff --git a/test/association.test.js b/test/association.test.js
index d1f3e59d..87ffedd5 100644
--- a/test/association.test.js
+++ b/test/association.test.js
@@ -5,6 +5,7 @@ import os from "node:os";
import path from "node:path";
import { associate, globToRegExp, passesStrict } from "../src/discovery/association.js";
+import { isWindowsPath, localPath } from "../src/discovery/paths.js";
import { normalizeRemote } from "../src/repo.js";
/** A repo identity backed by one real directory, so tier-1/tier-3 liveness is genuine. */
@@ -94,6 +95,72 @@ test("tier 1.5: a live sibling clone is deterministic, not a foreign live path",
assert.equal(associate({ cwd: other }, repo), null);
});
+/** Run `fn` with the process cwd inside `dir`, the way `backpass` runs from inside a checkout. */
+function fromInside(dir, fn) {
+ const previous = process.cwd();
+ process.chdir(dir);
+ try {
+ return fn();
+ } finally {
+ process.chdir(previous);
+ }
+}
+
+const WINDOWS_CWDS = [
+ "C:\\work\\demo",
+ "C:/work/demo",
+ "D:\\Projects\\foo",
+ "\\\\server\\share\\demo",
+ "//server/share/demo",
+];
+
+test(
+ "a Windows cwd matches no path tier on POSIX, even when backpass runs inside the clone",
+ { skip: process.platform === "win32" && "Windows spells these paths natively" },
+ () => {
+ const { repo, live } = makeRepo();
+ fromInside(live, () => {
+ for (const cwd of WINDOWS_CWDS) {
+ assert.equal(associate({ cwd }, repo), null, `${cwd} is no path on this machine`);
+ assert.equal(associate({ cwd, gitRoot: cwd }, repo), null, `${cwd} as a recorded root matches nothing either`);
+ assert.equal(
+ associate({ cwd, remotes: [] }, repo, { worktreeGlobs: ["**"] }),
+ null,
+ `${cwd} never reaches the best-effort tier`,
+ );
+ }
+ const remote = associate({ cwd: "C:\\work\\demo", remotes: ["git@github.com:acme/demo.git"] }, repo);
+ assert.equal(remote.tier, 2, "a recorded remote still associates the session");
+ });
+ },
+);
+
+test("a Windows cwd from another machine reaches no tier over there either", () => {
+ const { repo } = makeRepo();
+ const facts = { "C:/work/demo": { exists: false, real: "C:/work/demo" } };
+ assert.equal(associate({ cwd: "C:/work/demo" }, repo, { facts, host: "mac-home" }), null);
+ const remote = associate({ cwd: "C:/work/demo", remotes: ["https://github.com/acme/demo"] }, repo, {
+ facts,
+ host: "mac-home",
+ });
+ assert.equal(remote.tier, 2);
+});
+
+test("localPath refuses a Windows path only where it names no place", () => {
+ for (const cwd of WINDOWS_CWDS) {
+ assert.equal(isWindowsPath(cwd), true, cwd);
+ assert.equal(localPath(cwd, { platform: "linux" }), null, cwd);
+ assert.equal(localPath(cwd, { platform: "darwin" }), null, cwd);
+ assert.equal(localPath(cwd, { platform: "win32" }), cwd, cwd);
+ }
+ for (const posix of ["/home/me/demo", "relative/demo", "/", "a:b/c"]) {
+ assert.equal(isWindowsPath(posix), false, posix);
+ assert.equal(localPath(posix, { platform: "linux" }), posix, posix);
+ }
+ assert.equal(localPath("", { platform: "linux" }), null);
+ assert.equal(localPath(null, { platform: "linux" }), null);
+});
+
test("--strict keeps only the deterministic tiers", () => {
assert.equal(passesStrict({ tier: 1 }, true), true);
assert.equal(passesStrict({ tier: 1.5 }, true), true);
diff --git a/test/cli-errors.test.js b/test/cli-errors.test.js
new file mode 100644
index 00000000..48f09fa6
--- /dev/null
+++ b/test/cli-errors.test.js
@@ -0,0 +1,59 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { reportError } from "../src/cli.js";
+import { AcpxError } from "../src/acpx.js";
+
+function capture(t) {
+ const lines = [];
+ const original = console.error;
+ console.error = (...args) => lines.push(args.join(" "));
+ t.after(() => {
+ console.error = original;
+ });
+ return lines;
+}
+
+test("a timed-out harness call exits 1 with its message and a retry hint, not a stack trace", (t) => {
+ const lines = capture(t);
+ const err = new AcpxError("acpx claude session prompt timed out after 900s", { timedOut: true });
+
+ assert.equal(reportError(err), 1);
+
+ const output = lines.join("\n");
+ assert.match(output, /error acpx claude session prompt timed out after 900s/);
+ assert.match(output, /rerun to retry/);
+ assert.match(output, /timeoutSeconds/);
+ assert.doesNotMatch(output, /\n\s+at /);
+ assert.equal(lines.length, 2);
+});
+
+test("a timed-out adapter-configuration check gets a load hint, not timeoutSeconds advice", (t) => {
+ const lines = capture(t);
+ const err = new AcpxError("acpx config show timed out verifying the codex adapter configuration", {
+ timedOut: true,
+ stage: "verify",
+ });
+
+ assert.equal(reportError(err), 1);
+
+ const output = lines.join("\n");
+ assert.match(output, /error acpx config show timed out verifying the codex adapter configuration/);
+ assert.match(output, /too slow to start/);
+ assert.match(output, /rerun when the host is less loaded/);
+ assert.doesNotMatch(output, /timeoutSeconds/);
+ assert.doesNotMatch(output, /\n\s+at /);
+ assert.equal(lines.length, 2);
+});
+
+test("a non-timeout harness failure keeps its stack trace", (t) => {
+ const lines = capture(t);
+ const err = new AcpxError("acpx claude exec failed: exit 1");
+
+ assert.equal(reportError(err), 1);
+
+ const output = lines.join("\n");
+ assert.match(output, /AcpxError: acpx claude exec failed: exit 1/);
+ assert.match(output, /\n\s+at /);
+ assert.doesNotMatch(output, /rerun to retry/);
+});
diff --git a/test/file-session-source.test.js b/test/file-session-source.test.js
index 04ce099d..9e4e4ff2 100644
--- a/test/file-session-source.test.js
+++ b/test/file-session-source.test.js
@@ -18,6 +18,9 @@ import { classifyInteraction } from "../src/interaction.js";
import { sanitizeEvidence } from "../src/analyze.js";
import { renderPrompt } from "../src/prompts.js";
import { assertSourceCurrent } from "../src/provenance.js";
+import { ATTRIBUTION_VERSION, attributeTranscripts, checkoutRoots, owningFile } from "../src/nested.js";
+import { nestedCorpora } from "../src/commands/analyze.js";
+import { State } from "../src/state.js";
const fixtures = path.join(
path.dirname(fileURLToPath(import.meta.url)),
@@ -92,6 +95,59 @@ function config(overrides = {}) {
};
}
+for (const cached of [false, true]) {
+ test(`remote external sessions stay root-only with ${cached ? "stale cached" : "fresh"} attribution`, async () => {
+ const repo = projectRepo();
+ const weight = { path: "apps/api/AGENTS.md", dir: "apps/api" };
+ const state = new State(repo.root, { exclude: false }).ensure();
+ const transcripts = [];
+ for (const [index, remote] of [true, true, false].entries()) {
+ const { root } = makeSnapshot((payload, manifest) => {
+ manifest.sourceNamespace = `attribution-${index}`;
+ payload.sourceId = manifest.sourceNamespace;
+ payload.association.cwd = path.join(repo.root, weight.dir);
+ payload.association.remotes = repo.remotes;
+ if (remote) payload.association.hostAlias = "remote-host";
+ payload.events[1].name = "edit";
+ payload.events[1].input = { path: "handler.ts" };
+ });
+ const discovered = await discoverTranscripts({
+ repo,
+ scope: projectScope(repo),
+ config: config(),
+ sessionSource: root,
+ });
+ assert.equal(discovered.transcripts.length, 1);
+ const transcript = discovered.transcripts[0];
+ assert.equal(transcript.sourceKind, "external");
+ assert.equal(transcript.host, null);
+ assert.equal(transcript.sourceHostAlias, remote ? "remote-host" : null);
+ transcripts.push(transcript);
+ }
+ const cachePath = path.join(state.root, "nested", "attribution.json");
+ if (cached)
+ state.writeJsonFile(cachePath, {
+ version: ATTRIBUTION_VERSION,
+ roots: checkoutRoots(repo),
+ entries: Object.fromEntries(
+ transcripts.map((transcript) => [
+ transcriptIdentity(transcript),
+ { content: transcript.contentSignature, paths: ["apps/api/handler.ts"] },
+ ]),
+ ),
+ });
+ const attribution = await attributeTranscripts(transcripts, repo, state);
+ const remoteIds = transcripts.slice(0, 2).map(transcriptIdentity);
+ for (const id of remoteIds) assert.equal(attribution.get(id), null);
+ assert.equal(owningFile(remoteIds, [weight], attribution), null);
+ assert.deepEqual(attribution.get(transcriptIdentity(transcripts[2])), ["apps/api/handler.ts"]);
+ const { corpora } = await nestedCorpora({ repo, config: { state } }, [weight], transcripts);
+ assert.deepEqual(corpora[0].transcripts, [transcripts[2]]);
+ const saved = state.readJsonFile(cachePath, null);
+ for (const id of remoteIds) assert.equal(saved.entries[id], undefined);
+ });
+}
+
test("golden source scans and reads with origin harness, project, interaction, and stable identity", async () => {
const repo = projectRepo();
const { temp, root } = makeSnapshot((payload) => {
diff --git a/test/fixtures/opencode-v1-store.json b/test/fixtures/opencode-v1-store.json
new file mode 100644
index 00000000..f09ff295
--- /dev/null
+++ b/test/fixtures/opencode-v1-store.json
@@ -0,0 +1,122 @@
+{
+ "comment": "OpenCode 1.x store (1.18.32): DDL copied from a real opencode.db, rows modeled field-for-field on real message and part rows with the text replaced. 1.x also creates the session_message table its successor uses, empty.",
+ "schema": [
+ "CREATE TABLE `project` (\n `id` text PRIMARY KEY,\n `worktree` text NOT NULL,\n `vcs` text,\n `name` text,\n `icon_url` text,\n `icon_url_override` text,\n `icon_color` text,\n `time_created` integer NOT NULL,\n `time_updated` integer NOT NULL,\n `time_initialized` integer,\n `sandboxes` text NOT NULL,\n `commands` text\n )",
+ "CREATE TABLE `session` (\n `id` text PRIMARY KEY,\n `project_id` text NOT NULL,\n `workspace_id` text,\n `parent_id` text,\n `slug` text NOT NULL,\n `directory` text NOT NULL,\n `path` text,\n `title` text NOT NULL,\n `version` text NOT NULL,\n `share_url` text,\n `summary_additions` integer,\n `summary_deletions` integer,\n `summary_files` integer,\n `summary_diffs` text,\n `metadata` text,\n `cost` real DEFAULT 0 NOT NULL,\n `tokens_input` integer DEFAULT 0 NOT NULL,\n `tokens_output` integer DEFAULT 0 NOT NULL,\n `tokens_reasoning` integer DEFAULT 0 NOT NULL,\n `tokens_cache_read` integer DEFAULT 0 NOT NULL,\n `tokens_cache_write` integer DEFAULT 0 NOT NULL,\n `revert` text,\n `permission` text,\n `agent` text,\n `model` text,\n `time_created` integer NOT NULL,\n `time_updated` integer NOT NULL,\n `time_compacting` integer,\n `time_archived` integer,\n CONSTRAINT `fk_session_project_id_project_id_fk` FOREIGN KEY (`project_id`) REFERENCES `project`(`id`) ON DELETE CASCADE\n )",
+ "CREATE INDEX `session_project_idx` ON `session` (`project_id`)",
+ "CREATE INDEX `session_workspace_idx` ON `session` (`workspace_id`)",
+ "CREATE INDEX `session_parent_idx` ON `session` (`parent_id`)",
+ "CREATE TABLE `message` (\n `id` text PRIMARY KEY,\n `session_id` text NOT NULL,\n `time_created` integer NOT NULL,\n `time_updated` integer NOT NULL,\n `data` text NOT NULL,\n CONSTRAINT `fk_message_session_id_session_id_fk` FOREIGN KEY (`session_id`) REFERENCES `session`(`id`) ON DELETE CASCADE\n )",
+ "CREATE INDEX `message_session_time_created_id_idx` ON `message` (`session_id`,`time_created`,`id`)",
+ "CREATE TABLE `part` (\n `id` text PRIMARY KEY,\n `message_id` text NOT NULL,\n `session_id` text NOT NULL,\n `time_created` integer NOT NULL,\n `time_updated` integer NOT NULL,\n `data` text NOT NULL,\n CONSTRAINT `fk_part_message_id_message_id_fk` FOREIGN KEY (`message_id`) REFERENCES `message`(`id`) ON DELETE CASCADE\n )",
+ "CREATE INDEX `part_message_id_id_idx` ON `part` (`message_id`,`id`)",
+ "CREATE INDEX `part_session_idx` ON `part` (`session_id`)",
+ "CREATE TABLE `session_message` (\n `id` text PRIMARY KEY,\n `session_id` text NOT NULL,\n `type` text NOT NULL,\n `seq` integer NOT NULL,\n `time_created` integer NOT NULL,\n `time_updated` integer NOT NULL,\n `data` text NOT NULL,\n CONSTRAINT `fk_session_message_session_id_session_id_fk` FOREIGN KEY (`session_id`) REFERENCES `session`(`id`) ON DELETE CASCADE\n )"
+ ],
+ "rows": {
+ "project": [
+ {
+ "id": "28f22e59894e2c9ac7a8b3d6f5a5e3e41d2b7c10",
+ "worktree": "/repo/demo",
+ "vcs": "git",
+ "time_created": 1790605000000,
+ "time_updated": 1790605000000,
+ "sandboxes": "[]"
+ }
+ ],
+ "session": [
+ {
+ "id": "ses_f16e2d036ffeZd4lFcWRZCBMYV",
+ "project_id": "28f22e59894e2c9ac7a8b3d6f5a5e3e41d2b7c10",
+ "parent_id": null,
+ "slug": "gentle-comet",
+ "directory": "/repo/demo",
+ "title": "Parser fix",
+ "version": "1.18.32",
+ "time_created": 1790605317380,
+ "time_updated": 1790605324420
+ }
+ ],
+ "message": [
+ {
+ "id": "msg_0e864d504001D08PKrPyomGw72",
+ "session_id": "ses_f16e2d036ffeZd4lFcWRZCBMYV",
+ "time_created": 1790605317380,
+ "time_updated": 1790605317380,
+ "data": { "role": "user", "time": { "created": 1790605317380 }, "agent": "build", "model": { "providerID": "github-copilot", "modelID": "gpt-5.6-terra" }, "summary": { "diffs": [] } }
+ },
+ {
+ "id": "msg_0e864d51f001xQ2ZXd1YkNT6Ub",
+ "session_id": "ses_f16e2d036ffeZd4lFcWRZCBMYV",
+ "time_created": 1790605317429,
+ "time_updated": 1790605324420,
+ "data": { "parentID": "msg_0e864d504001D08PKrPyomGw72", "role": "assistant", "mode": "build", "agent": "build", "path": { "cwd": "/repo/demo", "root": "/repo/demo" }, "cost": 0.0210735, "tokens": { "total": 8411, "input": 8406, "output": 5, "reasoning": 0, "cache": { "write": 0, "read": 0 } }, "modelID": "gpt-5.6-terra", "providerID": "github-copilot", "time": { "created": 1790605317429, "completed": 1790605324420 }, "finish": "tool-calls" }
+ },
+ {
+ "id": "msg_0e864d6ab001fM3kC8wqJ0sQyL",
+ "session_id": "ses_f16e2d036ffeZd4lFcWRZCBMYV",
+ "time_created": 1790605324500,
+ "time_updated": 1790605325000,
+ "data": { "parentID": "msg_0e864d504001D08PKrPyomGw72", "role": "assistant", "mode": "build", "agent": "build", "path": { "cwd": "/repo/demo", "root": "/repo/demo" }, "cost": 0.001, "modelID": "gpt-5.6-terra", "providerID": "github-copilot", "time": { "created": 1790605324500, "completed": 1790605325000 }, "finish": "stop" }
+ }
+ ],
+ "part": [
+ {
+ "id": "prt_0e864d504002aT0SjrP1h8QmZ3",
+ "message_id": "msg_0e864d504001D08PKrPyomGw72",
+ "session_id": "ses_f16e2d036ffeZd4lFcWRZCBMYV",
+ "time_created": 1790605317380,
+ "time_updated": 1790605317380,
+ "data": { "type": "text", "text": "Open a PR for the parser fix." }
+ },
+ {
+ "id": "prt_0e864d520001Ry7iH2XjV9nKcP",
+ "message_id": "msg_0e864d51f001xQ2ZXd1YkNT6Ub",
+ "session_id": "ses_f16e2d036ffeZd4lFcWRZCBMYV",
+ "time_created": 1790605317430,
+ "time_updated": 1790605317430,
+ "data": { "type": "step-start", "snapshot": "f48752d17359ebb3869344a9d8aa578704c78bed" }
+ },
+ {
+ "id": "prt_0e864d521001bqL5mW3sVx8dTe",
+ "message_id": "msg_0e864d51f001xQ2ZXd1YkNT6Ub",
+ "session_id": "ses_f16e2d036ffeZd4lFcWRZCBMYV",
+ "time_created": 1790605317440,
+ "time_updated": 1790605318000,
+ "data": { "type": "reasoning", "text": "internal reasoning about the parser", "time": { "start": 1790605317440, "end": 1790605318000 }, "metadata": { "copilot": { "itemId": "OPAQUE" } } }
+ },
+ {
+ "id": "prt_0e864d522001Hc4nPz7uTg1wXa",
+ "message_id": "msg_0e864d51f001xQ2ZXd1YkNT6Ub",
+ "session_id": "ses_f16e2d036ffeZd4lFcWRZCBMYV",
+ "time_created": 1790605318010,
+ "time_updated": 1790605318010,
+ "data": { "type": "text", "text": "I'll run the tests first.", "time": { "start": 1790605318010, "end": 1790605318010 } }
+ },
+ {
+ "id": "prt_0e864d523001Kq9vBn2cLr5yMd",
+ "message_id": "msg_0e864d51f001xQ2ZXd1YkNT6Ub",
+ "session_id": "ses_f16e2d036ffeZd4lFcWRZCBMYV",
+ "time_created": 1790605318020,
+ "time_updated": 1790605324000,
+ "data": { "type": "tool", "tool": "bash", "callID": "call_jIlQmostJGFXrjUPNc4XhB1E", "state": { "status": "completed", "input": { "command": "npm test", "workdir": "/repo/demo" }, "output": "2 passing\n", "metadata": { "output": "2 passing\n", "exit": 0, "truncated": false }, "title": "npm test", "time": { "start": 1790605318020, "end": 1790605324000 } } }
+ },
+ {
+ "id": "prt_0e864d524001Wm6xFt3pQj8rNb",
+ "message_id": "msg_0e864d51f001xQ2ZXd1YkNT6Ub",
+ "session_id": "ses_f16e2d036ffeZd4lFcWRZCBMYV",
+ "time_created": 1790605324400,
+ "time_updated": 1790605324400,
+ "data": { "reason": "tool-calls", "snapshot": "f48752d17359ebb3869344a9d8aa578704c78bed", "type": "step-finish", "tokens": { "total": 8411, "input": 8406, "output": 5, "reasoning": 0, "cache": { "write": 0, "read": 0 } }, "cost": 0.0210735 }
+ },
+ {
+ "id": "prt_0e864d6ac001Zs3bYh7kNw2qVe",
+ "message_id": "msg_0e864d6ab001fM3kC8wqJ0sQyL",
+ "session_id": "ses_f16e2d036ffeZd4lFcWRZCBMYV",
+ "time_created": 1790605324600,
+ "time_updated": 1790605324600,
+ "data": { "type": "text", "text": "Opened PR #2731." }
+ }
+ ]
+ }
+}
diff --git a/test/fixtures/opencode-v2-store.json b/test/fixtures/opencode-v2-store.json
new file mode 100644
index 00000000..33f6b80f
--- /dev/null
+++ b/test/fixtures/opencode-v2-store.json
@@ -0,0 +1,337 @@
+{
+ "comment": "OpenCode 2.x store (2.0.18): DDL copied from a real opencode.db, rows modeled field-for-field on real session_message rows with the text replaced.",
+ "schema": [
+ "CREATE TABLE `project` (\n `id` text PRIMARY KEY,\n `worktree` text NOT NULL,\n `vcs` text,\n `name` text,\n `icon_url` text,\n `icon_url_override` text,\n `icon_color` text,\n `time_created` integer NOT NULL,\n `time_updated` integer NOT NULL,\n `time_initialized` integer,\n `time_active` integer DEFAULT 0 NOT NULL,\n `sandboxes` text NOT NULL,\n `commands` text\n )",
+ "CREATE TABLE `session_v2` (\n `id` text PRIMARY KEY,\n `project_id` text NOT NULL,\n `workspace_id` text,\n `parent_id` text,\n `fork_session_id` text,\n `fork_boundary` text,\n `slug` text NOT NULL,\n `directory` text NOT NULL,\n `path` text,\n `title` text,\n `version` text NOT NULL,\n `share_url` text,\n `summary_additions` integer,\n `summary_deletions` integer,\n `summary_files` integer,\n `summary_diffs` text,\n `metadata` text,\n `cost` real DEFAULT 0 NOT NULL,\n `tokens_input` integer DEFAULT 0 NOT NULL,\n `tokens_output` integer DEFAULT 0 NOT NULL,\n `tokens_reasoning` integer DEFAULT 0 NOT NULL,\n `tokens_cache_read` integer DEFAULT 0 NOT NULL,\n `tokens_cache_write` integer DEFAULT 0 NOT NULL,\n `revert` text,\n `permission` text,\n `agent` text,\n `model` text,\n `time_created` integer NOT NULL,\n `time_updated` integer NOT NULL,\n `time_idle` integer,\n `time_viewed` integer,\n `idle_outcome` text,\n `time_compacting` integer,\n `time_archived` integer,\n `time_suspended` integer,\n `resume_attempts` integer DEFAULT 0 NOT NULL,\n CONSTRAINT `fk_session_v2_project_id_project_id_fk` FOREIGN KEY (`project_id`) REFERENCES `project`(`id`) ON DELETE CASCADE\n )",
+ "CREATE INDEX `session_v2_project_idx` ON `session_v2` (`project_id`)",
+ "CREATE INDEX `session_v2_workspace_idx` ON `session_v2` (`workspace_id`)",
+ "CREATE INDEX `session_v2_parent_idx` ON `session_v2` (`parent_id`)",
+ "CREATE TABLE `session_message` (\n `id` text PRIMARY KEY,\n `session_id` text NOT NULL,\n `type` text NOT NULL,\n `seq` integer NOT NULL,\n `time_created` integer NOT NULL,\n `time_updated` integer NOT NULL,\n `data` text NOT NULL,\n CONSTRAINT `fk_session_message_session_id_session_v2_id_fk` FOREIGN KEY (`session_id`) REFERENCES `session_v2`(`id`) ON DELETE CASCADE\n )",
+ "CREATE UNIQUE INDEX `session_message_session_seq_idx` ON `session_message` (`session_id`,`seq`)",
+ "CREATE INDEX `session_message_session_type_seq_idx` ON `session_message` (`session_id`,`type`,`seq`)",
+ "CREATE INDEX `session_message_session_time_created_id_idx` ON `session_message` (`session_id`,`time_created`,`id`)",
+ "CREATE INDEX `session_message_time_created_idx` ON `session_message` (`time_created`)"
+ ],
+ "rows": {
+ "project": [
+ {
+ "id": "4543ef05f941fa749aeee49424f45ba51263fe31",
+ "worktree": "/repo/demo",
+ "vcs": "git",
+ "name": null,
+ "time_created": 1790600000000,
+ "time_updated": 1790600000000,
+ "time_active": 1790600000000,
+ "sandboxes": "[]"
+ }
+ ],
+ "session_v2": [
+ {
+ "id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "project_id": "4543ef05f941fa749aeee49424f45ba51263fe31",
+ "parent_id": null,
+ "slug": "quiet-harbor",
+ "directory": "/repo/demo",
+ "title": "Parser fix",
+ "version": "2.0.18",
+ "agent": "build",
+ "model": "{\"id\":\"claude-opus-5.5\",\"providerID\":\"github-copilot\",\"variant\":\"max\"}",
+ "time_created": 1790600000000,
+ "time_updated": 1790600000005
+ },
+ {
+ "id": "ses_f17c42540ffeM0ZIydCm19byyr",
+ "project_id": "4543ef05f941fa749aeee49424f45ba51263fe31",
+ "parent_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "slug": "brave-lantern",
+ "directory": "/repo/demo",
+ "title": "Review the parser fix",
+ "version": "2.0.18",
+ "agent": "general",
+ "model": "{\"id\":\"claude-opus-5.5\",\"providerID\":\"github-copilot\",\"variant\":\"max\"}",
+ "time_created": 1790600003000,
+ "time_updated": 1790600003006
+ },
+ {
+ "id": "ses_f139e87ceffeqUsW26A55Cc7W1",
+ "project_id": "4543ef05f941fa749aeee49424f45ba51263fe31",
+ "parent_id": null,
+ "slug": "calm-meadow",
+ "directory": "/repo/demo",
+ "title": "OK",
+ "version": "2.0.18",
+ "time_created": 1790600100000,
+ "time_updated": 1790600100004
+ },
+ {
+ "id": "ses_f0a1b2c3dffeResumedSession01",
+ "project_id": "4543ef05f941fa749aeee49424f45ba51263fe31",
+ "parent_id": null,
+ "slug": "old-river",
+ "directory": "/repo/demo",
+ "title": "Release checklist",
+ "version": "2.0.18",
+ "time_created": 1780000000000,
+ "time_updated": 1780000000006
+ },
+ {
+ "id": "ses_f1378472bffeProbeEmptySess1",
+ "project_id": "4543ef05f941fa749aeee49424f45ba51263fe31",
+ "parent_id": null,
+ "slug": "still-pond",
+ "directory": "/repo/demo",
+ "title": "New session - 2026-09-29T09:38:32.788Z",
+ "version": "2.0.18",
+ "time_created": 1790600150000,
+ "time_updated": 1790600150002
+ },
+ {
+ "id": "ses_f139e880dffeSelfChildSess01",
+ "project_id": "4543ef05f941fa749aeee49424f45ba51263fe31",
+ "parent_id": "ses_f139e87ceffeqUsW26A55Cc7W1",
+ "slug": "quick-heron",
+ "directory": "/repo/demo",
+ "title": "Summarize the trace",
+ "version": "2.0.18",
+ "time_created": 1790600100200,
+ "time_updated": 1790600100206
+ }
+ ],
+ "session_message": [
+ {
+ "id": "msg_probe_instruction",
+ "session_id": "ses_f1378472bffeProbeEmptySess1",
+ "type": "synthetic",
+ "seq": 0,
+ "time_created": 1790600150001,
+ "time_updated": 1790600150001,
+ "data": { "metadata": { "instruction": { "paths": ["/repo/demo/AGENTS.md"] } }, "text": "Instructions from: /repo/demo/AGENTS.md" }
+ },
+ {
+ "id": "msg_probe_system",
+ "session_id": "ses_f1378472bffeProbeEmptySess1",
+ "type": "system",
+ "seq": 1,
+ "time_created": 1790600150002,
+ "time_updated": 1790600150002,
+ "data": { "metadata": { "notice": "instructions" }, "text": "Instructions updated" }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000000",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "synthetic",
+ "seq": 0,
+ "time_created": 1790600000010,
+ "time_updated": 1790600000010,
+ "data": { "metadata": { "instruction": { "paths": ["/repo/demo/AGENTS.md"] } }, "time": { "created": 1790600000010 }, "text": "Instructions from: /repo/demo/AGENTS.md\n# Demo\n\n- Keep PRs small.", "description": "Loaded AGENTS.md" }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000001",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "system",
+ "seq": 1,
+ "time_created": 1790600000011,
+ "time_updated": 1790600000011,
+ "data": { "metadata": { "notice": "instructions", "instructionSources": ["core/date"] }, "time": { "created": 1790600000011 }, "text": "Today's date is Tue Sep 29 2026.", "description": "Instructions updated: core/date" }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000002",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "user",
+ "seq": 2,
+ "time_created": 1790600000012,
+ "time_updated": 1790600000012,
+ "data": { "metadata": { "displayText": "Open a PR for the parser fix.", "comments": [], "attachments": [], "agent": "build", "model": { "modelID": "claude-opus-5.5", "providerID": "github-copilot", "variant": "max" } }, "time": { "created": 1790600000012 }, "text": "Open a PR for the parser fix.", "files": [], "agents": [] }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000003",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "assistant",
+ "seq": 3,
+ "time_created": 1790600000100,
+ "time_updated": 1790600002900,
+ "data": { "time": { "created": 1790600000100, "streamed": 1790600001000, "completed": 1790600002900 }, "agent": "build", "model": { "id": "claude-opus-5.5", "providerID": "github-copilot", "variant": "max" }, "content": [ { "type": "reasoning", "text": "internal reasoning about the parser", "state": { "reasoningOpaque": "OPAQUE" }, "time": { "created": 1790600000200, "completed": 1790600000300 } }, { "type": "text", "text": "I'll run the tests first.", "state": { "reasoningOpaque": "OPAQUE" } }, { "type": "tool", "id": "toolu_01JFEeX4BmwwZN4sZGKiCoNw", "name": "shell", "executed": false, "state": { "status": "completed", "input": { "command": "npm test", "workdir": "/repo/demo" }, "content": [ { "type": "text", "text": "2 passing" } ], "metadata": { "exit": 0, "truncated": false } }, "time": { "created": 1790600000400, "ran": 1790600000410, "completed": 1790600001400 } }, { "type": "tool", "id": "toolu_01V36JvUoKMVoah95Aeh6zT1", "name": "read", "executed": false, "state": { "status": "completed", "input": { "path": "/repo/demo/src/parser.ts" }, "content": [ { "type": "text", "text": "Read file /repo/demo/src/parser.ts, lines 1-1\n1: export function parse() {}" }, { "type": "file", "mime": "image/png", "uri": "data:image/png;base64,AAAA" } ], "metadata": { "truncated": false } }, "time": { "created": 1790600001500, "ran": 1790600001510, "completed": 1790600001600 } }, { "type": "tool", "id": "toolu_016aoVojXHjQBqHr77sZKwTw", "name": "subagent", "executed": false, "state": { "status": "completed", "input": { "agent": "general", "description": "Review the parser fix", "background": true, "prompt": "You are a subagent spawned by another session.\nReview src/parser.ts." }, "content": [ { "type": "text", "text": "The subagent is working in the background (sessionID: ses_f17c42540ffeM0ZIydCm19byyr). You will be notified automatically when it finishes." } ], "metadata": { "sessionID": "ses_f17c42540ffeM0ZIydCm19byyr", "status": "running", "truncated": false } }, "time": { "created": 1790600002800, "ran": 1790600002810, "completed": 1790600002900 } } ], "finish": "tool-calls", "rawFinish": "tool_use", "cost": 0, "tokens": { "input": 1200, "output": 80, "reasoning": 20, "cache": { "read": 0, "write": 0 } } }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000004",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "synthetic",
+ "seq": 4,
+ "time_created": 1790600009000,
+ "time_updated": 1790600009000,
+ "data": { "metadata": { "source": "subagent", "childID": "ses_f17c42540ffeM0ZIydCm19byyr", "agent": "General", "state": "completed" }, "time": { "created": 1790600009000 }, "text": "\nNo blocking findings.\n", "description": "Review the parser fix" }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000005",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "synthetic",
+ "seq": 5,
+ "time_created": 1790600009100,
+ "time_updated": 1790600009100,
+ "data": { "time": { "created": 1790600009100 }, "text": "The previous response was interrupted. Continue from where you left off without repeating completed content." }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000006",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "assistant",
+ "seq": 6,
+ "time_created": 1790600009200,
+ "time_updated": 1790600009900,
+ "data": { "time": { "created": 1790600009200, "streamed": 1790600009500, "completed": 1790600009900 }, "agent": "build", "model": { "id": "claude-opus-5.5", "providerID": "github-copilot", "variant": "max" }, "content": [ { "type": "text", "text": "Opened PR #2731." }, { "type": "tool", "id": "toolu_014JCBUtjLo8UwvgmRfCqxsE", "name": "edit", "executed": false, "state": { "status": "error", "input": { "path": "/repo/demo/CHANGELOG.md", "oldString": "## Unreleased", "newString": "## 1.2.0" }, "error": { "type": "unknown", "message": "oldString not found in content" } }, "time": { "created": 1790600009600, "ran": 1790600009610, "completed": 1790600009620 } } ], "finish": "tool-calls", "cost": 0 }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000007",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "shell",
+ "seq": 7,
+ "time_created": 1790600010000,
+ "time_updated": 1790600010500,
+ "data": { "time": { "created": 1790600010000, "completed": 1790600010500 }, "shellID": "sh_0e84bf223001llrLlaYLNLlK4a", "command": "git status --short", "status": "exited", "exit": 0, "output": { "output": "nothing to commit", "cursor": 17, "size": 17, "truncated": false } }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000008",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "synthetic",
+ "seq": 8,
+ "time_created": 1790600010600,
+ "time_updated": 1790600010600,
+ "data": { "metadata": { "source": "shell", "shellID": "sh_0e84bf223001llrLlaYLNLlK4a", "state": "completed", "truncated": false, "exit": 0 }, "time": { "created": 1790600010600 }, "text": "The following shell command was executed by the user:\n\nnothing to commit\n", "description": "git status --short" }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000009",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "skill",
+ "seq": 9,
+ "time_created": 1790600011000,
+ "time_updated": 1790600011000,
+ "data": { "time": { "created": 1790600011000 }, "skill": "skl_release", "name": "release", "text": "# Release\n\nTag from main only." }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000010",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "compaction",
+ "seq": 10,
+ "time_created": 1790600012000,
+ "time_updated": 1790600013000,
+ "data": { "time": { "created": 1790600012000 }, "status": "completed", "reason": "auto", "model": { "id": "claude-opus-5.5", "providerID": "github-copilot", "variant": "max" }, "summary": "## Objective\n- Ship the parser fix.", "recent": "Opened PR #2731.", "cost": 0, "tokens": { "input": 3000, "output": 200, "reasoning": 0, "cache": { "read": 0, "write": 0 } } }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000011",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "idle",
+ "seq": 11,
+ "time_created": 1790600013100,
+ "time_updated": 1790600013100,
+ "data": { "time": { "created": 1790600013100 }, "outcome": "succeeded" }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000012",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "location-switched",
+ "seq": 12,
+ "time_created": 1790600013200,
+ "time_updated": 1790600013200,
+ "data": { "time": { "created": 1790600013200 }, "location": { "directory": "/repo/demo" }, "projectID": "4543ef05f941fa749aeee49424f45ba51263fe31", "subpath": "", "previous": { "location": { "directory": "/repo" }, "subpath": "" } }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000013",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "user",
+ "seq": 13,
+ "time_created": 1790600014000,
+ "time_updated": 1790600014000,
+ "data": { "metadata": { "source": "telegram", "telegram_message_id": 42 }, "time": { "created": 1790600014000 }, "text": "Thanks, ship it." }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000014",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "assistant",
+ "seq": 14,
+ "time_created": 1790600014100,
+ "time_updated": 1790600014900,
+ "data": { "time": { "created": 1790600014100, "streamed": 1790600014500, "completed": 1790600014900 }, "agent": "build", "model": { "id": "claude-opus-5.5", "providerID": "github-copilot", "variant": "max" }, "content": [ { "type": "text", "text": "Building the release." }, { "type": "tool", "id": "toolu_0185LfzLFCjFzeDGnR5Wf3Yp", "name": "shell", "executed": false, "state": { "status": "completed", "input": { "command": "npm run build", "background": true }, "content": [ { "type": "text", "text": "Command moved to the background (shell ID: sh_0e84aacd7001hD1EEplKBz5KVr)." } ], "metadata": { "status": "running", "truncated": false, "shellID": "sh_0e84aacd7001hD1EEplKBz5KVr" } }, "time": { "created": 1790600014600, "ran": 1790600014610, "completed": 1790600014700 } } ], "finish": "tool-calls", "cost": 0 }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000015",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "synthetic",
+ "seq": 15,
+ "time_created": 1790600020000,
+ "time_updated": 1790600020000,
+ "data": { "metadata": { "source": "shell", "shellID": "sh_0e84aacd7001hD1EEplKBz5KVr", "jobID": "sh_0e84aacd7001hD1EEplKBz5KVr", "state": "error", "truncated": false, "exit": 1 }, "time": { "created": 1790600020000 }, "text": "\nbuild failed: missing dist/\n", "description": "npm run build" }
+ },
+ {
+ "id": "msg_0e84aacd7001parent00000016",
+ "session_id": "ses_f17ca477affeM7vJpYuwLTunDK",
+ "type": "assistant",
+ "seq": 16,
+ "time_created": 1790600020100,
+ "time_updated": 1790600020800,
+ "data": { "time": { "created": 1790600020100, "completed": 1790600020800 }, "agent": "build", "model": { "id": "claude-opus-5.5", "providerID": "github-copilot", "variant": "max" }, "content": [ { "type": "text", "text": "The build failed; I will fix dist/ first." } ], "finish": "stop", "cost": 0 }
+ },
+ {
+ "id": "msg_0e84aacd7001child000000000",
+ "session_id": "ses_f17c42540ffeM0ZIydCm19byyr",
+ "type": "user",
+ "seq": 0,
+ "time_created": 1790600003010,
+ "time_updated": 1790600003010,
+ "data": { "time": { "created": 1790600003010 }, "text": "You are a subagent spawned by another session.\nReview src/parser.ts." }
+ },
+ {
+ "id": "msg_0e84aacd7001child000000001",
+ "session_id": "ses_f17c42540ffeM0ZIydCm19byyr",
+ "type": "assistant",
+ "seq": 1,
+ "time_created": 1790600003100,
+ "time_updated": 1790600008900,
+ "data": { "time": { "created": 1790600003100, "completed": 1790600008900 }, "agent": "general", "model": { "id": "claude-opus-5.5", "providerID": "github-copilot", "variant": "max" }, "content": [ { "type": "text", "text": "No blocking findings." } ], "finish": "stop", "cost": 0 }
+ },
+ {
+ "id": "msg_0e84aacd7001self0000000000",
+ "session_id": "ses_f139e87ceffeqUsW26A55Cc7W1",
+ "type": "user",
+ "seq": 0,
+ "time_created": 1790600100010,
+ "time_updated": 1790600100010,
+ "data": { "time": { "created": 1790600100010 }, "text": "\nReply with the single word OK and nothing else." }
+ },
+ {
+ "id": "msg_0e84aacd7001self0000000001",
+ "session_id": "ses_f139e87ceffeqUsW26A55Cc7W1",
+ "type": "assistant",
+ "seq": 1,
+ "time_created": 1790600100100,
+ "time_updated": 1790600100900,
+ "data": { "time": { "created": 1790600100100, "completed": 1790600100900 }, "agent": "build", "model": { "id": "claude-opus-5.5", "providerID": "github-copilot" }, "content": [ { "type": "text", "text": "OK" } ], "finish": "stop", "cost": 0 }
+ },
+ {
+ "id": "msg_0e84aacd7001selfchild00000",
+ "session_id": "ses_f139e880dffeSelfChildSess01",
+ "type": "user",
+ "seq": 0,
+ "time_created": 1790600100210,
+ "time_updated": 1790600100210,
+ "data": { "time": { "created": 1790600100210 }, "text": "You are a subagent spawned by another session.\nSummarize the trace." }
+ },
+ {
+ "id": "msg_0e84aacd7001resumed0000000",
+ "session_id": "ses_f0a1b2c3dffeResumedSession01",
+ "type": "user",
+ "seq": 0,
+ "time_created": 1780000000010,
+ "time_updated": 1780000000010,
+ "data": { "time": { "created": 1780000000010 }, "text": "Draft the release checklist." }
+ },
+ {
+ "id": "msg_0e84aacd7001resumed0000001",
+ "session_id": "ses_f0a1b2c3dffeResumedSession01",
+ "type": "user",
+ "seq": 1,
+ "time_created": 1790600200000,
+ "time_updated": 1790600200000,
+ "data": { "time": { "created": 1790600200000 }, "text": "Picking this up again: add the rollback step." }
+ }
+ ]
+ }
+}
diff --git a/test/fold.test.js b/test/fold.test.js
index 03507a37..39147622 100644
--- a/test/fold.test.js
+++ b/test/fold.test.js
@@ -186,6 +186,31 @@ test("near-duplicate gaps from different sessions cluster into one item", () =>
assert.equal(summary.gaps[0].quotes.length, 2);
});
+test("a cluster of ledger observations surfaces the union of entry ids", () => {
+ const summary = foldEvidence([], {
+ minGapEvidence: 2,
+ gapObservations: [
+ {
+ proposedInstruction: "Read docs/db.md before writing queries.",
+ sessionId: "a",
+ quote: "walked migrations",
+ gapId: "id-one",
+ domain: "project",
+ },
+ {
+ proposedInstruction: "Read docs/db.md before writing database queries.",
+ sessionId: "b",
+ quote: "rebuilt the schema",
+ gapId: "id-two",
+ domain: "project",
+ },
+ ],
+ });
+ assert.equal(summary.gaps.length, 1);
+ assert.equal(summary.gaps[0].id, undefined);
+ assert.deepEqual(summary.gaps[0].ids, ["id-one", "id-two"]);
+});
+
test("a gap seen in only one session is dropped - batch size greater than one", () => {
const summary = foldEvidence(
[
diff --git a/test/gap-ledger.test.js b/test/gap-ledger.test.js
index 5eb5add6..417ed8c7 100644
--- a/test/gap-ledger.test.js
+++ b/test/gap-ledger.test.js
@@ -215,6 +215,21 @@ test("a later uncited observation preserves the session's failed-trigger citatio
assert.equal(summary.gaps[0].failedTriggerSessions, 2);
});
+test("ledger observations carry the entry id onto the folded cluster", () => {
+ const phrasing = "Always pin the Node version with nvm.";
+ const ledger = { version: 1, entries: {} };
+ recordGapObservations(ledger, [
+ record("s1", [{ proposedInstruction: phrasing }]),
+ record("s2", [{ proposedInstruction: phrasing }]),
+ ]);
+ const observations = ledgerGapObservations(ledger, MEMORY_PATH);
+ assert.ok(observations.every((observation) => observation.gapIds?.length));
+ const summary = foldEvidence([], { gapObservations: observations, minGapEvidence: 2 });
+ const entryId = Object.keys(ledger.entries)[0];
+ assert.equal(summary.gaps[0].id, entryId);
+ assert.deepEqual(summary.gaps[0].ids, [entryId]);
+});
+
test("a sighting older than gapLedgerMaxAge expires instead of resurfacing indefinitely", async () => {
const h = harness({ gapLedgerMaxAge: "90d" });
await run(h, [record("claude-s1", [GAP])]);
@@ -376,6 +391,18 @@ test("mergeGapEntries unions sessions without double-counting and keeps the shor
assert.deepEqual(Object.keys(entries[0].sessions).sort(), ["s1", "s2", "shared"], "a session never counts twice");
});
+test("a merged entry keeps the absorbed entry id in its folded gap identity", () => {
+ const absorbedId = "a".repeat(16);
+ const targetId = "b".repeat(16);
+ const ledger = ledgerWith(
+ { id: absorbedId, text: "Pin the Node version with nvm before scripts.", sessions: ["s1"] },
+ { id: targetId, text: "Pin Node with nvm.", sessions: ["s2", "s3"] },
+ );
+ mergeGapEntries(ledger, [[absorbedId, targetId]]);
+ const summary = foldEvidence([], { gapObservations: ledgerGapObservations(ledger, MEMORY_PATH), minGapEvidence: 2 });
+ assert.deepEqual(summary.gaps[0].ids, [absorbedId, targetId]);
+});
+
test("mergeGapEntries reconciles conflicting domain votes without target-order bias", () => {
const orchestrationId = "a".repeat(16);
const projectId = "b".repeat(16);
diff --git a/test/harness-invoke.test.js b/test/harness-invoke.test.js
index 9711caf4..d8df2993 100644
--- a/test/harness-invoke.test.js
+++ b/test/harness-invoke.test.js
@@ -108,6 +108,21 @@ fs.appendFileSync(process.env.FAKE_ACPX_LOG, JSON.stringify({
CODEX_PATH: process.env.CODEX_PATH || null,
}) + "\\n");
const settings = process.env.FAKE_HARNESS_SETTINGS;
+// FAKE_CONFIG_SHOW_HANG: "always" hangs every config show until killed; "once" hangs only
+// the first one (the marker file records it), modelling a loaded host where node is slow
+// to start.
+const hang = process.env.FAKE_CONFIG_SHOW_HANG;
+const hangMarker = process.env.FAKE_CONFIG_SHOW_HANG_MARKER;
+const hangNow =
+ argv.includes("config") &&
+ argv.includes("show") &&
+ (hang === "always" || (hang === "once" && hangMarker && !fs.existsSync(hangMarker)));
+if (hangNow) {
+ if (hangMarker) fs.writeFileSync(hangMarker, "1");
+ // Block synchronously so nothing below runs; the caller's timeout kill ends the process.
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 60_000);
+ process.exit(0);
+}
if (argv.includes("config") && argv.includes("show")) {
const replacement = process.env.FAKE_REPLACEMENT_AGENT;
const agents = replacement ? { [replacement]: { argv: ["custom-adapter"] } } : {};
@@ -456,9 +471,12 @@ test("the process wrapper forwards a signal received while spawning", async () =
},
});
const exited = new Promise((resolve) => wrapper.once("close", (code, signal) => resolve({ code, signal })));
+ // Two node startups and a signal round-trip: well under a second alone, but seconds
+ // when the whole suite runs in parallel. A wrapper that swallows the signal never
+ // exits, so a generous bound still fails it.
const outcome = await Promise.race([
exited,
- new Promise((resolve) => setTimeout(() => resolve("timeout"), 2000).unref()),
+ new Promise((resolve) => setTimeout(() => resolve("timeout"), 10000).unref()),
]);
assert.notEqual(outcome, "timeout");
} finally {
@@ -678,6 +696,64 @@ test("configured replacement adapters are rejected for positional built-ins", as
}
});
+test("a timed-out adapter-configuration check fails the call, not the run", async () => {
+ resetLogsAndSettings();
+ process.env.FAKE_CONFIG_SHOW_HANG = "always";
+ try {
+ // An AcpxError is a per-call failure the analysis stage records and retries; a
+ // UserError would stop the whole run with "upgrade acpx" advice that cannot help.
+ await assert.rejects(
+ () =>
+ openSession({
+ agent: "codex",
+ model: "gpt-5.6-sol",
+ effort: "high",
+ sessionName: "bp-codex-verify-hang",
+ cwd: workDir,
+ verifyTimeoutMs: 2_000,
+ }),
+ {
+ name: "AcpxError",
+ timedOut: true,
+ stage: "verify",
+ message: /timed out verifying the codex adapter configuration/,
+ },
+ );
+ } finally {
+ delete process.env.FAKE_CONFIG_SHOW_HANG;
+ }
+ const calls = acpxCalls();
+ assert.equal(calls.filter((c) => c.argv.includes("config") && c.argv.includes("show")).length, 2);
+ assert.ok(!calls.some((c) => c.argv.includes("new") || c.argv.includes("exec")));
+});
+
+test("a slow first adapter-configuration check is retried before the session opens", async () => {
+ resetLogsAndSettings();
+ const marker = path.join(binDir, "config-show-hang-once");
+ fs.rmSync(marker, { force: true });
+ process.env.FAKE_CONFIG_SHOW_HANG = "once";
+ process.env.FAKE_CONFIG_SHOW_HANG_MARKER = marker;
+ try {
+ const session = await openSession({
+ agent: "codex",
+ model: "gpt-5.6-sol",
+ effort: "high",
+ sessionName: "bp-codex-verify-retry",
+ cwd: workDir,
+ verifyTimeoutMs: 2_000,
+ });
+ await session.close();
+ } finally {
+ delete process.env.FAKE_CONFIG_SHOW_HANG;
+ delete process.env.FAKE_CONFIG_SHOW_HANG_MARKER;
+ fs.rmSync(marker, { force: true });
+ }
+ const calls = acpxCalls();
+ assert.equal(calls.filter((c) => c.argv.includes("config") && c.argv.includes("show")).length, 2);
+ assert.ok(calls.some((c) => c.argv.includes("new")));
+ assert.deepEqual(setCalls(calls).map(setKey), ["reasoning_effort"]);
+});
+
test("Grok session forces an acpx raw-command override with process model and effort", async () => {
resetLogsAndSettings();
const before = Buffer.from(settingsBytes());
diff --git a/test/helpers/hermetic-config.js b/test/helpers/hermetic-config.js
new file mode 100644
index 00000000..5e7f0b95
--- /dev/null
+++ b/test/helpers/hermetic-config.js
@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Loaded before every test file (`--import` in the package.json `test` script).
+ *
+ * Two things a test process must not share with the developer's machine:
+ *
+ * - The config home. `loadConfig` layers `$XDG_CONFIG_HOME/backpass/config.json` under
+ * every run, so a developer's own personal config - custom ladders, hosts, a `user`
+ * block - would otherwise change what the suite asserts about defaults and agent
+ * selection. Each test process therefore starts from an empty config home of its own.
+ * Tests that need a config home still set `XDG_CONFIG_HOME` themselves and restore
+ * this value after.
+ * - The temp root. Tests create their fixtures with `fs.mkdtempSync(os.tmpdir())` and do
+ * not remove them, which left over a thousand directories behind per full run. Node's
+ * `os.tmpdir()` reads `TMPDIR` on every call, so pointing it at one per-process root
+ * (inherited by spawned CLI children) lets a single removal clean up everything.
+ */
+const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "backpass-test-root-")));
+process.env.TMPDIR = root;
+const configHome = fs.mkdtempSync(path.join(root, "config-"));
+process.env.XDG_CONFIG_HOME = configHome;
+/** Make every directory under `dir` writable again, so a test that failed before restoring its
+ * 0o555 fixture cannot keep the root from being removed. */
+function restoreWritable(dir) {
+ try {
+ fs.chmodSync(dir, 0o755);
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+ if (entry.isDirectory()) restoreWritable(path.join(dir, entry.name));
+ }
+ } catch {
+ // best-effort: the retry below reports nothing either way
+ }
+}
+
+/** Best-effort removal: it must never add a stack trace to a run that is already ending. */
+const removeRoot = () => {
+ try {
+ fs.rmSync(root, { recursive: true, force: true });
+ } catch {
+ restoreWritable(root);
+ try {
+ fs.rmSync(root, { recursive: true, force: true });
+ } catch {
+ // leave it to the OS temp reaper rather than fail the exit
+ }
+ }
+};
+process.on("exit", removeRoot);
+
+// A signal skips `exit`, so remove the directory here too, then re-raise the same signal
+// so the process still ends with the conventional signal exit.
+const signals = ["SIGINT", "SIGTERM"];
+const onSignal = (signal) => {
+ removeRoot();
+ for (const s of signals) process.removeListener(s, onSignal);
+ process.kill(process.pid, signal);
+};
+for (const signal of signals) process.once(signal, onSignal);
diff --git a/test/helpers/opencode.js b/test/helpers/opencode.js
new file mode 100644
index 00000000..81910990
--- /dev/null
+++ b/test/helpers/opencode.js
@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { DatabaseSync } from "node:sqlite";
+
+const FIXTURES = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "fixtures");
+
+/** An opencode golden fixture: the DDL of a real store and rows in table order. */
+export function readOpencodeFixture(name) {
+ return JSON.parse(fs.readFileSync(path.join(FIXTURES, name), "utf8"));
+}
+
+/** Build an opencode store from a golden fixture: the real DDL, then its rows in table order. */
+export function writeOpencodeStore(dbFile, fixture, { skipTables = [] } = {}) {
+ fs.mkdirSync(path.dirname(dbFile), { recursive: true });
+ const db = new DatabaseSync(dbFile);
+ try {
+ for (const statement of fixture.schema) {
+ const table = statement.match(/^CREATE TABLE `([^`]+)`/)?.[1];
+ if (!skipTables.includes(table)) db.exec(statement);
+ }
+ for (const [table, rows] of Object.entries(fixture.rows)) {
+ if (skipTables.includes(table)) continue;
+ for (const row of rows) {
+ const columns = Object.keys(row);
+ db.prepare(`INSERT INTO ${table} (${columns.join(", ")}) VALUES (${columns.map(() => "?").join(", ")})`).run(
+ ...columns.map((column) =>
+ row[column] && typeof row[column] === "object" ? JSON.stringify(row[column]) : row[column],
+ ),
+ );
+ }
+ }
+ } finally {
+ db.close();
+ }
+}
+
+/**
+ * Run `fn` with HOME on a fresh directory whose default opencode store `build` writes.
+ * HOME is restored, and the directory removed, whether `build` or `fn` succeeds or not.
+ */
+export async function withOpencodeHome(build, fn) {
+ const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-opencode-home-"));
+ const dbFile = path.join(homeDir, ".local", "share", "opencode", "opencode.db");
+ const previous = process.env.HOME;
+ try {
+ build(dbFile, homeDir);
+ process.env.HOME = homeDir;
+ return await fn(dbFile, homeDir);
+ } finally {
+ if (previous === undefined) delete process.env.HOME;
+ else process.env.HOME = previous;
+ fs.rmSync(homeDir, { recursive: true, force: true });
+ }
+}
diff --git a/test/nested-cli.test.js b/test/nested-cli.test.js
new file mode 100644
index 00000000..8ca2dfba
--- /dev/null
+++ b/test/nested-cli.test.js
@@ -0,0 +1,476 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Nested memory files through the real CLI, the way a monorepo user runs them: a root
+ * AGENTS.md and an `apps/api/AGENTS.md` named in `nestedMemoryFiles`, pi sessions that
+ * worked either under `apps/api/` or under `apps/web/`, and a stand-in acpx that reports
+ * one lesson per kind of session. `backpass` must feed the nested file only its own
+ * sessions, land each lesson in the file that owns it, and hand both files to one
+ * `backpass apply`; with nothing configured the run must stay the single-file run it was.
+ */
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const CLI = path.join(ROOT, "bin", "backpass.js");
+const FAKE_LAVISH = path.join(ROOT, "test", "fixtures", "fake-lavish", "lavish-axi");
+
+const API_QUOTE = "Please fix the api handler timeout in the orders route.";
+const WEB_QUOTE = "Please fix the web checkout button styling.";
+const API_GAP = "Run the api contract tests before editing a handler.";
+const WEB_GAP = "Build the web bundle before opening a pull request.";
+
+const ROOT_MEMORY = "# Monorepo memory\n\n- Use pnpm for every package script.\n";
+const API_MEMORY = "# API memory\n\n- Handlers live in apps/api/src/routes.\n";
+
+const binDir = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-nested-bin-"));
+const fakePi = path.join(binDir, "pi");
+const fakeAcpx = path.join(binDir, "acpx");
+fs.writeFileSync(fakePi, `#!${process.execPath}\nprocess.exit(0);\n`);
+fs.chmodSync(fakePi, 0o755);
+
+/**
+ * The stand-in harness. Analysis reports the lesson whose quote is in the trace; the
+ * synthesis edit turn appends every lesson the evidence it was shown carries; the annotate
+ * turn claims those changes with the quotes and source labels that evidence issued.
+ */
+fs.writeFileSync(
+ fakeAcpx,
+ `#!${process.execPath}
+const fs = require("node:fs");
+const path = require("node:path");
+const argv = process.argv.slice(2);
+const at = (flag) => (argv.indexOf(flag) >= 0 ? argv[argv.indexOf(flag) + 1] : null);
+if (argv.includes("config") && argv.includes("show")) {
+ process.stdout.write(JSON.stringify({ agents: {} }) + "\\n");
+ process.exit(0);
+}
+if (argv.includes("sessions") || argv.includes("set")) {
+ if (argv.includes("new")) process.stdout.write("fake-session-id\\n");
+ process.exit(0);
+}
+const promptFile = at("--file");
+if (!promptFile) process.exit(0);
+const prompt = fs.readFileSync(promptFile, "utf8");
+const cwd = at("--cwd") || process.cwd();
+const statePath = process.env.FAKE_STATE;
+const state = fs.existsSync(statePath) ? JSON.parse(fs.readFileSync(statePath, "utf8")) : { log: [], shown: {} };
+const save = () => fs.writeFileSync(statePath, JSON.stringify(state));
+const lessons = ${JSON.stringify([
+ { gap: API_GAP, quote: API_QUOTE },
+ { gap: WEB_GAP, quote: WEB_QUOTE },
+ ])};
+if (process.env.FAKE_SHARED_GAP) lessons[1].gap = lessons[0].gap;
+
+if (prompt.includes("You are auditing one past agent session")) {
+ const audited = /## The memory file under audit: (\\S+)/.exec(prompt)[1];
+ const gaps = lessons
+ .filter((lesson) => prompt.includes(lesson.quote))
+ .map((lesson) => ({
+ mistake: "the session had to work it out by hand",
+ proposedInstruction: lesson.gap,
+ recurrenceRisk: "high",
+ domain: "project",
+ quote: lesson.quote,
+ }));
+ state.log.push({ turn: "analysis", audited, gaps: gaps.map((gap) => gap.proposedInstruction), alsoLoaded: prompt.includes("## Also loaded in this session") });
+ save();
+ process.stdout.write(JSON.stringify({ positive: [], negative: [], gaps }) + "\\n");
+ process.exit(0);
+}
+if (prompt.includes("You are consolidating the gap ledger")) {
+ process.stdout.write(JSON.stringify({ merges: [] }) + "\\n");
+ process.exit(0);
+}
+if (prompt.includes("You are performing the synthesis step")) {
+ const memory = /## Current memory file: (\\S+)/.exec(prompt)[1];
+ const pairs = [...prompt.matchAll(/"([^"]+)" \\((pi · [^)]+)\\)/g)].map((m) => ({ text: m[1], source: m[2] }));
+ const shown = lessons.filter((lesson, index) =>
+ prompt.includes(":: " + lesson.gap) && lessons.findIndex((entry) => entry.gap === lesson.gap) === index);
+ state.shown[memory] = shown.map((lesson) => ({
+ ...lesson,
+ evidence: pairs.filter((pair) => lessons.some((entry) => entry.gap === lesson.gap && entry.quote === pair.text)),
+ }));
+ const budgetCount = prompt.includes("The count is this file PLUS every skill's \\\`description:\\\` line;\\nskill bodies are free until triggered.")
+ ? "surface"
+ : prompt.includes("The count is this file alone") ? "file" : null;
+ const nestedRule = prompt.includes("This run trains the nested memory file");
+ state.log.push({ turn: "edit", memory, lessons: shown.map((lesson) => lesson.gap), budgetCount, nestedRule });
+ save();
+ const target = path.join(cwd, memory);
+ let text = fs.readFileSync(target, "utf8");
+ for (const lesson of shown) text += "- " + lesson.gap + "\\n";
+ fs.writeFileSync(target, text);
+ process.stdout.write("Added the lessons the evidence carries.\\n");
+ process.exit(0);
+}
+if (prompt.includes("## Measured changes")) {
+ const memory = /staging copy of (\\S+?)\\. Every change/.exec(prompt)[1];
+ const changes = [...prompt.matchAll(/\\[(H\\d+):/g)].map((m) => m[1]);
+ const shown = state.shown[memory] || [];
+ state.log.push({ turn: "annotate", memory, changes });
+ save();
+ const edits = shown.length
+ ? [{
+ changes,
+ kind: "add",
+ title: shown.map((lesson) => lesson.gap).join(" "),
+ rationale: "two sessions hit it",
+ evidence: shown.flatMap((lesson) => lesson.evidence.map((pair) => ({ polarity: "negative", text: pair.text, source: pair.source }))),
+ }]
+ : [];
+ process.stdout.write(JSON.stringify({ edits, verdicts: [], notes: [] }) + "\\n");
+ process.exit(0);
+}
+process.exit(0);
+`,
+);
+fs.chmodSync(fakeAcpx, 0o755);
+
+function git(args, cwd) {
+ execFileSync("git", args, { cwd, stdio: "ignore" });
+}
+
+/** A monorepo checkout with a root memory file and one nested one. */
+function makeMonorepo({ config = null } = {}) {
+ const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "backpass-nested-repo-")));
+ const files = {
+ "AGENTS.md": ROOT_MEMORY,
+ "apps/api/AGENTS.md": API_MEMORY,
+ "apps/api/src/routes/orders.ts": "export const orders = 1;\n",
+ "apps/web/src/checkout.tsx": "export const checkout = 1;\n",
+ ...(config ? { ".backpassrc.json": `${JSON.stringify(config)}\n` } : {}),
+ };
+ for (const [name, text] of Object.entries(files)) {
+ fs.mkdirSync(path.dirname(path.join(dir, name)), { recursive: true });
+ fs.writeFileSync(path.join(dir, name), text);
+ }
+ git(["init", "-q", "-b", "main"], dir);
+ git(["config", "user.email", "test@example.com"], dir);
+ git(["config", "user.name", "test"], dir);
+ git(["add", "-A"], dir);
+ git(["commit", "-q", "-m", "monorepo"], dir);
+ return dir;
+}
+
+/** A pi session rooted at the repo that edits one file, named by a repo-relative path. */
+function writeSession(home, id, cwd, { quote, file }) {
+ const dir = path.join(home, ".pi", "agent", "sessions", id);
+ fs.mkdirSync(dir, { recursive: true });
+ const entries = [
+ { type: "session", version: 3, id, timestamp: new Date().toISOString(), cwd },
+ { type: "message", message: { role: "user", content: quote } },
+ {
+ type: "message",
+ message: {
+ role: "assistant",
+ content: [
+ { type: "text", text: "Reading the file first." },
+ { type: "toolCall", id: `${id}-read`, name: "read", arguments: { path: file } },
+ ],
+ },
+ },
+ { type: "message", message: { role: "toolResult", toolCallId: `${id}-read`, content: "export const x = 1;" } },
+ {
+ type: "message",
+ message: {
+ role: "assistant",
+ content: [{ type: "toolCall", id: `${id}-edit`, name: "edit", arguments: { path: file, edits: [] } }],
+ },
+ },
+ { type: "message", message: { role: "toolResult", toolCallId: `${id}-edit`, content: "edited" } },
+ { type: "message", message: { role: "user", content: "Now run the tests too." } },
+ { type: "message", message: { role: "assistant", content: "Tests pass." } },
+ ];
+ fs.writeFileSync(path.join(dir, `${id}.jsonl`), `${entries.map((e) => JSON.stringify(e)).join("\n")}\n`);
+}
+
+/** Two sessions that worked under apps/api, two under apps/web. */
+function makeCorpus(dir) {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-nested-home-"));
+ writeSession(home, "api-one", dir, { quote: API_QUOTE, file: "apps/api/src/routes/orders.ts" });
+ writeSession(home, "api-two", dir, { quote: API_QUOTE, file: "apps/api/src/routes/orders.ts" });
+ writeSession(home, "web-one", dir, { quote: WEB_QUOTE, file: "apps/web/src/checkout.tsx" });
+ writeSession(home, "web-two", dir, { quote: WEB_QUOTE, file: "apps/web/src/checkout.tsx" });
+ return home;
+}
+
+function run(dir, home, args, extraEnv = {}) {
+ const statePath = path.join(home, "fake-state.json");
+ const result = spawnSync(
+ process.execPath,
+ [
+ CLI,
+ ...args,
+ "--harness",
+ "pi",
+ "--since",
+ "all",
+ "--analysis-agent",
+ "pi",
+ "--synthesis-agent",
+ "claude",
+ "--synthesis-model",
+ "fake-model",
+ "--jobs",
+ "1",
+ ],
+ {
+ cwd: dir,
+ encoding: "utf8",
+ timeout: 60000,
+ env: {
+ ...process.env,
+ HOME: home,
+ USERPROFILE: home,
+ PATH: `${binDir}${path.delimiter}${process.env.PATH}`,
+ BACKPASS_ACPX_BIN: fakeAcpx,
+ FAKE_STATE: statePath,
+ NO_COLOR: "1",
+ CI: "1",
+ ...extraEnv,
+ },
+ },
+ );
+ const log = fs.existsSync(statePath) ? JSON.parse(fs.readFileSync(statePath, "utf8")).log : [];
+ return { ...result, output: `${result.stdout}${result.stderr}`, log };
+}
+
+function applyAll(dir, editIds) {
+ const decisions = editIds.map((id) => `${id}=accepted`).join(" ");
+ const scenario = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "backpass-nested-lavish-")), "scenario.json");
+ fs.writeFileSync(
+ scenario,
+ JSON.stringify({
+ polls: [
+ `prompts[1]{uid,prompt,selector,tag,text}:\n "1","BACKPASS_DECISIONS ${decisions}",button#btn-apply,choice,${decisions}`,
+ ],
+ }),
+ );
+ const result = spawnSync(process.execPath, [CLI, "apply", "--no-open"], {
+ cwd: dir,
+ encoding: "utf8",
+ env: { ...process.env, NO_COLOR: "1", BACKPASS_LAVISH_BIN: FAKE_LAVISH, FAKE_LAVISH_SCENARIO: scenario },
+ });
+ return { ...result, output: `${result.stdout}${result.stderr}` };
+}
+
+const readJson = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+
+test("a named nested file learns only from its subtree, and each lesson lands in the file that owns it", () => {
+ const dir = makeMonorepo({ config: { nestedMemoryFiles: ["apps/api/AGENTS.md"] } });
+ const home = makeCorpus(dir);
+
+ const result = run(dir, home, []);
+ assert.equal(result.status, 0, result.output);
+
+ // The nested surface is named for what it is, never as a file to consolidate.
+ assert.match(
+ result.output,
+ /apps\/api\/AGENTS\.md is a nested memory file: 2 of 4 session\(s\) worked under apps\/api\//,
+ );
+ assert.doesNotMatch(result.output, /consolidate/);
+
+ // Evidence scoping: the root file is audited on every session, the nested one only on
+ // the two that worked under apps/api, with the root shown as already loaded.
+ const analyses = result.log.filter((entry) => entry.turn === "analysis");
+ assert.equal(analyses.filter((entry) => entry.audited === "AGENTS.md").length, 4);
+ const nestedAnalyses = analyses.filter((entry) => entry.audited === "apps/api/AGENTS.md");
+ assert.equal(nestedAnalyses.length, 2);
+ assert.ok(nestedAnalyses.every((entry) => entry.alsoLoaded && entry.gaps.join() === API_GAP));
+ assert.ok(analyses.filter((entry) => entry.audited === "AGENTS.md").every((entry) => !entry.alsoLoaded));
+
+ // Routing: the api lesson reaches only the nested synthesis, the web lesson only the root.
+ // The nested synthesis is told what it trains and budgets that file alone.
+ const edits = result.log.filter((entry) => entry.turn === "edit");
+ assert.deepEqual(
+ edits.map((entry) => [entry.memory, entry.lessons, entry.budgetCount, entry.nestedRule]),
+ [
+ ["apps/api/AGENTS.md", [API_GAP], "file", true],
+ ["AGENTS.md", [WEB_GAP], "surface", false],
+ ],
+ );
+
+ // One proposal covers both files, each edit labeled by its file, each file its own budget.
+ const proposal = readJson(path.join(dir, ".backpass", "proposal.json"));
+ assert.deepEqual(
+ proposal.edits.map((edit) => [edit.id, edit.file, edit.nestedMemoryFile ?? null]),
+ [
+ ["e1", "AGENTS.md", null],
+ ["e2", "apps/api/AGENTS.md", "apps/api/AGENTS.md"],
+ ],
+ );
+ assert.equal(proposal.nested.length, 1);
+ assert.equal(proposal.nested[0].memoryFile.path, "apps/api/AGENTS.md");
+ assert.equal(proposal.nested[0].sessions, 2);
+ assert.deepEqual(proposal.nested[0].edits, ["e2"]);
+ assert.ok(proposal.targetFiles.some((target) => target.file === "apps/api/AGENTS.md"));
+ assert.match(result.output, /e2 ADD\s+apps\/api\/AGENTS\.md: /);
+ assert.match(result.output, /nested apps\/api\/AGENTS\.md · 2 session\(s\) under apps\/api\/ · budget /);
+
+ // The nested file's state is its own; the root's evidence dir holds only root evidence.
+ const nestedState = path.join(dir, ".backpass", "nested");
+ assert.ok(fs.existsSync(path.join(nestedState, "attribution.json")));
+ const rootEvidence = fs
+ .readdirSync(path.join(dir, ".backpass", "evidence"))
+ .map((file) => readJson(path.join(dir, ".backpass", "evidence", file)));
+ assert.ok(rootEvidence.every((record) => record.memoryPath === "AGENTS.md"));
+
+ // One apply writes both files, and only apply writes.
+ assert.equal(fs.readFileSync(path.join(dir, "apps/api/AGENTS.md"), "utf8"), API_MEMORY);
+ const applied = applyAll(dir, ["e1", "e2"]);
+ assert.equal(applied.status, 0, applied.output);
+ assert.equal(fs.readFileSync(path.join(dir, "AGENTS.md"), "utf8"), `${ROOT_MEMORY}- ${WEB_GAP}\n`);
+ assert.equal(fs.readFileSync(path.join(dir, "apps/api/AGENTS.md"), "utf8"), `${API_MEMORY}- ${API_GAP}\n`);
+ assert.match(applied.output, /wrote apps\/api\/AGENTS\.md \(e2\)/);
+});
+
+test("a gap spanning API and web is proposed only in root, not again from its API subset", () => {
+ const dir = makeMonorepo({ config: { nestedMemoryFiles: ["apps/api/AGENTS.md"] } });
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-nested-shared-home-"));
+ writeSession(home, "api-one", dir, { quote: API_QUOTE, file: "apps/api/src/routes/orders.ts" });
+ writeSession(home, "api-two", dir, { quote: API_QUOTE, file: "apps/api/src/routes/orders.ts" });
+ writeSession(home, "web-one", dir, { quote: WEB_QUOTE, file: "apps/web/src/checkout.tsx" });
+
+ const result = run(dir, home, [], { FAKE_SHARED_GAP: "1" });
+ assert.equal(result.status, 0, result.output);
+ const proposal = readJson(path.join(dir, ".backpass", "proposal.json"));
+ assert.deepEqual(
+ proposal.edits.map((edit) => edit.file),
+ ["AGENTS.md"],
+ );
+ assert.deepEqual(proposal.nested[0].edits, []);
+ assert.deepEqual(
+ result.log.filter((entry) => entry.turn === "edit").map((entry) => entry.lessons),
+ [[], [API_GAP]],
+ );
+});
+
+test("with no nested file named, a run trains the root file from every session, as it always did", () => {
+ const dir = makeMonorepo();
+ const home = makeCorpus(dir);
+
+ const result = run(dir, home, []);
+ assert.equal(result.status, 0, result.output);
+
+ const analyses = result.log.filter((entry) => entry.turn === "analysis");
+ assert.equal(analyses.length, 4);
+ assert.ok(analyses.every((entry) => entry.audited === "AGENTS.md" && !entry.alsoLoaded));
+ // Both lessons compete for the one root file, exactly as before nested files existed.
+ assert.deepEqual(
+ result.log
+ .filter((entry) => entry.turn === "edit")
+ .map((entry) => [entry.memory, [...entry.lessons].sort(), entry.budgetCount, entry.nestedRule]),
+ [["AGENTS.md", [API_GAP, WEB_GAP].sort(), "surface", false]],
+ );
+ const proposal = readJson(path.join(dir, ".backpass", "proposal.json"));
+ assert.equal(proposal.nested, undefined);
+ assert.ok(proposal.edits.every((edit) => edit.file === "AGENTS.md" && edit.nestedMemoryFile === undefined));
+ assert.ok(!fs.existsSync(path.join(dir, ".backpass", "nested")), "no nested state without a nested file");
+ assert.doesNotMatch(result.output, /nested memory file|\(nested\)|^ {2}nested /m);
+});
+
+test("an unchanged over-budget root permits nested training but not an unconfigured or edited root", () => {
+ const named = makeMonorepo({
+ config: { budgetTokens: 1, nestedBudgetTokens: 2000, nestedMemoryFiles: ["apps/api/AGENTS.md"] },
+ });
+ const apiHome = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-nested-api-home-"));
+ writeSession(apiHome, "api-one", named, { quote: API_QUOTE, file: "apps/api/src/routes/orders.ts" });
+ writeSession(apiHome, "api-two", named, { quote: API_QUOTE, file: "apps/api/src/routes/orders.ts" });
+ const nested = run(named, apiHome, []);
+ assert.equal(nested.status, 0, nested.output);
+ const proposal = readJson(path.join(named, ".backpass", "proposal.json"));
+ assert.deepEqual(
+ proposal.edits.map((edit) => edit.file),
+ ["apps/api/AGENTS.md"],
+ );
+ assert.ok(proposal.budget.startedOverBudget);
+ assert.equal(proposal.budget.delta, 0);
+
+ const editedRoot = makeMonorepo({
+ config: { budgetTokens: 1, nestedBudgetTokens: 2000, nestedMemoryFiles: ["apps/api/AGENTS.md"] },
+ });
+ const edited = run(editedRoot, makeCorpus(editedRoot), []);
+ assert.equal(edited.status, 1, edited.output);
+ assert.match(edited.output, /this run must shrink it/);
+
+ const unconfigured = makeMonorepo({ config: { budgetTokens: 1 } });
+ const noGapHome = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-nested-no-gap-home-"));
+ writeSession(noGapHome, "plain-one", unconfigured, {
+ quote: "Review the file.",
+ file: "apps/api/src/routes/orders.ts",
+ });
+ writeSession(noGapHome, "plain-two", unconfigured, {
+ quote: "Review the file.",
+ file: "apps/api/src/routes/orders.ts",
+ });
+ const root = run(unconfigured, noGapHome, []);
+ assert.equal(root.status, 1, root.output);
+ assert.match(root.output, /this run must shrink it/);
+});
+
+test("an untrained nested corpus cannot exempt an unchanged over-budget root", () => {
+ const dir = makeMonorepo({ config: { budgetTokens: 1 } });
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-nested-untrained-home-"));
+ writeSession(home, "api-one", dir, { quote: "Review the file.", file: "apps/api/src/routes/orders.ts" });
+ writeSession(home, "api-two", dir, { quote: "Review the file.", file: "apps/api/src/routes/orders.ts" });
+ const analyzed = run(dir, home, ["analyze"]);
+ assert.equal(analyzed.status, 0, analyzed.output);
+ fs.writeFileSync(
+ path.join(dir, ".backpassrc.json"),
+ `${JSON.stringify({ budgetTokens: 1, nestedMemoryFiles: ["apps/api/AGENTS.md"] })}\n`,
+ );
+
+ const proposed = run(dir, home, ["propose"]);
+ assert.equal(proposed.status, 1, proposed.output);
+ assert.match(proposed.output, /this run must shrink it/);
+ assert.deepEqual(
+ proposed.log.filter((entry) => entry.turn === "edit").map((entry) => entry.memory),
+ ["AGENTS.md"],
+ );
+});
+
+test("a subdirectory file listed only in memoryFiles still gets the consolidate warning; named as nested, it does not", () => {
+ const listed = makeMonorepo({ config: { memoryFiles: ["AGENTS.md", "apps/api/AGENTS.md"] } });
+ const home = makeCorpus(listed);
+ const unconfigured = run(listed, home, ["analyze"]);
+ assert.equal(unconfigured.status, 0, unconfigured.output);
+ assert.match(
+ unconfigured.output,
+ /apps\/api\/AGENTS\.md is a separate memory file and will NOT be updated - only AGENTS\.md is optimized/,
+ );
+
+ const named = makeMonorepo({
+ config: { memoryFiles: ["AGENTS.md", "apps/api/AGENTS.md"], nestedMemoryFiles: ["apps/api/AGENTS.md"] },
+ });
+ const namedHome = makeCorpus(named);
+ const nested = run(named, namedHome, ["analyze"]);
+ assert.equal(nested.status, 0, nested.output);
+ assert.doesNotMatch(nested.output, /separate memory file/);
+ assert.match(
+ nested.output,
+ /apps\/api\/AGENTS\.md is a nested memory file: 2 of 4 session\(s\) worked under apps\/api\//,
+ );
+ assert.match(
+ nested.output,
+ /analyzed against apps\/api\/AGENTS\.md \(nested, 1 instructions, \d+ tok\) from 2 session\(s\) under apps\/api\//,
+ );
+});
+
+test("--target on a nested file is refused by name, and a targeted run never trains a nested file", () => {
+ const dir = makeMonorepo({ config: { nestedMemoryFiles: ["apps/api/AGENTS.md"] } });
+ const home = makeCorpus(dir);
+
+ const refused = run(dir, home, ["analyze", "--target", "apps/api/AGENTS.md"]);
+ assert.equal(refused.status, 1);
+ assert.match(refused.output, /--target apps\/api\/AGENTS\.md is a nested memory file/);
+
+ const targeted = run(dir, home, ["analyze", "--target", "AGENTS.md"]);
+ assert.equal(targeted.status, 0, targeted.output);
+ assert.ok(targeted.log.every((entry) => entry.audited === "AGENTS.md"));
+ assert.doesNotMatch(targeted.output, /nested memory file/);
+});
diff --git a/test/nested.test.js b/test/nested.test.js
new file mode 100644
index 00000000..27a9fcf2
--- /dev/null
+++ b/test/nested.test.js
@@ -0,0 +1,895 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { loadConfig } from "../src/config.js";
+import { nestedCorpora, primaryMemoryFile } from "../src/commands/analyze.js";
+import { foldEvidence, renderEvidenceForPrompt } from "../src/fold.js";
+import { setLoggerSink } from "../src/logger.js";
+import { buildProposal } from "../src/proposal.js";
+import { applyDecisions } from "../src/apply/writer.js";
+import { State } from "../src/state.js";
+import { transcriptIdentity } from "../src/transcript.js";
+import {
+ applyNestedMemoryConfig,
+ attributeTranscripts,
+ checkoutRoots,
+ mergeNestedProposals,
+ nestedContext,
+ nestedStateDir,
+ owningFile,
+ reportNestedMemoryFiles,
+ renderAlsoLoaded,
+ resolveNestedMemoryFiles,
+ routingFor,
+ workedPaths,
+} from "../src/nested.js";
+import { makeRepo, stageAndMeasure, writeIn } from "./helpers/staging.js";
+
+/**
+ * Nested memory files, stage by stage: the opt-in config, where a session worked, which
+ * file owns a lesson, how the fold and the proposal gate route by it, and the per-file
+ * budget the writer enforces. `test/nested-cli.test.js` drives the same contract through
+ * the real CLI.
+ */
+
+// Keep a developer's own global config out of `loadConfig`.
+process.env.XDG_CONFIG_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-nested-xdg-"));
+
+const API = { path: "apps/api/AGENTS.md", dir: "apps/api" };
+const DB = { path: "apps/api/db/AGENTS.md", dir: "apps/api/db" };
+const WEB = { path: "apps/web/AGENTS.md", dir: "apps/web" };
+
+const ATTRIBUTION = new Map([
+ ["api-1", ["apps/api/src/orders.ts"]],
+ ["api-2", ["apps/api/routes/index.ts"]],
+ ["db-1", ["apps/api/db/schema.sql"]],
+ ["db-2", ["apps/api/db/migrate.ts"]],
+ ["web-1", ["apps/web/checkout.tsx"]],
+ ["web-2", ["apps/web"]],
+ ["both", ["apps/api/src/orders.ts", "apps/web/checkout.tsx"]],
+ ["root-file-and-api", ["README.md", "apps/api/src/orders.ts"]],
+ ["root", [""]],
+ ["remote", null],
+]);
+
+function captureWarnings(fn) {
+ const lines = [];
+ setLoggerSink((line) => lines.push(line));
+ try {
+ return { result: fn(), lines };
+ } catch (err) {
+ return { error: err, lines };
+ } finally {
+ setLoggerSink(null);
+ }
+}
+
+// ---------- configuration: nested files are named, never discovered ----------
+
+test("unset, nestedMemoryFiles changes nothing: the root list and the resolved weights are what they were", () => {
+ const repo = makeRepo({ "AGENTS.md": "# root\n", "apps/api/AGENTS.md": "# api\n" });
+ const config = loadConfig(repo.root);
+ assert.deepEqual(config.nestedMemoryFiles, []);
+ assert.equal(config.nestedBudgetTokens, null);
+ const memoryFiles = [...config.memoryFiles];
+ assert.equal(applyNestedMemoryConfig(repo.root, config), config);
+ assert.deepEqual(config.memoryFiles, memoryFiles);
+ assert.deepEqual(resolveNestedMemoryFiles(repo.root, config), [], "an existing nested file is never picked up");
+});
+
+test("nestedMemoryFiles is validated as a list of paths, and only for project scope", () => {
+ const repo = makeRepo({ "AGENTS.md": "# root\n" });
+ assert.throws(() => loadConfig(repo.root, { nestedMemoryFiles: "apps/api/AGENTS.md" }), /must be an array/);
+ assert.throws(() => loadConfig(repo.root, { nestedMemoryFiles: [""] }), /must be an array/);
+ assert.throws(() => loadConfig(repo.root, { nestedBudgetTokens: 0 }), /nestedBudgetTokens must be a positive number/);
+ assert.throws(
+ () => loadConfig(null, { nestedMemoryFiles: ["apps/api/AGENTS.md"] }, { kind: "user" }),
+ /project-scope only/,
+ );
+});
+
+test("each nested entry is one repo-relative file in a subdirectory, and leaves the root list", () => {
+ const repo = makeRepo({ "AGENTS.md": "# root\n", "apps/api/AGENTS.md": "# api\n" });
+ const config = (nestedMemoryFiles, memoryFiles = ["AGENTS.md", "CLAUDE.md"]) => ({ memoryFiles, nestedMemoryFiles });
+
+ const named = applyNestedMemoryConfig(
+ repo.root,
+ config(["./apps/api/AGENTS.md"], ["AGENTS.md", "apps/api/AGENTS.md", "CLAUDE.md"]),
+ );
+ assert.deepEqual(named.nestedMemoryFiles, ["apps/api/AGENTS.md"]);
+ assert.deepEqual(named.memoryFiles, ["AGENTS.md", "CLAUDE.md"], "a nested weight is never a separate root file");
+
+ assert.throws(() => applyNestedMemoryConfig(repo.root, config(["AGENTS.md"])), /at the repository root/);
+ assert.throws(
+ () => applyNestedMemoryConfig(repo.root, config(["apps/api/AGENTS.md", "apps/api/CLAUDE.md"])),
+ /two memory files in apps\/api\//,
+ );
+ assert.throws(() => applyNestedMemoryConfig(repo.root, config(["../elsewhere/AGENTS.md"])), /outside/);
+ assert.throws(
+ () => applyNestedMemoryConfig(repo.root, config(["apps/api/AGENTS.md"], ["apps/api/AGENTS.md"])),
+ /every memoryFiles entry is also listed in nestedMemoryFiles/,
+ );
+});
+
+test("a nested directory keeps the root pair's pointer model: a pointer is refused, a missing file is named", () => {
+ const repo = makeRepo({
+ "AGENTS.md": "# root\n",
+ "apps/api/AGENTS.md": "# api\n\n- Handlers live in src/routes.\n",
+ "apps/api/CLAUDE.md": "# api for claude\n\n- Something else entirely.\n",
+ "apps/web/AGENTS.md": "# web\n",
+ "apps/web/CLAUDE.md": "@AGENTS.md\n",
+ });
+ const config = {
+ memoryFiles: ["AGENTS.md", "CLAUDE.md"],
+ nestedMemoryFiles: ["apps/api/AGENTS.md", "apps/docs/AGENTS.md"],
+ };
+ const { result, lines } = captureWarnings(() => reportNestedMemoryFiles(resolveNestedMemoryFiles(repo.root, config)));
+ assert.deepEqual(
+ result.map((weight) => weight.path),
+ ["apps/api/AGENTS.md"],
+ );
+ assert.ok(
+ lines.some((line) =>
+ /apps\/api\/CLAUDE\.md is a separate memory file.*only apps\/api\/AGENTS\.md is optimized/.test(line),
+ ),
+ lines.join("\n"),
+ );
+ assert.ok(lines.some((line) => /nested memory file apps\/docs\/AGENTS\.md does not exist/.test(line)));
+ const singleRoot = captureWarnings(() =>
+ reportNestedMemoryFiles(
+ resolveNestedMemoryFiles(repo.root, { memoryFiles: ["AGENTS.md"], nestedMemoryFiles: ["apps/api/AGENTS.md"] }),
+ ),
+ );
+ assert.ok(singleRoot.lines.some((line) => /apps\/api\/CLAUDE\.md is a separate memory file/.test(line)));
+
+ const pointer = captureWarnings(() =>
+ reportNestedMemoryFiles(
+ resolveNestedMemoryFiles(repo.root, { memoryFiles: ["AGENTS.md"], nestedMemoryFiles: ["apps/web/CLAUDE.md"] }),
+ ),
+ );
+ assert.match(pointer.error?.message ?? "", /apps\/web\/CLAUDE\.md is only a pointer to apps\/web\/AGENTS\.md/);
+});
+
+test("a deeper nested analysis includes every loaded ancestor in its hash and context", () => {
+ const repo = makeRepo({
+ "AGENTS.md": "# Root rule\n",
+ [API.path]: "# API rule\n",
+ [DB.path]: "# Database rule\n",
+ [WEB.path]: "# Web rule\n",
+ });
+ const config = loadConfig(repo.root, { nestedMemoryFiles: [DB.path, WEB.path, API.path] });
+ const first = primaryMemoryFile(repo, config);
+ const db = first.nested.find((weight) => weight.path === DB.path);
+ const api = first.nested.find((weight) => weight.path === API.path);
+ const ancestorPaths = db.ancestors.map((ancestor) => ancestor.path);
+ assert.deepEqual(ancestorPaths, [API.path]);
+ const context = renderAlsoLoaded(first.file, db);
+ const rootAt = context.indexOf("### Root memory file: AGENTS.md");
+ const apiAt = context.indexOf(`### Ancestor memory file: ${API.path}`);
+ assert.ok(rootAt >= 0 && rootAt < apiAt);
+ assert.match(context, /# Root rule/);
+ assert.match(context, /# API rule/);
+ assert.ok(!context.includes("# Web rule") && !context.includes("# Database rule"));
+
+ writeIn(repo.root, API.path, "# Changed API rule\n");
+ const second = primaryMemoryFile(repo, config);
+ assert.notEqual(second.nested.find((weight) => weight.path === DB.path).hash, db.hash);
+ assert.notEqual(second.nested.find((weight) => weight.path === API.path).hash, api.hash);
+ assert.equal(
+ second.nested.find((weight) => weight.path === WEB.path).hash,
+ first.nested.find((weight) => weight.path === WEB.path).hash,
+ );
+ const updatedDb = second.nested.find((weight) => weight.path === DB.path);
+ assert.match(renderAlsoLoaded(second.file, updatedDb), /# Changed API rule/);
+});
+
+test("nested sibling warnings ignore an unrelated root memory basename", () => {
+ const repo = makeRepo({
+ "README.md": "# Root memory\n",
+ "apps/api/AGENTS.md": "# API memory\n",
+ "apps/api/README.md": "# API documentation\n",
+ });
+ const { result, lines } = captureWarnings(() =>
+ reportNestedMemoryFiles(
+ resolveNestedMemoryFiles(repo.root, { memoryFiles: ["README.md"], nestedMemoryFiles: [API.path] }),
+ ),
+ );
+ const paths = result.map((weight) => weight.path);
+ assert.deepEqual(paths, [API.path]);
+ assert.deepEqual(result[0].separate, []);
+ assert.deepEqual(lines, []);
+});
+
+test("nested resolution exposes every resolved sibling even when the named file is missing", () => {
+ const pointer = "\n@AGENTS.md\n";
+ const repo = makeRepo({
+ [API.path]: "# API memory\n",
+ "apps/api/CLAUDE.md": pointer,
+ "apps/docs/CLAUDE.md": "# Documentation memory\n",
+ });
+ const [api, docs] = resolveNestedMemoryFiles(repo.root, {
+ nestedMemoryFiles: [API.path, "apps/docs/AGENTS.md"],
+ });
+ assert.deepEqual(
+ api.all.map((file) => file.path),
+ [API.path, "apps/api/CLAUDE.md"],
+ );
+ assert.equal(api.all[1].text, pointer);
+ assert.deepEqual(api.separate, []);
+ assert.equal(docs.file, null);
+ assert.deepEqual(
+ docs.all.map((file) => file.path),
+ ["apps/docs/CLAUDE.md"],
+ );
+});
+
+// ---------- where a session worked ----------
+
+test("structured tool paths use their call workdir; cwd only places sessions without paths", () => {
+ const repo = makeRepo({ "apps/api/src/orders.ts": "", "apps/web/checkout.tsx": "" });
+ const roots = checkoutRoots(repo);
+ const events = [
+ { kind: "tool", name: "Read", input: { file_path: path.join(repo.root, "apps/api/src/orders.ts") } },
+ { kind: "tool", name: "read", input: { path: "apps/web/checkout.tsx" } },
+ {
+ kind: "tool",
+ name: "read",
+ input: { path: "button.ts", workdir: path.join(repo.root, "packages/ui") },
+ },
+ { kind: "tool", name: "exec_command", input: { cmd: "cat apps/docs/README.md", workdir: repo.root } },
+ {
+ kind: "tool",
+ name: "apply_patch",
+ input: `*** Begin Patch\n*** Update File: ${path.join(repo.root, "apps/api/src/new.ts")}\n@@\n-a\n+b\n*** Add File: libs/core/index.ts\n+x\n*** End Patch`,
+ },
+ { kind: "tool", name: "Bash", input: { command: "cd apps/mobile && npm test" } },
+ { kind: "tool", name: "Read", input: { file_path: "/etc/hosts" } },
+ { kind: "message", role: "user", text: "look at apps/admin too" },
+ ];
+ assert.deepEqual(workedPaths({ cwd: repo.root }, events, roots), [
+ "apps/api/src/new.ts",
+ "apps/api/src/orders.ts",
+ "apps/web/checkout.tsx",
+ "libs/core/index.ts",
+ "packages/ui/button.ts",
+ ]);
+ assert.deepEqual(workedPaths({ cwd: path.join(repo.root, "apps/api") }, [], roots), ["apps/api"]);
+ assert.deepEqual(
+ workedPaths({ cwd: repo.root }, [{ kind: "tool", input: { path: "src/orders.ts", cwd: "apps/api" } }], roots),
+ ["apps/api/src/orders.ts"],
+ );
+ assert.deepEqual(
+ workedPaths({ cwd: repo.root }, [{ kind: "tool", input: { command: "pwd", workdir: "apps/api" } }], roots),
+ [""],
+ );
+});
+
+test("relative tool paths require an absolute recorded base, not the backpass process cwd", () => {
+ const repo = makeRepo({ "apps/api/AGENTS.md": "# API\n" });
+ const roots = checkoutRoots(repo);
+ const relative = [
+ { kind: "tool", input: { path: "apps/api/src/orders.ts" } },
+ { kind: "tool", input: { path: "src/orders.ts", workdir: "apps/api" } },
+ { kind: "tool", input: "*** Begin Patch\n*** Update File: apps/api/src/orders.ts\n*** End Patch" },
+ ];
+ assert.deepEqual(workedPaths({}, relative, roots), []);
+ const absoluteWorkdir = path.join(repo.root, "apps/api");
+ const placedByWorkdir = [{ kind: "tool", input: { path: "src/orders.ts", workdir: absoluteWorkdir } }];
+ assert.deepEqual(workedPaths({}, placedByWorkdir, roots), ["apps/api/src/orders.ts"]);
+ const absolutePath = path.join(repo.root, "apps/api/src/orders.ts");
+ const placedByPath = [{ kind: "tool", input: { path: absolutePath, workdir: "apps/api" } }];
+ assert.deepEqual(workedPaths({}, placedByPath, roots), ["apps/api/src/orders.ts"]);
+ assert.deepEqual(workedPaths({ cwd: repo.root }, relative, roots), ["apps/api/src/orders.ts"]);
+ assert.deepEqual(workedPaths({ cwd: "apps/api" }, relative, roots), []);
+});
+
+test(
+ "a Windows tool path or workdir is never resolved against a POSIX cwd",
+ { skip: process.platform === "win32" && "Windows spells these paths natively" },
+ () => {
+ const repo = makeRepo({ "apps/api/AGENTS.md": "# API\n" });
+ const roots = checkoutRoots(repo);
+ const events = [
+ { kind: "tool", input: { filePath: "C:\\Users\\me\\notes.md" } },
+ { kind: "tool", input: { path: "\\\\server\\share\\apps\\api\\x.ts" } },
+ { kind: "tool", input: { path: "src/orders.ts", workdir: "C:\\work\\apps\\api" } },
+ { kind: "tool", input: "*** Begin Patch\n*** Update File: D:/work/apps/api/y.ts\n*** End Patch" },
+ { kind: "tool", input: { path: "apps/api/handler.ts" } },
+ ];
+ assert.deepEqual(workedPaths({ cwd: repo.root }, events, roots), ["apps/api/handler.ts"]);
+ assert.deepEqual(workedPaths({ cwd: "C:\\work" }, [], roots), [], "a Windows cwd places nothing either");
+ },
+);
+
+test("out-of-repo paths do not make in-repo API work cross-cutting", async () => {
+ const repo = makeRepo({ "apps/api/AGENTS.md": "# API\n" });
+ const paths = workedPaths(
+ { cwd: repo.root },
+ [
+ { kind: "tool", input: { path: "apps/api/handler.ts" } },
+ { kind: "tool", input: { path: "/etc/hosts" } },
+ ],
+ checkoutRoots(repo),
+ );
+ assert.deepEqual(paths, ["apps/api/handler.ts"]);
+ const attribution = new Map([["api", paths]]);
+ assert.equal(owningFile(["api"], [API], attribution), API.path);
+ const { corpora } = await nestedCorpora({}, [API], [{ identity: "api" }], attribution);
+ assert.deepEqual(
+ corpora[0].transcripts.map((item) => item.identity),
+ ["api"],
+ );
+});
+
+test("attribution reads a local session once, and never places a session that ran on another machine", async () => {
+ const repo = makeRepo({ "AGENTS.md": "# root\n" });
+ const state = new State(repo.root).ensure();
+ const sessionPath = path.join(repo.root, "..", `${path.basename(repo.root)}-pi-session.jsonl`);
+ const entries = [
+ { type: "session", version: 3, id: "s1", timestamp: new Date().toISOString(), cwd: repo.root },
+ {
+ type: "message",
+ message: {
+ role: "assistant",
+ content: [{ type: "toolCall", id: "t1", name: "edit", arguments: { path: "apps/api/src/orders.ts" } }],
+ },
+ },
+ ];
+ fs.writeFileSync(sessionPath, `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`);
+ const local = { harness: "pi", id: "pi-s1", nativeId: "s1", path: sessionPath, cwd: repo.root, mtimeMs: 1, bytes: 2 };
+ const remote = { ...local, id: "pi-s2", nativeId: "s2", host: "mac-home" };
+ const unreadable = { ...local, id: "pi-s3", nativeId: "s3", path: `${sessionPath}.missing` };
+
+ const first = await attributeTranscripts([local, remote, unreadable], repo, state);
+ assert.deepEqual(first.get(transcriptIdentity(local)), ["apps/api/src/orders.ts"]);
+ assert.equal(first.get(transcriptIdentity(remote)), null, "a session from another machine is never placed");
+ assert.deepEqual(first.get(transcriptIdentity(unreadable)), [""], "no readable tool call: the cwd alone places it");
+
+ // Same content signature: the cached placement stands without reading the file again.
+ fs.rmSync(sessionPath);
+ const second = await attributeTranscripts([local], repo, state);
+ assert.deepEqual(second.get(transcriptIdentity(local)), ["apps/api/src/orders.ts"]);
+});
+
+test("attribution cache changes when a sibling checkout becomes known", async () => {
+ const repo = makeRepo({ "AGENTS.md": "# root\n" });
+ const state = new State(repo.root).ensure();
+ const sibling = path.join(repo.root, "sibling");
+ fs.mkdirSync(sibling);
+ const sessionPath = path.join(repo.root, "session.jsonl");
+ fs.writeFileSync(
+ sessionPath,
+ [
+ { type: "session", version: 3, id: "roots", timestamp: new Date().toISOString(), cwd: sibling },
+ {
+ type: "message",
+ message: {
+ role: "assistant",
+ content: [{ type: "toolCall", id: "t1", name: "edit", arguments: { path: "apps/api/handler.ts" } }],
+ },
+ },
+ ]
+ .map((entry) => JSON.stringify(entry))
+ .join("\n") + "\n",
+ );
+ const transcript = {
+ harness: "pi",
+ id: "pi-roots",
+ nativeId: "roots",
+ path: sessionPath,
+ cwd: sibling,
+ mtimeMs: 1,
+ bytes: 2,
+ };
+ const first = await attributeTranscripts([transcript], repo, state);
+ assert.deepEqual(first.get(transcriptIdentity(transcript)), ["sibling/apps/api/handler.ts"]);
+ const second = await attributeTranscripts([transcript], { ...repo, siblingWorktrees: [sibling] }, state);
+ assert.deepEqual(second.get(transcriptIdentity(transcript)), ["apps/api/handler.ts"]);
+});
+
+// ---------- which file owns a lesson ----------
+
+test("a lesson belongs to the most specific named file every session behind it worked under, else to the root", () => {
+ const owner = (ids) => owningFile(ids, [API, DB, WEB], ATTRIBUTION);
+ assert.equal(owner(["api-1", "api-2"]), API.path);
+ assert.equal(owner(["db-1", "db-2"]), DB.path, "the deepest file in the chain owns it");
+ assert.equal(owner(["db-1", "api-1"]), API.path, "sessions spread over apps/api fall back to apps/api");
+ assert.equal(owner(["api-1", "web-1"]), null, "two unrelated directories are cross-cutting");
+ assert.equal(owner(["both"]), null, "one session in two unrelated directories is cross-cutting too");
+ assert.equal(owningFile(["both"], [API], ATTRIBUTION), null);
+ assert.equal(owningFile(["root-file-and-api"], [API], ATTRIBUTION), null);
+ assert.equal(owner(["api-1", "remote"]), null, "a session nobody could place keeps the lesson at the root");
+ assert.equal(owner(["root"]), null);
+ assert.equal(owner([]), null);
+});
+
+function evidenceRecord(identity, gap, extra = {}) {
+ return {
+ status: "ok",
+ transcript: { harness: "pi", nativeId: identity, identity, startedAt: 0, interaction: "interactive" },
+ positive: [],
+ negative: [],
+ gaps: [
+ {
+ mistake: "worked it out by hand",
+ proposedInstruction: gap,
+ recurrenceRisk: "high",
+ domain: "project",
+ quote: `${identity} hit it`,
+ ...extra,
+ },
+ ],
+ };
+}
+
+const API_GAP = "Run the api contract tests before editing a handler.";
+const WEB_GAP = "Build the web bundle before opening a pull request.";
+
+test("the fold keeps only the gap clusters this file owns, and names where the others went", () => {
+ const records = [
+ evidenceRecord("api-1", API_GAP),
+ evidenceRecord("api-2", API_GAP),
+ evidenceRecord("web-1", WEB_GAP),
+ evidenceRecord("web-2", WEB_GAP),
+ ];
+ const fold = (weight) =>
+ foldEvidence(records, { minGapEvidence: 2, route: routingFor([API, WEB], ATTRIBUTION, "AGENTS.md", weight) });
+
+ const root = fold(null);
+ assert.deepEqual(
+ root.gaps.map((gap) => gap.proposedInstruction),
+ [],
+ "each lesson came from one app's sessions, so neither is the root's",
+ );
+ assert.deepEqual(root.routedGaps.map((gap) => [gap.owner, gap.sessions]).sort(), [
+ [API.path, 2],
+ [WEB.path, 2],
+ ]);
+ assert.match(
+ renderEvidenceForPrompt(root),
+ /2 more gap cluster\(s\) belong to apps\/api\/AGENTS\.md, apps\/web\/AGENTS\.md/,
+ );
+
+ const api = fold(API.path);
+ assert.deepEqual(
+ api.gaps.map((gap) => gap.proposedInstruction),
+ [API_GAP],
+ );
+ assert.equal(api.sourceSessions["pi · api-1 · unknown date"], "api-1", "each issued label names its session");
+
+ const unrouted = foldEvidence(records, { minGapEvidence: 2 });
+ assert.equal(unrouted.gaps.length, 2);
+ assert.ok(!("routedGaps" in unrouted) && !("sourceSessions" in unrouted), "no routing, no new summary fields");
+});
+
+test("mixed-directory sessions never enter a nested analysis corpus or own its gap", async () => {
+ const transcripts = ["api-1", "both", "root-file-and-api"].map((identity) => ({ identity }));
+ const { corpora } = await nestedCorpora({}, [API], transcripts, ATTRIBUTION);
+ assert.deepEqual(
+ corpora[0].transcripts.map((item) => item.identity),
+ ["api-1"],
+ );
+ const records = [evidenceRecord("both", API_GAP), evidenceRecord("root-file-and-api", API_GAP)];
+ const route = routingFor([API], ATTRIBUTION, "AGENTS.md", null);
+ assert.equal(foldEvidence(records, { minGapEvidence: 2, route }).gaps.length, 1);
+ assert.equal(foldEvidence(records, { minGapEvidence: 2, route: { ...route, weight: API.path } }).gaps.length, 0);
+});
+
+test("bounded quotes retain evidence of a root-owned cross-directory cluster", () => {
+ const records = [
+ ...Array.from({ length: 6 }, (_, index) => evidenceRecord(`api-${index}`, API_GAP)),
+ evidenceRecord("web-1", API_GAP),
+ ];
+ const attribution = new Map(records.map((record) => [record.transcript.identity, ["apps/api/a.ts"]]));
+ attribution.set("web-1", ["apps/web/b.ts"]);
+ const root = foldEvidence(records, {
+ minGapEvidence: 2,
+ route: routingFor([API, WEB], attribution, "AGENTS.md", null),
+ });
+ assert.equal(root.gaps.length, 1);
+ assert.equal(root.gaps[0].quotes.length, 6);
+ assert.ok(root.gaps[0].quotes.some((quote) => quote.source.includes("web-1")));
+});
+
+test("a failed skill trigger stays with the root file, which owns the skill layer", () => {
+ const records = [
+ evidenceRecord("api-1", API_GAP, { coveredBySkill: "api-contract" }),
+ evidenceRecord("api-2", API_GAP, { coveredBySkill: "api-contract" }),
+ ];
+ const fold = (weight) =>
+ foldEvidence(records, { minGapEvidence: 2, route: routingFor([API], ATTRIBUTION, "AGENTS.md", weight) });
+ assert.deepEqual(
+ fold(null).gaps.map((gap) => gap.failedTriggerSkill),
+ ["api-contract"],
+ );
+ assert.deepEqual(fold(API.path).gaps, []);
+});
+
+// ---------- the proposal gate routes new instructions ----------
+
+const labelOf = (id) => `pi · ${id} · 1970-01-01`;
+
+function routedGate({
+ memoryPath,
+ weight,
+ sessions,
+ change = (text) => `${text}- Run the contract tests first.\n`,
+ kind = "add",
+ routing = true,
+ weights = [API, WEB],
+ initialText = null,
+}) {
+ const repo = makeRepo({
+ "AGENTS.md": "# Root\n\n- Use pnpm for every package script.\n",
+ "apps/api/AGENTS.md": "# API\n\n- Handlers live in src/routes.\n",
+ "apps/api/db/AGENTS.md": "# Database\n\n- Migrations live in db.\n",
+ });
+ if (initialText !== null) writeIn(repo.root, memoryPath, initialText);
+ const staged = stageAndMeasure({ repo, memoryPath, edit: (root) => writeIn(root, memoryPath, change) });
+ const labels = [...ATTRIBUTION.keys()].map(labelOf);
+ const summary = {
+ analyzedSessions: 4,
+ totals: { positive: 0, negative: 0, gapClusters: 1 },
+ instructions: [],
+ sources: labels,
+ sourceSessions: Object.fromEntries([...ATTRIBUTION.keys()].map((id) => [labelOf(id), id])),
+ };
+ return buildProposal(
+ {
+ edits: [
+ {
+ changes: staged.measured.changes.map((change) => change.id),
+ kind,
+ title: "contract tests",
+ evidence: sessions.map((id) => ({ polarity: "negative", text: `${id} hit it`, source: labelOf(id) })),
+ },
+ ],
+ },
+ {
+ memoryFile: staged.memoryFile,
+ config: { budgetTokens: 5000, maxEditsPerRun: 5, minGapEvidence: 2, skillsDir: ".agents/skills" },
+ repo,
+ summary,
+ measured: staged.measured,
+ routing: routing ? routingFor(weights, ATTRIBUTION, "AGENTS.md", weight) : null,
+ },
+ );
+}
+
+test("a new instruction backed only by one app's sessions is refused in the root file and kept in the app's", () => {
+ const inRoot = routedGate({ memoryPath: "AGENTS.md", weight: null, sessions: ["api-1", "api-2"] });
+ assert.equal(inRoot.violations.length, 1);
+ assert.match(
+ inRoot.violations[0],
+ /backed only by sessions that worked under apps\/api\/; it belongs in apps\/api\/AGENTS\.md/,
+ );
+
+ const inApi = routedGate({ memoryPath: API.path, weight: API.path, sessions: ["api-1", "api-2"] });
+ assert.deepEqual(inApi.violations, []);
+ assert.equal(inApi.proposal.edits.length, 1);
+
+ const unconfigured = routedGate({
+ memoryPath: "AGENTS.md",
+ weight: null,
+ sessions: ["api-1", "api-2"],
+ routing: false,
+ });
+ assert.deepEqual(unconfigured.violations, [], "without nested files the gate does not exist");
+});
+
+test("a new instruction backed by sessions from more than one app is refused in the app's file and kept in the root", () => {
+ const inApi = routedGate({ memoryPath: API.path, weight: API.path, sessions: ["api-1", "web-1"] });
+ assert.equal(inApi.violations.length, 1);
+ assert.match(inApi.violations[0], /cross-cutting evidence belongs in AGENTS\.md, not apps\/api\/AGENTS\.md/);
+
+ const inRoot = routedGate({ memoryPath: "AGENTS.md", weight: null, sessions: ["api-1", "web-1"] });
+ assert.deepEqual(inRoot.violations, []);
+});
+
+test("a rewrite stays with the file whose text it changes, whoever's sessions back it", () => {
+ const rewrite = routedGate({
+ memoryPath: "AGENTS.md",
+ weight: null,
+ sessions: ["api-1", "api-2"],
+ kind: "rewrite",
+ change: (text) => text.replace("every package script", "every package script, including the api's"),
+ });
+ assert.deepEqual(rewrite.violations, []);
+});
+
+test("a separate addition in a mixed rewrite routes to its deepest owner", () => {
+ const initialText = `# Memory\n\n- Rewrite this line.\n${Array.from({ length: 20 }, (_, i) => `- Existing rule ${i}.\n`).join("")}`;
+ const change = (text) => text.replace("Rewrite this line", "Clarify this line") + "- Run the contract tests first.\n";
+ /** @type {[string, string | null, { path: string, dir: string }[], string[], string][]} */
+ const cases = [
+ ["AGENTS.md", null, [API, DB], ["api-1", "api-2"], API.path],
+ [API.path, API.path, [API, DB], ["db-1", "db-2"], DB.path],
+ ];
+ for (const [memoryPath, weight, weights, sessions, owner] of cases) {
+ const result = routedGate({ memoryPath, weight, weights, sessions, kind: "rewrite", initialText, change });
+ assert.equal(result.proposal.edits.length, 0);
+ assert.ok(result.violations.some((violation) => violation.includes(`it belongs in ${owner}`)));
+ }
+ const correct = routedGate({
+ memoryPath: API.path,
+ weight: API.path,
+ weights: [API, DB],
+ sessions: ["api-1", "api-2"],
+ kind: "rewrite",
+ initialText,
+ change,
+ });
+ assert.deepEqual(correct.violations, []);
+ assert.equal(correct.proposal.edits[0].hunks.length, 2, "the rewrite and addition are separate measured hunks");
+});
+
+// ---------- each nested file has its own budget ----------
+
+test("a nested pass runs in its own state under its own budget, sharing only the recorded rejections", () => {
+ const repo = makeRepo({ "AGENTS.md": "# root\n", "apps/api/AGENTS.md": "# api\n" });
+ const rootState = new State(repo.root).ensure();
+ const ctx = {
+ repo,
+ config: { state: rootState, budgetTokens: 5000, nestedBudgetTokens: 40, memoryFiles: ["AGENTS.md"] },
+ };
+ const nested = nestedContext(ctx, API);
+ assert.equal(nested.config.budgetTokens, 40);
+ assert.deepEqual(nested.config.memoryFiles, [API.path]);
+ assert.deepEqual(nested.config.target, { kind: "memory", path: API.path, nested: true });
+ assert.ok(nested.config.state.root.startsWith(path.join(rootState.root, "nested")));
+ assert.equal(nested.config.state.rejectionsPath, rootState.rejectionsPath);
+ assert.equal(
+ nestedContext({ ...ctx, config: { ...ctx.config, nestedBudgetTokens: null } }, API).config.budgetTokens,
+ 5000,
+ );
+});
+
+function boundNestedContext() {
+ const repo = makeRepo();
+ const state = new State(repo.root, {
+ stateDir: path.join(repo.root, "private-state"),
+ mode: 0o700,
+ exclude: false,
+ binding: { kind: "project", root: repo.root },
+ }).ensure();
+ return { repo, config: { state, budgetTokens: 5000 } };
+}
+
+test(
+ "bound nested state keeps private evidence and shares rejection reads and writes",
+ { skip: process.platform === "win32" },
+ () => {
+ const ctx = boundNestedContext();
+ const rootState = ctx.config.state;
+ const state = nestedContext(ctx, API).config.state;
+ const transcript = { harness: "pi", id: "private-session" };
+ state.writeEvidence(transcript, { status: "ok", transcript });
+ assert.equal(state.readEvidence(transcript).status, "ok");
+ assert.equal(fs.statSync(state.evidencePath(transcript)).mode & 0o777, 0o600);
+ assert.deepEqual(state.readJsonFile(path.join(state.root, "scope.json"), null), rootState.binding);
+ rootState.writeRejections({ version: 1, entries: { first: { title: "root rejection" } } });
+ assert.equal(state.readRejections().entries.first.title, "root rejection");
+ state.writeRejections({ version: 1, entries: { second: { title: "nested rejection" } } });
+ assert.equal(rootState.readRejections().entries.second.title, "nested rejection");
+ },
+);
+
+for (const directory of ["nested", "weight", "evidence", "apply"]) {
+ test(
+ `bound nested state refuses a linked ${directory} directory before writing`,
+ { skip: process.platform === "win32" },
+ () => {
+ const ctx = boundNestedContext();
+ const rootState = ctx.config.state;
+ const weightDir = nestedStateDir(rootState, API.path);
+ const link =
+ directory === "nested"
+ ? path.join(rootState.root, "nested")
+ : directory === "weight"
+ ? weightDir
+ : path.join(weightDir, directory);
+ const outside = path.join(ctx.repo.root, "outside-state");
+ fs.mkdirSync(outside, { mode: 0o700 });
+ fs.mkdirSync(path.dirname(link), { recursive: true, mode: 0o700 });
+ fs.symlinkSync(outside, link, "dir");
+ assert.throws(() => {
+ const state = nestedContext(ctx, API).config.state;
+ state.writeEvidence({ harness: "pi", id: "escaped" }, { status: "ok" });
+ }, /unsafe private state path/);
+ assert.deepEqual(fs.readdirSync(outside), []);
+ },
+ );
+}
+
+for (const cached of [false, true]) {
+ test(
+ `bound attribution refuses a linked nested directory with ${cached ? "cached" : "missing"} state`,
+ { skip: process.platform === "win32" },
+ async () => {
+ const ctx = boundNestedContext();
+ const outside = path.join(ctx.repo.root, "outside-attribution");
+ fs.mkdirSync(outside, { mode: 0o700 });
+ const cache = path.join(outside, "attribution.json");
+ if (cached) fs.writeFileSync(cache, JSON.stringify({ version: 1, entries: {} }), { mode: 0o600 });
+ const before = cached ? fs.readFileSync(cache, "utf8") : null;
+ fs.symlinkSync(outside, path.join(ctx.config.state.root, "nested"), "dir");
+ await assert.rejects(attributeTranscripts([], ctx.repo, ctx.config.state), /unsafe private state path/);
+ assert.deepEqual(fs.readdirSync(outside), cached ? ["attribution.json"] : []);
+ if (cached) assert.equal(fs.readFileSync(cache, "utf8"), before);
+ },
+ );
+}
+
+test(
+ "bound attribution creates a private cache and reuses local placements",
+ { skip: process.platform === "win32" },
+ async () => {
+ const ctx = boundNestedContext();
+ const transcript = {
+ harness: "pi",
+ id: "local",
+ cwd: path.join(ctx.repo.root, API.dir),
+ path: "missing",
+ mtimeMs: 1,
+ bytes: 1,
+ };
+ const first = await attributeTranscripts([transcript], ctx.repo, ctx.config.state);
+ assert.deepEqual(first.get(transcriptIdentity(transcript)), [API.dir]);
+ const dir = path.join(ctx.config.state.root, "nested");
+ assert.equal(fs.statSync(dir).mode & 0o777, 0o700);
+ assert.equal(fs.statSync(path.join(dir, "attribution.json")).mode & 0o777, 0o600);
+ const second = await attributeTranscripts([transcript], ctx.repo, ctx.config.state);
+ assert.deepEqual(second, first);
+ },
+);
+
+function mergedProposal() {
+ const repo = makeRepo({
+ "AGENTS.md": "# Root\n\n- Use pnpm for every package script.\n",
+ "apps/api/AGENTS.md": "# API\n\n- Handlers live in src/routes.\n",
+ });
+ const config = { budgetTokens: 5000, maxEditsPerRun: 5, minGapEvidence: 2, skillsDir: ".agents/skills" };
+ const rootStaged = stageAndMeasure({ repo, edit: () => {} });
+ const root = buildProposal(
+ { edits: [] },
+ { memoryFile: rootStaged.memoryFile, config, repo, summary: null, measured: rootStaged.measured },
+ );
+ const apiStaged = stageAndMeasure({
+ repo,
+ memoryPath: API.path,
+ edit: (dir) =>
+ writeIn(dir, API.path, (text) => `${text}- Run the api contract tests before editing a handler, every time.\n`),
+ });
+ const api = buildProposal(
+ {
+ edits: [
+ {
+ changes: ["H1"],
+ kind: "add",
+ title: "contract tests",
+ evidence: [
+ { polarity: "negative", text: "api-1 hit it", source: "a" },
+ { polarity: "negative", text: "api-2 hit it", source: "b" },
+ ],
+ },
+ ],
+ },
+ {
+ memoryFile: apiStaged.memoryFile,
+ config,
+ repo,
+ summary: null,
+ measured: apiStaged.measured,
+ target: { kind: "memory", path: API.path, nested: true },
+ },
+ );
+ assert.deepEqual(api.violations, []);
+ const weight = { ...API, file: apiStaged.memoryFile };
+ const quiet = { ...WEB, file: { ...apiStaged.memoryFile, path: WEB.path } };
+ const proposal = mergeNestedProposals(root.proposal, [
+ { weight, transcripts: [{}, {}], proposal: api.proposal, summary: null, cap: 5000, skipped: null },
+ {
+ weight: quiet,
+ transcripts: [],
+ proposal: null,
+ summary: null,
+ cap: 5000,
+ skipped: "nothing to learn from this run",
+ },
+ ]);
+ return { repo, proposal, state: rootStaged.state };
+}
+
+test("one proposal covers every file: nested edits are renumbered, labeled by file, and freshness-checked", () => {
+ const { proposal } = mergedProposal();
+ assert.deepEqual(
+ proposal.edits.map((edit) => [edit.id, edit.file, edit.nestedMemoryFile, edit.targetsMemoryFile]),
+ [["e1", API.path, API.path, false]],
+ );
+ assert.deepEqual(
+ proposal.nested.map((entry) => [entry.memoryFile.path, entry.sessions, entry.edits, entry.skipped ?? null]),
+ [
+ [API.path, 2, ["e1"], null],
+ [WEB.path, 0, [], "nothing to learn from this run"],
+ ],
+ );
+ const quiet = proposal.nested[1].budget;
+ assert.equal(quiet.projected, quiet.current, "a file with nothing to learn still shows where its budget stands");
+ assert.deepEqual(
+ proposal.targetFiles.map((target) => target.file),
+ [API.path],
+ "only a file with edits is freshness-checked",
+ );
+});
+
+test("apply holds each nested file to its own budget, and writes nothing when the accepted subset breaks it", () => {
+ const over = mergedProposal();
+ const refused = applyDecisions({
+ proposal: over.proposal,
+ decisions: { e1: "accepted" },
+ repo: over.repo,
+ state: over.state,
+ config: { budgetTokens: 5000, nestedBudgetTokens: 20, nestedMemoryFiles: [API.path] },
+ });
+ assert.equal(refused.written.length, 0);
+ assert.match(
+ refused.failed[0]?.error ?? "",
+ /leave apps\/api\/AGENTS\.md at \d+ tokens, \d+ over its 20-token budget/,
+ );
+ assert.equal(
+ fs.readFileSync(path.join(over.repo.root, API.path), "utf8"),
+ "# API\n\n- Handlers live in src/routes.\n",
+ );
+
+ const within = mergedProposal();
+ const written = applyDecisions({
+ proposal: within.proposal,
+ decisions: { e1: "accepted" },
+ repo: within.repo,
+ state: within.state,
+ config: { budgetTokens: 5000, nestedBudgetTokens: 200, nestedMemoryFiles: [API.path] },
+ });
+ assert.deepEqual(written.failed, []);
+ assert.deepEqual(
+ written.written.map((entry) => [entry.file, entry.budget?.capTokens]),
+ [[API.path, 200]],
+ );
+ assert.match(fs.readFileSync(path.join(within.repo.root, API.path), "utf8"), /Run the api contract tests/);
+});
+
+test("apply refuses a saved nested write after the named scope is removed", () => {
+ const { repo, proposal, state } = mergedProposal();
+ const before = fs.readFileSync(path.join(repo.root, API.path), "utf8");
+ const result = applyDecisions({
+ proposal,
+ decisions: { e1: "accepted" },
+ repo,
+ state,
+ config: { budgetTokens: 5000, nestedBudgetTokens: 200, nestedMemoryFiles: [] },
+ });
+ assert.deepEqual(result.written, []);
+ assert.match(result.failed[0]?.error ?? "", /apps\/api\/AGENTS\.md is no longer named in nestedMemoryFiles/);
+ assert.equal(fs.readFileSync(path.join(repo.root, API.path), "utf8"), before);
+});
+
+test("nested-only apply is not blocked by an unchanged over-budget root", () => {
+ const { repo, proposal, state } = mergedProposal();
+ const rootBefore = fs.readFileSync(path.join(repo.root, "AGENTS.md"), "utf8");
+ const result = applyDecisions({
+ proposal,
+ decisions: { e1: "accepted" },
+ repo,
+ state,
+ config: { budgetTokens: 1, nestedBudgetTokens: 200, nestedMemoryFiles: [API.path] },
+ });
+ assert.deepEqual(result.failed, []);
+ assert.deepEqual(
+ result.written.map((item) => item.file),
+ [API.path],
+ );
+ assert.equal(fs.readFileSync(path.join(repo.root, "AGENTS.md"), "utf8"), rootBefore);
+ assert.match(fs.readFileSync(path.join(repo.root, API.path), "utf8"), /Run the api contract tests/);
+});
diff --git a/test/opencode-regressions.test.js b/test/opencode-regressions.test.js
new file mode 100644
index 00000000..37249499
--- /dev/null
+++ b/test/opencode-regressions.test.js
@@ -0,0 +1,188 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+import * as opencode from "../src/discovery/adapters/opencode.js";
+import { readTranscript } from "../src/discovery/index.js";
+import { distill } from "../src/distill.js";
+import { SELF_SESSION_SENTINEL } from "../src/sentinel.js";
+import { readOpencodeFixture, withOpencodeHome, writeOpencodeStore } from "./helpers/opencode.js";
+
+for (const layout of ["v1", "v2"]) {
+ for (const configured of [false, true]) {
+ test(`${layout} ${configured ? "configured" : "default"} store disappearing after discovery rejects transcript reading`, async () => {
+ await withOpencodeHome(
+ (dbFile, home) =>
+ writeOpencodeStore(
+ configured ? path.join(home, "copy.db") : dbFile,
+ readOpencodeFixture(`opencode-${layout}-store.json`),
+ ),
+ async (dbFile, home) => {
+ const config = { discovery: { opencodeStores: configured ? [path.join(home, "copy.db")] : [] } };
+ const [row] = await opencode.discover({ config });
+ assert.ok((await readTranscript({ ...row, harness: "opencode" })).events.length);
+ fs.rmSync(row.path);
+ await assert.rejects(readTranscript({ ...row, harness: "opencode" }), (error) => {
+ assert.ok(error instanceof Error);
+ assert.ok(error.message.includes(row.path), error.message);
+ return true;
+ });
+ assert.equal(fs.existsSync(row.path), false, "reading must not recreate the missing store");
+ },
+ );
+ });
+ }
+
+ test(`${layout} attachment-only user messages survive reading and distillation`, async () => {
+ const fixture = readOpencodeFixture(`opencode-${layout}-store.json`);
+ const file = { type: "file", mime: "image/png", filename: "failure.png", url: "data:image/png;base64,AAAA" };
+ const sessionId = fixture.rows[layout === "v1" ? "session" : "session_v2"][0].id;
+ if (layout === "v1") {
+ const user = fixture.rows.message.find((row) => row.session_id === sessionId && row.data.role === "user");
+ const part = fixture.rows.part.find((row) => row.message_id === user.id);
+ part.data = file;
+ } else {
+ const user = fixture.rows.session_message.find((row) => row.session_id === sessionId && row.type === "user");
+ user.data.text = "";
+ user.data.files = [file];
+ }
+ await withOpencodeHome(
+ (dbFile) => writeOpencodeStore(dbFile, fixture),
+ async () => {
+ const row = (await opencode.discover()).find((row) => row.id === sessionId);
+ assert.equal(row.self, false);
+ const { events } = await readTranscript({ ...row, harness: "opencode" });
+ assert.deepEqual(events[0], { kind: "message", role: "user", text: "[Attachment-only user message]" });
+ assert.equal(distill(events, {}).stats.userTurns, layout === "v1" ? 1 : 2);
+ },
+ );
+ });
+}
+
+test("2.x bookkeeping-only sessions are excluded, but every primary activity type is recorded", async () => {
+ const fixture = readOpencodeFixture("opencode-v2-store.json");
+ const types = ["synthetic", "system", "compaction", "idle", "location-switched", "agent-switched", "model-switched"];
+ const active = {
+ user: { text: "Hello" },
+ assistant: { content: [{ type: "text", text: "Hello" }] },
+ shell: { command: "pwd", output: { output: "/repo/demo" }, status: "exited", exit: 0 },
+ skill: { name: "release" },
+ };
+ for (const type of [...types, ...Object.keys(active)]) {
+ fixture.rows.session_v2.push({ ...fixture.rows.session_v2[0], id: type });
+ fixture.rows.session_message.push({
+ ...fixture.rows.session_message[0],
+ id: `msg_${type}`,
+ session_id: type,
+ type,
+ data: active[type] || { text: "Harness notice" },
+ });
+ }
+ await withOpencodeHome(
+ (dbFile) => writeOpencodeStore(dbFile, fixture),
+ async () => {
+ const rows = await opencode.discover();
+ for (const type of types)
+ assert.equal(
+ rows.some((row) => row.id === type),
+ false,
+ type,
+ );
+ for (const type of Object.keys(active)) {
+ const row = rows.find((row) => row.id === type);
+ assert.ok(row, type);
+ assert.equal((await opencode.read(row)).events.length, 1, type);
+ }
+ },
+ );
+});
+
+for (const layout of ["v1", "v2"]) {
+ test(`recent 2.x children retain old ${layout} self ancestry through an unused intermediate`, async () => {
+ const fixture = readOpencodeFixture("opencode-v2-store.json");
+ for (const rows of [fixture.rows.session_v2, fixture.rows.session_message]) {
+ for (const row of rows) row.time_created = row.time_updated = 1;
+ }
+ const [, realChild, self, , unused, selfChild] = fixture.rows.session_v2;
+ selfChild.parent_id = unused.id;
+ unused.parent_id = self.id;
+ // Only message activity advances; session metadata remains out of the window.
+ for (const message of fixture.rows.session_message) {
+ if ([realChild.id, selfChild.id].includes(message.session_id)) message.time_updated = 1000;
+ }
+ await withOpencodeHome(
+ (dbFile) => {
+ if (layout === "v1") {
+ const v1 = readOpencodeFixture("opencode-v1-store.json");
+ for (const session of v1.rows.session) {
+ session.project_id = fixture.rows.project[0].id;
+ session.time_created = session.time_updated = 1;
+ }
+ v1.rows.part[0].data.text = `${SELF_SESSION_SENTINEL}\nAnalyze this trace.`;
+ unused.parent_id = v1.rows.session[0].id;
+ writeOpencodeStore(dbFile, fixture);
+ writeOpencodeStore(dbFile, v1, { skipTables: ["project", "session_message"] });
+ } else {
+ writeOpencodeStore(dbFile, fixture);
+ }
+ },
+ async () => {
+ const rows = await opencode.discover({ cutoffMs: 1000 });
+ assert.deepEqual(rows.map((row) => row.id).sort(), [realChild.id, selfChild.id].sort());
+ assert.equal(rows.find((row) => row.id === selfChild.id).self, true);
+ assert.equal(rows.find((row) => row.id === realChild.id).self, false);
+ },
+ );
+ });
+
+ test(`${layout} bounded discovery does not materialize unrelated old sessions`, async (t) => {
+ const fixture = readOpencodeFixture(`opencode-${layout}-store.json`);
+ const sessions = fixture.rows[layout === "v1" ? "session" : "session_v2"];
+ for (let i = 0; i < 50; i++) {
+ const id = `old_${i}`;
+ sessions.push({ ...sessions[0], id, time_created: 1, time_updated: 1 });
+ if (layout === "v1") {
+ fixture.rows.message.push({ ...fixture.rows.message[0], id: `msg_${id}`, session_id: id, time_created: 1 });
+ fixture.rows.part.push({
+ ...fixture.rows.part[0],
+ id: `part_${id}`,
+ session_id: id,
+ message_id: `msg_${id}`,
+ time_created: 1,
+ });
+ } else {
+ const user = fixture.rows.session_message.find((row) => row.type === "user");
+ fixture.rows.session_message.push({
+ ...user,
+ id: `msg_${id}`,
+ session_id: id,
+ time_created: 1,
+ time_updated: 1,
+ });
+ }
+ }
+ await withOpencodeHome(
+ (dbFile) => writeOpencodeStore(dbFile, fixture),
+ async () => {
+ // Observe actual database result rows, not SQL spelling or implementation source.
+ const materialized = [];
+ const prepare = DatabaseSync.prototype.prepare;
+ t.mock.method(DatabaseSync.prototype, "prepare", function (...args) {
+ const statement = prepare.apply(this, args);
+ const all = statement.all;
+ t.mock.method(statement, "all", function (...params) {
+ const rows = all.apply(this, params);
+ materialized.push(...rows);
+ return rows;
+ });
+ return statement;
+ });
+ const rows = await opencode.discover({ cutoffMs: 1000 });
+ assert.ok(rows.length);
+ assert.equal(materialized.filter((row) => row.id?.startsWith("old_")).length, 0);
+ },
+ );
+ });
+}
diff --git a/test/opencode-stores.test.js b/test/opencode-stores.test.js
new file mode 100644
index 00000000..a405a67b
--- /dev/null
+++ b/test/opencode-stores.test.js
@@ -0,0 +1,248 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+import * as opencode from "../src/discovery/adapters/opencode.js";
+import { loadConfig } from "../src/config.js";
+import { discoverTranscripts } from "../src/discovery/index.js";
+import { setLoggerSink, UserError } from "../src/logger.js";
+import { readOpencodeFixture, withOpencodeHome, writeOpencodeStore } from "./helpers/opencode.js";
+
+/**
+ * `discovery.opencodeStores`: more OpenCode stores to read beside the default one, named
+ * in personal config (never the environment, which the OpenCode backpass runs for
+ * analysis inherits). Each store's sessions are read from that store; a store reached
+ * twice, or a session copied into two stores, is read once.
+ */
+
+const V1 = readOpencodeFixture("opencode-v1-store.json");
+const V2 = readOpencodeFixture("opencode-v2-store.json");
+const V1_SESSION = "ses_f16e2d036ffeZd4lFcWRZCBMYV";
+const V2_PARENT = "ses_f17ca477affeM7vJpYuwLTunDK";
+
+function withConfigHome(globalConfig, fn) {
+ const configHome = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-stores-xdg-"));
+ const previous = process.env.XDG_CONFIG_HOME;
+ try {
+ if (globalConfig) {
+ fs.mkdirSync(path.join(configHome, "backpass"), { recursive: true });
+ fs.writeFileSync(path.join(configHome, "backpass", "config.json"), JSON.stringify(globalConfig));
+ }
+ process.env.XDG_CONFIG_HOME = configHome;
+ return fn();
+ } finally {
+ if (previous === undefined) delete process.env.XDG_CONFIG_HOME;
+ else process.env.XDG_CONFIG_HOME = previous;
+ fs.rmSync(configHome, { recursive: true, force: true });
+ }
+}
+
+function tempRepo(t, repoConfig) {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-stores-repo-"));
+ t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+ if (repoConfig) fs.writeFileSync(path.join(root, ".backpassrc.json"), JSON.stringify(repoConfig));
+ return fs.realpathSync(root);
+}
+
+async function captureWarnings(fn) {
+ const lines = [];
+ setLoggerSink((line) => lines.push(line));
+ try {
+ return { result: await fn(), lines };
+ } finally {
+ setLoggerSink(null);
+ }
+}
+
+test("config fixtures restore the environment and remove directories on success and failure", () => {
+ const previous = process.env.XDG_CONFIG_HOME;
+ try {
+ for (const value of [undefined, "", "/original/config"]) {
+ for (const fail of [false, true]) {
+ if (value === undefined) delete process.env.XDG_CONFIG_HOME;
+ else process.env.XDG_CONFIG_HOME = value;
+ let configHome;
+ const failure = new Error("fixture callback failed");
+ const run = () =>
+ withConfigHome({}, () => {
+ configHome = process.env.XDG_CONFIG_HOME;
+ assert.ok(fs.existsSync(path.join(configHome, "backpass", "config.json")));
+ if (fail) throw failure;
+ return "result";
+ });
+ if (fail) assert.throws(run, (error) => error === failure);
+ else assert.equal(run(), "result");
+ assert.equal(process.env.XDG_CONFIG_HOME, value);
+ assert.equal(fs.existsSync(configHome), false);
+ }
+ }
+ } finally {
+ if (previous === undefined) delete process.env.XDG_CONFIG_HOME;
+ else process.env.XDG_CONFIG_HOME = previous;
+ }
+});
+
+test("repository fixtures are removed after their owning test", async (t) => {
+ let root;
+ await t.test("fixture owner", (t) => {
+ root = tempRepo(t, {});
+ assert.ok(fs.existsSync(path.join(root, ".backpassrc.json")));
+ });
+ assert.equal(fs.existsSync(root), false);
+});
+
+test("opencodeStores is personal configuration: expanded, absolute, and refused in a repository file", (t) => {
+ const home = os.homedir();
+ withConfigHome({ discovery: { opencodeStores: ["~/snapshots/opencode", "/srv/opencode.db"] } }, () => {
+ const config = loadConfig(tempRepo(t));
+ assert.deepEqual(config.discovery.opencodeStores, [path.join(home, "snapshots", "opencode"), "/srv/opencode.db"]);
+ assert.deepEqual(
+ loadConfig(null, {}, { kind: "user" }).discovery.opencodeStores,
+ [path.join(home, "snapshots", "opencode"), "/srv/opencode.db"],
+ "user scope reads the same top-level list, so stores are named once",
+ );
+ });
+ withConfigHome(null, () => {
+ assert.deepEqual(loadConfig(tempRepo(t)).discovery.opencodeStores, []);
+ assert.throws(
+ () => loadConfig(tempRepo(t), { discovery: { opencodeStores: "~/snap" } }),
+ /opencodeStores must be an array of paths/,
+ );
+ assert.throws(
+ () => loadConfig(tempRepo(t), { discovery: { opencodeStores: ["snapshots/opencode"] } }),
+ /opencodeStores entry "snapshots\/opencode" is not an absolute path/,
+ );
+ let refused = null;
+ try {
+ loadConfig(tempRepo(t, { discovery: { opencodeStores: ["/srv/opencode.db"] } }));
+ } catch (err) {
+ refused = err;
+ }
+ assert.ok(refused instanceof UserError, "a checked-in file may not point backpass at a transcript store");
+ assert.match(refused.message, /\.backpassrc\.json sets discovery\.opencodeStores/);
+ assert.match(refused.hint, /backpass[/\\]config\.json/);
+ });
+});
+
+test("a configured store joins the default one, and each session is read from its own store", async () => {
+ await withOpencodeHome(
+ (dbFile, home) => {
+ writeOpencodeStore(dbFile, V1);
+ writeOpencodeStore(path.join(home, "desktop", "opencode.db"), V2);
+ },
+ async (dbFile, home) => {
+ const configured = path.join(home, "desktop");
+ const rows = await opencode.discover({ cutoffMs: null, config: { discovery: { opencodeStores: [configured] } } });
+ const byId = new Map(rows.map((row) => [row.id, row]));
+ assert.equal(byId.get(V1_SESSION).path, dbFile);
+ assert.equal(byId.get(V2_PARENT).path, path.join(configured, "opencode.db"), "a directory holds opencode.db");
+ assert.equal(byId.get(V2_PARENT).cwd, "/repo/demo");
+
+ const { events } = await opencode.read(byId.get(V2_PARENT));
+ assert.equal(events[0].text, "Open a PR for the parser fix.", "read from the store it was listed in");
+
+ const byFile = await opencode.discover({
+ cutoffMs: null,
+ config: { discovery: { opencodeStores: [path.join(configured, "opencode.db")] } },
+ });
+ assert.deepEqual(byFile.map((row) => row.id).sort(), rows.map((row) => row.id).sort(), "or name the file");
+ },
+ );
+});
+
+test("a store named twice, or a session copied into two stores, is read once", async () => {
+ await withOpencodeHome(
+ (dbFile, home) => {
+ writeOpencodeStore(dbFile, V2);
+ writeOpencodeStore(path.join(home, "copy", "opencode.db"), V2);
+ },
+ async (dbFile, home) => {
+ const stores = [path.dirname(dbFile), dbFile, path.join(home, "copy")];
+ assert.deepEqual(opencode.storeFiles({ discovery: { opencodeStores: stores } }), [
+ dbFile,
+ path.join(home, "copy", "opencode.db"),
+ ]);
+ const rows = await opencode.discover({ cutoffMs: null, config: { discovery: { opencodeStores: stores } } });
+ const single = await opencode.discover({ cutoffMs: null });
+ assert.deepEqual(
+ rows.map((row) => row.id).sort(),
+ single.map((row) => row.id).sort(),
+ "one row per session, as if the store were read once",
+ );
+ assert.ok(
+ rows.every((row) => row.path === dbFile),
+ "the first store listing a session keeps it, so its identity is stable",
+ );
+ },
+ );
+});
+
+test("a configured store that is missing or unreadable is named and skipped; the rest are read", async () => {
+ await withOpencodeHome(
+ (dbFile, home) => {
+ writeOpencodeStore(dbFile, V1);
+ const junk = path.join(home, "junk", "opencode.db");
+ fs.mkdirSync(path.dirname(junk), { recursive: true });
+ const db = new DatabaseSync(junk);
+ db.exec("CREATE TABLE unrelated (id INTEGER)");
+ db.close();
+ writeOpencodeStore(path.join(home, "desktop", "opencode.db"), V2);
+ },
+ async (dbFile, home) => {
+ const warnings = [];
+ const rows = await opencode.discover({
+ cutoffMs: null,
+ config: {
+ discovery: {
+ opencodeStores: [path.join(home, "absent"), path.join(home, "junk"), path.join(home, "desktop")],
+ },
+ },
+ warn: (message) => warnings.push(message),
+ });
+ assert.ok(rows.some((row) => row.id === V1_SESSION));
+ assert.ok(rows.some((row) => row.id === V2_PARENT));
+ assert.deepEqual(warnings, [
+ `configured store ${path.join(home, "absent", "opencode.db")} not found - skipped`,
+ `configured store ${path.join(home, "junk", "opencode.db")} unreadable (no session or session_v2 table (unrecognised opencode store)) - skipped`,
+ ]);
+ },
+ );
+});
+
+test("discovery associates a configured store's sessions and names a missing store", async (t) => {
+ const repoRoot = tempRepo(t);
+ const shape = structuredClone(V2);
+ for (const session of shape.rows.session_v2) session.directory = repoRoot;
+ await withOpencodeHome(
+ (dbFile, home) => writeOpencodeStore(path.join(home, "desktop", "opencode.db"), shape),
+ async (dbFile, home) => {
+ const config = withConfigHome(
+ { discovery: { opencodeStores: [path.join(home, "desktop"), path.join(home, "absent")] } },
+ () => loadConfig(repoRoot, { discovery: { harnesses: ["opencode"], since: "all" } }),
+ );
+ config.state = { root: path.join(repoRoot, ".backpass"), readScanCache: () => ({ version: 1, entries: {} }) };
+ const repo = { name: path.basename(repoRoot), root: repoRoot, worktrees: [repoRoot], remotes: [] };
+ const { result, lines } = await captureWarnings(() => discoverTranscripts({ repo, config }));
+ assert.deepEqual(result.transcripts.map((transcript) => transcript.nativeId).sort(), [
+ "ses_f0a1b2c3dffeResumedSession01",
+ "ses_f17c42540ffeM0ZIydCm19byyr",
+ V2_PARENT,
+ ]);
+ assert.equal(
+ result.perHarness.opencode.self,
+ 2,
+ "backpass's own session in that store, and the subagent it delegated to, are still dropped",
+ );
+ assert.ok(result.transcripts.every((transcript) => transcript.association.tier === 1));
+ assert.ok(
+ lines.some((line) =>
+ line.includes(`opencode: configured store ${path.join(home, "absent", "opencode.db")} not found`),
+ ),
+ lines.join("\n"),
+ );
+ },
+ );
+});
diff --git a/test/proposal.test.js b/test/proposal.test.js
index 1fa8fd26..fad59e9d 100644
--- a/test/proposal.test.js
+++ b/test/proposal.test.js
@@ -17,7 +17,7 @@ import {
import { foldEvidence, renderEvidenceForPrompt, renderEvidenceReport } from "../src/fold.js";
import { estimateTokens } from "../src/tokens.js";
import { loadProjectSkills, skillDescriptionTokens } from "../src/skills.js";
-import { parseMemoryUnits } from "../src/memory.js";
+import { parseMemoryUnits, unitHash } from "../src/memory.js";
import { isSuppressedByRejection, recordRejection, State } from "../src/state.js";
import { applyDecisions } from "../src/apply/writer.js";
import { injectPayload, parseDecisions, renderApplySurface } from "../src/apply/lavish.js";
@@ -1657,6 +1657,156 @@ test("rejection suppression distinguishes multi-file extraction destinations", (
assert.equal(otherDestination.proposal.edits.length, 1, "a different destination is a materially different edit");
});
+const GAP_ID = "cafef00ddeadbeef";
+const THIRD_QUOTE = { polarity: "negative", text: "a third session hit the same pin", source: "pi · ghi · turn 2" };
+
+function summaryWithGap(quotes = QUOTE) {
+ return {
+ analyzedSessions: 4,
+ totals: { positive: 3, negative: 2, gapClusters: 1 },
+ sources: quotes.map((q) => q.source),
+ instructions: Array.from({ length: 20 }, (_, i) => ({
+ instruction: `AG-${String(i + 1).padStart(3, "0")}`,
+ positive: 0,
+ negative: 4,
+ harmSessions: 4,
+ sessions: 4,
+ relevance: 1,
+ quotes: [],
+ })),
+ gaps: [
+ {
+ id: GAP_ID,
+ proposedInstruction: "Always include the full PR URL.",
+ sessions: quotes.length,
+ quotes: quotes.map((q) => ({ text: q.text, source: q.source })),
+ },
+ ],
+ };
+}
+
+test("a reworded add of the same gap stays suppressed until more sessions arrive", () => {
+ const summary = summaryWithGap();
+ const first = gate({
+ edit: memoryEdit((t) => t.replace("## Rules\n\n", "## Rules\n\n- Always include the full PR URL.\n")),
+ annotation: { edits: [claim(["H1"], { kind: "add", title: "add url rule" })] },
+ context: { summary },
+ });
+ assert.deepEqual(first.violations, []);
+ assert.deepEqual(first.proposal.edits[0].gapIds, [GAP_ID]);
+ const rejections = recordRejection(first.proposal.edits[0], { version: 1, entries: {} }, undefined, "too-narrow");
+ assert.equal(Object.values(rejections.entries)[0].reason, "too-narrow");
+
+ const reworded = gate({
+ edit: memoryEdit((t) =>
+ t.replace("## Rules\n\n", "## Rules\n\n- Put the complete pull request URL in every mention.\n"),
+ ),
+ annotation: { edits: [claim(["H1"], { kind: "add", title: "different wording" })] },
+ context: { summary, rejections, isSuppressed: isSuppressedByRejection },
+ });
+ assert.equal(reworded.proposal.edits.length, 0, "same gap, same or fewer sessions, different bytes");
+ assert.deepEqual(reworded.violations, [], "a reason is not a violation");
+
+ const revived = gate({
+ edit: memoryEdit((t) =>
+ t.replace("## Rules\n\n", "## Rules\n\n- Put the complete pull request URL in every mention.\n"),
+ ),
+ annotation: {
+ edits: [claim(["H1"], { kind: "add", title: "different wording", evidence: [...QUOTE, THIRD_QUOTE] })],
+ },
+ context: { summary: summaryWithGap([...QUOTE, THIRD_QUOTE]), rejections, isSuppressed: isSuppressedByRejection },
+ });
+ assert.equal(revived.proposal.edits.length, 1, "strictly more sessions revive the identity");
+});
+
+test("extract is not suppressed by a rejected add that shares a gap id", () => {
+ const summary = summaryWithGap();
+ const added = gate({
+ edit: memoryEdit((t) => t.replace("## Rules\n\n", "## Rules\n\n- Always include the full PR URL.\n")),
+ annotation: { edits: [claim(["H1"], { kind: "add", title: "add url rule" })] },
+ context: { summary },
+ });
+ const rejections = recordRejection(added.proposal.edits[0], { version: 1, entries: {} });
+
+ const extracted = "- Use Node 18 via nvm before running any script.";
+ const extract = gate({
+ files: { ".agents/skills/setup-a/SKILL.md": skillFile("setup", "- Keep the existing setup step.\n") },
+ edit: (root) => {
+ writeIn(root, "AGENTS.md", (text) => text.replace(extracted, "- See the setup skill."));
+ writeIn(root, ".agents/skills/setup-a/SKILL.md", (text) => `${text}${extracted}\n`);
+ },
+ annotation: { edits: [claim(["H1", "H2"], { kind: "extract", title: "extract setup" })] },
+ context: { summary, rejections, isSuppressed: isSuppressedByRejection },
+ });
+ assert.deepEqual(extract.violations, [], extract.violations.join("\n"));
+ assert.equal(extract.proposal.edits.length, 1, "extract stays hunk-key only");
+ assert.deepEqual(extract.proposal.edits[0].gapIds, [GAP_ID]);
+});
+
+test("a rewrite of overlapping instruction units stays suppressed at equal session count", () => {
+ const first = gate({
+ edit: memoryEdit((t) => t.replace("include its URL.", "include its full URL.")),
+ annotation: { edits: [claim(["H1"], { kind: "rewrite", title: "expand url" })] },
+ });
+ assert.deepEqual(first.proposal.edits[0].instructionIds, [
+ unitHash("- Whenever a PR is mentioned, include its URL."),
+ ]);
+ const rejections = recordRejection(first.proposal.edits[0], { version: 1, entries: {} });
+
+ const reworded = gate({
+ edit: memoryEdit((t) => t.replace("include its URL.", "include the complete pull request URL.")),
+ annotation: { edits: [claim(["H1"], { kind: "rewrite", title: "expand url again" })] },
+ context: { rejections, isSuppressed: isSuppressedByRejection },
+ });
+ assert.equal(reworded.proposal.edits.length, 0);
+});
+
+test("a unit added above a rejected rewrite neither shifts suppression onto its neighbour nor loses the original", () => {
+ const first = gate({
+ edit: memoryEdit((t) => t.replace("include its URL.", "include its full URL.")),
+ annotation: { edits: [claim(["H1"], { kind: "rewrite", title: "expand url" })] },
+ });
+ const rejections = recordRejection(first.proposal.edits[0], { version: 1, entries: {} });
+ const shifted = MEMORY_TEXT.replace("## Rules\n\n", "## Rules\n\n- Never hand-edit CHANGELOG.md.\n");
+
+ const neighbour = gate({
+ text: shifted,
+ edit: memoryEdit((t) =>
+ t.replace("Never hand-edit CHANGELOG.md.", "Never hand-edit CHANGELOG.md or the manifest."),
+ ),
+ annotation: { edits: [claim(["H1"], { kind: "rewrite", title: "widen changelog rule" })] },
+ context: { rejections, isSuppressed: isSuppressedByRejection },
+ });
+ assert.equal(neighbour.proposal.edits.length, 1, "a different instruction now in the same position");
+
+ const original = gate({
+ text: shifted,
+ edit: memoryEdit((t) => t.replace("include its URL.", "include the complete pull request URL.")),
+ annotation: { edits: [claim(["H1"], { kind: "rewrite", title: "expand url again" })] },
+ context: { rejections, isSuppressed: isSuppressedByRejection },
+ });
+ assert.equal(original.proposal.edits.length, 0, "the rejected instruction moved down one position");
+});
+
+test("annotate instruction names the hunks do not touch are not stored and do not suppress", () => {
+ const first = gate({
+ edit: memoryEdit((t) => t.replace("Prefer small commits.", "Prefer tiny commits.")),
+ annotation: {
+ edits: [claim(["H1"], { kind: "rewrite", title: "tighten commits", instructions: ["AG-001", "AG-002"] })],
+ },
+ });
+ assert.deepEqual(first.proposal.edits[0].instructionIds, [unitHash("- Prefer small commits.")]);
+ const rejections = recordRejection(first.proposal.edits[0], { version: 1, entries: {} });
+ assert.deepEqual(Object.values(rejections.entries)[0].instructionIds, [unitHash("- Prefer small commits.")]);
+
+ const other = gate({
+ edit: memoryEdit((t) => t.replace("include its URL.", "include its full URL.")),
+ annotation: { edits: [claim(["H1"], { kind: "rewrite", title: "expand url", instructions: ["AG-001"] })] },
+ context: { rejections, isSuppressed: isSuppressedByRejection },
+ });
+ assert.equal(other.proposal.edits.length, 1, "padded annotate names must not widen suppression");
+});
+
test("projectWithDecisions tracks the budget for the subset the human accepted", () => {
const { proposal } = gate({
edit: memoryEdit((t) =>
@@ -1719,6 +1869,35 @@ test("applying decisions writes accepted edits, skips rejected ones, and remembe
assert.equal(Object.keys(remembered.entries).length, 1);
});
+test("a successful reject-only apply stores measured gap and instruction identities", () => {
+ const summary = summaryWithGap();
+ const { proposal, repo, state } = gate({
+ edit: memoryEdit((t) => t.replace("## Rules\n\n", "## Rules\n\n- Always include the full PR URL.\n")),
+ annotation: { edits: [claim(["H1"], { kind: "add", title: "add url rule" })] },
+ context: { summary },
+ });
+ assert.deepEqual(proposal.edits[0].gapIds, [GAP_ID]);
+
+ proposal.provenance = { source: { kind: "external", sourceId: "synthetic-rejection-source" } };
+
+ const results = applyDecisions({
+ proposal,
+ decisions: { e1: "rejected" },
+ repo,
+ state,
+ config: { budgetTokens: 5000 },
+ rejectReasons: { e1: "already-covered" },
+ });
+
+ assert.equal(results.rejectionsRecorded, true);
+ assert.equal(results.written.length, 0);
+ const entry = Object.values(state.readRejections().entries)[0];
+ assert.deepEqual(entry.gapIds, [GAP_ID]);
+ assert.equal(entry.reason, "already-covered");
+ assert.deepEqual(entry.provenance, proposal.provenance);
+ assert.equal(fs.readFileSync(path.join(repo.root, "AGENTS.md"), "utf8"), MEMORY_TEXT);
+});
+
test("apply refuses an accepted subset that exceeds the memory cap before writing any file", () => {
const skill = "---\nname: db\ndescription: old trigger\n---\n\nbody\n";
// The cap covers the always-loaded surface: the memory file plus the skill's
diff --git a/test/run-context.test.js b/test/run-context.test.js
index 279a4130..e2ccfde2 100644
--- a/test/run-context.test.js
+++ b/test/run-context.test.js
@@ -5,6 +5,7 @@ import os from "node:os";
import path from "node:path";
import { spawnSync } from "node:child_process";
import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
import { checkProposalRunContext, checkRunContext, inputInventory } from "../src/run-context.js";
import { State } from "../src/state.js";
@@ -78,6 +79,73 @@ test("snapshot, selected corpus, memory, and skill bytes remain pinned", () => {
assert.throws(() => checkRunContext(ctx, corpus), /inputMemoryDigest/);
});
+test("named nested memory bytes remain pinned through propose and apply", () => {
+ const { ctx, repoRoot } = fixture("nested-pin", { restricted: true });
+ const nestedPath = "apps/api/AGENTS.md";
+ ctx.config.nestedMemoryFiles = [nestedPath];
+ fs.mkdirSync(path.join(repoRoot, "apps/api"), { recursive: true });
+ fs.writeFileSync(path.join(repoRoot, nestedPath), "# API rules\n\n- Check contracts.\n");
+ const pinned = checkRunContext(ctx, corpus, { start: true });
+ const proposal = { provenance: { source: { kind: "native" }, runContext: pinned } };
+ checkProposalRunContext(ctx, proposal);
+ fs.appendFileSync(path.join(repoRoot, nestedPath), "- Check timeouts.\n");
+ assert.throws(() => checkRunContext(ctx, corpus), /inputMemoryDigest/);
+ assert.throws(() => checkProposalRunContext(ctx, proposal), /proposal is stale/);
+});
+
+function nestedPointerFixture(name, restricted) {
+ const workspace = fixture(name, { restricted });
+ workspace.ctx.config.nestedMemoryFiles = ["apps/api/AGENTS.md"];
+ const dir = path.join(workspace.repoRoot, "apps/api");
+ fs.mkdirSync(dir, { recursive: true });
+ fs.writeFileSync(path.join(dir, "AGENTS.md"), "# API rules\n\n- Check contracts.\n");
+ const pointer = path.join(dir, "CLAUDE.md");
+ fs.writeFileSync(pointer, "@AGENTS.md\n");
+ return { ...workspace, pointer };
+}
+
+test("nested pointer inventory records exact bytes and resolved targets", () => {
+ const { ctx, pointer, repoRoot } = nestedPointerFixture("nested-pointer-inventory", true);
+ const bytes = Buffer.from("\r\n\r\n@./AGENTS.md\r\n");
+ fs.writeFileSync(pointer, bytes);
+ const inventory = inputInventory(ctx);
+ const entry = inventory.entries.find((item) => item.path === "apps/api/CLAUDE.md");
+ assert.ok(entry);
+ assert.equal(entry.target, fs.realpathSync(pointer));
+ assert.equal(entry.pointerTarget, path.join(repoRoot, "apps/api/AGENTS.md"));
+ assert.equal(entry.bytes, bytes.length);
+ assert.equal(entry.digest, `sha256:${createHash("sha256").update(bytes).digest("hex")}`);
+});
+
+for (const restricted of [false, true]) {
+ for (const mutation of ["delete", "retarget", "bytes", "symlink"]) {
+ test(`frozen nested pointers refuse ${mutation} in ${restricted ? "restricted" : "native"} mode`, () => {
+ const { ctx, pointer, repoRoot } = nestedPointerFixture(`nested-pointer-${restricted}-${mutation}`, restricted);
+ if (mutation === "symlink") {
+ for (const name of ["first-pointer.md", "second-pointer.md"]) {
+ fs.writeFileSync(path.join(repoRoot, "apps/api", name), "@AGENTS.md\n");
+ }
+ fs.rmSync(pointer);
+ fs.symlinkSync("first-pointer.md", pointer);
+ }
+ const pinned = checkRunContext(ctx, corpus, { start: true });
+ const proposal = { provenance: { source: { kind: "native" }, runContext: pinned } };
+ assert.doesNotThrow(() => checkRunContext(ctx, corpus));
+ assert.doesNotThrow(() => checkProposalRunContext(ctx, proposal));
+ if (mutation === "delete") fs.rmSync(pointer);
+ else if (mutation === "retarget") fs.writeFileSync(pointer, "@../../AGENTS.md\n");
+ else if (mutation === "bytes") fs.writeFileSync(pointer, "\n@AGENTS.md\n");
+ else {
+ fs.rmSync(pointer);
+ fs.symlinkSync("second-pointer.md", pointer);
+ }
+ assert.notEqual(inputInventory(ctx).digest, pinned.inputMemoryDigest);
+ assert.throws(() => checkRunContext(ctx, corpus), /inputMemoryDigest/);
+ assert.throws(() => checkProposalRunContext(ctx, proposal), /proposal is stale/);
+ });
+ }
+}
+
test("inventory records exact bytes and pointer target; restricted mode refuses an unapproved pointer", () => {
const { ctx, repoRoot } = fixture("pointer", { restricted: true });
const inventory = inputInventory(ctx);
diff --git a/test/scope.test.js b/test/scope.test.js
index a06578fa..1ff7e7f0 100644
--- a/test/scope.test.js
+++ b/test/scope.test.js
@@ -139,6 +139,23 @@ test("user --strict drops sessions with only a dead unrecognisable cwd", () => {
assert.ok(kept.project);
});
+test(
+ "a Windows cwd keeps its recorded spelling as the user-scope key, wherever backpass runs",
+ { skip: process.platform === "win32" && "Windows spells this path natively" },
+ () => {
+ const previous = process.cwd();
+ process.chdir(initRepo("elsewhere"));
+ try {
+ const kept = associateUser({ cwd: "C:\\work\\demo" });
+ assert.equal(kept.tier, 3);
+ assert.equal(kept.project, "C:\\work\\demo", "never resolved under the process cwd");
+ assert.equal(associateUser({ cwd: "C:\\work\\demo" }, { strict: true }), null);
+ } finally {
+ process.chdir(previous);
+ }
+ },
+);
+
test("passesProjectFilter includes and excludes by project key or cwd", () => {
const transcript = { project: "/repos/alpha", cwd: "/repos/alpha" };
assert.equal(passesProjectFilter(transcript, { discovery: {} }), true);
diff --git a/test/self-session.test.js b/test/self-session.test.js
index 6b0148b5..480695ee 100644
--- a/test/self-session.test.js
+++ b/test/self-session.test.js
@@ -3,13 +3,16 @@ import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { spawnSync } from "node:child_process";
/**
* backpass's own analysis/synthesis calls are filed by each harness under this repo's
* cwd, so discovery would pick them up as tier-1 sessions. These tests drive real
- * discovery over a fake HOME holding the three acpx-backed stores (pi, codex, claude),
- * each with one genuine session and one session whose first user message is an actual
- * prompt backpass rendered, and assert only the genuine ones come back.
+ * discovery over a fake HOME holding the acpx-backed stores (pi, codex, claude, and
+ * opencode's SQLite store), each with one genuine session and one session whose first
+ * user message is an actual prompt backpass rendered, and assert only the genuine ones
+ * come back.
*/
const fakeHome = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-self-home-"));
process.env.HOME = fakeHome;
@@ -134,17 +137,83 @@ const piDir = path.join(fakeHome, ".pi", "agent", "sessions", `-${realRoot.repla
const codexDir = path.join(fakeHome, ".codex", "sessions", "2026", "08", "20");
const claudeDir = path.join(fakeHome, ".claude", "projects", realRoot.replace(/[/.]/g, "-"));
+/**
+ * opencode keeps every session in one SQLite store. The self session has the shape an
+ * `acpx opencode` call really records: a user message whose first text part is the
+ * rendered prompt. The store is small enough that its file head holds every session's
+ * text, so a genuine session must survive a self session sharing its database.
+ */
+function writeOpencodeStore(sessions) {
+ const store = path.join(fakeHome, ".local", "share", "opencode");
+ fs.mkdirSync(store, { recursive: true });
+ const db = new DatabaseSync(path.join(store, "opencode.db"));
+ db.exec(`
+ CREATE TABLE project (id TEXT PRIMARY KEY, worktree TEXT NOT NULL);
+ CREATE TABLE session (
+ id TEXT PRIMARY KEY, project_id TEXT NOT NULL, parent_id TEXT, directory TEXT NOT NULL,
+ title TEXT NOT NULL, time_created INTEGER NOT NULL, time_updated INTEGER NOT NULL
+ );
+ CREATE TABLE message (id TEXT PRIMARY KEY, session_id TEXT NOT NULL, time_created INTEGER NOT NULL, data TEXT NOT NULL);
+ CREATE TABLE part (
+ id TEXT PRIMARY KEY, message_id TEXT NOT NULL, session_id TEXT NOT NULL,
+ time_created INTEGER NOT NULL, data TEXT NOT NULL
+ );
+ `);
+ db.prepare("INSERT INTO project (id, worktree) VALUES (?, ?)").run("p1", realRoot);
+ writeOpencodeSessions(db, sessions);
+ db.close();
+}
+
+function writeOpencodeSessions(db, sessions) {
+ for (const { id, firstUserText, parentId = null, at = Date.parse("2026-08-20T10:00:00.000Z") } of sessions) {
+ db.prepare(
+ "INSERT INTO session (id, project_id, parent_id, directory, title, time_created, time_updated) VALUES (?, 'p1', ?, ?, ?, ?, ?)",
+ ).run(id, parentId, realRoot, id, at, at);
+ // An agent probe (`acpx opencode sessions new`) leaves a session with no messages at all.
+ if (firstUserText === null) continue;
+ const turns = [
+ { role: "user", parts: [{ type: "text", text: firstUserText }] },
+ { role: "assistant", parts: [{ type: "step-start" }, { type: "text", text: "{}" }] },
+ ];
+ turns.forEach((turn, index) => {
+ const messageId = `msg_${id}_${index}`;
+ db.prepare("INSERT INTO message (id, session_id, time_created, data) VALUES (?, ?, ?, ?)").run(
+ messageId,
+ id,
+ at + index,
+ JSON.stringify({ role: turn.role, time: { created: at + index } }),
+ );
+ turn.parts.forEach((part, partIndex) => {
+ db.prepare("INSERT INTO part (id, message_id, session_id, time_created, data) VALUES (?, ?, ?, ?, ?)").run(
+ `prt_${id}_${index}_${partIndex}`,
+ messageId,
+ id,
+ at + index,
+ JSON.stringify(part),
+ );
+ });
+ });
+ }
+}
+
writePiSession(piDir, "pi-real", "Add the changelog entry.");
writePiSession(piDir, "pi-self", analysisPrompt);
writeCodexSession(codexDir, "codex-real", "Fix the flaky test.");
writeCodexSession(codexDir, "codex-self", synthesisPrompt);
writeClaudeSession(claudeDir, "claude-real", "Open a PR for the parser fix.");
writeClaudeSession(claudeDir, "claude-self", analysisPrompt);
+writeOpencodeStore([
+ { id: "ses_opencode_real", firstUserText: "Why does the release job skip the tag?" },
+ { id: "ses_opencode_self", firstUserText: synthesisPrompt },
+ { id: "ses_opencode_probe", firstUserText: null },
+]);
// A genuine session that merely *talks about* the sentinel is not a self-session.
writePiSession(piDir, "pi-mentions", `Why does backpass prepend ${SELF_SESSION_SENTINEL} to its prompts?`);
function configFor() {
- const config = loadConfig(realRoot, { discovery: { harnesses: ["pi", "codex", "claude"], since: "all" } });
+ const config = loadConfig(realRoot, {
+ discovery: { harnesses: ["pi", "codex", "claude", "opencode"], since: "all" },
+ });
const cache = { version: 1, entries: {} };
config.state = { readScanCache: () => cache, writeScanCache: () => {} };
return config;
@@ -159,13 +228,16 @@ test("discovery excludes backpass-originated sessions from every acpx-backed har
const { transcripts, perHarness } = await discoverTranscripts({ repo, config: configFor() });
const ids = transcripts.map((t) => t.nativeId).sort();
- assert.deepEqual(ids, ["claude-real", "codex-real", "pi-mentions", "pi-real"]);
+ assert.deepEqual(ids, ["claude-real", "codex-real", "pi-mentions", "pi-real", "ses_opencode_real"]);
assert.equal(perHarness.pi.self, 1);
assert.equal(perHarness.codex.self, 1);
assert.equal(perHarness.claude.self, 1);
+ assert.equal(perHarness.opencode.self, 1);
+ assert.equal(perHarness.opencode.scanned, 2, "a probe's empty session is not listed at all");
assert.equal(perHarness.pi.matched, 2);
assert.equal(perHarness.codex.matched, 1);
assert.equal(perHarness.claude.matched, 1);
+ assert.equal(perHarness.opencode.matched, 1);
for (const t of transcripts) {
assert.equal(t.association.tier, 1);
assert.equal(t.identity, transcriptIdentity(t));
@@ -182,11 +254,261 @@ test("the exclusion survives the scan cache (a cached descriptor is still checke
"codex-real",
"pi-mentions",
"pi-real",
+ "ses_opencode_real",
]);
assert.equal(second.perHarness.pi.cached, 3);
assert.equal(second.perHarness.pi.self, 1);
});
+test("OpenCode attachment openings followed by prompt quotes survive CLI scans and shipped probes", async (t) => {
+ const { buildProbeProgram } = await import("../src/discovery/remote/bundle.js");
+ const db = new DatabaseSync(path.join(fakeHome, ".local", "share", "opencode", "opencode.db"));
+ const id = "ses_opencode_attachment";
+ const reply = "The screenshot shows a missing release tag. Create the tag before publishing.";
+ try {
+ writeOpencodeSessions(db, [
+ { id, firstUserText: "placeholder" },
+ { id: `${id}_child`, parentId: id, firstUserText: "Inspect the release" },
+ ]);
+ const update = db.prepare("UPDATE part SET data = ? WHERE id = ?");
+ update.run(
+ JSON.stringify({
+ type: "file",
+ mime: "image/png",
+ filename: "failure.png",
+ url: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII=",
+ }),
+ `prt_${id}_0_0`,
+ );
+ update.run(JSON.stringify({ type: "text", text: reply }), `prt_${id}_1_1`);
+ // A later user turn quotes a backpass prompt; it is not the conversation's opening.
+ const quotedPrompt = `${synthesisPrompt}\nWhy was this prompt sent?`;
+ const at = Date.parse("2026-08-20T10:00:02.000Z");
+ db.prepare("INSERT INTO message (id, session_id, time_created, data) VALUES (?, ?, ?, ?)").run(
+ `msg_${id}_2`,
+ id,
+ at,
+ JSON.stringify({ role: "user" }),
+ );
+ db.prepare("INSERT INTO part (id, message_id, session_id, time_created, data) VALUES (?, ?, ?, ?, ?)").run(
+ `prt_${id}_2_0`,
+ `msg_${id}_2`,
+ id,
+ at,
+ JSON.stringify({ type: "text", text: quotedPrompt }),
+ );
+ const initialized = spawnSync("git", ["init", "-q", realRoot], { encoding: "utf8" });
+ assert.equal(initialized.status, 0, initialized.stderr);
+
+ await t.test("CLI retains the conversation but not the empty probe or self session", () => {
+ for (let scan = 0; scan < 2; scan++) {
+ const result = spawnSync(
+ process.execPath,
+ [path.resolve("bin/backpass.js"), "scan", "--harness", "opencode", "--since", "all", "--strict", "--json"],
+ { cwd: realRoot, encoding: "utf8", timeout: 30000 },
+ );
+ assert.equal(result.status, 0, result.stderr);
+ const output = JSON.parse(result.stdout);
+ assert.deepEqual(output.transcripts.map((entry) => entry.nativeId).sort(), [
+ id,
+ `${id}_child`,
+ "ses_opencode_real",
+ ]);
+ assert.equal(output.perHarness.opencode.scanned, 4);
+ assert.equal(output.perHarness.opencode.self, 1);
+ }
+ });
+
+ await t.test("shipped probe retains the conversation but not the empty probe or self session", () => {
+ const result = spawnSync(process.execPath, ["-"], {
+ cwd: realRoot,
+ encoding: "utf8",
+ timeout: 30000,
+ input: buildProbeProgram({ op: "discover", harnesses: ["opencode"], cutoffMs: null }),
+ });
+ assert.equal(result.status, 0, result.stderr);
+ const output = JSON.parse(result.stdout);
+ assert.deepEqual(output.transcripts.map((entry) => entry.id).sort(), [id, `${id}_child`, "ses_opencode_real"]);
+ assert.equal(output.harnesses.opencode.scanned, 4);
+ assert.equal(output.harnesses.opencode.self, 1);
+ });
+
+ const { read } = await import("../src/discovery/adapters/opencode.js");
+ assert.deepEqual((await read({ id })).events, [
+ { kind: "message", role: "user", text: "[Attachment-only user message]" },
+ { kind: "message", role: "assistant", text: reply },
+ { kind: "message", role: "user", text: quotedPrompt },
+ ]);
+ } finally {
+ for (const sessionId of [id, `${id}_child`]) {
+ db.prepare("DELETE FROM part WHERE session_id = ?").run(sessionId);
+ db.prepare("DELETE FROM message WHERE session_id = ?").run(sessionId);
+ db.prepare("DELETE FROM session WHERE id = ?").run(sessionId);
+ }
+ db.close();
+ }
+});
+
+test("malformed OpenCode rows do not suppress valid sessions locally or remotely", async (t) => {
+ const { discover } = await import("../src/discovery/remote/probe.js");
+ const db = new DatabaseSync(path.join(fakeHome, ".local", "share", "opencode", "opencode.db"));
+ const at = Date.parse("2026-08-20T09:00:00.000Z");
+ try {
+ db.prepare(
+ "INSERT INTO session (id, project_id, directory, title, time_created, time_updated) VALUES (?, ?, ?, ?, ?, ?)",
+ ).run("ses_other", "other", path.join(fakeHome, "other-repo"), "Other repository", at, at);
+ for (const column of ["message", "part"]) {
+ for (const sessionId of ["ses_opencode_real", "ses_opencode_self", "ses_other"]) {
+ await t.test(`${column} corruption in ${sessionId}`, async () => {
+ // Recorded but unreadable messages are not unused probes. Remote discovery
+ // lists them; local association still excludes the unrelated repository.
+ const remoteIds = sessionId === "ses_other" ? ["ses_opencode_real", "ses_other"] : ["ses_opencode_real"];
+ const localIds = ["ses_opencode_real"];
+ // A valid first user message with unreadable content cannot be replaced by
+ // a later sentinel-bearing message when deciding whether the session is self.
+ const selfCount = column === "part" && sessionId === "ses_opencode_self" ? 0 : 1;
+ if (!selfCount) {
+ remoteIds.push("ses_opencode_self");
+ localIds.push("ses_opencode_self");
+ }
+ db.prepare("INSERT INTO message (id, session_id, time_created, data) VALUES (?, ?, ?, ?)").run(
+ "msg_corrupt",
+ sessionId,
+ at,
+ column === "message" ? "{broken" : JSON.stringify({ role: "user" }),
+ );
+ db.prepare("INSERT INTO part (id, message_id, session_id, time_created, data) VALUES (?, ?, ?, ?, ?)").run(
+ "prt_corrupt",
+ "msg_corrupt",
+ sessionId,
+ at,
+ column === "part" ? "{broken" : JSON.stringify({ type: "text", text: "Unreadable message" }),
+ );
+ try {
+ const config = configFor();
+ for (let scan = 0; scan < 2; scan++) {
+ const local = await discoverTranscripts({ repo, config, harnesses: ["opencode"] });
+ assert.equal(local.perHarness.opencode.error, null);
+ assert.deepEqual(local.transcripts.map((entry) => entry.nativeId).sort(), localIds);
+ assert.equal(local.perHarness.opencode.self, selfCount);
+ assert.equal(local.perHarness.opencode.scanned, remoteIds.length + selfCount);
+ }
+ const remote = await discover({ harnesses: ["opencode"], cutoffMs: at });
+ assert.equal(remote.harnesses.opencode.error, null);
+ assert.deepEqual(remote.transcripts.map((entry) => entry.id).sort(), remoteIds);
+ assert.equal(remote.harnesses.opencode.self, selfCount);
+ assert.equal(remote.harnesses.opencode.scanned, remoteIds.length + selfCount);
+ } finally {
+ db.prepare("DELETE FROM part WHERE id = ?").run("prt_corrupt");
+ db.prepare("DELETE FROM message WHERE id = ?").run("msg_corrupt");
+ }
+ });
+ }
+ }
+ } finally {
+ db.prepare("DELETE FROM session WHERE id = ?").run("ses_other");
+ db.close();
+ }
+});
+
+test("OpenCode self ancestry excludes descendants locally and remotely regardless of cutoff", async () => {
+ const { discover } = await import("../src/discovery/remote/probe.js");
+ const db = new DatabaseSync(path.join(fakeHome, ".local", "share", "opencode", "opencode.db"));
+ const old = Date.parse("2026-08-19T10:00:00.000Z");
+ const now = Date.parse("2026-08-21T00:00:00.000Z");
+ const sessions = [
+ { id: "self_grandchild", parentId: "self_child", firstUserText: "Inspect the parser" },
+ { id: "self_child", parentId: "self_old", firstUserText: "Delegate an exploration" },
+ { id: "self_via_empty", parentId: "self_empty", firstUserText: "Read the tests" },
+ { id: "self_empty", parentId: "self_old", firstUserText: null },
+ { id: "self_old", firstUserText: analysisPrompt, at: old },
+ { id: "real_child", parentId: "real_old", firstUserText: "Check the release" },
+ { id: "real_grandchild", parentId: "real_child", firstUserText: "Check the tag" },
+ { id: "real_old", firstUserText: "Fix the release", at: old },
+ { id: "self_under_real", parentId: "real_old", firstUserText: synthesisPrompt },
+ { id: "self_nested", parentId: "self_under_real", firstUserText: "Read the configuration" },
+ { id: "orphan", parentId: "missing", firstUserText: "Continue the task" },
+ { id: "cycle_a", parentId: "cycle_b", firstUserText: "Check A" },
+ { id: "cycle_b", parentId: "cycle_a", firstUserText: "Check B" },
+ ];
+ try {
+ writeOpencodeSessions(db, sessions);
+ for (const since of ["all", "1d"]) {
+ const expected = ["cycle_a", "cycle_b", "orphan", "real_child", "real_grandchild", "ses_opencode_real"];
+ if (since === "all") expected.push("real_old");
+ expected.sort();
+ const config = configFor();
+ config.discovery.since = since;
+ for (let scan = 0; scan < 2; scan++) {
+ const local = await discoverTranscripts({ repo, config, now, harnesses: ["opencode"] });
+ assert.equal(local.perHarness.opencode.error, null);
+ assert.deepEqual(local.transcripts.map((entry) => entry.nativeId).sort(), expected);
+ assert.equal(local.perHarness.opencode.self, since === "all" ? 7 : 6);
+ }
+ const remote = await discover({
+ harnesses: ["opencode"],
+ cutoffMs: since === "all" ? null : now - 24 * 60 * 60 * 1000,
+ });
+ assert.equal(remote.harnesses.opencode.error, null);
+ assert.deepEqual(remote.transcripts.map((entry) => entry.id).sort(), expected);
+ assert.equal(remote.harnesses.opencode.self, since === "all" ? 7 : 6);
+ }
+ } finally {
+ for (const { id } of sessions) {
+ db.prepare("DELETE FROM part WHERE session_id = ?").run(id);
+ db.prepare("DELETE FROM message WHERE session_id = ?").run(id);
+ db.prepare("DELETE FROM session WHERE id = ?").run(id);
+ }
+ db.close();
+ }
+});
+
+test("OpenCode discovery does not reread shared ancestors for each child", async (t) => {
+ const { discover } = await import("../src/discovery/adapters/opencode.js");
+ const db = new DatabaseSync(path.join(fakeHome, ".local", "share", "opencode", "opencode.db"));
+ const sessions = [
+ { id: "shared_real", parentId: "ses_opencode_real", firstUserText: "Explore the release" },
+ { id: "shared_self", parentId: "ses_opencode_self", firstUserText: "Explore the parser" },
+ ];
+ let reads = 0;
+ const prepare = DatabaseSync.prototype.prepare;
+ t.mock.method(DatabaseSync.prototype, "prepare", function (...args) {
+ const statement = prepare.apply(this, args);
+ const all = statement.all;
+ t.mock.method(statement, "all", function (...params) {
+ reads++;
+ return all.apply(this, params);
+ });
+ return statement;
+ });
+ try {
+ writeOpencodeSessions(db, sessions);
+ await discover({ cutoffMs: null });
+ const initialReads = reads;
+ const children = Array.from({ length: 32 }, (_, index) => ({
+ id: `shared_child_${index}`,
+ parentId: index % 2 ? "shared_self" : "shared_real",
+ firstUserText: "Inspect the tests",
+ }));
+ sessions.push(...children);
+ writeOpencodeSessions(db, children);
+ reads = 0;
+ const rows = await discover({ cutoffMs: null });
+ assert.equal(reads, initialReads, "adding siblings must not add ancestor database reads");
+ for (const child of children) {
+ assert.equal(rows.find((row) => row.id === child.id)?.self, child.parentId === "shared_self");
+ }
+ } finally {
+ for (const { id } of sessions) {
+ db.prepare("DELETE FROM part WHERE session_id = ?").run(id);
+ db.prepare("DELETE FROM message WHERE session_id = ?").run(id);
+ db.prepare("DELETE FROM session WHERE id = ?").run(id);
+ }
+ t.mock.restoreAll();
+ db.close();
+ }
+});
+
test("isSelfSession is fail-soft on a missing or directory path", () => {
assert.equal(isSelfSession({ path: path.join(fakeHome, "nope.jsonl") }), false);
assert.equal(isSelfSession({ path: fakeHome }), false);
diff --git a/test/state-mode.test.js b/test/state-mode.test.js
new file mode 100644
index 00000000..2fad934a
--- /dev/null
+++ b/test/state-mode.test.js
@@ -0,0 +1,89 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { State } from "../src/state.js";
+import { setLoggerSink } from "../src/logger.js";
+
+/**
+ * User-scope state is created 0700 and read back to prove it. Windows has no POSIX mode
+ * bits - chmod only toggles the read-only attribute and stat reports 0o666 - so the read-back
+ * can never match there (issue #115). These pin the win32 branch: skipped silently when the
+ * state dir resolves under the user's profile (where it inherits the profile's NTFS ACL), a
+ * warning when it resolves elsewhere (e.g. XDG_CONFIG_HOME redirected to a synced or network
+ * folder, so no ACL is inherited), and the read-back still enforced everywhere else.
+ */
+async function withPlatform(platform, fn) {
+ const original = Object.getOwnPropertyDescriptor(process, "platform");
+ Object.defineProperty(process, "platform", { value: platform, configurable: true });
+ try {
+ return await fn();
+ } finally {
+ Object.defineProperty(process, "platform", original);
+ }
+}
+
+/** A stat that reports the directory the way Windows does, whatever the host is. */
+function statAsWindows(t, stateDir) {
+ const realStat = fs.statSync;
+ t.mock.method(fs, "statSync", (p, ...rest) => {
+ const st = realStat(p, ...rest);
+ if (path.resolve(String(p)) !== path.resolve(stateDir)) return st;
+ return Object.assign(Object.create(Object.getPrototypeOf(st)), st, { mode: 0o40666 });
+ });
+}
+
+function captureWarnings(t) {
+ const lines = [];
+ setLoggerSink((line) => lines.push(line));
+ t.after(() => setLoggerSink(null));
+ return lines;
+}
+
+test("user-scope state dir inside the user profile is accepted on win32 with no warning", async (t) => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-home-"));
+ t.mock.method(os, "homedir", () => home);
+ const stateDir = path.join(home, ".config", "backpass", "user");
+ statAsWindows(t, stateDir);
+ const warnings = captureWarnings(t);
+
+ const state = await withPlatform("win32", () =>
+ new State(os.tmpdir(), { stateDir, mode: 0o700, exclude: false }).ensure(),
+ );
+
+ assert.equal(fs.existsSync(state.evidenceDir), true, "ensure() went on to create the state layout");
+ assert.equal(fs.existsSync(state.applyDir), true);
+ assert.deepEqual(warnings, []);
+});
+
+test("user-scope state dir redirected outside the user profile is accepted on win32 with a warning", async (t) => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-home-"));
+ t.mock.method(os, "homedir", () => home);
+ const stateDir = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "backpass-redirected-")), "user");
+ statAsWindows(t, stateDir);
+ const warnings = captureWarnings(t);
+
+ const state = await withPlatform("win32", () =>
+ new State(os.tmpdir(), { stateDir, mode: 0o700, exclude: false }).ensure(),
+ );
+
+ assert.equal(fs.existsSync(state.evidenceDir), true, "ensure() went on to create the state layout");
+ assert.equal(fs.existsSync(state.applyDir), true);
+ assert.equal(warnings.length, 1);
+ assert.match(warnings[0], /outside your Windows user profile/);
+ assert.match(warnings[0], new RegExp(stateDir.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+});
+
+test("user-scope state dir that did not come out 0700 is still refused off win32", async (t) => {
+ const stateDir = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "backpass-mode-")), "user");
+ statAsWindows(t, stateDir);
+
+ await withPlatform("linux", () =>
+ assert.throws(
+ () => new State(os.tmpdir(), { stateDir, mode: 0o700, exclude: false }).ensure(),
+ /could not secure state directory .* as mode 700 \(got 666\)/,
+ ),
+ );
+});
diff --git a/test/synthesize.test.js b/test/synthesize.test.js
index d382e9d0..7807e2ae 100644
--- a/test/synthesize.test.js
+++ b/test/synthesize.test.js
@@ -72,7 +72,7 @@ fs.writeFileSync(statePath, JSON.stringify(state));
fs.chmodSync(fakeAcpx, 0o755);
process.env.BACKPASS_ACPX_BIN = fakeAcpx;
-const { synthesizeProposal, ANNOTATE_TURNS } = await import("../src/synthesize.js");
+const { synthesizeProposal, ANNOTATE_TURNS, renderRejections } = await import("../src/synthesize.js");
const { applyDecisions } = await import("../src/apply/writer.js");
const { loadConfig } = await import("../src/config.js");
const { parseMemoryUnits, readMemoryFile } = await import("../src/memory.js");
@@ -185,14 +185,15 @@ function setup(
: "AGENTS.md";
if (externalMemory) fs.writeFileSync(memoryPath, text);
const memoryFile = readMemoryFile(repo.root, memoryPath, { allowExternal: externalMemory });
- const run = () =>
+ const run = ({ memoryFile: selectedFile = memoryFile, config: selectedConfig = config, routing = null } = {}) =>
synthesizeProposal({
- memoryFile,
+ memoryFile: selectedFile,
summary,
- config,
+ config: selectedConfig,
repo,
transcripts: [{ harness: "claude" }],
scope,
+ routing,
});
const calls = () =>
fs
@@ -204,6 +205,46 @@ function setup(
return { repo, config, memoryFile, externalSkillsDir, run, calls };
}
+test("root and nested synthesis both refuse direct writes to the other memory file", async () => {
+ for (const pass of ["root", "nested"]) {
+ const { repo, config, run } = setup(
+ { edit: {}, annotations: [{ reply: { edits: [] } }] },
+ { overrides: { nestedMemoryFiles: ["apps/api/AGENTS.md"] } },
+ );
+ const nestedPath = "apps/api/AGENTS.md";
+ const nestedText = "# API memory\n";
+ const absoluteNested = path.join(repo.root, nestedPath);
+ fs.mkdirSync(path.dirname(absoluteNested), { recursive: true });
+ fs.writeFileSync(absoluteNested, nestedText);
+ const target = pass === "root" ? absoluteNested : path.join(repo.root, "AGENTS.md");
+ fs.writeFileSync(
+ path.join(repo.root, "fake-script.json"),
+ JSON.stringify({ edit: { [target]: "# Direct write\n" }, annotations: [{ reply: { edits: [] } }] }),
+ );
+ const nestedConfig = {
+ ...config,
+ memoryFiles: [nestedPath],
+ target: { kind: "memory", path: nestedPath, nested: true },
+ };
+ await assert.rejects(
+ () =>
+ pass === "root"
+ ? run()
+ : run({
+ memoryFile: readMemoryFile(repo.root, nestedPath),
+ config: nestedConfig,
+ routing: { rootPath: "AGENTS.md" },
+ }),
+ (err) =>
+ err instanceof UserError &&
+ err.message.includes(
+ `synthesis changed ${pass === "root" ? nestedPath : "AGENTS.md"} in the repository directly`,
+ ),
+ );
+ assert.equal(fs.readFileSync(target, "utf8"), "# Direct write\n");
+ }
+});
+
test("synthesis edits the staging copy natively; measured hunks anchor to the raw file and nothing touches the repo until apply", async () => {
const { repo, config, run, calls } = setup({
edit: {
@@ -826,3 +867,24 @@ test("a skill backpass withheld from staging is not fingerprinted, so a third pa
const { violations } = await withheld.run();
assert.deepEqual(violations, []);
});
+
+test("the synthesis prompt lists stored rejection identities and reasons", () => {
+ const text = renderRejections({
+ version: 1,
+ entries: {
+ abc: {
+ kind: "add",
+ file: "AGENTS.md",
+ title: "pin node",
+ transcripts: 2,
+ rejectedAt: "2026-09-27T00:00:00.000Z",
+ gapIds: ["cafef00ddeadbeef"],
+ reason: "already-covered",
+ },
+ },
+ });
+ assert.match(text, /\[add\] pin node/);
+ assert.match(text, /cafef00ddeadbeef/);
+ assert.match(text, /already-covered/);
+ assert.doesNotMatch(text, /\(none\)/);
+});
diff --git a/test/tui-render.test.js b/test/tui-render.test.js
index ecdf52b1..b88bba4a 100644
--- a/test/tui-render.test.js
+++ b/test/tui-render.test.js
@@ -231,7 +231,7 @@ test("discovery frame: header gauge, rail, per-harness rows, plain-language labe
assert.ok(text.includes("git remote match"));
assert.ok(text.includes("8,912/10,317 sessions"));
assert.ok(text.includes("9 so far"));
- assert.ok(text.includes("1 sqlite query"));
+ assert.ok(text.includes("sqlite store"));
assert.ok(text.includes("store unreadable · harness skipped, run continues"));
assert.ok(text.includes("fail-soft"));
assert.ok(text.includes("new = not seen by a previous scan"));
@@ -241,6 +241,23 @@ test("discovery frame: header gauge, rail, per-harness rows, plain-language labe
assert.ok(!/\bmatched\b/.test(text));
});
+test("SQLite discovery rows describe the store without claiming a query count", () => {
+ for (const harness of ["opencode", "hermes"]) {
+ const state = stateAfter([
+ ["discover:start", { harnesses: [harness] }],
+ ["discover:harness:start", { harness }],
+ ["discover:harness:done", { harness, scanned: 4, matched: 4 }],
+ ]);
+ for (const width of [110, 80, 62]) {
+ const row = render(state, { width }).find((line) => line.includes(harness));
+ assert.ok(row, `${harness} row is visible at width ${width}`);
+ assert.match(row, /sqlite store/);
+ assert.doesNotMatch(row, /sqlite query/);
+ assert.match(row, /4 this repo/);
+ }
+ }
+});
+
test("every line fits the terminal and the header box is intact", () => {
for (const width of [100, 80, 62]) {
const lines = render(stateAfter(DISCOVERY_SCRIPT), { width });