@intentius/chant 0.101.0 → 0.104.0

package/src/cli/mcp/never-over-mcp.test.ts

@@ -0,0 +1,101 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendPendingGate, readGateLedger } from "../../lifecycle/gate-ledger";
+import { resetGateOrigin } from "../../lifecycle/gate-origin";
+
+const started = vi.fn();
+const resolveGate = vi.fn();
+
+vi.mock("../../op/discover", () => ({
+  discoverOps: async () => ({
+    errors: [],
+    ops: new Map([
+      ["tf-apply", { config: { name: "tf-apply", overview: "apply", phases: [], neverOverMcp: true } }],
+      ["plain-op", { config: { name: "plain-op", overview: "plain", phases: [] } }],
+    ]),
+  }),
+}));
+
+vi.mock("../../op/runtimes/local", () => ({
+  createLocalOpRuntime: () => ({
+    name: "local",
+    start: async (config: { name: string }) => {
+      started(config.name);
+      return { result: async () => ({ op: config.name, runId: "r1", state: "succeeded", startedAt: "t" }) };
+    },
+    status: async () => undefined,
+    list: async () => new Map(),
+    resolveGate,
+  }),
+}));
+
+import { createOpApproveTool, createOpRunTool, createOpStatusTool, createOpReportTool } from "./op-tools";
+
+function git(args: string[], cwd: string): void {
+  spawnSync("git", args, { cwd, encoding: "utf-8" });
+}
+
+describe("neverOverMcp (chant#3447)", () => {
+  const cwd = process.cwd();
+  beforeEach(() => {
+    started.mockClear();
+    resolveGate.mockClear();
+  });
+  afterEach(() => {
+    process.chdir(cwd);
+    resetGateOrigin();
+  });
+
+  test("op-approve refuses a CI-reached gate of a declared Op and the ledger is unchanged", async () => {
+    await withTestDir(async (dir) => {
+      git(["init", "-q", "-b", "main"], dir);
+      git(["config", "user.email", "t@chant.dev"], dir);
+      git(["config", "user.name", "T"], dir);
+      writeFileSync(join(dir, "README.md"), "x\n");
+      git(["add", "."], dir);
+      git(["commit", "-q", "-m", "init"], dir);
+
+      // A gate reached on forge CI, not over MCP: the same-origin rule would let it through.
+      await appendPendingGate(
+        {
+          op: "tf-apply",
+          gate: "wave-2",
+          timestamp: "2026-01-01T00:00:00.000Z",
+          origin: "cli",
+          expiresAt: "2999-01-01T00:00:00.000Z",
+          planDigest: `sha256:${"a".repeat(64)}`,
+        },
+        { cwd: dir },
+      );
+      const before = await readGateLedger("tf-apply", { cwd: dir });
+      expect(before.pending).toHaveLength(1);
+
+      process.chdir(dir);
+      await expect(createOpApproveTool().handler({ name: "tf-apply", gate: "wave-2" })).rejects.toThrow(
+        /neverOverMcp.*whichever channel/s,
+      );
+
+      expect(await readGateLedger("tf-apply", { cwd: dir })).toEqual(before);
+      expect(resolveGate).not.toHaveBeenCalled();
+    });
+  });
+
+  test("op-run refuses a declared Op and starts nothing", async () => {
+    await expect(createOpRunTool().handler({ name: "tf-apply" })).rejects.toThrow(/neverOverMcp.*chant run tf-apply/s);
+    expect(started).not.toHaveBeenCalled();
+  });
+
+  test("an Op that does not declare it still runs", async () => {
+    const result = (await createOpRunTool().handler({ name: "plain-op" })) as { state: string };
+    expect(result.state).toBe("succeeded");
+    expect(started).toHaveBeenCalledWith("plain-op");
+  });
+
+  test("op-status and op-report still answer for a declared Op", async () => {
+    await expect(createOpStatusTool().handler({ name: "tf-apply" })).resolves.toMatchObject({ op: "tf-apply" });
+    await expect(createOpReportTool().handler({ name: "tf-apply" })).resolves.toContain("# tf-apply");
+  });
+});

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

@@ -53,6 +53,21 @@ async function runtimeFor(name: unknown): Promise<OpRuntimeProvider> {
   return plugin.opRuntime;
 }
 
+/**
+ * The refusal for an Op that declares `neverOverMcp`, or `undefined` when MCP
+ * may act on it. It names the rule and the way through, which is a person at a
+ * shell. An Op that is not discovered is left to the caller's own not-found
+ * handling.
+ */
+async function neverOverMcpRefusal(name: string, action: "run" | "approve"): Promise<string | undefined> {
+  const { ops } = await discoverOps();
+  if (!ops.get(name)?.config.neverOverMcp) return undefined;
+  return action === "run"
+    ? `Op "${name}" declares neverOverMcp, so it is not run over MCP. Run it at a shell with \`chant run ${name}\`; op-status and op-report still answer here.`
+    : `Op "${name}" declares neverOverMcp, so its gates are not resolved over MCP, whichever channel reached them. ` +
+        `Approvals belong to people: approve at a shell with \`chant approve ${name} <gate>\`.`;
+}
+
 const RUNTIME_PARAM = {
   type: "string",
   description: 'Runtime to address: a lexicon name with an opRuntime, or "local" (the default)',
@@ -103,7 +118,8 @@ export function createOpRunTool(): ToolRegistration {
     definition: {
       name: "op-run",
       description:
-        "Run an Op on a runtime and return its result. Defaults to the built-in local runtime, which executes the Op in this process.",
+        "Run an Op on a runtime and return its result. Defaults to the built-in local runtime, which executes the Op in this process. " +
+        "Refuses an Op that declares neverOverMcp.",
       inputSchema: {
         type: "object",
         properties: {
@@ -117,6 +133,8 @@ export function createOpRunTool(): ToolRegistration {
       const name = params.name as string;
 
       const { ops } = await discoverOps();
+      const refusal = await neverOverMcpRefusal(name, "run");
+      if (refusal) throw new Error(refusal);
       if (!ops.has(name)) {
         const available = [...ops.keys()];
         return `Op "${name}" not found. Available: ${available.join(", ") || "none"}`;
@@ -185,7 +203,8 @@ export function createOpApproveTool(): ToolRegistration {
         "Record a gate's resolution on the gate ledger and wake the runtime hosting the gated run. " +
         "Refuses a gate this same channel reached: a run started with op-run must be approved from " +
         "somewhere else, normally `chant approve <op> <gate>` at a shell. The approver is recorded as " +
-        "unattested, because this channel cannot verify a name.",
+        "unattested, because this channel cannot verify a name. Also refuses every gate of an Op that " +
+        "declares neverOverMcp, whatever channel reached the gate.",
       inputSchema: {
         type: "object",
         properties: {
@@ -206,6 +225,9 @@ export function createOpApproveTool(): ToolRegistration {
       const gate = params.gate as string;
       if (!name || !gate) throw new Error("op-approve needs both an Op name and a gate name");
 
+      const refusal = await neverOverMcpRefusal(name, "approve");
+      if (refusal) throw new Error(refusal);
+
       const runtime = await runtimeFor(params.runtime);
       const outcome = await recordGateApproval(name, gate, {
         note: params.note as string | undefined,

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", "points-retract"]);
   });
 
   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
@@ -15,8 +15,9 @@
  *   read to the workspace root's pinned chant included (ws-021), and keeps
  *   anything a command prints away from the protocol on stdout.
  * - The writes (`records-new`, `records-amend`, `records-review`,
- *   `records-close`, `points-answer`) call the functions `chant workspace
- *   records new|amend|review|close` and `points answer` call, and return the
+ *   `records-close`, `points-answer`, `points-retract`) call the functions
+ *   `chant workspace records new|amend|review|close` and `points
+ *   answer|retract` call, and return the
  *   same JSON result. They keep every rule
  *   the CLI keeps: the kind's schema, a closed record never changing, an
  *   approved one changing only as its approval rule allows, a dissent needing
@@ -111,7 +112,8 @@ 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." },
+        followSquash: { type: "boolean", description: "With intent: follow squash merges to their pull requests' original commits (--follow-squash, #3035), fetching a pull request ref the clone lacks from origin. Off by default, so a read never reaches the network." },
         composites: { type: "boolean", description: "The composites document instead (--composites). Takes no kind or intent." },
         at: atProp,
       },
@@ -146,6 +148,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 +195,21 @@ 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)." },
+        followSquash: { type: "boolean", description: "Join each squash merge on HEAD to the runs its pull request's original commits joined (--follow-squash, #3035), fetching a pull request ref the clone lacks from origin." },
+      },
+    },
+  },
 ];
 
 export const workspaceWriteTools: ToolDefinition[] = [
@@ -268,7 +289,7 @@ export const workspaceWriteTools: ToolDefinition[] = [
   {
     name: "points-answer",
     description:
-      "Record people's answer to an open decision point question, or confirm a model's proposal: chant workspace points answer. Refused unless the point's quorum is met: distinct people, none holding the agent role, each holding one of the quorum's roles when it names any. An answered question never changes. " +
+      "Record people's answer to an open decision point question, or confirm a model's proposal: chant workspace points answer. Refused unless the point's quorum is met: distinct people, none holding the agent role, each holding one of the quorum's roles when it names any. An answered question never changes in place: points-retract takes it back. " +
       PROTOCOL,
     inputSchema: {
       type: "object",
@@ -276,12 +297,31 @@ export const workspaceWriteTools: ToolDefinition[] = [
         id: { type: "string", description: "The question's id, as workspace-points lists it." },
         answer: { type: ["string", "boolean"], description: "One of the question's candidates; for a noul, true or false." },
         by: { type: "array", items: { type: "string" }, description: "Each person who answered (--by)." },
+        note: { type: "string", description: "What the people who answered say with it, kept on the answer (--note)." },
+        relayedBy: { type: "string", description: "Who relayed the answer for the people in by, such as a follower; recorded as relayed_by and not counted toward the quorum (--relayed-by)." },
         kind: { type: "string", description: "The answer kind file. Without it, the declared answer kinds." },
         dryRun: dryRunProp,
       },
       required: ["id", "answer", "by"],
     },
   },
+  {
+    name: "points-retract",
+    description:
+      "Take back people's answer to a decision point question: chant workspace points retract. The question is escalated to people again, and the answer, who gave it and its note stay in the record's retractions with who retracted it, when and why. Refused unless the point's quorum is met, counted as for an answer. " +
+      PROTOCOL,
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The question's id, as workspace-points lists it." },
+        by: { type: "array", items: { type: "string" }, description: "Each person who takes the answer back (--by)." },
+        note: { type: "string", description: "Why, kept on the retraction (--note)." },
+        kind: { type: "string", description: "The answer kind file. Without it, the declared answer kinds." },
+        dryRun: dryRunProp,
+      },
+      required: ["id", "by"],
+    },
+  },
 ];
 
 /** A tool call that can't be made as given: the client gets it as an error result, and nothing runs. */
@@ -337,7 +377,7 @@ export function readArgv(tool: string, params: Record<string, unknown>): string[
       const composites = bool(params, "composites");
       const kindArgs = kinds(params).flatMap((k) => ["--kind", k]);
       if (composites) return ["workspace", "graph", "--composites", ...kindArgs, ...(intent !== undefined ? ["--intent", intent] : []), ...atArgs, "--json"];
-      if (intent !== undefined) return ["workspace", "graph", "--intent", intent, ...kindArgs, ...atArgs, "--json"];
+      if (intent !== undefined) return ["workspace", "graph", "--intent", intent, ...kindArgs, ...atArgs, ...(bool(params, "followSquash") ? ["--follow-squash"] : []), "--json"];
       return ["workspace", "graph", ...kindArgs, ...atArgs, "--json"];
     }
     case "workspace-changes": {
@@ -365,6 +405,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, ...(bool(params, "followSquash") ? ["--follow-squash"] : []), "--json"];
+    }
     case "workspace-points": {
       const kind = str(params, "kind");
       return ["workspace", "points", ...(bool(params, "open") ? ["--open"] : []), ...(kind !== undefined ? ["--kind", kind] : []), ...atArgs, "--json"];
@@ -372,11 +419,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",
@@ -520,7 +569,13 @@ export function createWorkspaceTools(options: WorkspaceToolsOptions): WorkspaceT
       if (typeof answer !== "string" && typeof answer !== "boolean") throw new ToolInputError("answer must be a string, or true or false");
       const by = params.by;
       if (!Array.isArray(by) || by.length === 0 || !by.every((b) => typeof b === "string" && b.trim() !== "")) throw new ToolInputError("by must list each person who answered");
-      return answerPoint({ cwd, id: str(params, "id", true)!, answer, by: by as string[], kind: str(params, "kind"), dryRun: bool(params, "dryRun") });
+      return answerPoint({ cwd, id: str(params, "id", true)!, answer, by: by as string[], note: str(params, "note"), relayedBy: str(params, "relayedBy"), kind: str(params, "kind"), dryRun: bool(params, "dryRun") });
+    },
+    "points-retract": async (params) => {
+      const { retractAnswer } = await import("../../workspace/decide");
+      const by = params.by;
+      if (!Array.isArray(by) || by.length === 0 || !by.every((b) => typeof b === "string" && b.trim() !== "")) throw new ToolInputError("by must list each person who takes the answer back");
+      return retractAnswer({ cwd, id: str(params, "id", true)!, by: by as string[], note: str(params, "note"), kind: str(params, "kind"), dryRun: bool(params, "dryRun") });
     },
     "records-close": async (params) => {
       const w = await write();

package/src/cli/registry.ts

@@ -9,6 +9,8 @@ export interface ParsedArgs {
   path: string;
   extraPositional?: string;
   extraPositional2?: string;
+  /** Every positional after the command word, in order (#3308): for a command with more than three, such as `workspace box listing set <member>`. */
+  positionals?: string[];
   output?: string;
   format: string;
   force?: boolean;
@@ -75,6 +77,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 */
@@ -236,6 +240,42 @@ export interface ParsedArgs {
    * ungated. A component's own authored gates are unaffected either way.
    */
   gate?: string;
+  /**
+   * `chant components fan-out --wave-gate <name>` (#3049) — one gate per wave
+   * instead of one over the set. Wave `n` waits on `<name>-wave-<n>`, bound to
+   * that wave's set digest, and is planned only once the waves before it
+   * applied. Also `chant build --components --generate <lexicon> --wave-gate
+   * <name>`, which generates one CI job per wave.
+   */
+  waveGate?: string;
+  /** `chant components fan-out --wave <n>` (#3049) — run wave `n` of a `--wave-gate` fan-out and no other. */
+  wave?: number;
+  /** `chant components fan-out --canary <component>` (#3049), repeatable — components that form wave 1. */
+  canary?: string[];
+  /**
+   * `chant components pr-plan|pr-apply --pr <n>` (#3183) — the pull or merge
+   * request the plan belongs to. Its gate is recorded under op `pr-<n>`.
+   * pr-apply finds it from the commit through `--forge` when omitted.
+   */
+  pr?: number;
+  /**
+   * `chant components pr-plan|pr-apply --forge github|gitlab|forgejo` (#3183)
+   * — post the note and the commit status on this forge, with the client
+   * read from the CI job's environment.
+   */
+  forge?: string;
+  /**
+   * `chant components pr-apply --require-review` (#3183) — count an approval
+   * only when its approver has a standing approving review on the pull
+   * request. Needs `--forge`.
+   */
+  requireReview?: boolean;
+  /**
+   * `chant build --components --generate <lexicon> --pr-loop` (#3183) —
+   * generate the pull-request pipeline: plan on the pull request, apply on
+   * merge bound to the approved digest.
+   */
+  prLoop?: boolean;
   /**
    * `chant components fan-out --resume <file>` (#2420) — the attempt record
    * this fan-out reads before it starts and writes when it finishes. Repeating
@@ -301,8 +341,10 @@ export interface ParsedArgs {
   bys?: string[];
   /** `chant workspace points --open` (#2739): only the questions still open. */
   open?: boolean;
-  /** `chant workspace points ask <point> --inputs <file|->` (#2739): the inputs, as a JSON object. */
+  /** `chant workspace points ask <point> --inputs <file|-|json>` (#2739): the inputs, as a JSON object. */
   inputs?: string;
+  /** `chant workspace points ask <point> --candidates <file|-|json>` (#3403): an ad-hoc point's question and candidates. */
+  candidates?: string;
   /** `chant workspace points ask <point> --response <file>` (#2739): a POST /v1/systemone response the caller got from a backend. */
   response?: string;
   /** `chant workspace points ask <point> --subject <id>` (#2739): what the question is about. */
@@ -313,8 +355,10 @@ 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` and `chant workspace runs` (#3035): follow squash merges to their pull requests' original commits, fetching missing pull request refs. */
+  followSquash?: boolean;
   /** `chant workspace graph --intent --record <id>`: walk one decision record over every entry its constrains lists. */
   record?: string;
   /** `chant workspace patch <range> --path <p>`: only these paths, from the workspace root. Repeatable. */
@@ -329,10 +373,24 @@ 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 amend|review|close <id> --expect <digest>` (#3173): the record's digest the caller last read; the write is refused with record-conflict when it has moved on. */
+  expect?: string;
   /** `chant workspace records review <id> --verdict <v>` (#2670): agree, dissent or abstain. */
   verdict?: string;
+  /** `chant workspace box listing set <member> --cover <image>` (#3308): a PNG, JPEG or WebP picture to copy in as the box's cover. */
+  cover?: string;
+  /** `chant workspace box listing set <member> --cover <image> --cover-path <path>` (#3308): where the cover goes, from the workspace root. */
+  coverPath?: string;
+  /** `chant workspace box publish <member> --records` (#3165): publish the records kept uncommitted instead of a work item. */
+  records?: boolean;
+  /** `chant workspace wip save --label <text>` (#3172): what the caller calls the snapshot, such as a turn id. */
+  label?: string;
+  /** `chant workspace wip --branch <branch>` (#3172): list one branch's snapshots. */
+  branch?: string;
   /**
    * `chant workspace records review <id> --by <principal>` (#2670): the
    * reviewer, as the caller names them. Also `chant workspace records new
@@ -344,8 +402,15 @@ 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 approve <op> <gate> --relayed-by <principal>` and `chant workspace
+   * points answer <id> --relayed-by <principal>` (#3402): the principal that
+   * carried the approval or answer to chant on behalf of the person it names.
+   */
+  relayedBy?: string;
   /** `chant workspace records review <id> --session <id>` (#2670): the review session the verdict was given in. */
   session?: string;
   /** `chant workspace records new <kind> --prefix <prefix>` (#2670): the id prefix to allocate under. */
@@ -360,6 +425,8 @@ export interface ParsedArgs {
   claim?: string;
   /** `chant workspace evidence sign --environment <file>` (#2553): the runner environment, hashed into the evidence. */
   environment?: string;
+  /** `chant workspace runs statement <id> --signer <principal>` (#3192): the runner principal that will sign. */
+  signer?: string;
   /** `chant workspace evidence verify --envelope <file>` (#2553). */
   envelope?: string;
   /** `chant workspace signers rotate --threshold <n>` (#2553). */
@@ -476,6 +543,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 +555,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;