pi-gauntlet 8.2.1 → 8.4.0

package/extensions/telemetry-leg.test.ts

@@ -0,0 +1,151 @@
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, test } from "node:test";
+import { parse } from "yaml";
+import { isolatedGitEnv } from "./test-support/git-env.mjs";
+import { resolveTelemetry } from "./lib/gauntlet-settings.ts";
+import type { ReadToolCallEvent } from "@earendil-works/pi-coding-agent";
+
+const gitEnv = isolatedGitEnv(mkdtempSync(join(tmpdir(), "telemetry-leg-env-")));
+const originalGitEnv = Object.fromEntries(Object.keys(gitEnv).map(key => [key, process.env[key]]));
+Object.assign(process.env, gitEnv);
+// vcs.ts snapshots the environment at import time, including publisher subprocess settings.
+const { default: registerTelemetry, realDeps } = await import("./telemetry.ts");
+const { registerLegTelemetry } = await import("./lib/telemetry-leg.ts");
+
+const ref = "refs/heads/gauntlet/telemetry";
+const originalDepth = process.env.PI_SUBAGENT_DEPTH;
+process.env.PI_SUBAGENT_DEPTH = "0";
+after(() => {
+  for (const [key, value] of Object.entries(originalGitEnv)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+  if (originalDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH;
+  else process.env.PI_SUBAGENT_DEPTH = originalDepth;
+});
+
+for (const skill of ["shape-ticket", "gatekeep-pr", "check-delivery"] as const) {
+  test(`${skill} read tool_call opens a leg before any tool_result`, async () => {
+    const handlers = new Map<string, (event: unknown, ctx: unknown) => unknown>();
+    const live = registerLegTelemetry({
+      on: (name: string, handler: (event: unknown, ctx: unknown) => unknown) => handlers.set(name, handler),
+    } as any, {
+      ...realDeps,
+      now: () => "2026-11-06T12:34:56Z",
+      settings: () => ({ telemetry: resolveTelemetry({}), specDirs: [], planDirs: [], errors: [], versions: {} }),
+    }, () => false);
+    const ctx = { cwd: tmpdir(), sessionManager: { getSessionId: () => `session-${skill}` } };
+    const event: ReadToolCallEvent = {
+      type: "tool_call", toolCallId: "load-skill", toolName: "read",
+      input: { path: `/package/skills/${skill}/SKILL.md` },
+    };
+    assert.equal(live(), undefined);
+    await handlers.get("tool_call")!(event, ctx);
+    assert.ok(live(), "the read call must open the accumulator without waiting for a result");
+  });
+}
+
+// Real plumbing stays local: origin's portable identity is rewritten to a scratch bare repo.
+function harness(skill: string) {
+  const scratch = mkdtempSync(join(tmpdir(), "telemetry-leg-"));
+  const root = join(scratch, "product");
+  const origin = join(scratch, "origin.git");
+  mkdirSync(root);
+  const git = (cwd: string, ...args: string[]) => execFileSync("git", ["-C", cwd, "-c", "commit.gpgsign=false", ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  git(scratch, "init", "--bare", origin);
+  git(root, "init", "-b", "feature/example");
+  git(root, "config", "user.name", "Leg Tester");
+  git(root, "config", "user.email", "leg@example.test");
+  git(root, "remote", "add", "origin", "https://example.test/team/product.git");
+  git(root, "config", `url.${origin}.insteadOf`, "https://example.test/team/product.git");
+  writeFileSync(join(root, "file.txt"), "base\n");
+  git(root, "add", "file.txt");
+  git(root, "commit", "-m", "initial");
+  writeFileSync(join(root, "file.txt"), "staged user change\n");
+  git(root, "add", "file.txt");
+  writeFileSync(join(root, "file.txt"), "unstaged user change\n");
+  const head = git(root, "rev-parse", "HEAD");
+  const index = readFileSync(join(root, ".git/index"));
+  const handlers = new Map<string, ((event: any, ctx: any) => unknown)[]>();
+  const messages: unknown[] = [];
+  const ctx = { cwd: root, sessionManager: { getBranch: () => [], getSessionId: () => `session-${skill}` } };
+  registerTelemetry({
+    on: (name: string, handler: (event: any, ctx: any) => unknown) => handlers.set(name, [...(handlers.get(name) ?? []), handler]),
+    sendMessage: (message: unknown) => messages.push(message),
+  } as any, {
+    ...realDeps,
+    now: () => "2026-11-06T12:34:56Z",
+    settings: () => ({ telemetry: resolveTelemetry({}), specDirs: [], planDirs: [], errors: [], versions: { "pi-gauntlet": "8.2.1" } }),
+  });
+  const emit = async (name: string, event: unknown = {}) => {
+    for (const handler of handlers.get(name) ?? []) await handler(event, ctx);
+  };
+  const say = (text: string) => emit("message_end", { message: { role: "assistant", content: [{ type: "text", text }] } });
+  const hasRecord = () => spawnSync("git", ["-C", origin, "rev-parse", "--verify", ref], { stdio: "ignore" }).status === 0;
+  return { root, origin, git, head, index, emit, say, hasRecord, messages };
+}
+
+for (const [skill, outcome, activation, empty] of [
+  ["shape-ticket", "created", "input"],
+  ["gatekeep-pr", "approved", "expanded"],
+  ["check-delivery", "delivered", "read"],
+  ["gatekeep-pr", "stopped", "input"],
+  ["shape-ticket", "written", "input", true],
+] as const) {
+  test(`${skill} ${outcome}${empty ? " with no items" : ""} seals one session leg only after the final settlement and follow-on work`, async () => {
+    const marker = outcome === "stopped" ? "stuck" : "done";
+    const h = harness(skill);
+    await h.emit("session_start");
+    // Terminal-looking text outside a selected skill is not a leg.
+    await h.say(`gauntlet: done ${outcome}\n#42: ${outcome}`);
+    await h.emit("agent_settled", { aborted: false });
+    assert.equal(h.hasRecord(), false);
+    if (activation === "input") await h.emit("input", { text: `/skill:${skill} create a ticket`, source: "interactive" });
+    if (activation === "expanded") await h.emit("before_agent_start", { messageType: "user", prompt: `<skill name="${skill}" location="/package/skills/${skill}/SKILL.md">\nInstructions\n</skill>\n\n#42` });
+    if (activation === "read") await h.emit("tool_call", { type: "tool_call", toolName: "read", toolCallId: "load-skill", input: { path: `/package/skills/${skill}/SKILL.md` } });
+    await h.say("gauntlet: gate approval\n1. Approve\n2. Decline");
+    await h.emit("agent_settled", { aborted: false });
+    assert.equal(h.hasRecord(), false, "human gate is not completion");
+    await h.say(`gauntlet: done ${outcome}\n#42: ${outcome}`);
+    await h.emit("agent_end");
+    assert.equal(h.hasRecord(), false, "agent_end can precede follow-on work");
+    await h.emit("tool_call", { toolName: "bash", toolCallId: "follow-on", input: { command: "write approved result" } });
+    await h.emit("tool_result", { toolName: "bash", toolCallId: "follow-on", input: {}, isError: false, content: [] });
+    await h.say("Follow-on assessment is still running.");
+    await h.emit("agent_settled", { aborted: false });
+    assert.equal(h.hasRecord(), false, "an earlier terminal message cannot settle follow-on work");
+    await h.say(`gauntlet: ${marker} ${outcome}\n#42: ${outcome}`);
+    await h.emit("agent_settled", { aborted: true });
+    assert.equal(h.hasRecord(), false, "aborting is not a terminal settlement");
+    await h.emit("message_end", { message: {
+      role: "assistant", content: [{ type: "text", text: `gauntlet: ${marker} ${outcome}${empty ? "\nworktree: done\nNo settled items." : `\n#42: ${outcome}`}` }],
+      usage: { input: 12, output: 4, cost: 0.125 },
+    } });
+    await h.emit("agent_settled", { aborted: false });
+    assert.equal(h.hasRecord(), true, "final settlement must push a leg record even without items");
+    const path = `team/product/${skill}/20261106T123456Z-session-${skill}.yaml`;
+    assert.equal(h.git(h.origin, "ls-tree", "-r", "--name-only", ref), path);
+    const record = parse(h.git(h.origin, "show", `${ref}:${path}`));
+    assert.equal(record.skill, skill);
+    assert.equal(record.session, `session-${skill}`);
+    assert.equal(record.repo, "team/product");
+    assert.equal(record.ts, "2026-11-06T12:34:56Z");
+    assert.deepEqual(record.items, empty ? [] : [{ kind: skill === "gatekeep-pr" ? "pr" : "ticket", key: "#42", outcome }]);
+    assert.equal(record.cost, 0.125);
+    assert.equal(record.tokens.input, 12);
+    const tip = h.git(h.origin, "rev-parse", ref);
+    await h.emit("agent_settled", { aborted: false });
+    await h.say(`gauntlet: done settled\n#43: ${outcome}`);
+    await h.emit("agent_settled", { aborted: false });
+    await h.emit("session_shutdown");
+    assert.equal(h.git(h.origin, "rev-parse", ref), tip, "duplicate lifecycle events do not append records");
+    assert.equal(h.git(h.root, "rev-parse", "HEAD"), h.head);
+    assert.deepEqual(readFileSync(join(h.root, ".git/index")), h.index);
+    assert.equal(readFileSync(join(h.root, "file.txt"), "utf8"), "unstaged user change\n");
+    assert.equal(h.git(h.root, "rev-parse", ref), tip);
+  });
+}

package/extensions/telemetry-settlement-contract.test.ts

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync } from "node:fs";
+import test from "node:test";
+import { settlementItems } from "./lib/telemetry-leg.ts";
+import { MODELS } from "../eval/lib/models.mjs";
+
+const read = (path: string) => readFileSync(new URL(`../${path}`, import.meta.url), "utf8");
+const head = "abc123456789abcdef0123456789abcdef01234567";
+const otherHead = "def123456789abcdef0123456789abcdef01234567";
+
+for (const [skill, items] of [
+  ["shape-ticket", [{ kind: "ticket", key: "#83", outcome: "written" }]],
+  ["gatekeep-pr", [
+    { kind: "pr", key: `#31@${head}`, ticket: "#12", outcome: "merged" },
+    { kind: "pr", key: `#32@${otherHead}`, outcome: "stuck - CI pending past 15 minutes" },
+  ]],
+  ["check-delivery", [{ kind: "ticket", key: "#52", outcome: "delivered" }]],
+] as const) {
+  test(`${skill} selected eval replies parse into settled item identities`, () => {
+    const result = JSON.parse(read(`eval/${skill}/results/per-ref-settlement/candidate.json`));
+    for (const model of MODELS.replay) {
+      const output = result.outputs[model];
+      assert.equal(output?.status, "ok", output?.error ?? model);
+      assert.match(output.text, /^gauntlet: (done|stuck)\b/);
+      assert.equal(output.text.match(/^gauntlet: (done|stuck)\b/gm)?.length, 1);
+      assert.deepEqual(settlementItems(skill, output.text), items, model);
+      assert.ok(Object.values(output.mechanical).every((value) => value === "holds"), model);
+      assert.ok(["improved", "unchanged"].includes(result.judge[model]?.verdict), model);
+    }
+  });
+}
+
+test("skill owners keep terminal rows after writes and cleanup", () => {
+  const shape = read("skills/shape-ticket/reference/repo-audit.md");
+  assert.match(shape, /actual ref returned by the write/);
+  assert.doesNotMatch(shape, /use the drafted title for create/);
+  assert.match(shape, /after every selected write/);
+  const delivery = read("skills/check-delivery/SKILL.md");
+  assert.match(delivery, /<ref>: <outcome>/);
+  assert.match(delivery, /already recorded/);
+  const gate = read("skills/gatekeep-pr/reference/post-selection-loop.md");
+  assert.ok(gate.includes("#<N>@<head sha>: <outcome>"));
+  assert.match(gate, /full assessed `headRefOid`/);
+  assert.match(gate, /cleanup pick is answered/);
+  assert.match(read("skills/gatekeep-pr/reference/batch.md"), /gauntlet: retired #<N> - <reason>/);
+  assert.match(read("skills/gatekeep-pr/reference/cleanup.md"), /### Settlement rows/);
+  const ci = read("scripts/ci.mjs");
+  assert.ok(ci.includes('includes("#<N>@<head sha>: <outcome>")'));
+  assert.ok(ci.includes("gatekeep-pr must not mention telemetry"));
+  for (const file of readdirSync(new URL("../skills/gatekeep-pr/", import.meta.url), { recursive: true })) {
+    if (file.endsWith(".md")) assert.doesNotMatch(read(`skills/gatekeep-pr/${file}`), /telemetry/i);
+  }
+});
+
+test("configuration names the settlement grammar and per-skill tokens", () => {
+  const docs = read("doc/configuration.md");
+  assert.ok(docs.includes("<ref>: <outcome>[ (<ticket ref>)]"));
+  for (const tokens of [
+    ["shape-ticket", "written", "closed", "close failed (<operation>: <reason>)", "close by hand", "dropped", "declined", "stopped", "no-op", "unfetched"],
+    ["gatekeep-pr", "approved", "merged", "closed-pr", "final", "merge-queued", "stuck - <reason>"],
+    ["check-delivery", "delivered", "manual", "declined", "already recorded", "skipped", "failed - <reason>"],
+  ]) {
+    const row = docs.split("\n").find((line) => line.startsWith(`| ${tokens[0]} |`));
+    assert.ok(row, tokens[0]);
+    for (const token of tokens.slice(1)) assert.ok(row.includes(`\`${token}\``), token);
+  }
+});

package/extensions/telemetry.test.ts

@@ -20,7 +20,7 @@
 
   type Handler = (event: any, ctx: any) => unknown;
 
-  function harness(o: { branch?: unknown[]; enabled?: boolean; gitFail?: (args: string[], cwd: string) => GitResult | undefined; jjWorkspace?: boolean; jjFail?: (args: string[], cwd: string) => GitResult | undefined; cwdSub?: string; sessionId?: string; model?: { provider: string; id: string }; thinkingLevel?: string; contextTokens?: number | null; telemetryWarning?: string; telemetryDir?: string } = {}) {
+  function harness(o: { branch?: unknown[]; enabled?: boolean; gitFail?: (args: string[], cwd: string) => GitResult | undefined; jjWorkspace?: boolean; jjFail?: (args: string[], cwd: string) => GitResult | undefined; cwdSub?: string; sessionId?: string; model?: { provider: string; id: string }; thinkingLevel?: string; contextTokens?: number | null; telemetryWarning?: string } = {}) {
     const root = mkdtempSync(join(tmpdir(), "telemetry-test-"));
     tempDirs.push(root);
     mkdirSync(join(root, "doc/specs"), { recursive: true });
@@ -33,8 +33,11 @@
     const jjCalls: string[][] = [];
     const readFileCalls: string[] = [];
     const specDirs = resolveFlowGuards({}).specDirs;
+    const fetchedRecords = new Map<string, string>();
     let clock = Date.parse("2026-09-17T10:00:00Z");
     const deps: Deps = {
+      telemetryRepo: () => "test/repo",
+      readTelemetryBranch: () => ({ records: [...fetchedRecords].map(([path, bytes]) => ({ path, bytes })) }),
       fs: { ...realFs, readFile: (p) => { readFileCalls.push(p); return realFs.readFile(p); } },
       now: () => new Date((clock += 1000)).toISOString().replace(/\.\d{3}Z$/, "Z"),
       git: async (args, cwd) => {
@@ -58,7 +61,7 @@
         if (args[0] === "ls-files") return { code: 0, stdout: "", stderr: "" };
         return { code: 0, stdout: "", stderr: "" };
       },
-      settings: () => ({ specDirs, planDirs: planDirsFor(specDirs), telemetry: { enabled: o.enabled ?? true, dir: o.telemetryDir ?? ".pi/gauntlet/telemetry", buckets: DEFAULT_TELEMETRY_BUCKETS, warning: o.telemetryWarning }, errors: [], agentOverrides: { implementer: { model: "p/x" } }, versions: { pi: "0.85.1" } }),
+      settings: () => ({ specDirs, planDirs: planDirsFor(specDirs), telemetry: { enabled: o.enabled ?? true, buckets: DEFAULT_TELEMETRY_BUCKETS, warning: o.telemetryWarning }, errors: [], agentOverrides: { implementer: { model: "p/x" } }, versions: { pi: "0.85.1" } }),
       // A plain jj workspace: `jj root` answers the temp root while git rev-parse fails.
       jj: async (args, cwd) => {
         jjCalls.push(args);
@@ -83,7 +86,7 @@
       for (const h of handlers.get(name) ?? []) out.push(await h(event, ctx));
       return out;
     };
-    const recordPath = (spec = "doc/specs/a.md") => join(ctx.cwd, ".pi/gauntlet/telemetry", spec.replace(/\.md$/, ".yaml"));
+    const recordPath = (spec = "doc/specs/a.md") => join(ctx.cwd.replace(/\/\.worktrees\/.*$/, ""), o.jjWorkspace ? ".jj/gauntlet/telemetry" : ".git/gauntlet/telemetry", spec.replace(/\.md$/, ".yaml"));
     const readRecord = (spec?: string) => parseRecord(readFileSync(recordPath(spec), "utf8"))!;
     const gitWrites = () => gitCalls.filter((a) => a[0] === "add" || a[0] === "commit");
     const excludeFile = () => join(root, ".git/info/exclude");
@@ -97,7 +100,7 @@
       await emit("tool_call", { toolName: "write", toolCallId: "w", input: { path: rel, content: body } });
       return emit("tool_result", { toolName: "write", toolCallId: "w", input: { path: rel, content: body }, content: [], isError: false, details: undefined });
     };
-    return { root, handlers, emit, gitCalls, gitCwds, jjCalls, readFileCalls, gitWrites, excludeFile, bash, recordPath, readRecord, phaseResult, writeSpec, setBranch: (b: unknown[]) => (branch = b), ctx };
+    return { fetchedRecords, root, handlers, emit, gitCalls, gitCwds, jjCalls, readFileCalls, gitWrites, excludeFile, bash, recordPath, readRecord, phaseResult, writeSpec, setBranch: (b: unknown[]) => (branch = b), ctx };
   }
 
   const P = (over: Record<string, string> = {}) => Object.fromEntries(["brainstorm", "plan", "implement", "verify", "ship"].map((p) => [p, { status: over[p] ?? "pending" }]));
@@ -151,7 +154,7 @@
     }
   });
 
-  test("bind on first spec write flushes buffered phase event, mints run_id, writes the exclude line, never stages or commits", async () => {
+  test("bind on first spec write flushes buffered phase event and mints run_id without excludes, staging or commits", async () => {
     const h = harness();
     await h.emit("session_start", { type: "session_start", reason: "startup" });
     await h.phaseResult("start", P({ brainstorm: "in_progress" }));
@@ -175,19 +178,19 @@
     const rec2 = h.readRecord();
     assert.equal(rec2.approved_at, rec2.events.findLast((e) => e.kind === "phase")!.ts);
     assert.equal(h.gitWrites().length, 0, "the recorder never runs git add or git commit");
-    assert.equal(readFileSync(h.excludeFile(), "utf8"), ".pi/gauntlet/telemetry/\n");
+    assert.equal(existsSync(h.excludeFile()), false);
     await h.phaseResult("reset", P());
     await h.phaseResult("start", P({ brainstorm: "in_progress" }));
     await h.writeSpec("doc/specs/a.md", "# Spec again\n");
-    assert.equal(readFileSync(h.excludeFile(), "utf8"), ".pi/gauntlet/telemetry/\n", "exclude line is written once after rebind");
+    assert.equal(existsSync(h.excludeFile()), false, "rebind never edits excludes");
   });
 
-  test("a docs/specs write binds under the default dirs and the record lands under telemetry.dir/docs/specs", async () => {
+  test("a docs/specs write binds under the common-dir in-progress store", async () => {
     const h = harness();
     await h.phaseResult("start", P({ brainstorm: "in_progress" }));
     assert.equal(existsSync(h.recordPath("docs/specs/x.md")), false);
     await h.writeSpec("docs/specs/x.md");
-    assert.equal(h.recordPath("docs/specs/x.md"), join(h.root, ".pi/gauntlet/telemetry/docs/specs/x.yaml"));
+    assert.equal(h.recordPath("docs/specs/x.md"), join(h.root, ".git/gauntlet/telemetry/docs/specs/x.yaml"));
     assert.equal(h.readRecord("docs/specs/x.md").spec, "docs/specs/x.md");
     await h.phaseResult("complete", P({ brainstorm: "complete" }));
     const rec = h.readRecord("docs/specs/x.md");
@@ -359,7 +362,7 @@
     const rec = h.readRecord("doc/specs/draft.md");
     assert.equal(rec.spec, "doc/specs/draft.md");
     assert.equal(readFileSync(h.recordPath("doc/specs/final.md"), "utf8"), "existing\n");
-    assert.deepEqual(rec.events.filter((e) => e.kind === "warning").map((e: any) => e.message), ["record move skipped: .pi/gauntlet/telemetry/doc/specs/final.yaml already exists"]);
+    assert.deepEqual(rec.events.filter((e) => e.kind === "warning").map((e: any) => e.message), [`record move skipped: ${h.recordPath("doc/specs/final.md")} already exists`]);
   });
 
   test("rename refuses a tracked destination collision and keeps the draft binding", async () => {
@@ -374,9 +377,9 @@
     assert.ok(rec.events.some((e) => e.kind === "warning" && (e as any).message.endsWith("already exists")));
   });
 
-  test("telemetry resolver warning is emitted once while its fallback directory is used", async () => {
-    const message = "telemetry.dir must be a non-empty path relative to the git toplevel; using the default";
-    const h = harness({ telemetryWarning: message, telemetryDir: ".pi/gauntlet/telemetry" });
+  test("telemetry resolver warning is emitted once", async () => {
+    const message = "telemetry.remote must be a non-empty URL; using origin";
+    const h = harness({ telemetryWarning: message });
     await h.phaseResult("start", P({ brainstorm: "in_progress" }));
     await h.writeSpec("doc/specs/a.md");
     await h.writeSpec("doc/specs/a.md", "# Again\n");
@@ -409,11 +412,13 @@
     assert.deepEqual(nogit.readRecord().events.filter((e) => e.kind === "warning").map((e: any) => e.message), [`spec ${outsideSpec} is outside a git checkout; telemetry not recorded`]);
   });
 
-  test("failed git-common-dir lookup warns in the record", async () => {
+  test("failed git-common-dir lookup never falls back to writing inside the checkout", async () => {
     const h = harness({ gitFail: (args) => args.includes("--git-common-dir") && !args.includes("--show-toplevel") ? { code: 1, stdout: "", stderr: "unsupported flag\nmore detail" } : undefined });
     await h.phaseResult("start", P({ brainstorm: "in_progress" }));
     await h.writeSpec("doc/specs/a.md");
-    assert.deepEqual(h.readRecord().events.filter((e) => e.kind === "warning").map((e: any) => e.message), ["exclude skipped: git rev-parse --git-common-dir failed: unsupported flag"]);
+    assert.equal(existsSync(h.recordPath()), false);
+    assert.equal(existsSync(join(h.root, ".pi/gauntlet")), false);
+    assert.equal(existsSync(h.excludeFile()), false);
   });
 
   test("jj-bound checkout: record is written with no warning, no exclude line, and no git add/commit", async () => {
@@ -438,27 +443,27 @@
     await h.phaseResult("start", P({ brainstorm: "in_progress" }));
     await h.writeSpec("doc/specs/a.md");
     const wt = join(h.root, ".worktrees/x");
-    const sealedPath = join(wt, ".pi/gauntlet/telemetry/doc/specs/b.yaml");
-    mkdirSync(join(wt, ".pi/gauntlet/telemetry/doc/specs"), { recursive: true });
-    writeFileSync(sealedPath, serializeRecord({ ...h.readRecord(), spec: "doc/specs/b.md", status: "shipped", shipped_at: "2026-09-17T18:00:00Z" }));
-    const before = readFileSync(sealedPath, "utf8");
+    const sealedPath = "test/repo/brainstorming/doc/specs/b.yaml";
+    const before = serializeRecord({ ...h.readRecord(), spec: "doc/specs/b.md", status: "shipped", shipped_at: "2026-09-17T18:00:00Z" });
+    h.fetchedRecords.set(sealedPath, before);
     await h.emit("tool_result", { toolName: "write", toolCallId: "w", input: { path: join(wt, "doc/specs/b.md"), content: "# B\n" }, content: [], isError: false, details: undefined });
     await h.phaseResult("complete", P({ brainstorm: "complete" }));
     assert.ok(h.readRecord().events.some((e) => e.kind === "phase" && e.action === "complete"));
-    assert.equal(readFileSync(sealedPath, "utf8"), before);
+    assert.equal(h.fetchedRecords.get(sealedPath), before);
   });
 
-  test("worktree spec from a primary cwd: record keyed under the worktree, exclude written to the common dir (AC 8)", async () => {
+  test("worktree spec from a primary cwd uses the common-dir store without changing excludes", async () => {
     const h = harness();
     await h.emit("session_start", { type: "session_start", reason: "startup" });
     await h.phaseResult("start", P({ brainstorm: "in_progress" }));
     await h.writeSpec(".worktrees/x/doc/specs/a.md");
     const wt = join(h.root, ".worktrees/x");
-    assert.ok(existsSync(join(wt, ".pi/gauntlet/telemetry/doc/specs/a.yaml")), "record lives under the worktree toplevel");
+    assert.ok(existsSync(h.recordPath()), "record lives under the shared git common dir");
+    assert.equal(existsSync(join(wt, ".pi/gauntlet")), false);
     assert.equal(existsSync(join(h.root, ".pi/gauntlet")), false, "nothing written under the primary checkout");
     assert.ok(h.gitCwds.every((c) => c === wt || c.startsWith(wt + "/")), "no git call runs in the primary");
     assert.equal(h.gitWrites().length, 0);
-    assert.equal(readFileSync(join(h.root, ".git/info/exclude"), "utf8"), ".pi/gauntlet/telemetry/\n", "exclude lands in the primary's common dir");
+    assert.equal(existsSync(h.excludeFile()), false);
   });
 
   test("a spec in another checkout is a fresh bind, never a git mv", async () => {
@@ -473,7 +478,7 @@
         await h.emit("tool_result", { toolName: "edit", toolCallId: "e", input: { path: "doc/specs/a.md", oldText: "# Old\n", newText: "# Spec\n" }, content: [], isError: false, details: undefined });
       }
       assert.ok(existsSync(h.recordPath("doc/specs/a.md")), `primary record created for ${tool}`);
-      assert.ok(existsSync(join(h.root, ".worktrees/x/.pi/gauntlet/telemetry/doc/specs/a.yaml")), `worktree record left in place for ${tool}`);
+      assert.equal(existsSync(join(h.root, ".worktrees/x/.pi/gauntlet")), false, `no worktree-local record for ${tool}`);
       assert.equal(h.gitCalls.some((a) => a[0] === "mv"), false);
       assert.equal(h.readRecord("doc/specs/a.md").events.some((e) => e.kind === "spec_renamed"), false);
     }
@@ -973,9 +978,10 @@
     const before = readFileSync(h.recordPath(), "utf8");
     const h2 = harness();
     h2.ctx.cwd = h.root;
+    h2.fetchedRecords.set("test/repo/brainstorming/doc/specs/a.yaml", before);
     await h2.phaseResult("start", P({ brainstorm: "in_progress" }));
     const [blocked] = await h2.emit("tool_call", { toolName: "write", toolCallId: "w", input: { path: "doc/specs/a.md" } });
-    assert.deepEqual(blocked, { block: true, reason: guardReason("doc/specs/a.md", rec.shipped_at, ".pi/gauntlet/telemetry/doc/specs/a.yaml") });
+    assert.deepEqual(blocked, { block: true, reason: guardReason("doc/specs/a.md", rec.shipped_at, "gauntlet/telemetry") });
     assert.equal(readFileSync(h.recordPath(), "utf8"), before);
     assert.equal(h.readRecord().derived.spec_edits_after_ship, 0);
   });
@@ -989,8 +995,10 @@
     const before = readFileSync(first.recordPath("doc/specs/old.md"), "utf8");
     const h = harness({ sessionId: "s2" });
     h.ctx.cwd = first.root;
+    h.fetchedRecords.set("test/repo/brainstorming/doc/specs/old.yaml", before);
     await h.phaseResult("start", P({ brainstorm: "in_progress" }));
     await h.writeSpec("doc/specs/old.md");
+    await h.emit("tool_result", { toolName: "plan_check", input: {}, content: [], isError: false, details: { status: "pass", specPath: join(first.root, "doc/specs/old.md") } });
     assert.equal(readFileSync(first.recordPath("doc/specs/old.md"), "utf8"), before);
     assert.equal(existsSync(h.excludeFile()), false);
     await h.writeSpec("doc/specs/new.md");
@@ -1090,7 +1098,7 @@
     assert.equal(h.readRecord().status, "in_progress", "git keep path no longer stamps; the seal bin owns shipped_at");
   });
 
-  test("a sealed on-disk record freezes the recorder: shutdown does not overwrite it", async () => {
+  test("a stamped pending record freezes the recorder on shutdown", async () => {
     const h = await boundInShip();
     const sealed = { ...h.readRecord(), status: "shipped" as const, shipped_at: "2026-09-17T18:00:00Z" };
     writeFileSync(h.recordPath(), serializeRecord(sealed));
@@ -1100,6 +1108,14 @@
     assert.equal(readFileSync(h.recordPath(), "utf8"), before);
   });
 
+  test("a branch-owned record freezes the recorder on shutdown", async () => {
+    const h = await boundInShip();
+    rmSync(h.recordPath());
+    await h.emit("session_compact", { type: "session_compact", reason: "manual" });
+    await h.emit("session_shutdown", { type: "session_shutdown", reason: "quit" });
+    assert.equal(existsSync(h.recordPath()), false, "flush must not recreate a published record");
+  });
+
   test("a frozen record cannot bind another spec through plan_check or another checkout write", async () => {
     const h = await boundInShip();
     writeFileSync(h.recordPath(), serializeRecord({ ...h.readRecord(), status: "shipped", shipped_at: "2026-09-17T18:00:00Z" }));
@@ -1294,9 +1310,10 @@
     const before = readFileSync(h.recordPath(), "utf8");
     const h2 = harness();
     h2.ctx.cwd = h.root;
+    h2.fetchedRecords.set("test/repo/brainstorming/doc/specs/a.yaml", before);
     await h2.phaseResult("start", P({ brainstorm: "in_progress" }));
     const [blocked] = await h2.emit("tool_call", { toolName: "write", toolCallId: "w1", input: { path: "doc/specs/a.md", content: "# again" } });
-    assert.deepEqual(blocked, { block: true, reason: guardReason("doc/specs/a.md", h.readRecord().shipped_at!, ".pi/gauntlet/telemetry/doc/specs/a.yaml") });
+    assert.deepEqual(blocked, { block: true, reason: guardReason("doc/specs/a.md", h.readRecord().shipped_at!, "gauntlet/telemetry") });
     assert.equal(readFileSync(h.recordPath(), "utf8"), before, "shipped record byte-identical");
     const [editPass] = await h2.emit("tool_call", { toolName: "edit", toolCallId: "e1", input: { path: "doc/specs/a.md", edits: [] } });
     assert.equal(editPass, undefined);