@intentius/chant 0.102.0 → 0.104.0

package/src/cli/main.ts

@@ -347,6 +347,30 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.fromAffected = args[++i];
     } else if (arg === "--gate") {
       result.gate = args[++i];
+    } else if (arg === "--wave-gate") {
+      result.waveGate = args[++i];
+      if (!result.waveGate || result.waveGate.startsWith("-")) throw new Error("--wave-gate needs a gate name: --wave-gate <name>");
+    } else if (arg === "--wave") {
+      const raw = args[++i];
+      const wave = Number(raw);
+      if (!Number.isInteger(wave) || wave < 1) throw new Error(`--wave needs a wave number from 1: got "${raw ?? ""}"`);
+      result.wave = wave;
+    } else if (arg === "--canary") {
+      const raw = args[++i];
+      if (!raw || raw.startsWith("-")) throw new Error("--canary needs a component name: --canary <name>[,<name>...]");
+      (result.canary ??= []).push(...raw.split(",").map((n) => n.trim()).filter(Boolean));
+    } else if (arg === "--pr") {
+      const raw = args[++i];
+      const pr = Number(raw);
+      if (!Number.isInteger(pr) || pr < 1) throw new Error(`--pr needs a pull or merge request number: got "${raw ?? ""}"`);
+      result.pr = pr;
+    } else if (arg === "--forge") {
+      result.forge = args[++i];
+      if (!result.forge || result.forge.startsWith("-")) throw new Error("--forge needs a forge: --forge github|gitlab|forgejo");
+    } else if (arg === "--require-review") {
+      result.requireReview = true;
+    } else if (arg === "--pr-loop") {
+      result.prLoop = true;
     } else if (arg === "--resume") {
       result.resume = args[++i];
     } else if (arg === "--local") {
@@ -389,6 +413,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       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]|path#symbol>, or --intent --record <id>");
+    } else if (arg === "--follow-squash") {
+      // `chant workspace graph --intent ... --follow-squash` and `chant workspace runs --follow-squash` (#3035)
+      result.followSquash = true;
     } else if (arg === "--record") {
       // `chant workspace graph --intent --record <id>`
       result.record = args[++i];
@@ -423,6 +450,29 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace records amend <id> --set <file|->` (#2670)
       result.set = args[++i];
       if (!result.set || (result.set.startsWith("-") && result.set !== "-")) throw new Error("--set needs a JSON file, or - for standard input: --set <file|->");
+    } else if (arg === "--cover") {
+      // `chant workspace box listing set <member> --cover <image>` (#3308)
+      result.cover = args[++i];
+      if (!result.cover || result.cover.startsWith("-")) throw new Error("--cover needs a PNG, JPEG or WebP file: --cover <image>");
+    } else if (arg === "--cover-path") {
+      // `chant workspace box listing set <member> --cover <image> --cover-path <path>` (#3308)
+      result.coverPath = args[++i];
+      if (!result.coverPath || result.coverPath.startsWith("-")) throw new Error("--cover-path needs a path from the workspace root: --cover-path <path>");
+    } else if (arg === "--records") {
+      // `chant workspace box publish <member> --records` (#3165): the records kept uncommitted, not a work item.
+      result.records = true;
+    } else if (arg === "--expect") {
+      // `chant workspace records amend|review|close <id> --expect <digest>` (#3173): the record's digest the caller last read.
+      result.expect = args[++i];
+      if (!result.expect || result.expect.startsWith("-")) throw new Error("--expect needs the record's digest, as records --json prints it: --expect <digest>");
+    } else if (arg === "--label") {
+      // `chant workspace wip save --label <text>` (#3172)
+      result.label = args[++i];
+      if (!result.label || result.label.startsWith("-")) throw new Error("--label needs the snapshot's name, such as a turn id: --label <text>");
+    } else if (arg === "--branch") {
+      // `chant workspace wip --branch <branch>` (#3172)
+      result.branch = args[++i];
+      if (!result.branch || result.branch.startsWith("-")) throw new Error("--branch needs a branch name: --branch <branch>");
     } else if (arg === "--verdict") {
       // `chant workspace records review <id> --verdict agree|dissent|abstain` (#2670)
       result.verdict = args[++i];
@@ -437,9 +487,13 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace points --open` (#2739): only the questions still open.
       result.open = true;
     } else if (arg === "--inputs") {
-      // `chant workspace points ask <point> --inputs <file|->` (#2739)
+      // `chant workspace points ask <point> --inputs <file|-|json>` (#2739; JSON itself, #3403)
       result.inputs = args[++i];
-      if (!result.inputs || (result.inputs.startsWith("-") && result.inputs !== "-")) throw new Error("--inputs needs a JSON file, or - for standard input: --inputs <file|->");
+      if (!result.inputs || (result.inputs.startsWith("-") && result.inputs !== "-")) throw new Error("--inputs needs a JSON file, - for standard input, or the JSON itself: --inputs <file|-|json>");
+    } else if (arg === "--candidates") {
+      // `chant workspace points ask <point> --candidates <file|-|json>` (#3403): an ad-hoc point's question and candidates.
+      result.candidates = args[++i];
+      if (!result.candidates || (result.candidates.startsWith("-") && result.candidates !== "-")) throw new Error("--candidates needs a JSON file, - for standard input, or the JSON itself: --candidates <file|-|json>");
     } else if (arg === "--response") {
       // `chant workspace points ask <point> --response <file>` (#2739): a POST /v1/systemone response the caller got.
       result.response = args[++i];
@@ -508,6 +562,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.actor = args[++i];
     } else if (arg === "--approver") {
       result.approver = args[++i];
+    } else if (arg === "--relayed-by") {
+      // `chant approve <op> <gate> --relayed-by <principal>` and `workspace points answer <id> --relayed-by <principal>` (#3402):
+      // who carried the approval or answer to chant for the person it names.
+      result.relayedBy = args[++i];
+      if (!result.relayedBy || result.relayedBy.startsWith("-")) throw new Error("--relayed-by needs the principal that relayed it: --relayed-by <principal>");
     } else if (arg === "--on") {
       // `chant run ... --on <lexicon>` (#2121) — which runtime hosts the run.
       result.on = args[++i];
@@ -577,6 +636,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 === "--signer") {
+      // `chant workspace runs statement <id> --signer <principal>` (#3192): the runner principal that will sign.
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error("--signer needs a principal: --signer <principal>");
+      result.signer = 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];
@@ -659,6 +723,7 @@ export function parseArgs(args: string[]): ParsedArgs {
       // flags" isn't something this loop can name in isolation.
       throw new Error(`Unknown flag: ${arg}\nRun "chant --help" to see supported flags.`);
     } else if (!arg.startsWith("-")) {
+      if (result.command) (result.positionals ??= []).push(arg);
       if (!result.command) {
         result.command = arg;
       } else if (result.path === ".") {
@@ -777,6 +842,14 @@ Commands:
                         (--json)          its target, stage (planned/emitted/bridged/
                                           applied) and path. Read-only.
 
+Change sets:
+  change-set summary <file>  The grouped plan summary of a change-set
+                        [--format text|json|markdown]  document: members taking
+                        [--limit <chars>]  the same change grouped, every destroy,
+                                          replacement, failure and hole named.
+                                          markdown fits an MR/PR note of --limit
+                                          characters (default 65536). Read-only.
+
 Ops:
   run <name>            Run an Op on the resolved runtime (--on; local by default)
                         [--work <id>] [--holder <name>]: the work item an Op
@@ -838,7 +911,9 @@ Ops:
                         --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
+                        file at base lists for --actor. --relayed-by
+                        <principal> records who carried the approval to chant
+                        for --actor (a follower, a bot); --sign covers it
 
   graph                 Show Op dependency graph (--stacks for cross-stack order,
                         --format ir|mermaid|dot|layout for the lint-gated graph IR,
@@ -909,7 +984,7 @@ Workspace (level 1, #2524):
                         the fields hold none. --sign seals the record's author
                         (decided_by for decisions) with an ssh key. Prints
                         {path, id} as JSON and never commits
-  workspace records amend <id> [--kind <kind file>] --set <file|-> [--sign [<key file>]] [--dry-run]
+  workspace records amend <id> [--kind <kind file>] --set <file|-> [--expect <digest>] [--sign [<key file>]] [--dry-run]
                         Set top-level fields of one record. A closed record
                         never changes, and an approved one changes only its
                         state (upward), pins and reviews; anything else is
@@ -918,21 +993,30 @@ Workspace (level 1, #2524):
                         decisions) is refused with ratify-quorum-not-met
                         until its quorum is met. --sign seals the author
                         again; without it an amendment removes the author
-                        seal and says so. Prints {path, id, changed}
-  workspace records review <id> [--kind <kind file>] --verdict agree|dissent|abstain --by <principal> [--note <text>] [--session <id>] [--sign [<key file>]] [--dry-run]
+                        seal and says so. --expect refuses the write with
+                        record-conflict when the record's digest has moved
+                        on. Prints {path, id, changed, digest}
+  workspace records review <id> [--kind <kind file>] --verdict agree|dissent|abstain --by <principal> [--note <text>] [--session <id>] [--expect <digest>] [--sign [<key file>]] [--dry-run]
                         Append a review to one record, dated and bound to
                         the digest of the record text. A dissent needs
                         --note. --sign seals it with an ssh key (git's
                         user.signingkey without a file); under a signers
                         file at base only a sealed verdict counts. With
                         --session, the session must be open, and the verdict
-                        is appended to its verdicts too. Prints
-                        {path, id, review}
-  workspace records close <session id> [--kind <session kind file>] [--dry-run]
+                        is appended to its verdicts too. --expect refuses a
+                        verdict on a record that moved on. Prints
+                        {path, id, review, digest}
+  workspace records close <session id> [--kind <session kind file>] [--expect <digest>] [--dry-run]
                         Close an open review session: its state, close time,
                         closing commit and seal, in one write. Without
                         --kind, the one session kind the declaration names.
                         Prints {path, id, changed, seal, closedRev}
+                        Every working-tree write holds the working tree's
+                        write lock (CHANT_WRITE_LOCK_WAIT_MS, default 15s)
+  workspace lock [acquire --holder <name> [--ttl <duration>] | release --token <token>] [--json]
+                        Who holds the working tree's write lock; take it for
+                        a batch of writes across chant calls, each run with
+                        CHANT_WRITE_LOCK=<token>, and give it back
   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
@@ -950,12 +1034,14 @@ Workspace (level 1, #2524):
                         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]
+  workspace runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>] [--follow-squash] [--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
+                        Read-only, never fetches; --follow-squash joins each
+                        squash merge to its pull request's runs, fetching a
+                        missing refs/pull/<n>/head from origin
   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
@@ -966,18 +1052,65 @@ Workspace (level 1, #2524):
                         and the commits it made
   workspace runs record --from <file|->
                         Record a finished run, its start and end in one write
+  workspace runs sign <run id> (--key <runner.pem> | --envelope <file|->) [--base <rev>]
+                        Store a DSSE statement over an ended run (its record's
+                        hash, work item, harness, model and commits), signed
+                        with a runner or steward key .chant/trust.json lists
+                        at base, or signed elsewhere and checked here
+  workspace runs statement <run id> --signer <principal>
+                        Print the statement for a signer whose key is
+                        elsewhere, such as a lobby, with the payload to sign
+  workspace runs verify [<run id>] [--require signed] [--base <rev>] [--json]
+                        Judge each run's stored statements against the runner
+                        keys at base. Reports only, unless --require signed
+  workspace box listing set <member> [--from <file|->] [--cover <image> [--cover-path <path>]] [--by <principal>] [--dry-run]
+                        Change a box's listing (published, title, line, cover)
+                        in the declaration, in place, keeping its formatting
+                        and comments; --cover copies a PNG, JPEG or WebP into
+                        the repository. Judged by the write scope at base.
+                        Prints the box-listing-write document; never commits
+  workspace box publish <member> (<item> | --records) [--by <principal>] [--head <owner/name>] [--dry-run]
+                        Publish a built work item, or the records kept
+                        uncommitted, through the publisher the box block names:
+                        run with a JSON request on stdin, its answer checked
+                        and its commit held to the apply record (ws-088).
+                        Prints the box-publish document; chant itself never
+                        commits, pushes or calls a forge
+  workspace wip [--branch <branch>] [--json]
+                        List the work-in-progress snapshots under
+                        refs/chant/wip/<branch>, newest first, and how far each
+                        ref the box's replicate policy names is from its remote.
+                        Reads locally; never fetches (#3172)
+  workspace wip save [--label <text>] [--by <principal>]
+                        Snapshot the whole working tree, uncommitted records
+                        included, onto refs/chant/wip/<branch> without touching
+                        the index or the branch; pushes when the policy says so
+  workspace wip restore [<snapshot>] [--by <principal>]
+                        Put the working tree back as the snapshot (the branch's
+                        latest by default) holds it, after a snapshot of how it
+                        is now; HEAD never moves
+  workspace wip push    Push the refs the box's replicate policy names to its
+                        remote, never forced, for the host's schedule
+  workspace wip fetch   On a replacement box, bring back what was replicated:
+                        create or fast-forward the local refs, then wip restore
   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;
                         --open keeps the escalated and proposed ones (ws-058)
-  workspace points ask <point> --inputs <file|-> [--response <file>] [--subject <id>] [--kind <kind file>] [--dry-run]
+  workspace points ask <point> --inputs <file|-|json> [--candidates <file|-|json>] [--response <file>] [--subject <id>] [--kind <kind file>] [--dry-run]
                         Ask a point's table, model and quorum deciders and
                         record the answer: proposed from a model, escalated to
                         people below its threshold. --response is a POST
-                        /v1/systemone response the caller got; chant calls no model
-  workspace points answer <id> --answer <value> --by <name>... [--kind <kind file>] [--dry-run]
+                        /v1/systemone response the caller got; chant calls no model.
+                        --candidates gives an ad-hoc point's question and
+                        candidates, { question, criteria }
+  workspace points answer <id> --answer <value> --by <name>... [--note <text>] [--relayed-by <principal>] [--kind <kind file>] [--dry-run]
                         Record people's answer to an open question, or confirm
-                        a model's proposal, once the point's quorum is met
+                        a model's proposal, once the point's quorum is met,
+                        with their note and who relayed it
+  workspace points retract <id> --by <name>... [--note <text>] [--kind <kind file>] [--dry-run]
+                        Take an answer back: the question is open for people
+                        again, and the answer stays in its retractions
   workspace pin <path> [--json]
                         Print the integrity value that pins the plugin at
                         <path>, to put in a path pin of chant.workspace.json.
@@ -987,13 +1120,14 @@ Workspace (level 1, #2524):
                         member it is bound to, the record kinds and verbs its
                         write scope allows, and the spec records --current
                         prints. Without a name, the session CHANT_AGENT names
-  workspace verify [--base <rev>] [--head <rev>] [--require attested]
+  workspace verify [--base <rev>] [--head <rev>] [--require attested | attested-runs]
                         Check the commits in base..head against the signers
                         and roles read from base. A change to the signers file
                         or .chant/trust.json needs a signature by a signer
                         trusted at base, and a new signer set needs a
-                        threshold of the old one. Does nothing without a
-                        signers file
+                        threshold of the old one. A commit an agent run made
+                        is attested by the run's signed statement; with
+                        attested-runs, only those commits must be
   workspace signers [--json] [rotate [--threshold <n>] | sign --key <file>]
                         Show the signer history at base, or propose the next
                         signer set and sign it with a current signer's key
@@ -1101,12 +1235,14 @@ 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]|path#symbol> [--at <rev>] [--kind <kind file>...] [--json]
+  workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--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.
-                        Without --kind, every record kind the declaration names
-  workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--json]
+                        Without --kind, every record kind the declaration names.
+                        --follow-squash follows a squash merge to its pull
+                        request's commits, fetching a missing ref from origin
+  workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]
                         One decision's intent walk over every path: and member:
                         entry it constrains: the commits in its window, each
                         own, worked, within-other or unexplained, with counts
@@ -1156,8 +1292,23 @@ Component release ledger + status:
                             (--base <ref> [--head <ref>] [--include-dependents],
                              or --from-affected <file>; --dry-run prints the
                              derivation and dispatches nothing; --gate <name>
-                             puts one approval over the whole set; --resume
-                             <file> finishes an attempt that stopped)
+                             puts one approval over the whole set;
+                             --wave-gate <name> puts one on each wave, planned
+                             when the wave is reached, with --canary <name>
+                             for wave 1 and --wave <n> for one wave per CI
+                             job; --resume <file> finishes an attempt that
+                             stopped)
+  components pr-plan       Plan the components a pull request reaches and
+                            the ones that depend on them, and write the
+                            report and note (--base <ref> --pr <n>
+                            [--forge github|gitlab|forgejo] posts them);
+                            applies nothing
+  components pr-apply      On merge: plan the same members again and apply
+                            them only if an approval stands for that digest
+                            (chant approve pr-<n> pr-apply --plan <digest>);
+                            a moved plan refuses with exit 3
+                            (--require-review: the approver must have
+                            approved the pull request on the forge)
   components release <env> Append one immutable release record
                             (--component <name> --digest <sha256:...>
                              [--git-sha <sha>] [--run-id <id>] [--actor <name>]);
@@ -1564,6 +1715,8 @@ export const commandRegistry: CommandDef[] = [
   // Status read over a tree of carve manifests (#2038): the contract a
   // renderer replaces its own walk-and-guess discovery with. Read-only.
   { name: "carve status", handler: runCarveStatus },
+  // #3188 — the grouped plan summary of a change-set document. Reads one file; imported on first use.
+  { name: "change-set summary", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/change-set")).runChangeSetSummary(ctx) },
   { name: "init", handler: runInit, runsNoConfig: true },
   { name: "init lexicon", handler: runInitLexicon },
 { name: "update", handler: runUpdate },
@@ -1630,6 +1783,12 @@ export const commandRegistry: CommandDef[] = [
   { name: "workspace graph", handler: async (ctx) => (await import("../workspace/member-commands")).runWorkspaceMembers(ctx, "graph") },
   // Each unit decides for itself whether its config is loaded (runCommandInProcess).
   { name: "workspace member-run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-run")).runWorkspaceMemberRun(ctx, runCommandInProcess) },
+  // #3308 — a box's listing, written through chant so a tool never edits the declaration itself (ws-074).
+  { name: "workspace box", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/box-cli")).runWorkspaceBox(ctx) },
+  // #3173 — the working tree's write lock, held across chant calls for a batch of writes (ws-089).
+  { name: "workspace lock", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/write-lock-cli")).runWorkspaceLock(ctx) },
+  // #3172 — work in progress under refs/chant/wip/<branch>, replicated under the box's policy (ws-085).
+  { name: "workspace wip", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/wip-cli")).runWorkspaceWip(ctx) },
   { name: "workspace pin", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/pin-cli")).runWorkspacePin(ctx) },
   // #2548 — an agent session's member, write scope and spec, for a session that resumes.
   { name: "workspace agent", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/agent-cli")).runWorkspaceAgent(ctx) },
@@ -1655,6 +1814,9 @@ export const commandRegistry: CommandDef[] = [
 
   // Component release ledger + status surface (#568, epic #551)
   { name: "components fan-out", requiresPlugins: true, handler: runComponentsFanOut },
+  // #3183 — the pull-request loop the generated CI runs. Imported on first use.
+  { name: "components pr-plan", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrPlan(ctx) },
+  { name: "components pr-apply", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrApply(ctx) },
   { name: "components status", requiresPlugins: true, handler: runComponentsStatus },
   { name: "components release", handler: runComponentsReleaseRecord },
   { name: "components export", handler: runComponentsExport },

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

@@ -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", "workspace-runs", "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 () => {