@intentius/chant 0.102.0 → 0.104.0

package/src/workspace/reason-codes.ts

@@ -136,10 +136,14 @@ export const REASONS = {
   "source-harvest-not-proposed": "A harvested record (source.via harvest) was written in a state other than the kind's first: a harvest proposes, and a person decides.",
   "ratify-quorum-not-met": "The write puts a record in its kind's ratified state (reviews.ratified), and the record's quorum is not met: too few agreeing verdicts count.",
   "record-sign-failed": "--sign was given and no author seal could be made: the record names no author, the key can't be read or used, git names no ssh signing key, or ssh-keygen is not installed.",
+  // Concurrent writers in one working tree (#3173, ws-089): a write that is refused rather than overwrite another's.
+  "record-conflict": "--expect named a digest the record no longer has: another write changed it after the caller read it. The refusal names the digest it has now; re-read the record and write again.",
+  "write-lock-timeout": "Another write held the working tree's write lock for longer than the write waits (CHANT_WRITE_LOCK_WAIT_MS); the refusal names the holder. Run the write again.",
+  "write-lock-not-held": "CHANT_WRITE_LOCK names a batch's lock token that no longer holds the working tree's write lock: the batch released it, or it expired and another writer took it.",
   // Write scope (#2548): a records write that is refused, and a commit check --changes reports, outside the writer's scope.
   "write-scope-member": "The write is to a file, or to a record kind, of a member outside the writer's scope: an agent session writes only its own member, and writeScope.<class>.members leaves the member out.",
   "write-scope-kind": "The write is to a record kind writeScope.<class>.records does not list, with a verb it does not list for the kind, or deletes a record.",
-  "write-scope-protected": "The write is to a file writeScope.<class>.protected lists, or one under a directory it lists, outside any top-level keys the entry's except allows (#3146).",
+  "write-scope-protected": "The write is to a file writeScope.<class>.protected lists, or one under a directory it lists, outside the top-level keys or JSON Pointers the entry's except allows (#3146, #3308).",
   "write-scope-class-unknown": "The declaration's writeScope at base names a principal class no pinned package supplies, and the writer is judged human, so it may be in that class; the write is refused until the package is installed at the pinned version or the entry removed (#3080).",
   "agent-unknown": "CHANT_AGENT, or a commit's Chant-Agent trailer, names an agent session the declaration at base does not declare.",
   "principal-unidentified": "chant.workspace.json at base sets identity.attribution to identified, and the write names a person by a bare name: --by, an author field or a decision point's answerer must be a forge identity (github:<login>, gitlab:<login>, <forge>@<host>:<login>), a principal the signers file at base lists, or an agent, runner or service principal (#3163).",
@@ -155,6 +159,9 @@ export const REASONS = {
   "answer-not-candidate": "The people's answer is not one of the question's candidates.",
   "quorum-not-met": "Too few of the people who answered count toward the point's quorum: distinct, not holding the agent role, not the steward that asked, and holding one of its roles when it names any.",
   "answer-in-steward-turn": "The answer was given during a steward's turn, or by a process it started: a steward never answers a decision point, and a person answers it through hud or at a shell.",
+  "answer-not-answered": "points retract names a question that has no answer to retract: it is escalated or proposed, and people answer it instead (#3351).",
+  "answer-field-unsupported": "The answer kind's copy of point-answer.schema.json predates a field the write needs, a note, a relay, a retraction or an ad-hoc question's asked: copy the schema anew to turn it on (#3351, #3402, #3403).",
+  "point-candidates-invalid": "points ask names an ad-hoc point without --candidates, a declared point with them, or candidates that are not a question and criteria of the point's question type (#3403).",
   // records --since that fails (#2673).
   "since-rev-unknown": "--since names no commit, or a session with no opening revision and no commit that added it.",
   "since-session-unknown": "--since has the shape of a session id and names no commit, and no session the kind or the declaration reads has that id.",
@@ -168,6 +175,7 @@ export const REASONS = {
   // The intent graph: part of the walk that can't be read. The document is still printed.
   "intent-history-shallow": "The repository is a shallow clone, so the region's history stops at the clone's boundary.",
   "intent-plugin-failed": "A kind file's commitJoins, which joins commits to units, contracts and evidence, failed for a commit.",
+  "squash-unfollowed": "A squash commit's pull request ref (refs/pull/<n>/head) is not in the clone and could not be fetched from origin, so its original commits are not followed; the read keeps its answer without them.",
   // The intent graph: findings, each a node in the graph.
   "intent-commit-undecided": "A commit changed the region when no decision constrained it at path granularity.",
   "intent-commit-bare": "A commit names no unit, carries no record through its Chant-Record or Chant-Lease trailer, and has no pull request and no decision covering the region at its time.",
@@ -186,6 +194,7 @@ export const REASONS = {
   "intent-decision-unimplemented": "A decided decision constrains the region, no work item that is not dropped implements it, and no commit falls in its window.",
   "intent-work-blocked": "A work item constraining the region has commits in its window while a work item it needs is not done.",
   "intent-work-open-decided-code": "Commits in the region are a decision's own work while the work item implementing that decision is still open.",
+  "intent-commit-join-conflict": "A commit joined to an agent run by its Chant-Run trailer or the run's record has the patch-id of a commit another run recorded, so it is not joined to that run by content.",
   // The intent graph's answer to why the region is like this (#3034): what it can't account for.
   "intent-why-no-decision": "No current decision governs the region at any granularity, and none is carried out by the commits or runs that made its current lines.",
   "intent-why-no-run": "None of the region's current lines was made by a commit an agent run is joined to.",
@@ -207,6 +216,7 @@ export const REASONS = {
   "environments-none-declared": "The member's chant.config.ts declares no environments, so only local and the environments in its ledger are listed.",
   "environments-ledger-undeclared": "The member's ledger has releases in an environment its config's environments don't cover, so chant run --env would refuse it and it is not listed.",
   "environments-ledger-unreadable": "The chant/lifecycle branch exists and the member's ledger environments could not be listed.",
+  "environments-component-undeclared": "A component declares an environment its member's chant.config.ts environments don't cover, so chant run --env would refuse it and it is not listed (#3153).",
   // A declared diagram's source or render (check, #2764). Each is also a WSP finding.
   "diagram-source-missing": "A declared diagram's source file does not exist in the tree read.",
   "diagram-render-missing": "A declared diagram's render file does not exist in the tree read.",
@@ -241,6 +251,30 @@ export const REASONS = {
   "run-ended": "runs end names a run whose end is already recorded.",
   "runs-no-ledger": "The checkout has no chant/lifecycle branch, so there are no agent runs to read.",
   "runs-ledger-malformed": "Some lines of the agent run ledger aren't run events; the rest are read.",
+  // The agent-run statement (runs sign, statement and verify, #3192): why a statement is refused or does not verify.
+  "run-not-ended": "runs sign or runs statement names a run with no end recorded. A statement is signed over the run's whole record.",
+  "run-statement-invalid": "The envelope's payload is not an in-toto Statement v1 with chant's agent-run predicate, or has a field the predicate does not define.",
+  "run-statement-signer-mismatch": "The statement names a signer other than the runner whose key signed it.",
+  "run-statement-mismatch": "A listed runner key signed the statement, and it does not match the run's record: another run, a record that hashes differently, or another unit, harness, model, provider or principal.",
+  // A box's listing written through chant (box listing set, #3308): why the write was refused. Nothing is written.
+  "listing-member-unknown": "box listing set names a member the declaration does not declare.",
+  "listing-box-missing": "box listing set names a member whose entry declares no box block, so it has no listing.",
+  "listing-cover-invalid": "The cover can't be read, is not a PNG, JPEG or WebP picture, is larger than 5 MiB, has a path outside the workspace, or has an extension other than its picture format's.",
+  // A box's work published through chant (box publish, #3165, ws-088): why the call printed no result.
+  "publish-member-unknown": "box publish names a member the declaration does not declare.",
+  "publish-none": "box publish names a member whose box block names no publisher, or which declares no box block.",
+  "publish-refused": "The box's publisher refused (it exited 2): nothing was published, and its message says why.",
+  "publish-failed": "The box's publisher could not be run, failed (a nonzero exit other than 2) or ran out of time; its message says what it had done.",
+  "publish-answer-invalid": "The box's publisher exited 0 and printed no JSON object, or one box-publish.schema.json does not allow.",
+  "publish-unrecorded": "The commit the publisher named is not in the repository, or lacks the apply record of ws-075: Chant-Applied-By naming --by, Chant-Applied-At, Chant-Applied-Commit and a Chant-Record for the item, or a Chant-Record for each record sent.",
+  // Work in progress under refs/chant/wip/<branch> and its replication (wip save|restore|push|fetch, #3172): why the write was refused. Nothing is written.
+  "wip-no-branch": "HEAD is detached, or names a branch with no commit yet, so there is no branch to keep work in progress for.",
+  "wip-none": "wip restore was given no snapshot, and the branch has none under refs/chant/wip/<branch>.",
+  "wip-snapshot-unknown": "wip restore names something that is not a work-in-progress snapshot chant took.",
+  "wip-branch-other": "wip restore names a snapshot taken on another branch than the one checked out.",
+  "wip-race": "Another writer moved refs/chant/wip/<branch> between this command's read and its write.",
+  "wip-policy-none": "wip push or wip fetch was run, and no box block declares replicate, so there is no remote.",
+  "wip-remote-unknown": "The replicate policy names a git remote the checkout does not have; the host adds it, with its credential, before chant pushes.",
   // A box whose isolation fails (check, #2727). Each is also a WSP finding.
   "box-isolation-collision": "Two boxes on one host resolve to the same port, state path or cookie name, or two ports in one box share an offset.",
   "box-isolation-literal": "A host's stateRoot or a box's state entry is a literal machine path instead of one derived from an environment reference and the box's name.",
@@ -263,9 +297,9 @@ export const REASONS = {
   "evidence-payload-type": "The envelope's payload type is not application/vnd.in-toto+json.",
   "evidence-statement-invalid": "The payload is not an in-toto Statement v1 with chant's runner-evidence predicate, or has a field the predicate does not define.",
   "evidence-runner-mismatch": "The statement names a runner other than the one whose key signed it.",
-  "runner-key-invalid": "The key given to evidence sign is not an Ed25519 private key in PEM.",
-  "runner-key-is-signer": "The key given to evidence sign is a person's key in the signers file. Evidence is signed by a service or CI identity.",
-  "runner-key-unlisted": "The policy at base lists no runner with the key given to evidence sign.",
+  "runner-key-invalid": "The key given to evidence sign or runs sign is not an Ed25519 private key in PEM.",
+  "runner-key-is-signer": "The key given to evidence sign or runs sign is a person's key in the signers file. Evidence and run statements are signed by a service or CI identity.",
+  "runner-key-unlisted": "The policy at base lists no runner with the key given to evidence sign or runs sign.",
   // The lineage lock (check).
   "lock-invalid": "The lineage lock can't be read.",
   "manual-step-open": "A scope in the lineage lock has an open manual step.",

package/src/workspace/record-sessions.ts

@@ -12,7 +12,7 @@
  * `citedBy`. This module only reads; nothing here writes a seal into a file.
  */
 
-import { recordSeal, type RecordEntry, type RecordFormat, type RecordKind } from "./records";
+import { recordSeal, sessionSubjectKinds, type RecordEntry, type RecordFormat, type RecordKind, type SessionSubjects } from "./records";
 
 /** A subject record's review entry that names a session in its `session` field. */
 export interface SessionCitation {
@@ -43,18 +43,19 @@ export function sessionSeal(text: string, field: string, format: RecordFormat =
 /**
  * Check each session in `entries` against its seal and the subject records,
  * and fill in `citedBy`. `texts` holds each entry's file text by path.
- * `subjects` holds the subject records and the name of their reviews list;
- * it is null when they were not read, and then no verdict is checked.
+ * `subjects` holds the records of each subject kind and the name of their
+ * reviews list; it is null when they were not read, and then no verdict is
+ * checked.
  */
-export function joinSessions(kind: RecordKind, entries: RecordEntry[], texts: Map<string, string>, subjects: { records: RecordEntry[]; reviews: string } | null): void {
+export function joinSessions(kind: RecordKind, entries: RecordEntry[], texts: Map<string, string>, subjects: SessionSubjects[] | null): void {
   const decl = kind.session;
   if (!decl) return;
   const closed = new Set(kind.closedStates);
-  const subjectIds = new Set(subjects?.records.map((s) => s.id).filter((id): id is string => id !== null) ?? []);
+  const subjectIds = new Set((subjects ?? []).flatMap((k) => k.records.map((s) => s.id)).filter((id): id is string => id !== null));
   const citations = new Map<string, SessionCitation[]>();
-  for (const s of subjects?.records ?? []) {
+  for (const { s, reviewsField } of (subjects ?? []).flatMap((k) => k.records.map((s) => ({ s, reviewsField: k.reviews })))) {
     if (s.id === null) continue;
-    const reviews = s.data?.[subjects!.reviews];
+    const reviews = s.data?.[reviewsField];
     if (!Array.isArray(reviews)) continue;
     reviews.forEach((r, index) => {
       if (r === null || typeof r !== "object") return;
@@ -96,7 +97,7 @@ export function joinSessions(kind: RecordKind, entries: RecordEntry[], texts: Ma
       if (v === null || typeof v !== "object") return;
       const record = (v as Record<string, unknown>).record;
       if (typeof record === "string" && !subjectIds.has(record)) {
-        e.reasons.push({ code: "session-verdict-unknown-record", message: `${decl.verdicts}[${i}] names ${record}, which no ${decl.subjects.kind} record has` });
+        e.reasons.push({ code: "session-verdict-unknown-record", message: `${decl.verdicts}[${i}] names ${record}, which no ${sessionSubjectKinds(decl).join(" or ")} record has` });
       }
     });
   }

package/src/workspace/records-amend.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."
@@ -176,6 +181,9 @@
                 "amend-supersede-instead",
                 "record-sign-failed",
                 "ratify-quorum-not-met",
+                "record-conflict",
+                "write-lock-timeout",
+                "write-lock-not-held",
                 "write-scope-member",
                 "write-scope-kind",
                 "write-scope-class-unknown",
@@ -199,6 +207,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-cli.ts

@@ -23,7 +23,7 @@
  */
 
 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";
@@ -40,6 +40,7 @@ import {
   loadRecordKind,
   normalisePrincipal,
   readRecords,
+  readSessionSubjects,
   RECORD_SEAL_FIELD,
   RecordReadError,
   type LoadedRecordKind,
@@ -54,6 +55,15 @@ import {
   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, WorkAnswer } from "./work";
 import { activeAttestors, type CommitAttestor, type ProvenanceLevel } from "./trust/attestor";
@@ -122,6 +132,12 @@ export type RecordView = RecordEntry & {
    * (`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
@@ -372,11 +388,7 @@ 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 };
 }
@@ -451,6 +463,8 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       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");

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,6 +176,9 @@
                 "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",
@@ -193,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,
+  );
+});