@intentius/chant 0.101.0 → 0.102.0

package/src/workspace/trailer-joins.test.ts

@@ -0,0 +1,171 @@
+/**
+ * chant's commit trailers (#3149): the vocabulary, and the joins `graph
+ * --intent` and `graph --intent --record` make through it.
+ *
+ * - c0 adds the workspace and s-001, decided, which constrains path:app.
+ * - c1 adds W-001, open, implementing s-001.
+ * - c2 edits app/main.js with Chant-Record: work:W-001, Chant-Run and Chant-Agent.
+ * - c3 edits app/main.js with only a Chant-Lease, whose token the lease
+ *   history of W-001 on chant/lifecycle names.
+ * - c4 edits app/main.js with Chant-Record: decision:s-001.
+ * - c5 edits app/main.js with nothing to account for it.
+ * - c6 edits app/main.js with a Chant-Record no kind has, and the apply trailers.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { writeBlobToPath } from "../lifecycle/git";
+import { cleanScratch, contract, git, REPO, repo, writeFiles } from "./__fixtures__/contract-repo";
+import { intentGraph, type CommitNode, type IntentDocument } from "./intent";
+import { intentRecord, type IntentRecordDocument } from "./intent-record";
+import intentRecordSchema from "./intent-record.schema.json";
+import intentSchema from "./intent.schema.json";
+import { parseFrontMatter } from "./records";
+import { formatChantTrailers, parseRecordRef, readChantTrailers } from "./trailers";
+
+const REF = join(REPO, "reference-workspace");
+const BASE = (() => {
+  const fm = parseFrontMatter(readFileSync(join(REF, "decisions", "ref-001-how-the-app-is-deployed.md"), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+})();
+
+function decision(id: string, fields: Record<string, unknown>): string {
+  const data = { ...BASE, id, title: `Decision ${id}`, state: "decided", supersedes: [], evidence: [], reviews: [], ...fields };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+function work(id: string, fields: Record<string, unknown>): string {
+  const data = { schema: 1, id, title: `Work ${id}`, state: "open", implements: [], needs: [], constrains: [], evidence: [], opened_on: "2026-10-01", supersedes: [], ...fields };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n\nWhat the work is.\n`;
+}
+
+const TOKEN = "3f0c7d2e-lease-token";
+const TIP = "a".repeat(40);
+let root: string;
+const sha: Record<string, string> = {};
+let tick = 0;
+
+function commit(message: string[]): string {
+  const date = `2026-10-01T12:00:${String(tick++).padStart(2, "0")}Z`;
+  process.env.GIT_AUTHOR_DATE = date;
+  process.env.GIT_COMMITTER_DATE = date;
+  try {
+    git(root, "add", "-A");
+    git(root, "commit", "-q", ...message.flatMap((m) => ["-m", m]));
+  } finally {
+    delete process.env.GIT_AUTHOR_DATE;
+    delete process.env.GIT_COMMITTER_DATE;
+  }
+  return git(root, "rev-parse", "HEAD");
+}
+
+const KINDS = ["decisions/decision.kind.mjs", "work/work.kind.mjs"];
+
+beforeAll(async () => {
+  root = repo({
+    "chant.workspace.json": JSON.stringify({ name: "trailers", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "the app" }] }),
+    "decisions/decision.kind.mjs": readFileSync(join(REF, "decisions", "decision.kind.mjs"), "utf-8"),
+    "decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
+    "work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
+    "work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
+    "app/main.js": "export const n = 0;\n",
+    "decisions/s-001-app.md": decision("s-001", { constrains: ["path:app"] }),
+  });
+  sha.c0 = commit(["the workspace, and s-001"]);
+  writeFiles(root, { "work/W-001-app.md": work("W-001", { implements: ["s-001"] }) });
+  sha.c1 = commit(["W-001"]);
+  writeFiles(root, { "app/main.js": "export const n = 1;\n" });
+  sha.c2 = commit(["one", formatChantTrailers({ agent: "factory", run: "r-0001", records: ["work:W-001"] }).join("\n")]);
+  writeFiles(root, { "app/main.js": "export const n = 2;\n" });
+  sha.c3 = commit(["two", `Chant-Lease: ${TOKEN}`]);
+  writeFiles(root, { "app/main.js": "export const n = 3;\n" });
+  sha.c4 = commit(["three", "Chant-Record: decision:s-001"]);
+  writeFiles(root, { "app/main.js": "export const n = 4;\n" });
+  sha.c5 = commit(["four"]);
+  writeFiles(root, { "app/main.js": "export const n = 5;\n" });
+  sha.c6 = commit(["five", formatChantTrailers({ records: [{ kind: "contract", id: "C-001" }], applied: { by: "alice", at: "2026-10-01T12:00:06Z", commit: TIP } }).join("\n")]);
+  const line = { version: 1, event: "claim", item: "W-001", holder: "factory", by: "factory", token: TOKEN, acquiredAt: "2026-10-01T12:00:00Z", expiresAt: "2026-10-01T12:10:00Z", timestamp: "2026-10-01T12:00:00Z" };
+  await writeBlobToPath("_leases", "W-001.jsonl", JSON.stringify(line), "Work lease claim: W-001", { cwd: root });
+});
+afterAll(cleanScratch);
+
+describe("the trailer vocabulary", () => {
+  test("formats in a fixed order and reads back what it wrote", () => {
+    const lines = formatChantTrailers({ applied: { by: "bob", commit: TIP }, records: ["work:W-1", { kind: "decision", id: "ws-075" }], run: "r-1", lease: "tok", agent: "factory" });
+    expect(lines).toEqual(["Chant-Agent: factory", "Chant-Lease: tok", "Chant-Run: r-1", "Chant-Record: work:W-1", "Chant-Record: decision:ws-075", "Chant-Applied-By: bob", `Chant-Applied-Commit: ${TIP}`]);
+    const trailers: Record<string, string[]> = {};
+    for (const l of lines) (trailers[l.slice(0, l.indexOf(":"))] ??= []).push(l.slice(l.indexOf(":") + 1).trim());
+    expect(readChantTrailers(trailers)).toEqual({
+      agent: "factory",
+      lease: "tok",
+      run: "r-1",
+      records: [
+        { kind: "work", id: "W-1" },
+        { kind: "decision", id: "ws-075" },
+      ],
+      applied: { by: "bob", at: null, commit: TIP },
+    });
+  });
+
+  test("refuses a value git would read differently", () => {
+    expect(() => formatChantTrailers({ run: "a\nb" })).toThrow(/one line/);
+    expect(() => formatChantTrailers({ records: ["W-1"] })).toThrow(/<kind>:<id>/);
+    expect(() => formatChantTrailers({ applied: { by: "x", commit: "abc" } })).toThrow(/full commit id/);
+  });
+
+  test("reads keys without case and skips malformed record refs", () => {
+    expect(parseRecordRef("Work:W-1")).toBeUndefined();
+    const t = readChantTrailers({ "chant-record": ["work:W-1", "nonsense", "work:W-1"], "CHANT-RUN": ["r-9"] });
+    expect(t.records).toEqual([{ kind: "work", id: "W-1" }]);
+    expect(t.run).toBe("r-9");
+    expect(t.applied).toBeNull();
+  });
+});
+
+const intentContract = contract(intentSchema);
+const recordContract = contract(intentRecordSchema);
+
+async function region(): Promise<Exclude<IntentDocument, { error: unknown }>> {
+  const { doc } = await intentGraph({ cwd: root, region: "app/main.js", kinds: KINDS.map((k) => join(root, k)) });
+  intentContract.expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+describe("graph --intent joins a commit through chant's trailers", () => {
+  test("each commit node reports what its trailers name", async () => {
+    const doc = await region();
+    const commit = (k: string) => doc.nodes.find((n) => n.id === `commit:${sha[k]}`) as CommitNode;
+    expect(commit("c2").joins).toEqual({ agent: "factory", lease: null, run: "r-0001", records: [{ kind: "work", id: "W-001", node: "record:work/W-001" }], applied: null });
+    expect(commit("c3").joins.lease).toEqual({ token: TOKEN, item: "W-001" });
+    expect(commit("c4").joins.records).toEqual([{ kind: "decision", id: "s-001", node: "record:decision/s-001" }]);
+    expect(commit("c5").joins).toEqual({ agent: null, lease: null, run: null, records: [], applied: null });
+    expect(commit("c6").joins.records).toEqual([{ kind: "contract", id: "C-001", node: null }]);
+    expect(commit("c6").joins.applied).toEqual({ by: "alice", at: "2026-10-01T12:00:06Z", commit: TIP });
+  });
+
+  test("a carried record makes the commit the decision's own work", async () => {
+    const doc = await region();
+    const state = (k: string) => (doc.nodes.find((n) => n.id === `commit:${sha[k]}`) as CommitNode).state;
+    expect(state("c2")).toBe("decided");
+    expect(state("c3")).toBe("decided");
+    expect(state("c4")).toBe("decided");
+    expect(state("c5")).toBe("decided-by-window");
+    expect(state("c6")).toBe("decided-by-window");
+    const carries = doc.edges.filter((e) => e.kind === "carries").map((e) => `${e.from} ${e.to}`);
+    // Newest first, as the history lists the commits.
+    expect(carries).toEqual([`commit:${sha.c4} record:decision/s-001`, `commit:${sha.c3} record:work/W-001`, `commit:${sha.c2} record:work/W-001`]);
+    expect(doc.nodes.some((n) => n.id === "record:work/W-001" && n.kind === "work")).toBe(true);
+  });
+
+  test("graph --intent --record buckets the same commits as own", async () => {
+    const { doc } = await intentRecord({ cwd: root, record: "s-001", kinds: KINDS.map((k) => join(root, k)) });
+    recordContract.expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    const bucket = (k: string) => (doc as Exclude<IntentRecordDocument, { error: unknown }>).commits.find((c) => c.sha === sha[k])?.bucket;
+    expect([bucket("c2"), bucket("c3"), bucket("c4"), bucket("c5")]).toEqual(["own", "own", "own", "worked"]);
+    expect(doc.commits.find((c) => c.sha === sha.c3)?.joins.lease).toEqual({ token: TOKEN, item: "W-001" });
+  });
+});

package/src/workspace/trailer-joins.ts

@@ -0,0 +1,82 @@
+/**
+ * Joining a commit through chant's own trailers (#3149, ws-075), for `graph
+ * --intent` and `graph --intent --record`.
+ *
+ * A plugin's `commitJoins` reads a kind's own trailers (`intent-joins.ts`).
+ * These are core's: a `Chant-Record` names a record by kind and id, and a
+ * `Chant-Lease` names a work lease by its fencing token, which the lease
+ * histories on `chant/lifecycle` turn into the work item it was taken on.
+ * Both read the local branch and never fetch.
+ */
+
+import { execFileSync } from "node:child_process";
+import { parseLeaseHistory } from "../lifecycle/work-lease";
+import { readChantTrailers, type AppliedTrailers, type ChantTrailers } from "./trailers";
+
+/** The branch the lease histories are on. */
+const LEDGER_BRANCH = "refs/heads/chant/lifecycle";
+
+/** What chant's trailers on one commit join it to, as a commit in `graph --intent` reports it. */
+export interface CommitTrailerJoins {
+  /** `Chant-Agent`: the agent session that wrote the commit. */
+  agent: string | null;
+  /** `Chant-Lease`: the work lease's token, and the work item a lease history on `chant/lifecycle` names for it, or null when none does. */
+  lease: { token: string; item: string | null } | null;
+  /** `Chant-Run`: the agent run that made the commit. */
+  run: string | null;
+  /** Each `Chant-Record`, with the id of its node in the graph, or null when no kind read has the record. */
+  records: { kind: string; id: string; node: string | null }[];
+  /** The `Chant-Applied-*` trailers of a commit that applied a leased branch. */
+  applied: AppliedTrailers | null;
+}
+
+function git(top: string, args: string[]): string | undefined {
+  try {
+    return execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The work item each lease token names, from the lease histories
+ * (`_leases/<item>.jsonl`, any member's) on the local `chant/lifecycle`
+ * branch. A token no history names is left out. Never fetches.
+ */
+export function leaseItemsByToken(top: string, tokens: string[]): Map<string, string> {
+  const out = new Map<string, string>();
+  const wanted = [...new Set(tokens.filter((t) => t !== ""))];
+  if (wanted.length === 0 || git(top, ["rev-parse", "--verify", "--quiet", LEDGER_BRANCH]) === undefined) return out;
+  const listed = git(top, ["grep", "-l", "-F", ...wanted.flatMap((t) => ["-e", t]), LEDGER_BRANCH, "--", ":(glob)**/_leases/*.jsonl"]);
+  for (const line of (listed ?? "").split("\n")) {
+    const path = line.startsWith(`${LEDGER_BRANCH}:`) ? line.slice(LEDGER_BRANCH.length + 1) : "";
+    const m = path.match(/(?:^|\/)_leases\/([^/]+)\.jsonl$/);
+    if (!m) continue;
+    const text = git(top, ["show", `${LEDGER_BRANCH}:${path}`]);
+    for (const r of parseLeaseHistory(text ?? "").records) if (wanted.includes(r.token) && r.item === m[1] && !out.has(r.token)) out.set(r.token, r.item);
+  }
+  return out;
+}
+
+/** Read chant's trailers from each commit, and the work items their lease tokens name. */
+export function readTrailerJoins(top: string, commits: { sha: string; trailers: Record<string, string[]> }[]): Map<string, { trailers: ChantTrailers; joins: CommitTrailerJoins }> {
+  const read = commits.map((c) => ({ sha: c.sha, trailers: readChantTrailers(c.trailers) }));
+  const items = leaseItemsByToken(
+    top,
+    read.map((r) => r.trailers.lease).filter((t): t is string => t !== null),
+  );
+  const out = new Map<string, { trailers: ChantTrailers; joins: CommitTrailerJoins }>();
+  for (const { sha, trailers } of read) {
+    out.set(sha, {
+      trailers,
+      joins: {
+        agent: trailers.agent,
+        lease: trailers.lease === null ? null : { token: trailers.lease, item: items.get(trailers.lease) ?? null },
+        run: trailers.run,
+        records: trailers.records.map((r) => ({ kind: r.kind, id: r.id, node: null })),
+        applied: trailers.applied,
+      },
+    });
+  }
+  return out;
+}

package/src/workspace/trailers.ts

@@ -0,0 +1,148 @@
+/**
+ * chant's commit trailers (#3149, ws-075): the vocabulary a commit uses to
+ * name the lease, the agent run, the records and the apply behind it.
+ *
+ * A trailer is how a commit points at a fact kept elsewhere: a work lease on
+ * `chant/lifecycle`, an agent run in the run ledger (#3033), a record in the
+ * working tree. Provenance is keyed to those ids, never to commit SHAs, so a
+ * commit that keeps its message through a rebase or a cherry-pick keeps its
+ * joins (#3037). chant never writes a commit itself (ws-074): whoever makes
+ * the commit adds the trailers, and chant reads them back in `graph
+ * --intent`, `graph --intent --record` and `workspace runs`.
+ *
+ * | Trailer | Value | Names |
+ * |---|---|---|
+ * | `Chant-Agent` | an agent session | the session that wrote the commit (ws-067) |
+ * | `Chant-Lease` | a fencing token | the work lease the commit was made under |
+ * | `Chant-Run` | a run id | the agent run that made the commit (#3033) |
+ * | `Chant-Record` | `<kind>:<id>` | a record the commit carries out or changes; repeatable |
+ * | `Chant-Applied-By` | a principal | who applied a leased branch, on the apply commit |
+ * | `Chant-Applied-At` | ISO 8601 | when it was applied |
+ * | `Chant-Applied-Commit` | a commit id | the tip of the branch that was applied |
+ *
+ * Every other trailer is a plugin's, and core gives it no meaning; a kind's
+ * `commitJoins` may (`intent-joins.ts`).
+ */
+
+import { trailerValue, trailerValues } from "./intent-joins";
+
+/** The agent session that wrote a commit (ws-067). */
+export const AGENT_TRAILER = "Chant-Agent";
+/** The fencing token of the work lease a commit was made under. */
+export const LEASE_TRAILER = "Chant-Lease";
+/** The agent run that made a commit (#3033). */
+export const RUN_TRAILER = "Chant-Run";
+/** A record a commit carries out or changes, as `<kind>:<id>`. Repeatable. */
+export const RECORD_TRAILER = "Chant-Record";
+/** Who applied a leased branch, on the commit that applied it. */
+export const APPLIED_BY_TRAILER = "Chant-Applied-By";
+/** When the branch was applied, ISO 8601. */
+export const APPLIED_AT_TRAILER = "Chant-Applied-At";
+/** The tip of the branch that was applied. */
+export const APPLIED_COMMIT_TRAILER = "Chant-Applied-Commit";
+
+/** Every trailer key core reads, in the order a writer should add them. */
+export const CHANT_TRAILERS = [AGENT_TRAILER, LEASE_TRAILER, RUN_TRAILER, RECORD_TRAILER, APPLIED_BY_TRAILER, APPLIED_AT_TRAILER, APPLIED_COMMIT_TRAILER] as const;
+
+/** A record kind's name, as a kind file's `recordKind.name` gives it. */
+const KIND_NAME = /^[a-z][a-z0-9-]*$/;
+/** A record id, as the record kinds allocate them and as a work lease keys them. */
+const RECORD_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const COMMIT_ID = /^[0-9a-f]{40,64}$/;
+
+/** One `Chant-Record` value. */
+export interface RecordRef {
+  /** The record kind's name, such as `decision` or `work`. */
+  kind: string;
+  id: string;
+}
+
+/** An apply, from the `Chant-Applied-*` trailers. */
+export interface AppliedTrailers {
+  by: string;
+  /** ISO 8601, or null when the trailer is missing. */
+  at: string | null;
+  /** The applied branch's tip, or null when the trailer is missing or is not a commit id. */
+  commit: string | null;
+}
+
+/** What chant's own trailers on one commit say. */
+export interface ChantTrailers {
+  agent: string | null;
+  lease: string | null;
+  run: string | null;
+  /** Each well-formed `Chant-Record` value, in order, without repeats. */
+  records: RecordRef[];
+  applied: AppliedTrailers | null;
+}
+
+/** Parse one `Chant-Record` value, `<kind>:<id>`, or undefined when it is not one. */
+export function parseRecordRef(value: string): RecordRef | undefined {
+  const colon = value.indexOf(":");
+  if (colon <= 0) return undefined;
+  const kind = value.slice(0, colon).trim();
+  const id = value.slice(colon + 1).trim();
+  return KIND_NAME.test(kind) && RECORD_ID.test(id) ? { kind, id } : undefined;
+}
+
+/** Read chant's own trailers from a commit's parsed trailers. Keys compare without case, as git's do. */
+export function readChantTrailers(trailers: Record<string, string[]>): ChantTrailers {
+  const records: RecordRef[] = [];
+  for (const v of trailerValues(trailers, RECORD_TRAILER)) {
+    const ref = parseRecordRef(v);
+    if (ref && !records.some((r) => r.kind === ref.kind && r.id === ref.id)) records.push(ref);
+  }
+  const by = trailerValue(trailers, APPLIED_BY_TRAILER) ?? null;
+  const commit = trailerValue(trailers, APPLIED_COMMIT_TRAILER) ?? null;
+  return {
+    agent: trailerValue(trailers, AGENT_TRAILER) ?? null,
+    lease: trailerValue(trailers, LEASE_TRAILER) ?? null,
+    run: trailerValue(trailers, RUN_TRAILER) ?? null,
+    records,
+    applied: by === null ? null : { by, at: trailerValue(trailers, APPLIED_AT_TRAILER) ?? null, commit: commit !== null && COMMIT_ID.test(commit) ? commit : null },
+  };
+}
+
+/** Whether a commit carries any of chant's own trailers. */
+export function hasChantTrailers(t: ChantTrailers): boolean {
+  return t.agent !== null || t.lease !== null || t.run !== null || t.records.length > 0 || t.applied !== null;
+}
+
+/** What a writer passes to {@link formatChantTrailers}. */
+export interface ChantTrailerInput {
+  agent?: string;
+  lease?: string;
+  run?: string;
+  records?: (RecordRef | string)[];
+  applied?: { by: string; at?: string; commit?: string };
+}
+
+/**
+ * The trailer lines for a commit message, in {@link CHANT_TRAILERS} order.
+ * Throws when a value holds a line break or a record ref is malformed, since
+ * either would write a trailer git parses differently.
+ */
+export function formatChantTrailers(input: ChantTrailerInput): string[] {
+  const lines: string[] = [];
+  const add = (key: string, value: string | undefined) => {
+    if (value === undefined) return;
+    const v = value.trim();
+    if (v === "" || /[\r\n]/.test(v)) throw new Error(`${key} takes one line of text, not ${JSON.stringify(value)}`);
+    lines.push(`${key}: ${v}`);
+  };
+  add(AGENT_TRAILER, input.agent);
+  add(LEASE_TRAILER, input.lease);
+  add(RUN_TRAILER, input.run);
+  for (const r of input.records ?? []) {
+    const ref = typeof r === "string" ? parseRecordRef(r) : r;
+    if (!ref || !KIND_NAME.test(ref.kind) || !RECORD_ID.test(ref.id)) throw new Error(`${RECORD_TRAILER} takes <kind>:<id>, not ${JSON.stringify(r)}`);
+    add(RECORD_TRAILER, `${ref.kind}:${ref.id}`);
+  }
+  if (input.applied) {
+    add(APPLIED_BY_TRAILER, input.applied.by);
+    add(APPLIED_AT_TRAILER, input.applied.at);
+    if (input.applied.commit !== undefined && !COMMIT_ID.test(input.applied.commit)) throw new Error(`${APPLIED_COMMIT_TRAILER} takes a full commit id, not ${JSON.stringify(input.applied.commit)}`);
+    add(APPLIED_COMMIT_TRAILER, input.applied.commit);
+  }
+  return lines;
+}

package/src/workspace/trust/seal.ts

@@ -36,6 +36,12 @@ export const REVIEW_SEAL_NAMESPACE = "chant-review";
 /** The ssh signature namespace of a record's author seal (#2688). */
 export const RECORD_SEAL_NAMESPACE = "chant-record";
 
+/**
+ * The ssh signature namespace of a gate approval's seal (#3163, ws-080), so a
+ * verdict, record or commit signature can't stand in for one.
+ */
+export const GATE_SEAL_NAMESPACE = "chant-gate";
+
 /** A seal as a review entry holds it. */
 export interface VerdictSeal {
   /** The principal who signed: the reviewer, as the signers file names them. */
@@ -81,6 +87,27 @@ export function recordSealPayload(record: string, digest: string, author: string
   return Buffer.from(`${record}\n${digest}\n${author}\n${state ?? ""}`, "utf-8");
 }
 
+/** The gate approval a seal covers (#3163): the fields of a gate resolution line that say what was approved, by whom and when. */
+export interface SealedGateApproval {
+  op: string;
+  gate: string;
+  environment?: string;
+  planDigest?: string;
+  resolvedBy: string;
+  timestamp: string;
+  seal?: unknown;
+}
+
+/**
+ * The bytes a gate approval's seal signs (#3163): the op (or component), the
+ * gate, the environment, the plan digest, the approver and the time, joined
+ * by LF with no final newline. An approval that binds no environment or plan
+ * signs an empty line for it.
+ */
+export function gateSealPayload(a: SealedGateApproval): Buffer {
+  return Buffer.from(`${a.op}\n${a.gate}\n${a.environment ?? ""}\n${a.planDigest ?? ""}\n${a.resolvedBy}\n${a.timestamp}`, "utf-8");
+}
+
 /** The record an author seal covers (#2688). */
 export interface SealedRecord {
   record: string | null;
@@ -155,6 +182,22 @@ export function checkRecordSeal(policy: TrustPolicy, r: SealedRecord): SealCheck
   });
 }
 
+/**
+ * Check a gate approval's seal (#3163), as a verdict's is checked, over
+ * {@link gateSealPayload} in the `chant-gate` namespace: it verifies only
+ * when the signers file at base lists a key for the approver.
+ */
+export function checkGateSeal(policy: TrustPolicy, a: SealedGateApproval): SealCheck {
+  return checkSeal(policy, {
+    principal: a.resolvedBy,
+    what: `the approval of gate ${a.gate} by ${a.resolvedBy}`,
+    role: "approver",
+    namespace: GATE_SEAL_NAMESPACE,
+    seal: a.seal,
+    payload: gateSealPayload(a),
+  });
+}
+
 function checkSeal(policy: TrustPolicy, s: SealSubject): SealCheck {
   const where = `${policy.signersPath} at base`;
   if (s.seal === undefined || s.seal === null) {
@@ -205,7 +248,7 @@ function checkIntegrity(principal: string, payload: Buffer, signature: string, n
     const r = sshKeygen(["-Y", "check-novalidate", "-n", namespace, "-s", sigFile], payload);
     if (r.missing) return { attested: null, code: "seal-unverifiable", message: `the seal by ${principal} can't be checked here: ssh-keygen is not installed` };
     if (r.status !== 0) {
-      return { attested: false, code: "seal-signature-invalid", message: `the seal by ${principal} does not verify over ${namespace === RECORD_SEAL_NAMESPACE ? "this record" : "this verdict"}, even without a signers file` };
+      return { attested: false, code: "seal-signature-invalid", message: `the seal by ${principal} does not verify over ${namespace === RECORD_SEAL_NAMESPACE ? "this record" : namespace === GATE_SEAL_NAMESPACE ? "this approval" : "this verdict"}, even without a signers file` };
     }
     const key = FINGERPRINT.exec(r.stdout + r.stderr)?.[1];
     return {
@@ -279,6 +322,14 @@ export function sealRecord(keyFile: string, r: { record: string; digest: string;
   return sign(keyFile, recordSealPayload(r.record, r.digest, r.author, r.state), RECORD_SEAL_NAMESPACE, r.author);
 }
 
+/**
+ * Seal a gate approval (#3163) with the key in `keyFile`, over
+ * {@link gateSealPayload}. Throws a {@link SealError}.
+ */
+export function sealGateApproval(keyFile: string, a: SealedGateApproval): VerdictSeal {
+  return sign(keyFile, gateSealPayload(a), GATE_SEAL_NAMESPACE, a.resolvedBy);
+}
+
 function sign(keyFile: string, payload: Buffer, namespace: string, signer: string): VerdictSeal {
   const signed = sshKeygen(["-q", "-Y", "sign", "-n", namespace, "-f", keyFile], payload);
   if (signed.missing) throw new SealError("--sign needs ssh-keygen, and it is not installed here");

package/src/workspace/work-cli.e2e.test.ts

@@ -158,12 +158,39 @@ describe("chant workspace work (#2732)", () => {
     expect(json(closed).error.code).toBe("work-item-closed");
     const verb = await chant(root, ["workspace", "work", "grab", "W-001", "--holder", "a"]);
     expect(verb.code).toBe(1);
-    expect(verb.stderr).toContain("claim, renew, release or history");
+    expect(verb.stderr).toContain("claim, renew, release, history or evidence");
     const noHolder = await chant(root, ["workspace", "work", "claim", "W-001"]);
     expect(noHolder.code).toBe(1);
     expect(noHolder.stderr).toContain("--holder");
   }, 120_000);
 
+  test("evidence (#3159): needs the holder, the token and the entry, runs only under the live lease, and names only a criterion the item lists", async () => {
+    const entry = JSON.stringify({ criterion: "AC-1", result: "pass", title: "The test", url: "https://example.com/ci/1" });
+    const usage = await chant(root, ["workspace", "work", "evidence", "W-002", "--holder", "a", "--from", "-"]);
+    expect(usage.code).toBe(1);
+    expect(JSON.parse(usage.stdout).error).toMatchObject({ code: "write-usage-invalid", message: expect.stringContaining("--token") });
+    const evidence = (holder: string, token: string) =>
+      new Promise<Run>((resolve) => {
+        const child = spawn(CHANT[0], [...CHANT.slice(1), "workspace", "work", "evidence", "W-002", "--holder", holder, "--token", token, "--from", "-"], { cwd: root, env: { ...process.env, NO_COLOR: "1" } });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += d));
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("close", (code) => resolve({ code, stdout, stderr }));
+        child.stdin.end(entry);
+      });
+    // worker-d holds W-002 since the records test above: anyone else is refused.
+    const held = json(await chant(root, ["workspace", "work", "claim", "W-002", "--holder", "ev", "--json"])).refused.heldBy as { holder: string; token: string };
+    const other = await evidence("ev", "none");
+    expect(other.code).toBe(1);
+    expect(JSON.parse(other.stdout).error.code).toBe("lease-held");
+    const stale = await evidence(held.holder, "not-the-token");
+    expect(JSON.parse(stale.stdout).error.code).toBe("lease-token-mismatch");
+    const unlisted = await evidence(held.holder, held.token);
+    expect(unlisted.code).toBe(1);
+    expect(JSON.parse(unlisted.stdout).error.code).toBe("work-criterion-unknown");
+  }, 120_000);
+
   test("the lease fields reach an MCP client through workspace-records and workspace-status", async () => {
     const claim = await chant(root, ["workspace", "work", "claim", "W-001", "--holder", "mcp-worker", "--json"]);
     expect(claim.code, claim.stderr).toBe(0);