Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

33.9 KB
Raw Blame
/**
 * Session notes: one note per session, written by `trail note` into
 * `~/.trail/repos/<repo>/notes/`, read back by `ask` for the next session on
 * the same thing. Never in the repo.
 */
import { test } from "node:test";
import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { join, sep } from "node:path";
import {
  costLabel,
  findNotes,
  formatNoteHits,
  listNotes,
  parseNote,
  renderNote,
  sectionLead,
  shortDate,
  slug,
  tokensLabel,
  writeNote,
  type Note,
} from "../src/notes/notes.js";
import { learningId } from "../src/notes/learning-fields.js";
import { aboutTerms, costFromTranscript, FALLBACK_ACTIVE_MS } from "../src/notes/session-cost.js";
import { ensureRepoHome, repoPlace } from "../src/notes/home.js";
import { homeEnv, tmpRepo } from "./helpers.js";

// Everything this file writes in-process goes to a scratch ~/.trail.
const TRAIL_HOME = mkdtempSync(join(tmpdir(), "notes-trail-home-"));
process.env.TRAIL_HOME = TRAIL_HOME;

const BODY = [
  "## Decided",
  "Rotate each box in `NormalizeBox` by its own page's `/Rotate` before scaling.",
  "",
  "## Tried and ruled out",
  "- Rotating the image before OCR. Works, but doubles latency on long files.",
  "",
  "## Watch out",
  "`/Rotate` can be 270 on a single page inside an otherwise upright file.",
].join("\n");

function note(over: Partial<Note> = {}): Note {
  return {
    path: join(homedir(), ".trail", "repos", "github.com", "acme", "extract", "notes", "2026-10-07-bbox-priya.md"),
    title: "Bbox coordinates are off on rotated PDFs",
    author: "Priya",
    date: "2026-10-07",
    branch: "fix/bbox-rotation",
    cost: { minutes: 12, tokens: 9600 },
    touches: ["internal/ocr/bbox.go#NormalizeBox", "internal/ocr/client.go"],
    body: BODY,
    ...over,
  };
}

// --- the file format ---

test("a note round-trips through its file, frontmatter and all", () => {
  const n = note();
  const text = renderNote(n);
  assert.match(text, /^---\ntitle: Bbox coordinates are off on rotated PDFs\nauthor: Priya\ndate: 2026-10-07\nbranch: fix\/bbox-rotation\ncost: \{ minutes: 12, tokens: 9600 \}\ntouches:\n  - "internal\/ocr\/bbox.go#NormalizeBox"\n  - internal\/ocr\/client.go\n---\n\n## Decided/);
  // Written without the newer fields, it reads back with their defaults.
  assert.deepEqual(parseNote(text, n.path), { ...n, id: learningId("2026-10-07-bbox-priya.md"), status: "active" });
});

test("titles that YAML would misread are quoted, and still come back intact", () => {
  const n = note({ title: "Retries: why #3 fails", touches: [], cost: undefined, branch: undefined });
  assert.equal(parseNote(renderNote(n), n.path)?.title, "Retries: why #3 fails");
});

test("a file without a title isn't a note", () => {
  assert.equal(parseNote("# just markdown\n", "x.md"), null);
  assert.equal(parseNote("---\nauthor: x\n---\nbody", "x.md"), null);
});

test("writeNote names the file by date, title and author, never overwrites, and writes nothing into the repo", () => {
  const repo = tmpRepo("notes-write");
  const a = writeNote(repo, { title: "Bbox coordinates are off on rotated PDFs", body: BODY, author: "Priya", date: "2026-10-07" });
  const b = writeNote(repo, { title: "Bbox coordinates are off on rotated PDFs", body: "again", author: "Priya", date: "2026-10-07" });
  const notes = join(repoPlace(repo).dir, "notes");
  assert.ok(notes.startsWith(join(TRAIL_HOME, "repos", "local") + sep), notes);
  assert.equal(a.path, join(notes, "2026-10-07-bbox-coordinates-are-off-on-rotated-priya.md"));
  assert.equal(b.path, join(notes, "2026-10-07-bbox-coordinates-are-off-on-rotated-priya-2.md"));
  assert.match(readFileSync(a.path, "utf8"), /Rotate each box/);
  assert.equal(listNotes(repo).length, 2);
  assert.deepEqual(readdirSync(repo), [], "the repo itself is untouched");
});

test("ensureRepoHome makes the folder once and writes ~/.trail's README once, keeping someone's edits", () => {
  const repo = tmpRepo("notes-dir");
  assert.equal(ensureRepoHome(repo).created, true);
  assert.ok(existsSync(join(repoPlace(repo).dir, "notes")));
  const readme = join(TRAIL_HOME, "README.md");
  assert.match(readFileSync(readme, "utf8"), /^# ~\/\.trail/);
  writeFileSync(readme, "ours\n");
  assert.equal(ensureRepoHome(repo).created, false);
  assert.equal(readFileSync(readme, "utf8"), "ours\n");
});

test("small formatting helpers", () => {
  assert.equal(slug("Bbox coordinates are off on rotated PDFs!"), "bbox-coordinates-are-off-on-rotated");
  assert.equal(shortDate("2026-10-07"), "Oct 7");
  assert.equal(tokensLabel(9600), "~9.6k tokens");
  assert.equal(tokensLabel(31_200), "~31k tokens");
  assert.equal(tokensLabel(600), "~600 tokens");
  assert.equal(costLabel({ minutes: 12, tokens: 9600 }), "took 12 min and ~9.6k tokens to work out");
  assert.equal(costLabel(undefined), null);
  assert.equal(sectionLead(BODY, "Tried and ruled out"), "Rotating the image before OCR. Works, but doubles latency on long files.");
  assert.equal(sectionLead(BODY, "Missing"), null);
});

// --- finding the notes that bear on a query ---

test("a note shows up for a query that shares its words, or for results in a file it touches", () => {
  const notes = [note(), note({ path: "b.md", title: "Webhook retries back off too fast", body: "## Decided\nUse jitter.", touches: ["internal/hooks/retry.go"] })];
  assert.equal(findNotes(notes, "bbox coordinates rotated pdf")[0]?.note.title, "Bbox coordinates are off on rotated PDFs");
  // Words in common with neither title, but the results land in a file the note touches.
  const byFile = findNotes(notes, "thumbnail crop area", ["internal/ocr/bbox.go"]);
  assert.equal(byFile.length, 1);
  assert.deepEqual(byFile[0]?.shared, ["internal/ocr/bbox.go"]);
});

test("an unrelated note never rides along", () => {
  assert.deepEqual(findNotes([note()], "logging setup for the worker"), []);
  // One stray body word is not enough.
  assert.deepEqual(findNotes([note()], "latency dashboards"), []);
});

test("ask's learnings block names the author, the date, each section's lead and the cost", () => {
  const lines = formatNoteHits([{ note: note(), score: 9, shared: [] }]);
  assert.deepEqual(lines, [
    "from Priya's learning · Oct 7 · Bbox coordinates are off on rotated PDFs",
    "  decided     Rotate each box in `NormalizeBox` by its own page's `/Rotate` before scaling.",
    "  ruled out   Rotating the image before OCR. Works, but doubles latency on long files.",
    "  watch out   `/Rotate` can be 270 on a single page inside an otherwise upright file.",
    "  ~/.trail/repos/github.com/acme/extract/notes/2026-10-07-bbox-priya.md · took 12 min and ~9.6k tokens to work out",
    "",
  ]);
});

// --- what a session cost, from Claude Code's transcript ---

function line(o: object): string {
  return JSON.stringify(o);
}
const at = (min: number) => new Date(Date.parse("2026-10-07T10:00:00Z") + min * 60_000).toISOString();
const usage = (input: number, created: number, output: number, read = 50_000) => ({
  input_tokens: input,
  cache_creation_input_tokens: created,
  cache_read_input_tokens: read,
  output_tokens: output,
});

test("cost counts fresh tokens once per message, and active minutes only", () => {
  const t = [
    line({ type: "user", timestamp: at(0), message: { content: "fix bbox" } }),
    // One message, two content blocks: the usage repeats and must count once.
    line({ type: "assistant", timestamp: at(1), message: { id: "m1", usage: usage(100, 2000, 300), content: [{ type: "text", text: "looking" }] } }),
    line({ type: "assistant", timestamp: at(1), message: { id: "m1", usage: usage(100, 2000, 300), content: [{ type: "tool_use", id: "t1", name: "Bash", input: { command: "trail ask x" } }] } }),
    // 40 minutes away from the keyboard: not counted.
    line({ type: "assistant", timestamp: at(41), message: { id: "m2", usage: usage(50, 1000, 200), content: [] } }),
  ].join("\n");
  const c = costFromTranscript(t, Date.parse(at(45)));
  assert.equal(c?.tokens, 2400 + 1250);
  assert.equal(c?.minutes, 5, "1 min, then the 40-min gap skipped, then 4 min to now");
});

test("cost starts after the session's last finished note, not the one being written", () => {
  const t = [
    line({ type: "assistant", timestamp: at(0), message: { id: "a", usage: usage(0, 9000, 1000), content: [{ type: "tool_use", id: "n1", name: "Bash", input: { command: "trail note --title first <<'EOF'" } }] } }),
    line({ type: "user", timestamp: at(1), message: { content: [{ type: "tool_result", tool_use_id: "n1", content: "✓ note saved" }] } }),
    line({ type: "assistant", timestamp: at(2), message: { id: "b", usage: usage(10, 400, 90), content: [] } }),
    // The note call in flight now: no result yet, so it is not a boundary.
    line({ type: "assistant", timestamp: at(3), message: { id: "c", usage: usage(0, 0, 100), content: [{ type: "tool_use", id: "n2", name: "Bash", input: { command: "trail note --title second" } }] } }),
  ].join("\n");
  assert.equal(costFromTranscript(t, Date.parse(at(3)))?.tokens, 600);
});

test("the cost carries the files the session edited since its last note, for the repos the note goes to", () => {
  const edit = (id: string, name: string, input: object) =>
    line({ type: "assistant", timestamp: at(1), message: { id, usage: usage(0, 0, 10), content: [{ type: "tool_use", id, name, input }] } });
  const t = [
    edit("e0", "Edit", { file_path: "/src/extract/old.go" }),
    line({ type: "assistant", timestamp: at(1), message: { id: "n", usage: usage(0, 0, 1), content: [{ type: "tool_use", id: "n1", name: "Bash", input: { command: "trail note --title first" } }] } }),
    line({ type: "user", timestamp: at(1), message: { content: [{ type: "tool_result", tool_use_id: "n1", content: "✓" }] } }),
    edit("e1", "Edit", { file_path: "/src/extract/internal/ocr/bbox.go" }),
    edit("e2", "Write", { file_path: "/src/ocr-lib/rotate.py" }),
    edit("e3", "MultiEdit", { file_path: "/src/extract/internal/ocr/bbox.go" }),
    edit("e4", "NotebookEdit", { notebook_path: "/src/extract/notebooks/rotation.ipynb" }),
    edit("e5", "Read", { file_path: "/src/extract/README.md" }),
  ].join("\n");
  assert.deepEqual(costFromTranscript(t, Date.parse(at(2)))?.edited, [
    "/src/extract/internal/ocr/bbox.go",
    "/src/ocr-lib/rotate.py",
    "/src/extract/notebooks/rotation.ipynb",
  ]);
});

test("a note names its work by its files and specific backticked terms, not by phrases", () => {
  const body = "## Decided\n- `dropHtmlComments` in `src/notes/pr-reviews.ts` repeats until stable.\n- Run `trail init` and `publish`, keep `repo_id`, see `git check-ignore`.\n- `main` is fine.";
  assert.deepEqual(aboutTerms(body, ["internal/ocr/bbox.go#NormalizeBox"]), [
    "internal/ocr/bbox.go",
    "bbox.go",
    "dropHtmlComments",
    "src/notes/pr-reviews.ts",
    "repo_id",
  ]);
});

test("a note's cost starts at the turn where its work first came up, not at the session's start", () => {
  const t = [
    // An hour on something else first.
    line({ type: "user", timestamp: at(0), message: { content: "search slack for the release" } }),
    line({ type: "assistant", timestamp: at(5), message: { id: "s", usage: usage(0, 50_000, 1000), content: [{ type: "tool_use", id: "x", name: "Bash", input: { command: "slack search release" } }] } }),
    line({ type: "assistant", timestamp: at(9), message: { id: "s2", usage: usage(0, 40_000, 1000), content: [] } }),
    // The turn the learning is about: its prompt counts, then the tool call that names the file.
    line({ type: "user", timestamp: at(10), message: { content: "why is the box rotated?" } }),
    line({ type: "assistant", timestamp: at(11), message: { id: "w", usage: usage(0, 3000, 500), content: [{ type: "tool_use", id: "r", name: "Read", input: { file_path: "/repo/internal/ocr/bbox.go" } }] } }),
    line({ type: "assistant", timestamp: at(14), message: { id: "w2", usage: usage(0, 2000, 500), content: [] } }),
    // The note being saved names everything: it never counts as where the work began.
    line({ type: "assistant", timestamp: at(15), message: { id: "n", usage: usage(0, 0, 100), content: [{ type: "tool_use", id: "n1", name: "Bash", input: { command: "trail note --title x <<'EOF'\nslack bbox.go\nEOF" } }] } }),
  ].join("\n");
  const now = Date.parse(at(15));
  const whole = costFromTranscript(t, now)!;
  const scoped = costFromTranscript(t, now, aboutTerms("see `internal/ocr/bbox.go`"))!;
  assert.equal(whole.tokens, 51_000 + 41_000 + 3500 + 2500 + 100);
  assert.equal(scoped.tokens, 3500 + 2500 + 100);
  assert.equal(scoped.minutes, 5);
  assert.equal(scoped.countedFrom, Date.parse(at(10)));
  assert.equal(scoped.startedAt, Date.parse(at(0)), "the stretch since the last note still starts at the top");
});

test("when nothing in the transcript names the work, only the last 30 active minutes count", () => {
  const t = Array.from({ length: 13 }, (_, i) =>
    line({ type: "assistant", timestamp: at(i * 5), message: { id: `m${i}`, usage: usage(0, 1000, 0), content: [] } }),
  ).join("\n");
  const now = Date.parse(at(60));
  assert.equal(costFromTranscript(t, now)!.minutes, 60);
  const capped = costFromTranscript(t, now, ["nowhere/in/it.go"])!;
  assert.equal(capped.minutes, FALLBACK_ACTIVE_MS / 60_000);
  assert.equal(capped.tokens, 7000, "the entries at 30, 35, …, 60 minutes");
});

test("no transcript entries, no cost", () => {
  assert.equal(costFromTranscript("", Date.now()), null);
  assert.equal(costFromTranscript("not json\n", Date.now()), null);
});

// --- end to end ---

/** Runs from this checkout (so `--import tsx` resolves); the repo goes in `args`. */
function run(name: "trail" | "graft", args: string[], home: string, input?: string) {
  const r = spawnSync(process.execPath, ["--import", "tsx", join(process.cwd(), "src", "bin", `${name}.ts`), ...args], {
    input,
    encoding: "utf8",
    env: { ...process.env, ...homeEnv(home), DO_NOT_TRACK: "1", CLAUDECODE: undefined, TRAIL_INVOKED_AS: undefined, TRAIL_HOME: undefined },
  });
  return { status: r.status, out: r.stdout, err: r.stderr };
}

function repoWithCode(): string {
  const d = tmpRepo("notes-e2e");
  mkdirSync(join(d, "internal", "ocr"), { recursive: true });
  writeFileSync(join(d, "internal", "ocr", "bbox.go"), "package ocr\n\nfunc NormalizeBox(x float64, rotate int) float64 {\n\treturn x\n}\n");
  writeFileSync(join(d, "CLAUDE.md"), "# extract\n\nTeam rules.\n");
  spawnSync("git", ["init", "-q"], { cwd: d });
  spawnSync("git", ["config", "user.name", "Priya Raman"], { cwd: d });
  spawnSync("git", ["config", "user.email", "[email protected]"], { cwd: d });
  spawnSync("git", ["add", "-A"], { cwd: d });
  spawnSync("git", ["-c", "commit.gpgsign=false", "commit", "-qm", "init"], { cwd: d });
  return d;
}

/** The one folder of notes under a scratch HOME's ~/.trail/repos. */
function notesUnder(home: string): string {
  const local = join(home, ".trail", "repos", "local");
  const [key] = readdirSync(local);
  return join(local, key!, "notes");
}

test("trail init makes the repo's .trail/learnings/ and says to commit it; graft init makes neither", () => {
  const home = mkdtempSync(join(tmpdir(), "notes-home-"));
  const d = repoWithCode();
  const t = run("trail", ["init", d, "--agents", "claude", "--yes", "--no-global"], home);
  assert.equal(t.status, 0, t.err);
  assert.match(t.err, /✓ learnings {2}\.trail\/learnings\/ · a session that fixes a bug, takes a correction or opens a PR leaves one there, for your whole team/);
  assert.match(t.err, /· commit \.claude\/settings\.json and \.trail\/ once: after that, teammates' Claude reads your learnings even before they install trail/);
  assert.ok(existsSync(join(d, ".trail", "learnings")));
  assert.match(readFileSync(join(d, ".trail", "README.md"), "utf8"), /^# \.trail/);
  assert.equal(readFileSync(join(d, "CLAUDE.md"), "utf8"), "# extract\n\nTeam rules.\n", "the team's CLAUDE.md is untouched");

  const g = repoWithCode();
  const home2 = mkdtempSync(join(tmpdir(), "notes-home-"));
  assert.equal(run("graft", ["init", g, "--agents", "claude", "--yes", "--no-global"], home2).status, 0);
  assert.equal(existsSync(join(home2, ".trail")), false);
  assert.equal(existsSync(join(g, ".trail")), false);
});

test("trail note saves a learning in .trail/learnings/ to commit, ask shows it to the next session, uninstall leaves it", () => {
  const home = mkdtempSync(join(tmpdir(), "notes-home-"));
  const d = repoWithCode();
  run("trail", ["init", d, "--agents", "claude", "--yes", "--no-global"], home);
  // Init's files go in with the setup commit, as they would for a real team.
  spawnSync("git", ["add", "-A"], { cwd: d });
  spawnSync("git", ["-c", "commit.gpgsign=false", "commit", "-qm", "wire trail"], { cwd: d });
  // A teammate worked on the same file: the case for committing names them.
  writeFileSync(join(d, "internal", "ocr", "bbox.go"), "package ocr\n\nfunc NormalizeBox(x float64, rotate int) float64 {\n\treturn x * 1\n}\n");
  spawnSync("git", ["-c", "commit.gpgsign=false", "-c", "user.name=Anay Shah", "-c", "[email protected]", "commit", "-qam", "scale"], { cwd: d });
  writeFileSync(join(d, "internal", "ocr", "bbox.go"), "package ocr\n\nfunc NormalizeBox(x float64, rotate int) float64 {\n\treturn -x\n}\n");

  const saved = run("trail", ["note", d, "--title", "Bbox coordinates are off on rotated PDFs", "--minutes", "12", "--tokens", "9600"], home, BODY);
  assert.equal(saved.status, 0, saved.err);
  assert.match(saved.out, /^✓ added to this repo · \.trail\/learnings\/\d{4}-\d{2}-\d{2}-bbox-coordinates-are-off-on-rotated-priya\.md$/m);
  assert.match(saved.out, /· the next session that touches bbox\.go starts from this, and gets to a PR 3x faster/);
  assert.match(
    saved.out,
    /^🌱 Anay works in this part of the codebase\. Commit what you learned and their agents get to a PR 3x faster · git add \.trail\/learnings\/\S+\.md$/m,
  );
  assert.match(
    saved.out,
    /\[trail\] Close your reply with one line, word for word\. If this learning is committed by the end of your turn: 📝 Committed · Anay works in this part of the codebase, and their agents now get to a PR 3x faster\n  If it isn't: 📝 Learning: "Bbox coordinates are off on rotated PDFs" · your teammates' Claude reads it when they open bbox\.go\. Commit it with this change\? \(y\/n\)\n  On a yes, commit it with the change: in the change's own commit when that isn't pushed yet\.$/m,
    "the closing lines, for the agent's reply: committed, or the ask to commit it",
  );
  const [file] = readdirSync(join(d, ".trail", "learnings")).filter((f) => f.endsWith(".md"));
  const written = parseNote(readFileSync(join(d, ".trail", "learnings", file!), "utf8"), "x");
  assert.equal(written?.author, "Priya");
  assert.deepEqual(written?.touches, ["internal/ocr/bbox.go"], "the changed file, not the wiring init wrote");
  const status = spawnSync("git", ["status", "--porcelain", "--untracked-files=all"], { cwd: d, encoding: "utf8" }).stdout;
  assert.equal(status, ` M internal/ocr/bbox.go\n?? .trail/learnings/${file}\n`, "the learning waits to be committed with the change");

  // Asked from either name, and from a subfolder of the repo.
  for (const [name, dir] of [["trail", d], ["graft", d], ["trail", join(d, "internal")]] as const) {
    const ask = run(name, ["ask", "bbox rotated pdf", dir], home);
    assert.equal(ask.status, 0, ask.err);
    assert.match(ask.out, /from Priya's learning · \w{3} \d+ · Bbox coordinates are off on rotated PDFs/);
    assert.match(ask.out, /ruled out {3}Rotating the image before OCR/);
    assert.match(ask.out, /\.trail\/learnings\/\d{4}-\d{2}-\d{2}-bbox/);
    assert.doesNotMatch(ask.out, /3x faster|gets you to a PR/, "no worth its own measured cost doesn't back");
  }
  // Not connected to a workspace: what was searched stays unrecorded, so a later sign-in has nothing old to send.
  assert.equal(existsSync(join(home, ".trail", "outbox.jsonl")), false, "no outbox before connecting");

  const st = run("trail", ["status", d], home);
  assert.equal(st.status, 0, st.err);
  assert.match(st.out, /^learnings {3}1 added to this repo, in \.trail\/learnings\/$/m);
  assert.equal(JSON.parse(run("trail", ["status", d, "--json"], home).out).learnings.repo, 1);

  const un = run("trail", ["uninstall", d, "-y", "--no-global"], home);
  assert.equal(un.status, 0, un.err);
  assert.ok(existsSync(join(d, ".trail", "learnings", file!)), "learnings are the team's, never uninstalled");
});

test("trail note --personal keeps it in ~/.trail, out of the repo", () => {
  const home = mkdtempSync(join(tmpdir(), "notes-home-"));
  const d = repoWithCode();
  const saved = run("trail", ["note", d, "--personal", "--title", "My editor runs gofmt on save"], home, BODY);
  assert.equal(saved.status, 0, saved.err);
  assert.match(saved.out, /^✓ saved just for you · ~\/\.trail\/repos\/local\/[^/]+\/notes\/\d{4}-\d{2}-\d{2}-my-editor-runs-gofmt-on-save-priya\.md$/m);
  assert.match(saved.out, /^· just for you: kept on this machine, out of the repo$/m);
  assert.match(saved.out, /📝 Saved just for you · stays on this machine, out of the repo$/m);
  assert.ok(existsSync(notesUnder(home)));
  assert.equal(existsSync(join(d, ".trail")), false);
});

test("trail note without a body says how to write one", () => {
  const home = mkdtempSync(join(tmpdir(), "notes-home-"));
  const r = run("trail", ["note", repoWithCode(), "--title", "x"], home, "");
  assert.equal(r.status, 1);
  assert.match(r.err, /a learning needs a --title and a body/);
});

// --- what agents read in a repo that uses trail ---

test("the skill speaks trail in a repo wired for it, names the map in .trail/cache/, and teaches learnings", async () => {
  const { skillTemplate } = await import("../src/claude/skill-template.js");
  const graft = skillTemplate("graft");
  const trail = skillTemplate("trail");
  assert.equal(skillTemplate(), graft, "graft is the default, unchanged");
  assert.doesNotMatch(graft, /\.trail\//);
  assert.match(trail, /^name: trail$/m, "it lives in .claude/skills/trail/");
  assert.match(trail, /`trail ask "<question>" --source`/);
  assert.match(trail, /`trail build` \/ `trail build --check`/);
  assert.match(trail, /`\.trail\/cache\/` holds a graph/, "under trail the code map is in .trail/cache/");
  assert.doesNotMatch(trail, /\bgraft (ask|grep|skeleton|callers|map|build|check)\b/);
  assert.match(trail, /trail note --title/);
  assert.match(trail, /It's written to `\.trail\/learnings\/`\. Commit it\n  with the change it came from/);
  assert.match(trail, /- Just for the user, with `--personal`: how this person likes to work/);
  assert.doesNotMatch(trail, /trail learn|trail skills show/, "corrections are learnings too, not takeaways on a skill");
  assert.match(trail, /## If trail isn't installed/);
});

// Claude Code reads only a skill's description up front, so the moments to
// reach for trail have to be named there, and lead the body.
test("the trail skill's description names when to use its commands, and the body leads with them", async () => {
  const { skillTemplate } = await import("../src/claude/skill-template.js");
  const matter = (await import("gray-matter")).default;
  const { data, content } = matter(skillTemplate("trail"));
  assert.equal(data.name, "trail");
  assert.ok(data.description.length <= 1024, "skill descriptions are capped at 1,024 characters");
  assert.match(data.description, /ANY task in this repo/);
  assert.match(data.description, /trail ask before grepping/);
  assert.match(data.description, /When the session finds what the code can't tell\s+the next person/);
  assert.match(data.description, /save a learning with trail note and commit it with the change/);
  assert.match(data.description, /\.trail\/learnings\//, "where the learnings are, for a Claude without trail");
  assert.match(data.description, /npm install -g @trailhq\/trail/, "and how to get the command");
  assert.doesNotMatch(data.description, /graft/, "nothing about the old name or the graft\/ folder");
  const moments = content.indexOf("## When to reach for trail");
  assert.ok(moments >= 0 && moments < content.indexOf("## The tools"), "the moments come before the tool docs");
  assert.match(content, /\*\*When the session finds what the code can't tell the next person\*\*/);
  assert.match(data.description, /the user correcting how something is done\s+here/);
  const saving = content.indexOf("## Saving a learning");
  assert.ok(saving > moments && saving < content.indexOf("## The tools"), "what to save comes before the tool docs");
  assert.match(content, /Good, `--title "CodeQL init and analyze must share a version"`/, "one good example");
  assert.match(content, /Bad, `--title "Finishing the rollout PR"`/, "and one bad one");
  assert.match(content, /\*\*When the user corrects how something is done here\*\*/);
});

test("the session-start directive mentions learnings only in a repo that keeps them", async () => {
  const { formatOrientation } = await import("../src/claude/format.js");
  assert.doesNotMatch(formatOrientation("# map", 100), /learning/);
  const some = formatOrientation("# map", 100, undefined, 3, true);
  assert.match(some, /This repo has 3 learnings from past sessions/);
  assert.match(some, /📝 Started from Priya's learning, adding what it saved \(· saved ~90k tokens and ~12 min\) only when (trail|graft) prints that with it/, "the closing line, by example");
  assert.doesNotMatch(some, /3x faster/, "no value claim by example");
  assert.match(some, /Save a learning when the session finds what the code can't tell the next person/);
  assert.match(some, /never for setting up trail, status, or what the diff shows/);
  assert.match(some, /commit it with the change/);
  const none = formatOrientation("# map", 100, undefined, 0, true);
  assert.doesNotMatch(none, /This repo has/);
  assert.match(none, /Save a learning when the session finds/, "a repo set up for learnings is told to leave one from the first session");
});

test("hooks speak trail only in a repo wired for it, on a machine with trail installed", async () => {
  const { adoptRepoBrand } = await import("../src/brand.js");
  const bin = mkdtempSync(join(tmpdir(), "notes-bin-"));
  writeFileSync(join(bin, process.platform === "win32" ? "trail.cmd" : "trail"), "");
  const withTrail = tmpRepo("brand-repo");
  mkdirSync(join(withTrail, ".claude", "helpers"), { recursive: true });
  writeFileSync(join(withTrail, ".claude", "helpers", "trail-hooks.cjs"), "");
  const plain = tmpRepo("brand-plain");
  assert.equal(adoptRepoBrand(withTrail, { PATH: bin }), "trail");
  assert.equal(adoptRepoBrand(withTrail, { PATH: "" }), "graft", "trail not installed: don't suggest it");
  assert.equal(adoptRepoBrand(plain, { PATH: bin }), "graft");
  assert.equal(adoptRepoBrand(plain, { PATH: bin, TRAIL_INVOKED_AS: "trail" }), "trail", "a name already set is kept");
});

test("Cursor's and Codex's hooks speak trail in a repo whose only trail wiring is theirs", async () => {
  const { adoptRepoBrand } = await import("../src/brand.js");
  const { hostsWiredForTrail } = await import("../src/hosts/registry.js");
  const bin = mkdtempSync(join(tmpdir(), "notes-bin-"));
  writeFileSync(join(bin, process.platform === "win32" ? "trail.cmd" : "trail"), "");
  const cursorOnly = tmpRepo("brand-cursor");
  mkdirSync(join(cursorOnly, ".cursor", "rules"), { recursive: true });
  writeFileSync(join(cursorOnly, ".cursor", "rules", "trail.mdc"), "");
  assert.equal(adoptRepoBrand(cursorOnly, { PATH: bin }, hostsWiredForTrail), "trail");
  assert.equal(adoptRepoBrand(cursorOnly, { PATH: bin }), "graft", "without the hosts check, only .claude counts");
  assert.equal(adoptRepoBrand(tmpRepo("brand-none"), { PATH: bin }, hostsWiredForTrail), "graft");
});

// --- wiring under trail's names ---

test("trail init moves a graft-wired repo to trail's names, and uninstall takes either set out", () => {
  const home = mkdtempSync(join(tmpdir(), "notes-home-"));
  const d = repoWithCode();
  const env = { GRAFT_MCP_NPX: "1" };
  Object.assign(process.env, env);
  try {
    assert.equal(run("graft", ["init", d, "--agents", "claude", "--yes", "--no-global"], home).status, 0);
    assert.ok(existsSync(join(d, ".claude", "helpers", "graft-hooks.cjs")));
    assert.ok(existsSync(join(d, ".claude", "skills", "graft", "SKILL.md")));

    const t = run("trail", ["init", d, "--agents", "claude", "--yes", "--no-global"], home);
    assert.equal(t.status, 0, t.err);
    // Shared: the hook in .trail/ and one SessionStart entry. The old layout is gone.
    for (const f of [".trail/hook.cjs", ".trail/statusline.cjs"]) assert.ok(existsSync(join(d, f)), f);
    for (const f of ["helpers", "skills/graft", "skills/trail"]) assert.equal(existsSync(join(d, ".claude", f)), false, f);
    const settings = JSON.parse(readFileSync(join(d, ".claude", "settings.json"), "utf8"));
    assert.deepEqual(Object.keys(settings.hooks), ["SessionStart"]);
    assert.match(JSON.stringify(settings.hooks.SessionStart), /\/\.trail\/hook\.cjs\\" session-start/);
    for (const k of ["statusLine", "permissions", "footerLinksRegexes"]) assert.equal(settings[k], undefined, k);
    // Personal: status line, allowlist, and under --no-global every other hook, never session start.
    const local = JSON.parse(readFileSync(join(d, ".claude", "settings.local.json"), "utf8"));
    assert.match(local.statusLine.command, /\.trail\/statusline\.cjs/);
    assert.ok(local.permissions.allow.includes("Bash(trail:*)"));
    assert.equal(local.hooks.SessionStart, undefined);
    assert.match(JSON.stringify(local.hooks.UserPromptSubmit), /\.trail\/hook\.cjs\\" prompt/);
    assert.match(JSON.stringify(local.hooks.SessionEnd), /\.trail\/hook\.cjs\\" session-end/);
    // No MCP server for Claude Code: graft's .mcp.json had only graft's, so it goes.
    assert.equal(existsSync(join(d, ".mcp.json")), false);
    // Nothing personal shows in git, and .gitignore is untouched by the setup.
    assert.match(readFileSync(join(d, ".trail", ".gitignore"), "utf8"), /^statusline\.cjs$/m);
    for (const f of [".claude/settings.local.json", ".trail/statusline.cjs"]) assert.equal(spawnSync("git", ["check-ignore", "-q", f], { cwd: d }).status, 0, f);

    // Running it again changes nothing.
    const before = [".claude/settings.json", ".claude/settings.local.json"].map((f) => readFileSync(join(d, f), "utf8"));
    const again = run("trail", ["init", d, "--agents", "claude", "--yes", "--no-global"], home);
    assert.equal(again.status, 0, again.err);
    assert.deepEqual([".claude/settings.json", ".claude/settings.local.json"].map((f) => readFileSync(join(d, f), "utf8")), before);

    const un = run("trail", ["uninstall", d, "-y", "--no-global"], home);
    assert.equal(un.status, 0, un.err);
    for (const f of [".trail/hook.cjs", ".trail/statusline.cjs"]) assert.equal(existsSync(join(d, f)), false, f);
    // Both held only what init wrote, so they go with it.
    for (const f of ["settings.json", "settings.local.json"]) assert.equal(existsSync(join(d, ".claude", f)), false, f);
  } finally {
    delete process.env.GRAFT_MCP_NPX;
  }
});

// After a check conflict the agent says why; it saves a learning about it
// only when the person asks, like any other learning.
test("nothing tells the agent to save a learning on its own after a check conflict", async () => {
  const { skillTemplate } = await import("../src/claude/skill-template.js");
  const { teamNotesDirective } = await import("../src/claude/format.js");
  const saved = process.env.TRAIL_INVOKED_AS;
  process.env.TRAIL_INVOKED_AS = "trail";
  let directive: string;
  try {
    directive = teamNotesDirective(3, true);
  } finally {
    if (saved === undefined) delete process.env.TRAIL_INVOKED_AS;
    else process.env.TRAIL_INVOKED_AS = saved;
  }
  // The skill's check-conflict text is #663's (D184): it says to save a new learning with --replaces. The session
  // directive's trail check line is part 6's, and still waits for the user.
  void skillTemplate;
  for (const [where, text] of [["session directive", directive]] as const) {
    assert.doesNotMatch(text.replace(/\s+/g, " "), /and save a new learning/, where);
    assert.match(text.replace(/\s+/g, " "), /If the user asks you to save what changed, save it as a new learning/, where);
  }
});

test("trail status and trail init count only live learnings: not retired, held or replaced ones", () => {
  const home = mkdtempSync(join(tmpdir(), "notes-home-"));
  const d = repoWithCode();
  const dir = join(d, ".trail", "learnings");
  mkdirSync(dir, { recursive: true });
  const file = (name: string, extra = "", date = "2026-10-08") =>
    writeFileSync(join(dir, name), `---\ntitle: "${name}"\nauthor: Priya\ndate: ${date}\n${extra}---\n\n${BODY}\n`);
  file("2026-10-08-active-priya.md");
  file("2026-10-08-retired-priya.md", "status: retired\n");
  file("2026-10-08-held-priya.md", "status: held\n");
  file("2026-10-08-old-priya.md", "id: l-0a0a0a0a\n");
  file("2026-10-09-new-priya.md", "id: l-0b0b0b0b\nreplaces: l-0a0a0a0a\n", "2026-10-09");
  const st = run("trail", ["status", d], home);
  assert.equal(st.status, 0, st.err);
  assert.match(st.out, /^learnings {3}2 /m);
  assert.equal(JSON.parse(run("trail", ["status", d, "--json"], home).out).learnings.repo, 2);
  const init = run("trail", ["init", d, "--agents", "claude", "--yes", "--no-global"], home);
  assert.equal(init.status, 0, init.err);
  assert.match(init.err, /✓ learnings {2}2 in \.trail\/learnings\//);
});

test("the session and the skill say a replacement saved on a branch leaves the conflict in place until it's merged", async () => {
  const { skillTemplate } = await import("../src/claude/skill-template.js");
  const { teamNotesDirective } = await import("../src/claude/format.js");
  const saved = process.env.TRAIL_INVOKED_AS;
  process.env.TRAIL_INVOKED_AS = "trail";
  let directive: string;
  try {
    directive = teamNotesDirective(3, true);
  } finally {
    if (saved === undefined) delete process.env.TRAIL_INVOKED_AS;
    else process.env.TRAIL_INVOKED_AS = saved;
  }
  for (const [where, text] of [["skill", skillTemplate("trail")], ["session directive", directive]] as const) {
    const flat = text.replace(/\s+/g, " ");
    assert.match(flat, /A replacement saved on this branch leaves the conflict in place until it's merged/, where);
    assert.doesNotMatch(flat, /team has learned/, where);
  }
});