@intentius/chant 0.91.0 → 0.94.0

package/src/cli/handlers/graph.ts

@@ -21,6 +21,7 @@ import { toDot } from "../../graph-dot";
 import { getLayoutEngine, toLayoutInput, type NodeSize } from "../../graph-layout";
 import { lintCommand } from "../commands/lint";
 import { loadPlugins, resolveProjectLexicons, collectBuildRootContributors } from "../plugins";
+import { isNoLexiconDetected } from "../../detectLexicon";
 import { readFileSync } from "node:fs";
 import { formatError, formatWarning, formatBold } from "../format";
 import type { CommandContext, ParsedArgs } from "../registry";
@@ -31,6 +32,19 @@ import type { BuildParamProvenance } from "../../provenance";
 import { discoverComponents } from "../../components/discover";
 import { cfnDeployStacks } from "./components";
 
+/**
+ * The project's lexicons, or none for a project that declares none and imports
+ * none (an Ops-only member, `lexicons: []`): detection's NO_LEXICON_DETECTED
+ * sentinel means "no lexicon", as `chant lint` reads it, not a failed graph (#2841).
+ */
+async function projectLexiconsOrNone(projectPath: string): Promise<string[]> {
+  try {
+    return await resolveProjectLexicons(projectPath);
+  } catch (err) {
+    if (isNoLexiconDetected(err)) return [];
+    throw err;
+  }
+}
 
 /**
  * Resolve this invocation's declared build-time parameters, the same way
@@ -223,7 +237,7 @@ async function runGraphLive(
   // `graph` is not `requiresPlugins` (Op/source-graph modes must work without a
   // lexicon), so `ctx.plugins` is empty. The live path needs the project's
   // observation plugins — load them here, mirroring the lifecycle handlers.
-  const plugins = ctx.plugins.length > 0 ? ctx.plugins : await loadPlugins(await resolveProjectLexicons(projectPath));
+  const plugins = ctx.plugins.length > 0 ? ctx.plugins : await loadPlugins(await projectLexiconsOrNone(projectPath));
   const declaredEnvNames = environmentNames(config.environments);
   if (declaredEnvNames && !matchesDeclaredEnvironment(config.environments, environment)) {
     console.error(formatError({
@@ -828,7 +842,7 @@ async function runGraphView(
   {
     const plugins = ctx.plugins.length > 0
       ? ctx.plugins
-      : await loadPlugins(await resolveProjectLexicons(projectPath));
+      : await loadPlugins(await projectLexiconsOrNone(projectPath));
     const predicted = await predictOntoIr(ir, plugins as LexiconPlugin[], ctx.args, {
       // No environment on the declared path: the file is not deployed anywhere
       // yet, and naming one would claim it was.

package/src/cli/handlers/operator.ts

@@ -29,7 +29,7 @@ import {
 } from "../../op/operator";
 import { readLease, releaseLease, currentHolderId, DEFAULT_LEASE_TTL_MS } from "../../lifecycle/lease";
 import { readConvergeLedger, type ConvergeTickRecord } from "../../lifecycle/converge-ledger";
-import { readRunLedger } from "../../lifecycle/run-ledger";
+import { readRunLedger, runEnvOf } from "../../lifecycle/run-ledger";
 import type { OpRunRecord } from "../../op/runtime";
 import type { GateResolutionRecord, PendingGateRecord } from "../../lifecycle/gate-ledger";
 import {
@@ -413,6 +413,12 @@ async function statusFor(opName: string, env: string, cwd?: string): Promise<OpS
 export interface StandaloneGateLine {
   op: string;
   gate: string;
+  /**
+   * The Op whose newest run stopped at this gate, when the gate is a
+   * command's own rather than the Op's (#2779): a step running `chant
+   * workspace upgrade` stops its run at `workspace-upgrade` / `<scope>`.
+   */
+  run?: string;
   description?: string;
   expiresAt: string;
   url?: string;
@@ -458,6 +464,32 @@ export async function runOperatorStatus(ctx: CommandContext): Promise<number> {
     }
   }
 
+  // A gate a command decided inside an Op's step (#2779) is recorded under
+  // the command's op, which is not an `*.op.ts`, so the loop above never
+  // reads it. The Op's newest run names it; list it against that Op while it
+  // still stands.
+  for (const [opName, discovered] of [...allOps.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    let newest: OpRunRecord | undefined;
+    try {
+      newest = (await readRunLedger(runEnvOf(discovered.config), opName)).records.at(-1);
+    } catch {
+      continue;
+    }
+    const gateOp = newest?.status === "gated" ? newest.gate?.op : undefined;
+    if (!newest?.gate || !gateOp || gateOp === opName) continue;
+    const record = (await pendingGatesFor(gateOp)).find((r) => r.gate === newest.gate!.name);
+    if (!record || covered.has(`${gateOp} ${record.gate}`)) continue;
+    covered.add(`${gateOp} ${record.gate}`);
+    standalone.push({
+      op: gateOp,
+      gate: record.gate,
+      run: opName,
+      expiresAt: record.expiresAt,
+      ...(record.description ? { description: record.description } : {}),
+      ...(record.url ? { url: record.url } : {}),
+    });
+  }
+
   if (ops.length === 0 && standalone.length === 0) {
     console.error(formatWarning({ message: "No ConvergeOp declarations found" }));
     return 0;
@@ -494,7 +526,7 @@ export async function runOperatorStatus(ctx: CommandContext): Promise<number> {
   if (standalone.length > 0) {
     console.log(formatBold("pending gates (no converge tick)"));
     for (const g of standalone) {
-      console.log(`  - ${g.op} gate "${g.gate}" — resolve: chant approve ${g.op} ${g.gate}`);
+      console.log(`  - ${g.op} gate "${g.gate}"${g.run ? ` (Op ${g.run}'s run stopped here)` : ""} — resolve: chant approve ${g.op} ${g.gate}`);
       if (g.description) console.log(`    ${g.description}`);
       console.log(`    expires: ${g.expiresAt}`);
       if (g.url) console.log(`    approve at: ${g.url}`);

package/src/cli/handlers/run.test.ts

@@ -5,6 +5,13 @@ import { join } from "node:path";
 import type { ParsedArgs } from "../registry";
 
 const discoverOpsMock = vi.fn();
+// Default: no steward owns anything discovered, so `stewardTurnGate` (#2750)
+// is a no-op for every test that doesn't explicitly set up a steward — a
+// `mockResolvedValueOnce` in those tests overrides it for one call and this
+// default is what every other call sees.
+const discoverStewardsMock = vi.fn().mockResolvedValue({ stewards: new Map(), errors: [], conflicts: [] });
+const acquireStewardTurnMock = vi.fn();
+const releaseLeaseMock = vi.fn();
 const loadChantConfigMock = vi.fn();
 const writeFileSyncMock = vi.fn();
 const mkdirSyncMock = vi.fn();
@@ -18,7 +25,18 @@ const recordGateApprovalMock = vi.fn();
 const { memoryGateLedgerPort } = await vi.importActual<typeof import("../../op/gate")>("../../op/gate");
 let gateLedger = memoryGateLedgerPort();
 
-vi.mock("../../op/discover", () => ({ discoverOps: () => discoverOpsMock() }));
+vi.mock("../../op/discover", () => ({
+  discoverOps: () => discoverOpsMock(),
+  discoverStewards: () => discoverStewardsMock(),
+}));
+vi.mock("../../op/operator", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../op/operator")>();
+  return { ...actual, acquireStewardTurn: (...args: unknown[]) => acquireStewardTurnMock(...args) };
+});
+vi.mock("../../lifecycle/lease", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../lifecycle/lease")>();
+  return { ...actual, releaseLease: (...args: unknown[]) => releaseLeaseMock(...args) };
+});
 vi.mock("../../config", async () => {
   const actual = await vi.importActual<typeof import("../../config")>("../../config");
   return { ...actual, loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args) };
@@ -288,6 +306,138 @@ describe("runOp dispatcher", () => {
   });
 });
 
+/**
+ * chant #2750 — an Op a declared steward lists is one of its turns, not a
+ * run beside one: `chant run <op>` for such an Op takes the steward's turn
+ * lease (in the local form) or is redirected to the steward's thread (on
+ * fountain), rather than running unaware of a turn already in progress.
+ *
+ * `acquireStewardTurn` and `releaseLease` are stubbed here (mocked above):
+ * the point of these tests is the CLI's own decision and its message, not
+ * the lease's git plumbing, which `op/steward.test.ts` and
+ * `lifecycle/lease.test.ts` already cover against a real repo.
+ */
+describe("runOp: a steward's turn (#2750)", () => {
+  function stewardOwning(opName: string, name: string, form: "local" | "fountain" = "local") {
+    return {
+      stewards: new Map([[name, {
+        declaration: {
+          kind: "Chant::Steward", name, ops: [{ name: opName, phases: [] }],
+          form: { default: form, environments: {} }, capabilities: [], vault: null,
+        },
+        filePath: "ops/steward.op.ts", exportName: "steward",
+      }]]),
+      errors: [], conflicts: [],
+    };
+  }
+
+  beforeEach(() => {
+    discoverOpsMock.mockReset();
+    loadChantConfigMock.mockReset().mockResolvedValue({ config: {} });
+    loadPluginsMock.mockReset().mockResolvedValue([]);
+    acquireStewardTurnMock.mockReset();
+    releaseLeaseMock.mockReset().mockResolvedValue(true);
+  });
+
+  test("local form, the turn is free: takes it, runs, and releases it once the run is over", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([localOp("release", [{ kind: "activity", fn: "shellCmd", args: { cmd: "true" } }])]),
+      errors: [],
+    });
+    discoverStewardsMock.mockResolvedValueOnce(stewardOwning("release", "box-steward"));
+    acquireStewardTurnMock.mockResolvedValue({
+      acquired: true,
+      lease: { op: "_turns/box-steward", holder: "h", token: "t1", acquiredAt: "x", expiresAt: "y" },
+    });
+    const stderrWrite = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const exit = await runOp({ args: makeArgs({ path: "release" }), plugins: [], serializers: [] });
+    stderrWrite.mockRestore();
+
+    expect(exit).toBe(0);
+    expect(acquireStewardTurnMock).toHaveBeenCalledTimes(1);
+    expect(acquireStewardTurnMock.mock.calls[0]?.[0]).toBe("box-steward");
+    expect(releaseLeaseMock).toHaveBeenCalledTimes(1);
+    expect(releaseLeaseMock).toHaveBeenCalledWith("_turns/box-steward", expect.any(String), "t1");
+  });
+
+  test("local form, a turn is already in progress: refused, naming the steward and holder, nothing runs", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([localOp("release", [{ kind: "activity", fn: "shellCmd", args: { cmd: "true" } }])]),
+      errors: [],
+    });
+    discoverStewardsMock.mockResolvedValueOnce(stewardOwning("release", "box-steward"));
+    acquireStewardTurnMock.mockResolvedValue({
+      acquired: false,
+      reason: "held",
+      heldBy: { op: "_turns/box-steward", holder: "other-host:123:abcd", token: "t0", acquiredAt: "x", expiresAt: "y" },
+    });
+    const stderr = makeStderrSpy();
+    const exit = await runOp({ args: makeArgs({ path: "release" }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    const out = stderr.join("\n");
+    expect(out).toContain('steward "box-steward"');
+    expect(out).toContain("other-host:123:abcd");
+    expect(out).toContain("chant operator status --steward box-steward");
+    expect(releaseLeaseMock).not.toHaveBeenCalled();
+  });
+
+  test("fountain form without --on fountain: refused, naming the redirect, no turn lease touched", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([localOp("release", [])]), errors: [] });
+    discoverStewardsMock.mockResolvedValueOnce(stewardOwning("release", "box-steward", "fountain"));
+    const stderr = makeStderrSpy();
+    const exit = await runOp({ args: makeArgs({ path: "release" }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    const out = stderr.join("\n");
+    expect(out).toContain('steward "box-steward"');
+    expect(out).toContain("chant run release --on fountain");
+    expect(acquireStewardTurnMock).not.toHaveBeenCalled();
+  });
+
+  test("fountain form with --on fountain: the local turn-lease check is skipped and the fountain runtime runs it", async () => {
+    const runtime = {
+      name: "fountain",
+      start: vi.fn(async (op: { name: string }) => ({
+        op: op.name,
+        runId: "f-1",
+        result: async () => ({ op: op.name, runId: "f-1", state: "completed" as const, startedAt: "t", endedAt: "t" }),
+      })),
+      status: vi.fn(), log: vi.fn(), list: vi.fn(), cancel: vi.fn(),
+    };
+    discoverOpsMock.mockResolvedValue({ ops: new Map([localOp("release", [])]), errors: [] });
+    discoverStewardsMock.mockResolvedValueOnce(stewardOwning("release", "box-steward", "fountain"));
+    loadChantConfigMock.mockResolvedValue({ config: { lexicons: ["fountain"] } });
+    makeStdoutSpy();
+    const exit = await runOp({
+      args: makeArgs({ path: "release", on: "fountain" }),
+      plugins: [{ name: "fountain", opRuntime: runtime } as never], serializers: [],
+    });
+
+    expect(exit).toBe(0);
+    expect(runtime.start).toHaveBeenCalledTimes(1);
+    expect(acquireStewardTurnMock).not.toHaveBeenCalled();
+  });
+
+  test("local form, the turn lease's own acquire throws (a stale .lock): refused as a lease error, not an uncaught exception, and nothing runs", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([localOp("release", [{ kind: "activity", fn: "shellCmd", args: { cmd: "true" } }])]),
+      errors: [],
+    });
+    discoverStewardsMock.mockResolvedValueOnce(stewardOwning("release", "box-steward"));
+    acquireStewardTurnMock.mockRejectedValue(new Error("cannot lock ref 'refs/chant/lease/_turns/box-steward': File exists"));
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({ args: makeArgs({ path: "release" }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    const out = stderr.join("\n");
+    expect(out).toContain('steward "box-steward"');
+    expect(out).toContain("cannot lock ref");
+    expect(releaseLeaseMock).not.toHaveBeenCalled();
+  });
+});
+
 /**
  * chant #2243 — a gated run's exit code is the one thing `--gated-exit`
  * remaps, and the gate is reported where CI can see it without opening a log.
@@ -373,7 +523,9 @@ describe("runOp: --gated-exit (#2243)", () => {
 
   test("a run that fails for any other reason is still red under the flag", async () => {
     discoverOpsMock.mockResolvedValue({
-      ops: new Map([localOp("broken", [{ kind: "activity", fn: "shellCmd", args: { cmd: "exit 7" } }])]),
+      // atMostOnce: one attempt. The default profile retries twice with 5s and
+      // 10s backoff, which put this test at 15s for waits it does not test (#2817).
+      ops: new Map([localOp("broken", [{ kind: "activity", fn: "shellCmd", profile: "atMostOnce", args: { cmd: "exit 7" } }])]),
       errors: [],
     });
     const file = summaryFile();

package/src/cli/handlers/run.ts

@@ -11,12 +11,16 @@ import { approveCommand, describeGateMismatch } from "../../op/gate";
 import { summaryLedgerPrefix, writeGatedRunSummary, type GatedRunSummary } from "../../op/gate-summary";
 import { createLocalOpRuntime } from "../../op/runtimes/local";
 import type { OpRuntimeProvider, OpRunStatus } from "../../op/runtime";
-import { renderHuman, renderJson } from "../../op/local-output";
+import { pointAnswerCommand, renderHuman, renderJson } from "../../op/local-output";
 import { loadPlugins } from "../plugins";
 import { recordGateApproval } from "./operator";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import type { CommandContext } from "../registry";
+import { stewardFormFor, stewardTurnLeaseName, DEFAULT_STEWARD_ENV, type StewardDeclaration } from "../../op/steward";
+import { acquireStewardTurn, STEWARD_TURN_WAIT_MS } from "../../op/operator";
+import { releaseLease, currentHolderId, type AcquireLeaseResult } from "../../lifecycle/lease";
+import { StaleLockError } from "../../lifecycle/git";
 import { renderDriverHuman, renderDriverJson } from "../../components/driver-output";
 import { ndjsonProgressSink } from "../../components/run-progress";
 import { maybeRecordAutoRelease } from "../../components/auto-release";
@@ -527,6 +531,94 @@ function refusesPolicyGateUnderSandbox(ctx: CommandContext, config: OpConfig, op
   return true;
 }
 
+/** What `stewardTurnGate` decided before `chant run <op>` is allowed to start. */
+type StewardTurnGate =
+  | { ok: true; release?: () => Promise<void> }
+  | { ok: false; message: string; hint: string };
+
+/**
+ * `chant run <op>` for an Op a declared steward lists is one of that
+ * steward's turns, not a run beside it (#2750, follow-up to #2731).
+ *
+ * On fountain, the run belongs on the steward's thread: without `--on
+ * fountain` this refuses outright, naming the command that posts it there
+ * instead (the fountain runtime's own turn already refuses a busy teammate,
+ * unretried — see chant-fountain-ops).
+ *
+ * In the local form, the run takes the steward's turn lease
+ * (`../../op/operator.ts`'s `acquireStewardTurn`) — the same lease a round's
+ * scheduled tick holds for the length of its own run. Held already, this
+ * waits up to {@link STEWARD_TURN_WAIT_MS} (long enough to ride out a race
+ * with a turn that's just ending) and then refuses, naming the steward and
+ * its holder. It never queues past that: a round's own leases skip and
+ * report rather than wait (`../../op/operator.ts`'s module doc), and a
+ * foreground CLI blocked with no visibility for however long a scheduled
+ * turn takes would be a worse answer than a clear refusal with a retry in
+ * hand. Ctrl-C already means "abort my own run" here; it must not also mean
+ * "give up waiting for someone else's turn".
+ *
+ * `undefined` (via the caller checking `owner`) when no steward lists this
+ * op — the ordinary, untouched path.
+ */
+async function stewardTurnGate(opName: string, ctx: CommandContext): Promise<StewardTurnGate | undefined> {
+  const { stewards } = await discoverStewards().catch(() => ({ stewards: new Map<string, { declaration: StewardDeclaration }>() }));
+  let owner: StewardDeclaration | undefined;
+  for (const { declaration } of stewards.values()) {
+    if (declaration.ops.some((op) => op.name === opName)) {
+      owner = declaration;
+      break;
+    }
+  }
+  if (!owner) return undefined;
+
+  const env = ctx.args.env ?? DEFAULT_STEWARD_ENV;
+  const form = stewardFormFor(owner, env);
+
+  if (form === "fountain") {
+    if (ctx.args.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}"`,
+      hint:
+        `Run \`chant run ${opName} --on fountain\` so it posts to "${owner.name}"'s thread. ` +
+        `A plain \`chant run ${opName}\` would run it outside that thread, beside the steward instead of one of its turns.`,
+    };
+  }
+
+  const holder = currentHolderId();
+  let turn: AcquireLeaseResult;
+  try {
+    turn = await acquireStewardTurn(owner.name, holder, { waitMs: STEWARD_TURN_WAIT_MS });
+  } catch (err) {
+    // Not turn contention — the acquire attempt itself failed (most likely a
+    // StaleLockError, a `.lock` left behind by a killed operator process).
+    // Report it as a refusal rather than letting it propagate uncaught out
+    // of `runOpOnRuntime`, before that function's own try/catch even starts.
+    return {
+      ok: false,
+      message: `Op "${opName}" is one of steward "${owner.name}"'s turns, and its lease could not be read`,
+      hint:
+        `${err instanceof StaleLockError ? err.message : err instanceof Error ? err.message : String(err)} ` +
+        `This can happen when an operator process was killed mid-write; check refs/chant/lease/_turns/${owner.name} for a stale lock.`,
+    };
+  }
+  if (!turn.acquired) {
+    const heldBy = turn.heldBy?.holder;
+    return {
+      ok: false,
+      message:
+        `Op "${opName}" is one of steward "${owner.name}"'s turns, and a turn is in progress` +
+        (heldBy ? ` (held by ${heldBy})` : ""),
+      hint:
+        `Wait for the turn to finish and re-run \`chant run ${opName}\`, or check \`chant operator status --steward ${owner.name}\`. ` +
+        `If it looks stuck, stop the operator process holding it (Ctrl-C, or kill it) — its lease also expires on its own.`,
+    };
+  }
+  const lease = turn.lease!;
+  const stewardName = owner.name;
+  return { ok: true, release: async () => { await releaseLease(stewardTurnLeaseName(stewardName), holder, lease.token).catch(() => false); } };
+}
+
 export async function runOp(ctx: CommandContext): Promise<number> {
   if (ctx.args.generate) {
     if (ctx.args.components) {
@@ -864,8 +956,20 @@ export async function runOpOnRuntime(ctx: CommandContext): Promise<number> {
   // Pre-flight: --sandbox cannot cover a policyGate step (#2003).
   if (refusesPolicyGateUnderSandbox(ctx, config, opName)) return 1;
 
+  // A hand run of an Op a declared steward lists is one of that steward's
+  // turns, not a run beside it (#2750). `undefined` when no steward lists
+  // this op at all — the ordinary path.
+  const stewardGate = await stewardTurnGate(opName, ctx);
+  if (stewardGate && !stewardGate.ok) {
+    console.error(formatError({ message: stewardGate.message, hint: stewardGate.hint }));
+    return 1;
+  }
+
   const runtime = await resolveOpRuntime(ctx);
-  if (!runtime) return 1;
+  if (!runtime) {
+    await stewardGate?.release?.();
+    return 1;
+  }
 
   // The work lease (#2748). `--work` names the item an Op with a work lease
   // runs under; it is taken where the run executes, which for a hosted
@@ -940,6 +1044,18 @@ export async function runOpOnRuntime(ctx: CommandContext): Promise<number> {
       }
       return gatedExit;
     }
+    // A run waiting on an open decision point (#2749) is waiting on a person,
+    // like a gated one, and exits with the same code. Its answer comes through
+    // hud or `points answer`, never a `chant approve`.
+    if (status.state === "waiting") {
+      if (!status.result && status.point) {
+        console.error(formatWarning({
+          message: `Op "${opName}" is waiting on decision point "${status.point.point}" (${status.point.id})`,
+          hint: `A person answers it with: ${pointAnswerCommand(status.point.id)}`,
+        }));
+      }
+      return gatedExit;
+    }
     return status.state === "completed" ? 0 : 1;
   } catch (err) {
     if (err instanceof OpRunFailure) {
@@ -950,6 +1066,9 @@ export async function runOpOnRuntime(ctx: CommandContext): Promise<number> {
     return 1;
   } finally {
     process.removeListener("SIGINT", onSigint);
+    // The turn is over, win or lose — free it so the steward's next round,
+    // or the next hand run, doesn't wait out this run's own TTL (#2750).
+    await stewardGate?.release?.();
   }
 }
 

package/src/cli/main.test.ts

@@ -727,6 +727,16 @@ describe("workspace graph --intent (#2651)", () => {
   });
 });
 
+describe("workspace check --changes (#2773)", () => {
+  test("parses the range, the work item and the severity", () => {
+    const args = parseArgs(["workspace", "check", "--changes", "main..HEAD", "--work", "W-001", "--severity", "fail", "--json"]);
+    expect(args).toMatchObject({ command: "workspace", path: "check", changes: "main..HEAD", work: "W-001", severity: "fail", json: true });
+    expect(() => parseArgs(["workspace", "check", "--changes"])).toThrow(/--changes needs a range/);
+    expect(() => parseArgs(["workspace", "check", "--changes", "main", "--severity"])).toThrow(/--severity needs off, warn or fail/);
+    expect(resolveCommand(args, commandRegistry)?.def.name).toBe("workspace check");
+  });
+});
+
 describe("workspace init and ls (#2534)", () => {
   test("resolve to their commands in the one workspace group, with the directory as extra positional", () => {
     const ls = parseArgs(["workspace", "ls", "examples", "--at", "HEAD", "--json"]);

package/src/cli/main.ts

@@ -379,6 +379,14 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace graph --intent <path[:start-end]>` (#2651)
       result.intent = args[++i];
       if (!result.intent || result.intent.startsWith("-")) throw new Error("--intent needs a region: --intent <path[:start-end]>");
+    } else if (arg === "--changes") {
+      // `chant workspace check --changes <base>..<head>` (#2773)
+      result.changes = args[++i];
+      if (!result.changes || result.changes.startsWith("-")) throw new Error("--changes needs a range: --changes <base>..<head>");
+    } else if (arg === "--severity") {
+      // `chant workspace check --changes <range> --severity off|warn|fail` (#2773)
+      result.severity = args[++i];
+      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 === "--set") {
@@ -858,6 +866,10 @@ Workspace (level 1, #2524):
                         separate clones coordinate. A claim is refused, exit 2,
                         while anyone holds it live. Each change appends to
                         _leases/<id>.jsonl on chant/lifecycle
+  workspace work history <id> [--kind <kind file>] [--json]
+                        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 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;
@@ -896,6 +908,13 @@ Workspace (level 1, #2524):
                         whose pinned files changed. Needs no workspace file.
                         --at reads a commit's git objects; --format json
                         prints the read-contract document
+  workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]
+                        Map each path the diff changes to the current records
+                        whose constrains cover it: change-uncovered when none
+                        does, change-out-of-scope when a record in hand (the
+                        --work item and its decisions) lists it in
+                        out_of_scope. The declaration's changes block sets
+                        the severity (warn by default) and ignore globs
   workspace build [dir] [--member <name>] [-o <dir>] [--dry-run]
                         Build every chant member and example project, each with
                         its own chant, one process per toolchain. -o <dir>
@@ -1265,9 +1284,10 @@ async function loadPluginsOrExit(path: string): Promise<import("../lexicon").Lex
  * #2700 — whether `path` is the root of a declared workspace and holds no
  * lexicon of its own: no `lexicons` in a root config, and no lexicon import in
  * the root's source, which leaves the members' directories out (#2527). A
- * generated chud repo is this shape: its lexicons are all in `delivery/`.
- * `chant serve mcp` starts there instead of refusing with "No lexicon
- * detected", and serves core with the chant members' lexicons.
+ * generated app repo can be this shape: its lexicons are all under a
+ * delivery directory, not the root. `chant serve mcp` starts there instead of
+ * refusing with "No lexicon detected", and serves core with the chant
+ * members' lexicons.
  *
  * A directory with no workspace declaration costs only `findWorkspaceRoot`'s
  * existence checks, so a level-0 project reaches `loadPluginsOrExit` as before.

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

@@ -2,12 +2,12 @@
  * #2700 — the lexicons `chant serve mcp` loads at the root of a declared
  * workspace that has no lexicon of its own.
  *
- * Such a root (a generated chud repo, say, whose lexicons are all in
- * `delivery/`) used to refuse with "No lexicon detected", so an agent started
- * there got none of chant's tools. The server now starts with core's tools and
- * resources, and with the lexicons of the workspace's members of kind chant,
- * each read from that member's own config the way `chant build` in the
- * member's directory reads it.
+ * Such a root (a generated app repo, say, whose lexicons are all under a
+ * delivery directory) used to refuse with "No lexicon detected", so an agent
+ * started there got none of chant's tools. The server now starts with core's
+ * tools and resources, and with the lexicons of the workspace's members of
+ * kind chant, each read from that member's own config the way `chant build`
+ * in the member's directory reads it.
  *
  * Loading is best effort, one member and one lexicon at a time: a member whose
  * config does not load, or a lexicon this chant cannot import, is left out and

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-records", "workspace-points", "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-work-history", "records-new", "records-amend", "records-review", "records-close", "points-answer"]);
   });
 
   test("a server outside any workspace, or given none, does not", async () => {
@@ -100,8 +100,8 @@ describe("which servers have the workspace tools", () => {
     }
   });
 
-  test("the descriptions say records are proposals and by names who decided", () => {
-    for (const t of workspaceWriteTools) expect(t.description).toMatch(/proposals until they are reviewed.*by must name the person or agent that actually decided/s);
+  test("the descriptions say records are proposals and by names who proposed or decided", () => {
+    for (const t of workspaceWriteTools) expect(t.description).toMatch(/proposals until they are reviewed.*by must name the person or agent that actually proposed or decided it/s);
   });
 });
 
@@ -128,6 +128,28 @@ describe("reads", () => {
     expect(bad.isError).toBe(true);
   }, 120_000);
 
+  test("workspace-work-history returns the document chant workspace work history --json prints (#2785)", async () => {
+    const s = server();
+    const res = await call(s, "workspace-work-history", { item: "W-1" });
+    expect(res.isError).toBeUndefined();
+    expect(res.structuredContent).toEqual(cli(["workspace", "work", "history", "W-1", "--json"]));
+    expect(res.structuredContent).toMatchObject({ contract: 1, error: { code: expect.any(String) } });
+    const bad = await call(s, "workspace-work-history", {});
+    expect(bad.isError).toBe(true);
+  }, 120_000);
+
+  test("workspace-changes returns the document chant workspace check --changes --json prints (#2773)", async () => {
+    const s = server();
+    const res = await call(s, "workspace-changes", { range: "HEAD", severity: "fail" });
+    expect(res.isError).toBeUndefined();
+    expect(res.structuredContent).toEqual(cli(["workspace", "check", "--changes", "HEAD", "--severity", "fail", "--json"]));
+    expect(res.structuredContent).toMatchObject({ severity: "fail", paths: [], findings: [], ok: true });
+    const unknown = await call(s, "workspace-changes", { range: "HEAD", work: "W-999" });
+    expect(unknown.structuredContent).toMatchObject({ error: { code: "work-item-unknown" } });
+    const bad = await call(s, "workspace-changes", { range: "HEAD", severity: "loud" });
+    expect(bad.isError).toBe(true);
+  }, 120_000);
+
   test("an error document is returned as a document, and a flag-shaped value is refused before chant runs", async () => {
     const s = server();
     const missing = await call(s, "workspace-records", { kind: "nowhere/none.kind.mjs" });
@@ -143,6 +165,7 @@ describe("reads", () => {
     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 } });
     expect(mcpToolCall(["workspace", "check", "--format", "json"])).toBeUndefined();
+    expect(mcpToolCall(["workspace", "check", "--changes", "main..HEAD", "--work", "W-001", "--json"])).toEqual({ name: "workspace-changes", arguments: { range: "main..HEAD", work: "W-001" } });
   });
 });
 
@@ -186,25 +209,18 @@ describe("writes", () => {
     const reasoning = await call(s, "records-amend", { kind: KIND, id: "fix-001", fields: { question: "Something else?" } });
     expect(reasoning.structuredContent).toMatchObject({ error: { code: "amend-supersede-instead" } });
 
-    const both = await call(s, "records-new", { kind: KIND, record: { ...proposal("Two authors"), decided_by: "alice" }, by: "bob", dryRun: true });
+    // A new record opens proposed (MCP forces it), so by names the proposer, in proposedBy's field, not the decider (#2756).
+    const both = await call(s, "records-new", { kind: KIND, record: { ...proposal("Two proposers"), proposed_by: "alice" }, by: "bob", dryRun: true });
     expect(both.structuredContent).toMatchObject({ error: { code: "write-input-invalid" } });
-    const by = await call(s, "records-new", { kind: KIND, record: proposal("One author"), by: "alice", dryRun: true });
+    const by = await call(s, "records-new", { kind: KIND, record: proposal("One proposer"), by: "alice", dryRun: true });
     expect(by.structuredContent, JSON.stringify(by.structuredContent)).toHaveProperty("text");
-    expect((by.structuredContent as { text: string }).text).toContain('decided_by: "alice"');
+    expect((by.structuredContent as { text: string }).text).toContain('proposed_by: "alice"');
+    expect((by.structuredContent as { text: string }).text).toContain("decided_by: null");
+
+    // --sign seals the decider, and a record by names as proposed carries no decided_by yet.
+    const signed = await call(s, "records-new", { kind: KIND, record: proposal("Signed"), by: "alice", sign: true, dryRun: true });
+    expect(signed.structuredContent).toMatchObject({ error: { code: "record-sign-failed", message: expect.stringContaining("names no decided_by") } });
 
-    // No key configured on this host: the CLI's refusal and remedy.
-    const home = { GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1" };
-    const saved = { ...process.env };
-    Object.assign(process.env, home);
-    try {
-      const signed = await call(s, "records-new", { kind: KIND, record: proposal("Signed"), by: "alice", sign: true, dryRun: true });
-      expect(signed.structuredContent).toMatchObject({ error: { code: "record-sign-failed", message: expect.stringContaining("pass --sign <key file>") } });
-    } finally {
-      for (const k of Object.keys(home)) {
-        if (saved[k] === undefined) delete process.env[k];
-        else process.env[k] = saved[k];
-      }
-    }
     // Nothing above wrote a file.
     expect(readFileSync(join(ws.dir, "decisions", "fix-001-how-the-app-is-deployed.md"), "utf-8")).toContain('question: "What declares the app\'s deployment?"');
   }, 180_000);