Skip to content

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

14.0 KB
Raw Blame
/**
 * Trying to break the fold and the gate (the g3 review): background commands,
 * parallel calls, notices mid-run, subagent lines, writes to Trail's files by
 * every route a shell offers (a symlink included), each entrypoint, two hook
 * processes at once, and the modes of every file the skills code writes.
 * Synthetic repos, prompts and output only.
 */
import { test } from "node:test";
import assert from "node:assert/strict";
import { spawn } from "node:child_process";
import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, statSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { checkedSuccess, freshRunId } from "../src/trace/runs.js";
import { effectiveFolder } from "../src/trace/run-calls.js";
import { tamperOf } from "../src/trace/tamper.js";
import { appendPostMark, gateFilePath, writeGateFile } from "../src/trace/gate-file.js";
import { notePoolDay, poolPath } from "../src/trace/pool.js";
import { skillsGate, withSkillSession } from "../src/trace/skill-session.js";
import { jsonl, said, sidechain, taskNotification, toolResult, toolUse } from "./trace-fixtures.js";
import { ask, at, bash, injection, session } from "./trace-run-fixtures.js";

const POSIX = process.platform !== "win32";
const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
const SRC = join(ROOT, "src");

/* ------------------------------------------------------ background commands */

test("a background command's result is not its outcome: it never passes a check", () => {
  const s = session("bg");
  s.fold([
    ask("run the tests", 0),
    ...bash("npm test", "Command running in background with ID: b1x2. Output is being written to: /tmp/tasks/b1x2.output", { sec: 1, bg: true }),
    ...bash("npm run test:e2e &", "", { sec: 2 }),
  ]);
  const run = s.st.runs[0]!;
  assert.deepEqual(run.calls.map((c) => [c.bg, c.check?.passed ?? null]), [[true, false], [true, false]]);
  assert.equal(checkedSuccess(run, "Started the tests.").checked, false);
});

/* ---------------------------------------------- parallel calls, notices, subagents */

test("parallel calls in one turn, results arriving in the other order, each get their own outcome", () => {
  const s = session("parallel");
  const turn = said("Running both.", { timestamp: at(1) }) as { message: { content: unknown[] } };
  turn.message.content.push(
    { type: "tool_use", id: "toolu_par_a", name: "Bash", input: { command: "npm run lint" } },
    { type: "tool_use", id: "toolu_par_b", name: "Bash", input: { command: "npm run build" } },
  );
  s.fold([ask("run the tests", 0), turn, toolResult("toolu_par_b", "error TS2304: Cannot find name 'x'.", true, { timestamp: at(3) }), toolResult("toolu_par_a", "ok", false, { timestamp: at(4) })]);
  const run = s.st.runs[0]!;
  assert.deepEqual(run.calls.map((c) => [c.cmd, c.failed]), [["npm run lint", false], ["npm run build", true]]);
  assert.equal(run.failedCount, 1);
});

test("a task notice mid-run starts nothing; a subagent's lines in the parent transcript are not the run's", () => {
  const s = session("notice");
  s.fold([
    ask("run the integration tests", 0),
    ...bash("npm run db:up", "ok", { sec: 1 }),
    taskNotification(),
    sidechain(),
    toolUse("toolu_side", "Bash", { command: "rm -rf build" }, { isSidechain: true, timestamp: at(3) }),
    toolResult("toolu_side", "", false, { isSidechain: true, timestamp: at(4) }),
    ...bash("npm run test:integration", "Tests  9 passed (9)", { sec: 5 }),
  ]);
  assert.equal(s.st.runs.length, 1);
  assert.deepEqual([s.st.runs[0]!.typedCount, s.st.runs[0]!.commands, s.st.runs[0]!.toolCalls], [1, 2, 2]);
});

/* ------------------------------------------------------------------ cd chains */

test("cd chains: `cd -` back to where the call started is known; one with no cd before it in the call is not", () => {
  assert.equal(effectiveFolder("/home/dev/shop", "cd backend && cd - && npm test", "/home/dev"), "/home/dev/shop");
  assert.equal(effectiveFolder("/home/dev/shop", "cd backend && cd ../web && cd - && go test ./...", "/home/dev"), resolve("/home/dev/shop/backend"));
  assert.equal(effectiveFolder("/home/dev/shop", "cd - && npm test", "/home/dev"), null);
});

/* --------------------------------------------------------------------- tamper */

function homeWithTrail(): { home: string; trail: string; ctx: { trailHome: string; transcriptPath: string; home: string } } {
  const home = mkdtempSync(join(tmpdir(), "breaks-home-"));
  const trail = join(home, ".trail");
  mkdirSync(join(trail, "runs"), { recursive: true });
  writeFileSync(join(trail, "settings.json"), "{}");
  const transcript = join(home, ".claude", "projects", "-home-dev-shop", "5f0c.jsonl");
  mkdirSync(join(transcript, ".."), { recursive: true });
  writeFileSync(transcript, "");
  return { home, trail, ctx: { trailHome: trail, transcriptPath: transcript, home } };
}

test("tamper: every shell route to a write trips it (pushd, cd -, tar, unzip, >|, awk inplace, a variable, ln)", () => {
  const { ctx } = homeWithTrail();
  const bashT = (cmd: string) => tamperOf("Bash", { command: cmd }, cmd, { ...ctx, folder: "/home/dev/shop" });
  for (const cmd of [
    "pushd ~/.trail && rm settings.json",
    "cd ~/.trail && cd /tmp && cd - && rm settings.json",
    "tar -xf /tmp/forged.tar -C ~/.trail",
    "tar --directory=$HOME/.trail -xzf /tmp/forged.tgz",
    "unzip -o /tmp/forged.zip -d ~/.trail/skills",
    "echo '{}' >| ~/.trail/settings.json",
    "awk -i inplace '{print}' ~/.trail/state/skills.json",
    "D=~/.trail; echo x > $D/settings.json",
    'export T="$HOME/.trail" && echo x > "$T/offers.jsonl"',
    "ln -s ~/.trail/settings.json /tmp/alias.json",
    `ln -sf /tmp/forged.jsonl ${ctx.transcriptPath}`,
    `python3 -c "open('$HOME/.trail/settings.json','w').write('{}')"`,
    `node -e 'require("fs").writeFileSync(require("os").homedir()+"/.trail/settings.json","{}")'`,
    `sed -i '' 's/no/yes/' ${ctx.transcriptPath}`,
  ]) assert.ok(bashT(cmd), cmd);
  for (const cmd of ["cat ~/.trail/settings.json", "D=~/.trail; ls $D", "ln -s /home/dev/shop/dist /tmp/dist", "tar -czf /tmp/backup.tgz -C ~/.trail .", "echo x >| /tmp/out.txt"]) {
    assert.equal(bashT(cmd), null, cmd);
  }
});

test("tamper: a write through a symlink that leads into Trail's home trips it, and so does a Trail home that is itself a link", { skip: !POSIX && "posix only" }, () => {
  const { home, trail, ctx } = homeWithTrail();
  const alias = join(home, "alias.json");
  symlinkSync(join(trail, "settings.json"), alias);
  const dirAlias = join(home, "notes");
  symlinkSync(join(trail, "runs"), dirAlias);
  const at = (cmd: string, c = ctx) => tamperOf("Bash", { command: cmd }, cmd, { ...c, folder: home });
  assert.ok(at(`echo '{"skills":"on"}' > ${alias}`));
  assert.ok(at(`cp /tmp/forged.json ${dirAlias}/r-1001-aaaa.json`), "a new file in a linked folder");
  assert.equal(at(`cat ${alias}`), null);
  assert.ok(tamperOf("Write", { file_path: alias }, null, ctx), "an edit tool through the link");
  // ~/.trail is a link to a folder elsewhere: writing the real folder is writing Trail's home.
  const real = join(home, "data", "trail");
  mkdirSync(real, { recursive: true });
  const linkedHome = join(home, "linked-trail");
  symlinkSync(real, linkedHome);
  assert.ok(at(`echo x > ${join(real, "settings.json")}`, { ...ctx, trailHome: linkedHome }));
});

/* ------------------------------------------------------------------- the gate */

test("the gate: a bare `sdk` entrypoint is a script too, as the transcript reader already treats it", () => {
  const home = mkdtempSync(join(tmpdir(), "breaks-gate-"));
  mkdirSync(join(home, ".trail"), { recursive: true });
  writeFileSync(join(home, ".trail", "settings.json"), JSON.stringify({ skills: "on" }));
  const env = { HOME: home, TRAIL_HOME: join(home, ".trail"), CLAUDE_CODE_ENTRYPOINT: "sdk", PATH: process.env.PATH };
  const g = skillsGate({ session_id: "s-1", cwd: ROOT, transcript_path: "/x.jsonl" }, ROOT, env);
  assert.ok(g.ok);
  assert.deepEqual([g.ctx.entry, g.ctx.fold, g.ctx.learnOff], ["headless", false, "headless"]);
});

/* ---------------------------------------------------- files: links, ids, modes */

test("a post mark is never written through a symlink", { skip: !POSIX && "posix only" }, () => {
  const home = mkdtempSync(join(tmpdir(), "breaks-mark-"));
  const env = { TRAIL_HOME: join(home, ".trail") };
  mkdirSync(join(home, ".trail", "sessions"), { recursive: true });
  const victim = join(home, "victim.txt");
  writeFileSync(victim, "keep\n", { mode: 0o644 });
  symlinkSync(victim, join(home, ".trail", "sessions", "s-link.post.jsonl"));
  assert.throws(() => appendPostMark("s-link", { id: "toolu_1", at: at(1), failed: false }, env));
  assert.equal(readFileSync(victim, "utf8"), "keep\n");
  assert.equal(statSync(victim).mode & 0o777, 0o644);
});

test("a new run's id is never one already taken in this session or by a sheet on disk", () => {
  let asked = 0;
  const id = freshRunId(new Date(2026, 9, 27, 10), () => ++asked < 4);
  assert.match(id, /^r-1027-[0-9a-f]{4}$/);
  assert.equal(asked, 4, "it kept drawing until an id was free");
  const s = session("ids");
  const sheets = join(mkdtempSync(join(tmpdir(), "breaks-ids-")), ".trail");
  mkdirSync(join(sheets, "runs"), { recursive: true });
  s.fold([ask("run the tests", 0), ...bash("npm test", "ok", { sec: 1 })], { trailHome: sheets });
  assert.ok(!existsSync(join(sheets, "runs", `${s.st.runs[0]!.id}.json`)));
});

test("modes: every skills file is 0600 in 0700 folders", { skip: !POSIX && "posix only" }, () => {
  const home = mkdtempSync(join(tmpdir(), "breaks-modes-"));
  mkdirSync(join(home, ".trail"), { recursive: true, mode: 0o755 });
  writeFileSync(join(home, ".trail", "settings.json"), JSON.stringify({ skills: "on" }));
  const env = { HOME: home, TRAIL_HOME: join(home, ".trail"), CLAUDE_CODE_ENTRYPOINT: "cli", PATH: process.env.PATH };
  const transcript = join(home, "t.jsonl");
  writeFileSync(transcript, jsonl([ask("run the tests", 0), ...bash("npm test", "Tests  2 passed (2)", { sec: 1 }), ask("publish 1.4.3", 60)]));
  const g = skillsGate({ session_id: "s-modes", cwd: ROOT, transcript_path: transcript }, ROOT, env);
  assert.ok(g.ok && g.ctx.fold);
  withSkillSession(g.ctx, { catchUp: true }, (st) => { st.injected.push(injection()); writeGateFile("s-modes", st, env); });
  appendPostMark("s-modes", { id: "toolu_1", at: at(1), failed: false }, env);
  notePoolDay("github.com/acme/shop", { job: "tests", words: ["tests"] }, { d: "2026-10-01", s: "e76b4ca7f1a0", costly: true }, null, env, new Date(2026, 9, 1, 12));
  const sessions = join(home, ".trail", "sessions");
  const runs = join(home, ".trail", "runs");
  const files = [join(sessions, "s-modes.json"), gateFilePath("s-modes", env), join(sessions, "s-modes.post.jsonl"), join(runs, "index.json"), poolPath("github.com/acme/shop", env)];
  const sheet = readFileSync(join(runs, "index.json"), "utf8").match(/r-\d{4}-[0-9a-f]{4}/)![0];
  files.push(join(runs, `${sheet}.json`));
  for (const f of files) assert.equal(statSync(f).mode & 0o777, 0o600, f);
  for (const d of [sessions, runs, join(poolPath("github.com/acme/shop", env), "..")]) assert.equal(statSync(d).mode & 0o777, 0o700, d);
  assert.ok(!lstatSync(sessions).isSymbolicLink());
});

/* --------------------------------------------------- two hook processes at once */

const SKILL_SESSION = join(SRC, "trace", "skill-session.ts");

test("two hook processes catching up at once while the transcript grows: every call folded once, no update lost", { skip: !POSIX && "posix only", timeout: 90_000 }, async () => {
  const home = mkdtempSync(join(tmpdir(), "breaks-race-"));
  mkdirSync(join(home, ".trail"), { recursive: true });
  writeFileSync(join(home, ".trail", "settings.json"), JSON.stringify({ skills: "on" }));
  const transcript = join(home, "t.jsonl");
  writeFileSync(transcript, jsonl([ask("run the integration tests", 0)]));
  const lines = Array.from({ length: 80 }, (_, i) => jsonl(bash(`npm run step:${i}`, "ok", { sec: 1 + i, id: `toolu_race_${i}` })));
  const writer = join(home, "writer.mjs");
  writeFileSync(writer, `import { appendFileSync } from "node:fs";
const lines = ${JSON.stringify(lines)};
for (const l of lines) { appendFileSync(${JSON.stringify(transcript)}, l); const until = Date.now() + 4; while (Date.now() < until) {} }`);
  const hook = join(home, "hook.mts");
  writeFileSync(hook, `const { skillsGate, withSkillSession } = await import(${JSON.stringify(SKILL_SESSION)});
const env = { ...process.env, HOME: ${JSON.stringify(home)}, TRAIL_HOME: ${JSON.stringify(join(home, ".trail"))}, CLAUDE_CODE_ENTRYPOINT: "cli" };
delete env.CI; delete env.GITHUB_ACTIONS; delete env.TRAIL_NO_HOOKS;
let lost = 0;
for (let i = 0; i < 30; i++) {
  const g = skillsGate({ session_id: "s-race", cwd: ${JSON.stringify(ROOT)}, transcript_path: ${JSON.stringify(transcript)} }, ${JSON.stringify(ROOT)}, env);
  const r = withSkillSession(g.ctx, { catchUp: true, waitMs: 20000 }, (st) => { st.scopeKeys.push("p" + process.pid + "-" + i); return 1; });
  if (r !== 1) lost++;
}
process.stdout.write(String(lost));`);
  const run = (file: string, loader: boolean) => new Promise<string>((done) => {
    let out = "";
    const p = spawn(process.execPath, loader ? ["--import", "tsx", file] : [file], { cwd: ROOT, stdio: ["ignore", "pipe", "inherit"] });
    p.stdout.on("data", (d) => (out += d));
    p.on("exit", () => done(out));
  });
  const outs = await Promise.all([run(hook, true), run(hook, true), run(writer, false)]);
  assert.deepEqual(outs.slice(0, 2), ["0", "0"], "a hook gave up on the lock");
  // One last catch-up after the writer is done.
  const env = { HOME: home, TRAIL_HOME: join(home, ".trail"), CLAUDE_CODE_ENTRYPOINT: "cli", PATH: process.env.PATH };
  const g = skillsGate({ session_id: "s-race", cwd: ROOT, transcript_path: transcript }, ROOT, env);
  assert.ok(g.ok);
  const st = withSkillSession(g.ctx, { catchUp: true, waitMs: 5000 }, (s) => s)!;
  assert.equal(st.runs.length, 1);
  assert.equal(st.runs[0]!.commands, 80, "every call folded exactly once");
  assert.equal(st.scopeKeys.filter((k) => k.startsWith("p")).length, 60, "no update lost");
});