@intentius/chant 0.124.40 → 0.124.42

package/src/cli/handlers/fan-out.ts

@@ -56,7 +56,8 @@ import { samePlanDigest } from "../../lifecycle/plan-digest";
 import { affectedStacks } from "../../lifecycle/affected";
 import { changedFilesBetween, lexiconChangedUnits } from "../../components/changed-files";
 import { deriveFanOut, fanOutRegistry } from "../../components/fan-out-support";
-import { EarlierWaveNotAppliedError, runFanOut } from "../../components/fan-out-run";
+import { EarlierWaveNotAppliedError, EarlierWaveWaitingError, fanOutGateDigest, runFanOut, type FanOutWaveGate } from "../../components/fan-out-run";
+import { parseComponentTargets } from "../../components/capability";
 import { readFanOutAttempt, writeFanOutAttempt, type FanOutAttempt } from "../../components/fan-out-record";
 import { componentInputDigests, progressThatCarries } from "../../components/fan-out-inputs";
 import { appliedDigestOf } from "../../components/auto-release";
@@ -267,8 +268,30 @@ async function fanOut(ctx: CommandContext, projectPath: string, config: ChantCon
     }));
   }
 
+  // #4300: `--target <component>:<address>`, the addresses a component's steps narrow to.
+  let targets: Record<string, string[]> | undefined;
+  if (args.targets && args.targets.length > 0) {
+    try {
+      targets = parseComponentTargets(args.targets, new Set(derived.components.map((c) => c.name)));
+    } catch (err) {
+      console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+      return 1;
+    }
+    const running = new Set(derived.plan.order);
+    const outside = Object.keys(targets).filter((name) => !running.has(name));
+    if (outside.length > 0) {
+      console.error(formatError({
+        message: `--target names ${outside.join(", ")}, which this fan-out does not run`,
+        hint: "A target narrows a component the change selects. Drop the --target, or change what the fan-out selects.",
+      }));
+      return 1;
+    }
+  }
+  // The fan-out's identity: the derivation's digest, with the targets in it (#4300).
+  const runDigest = fanOutGateDigest(derived.plan.digest, targets);
+
   const gate = args.gate ? { op: FAN_OUT_GATE_OP, gate: args.gate } : undefined;
-  const waveGate = args.waveGate
+  const waveGate: FanOutWaveGate | undefined = args.waveGate
     ? { op: FAN_OUT_GATE_OP, gate: args.waveGate, ...(args.wave !== undefined ? { only: args.wave } : {}) }
     : undefined;
 
@@ -287,6 +310,7 @@ async function fanOut(ctx: CommandContext, projectPath: string, config: ChantCon
   let priorOutputs: Record<string, Record<string, unknown>> = {};
   let priorWaves: WaveRecord[] = [];
   let priorCarried: Record<string, unknown> = {};
+  let priorFailed: string[] = [];
   let progress: FanOutProgress | undefined;
   if (resumePath) {
     let attempt: FanOutAttempt | undefined;
@@ -296,7 +320,7 @@ async function fanOut(ctx: CommandContext, projectPath: string, config: ChantCon
       console.error(formatError({ message: `--resume: could not read "${args.resume}": ${err instanceof Error ? err.message : String(err)}` }));
       return 1;
     }
-    if (attempt && !samePlanDigest(attempt.digest, derived.plan.digest)) {
+    if (attempt && !samePlanDigest(attempt.digest, runDigest)) {
       console.error(formatWarning({
         message: `--resume: "${args.resume}" records a different fan-out (${attempt.digest || "no digest"}), so its progress does not apply here`,
         hint: "The derivation changed, which makes this a different change. Everything selected will run.",
@@ -330,6 +354,12 @@ async function fanOut(ctx: CommandContext, projectPath: string, config: ChantCon
       );
       progress = { completed: split.carried };
       priorWaves = attempt.waves ?? [];
+      // #4291: what failed stays in the record until it applies, so each later wave's job blocks its dependents and runs the rest.
+      priorFailed = attempt.failed.filter((name) => !carried.has(name));
+      if (waveGate?.only !== undefined) {
+        waveGate.failedEarlier = priorFailed;
+        waveGate.waitingEarlier = priorWaves.filter((w) => w.status === "gated").map((w) => ({ wave: w.wave, gate: w.gate, components: w.components }));
+      }
       // What steps kept per member (#3459), such as a choudoufu root's wave
       // resume file. Each step decides whether what it kept still applies.
       priorCarried = attempt.carried ?? {};
@@ -397,14 +427,14 @@ async function fanOut(ctx: CommandContext, projectPath: string, config: ChantCon
   // repeated command picks up from there instead of redoing them.
   const completedSoFar = new Set(priorCompleted);
   const inputsSoFar: Record<string, string> = { ...priorInputs };
-  const failedSoFar: string[] = [];
+  const failedSoFar = new Set(priorFailed);
   const outputsSoFar = { ...priorOutputs };
   let wavesSoFar = priorWaves;
   const carriedSoFar: Record<string, unknown> = { ...priorCarried };
   const recordAttempt = (): void => {
     if (!resumePath) return;
     const attempt: FanOutAttempt = {
-      digest: derived.plan.digest,
+      digest: runDigest,
       completed: [...completedSoFar].sort(),
       failed: [...failedSoFar].sort(),
       outputs: outputsSoFar,
@@ -426,6 +456,7 @@ async function fanOut(ctx: CommandContext, projectPath: string, config: ChantCon
       env,
       releaseIdentity: () => (revision ? { revision } : {}),
       componentOutputs,
+      ...(targets ? { targets } : {}),
       ...(gate ? { gate } : {}),
       ...(waveGate ? { waveGate } : {}),
       ...(waveGate
@@ -455,8 +486,9 @@ async function fanOut(ctx: CommandContext, projectPath: string, config: ChantCon
                 completedSoFar.add(settled.component);
                 if (inputsNow[settled.component] !== undefined) inputsSoFar[settled.component] = inputsNow[settled.component]!;
                 if (outputs) outputsSoFar[settled.component] = outputs;
+                failedSoFar.delete(settled.component);
               } else if (settled.status === "fail") {
-                failedSoFar.push(settled.component);
+                failedSoFar.add(settled.component);
               }
               recordAttempt();
             },
@@ -466,6 +498,11 @@ async function fanOut(ctx: CommandContext, projectPath: string, config: ChantCon
   } catch (err) {
     events?.settle("failed", err instanceof Error ? err.message : String(err));
     // `--wave <n>` reached before an earlier wave applied: nothing ran.
+    // #4291: an earlier wave waits at its gate, so this one waits too.
+    if (err instanceof EarlierWaveWaitingError) {
+      console.error(formatInfo(err.message));
+      return GATED_EXIT_CODE;
+    }
     if (err instanceof EarlierWaveNotAppliedError) {
       console.error(formatError({ message: err.message }));
       return 1;

package/src/cli/handlers/gate-resume.ts

@@ -27,6 +27,7 @@ import {
 import { appliedGatePath, parseAppliedGateFile, type AppliedGateLine, type FinishedGateRecord } from "../../lifecycle/gate-applied";
 import { listFilesInDir, pushLifecycleStatus, readBlobFromPath, requireLifecycleLedger } from "../../lifecycle/git";
 import { parseGateSubject } from "../../op/gate-point";
+import { quorumRules, ruleNeedsProof, trustQuorumJudge, type GateQuorumJudge } from "../../op/gate-quorum";
 import {
   resolutionAnswering,
   resumeGateRun,
@@ -91,6 +92,17 @@ export interface ResumeGateOptions {
   /** The lines of `_gates/<op>/applied.jsonl` (#3858). Read from `chant/lifecycle` by {@link resumeOpGates} when not given. */
   applied?: readonly AppliedGateLine[];
   finished?: readonly FinishedGateRecord[];
+  /** Proves approvers for approval rules that name roles (#4290). Read from the trust policy at base when a fact needs one and none is given. */
+  judge?: GateQuorumJudge;
+}
+
+/** The judge a fact's approval rules are met by (#4290): the trust policy at base, read only when a rule names roles or notAuthor. */
+async function judgeFor(pending: readonly PendingGateRecord[], opts: ResumeGateOptions): Promise<GateQuorumJudge | undefined> {
+  if (opts.judge) return opts.judge;
+  if (!pending.some((p) => quorumRules(p.approval?.quorum).some(ruleNeedsProof))) return undefined;
+  const { scopeSource } = await import("../../workspace/write-scope");
+  const { policy } = scopeSource(process.cwd());
+  return trustQuorumJudge({ signers: policy, roles: policy.roles });
 }
 
 /** Every question the workspace at `cwd` lists, by id, the lifecycle ledger's included. Empty when the workspace can't be read. */
@@ -108,6 +120,7 @@ export async function resumeStanding(
   opts: ResumeGateOptions = {},
   pending: readonly PendingGateRecord[] = [standing],
 ): Promise<GateResumeReport> {
+  const judge = await judgeFor([standing], opts);
   const [candidate] = planGateResumes({
     op: standing.op,
     pending: [standing],
@@ -115,7 +128,7 @@ export async function resumeStanding(
     applied: opts.applied ?? [],
     now: standing.timestamp,
     ...(opts.questions ? { questions: opts.questions } : {}),
-    answering: (r, s) => resolutionAnswering(r, s, pending),
+    answering: (r, s) => resolutionAnswering(r, s, pending, judge),
   });
   return resumeCandidate(candidate!, opts);
 }
@@ -199,6 +212,7 @@ export async function resumeOpGates(op: string, gate: string | undefined, opts:
   const now = opts.now ?? new Date().toISOString();
   // Read the workspace's questions once, and only when a fact waits on one (#3835).
   const questions = opts.questions ?? (ledger.pending.some((p) => p.answer) ? await workspaceQuestions(process.cwd()) : undefined);
+  const judge = await judgeFor(ledger.pending, opts);
   const candidates = planGateResumes({
     op,
     pending: ledger.pending,
@@ -208,7 +222,7 @@ export async function resumeOpGates(op: string, gate: string | undefined, opts:
     now,
     ...(gate !== undefined ? { gate } : {}),
     ...(questions ? { questions } : {}),
-    answering: resolutionAnswering,
+    answering: (r, s, p) => resolutionAnswering(r, s, p, judge),
   });
   const reports: GateResumeReport[] = [];
   for (const c of candidates) reports.push(await resumeCandidate(c, opts));

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

@@ -0,0 +1,98 @@
+/**
+ * #4293: `chant lock` and `chant unlock` take, list and release target locks
+ * on `chant/lifecycle`, and exit 3 when another pull request holds a target.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { commandRegistry, parseArgs } from "../main";
+import { resolveCommand } from "../registry";
+
+const dirs: string[] = [];
+const home = process.cwd();
+afterAll(() => {
+  process.chdir(home);
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function initRepo(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-lock-cli-")));
+  dirs.push(dir);
+  git(dir, "init", "-q", "-b", "main");
+  git(dir, "config", "user.email", "test@chant.dev");
+  git(dir, "config", "user.name", "Test");
+  git(dir, "config", "commit.gpgsign", "false");
+  writeFileSync(join(dir, "README.md"), "# t\n");
+  git(dir, "add", "README.md");
+  git(dir, "commit", "-q", "-m", "init");
+  return dir;
+}
+
+async function run(argv: string[]): Promise<{ code: number; out: string; err: string }> {
+  let out = "";
+  let err = "";
+  vi.spyOn(console, "log").mockImplementation((s) => void (out += String(s) + "\n"));
+  vi.spyOn(console, "error").mockImplementation((s) => void (err += String(s) + "\n"));
+  const args = parseArgs(argv);
+  const match = resolveCommand(args, commandRegistry);
+  expect(match?.def.name).toBe(argv[0]);
+  const code = await match!.def.handler({ args, plugins: [], serializers: [] });
+  vi.restoreAllMocks();
+  return { code: code ?? 0, out, err };
+}
+
+let repo: string;
+beforeEach(() => {
+  repo = initRepo();
+  process.chdir(repo);
+});
+afterEach(() => {
+  process.chdir(home);
+  vi.restoreAllMocks();
+});
+
+describe("chant lock and chant unlock", () => {
+  test("lock takes named targets, a second pull request exits 3 naming the holder, unlock frees them", async () => {
+    const taken = await run(["lock", "web", "api", "--pr", "1", "--by", "alice", "--json"]);
+    expect(taken.code).toBe(0);
+    expect(JSON.parse(taken.out)).toMatchObject({ gate: "pr-apply", pr: 1, ok: true, stage: "lock", taken: ["api", "web"] });
+
+    const held = await run(["lock", "web", "--pr", "2", "--by", "bob"]);
+    expect(held.code).toBe(3);
+    expect(held.err).toContain("web is locked by pull request 1 (locked with chant lock by alice), so pull request 2 is not locked");
+
+    const listed = await run(["lock", "--list", "--json"]);
+    expect(Object.keys(JSON.parse(listed.out).locks)).toEqual(["api", "web"]);
+
+    const released = await run(["unlock", "--pr", "1", "--json"]);
+    expect(JSON.parse(released.out)).toMatchObject({ released: ["api", "web"] });
+    expect((await run(["lock", "web", "--pr", "2", "--by", "bob"])).code).toBe(0);
+  });
+
+  test("--from-report locks the components a pr-plan.json selected, as plan locks, and refuses another pull request's report", async () => {
+    const report = join(repo, "pr-plan.json");
+    writeFileSync(report, JSON.stringify({ pr: 4, head: "b".repeat(40), selection: { waves: [["db"], ["api", "web"]] } }));
+    const taken = await run(["lock", "--from-report", report, "--pr", "4", "--stage", "plan", "--json"]);
+    expect(JSON.parse(taken.out)).toMatchObject({ ok: true, stage: "plan", taken: ["api", "db", "web"] });
+    const file = JSON.parse(git(repo, "show", "chant/lifecycle:_locks/pr-apply.json"));
+    expect(file.locks.db).toMatchObject({ pr: 4, stage: "plan", head: "b".repeat(40) });
+
+    const wrong = await run(["lock", "--from-report", report, "--pr", "5"]);
+    expect(wrong.code).toBe(1);
+    expect(wrong.err).toContain("is the report of pull request 4, not 5");
+  });
+
+  test("refuses without --pr or targets, an unknown stage, and a gate that is not a file name", async () => {
+    expect((await run(["lock", "web"])).err).toContain("--pr <n>");
+    expect((await run(["lock", "--pr", "1"])).err).toContain("needs the targets");
+    expect((await run(["lock", "web", "--pr", "1", "--stage", "merge"])).err).toContain("--stage merge is not one of plan, apply, lock");
+    expect((await run(["lock", "web", "--pr", "1", "--gate", "../x"])).code).toBe(1);
+    expect((await run(["unlock"])).err).toContain("--pr <n>");
+  });
+});

package/src/cli/handlers/lock.ts

@@ -0,0 +1,202 @@
+/**
+ * `chant lock` and `chant unlock` (#4293): take, list and release the target
+ * locks a pull request holds (../../lifecycle/target-lock.ts).
+ *
+ * ```
+ * chant lock <target>... --pr <n> [--stage plan|apply|lock] [--head <sha>] [--by <who>] [--gate <name>] [--forge <kind>] [--json]
+ * chant lock --from-report <pr-plan.json> --pr <n> [--stage plan] [--forge <kind>] [--json]
+ * chant lock --list [--gate <name>] [--json]
+ * chant unlock --pr <n> [<target>...] [--gate <name>] [--json]
+ * ```
+ *
+ * The targets are names: the components `chant components pr-plan` selects,
+ * which are what `pr-apply` checks under `ci.locks`, or any other name a
+ * pipeline locks by. `--from-report` reads them from a pull-request report
+ * (`selection.waves`), so a lock job that runs the target branch's code can
+ * lock what the plan job, which ran the pull request's code, selected.
+ *
+ * `--forge` reads which holders are still open, so a lock whose pull
+ * request merged or closed is taken over, and, with `--head`, posts the
+ * `chant/lock` status on that commit. Without it every lock counts as held.
+ *
+ * Exit 0 when the locks are taken or released, 3 when another open pull
+ * request holds a target (nothing is locked), 1 on an error.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { CommandContext } from "../registry";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../format";
+import { FORGE_KINDS, forgeFromEnv, type ForgeKind, type PrForge } from "../../pr-forge";
+import { PR_APPLY_GATE } from "../../pr-loop";
+import {
+  describeHeldTargetLocks,
+  readTargetLocks,
+  releaseTargetLocks,
+  takeTargetLocks,
+  targetLockGateProblem,
+  targetLockPathAt,
+  TARGET_LOCK_STAGES,
+  type TargetLockStage,
+} from "../../lifecycle/target-lock";
+
+/** The exit for a target another open pull request holds: 3, as a run stopped at a gate exits (`GATED_EXIT_CODE` in ./run.ts). */
+const HELD_EXIT_CODE = 3;
+
+/** The status `chant lock --head <sha> --forge <kind>` posts. */
+export const LOCK_STATUS_CONTEXT = "chant/lock";
+
+const fail = (message: string, hint?: string): number => {
+  console.error(formatError({ message, ...(hint ? { hint } : {}) }));
+  return 1;
+};
+
+/** The targets named after the command word. */
+function targetsOf(ctx: CommandContext): string[] {
+  return (ctx.args.positionals ?? []).filter((t) => t !== "");
+}
+
+function gateOf(ctx: CommandContext): string | { error: string } {
+  const gate = ctx.args.gate ?? PR_APPLY_GATE;
+  const problem = targetLockGateProblem(gate);
+  return problem ? { error: problem } : gate;
+}
+
+function forgeOf(ctx: CommandContext): PrForge | undefined | { error: string } {
+  const kind = ctx.args.forge;
+  if (kind === undefined) return undefined;
+  if (!(FORGE_KINDS as readonly string[]).includes(kind)) return { error: `--forge ${kind} is not one of ${FORGE_KINDS.join(", ")}` };
+  try {
+    return forgeFromEnv(kind as ForgeKind);
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+const prName = (forge: PrForge | undefined) => (n: number) => (forge?.kind === "gitlab" ? `merge request !${n}` : `pull request ${n}`);
+
+/** The components a `pr-plan.json` selected, and the head it planned, checked against `--pr`. */
+function fromReport(file: string, pr: number): { targets: string[]; head?: string } | { error: string } {
+  let doc: { pr?: unknown; head?: unknown; selection?: { waves?: unknown } };
+  try {
+    doc = JSON.parse(readFileSync(resolve(file), "utf8"));
+  } catch (err) {
+    return { error: `--from-report: could not read "${file}": ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (doc.pr !== pr) return { error: `--from-report: "${file}" is the report of ${doc.pr === null || doc.pr === undefined ? "no pull request" : `pull request ${String(doc.pr)}`}, not ${pr}` };
+  const waves = doc.selection?.waves;
+  if (!Array.isArray(waves) || !waves.every((w) => Array.isArray(w) && w.every((n) => typeof n === "string"))) {
+    return { error: `--from-report: "${file}" has no selection.waves; pass a pr-plan.json that chant components pr-plan wrote` };
+  }
+  return { targets: (waves as string[][]).flat(), ...(typeof doc.head === "string" ? { head: doc.head } : {}) };
+}
+
+async function postStatus(forge: PrForge | undefined, head: string | undefined, state: "success" | "failure", description: string): Promise<void> {
+  if (!forge || !head) return;
+  try {
+    await forge.setStatus(head, { context: LOCK_STATUS_CONTEXT, state, description: description.length > 140 ? `${description.slice(0, 137)}...` : description, ...(forge.runUrl ? { url: forge.runUrl } : {}) });
+  } catch (err) {
+    console.error(formatWarning({ message: `could not post ${LOCK_STATUS_CONTEXT} on ${head}: ${err instanceof Error ? err.message : String(err)}` }));
+  }
+}
+
+/** chant lock */
+export async function runLock(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const gate = gateOf(ctx);
+  if (typeof gate !== "string") return fail(gate.error);
+
+  if (args.list) {
+    if (targetsOf(ctx).length > 0 || args.pr !== undefined) return fail("--list prints every lock; drop the targets and --pr");
+    let file;
+    try {
+      file = await readTargetLocks(gate);
+    } catch (err) {
+      return fail(err instanceof Error ? err.message : String(err));
+    }
+    const rows = Object.entries(file.locks).sort(([a], [b]) => a.localeCompare(b));
+    if (args.json) {
+      console.log(JSON.stringify({ gate, path: await targetLockPathAt(gate), locks: Object.fromEntries(rows) }, null, 2));
+      return 0;
+    }
+    if (rows.length === 0) console.error(formatInfo(`no target locks on ${gate}`));
+    for (const [target, l] of rows) console.log(`${target}\tpull request ${l.pr}\t${l.stage}\t${l.by}\t${l.at}`);
+    return 0;
+  }
+
+  if (args.pr === undefined) return fail("chant lock needs the pull or merge request that holds the locks: --pr <n>", "chant lock --list prints the locks held now.");
+  const stage = (args.lockStage ?? "lock") as TargetLockStage;
+  if (!(TARGET_LOCK_STAGES as readonly string[]).includes(stage)) return fail(`--stage ${args.lockStage} is not one of ${TARGET_LOCK_STAGES.join(", ")}`);
+
+  let targets = targetsOf(ctx);
+  let head = args.head;
+  if (args.fromReport) {
+    if (targets.length > 0) return fail("--from-report reads the targets from the report; drop the names");
+    const read = fromReport(args.fromReport, args.pr);
+    if ("error" in read) return fail(read.error);
+    targets = read.targets;
+    head ??= read.head;
+  } else if (targets.length === 0 && stage !== "plan") {
+    return fail("chant lock needs the targets to lock: chant lock <target>... --pr <n>", "Or --from-report <pr-plan.json> to lock what a plan selected.");
+  }
+
+  const forge = forgeOf(ctx);
+  if (forge && "error" in forge) return fail(forge.error);
+  const isOpen = forge?.pullRequestOpen?.bind(forge);
+  const by = args.by ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER ?? "unknown";
+  const name = prName(forge);
+
+  let result;
+  try {
+    result = await takeTargetLocks(
+      gate,
+      targets,
+      { pr: args.pr, by, at: new Date().toISOString(), stage, ...(head ? { head } : {}) },
+      { ...(isOpen ? { isOpen } : {}), releaseStalePlan: stage === "plan" },
+    );
+  } catch (err) {
+    return fail(`could not take the locks of ${gate}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  if (!result.ok) {
+    const holders = [...new Set(result.held.map((h) => h.pr))].sort((a, b) => a - b);
+    const text = `${describeHeldTargetLocks(result.held, name)}, so ${name(args.pr)} is not locked`;
+    await postStatus(forge, head, "failure", `locked by ${holders.map(name).join(", ")}: ${result.held.map((h) => h.target).join(", ")}`);
+    if (args.json) console.log(JSON.stringify({ gate, pr: args.pr, ok: false, held: result.held }, null, 2));
+    console.error(formatError({ message: text, hint: `Lock again once ${holders.length === 1 ? "it merges or closes" : "they merge or close"}, or after chant unlock --pr ${holders[0]}.${isOpen ? "" : " Without --forge every lock counts as held."}` }));
+    return HELD_EXIT_CODE;
+  }
+
+  const holds = result.taken.length > 0 ? `holds ${result.taken.join(", ")}` : "reaches no target";
+  await postStatus(forge, head, "success", holds);
+  if (args.json) {
+    console.log(JSON.stringify({ gate, pr: args.pr, ok: true, stage, taken: result.taken, released: result.released, expired: result.expired, pushed: result.pushed }, null, 2));
+    return 0;
+  }
+  console.error(formatSuccess(`${name(args.pr)} ${holds} on ${gate}`));
+  if (result.released.length > 0) console.error(formatInfo(`released ${result.released.join(", ")}, which it no longer reaches`));
+  if (result.expired.length > 0) console.error(formatInfo(`took over ${result.expired.join(", ")} from pull requests that merged or closed`));
+  if (!result.pushed && (result.taken.length > 0 || result.released.length > 0)) console.error(formatInfo("chant/lifecycle was not pushed: this repository has no remote, or recording is off"));
+  return 0;
+}
+
+/** chant unlock */
+export async function runUnlock(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const gate = gateOf(ctx);
+  if (typeof gate !== "string") return fail(gate.error);
+  if (args.pr === undefined) return fail("chant unlock needs the pull or merge request whose locks it releases: --pr <n>");
+  const targets = targetsOf(ctx);
+  let result;
+  try {
+    result = await releaseTargetLocks(gate, args.pr, targets.length > 0 ? { targets } : {});
+  } catch (err) {
+    return fail(`could not release the locks of ${gate}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (args.json) {
+    console.log(JSON.stringify({ gate, pr: args.pr, released: result.released, pushed: result.pushed }, null, 2));
+    return 0;
+  }
+  if (result.released.length === 0) console.error(formatInfo(`pull request ${args.pr} holds no lock${targets.length > 0 ? ` on ${targets.join(", ")}` : ""} on ${gate}`));
+  else console.error(formatSuccess(`released the locks pull request ${args.pr} held on ${result.released.join(", ")}`));
+  return 0;
+}

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

@@ -1278,7 +1278,9 @@ describe("runApprove — a gate with an approval policy (#2508)", () => {
     }));
     const out = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
     expect(out).toContain("log-only mode, so the decision is recorded and does not change the outcome");
-    expect(out).toContain("Quorum: 1 of 2 human approval(s) with role maintainer for this plan (alex)");
+    // #4290: a claimed role is recorded for the policy, and the quorum never counts it.
+    expect(out).toContain("Quorum: 0 of 2 human approval(s) with role maintainer for this plan (none yet)");
+    expect(out).toContain("its roles are read from .chant/trust.json at base");
     errSpy.mockRestore();
   });