@intentius/chant 0.102.0 → 0.104.0

package/src/workspace/symbols.ts

@@ -7,7 +7,10 @@
  * walk follows those lines through history as it follows any line range
  * (`git log -L`). Resolvers are chosen by file extension. Core ships one for
  * TypeScript and JavaScript, parsed with the TypeScript compiler chant already
- * depends on; a file with no resolver is refused with
+ * depends on. A lexicon can contribute more through its plugin's
+ * `symbolResolvers()` (#3313), which the intent walk loads for a file in a
+ * member that configures the lexicon (`lexicon-symbols.ts`); core's resolver
+ * stays the one for `.ts` and `.js`. A file with no resolver is refused with
  * `intent-symbol-unsupported`, and a line range still works for it.
  *
  * A symbol is a name, or a dotted path through classes, namespaces,
@@ -143,17 +146,25 @@ const typescriptResolver: SymbolResolver = {
 /** The resolvers core ships, chosen by the file's extension. */
 export const SYMBOL_RESOLVERS: readonly SymbolResolver[] = [typescriptResolver];
 
-/** The resolver for a path, or undefined when none reads its language. */
-export function symbolResolverFor(path: string): SymbolResolver | undefined {
+/**
+ * The resolver for a path, or undefined when none reads its language. Core's
+ * resolvers come first, so a lexicon's never takes `.ts` or `.js` from them;
+ * among `extra`, the first that names the extension wins.
+ */
+export function symbolResolverFor(path: string, extra: readonly SymbolResolver[] = []): SymbolResolver | undefined {
   const lower = path.toLowerCase();
-  return SYMBOL_RESOLVERS.find((r) => r.extensions.some((e) => lower.endsWith(e)));
+  return [...SYMBOL_RESOLVERS, ...extra].find((r) => r.extensions.some((e) => lower.endsWith(e.toLowerCase())));
 }
 
-/** Resolve `symbol` in the file `path` holding `text`: its current lines, or why it can't be. */
-export function resolveSymbol(path: string, text: string, symbol: string): SymbolResolution {
-  const resolver = symbolResolverFor(path);
+/**
+ * Resolve `symbol` in the file `path` holding `text`: its current lines, or
+ * why it can't be. `extra` are the resolvers a lexicon contributed for the
+ * file's member (#3313).
+ */
+export function resolveSymbol(path: string, text: string, symbol: string, extra: readonly SymbolResolver[] = []): SymbolResolution {
+  const resolver = symbolResolverFor(path, extra);
   if (!resolver) {
-    const known = SYMBOL_RESOLVERS.flatMap((r) => r.extensions).join(", ");
+    const known = [...new Set([...SYMBOL_RESOLVERS, ...extra].flatMap((r) => r.extensions))].join(", ");
     return { ok: false, reason: "unsupported", message: `${path} has no symbol resolver: symbols resolve in ${known} files. Give a line range, ${path}:<start>-<end>, instead`, candidates: [] };
   }
   const all = resolver.declarations(path, text);
@@ -165,7 +176,7 @@ export function resolveSymbol(path: string, text: string, symbol: string): Symbo
     return { ok: true, declaration: { qualified: symbol, kind: exact[0].kind, lines: { start, end } } };
   }
   const nested = [...new Set(all.filter((d) => d.qualified.endsWith(`.${symbol}`)).map((d) => d.qualified))];
-  if (nested.length === 1) return resolveSymbol(path, text, nested[0]);
+  if (nested.length === 1) return resolveSymbol(path, text, nested[0], extra);
   if (nested.length > 1) {
     return { ok: false, reason: "ambiguous", message: `${symbol} names ${nested.length} declarations in ${path}: ${nested.join(", ")}. Give the qualified name`, candidates: nested };
   }

package/src/workspace/trust/run-commits.ts

@@ -0,0 +1,115 @@
+/**
+ * Which commits of a change agent runs made, and which of those a signed run
+ * statement covers (#3192), for `chant workspace verify`.
+ *
+ * A commit names its run by the `Chant-Run` trailer (ws-075), or a run's end
+ * lists it (ws-076). A run statement verified against the runner keys at
+ * base names the commits it covers as its subjects. Every `_agent-runs`
+ * directory on `chant/lifecycle` is read, the flat one and each member's,
+ * from the local branch or, when there is none, from `origin`'s copy. Nothing
+ * is fetched: CI fetches `chant/lifecycle` before it verifies.
+ */
+
+import { execFileSync } from "node:child_process";
+import { AGENT_RUNS_DIR, LEDGER_BRANCH, foldRun, parseRunFile, readRunFiles, type RunView } from "../runs";
+import { RUN_TRAILER } from "../trailers";
+import type { RunnerKey } from "./policy";
+import { attestRun } from "./run-statement";
+
+function git(repo: string, args: string[]): string | undefined {
+  try {
+    return execFileSync("git", args, { cwd: repo, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+  } catch {
+    return undefined;
+  }
+}
+
+/** Every run on the ledger, in every member's `_agent-runs`, and the ref and tip read. */
+export function readLedgerRuns(repo: string): { ref: string | null; tip: string | null; runs: RunView[] } {
+  for (const ref of [`refs/heads/${LEDGER_BRANCH}`, `refs/remotes/origin/${LEDGER_BRANCH}`]) {
+    const tip = git(repo, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`])?.trim();
+    if (!tip) continue;
+    const dirs = new Set<string>();
+    for (const path of (git(repo, ["ls-tree", "-r", "--name-only", tip]) ?? "").split("\n")) {
+      const at = path.lastIndexOf(`${AGENT_RUNS_DIR}/`);
+      if (at >= 0 && (at === 0 || path[at - 1] === "/") && path.endsWith(".jsonl")) dirs.add(path.slice(0, at + AGENT_RUNS_DIR.length));
+    }
+    const runs: RunView[] = [];
+    for (const dir of dirs) {
+      for (const [id, f] of readRunFiles(repo, dir, ref).files) {
+        const view = foldRun(id, f.path, parseRunFile(f.content, id).lines);
+        if (view) runs.push(view);
+      }
+    }
+    return { ref, tip, runs };
+  }
+  return { ref: null, tip: null, runs: [] };
+}
+
+/** One commit of a change that an agent run made, and whether a signed statement covers it. */
+export interface RunCommitVerdict {
+  commit: string;
+  /** The runs that name the commit: by its `Chant-Run` trailer, or by their end's list. */
+  runs: string[];
+  /** Whether a statement verified against the runner keys at base names the commit. */
+  attested: boolean;
+  /** The run whose statement covers it, when attested. */
+  run?: string;
+  signer?: string;
+  class?: RunnerKey["class"];
+  reason: string;
+}
+
+export interface ChangeRuns {
+  /** The ledger ref read, or null when there is no `chant/lifecycle` here. */
+  ledger: string | null;
+  /** The runner and steward principals at base. */
+  runners: string[];
+  /** The change's commits that a run names or a statement covers, oldest first. */
+  commits: RunCommitVerdict[];
+}
+
+/**
+ * Judge `commits` (the change, oldest first) against the run ledger: which
+ * ones runs made, and which of those a verified statement covers.
+ */
+export function changeRuns(repo: string, commits: string[], runners: readonly RunnerKey[]): ChangeRuns {
+  const { ref, runs } = readLedgerRuns(repo);
+  const out: ChangeRuns = { ledger: ref, runners: runners.map((r) => r.principal), commits: [] };
+  if (commits.length === 0) return out;
+  const inChange = new Set(commits);
+  const naming = new Map<string, Set<string>>();
+  const name = (sha: string, id: string) => (naming.get(sha) ?? naming.set(sha, new Set()).get(sha)!).add(id);
+  // Trailers on the change's own commits.
+  const log = git(repo, ["log", "--no-walk=unsorted", `--format=%x00%H%x1f%(trailers:key=${RUN_TRAILER},valueonly,separator=%x1e)`, ...commits]) ?? "";
+  for (const rec of log.split("\0")) {
+    if (!rec.trim()) continue;
+    const [sha, values] = rec.split("\x1f");
+    for (const v of (values ?? "").split("\x1e").map((x) => x.trim()).filter(Boolean)) name(sha.trim(), v);
+  }
+  const covered = new Map<string, { run: string; signer: string; class: RunnerKey["class"] }>();
+  for (const run of runs) {
+    for (const c of run.commits) if (inChange.has(c.sha)) name(c.sha, run.id);
+    const a = attestRun(run, runners);
+    if (a.status !== "signed") continue;
+    for (const sha of a.commits) if (inChange.has(sha) && !covered.has(sha)) covered.set(sha, { run: run.id, signer: a.signer!, class: a.class! });
+  }
+  const byId = new Map(runs.map((r) => [r.id, r]));
+  for (const commit of commits) {
+    const ids = [...(naming.get(commit) ?? [])].sort();
+    const cover = covered.get(commit);
+    if (ids.length === 0 && !cover) continue;
+    if (cover) {
+      out.commits.push({ commit, runs: ids, attested: true, run: cover.run, signer: cover.signer, class: cover.class, reason: `agent run ${cover.run}'s statement, signed by ${cover.signer} (${cover.class}), names this commit` });
+      continue;
+    }
+    const why = ids.map((id) => {
+      const r = byId.get(id);
+      if (!r) return `${id} is not in the run ledger${ref ? "" : " (there is no chant/lifecycle branch here; fetch it)"}`;
+      const a = attestRun(r, runners);
+      return a.status === "signed" ? `${id}'s statement, signed by ${a.signer}, does not name this commit` : `${id}: ${a.reason}`;
+    });
+    out.commits.push({ commit, runs: ids, attested: false, reason: why.join("; ") });
+  }
+  return out;
+}

package/src/workspace/trust/run-statement.ts

@@ -0,0 +1,226 @@
+/**
+ * The agent-run statement (#3192, ws-090): a runner's or steward's signed
+ * word that an agent run happened as its record says.
+ *
+ * The run record (#3033, ws-076) is written by whatever ran the agent, so on
+ * its own it is as trustworthy as that writer. A statement is an in-toto
+ * Statement v1 in a DSSE envelope (./dsse.ts), signed with an Ed25519 key the
+ * trust policy at base lists under `runners` in `.chant/trust.json`, the same
+ * keys runner evidence uses (#2553, ws-069). A person's key, one the signers
+ * file lists, is never a runner key.
+ *
+ * - `subject`: each commit the run made, by its id (`digest.gitCommit`), with
+ *   its `git patch-id --stable` as an annotation when it has a patch.
+ * - `predicate`: the signer's principal, the run's id and the SHA-256 of its
+ *   record (the start and end lines), the work item, the harness, the model
+ *   and provider, and the principal the run worked for (studio-036 b).
+ *
+ * The statement is stored as a run-ledger fact: a `statement` line in the
+ * run's own file on `chant/lifecycle`, after its end. Verifying needs only
+ * the envelope, the run's record and the runner keys at base, so it works
+ * offline, and a verifier re-checks every stored statement rather than
+ * trusting that it was checked when written.
+ */
+
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { canonicalJson } from "../../effect-receipt";
+import type { ReasonCode } from "../reason-codes";
+import type { RunEndLine, RunStartLine, RunView } from "../runs";
+import { IN_TOTO_PAYLOAD_TYPE, signEnvelope, verifyEnvelope, type DsseEnvelope } from "./dsse";
+import { STATEMENT_TYPE } from "./evidence";
+import type { KeyObject } from "node:crypto";
+import type { RunnerKey } from "./policy";
+
+export const AGENT_RUN_PREDICATE = "https://intentius.io/chant/agent-run/v1";
+
+const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
+const fullCommit = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/);
+const patchId = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/);
+const text = z.string().min(1);
+
+/** The statement a runner signs for a run. Strict, so a verifier never acts on a field it does not know. */
+export const runStatementSchema = z
+  .object({
+    _type: z.literal(STATEMENT_TYPE),
+    subject: z.array(
+      z
+        .object({
+          name: fullCommit,
+          digest: z.object({ gitCommit: fullCommit }).strict(),
+          annotations: z.object({ patchId }).strict().optional(),
+        })
+        .strict()
+        .refine((s) => s.name === s.digest.gitCommit, "a commit subject is named by its own id"),
+    ),
+    predicateType: z.literal(AGENT_RUN_PREDICATE),
+    predicate: z
+      .object({
+        signer: text,
+        run: z.object({ id: text, record: z.object({ sha256: sha256Hex }).strict() }).strict(),
+        unit: z.object({ id: text, kind: text.nullable() }).strict().nullable(),
+        harness: z.object({ name: text, version: text.nullable() }).strict(),
+        model: text.nullable(),
+        provider: text.nullable(),
+        by: text.nullable(),
+      })
+      .strict(),
+  })
+  .strict();
+export type RunStatement = z.infer<typeof runStatementSchema>;
+
+/**
+ * The SHA-256 of a run's record: the canonical JSON (keys sorted, no
+ * whitespace) of the array `[start line, end line]` as the ledger holds them.
+ * Statement lines are not part of it, so storing a statement never changes
+ * the hash it signs.
+ */
+export function runRecordDigest(start: RunStartLine, end: RunEndLine): string {
+  return createHash("sha256").update(canonicalJson([start, end]), "utf8").digest("hex");
+}
+
+/** The statement for an ended run, as `signer` would sign it. The run's commits are its subjects, sorted by id. */
+export function buildRunStatement(run: RunView, signer: string): RunStatement {
+  if (!run.record) throw new Error(`agent run ${run.id} has not ended, so it has no record to sign`);
+  const commits = [...new Map(run.commits.map((c) => [c.sha, c])).values()].sort((a, b) => (a.sha < b.sha ? -1 : a.sha > b.sha ? 1 : 0));
+  return {
+    _type: STATEMENT_TYPE,
+    subject: commits.map((c) => ({ name: c.sha, digest: { gitCommit: c.sha }, ...(c.patchId ? { annotations: { patchId: c.patchId } } : {}) })),
+    predicateType: AGENT_RUN_PREDICATE,
+    predicate: {
+      signer,
+      run: { id: run.id, record: { sha256: run.record.sha256 } },
+      unit: run.unit ? { id: run.unit.id, kind: run.unit.kind } : null,
+      harness: { name: run.harness.name, version: run.harness.version },
+      model: run.model,
+      provider: run.provider,
+      by: run.by,
+    },
+  };
+}
+
+/** The payload bytes a signer signs: the statement's canonical JSON. Any serialization verifies; this one is reproducible. */
+export function runStatementPayload(statement: RunStatement): Buffer {
+  return Buffer.from(canonicalJson(statement), "utf8");
+}
+
+export function signRunStatement(statement: RunStatement, key: KeyObject, publicKey: string): DsseEnvelope {
+  return signEnvelope(IN_TOTO_PAYLOAD_TYPE, runStatementPayload(statement), key, publicKey);
+}
+
+// ── Verifying ────────────────────────────────────────────────────────────────
+
+/**
+ * Why a stored statement does not verify. Each is in `reason-codes.ts`.
+ * `envelope-invalid` and `envelope-untrusted` are runner evidence's codes:
+ * the envelope is the same, and so is the rule for its keys.
+ */
+export const RUN_STATEMENT_FAILURE_CODES = ["envelope-invalid", "envelope-untrusted", "run-statement-invalid", "run-statement-signer-mismatch", "run-statement-mismatch"] as const satisfies readonly ReasonCode[];
+export type RunStatementFailureCode = (typeof RUN_STATEMENT_FAILURE_CODES)[number];
+
+/** One stored statement, judged against the runner keys at base and the run's record. */
+export type RunStatementVerdict =
+  | { status: "verified"; signer: string; class: RunnerKey["class"]; keyid: string; statement: RunStatement; reason: string }
+  | {
+      status: "mismatch" | "untrusted" | "invalid";
+      code: RunStatementFailureCode;
+      reason: string;
+      /** Set when a listed runner key signed it, so the failure is in what it says. */
+      signer?: string;
+      class?: RunnerKey["class"];
+      keyid?: string;
+    };
+
+const same = (a: unknown, b: unknown) => canonicalJson(a ?? null) === canonicalJson(b ?? null);
+
+/**
+ * Verify one envelope for `run`: a signature by a runner key at base, a
+ * well-formed statement whose signer is that key's principal, for this run,
+ * and agreeing with its record. Never throws.
+ */
+export function verifyRunStatement(envelope: unknown, runners: readonly RunnerKey[], run: RunView): RunStatementVerdict {
+  const v = verifyEnvelope(envelope, runners);
+  if (!v.ok) return { status: v.code === "envelope-untrusted" ? "untrusted" : "invalid", code: v.code, reason: v.reason };
+  const runner = runners.find((r) => r.principal === v.principal)!;
+  const signed = { signer: v.principal, class: runner.class, keyid: v.keyid };
+  if (v.payloadType !== IN_TOTO_PAYLOAD_TYPE) {
+    return { status: "invalid", code: "run-statement-invalid", reason: `payload type ${v.payloadType} is not ${IN_TOTO_PAYLOAD_TYPE}`, ...signed };
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(v.payload.toString("utf8"));
+  } catch {
+    return { status: "invalid", code: "run-statement-invalid", reason: "the payload is not JSON", ...signed };
+  }
+  const parsed = runStatementSchema.safeParse(raw);
+  if (!parsed.success) {
+    const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "/"}: ${i.message}`).join("; ");
+    return { status: "invalid", code: "run-statement-invalid", reason: `the payload is not a ${AGENT_RUN_PREDICATE} statement: ${detail}`, ...signed };
+  }
+  const statement = parsed.data;
+  const p = statement.predicate;
+  // A runner cannot speak for another: the principal inside is the one whose key signed.
+  if (p.signer !== v.principal) {
+    return { status: "invalid", code: "run-statement-signer-mismatch", reason: `the statement names signer ${JSON.stringify(p.signer)}, but ${v.principal}'s key signed it`, ...signed };
+  }
+  const differs: string[] = [];
+  if (p.run.id !== run.id) differs.push(`it is for run ${p.run.id}`);
+  else if (!run.record) differs.push("the run has no end in the ledger");
+  else if (p.run.record.sha256 !== run.record.sha256) differs.push(`the record hashed ${p.run.record.sha256.slice(0, 12)} when signed and ${run.record.sha256.slice(0, 12)} now`);
+  if (!same(p.unit, run.unit)) differs.push(`unit ${JSON.stringify(p.unit?.id ?? null)}, the record says ${JSON.stringify(run.unit?.id ?? null)}`);
+  if (!same(p.harness, run.harness)) differs.push(`harness ${JSON.stringify(p.harness.name)}, the record says ${JSON.stringify(run.harness.name)}`);
+  if (p.model !== run.model) differs.push(`model ${JSON.stringify(p.model)}, the record says ${JSON.stringify(run.model)}`);
+  if (p.provider !== run.provider) differs.push(`provider ${JSON.stringify(p.provider)}, the record says ${JSON.stringify(run.provider)}`);
+  if (p.by !== run.by) differs.push(`by ${JSON.stringify(p.by)}, the record says ${JSON.stringify(run.by)}`);
+  if (differs.length > 0) {
+    return { status: "mismatch", code: "run-statement-mismatch", reason: `signed by ${v.principal}, but the statement does not match run ${run.id}'s record: ${differs.join("; ")}`, ...signed };
+  }
+  const n = statement.subject.length;
+  return { status: "verified", ...signed, statement, reason: `signed by ${v.principal} (${runner.class}) over the run's record and ${n} commit${n === 1 ? "" : "s"}` };
+}
+
+/** A run's attestation: its best statement, or why it has none. */
+export interface RunAttestation {
+  /**
+   * `signed`: a statement verifies. `unsigned`: the ledger holds none.
+   * Otherwise the best failure among the stored statements, `mismatch`
+   * before `untrusted` before `invalid`.
+   */
+  status: "signed" | "unsigned" | "mismatch" | "untrusted" | "invalid";
+  signer: string | null;
+  class: RunnerKey["class"] | null;
+  keyid: string | null;
+  /** The code of the failure `status` reports, or null when signed or unsigned. */
+  code: RunStatementFailureCode | null;
+  reason: string;
+  /** The commits the verified statement names, sorted. Empty unless signed. */
+  commits: string[];
+  /** One verdict per stored statement, in ledger order. */
+  statements: RunStatementVerdict[];
+}
+
+const RANK = { mismatch: 0, untrusted: 1, invalid: 2 } as const;
+
+/** Judge every statement the ledger holds for `run`. */
+export function attestRun(run: RunView, runners: readonly RunnerKey[]): RunAttestation {
+  const verdicts = run.statements.map((s) => verifyRunStatement(s.envelope, runners, run));
+  const good = verdicts.find((v): v is Extract<RunStatementVerdict, { status: "verified" }> => v.status === "verified");
+  if (good) {
+    return { status: "signed", signer: good.signer, class: good.class, keyid: good.keyid, code: null, reason: good.reason, commits: good.statement.subject.map((s) => s.name), statements: verdicts };
+  }
+  if (verdicts.length === 0) {
+    const reason = run.state === "running" ? "the run has not ended, and a statement is signed over an ended run" : "the ledger holds no statement for this run";
+    return { status: "unsigned", signer: null, class: null, keyid: null, code: null, reason, commits: [], statements: verdicts };
+  }
+  const worst = [...verdicts].sort((a, b) => RANK[a.status as keyof typeof RANK] - RANK[b.status as keyof typeof RANK])[0] as Exclude<RunStatementVerdict, { status: "verified" }>;
+  return {
+    status: worst.status,
+    signer: worst.signer ?? null,
+    class: worst.class ?? null,
+    keyid: worst.keyid ?? null,
+    code: worst.code,
+    reason: worst.reason,
+    commits: [],
+    statements: verdicts,
+  };
+}

package/src/workspace/trust/seal.ts

@@ -94,6 +94,8 @@ export interface SealedGateApproval {
   environment?: string;
   planDigest?: string;
   resolvedBy: string;
+  /** Who relayed the approval for `resolvedBy` (#3402), when someone did. */
+  relayedBy?: string;
   timestamp: string;
   seal?: unknown;
 }
@@ -102,10 +104,14 @@ export interface SealedGateApproval {
  * 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.
+ * signs an empty line for it. A relayed approval (#3402) signs a seventh line,
+ * `relayed-by <principal>`, so the relay can't be added, changed or removed
+ * after sealing; an approval nobody relayed signs the six lines it always did,
+ * so seals made before #3402 still verify.
  */
 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");
+  const relay = a.relayedBy !== undefined ? `\nrelayed-by ${a.relayedBy}` : "";
+  return Buffer.from(`${a.op}\n${a.gate}\n${a.environment ?? ""}\n${a.planDigest ?? ""}\n${a.resolvedBy}\n${a.timestamp}${relay}`, "utf-8");
 }
 
 /** The record an author seal covers (#2688). */

package/src/workspace/trust/verify-cli.ts

@@ -1,5 +1,5 @@
 /**
- * `chant workspace verify [--base <rev>] [--head <rev>] [--require attested] [--json]`
+ * `chant workspace verify [--base <rev>] [--head <rev>] [--require attested | attested-runs] [--json]`
  * (#2547): check a change against the trust policy at its base. See ./verify.ts.
  *
  * Exit 0 when the change passes, 1 when it does not or cannot be checked.
@@ -11,12 +11,12 @@ import { gitRoot } from "../record-source";
 import { activeAttestors } from "./attestor";
 import { verifyChange, type ChangeReport } from "./verify";
 
-const USAGE = "chant workspace verify [--base <rev>] [--head <rev>] [--require attested] [--json]";
+const USAGE = "chant workspace verify [--base <rev>] [--head <rev>] [--require attested | attested-runs] [--json]";
 
 export async function runWorkspaceVerify(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
-  if (args.require !== undefined && args.require !== "attested") {
-    console.error(formatError({ message: `--require takes one level, attested, not ${JSON.stringify(args.require)}`, hint: USAGE }));
+  if (args.require !== undefined && args.require !== "attested" && args.require !== "attested-runs") {
+    console.error(formatError({ message: `--require takes attested or attested-runs, not ${JSON.stringify(args.require)}`, hint: USAGE }));
     return 1;
   }
   const repo = gitRoot(process.cwd());
@@ -28,7 +28,7 @@ export async function runWorkspaceVerify(ctx: CommandContext): Promise<number> {
     repo,
     base: args.base,
     head: args.head,
-    require: args.require === "attested" ? "attested" : undefined,
+    require: args.require === "attested" || args.require === "attested-runs" ? args.require : undefined,
     attestors: await activeAttestors(),
   });
   if (args.json) console.log(JSON.stringify(report, null, 2));
@@ -48,6 +48,7 @@ function printReport(r: ChangeReport): void {
     const note = c.skipped ? ` (${c.skipped})` : c.level === "attested" ? "" : ` (${c.reason})`;
     lines.push(`  ${c.commit.slice(0, 8)}  ${c.level}${who}  ${c.subject}${note}`);
   }
+  for (const c of r.runs.commits) lines.push(`  ${c.commit.slice(0, 8)}  agent run ${c.runs.join(", ") || c.run}: ${c.attested ? "attested" : "not attested"}, ${c.reason}`);
   for (const w of r.protectedWrites) lines.push(`  protected write ${w.commit.slice(0, 8)} ${w.paths.join(", ")}: ${w.allowed ? "allowed" : "refused"}, ${w.reason}`);
   if (r.rotation && "to" in r.rotation) lines.push(`  signer set: version ${r.rotation.from} to ${r.rotation.to}, signed by ${r.rotation.signedBy.join(", ")}`);
   for (const n of r.notes) lines.push(n);

package/src/workspace/trust/verify.ts

@@ -10,6 +10,15 @@
  *
  * Attestation is opt-in (#2525 rule 6). Without a signers file at base the
  * check passes and says so, unless `--require attested` asks for more.
+ *
+ * Agent runs (#3192): a commit an agent run made, by its `Chant-Run` trailer
+ * or its run's end, is attested by a run statement that a runner or steward
+ * key at base signed and that names the commit. Such a commit counts as
+ * `attested` with the attestor `agent-run`, so `--require attested` tells a
+ * person's signed commit from a run's attested one by the attestor.
+ * `--require attested-runs` asks only that every commit a run made be
+ * covered, and needs runner keys at base but no signers file. Without
+ * `--require`, `runs` reports and nothing fails (studio-035 d).
  */
 
 import { execFileSync } from "node:child_process";
@@ -17,6 +26,10 @@ import { type CommitAttestor, type ProvenanceLevel } from "./attestor";
 import { policyAtBase, commitProvenance, resolveBase, type BaseSource, type RecordProvenance } from "./provenance";
 import { policyWriters, protectedPaths, type ExcludedSigner, type TrustPolicy } from "./policy";
 import { fileAt, nextVersion, rotationPath, signerHistory, type RotationRefusalCode } from "./rotation";
+import { changeRuns, type ChangeRuns } from "./run-commits";
+
+/** What `--require` takes: a provenance level, or `attested-runs` (#3192). */
+export type VerifyRequirement = ProvenanceLevel | "attested-runs";
 
 export interface CommitVerdict extends RecordProvenance {
   commit: string;
@@ -46,8 +59,10 @@ export interface ChangeReport {
     writers: string[];
     problems: string[];
   };
-  require: ProvenanceLevel | null;
+  require: VerifyRequirement | null;
   commits: CommitVerdict[];
+  /** The change's commits that agent runs made, and which a signed run statement covers (#3192). */
+  runs: ChangeRuns;
   protectedPaths: string[];
   /** Protected paths whose content differs between the merge base and head. */
   protectedChanged: string[];
@@ -67,7 +82,7 @@ export interface VerifyOptions {
   repo: string;
   base?: string;
   head?: string;
-  require?: ProvenanceLevel;
+  require?: VerifyRequirement;
   attestors: readonly CommitAttestor[];
 }
 
@@ -115,6 +130,7 @@ export function verifyChange(opts: VerifyOptions): ChangeReport {
     },
     require: opts.require ?? null,
     commits: [],
+    runs: { ledger: null, runners: [], commits: [] },
     protectedPaths: protectedPaths(policy),
     protectedChanged: [],
     protectedWrites: [],
@@ -139,6 +155,20 @@ export function verifyChange(opts: VerifyOptions): ChangeReport {
     return report;
   }
 
+  // Every commit in the change, oldest first, with its parents.
+  const listing = git(repo, ["rev-list", "--reverse", "--parents", `${base.commit}..${head}`]).split("\n").filter(Boolean);
+  const parentsOf = new Map(listing.map((l) => { const [c, ...p] = l.split(" "); return [c, p.length] as const; }));
+  report.runs = changeRuns(repo, [...parentsOf.keys()], policy.runners);
+  if (opts.require === "attested-runs") {
+    if (policy.runners.length === 0 && report.runs.commits.length > 0) {
+      report.notes.push(`.chant/trust.json at base lists no runner keys, so no run statement can verify`);
+    }
+    for (const r of report.runs.commits) {
+      if (r.attested || r.runs.length === 0 || mergeWithoutOwnChanges(repo, r.commit, parentsOf.get(r.commit) ?? 0)) continue;
+      report.failures.push(`${r.commit.slice(0, 8)} was made by agent run ${r.runs.join(", ")}, and --require attested-runs was given: ${r.reason}`);
+    }
+  }
+
   const mergeBase = git(repo, ["merge-base", base.commit, head]).trim();
   const changedPaths = git(repo, ["--literal-pathspecs", "diff", "--name-only", "--no-renames", mergeBase, head, "--", ...report.protectedPaths])
     .split("\n")
@@ -150,18 +180,21 @@ export function verifyChange(opts: VerifyOptions): ChangeReport {
     if (changedPaths.includes(policy.signersPath)) {
       report.notes.push(`this change adds ${policy.signersPath}; it applies to changes made after it is merged, never to this one`);
     }
-    if (opts.require) report.failures.push(`--require ${opts.require} was given, and there is no signers file at base to attest anything`);
+    if (opts.require && opts.require !== "attested-runs") report.failures.push(`--require ${opts.require} was given, and there is no signers file at base to attest anything`);
     report.ok = report.failures.length === 0;
     return report;
   }
 
   // Every commit in the change, judged by the policy at base.
-  const listing = git(repo, ["rev-list", "--reverse", "--parents", `${base.commit}..${head}`]).split("\n").filter(Boolean);
+  const runCover = new Map(report.runs.commits.filter((r) => r.attested).map((r) => [r.commit, r]));
   const verdicts = new Map<string, CommitVerdict>();
   for (const line of listing) {
     const [commit, ...parents] = line.split(" ");
     const subject = git(repo, ["log", "-1", "--format=%s", commit]).trim();
-    const p = commitProvenance(repo, policy, commit, opts.attestors);
+    let p = commitProvenance(repo, policy, commit, opts.attestors);
+    const cover = runCover.get(commit);
+    // A commit no signer attests, made by a run a runner key at base vouches for (#3192).
+    if (p.level !== "attested" && cover) p = { level: "attested", commit, attestor: "agent-run", principal: cover.signer, reason: cover.reason };
     const v: CommitVerdict = { ...p, commit, subject };
     if (p.level !== "attested" && mergeWithoutOwnChanges(repo, commit, parents.length)) {
       v.skipped = "a merge with no changes of its own; the commits it brings are checked instead";
@@ -205,7 +238,7 @@ export function verifyChange(opts: VerifyOptions): ChangeReport {
     }
   }
 
-  if (opts.require) {
+  if (opts.require && opts.require !== "attested-runs") {
     for (const v of report.commits) {
       if (v.skipped || v.level === opts.require) continue;
       report.failures.push(`${v.commit.slice(0, 8)} is ${v.level}, and --require ${opts.require} was given: ${v.reason}`);