@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/intent.ts

@@ -1,6 +1,7 @@
 /**
  * The intent graph over one region: `chant workspace graph --intent
- * <path[:start-end]>` (#2651; #2650 sections B and C1; #2524 D8, D15).
+ * <path[:start-end]|path#symbol>` (#2651; #2650 sections B and C1; #2524 D8,
+ * D15; #3034).
  *
  * A person points at some code and asks how it got this way and who decided
  * it should be this way. This module gathers what the workspace records about
@@ -30,7 +31,30 @@
  * record kind the declaration names (#2680), and each one's `commitJoins`
  * runs for every commit in that order. chant emits the
  * graph and hud renders it (#2524 D8, D15). Git is read through a local
- * `git` subprocess only: no fetch, no network.
+ * `git` subprocess only: no fetch, no network, except to follow a squash
+ * when asked (below).
+ *
+ * A region can name a symbol, `path#symbol`, which `symbols.ts` resolves to
+ * its current lines (#3034). For a file region the document also carries
+ * `why`: who made the region's current lines, from `git blame`, the agent run
+ * behind each (narrowed by the hunks a run recorded when several share a
+ * commit), and the decisions governing the region, most relevant first, with
+ * `explained: false` and closed gap codes when nothing accounts for it.
+ *
+ * A commit joins an agent run by its `Chant-Run` trailer or the run's own
+ * list of commits, and, failing both, by content (#3036): a commit whose
+ * `git patch-id --stable` equals one the run recorded, as after a rebase or a
+ * cherry-pick that dropped the trailer. Its `made-by` edge says `patch-id`,
+ * and a commit joined one way whose content matches another run's recorded
+ * commit is `intent-commit-join-conflict`.
+ *
+ * Asked to (`followSquash`, #3035), the walk follows a squash merge to its
+ * pull request's original commits (`squash.ts`): the squash commit node lists
+ * them with their trailers, joins and signatures, carries what their trailers
+ * and plugin joins carry, and joins their runs, marked `squash`. That is the
+ * one part of the walk that may reach the network, to fetch a pull request
+ * ref the clone lacks; a ref that can't be read is `squash-unfollowed` in
+ * `reasons`, and the walk keeps its answer without it.
  */
 
 import { execFileSync } from "node:child_process";
@@ -48,6 +72,11 @@ import type { DecidedIn } from "./record-decided";
 import { importKindModule, loadRecordKind, parseFrontMatter, RecordReadError, supersedesTargets, type LoadedRecordKind } from "./records";
 import { queryRecords, type RecordView } from "./records-cli";
 import { isPluginCode, type PluginCode, type ReasonCode } from "./reason-codes";
+import { addSquashRuns, RUN_JOIN_ORDER, runsForCommits, type RunCost, type RunJoin, type RunPin, type RunUsage, type RunView } from "./runs";
+import { followSquashes, squashLineOrigins, type Forge, type SquashFollow } from "./squash";
+import { memberDirOnDisk, memberSymbolResolvers, type SymbolPluginLoader } from "./lexicon-symbols";
+import { resolveSymbol, symbolResolverFor, type SymbolResolver } from "./symbols";
+import { readTrailerJoins, type CommitTrailerJoins } from "./trailer-joins";
 import { joinPath, skippedDir, type WorkspaceTree } from "./tree";
 import { activeAttestors, type ProvenanceLevel } from "./trust/attestor";
 import { commitProvenance, policyAtBase, resolveBase } from "./trust/provenance";
@@ -66,7 +95,7 @@ export const INTENT_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/works
 export const INTENT_FINDING_CODES = [
   /** A commit touched the region when no decision constrained it at path granularity. */
   "intent-commit-undecided",
-  /** A commit has no unit, no pull request reference and no decision covering the region at its time. */
+  /** A commit has no unit, carries no record through chant's trailers, has no pull request reference and no decision covering the region at its time. */
   "intent-commit-bare",
   /** A pinned artifact's bytes no longer hash to the pin. */
   "intent-pin-drifted",
@@ -98,6 +127,8 @@ export const INTENT_FINDING_CODES = [
   "intent-work-blocked",
   /** Commits in the region are a decision's own work while the work item implementing it is still open: the code says done and the queue says not (#2683). */
   "intent-work-open-decided-code",
+  /** A commit joined to an agent run by its trailer or the run's record has the patch-id of a commit another run recorded; the content join is not made (#3036). */
+  "intent-commit-join-conflict",
 ] as const satisfies readonly ReasonCode[];
 export type IntentFindingCode = (typeof INTENT_FINDING_CODES)[number];
 
@@ -107,6 +138,8 @@ export const INTENT_REASON_CODES = [
   "intent-history-shallow",
   /** A plugin's commitJoins failed for a commit. */
   "intent-plugin-failed",
+  /** A squash commit's pull request ref could not be read or fetched, so its original commits are not followed (#3035). */
+  "squash-unfollowed",
 ] as const satisfies readonly ReasonCode[];
 export type IntentReasonCode = (typeof INTENT_REASON_CODES)[number];
 
@@ -123,9 +156,28 @@ export const INTENT_ERROR_CODES = [
   "intent-region-invalid",
   /** --record names an id no record of a decision kind read has. */
   "intent-record-unknown",
+  /** The region names a symbol in a file no resolver reads (#3034). */
+  "intent-symbol-unsupported",
+  /** The region names a symbol the file does not declare (#3034). */
+  "intent-symbol-unknown",
+  /** The region names a symbol that matches more than one declaration (#3034). */
+  "intent-symbol-ambiguous",
 ] as const satisfies readonly ReasonCode[];
 export type IntentErrorCode = (typeof INTENT_ERROR_CODES)[number];
 
+/** Why `why` can't account for some or all of a region (#3034). Closed. */
+export const INTENT_WHY_CODES = [
+  /** No current decision governs the region, at any granularity, and none is carried out by the commits or runs that made its lines. */
+  "intent-why-no-decision",
+  /** None of the region's current lines was made by a commit an agent run is joined to. */
+  "intent-why-no-run",
+  /** Some of the region's lines are not committed, so nothing made them yet. */
+  "intent-why-uncommitted",
+  /** Some lines come from a commit that several runs made, and no run's recorded hunks say which wrote them. */
+  "intent-why-run-ambiguous",
+] as const satisfies readonly ReasonCode[];
+export type IntentWhyCode = (typeof INTENT_WHY_CODES)[number];
+
 export class IntentError extends Error {
   constructor(
     readonly code: IntentErrorCode,
@@ -157,6 +209,8 @@ export interface RegionNode {
   generated: boolean | null;
   /** Set when the region was given as a graph node id. */
   node: string | null;
+  /** Set when the region was given as `path#symbol` (#3034): the symbol as given, the declaration it resolved to, and its kind. `lines` holds its current lines. */
+  symbol?: { name: string; qualified: string; kind: string } | null;
 }
 
 export interface FileNode {
@@ -196,6 +250,46 @@ export interface CommitNode {
    * null when no record kind was read.
    */
   state: CommitState | null;
+  /**
+   * What chant's own trailers join the commit to (#3149, ws-075): the agent
+   * session, the work lease and the item it was taken on, the agent run, the
+   * records it names and the apply it records. A record or a lease item that
+   * a kind read has is linked by a `carries` edge.
+   */
+  joins: CommitTrailerJoins;
+  /**
+   * Set only when the walk follows squashes (#3035) and the commit squashes
+   * a pull request: its original commits, read from the forge's pull request
+   * ref. The commit carries what they carry and joins their runs.
+   */
+  squash?: SquashNode;
+}
+
+/** A squash commit's pull request, followed to its original commits (#3035). */
+export interface SquashNode {
+  pullRequest: number;
+  /** The forge `origin` points at, or null for one chant doesn't know. */
+  forge: Forge | null;
+  /** The local ref the pull request's head was read from, or null. */
+  ref: string | null;
+  /** The pull request's head commit, or null. */
+  head: string | null;
+  /** Whether this read fetched the ref. */
+  fetched: boolean;
+  /** Whether the original commits were read; when false, `squash-unfollowed` in `reasons` says why. */
+  followed: boolean;
+  /** The original commits, oldest first, each with what its own trailers join and its provenance level. */
+  commits: SquashedCommit[];
+}
+
+export interface SquashedCommit {
+  sha: string;
+  subject: string;
+  author: { name: string; email: string };
+  date: string;
+  trailers: Record<string, string[]>;
+  signature: { level: ProvenanceLevel; reason: string; principal?: string };
+  joins: CommitTrailerJoins;
 }
 
 export type CommitState = "decided" | "decided-by-window" | "undecided";
@@ -299,6 +393,18 @@ export interface WorkGapSource {
   artifact?: string;
 }
 
+/** A review session that led to a work item (#3154, E21). */
+export interface WorkReview {
+  /** The session record's node-style id, `record:<kind>/<id>`. */
+  id: string;
+  recordKind: string;
+  record: string;
+  path: string;
+  state: string | null;
+  /** The comments whose follow_ups name the item, numbered from 1; empty when only the session's own follow_ups do. */
+  comments: number[];
+}
+
 export interface WorkNode {
   id: string;
   kind: "work";
@@ -329,9 +435,47 @@ export interface WorkNode {
   constrains: { entry: string; granularity: Granularity }[];
   /** The item's work warnings, as records reports them, and work-done-gap-open. */
   warnings: { code: WorkWarningCode; message: string }[];
+  /**
+   * The review sessions whose comments led to this item (#3154, E21 in
+   * arugula-salad/hud#823): each session record of a session kind read whose
+   * `comments[].follow_ups` (or its own `follow_ups`) names the item as
+   * `<kind>:<id>`, with the 1-based numbers of those comments. A commit that
+   * carries the item, by its `Chant-Record: work:<id>` trailer, joins back
+   * to the review through it. Empty when none does. Added within contract 1.
+   */
+  reviews?: WorkReview[];
+}
+
+/**
+ * An agent run that made a commit in the walk (#3033): from the run ledger on
+ * the local `chant/lifecycle` branch. A run a `Chant-Run` trailer names and
+ * the ledger lacks is listed with `recorded: false` and nothing else known.
+ */
+export interface RunNode {
+  id: string;
+  kind: "run";
+  run: string;
+  recorded: boolean;
+  state: "running" | "ended" | null;
+  harness: { name: string; version: string | null } | null;
+  model: string | null;
+  provider: string | null;
+  by: string | null;
+  agent: string | null;
+  unit: string | null;
+  startedAt: string | null;
+  endedAt: string | null;
+  outcome: string | null;
+  usage: RunUsage | null;
+  cost: RunCost | null;
+  transcript: RunPin | null;
+  /** The instruction the run was given, pinned by hash, with the writer's excerpt when it gave one (#3034). */
+  instruction?: RunPin | null;
+  /** The fencing token of the work lease it worked under (#3034). */
+  lease?: string | null;
 }
 
-export type IntentNode = RegionNode | FileNode | MemberNode | CommitNode | JoinedNode | EvidenceEntryNode | DecisionNode | WorkNode | ArtifactNode | LinkNode | FindingNode;
+export type IntentNode = RegionNode | FileNode | MemberNode | CommitNode | JoinedNode | EvidenceEntryNode | DecisionNode | WorkNode | ArtifactNode | LinkNode | FindingNode | RunNode;
 
 export type Granularity = "path" | "member" | "contract" | "issue";
 
@@ -340,7 +484,87 @@ export type IntentEdge =
   | { kind: "pins"; from: string; to: string; pinnedSha256: string | null; pinState: PinState }
   | { kind: "touched-by"; from: string; to: string; lines: LineRange[] | null }
   | { kind: "within"; from: string; to: string; state: "decided" | "decided-by-window" | "worked" }
-  | { kind: "produced-by" | "serves" | "cites-evidence" | "supersedes" | "links" | "implements" | "needs" | "addressed-by"; from: string; to: string };
+  | { kind: "made-by"; from: string; to: string; joinedBy: RunJoin[]; recordedAs?: string; via?: string[] }
+  | { kind: "produced-by" | "serves" | "cites-evidence" | "supersedes" | "links" | "implements" | "needs" | "addressed-by" | "carries" | "worked-on"; from: string; to: string };
+
+/** Lines of the region that one commit, and the same runs, last wrote (#3034). */
+export interface WhySpan {
+  start: number;
+  end: number;
+  /** The commit node, or null for lines not committed yet. */
+  commit: string | null;
+  sha: string | null;
+  /** The run nodes behind these lines: the run the commit's Chant-Run names first, then those whose record lists it. */
+  runs: string[];
+  /** `hunks` when a run's recorded hunks chose among the commit's runs; null when every run that made the commit is listed. */
+  narrowedBy: "hunks" | null;
+  /** How the runs in `runs` join the commit, as their `made-by` edges say, without repeats (#3036). Empty with no runs. */
+  joinedBy: RunJoin[];
+  /**
+   * For lines of a followed squash (#3035): the sha of the original commit
+   * that last wrote them, one of the commit node's `squash.commits`, by blame
+   * at the pull request's head; `runs` keeps that commit's runs and the
+   * squash's own. Empty when the file at the head is not the squash's, so
+   * blame there can't say. Absent for any other commit.
+   */
+  via?: string[];
+}
+
+/** Why a decision is in `why`, most relevant first (#3034). */
+export type WhyRelevance = "carried" | "path" | "contract" | "issue" | "member" | "related";
+
+export interface WhyDecision {
+  decision: string;
+  /**
+   * carried: a commit or run that made the region's current lines carries it
+   * out. path, contract, issue, member: it constrains the region that way.
+   * related: it is in the graph only through supersession, or because a
+   * commit that no longer made any current line carried it out.
+   */
+  relevance: WhyRelevance;
+  /** Not superseded. */
+  current: boolean;
+  /** Its state is one its kind closes, such as ratified. */
+  closed: boolean;
+  /** How many of the region's current lines were made as its own work. */
+  lines: number;
+}
+
+export interface WhyRun {
+  run: string;
+  /** How many of the region's current lines it wrote. */
+  lines: number;
+  /** The commit nodes through which it made them. */
+  commits: string[];
+  /** The work item it worked on, as the run record names it, and its node when a work kind read has it. */
+  unit: { id: string; kind: string | null; node: string | null } | null;
+  /** The decision nodes it carried out: through its work item's implements, and the decision records it names. */
+  decisions: string[];
+  /** How it joins the commits in `commits`, as their `made-by` edges say, without repeats (#3036). */
+  joinedBy: RunJoin[];
+}
+
+export interface WhyGap {
+  code: IntentWhyCode;
+  message: string;
+  /** The lines the gap is about, when it is about some of them. */
+  lines?: LineRange[];
+}
+
+/** The answer to "why is it like this" over the region (#3034, hud#700). */
+export interface WhyAnswer {
+  /** The lines accounted for: the region's range, the whole file, or null for a directory, which is not blamed. */
+  lines: LineRange | null;
+  /** The current lines, top to bottom, each span with the commit and runs that last wrote it. Empty for a directory. */
+  blame: WhySpan[];
+  /** The decisions governing the region, most relevant first. */
+  decisions: WhyDecision[];
+  /** The runs that wrote the current lines, most lines first; for a directory, every run in the walk, newest first. */
+  runs: WhyRun[];
+  /** Whether a current decision governs the region or is carried out by what made its lines. */
+  explained: boolean;
+  gaps: WhyGap[];
+}
 
 export interface IntentReason {
   code: IntentReasonCode;
@@ -364,15 +588,18 @@ export type IntentDocument =
       edges: IntentEdge[];
       reasons: IntentReason[];
       summary: { commits: number; decisions: number; artifacts: number; findings: number };
+      why: WhyAnswer;
     })
   | (Head & { error: { code: IntentErrorCode; message: string } });
 
 export interface IntentQuery {
   /** Where the walk up to the declaration starts, and what the region path is relative to. */
   cwd: string;
-  /** `path`, `path:line` or `path:start-end`, or a graph node id `<member>/<id>`. */
+  /** `path`, `path:line`, `path:start-end` or `path#symbol`, or a graph node id `<member>/<id>`. */
   region: string;
   at?: string;
+  /** Follow squash merges to their pull requests' original commits, fetching a missing pull request ref from `origin` (#3035). */
+  followSquash?: boolean;
   /**
    * Kind files: record kinds, plugins with `commitJoins`, or both. Relative to
    * `cwd`. Left out, every record kind the declaration names, in its order
@@ -385,6 +612,11 @@ export interface IntentQuery {
    * --member` does.
    */
   resolveNode?: (cwd: string, at: string | undefined, member: string, id: string) => Promise<{ file: string; line: number | null } | null | undefined>;
+  /**
+   * Load a lexicon plugin by name, for the symbol resolvers a member's
+   * lexicons contribute (#3313). The default is the CLI's `loadPlugin`.
+   */
+  loadLexicon?: SymbolPluginLoader;
 }
 
 export interface IntentResult {
@@ -442,6 +674,45 @@ export function regionHistory(top: string, rev: string, gitPath: string, type: "
     .map((sha) => ({ sha, lines: null }));
 }
 
+/** One current line of a file, and the commit that last wrote it. */
+export interface BlamedLine {
+  line: number;
+  /** Null for a line not committed yet. */
+  sha: string | null;
+  /** The file's path in that commit, from the repository root. */
+  origPath: string;
+  /** The line's number in that commit's version of the file. */
+  origLine: number;
+}
+
+const ZERO_SHA = /^0+$/;
+
+/**
+ * `git blame` over a file's lines (#3034): at `rev`, or in the working tree
+ * when `rev` is null, where a line not committed yet has no commit. Undefined
+ * when git can't blame the file, such as one never committed.
+ */
+export function blameLines(top: string, rev: string | null, gitPath: string, lines: LineRange | null): BlamedLine[] | undefined {
+  const out = tryGit(top, ["blame", "--line-porcelain", ...(lines ? [`-L${lines.start},${lines.end}`] : []), ...(rev ? [rev] : []), "--", gitPath]);
+  if (out === undefined) return undefined;
+  const result: BlamedLine[] = [];
+  let current: { sha: string; origLine: number; line: number; origPath: string } | undefined;
+  for (const l of out.split("\n")) {
+    if (l.startsWith("\t")) {
+      if (current) result.push({ line: current.line, sha: ZERO_SHA.test(current.sha) ? null : current.sha, origPath: current.origPath, origLine: current.origLine });
+      current = undefined;
+      continue;
+    }
+    const head = l.match(/^([0-9a-f]{40,64}) (\d+) (\d+)(?: \d+)?$/);
+    if (head) {
+      current = { sha: head[1], origLine: Number(head[2]), line: Number(head[3]), origPath: gitPath };
+      continue;
+    }
+    if (current && l.startsWith("filename ")) current.origPath = l.slice("filename ".length);
+  }
+  return result;
+}
+
 /** Subject, body, author, date and trailers of each commit. */
 export function commitDetails(top: string, shas: string[]): Map<string, IntentCommit> {
   const out = new Map<string, IntentCommit>();
@@ -538,7 +809,8 @@ export function parseRegion(arg: string): { path: string; lines: LineRange | nul
   return { path: m[1], lines: { start, end } };
 }
 
-function regionId(path: string, lines: LineRange | null): string {
+function regionId(path: string, lines: LineRange | null, symbol?: string): string {
+  if (symbol !== undefined) return `region:${path}#${symbol}`;
   return `region:${path}${lines ? `:${lines.start}${lines.end === lines.start ? "" : `-${lines.end}`}` : ""}`;
 }
 
@@ -649,13 +921,46 @@ export async function loadKinds(query: IntentQuery, top: string): Promise<Loaded
   return out;
 }
 
-async function resolveRegion(query: IntentQuery, located: LocatedWorkspace, declaration: Declaration): Promise<{ path: string; lines: LineRange | null; node: string | null }> {
+interface ResolvedRegion {
+  path: string;
+  lines: LineRange | null;
+  node: string | null;
+  symbol: { name: string; qualified: string; kind: string } | null;
+}
+
+async function resolveRegion(query: IntentQuery, located: LocatedWorkspace, declaration: Declaration): Promise<ResolvedRegion> {
   const parsed = parseRegion(query.region);
   if ("error" in parsed) throw new IntentError("intent-region-invalid", parsed.error);
-  const rel = toPosix(relative(realpathOr(located.rootOnDisk), resolve(realpathOr(query.cwd), parsed.path)));
-  const path = rel === "" ? "." : rel;
-  if (path === "." || (isWorkspacePath(path) && !path.startsWith("../") && located.tree.stat(path) !== undefined)) {
-    return { path, lines: parsed.lines, node: null };
+  const inWorkspace = (p: string): string | undefined => {
+    const rel = toPosix(relative(realpathOr(located.rootOnDisk), resolve(realpathOr(query.cwd), p)));
+    const path = rel === "" ? "." : rel;
+    return path === "." || (isWorkspacePath(path) && !path.startsWith("../") && located.tree.stat(path) !== undefined) ? path : undefined;
+  };
+  const path = inWorkspace(parsed.path);
+  if (path !== undefined) return { path, lines: parsed.lines, node: null, symbol: null };
+  // path#symbol (#3034): the symbol's current lines in the tree read.
+  const hash = parsed.lines ? -1 : query.region.lastIndexOf("#");
+  if (hash > 0) {
+    const name = query.region.slice(hash + 1);
+    const file = inWorkspace(query.region.slice(0, hash));
+    if (file !== undefined && name !== "") {
+      if (file === "." || located.tree.stat(file) !== "file") throw new IntentError("intent-region-invalid", `${file} is a directory, and a symbol needs a file`);
+      // A file core's resolver doesn't read may have one from its member's lexicons (#3313).
+      let extra: SymbolResolver[] = [];
+      let why = "";
+      if (!symbolResolverFor(file)) {
+        const holder = memberHolding(file, declaration.members);
+        const m = holder ? declaration.members.find((x) => x.name === holder) : undefined;
+        if (m && m.kind === "chant") {
+          const got = await memberSymbolResolvers(memberDirOnDisk(located.rootOnDisk, m.dir), query.loadLexicon);
+          extra = got.resolvers;
+          if (got.problems.length > 0) why = `; member ${m.name}: ${got.problems.join("; ")}`;
+        }
+      }
+      const r = resolveSymbol(file, located.tree.read(file), name, extra);
+      if (!r.ok) throw new IntentError(r.reason === "unsupported" ? "intent-symbol-unsupported" : r.reason === "ambiguous" ? "intent-symbol-ambiguous" : "intent-symbol-unknown", `${r.message}${r.reason === "unsupported" ? why : ""}${located.tree.label}`);
+      return { path: file, lines: r.declaration.lines, node: null, symbol: { name, qualified: r.declaration.qualified, kind: r.declaration.kind } };
+    }
   }
   // A graph node id, <member>/<id>, when no such path exists (#2650 B1).
   const slash = query.region.indexOf("/");
@@ -664,10 +969,10 @@ async function resolveRegion(query: IntentQuery, located: LocatedWorkspace, decl
     const loc = await (query.resolveNode ?? resolveNodeFromGraph)(query.cwd, query.at, member.name, query.region);
     if (loc) {
       const file = joinPath(member.dir, loc.file);
-      return { path: file === "" ? "." : file, lines: loc.line ? { start: loc.line, end: loc.line } : null, node: query.region };
+      return { path: file === "" ? "." : file, lines: loc.line ? { start: loc.line, end: loc.line } : null, node: query.region, symbol: null };
     }
   }
-  throw new IntentError("intent-region-invalid", `${query.region} is not a path in the workspace${located.tree.label}, or a graph node id`);
+  throw new IntentError("intent-region-invalid", `${query.region} is not a path in the workspace${located.tree.label}, a path#symbol, or a graph node id`);
 }
 
 /** Build the intent document. Never throws an {@link IntentError}, {@link WorkspaceReadError} or {@link RecordReadError}. */
@@ -714,8 +1019,19 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
 
   // The region, its files and its member.
   const member = region.path === "." ? (declaration.members.find((m) => m.dir === ".")?.name ?? null) : memberHolding(region.path, declaration.members);
-  const rid = regionId(region.path, region.lines);
-  add<RegionNode>({ id: rid, kind: "region", path: region.path, lines: region.lines, member, at: located.at, type, generated: type === "file" ? isGeneratedPath(declaration, region.path) : null, node: region.node });
+  const rid = regionId(region.path, region.lines, region.symbol?.name);
+  add<RegionNode>({
+    id: rid,
+    kind: "region",
+    path: region.path,
+    lines: region.lines,
+    member,
+    at: located.at,
+    type,
+    generated: type === "file" ? isGeneratedPath(declaration, region.path) : null,
+    node: region.node,
+    symbol: region.symbol,
+  });
   const files = type === "dir" ? filesUnder(located.tree, region.path) : [];
   for (const f of files) add<FileNode>({ id: `file:${f}`, kind: "file", path: f, member: memberHolding(f, declaration.members), generated: isGeneratedPath(declaration, f) });
   const memberNode = (name: string) => {
@@ -731,7 +1047,27 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
   const workspacePrefix = located.root === "." ? "" : located.root;
   const gitPath = joinPath(workspacePrefix, region.path);
   const touched = rev ? regionHistory(top, rev, gitPath, type, region.lines) : [];
+  // Who last wrote each current line of a file region (#3034). A commit blame
+  // names and the history walk missed, as when a move confuses git log -L,
+  // joins the commits that touched the region.
+  const fileLines = type === "file" ? (region.lines ?? { start: 1, end: Math.max(1, located.tree.read(region.path).replace(/\n$/, "").split("\n").length) }) : null;
+  const blamed: BlamedLine[] =
+    fileLines === null
+      ? []
+      : ((rev ? blameLines(top, located.at, gitPath, region.lines) : undefined) ??
+        // A file git can't blame in the working tree has never been committed: every line is new.
+        (located.at === null ? Array.from({ length: fileLines.end - fileLines.start + 1 }, (_, i) => ({ line: fileLines.start + i, sha: null, origPath: gitPath, origLine: fileLines.start + i })) : []));
+  for (const sha of new Set(blamed.map((b) => b.sha).filter((x): x is string => x !== null))) {
+    if (!touched.some((t) => t.sha === sha)) touched.push({ sha, lines: null });
+  }
   const details = commitDetails(top, touched.map((t) => t.sha));
+  // Squash merges, followed to the pull request's original commits when asked (#3035).
+  const follows = query.followSquash ? followSquashes(top, [...details.values()], { fetchMissing: true }) : new Map<string, SquashFollow>();
+  for (const f of follows.values()) {
+    if (f.problem) reasons.push({ code: "squash-unfollowed", message: `${f.sha.slice(0, 8)} squashes pull request #${f.pullRequest}, and ${f.problem}, so its original commits are not followed` });
+  }
+  const originalDetails = commitDetails(top, [...new Set([...follows.values()].flatMap((f) => f.commits))]);
+  const originalsOf = (sha: string): IntentCommit[] => (follows.get(sha)?.commits ?? []).map((o) => originalDetails.get(o)).filter((x): x is IntentCommit => x !== undefined);
 
   // Each commit's provenance, judged by the policy at base as records judges a record's (#2547).
   const policy = policyAtBase(top, resolveBase(top));
@@ -752,60 +1088,128 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     unit?: string;
     contracts: string[];
     authorship: string[];
-    /** The record ids the commit's units and contracts say they carry out. */
+    /** The record ids the commit's units and contracts say they carry out, and the ones its Chant-Record and Chant-Lease trailers name or implement. */
     decisions: string[];
+    /** The nodes of the records the commit's own trailers name (#3149). */
+    carries: string[];
   }
   const joined = new Map<string, Joined>();
+  // chant's own trailers on each commit (#3149), with the items their lease tokens name.
+  const trailerJoins = readTrailerJoins(top, [...details.values(), ...originalDetails.values()]);
   const pluginFindings: { commit: string; plugin: string; finding: PluginFinding }[] = [];
+  const signatureOf = (sha: string): CommitNode["signature"] => {
+    if (!policy.active) return { level: "unattested", reason: policy.problems.length ? policy.problems.join("; ") : `no signers file (${policy.signersPath}) at base; attestation is off` };
+    const p = commitProvenance(top, policy, sha, attestors);
+    return { level: p.level, reason: p.reason, ...(p.principal ? { principal: p.principal } : {}) };
+  };
   const failedPlugins = new Set<string>();
   for (const t of touched) {
     const c = details.get(t.sha);
     if (!c) continue;
-    const signature = policy.active
-      ? (() => {
-          const p = commitProvenance(top, policy, c.sha, attestors);
-          return { level: p.level, reason: p.reason, ...(p.principal ? { principal: p.principal } : {}) };
-        })()
-      : { level: "unattested" as const, reason: policy.problems.length ? policy.problems.join("; ") : `no signers file (${policy.signersPath}) at base; attestation is off` };
+    const signature = signatureOf(c.sha);
     const pr = c.subject.match(/\(#([0-9]+)\)\s*$/);
     const cid = `commit:${c.sha}`;
-    add<CommitNode>({ id: cid, kind: "commit", sha: c.sha, subject: c.subject, author: c.author, date: c.date, trailers: c.trailers, pullRequest: pr ? Number(pr[1]) : null, signature, lines: t.lines, state: null });
+    const f = follows.get(c.sha);
+    const squash: SquashNode | undefined = f
+      ? {
+          pullRequest: f.pullRequest,
+          forge: f.forge,
+          ref: f.ref,
+          head: f.head,
+          fetched: f.fetched,
+          followed: f.followed,
+          commits: originalsOf(c.sha).map((o) => ({ sha: o.sha, subject: o.subject, author: o.author, date: o.date, trailers: o.trailers, signature: signatureOf(o.sha), joins: trailerJoins.get(o.sha)!.joins })),
+        }
+      : undefined;
+    add<CommitNode>({ id: cid, kind: "commit", sha: c.sha, subject: c.subject, author: c.author, date: c.date, trailers: c.trailers, pullRequest: pr ? Number(pr[1]) : null, signature, lines: t.lines, state: null, joins: trailerJoins.get(c.sha)!.joins, ...(squash ? { squash } : {}) });
     edges.push({ kind: "touched-by", from: rid, to: cid, lines: t.lines });
 
-    // 2. Each commit's origin, from the plugins.
-    const entry: Joined = { contracts: [], authorship: [], decisions: [] };
+    // 2. Each commit's origin, from the plugins. A followed squash also takes its original commits' (#3035).
+    const entry: Joined = { contracts: [], authorship: [], decisions: [], carries: [] };
     joined.set(c.sha, entry);
+    const pushEdge = (e: IntentEdge) => {
+      if (!edges.some((x) => x.kind === e.kind && x.from === e.from && x.to === e.to)) edges.push(e);
+    };
+    const subjects: IntentCommit[] = [c, ...originalsOf(c.sha)];
     for (const k of kinds) {
       if (!k.joins) continue;
-      let result;
-      try {
-        result = await runCommitJoins(k.joins, c, { read: readAt, list: listAt, at: located.at }, k.name);
-      } catch (err) {
-        const message = `${k.display}: commitJoins failed for ${c.sha.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`;
-        if (!failedPlugins.has(message)) reasons.push({ code: "intent-plugin-failed", message });
-        failedPlugins.add(message);
-        continue;
-      }
-      const joinedNode = (kind: JoinedNode["kind"], e: JoinedEntity): string => {
-        const { id, ...data } = e;
-        return add<JoinedNode>({ id: `${kind}:${id}`, kind, ref: id, plugin: k.display, data }).id;
-      };
-      const unitId = result.unit ? joinedNode("unit", result.unit) : undefined;
-      const contractId = result.contract ? joinedNode("contract", result.contract) : undefined;
-      if (unitId) {
-        entry.unit = unitId;
-        edges.push({ kind: "produced-by", from: cid, to: unitId });
-        if (contractId) edges.push({ kind: "serves", from: unitId, to: contractId });
+      for (const subject of subjects) {
+        const original = subject !== c;
+        let result;
+        try {
+          result = await runCommitJoins(k.joins, subject, { read: readAt, list: listAt, at: located.at }, k.name);
+        } catch (err) {
+          const message = `${k.display}: commitJoins failed for ${subject.sha.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`;
+          if (!failedPlugins.has(message)) reasons.push({ code: "intent-plugin-failed", message });
+          failedPlugins.add(message);
+          continue;
+        }
+        const joinedNode = (kind: JoinedNode["kind"], e: JoinedEntity): string => {
+          const { id, ...data } = e;
+          return add<JoinedNode>({ id: `${kind}:${id}`, kind, ref: id, plugin: k.display, data }).id;
+        };
+        const unitId = result.unit ? joinedNode("unit", result.unit) : undefined;
+        const contractId = result.contract ? joinedNode("contract", result.contract) : undefined;
+        if (unitId) {
+          if (original) entry.unit ??= unitId;
+          else entry.unit = unitId;
+          pushEdge({ kind: "produced-by", from: cid, to: unitId });
+          if (contractId) pushEdge({ kind: "serves", from: unitId, to: contractId });
+        }
+        if (contractId) entry.contracts.push(result.contract!.id);
+        if (unitId) entry.decisions.push(...entityDecisions(result.unit), ...entityDecisions(result.contract));
+        for (const f of result.findings ?? []) pluginFindings.push({ commit: cid, plugin: k.display, finding: f });
+        const evidence = result.evidence === undefined ? [] : Array.isArray(result.evidence) ? result.evidence : [result.evidence];
+        for (const e of evidence) pushEdge({ kind: "cites-evidence", from: unitId ?? contractId ?? cid, to: joinedNode("evidence", e) });
+        // Authorship is checked against the squash's own trailers, so only its own claims count.
+        if (!original) entry.authorship.push(...(result.authorship ?? []));
       }
-      if (contractId) entry.contracts.push(result.contract!.id);
-      if (unitId) entry.decisions.push(...entityDecisions(result.unit), ...entityDecisions(result.contract));
-      for (const f of result.findings ?? []) pluginFindings.push({ commit: cid, plugin: k.display, finding: f });
-      const evidence = result.evidence === undefined ? [] : Array.isArray(result.evidence) ? result.evidence : [result.evidence];
-      for (const e of evidence) edges.push({ kind: "cites-evidence", from: unitId ?? contractId ?? cid, to: joinedNode("evidence", e) });
-      entry.authorship.push(...(result.authorship ?? []));
     }
   }
 
+  // The agent runs that made each commit (#3033): the one its Chant-Run names, and any whose record lists it.
+  const runJoins = await runsForCommits(
+    top,
+    located.rootOnDisk,
+    [...new Set([...touched.map((t) => t.sha), ...originalDetails.keys()])].map((sha) => ({ sha, run: trailerJoins.get(sha)?.joins.run ?? null })),
+  );
+  // A followed squash joins its original commits' runs (#3035).
+  addSquashRuns(runJoins.refs, follows);
+  for (const t of touched) {
+    if (!nodes.has(`commit:${t.sha}`)) continue;
+    for (const ref of runJoins.refs.get(t.sha) ?? []) {
+      const r = runJoins.runs.get(ref.id);
+      const node = add<RunNode>({
+        id: `run:${ref.id}`,
+        kind: "run",
+        run: ref.id,
+        recorded: r !== undefined,
+        state: r?.state ?? null,
+        harness: r?.harness ?? null,
+        model: r?.model ?? null,
+        provider: r?.provider ?? null,
+        by: r?.by ?? null,
+        agent: r?.agent ?? null,
+        unit: r?.unit?.id ?? null,
+        startedAt: r?.startedAt ?? null,
+        endedAt: r?.endedAt ?? null,
+        outcome: r?.outcome ?? null,
+        usage: r?.usage ?? null,
+        cost: r?.cost ?? null,
+        transcript: r?.transcript ?? null,
+        instruction: r?.instruction ?? null,
+        lease: r?.lease ?? null,
+      });
+      edges.push({ kind: "made-by", from: `commit:${t.sha}`, to: node.id, joinedBy: ref.joinedBy, ...(ref.recordedAs ? { recordedAs: ref.recordedAs } : {}), ...(ref.via ? { via: ref.via } : {}) });
+    }
+  }
+  // A commit a trailer or a record joins to one run, with the content of a commit another run recorded (#3036).
+  for (const x of runJoins.conflicts) {
+    if (!nodes.has(`commit:${x.sha}`)) continue;
+    const others = x.content.map((m) => `${m.run} (${m.sha.slice(0, 8)})`).join(", ");
+    find("intent-commit-join-conflict", `${x.sha.slice(0, 8)} joins ${x.joined.join(", ")} by its trailer or the run's record, and has the patch-id of a commit ${others} recorded; it is not joined to ${x.content.length === 1 ? "that run" : "those runs"}`, [`commit:${x.sha}`, ...x.joined.map((id) => `run:${id}`)]);
+  }
+
   // 3. The decisions whose constrains cover the region, and their chains.
   const regionFull = region.path === "." ? workspacePrefix : gitPath;
   const origin = originRepo(top);
@@ -1099,16 +1503,6 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     }
     if (node.constrains.length > 0) workCovering.push(h);
   }
-  for (const h of workAll.filter((x) => x.node)) {
-    for (const id of implementedIds(h)) {
-      const hit = decisionById.get(id.slice("record:".length))!;
-      edges.push({ kind: "implements", from: h.node!.id, to: decisionNode(hit.kind, hit.view).id });
-    }
-    for (const n of idList(h.view.data, workSpec(h).needs)) {
-      const hit = workByKey.get(`${h.kind.records!.loaded.kind.name}/${n}`);
-      if (hit) edges.push({ kind: "needs", from: h.node!.id, to: workNode(hit).id });
-    }
-  }
   const workWindows = new Map<string, { from: Set<string>; until: Set<string> | null }>();
   if (rev) {
     for (const h of workCovering) {
@@ -1125,6 +1519,105 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     return !!w && w.from.has(sha) && !w.until?.has(sha);
   };
 
+  // The records chant's own trailers name (#3149): a Chant-Record of a kind
+  // read, and the work item a Chant-Lease was taken on. The commit carries
+  // each, and is the own work of a decision it names or that a work item it
+  // names implements.
+  const recordKinds = new Map(kinds.filter((k) => k.records).map((k) => [k.records!.loaded.kind.name, k]));
+  /** The work item a run worked on and the records it names, among the kinds read, deduplicated. */
+  const runTargets = (r: RunView): { node: string; work?: WorkHit; decision?: string }[] => {
+    const out: { node: string; work?: WorkHit; decision?: string }[] = [];
+    const push = (x: { node: string; work?: WorkHit; decision?: string }) => {
+      if (!out.some((o) => o.node === x.node)) out.push(x);
+    };
+    if (r.unit) {
+      const named = r.unit.kind ? workKinds.filter((k) => k.records!.loaded.kind.name === r.unit!.kind) : workKinds;
+      const hits = named.map((k) => workByKey.get(`${k.records!.loaded.kind.name}/${r.unit!.id}`)).filter((h): h is WorkHit => h !== undefined);
+      if (hits.length === 1) push({ node: workNode(hits[0]).id, work: hits[0] });
+    }
+    for (const ref of r.records) {
+      const k = recordKinds.get(ref.kind);
+      if (!k) continue;
+      if (k.records!.loaded.kind.work) {
+        const h = workByKey.get(`${ref.kind}/${ref.id}`);
+        if (h) push({ node: workNode(h).id, work: h });
+        continue;
+      }
+      const hit = decisionById.get(`${ref.kind}/${ref.id}`);
+      if (hit) push({ node: decisionNode(hit.kind, hit.view).id, decision: `${ref.kind}/${ref.id}` });
+    }
+    return out;
+  };
+  for (const t of touched) {
+    const c = nodes.get(`commit:${t.sha}`) as CommitNode | undefined;
+    const j = joined.get(t.sha);
+    if (!c || !j) continue;
+    const carry = (to: string) => {
+      if (j.carries.includes(to)) return;
+      j.carries.push(to);
+      edges.push({ kind: "carries", from: c.id, to });
+    };
+    const carryWork = (h: WorkHit): string => {
+      const node = workNode(h);
+      carry(node.id);
+      j.decisions.push(...implementedIds(h).map((id) => id.slice("record:".length)));
+      return node.id;
+    };
+    // The commit's own trailers, and a followed squash's original commits' (#3035).
+    for (const joins of [c.joins, ...(c.squash?.commits ?? []).map((o) => o.joins)]) {
+      for (const r of joins.records) {
+        const k = recordKinds.get(r.kind);
+        if (!k) continue;
+        if (k.records!.loaded.kind.work) {
+          const h = workByKey.get(`${r.kind}/${r.id}`);
+          if (h) r.node = carryWork(h);
+          continue;
+        }
+        const hit = decisionById.get(`${r.kind}/${r.id}`);
+        if (!hit) continue;
+        r.node = decisionNode(hit.kind, hit.view).id;
+        carry(r.node);
+        j.decisions.push(`${r.kind}/${r.id}`);
+      }
+      const item = joins.lease?.item;
+      if (item) {
+        const hits = workKinds.map((k) => workByKey.get(`${k.records!.loaded.kind.name}/${item}`)).filter((h): h is WorkHit => h !== undefined);
+        if (hits.length === 1) carryWork(hits[0]);
+      }
+    }
+    // The runs that made the commit (#3034): its run's work item and the
+    // records the run names are carried as a Chant-Lease and a Chant-Record are.
+    for (const ref of runJoins.refs.get(t.sha) ?? []) {
+      const r = runJoins.runs.get(ref.id);
+      if (!r) continue;
+      for (const target of runTargets(r)) {
+        if (target.work) carryWork(target.work);
+        else if (target.decision) {
+          carry(target.node);
+          j.decisions.push(target.decision);
+        }
+      }
+    }
+  }
+  // Each recorded run in the walk to the work item and records it worked on (#3034).
+  for (const n of [...nodes.values()]) {
+    if (n.kind !== "run") continue;
+    const r = runJoins.runs.get(n.run);
+    if (!r) continue;
+    for (const target of runTargets(r)) edges.push({ kind: "worked-on", from: n.id, to: target.node });
+  }
+  // Each work item in the graph, those its commits and runs carry included, to the decisions it implements and the items it needs.
+  for (const h of workAll.filter((x) => x.node)) {
+    for (const id of implementedIds(h)) {
+      const hit = decisionById.get(id.slice("record:".length))!;
+      edges.push({ kind: "implements", from: h.node!.id, to: decisionNode(hit.kind, hit.view).id });
+    }
+    for (const n of idList(h.view.data, workSpec(h).needs)) {
+      const hit = workByKey.get(`${h.kind.records!.loaded.kind.name}/${n}`);
+      if (hit) edges.push({ kind: "needs", from: h.node!.id, to: workNode(hit).id });
+    }
+  }
+
   const coveredAt = (sha: string, granularities: Granularity[]) =>
     covering.filter((c) => {
       if (!c.node.constrains.some((x) => granularities.includes(x.granularity))) return false;
@@ -1133,9 +1626,10 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     });
   const readsRecords = kinds.some((k) => k.records);
   // A decision's own work: a commit whose unit, or that unit's contract, names
-  // the decision, or whose unit serves a contract the decision constrains.
+  // the decision, or whose unit serves a contract the decision constrains; or
+  // a commit whose own trailers name the decision, or a work item implementing it.
   const ownWork = (j: Joined, d: DecisionNode) =>
-    !!j.unit && (j.decisions.some((x) => x === d.record || x === `${d.recordKind}/${d.record}`) || d.constrains.some((x) => x.granularity === "contract" && j.contracts.includes(x.entry)));
+    (!!j.unit || j.carries.length > 0) && (j.decisions.some((x) => x === d.record || x === `${d.recordKind}/${d.record}`) || d.constrains.some((x) => x.granularity === "contract" && j.contracts.includes(x.entry)));
   for (const t of touched) {
     const c = nodes.get(`commit:${t.sha}`) as CommitNode | undefined;
     if (!c) continue;
@@ -1152,8 +1646,8 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     if (readsRecords && c.state === "undecided") {
       find("intent-commit-undecided", `${t.sha.slice(0, 8)} changed the region when no decision constrained ${region.path} by path`, [c.id, rid]);
     }
-    if (readsRecords && !j.unit && c.pullRequest === null && coveredAt(t.sha, ["path", "member", "contract", "issue"]).length === 0) {
-      find("intent-commit-bare", `${t.sha.slice(0, 8)} names no unit, no pull request and no decision`, [c.id]);
+    if (readsRecords && !j.unit && j.carries.length === 0 && c.pullRequest === null && coveredAt(t.sha, ["path", "member", "contract", "issue"]).length === 0) {
+      find("intent-commit-bare", `${t.sha.slice(0, 8)} names no unit, no record, no pull request and no decision`, [c.id]);
     }
     const claims = [...new Set(j.authorship)].filter((key) => hasTrailer(c.trailers, key));
     if (claims.length > 0 && c.signature.level !== "attested") {
@@ -1303,7 +1797,37 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
       for (const h of by) edges.push({ kind: "addressed-by", from: f.id, to: workNode(h).id });
     }
   }
+  // Reviews that led to a work item in the graph (#3154, E21): a session's comments[].follow_ups name it.
+  const workNodes = [...nodes.values()].filter((n): n is WorkNode => n.kind === "work");
+  if (workNodes.length > 0) {
+    const byRef = new Map(workNodes.map((n) => [`${n.recordKind}:${n.record}`, n]));
+    for (const k of kinds) {
+      const loaded = k.records?.loaded.kind;
+      if (!loaded?.session) continue;
+      for (const v of k.records!.views) {
+        if (v.id === null || !v.data) continue;
+        const hits = new Map<WorkNode, number[]>();
+        const note = (refs: unknown, comment: number | null) => {
+          if (!Array.isArray(refs)) return;
+          for (const ref of refs) {
+            const n = typeof ref === "string" ? byRef.get(ref) : undefined;
+            if (!n) continue;
+            const list = hits.get(n) ?? [];
+            if (comment !== null && !list.includes(comment)) list.push(comment);
+            hits.set(n, list);
+          }
+        };
+        note(v.data.follow_ups, null);
+        const comments = Array.isArray(v.data.comments) ? v.data.comments : [];
+        comments.forEach((c: unknown, i: number) => note((c as { follow_ups?: unknown } | null)?.follow_ups, i + 1));
+        for (const [n, list] of hits) {
+          (n.reviews ??= []).push({ id: `record:${loaded.name}/${v.id}`, recordKind: loaded.name, record: v.id, path: v.path, state: v.state, comments: list.sort((a, b) => a - b) });
+        }
+      }
+    }
+  }
   for (const f of findings) nodes.set(f.id, f);
+  const why = explain();
   const all = [...nodes.values()];
   return {
     doc: {
@@ -1322,7 +1846,140 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
         artifacts: all.filter((n) => n.kind === "artifact").length,
         findings: findings.length,
       },
+      why,
     },
     failed: reasons.some((r) => r.code === "intent-plugin-failed"),
   };
+
+  /** "Why is it like this" over the region (#3034): who made its current lines, and the decisions governing it, most relevant first. */
+  function explain(): WhyAnswer {
+    const hunksOf = (run: string, sha: string) => runJoins.runs.get(run)?.commits.find((c) => c.sha === sha)?.hunks ?? null;
+    const joinOf = (run: string, sha: string): RunJoin[] => (runJoins.refs.get(sha) ?? []).find((r) => r.id === run)?.joinedBy ?? [];
+    const joinsOf = (runs: string[], shas: string[]): RunJoin[] => {
+      const all = new Set(runs.flatMap((id) => shas.flatMap((sha) => joinOf(id, sha))));
+      return RUN_JOIN_ORDER.filter((j) => all.has(j));
+    };
+    // For a followed squash (#3035), the original commit behind each of its lines, by blame at the pull request's head.
+    const origins = new Map<string, Map<number, string> | undefined>();
+    const originOf = (sha: string, path: string, line: number): { squash: boolean; origin: string | undefined } => {
+      const f = follows.get(sha);
+      if (!f?.followed || !f.head) return { squash: false, origin: undefined };
+      const key = `${sha}\0${path}`;
+      if (!origins.has(key)) origins.set(key, squashLineOrigins(top!, sha, f.head, path, new Set(f.commits)));
+      return { squash: true, origin: origins.get(key)?.get(line) };
+    };
+    // Each current line: its commit, and the runs that wrote it.
+    const who = blamed.map((b) => {
+      if (b.sha === null) return { line: b.line, sha: null, runs: [] as string[], narrowedBy: null as "hunks" | null, via: undefined as string[] | undefined };
+      const sha = b.sha;
+      const { squash, origin } = originOf(sha, b.origPath, b.origLine);
+      const via = squash ? (origin ? [origin] : []) : undefined;
+      // On a squash line blame at the head traced to one original, a run joined only through the other originals didn't write it.
+      const refs = (runJoins.refs.get(sha) ?? []).filter((r) => !origin || r.joinedBy.some((j) => j !== "squash") || (r.via ?? []).includes(origin)).map((r) => r.id);
+      const withHunks = refs.filter((id) => hunksOf(id, sha) !== null);
+      if (withHunks.length === 0) return { line: b.line, sha, runs: refs, narrowedBy: null, via };
+      const wrote = withHunks.filter((id) => hunksOf(id, sha)!.some((h) => h.path === b.origPath && h.start <= b.origLine && b.origLine <= h.end));
+      // A run that recorded its hunks and doesn't cover the line didn't write it; a run that recorded none may have.
+      return { line: b.line, sha, runs: wrote.length > 0 ? wrote : refs.filter((id) => !withHunks.includes(id)), narrowedBy: "hunks" as const, via };
+    });
+    const spans: WhySpan[] = [];
+    for (const w of who) {
+      const last = spans[spans.length - 1];
+      const via = w.via;
+      if (last && last.end === w.line - 1 && last.sha === w.sha && last.narrowedBy === w.narrowedBy && last.runs.join("\0") === w.runs.map((r) => `run:${r}`).join("\0") && last.via?.join("\0") === via?.join("\0")) {
+        last.end = w.line;
+        continue;
+      }
+      spans.push({ start: w.line, end: w.line, commit: w.sha ? `commit:${w.sha}` : null, sha: w.sha, runs: w.runs.map((r) => `run:${r}`), narrowedBy: w.narrowedBy, joinedBy: w.sha ? joinsOf(w.runs, [w.sha]) : [], ...(via ? { via } : {}) });
+    }
+    const ranges = (lines: number[]): LineRange[] => {
+      const out: LineRange[] = [];
+      for (const l of lines) {
+        const last = out[out.length - 1];
+        if (last && last.end === l - 1) last.end = l;
+        else out.push({ start: l, end: l });
+      }
+      return out;
+    };
+
+    // The decisions, most relevant first.
+    const decisionNodes = [...nodes.values()].filter((n): n is DecisionNode => n.kind === "decision");
+    const ownLines = (d: DecisionNode) => who.filter((w) => w.sha !== null && ownWork(joined.get(w.sha) ?? { contracts: [], authorship: [], decisions: [], carries: [] }, d)).length;
+    const ORDER: WhyRelevance[] = ["carried", "path", "contract", "issue", "member", "related"];
+    const ranked = decisionNodes.map((d) => {
+      const lines = ownLines(d);
+      const carried = lines > 0 || (fileLines === null && touched.some((t) => ownWork(joined.get(t.sha) ?? { contracts: [], authorship: [], decisions: [], carries: [] }, d)));
+      const granularities = new Set(d.constrains.map((c) => c.granularity));
+      const relevance: WhyRelevance = carried ? "carried" : ((["path", "contract", "issue", "member"] as const).find((g) => granularities.has(g)) ?? "related");
+      // A narrower path constraint is more specific to the region.
+      const specificity = Math.max(0, ...d.constrains.filter((c) => c.granularity === "path").map((c) => c.entry.length));
+      return { d, entry: { decision: d.id, relevance, current: d.supersededBy === null, closed: d.closed, lines } satisfies WhyDecision, specificity };
+    });
+    ranked.sort(
+      (a, b) =>
+        Number(b.entry.current) - Number(a.entry.current) ||
+        ORDER.indexOf(a.entry.relevance) - ORDER.indexOf(b.entry.relevance) ||
+        b.entry.lines - a.entry.lines ||
+        Number(b.entry.closed) - Number(a.entry.closed) ||
+        b.specificity - a.specificity ||
+        (b.d.decidedIn?.date ?? "").localeCompare(a.d.decidedIn?.date ?? "") ||
+        a.d.id.localeCompare(b.d.id),
+    );
+    const decisions = ranked.map((r) => r.entry);
+
+    // The runs that wrote the current lines, most lines first; for a directory, every run in the walk.
+    const runNodes = [...nodes.values()].filter((n): n is RunNode => n.kind === "run");
+    const runEntry = (n: RunNode, lines: number, commits: string[]): WhyRun => {
+      const r = runJoins.runs.get(n.run);
+      const targets = edges.filter((e) => e.kind === "worked-on" && e.from === n.id).map((e) => nodes.get(e.to));
+      const work = r?.unit ? targets.find((t): t is WorkNode => t?.kind === "work" && t.record === r.unit!.id) : undefined;
+      const carried = new Set<string>();
+      for (const t of targets) {
+        if (t?.kind === "decision") carried.add(t.id);
+        if (t?.kind === "work") for (const e of edges) if (e.kind === "implements" && e.from === t.id) carried.add(e.to);
+      }
+      const shas = commits.map((c) => c.slice("commit:".length));
+      return { run: n.id, lines, commits, unit: r?.unit ? { id: r.unit.id, kind: r.unit.kind, node: work?.id ?? null } : null, decisions: [...carried], joinedBy: joinsOf([n.run], shas) };
+    };
+    let runs: WhyRun[];
+    if (fileLines !== null) {
+      const tally = new Map<string, { lines: number; commits: Set<string> }>();
+      for (const w of who) {
+        for (const id of w.runs) {
+          const t = tally.get(id) ?? tally.set(id, { lines: 0, commits: new Set() }).get(id)!;
+          t.lines++;
+          t.commits.add(`commit:${w.sha}`);
+        }
+      }
+      runs = [...tally]
+        .map(([id, t]) => ({ n: nodes.get(`run:${id}`) as RunNode, t }))
+        .filter((x) => x.n !== undefined)
+        .sort((a, b) => b.t.lines - a.t.lines || (b.n.startedAt ?? "").localeCompare(a.n.startedAt ?? "") || a.n.run.localeCompare(b.n.run))
+        .map((x) => runEntry(x.n, x.t.lines, [...x.t.commits]));
+    } else {
+      runs = runNodes
+        .sort((a, b) => (b.startedAt ?? "").localeCompare(a.startedAt ?? "") || a.run.localeCompare(b.run))
+        .map((n) => runEntry(n, 0, edges.filter((e) => e.kind === "made-by" && e.to === n.id).map((e) => e.from)));
+    }
+
+    const explained = decisions.some((d) => d.current && d.relevance !== "related");
+    const gaps: WhyGap[] = [];
+    if (!explained) {
+      gaps.push({
+        code: "intent-why-no-decision",
+        message: readsRecords ? `no current decision governs ${region.path}, and none is carried out by what made its lines` : `no record kind was read, so no decision can account for ${region.path}`,
+      });
+    }
+    const committed = who.filter((w) => w.sha !== null);
+    if (fileLines !== null ? committed.length > 0 && committed.every((w) => w.runs.length === 0) : touched.length > 0 && runNodes.length === 0) {
+      gaps.push({ code: "intent-why-no-run", message: `no agent run is joined to the commits that made ${fileLines !== null ? "the current lines of " : ""}${region.path}` });
+    }
+    const uncommitted = who.filter((w) => w.sha === null).map((w) => w.line);
+    if (uncommitted.length > 0) gaps.push({ code: "intent-why-uncommitted", message: `${uncommitted.length} ${uncommitted.length === 1 ? "line is" : "lines are"} not committed yet`, lines: ranges(uncommitted) });
+    const ambiguous = who.filter((w) => w.runs.length > 1).map((w) => w.line);
+    if (ambiguous.length > 0) {
+      gaps.push({ code: "intent-why-run-ambiguous", message: `${ambiguous.length} ${ambiguous.length === 1 ? "line comes" : "lines come"} from a commit several runs made, and no run's recorded hunks say which wrote ${ambiguous.length === 1 ? "it" : "them"}`, lines: ranges(ambiguous) });
+    }
+    return { lines: fileLines, blame: spans, decisions, runs, explained, gaps };
+  }
 }