@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/records-cli.ts

@@ -15,10 +15,15 @@
  *
  * 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";
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
@@ -35,6 +40,7 @@ import {
   loadRecordKind,
   normalisePrincipal,
   readRecords,
+  readSessionSubjects,
   RECORD_SEAL_FIELD,
   RecordReadError,
   type LoadedRecordKind,
@@ -48,8 +54,18 @@ import {
   type SealInput,
   type VerdictAttestation,
 } from "./records";
+import { readCheckoutHead, worktreeStates, type CheckoutView, type WorktreeState } from "./records-checkout";
+import { lastWriteReader, type LastWrite } from "./write-lock";
+
+function readTextOrNull(file: string): string | null {
+  try {
+    return readFileSync(file, "utf-8");
+  } catch {
+    return null;
+  }
+}
 import { gitTree, workingTree, type WorkspaceTree } from "./tree";
-import type { DecisionWork } from "./work";
+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 { returnedPolicy, type TrustPolicy } from "./trust/policy";
@@ -62,7 +78,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 +97,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 +126,26 @@ 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;
+  /**
+   * Beside `worktree` (#3173): the last chant write of the record's file, from
+   * the write journal (`write-lock.ts`), while the file holds the text it
+   * left, or null.
+   */
+  lastWrite?: LastWrite | null;
+  /**
+   * 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). */
@@ -134,6 +172,10 @@ export type RecordsDocument =
       /** 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 };
@@ -227,7 +269,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, ...(query.current ? { spec: specOf(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. */
@@ -345,17 +388,15 @@ export async function readRecordsFor(
   if (at === null && query.overlay) source = await query.overlay(source, { loaded, root });
   const history = top ? gitHistory(top, at ?? "HEAD", workspaceRoot) : undefined;
   // A session kind's verdicts name records of another kind, read from the same tree (#2673).
-  let subjects: { records: RecordEntry[]; reviews: string } | undefined;
-  if (loaded.kind.session) {
-    const subjectKind = await loadRecordKind(resolve(dirname(loaded.file), loaded.kind.session.subjects.kind), cwd);
-    subjects = { records: (await readRecords(subjectKind, { root, source })).records, reviews: subjectKind.kind.reviews?.field ?? "reviews" };
-  }
+  const subjects = await readSessionSubjects(loaded, root, source);
   const result = await readRecords(loaded, { root, source, current: !!query.current, assets, workspaceRoot, ...(history ? { history } : {}), ...(subjects ? { subjects } : {}) });
   return { loaded, root, top, at, workspaceRoot, tree: assets, result };
 }
 
 /** 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).
@@ -395,6 +436,43 @@ 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";
+      const lastWrite = lastWriteReader(top);
+      for (const r of records) 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");
+        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,
@@ -408,9 +486,11 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       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) {
@@ -561,6 +641,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 }));
@@ -579,13 +664,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) {
@@ -643,7 +728,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) {
@@ -651,7 +736,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) {
@@ -717,7 +802,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));
@@ -728,7 +826,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(", ");
@@ -745,9 +844,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");
 }
 

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

@@ -108,6 +108,11 @@
             "$ref": "#/$defs/warning"
           }
         },
+        "digest": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "Added in contract 1 by #3173. The record's digest after the write, as chant workspace records --json reports it (with --dry-run, the digest it would have). Pass it as --expect to the next amend, review or close of the record, so that write is refused with record-conflict if someone else wrote the record in between."
+        },
         "text": {
           "type": "string",
           "description": "With --dry-run only: the whole text of the file the command would write."
@@ -171,8 +176,12 @@
                 "write-usage-invalid",
                 "record-not-found",
                 "record-closed",
+                "record-conflict",
+                "write-lock-timeout",
+                "write-lock-not-held",
                 "write-scope-member",
                 "write-scope-kind",
+                "write-scope-class-unknown",
                 "agent-unknown",
                 "record-unparseable",
                 "record-schema-invalid",
@@ -192,6 +201,76 @@
             }
           }
         },
+        "conflict": {
+          "type": "object",
+          "description": "Added in contract 1 by #3173. With record-conflict only: the record as it is now. Re-read it, and write again with --expect set to digest if the change still stands.",
+          "required": [
+            "id",
+            "path",
+            "expected",
+            "digest",
+            "lastWrite"
+          ],
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string",
+              "description": "The record file, from the repository root."
+            },
+            "expected": {
+              "type": "string",
+              "description": "The digest given with --expect."
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "The record's digest now."
+            },
+            "lastWrite": {
+              "description": "The last chant write of the record file, from the write journal in the git directory, while the file still holds the text it left; null when the journal does not know it.",
+              "oneOf": [
+                {
+                  "type": "null"
+                },
+                {
+                  "type": "object",
+                  "required": [
+                    "verb",
+                    "by",
+                    "agent",
+                    "at"
+                  ],
+                  "properties": {
+                    "verb": {
+                      "type": "string",
+                      "description": "The write command, such as records amend or points answer."
+                    },
+                    "by": {
+                      "type": [
+                        "string",
+                        "null"
+                      ],
+                      "description": "The principal the write named, or null when it named none."
+                    },
+                    "agent": {
+                      "type": [
+                        "string",
+                        "null"
+                      ],
+                      "description": "The agent session it was made in (CHANT_AGENT), or null."
+                    },
+                    "at": {
+                      "type": "string",
+                      "description": "When, as an ISO 8601 time."
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        },
         "path": false
       }
     }

package/src/workspace/records-close.ts

@@ -10,10 +10,11 @@
  * in place and writes only when the session comes back valid: a verdict
  * naming a record the subjects lack is refused with
  * `session-verdict-unknown-record`. A session already closed is
- * `record-closed`. It writes one file or none and never commits.
+ * `record-closed`. It writes one file or none and never commits. Like them
+ * it holds the working tree's write lock, and takes `--expect <digest>`
+ * (#3173).
  */
 
-import { writeFileSync } from "node:fs";
 import type { ReasonCode } from "./reason-codes";
 import { sessionSeal } from "./record-sessions";
 import { RECORD_REASON_CODES } from "./records";
@@ -28,12 +29,15 @@ import {
   RECORDS_WRITE_CONTRACT_VERSION,
   RecordWriteError,
   refuseOutOfScope,
+  refuseStale,
   replaceFields,
   stableJson,
-  validateWrite,
+  validatedEntry,
+  writeWho,
   type WriteFailure,
   type WriteResult,
 } from "./records-write";
+import { noteWrites, withWriteLock, writeFileAtomic, WRITE_LOCK_CODES } from "./write-lock";
 import { headCommit } from "./session-kinds";
 import { WRITE_SCOPE_CODES } from "./write-scope";
 
@@ -45,6 +49,8 @@ export const CLOSE_ERROR_CODES = [
   "write-usage-invalid",
   "record-not-found",
   "record-closed",
+  "record-conflict",
+  ...WRITE_LOCK_CODES,
   ...WRITE_SCOPE_CODES,
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
@@ -71,6 +77,8 @@ export interface CloseRecordOptions {
   now?: Date;
   /** The agent session the write is made in (#2548). */
   agent?: string;
+  /** The session's digest the caller last read (#3173): the close is refused with record-conflict when it has another. */
+  expect?: string;
 }
 
 /** An ISO 8601 time in UTC to the second, as the reference session schema's dateTime takes it. */
@@ -78,8 +86,19 @@ function isoSeconds(d: Date): string {
   return d.toISOString().replace(/\.\d{3}Z$/, "Z");
 }
 
-/** `records close`: close one open session and seal it. */
+/** `records close`: close one open session and seal it, holding the write lock (#3173). */
 export async function closeRecord(opts: CloseRecordOptions): Promise<CloseDocument> {
+  try {
+    if (opts.expect !== undefined && !/^[0-9a-f]{64}$/.test(opts.expect)) {
+      throw new RecordWriteError("write-usage-invalid", `--expect takes a record's digest, 64 lowercase hex digits as records --json prints it, not ${JSON.stringify(opts.expect)}`);
+    }
+    return await withWriteLock(opts.cwd, writeWho("records close", opts), opts.dryRun, () => closeRecordLocked(opts));
+  } catch (err) {
+    return failure<CloseErrorCode>(RECORDS_CLOSE_SCHEMA_ID, err);
+  }
+}
+
+async function closeRecordLocked(opts: CloseRecordOptions): Promise<CloseDocument> {
   try {
     const o = await open(opts.kind, opts.cwd);
     refuseOutOfScope(o, "close", opts.cwd, opts);
@@ -92,6 +111,7 @@ export async function closeRecord(opts: CloseRecordOptions): Promise<CloseDocume
     if (closedState === undefined) throw new RecordWriteError("write-usage-invalid", `the ${kind.name} kind lists no closed state, so a session of it can't close`);
     const before = await readAll(o, o.source);
     const target = findRecord(before, opts.id, kind.name);
+    refuseStale(o, target, opts.id, opts.expect);
     if (target.state !== null && (kind.closedStates ?? []).includes(target.state)) {
       throw new RecordWriteError("record-closed", `${opts.id} is already ${target.state}, and a closed session is sealed and stays as it is`);
     }
@@ -115,8 +135,11 @@ export async function closeRecord(opts: CloseRecordOptions): Promise<CloseDocume
     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`);
     }
-    const warnings = await validateWrite(o, before, target.path, text);
-    if (!opts.dryRun) writeFileSync(abs(o, target.path), text);
+    const entry = await validatedEntry(o, before, target.path, text);
+    if (!opts.dryRun) {
+      writeFileAtomic(abs(o, target.path), text);
+      noteWrites(o.root, [{ path: target.path, text }], writeWho("records close", opts));
+    }
     const written = { ...merged, [decl.seal]: digest };
     return {
       $schema: RECORDS_CLOSE_SCHEMA_ID,
@@ -128,7 +151,8 @@ export async function closeRecord(opts: CloseRecordOptions): Promise<CloseDocume
       seal: { field: decl.seal, digest },
       closedRev,
       dryRun: !!opts.dryRun,
-      warnings,
+      warnings: entry.warnings,
+      digest: entry.digest,
       ...(opts.dryRun ? { text } : {}),
     };
   } catch (err) {

package/src/workspace/records-concurrent.e2e.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Concurrent writers in one working tree through the command line (#3173,
+ * ws-089): three `records amend --expect` processes started at once against
+ * one record, two people's and an agent's (CHANT_AGENT). Exactly one wins;
+ * the others exit 1 with record-conflict and the digest to retry from, and the
+ * retry wins. Then a batch: `lock acquire` holds the lock, a write run with
+ * CHANT_WRITE_LOCK goes ahead, and one without it is refused with
+ * write-lock-timeout until `lock release`. The in-process cases are in
+ * records-concurrent.test.ts.
+ */
+
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, git, REPO, repo } from "./__fixtures__/contract-repo";
+import { parseFrontMatter } from "./records";
+import { renderRecord } from "./records-write";
+
+const DECISIONS = join(REPO, "docs", "design", "decisions");
+const KIND = "decisions/decision.kind.mjs";
+type Data = Record<string, unknown>;
+
+const SAMPLE = (() => {
+  const fm = parseFrontMatter(readFileSync(join(DECISIONS, "ws-003-seal-scope.md"), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+})();
+const proposal = (over: Data): Data => ({ ...structuredClone(SAMPLE), state: "proposed", choice: null, decided_by: null, decided_on: null, ...over });
+
+let root: string;
+beforeAll(() => {
+  root = repo(
+    {
+      "chant.workspace.json": JSON.stringify({
+        name: "box",
+        schema: 1,
+        members: [{ name: "app", dir: "app", kind: "other", because: "a plain Node server" }],
+        records: [{ kind: KIND }],
+        writeScope: { agent: { records: { decision: ["new", "amend", "review"] } } },
+        agents: [{ name: "app-agent", member: "app" }],
+      }),
+      [KIND]: readFileSync(join(DECISIONS, "decision.kind.mjs"), "utf-8"),
+      "decisions/decision.schema.json": readFileSync(join(DECISIONS, "decision.schema.json"), "utf-8"),
+      "decisions/ws-001-one.md": renderRecord(proposal({ id: "ws-001", title: "One" }), "\n# One\n"),
+      "app/server.mjs": "export const port = 8080;\n",
+    },
+    true,
+  );
+  git(root, "branch", "-M", "main");
+});
+afterAll(cleanScratch);
+
+/** Run chant in the repository, without waiting on the others. */
+function chant(args: string[], opts: { input?: string; env?: Record<string, string> } = {}): Promise<{ status: number; doc: Record<string, any> }> {
+  const loader = pathToFileURL(join(REPO, "node_modules", "tsx", "dist", "loader.mjs")).href;
+  return new Promise((resolve, reject) => {
+    const child = execFile(
+      process.execPath,
+      ["--import", loader, join(REPO, "packages", "core", "src", "cli", "main.ts"), "workspace", ...args],
+      { cwd: root, encoding: "utf-8", env: { ...process.env, TSX_DISABLE_CACHE: "1", ...opts.env } },
+      (err, stdout, stderr) => {
+        try {
+          resolve({ status: err ? Number((err as { code?: number }).code ?? 1) : 0, doc: JSON.parse(stdout) });
+        } catch {
+          reject(new Error(`chant ${args.join(" ")} printed no JSON: ${stderr}`));
+        }
+      },
+    );
+    child.stdin!.end(opts.input ?? "");
+  });
+}
+
+const amend = (fields: Data, expect: string, env?: Record<string, string>) => chant(["records", "amend", "ws-001", "--kind", KIND, "--set", "-", "--expect", expect], { input: JSON.stringify(fields), env });
+
+describe("concurrent writers through the command line (#3173)", () => {
+  test(
+    "three amends from one digest in three processes: one wins, two conflict, and their retries win",
+    async () => {
+      const read = await chant(["records", "--kind", KIND, "--json"]);
+      const d0 = read.doc.records.find((r: { id: string }) => r.id === "ws-001").digest as string;
+      const runs = await Promise.all([
+        amend({ title: "One, as alice has it" }, d0),
+        amend({ question: "What does bob ask?" }, d0),
+        amend({ constrains: ["member:app"] }, d0, { CHANT_AGENT: "app-agent" }),
+      ]);
+      const won = runs.filter((r) => r.status === 0);
+      const lost = runs.filter((r) => r.status !== 0);
+      expect(won).toHaveLength(1);
+      expect(lost.map((r) => r.doc.error.code)).toEqual(["record-conflict", "record-conflict"]);
+      const d1 = won[0].doc.digest as string;
+      for (const r of lost) expect(r.doc.conflict).toMatchObject({ expected: d0, digest: d1, lastWrite: { verb: "records amend" } });
+
+      // Each loser retries from what it was told, one after the other.
+      const fieldsOf = (i: number) => [{ title: "One, as alice has it" }, { question: "What does bob ask?" }, { constrains: ["member:app"] }][i];
+      let digest = d1;
+      for (const r of lost) {
+        const i = runs.indexOf(r);
+        const retry = await amend(fieldsOf(i), digest, i === 2 ? { CHANT_AGENT: "app-agent" } : undefined);
+        expect(retry.status).toBe(0);
+        digest = retry.doc.digest;
+      }
+      const end = await chant(["records", "--kind", KIND, "--json"]);
+      const rec = end.doc.records.find((r: { id: string }) => r.id === "ws-001");
+      expect(rec.digest).toBe(digest);
+      expect(rec.data).toMatchObject({ title: "One, as alice has it", question: "What does bob ask?", constrains: ["member:app"] });
+      expect(rec.lastWrite).toMatchObject({ verb: "records amend" });
+    },
+    120_000,
+  );
+
+  test(
+    "a batch holds the lock across calls: its own writes go ahead, another writer's waits and is refused",
+    async () => {
+      const taken = await chant(["lock", "acquire", "--holder", "hud:alice", "--ttl", "60s"]);
+      expect(taken).toMatchObject({ status: 0, doc: { verb: "acquire", holder: { verb: "batch", by: "hud:alice" } } });
+      const token = taken.doc.token as string;
+      const status = await chant(["lock"]);
+      expect(status.doc.holder).toMatchObject({ by: "hud:alice" });
+      expect(status.doc.token).toBeUndefined();
+
+      const outsider = await chant(["records", "review", "ws-001", "--kind", KIND, "--verdict", "agree", "--by", "bob"], { env: { CHANT_WRITE_LOCK_WAIT_MS: "300" } });
+      expect(outsider).toMatchObject({ status: 1, doc: { error: { code: "write-lock-timeout" } } });
+      expect(outsider.doc.error.message).toContain("hud:alice");
+      const inside = await chant(["records", "review", "ws-001", "--kind", KIND, "--verdict", "agree", "--by", "alice"], { env: { CHANT_WRITE_LOCK: token } });
+      expect(inside.status).toBe(0);
+
+      expect((await chant(["lock", "release", "--token", token])).status).toBe(0);
+      const after = await chant(["records", "review", "ws-001", "--kind", KIND, "--verdict", "agree", "--by", "bob"]);
+      expect(after.status).toBe(0);
+    },
+    120_000,
+  );
+});