@intentius/chant 0.101.0 → 0.102.0

package/src/workspace/records-write.ts

@@ -50,7 +50,8 @@ import { policyAtBase, resolveBase } from "./trust/provenance";
 import { WorkspaceReadError } from "./declaration";
 import { findSessionKinds, headCommit, sessionKindsFor } from "./session-kinds";
 import { workingTree } from "./tree";
-import { AGENT_ENV, refuseRecordWrite, WRITE_SCOPE_CODES, WriteScopeError } from "./write-scope";
+import { AGENT_ENV, refuseRecordWrite, WRITE_SCOPE_CODES, WriteScopeError, type ScopeSource } from "./write-scope";
+import { IDENTITY_CODES, IdentityError, refuseUnidentified } from "./identity";
 import type { WriteVerb } from "./declaration";
 
 // ── Contract ─────────────────────────────────────────────────────────────────
@@ -78,6 +79,7 @@ export const NEW_ERROR_CODES = [
   "record-state-not-initial",
   "ratify-quorum-not-met",
   ...WRITE_SCOPE_CODES,
+  ...IDENTITY_CODES,
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -93,6 +95,7 @@ export const AMEND_ERROR_CODES = [
   "record-sign-failed",
   "ratify-quorum-not-met",
   ...WRITE_SCOPE_CODES,
+  ...IDENTITY_CODES,
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -108,6 +111,7 @@ export const REVIEW_ERROR_CODES = [
   "session-unknown",
   "session-not-open",
   ...WRITE_SCOPE_CODES,
+  ...IDENTITY_CODES,
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -361,8 +365,24 @@ export async function open(kind: string, cwd: string): Promise<Opened> {
  * written with `verb`, by the session `agent` names (`CHANT_AGENT`) or the
  * principal `by` names. Throws a {@link WriteScopeError}.
  */
-export function refuseOutOfScope(o: Opened, verb: WriteVerb, cwd: string, writer: { agent?: string; by?: string }): void {
-  refuseRecordWrite(cwd, { kindName: o.loaded.kind.name, kindFile: o.loaded.file, recordsDir: o.loaded.dir, verb, agent: writer.agent, principal: writer.by });
+export function refuseOutOfScope(o: Opened, verb: WriteVerb, cwd: string, writer: { agent?: string; by?: string }): ScopeSource {
+  const source = refuseRecordWrite(cwd, { kindName: o.loaded.kind.name, kindFile: o.loaded.file, recordsDir: o.loaded.dir, verb, agent: writer.agent, principal: writer.by });
+  // #3163: under identity.attribution "identified" at base, --by names a forge identity or a signer.
+  if (writer.by !== undefined) refuseUnidentified(source, [writer.by], "--by", { agent: writer.agent });
+  return source;
+}
+
+/**
+ * Refuse author fields (the kind's reviews.decider and proposedBy fields)
+ * that name a person by a bare name, under identity.attribution
+ * "identified" at base (#3163). `flag` is where the fields came from.
+ */
+function refuseUnidentifiedAuthors(source: ScopeSource, kind: Opened["loaded"]["kind"], fields: Record<string, unknown>, flag: string, agent?: string): void {
+  const names = [kind.reviews?.decider, kind.proposedBy?.field]
+    .filter((f): f is string => f !== undefined)
+    .map((f) => fields[f])
+    .filter((v): v is string => typeof v === "string" && v.trim() !== "");
+  refuseUnidentified(source, names, `${flag} author`, { agent });
 }
 
 /**
@@ -628,7 +648,7 @@ function today(): string {
 }
 
 export function failure<C>(schema: string, err: unknown): WriteFailure<C> {
-  if (err instanceof RecordWriteError || err instanceof RecordReadError || err instanceof WriteScopeError) {
+  if (err instanceof RecordWriteError || err instanceof RecordReadError || err instanceof WriteScopeError || err instanceof IdentityError) {
     return { $schema: schema, contract: RECORDS_WRITE_CONTRACT_VERSION, error: { code: err.code as C, message: err.message } };
   }
   throw err;
@@ -773,9 +793,10 @@ export async function newRecord(opts: NewRecordOptions & ChannelOptions): Promis
       throw new RecordWriteError("write-usage-invalid", `--prefix takes letters and digits, starting with a letter, not ${JSON.stringify(opts.prefix)}`);
     }
     const o = await open(opts.kind, opts.cwd);
-    refuseOutOfScope(o, "new", opts.cwd, opts);
+    const scope = refuseOutOfScope(o, "new", opts.cwd, opts);
     const fields = applyChannel(o, parseFields(opts.fields, "--from"), opts, true, "--from");
     const { kind, schema } = o.loaded;
+    refuseUnidentifiedAuthors(scope, kind, fields, "--from", opts.agent);
     refuseSealField(o, fields, "--from");
     refuseRevisionFields(kind, fields, {}, "--from");
     const idField = kind.idField!;
@@ -858,9 +879,10 @@ export interface AmendRecordOptions {
 export async function amendRecord(opts: AmendRecordOptions & ChannelOptions): Promise<AmendDocument> {
   try {
     const o = await open(opts.kind, opts.cwd);
-    refuseOutOfScope(o, "amend", opts.cwd, opts);
+    const scope = refuseOutOfScope(o, "amend", opts.cwd, opts);
     const given = applyChannel(o, parseFields(opts.fields, "--set"), opts, false, "--set");
     const { kind } = o.loaded;
+    refuseUnidentifiedAuthors(scope, kind, given, "--set", opts.agent);
     refuseSealField(o, given, "--set");
     const before = await readAll(o, o.source);
     const target = findRecord(before, opts.id, kind.name);

package/src/workspace/records.schema.json

@@ -124,6 +124,14 @@
         },
         "error": false,
         "current": { "type": "boolean", "description": "Whether superseded records were left out (--current)." },
+        "uncommitted": {
+          "type": "boolean",
+          "description": "Added in contract 1 by #3160. Whether only the records HEAD doesn't hold were listed (--uncommitted): each record's worktree is then modified or new, checkout is present, and summary's total, valid and invalid count the records listed. Absent from documents written before #3160, which read as false."
+        },
+        "checkout": {
+          "description": "Added in contract 1 by #3160, on a read of the working tree in a git repository; absent under --at and outside git. The branch, head and base the working tree is on, and the records of the kind it has deleted.",
+          "$ref": "#/$defs/checkout"
+        },
         "trust": { "$ref": "#/$defs/trust" },
         "records": {
           "description": "One entry per file the kind locates, sorted by path.",
@@ -145,6 +153,42 @@
           "type": "array",
           "items": { "$ref": "#/$defs/decisionWork" }
         }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "uncommitted": { "const": true } }, "required": ["uncommitted"] },
+          "then": {
+            "required": ["checkout"],
+            "properties": {
+              "checkout": true,
+              "at": { "type": "null" },
+              "records": { "type": "array", "items": { "type": "object", "required": ["worktree"], "properties": { "worktree": { "enum": ["modified", "new"] } } } }
+            }
+          }
+        }
+      ]
+    },
+    "checkout": {
+      "type": "object",
+      "required": ["branch", "head", "base", "baseFrom", "deleted"],
+      "properties": {
+        "branch": { "type": ["string", "null"], "description": "The checked-out branch's short name, such as chant/work/w-12, or null when HEAD is detached." },
+        "head": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "The full commit id HEAD names, or null before the first commit (every record is then new). Each record's worktree is judged against it."
+        },
+        "base": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "The merge base of head and the target branch tip, the commit the branch forked from: what applying the branch would be measured against. The target is --base when given, else origin/HEAD, main or master, as for trust. Null without a head, a target, or common history."
+        },
+        "baseFrom": { "enum": ["flag", "origin/HEAD", "main", "master", null], "description": "Where the target branch was found; null when there is none." },
+        "deleted": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Record files of the kind that head holds and the working tree no longer has, staged or not, from the repository root with / separators, sorted. A renamed record is here under its old name and in records as new."
+        }
       }
     },
     "workLink": {
@@ -155,6 +199,17 @@
         "state": { "type": ["string", "null"], "description": "The linked record's state as it writes it, or null when no record has the id." }
       }
     },
+    "workAnswer": {
+      "type": "object",
+      "required": ["id", "point", "state", "answer", "answeredBy"],
+      "properties": {
+        "id": { "type": "string", "description": "The answer record's id: the point's name and the first 12 hex digits of its inputs hash." },
+        "point": { "type": ["string", "null"], "description": "The decision point it answers." },
+        "state": { "type": ["string", "null"], "description": "escalated, proposed or answered." },
+        "answer": { "oneOf": [{ "type": "string" }, { "type": "boolean" }, { "type": "null" }], "description": "The answer, or null while there is none." },
+        "answeredBy": { "type": "array", "items": { "type": "string" }, "description": "The people who answered or confirmed it; empty when a table or a model answered." }
+      }
+    },
     "decisionWork": {
       "type": "object",
       "required": ["id", "path", "state", "supersededBy", "implementedBy"],
@@ -199,7 +254,7 @@
           "items": { "$ref": "#/$defs/asset" }
         },
         "warnings": {
-          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, (added by #2654) an evidence list that is empty, (added by #2672) a verdict that names no digest, or (added by #2683) a work record's links and dates, or (added by #2688) a record whose author seal is not attested under a signers file at base, or (added by #2772) a work record's acceptance criteria unmet when it is done, or met by a manual verdict from its implementer. A work record never carries record-no-evidence; a done one with no evidence carries work-done-unpinned. valid and --current do not look at them.",
+          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, (added by #2654) an evidence list that is empty, (added by #2672) a verdict that names no digest, or (added by #2683) a work record's links and dates, or (added by #2688) a record whose author seal is not attested under a signers file at base, or (added by #2772) a work record's acceptance criteria unmet when it is done, or met by a manual verdict from its implementer, or (added by #3147) a work record's contract that no record has or nobody approved, or a builder tier its kind does not list. A work record never carries record-no-evidence; a done one with no evidence carries work-done-unpinned. valid and --current do not look at them.",
           "type": "array",
           "items": { "$ref": "#/$defs/warning" }
         },
@@ -243,6 +298,19 @@
           "description": "Added in contract 1 by #2772, on every parsed record of a work kind whose work block names acceptance criteria. How many of the record's criteria passing evidence meets: evidence naming the criterion, with result pass and the criterion's verification, and for a manual criterion a by other than the implementer. Null when the record lists no criteria, so a record without them reads as before.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workAcceptance" }]
         },
+        "worktree": {
+          "enum": ["committed", "modified", "new"],
+          "description": "Added in contract 1 by #3160, on every record of a read of the working tree in a git repository; absent under --at and outside git. committed when the file is as HEAD holds it, modified when it differs from HEAD, new when HEAD doesn't hold it, staged or not. modified and new are the records a person has kept and not yet committed or applied."
+        },
+        "contract": {
+          "description": "Added in contract 1 by #3147, on every parsed record of a work kind whose work block names a contract kind. The contract record the item builds, by the id in the work block's contract field, with that record's state now; state is null when no record of the contract kind has the id. Null when the item names no contract.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workLink" }]
+        },
+        "answers": {
+          "description": "Added in contract 1 by #3147, on every record with an id of a work kind whose work block names an answer kind. The decision-point answers about the item: each answer record whose constrains names the item's id, in path order, joined by id and never copied onto the item. Read at the same revision; in the working tree, with the answers a steward keeps on the lifecycle ledger laid over it. Absent when the answer kind can't be read.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/workAnswer" }
+        },
         "lease": {
           "description": "Added in contract 1 by #2732, on every record of a work kind with an id, read in the working tree (absent under --at). The item's active work lease (chant workspace work claim), or null when nobody holds one live. Read from the local lease refs, refs/chant/lease/[_members/<member>/]work/<id> and the remote's as last fetched, of the ledger owning the work kind file; records never fetches.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workLease" }]
@@ -319,6 +387,9 @@
             "work-done-gap-open",
             "work-acceptance-unmet",
             "work-acceptance-self-verified",
+            "work-contract-unknown",
+            "work-contract-undecided",
+            "work-tier-unknown",
             "answer-points-unreadable",
             "answer-point-unknown",
             "answer-point-changed",

package/src/workspace/records.ts

@@ -419,6 +419,23 @@ export const recordKindSchema = z
      * done record with a criterion that no passing evidence meets is warned
      * `work-acceptance-unmet`, which `check` fails on (WSP117). Optional, and
      * a record without the list is read as before.
+     *
+     * #3147 adds four, each optional:
+     *
+     * - `contract`: the front-matter field naming the contract record the
+     *   item builds, and the kind file of those records (relative to this
+     *   kind file). Each record gets `contract` with that record's state,
+     *   warned `work-contract-unknown` or `work-contract-undecided`.
+     * - `tier`: the field holding the item's builder tier, and the tiers the
+     *   workspace allows, declared once here. A tier outside them is warned
+     *   `work-tier-unknown`.
+     * - `attempts`: the field holding an item's own attempt limit, and the
+     *   default `max` for items without one. `work history` counts attempts
+     *   against it.
+     * - `answers`: the answer kind file (relative to this kind file) whose
+     *   records answer decision points about an item. Each record gets
+     *   `answers`, the answers whose `constrains` names its id, joined by id
+     *   rather than copied onto the item.
      */
     work: z
       .object({
@@ -429,6 +446,14 @@ export const recordKindSchema = z
         done: z.string().min(1),
         closedOn: z.string().min(1),
         acceptance: z.object({ field: z.string().min(1), implementer: z.string().min(1) }).strict().optional(),
+        contract: z.object({ field: z.string().min(1), kind: z.string().min(1) }).strict().optional(),
+        tier: z
+          .object({ field: z.string().min(1), tiers: z.array(z.string().min(1)).min(1) })
+          .strict()
+          .refine((t) => new Set(t.tiers).size === t.tiers.length, { message: "work.tier.tiers lists each tier once", path: ["tiers"] })
+          .optional(),
+        attempts: z.object({ field: z.string().min(1), max: z.number().int().min(1) }).strict().optional(),
+        answers: z.string().min(1).optional(),
       })
       .strict()
       .optional(),
@@ -1148,6 +1173,8 @@ export interface RecordEntry {
   implements?: WorkLink[];
   /** For a work kind with acceptance criteria (#2772): how many of the record's criteria passing evidence meets, or null when it lists none. */
   acceptance?: WorkAcceptance | null;
+  /** For a work kind with a contract link (#3147): the contract record the item builds, with its state, or null when it names none. */
+  contract?: WorkLink | null;
 }
 
 export interface ReadRecordsOptions {

package/src/workspace/runs-cli.ts

@@ -0,0 +1,381 @@
+/**
+ * `chant workspace runs` (#3033, ws-076): read and write the agent run
+ * record.
+ *
+ * - `runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>]
+ *   --json` reads every run in the ledger with the commits it made, and
+ *   totals tokens and cost per work item, per decision and per principal,
+ *   naming the runs that report no cost instead of counting them as zero
+ *   (`runs.schema.json`, a read-contract output).
+ * - `runs start --from <file|->`, `runs end <id> --from <file|->` and `runs
+ *   record --from <file|->` append a run's start, its end, or both, to
+ *   `_agent-runs/<id>.jsonl` on `chant/lifecycle` (`runs-write.schema.json`).
+ *
+ * chant records runs and never starts one: whatever ran the agent writes the
+ * record. Reads never fetch.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { declaredRecordKinds, readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError } from "./declaration";
+import { declaredKindFile } from "./declared-kinds";
+import type { ReasonCode } from "./reason-codes";
+import { loadRecordKind, RecordReadError } from "./records";
+import { queryRecords } from "./records-cli";
+import {
+  commitsByRunTrailer,
+  endRun,
+  foldRun,
+  joinTrailerCommits,
+  LEDGER_BRANCH,
+  readRuns,
+  recordRun,
+  RunWriteError,
+  startRun,
+  type RunLedgerWrite,
+  type RunView,
+  type RunWriteContext,
+} from "./runs";
+import { RUN_TRAILER } from "./trailers";
+import { locateWorkspace } from "./which-chant";
+import { idList } from "./work";
+import { AGENT_ENV } from "./write-scope";
+import { execFileSync } from "node:child_process";
+
+/** The version of the `runs` documents this chant writes: read contract 1. */
+export const RUNS_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for `runs --json`, shipped beside this file. */
+export const RUNS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/runs/v1/runs.schema.json";
+
+/** `$id` of the JSON Schema for what `runs start|end|record` print. */
+export const RUNS_WRITE_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/runs-write/v1/runs-write.schema.json";
+
+const USAGE = [
+  "chant workspace runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>] [--json]",
+  "chant workspace runs start --from <file|->",
+  "chant workspace runs end <run id> [--from <file|->]",
+  "chant workspace runs record --from <file|->",
+].join("\n");
+
+/** Why `runs` read nothing. Closed. */
+export const RUNS_ERROR_CODES = [...WORKSPACE_ERROR_CODES] as const satisfies readonly ReasonCode[];
+export type RunsErrorCode = (typeof RUNS_ERROR_CODES)[number];
+
+/** Why part of the read is missing. The read still succeeds. Closed. */
+export const RUNS_REASON_CODES = ["runs-no-ledger", "runs-ledger-malformed", "kind-unreadable"] as const satisfies readonly ReasonCode[];
+export type RunsReasonCode = (typeof RUNS_REASON_CODES)[number];
+
+/** Why a run write was refused or could not run. Closed. */
+export const RUNS_WRITE_ERROR_CODES = [...WORKSPACE_ERROR_CODES, "write-usage-invalid", "write-input-invalid", "run-exists", "run-unknown", "run-ended"] as const satisfies readonly ReasonCode[];
+export type RunsWriteErrorCode = (typeof RUNS_WRITE_ERROR_CODES)[number];
+
+// ── Totals ───────────────────────────────────────────────────────────────────
+
+/** Tokens and cost summed over some runs. */
+export interface RunTotals {
+  runs: number;
+  /** Runs with no end recorded yet. */
+  running: number;
+  /** Summed over the runs that report usage; a count a run leaves out adds nothing. */
+  tokens: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  /** One sum per currency, since amounts in two currencies don't add. */
+  cost: { currency: string; amount: number }[];
+  /** The runs that report no cost, running ones included: left out of `cost`, never counted as zero. */
+  unpriced: string[];
+  /** The runs that report no usage: left out of `tokens`. */
+  unreported: string[];
+}
+
+const round = (n: number) => Math.round(n * 1e6) / 1e6;
+
+export function totalRuns(runs: RunView[]): RunTotals {
+  const t: RunTotals = { runs: runs.length, running: 0, tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, cost: [], unpriced: [], unreported: [] };
+  for (const r of runs) {
+    if (r.state === "running") t.running++;
+    if (r.usage) {
+      t.tokens.input += r.usage.inputTokens ?? 0;
+      t.tokens.output += r.usage.outputTokens ?? 0;
+      t.tokens.cacheRead += r.usage.cacheReadTokens ?? 0;
+      t.tokens.cacheWrite += r.usage.cacheWriteTokens ?? 0;
+    } else t.unreported.push(r.id);
+    if (r.cost) {
+      const sum = t.cost.find((c) => c.currency === r.cost!.currency);
+      if (sum) sum.amount = round(sum.amount + r.cost.amount);
+      else t.cost.push({ currency: r.cost.currency, amount: round(r.cost.amount) });
+    } else t.unpriced.push(r.id);
+  }
+  t.cost.sort((a, b) => (a.currency < b.currency ? -1 : a.currency > b.currency ? 1 : 0));
+  return t;
+}
+
+/** Group runs by a key each run gives zero or more of, in first-seen order. */
+function groupBy<K extends string | null>(runs: RunView[], keys: (r: RunView) => K[]): Map<K, RunView[]> {
+  const out = new Map<K, RunView[]>();
+  for (const r of runs) for (const k of keys(r)) (out.get(k) ?? out.set(k, []).get(k)!).push(r);
+  return out;
+}
+
+// ── The read ─────────────────────────────────────────────────────────────────
+
+export interface RunsQuery {
+  cwd: string;
+  /** Only the runs on this work item. */
+  unit?: string;
+  /** Only the runs that carried out this decision: its id, or `<kind>/<id>`. */
+  decision?: string;
+  /** Only the runs made for this principal. */
+  by?: string;
+  /** Only the runs that made a commit after `since` on HEAD, or started after its commit date. */
+  since?: string;
+}
+
+export interface RunsReason {
+  code: RunsReasonCode;
+  message: string;
+}
+
+/** What `runs --json` prints. */
+export type RunsDocument =
+  | {
+      $schema: string;
+      contract: number;
+      chant: string;
+      workspace: { name: string; root: string };
+      ledger: { branch: string; dir: string; commit: string | null };
+      filter: { unit: string | null; decision: string | null; by: string | null; since: string | null };
+      /** Newest first, by when each started. */
+      runs: RunView[];
+      totals: {
+        all: RunTotals;
+        byUnit: (RunTotals & { unit: string | null })[];
+        byDecision: (RunTotals & { decision: string })[];
+        byPrincipal: (RunTotals & { principal: string | null })[];
+      };
+      malformed: number;
+      reasons: RunsReason[];
+    }
+  | { $schema: string; contract: number; chant: string; error: { code: RunsErrorCode; message: string } };
+
+/**
+ * The decisions each run carried out, as `<kind>/<id>`: the ones its work
+ * item implements, read through the declared work kinds, and the records it
+ * names of a kind a work kind calls its decision kind. Fills `decisions` in
+ * place.
+ */
+export async function resolveRunDecisions(runs: RunView[], rootOnDisk: string, declared: string[], reasons: RunsReason[]): Promise<void> {
+  const implementsOf = new Map<string, Set<string>>();
+  const decisionKinds = new Set<string>();
+  for (const file of declared) {
+    try {
+      const loaded = await loadRecordKind(file, rootOnDisk);
+      const work = loaded.kind.work;
+      if (!work) continue;
+      const decisionKind = (await loadRecordKind(resolve(dirname(loaded.file), work.decisions), rootOnDisk)).kind.name;
+      decisionKinds.add(decisionKind);
+      const doc = await queryRecords({ kind: loaded.file, cwd: rootOnDisk, workGaps: false });
+      if ("error" in doc) throw new RecordReadError(doc.error.code as never, doc.error.message);
+      for (const v of doc.records) {
+        if (v.id === null) continue;
+        const set = implementsOf.get(v.id) ?? implementsOf.set(v.id, new Set()).get(v.id)!;
+        for (const d of idList(v.data, work.implements)) set.add(`${decisionKind}/${d}`);
+      }
+    } catch (err) {
+      if (!(err instanceof RecordReadError)) throw err;
+      reasons.push({ code: "kind-unreadable", message: `${file}: ${err.message}; the decisions its work items implement are left out` });
+    }
+  }
+  if (decisionKinds.size === 0) decisionKinds.add("decision");
+  for (const r of runs) {
+    const out = new Set<string>(r.unit ? (implementsOf.get(r.unit.id) ?? []) : []);
+    for (const ref of r.records) if (decisionKinds.has(ref.kind)) out.add(`${ref.kind}/${ref.id}`);
+    r.decisions = [...out].sort();
+  }
+}
+
+function tryGit(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;
+  }
+}
+
+/** Read the run ledger and build the document. Never throws a {@link WorkspaceReadError}. */
+export async function workspaceRuns(query: RunsQuery): Promise<RunsDocument> {
+  const head = { $schema: RUNS_OUTPUT_SCHEMA_ID, contract: RUNS_CONTRACT_VERSION, chant: readerVersion() };
+  try {
+    const located = locateWorkspace(query.cwd);
+    const declaration = readDeclaration(located.tree, "", { rootChant: true });
+    const top = located.top;
+    if (!top) throw new WorkspaceReadError("not-a-git-repository", "agent runs are kept on the chant/lifecycle branch, and this directory is not in a git repository");
+    const reasons: RunsReason[] = [];
+    const { tip, dir, runs, malformed } = await readRuns(top, located.rootOnDisk);
+    if (!tip) reasons.push({ code: "runs-no-ledger", message: `this checkout has no ${LEDGER_BRANCH} branch, so there are no agent runs to read; fetch it first if the remote has one` });
+    if (malformed > 0) reasons.push({ code: "runs-ledger-malformed", message: `${malformed} ${malformed === 1 ? "line" : "lines"} of ${dir} on ${LEDGER_BRANCH} ${malformed === 1 ? "is" : "are"} not a run event and ${malformed === 1 ? "was" : "were"} left out` });
+    joinTrailerCommits(runs, commitsByRunTrailer(top), top);
+    const all = [...runs.values()];
+    await resolveRunDecisions(all, located.rootOnDisk, declaredRecordKinds(declaration).map((d) => declaredKindFile(d, located.rootOnDisk)), reasons);
+
+    let since: { commits: Set<string>; date: number } | undefined;
+    if (query.since !== undefined) {
+      const sha = tryGit(top, ["rev-parse", "--verify", "--quiet", `${query.since}^{commit}`])?.trim();
+      if (!sha) throw new WorkspaceReadError("revision-unknown", `--since ${query.since} names no commit in this repository`);
+      const commits = new Set((tryGit(top, ["rev-list", `${sha}..HEAD`]) ?? "").split("\n").map((s) => s.trim()).filter(Boolean));
+      since = { commits, date: Number(tryGit(top, ["show", "-s", "--format=%ct", sha])?.trim() ?? "0") * 1000 };
+    }
+    const wantDecision = query.decision;
+    const selected = all
+      .filter((r) => query.unit === undefined || r.unit?.id === query.unit)
+      .filter((r) => wantDecision === undefined || r.decisions.some((d) => d === wantDecision || d.slice(d.indexOf("/") + 1) === wantDecision))
+      .filter((r) => query.by === undefined || r.by === query.by)
+      .filter((r) => !since || r.commits.some((c) => since!.commits.has(c.sha)) || Date.parse(r.startedAt) > since.date)
+      .sort((a, b) => (a.startedAt < b.startedAt ? 1 : a.startedAt > b.startedAt ? -1 : a.id < b.id ? 1 : -1));
+
+    const byUnit = [...groupBy(selected, (r) => [r.unit?.id ?? null])].map(([unit, rs]) => ({ unit, ...totalRuns(rs) }));
+    const byDecision = [...groupBy(selected, (r) => r.decisions)].map(([decision, rs]) => ({ decision: decision as string, ...totalRuns(rs) }));
+    const byPrincipal = [...groupBy(selected, (r) => [r.by])].map(([principal, rs]) => ({ principal, ...totalRuns(rs) }));
+    return {
+      ...head,
+      workspace: { name: declaration.name, root: located.root },
+      ledger: { branch: LEDGER_BRANCH, dir, commit: tip },
+      filter: { unit: query.unit ?? null, decision: query.decision ?? null, by: query.by ?? null, since: query.since ?? null },
+      runs: selected,
+      totals: { all: totalRuns(selected), byUnit, byDecision, byPrincipal },
+      malformed,
+      reasons,
+    };
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) return { ...head, error: { code: err.code as RunsErrorCode, message: err.describe() } };
+    throw err;
+  }
+}
+
+// ── The writes ───────────────────────────────────────────────────────────────
+
+export type RunsVerb = "start" | "end" | "record";
+
+/** What `runs start|end|record` print. */
+export type RunsWriteDocument =
+  | {
+      $schema: string;
+      contract: number;
+      verb: RunsVerb;
+      /** The run as the ledger now holds it. */
+      run: RunView;
+      /** The line a commit the run makes carries, `Chant-Run: <id>` (#3149). */
+      trailer: string;
+      ledger: RunLedgerWrite;
+    }
+  | { $schema: string; contract: number; verb: RunsVerb | null; error: { code: RunsWriteErrorCode; message: string } };
+
+export interface RunsWriteRequest {
+  verb: RunsVerb;
+  /** The run id, for `end`. */
+  id?: string;
+  /** The JSON fields, as text. */
+  fields: string;
+  cwd: string;
+  /** The agent session in `CHANT_AGENT`, the default for `agent`. */
+  agent?: string;
+  now?: () => Date;
+}
+
+/** Run one write and build the document it prints. */
+export async function runsWrite(req: RunsWriteRequest): Promise<RunsWriteDocument> {
+  const head = { $schema: RUNS_WRITE_SCHEMA_ID, contract: RUNS_CONTRACT_VERSION };
+  const fail = (code: RunsWriteErrorCode, message: string): RunsWriteDocument => ({ ...head, verb: req.verb, error: { code, message } });
+  let fields: unknown;
+  try {
+    fields = req.fields.trim() === "" ? {} : JSON.parse(req.fields);
+  } catch (err) {
+    return fail("write-input-invalid", `the fields are not JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (fields === null || typeof fields !== "object" || Array.isArray(fields)) return fail("write-input-invalid", "the fields are a JSON object");
+  if (req.verb !== "end" && req.agent && (fields as Record<string, unknown>).agent === undefined) fields = { ...(fields as object), agent: req.agent };
+  try {
+    const located = locateWorkspace(req.cwd);
+    const declaration = readDeclaration(located.tree, "", { rootChant: true });
+    if (!located.top) return fail("not-a-git-repository", "agent runs are kept on the chant/lifecycle branch, and this directory is not in a git repository");
+    const ctx: RunWriteContext = { top: located.top, rootOnDisk: located.rootOnDisk, cwd: req.cwd, now: req.now };
+    const result = req.verb === "start" ? await startRun(fields, ctx) : req.verb === "end" ? await endRun(req.id ?? "", fields, ctx) : await recordRun(fields, ctx);
+    const run = foldRun(result.id, result.ledger.path, result.lines)!;
+    await resolveRunDecisions([run], located.rootOnDisk, declaredRecordKinds(declaration).map((d) => declaredKindFile(d, located.rootOnDisk)), []);
+    return { ...head, verb: req.verb, run, trailer: `${RUN_TRAILER}: ${run.id}`, ledger: result.ledger };
+  } catch (err) {
+    if (err instanceof RunWriteError) return fail(err.code, err.message);
+    if (err instanceof WorkspaceReadError) return fail(err.code as RunsWriteErrorCode, err.describe());
+    throw err;
+  }
+}
+
+// ── Text ─────────────────────────────────────────────────────────────────────
+
+function money(t: RunTotals): string {
+  const priced = t.cost.map((c) => `${c.amount} ${c.currency}`).join(" + ") || "no cost reported";
+  return `${priced}${t.unpriced.length > 0 ? `, ${t.unpriced.length} unpriced` : ""}`;
+}
+
+/** The read as lines for a person. */
+export function formatRuns(doc: Extract<RunsDocument, { runs: unknown }>): string {
+  const out: string[] = [];
+  for (const r of doc.runs) {
+    const model = [r.harness.name, r.model].filter(Boolean).join("/");
+    const tokens = r.usage ? `${r.usage.inputTokens ?? "?"} in, ${r.usage.outputTokens ?? "?"} out` : "no usage";
+    const cost = r.cost ? `${r.cost.amount} ${r.cost.currency} (${r.cost.source})` : "unpriced";
+    out.push(`${r.id}  ${r.state}${r.outcome ? ` ${r.outcome}` : ""}  ${r.startedAt}  ${model}${r.by ? ` for ${r.by}` : ""}${r.unit ? `  on ${r.unit.id}` : ""}  ${tokens}  ${cost}  ${r.commits.length} commit${r.commits.length === 1 ? "" : "s"}`);
+  }
+  if (doc.runs.length === 0) out.push("no agent runs");
+  const t = doc.totals.all;
+  out.push(`${t.runs} run${t.runs === 1 ? "" : "s"} (${t.running} running): ${t.tokens.input} tokens in, ${t.tokens.output} out; ${money(t)}`);
+  for (const r of doc.reasons) out.push(`reason  ${r.code}: ${r.message}`);
+  return out.join("\n");
+}
+
+// ── The command ──────────────────────────────────────────────────────────────
+
+function readFields(value: string | undefined, cwd: string): string {
+  if (value === undefined) return "";
+  return readFileSync(value === "-" ? 0 : resolve(cwd, value), "utf-8");
+}
+
+export async function runWorkspaceRuns(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const cwd = process.cwd();
+  const verb = args.extraPositional;
+  if (verb === "start" || verb === "end" || verb === "record") {
+    const print = (doc: RunsWriteDocument): number => {
+      console.log(JSON.stringify(doc, null, 2));
+      return "error" in doc ? 1 : 0;
+    };
+    const usage = (message: string) => print({ $schema: RUNS_WRITE_SCHEMA_ID, contract: RUNS_CONTRACT_VERSION, verb, error: { code: "write-usage-invalid", message } });
+    for (const [flag, v] of [["--unit", args.unit], ["--decision", args.decision], ["--by", args.by], ["--since", args.since]] as const) {
+      if (v !== undefined) return usage(`runs ${verb} takes its fields with --from, not ${flag}`);
+    }
+    if (verb === "end" && !args.extraPositional2) return usage("runs end needs the run id: runs end <run id>");
+    if (verb !== "end" && args.extraPositional2) return usage(`runs ${verb} takes no run id; put an id in the fields to choose one`);
+    if (verb !== "end" && args.migrateFrom === undefined) return usage(`runs ${verb} needs --from <file|->: the run's fields as JSON`);
+    let fields: string;
+    try {
+      fields = readFields(args.migrateFrom, cwd);
+    } catch (err) {
+      return print({ $schema: RUNS_WRITE_SCHEMA_ID, contract: RUNS_CONTRACT_VERSION, verb, error: { code: "write-input-invalid", message: `--from ${args.migrateFrom} could not be read: ${err instanceof Error ? err.message : String(err)}` } });
+    }
+    return print(await runsWrite({ verb, id: args.extraPositional2, fields, cwd, agent: process.env[AGENT_ENV] || undefined }));
+  }
+  if (verb !== undefined) {
+    console.error(formatError({ message: `chant workspace runs takes start, end or record, or no verb to read, not ${verb}`, hint: USAGE }));
+    return 1;
+  }
+  if (args.migrateFrom !== undefined) {
+    console.error(formatError({ message: "runs is a read and takes no --from; write with runs start, end or record", hint: USAGE }));
+    return 1;
+  }
+  const doc = await workspaceRuns({ cwd, unit: args.unit, decision: args.decision, by: args.by, since: args.since });
+  if (args.json) console.log(JSON.stringify(doc, null, 2));
+  else if ("error" in doc) console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+  else console.log(formatRuns(doc));
+  return "error" in doc ? 1 : 0;
+}