pi-gauntlet 5.10.2 → 5.12.0

package/bin/gauntlet-performance.test.mjs

@@ -0,0 +1,350 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const CLI = join(dirname(fileURLToPath(import.meta.url)), "gauntlet-performance.mjs");
+const TDIR = ".pi/gauntlet/telemetry/doc/specs";
+const EMPTY_AGENT = mkdtempSync(join(tmpdir(), "gp-empty-agent-"));
+process.on("exit", () => rmSync(EMPTY_AGENT, { recursive: true, force: true }));
+
+const write = (root, rel, text) => {
+  mkdirSync(join(root, dirname(rel)), { recursive: true });
+  writeFileSync(join(root, rel), text);
+};
+const gitRepo = (prefix = "gp-") => {
+  const root = mkdtempSync(join(tmpdir(), prefix));
+  spawnSync("git", ["init", "-q"], { cwd: root });
+  return root;
+};
+const invoke = (cwd, args = [], env = {}) => {
+  const r = spawnSync(process.execPath, [CLI, ...args], {
+    cwd, encoding: "utf8", env: { ...process.env, PI_CODING_AGENT_DIR: EMPTY_AGENT, ...env },
+  });
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr.trim(), lines: r.stdout.split("\n").filter(Boolean) };
+};
+const json = (cwd, args = []) => JSON.parse(invoke(cwd, ["--json", ...args]).stdout);
+const cleanup = (t, ...roots) => t.after(() => roots.forEach((r) => rmSync(r, { recursive: true, force: true })));
+
+const phase = (extra) => `{ started_at: 2026-09-01T00:00:00Z, completed_at: 2026-09-01T00:10:00Z, duration_s: 600, ${extra} }`;
+const tokens = (input, output, cacheRead, cacheWrite, cost) =>
+  `tokens: { input: ${input}, output: ${output}, cache_read: ${cacheRead}, cache_write: ${cacheWrite}, cost: ${cost} }`;
+
+// Complete run: cache-dominated tokens, an unphased block that must be ignored, two models.
+const COMPLETE = `schema: 1
+spec: doc/specs/a.md
+run_id: aaaaaaaa-0000-0000-0000-000000000001
+status: shipped
+created_at: 2026-09-01T00:00:00Z
+shipped_at: 2026-09-01T01:00:00Z
+versions: { pi-gauntlet: 5.9.1 }
+derived:
+  duration_s: 3600
+  phases:
+    brainstorm: ${phase(`model: m/alpha, ${tokens(100, 10, 5000, 200, 1.5)}`)}
+    plan: ${phase(`model: m/alpha, ${tokens(50, 5, 1000, 100, 0.5)}`)}
+    implement: ${phase(`model: m/beta, ${tokens(10, 1, 100, 10, 0.25)}`)}
+    verify: ${phase(`model: m/beta`)}
+    ship: ${phase(`model: m/beta`)}
+    unphased: { ${tokens(99999, 99999, 99999, 99999, 999)} }
+  personas:
+    worker: { dispatches: 3, models: [m/beta] }
+    spec-council-member: { dispatches: 4, models: [m/alpha] }
+  reviews:
+    spec-reviewer: { dispatches: 1, nonzero_exit: 0, findings: { blocker: 1, major: 2, minor: 3 } }
+    code-reviewer: { dispatches: 1, nonzero_exit: 0 }
+  conformance_loops: 2
+  conformance_open_gaps: 0
+  gates: { spec_rounds: 1, plan_rounds: 1, fix_round_grants: 1, task_reopens: 0, ship_option: squash }
+  tests: { command: npm test, result: pass }
+accumulators: {}
+events: []
+`;
+// Truncated run: stamped shipped by salvage, stale duration_s, no ship phase, zero gates.
+const TRUNCATED = `schema: 1
+spec: doc/specs/b.md
+run_id: bbbbbbbb-0000-0000-0000-000000000002
+status: shipped
+created_at: 2026-09-02T00:00:00Z
+shipped_at: 2026-09-02T02:00:00Z
+versions: { pi-gauntlet: 5.9.1 }
+derived:
+  duration_s: 2501
+  phases:
+    brainstorm: ${phase(`model: m/alpha, ${tokens(1, 1, 1, 1, 0.01)}`)}
+    plan: { started_at: 2026-09-02T00:10:00Z, model: m/alpha }
+  personas: {}
+  conformance_loops: 0
+  gates: { spec_rounds: 0, plan_rounds: 0, fix_round_grants: 0, task_reopens: 0 }
+accumulators: {}
+events: []
+`;
+const IN_PROGRESS = `schema: 1
+spec: doc/specs/c.md
+run_id: cccccccc-0000-0000-0000-000000000003
+status: in_progress
+created_at: 2026-09-03T00:00:00Z
+versions: { pi-gauntlet: 5.11.0 }
+derived:
+  duration_s: 10
+  phases: { brainstorm: { started_at: 2026-09-03T00:00:00Z } }
+  personas: {}
+  conformance_loops: 0
+  gates: { spec_rounds: 0, plan_rounds: 0, fix_round_grants: 0, task_reopens: 0 }
+accumulators: {}
+events: []
+`;
+// Second complete run on 5.9.1 with different numbers: makes p50 over an even count.
+const COMPLETE_2 = COMPLETE
+  .replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: dddddddd-0000-0000-0000-000000000004")
+  .replace("spec: doc/specs/a.md", "spec: doc/specs/d.md")
+  .replace("created_at: 2026-09-01T00:00:00Z", "created_at: 2026-09-04T00:00:00Z")
+  .replace("duration_s: 3600", "duration_s: 7200")
+  .replace("fix_round_grants: 1", "fix_round_grants: 3")
+  .replace(/reviews:[\s\S]*?conformance_loops/, "conformance_loops");
+const OLD_VERSION = COMPLETE
+  .replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: eeeeeeee-0000-0000-0000-000000000005")
+  .replace("spec: doc/specs/a.md", "spec: doc/specs/e.md")
+  .replace("pi-gauntlet: 5.9.1", "pi-gauntlet: 5.10.0");
+const BAD_GATES = IN_PROGRESS
+  .replace("run_id: cccccccc-0000-0000-0000-000000000003", "run_id: ffffffff-0000-0000-0000-000000000006")
+  .replace("spec: doc/specs/c.md", "spec: doc/specs/f.md")
+  .replace(/gates: \{[^}]*\}/, 'gates: "nope"');
+const EMPTY_REVIEWS = IN_PROGRESS
+  .replace("run_id: cccccccc-0000-0000-0000-000000000003", "run_id: gggggggg-0000-0000-0000-000000000007")
+  .replace("spec: doc/specs/c.md", "spec: doc/specs/g.md")
+  .replace("created_at: 2026-09-03T00:00:00Z", "created_at: 2026-09-05T00:00:00Z")
+  .replace("  conformance_loops: 0", "  reviews: {}\n  conformance_loops: 0");
+const REVIEW_WITHOUT_FINDINGS = IN_PROGRESS
+  .replace("run_id: cccccccc-0000-0000-0000-000000000003", "run_id: hhhhhhhh-0000-0000-0000-000000000008")
+  .replace("spec: doc/specs/c.md", "spec: doc/specs/h.md")
+  .replace("  conformance_loops: 0", "  reviews: { code-reviewer: { dispatches: 1, nonzero_exit: 0 } }\n  conformance_loops: 0");
+
+const corpus = (root) => {
+  write(root, `${TDIR}/a.yaml`, COMPLETE);
+  write(root, `${TDIR}/b.yaml`, TRUNCATED);
+  write(root, `${TDIR}/c.yaml`, IN_PROGRESS);
+  write(root, `${TDIR}/d.yaml`, COMPLETE_2);
+  write(root, `${TDIR}/e.yaml`, OLD_VERSION);
+  write(root, `${TDIR}/f.yaml`, BAD_GATES);
+  write(root, `${TDIR}/present-empty-reviews.yaml`, EMPTY_REVIEWS);
+  write(root, `${TDIR}/broken.yaml`, "schema: 1\nspec: [\n");
+  write(root, `${TDIR}/v2.yaml`, "schema: 2\nspec: doc/specs/z.md\nrun_id: z\n");
+  write(root, `${TDIR}/norec.yaml`, "schema: 1\nspec: doc/specs/z.md\n");
+  return root;
+};
+const byId = (runs, prefix) => runs.find((r) => r.run_id.startsWith(prefix));
+
+test("per-run fields: typed reads, unphased excluded, truncated wall null, findings null vs 0/0/0", (t) => {
+  const root = corpus(gitRepo()); cleanup(t, root);
+  const d = json(root);
+  assert.deepEqual(d.corpus, { [root.split("/").pop()]: 7 });
+  assert.equal(d.since, null);
+  const a = byId(d.runs, "aaaaaaaa");
+  assert.equal(a.repo, root.split("/").pop());
+  assert.equal(a.spec, "a");
+  assert.equal(a.version, "5.9.1");
+  assert.equal(a.status, "shipped");
+  assert.equal(a.truncated, false);
+  assert.equal(a.wall_s, 3600);
+  assert.deepEqual(a.phase_min, { brainstorm: 10, plan: 10, implement: 10, verify: 10, ship: 10 });
+  assert.equal(a.tokens, 100 + 10 + 5000 + 200 + 50 + 5 + 1000 + 100 + 10 + 1 + 100 + 10);
+  assert.equal(a.cost, 2.25);
+  assert.deepEqual(a.models, ["m/alpha", "m/beta"]);
+  assert.equal(a.dispatches, 7);
+  assert.equal(a.grants, 1);
+  assert.equal(a.reopens, 0);
+  assert.equal(a.spec_rounds, 1);
+  assert.equal(a.plan_rounds, 1);
+  assert.equal(a.loops, 2);
+  assert.equal(a.open_gaps, 0);
+  assert.deepEqual(a.findings, { blocker: 1, major: 2, minor: 3 });
+  assert.equal(a.council, 4);
+  assert.equal(a.ship_option, "squash");
+  assert.equal(a.tests, "pass");
+  const b = byId(d.runs, "bbbbbbbb");
+  assert.equal(b.truncated, true);
+  assert.equal(b.wall_s, null);
+  assert.deepEqual(b.phase_min, { brainstorm: 10, plan: null, implement: null, verify: null, ship: null });
+  assert.equal(b.tokens, 4);
+  assert.equal(b.dispatches, null);
+  assert.equal(b.findings, null);
+  assert.equal(b.council, null);
+  assert.equal(b.ship_option, null);
+  assert.equal(b.tests, null);
+  const dd = byId(d.runs, "dddddddd");
+  assert.equal(dd.findings, null);
+  const f = byId(d.runs, "ffffffff");
+  assert.equal(f.grants, null);
+  assert.equal(f.status, "in_progress");
+  const emptyReviews = byId(d.runs, "gggggggg");
+  assert.deepEqual(emptyReviews.findings, { blocker: 0, major: 0, minor: 0 });
+});
+
+test("review entries without findings contribute zero counters", (t) => {
+  const root = gitRepo(); cleanup(t, root);
+  write(root, `${TDIR}/review-without-findings.yaml`, REVIEW_WITHOUT_FINDINGS);
+  const d = json(root);
+  assert.deepEqual(d.runs[0].findings, { blocker: 0, major: 0, minor: 0 });
+});
+
+test("malformed findings counters remain null in JSON and render as dashes in text", (t) => {
+  const root = gitRepo(); cleanup(t, root);
+  const malformed = COMPLETE.replace(
+    "findings: { blocker: 1, major: 2, minor: 3 }",
+    'findings: { blocker: "bad", major: 2, minor: 3 }',
+  );
+  write(root, `${TDIR}/malformed-findings.yaml`, malformed);
+  const d = json(root);
+  assert.deepEqual(d.runs[0].findings, { blocker: null, major: 2, minor: 3 });
+  const row = invoke(root).lines.find((line) => line.startsWith("aaaaaaaa"));
+  assert.match(row, /\s-\/2\/3\s+4$/);
+});
+
+test("malformed reviewer entries and findings objects contribute null counters", (t) => {
+  const root = gitRepo(); cleanup(t, root);
+  const malformedFindings = COMPLETE.replace(
+    "findings: { blocker: 1, major: 2, minor: 3 }",
+    'findings: "bad"',
+  );
+  const malformedReviewer = COMPLETE.replace(
+    "spec-reviewer: { dispatches: 1, nonzero_exit: 0, findings: { blocker: 1, major: 2, minor: 3 } }",
+    'spec-reviewer: "bad"',
+  );
+  write(root, `${TDIR}/malformed-findings-object.yaml`, malformedFindings);
+  write(root, `${TDIR}/malformed-reviewer.yaml`, malformedReviewer.replace(
+    "run_id: aaaaaaaa-0000-0000-0000-000000000001",
+    "run_id: 22222222-0000-0000-0000-000000000012",
+  ));
+  const d = json(root);
+  assert.deepEqual(byId(d.runs, "aaaaaaaa").findings, { blocker: null, major: null, minor: null });
+  assert.deepEqual(byId(d.runs, "22222222").findings, { blocker: null, major: null, minor: null });
+});
+
+test("phase minutes remain unrounded in JSON", (t) => {
+  const root = gitRepo(); cleanup(t, root);
+  write(root, `${TDIR}/phase-61.yaml`, COMPLETE.replace("duration_s: 600", "duration_s: 61"));
+  const d = json(root);
+  assert.equal(d.runs[0].phase_min.brainstorm, 61 / 60);
+});
+
+test("aggregates: only shipped non-truncated rows feed p50/max; even-count p50 is the mean; models tally; unknown group", (t) => {
+  const root = corpus(gitRepo()); cleanup(t, root);
+  write(root, `${TDIR}/g.yaml`, COMPLETE.replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: 99999999-0000-0000-0000-000000000009").replace("versions: { pi-gauntlet: 5.9.1 }", "versions: {}"));
+  const d = json(root);
+  assert.deepEqual(d.by_version.map((g) => g.version), ["5.9.1", "5.10.0", "5.11.0", "unknown"]);
+  const v591 = d.by_version[0];
+  assert.equal(v591.n, 3);
+  assert.equal(v591.shipped, 2);
+  assert.equal(v591.truncated, 1);
+  assert.deepEqual(v591.wall_s, { p50: 5400, max: 7200 });
+  assert.deepEqual(v591.grants, { p50: 2, max: 3 });
+  assert.deepEqual(v591.dispatches, { p50: 7 });
+  assert.deepEqual(v591.findings, { blocker: { p50: 1 }, major: { p50: 2 }, minor: { p50: 3 } });
+  assert.deepEqual(v591.models, { "m/alpha": 2, "m/beta": 2 });
+  const v5110 = d.by_version[2];
+  assert.equal(v5110.n, 3);
+  assert.equal(v5110.shipped, 0);
+  assert.deepEqual(v5110.wall_s, { p50: null, max: null });
+  assert.deepEqual(v5110.models, {});
+  assert.equal(d.by_version[3].shipped, 1);
+});
+
+test("row order is created_at then run_id; skipped lists unparseable, schema, not a record", (t) => {
+  const root = corpus(gitRepo()); cleanup(t, root);
+  const d = json(root);
+  assert.deepEqual(d.runs.map((r) => r.run_id[0]), ["a", "e", "b", "c", "f", "d", "g"]);
+  const reasons = Object.fromEntries(d.skipped.map((s) => [s.file.split("/").pop(), s.reason]));
+  assert.equal(reasons["broken.yaml"], "unparseable");
+  assert.equal(reasons["v2.yaml"], "schema 2");
+  assert.equal(reasons["norec.yaml"], "not a record");
+});
+
+test("text output: header, shipped* marker, - cells, by version block, skipped lines", (t) => {
+  const root = corpus(gitRepo()); cleanup(t, root);
+  const r = invoke(root);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(r.lines[0], `corpus: ${root.split("/").pop()}=7`);
+  assert.equal(r.lines[1], "runs (7)");
+  assert.match(r.lines[2], /^run_id\s+repo\s+spec\s+version\s+status\s+wall\s+b\/p\/i\/v\/s min\s+tokens\s+cost\s+models\s+disp\s+grants\s+reopens\s+loops\s+findings\s+council$/);
+  const bRow = r.lines.find((l) => l.startsWith("bbbbbbbb"));
+  assert.match(bRow, /\s5\.9\.1\s+shipped\*\s+-\s+10\/-\/-\/-\/-\s/);
+  assert.match(bRow, /\s-\s*$/);
+  const aRow = r.lines.find((l) => l.startsWith("aaaaaaaa"));
+  assert.match(aRow, /\sshipped\s+60m\s+10\/10\/10\/10\/10\s+6\.6k\s+2\.25\s+m\/alpha,m\/beta\s+7\s+1\s+0\s+2\s+1\/2\/3\s+4$/);
+  assert.ok(r.lines.includes("by version"));
+  const v = r.lines.find((l) => l.startsWith("5.9.1"));
+  assert.match(v, /^5\.9\.1\s+3\s+2\s+1\s+90m\/120m\s/);
+  assert.ok(r.lines.some((l) => /^skipped: .*broken\.yaml: unparseable$/.test(l)));
+});
+
+test("--since numeric compare: 5.10.0 > 5.9.1, unknown and malformed versions dropped; no rows -> no records found, exit 0", (t) => {
+  const root = corpus(gitRepo()); cleanup(t, root);
+  write(root, `${TDIR}/g.yaml`, COMPLETE.replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: 99999999-0000-0000-0000-000000000009").replace("versions: { pi-gauntlet: 5.9.1 }", "versions: {}"));
+  write(root, `${TDIR}/malformed-version.yaml`, COMPLETE.replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: 11111111-0000-0000-0000-000000000011").replace("pi-gauntlet: 5.9.1", "pi-gauntlet: 5.9.1garbage"));
+  write(root, `${TDIR}/leading-zero-version.yaml`, COMPLETE.replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: 33333333-0000-0000-0000-000000000013").replace("pi-gauntlet: 5.9.1", "pi-gauntlet: 5.09.1"));
+  assert.equal(byId(json(root).runs, "11111111").version, "unknown");
+  assert.equal(byId(json(root).runs, "33333333").version, "unknown");
+  const sinceFive = json(root, ["--since", "5.0.0"]);
+  assert.equal(byId(sinceFive.runs, "33333333"), undefined);
+  const d = json(root, ["--since", "5.10.0"]);
+  assert.equal(d.since, "5.10.0");
+  assert.deepEqual(d.runs.map((r) => r.version).sort(), ["5.10.0", "5.11.0", "5.11.0", "5.11.0"]);
+  const r = invoke(root, ["--since", "9.9.9"]);
+  assert.equal(r.status, 0);
+  assert.equal(r.lines[0], `corpus: ${root.split("/").pop()}=0   since: 9.9.9`);
+  assert.match(r.lines[1], /^no records found in .*\.pi\/gauntlet\/telemetry$/);
+  assert.equal(r.lines.length, 2);
+});
+
+test("--dir: repo root with telemetry dir, repo root without (skipped, checkout not walked), bare telemetry dir; duplicate run_id collapses", (t) => {
+  const root = corpus(gitRepo());
+  const other = gitRepo("gp-other-");
+  write(other, `${TDIR}/dup.yaml`, COMPLETE);
+  write(other, `${TDIR}/h.yaml`, COMPLETE.replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: 88888888-0000-0000-0000-000000000008"));
+  const empty = gitRepo("gp-empty-");
+  write(empty, "doc/specs/decoy.yaml", COMPLETE.replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: 77777777-0000-0000-0000-000000000007"));
+  const bare = mkdtempSync(join(tmpdir(), "gp-bare-"));
+  write(bare, "x.yaml", COMPLETE.replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: 66666666-0000-0000-0000-000000000006"));
+  cleanup(t, root, other, empty, bare);
+  const d = json(root, ["--dir", other, "--dir", empty, "--dir", bare, "--dir", join(bare, "missing")]);
+  assert.equal(d.corpus[other.split("/").pop()], 1);
+  assert.equal(d.corpus[bare.split("/").pop()], 1);
+  assert.equal(d.corpus[empty.split("/").pop()], undefined);
+  assert.ok(d.runs.some((r) => r.run_id.startsWith("88888888")));
+  assert.ok(d.runs.some((r) => r.run_id.startsWith("66666666")));
+  assert.ok(!d.runs.some((r) => r.run_id.startsWith("77777777")));
+  assert.equal(d.runs.filter((r) => r.run_id.startsWith("aaaaaaaa")).length, 1);
+  assert.ok(d.skipped.some((s) => s.file.endsWith("dup.yaml") && s.reason === "duplicate run_id"));
+  assert.ok(d.skipped.some((s) => s.file === empty && s.reason === "no telemetry dir"));
+  assert.ok(d.skipped.some((s) => s.file === join(bare, "missing") && s.reason === "not found"));
+});
+
+test("--dir skips an existing regular file as not a directory", (t) => {
+  const root = gitRepo();
+  const file = join(root, "telemetry.yaml");
+  writeFileSync(file, COMPLETE);
+  cleanup(t, root);
+  const r = invoke(root, ["--json", "--dir", file]);
+  assert.equal(r.status, 0, r.stderr);
+  const d = JSON.parse(r.stdout);
+  assert.ok(d.skipped.some((s) => s.file === file && s.reason === "not a directory"));
+});
+
+test("repo .pi/settings.json telemetry.dir is honoured for the default corpus", (t) => {
+  const root = gitRepo(); cleanup(t, root);
+  write(root, ".pi/settings.json", JSON.stringify({ piGauntlet: { telemetry: { dir: "custom/dir" } } }));
+  write(root, "custom/dir/doc/specs/a.yaml", COMPLETE);
+  const d = json(root);
+  assert.equal(d.runs.length, 1);
+});
+
+test("usage error exits 1", (t) => {
+  const root = gitRepo(); cleanup(t, root);
+  assert.equal(invoke(root, ["--bogus"]).status, 1);
+  assert.equal(invoke(root, ["--since", "abc"]).status, 1);
+  assert.equal(invoke(root, ["--since", "5.09.1"]).status, 1);
+});

package/bin/gauntlet-telemetry-salvage.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 // Restore a gauntlet telemetry record that a plan strip or a gate fix commit removed
 // from the branch. The recorder pathspec-commits the record at every checkpoint, so the
-// newest copy is always in the deleting commit's parent. Exit 0 on every outcome: the
-// callers are ship paths and this script never blocks one.
-import { existsSync, readFileSync, rmSync } from "node:fs";
+// newest copy is always in the deleting commit's parent. An in_progress record with no
+// ship phase is stamped shipped at landing. Exit 0 on every outcome: the callers are ship
+// paths and this script never blocks one.
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { spawnSync } from "node:child_process";
@@ -11,6 +12,7 @@ import process from "node:process";
 import { mergeGauntlet, resolveTelemetry } from "../extensions/lib/gauntlet-settings.ts";
 import { isSpecPath, recordPathFor } from "../extensions/lib/telemetry-paths.ts";
 import { BASE_REFS } from "../extensions/lib/telemetry-ship.ts";
+import { parseRecord, serializeRecord } from "../extensions/lib/telemetry-record.ts";
 
 const GIT_TIMEOUT_MS = 10_000;
 const COMMIT_TIMEOUT_MS = Number(process.env.GAUNTLET_SALVAGE_COMMIT_TIMEOUT_MS) || 30_000;
@@ -67,10 +69,40 @@ function resolveBase(root, explicit) {
   return undefined;
 }
 
+// in_progress with no ship phase: the recorder lost its binding before the ship, so the
+// landing finishes the record instead of leaving it in_progress on main forever.
+const unfinished = (rec) => {
+  const phases = rec?.derived?.phases;
+  return rec?.status === "in_progress" && (phases === null || typeof phases !== "object" || !("ship" in phases));
+};
+const stamped = (rec, now) => serializeRecord({ ...rec, status: "shipped", shipped_at: now });
+
+function stampPresent(root, rec, check) {
+  const line = `present ${rec}`;
+  const abs = join(root, rec);
+  // Only a copy identical to HEAD in both worktree and index is script-owned.
+  if (!existsSync(abs) || !git(root, ["diff", "--quiet", "HEAD", "--", rec]).ok || !git(root, ["diff", "--quiet", "--cached", "HEAD", "--", rec]).ok) return line;
+  const parsed = parseRecord(readFileSync(abs, "utf8"));
+  if (!unfinished(parsed)) return line;
+  if (check) return `unfinished ${rec}`;
+  const prior = readFileSync(abs);
+  const failed = (reason) => {
+    writeFileSync(abs, prior);
+    git(root, ["reset", "-q", "--", rec]);
+    return `restore failed ${rec}: ${reason}`;
+  };
+  writeFileSync(abs, stamped(parsed, new Date().toISOString()));
+  const add = git(root, ["add", "-f", "--", rec]);
+  if (!add.ok) return failed(add.stderr);
+  const commit = git(root, ["commit", "-q", "-m", `telemetry: mark ${rec} shipped at landing`, "--", rec], COMMIT_TIMEOUT_MS);
+  if (!commit.ok) return failed(commit.stderr);
+  return `${line} (marked shipped)`;
+}
+
 function salvage(root, rec, base, check) {
   const presence = git(root, ["cat-file", "-e", `HEAD:${rec}`]);
   if (presence.timedOut) return `restore failed ${rec}: timed out`;
-  if (presence.ok) return `present ${rec}`;
+  if (presence.ok) return stampPresent(root, rec, check);
   const history = git(root, ["log", `${base}..HEAD`, "--grep=^telemetry: ", "-1", "--format=%H"]);
   if (history.timedOut) return `restore failed ${rec}: timed out`;
   if (!history.stdout) return `no telemetry run ${rec}`;
@@ -89,7 +121,12 @@ function salvage(root, rec, base, check) {
   }
   let created = false;
   let stagedByScript = false;
+  let priorBytes;
   const rollback = () => {
+    if (priorBytes !== undefined) {
+      writeFileSync(abs, priorBytes);
+      if (preStaged) git(root, ["add", "-f", "--", rec]);
+    }
     if (stagedByScript) git(root, ["reset", "-q", "--", rec]);
     if (created) rmSync(abs, { force: true });
   };
@@ -102,15 +139,20 @@ function salvage(root, rec, base, check) {
     const co = git(root, ["checkout", `${del}^`, "--", rec]);
     if (!co.ok) return `restore failed ${rec}: ${co.stderr}`;
     created = true;
-    stagedByScript = true;
-  } else if (!preStaged) {
-    const add = git(root, ["add", "-f", "--", rec]);
-    if (!add.ok) return failed(add.stderr);
-    stagedByScript = true;
   }
+  stagedByScript = !preStaged;
+  let suffix = "";
+  const parsed = parseRecord(readFileSync(abs, "utf8"));
+  if (unfinished(parsed)) {
+    priorBytes = readFileSync(abs);
+    writeFileSync(abs, stamped(parsed, new Date().toISOString()));
+    suffix = " (marked shipped)";
+  }
+  const add = git(root, ["add", "-f", "--", rec]);
+  if (!add.ok) return failed(add.stderr);
   const commit = git(root, ["commit", "-q", "-m", `telemetry: restore record stripped in ${del.slice(0, 10)}`, "--", rec], COMMIT_TIMEOUT_MS);
   if (!commit.ok) return failed(commit.stderr);
-  return `restored ${rec} from ${del}`;
+  return `restored ${rec} from ${del}${suffix}`;
 }
 
 function main() {

package/bin/gauntlet-telemetry-salvage.test.mjs

@@ -11,6 +11,11 @@
   const REC = ".pi/gauntlet/telemetry/doc/specs/x.yaml";
   const RECORD_V1 = "schema: 1\nspec: doc/specs/x.md\nstatus: in_progress\n";
   const RECORD_V2 = "schema: 1\nspec: doc/specs/x.md\nstatus: shipped\n";
+  // Records parseRecord accepts (run_id present). UNFINISHED: in_progress, no ship phase.
+  const UNFINISHED = "schema: 1\nspec: doc/specs/x.md\nrun_id: r-1\nstatus: in_progress\ncreated_at: 2026-09-17T16:11:45Z\nderived:\n  duration_s: 60\n  phases:\n    brainstorm: { started_at: 2026-09-17T16:11:45Z, duration_s: 60 }\n";
+  const SHIP_PHASE = UNFINISHED.replace("    brainstorm:", "    ship: { started_at: 2026-09-17T16:12:45Z }\n    brainstorm:");
+  const SCALAR_PHASES = UNFINISHED.replace("  phases:\n    brainstorm: { started_at: 2026-09-17T16:11:45Z, duration_s: 60 }", "  phases: nope");
+  const FINISHED = UNFINISHED.replace("status: in_progress", "status: shipped\nshipped_at: 2026-09-17T18:56:13Z");
 
   const git = (cwd, args, env = {}) =>
     spawnSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", "-c", "commit.gpgsign=false", ...args], {
@@ -32,7 +37,7 @@
     return out(root, ["rev-parse", "HEAD"]);
   };
   // main: README only. feat: spec (+ record when withRecord).
-  const repo = ({ withRecord = true } = {}) => {
+  const repo = ({ withRecord = true, record = RECORD_V1 } = {}) => {
     const root = mkdtempSync(join(tmpdir(), "gts-"));
     git(root, ["init", "-q", "-b", "main"]);
     write(root, "README.md", "# fixture\n");
@@ -41,7 +46,7 @@
     write(root, SPEC, "# Spec X\n\n**Goal:** g.\n");
     commit(root, "Add spec", SPEC);
     if (withRecord) {
-      write(root, REC, RECORD_V1);
+      write(root, REC, record);
       commit(root, "telemetry: doc/specs/x.md", REC);
     }
     return root;
@@ -348,6 +353,103 @@ PATH="${process.env.PATH.split(":").filter((part) => part !== bin).join(":")}" e
     assert.equal(out(remote, ["for-each-ref"]), remoteBefore);
   });
 
+  test("present + unfinished -> stamped shipped, one telemetry: commit, clean tree", (t) => {
+    const root = repo({ record: UNFINISHED }); cleanup(t, root);
+    const n = commitCount(root);
+    const r = run(root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.deepEqual(r.lines, [`present ${REC} (marked shipped)`]);
+    const text = readFileSync(join(root, REC), "utf8");
+    assert.match(text, /^status: shipped$/m);
+    assert.match(text, /^shipped_at: \d{4}-\d{2}-\d{2}T/m);
+    assert.doesNotMatch(text, /in_progress/);
+    assert.equal(commitCount(root), n + 1);
+    assert.equal(headSubject(root), `telemetry: mark ${REC} shipped at landing`);
+    assert.deepEqual(headFiles(root), [REC]);
+    assert.equal(porcelain(root), "");
+  });
+
+  test("present + scalar phases -> stamped shipped, exit 0", (t) => {
+    const root = repo({ record: SCALAR_PHASES }); cleanup(t, root);
+    const r = run(root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.deepEqual(r.lines, [`present ${REC} (marked shipped)`]);
+    assert.match(readFileSync(join(root, REC), "utf8"), /^status: shipped$/m);
+  });
+
+  test("present + in_progress with a ship phase -> untouched", (t) => {
+    const root = repo({ record: SHIP_PHASE }); cleanup(t, root);
+    const before = head(root);
+    const r = run(root);
+    assert.deepEqual(r.lines, [`present ${REC}`]);
+    assert.equal(head(root), before);
+    assert.equal(readFileSync(join(root, REC), "utf8"), SHIP_PHASE);
+  });
+
+  test("present + unfinished but worktree copy dirty -> untouched, present", (t) => {
+    const root = repo({ record: UNFINISHED }); cleanup(t, root);
+    write(root, REC, UNFINISHED + "# local edit\n");
+    const before = head(root);
+    const r = run(root);
+    assert.deepEqual(r.lines, [`present ${REC}`]);
+    assert.equal(head(root), before);
+    assert.equal(readFileSync(join(root, REC), "utf8"), UNFINISHED + "# local edit\n");
+  });
+
+  test("present + already shipped -> byte-identical, no commit", (t) => {
+    const root = repo({ record: FINISHED }); cleanup(t, root);
+    const before = head(root);
+    const r = run(root);
+    assert.deepEqual(r.lines, [`present ${REC}`]);
+    assert.equal(head(root), before);
+    assert.equal(readFileSync(join(root, REC), "utf8"), FINISHED);
+  });
+
+  test("restore with scalar phases -> stamped shipped, exit 0", (t) => {
+    const root = repo({ record: SCALAR_PHASES }); cleanup(t, root);
+    const del = rmCommit(root, "strip", REC);
+    const r = run(root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.deepEqual(r.lines, [`restored ${REC} from ${del} (marked shipped)`]);
+    assert.match(out(root, ["show", `HEAD:${REC}`]), /^status: shipped$/m);
+  });
+
+  test("restore of an unfinished record -> one commit whose bytes carry the stamp", (t) => {
+    const root = repo({ record: UNFINISHED }); cleanup(t, root);
+    const del = rmCommit(root, "strip", REC);
+    write(root, REC, UNFINISHED);
+    const n = commitCount(root);
+    const r = run(root);
+    assert.deepEqual(r.lines, [`restored ${REC} from ${del} (marked shipped)`]);
+    assert.equal(commitCount(root), n + 1);
+    const committed = out(root, ["show", `HEAD:${REC}`]);
+    assert.match(committed, /^status: shipped$/m);
+    assert.match(committed, /^shipped_at: /m);
+    assert.equal(porcelain(root), "");
+  });
+
+  test("--check on present + unfinished -> unfinished <rec>, nothing changes", (t) => {
+    const root = repo({ record: UNFINISHED }); cleanup(t, root);
+    const before = head(root);
+    const r = run(root, ["--check"]);
+    assert.deepEqual(r.lines, [`unfinished ${REC}`]);
+    assert.equal(head(root), before);
+    assert.equal(readFileSync(join(root, REC), "utf8"), UNFINISHED);
+    assert.equal(porcelain(root), "");
+  });
+
+  test("present + unfinished, rejecting pre-commit hook -> restore failed, HEAD bytes and index restored", (t) => {
+    const root = repo({ record: UNFINISHED }); cleanup(t, root);
+    write(root, ".git/hooks/pre-commit", "#!/bin/sh\nexit 1\n");
+    chmodSync(join(root, ".git/hooks/pre-commit"), 0o755);
+    const before = head(root);
+    const r = run(root);
+    assert.match(r.stdout, new RegExp(`^restore failed ${REC.replace(/\./g, "\\.")}: `));
+    assert.equal(head(root), before);
+    assert.equal(readFileSync(join(root, REC), "utf8"), UNFINISHED);
+    assert.equal(porcelain(root), "");
+  });
+
   test("finishing Option 1 fixture: strip-on-branch + salvage + merge --squash leaves the record, not the plan, staged", (t) => {
     const root = repo(); cleanup(t, root);
     const plan = "doc/plans/x.md";

package/extensions/lib/checkout.test.ts

@@ -3,7 +3,7 @@ import { after, test } from "node:test";
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { checkoutOf, parseCheckout, gitSync, type GitResult } from "./checkout.ts";
+import { checkoutOf, checkoutOfSync, parseCheckout, gitSync, jjSync, type GitResult } from "./checkout.ts";
 
 const tempDirs: string[] = [];
 after(() => { for (const d of tempDirs) rmSync(d, { recursive: true, force: true }); });
@@ -32,7 +32,7 @@ test("checkoutOf: a file path runs git in its dirname", async () => {
   writeFileSync(join(dir, "spec.md"), "# s\n");
   const cwds: string[] = [];
   const git = (_args: string[], cwd: string): GitResult => { cwds.push(cwd); return out([dir, dir + "/.git", dir + "/.git"]); };
-  assert.deepEqual(await checkoutOf(join(dir, "spec.md"), git), { toplevel: dir, isPrimary: true });
+  assert.deepEqual(await checkoutOf(join(dir, "spec.md"), git), { toplevel: dir, isPrimary: true, via: "git" });
   assert.deepEqual(cwds, [dir]);
 });
 
@@ -57,3 +57,66 @@ test("gitSync: never throws; nonzero code outside a repo", () => {
   assert.notEqual(r.code, 0);
   assert.equal(typeof r.stdout, "string");
 });
+
+test("checkoutOf: falls back to `jj root` when git fails, added workspace is not primary", async () => {
+  const dir = tmp();
+  mkdirSync(join(dir, ".jj"));
+  writeFileSync(join(dir, ".jj", "repo"), "/main/repo/.jj/repo\n"); // pointer file in added workspaces
+  const git = (): GitResult => ({ code: 128, stdout: "" });
+  const jj = (args: string[], cwd: string): GitResult => {
+    assert.deepEqual(args, ["root"]);
+    assert.equal(cwd, dir);
+    return { code: 0, stdout: dir + "\n" };
+  };
+  assert.deepEqual(await checkoutOf(join(dir, "doc", "plan.md"), git, jj), { toplevel: dir, isPrimary: false, via: "jj" });
+});
+
+test("checkoutOf: jj primary checkout keeps .jj/repo as a directory", async () => {
+  const dir = tmp();
+  mkdirSync(join(dir, ".jj", "repo"), { recursive: true });
+  const git = (): GitResult => ({ code: 128, stdout: "" });
+  const jj = (): GitResult => ({ code: 0, stdout: dir + "\n" });
+  assert.deepEqual(await checkoutOf(dir, git, jj), { toplevel: dir, isPrimary: true, via: "jj" });
+});
+
+test("checkoutOf: git result wins when it resolves, jj is not consulted", async () => {
+  const dir = tmp();
+  let jjCalled = false;
+  const git = (): GitResult => out([dir, dir + "/.git", dir + "/.git"]);
+  const jj = (): GitResult => { jjCalled = true; return { code: 0, stdout: "/elsewhere\n" }; };
+  assert.deepEqual(await checkoutOf(dir, git, jj), { toplevel: dir, isPrimary: true, via: "git" });
+  assert.equal(jjCalled, false);
+});
+
+test("checkoutOf: undefined when neither git nor jj resolves", async () => {
+  const fail = (): GitResult => ({ code: 1, stdout: "" });
+  assert.equal(await checkoutOf(join(tmp(), "x.md"), fail, fail), undefined);
+});
+
+test("jjSync: never throws; nonzero code outside a jj repo", () => {
+  const r = jjSync(["root"], tmp());
+  assert.notEqual(r.code, 0);
+  assert.equal(typeof r.stdout, "string");
+});
+
+test("checkoutOfSync: git wins without consulting jj", () => {
+  const dir = tmp();
+  let jjCalled = false;
+  const git = (): GitResult => out([dir, dir + "/.git", dir + "/.git"]);
+  const jj = (): GitResult => { jjCalled = true; return { code: 0, stdout: "/elsewhere\n" }; };
+  assert.deepEqual(checkoutOfSync(dir, git, jj), { toplevel: dir, isPrimary: true, via: "git" });
+  assert.equal(jjCalled, false);
+});
+
+test("checkoutOfSync: falls back to `jj root` when git fails", () => {
+  const dir = tmp();
+  mkdirSync(join(dir, ".jj", "repo"), { recursive: true });
+  const git = (): GitResult => ({ code: 128, stdout: "" });
+  const jj = (): GitResult => ({ code: 0, stdout: dir + "\n" });
+  assert.deepEqual(checkoutOfSync(join(dir, "doc", "specs"), git, jj), { toplevel: dir, isPrimary: true, via: "jj" });
+});
+
+test("checkoutOfSync: undefined when neither git nor jj resolves", () => {
+  const fail = (): GitResult => ({ code: 1, stdout: "" });
+  assert.equal(checkoutOfSync(join(tmp(), "x.md"), fail, fail), undefined);
+});