@intentius/chant 0.100.0 → 0.102.0

package/src/workspace/import.ts

@@ -0,0 +1,325 @@
+/**
+ * `chant workspace import`: bring an export back into the workspace it came
+ * from (#2552, #2524 D10, requirements X3 and X5, ws-004, ws-073).
+ *
+ * The source is the export member, or a directory holding a copy of an
+ * export, such as the repository a hosted copy was kept in. Its
+ * `.chant/export.json` names the workspace and the members that went, and the
+ * hash each file had on both sides when it went: the merge base.
+ *
+ * For each file, three hashes decide. A file the copy did not change is left
+ * alone. A file the copy changed is written when the workspace did not
+ * change it since the export. A file both changed differently is a conflict,
+ * and any conflict refuses the whole import, which then writes nothing. The
+ * same holds for removed and added files. Only paths inside the members that
+ * went, and the record directories of a whole export, are written: a copy
+ * that holds anything else is refused, so an import never writes into another
+ * member.
+ *
+ * Host values switch back (X3): the host-bound values the export recorded
+ * are put back in the files the lineage lists, and in the lock. Each lineage
+ * scope merges the same way as a file, with the scope's digest as the base.
+ *
+ * Every write is recorded in `.chant/returns/<id>.json` (./returns.ts). When
+ * the copy is a git repository of its own, each written file also carries the
+ * commit that last changed it there, with the original signature, and the
+ * tree objects that tie that commit to the bytes. Records keep their seals,
+ * since their bytes are copied as they are.
+ *
+ * Last, the export member is written again from the workspace as it now
+ * stands (the default), or removed with its declaration entry (`--remove`).
+ */
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { readDeclaration, type Declaration } from "./declaration";
+import {
+  EXPORT_MANIFEST,
+  ExportError,
+  exportMember,
+  exportWorkspace,
+  gitTopOf,
+  isLockPath,
+  lineageDigest,
+  listFiles,
+  lockDir,
+  rawDeclaration,
+  readManifestAt,
+  scopedPath,
+  switchHostValues,
+  under,
+  type ExportManifest,
+  type ExportResult,
+} from "./export";
+import { fileHash, LOCK_FILE, parseLock, renderLock, type LineageLock } from "./lineage-lock";
+import { buildOrigin, originSigners, RETURNS_DIR, writeReturn, type ReturnRecord } from "./returns";
+import { workingTree } from "./tree";
+
+export interface ImportOptions {
+  /** The workspace root. */
+  root: string;
+  /** The returned copy's directory. Absent: the export member. */
+  from?: string;
+  /** Remove the export member and its declaration entry, rather than writing it again. */
+  remove?: boolean;
+  dryRun?: boolean;
+}
+
+export interface ImportConflict {
+  path: string;
+  reason: string;
+}
+
+export interface ImportResult {
+  /** The export the copy started from. */
+  export: string;
+  /** The copy's directory, as given or the export member's. */
+  from: string;
+  written: string[];
+  removed: string[];
+  /** Locks changed, by path. */
+  locks: string[];
+  /** Paths whose host-bound values were switched back. */
+  hostValues: string[];
+  conflicts: ImportConflict[];
+  /** Paths in the copy that are outside every member that went. */
+  outside: string[];
+  /** The return record written, relative to the workspace root, or null when nothing changed or for a dry run. */
+  returnRecord: string | null;
+  return: ReturnRecord | null;
+  /** What happened to the export member: written again, removed, or left (nothing changed, a dry run, or a conflict). */
+  member: { name: string; action: "regenerated" | "removed" | "left"; note?: string } | null;
+  applied: boolean;
+}
+
+/** Paths the copy may hold besides member and record files. */
+function ignoredInCopy(path: string): boolean {
+  return path === EXPORT_MANIFEST || path === "chant.workspace.json" || path === "chant.workspace.jsonc" || path.startsWith(`${RETURNS_DIR}/`);
+}
+
+function readOr(abs: string): Buffer | undefined {
+  return existsSync(abs) ? readFileSync(abs) : undefined;
+}
+
+/** Plan the import, and apply it unless `dryRun` or a conflict. Throws an {@link ExportError}. */
+export async function importWorkspace(o: ImportOptions): Promise<ImportResult> {
+  const root = resolve(o.root);
+  const decl = readDeclaration(workingTree(root));
+  const fromDir = o.from !== undefined ? resolve(o.from) : join(root, exportMember(decl).dir);
+  const manifest = readManifestAt(fromDir);
+  if (!manifest) throw new ExportError(`${fromDir} holds no ${EXPORT_MANIFEST}: it is not an export`);
+  if (manifest.from.workspace !== decl.name) {
+    throw new ExportError(`the export came from workspace ${manifest.from.workspace}, and this one is ${decl.name}`);
+  }
+  const memberDirs = manifest.members.map((name) => {
+    const m = decl.members.find((x) => x.name === name);
+    if (!m) throw new ExportError(`member ${name} went with the export, and this workspace no longer declares it`);
+    return m.dir;
+  });
+  const allowed = [...memberDirs, ...manifest.dirs];
+  const others = decl.members.filter((m) => !manifest.members.includes(m.name) && m.dir !== ".");
+
+  // The copy's files and locks.
+  const copyFiles = new Map<string, Buffer>();
+  const copyLocks = new Map<string, LineageLock>();
+  const outside: string[] = [];
+  for (const path of listFiles(fromDir)) {
+    if (ignoredInCopy(path)) continue;
+    if (path === LOCK_FILE) {
+      copyLocks.set(path, parseLock(readFileSync(join(fromDir, path), "utf-8")));
+      continue;
+    }
+    if (!allowed.some((d) => under(path, d)) || others.some((m) => under(path, m.dir))) {
+      outside.push(path);
+      continue;
+    }
+    if (isLockPath(path)) copyLocks.set(path, parseLock(readFileSync(join(fromDir, path), "utf-8")));
+    else copyFiles.set(path, readFileSync(join(fromDir, path)));
+  }
+
+  // Each scope's digest as the copy holds it, before host values go back.
+  const copyDigests = new Map<string, string>();
+  for (const [path, lock] of copyLocks) for (const [scope, lineage] of Object.entries(lock.scopes)) copyDigests.set(`${path}#${scope}`, lineageDigest(lineage));
+
+  // Host values back (X3), in the files and in each lock.
+  const exportForm = new Map(copyFiles);
+  const hostValues = new Set<string>();
+  for (const [path, lock] of copyLocks) {
+    for (const [scope, lineage] of Object.entries(lock.scopes)) {
+      const values = manifest.hostValues[`${path}#${scope}`];
+      if (!values) continue;
+      const back = Object.fromEntries(Object.entries(values).map(([n, v]) => [n, { from: v.export, to: v.host }]));
+      for (const p of switchHostValues(lineage, lockDir(path), scope, back, copyFiles)) hostValues.add(p);
+    }
+  }
+
+  const conflicts: ImportConflict[] = [];
+  const writes = new Map<string, Buffer>();
+  const removes: string[] = [];
+  for (const path of [...new Set([...Object.keys(manifest.files), ...copyFiles.keys()])].sort()) {
+    if (!allowed.some((d) => under(path, d))) continue;
+    const base = manifest.files[path];
+    const copy = exportForm.get(path);
+    const changedThere = copy === undefined ? base !== undefined : base === undefined || fileHash(copy) !== base.export;
+    if (!changedThere) continue;
+    const here = readOr(join(root, path));
+    const changedHere = here === undefined ? base !== undefined : base === undefined || fileHash(here) !== base.host;
+    if (copy === undefined) {
+      if (here === undefined) continue;
+      if (changedHere) conflicts.push({ path, reason: "the copy removed it, and it changed here since the export" });
+      else removes.push(path);
+      continue;
+    }
+    const target = copyFiles.get(path)!;
+    if (here !== undefined && here.equals(target)) continue;
+    if (changedHere) {
+      conflicts.push({ path, reason: here === undefined ? "the copy changed it, and it was removed here since the export" : base === undefined ? "the copy added it, and a different file was added here" : "the copy and this workspace both changed it since the export" });
+      continue;
+    }
+    writes.set(path, target);
+  }
+
+  // Locks, scope by scope.
+  const lockWrites = new Map<string, LineageLock>();
+  for (const path of [...new Set([...Object.keys(manifest.locks), ...copyLocks.keys()])].sort()) {
+    const there = copyLocks.get(path);
+    const hereText = readOr(join(root, path));
+    const here: LineageLock | null = hereText ? parseLock(hereText.toString("utf-8")) : null;
+    const next: LineageLock = here ? JSON.parse(JSON.stringify(here)) : { lockVersion: 1, scopes: {} };
+    let changed = false;
+    const recorded = manifest.locks[path] ?? {};
+    for (const scope of [...new Set([...Object.keys(recorded), ...Object.keys(there?.scopes ?? {})])].sort()) {
+      const base = recorded[scope];
+      const theirs = there?.scopes[scope];
+      const ours = here?.scopes[scope];
+      const theirDigest = copyDigests.get(`${path}#${scope}`);
+      const changedThere = theirDigest === undefined ? base !== undefined : base === undefined || theirDigest !== base.export;
+      if (!changedThere) continue;
+      const changedHere = ours === undefined ? base !== undefined : base === undefined || lineageDigest(ours) !== base.host;
+      const where = `${path} scope ${scope}`;
+      if (changedHere) {
+        conflicts.push({ path: where, reason: "the copy and this workspace both changed the lineage since the export" });
+        continue;
+      }
+      if (!theirs) {
+        delete next.scopes[scope];
+        changed = true;
+        continue;
+      }
+      if (base?.partial && ours) {
+        // Only part of the scope went: take the copy's files, and nothing that would move the rest.
+        const { files: _f, manualSteps: _m, repinned: _r, ...a } = ours;
+        const { files: _f2, manualSteps: _m2, repinned: _r2, ...b } = theirs;
+        if (JSON.stringify(a) !== JSON.stringify(b)) {
+          conflicts.push({ path: where, reason: "the copy upgraded a scope only part of which went with the export; upgrade it here instead" });
+          continue;
+        }
+        const dir = lockDir(path);
+        const went = (f: string) => manifest.files[scopedPath(dir, scope, f)] !== undefined || theirs.files[f] !== undefined;
+        const files = Object.fromEntries(Object.entries(ours.files).filter(([f]) => !went(f)));
+        next.scopes[scope] = {
+          ...ours,
+          files: { ...files, ...theirs.files },
+          manualSteps: [...ours.manualSteps.filter((s) => !went(s.path)), ...theirs.manualSteps],
+        };
+      } else {
+        next.scopes[scope] = theirs;
+      }
+      changed = true;
+    }
+    if (changed) lockWrites.set(path, next);
+  }
+
+  const result: ImportResult = {
+    export: manifest.id,
+    from: fromDir,
+    written: [...writes.keys()],
+    removed: removes,
+    locks: [...lockWrites.keys()],
+    hostValues: [...hostValues].filter((p) => writes.has(p)).sort(),
+    conflicts,
+    outside,
+    returnRecord: null,
+    return: null,
+    member: null,
+    applied: false,
+  };
+  if (outside.length > 0 || conflicts.length > 0) return result;
+  const nothing = writes.size === 0 && removes.length === 0 && lockWrites.size === 0;
+
+  // The return record: what came back, and where each file was made.
+  const ownRepo = gitTopOf(fromDir);
+  const own = ownRepo !== undefined && realpathSync(ownRepo) === realpathSync(fromDir);
+  let head: string | null = null;
+  if (own) {
+    try {
+      head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: fromDir, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    } catch {
+      head = null;
+    }
+  }
+  const paths: ReturnRecord["paths"] = {};
+  for (const [path, data] of writes) {
+    const origin = own && head && !hostValues.has(path) ? buildOrigin(fromDir, path, data) : undefined;
+    paths[path] = { sha256: fileHash(data), ...(origin ? { origin } : {}) };
+  }
+  for (const path of lockWrites.keys()) paths[path] = { sha256: fileHash(renderLock(lockWrites.get(path)!)) };
+  const origins = Object.values(paths).flatMap((p) => (p.origin ? [p.origin] : []));
+  const idBody = JSON.stringify({ export: manifest.id, head, paths: Object.fromEntries(Object.entries(paths).map(([p, v]) => [p, v.sha256])), removes });
+  const ret: ReturnRecord = {
+    schema: 1,
+    id: `ret-${createHash("sha256").update(idBody).digest("hex").slice(0, 12)}`,
+    export: { id: manifest.id, workspace: manifest.from.workspace, revision: manifest.from.revision },
+    head,
+    paths,
+    removed: removes,
+    hostValues: result.hostValues,
+    signers: originSigners(origins),
+  };
+  if (!nothing) result.return = ret;
+  if (o.dryRun) return result;
+
+  // Apply.
+  for (const [path, data] of writes) {
+    const abs = join(root, path);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, data);
+  }
+  for (const path of removes) rmSync(join(root, path), { force: true });
+  for (const [path, lock] of lockWrites) {
+    const abs = join(root, path);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, renderLock(lock));
+  }
+  if (!nothing) result.returnRecord = writeReturn(root, ret);
+  result.applied = true;
+
+  // The export member: written again from the workspace as it stands, or removed.
+  result.member = await settleExportMember(root, decl, manifest, o.remove === true, fromDir);
+  return result;
+}
+
+async function settleExportMember(root: string, decl: Declaration, manifest: ExportManifest, remove: boolean, fromDir: string): Promise<ImportResult["member"]> {
+  const m = decl.members.find((x) => x.name === manifest.member);
+  if (!m) return null;
+  if (!remove) {
+    const again: ExportResult = await exportWorkspace({
+      root,
+      to: m.name,
+      ...(manifest.whole ? {} : { members: manifest.members }),
+      params: Object.fromEntries(Object.values(manifest.hostValues).flatMap((v) => Object.entries(v).map(([n, x]) => [n, x.export]))),
+    });
+    return { name: m.name, action: "regenerated", note: `${again.manifest.id}, ${again.files} file(s)` };
+  }
+  rmSync(join(root, m.dir), { recursive: true, force: true });
+  const { file, obj } = rawDeclaration(root);
+  if (file.endsWith(".jsonc")) {
+    return { name: m.name, action: "removed", note: `removed ${m.dir}; ${file} keeps comments, so drop the entry for ${m.name} by hand` };
+  }
+  obj.members = (obj.members as { name: string }[]).filter((e) => e.name !== m.name);
+  writeFileSync(join(root, file), JSON.stringify(obj, null, 2) + "\n");
+  const inside = resolve(fromDir) === resolve(root, m.dir);
+  return { name: m.name, action: "removed", note: `removed ${m.dir} and its entry in ${file}${inside ? "" : `; the copy at ${relative(root, fromDir) || "."} is left as it is`}` };
+}

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>...] [--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,9 +14,9 @@ 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 USAGE = "chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--json]";
 const RECORD_USAGE = "chant workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--json]";
 
 type Result = Exclude<IntentDocument, { 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,40 @@ 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));
+  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";
+    out.push(`  run       ${r.run}: ${what}`);
+  }
+  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.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 +153,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 +171,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 +187,16 @@ 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})` : ""}`).join(", ");
+    out.push(`${c.bucket.padEnd(12)} ${short(c.sha)} ${c.date.slice(0, 10)} ${c.subject}; ${why}${runs ? `; ${runs}` : ""}; ${c.files.join(", ") || c.entries.join(", ")}`);
   }
   for (const x of doc.reasons) out.push(`reason    ${x.code}: ${x.message}`);
   const n = doc.counts;
@@ -172,7 +226,7 @@ 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).