@intentius/chant 0.124.5 → 0.124.7

package/src/pr-forge.ts

@@ -2,7 +2,8 @@
  * What chant and the products built on it ask of a forge: keep one comment
  * (a merge request note on GitLab) on a pull request up to date, set a commit
  * status, keep one tracking issue in the repository, list who approved a pull
- * request, and find the pull request that merged a commit.
+ * request, find the pull request that merged a commit, and open or edit a
+ * pull request (a merge request on GitLab) for a branch.
  *
  * The pull-request loop (#3183) uses the note, the status and the review
  * calls. `reconcilePr`'s `comment` and `issue` finding modes post through the
@@ -21,6 +22,10 @@
  * `gitlab:<login>`, or `<forge>@<host>:<login>` off the forge's default host.
  * The apply compares that string with the approval's `resolvedBy`.
  *
+ * Opening a pull request goes over REST too (#3798): `gh pr` speaks GitHub's
+ * GraphQL, which Forgejo does not serve, so chant's own pull-request paths
+ * open theirs through {@link PrForge.openPullRequest} on Forgejo and GitLab.
+ *
  * Like `./pr-loop.ts`, this bundles without the TypeScript toolchain (#3421):
  * it imports nothing but `node:fs`, to read a CI job's event payload.
  * `./pr-forge-bundle.test.ts` holds it to that.
@@ -41,7 +46,13 @@ export type ForgeFetch = (
 export interface ForgeStatus {
   /** The status's name, such as `chant/plan` or `terragucci/plan`. */
   context: string;
-  state: "pending" | "success" | "failure";
+  /**
+   * GitLab's own states, plus GitHub's `failure` and `error`. Each forge gets
+   * the nearest state it has ({@link statusStateFor}): `running` is `pending`
+   * on GitHub and Forgejo, `canceled` is `error` there, and `failure` and
+   * `error` are `failed` on GitLab.
+   */
+  state: ForgeStatusState;
   /** Cut to what the forge keeps: 140 characters on GitHub and Forgejo, 255 on GitLab. */
   description: string;
   /** The pipeline run, linked from the status. */
@@ -50,6 +61,30 @@ export interface ForgeStatus {
   pipelineId?: number;
 }
 
+/** A commit status's state, as a caller names it. */
+export type ForgeStatusState = "pending" | "running" | "success" | "failed" | "failure" | "canceled" | "error";
+
+/** Every {@link ForgeStatusState}, for a caller that reads one from its own input. */
+export const FORGE_STATUS_STATES: readonly ForgeStatusState[] = ["pending", "running", "success", "failed", "failure", "canceled", "error"];
+
+/**
+ * What each forge is sent for a {@link ForgeStatusState} (#3834). GitHub
+ * keeps `pending`, `success`, `failure` and `error`; Forgejo the same and
+ * `warning`; GitLab `pending`, `running`, `success`, `failed` and `canceled`.
+ * A state the forge lacks becomes its nearest one.
+ */
+const STATUS_STATE: Record<"github" | "gitlab", Record<ForgeStatusState, string>> = {
+  github: { pending: "pending", running: "pending", success: "success", failed: "failure", failure: "failure", canceled: "error", error: "error" },
+  gitlab: { pending: "pending", running: "running", success: "success", failed: "failed", failure: "failed", canceled: "canceled", error: "failed" },
+};
+
+/** The state `kind` is sent for `state`. Forgejo takes GitHub's. */
+export function statusStateFor(kind: ForgeKind, state: ForgeStatusState): string {
+  const mapped = STATUS_STATE[kind === "gitlab" ? "gitlab" : "github"][state];
+  if (mapped === undefined) throw new Error(`a commit status state is one of ${FORGE_STATUS_STATES.join(", ")}, not ${JSON.stringify(state)}`);
+  return mapped;
+}
+
 /**
  * How a comment or an issue is told to be the caller's own. By default the
  * body starts with the marker, chant's recipe since #2291, and anyone may
@@ -59,12 +94,15 @@ export interface MarkerMatch {
   /** `prefix` (the default): the body starts with the marker. `anywhere`: the body carries it. */
   match?: "prefix" | "anywhere";
   /**
-   * Only a comment or issue written by this login counts: `user.login` on
-   * GitHub and Forgejo, `author.username` on GitLab, compared without case.
-   * A merge request's author can write a note carrying any marker, so a
-   * product that reads its own notes back names its bot here.
+   * Only a comment or issue written by this login, or by any of these
+   * logins, counts: `user.login` on GitHub and Forgejo, `author.username` on
+   * GitLab, compared without case. A merge request's author can write a note
+   * carrying any marker, so a product that reads its own notes back names
+   * its bot here. A list is for a bot whose login the job cannot know in
+   * advance, such as `gitea-actions` or `forgejo-actions` on Forgejo (#3834).
+   * An empty list matches nobody.
    */
-  author?: string;
+  author?: string | readonly string[];
 }
 
 /** What {@link PrForge.upsertComment} did. */
@@ -146,6 +184,34 @@ export interface IssueResult {
   created?: string;
 }
 
+/** A pull request (merge request) for {@link PrForge.openPullRequest} to open. */
+export interface PullRequestSpec {
+  /** The branch with the change, in the same repository. */
+  head: string;
+  /** The branch it merges into. Default: the repository's default branch, read from the forge. */
+  base?: string;
+  title: string;
+  body: string;
+  /**
+   * Open it as a draft: GitHub's `draft`, GitLab's `Draft: ` title prefix,
+   * Forgejo's `WIP: ` title prefix (it has no draft field).
+   */
+  draft?: boolean;
+}
+
+/** A pull request (merge request) as the forge answered it. */
+export interface PullRequest {
+  /** The pull request's number, or the merge request's iid. */
+  number: number;
+  url?: string;
+  title: string;
+  body: string;
+  /** Its head (source) branch. */
+  head: string;
+  /** Its base (target) branch. */
+  base?: string;
+}
+
 export interface PrForge {
   kind: ForgeKind;
   /** Lower-cased, such as `github.com`. */
@@ -208,6 +274,22 @@ export interface PrForge {
   approvers(pr: number): Promise<string[]>;
   /** The merged pull request that produced `sha`, or null. */
   pullRequestFor(sha: string): Promise<number | null>;
+  /**
+   * Open a pull request (a merge request on GitLab) from `head` into `base`,
+   * or into the default branch when `base` is not given. Over REST on every
+   * forge, so it works on Forgejo, where `gh pr create` cannot (#3798).
+   */
+  openPullRequest(spec: PullRequestSpec): Promise<PullRequest>;
+  /**
+   * The OPEN pull request whose head is branch `head` in this repository (a
+   * fork's branch of the same name is not it), or undefined. The oldest when
+   * there are several.
+   */
+  findPullRequest(head: string): Promise<PullRequest | undefined>;
+  /** Change an open pull request's title or body. */
+  editPullRequest(pr: number, change: { title?: string; body?: string }): Promise<PullRequest | undefined>;
+  /** Add labels to a pull request by name. Forgejo needs them to exist; GitHub and GitLab make them. */
+  addLabels(pr: number, labels: readonly string[]): Promise<void>;
 }
 
 /** A GitHub or Forgejo client. */
@@ -301,8 +383,15 @@ interface Threads {
 const carries = (body: string, marker: string, match: MarkerMatch["match"]): boolean =>
   match === "anywhere" ? body.includes(marker) : body.startsWith(marker);
 
+/** Whether `author` is one of `want`, without case. No `want` (or `""`) takes anyone. */
+const authorIn = (want: MarkerMatch["author"], author: string | undefined): boolean => {
+  if (want === undefined || want === "") return true;
+  const logins = (typeof want === "string" ? [want] : want).map((l) => l.toLowerCase());
+  return author !== undefined && logins.includes(author.toLowerCase());
+};
+
 const ownedBy = (marker: string, opts: MarkerMatch) => (t: Thread): boolean =>
-  carries(t.body, marker, opts.match) && (!opts.author || t.author?.toLowerCase() === opts.author.toLowerCase());
+  carries(t.body, marker, opts.match) && authorIn(opts.author, t.author);
 
 function checkMarker(what: string, marker: string, body: string, match: MarkerMatch["match"]): void {
   if (!marker) throw new Error(`the ${what} needs a marker to be found again`);
@@ -420,6 +509,21 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
     return { id, body: str(v.body) ?? "", ...(created ? { created } : {}), ...(str(v.title) !== undefined ? { title: str(v.title) } : {}), ...(author ? { author } : {}), ...(url ? { url } : {}) };
   };
   const threads = (items: unknown[]): Thread[] => items.map(thread).filter((t): t is Thread => t !== undefined);
+  const pull = (v: unknown): PullRequest | undefined => {
+    if (!isObject(v)) return undefined;
+    const number = num(v.number);
+    const head = isObject(v.head) ? str(v.head.ref) : undefined;
+    if (number === undefined) return undefined;
+    const base = isObject(v.base) ? str(v.base.ref) : undefined;
+    const url = str(v.html_url);
+    return { number, title: str(v.title) ?? "", body: str(v.body) ?? "", head: head ?? "", ...(base ? { base } : {}), ...(url ? { url } : {}) };
+  };
+  /** A pull request whose head branch lives in this repository, not a fork. */
+  const fromHere = (v: unknown, head: string): boolean => {
+    if (!isObject(v) || !isObject(v.head) || v.head.ref !== head) return false;
+    const full = isObject(v.head.repo) ? str(v.head.repo.full_name) : undefined;
+    return full === undefined || full.toLowerCase() === opts.repo.toLowerCase();
+  };
   const t: Threads = {
     comments: async (pr) => threads(await api.list(`${repo}/issues/${pr}/comments`, pageParams, pageSize)),
     addComment: async (pr, body) => thread(await api.call("POST", `${repo}/issues/${pr}/comments`, { body })),
@@ -445,7 +549,7 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
     ...threadCalls(t),
     async setStatus(sha, status) {
       await api.call("POST", `${repo}/statuses/${sha}`, {
-        state: status.state,
+        state: statusStateFor(kind, status.state),
         context: status.context,
         description: status.description.slice(0, GITHUB_DESCRIPTION),
         ...(status.url ? { target_url: status.url } : {}),
@@ -483,9 +587,44 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       const pick = (exact ?? merged[0]) as Record<string, unknown> | undefined;
       return pick && typeof pick.number === "number" ? pick.number : null;
     },
+    async openPullRequest(spec) {
+      const base = spec.base ?? (await defaultBranchOf(api, repo, "default_branch"));
+      const title = spec.draft && kind === "forgejo" ? `WIP: ${spec.title}` : spec.title;
+      const made = await api.call("POST", `${repo}/pulls`, {
+        title,
+        body: spec.body,
+        head: spec.head,
+        base,
+        ...(spec.draft && kind === "github" ? { draft: true } : {}),
+      });
+      return pull(made) ?? { number: 0, title, body: spec.body, head: spec.head, base };
+    },
+    async findPullRequest(head) {
+      // GitHub filters by `owner:branch` server-side; Forgejo's list takes no
+      // head filter, so every open page is read and matched here.
+      const owner = opts.repo.split("/")[0];
+      const query = kind === "github" ? `?state=open&head=${encodeURIComponent(`${owner}:${head}`)}` : "?state=open";
+      const open = (await api.list(`${repo}/pulls${query}`, pageParams, pageSize)).filter((p) => fromHere(p, head));
+      return open.map(pull).filter((p): p is PullRequest => p !== undefined).sort((a, b) => a.number - b.number)[0];
+    },
+    async editPullRequest(pr, change) {
+      return pull(await api.call("PATCH", `${repo}/pulls/${pr}`, { ...(change.title !== undefined ? { title: change.title } : {}), ...(change.body !== undefined ? { body: change.body } : {}) }));
+    },
+    async addLabels(pr, labels) {
+      if (labels.length === 0) return;
+      await api.call("POST", `${repo}/issues/${pr}/labels`, { labels: [...labels] });
+    },
   };
 }
 
+/** The repository's default branch, from `GET` on the repository (`/repos/{repo}`, `/projects/{id}`). */
+async function defaultBranchOf(api: Transport, path: string, field: string): Promise<string> {
+  const r = await api.call("GET", path);
+  const branch = isObject(r) ? str(r[field]) : undefined;
+  if (!branch) throw new Error(`${path} names no default branch to open the pull request against; pass base`);
+  return branch;
+}
+
 /** A GitHub client (github.com or GitHub Enterprise Server). */
 export function githubForge(opts: GithubForgeOptions): GithubShapedForge {
   return githubShaped("github", opts);
@@ -515,8 +654,6 @@ export interface GitlabForgeOptions {
   fetch?: ForgeFetch;
 }
 
-const GITLAB_STATE: Record<ForgeStatus["state"], string> = { pending: "pending", success: "success", failure: "failed" };
-
 /**
  * A GitLab client. Writing notes needs an access token with the `api` scope
  * on most instances: the job token reaches only the endpoints the instance's
@@ -545,6 +682,14 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
     return { id, body: str(v.description) ?? "", ...(created ? { created } : {}), ...(str(v.title) !== undefined ? { title: str(v.title) } : {}), ...(author ? { author } : {}), ...(url ? { url } : {}) };
   };
   const notes = `${project}/merge_requests`;
+  const mergeRequest = (v: unknown): PullRequest | undefined => {
+    if (!isObject(v)) return undefined;
+    const number = num(v.iid);
+    if (number === undefined) return undefined;
+    const base = str(v.target_branch);
+    const url = str(v.web_url);
+    return { number, title: str(v.title) ?? "", body: str(v.description) ?? "", head: str(v.source_branch) ?? "", ...(base ? { base } : {}), ...(url ? { url } : {}) };
+  };
   const t: Threads = {
     comments: async (mr) =>
       (await api.list(`${notes}/${mr}/notes`, pageParams, 100))
@@ -577,7 +722,7 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
     async setStatus(sha, status) {
       try {
         await api.call("POST", `${project}/statuses/${sha}`, {
-          state: GITLAB_STATE[status.state],
+          state: statusStateFor("gitlab", status.state),
           name: status.context,
           description: status.description.slice(0, GITLAB_DESCRIPTION),
           ...(status.url ? { target_url: status.url } : {}),
@@ -606,6 +751,28 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
         ?? mrs.find((m) => isObject(m) && m.state === "merged");
       return isObject(merged) && typeof merged.iid === "number" ? merged.iid : null;
     },
+    async openPullRequest(spec) {
+      const base = spec.base ?? (await defaultBranchOf(api, project, "default_branch"));
+      const title = spec.draft ? `Draft: ${spec.title}` : spec.title;
+      const made = await api.call("POST", notes, { source_branch: spec.head, target_branch: base, title, description: spec.body });
+      return mergeRequest(made) ?? { number: 0, title, body: spec.body, head: spec.head, base };
+    },
+    async findPullRequest(head) {
+      const open = await api.list(`${notes}?state=opened&source_branch=${encodeURIComponent(head)}`, pageParams, 100);
+      return open
+        // A fork's merge request into this project has another source project.
+        .filter((m) => isObject(m) && m.source_branch === head && (m.source_project_id === undefined || m.source_project_id === m.project_id))
+        .map(mergeRequest)
+        .filter((m): m is PullRequest => m !== undefined)
+        .sort((a, b) => a.number - b.number)[0];
+    },
+    async editPullRequest(mr, change) {
+      return mergeRequest(await api.call("PUT", `${notes}/${mr}`, { ...(change.title !== undefined ? { title: change.title } : {}), ...(change.body !== undefined ? { description: change.body } : {}) }));
+    },
+    async addLabels(mr, labels) {
+      if (labels.length === 0) return;
+      await api.call("PUT", `${notes}/${mr}`, { add_labels: labels.join(",") });
+    },
   };
 }
 

package/src/workspace/points-cli.ts

@@ -250,7 +250,7 @@ export function responseAsk(response: unknown): ModelAsk {
 const USAGE = [
   "chant workspace points [--open] [--kind <kind file>] [--at <rev>] [--json]",
   "chant workspace points ask <point> --inputs <file|-|json> [--candidates <file|-|json>] [--response <file>] [--subject <id>] [--kind <kind file>] [--dry-run]",
-  "chant workspace points answer <id> --answer <value> --by <name> [--by <name>...] [--note <text>] [--relayed-by <principal>] [--kind <kind file>] [--dry-run]",
+  "chant workspace points answer <id> --answer <value> --by <name> [--by <name>...] [--note <text>] [--relayed-by <principal>] [--kind <kind file>] [--resume] [--dry-run]",
   "chant workspace points retract <id> --by <name> [--by <name>...] [--note <text>] [--kind <kind file>] [--dry-run]",
 ].join("\n");
 
@@ -311,7 +311,12 @@ export async function runWorkspacePoints(ctx: CommandContext): Promise<number> {
     if (!id) return print(usage("answer", "answer needs the question's id"));
     if (args.answer === undefined) return print(usage("answer", "--answer <value> is required"));
     if (!args.bys || args.bys.length === 0) return print(usage("answer", "--by <name> is required, once for each person who answered"));
-    return print(await answerPoint({ cwd, id, answer: args.answer, by: args.bys, note: args.note, relayedBy: args.relayedBy, kind: args.kind, dryRun: args.dryRun }));
+    const answered = await answerPoint({ cwd, id, answer: args.answer, by: args.bys, note: args.note, relayedBy: args.relayedBy, kind: args.kind, dryRun: args.dryRun });
+    const code = print(answered);
+    // --resume (#3835): start the job waiting at the gate the question names, as `chant approve --resume` does.
+    if (code !== 0 || args.dryRun || !(args.resumeRun || args.resume !== undefined) || !("question" in answered)) return code;
+    const { resumeAfterAnswer } = await import("../cli/handlers/gate-resume");
+    return resumeAfterAnswer(answered.question, cwd);
   }
   if (verb === "retract") {
     const id = args.extraPositional2;

package/src/workspace/records-cli.ts

@@ -99,6 +99,13 @@ export interface RecordsQuery {
   workGaps?: boolean;
   /** List only the records that are modified or new against `HEAD` (#3160). Needs git and a working-tree read. */
   uncommitted?: boolean;
+  /**
+   * For an answer kind read in the working tree (#3833): fetch `chant/lifecycle`
+   * first, best effort, as `points answer` does, so an answer held there by
+   * another clone or a CI job is listed. The command sets it; other readers
+   * read the local ledger as it is.
+   */
+  fetchLedger?: boolean;
 }
 
 /**
@@ -146,6 +153,14 @@ export type RecordView = RecordEntry & {
    * steward keeps on the lifecycle ledger (#2786) laid over it.
    */
   answers?: WorkAnswer[];
+  /**
+   * For a record of an answer kind (one with an `answers` block) read in the
+   * working tree (#3833): where the record is held on the lifecycle ledger,
+   * `chant/lifecycle:<path>`, as `points` names it for a question, or null
+   * when it is the working tree's file. A record held on the ledger has no
+   * `worktree` or `lastWrite`, since the checkout doesn't hold it.
+   */
+  ledger?: string | null;
 };
 
 /** The role in the trust policy whose holders' verdicts the quorum does not count (#2671). */
@@ -398,7 +413,19 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
   // A revision has no working tree to hold anything uncommitted; the CLI and the MCP tool refuse the pair first.
   if (query.uncommitted && query.at !== undefined) throw new Error("--uncommitted reads the working tree and takes no --at");
   try {
-    const { loaded, root, top, at, workspaceRoot, tree, result } = await readRecordsFor(query);
+    // An answer kind's records include the answers held on the lifecycle ledger (#2786, #3815), as `points` lists them (#3833).
+    let heldOnLedger: Map<string, string> | undefined;
+    const { loaded, root, top, at, workspaceRoot, tree, result } = await readRecordsFor({
+      ...query,
+      overlay: async (base, { loaded: l, root: r }) => {
+        if (!l.kind.answers) return base;
+        const { readLedgerAnswers, refreshLedger, withLedgerAnswers } = await import("./answers-ledger");
+        if (query.fetchLedger) await refreshLedger(l.file);
+        const ledger = await readLedgerAnswers({ file: l.file, name: l.kind.name, dirRel: relative(r, l.dir).split(sep).join("/") || "." });
+        heldOnLedger = new Map([...ledger.byPath.values()].map((a) => [a.path, a.ledger]));
+        return withLedgerAnswers(base, ledger);
+      },
+    });
     // Provenance, judged by the policy at base and never by the tree read (#2547).
     const base = top ? resolveBase(top, query.base) : { commit: null, from: null };
     const policy = top ? policyAtBase(top, base) : policyAtBase(root, base);
@@ -426,6 +453,7 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
         ...(seals ? authorSeal(loaded.kind, r, recordPolicy, seals.checkRecordSeal) : {}),
       });
     }
+    if (heldOnLedger) for (const r of records) r.ledger = heldOnLedger.get(r.path) ?? null;
     if (loaded.kind.approval && !loaded.kind.work && top) {
       const decided = decidedCommits(top, at ?? "HEAD", records.map((r) => r.path), loaded.kind);
       for (const r of records) r.decidedIn = decided.get(r.path) ?? null;
@@ -461,13 +489,15 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
     if (at === null && top) {
       const { head, ...rest } = readCheckoutHead(top, query.base);
       const dir = relative(root, loaded.dir).split(sep).join("/") || ".";
+      // A record held on the ledger is not the checkout's: it has no worktree state, and is never uncommitted (#3833).
+      const inTree = records.filter((r) => !r.ledger);
       const { states, deleted } = worktreeStates(top, head, dir, records.map((r) => r.path), new RegExp(loaded.kind.location.match));
-      for (const r of records) r.worktree = states.get(r.path) ?? "new";
+      for (const r of inTree) r.worktree = states.get(r.path) ?? "new";
       const lastWrite = lastWriteReader(top);
-      for (const r of records) r.lastWrite = lastWrite(r.path, readTextOrNull(join(top, ...r.path.split("/"))));
+      for (const r of inTree) r.lastWrite = lastWrite(r.path, readTextOrNull(join(top, ...r.path.split("/"))));
       checkout = { branch: rest.branch, head, base: rest.base, baseFrom: rest.baseFrom, deleted };
       if (query.uncommitted) {
-        listed = records.filter((r) => r.worktree !== "committed");
+        listed = inTree.filter((r) => r.worktree !== "committed");
         summary = { ...summary, total: listed.length, valid: listed.filter((r) => r.valid).length, invalid: listed.filter((r) => !r.valid).length };
       }
     } else if (query.uncommitted && !top) {
@@ -664,7 +694,7 @@ export async function runWorkspaceRecords(ctx: CommandContext): Promise<number>
     else console.log(formatSince(since));
     return "error" in since ? 1 : 0;
   }
-  const doc = await queryRecords({ kind: args.kind, current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd() });
+  const doc = await queryRecords({ kind: args.kind, current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd(), fetchLedger: true });
   if (args.json) {
     console.log(JSON.stringify(doc, null, 2));
   } else if ("error" in doc) {
@@ -728,7 +758,7 @@ async function runDeclaredRecords(args: CommandContext["args"]): Promise<number>
     return 1;
   }
   if (args.since !== undefined) return runDeclaredSince(declared, args);
-  const set = await queryDeclaredRecords(declared, { current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd() });
+  const set = await queryDeclaredRecords(declared, { current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd(), fetchLedger: true });
   if (args.json) console.log(JSON.stringify(set, null, 2));
   for (const doc of args.json ? [] : set.kinds) {
     if ("error" in doc) {
@@ -827,7 +857,8 @@ function formatRecords(
     const attested = r.provenance.level === "attested" ? `  attested by ${r.provenance.principal}` : "";
     const sealed = r.attested === true ? `  sealed by ${(r.data?.[RECORD_SEAL_FIELD] as { signer: string }).signer}` : "";
     const uncommitted = r.worktree === "new" || r.worktree === "modified" ? `  (${r.worktree}, uncommitted)` : "";
-    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${remediated}${attested}${sealed}${uncommitted}${flag}`);
+    const ledger = r.ledger ? `  (held on ${r.ledger})` : "";
+    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${remediated}${attested}${sealed}${uncommitted}${ledger}${flag}`);
     if (r.ready !== undefined) {
       const blocked = (r.blockedBy ?? []).map((b) => `${b.id} (${b.state ?? "unknown"})`).join(", ");
       const implemented = (r.implements ?? []).map((d) => `${d.id} (${d.state ?? "unknown"})`).join(", ");

package/src/workspace/records.schema.json

@@ -327,6 +327,10 @@
           "type": "array",
           "items": { "$ref": "#/$defs/workAnswer" }
         },
+        "ledger": {
+          "type": ["string", "null"],
+          "description": "Added in contract 1 by #3833, on every record of an answer kind (one with an answers block) read in the working tree; absent under --at. Where the record is held on the lifecycle ledger, chant/lifecycle:<path on the branch>, as chant workspace points names it for a question, or null when it is the working tree's file. An answer held on the ledger (a question a steward asked, or one asked with --store ledger) reads as if it sat in the kind's directory and wins over a file of the same name; it has no worktree or lastWrite and is never listed by --uncommitted. The command fetches chant/lifecycle first, best effort."
+        },
         "lease": {
           "description": "Added in contract 1 by #2732, on every record of a work kind with an id, read in the working tree (absent under --at). The item's active work lease (chant workspace work claim), or null when nobody holds one live. Read from the local lease refs, refs/chant/lease/[_members/<member>/]work/<id> and the remote's as last fetched, of the ledger owning the work kind file; records never fetches.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workLease" }]