@intentius/chant 0.100.0 → 0.102.0

package/src/workspace/records-checkout.ts

@@ -0,0 +1,106 @@
+/**
+ * The checkout a working-tree read is made in, and which records in it are
+ * uncommitted (#3160).
+ *
+ * Work in progress lives as uncommitted files in a work branch's working tree
+ * (#3158, #3145). A reader such as hud or studio shows "kept, not yet
+ * applied" from `records --json` alone: each record says whether it is
+ * committed, modified or new against `HEAD`, and the document names the
+ * branch, the commit `HEAD` names and the base that branch forked from. The
+ * reader never diffs git itself.
+ *
+ * Every git call here reads. None takes the index lock or refreshes the
+ * index (`--no-optional-locks`), so a read leaves the checkout as it was,
+ * `.git` included, which the reader conformance suite checks.
+ */
+
+import { execFileSync } from "node:child_process";
+import { resolveBase, type BaseSource } from "./trust/provenance";
+
+/** Where a record's file stands against `HEAD`. */
+export type WorktreeState = "committed" | "modified" | "new";
+
+/** The branch, head and base of a checkout (#3160). `records` and `status` both print it. */
+export interface CheckoutHead {
+  /** The checked-out branch's short name, such as `chant/work/w-12`, or null when `HEAD` is detached. */
+  branch: string | null;
+  /** The commit `HEAD` names, or null before the first commit. Each record's `worktree` is judged against it. */
+  head: string | null;
+  /** The merge base of `head` and the target branch tip: the commit the branch forked from. Null without a head, a target, or common history. */
+  base: string | null;
+  /** Where the target branch was found: `flag` for `--base`, else `origin/HEAD`, `main` or `master`. Null when there is none. */
+  baseFrom: BaseSource | null;
+}
+
+/** {@link CheckoutHead} for one record kind, with the record files `HEAD` has and the working tree does not. */
+export interface CheckoutView extends CheckoutHead {
+  /** Record files of the kind at `head` that the working tree no longer has, from the repository root, sorted. */
+  deleted: string[];
+}
+
+function git(top: string, args: string[]): string {
+  return execFileSync("git", ["--no-optional-locks", "--literal-pathspecs", ...args], {
+    cwd: top,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+    maxBuffer: 256 * 1024 * 1024,
+  });
+}
+
+function tryGit(top: string, args: string[]): string | undefined {
+  try {
+    return git(top, args);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The branch, head and base of the checkout at `top`. `explicitBase` is
+ * `--base`, as the trust policy takes it; otherwise the target branch is the
+ * one the policy is read at (`origin/HEAD`, then `main`, then `master`).
+ */
+export function readCheckoutHead(top: string, explicitBase?: string): CheckoutHead {
+  const branch = tryGit(top, ["symbolic-ref", "--quiet", "--short", "HEAD"])?.trim() || null;
+  const head = tryGit(top, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"])?.trim() || null;
+  const target = resolveBase(top, explicitBase);
+  const base = head && target.commit ? tryGit(top, ["merge-base", head, target.commit])?.trim() || null : null;
+  return { branch, head, base, baseFrom: target.from };
+}
+
+/** NUL-separated git output as a list. */
+function zList(out: string | undefined): string[] {
+  return (out ?? "").split("\0").filter(Boolean);
+}
+
+/**
+ * Each of `paths` (record files directly in `dir`, from the repository root)
+ * as committed, modified or new against `head`, and the files directly in
+ * `dir` at `head` whose names `match` and that `paths` leaves out: the
+ * records deleted in the working tree. With no head every path is new.
+ *
+ * Staged and unstaged changes count alike: anything `HEAD` does not hold is
+ * uncommitted. A rename is a new record and a deleted one.
+ */
+export function worktreeStates(
+  top: string,
+  head: string | null,
+  dir: string,
+  paths: readonly string[],
+  match: RegExp,
+): { states: Map<string, WorktreeState>; deleted: string[] } {
+  const states = new Map<string, WorktreeState>();
+  if (head === null) {
+    for (const p of paths) states.set(p, "new");
+    return { states, deleted: [] };
+  }
+  const prefix = dir === "." ? "" : `${dir}/`;
+  const direct = (p: string) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/");
+  const spec = dir === "." ? "." : dir;
+  const atHead = new Set(zList(tryGit(top, ["ls-tree", "-r", "-z", "--name-only", head, "--", spec])).filter(direct));
+  const changed = new Set(zList(tryGit(top, ["diff", "--name-only", "-z", "--no-renames", head, "--", spec])));
+  for (const p of paths) states.set(p, !atHead.has(p) ? "new" : changed.has(p) ? "modified" : "committed");
+  const present = new Set(paths);
+  const deleted = [...atHead].filter((p) => !present.has(p) && match.test(p.slice(prefix.length))).sort();
+  return { states, deleted };
+}

package/src/workspace/records-cli.ts

@@ -15,6 +15,11 @@
  *
  * With `--since <rev>` it prints what changed between two revisions instead,
  * through `records-since.ts` (#2673).
+ *
+ * A working-tree read in git says, for each record, whether it is committed,
+ * modified or new against `HEAD`, and names the branch, head and base of the
+ * checkout; `--uncommitted` lists only the records `HEAD` doesn't hold
+ * (#3160, `records-checkout.ts`).
  */
 
 import { execFileSync } from "node:child_process";
@@ -48,11 +53,12 @@ import {
   type SealInput,
   type VerdictAttestation,
 } from "./records";
+import { readCheckoutHead, worktreeStates, type CheckoutView, type WorktreeState } from "./records-checkout";
 import { gitTree, workingTree, type WorkspaceTree } from "./tree";
-import type { DecisionWork } from "./work";
-import { activeAttestors, type ProvenanceLevel } from "./trust/attestor";
+import type { DecisionWork, WorkAnswer } from "./work";
+import { activeAttestors, type CommitAttestor, type ProvenanceLevel } from "./trust/attestor";
 import { policyAtBase, recordProvenance, resolveBase, type BaseSource, type RecordProvenance } from "./trust/provenance";
-import type { TrustPolicy } from "./trust/policy";
+import { returnedPolicy, type TrustPolicy } from "./trust/policy";
 import type { SealedRecord } from "./trust/seal";
 
 /** The version of the `records` output this chant writes. */
@@ -62,7 +68,7 @@ export const RECORDS_CONTRACT_VERSION = 1;
 export const RECORDS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json";
 
 const USAGE =
-  "chant workspace records [--kind <kind file>] [--current] [--at <rev>] [--base <rev>] [--require attested] [--json] | chant workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json] | chant workspace records pin <path> | chant workspace records new|amend|review|close (#2670, #2693)";
+  "chant workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--json] | chant workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json] | chant workspace records pin <path> | chant workspace records new|amend|review|close (#2670, #2693)";
 
 /** Exit code when the read worked and a record falls below `--require`. */
 export const EXIT_BELOW_REQUIRED = 2;
@@ -81,6 +87,8 @@ export interface RecordsQuery {
    * false; the intent graph passes false, since it raises the warning itself.
    */
   workGaps?: boolean;
+  /** List only the records that are modified or new against `HEAD` (#3160). Needs git and a working-tree read. */
+  uncommitted?: boolean;
 }
 
 /**
@@ -108,6 +116,20 @@ export type RecordView = RecordEntry & {
    * (`record-decided.ts`). The intent graph's windows open at this commit.
    */
   decidedIn?: DecidedIn | null;
+  /**
+   * For a read in the working tree of a git repository (#3160): whether the
+   * record's file is as `HEAD` holds it (`committed`), changed from it
+   * (`modified`), or not in it (`new`), staged or not. Absent under `--at`.
+   */
+  worktree?: WorktreeState;
+  /**
+   * For a work kind whose work block names an answer kind (#3147): the
+   * decision-point answers about the item, the answer records whose
+   * `constrains` names its id, joined by id and never copied onto the item.
+   * Read at the same revision; in the working tree, with the questions a
+   * steward keeps on the lifecycle ledger (#2786) laid over it.
+   */
+  answers?: WorkAnswer[];
 };
 
 /** The role in the trust policy whose holders' verdicts the quorum does not count (#2671). */
@@ -129,11 +151,15 @@ export type RecordsDocument =
   | {
       $schema: string;
       contract: number;
-      kind: { name: string; schema: string; file: string; format: RecordFormat };
+      kind: { name: string; schema: string; file: string; format: RecordFormat; spec: boolean };
       at: string | null;
       /** The directory pinned paths resolve in, from the repository root: the workspace holding the kind file, or the repository root (#2549). */
       workspaceRoot: string;
       current: boolean;
+      /** Whether only the records `HEAD` doesn't hold were listed (`--uncommitted`, #3160). */
+      uncommitted: boolean;
+      /** For a read in the working tree of a git repository (#3160): the branch, head and base it is on, and the records deleted from it. Absent under `--at`. */
+      checkout?: CheckoutView;
       trust: TrustView;
       records: RecordView[];
       summary: { total: number; valid: number; invalid: number; superseded: number };
@@ -161,6 +187,47 @@ export interface RecordsSetDocument {
   $schema: string;
   contract: number;
   kinds: (RecordsDocument & { declared: DeclaredKindView })[];
+  /** With `--current`: the workspace's spec (#2524 D20, #2546), from the kinds marked `spec: true`. */
+  spec?: SpecView;
+}
+
+/**
+ * The spec (#2524 D20): the current records of every declared kind marked
+ * `spec: true`, each with the workspace files it pins. `records --current
+ * --json` prints it beside the kinds, so an agent resumes from the
+ * declaration and this one read.
+ */
+export interface SpecView {
+  /** The spec kinds, as the declaration names them, in its order. */
+  kinds: DeclaredKindView[];
+  records: SpecRecord[];
+}
+
+/** One current record of a spec kind. */
+export interface SpecRecord {
+  /** The kind's name, such as decision. */
+  kind: string;
+  id: string | null;
+  path: string;
+  state: string | null;
+  valid: boolean;
+  /** The digest a verdict names (#2672). */
+  digest: string;
+  /** Each workspace file the record pins: its path from the workspace root, the sha256 pinned, and how it compares with the tree read (#2549). */
+  assets: RecordEntry["assets"];
+}
+
+/** The spec of a set of declared kinds already read with `--current`. */
+export function specOf(kinds: RecordsSetDocument["kinds"]): SpecView {
+  const spec: SpecView = { kinds: [], records: [] };
+  for (const doc of kinds) {
+    if ("error" in doc || !doc.kind.spec) continue;
+    spec.kinds.push(doc.declared);
+    for (const r of doc.records) {
+      spec.records.push({ kind: doc.kind.name, id: r.id, path: r.path, state: r.state, valid: r.valid, digest: r.digest, assets: r.assets });
+    }
+  }
+  return spec;
 }
 
 /**
@@ -186,7 +253,8 @@ export async function queryDeclaredRecords(kinds: { declared: RecordKindDeclarat
     const doc = await queryRecords({ ...query, kind: k.file });
     out.push({ ...doc, declared: { member: k.declared.member, path: k.declared.path, name: k.declared.name } });
   }
-  return { $schema: RECORDS_OUTPUT_SCHEMA_ID, contract: RECORDS_CONTRACT_VERSION, kinds: out };
+  // The spec is every current spec record; an --uncommitted read lists only some, so it has none.
+  return { $schema: RECORDS_OUTPUT_SCHEMA_ID, contract: RECORDS_CONTRACT_VERSION, kinds: out, ...(query.current && !query.uncommitted ? { spec: specOf(out) } : {}) };
 }
 
 /** A records read, before provenance. */
@@ -315,26 +383,37 @@ export async function readRecordsFor(
 
 /** Run the query and build the document `--json` prints. Never throws a {@link RecordReadError}. */
 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);
     // 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);
+    const attestors = policy.active ? await activeAttestors() : [];
     const provenance = recordProvenance({
       repo: top,
       policy,
       at,
       paths: result.records.map((r) => r.path),
-      attestors: policy.active ? await activeAttestors() : [],
+      attestors,
+      ...(policy.active ? { revisit: await returnedRevisit(tree, workspaceRoot, policy, attestors) } : {}),
     });
     const seals = loaded.kind.reviews ? await import("./trust/seal") : undefined;
     const quorumOptions = await quorumOptionsFor(loaded, tree, policy);
-    const records: RecordView[] = result.records.map((r) => ({
-      ...r,
-      provenance: provenance.get(r.path)!,
-      ...(quorumOptions ? { quorum: computeQuorum(loaded.kind, r, quorumOptions) } : {}),
-      ...(seals ? authorSeal(loaded.kind, r, policy, seals.checkRecordSeal) : {}),
-    }));
+    const records: RecordView[] = [];
+    for (const r of result.records) {
+      const p = provenance.get(r.path)!;
+      // Returned work (#2552): its seals verify against the signers admitted for its return too.
+      const recordPolicy = p.returned ? returnedPolicy(policy, p.returned.id) : policy;
+      const options = p.returned ? await quorumOptionsFor(loaded, tree, recordPolicy) : quorumOptions;
+      records.push({
+        ...r,
+        provenance: p,
+        ...(options ? { quorum: computeQuorum(loaded.kind, r, options) } : {}),
+        ...(seals ? authorSeal(loaded.kind, r, recordPolicy, seals.checkRecordSeal) : {}),
+      });
+    }
     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;
@@ -345,6 +424,41 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       const leases = await activeWorkLeases(loaded.file);
       for (const r of records) if (r.id !== null) r.lease = leases.get(r.id) ?? null;
     }
+    if (loaded.kind.work?.answers) {
+      // The answers about each item, joined by id (#3147). An answer kind that can't be read leaves answers out rather than failing the work read.
+      const [{ workAnswers }, { readLedgerAnswers, withLedgerAnswers }] = await Promise.all([import("./work"), import("./answers-ledger")]);
+      const answersRead = await readRecordsFor({
+        kind: resolve(dirname(loaded.file), loaded.kind.work.answers),
+        cwd: query.cwd,
+        ...(query.at !== undefined ? { at: query.at } : {}),
+        overlay: async (base, { loaded: l, root: r }) =>
+          withLedgerAnswers(base, await readLedgerAnswers({ file: l.file, name: l.kind.name, dirRel: relative(r, l.dir).split(sep).join("/") || "." })),
+      }).catch((err: unknown) => {
+        if (err instanceof RecordReadError) return undefined;
+        throw err;
+      });
+      if (answersRead) {
+        const byItem = workAnswers(answersRead.result.records, records.flatMap((r) => (r.id !== null ? [r.id] : [])));
+        for (const r of records) if (r.id !== null) r.answers = byItem.get(r.id) ?? [];
+      }
+    }
+    // Which records the checkout holds uncommitted, judged after every record is read, so links still resolve across the whole set (#3160).
+    let checkout: CheckoutView | undefined;
+    let listed = records;
+    let summary = result.summary;
+    if (at === null && top) {
+      const { head, ...rest } = readCheckoutHead(top, query.base);
+      const dir = relative(root, loaded.dir).split(sep).join("/") || ".";
+      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";
+      checkout = { branch: rest.branch, head, base: rest.base, baseFrom: rest.baseFrom, deleted };
+      if (query.uncommitted) {
+        listed = records.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) {
+      throw new RecordReadError("not-a-git-repository", "--uncommitted compares the working tree with HEAD, and this directory is not in a git repository");
+    }
     return {
       $schema: RECORDS_OUTPUT_SCHEMA_ID,
       contract: RECORDS_CONTRACT_VERSION,
@@ -353,13 +467,16 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
         schema: loaded.kind.schema.id,
         file: relative(root, loaded.file).split("\\").join("/"),
         format: loaded.kind.format,
+        spec: loaded.kind.spec === true,
       },
       at,
       workspaceRoot,
       current: !!query.current,
+      uncommitted: !!query.uncommitted,
+      ...(checkout ? { checkout } : {}),
       trust: { base: base.commit, baseFrom: base.from, active: policy.active, signersPath: policy.signersPath, problems: policy.problems },
-      records,
-      summary: result.summary,
+      records: listed,
+      summary,
       ...(result.decisions ? { decisions: result.decisions } : {}),
     };
   } catch (err) {
@@ -368,6 +485,36 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
   }
 }
 
+/**
+ * The second look recordProvenance takes at each record (#2552): a record
+ * whose bytes came back in a return is judged by the commit it was made in,
+ * which the return carries, rather than by the import here. `tree` is the
+ * workspace root's tree, as read; record paths are from the repository root.
+ */
+async function returnedRevisit(
+  tree: WorkspaceTree,
+  workspaceRoot: string,
+  policy: TrustPolicy,
+  attestors: readonly CommitAttestor[],
+): Promise<((path: string, host: RecordProvenance) => RecordProvenance | undefined) | undefined> {
+  const { readReturns, returnedProvenance } = await import("./returns");
+  const { returns } = readReturns(tree);
+  if (returns.length === 0) return undefined;
+  const prefix = workspaceRoot === "." ? "" : `${workspaceRoot}/`;
+  return (path, host) => {
+    if (!path.startsWith(prefix)) return undefined;
+    const rel = path.slice(prefix.length);
+    const holding = returns.filter((r) => r.paths[rel] !== undefined);
+    if (holding.length === 0 || tree.stat(rel) !== "file") return undefined;
+    const content = Buffer.from(tree.bytes ? tree.bytes(rel) : tree.read(rel));
+    for (const r of holding) {
+      const p = returnedProvenance(policy, attestors, r, rel, content, host);
+      if (p) return p;
+    }
+    return undefined;
+  };
+}
+
 /**
  * A record's author seal checked against the policy at base (#2688), for a
  * kind with a reviews list: its author is the kind's `reviews.decider` field.
@@ -480,6 +627,11 @@ export async function runWorkspaceRecords(ctx: CommandContext): Promise<number>
     console.error(formatError({ message: `chant workspace records takes no argument but pin, new, amend, review or close (got ${args.extraPositional})`, hint: USAGE }));
     return 1;
   }
+  const pairing = uncommittedPairing(args);
+  if (pairing) {
+    console.error(formatError({ message: pairing, hint: USAGE }));
+    return 1;
+  }
   if (!args.kind) return runDeclaredRecords(args);
   if (args.require !== undefined && args.require !== "attested") {
     console.error(formatError({ message: `--require takes one level, attested, not ${JSON.stringify(args.require)}`, hint: USAGE }));
@@ -498,13 +650,13 @@ 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, 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() });
   if (args.json) {
     console.log(JSON.stringify(doc, null, 2));
   } else if ("error" in doc) {
     console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
   } else {
-    console.log(formatRecords(doc.records, doc.summary, doc.at));
+    console.log(formatRecords(doc.records, doc.summary, doc.at, doc.checkout));
   }
   if ("error" in doc) return 1;
   if (args.require) {
@@ -562,7 +714,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, 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() });
   if (args.json) console.log(JSON.stringify(set, null, 2));
   for (const doc of args.json ? [] : set.kinds) {
     if ("error" in doc) {
@@ -570,7 +722,7 @@ async function runDeclaredRecords(args: CommandContext["args"]): Promise<number>
       continue;
     }
     console.log(`${doc.declared.name ?? doc.kind.name} (${doc.declared.path})`);
-    console.log(formatRecords(doc.records, doc.summary, doc.at));
+    console.log(formatRecords(doc.records, doc.summary, doc.at, doc.checkout));
   }
   if (set.kinds.some((d) => "error" in d)) return 1;
   if (args.require) {
@@ -636,7 +788,20 @@ export function belowRequired(records: RecordView[], required: ProvenanceLevel):
   return records.filter((r) => r.provenance.level !== required);
 }
 
-function formatRecords(records: RecordView[], summary: { total: number; valid: number; invalid: number; superseded: number }, at: string | null): string {
+/** Why `--uncommitted` can't be given with the other flags given, or undefined when it can (#3160). */
+function uncommittedPairing(args: CommandContext["args"]): string | undefined {
+  if (!args.uncommitted) return undefined;
+  if (args.at !== undefined) return "--uncommitted reads the working tree against HEAD, and takes no --at";
+  if (args.since !== undefined) return "--uncommitted takes no --since: --since compares two revisions";
+  return undefined;
+}
+
+function formatRecords(
+  records: RecordView[],
+  summary: { total: number; valid: number; invalid: number; superseded: number },
+  at: string | null,
+  checkout?: CheckoutView,
+): string {
   const lines: string[] = [];
   const idWidth = Math.max(2, ...records.map((r) => (r.id ?? "-").length));
   const stateWidth = Math.max(5, ...records.map((r) => (r.state ?? "-").length));
@@ -647,7 +812,8 @@ function formatRecords(records: RecordView[], summary: { total: number; valid: n
     const remediated = r.remediatedBy.length > 0 ? `  remediated by ${r.remediatedBy.join(", ")}` : "";
     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}` : "";
-    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${remediated}${attested}${sealed}${flag}`);
+    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}`);
     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(", ");
@@ -664,9 +830,16 @@ function formatRecords(records: RecordView[], summary: { total: number; valid: n
       lines.push(`${" ".repeat(idWidth + 2)}quorum ${q.agreed} of ${q.need} agreed, ${verdict}; ${q.notCounted.length} not counted${concerns}`);
     }
   }
+  for (const path of checkout?.deleted ?? []) lines.push(`${"-".padEnd(idWidth)}  ${"-".padEnd(stateWidth)}  ${path}  (deleted, uncommitted)`);
   lines.push(
     `${summary.total} records${at ? ` at ${at.slice(0, 8)}` : ""}: ${summary.valid} valid, ${summary.invalid} invalid, ${summary.superseded} superseded`,
   );
+  if (checkout) {
+    const branch = checkout.branch ?? "a detached HEAD";
+    const head = checkout.head ? ` at ${checkout.head.slice(0, 8)}` : " with no commits";
+    const base = checkout.base ? `, forked from ${checkout.base.slice(0, 8)} of ${checkout.baseFrom}` : "";
+    lines.push(`working tree on ${branch}${head}${base}`);
+  }
   return lines.join("\n");
 }
 
@@ -676,7 +849,7 @@ export async function runWorkspaceUnknown(ctx: CommandContext): Promise<number>
   console.error(
     formatError({
       message: sub ? `Unknown workspace subcommand: ${sub}` : "chant workspace needs a subcommand",
-      hint: `Workspace subcommands: audit, build, check, graph, init, lineage, lint, ls, records, status, upgrade, verify, work. Run "chant --help" for their options.`,
+      hint: `Workspace subcommands: adopt-lineage, audit, build, check, evidence, graph, hash-index, init, lineage, lint, ls, pin, records, signers, status, upgrade, verify, versions, work. Run "chant --help" for their options.`,
     }),
   );
   return 1;

package/src/workspace/records-close.schema.json

@@ -84,8 +84,8 @@
             },
             "digest": {
               "type": "string",
-              "pattern": "^[0-9a-f]{64}$",
-              "description": "The seal written: the lowercase hex SHA-256 of the file with LF line endings and without its seal line, which records checks on every read (session-seal-mismatch)."
+              "pattern": "^sha256:[0-9a-f]{64}$",
+              "description": "The seal written: sha256: and the lowercase hex SHA-256 of the JCS form of the whole session without its seal field (its front matter as core and the text below it as body, line endings LF), which records checks on every read (session-seal-mismatch). Before #2546 it was the bare hex SHA-256 of the file's text without the seal line."
             }
           }
         },
@@ -171,6 +171,10 @@
                 "write-usage-invalid",
                 "record-not-found",
                 "record-closed",
+                "write-scope-member",
+                "write-scope-kind",
+                "write-scope-class-unknown",
+                "agent-unknown",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",
@@ -178,6 +182,7 @@
                 "record-supersedes-conflict",
                 "record-remediates-unknown",
                 "record-remediates-not-closed",
+                "record-seal-mismatch",
                 "session-seal-mismatch",
                 "session-verdict-unknown-record"
               ]

package/src/workspace/records-close.ts

@@ -3,7 +3,8 @@
  * session in one write. It sets the session's state to its kind's closed
  * state, the time it closed and the commit it closed at (the fields the
  * kind's `session` block names in `closedOn` and `closedRev`), and then the
- * seal by chant's rule ({@link sessionSeal}), so a UI never computes a seal.
+ * seal by chant's whole-file rule ({@link sessionSeal}, #2546), so a UI never
+ * computes a seal.
  *
  * Like `new`, `amend` and `review`, it reads the records again with the file
  * in place and writes only when the session comes back valid: a verdict
@@ -26,6 +27,7 @@ import {
   readAll,
   RECORDS_WRITE_CONTRACT_VERSION,
   RecordWriteError,
+  refuseOutOfScope,
   replaceFields,
   stableJson,
   validateWrite,
@@ -33,6 +35,7 @@ import {
   type WriteResult,
 } from "./records-write";
 import { headCommit } from "./session-kinds";
+import { WRITE_SCOPE_CODES } from "./write-scope";
 
 export const RECORDS_CLOSE_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records-close/v1/records-close.schema.json";
 
@@ -42,6 +45,7 @@ export const CLOSE_ERROR_CODES = [
   "write-usage-invalid",
   "record-not-found",
   "record-closed",
+  ...WRITE_SCOPE_CODES,
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 export type CloseErrorCode = (typeof CLOSE_ERROR_CODES)[number];
@@ -65,6 +69,8 @@ export interface CloseRecordOptions {
   cwd: string;
   /** The close time. Defaults to now. */
   now?: Date;
+  /** The agent session the write is made in (#2548). */
+  agent?: string;
 }
 
 /** An ISO 8601 time in UTC to the second, as the reference session schema's dateTime takes it. */
@@ -76,6 +82,7 @@ function isoSeconds(d: Date): string {
 export async function closeRecord(opts: CloseRecordOptions): Promise<CloseDocument> {
   try {
     const o = await open(opts.kind, opts.cwd);
+    refuseOutOfScope(o, "close", opts.cwd, opts);
     const { kind } = o.loaded;
     const decl = kind.session;
     if (!decl || kind.stateField === undefined) {
@@ -97,12 +104,13 @@ export async function closeRecord(opts: CloseRecordOptions): Promise<CloseDocume
       ...(decl.closedOn ? { [decl.closedOn]: isoSeconds(opts.now ?? new Date()) } : {}),
       ...(decl.closedRev ? { [decl.closedRev]: closedRev } : {}),
     };
-    // The seal line is written last, into text that already holds everything else, so the seal is the digest of the file without it.
+    // The seal is written last, into text that already holds everything else: the whole-file seal of the session without its seal field (#2546).
     const merged = { ...old, ...set };
     delete merged[decl.seal];
     const unsealed = replaceFields(o.source.read(target.path), set, merged);
     if (unsealed === undefined) throw new RecordWriteError("record-unparseable", `${target.path}: its fields can't be rewritten in place without changing the rest of the file`);
     const digest = sessionSeal(unsealed, decl.seal, kind.format);
+    if (digest === null) throw new RecordWriteError("record-unparseable", `${target.path} can't be read, so it can't be sealed`);
     const text = replaceFields(unsealed, { [decl.seal]: digest }, { ...merged, [decl.seal]: digest });
     if (text === undefined || sessionSeal(text, decl.seal, kind.format) !== digest) {
       throw new RecordWriteError("record-unparseable", `${target.path}: the ${decl.seal} line can't be added without changing the text it seals`);

package/src/workspace/records-formats.test.ts

@@ -154,7 +154,8 @@ const SESSION_SCHEMA = {
     comments: { type: "array" },
     follow_ups: { type: "array", items: ref("contractId") },
     closed_at: ref("datetime"),
-    seal: ref("sha256"),
+    // The whole-file seal (#2546): sha256: and the hex SHA-256 of the session's JCS form without it.
+    seal: { type: "string", pattern: "^sha256:[0-9a-f]{64}$" },
   },
 };
 
@@ -294,7 +295,7 @@ const SESSION = {
   comments: [],
   follow_ups: ["C-002"],
   closed_at: "2026-09-24T11:00:00.000Z",
-  seal: "e".repeat(64),
+  seal: `sha256:${"e".repeat(64)}`,
 };
 
 // ── 1. The json format ───────────────────────────────────────────────────────
@@ -372,11 +373,16 @@ describe("format json", () => {
 });
 
 describe("a JSON session kind (#2673)", () => {
-  test("its seal is the digest without the seal member, by the JSON rule", async () => {
+  test("its seal is the whole-file JCS seal without the seal member (#2546)", async () => {
     write("design/session.kind.mjs", kindFile({ ...KINDS.session, session: { verdicts: "approvals", seal: "seal", subjects: { kind: "contract.kind.mjs" } } }));
     write("design/contracts/C-001-first.md", '---\nid: "C-001"\nstatus: "approved"\n---\n');
+    // JCS of the object without its seal: keys sorted, no whitespace. The member order and indentation of the file play no part.
+    const sorted = (v: unknown): unknown =>
+      v === null || typeof v !== "object" ? v : Array.isArray(v) ? v.map(sorted) : Object.fromEntries(Object.keys(v).sort().map((k) => [k, sorted((v as Record<string, unknown>)[k])]));
+    const jcsSeal = (v: object): string => `sha256:${sha256(JSON.stringify(sorted(v)))}`;
     const { seal: _drop, ...unsealed } = SESSION;
-    const seal = sha256(json(unsealed));
+    const seal = jcsSeal(unsealed);
+    // Sealed over SESSION, then changed: a verdict added, or the id.
     write("design/sessions/S-0001.json", json({ ...SESSION, approvals: [{ record: "C-001" }], seal }));
     write("design/sessions/S-0002.json", json({ ...SESSION, id: "S-0002", seal }));
     const doc = await query("session");
@@ -385,7 +391,7 @@ describe("a JSON session kind (#2673)", () => {
       ["S-0002", ["session-seal-mismatch"]],
     ]);
     const good = { ...unsealed, id: "S-0003" };
-    write("design/sessions/S-0003.json", json({ ...good, seal: sha256(json(good)) }));
+    write("design/sessions/S-0003.json", `${JSON.stringify({ seal: jcsSeal(good), ...Object.fromEntries(Object.entries(good).reverse()) })}\n`);
     const [, , third] = (await query("session")).records;
     expect([third.id, codes(third)]).toEqual(["S-0003", []]);
   });
@@ -547,6 +553,8 @@ describe("kinds without a lifecycle", () => {
     ["neither idField nor idFrom", { ...KINDS.closure, idField: undefined }, /idField: a kind names its id with exactly one of idField and idFrom/],
     ["an unknown format", { ...KINDS.closure, format: "yaml" }, /format/],
     ["a session block without states", { ...KINDS.closure, session: { verdicts: "approvals", seal: "seal", subjects: { kind: "contract.kind.mjs" } } }, /session: a session kind must have states/],
+    ["a seal without states (#2546)", { ...KINDS.closure, seal: { field: "seal" } }, /seal: a kind without states cannot have seal/],
+    ["a seal naming another field than session.seal (#2546)", { ...KINDS.session, session: { verdicts: "approvals", seal: "seal", subjects: { kind: "contract.kind.mjs" } }, seal: { field: "closed_digest" } }, /seal: seal.field and session.seal name the field/],
   ])("a kind with %s is kind-invalid, naming the field", async (_label, kind, why) => {
     write("design/closure.kind.mjs", kindFile(kind));
     const error = await failure("closure");