Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* The update gate (phase 2 design 4.11, P29, R4, R11, R14): `trail skills
* update <name> --offer <id>` changes a skill only after the person typed
* yes to the offer that showed that exact change, from the file it was
* computed from, with every new step read again in the transcript. Both
* halves, through the real fold, session lock and receipts.
* Synthetic sessions only (acme/shop, acme-cli).
*/
import { after, test } from "node:test";
import assert from "node:assert/strict";
import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { said } from "./trace-fixtures.js";
import { T, append, ctxAt, prompt, state, where } from "./skills-consent-fixtures.js";
import { OTHER, blockRun, cleanup, keptSkill, mk, needsFix, offerAtStop, runUpdate, sayLines, updateCmd } from "./skills-update-fixtures.js";
import { getSkillState } from "../src/skills/state.js";
import { readLedger } from "../src/skills/ledger.js";
import { listVersions, versionsDir } from "../src/skills/versions.js";
import { skillHash } from "../src/skills/skillmd.js";
import { readRunSheet } from "../src/trace/runs.js";
import { withSkillSession } from "../src/trace/skill-session.js";
import { UPDATE_DENY, foldInputFor } from "../src/skills/update-gate.js";
after(cleanup);
/** Kept, used, offered at Stop, the offer said, and the person's yes typed. */
function yesToUpdate(opts: { say?: boolean; answer?: string } = {}) {
const b = mk();
const { ref, skill } = keptSkill(b);
blockRun(b, skill, 100);
const o = offerAtStop(b, 150);
if (opts.say !== false) sayLines(b, 152, o.offer);
prompt(b, 160, opts.answer ?? "yes");
return { b, ref, skill, ...o };
}
test("the plan behind the offer: step 4 becomes the publish that worked", () => {
const { plan } = yesToUpdate();
assert.equal(plan.plan?.op, "update");
assert.equal(plan.next.steps[3]!.cmd, OTHER("{version}"));
assert.equal(plan.next.meta.version, "2");
assert.equal(plan.handEdited, false);
});
test("a yes to the offer: the receipt, then v2 written, v1 kept, the ledger's changed line, candidate again, the receipt used once", () => {
const { b, ref, offer } = yesToUpdate();
const v1 = readFileSync(ref.file, "utf8");
const r = runUpdate(b, 170, updateCmd(offer));
assert.equal(r.decision, null);
assert.equal(r.cli?.code, 0, r.cli?.lines.join("\n"));
assert.deepEqual(r.cli!.lines, [
`✓ changed release-npm to v2 · step 4 is now '${OTHER("{version}")}'`,
`Tell the person what Trail changed: release-npm is now v2: step 4 is now '${OTHER("{version}")}'. It's a candidate again until its next checked use. The old version is kept; to go back: trail skills restore release-npm --version 1`,
]);
assert.equal(r.cli!.op, "update");
assert.equal(readFileSync(join(versionsDir(ref), "v1", "SKILL.md"), "utf8"), v1);
assert.match(readFileSync(ref.file, "utf8"), /npm publish \.\/dist\/acme-cli-\{version\}\.tgz/);
const st = getSkillState(ref.id, b.env)!;
assert.equal(st.status, "candidate");
assert.equal(st.hash, skillHash(readFileSync(ref.file, "utf8")));
const changed = readLedger(ref.id, b.env).filter((l) => l.event === "changed");
assert.deepEqual(changed.map((l) => l.event === "changed" && [l.op, l.from, l.to, l.offerId]), [["update", 1, 2, offer.offerId]]);
assert.equal(state(b).pendingOffer, null, "the consent is spent with the write");
const again = runUpdate(b, 180, updateCmd(offer), { skipHook: true });
assert.deepEqual(again.cli?.lines, [UPDATE_DENY.noYes]);
assert.deepEqual(listVersions(ref), [1]);
});
/* ---------------------------------------------------------- PreToolUse half */
test("no pending offer, another offer's id, or a moment 2 offer's id: denied, no receipt", () => {
const { b, offer } = yesToUpdate();
const other = runUpdate(b, 170, `trail skills update release-npm --offer o-ffffff`);
assert.equal(other.decision?.reason, UPDATE_DENY.noOffer);
const c = mk();
keptSkill(c);
assert.equal(runUpdate(c, 50, updateCmd(offer)).decision?.reason, UPDATE_DENY.noOffer);
// A moment 2 offer pending under that id.
withMoment(b, "repeated");
assert.equal(runUpdate(b, 175, updateCmd(offer)).decision?.reason, UPDATE_DENY.noOffer);
const dir = join(b.env.TRAIL_HOME!, "receipts");
assert.ok(!existsSync(dir) || !readdirSync(dir).some((n) => n.endsWith(".update.json")));
});
function withMoment(b: ReturnType<typeof mk>, moment: "repeated") {
withSkillSession(ctxAt(b, 0), { catchUp: false }, (st) => { st.pendingOffer!.moment = moment; });
}
test("another skill's name names the right command", () => {
const { b, offer } = yesToUpdate();
assert.equal(runUpdate(b, 170, updateCmd(offer, "ship-web")).decision?.reason,
`trail · not changed: the offer was for the skill release-npm. Run: trail skills update release-npm --offer ${offer.offerId}`);
});
test("no typed yes, a no, or a yes whose reply before it doesn't end with line 2 (D72): denied", () => {
{
const b = mk();
const { skill } = keptSkill(b);
blockRun(b, skill, 100);
const { offer } = offerAtStop(b, 150);
sayLines(b, 152, offer);
assert.equal(runUpdate(b, 170, updateCmd(offer)).decision?.reason, UPDATE_DENY.noYes);
}
{
const { b, offer } = yesToUpdate({ say: false });
assert.equal(runUpdate(b, 170, updateCmd(offer)).decision?.reason, UPDATE_DENY.noYes);
}
{
const b = mk();
const { skill } = keptSkill(b);
blockRun(b, skill, 100);
const { offer } = offerAtStop(b, 150);
sayLines(b, 152, offer, { after: "\n\nAlso, should I bump the docs too?" });
prompt(b, 160, "yes");
assert.equal(runUpdate(b, 170, updateCmd(offer)).decision?.reason, UPDATE_DENY.noYes);
}
});
test("a yes typed before the offer was shown is no yes to it", () => {
const b = mk();
const { skill } = keptSkill(b);
blockRun(b, skill, 100);
const { offer } = offerAtStop(b, 150);
sayLines(b, 152, offer);
prompt(b, 160, "yes");
// The offer re-stamped as shown later than the typed line.
withSkillSession(ctxAt(b, 0), { catchUp: false }, (st) => { st.pendingOffer!.shownAt = T(300).toISOString(); });
assert.equal(runUpdate(b, 310, updateCmd(offer)).decision?.reason, UPDATE_DENY.noYes);
});
test("the file changed after the offer (baseHash), or the run sheet edited after it (proposalSha): not changed", () => {
{
const { b, ref, offer } = yesToUpdate();
writeFileSync(ref.file, readFileSync(ref.file, "utf8").replace("npm run build", "npm run build:prod"));
assert.equal(runUpdate(b, 170, updateCmd(offer)).decision?.reason,
"trail · not changed: release-npm changed since Trail showed this, so nothing changed. The person can see it with: trail skills show release-npm");
}
{
const { b, offer, runId } = yesToUpdate();
const sheet = readRunSheet(runId, b.env)!;
const i = sheet.calls.findIndex((c) => c.cmd === OTHER("1.4.4"));
sheet.calls[i] = { ...sheet.calls[i]!, cmd: "npm publish ./dist/acme-cli-1.4.4.tgz --access public --tag next" };
writeFileSync(join(b.env.TRAIL_HOME!, "runs", `${runId}.json`), JSON.stringify(sheet));
assert.match(runUpdate(b, 170, updateCmd(offer)).decision?.reason ?? "", /changed since Trail showed this/);
}
});
test("each pin on its own: an offer whose baseHash, or whose proposalSha, isn't the replan's is not changed", () => {
for (const pin of ["baseHash", "proposalSha"] as const) {
const { b, offer } = yesToUpdate();
withSkillSession(ctxAt(b, 165), { catchUp: false }, (st) => {
st.pendingOffer!.fold![pin] = pin === "baseHash" ? `sha256:${"0".repeat(64)}` : "0".repeat(16);
});
assert.match(runUpdate(b, 170, updateCmd(offer)).decision?.reason ?? "", /changed since Trail showed this/, pin);
}
});
test("R4: a new step whose call doesn't read back in the transcript as it worked is refused", () => {
const { b, offer, runId } = yesToUpdate();
// The publish that worked, its result rewritten in place (same length, so every offset holds): the sheet still says it passed.
const call = readRunSheet(runId, b.env)!.calls.find((c) => c.cmd === OTHER("1.4.4"))!;
const text = readFileSync(b.tx, "utf8");
const at = text.indexOf(`"tool_use_id":"${call.id}"`);
const line = text.slice(text.lastIndexOf("\n", at) + 1, text.indexOf("\n", at));
const bad = line.replace('"content":"+ [email protected]"', '"content":"npm error code 1"');
assert.notEqual(bad, line);
writeFileSync(b.tx, text.replace(line, bad));
assert.equal(runUpdate(b, 170, updateCmd(offer)).decision?.reason, `trail · not changed: these steps never ran here and worked: ${OTHER("{version}")}.`);
});
test("a subagent, a headless session and tier B are each denied", () => {
const { b, offer } = yesToUpdate();
assert.equal(runUpdate(b, 170, updateCmd(offer), { ctx: { ...ctxAt(b, 170), subagent: true } }).decision?.reason, UPDATE_DENY.subagent);
assert.equal(runUpdate(b, 171, updateCmd(offer), { ctx: { ...ctxAt(b, 171), entry: "headless", learn: false, learnOff: "headless" } }).decision?.reason, UPDATE_DENY.noPerson);
assert.equal(runUpdate(b, 172, updateCmd(offer), { ctx: { ...ctxAt(b, 172), tier: "B", learn: false, learnOff: "host" } }).decision?.reason, UPDATE_DENY.noPerson);
});
test("a chained update, root options and a `$x` name are denied as not one plain update", () => {
const { b, offer } = yesToUpdate();
for (const cmd of [`true && ${updateCmd(offer)}`, `trail --json skills update release-npm --offer ${offer.offerId}`, `trail skills update $x --offer ${offer.offerId}`]) {
assert.equal(runUpdate(b, 170, cmd).decision?.reason, UPDATE_DENY.flags, cmd);
}
});
test("the receipt is written once, for this offer, with the two hashes and no step text", () => {
const { b, offer } = yesToUpdate();
runUpdate(b, 170, updateCmd(offer), { name: "never-run" });
const files = readdirSync(join(b.env.TRAIL_HOME!, "receipts")).filter((n) => n.endsWith(".update.json"));
assert.equal(files.length, 1);
const r = JSON.parse(readFileSync(join(b.env.TRAIL_HOME!, "receipts", files[0]!), "utf8"));
assert.deepEqual(Object.keys(r).sort(), ["at", "baseHash", "host", "kind", "name", "offerId", "op", "proposalSha", "runId", "session", "skillId", "toolUseId", "transcriptPath", "typed", "usedAt", "v"]);
assert.equal(r.proposalSha, offer.fold!.proposalSha);
assert.ok(!JSON.stringify(r).includes("npm publish"));
});
/* ------------------------------------------------------------------ CLI half */
test("CLI: no receipt, or one naming another transcript (D82), changes nothing", () => {
const { b, ref, offer } = yesToUpdate();
assert.deepEqual(runUpdate(b, 170, updateCmd(offer), { skipHook: true }).cli?.lines, [UPDATE_DENY.noYes]);
runUpdate(b, 175, updateCmd(offer), { name: "nobody" });
const path = join(b.env.TRAIL_HOME!, "receipts", readdirSync(join(b.env.TRAIL_HOME!, "receipts")).find((n) => n.endsWith(".update.json"))!);
const r = JSON.parse(readFileSync(path, "utf8"));
writeFileSync(join(b.root, "copy.jsonl"), readFileSync(b.tx));
writeFileSync(path, JSON.stringify({ ...r, name: "release-npm", transcriptPath: join(b.root, "copy.jsonl") }));
assert.deepEqual(runUpdate(b, 180, updateCmd(offer), { skipHook: true }).cli?.lines, [UPDATE_DENY.transcript]);
assert.deepEqual(listVersions(ref), []);
});
test("CLI: a receipt older than 30 minutes, the typed line gone, or the run sheet gone changes nothing", () => {
{
const { b, ref, offer } = yesToUpdate();
const r = runUpdate(b, 170, updateCmd(offer), { cliAt: 170 + 31 * 60 });
assert.deepEqual(r.cli?.lines, [UPDATE_DENY.noYes]);
assert.deepEqual(listVersions(ref), []);
}
{
const { b, ref, offer } = yesToUpdate();
const lines = readFileSync(b.tx, "utf8").split("\n");
const at = lines.findIndex((l) => l.includes('"yes"') && l.includes('"type":"user"'));
lines[at] = lines[at]!.replace('"yes"', '"no!"');
writeFileSync(b.tx, lines.join("\n"));
const r = runUpdate(b, 170, updateCmd(offer), { skipHook: true });
assert.equal(r.cli?.code, 1);
assert.deepEqual(listVersions(ref), []);
}
{
const { b, ref, offer, runId } = yesToUpdate();
// PreToolUse passes, then the sheet is pruned before the CLI runs.
const r = runUpdate(b, 170, updateCmd(offer), { name: "nobody" });
assert.equal(r.decision, null);
rmSync(join(b.env.TRAIL_HOME!, "runs", `${runId}.json`));
const path = join(b.env.TRAIL_HOME!, "receipts", readdirSync(join(b.env.TRAIL_HOME!, "receipts")).find((n) => n.endsWith(".update.json"))!);
const rec = JSON.parse(readFileSync(path, "utf8"));
writeFileSync(path, JSON.stringify({ ...rec, name: "release-npm", usedAt: null }));
const cli = runUpdate(b, 180, updateCmd(offer), { skipHook: true });
assert.equal(cli.cli?.code, 1);
assert.deepEqual(listVersions(ref), []);
}
});
test("CLI: the file changed between the halves changes nothing, and the receipt is spent", () => {
const { b, ref, offer } = yesToUpdate();
const r1 = runUpdate(b, 170, updateCmd(offer), { name: "nobody" });
assert.equal(r1.decision, null);
writeFileSync(ref.file, `${readFileSync(ref.file, "utf8")}\nMine.\n`);
const path = join(b.env.TRAIL_HOME!, "receipts", readdirSync(join(b.env.TRAIL_HOME!, "receipts")).find((n) => n.endsWith(".update.json"))!);
const rec = JSON.parse(readFileSync(path, "utf8"));
writeFileSync(path, JSON.stringify({ ...rec, usedAt: null }));
const r2 = runUpdate(b, 180, updateCmd(offer), { skipHook: true });
assert.match(r2.cli?.lines[0] ?? "", /changed since Trail showed this/);
assert.deepEqual(listVersions(ref), []);
assert.notEqual(JSON.parse(readFileSync(path, "utf8")).usedAt, null);
});
/* -------------------------------------------------------- drift and hand edits */
test("drift's replace on a needs-fix skill: v2 is the fresh compile, failures cleared, candidate", () => {
const b = mk();
const { ref, skill } = keptSkill(b);
needsFix(b);
blockRun(b, skill, 100);
const { offer, plan } = offerAtStop(b, 150, "replace");
sayLines(b, 152, offer);
prompt(b, 160, "yes");
const r = runUpdate(b, 170, updateCmd(offer));
assert.equal(r.cli?.code, 0, r.decision?.reason ?? r.cli?.lines.join("\n"));
assert.equal(r.cli!.op, "replace");
assert.match(r.cli!.lines[0]!, /^✓ changed release-npm to v2 · the \d steps that just worked replace the old ones$/);
assert.equal(readFileSync(ref.file, "utf8"), plan.text);
const st = getSkillState(ref.id, b.env)!;
assert.deepEqual([st.status, st.statusWhy, st.prevStatus], ["candidate", undefined, undefined]);
});
test("J15 D's shape: a hand-edited skill gets only a proposal, the diff and the person's cp line", () => {
const b = mk();
const { ref, skill } = keptSkill(b);
const mine = `${readFileSync(ref.file, "utf8")}\nMy own note: the mirror is slow.\n`;
writeFileSync(ref.file, mine);
needsFix(b);
blockRun(b, skill, 100);
const { offer } = offerAtStop(b, 150, "replace");
assert.equal(offer.fold!.handEdited, true);
sayLines(b, 152, offer);
prompt(b, 160, "yes");
const r = runUpdate(b, 170, updateCmd(offer));
assert.equal(r.cli?.code, 0, r.decision?.reason ?? r.cli?.lines.join("\n"));
assert.equal(r.cli!.proposal, true);
assert.equal(readFileSync(ref.file, "utf8"), mine, "the person's file is never written");
const last = r.cli!.lines.at(-1)!;
assert.equal(last, "Tell the person: you changed release-npm by hand, so Trail left it alone and wrote the change beside it. To use it, they run this in their own terminal: cp ~/trail-home/skills/release-npm/.versions/proposed-v2/SKILL.md ~/trail-home/skills/release-npm/SKILL.md (their edited file is kept in .versions/hand-2026-10-27)");
assert.match(r.cli!.lines[0]!, /^--- release-npm\/SKILL\.md \(yours\)$/);
assert.ok(r.cli!.lines.length <= 41);
assert.ok(existsSync(join(versionsDir(ref), "proposed-v2", "SKILL.md")));
assert.equal(getSkillState(ref.id, b.env)!.status, "needs-fix", "J15 D: it stays needs-fix until the person copies it");
});
void said;
void append;
void where;
test("after show me, the yes answers line 2 asked again (c3's show directive), never 1a's Keep it?", () => {
for (const [ask, code] of [["line2", 0], ["keep", 1]] as const) {
const b = mk();
const { skill } = keptSkill(b);
blockRun(b, skill, 100);
const { offer } = offerAtStop(b, 150);
sayLines(b, 152, offer);
prompt(b, 160, "show me");
append(b, [said(`Here is the change.\n\n${ask === "line2" ? offer.lines![1] : "Keep it? (yes / no)"}`, where(b, 165))]);
prompt(b, 170, "yes");
const r = runUpdate(b, 180, updateCmd(offer));
assert.equal(r.cli?.code ?? 1, code, `${ask}: ${r.decision?.reason ?? r.cli?.lines.join("\n")}`);
}
});
test("drift: 'keep it' is no yes to replace (it means leave it)", () => {
const b = mk();
const { skill } = keptSkill(b);
needsFix(b);
blockRun(b, skill, 100);
const { offer } = offerAtStop(b, 150, "replace");
sayLines(b, 152, offer);
prompt(b, 160, "keep it");
const r = runUpdate(b, 170, updateCmd(offer));
assert.notEqual(r.decision, null);
});
test("c8: the fold input names the store's taken names, so a split's fallback name is free (FoldInput.taken)", () => {
const b = mk();
const { skill } = keptSkill(b);
blockRun(b, skill, 100);
const { runId } = offerAtStop(b, 150);
const fi = foldInputFor("s-7f3a2c", runId, b.env, { st: null as never });
assert.ok(fi, "the input builds from disk");
assert.equal(typeof fi!.taken, "function");
assert.equal(fi!.taken!("release-npm"), true, "the kept skill's own name is taken");
assert.equal(fi!.taken!("release-npm-2"), false);
});