@intentius/chant 0.101.0 → 0.102.0

package/src/cli/handlers/run.ts

@@ -1,7 +1,7 @@
 import { lexiconNames } from "../../lexicon-module";
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, basename } from "node:path";
 import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
-import { loadChantConfig, resolveAutoReleaseDisabled, type ChantConfig } from "../../config";
+import { loadChantConfig, resolveAutoReleaseDisabled, InvalidChantConfigError, type ChantConfig } from "../../config";
 import { discoverOps, discoverStewards } from "../../op/discover";
 import { stewardWorkHolder } from "../../op/work-lease-run";
 import type { OpConfig } from "../../op/types";
@@ -108,10 +108,12 @@ function refuseDurableComponentSubcommand(what: string, hint: string): number {
 /**
  * Resolve the one runtime this invocation talks to.
  *
- * `--on <name>` picks the named lexicon's `opRuntime` (`../../lexicon.ts`);
- * without it, core's built-in `local` provider runs the Op in this process.
- * Every `chant run` subcommand goes through whichever comes back, so there is
- * one dispatch path rather than a branch per runtime.
+ * `--on <name>` picks the named lexicon's `opRuntime` (`../../lexicon.ts`).
+ * Without it, `run.on` in `chant.config.ts` does (#2523), and without either,
+ * core's built-in `local` provider runs the Op in this process. `local`, from
+ * either place, names the built-in provider. Every `chant run` subcommand goes
+ * through whichever comes back, so there is one dispatch path rather than a
+ * branch per runtime.
  *
  * A lexicon already loaded into the command context wins the lookup — that is
  * how a test hands in a stub, and how a command that loaded plugins for its
@@ -121,22 +123,20 @@ function refuseDurableComponentSubcommand(what: string, hint: string): number {
  *
  * Returns `undefined` after printing an actionable error — an unconfigured
  * name is answered with the configured list, a configured lexicon that hosts
- * nothing is named outright.
+ * nothing is named outright. A `run.on` default gets the same messages as
+ * `--on`, labelled `run.on` and the config file instead of `--on`.
  */
 async function resolveOpRuntime(ctx: CommandContext): Promise<OpRuntimeProvider | undefined> {
-  const on = ctx.args.on;
+  const choice = await chooseOpRuntime(ctx);
+  if (!choice) return undefined;
+  const { on, source, configured } = choice;
   if (!on || on === "local") return createLocalOpRuntime({ projectPath: resolve(".") });
 
-  // Read the configured list straight from `chant.config.ts` rather than
-  // through `resolveProjectLexicons`: `--on` names a *configured* lexicon, and
-  // that helper's fallback is a source scan of the whole project, which is a
-  // long wait to be told a name is wrong.
-  let configured: string[] = [];
-  try {
-    configured = lexiconNames((await loadChantConfig(resolve("."))).config.lexicons ?? []);
-  } catch {
-    // No/unreadable chant.config.ts — the error below says so by listing nothing.
-  }
+  // How the error names the choice, and how to get the built-in runtime back.
+  const label = source === "flag" ? `--on ${on}` : `run.on "${on}" in ${choice.configFile}`;
+  const fallback = source === "flag"
+    ? "Omit --on to run on the built-in local runtime."
+    : `Fix \`run.on\` in ${choice.configFile}, or pass --on local to run on the built-in local runtime.`;
 
   let plugin = ctx.plugins.find((p) => p.name === on);
   if (!plugin && configured.includes(on)) {
@@ -146,18 +146,18 @@ async function resolveOpRuntime(ctx: CommandContext): Promise<OpRuntimeProvider
   if (!plugin) {
     const known = [...new Set([...ctx.plugins.map((p) => p.name), ...configured])];
     console.error(formatError({
-      message: `--on ${on}: "${on}" is not a configured lexicon`,
+      message: `${label}: "${on}" is not a configured lexicon`,
       hint: known.length > 0
-        ? `Configured lexicons: ${known.join(", ")}. Omit --on to run on the built-in local runtime.`
-        : "chant.config.ts configures no lexicons. Omit --on to run on the built-in local runtime.",
+        ? `Configured lexicons: ${known.join(", ")}. ${fallback}`
+        : `chant.config.ts configures no lexicons. ${fallback}`,
     }));
     return undefined;
   }
 
   if (!plugin.opRuntime) {
     console.error(formatError({
-      message: `--on ${on}: lexicon "${on}" does not host Op runs`,
-      hint: "It declares no opRuntime. Omit --on to run on the built-in local runtime.",
+      message: `${label}: lexicon "${on}" does not host Op runs`,
+      hint: `It declares no opRuntime. ${fallback}`,
     }));
     return undefined;
   }
@@ -165,6 +165,64 @@ async function resolveOpRuntime(ctx: CommandContext): Promise<OpRuntimeProvider
   return plugin.opRuntime;
 }
 
+/** Which runtime name an invocation asked for, and where the name came from. */
+interface OpRuntimeChoice {
+  /** The runtime name; `undefined` or `"local"` is the built-in runtime. */
+  on: string | undefined;
+  /** `flag` for `--on`, `config` for `run.on`, `default` when neither named one. */
+  source: "flag" | "config" | "default";
+  /** The lexicons `chant.config.ts` configures. */
+  configured: string[];
+  /** The config file's name, for messages about `run.on`. */
+  configFile: string;
+}
+
+/**
+ * The runtime name `--on`, then `run.on` in `chant.config.ts` (#2523), then
+ * the built-in default pick, without loading any lexicon.
+ *
+ * Reads the configured list straight from `chant.config.ts` rather than
+ * through `resolveProjectLexicons`: `--on` names a *configured* lexicon, and
+ * that helper's fallback is a source scan of the whole project, which is a
+ * long wait to be told a name is wrong.
+ *
+ * A config that fails to load leaves the flag's choice alone, as before. With
+ * no flag, a config whose `run` block is invalid is refused (printed, then
+ * `undefined`): running the Op locally would hide that the project asked for
+ * another runtime. Any other load failure falls back to the built-in runtime,
+ * which is what a project with no `run.on` got before. `quiet` skips printing
+ * that refusal, for a caller that only peeks at the choice and leaves the
+ * reporting to {@link resolveOpRuntime}.
+ */
+async function chooseOpRuntime(ctx: CommandContext, quiet = false): Promise<OpRuntimeChoice | undefined> {
+  const flag = ctx.args.on;
+  if (flag === "local") return { on: "local", source: "flag", configured: [], configFile: "chant.config.ts" };
+
+  let configured: string[] = [];
+  let configuredOn: string | undefined;
+  let configFile = "chant.config.ts";
+  try {
+    const { config, configPath } = await loadChantConfig(resolve("."));
+    configured = lexiconNames(config.lexicons ?? []);
+    configuredOn = config.run?.on;
+    if (configPath) configFile = basename(configPath);
+  } catch (err) {
+    if (!flag && err instanceof InvalidChantConfigError && err.key === "run") {
+      if (quiet) return undefined;
+      console.error(formatError({
+        message: err.message,
+        hint: "`run.on` names the runtime that hosts this project's Op runs: a configured lexicon with an opRuntime, or \"local\". Fix it, or pass --on to pick the runtime for this run.",
+      }));
+      return undefined;
+    }
+    // No/unreadable chant.config.ts: an `--on` error says so by listing nothing.
+  }
+
+  if (flag) return { on: flag, source: "flag", configured, configFile };
+  if (configuredOn) return { on: configuredOn, source: "config", configured, configFile };
+  return { on: undefined, source: "default", configured, configFile };
+}
+
 /** An ISO-8601 instant trimmed to what a table cell has room for. */
 function shortInstant(iso: string | undefined): string {
   return iso ? iso.slice(0, 19).replace("T", " ") : "—";
@@ -395,6 +453,7 @@ export async function runOpApprove(ctx: CommandContext): Promise<number> {
     note: ctx.args.note,
     url: ctx.args.url,
     plan: ctx.args.plan,
+    ...(ctx.args.sign !== undefined ? { sign: ctx.args.sign } : {}),
   });
   if (!outcome.ok) return 1;
 
@@ -582,7 +641,9 @@ async function stewardTurnGate(opName: string, ctx: CommandContext): Promise<Ste
   const form = stewardFormFor(owner, env);
 
   if (form === "fountain") {
-    if (ctx.args.on === "fountain") return { ok: true };
+    // `run.on: "fountain"` asks for the steward's thread as much as the flag
+    // does (#2523).
+    if ((await chooseOpRuntime(ctx, true))?.on === "fountain") return { ok: true };
     return {
       ok: false,
       message: `Op "${opName}" is one of steward "${owner.name}"'s Ops, which runs on fountain in environment "${env}"`,

package/src/cli/handlers/scenario.ts

@@ -15,7 +15,7 @@ import { collectEffectReceipts, isEffectReceipt, type EffectReceiptDeclaration }
 import { evaluateScenario, type ScenarioBehaviourFixture, type ScenarioVerdict } from "../../lifecycle/scenario-eval";
 import { validateBehaviourResult } from "../../behaviour-delta";
 import { collectScenarios, type ScenarioDeclaration, type ScenarioGiven } from "../../lifecycle/scenario";
-import { isResourceDeclarable } from "../../declarable";
+import { isObservableDeclarable } from "../../declarable";
 import { loadChantConfig } from "../../config";
 import { unknownEnvError } from "../../env";
 import { collectBuildRootContributors } from "../plugins";
@@ -281,7 +281,7 @@ async function evaluateOneScenario(
     // and observed like any resource (#1832) — it joins the declared axis so
     // its lexicon's fixture data can confirm presence, absence, or a hole,
     // the same as `runLifecyclePlan` (lifecycle.ts:1184).
-    if (!isResourceDeclarable(entity) && !isEffectReceipt(entity)) continue;
+    if (!isObservableDeclarable(entity) && !isEffectReceipt(entity)) continue;
     if (!declaredByLexicon.has(entity.lexicon)) declaredByLexicon.set(entity.lexicon, new Set());
     declaredByLexicon.get(entity.lexicon)!.add(name);
   }

package/src/cli/main.test.ts

@@ -767,6 +767,7 @@ describe("workspace init and ls (#2534)", () => {
       "workspace pin",
       "workspace points",
       "workspace records",
+      "workspace runs",
       "workspace signers",
       "workspace status",
       "workspace upgrade",

package/src/cli/main.ts

@@ -102,6 +102,7 @@ const BOOLEAN_FLAGS = new Set([
   "--durable-requests",
   "--skip-mcp",
   "--current",
+  "--uncommitted",
   "--allow-code",
   "--root-only",
   "--generated",
@@ -227,6 +228,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant import --kustomize <dir>` (#1548): render the overlay, import
       // the output through the k8s template parser.
       result.kustomize = args[++i];
+    } else if (arg === "--parser-option") {
+      // `chant import --parser-option key[=value]` (#2994), repeatable: checked
+      // against the lexicon's parserOptions() by the import command.
+      const v = args[++i];
+      if (!v || v.startsWith("-")) throw new Error("--parser-option needs key or key=value: --parser-option acceptLossyV1");
+      (result.parserOption ??= []).push(v);
     } else if (arg === "--type") {
       result.selectType = args[++i];
     } else if (arg === "--name") {
@@ -377,11 +384,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace graph --composites` (#2662)
       result.composites = true;
     } else if (arg === "--intent") {
-      // `chant workspace graph --intent <path[:start-end]>` (#2651), or `--intent --record <id>` with no region.
+      // `chant workspace graph --intent <path[:start-end]|path#symbol>` (#2651), or `--intent --record <id>` with no region.
       const value = args[i + 1];
       if (value !== undefined && !value.startsWith("-")) result.intent = args[++i];
       else if (args.includes("--record")) result.intent = "";
-      else throw new Error("--intent needs a region: --intent <path[:start-end]>, or --intent --record <id>");
+      else throw new Error("--intent needs a region: --intent <path[:start-end]|path#symbol>, or --intent --record <id>");
     } else if (arg === "--record") {
       // `chant workspace graph --intent --record <id>`
       result.record = args[++i];
@@ -409,6 +416,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (!result.severity || result.severity.startsWith("-")) throw new Error("--severity needs off, warn or fail");
     } else if (arg === "--current") {
       result.current = true;
+    } else if (arg === "--uncommitted") {
+      // `chant workspace records --uncommitted` (#3160)
+      result.uncommitted = true;
     } else if (arg === "--set") {
       // `chant workspace records amend <id> --set <file|->` (#2670)
       result.set = args[++i];
@@ -445,6 +455,7 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--sign") {
       // `chant workspace records review <id> --sign [<key file>]` (#2687): seal the verdict.
       // `records new` and `records amend` take it too, to seal the record's author (#2688).
+      // `chant approve <op> <gate> --sign [<key file>]` seals a gate approval (#3163).
       // With no key file, git's user.signingkey, as `git commit -S` reads it.
       const next = args[i + 1];
       result.sign = next !== undefined && !next.startsWith("-") ? args[++i] : true;
@@ -566,6 +577,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       const value = args[++i];
       if (!value || value.startsWith("-")) throw new Error(`${arg} needs a value: ${arg} <${arg.slice(2)}>`);
       result[arg.slice(2) as "holder" | "ttl" | "token" | "outcome"] = value;
+    } else if (arg === "--unit" || arg === "--decision") {
+      // `chant workspace runs --unit <id> | --decision <id>` (#3033): the runs on one work item, or for one decision.
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error(`${arg} needs an id: ${arg} <id>`);
+      result[arg.slice(2) as "unit" | "decision"] = value;
     } else if (arg === "--note") {
       result.note = args[++i];
     } else if (arg === "--expire") {
@@ -818,7 +834,11 @@ Ops:
                         and defaults to the PR/MR of the surrounding CI job.
                         The next "chant run <op>" walks through the gate.
                         --expire clears a pending fact without approving it,
-                        so the gate is re-decided from scratch next run
+                        so the gate is re-decided from scratch next run.
+                        --sign [<key file>] seals the approval with an ssh
+                        key; a gate the workspace's identity.gates names
+                        counts only an approval sealed by a key the signers
+                        file at base lists for --actor
 
   graph                 Show Op dependency graph (--stacks for cross-stack order,
                         --format ir|mermaid|dot|layout for the lint-gated graph IR,
@@ -858,7 +878,7 @@ Workspace (level 1, #2524):
                         beside it and marks the members whose digests differ.
                         Read only; never fetches. --json prints the
                         read-contract document
-  workspace records [--kind <kind file>] [--current] [--at <rev>] [--base <rev>] [--require attested] [--json]
+  workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--json]
                         Without --kind, every record kind the declaration
                         names. Read the records a record kind locates, validated
                         against its schema, with reason codes for invalid
@@ -868,7 +888,10 @@ Workspace (level 1, #2524):
                         the signers at --base (default: the target branch);
                         --require attested exits 2 if any record is not
                         attested. A pinned file that changed is a warning,
-                        asset-drift or asset-missing
+                        asset-drift or asset-missing. In the working tree,
+                        each record says whether it is committed, modified
+                        or new against HEAD, with the branch and base;
+                        --uncommitted lists only the modified and new ones
   workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json]
                         What changed in the records between <rev> and --at
                         (default: the working tree): new and removed records,
@@ -910,7 +933,7 @@ Workspace (level 1, #2524):
                         closing commit and seal, in one write. Without
                         --kind, the one session kind the declaration names.
                         Prints {path, id, changed, seal, closedRev}
-  workspace work claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <text>] [--note <text>] [--json]
+  workspace work claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <outcome>] [--note <text>] [--json]
                         Take, heartbeat or give back the lease on a work item:
                         refs/chant/lease/work/<id>, a compare-and-set ref with a
                         fencing token and an expiry, pushed to the remote so
@@ -921,6 +944,28 @@ Workspace (level 1, #2524):
                         A work item's lease history: each claim with its token
                         and holder, and how it ended, released with an outcome
                         or never released (expired or lost). Read-only
+  workspace work evidence <id> --holder <name> --token <token> --from <file|-> [--kind <kind file>]
+                        Attach evidence for one acceptance criterion under the
+                        lease you hold: the entry (criterion, result, title,
+                        a url or a path pinned by hash) is appended to the
+                        item's pins through records amend. Prints the
+                        work-evidence document and never commits
+  workspace runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>] [--json]
+                        The agent runs in the run ledger on chant/lifecycle, each
+                        with its model, tokens, cost and the commits it made,
+                        and totals per work item, decision and principal; a run
+                        that reports no cost is listed as unpriced, never zero.
+                        Read-only, never fetches
+  workspace runs start --from <file|->
+                        Record that an agent run started: who it worked for,
+                        its harness, model, work item and lease. Prints the run
+                        and its Chant-Run trailer. chant never starts a run
+  workspace runs end <run id> [--from <file|->]
+                        Record how a started run ended: its outcome, tokens,
+                        cost and price source, the transcript pinned by hash,
+                        and the commits it made
+  workspace runs record --from <file|->
+                        Record a finished run, its start and end in one write
   workspace points [--open] [--kind <kind file>] [--at <rev>] [--json]
                         List the decision points the declared answer kinds'
                         points files declare, and the questions asked of them;
@@ -1056,7 +1101,7 @@ Workspace (level 1, #2524):
                         Each composite instance the members declare, with the
                         components whose contract can deploy it; an instance
                         with none lists an empty set
-  workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]
+  workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--json]
                         The intent graph over one region: the commits that
                         touched it, the decisions whose constrains cover it,
                         the artifacts they pin, and findings with closed codes.
@@ -1150,8 +1195,13 @@ Lexicon development:
                             --check: fail if the committed baseline drifted (never writes);
                             --run-examples: also run example build harness;
                             --pinned-digest <file>: verify spec digest before regen)
-  dev pinned-upgrade <dir> Report if a pinned lexicon (k8s|gcp|docker|gitlab) has a newer
-                           upstream release; dry-run bump + regen + surface-diff, then revert
+  dev pinned-upgrade <dir> [pin]
+                           Report if a lexicon that declares upstreamPin (k8s, k3s, gcp, docker,
+                           gitlab, cedar, sql) has a newer upstream release; dry-run bump + regen +
+                           surface-diff, then revert. A pin that moves with other constants (sql's
+                           image digest) is reported with how to move it, not edited. A lexicon
+                           with several pins (sql: clickhouse, postgres-14 .. postgres-18) gets one
+                           report per pin; name a pin to check only that one
                            (reports only; --force bypasses the spec cache, -f json for JSON)
   dev rolling-upgrade <dir>  Report rolling-spec drift (aws, azure, github): regen from
                            latest, diff surface vs committed baseline, print delta + PR
@@ -1194,8 +1244,9 @@ Options:
   -h, --help            Show this help message
   -V, --version         Print the installed chant's version
   --on <lexicon>        Which runtime hosts the run: a configured lexicon with
-                        an opRuntime, or the built-in local runtime when
-                        omitted (every run subcommand; #2121)
+                        an opRuntime, or local. Omitted, run.on in
+                        chant.config.ts decides, then the built-in local
+                        runtime (every run subcommand; #2121, #2523)
   --local               Run an Op with the local in-process executor (default)
   -p, --profile <name>  Named connection profile the hosting runtime targets
                         (fountain.profiles in chant.config.ts); each runtime's
@@ -1287,6 +1338,7 @@ Examples:
   chant components export prod --component search-service -o ./dist/search-service
   chant import template.json --output ./infra/
   chant import manifest.yaml --lexicon k8s --output ./infra/
+  chant import dash.json --lexicon grafana --parser-option acceptLossyV1
   chant import --from prod --name my-bucket --output src/
   chant lint ./infra/
   chant lint ./infra/ --format sarif
@@ -1552,6 +1604,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "workspace ls", handler: async (ctx) => (await import("../workspace/ls")).runWorkspaceLs(ctx) },
   // #2732 — the work lease: claim, renew and release a work item.
   { name: "workspace work", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/work-cli")).runWorkspaceWork(ctx) },
+  // #3033 — the agent run record: what each run cost and which commits it made. chant records runs and never starts one.
+  { name: "workspace runs", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/runs-cli")).runWorkspaceRuns(ctx) },
   { name: "workspace status", handler: async (ctx) => (await import("../workspace/status")).runWorkspaceStatus(ctx) },
   { name: "workspace lineage", handler: async (ctx) => (await import("../workspace/lineage-cli")).runWorkspaceLineage(ctx) },
   { name: "workspace upgrade", handler: async (ctx) => (await import("../workspace/lineage-upgrade-cli")).runWorkspaceUpgrade(ctx) },

package/src/cli/mcp/workspace-tools.test.ts

@@ -12,7 +12,7 @@ import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { createConformanceWorkspace, defaultChantCommand, mcpToolCall, type ConformanceWorkspace } from "../../workspace/conformance";
 import { McpServer } from "./server";
-import { workspaceReadTools, workspaceWriteTools } from "./workspace-tools";
+import { readArgv, workspaceReadTools, workspaceWriteTools } from "./workspace-tools";
 
 const KIND = "decisions/decision.kind.mjs";
 const chant = defaultChantCommand();
@@ -85,7 +85,7 @@ describe("which servers have the workspace tools", () => {
       const { tools } = (await rpc(server(cwd), "tools/list")) as { tools: { name: string }[] };
       expect(tools.map((t) => t.name)).toEqual(expect.arrayContaining(names));
     }
-    expect(names).toEqual(["workspace-ls", "workspace-status", "workspace-graph", "workspace-changes", "workspace-records", "workspace-points", "workspace-agent", "workspace-work-history", "records-new", "records-amend", "records-review", "records-close", "points-answer"]);
+    expect(names).toEqual(["workspace-ls", "workspace-status", "workspace-graph", "workspace-changes", "workspace-records", "workspace-points", "workspace-agent", "workspace-work-history", "workspace-runs", "records-new", "records-amend", "records-review", "records-close", "points-answer"]);
   });
 
   test("a server outside any workspace, or given none, does not", async () => {
@@ -161,6 +161,9 @@ describe("reads", () => {
 
   test("the conformance suite's argv maps to the tool that answers it", () => {
     expect(mcpToolCall(["workspace", "records", "--kind", KIND, "--json"])).toEqual({ name: "workspace-records", arguments: { kind: KIND } });
+    expect(mcpToolCall(["workspace", "records", "--uncommitted", "--kind", KIND, "--json"])).toEqual({ name: "workspace-records", arguments: { uncommitted: true, kind: KIND } });
+    expect(readArgv("workspace-records", { kind: KIND, uncommitted: true })).toEqual(["workspace", "records", "--kind", KIND, "--uncommitted", "--json"]);
+    expect(() => readArgv("workspace-records", { uncommitted: true, at: "HEAD" })).toThrow(/takes no at or since/);
     expect(mcpToolCall(["workspace", "status", "dev", "--json"])).toEqual({ name: "workspace-status", arguments: { env: "dev" } });
     expect(mcpToolCall(["workspace", "graph", "--intent", "a.mjs:1", "--kind", KIND, "--json"])).toEqual({ name: "workspace-graph", arguments: { intent: "a.mjs:1", kind: [KIND] } });
     expect(mcpToolCall(["workspace", "graph", "--composites", "--json"])).toEqual({ name: "workspace-graph", arguments: { composites: true } });

package/src/cli/mcp/workspace-tools.ts

@@ -7,7 +7,7 @@
  *
  * - The reads (`workspace-ls`, `workspace-status`, `workspace-graph`,
  *   `workspace-changes`, `workspace-records`, `workspace-points`,
- *   `workspace-work-history`) run `chant workspace <command>
+ *   `workspace-work-history`, `workspace-runs`) run `chant workspace <command>
  *   ... --json` with the chant this server runs as, in the server's
  *   directory, and return the
  *   document it printed, unchanged, with its reason codes (#2536). Running the
@@ -111,7 +111,7 @@ export const workspaceReadTools: ToolDefinition[] = [
           items: { type: "string" },
           description: "Record kind files whose records join the graph (--kind). The plain graph takes one; intent takes several.",
         },
-        intent: { type: "string", description: "The region for the intent graph: a workspace path, path:line or path:start-end (--intent)." },
+        intent: { type: "string", description: "The region for the intent graph: a workspace path, path:line, path:start-end, or path#symbol for a TypeScript or JavaScript declaration such as src/server.ts#createApp (--intent). The document's why answers why the region is like this." },
         composites: { type: "boolean", description: "The composites document instead (--composites). Takes no kind or intent." },
         at: atProp,
       },
@@ -146,6 +146,10 @@ export const workspaceReadTools: ToolDefinition[] = [
       properties: {
         kind: kindProp,
         current: { type: "boolean", description: "Leave out records a closed record supersedes (--current)." },
+        uncommitted: {
+          type: "boolean",
+          description: "Only the records the working tree holds modified or new against HEAD, with the checkout's branch, head and base (--uncommitted, #3160). Takes no at or since.",
+        },
         since: { type: "string", description: "A revision, or a review session id, to compare with (--since)." },
         id: { type: "string", description: "Keep only the record with this id in the document's records." },
         at: atProp,
@@ -189,6 +193,20 @@ export const workspaceReadTools: ToolDefinition[] = [
       required: ["item"],
     },
   },
+  {
+    name: "workspace-runs",
+    description:
+      "The agent runs in the workspace's run ledger on chant/lifecycle: chant workspace runs --json (runs.schema.json, #3033). Each run has who it worked for, its harness and model, its tokens and cost with the price source, the transcript pinned by hash and the commits it made, and the totals are per work item, per decision and per principal. A run that reports no cost is listed as unpriced, never counted as zero. Returns the document unchanged.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        unit: { type: "string", description: "Only the runs on this work item (--unit)." },
+        decision: { type: "string", description: "Only the runs that carried out this decision, by id or <kind>/<id> (--decision)." },
+        by: { type: "string", description: "Only the runs made for this principal (--by)." },
+        since: { type: "string", description: "Only the runs that made a commit after this revision, or started after it (--since)." },
+      },
+    },
+  },
 ];
 
 export const workspaceWriteTools: ToolDefinition[] = [
@@ -365,6 +383,13 @@ export function readArgv(tool: string, params: Record<string, unknown>): string[
       const kind = str(params, "kind");
       return ["workspace", "work", "history", item, ...(kind !== undefined ? ["--kind", kind] : []), "--json"];
     }
+    case "workspace-runs": {
+      const flags = (["unit", "decision", "by", "since"] as const).flatMap((f) => {
+        const v = str(params, f);
+        return v !== undefined ? [`--${f}`, v] : [];
+      });
+      return ["workspace", "runs", ...flags, "--json"];
+    }
     case "workspace-points": {
       const kind = str(params, "kind");
       return ["workspace", "points", ...(bool(params, "open") ? ["--open"] : []), ...(kind !== undefined ? ["--kind", kind] : []), ...atArgs, "--json"];
@@ -372,11 +397,13 @@ export function readArgv(tool: string, params: Record<string, unknown>): string[
     case "workspace-records": {
       const kind = str(params, "kind");
       const since = str(params, "since");
+      if (bool(params, "uncommitted") && (at !== undefined || since !== undefined)) throw new ToolInputError("uncommitted reads the working tree against HEAD, and takes no at or since");
       return [
         "workspace",
         "records",
         ...(kind !== undefined ? ["--kind", kind] : []),
         ...(bool(params, "current") ? ["--current"] : []),
+        ...(bool(params, "uncommitted") ? ["--uncommitted"] : []),
         ...(since !== undefined ? ["--since", since] : []),
         ...atArgs,
         "--json",

package/src/cli/registry.ts

@@ -75,6 +75,8 @@ export interface ParsedArgs {
   migrateFrom?: string;
   /** `chant import --kustomize <dir>` — render the kustomization, then import (#1548) */
   kustomize?: string;
+  /** `chant import --parser-option key[=value]`, repeatable (#2994): options for the lexicon's template parser */
+  parserOption?: string[];
   /** `chant carve advise --state <path>` — opt-in .tfstate for accurate instance counts */
   statePath?: string;
   /** `chant carve emit --select <tf-address>` — the Terraform resource to carve */
@@ -313,7 +315,7 @@ export interface ParsedArgs {
   noCache?: boolean;
   /** `chant workspace graph --composites` (#2662): print each composite instance with the components that can deploy it. */
   composites?: boolean;
-  /** `chant workspace graph --intent <path[:start-end]>` (#2651): the region the intent graph is over. Empty with `--record`. */
+  /** `chant workspace graph --intent <path[:start-end]|path#symbol>` (#2651): the region the intent graph is over. Empty with `--record`. */
   intent?: string;
   /** `chant workspace graph --intent --record <id>`: walk one decision record over every entry its constrains lists. */
   record?: string;
@@ -329,6 +331,8 @@ export interface ParsedArgs {
   severity?: string;
   /** `chant workspace records --current` (#2546): leave out records a closed record supersedes. */
   current?: boolean;
+  /** `chant workspace records --uncommitted` (#3160): only the records the working tree holds modified or new against HEAD. */
+  uncommitted?: boolean;
   /** `chant workspace records amend <id> --set <file|->` (#2670): the JSON fields to set. */
   set?: string;
   /** `chant workspace records review <id> --verdict <v>` (#2670): agree, dissent or abstain. */
@@ -344,6 +348,7 @@ export interface ParsedArgs {
   /**
    * `chant workspace records review <id> --sign [<key file>]` (#2687): the key that seals the verdict, or true for git's user.signingkey.
    * On `records new` and `records amend`, the key that seals the record's author (#2688).
+   * On `chant approve` and `chant run approve`, the key that seals the gate approval (#3163).
    */
   sign?: string | true;
   /** `chant workspace records review <id> --session <id>` (#2670): the review session the verdict was given in. */
@@ -476,6 +481,10 @@ export interface ParsedArgs {
    * project's only steward.
    */
   steward?: string;
+  /** `chant workspace runs --unit <id>` (#3033): only the agent runs on this work item. */
+  unit?: string;
+  /** `chant workspace runs --decision <id>` (#3033): only the agent runs that carried out this decision. */
+  decision?: string;
   /** `chant workspace work claim|renew|release <id> --holder <name>` (#2732): who holds, or releases, the work lease. */
   holder?: string;
   /** `chant run <op> --work <id>` (#2748): the work item an Op with a work lease runs under. `chant workspace check --changes --work <id>` (#2773): the work item in hand. */
@@ -484,7 +493,7 @@ export interface ParsedArgs {
   ttl?: string;
   /** `chant workspace work renew|release <id> --token <token>` (#2732): the fencing token the caller holds. */
   token?: string;
-  /** `chant workspace work release <id> --outcome <text>` (#2732): how the work ended, such as done or not_done. */
+  /** `chant workspace work release <id> --outcome <outcome>` (#2732): how the work ended, one of the closed list WORK_LEASE_OUTCOMES (#3147). */
   outcome?: string;
   /** `chant operator --once` (#1485) — run a single round and exit, instead of looping until Ctrl-C. Also the offline test/cron-invoker story. */
   once?: boolean;