@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/intent-cli.ts

@@ -1,9 +1,10 @@
 /**
- * `chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]`
- * (#2651): the intent graph over one region (`intent.ts`), printed as JSON
+ * `chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]`
+ * (#2651, #3034): the intent graph over one region (`intent.ts`), printed as JSON
  * with `--json` or as a walk, one line per node, in the order of #2650
  * section B: the region, its decisions, their artifacts, the commits, and the
- * findings. Under each decision come the commits made inside its window, and
+ * findings, then why the region is like this: who made its current lines and
+ * the decisions governing it, most relevant first. Under each decision come the commits made inside its window, and
  * when any of them is not the decision's own work, the question #2650 B puts
  * to the person about it (#2656). Without `--kind`, the walk reads every
  * record kind the declaration names (#2680).
@@ -13,10 +14,10 @@ import { resolve } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
 import { intentRecord, type IntentRecordDocument } from "./intent-record";
-import { intentGraph, type ArtifactNode, type CommitNode, type DecisionNode, type IntentDocument, type IntentEdge, type IntentNode, type WorkNode } from "./intent";
+import { intentGraph, type ArtifactNode, type CommitNode, type DecisionNode, type IntentDocument, type IntentEdge, type IntentNode, type RunNode, type WhyAnswer, type WorkNode } from "./intent";
 
-const USAGE = "chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]";
-const RECORD_USAGE = "chant workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--json]";
+const USAGE = "chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
+const RECORD_USAGE = "chant workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
 
 type Result = Exclude<IntentDocument, { error: unknown }>;
 type RecordResult = Exclude<IntentRecordDocument, { error: unknown }>;
@@ -45,7 +46,10 @@ function withinLines(doc: Result, d: DecisionNode): string[] {
       .map((p) => doc.nodes.find((n) => n.id === p.to))
       .map((n) => (n && "ref" in n ? n.ref : undefined))
       .filter(Boolean);
-    const by = unit.length > 0 ? `unit ${unit.join(", ")}` : "no unit";
+    const carried = (c.joins?.records ?? []).filter((r) => r.node !== null).map((r) => `${r.kind}:${r.id}`);
+    const item = c.joins?.lease?.item;
+    if (item && !carried.some((r) => r.endsWith(`:${item}`))) carried.push(`lease on ${item}`);
+    const by = unit.length > 0 ? `unit ${unit.join(", ")}` : carried.length > 0 ? `carries ${carried.join(", ")}` : "no unit";
     const label = e.state === "decided" ? "decided " : "within  ";
     out.push(`  ${label}  ${short(c.sha)} ${c.subject}; ${by}${e.state === "decided" ? `, ${d.record}'s own work` : `, in ${d.record}'s window and not its work`}`);
   }
@@ -85,6 +89,17 @@ function artifactLine(doc: Result, a: ArtifactNode): string {
   return `artifact  ${a.path} ${a.pinState}; pinned by ${by.join(", ")}; now ${short(a.currentSha256)}`;
 }
 
+/** What chant's own trailers on a commit say (#3149), one line each. */
+function joinLines(j: CommitNode["joins"] | undefined): string[] {
+  if (!j) return [];
+  const out: string[] = [];
+  if (j.agent) out.push(`  agent     ${j.agent}`);
+  if (j.lease) out.push(`  lease     ${j.lease.token}${j.lease.item ? ` on ${j.lease.item}` : ", no lease history names it"}`);
+  for (const r of j.records) out.push(`  record    ${r.kind}:${r.id}${r.node ? "" : ", in no kind read"}`);
+  if (j.applied) out.push(`  applied   by ${j.applied.by}${j.applied.at ? ` at ${j.applied.at}` : ""}${j.applied.commit ? `, ${short(j.applied.commit)}` : ""}`);
+  return out;
+}
+
 function commitLine(doc: Result, c: CommitNode): string[] {
   const lines = c.lines && c.lines.length > 0 ? `, lines ${c.lines.map((l) => (l.start === l.end ? `${l.start}` : `${l.start}-${l.end}`)).join(", ")}` : "";
   const out = [`commit    ${short(c.sha)} ${c.date.slice(0, 10)} ${c.author.name}: ${c.subject}${lines}; ${c.signature.level}`];
@@ -94,6 +109,56 @@ function commitLine(doc: Result, c: CommitNode): string[] {
     for (const s of edgesFrom(doc, e.to, "serves")) out.push(`  contract  ${s.to.slice("contract:".length)}`);
     for (const s of edgesFrom(doc, e.to, "cites-evidence")) out.push(`  evidence  ${s.to.slice("evidence:".length)}`);
   }
+  out.push(...joinLines(c.joins));
+  if (c.squash) {
+    const s = c.squash;
+    out.push(`  squash    #${s.pullRequest}${s.followed ? `: ${s.commits.length} original ${s.commits.length === 1 ? "commit" : "commits"} from ${s.ref}${s.fetched ? ", fetched" : ""}` : ", not followed"}`);
+    for (const o of s.commits) {
+      const carried = [...o.joins.records.map((r) => `${r.kind}:${r.id}`), ...(o.joins.lease ? [`lease ${o.joins.lease.token}`] : []), ...(o.joins.run ? [`run ${o.joins.run}`] : [])];
+      out.push(`  original  ${short(o.sha)} ${o.subject}; ${o.signature.level}${carried.length > 0 ? `; ${carried.join(", ")}` : ""}`);
+    }
+  }
+  for (const e of edgesFrom(doc, c.id, "made-by")) {
+    const r = doc.nodes.find((n): n is RunNode => n.kind === "run" && n.id === e.to);
+    if (!r) continue;
+    const what = r.recorded ? `${[r.harness?.name, r.model].filter(Boolean).join("/") || "no model recorded"}${r.by ? ` for ${r.by}` : ""}${r.cost ? `, ${r.cost.amount} ${r.cost.currency}` : ", unpriced"}` : "not in the run ledger";
+    const content =
+      e.kind !== "made-by"
+        ? ""
+        : e.joinedBy.includes("patch-id")
+          ? `; joined by content${e.recordedAs ? `, as ${short(e.recordedAs)}` : ""}`
+          : e.joinedBy.length === 1 && e.joinedBy[0] === "squash"
+            ? `; through the squash, by ${(e.via ?? []).map(short).join(", ")}`
+            : "";
+    out.push(`  run       ${r.run}: ${what}${content}`);
+  }
+  return out;
+}
+
+const span = (l: { start: number; end: number }) => (l.start === l.end ? `${l.start}` : `${l.start}-${l.end}`);
+
+/** Why the region is like this (#3034): the decisions most relevant first, then who made each span of its current lines, then the gaps. */
+export function whyLines(doc: Result, why: WhyAnswer): string[] {
+  const out: string[] = [];
+  const record = (id: string) => {
+    const n = doc.nodes.find((x) => x.id === id);
+    return n && (n.kind === "decision" || n.kind === "work") ? n.record : id;
+  };
+  const runLabel = (id: string) => {
+    const r = doc.nodes.find((n): n is RunNode => n.kind === "run" && n.id === id);
+    if (!r) return id;
+    const what = [r.harness?.name, r.model].filter(Boolean).join("/");
+    return `${r.run}${what ? ` (${what})` : r.recorded ? "" : " (not in the run ledger)"}${r.unit ? ` on ${r.unit}` : ""}`;
+  };
+  out.push(`why       ${why.explained ? "explained" : "unexplained"}${why.lines ? `, lines ${span(why.lines)}` : ""}`);
+  for (const d of why.decisions) {
+    out.push(`  decision  ${record(d.decision)} ${d.relevance}${d.lines > 0 ? `, ${d.lines} ${d.lines === 1 ? "line" : "lines"}` : ""}${d.current ? "" : ", superseded"}${d.closed ? ", closed" : ""}`);
+  }
+  for (const b of why.blame) {
+    const by = b.runs.length > 0 ? `; ${b.runs.map(runLabel).join(", ")}${b.narrowedBy ? " (by its hunks)" : ""}${b.joinedBy?.includes("patch-id") ? " (joined by content)" : ""}${b.via && b.via.length > 0 ? ` (squashed from ${b.via.map(short).join(", ")})` : ""}` : b.sha ? "; no run" : "";
+    out.push(`  lines     ${span(b)} ${b.sha ? short(b.sha) : "uncommitted"}${by}`);
+  }
+  for (const g of why.gaps) out.push(`  gap       ${g.code}: ${g.message}${g.lines ? ` (lines ${g.lines.map(span).join(", ")})` : ""}`);
   return out;
 }
 
@@ -104,7 +169,8 @@ export function formatIntent(doc: Result): string {
   if (region?.kind === "region") {
     const lines = region.lines ? `:${region.lines.start}${region.lines.end === region.lines.start ? "" : `-${region.lines.end}`}` : "";
     const where = doc.at ? `at ${short(doc.at)}` : "in the working tree";
-    out.push(`region    ${region.path}${lines} (${region.type}, member ${region.member ?? "none"}${region.generated ? ", generated" : ""}) ${where}${region.node ? `, from node ${region.node}` : ""}`);
+    const symbol = region.symbol ? `#${region.symbol.name} (${region.symbol.kind} ${region.symbol.qualified}, lines ${region.lines ? span(region.lines) : "none"})` : lines;
+    out.push(`region    ${region.path}${symbol} (${region.type}, member ${region.member ?? "none"}${region.generated ? ", generated" : ""}) ${where}${region.node ? `, from node ${region.node}` : ""}`);
   }
   const files = ofKind(doc, "file");
   if (files.length > 0) out.push(`files     ${files.length} under the region, ${files.filter((f) => f.generated).length} generated`);
@@ -121,6 +187,7 @@ export function formatIntent(doc: Result): string {
     out.push(`finding   ${f.code}: ${f.message}${by}`);
   }
   for (const r of doc.reasons) out.push(`reason    ${r.code}: ${r.message}`);
+  if (doc.why) out.push(...whyLines(doc, doc.why));
   const kinds = doc.kinds.length === 0 ? "; no --kind, so no decisions were read" : "";
   const work = ofKind(doc, "work").length;
   out.push(`${doc.summary.commits} commits, ${doc.summary.decisions} decisions, ${work > 0 ? `${work} work ${work === 1 ? "item" : "items"}, ` : ""}${doc.summary.artifacts} artifacts, ${doc.summary.findings} findings${kinds}`);
@@ -136,13 +203,17 @@ export function formatIntentRecord(doc: RecordResult): string {
   for (const c of doc.commits) {
     const why =
       c.bucket === "own"
-        ? `unit ${c.unit}`
+        ? c.unit !== null
+          ? `unit ${c.unit}`
+          : `carries ${[...(c.joins?.records ?? []).filter((x) => x.node !== null).map((x) => `${x.kind}:${x.id}`), ...(c.joins?.lease?.item ? [`lease on ${c.joins.lease.item}`] : [])].join(", ")}`
         : c.bucket === "worked"
           ? `worked by ${c.workedBy.map((w) => w.record).join(", ")}`
           : c.bucket === "within-other"
             ? `within ${c.alsoWithin.map((w) => w.record).join(", ")}`
             : "nothing else accounts for it";
-    out.push(`${c.bucket.padEnd(12)} ${short(c.sha)} ${c.date.slice(0, 10)} ${c.subject}; ${why}; ${c.files.join(", ") || c.entries.join(", ")}`);
+    const runs = (c.runs ?? []).map((r) => `run ${r.id}${r.model ? ` (${r.model})` : ""}${r.joinedBy?.includes("squash") && !r.joinedBy.some((j) => j !== "squash") ? " through the squash" : ""}`).join(", ");
+    const squash = c.squash ? `; squash of #${c.squash.pullRequest}${c.squash.followed ? `, ${c.squash.commits.length} original ${c.squash.commits.length === 1 ? "commit" : "commits"}` : ", not followed"}` : "";
+    out.push(`${c.bucket.padEnd(12)} ${short(c.sha)} ${c.date.slice(0, 10)} ${c.subject}; ${why}${runs ? `; ${runs}` : ""}${squash}; ${c.files.join(", ") || c.entries.join(", ")}`);
   }
   for (const x of doc.reasons) out.push(`reason    ${x.code}: ${x.message}`);
   const n = doc.counts;
@@ -152,7 +223,7 @@ export function formatIntentRecord(doc: RecordResult): string {
 
 async function runRecord(ctx: CommandContext, cwd: string, kinds: string[] | undefined): Promise<number> {
   const { args } = ctx;
-  const { doc, failed } = await intentRecord({ cwd, record: args.record!, at: args.at, kinds: kinds?.map((k) => resolve(k)) });
+  const { doc, failed } = await intentRecord({ cwd, record: args.record!, at: args.at, kinds: kinds?.map((k) => resolve(k)), followSquash: args.followSquash });
   if (args.json) console.log(JSON.stringify(doc, null, 2));
   if ("error" in doc) {
     console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: RECORD_USAGE }));
@@ -172,12 +243,12 @@ export async function runWorkspaceIntent(ctx: CommandContext, cwd: string): Prom
     return runRecord(ctx, cwd, args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined));
   }
   if (!args.intent) {
-    console.error(formatError({ message: "--intent needs a region: a path, path:line or path:start-end", hint: USAGE }));
+    console.error(formatError({ message: "--intent needs a region: a path, path:line, path:start-end or path#symbol", hint: USAGE }));
     return 1;
   }
   // No --kind: undefined, so the walk reads the kinds the declaration names (#2680).
   const kinds = args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined);
-  const { doc, failed } = await intentGraph({ cwd, region: args.intent, at: args.at, kinds: kinds?.map((k) => resolve(k)) });
+  const { doc, failed } = await intentGraph({ cwd, region: args.intent, at: args.at, kinds: kinds?.map((k) => resolve(k)), followSquash: args.followSquash });
   if (args.json) console.log(JSON.stringify(doc, null, 2));
   if ("error" in doc) {
     console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));

package/src/workspace/intent-patch-id.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Joining a commit to its agent run by patch-id when the trailer is gone (#3036).
+ *
+ * - app/server.ts; s-001 (path:app/server.ts) is decided and W-001 implements it.
+ * - On a side branch, run A (on W-001) records c1, which carries no trailer.
+ *   main cherry-picks it as p1: a new sha, the same patch-id.
+ * - Run B records b1 on the side branch; main then commits the same change
+ *   as p2 with `Chant-Run: run-c`: a trailer join, and content that matches
+ *   another run's recorded commit.
+ * - Run D records d1 and d2 on the side branch; main squashes them into one
+ *   commit, sq, whose patch-id is neither's.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, git, REPO, repo, writeFiles } from "./__fixtures__/contract-repo";
+import { intentGraph, type IntentDocument } from "./intent";
+import { formatIntent } from "./intent-cli";
+import { intentRecord } from "./intent-record";
+import intentRecordSchema from "./intent-record.schema.json";
+import intentSchema from "./intent.schema.json";
+import { parseFrontMatter } from "./records";
+import { runsWrite, workspaceRuns } from "./runs-cli";
+import runsSchema from "./runs.schema.json";
+
+const REF = join(REPO, "reference-workspace");
+const BASE = (() => {
+  const fm = parseFrontMatter(readFileSync(join(REF, "decisions", "ref-001-how-the-app-is-deployed.md"), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+})();
+const decision = (id: string, fields: Record<string, unknown>) => `---\n${JSON.stringify({ ...BASE, id, title: `Decision ${id}`, state: "decided", supersedes: [], evidence: [], reviews: [], ...fields }, null, 2)}\n---\n\n# ${id}\n`;
+const work = (id: string, fields: Record<string, unknown>) =>
+  `---\n${JSON.stringify({ schema: 1, id, title: `Work ${id}`, state: "open", implements: [], needs: [], constrains: [], evidence: [], opened_on: "2026-10-01", supersedes: [], ...fields }, null, 2)}\n---\n\n# ${id}\n\nWhat the work is.\n`;
+
+const LINES = ["// The app server.", "export const a = 0;", "export const b = 0;", "export const c = 0;", "export const d = 0;", "export const e = 0;"];
+const text = (lines: string[]) => `${lines.join("\n")}\n`;
+const edit = (lines: string[], at: number, to: string) => lines.map((l, i) => (i === at - 1 ? to : l));
+
+type Doc = Exclude<IntentDocument, { error: unknown }>;
+
+let root: string;
+const sha: Record<string, string> = {};
+
+function commit(message: string[]): string {
+  git(root, "add", "-A");
+  git(root, "commit", "-q", ...message.flatMap((m) => ["-m", m]));
+  return git(root, "rev-parse", "HEAD");
+}
+async function record(fields: object): Promise<void> {
+  const doc = await runsWrite({ verb: "record", fields: JSON.stringify(fields), cwd: root });
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+}
+async function walk(region: string): Promise<Doc> {
+  const { doc } = await intentGraph({ cwd: root, region });
+  contract(intentSchema).expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+beforeAll(async () => {
+  root = repo({
+    "chant.workspace.json": JSON.stringify({ name: "patch-id", schema: 1, records: [{ kind: "decisions/decision.kind.mjs" }, { kind: "work/work.kind.mjs" }], members: [{ name: "app", dir: "app", kind: "other", because: "the app" }] }),
+    "decisions/decision.kind.mjs": readFileSync(join(REF, "decisions", "decision.kind.mjs"), "utf-8"),
+    "decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
+    "work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
+    "work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
+    "app/server.ts": text(LINES),
+    "decisions/s-001-server.md": decision("s-001", { constrains: ["path:app/server.ts"] }),
+    "work/W-001-server.md": work("W-001", { implements: ["s-001"] }),
+  });
+  sha.c0 = commit(["the workspace"]);
+  const main = git(root, "rev-parse", "--abbrev-ref", "HEAD");
+
+  // The side branch, where the runs made their commits.
+  git(root, "checkout", "-q", "-b", "side");
+  writeFiles(root, { "app/server.ts": text(edit(LINES, 2, "export const a = 1;")) });
+  sha.c1 = commit(["a is 1"]);
+  writeFiles(root, { "app/server.ts": text(edit(edit(LINES, 2, "export const a = 1;"), 3, "export const b = 1;")) });
+  sha.b1 = commit(["b is 1"]);
+  git(root, "checkout", "-q", "-b", "squashed", sha.c0);
+  writeFiles(root, { "app/server.ts": text(edit(LINES, 5, "export const d = 1;")) });
+  sha.d1 = commit(["d is 1"]);
+  writeFiles(root, { "app/server.ts": text(edit(edit(LINES, 5, "export const d = 1;"), 6, "export const e = 1;")) });
+  sha.d2 = commit(["e is 1"]);
+  git(root, "checkout", "-q", main);
+
+  await record({ id: "run-a", harness: "claude-code", model: "claude-opus-5-5", unit: "W-001", startedAt: "2026-10-01T10:00:00Z", commits: [{ sha: sha.c1, hunks: [{ path: "app/server.ts", start: 2, end: 2 }] }] });
+  await record({ id: "run-b", harness: "claude-code", startedAt: "2026-10-01T11:00:00Z", commits: [sha.b1] });
+  await record({ id: "run-c", harness: "other", startedAt: "2026-10-01T11:30:00Z" });
+  await record({ id: "run-d", harness: "claude-code", startedAt: "2026-10-01T12:00:00Z", commits: [sha.d1, sha.d2] });
+
+  // main: a cherry-pick that keeps no trailer, a commit whose trailer names another run, and a squash.
+  git(root, "cherry-pick", sha.c1);
+  sha.p1 = git(root, "rev-parse", "HEAD");
+  writeFiles(root, { "app/server.ts": text(edit(edit(LINES, 2, "export const a = 1;"), 3, "export const b = 1;")) });
+  sha.p2 = commit(["b is 1, again", "Chant-Run: run-c"]);
+  git(root, "merge", "--squash", "-q", "squashed");
+  sha.sq = commit(["d and e (#7)"]);
+}, 60_000);
+afterAll(cleanScratch);
+
+describe("graph --intent joins by patch-id when the trailer is gone", () => {
+  test("a cherry-pick of a recorded commit joins its run by content", async () => {
+    const doc = await walk("app/server.ts:2");
+    expect(sha.p1).not.toBe(sha.c1);
+    expect(doc.edges.filter((e) => e.kind === "made-by" && e.from === `commit:${sha.p1}`)).toEqual([{ kind: "made-by", from: `commit:${sha.p1}`, to: "run:run-a", joinedBy: ["patch-id"], recordedAs: sha.c1 }]);
+    // The run's work item is carried as by any join, so the commit is s-001's own work.
+    expect(doc.edges).toContainEqual({ kind: "carries", from: `commit:${sha.p1}`, to: "record:work/W-001" });
+    expect(doc.edges).toContainEqual({ kind: "within", from: `commit:${sha.p1}`, to: "record:decision/s-001", state: "decided" });
+    // The why block marks the span and the run as joined by content. The recorded hunks are
+    // line numbers in the recorded commit, so a content join is not narrowed by them.
+    expect(doc.why.blame).toEqual([{ start: 2, end: 2, commit: `commit:${sha.p1}`, sha: sha.p1, runs: ["run:run-a"], narrowedBy: null, joinedBy: ["patch-id"] }]);
+    expect(doc.why.runs).toEqual([{ run: "run:run-a", lines: 1, commits: [`commit:${sha.p1}`], unit: { id: "W-001", kind: null, node: "record:work/W-001" }, decisions: ["record:decision/s-001"], joinedBy: ["patch-id"] }]);
+    expect(doc.why.decisions[0]).toMatchObject({ decision: "record:decision/s-001", relevance: "carried", lines: 1 });
+    expect(formatIntent(doc)).toContain(`run-a: claude-code/claude-opus-5-5, unpriced; joined by content, as ${sha.c1.slice(0, 8)}`);
+    expect(formatIntent(doc)).toContain("(joined by content)");
+  });
+
+  test("a trailer join is never overridden, and content that matches another run is a finding", async () => {
+    const doc = await walk("app/server.ts:3");
+    expect(doc.edges.filter((e) => e.kind === "made-by" && e.from === `commit:${sha.p2}`)).toEqual([{ kind: "made-by", from: `commit:${sha.p2}`, to: "run:run-c", joinedBy: ["trailer"] }]);
+    const conflict = doc.nodes.find((n) => n.kind === "finding" && n.code === "intent-commit-join-conflict");
+    expect(conflict).toMatchObject({ concerns: [`commit:${sha.p2}`, "run:run-c"] });
+    expect(conflict && "message" in conflict ? conflict.message : "").toContain(`run-b (${sha.b1.slice(0, 8)})`);
+  });
+
+  test("a squash of several commits has a patch-id of its own and doesn't join by content", async () => {
+    const doc = await walk("app/server.ts:5-6");
+    expect(doc.edges.filter((e) => e.kind === "made-by" && e.from === `commit:${sha.sq}`)).toEqual([]);
+    expect(doc.why.gaps.map((g) => g.code)).toContain("intent-why-no-run");
+  });
+
+  test("graph --intent --record lists the content join on the commit", async () => {
+    const { doc } = await intentRecord({ cwd: root, record: "s-001" });
+    contract(intentRecordSchema).expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.commits.find((c) => c.sha === sha.p1)?.runs).toEqual([
+      { id: "run-a", recorded: true, state: "ended", harness: "claude-code", model: "claude-opus-5-5", provider: null, by: null, agent: null, unit: "W-001", joinedBy: ["patch-id"], recordedAs: sha.c1 },
+    ]);
+  });
+});
+
+describe("runs --json joins by patch-id", () => {
+  test("a run lists the rewritten commit after the one it recorded, with no hunks", async () => {
+    const doc = await workspaceRuns({ cwd: root });
+    contract(runsSchema).expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    const byId = new Map(doc.runs.map((r) => [r.id, r]));
+    const a = byId.get("run-a")!;
+    expect(a.commits).toEqual([
+      { sha: sha.c1, patchId: expect.stringMatching(/^[0-9a-f]{40}$/), joinedBy: ["record"], hunks: [{ path: "app/server.ts", start: 2, end: 2 }] },
+      { sha: sha.p1, patchId: a.commits[0].patchId, joinedBy: ["patch-id"], hunks: null, recordedAs: sha.c1 },
+    ]);
+    // p2 carries Chant-Run: run-c, so it joins run C by trailer and run B not at all.
+    expect(byId.get("run-b")!.commits.map((c) => c.sha)).toEqual([sha.b1]);
+    expect(byId.get("run-c")!.commits).toEqual([{ sha: sha.p2, patchId: expect.any(String), joinedBy: ["trailer"], hunks: null }]);
+    // The squash joins neither of run D's commits.
+    expect(byId.get("run-d")!.commits.map((c) => c.sha)).toEqual([sha.d1, sha.d2]);
+  });
+});