@intentius/chant 0.124.12 → 0.124.14

package/dist/cli/handlers/operator.js

@@ -0,0 +1,1162 @@
+/**
+ * `chant operator` / `chant operator status` / `chant approve` (#1485,
+ * epic #1487) — the CLI surface for the native durable-tick operator. See
+ * `../../op/operator.ts` for the loop itself; this module is the thin CLI
+ * shell around it (discover, load activities, print), mirroring
+ * `run.ts`'s `runOpLocal` shape (SIGINT → AbortController, `loadActivities`/
+ * `loadProfiles` from the project's configured lexicons).
+ */
+import { lexiconNames } from "../../lexicon-module.js";
+import { loadChantConfig } from "../../config.js";
+import { build } from "../../build.js";
+import { isObservableDeclarable } from "../../declarable.js";
+import { collectBuildRootContributors, collectChangeSubscribers } from "../plugins.js";
+import { discoverOps, discoverStewards } from "../../op/discover.js";
+import { pickSteward, stewardBesideOf, stewardFormFor, stewardLeaseName, stewardTurnOps, DEFAULT_STEWARD_ENV } from "../../op/steward.js";
+import { loadActivities, loadProfiles } from "../../op/activity-registry.js";
+import { parseDuration } from "../../op/local-executor.js";
+import { discoverConvergeOps, runOperatorRound, runOperatorForever, formatRoundLine, formatSignalLine, DEFAULT_OPERATOR_INTERVAL_MS, acquireStewardLease, createBesideState, waitForBesideRuns, } from "../../op/operator.js";
+import { readLease, releaseLease, currentHolderId, DEFAULT_LEASE_TTL_MS } from "../../lifecycle/lease.js";
+import { readConvergeLedger } from "../../lifecycle/converge-ledger.js";
+import { readRunLedger, runEnvOf } from "../../lifecycle/run-ledger.js";
+import { currentGateOrigin, isModelAuthored, sameOriginRefusal, UNATTESTED_APPROVER, } from "../../lifecycle/gate-origin.js";
+import { appendGateResolution, appendPendingGate, readGateResolutions, readGateLedger, latestResolutionSince, latestPendingGate, isPendingGateExpired, resolveApprovalUrl, isApprovalUrl, } from "../../lifecycle/gate-ledger.js";
+import { isPlanDigest, samePlanDigest } from "../../lifecycle/plan-digest.js";
+import { gateContextDigest, gatePolicyRequest, loadGatePolicyEvaluator, } from "../../op/gate-approval.js";
+import { approverOf, humanQuorumSince, tallyGateApprovals } from "../../op/gate.js";
+import { FAN_OUT_GATE_OP, OVERRIDE_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name.js";
+import { PR_GATE_OP } from "../../pr-loop.js";
+import { pushLifecycleReport, requireLifecycleLedger } from "../../lifecycle/git.js";
+import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note.js";
+import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format.js";
+/** Load the activities a local tick needs, the same way a local run does: core's base activities plus whatever the project's configured lexicons contribute. Best-effort on the lexicon list — an unreadable `chant.config.ts` falls back to base activities only. */
+async function loadOperatorActivities() {
+    let lexicons = [];
+    try {
+        lexicons = lexiconNames((await loadChantConfig(process.cwd())).config.lexicons ?? []);
+    }
+    catch {
+        // No/invalid chant.config — fall back to base activities only.
+    }
+    return Promise.all([loadActivities(lexicons), loadProfiles()]);
+}
+/**
+ * Bind the change-signal seams (#1981) the daemon will keep subscribed, or an
+ * empty list.
+ *
+ * Three gates, in cost order, so a project that gains nothing from this pays
+ * nothing for it:
+ *
+ * 1. No configured lexicon implements `subscribeChanges`. Return immediately,
+ *    without loading config or building anything. This is every project today.
+ * 2. No `--env`. A subscription resolves the same cluster binding a read
+ *    does, and there is no binding to resolve without an environment. Said out
+ *    loud rather than silently skipped, because "why did it not wake" is
+ *    otherwise unanswerable.
+ * 3. The build that supplies the declared entities failed. Warn and fall back
+ *    to the timer. A subscription is an optimization; a build error here must
+ *    not stop the operator, which has its own per-tick build inside the tick.
+ */
+async function collectOperatorSubscribers(ctx, env) {
+    if (!ctx.plugins.some((p) => typeof p.subscribeChanges === "function"))
+        return [];
+    if (!env) {
+        console.error(formatWarning({
+            message: "a change signal needs an environment to resolve its binding, so this runs on the timer alone",
+            hint: "pass --env <env> to let a lexicon's subscribeChanges wake a tick early",
+        }));
+        return [];
+    }
+    const cwd = process.cwd();
+    try {
+        const { config } = await loadChantConfig(cwd);
+        const buildRoots = collectBuildRootContributors(ctx.plugins, config, cwd);
+        const buildResult = await build(config.sourceDir ?? ".", ctx.serializers, undefined, { buildRoots });
+        if (buildResult.errors.length > 0) {
+            console.error(formatWarning({
+                message: "build failed while scoping the change signal, so this runs on the timer alone",
+            }));
+            return [];
+        }
+        // The declared estate, sliced per lexicon: the same slice
+        // `takeSnapshot` hands `describeResources`, and the bound on what any
+        // subscription may watch.
+        const entities = new Map();
+        for (const [name, entity] of buildResult.entities) {
+            if (!isObservableDeclarable(entity))
+                continue;
+            let perLexicon = entities.get(entity.lexicon);
+            if (!perLexicon)
+                entities.set(entity.lexicon, (perLexicon = new Map()));
+            perLexicon.set(name, {
+                entityType: entity.entityType,
+                props: (entity.props != null ? entity.props : {}),
+            });
+        }
+        return collectChangeSubscribers(ctx.plugins, { environment: env, cwd, entities });
+    }
+    catch (err) {
+        console.error(formatWarning({
+            message: `could not scope the change signal, so this runs on the timer alone (${err instanceof Error ? err.message : String(err)})`,
+        }));
+        return [];
+    }
+}
+// ── chant operator ──────────────────────────────────────────────────────────
+/**
+ * `chant operator [--env <env>] [--interval <duration>] [--lease-ttl
+ * <duration>] [--once]` — run scheduled ticks for this project's discovered
+ * ConvergeOps, locally, with no service to install (issue's own worked
+ * example). `--once` runs a single round and exits (also the offline test
+ * story, and what a cron/systemd-timer/k8s-CronJob invoker uses instead of
+ * leaving the daemon running); omitted, the daemon loops until Ctrl-C.
+ */
+export async function runOperator(ctx) {
+    if (ctx.args.steward !== undefined)
+        return runStewardOperator(ctx);
+    const { ops, errors } = await discoverConvergeOps({ env: ctx.args.env });
+    for (const err of errors)
+        console.error(formatWarning({ message: err }));
+    if (ops.length === 0) {
+        console.error(formatWarning({
+            message: ctx.args.env
+                ? `No ConvergeOp declarations found for env "${ctx.args.env}"`
+                : "No ConvergeOp declarations found (*.op.ts built with ConvergeOp(...))",
+        }));
+        return 0;
+    }
+    let activities, profiles;
+    try {
+        [activities, profiles] = await loadOperatorActivities();
+    }
+    catch (err) {
+        console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        return 1;
+    }
+    const intervalMs = ctx.args.interval ? parseDuration(ctx.args.interval) : DEFAULT_OPERATOR_INTERVAL_MS;
+    const leaseTtlMs = ctx.args.leaseTtl ? parseDuration(ctx.args.leaseTtl) : DEFAULT_LEASE_TTL_MS;
+    const controller = new AbortController();
+    // `process.on`, not `.once`: a `.once` listener is gone the instant it
+    // fires, so a second SIGINT arriving while shutdown is still in flight
+    // (the `finally` below hasn't run yet) has no listener left and takes
+    // Node's default disposition — the process ends right there, before
+    // whatever the `finally` was going to do. Kept registered for the whole
+    // shutdown and only removed once it's actually over; `stopping` makes a
+    // repeat signal a no-op rather than a second `abort()`/log line (#2872).
+    let stopping = false;
+    const onSigint = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        console.error(formatWarning({ message: "interrupted — stopping operator" }));
+        controller.abort();
+    };
+    process.on("SIGINT", onSigint);
+    const printRound = (events) => {
+        for (const event of events)
+            console.error(formatInfo(formatRoundLine(event)));
+    };
+    try {
+        if (ctx.args.once) {
+            const events = await runOperatorRound({ env: ctx.args.env, leaseTtlMs, activities, profiles, signal: controller.signal });
+            printRound(events);
+            return events.some((e) => e.kind === "tick-failed") ? 1 : 0;
+        }
+        console.error(formatInfo(`chant operator: watching ${ops.length} ConvergeOp(s) every ${intervalMs}ms (Ctrl-C to stop)`));
+        // A change signal (#1981) only ever shortens the sleep above. Every round
+        // it wakes is the round the timer would have run.
+        const subscribers = await collectOperatorSubscribers(ctx, ctx.args.env);
+        await runOperatorForever({
+            env: ctx.args.env,
+            intervalMs,
+            leaseTtlMs,
+            activities,
+            profiles,
+            signal: controller.signal,
+            onRound: printRound,
+            subscribers,
+            onSignalEvent: (event) => console.error(formatInfo(formatSignalLine(event))),
+        });
+        return 0;
+    }
+    finally {
+        // Only when no signal started this shutdown. After one did, the process
+        // exits right after this returns, and removing the listener would put
+        // SIGINT back to its default disposition for that last stretch: a repeat
+        // signal arriving there ends the process by signal instead of the exit
+        // code (see the steward's `finally` below).
+        if (!stopping)
+            process.removeListener("SIGINT", onSigint);
+    }
+}
+// ── chant operator --steward ────────────────────────────────────────────────
+/**
+ * `chant operator --steward [<name>] [--env <env>] [--interval] [--lease-ttl]
+ * [--once]` (#2731) — a steward's local form. The same Ops the steward runs on
+ * Fountain, on the same crons, one at a time, each under its operator lease,
+ * and the whole process under the steward's own lease.
+ *
+ * Refuses, before ticking anything:
+ * - an environment whose form is `fountain`, because there the composite's
+ *   Agent and Teammate are the steward and this process would be a second
+ *   writer beside them;
+ * - a steward whose lease another live process holds (a second local
+ *   operator for it).
+ */
+export async function runStewardOperator(ctx) {
+    const { stewards, errors, conflicts } = await discoverStewards();
+    for (const err of errors)
+        console.error(formatWarning({ message: err }));
+    for (const conflict of conflicts)
+        console.error(formatError({ message: conflict }));
+    const picked = pickSteward(stewards, ctx.args.steward ?? "");
+    if (typeof picked === "string") {
+        console.error(formatError({ message: picked }));
+        return 1;
+    }
+    const steward = picked;
+    const env = ctx.args.env ?? DEFAULT_STEWARD_ENV;
+    const form = stewardFormFor(steward, env);
+    if (form !== "local") {
+        console.error(formatError({
+            message: `steward "${steward.name}" runs on ${form} in environment "${env}", so a local operator for it would be a second writer`,
+            hint: `Its turns run on the fountain teammate "${steward.name}". Run this in an environment the declaration's form makes local, or change the form.`,
+        }));
+        return 1;
+    }
+    let activities, profiles;
+    try {
+        [activities, profiles] = await loadOperatorActivities();
+    }
+    catch (err) {
+        console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        return 1;
+    }
+    const intervalMs = ctx.args.interval ? parseDuration(ctx.args.interval) : DEFAULT_OPERATOR_INTERVAL_MS;
+    const leaseTtlMs = ctx.args.leaseTtl ? parseDuration(ctx.args.leaseTtl) : DEFAULT_LEASE_TTL_MS;
+    const holder = currentHolderId();
+    const controller = new AbortController();
+    // `process.on`, not `.once` (#2872): a supervisor that signals both a
+    // process group and a child sends a second SIGTERM close behind the
+    // first. A `.once` listener has already unregistered itself by then, so
+    // that second signal takes Node's default disposition and ends the
+    // process immediately — before the `finally` below releases the
+    // steward's lease. Kept registered for the whole shutdown and removed
+    // only once it's over, so a second, third or later signal is a no-op
+    // (`stopping` guards against re-aborting or re-logging) rather than a
+    // fast exit that skips the release.
+    //
+    // Registered before the steward's lease is taken, not after: the lease is
+    // visible to other readers as soon as its ref is written, and the acquire
+    // goes on to push it. A SIGTERM in that stretch found no listener and ended
+    // the process by signal with the lease still held (the
+    // operator-steward-signal e2e test failed this way). Caught here, it aborts
+    // the controller, the loop below starts no round, and the `finally`
+    // releases the lease.
+    let stopping = false;
+    const onSigint = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        console.error(formatWarning({ message: "interrupted — stopping steward" }));
+        controller.abort();
+    };
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigint);
+    // Refuse a second local operator up front rather than letting it loop on
+    // `steward-busy` rounds: one steward is one writer.
+    const first = await acquireStewardLease(steward.name, holder, { ttlMs: leaseTtlMs }).catch((err) => {
+        process.removeListener("SIGINT", onSigint);
+        process.removeListener("SIGTERM", onSigint);
+        throw err;
+    });
+    if (!first.acquired) {
+        console.error(formatError({
+            message: `steward "${steward.name}" is already running (lease held by ${first.heldBy?.holder ?? "another process"} until ${first.heldBy?.expiresAt ?? "?"})`,
+            hint: "One steward is one writer. Stop the other operator, or wait for its lease to expire.",
+        }));
+        process.removeListener("SIGINT", onSigint);
+        process.removeListener("SIGTERM", onSigint);
+        return 1;
+    }
+    const printRound = (events) => {
+        for (const event of events)
+            console.error(formatInfo(formatRoundLine(event)));
+    };
+    const turnOps = stewardTurnOps(steward);
+    const scheduled = turnOps.filter((op) => op.schedule !== undefined);
+    const beside = stewardBesideOf(steward).map((b) => b.op);
+    try {
+        if (ctx.args.once) {
+            // One round, and the runs it started beside the turns (#2861) to their end.
+            const besideState = createBesideState();
+            const events = await runOperatorRound({ steward, holder, leaseTtlMs, activities, profiles, signal: controller.signal, besideState, stewardEnv: env });
+            printRound(events);
+            await waitForBesideRuns(besideState);
+            const ended = besideState.ended.splice(0);
+            printRound(ended);
+            return events.some((e) => e.kind === "tick-failed" || e.kind === "steward-busy" || e.kind === "ready-failed") ||
+                ended.some((e) => e.kind === "beside-ended" && e.code !== 0 && e.code !== 3)
+                ? 1
+                : 0;
+        }
+        console.error(formatInfo(`chant operator: steward ${steward.name} (local) runs ${scheduled.length} scheduled Op(s) of ${turnOps.length} as its turns` +
+            (beside.length > 0 ? `, and ${beside.join(", ")} beside them` : "") +
+            `, checking every ${intervalMs}ms (Ctrl-C to stop)`));
+        await runOperatorForever({
+            steward,
+            stewardEnv: env,
+            holder,
+            intervalMs,
+            leaseTtlMs,
+            activities,
+            profiles,
+            signal: controller.signal,
+            onRound: printRound,
+        });
+        return 0;
+    }
+    finally {
+        // The listeners stay registered through this whole `finally`, not just
+        // the `try` above (#2872): the lease release below is itself async (two
+        // more git plumbing calls), and a repeat signal landing in that window
+        // is exactly the shape the issue reported — removing the listeners
+        // first, before awaiting the release, would reopen the same hole one
+        // step later. `stopping` (set already) makes every repeat here a no-op.
+        // A courtesy: the lease expires on its own if this never runs.
+        const { record } = await readLease(stewardLeaseName(steward.name)).catch(() => ({ record: undefined }));
+        if (record?.holder === holder)
+            await releaseLease(stewardLeaseName(steward.name), holder, record.token).catch(() => false);
+        // Removed only when no signal started this shutdown. After one did, the
+        // CLI goes on to `flushAndExit` (../main.ts) and `process.exit`, and
+        // removing the last SIGTERM listener hands the signal back to its
+        // default disposition for that stretch: a repeat SIGTERM arriving there
+        // ended the process by signal (exit code null) with the lease already
+        // released. That was the operator-steward-signal e2e test's intermittent
+        // failure; a SIGTERM every 2ms after the first hit it 8 runs of 8.
+        if (!stopping) {
+            process.removeListener("SIGINT", onSigint);
+            process.removeListener("SIGTERM", onSigint);
+        }
+    }
+}
+/**
+ * Every gate an op is currently standing at, read from its own gate ledger
+ * (#2119) — a live (unexpired) pending fact with no resolution newer than it.
+ *
+ * Ledger-first, so `chant operator status` sees a gate any run recorded, not
+ * only one a converge tick's dispatch reached. Before this, a plain `chant run
+ * <op>` could not produce a pending gate at all (the executor refused the op
+ * outright), so reading the converge ledger's `gated` outcomes was the whole
+ * story; now it is one source among the ops' own.
+ */
+export async function pendingGatesFor(opName, opts = {}) {
+    const now = opts.now ?? new Date().toISOString();
+    const { resolutions, pending } = await readGateLedger(opName, { cwd: opts.cwd });
+    const standing = [];
+    for (const gate of new Set(pending.map((p) => p.gate))) {
+        const latest = latestPendingGate(pending, gate);
+        if (!latest || isPendingGateExpired(latest, now))
+            continue;
+        if (latestResolutionSince(resolutions, gate, latest.timestamp))
+            continue;
+        standing.push(latest);
+    }
+    return standing.sort((a, b) => a.gate.localeCompare(b.gate));
+}
+async function statusFor(opName, env, cwd) {
+    const [{ records }, { record: lease }] = await Promise.all([
+        readConvergeLedger(env, { cwd }),
+        readLease(opName, { cwd }),
+    ]);
+    const ownRecords = records.filter((r) => r.op === opName);
+    const lastTick = ownRecords.at(-1);
+    const pendingGates = [];
+    const seen = new Set();
+    // The dispatched ops this ConvergeOp's last tick recorded as gated, plus the
+    // ConvergeOp itself — a gate can sit on either.
+    const gateOps = new Set([opName]);
+    const ruleFor = new Map();
+    for (const outcome of lastTick?.outcomes ?? []) {
+        if (outcome.action !== "gated" || !outcome.gateName || !outcome.op)
+            continue;
+        gateOps.add(outcome.op);
+        ruleFor.set(`${outcome.op}\0${outcome.gateName}`, outcome.ruleId);
+    }
+    for (const gateOp of [...gateOps].sort()) {
+        for (const record of await pendingGatesFor(gateOp, { cwd })) {
+            seen.add(`${gateOp}\0${record.gate}`);
+            pendingGates.push({
+                op: gateOp,
+                gate: record.gate,
+                expiresAt: record.expiresAt,
+                ...(ruleFor.get(`${gateOp}\0${record.gate}`) ? { rule: ruleFor.get(`${gateOp}\0${record.gate}`) } : {}),
+                ...(record.description ? { description: record.description } : {}),
+                ...(record.url ? { url: record.url } : {}),
+            });
+        }
+    }
+    // A tick that recorded a `gated` outcome before the executor started writing
+    // pending facts (#2119) still has nothing in `_gates` to read; fall back to
+    // the outcome itself so an in-flight gate isn't dropped on upgrade.
+    if (lastTick) {
+        for (const outcome of lastTick.outcomes) {
+            if (outcome.action !== "gated" || !outcome.gateName || !outcome.op)
+                continue;
+            if (seen.has(`${outcome.op}\0${outcome.gateName}`))
+                continue;
+            const { records: resolutions } = await readGateResolutions(outcome.op, { cwd });
+            if (latestResolutionSince(resolutions, outcome.gateName, lastTick.timestamp))
+                continue;
+            pendingGates.push({
+                rule: outcome.ruleId,
+                op: outcome.op,
+                gate: outcome.gateName,
+                ...(outcome.url ? { url: outcome.url } : {}),
+            });
+        }
+    }
+    return {
+        op: opName,
+        env,
+        lastTick,
+        pendingGates,
+        lease: lease ? { holder: lease.holder, expiresAt: lease.expiresAt } : undefined,
+    };
+}
+/**
+ * `chant operator status [--env <env>] [--json]` — last tick, outcome
+ * counts, and pending gates, read from the `chant/lifecycle` orphan branch
+ * alone (issue acceptance criterion). No live query, no daemon needs to be
+ * running: everything here was already durably recorded by whichever
+ * process (this operator, a bare `chant run <op>`, or another machine's
+ * operator) ran the last tick.
+ *
+ * Pending gates are read from every discovered op's own gate ledger, not only
+ * from a converge tick's `gated` outcomes (#2119) — a gate an ordinary `chant
+ * run <op>` stopped at is the same standing fact and shows up the same way,
+ * under "pending gates" for ops with no converge tick behind them.
+ */
+export async function runOperatorStatus(ctx) {
+    const { ops, errors } = await discoverConvergeOps({ env: ctx.args.env });
+    for (const err of errors)
+        console.error(formatWarning({ message: err }));
+    const rows = await Promise.all(ops.map((d) => statusFor(d.config.name, d.config.labels?.Env ?? "unknown")));
+    // Every other discovered op that is standing at a gate. `discoverOps` sees
+    // the whole project, so an ApplyOp someone ran by hand this morning is here
+    // even though no ConvergeOp ever dispatched it.
+    const covered = new Set(rows.flatMap((r) => r.pendingGates.map((g) => `${g.op ?? r.op} ${g.gate}`)));
+    const { ops: allOps } = await discoverOps();
+    const standalone = [];
+    for (const opName of [...allOps.keys()].sort()) {
+        for (const record of await pendingGatesFor(opName)) {
+            if (covered.has(`${opName} ${record.gate}`))
+                continue;
+            standalone.push({
+                op: opName,
+                gate: record.gate,
+                expiresAt: record.expiresAt,
+                ...(record.description ? { description: record.description } : {}),
+                ...(record.url ? { url: record.url } : {}),
+            });
+        }
+    }
+    // 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;
+        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;
+    }
+    if (ctx.args.json) {
+        console.log(JSON.stringify(standalone.length > 0 ? { rows, pendingGates: standalone } : rows, null, 2));
+        return 0;
+    }
+    for (const row of rows) {
+        console.log(formatBold(`${row.op} (${row.env})`));
+        if (!row.lastTick) {
+            console.log("  no ticks recorded yet");
+        }
+        else {
+            console.log(`  last tick : ${row.lastTick.timestamp}`);
+            console.log(`  ${row.lastTick.log}`);
+        }
+        console.log(`  lease     : ${row.lease ? `held by ${row.lease.holder} (expires ${row.lease.expiresAt})` : "free"}`);
+        if (row.pendingGates.length > 0) {
+            console.log(`  pending gates:`);
+            for (const g of row.pendingGates) {
+                const op = g.op ?? row.op;
+                console.log(`    - ${op} gate "${g.gate}"${g.rule ? ` (rule ${g.rule})` : ""} — resolve: chant approve ${op} ${g.gate}`);
+                if (g.expiresAt)
+                    console.log(`      expires: ${g.expiresAt}`);
+                if (g.url)
+                    console.log(`      approve at: ${g.url}`);
+            }
+        }
+        console.log("");
+    }
+    if (standalone.length > 0) {
+        console.log(formatBold("pending gates (no converge tick)"));
+        for (const g of standalone) {
+            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}`);
+        }
+        console.log("");
+    }
+    return 0;
+}
+/**
+ * Gather the converge/gate history a set of ConvergeOps has recorded, merged
+ * into one timestamp-ordered timeline, oldest first.
+ *
+ * `since` (inclusive) and `limit` are applied after the merge — `limit` keeps
+ * the *newest* n entries, since that is what a log is asked for, and then
+ * prints them oldest-first like every other log.
+ */
+export async function collectOperatorLog(ops, opts = {}) {
+    const wanted = opts.op ? ops.filter((o) => o.name === opts.op) : ops;
+    const sinceMs = opts.since ? new Date(opts.since).getTime() : undefined;
+    const entries = [];
+    const malformed = { converge: 0, gates: 0, runs: 0 };
+    // One read per distinct environment — several ConvergeOps can share one
+    // `<env>/converge.jsonl`, and re-reading it per op would both cost more and
+    // double-count its malformed lines.
+    const envs = [...new Set(wanted.map((o) => o.env))].sort();
+    const opNames = new Set(wanted.map((o) => o.name));
+    const gateOps = new Set();
+    for (const env of envs) {
+        const { records, malformed: bad } = await readConvergeLedger(env, { cwd: opts.cwd });
+        malformed.converge += bad;
+        for (const record of records) {
+            if (!opNames.has(record.op))
+                continue;
+            for (const outcome of record.outcomes) {
+                if (outcome.action === "gated" && outcome.op)
+                    gateOps.add(outcome.op);
+            }
+            entries.push({ kind: "tick", timestamp: record.timestamp, record });
+        }
+    }
+    for (const gateOp of [...gateOps].sort()) {
+        const { records, malformed: bad } = await readGateResolutions(gateOp, { cwd: opts.cwd });
+        malformed.gates += bad;
+        for (const record of records) {
+            entries.push({ kind: "gate-resolution", timestamp: record.timestamp, record });
+        }
+    }
+    // The runs each discovered Op recorded (#2118). Keyed `<env>/runs__<op>`,
+    // so unlike the converge ledger this is one read per (env, op) pair rather
+    // than per env — a ConvergeOp's own ticks and its own runs interleave here.
+    for (const { name, env } of wanted) {
+        const { records, malformed: bad } = await readRunLedger(env, name, { cwd: opts.cwd });
+        malformed.runs += bad;
+        for (const record of records) {
+            entries.push({ kind: "run", timestamp: record.ended, record });
+        }
+    }
+    // Within one instant: the tick first (it is what dispatched anything else),
+    // then the run it dispatched, then the gate resolution against that run.
+    const rank = { tick: 0, run: 1, "gate-resolution": 2 };
+    let merged = entries.sort((a, b) => {
+        const delta = new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime();
+        return delta !== 0 ? delta : rank[a.kind] - rank[b.kind];
+    });
+    if (sinceMs !== undefined)
+        merged = merged.filter((e) => new Date(e.timestamp).getTime() >= sinceMs);
+    if (opts.limit !== undefined && merged.length > opts.limit)
+        merged = merged.slice(-opts.limit);
+    return { entries: merged, malformed };
+}
+function renderLogEntry(entry) {
+    if (entry.kind === "run") {
+        const { record } = entry;
+        const id = `[${record.id.slice(0, 8)}]`;
+        const outcomes = Object.entries(record.outcomes).map(([k, v]) => `${k}=${String(v)}`).join(" ");
+        const steps = record.phases.reduce((n, p) => n + p.steps.length, 0);
+        return [
+            `${record.ended}  ${record.op}@${record.env}  ${id}  run ${record.status} ` +
+                `phases=${record.phases.length} steps=${steps}${outcomes ? `  ${outcomes}` : ""}`,
+        ];
+    }
+    if (entry.kind === "gate-resolution") {
+        const { record } = entry;
+        return [
+            `${record.timestamp}  gate-resolved  ${record.op}/${record.gate} by ${record.resolvedBy}` +
+                (record.url ? `  ${record.url}` : ""),
+        ];
+    }
+    const { record } = entry;
+    const id = record.id ? `[${record.id.slice(0, 8)}]` : "[--------]";
+    const lines = [`${record.timestamp}  ${record.op}@${record.env}  ${id}  ${record.log}`];
+    for (const outcome of record.outcomes) {
+        if (outcome.action !== "gated" || !outcome.gateName)
+            continue;
+        lines.push(`    gated  ${outcome.ruleId} → ${outcome.op ?? "?"} gate "${outcome.gateName}"` +
+            (outcome.url ? `  ${outcome.url}` : ""));
+    }
+    return lines;
+}
+/**
+ * `chant operator log [--env <env>] [--op <name>] [--since <iso>] [--limit
+ * <n>] [--json]` (#2029) — the converge tick history and the gate resolutions
+ * against it, read from the `chant/lifecycle` orphan branch alone.
+ *
+ * `readConvergeLedger` has always returned every tick for an environment;
+ * until this its only caller was `operator status`, which threw the history
+ * away and kept `.at(-1)`. A consumer wanting more than the newest row had to
+ * `git show chant/lifecycle:<env>/converge.jsonl` and parse it — which pins it
+ * to the orphan branch's name, the `<env>/converge.jsonl` path convention, the
+ * `_gates/<op>.jsonl` convention and the on-disk encoding, none of which are
+ * promised contracts. This is the read surface that makes those private again.
+ *
+ * Read-only: no lease, no dispatch, no daemon. Same `--json` discipline as
+ * `operator status` — one JSON document on stdout, diagnostics on stderr.
+ */
+export async function runOperatorLog(ctx) {
+    const { ops, errors } = await discoverConvergeOps({ env: ctx.args.env });
+    for (const err of errors)
+        console.error(formatWarning({ message: err }));
+    if (ops.length === 0) {
+        console.error(formatWarning({ message: "No ConvergeOp declarations found" }));
+        return 0;
+    }
+    if (ctx.args.since && Number.isNaN(new Date(ctx.args.since).getTime())) {
+        console.error(formatError({
+            message: `--since must be an ISO-8601 timestamp (got "${ctx.args.since}")`,
+            hint: "e.g. --since 2026-01-01T00:00:00Z",
+        }));
+        return 1;
+    }
+    if (ctx.args.limit !== undefined && (!Number.isInteger(ctx.args.limit) || ctx.args.limit < 1)) {
+        console.error(formatError({ message: `--limit must be a positive integer (got "${ctx.args.limit}")` }));
+        return 1;
+    }
+    const { entries, malformed } = await collectOperatorLog(ops.map((d) => ({ name: d.config.name, env: d.config.labels?.Env ?? "unknown" })), { op: ctx.args.op, since: ctx.args.since, limit: ctx.args.limit });
+    if (ctx.args.json) {
+        console.log(JSON.stringify({ entries, malformed }, null, 2));
+        return 0;
+    }
+    const unreadable = malformed.converge + malformed.gates + malformed.runs;
+    if (unreadable > 0) {
+        console.error(formatWarning({
+            message: `${unreadable} ledger line(s) were unreadable and are missing from this timeline ` +
+                `(converge: ${malformed.converge}, gates: ${malformed.gates}, runs: ${malformed.runs})`,
+        }));
+    }
+    if (entries.length === 0) {
+        console.error(formatWarning({ message: "No converge ticks or Op runs recorded yet" }));
+        return 0;
+    }
+    for (const entry of entries) {
+        for (const line of renderLogEntry(entry))
+            console.log(line);
+    }
+    return 0;
+}
+// ── chant approve <op> <gate> ───────────────────────────────────────────────
+/**
+ * `chant approve <op> <gate> [--actor <name>] [--note <text>] [--url <url>]
+ * [--expire]` — record the out-of-band resolution fact for a gate a run
+ * stopped at (issue #1485: "resolution is an out-of-band act that writes the
+ * counterpart fact"). Per that issue's leaning on open question 3 ("local
+ * trust in v1"), this performs no authorization check beyond "you can run
+ * `chant approve` locally".
+ *
+ * Since #2119 this closes the loop rather than just narrating it: the next
+ * `chant run <op>` reads the resolution, finds it newer than the gate's
+ * pending fact, and walks through.
+ *
+ * `--expire` is the other half — clear a standing pending fact *without*
+ * approving anything, for a gate that was recorded against a run nobody
+ * intends to finish. It writes no resolution; it appends a pending fact that
+ * is already expired, which supersedes the standing one on an append-only
+ * ledger, so the next run decides the gate from scratch.
+ */
+/** The ledger branch, named in the warnings below so a reader can go look at it. */
+const LIFECYCLE_BRANCH = "chant/lifecycle";
+/**
+ * Push the ledger and say so when it does not land (#2309 review, refs #2310).
+ *
+ * Both write paths here used `pushLifecycle().catch(() => undefined)` and then
+ * printed unconditional success and exited 0. A rejected push — a stale lease,
+ * no credentials, no network — therefore read as a completed approval, which
+ * is the one thing an approval must never do: the operator walks away
+ * believing the gate is answered for everybody, while the resolution exists
+ * only in their own checkout.
+ *
+ * The append is still a correct *local* fact, so this is a warning and not a
+ * failure; the exit code is unchanged. With no remote at all there is nobody
+ * elsewhere to tell, so that case is a quiet suffix and no warning (#3677).
+ */
+async function reportedPush(consequence) {
+    const { pushed, pushWarning } = await pushLifecycleReport();
+    if (pushed)
+        return { pushed, suffix: "" };
+    if (isLifecycleLocalNote(pushWarning))
+        return { pushed, suffix: ` (${LIFECYCLE_LOCAL_NOTE})` };
+    console.error(formatWarning({
+        message: `The push to the remote did not land: ${pushWarning ?? "no reason given"}`,
+        hint: consequence,
+    }));
+    return { pushed, suffix: " (local only — the push did not land)" };
+}
+export async function runApprove(ctx) {
+    const opName = ctx.args.path;
+    const gate = ctx.args.extraPositional;
+    if (!opName || opName === "." || !gate) {
+        console.error(formatError({ message: "Usage: chant approve <op> <gate>" }));
+        return 1;
+    }
+    if (ctx.args.expire) {
+        // Same guard as the approve path below (#2303): `--expire` reads the
+        // standing fact and appends beside it, so a clone that never fetched the
+        // branch would both fail to see the fact it is expiring and replace the
+        // branch with the expiry alone.
+        try {
+            await requireLifecycleLedger();
+        }
+        catch (err) {
+            console.error(formatError({
+                message: `Cannot expire the gate: ${err instanceof Error ? err.message : String(err)}`,
+            }));
+            return 1;
+        }
+        const now = new Date().toISOString();
+        const standing = latestPendingGate((await readGateLedger(opName)).pending, gate);
+        if (!standing || isPendingGateExpired(standing, now)) {
+            console.error(formatWarning({
+                message: `Gate "${gate}" on "${opName}" has no standing pending fact — nothing to expire`,
+            }));
+            return 0;
+        }
+        await appendPendingGate({
+            op: opName,
+            gate,
+            timestamp: now,
+            expiresAt: now,
+            ...(standing.description ? { description: standing.description } : {}),
+        });
+        const push = await reportedPush(`The expiry is recorded locally on ${LIFECYCLE_BRANCH}. Until it reaches the remote, ` +
+            `a run in another checkout still sees the old pending fact.`);
+        console.error(formatSuccess(`Gate "${gate}" on "${opName}" expired at ${now} — not approved` + push.suffix));
+        console.error(formatInfo(opName === FAN_OUT_GATE_OP
+            ? `The next \`chant components fan-out\` decides this gate from scratch and records a fresh pending fact.`
+            : PR_GATE_OP.test(opName)
+                ? `The next \`chant components pr-apply\` decides this gate from scratch and records a fresh pending fact.`
+                : opName === WORKSPACE_UPGRADE_GATE_OP
+                    ? `The next \`chant workspace upgrade ${gate}\` decides this gate from scratch and records a fresh pending fact.`
+                    : `The next \`chant run ${opName}\` decides this gate from scratch and records a fresh pending fact.`));
+        return 0;
+    }
+    // #3760: an override of a denied plan names its rules and gives a reason.
+    if (opName === OVERRIDE_GATE_OP) {
+        const { runOverrideApprove } = await import("./override-approve.js");
+        return runOverrideApprove(ctx);
+    }
+    if (ctx.args.rules !== undefined || ctx.args.reason !== undefined) {
+        console.error(formatError({
+            message: `--rule and --reason override a denied plan: chant approve ${OVERRIDE_GATE_OP} <subject> --rule <id> --reason <text>`,
+            hint: `To approve gate "${gate}" on "${opName}", put any prose in --note.`,
+        }));
+        return 1;
+    }
+    // `--approver` wins over `--actor`, the same precedence `chant run approve`
+    // has applied since #2126 (`../handlers/run.ts`'s `runOpApprove`). Reading
+    // only `--actor` here meant every README that teaches `--approver you`
+    // recorded the shell user instead (#2192).
+    const outcome = await recordGateApproval(opName, gate, {
+        actor: ctx.args.approver ?? ctx.args.actor,
+        note: ctx.args.note,
+        url: ctx.args.url,
+        plan: ctx.args.plan,
+        ...(ctx.args.env !== undefined ? { environment: ctx.args.env } : {}),
+        allowSameOrigin: ctx.args.allowSameOrigin,
+        ...(ctx.args.roles ? { roles: ctx.args.roles } : {}),
+        ...(ctx.args.agent ? { agent: true } : {}),
+        ...(ctx.args.sign !== undefined ? { sign: ctx.args.sign } : {}),
+        ...(ctx.args.relayedBy !== undefined ? { relayedBy: ctx.args.relayedBy } : {}),
+    });
+    if (!outcome.ok)
+        return 1;
+    // #3683: start the CI job that waits at this gate again.
+    if (ctx.args.resumeRun || ctx.args.resume !== undefined) {
+        const { resumeAfterApproval } = await import("./gate-resume.js");
+        return resumeAfterApproval(opName, gate, outcome.record.environment, outcome.pushed);
+    }
+    console.error(formatInfo(`This records the resolution as a fact; it does not itself re-run anything. ` +
+        (opName === FAN_OUT_GATE_OP
+            ? `Repeat the \`chant components fan-out\` command and it walks through gate "${gate}".`
+            : PR_GATE_OP.test(opName)
+                ? `The pull request's apply (\`chant components pr-apply\`) walks through gate "${gate}" when it plans this same digest.`
+                : opName === WORKSPACE_UPGRADE_GATE_OP
+                    ? `Repeat \`chant workspace upgrade ${gate}\` with the same target, and it applies the patch this approval names.`
+                    : `Run \`chant run ${opName}\` and it walks through gate "${gate}".`)));
+    return 0;
+}
+/**
+ * The ledger write behind `chant approve` — extracted so `chant run approve`
+ * (#2121) records the identical fact before waking the runtime that hosts the
+ * gated run, instead of growing a second, drifting writer.
+ *
+ * Prints the same warning for an undiscovered op and the same success line as
+ * `chant approve` always did; the caller adds whatever it does next.
+ *
+ * Since #2300 the resolution names the plan it approves. By default that is
+ * the standing pending fact's plan — the one the gated run produced — so the
+ * common path is still `chant run`, read, `chant approve`. With no pending
+ * fact and no `--plan`, this refuses: there is nothing on the ledger saying
+ * what would be approved, and writing a resolution anyway is what made an
+ * approval mean "the next run" instead of "this plan".
+ */
+export async function recordGateApproval(opName, gate, opts) {
+    const { ops } = await discoverOps();
+    // `fan-out` is the op name every `chant components fan-out` gate is recorded
+    // under (../handlers/fan-out.ts). It is a command rather than a declaration,
+    // so there is no `*.op.ts` to find and nothing is wrong when none is there.
+    if (!ops.has(opName) && opName !== FAN_OUT_GATE_OP && opName !== WORKSPACE_UPGRADE_GATE_OP && opName !== OVERRIDE_GATE_OP) {
+        console.error(formatWarning({
+            message: `Op "${opName}" was not found among discovered *.op.ts declarations — recording the resolution anyway`,
+        }));
+    }
+    // Read the branch before appending to it (#2303 finding 2). Without this,
+    // an approve in a clone that never fetched `chant/lifecycle` builds its
+    // commit from an empty tree with no parent and replaces the branch with a
+    // single commit holding only this resolution — the pending fact it is
+    // answering is discarded rather than appended to.
+    try {
+        await requireLifecycleLedger();
+    }
+    catch (err) {
+        console.error(formatError({
+            message: `Cannot record the approval: ${err instanceof Error ? err.message : String(err)}`,
+            hint: "The pending fact this answers lives on that branch; appending without it would drop it.",
+        }));
+        return { ok: false };
+    }
+    // #2028: the resolution's link is typed. `--url` wins; otherwise, running
+    // inside the PR/MR job that carries the change is itself the address, the
+    // same env fallback `--actor` uses. `--note` stays free-text prose.
+    const url = opts.url ?? resolveApprovalUrl();
+    if (url && !isApprovalUrl(url)) {
+        console.error(formatError({
+            message: `--url must be an absolute http/https URL (got "${url}")`,
+            hint: "Pass the PR/MR link, or omit --url and put prose in --note.",
+        }));
+        return { ok: false };
+    }
+    // #2300: an approval is for a plan, so this command has to know which one.
+    // `--plan` names it outright; otherwise it comes off the gate's standing
+    // pending fact — the plan the run that stopped at this gate produced, which
+    // is the plan whoever is typing this just read. There is deliberately no
+    // third fallback: approving with no plan in sight is the behaviour
+    // INTENTIUS/choudoufu#1026 measured, where the resolution authorised the
+    // next run rather than anything anyone had seen.
+    // #2574: a component gate's pending facts carry the environment they were
+    // recorded in, and an approval answers one environment. `--env` picks it;
+    // without it, the newest standing fact decides, and the success line below
+    // names the environment it chose.
+    const ledgerBefore = await readGateLedger(opName);
+    const pendingFor = (all) => {
+        const bound = all.some((p) => p.gate === gate && p.environment !== undefined);
+        return bound && opts.environment !== undefined ? all.filter((p) => p.environment === opts.environment) : all;
+    };
+    const standing = latestPendingGate(pendingFor(ledgerBefore.pending), gate);
+    const environment = standing?.environment;
+    let planDigest;
+    if (opts.plan !== undefined) {
+        if (!isPlanDigest(opts.plan)) {
+            console.error(formatError({
+                message: `--plan must be a plan digest ("jcs1-sha256:" or "sha256:", then 64 hex characters), got "${opts.plan}"`,
+                hint: "Copy it from the gated run's `plan :` line, or from the pending-gate summary. It is not a plan file path.",
+            }));
+            return { ok: false };
+        }
+        planDigest = opts.plan;
+    }
+    else {
+        if (!standing) {
+            console.error(formatError({
+                message: opts.environment !== undefined && ledgerBefore.pending.some((p) => p.gate === gate && p.environment !== undefined)
+                    ? `Gate "${gate}" on "${opName}" has no pending fact in environment "${opts.environment}", so there is no plan to approve`
+                    : `Gate "${gate}" on "${opName}" has no pending fact, so there is no plan to approve`,
+                hint: `Run \`chant run ${opName}\` first — it plans, stops at the gate, and records the plan this ` +
+                    `approval would be for. To approve a plan you already have the digest for, pass ` +
+                    `\`--plan <digest>\`.`,
+            }));
+            return { ok: false };
+        }
+        planDigest = standing.planDigest;
+    }
+    // chant#2384 — the gate's whole value is that its two halves have different
+    // authors. At a shell they do: a person runs, reads the plan, and approves.
+    // On MCP and ACP the person's only act was launching the server, and every
+    // call after is the model's, so a gate reached over one of those channels and
+    // resolved over the same one has no second party in it. Refused by default,
+    // the way #2300 refuses a plan nobody approved.
+    const origin = opts.origin ?? currentGateOrigin();
+    const ledger = await readGateLedger(opName);
+    const standingForOrigin = latestPendingGate(pendingFor(ledger.pending), gate);
+    // chant#3485: a gate that is never resolved over MCP or ACP says so on its
+    // own record, or on its Op's config. No flag overrides this one.
+    if (isModelAuthored(origin) && (standingForOrigin?.neverOverMcp || ops.get(opName)?.config.neverOverMcp)) {
+        console.error(formatError({
+            message: `Gate "${gate}" on "${opName}" is never resolved over ${origin === "acp" ? "ACP" : "MCP"}`,
+            hint: `Approvals belong to people: \`chant approve ${opName} ${gate}\` at a shell.`,
+        }));
+        return { ok: false };
+    }
+    // #3170: a gate that asks a decision point passes on the point's answer,
+    // which the run cites on the ledger. An approval here would count for nothing.
+    if (standingForOrigin?.answer) {
+        console.error(formatError({
+            message: `Gate "${gate}" on "${opName}" asks decision point ${standingForOrigin.answer.point}, so its answer passes the gate, not an approval`,
+            hint: `Answer the question: \`chant workspace points answer ${standingForOrigin.answer.id} --answer <value> --by <name>\`, then run \`chant run ${opName}\` again.`,
+        }));
+        return { ok: false };
+    }
+    const refusal = sameOriginRefusal(standingForOrigin?.origin, origin);
+    if (refusal && !opts.allowSameOrigin) {
+        console.error(formatError({
+            message: `Gate "${gate}" on "${opName}" cannot be resolved from here: ${refusal}`,
+            hint: `Approve it from a channel the run did not come from — \`chant approve ${opName} ${gate}\` ` +
+                `at a shell is the usual one. If resolving from the same channel genuinely is the intent, ` +
+                `pass --allow-same-origin, which records that it was deliberate.`,
+        }));
+        return { ok: false };
+    }
+    // #3402: the relay is a principal, on one line (the seal's payload is LF-joined).
+    const relayedBy = opts.relayedBy?.trim();
+    if (opts.relayedBy !== undefined && (!relayedBy || /[\r\n]/.test(relayedBy))) {
+        console.error(formatError({
+            message: `--relayed-by needs one principal on one line (got ${JSON.stringify(opts.relayedBy)})`,
+            hint: "Name who relayed the approval, such as --relayed-by github:<login> or a principal the signers file lists.",
+        }));
+        return { ok: false };
+    }
+    const resolvedBy = opts.actor
+        ?? (isModelAuthored(origin)
+            // A channel that cannot attest to a name does not get to write one down.
+            // "unattested" reads as what it is; a name the model chose would read in
+            // the ledger exactly like a name a person gave.
+            ? UNATTESTED_APPROVER
+            : process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER ?? "unknown");
+    // #2508: who this is, as the gate's quorum and policy read it. A model on
+    // MCP or ACP is an agent whatever it claims, the same reasoning that gives
+    // it `UNATTESTED_APPROVER` for a name.
+    const approver = {
+        kind: opts.agent || isModelAuthored(origin) ? "agent" : "human",
+        ...(opts.roles && opts.roles.length > 0 ? { roles: [...new Set(opts.roles)] } : {}),
+    };
+    // #3163, ws-080: the declaration at base may require a checkable approver
+    // (identity.attribution "identified") and a signed approval for this gate
+    // (identity.gates). Both are judged before anything is written.
+    const cwd = opts.cwd ?? process.cwd();
+    const identity = await import("../../workspace/identity.js");
+    const { scopeSource } = await import("../../workspace/write-scope.js");
+    const scope = scopeSource(cwd);
+    try {
+        identity.refuseUnidentified(scope, [resolvedBy], opts.actor !== undefined ? "--actor" : "the approver");
+        if (relayedBy)
+            identity.refuseUnidentified(scope, [relayedBy], "--relayed-by");
+    }
+    catch (err) {
+        if (!(err instanceof identity.IdentityError))
+            throw err;
+        console.error(formatError({
+            message: `Gate "${gate}" on "${opName}" was not approved: ${err.message}`,
+            hint: "Pass --actor <forge identity or signer>, as the surface that signed the person in maps them, for example --actor github:<login>.",
+        }));
+        return { ok: false };
+    }
+    const rule = identity.gateAdmissionFrom(scope, gate);
+    if (rule && opts.sign === undefined) {
+        console.error(formatError({
+            message: `Gate "${gate}" needs a signed approval: chant.workspace.json at base names it in identity.gates` +
+                (rule.requirement.class !== null ? `, from the class ${rule.requirement.class}` : "") +
+                `, and this approval is not signed`,
+            hint: `chant approve ${opName} ${gate} --actor <principal> --sign [<key file>], with a key ${scope.policy.signersPath} at base lists for that principal.`,
+        }));
+        return { ok: false };
+    }
+    const timestamp = new Date().toISOString();
+    let seal;
+    if (opts.sign !== undefined) {
+        const { resolveSigningKey, sealGateApproval, SealError } = await import("../../workspace/trust/seal.js");
+        try {
+            const key = resolveSigningKey(opts.sign, cwd);
+            try {
+                seal = sealGateApproval(key.file, {
+                    op: opName,
+                    gate,
+                    ...(environment !== undefined ? { environment } : {}),
+                    ...(planDigest !== undefined ? { planDigest } : {}),
+                    resolvedBy,
+                    ...(relayedBy ? { relayedBy } : {}),
+                    timestamp,
+                });
+            }
+            finally {
+                key.cleanup();
+            }
+        }
+        catch (err) {
+            if (!(err instanceof SealError))
+                throw err;
+            console.error(formatError({ message: `Gate "${gate}" on "${opName}" was not approved: ${err.message}` }));
+            return { ok: false };
+        }
+    }
+    if (rule) {
+        const why = rule.refuses({
+            op: opName,
+            gate,
+            ...(environment !== undefined ? { environment } : {}),
+            ...(planDigest !== undefined ? { planDigest } : {}),
+            resolvedBy,
+            ...(relayedBy ? { relayedBy } : {}),
+            timestamp,
+            seal,
+        });
+        if (why !== null) {
+            console.error(formatError({
+                message: `Gate "${gate}" on "${opName}" was not approved: ${why}`,
+                hint: `identity.gates.${gate} in chant.workspace.json at base counts only an approval signed by a key ${scope.policy.signersPath} lists for the approver` +
+                    (rule.requirement.class !== null ? `, who holds the role of the class ${rule.requirement.class}` : "") + ".",
+            }));
+            return { ok: false };
+        }
+    }
+    // #2508: a gate with a policy has it evaluated for this approval now, while
+    // the approver is known, against the context the gated run recorded. The
+    // decision is written next to the approval, so a pass can be traced to the
+    // rule that allowed it.
+    const approval = standingForOrigin?.approval;
+    let policyDecision;
+    if (approval?.policy) {
+        try {
+            const evaluator = opts.evaluator ?? (await loadGatePolicyEvaluator(approval.policy.lexicon));
+            const answer = await evaluator.evaluateGatePolicy(approval.policy, gatePolicyRequest({
+                op: opName,
+                gate,
+                resolvedBy,
+                approver,
+                ...(planDigest !== undefined ? { planDigest } : {}),
+                ...(approval.context ? { context: approval.context } : {}),
+            }));
+            policyDecision = {
+                policy: approval.policy.name,
+                version: approval.policy.version,
+                mode: approval.mode,
+                contextDigest: gateContextDigest(approval.context),
+                decision: answer.decision,
+                determining: answer.determining,
+                errors: answer.errors,
+            };
+        }
+        catch (err) {
+            console.error(formatError({
+                message: `Gate "${gate}" on "${opName}" declares policy "${approval.policy.name}", which could not be evaluated: ${err instanceof Error ? err.message : String(err)}`,
+                hint: `Install the ${approval.policy.lexicon} lexicon in this project, or approve from a checkout that has it.`,
+            }));
+            return { ok: false };
+        }
+    }
+    const { record } = await appendGateResolution({
+        op: opName,
+        gate,
+        resolvedBy,
+        ...(relayedBy ? { relayedBy } : {}),
+        timestamp,
+        ...(seal ? { seal } : {}),
+        approver,
+        ...(policyDecision ? { policyDecision } : {}),
+        ...(opts.note ? { note: opts.note } : {}),
+        ...(url ? { url } : {}),
+        ...(planDigest !== undefined ? { planDigest } : {}),
+        ...(environment !== undefined ? { environment } : {}),
+        origin,
+        ...(refusal && opts.allowSameOrigin ? { sameOriginOverride: true } : {}),
+    });
+    const push = await reportedPush(`The resolution is recorded locally on ${LIFECYCLE_BRANCH}. Until it reaches the remote, ` +
+        `a run in another checkout will not see it.`);
+    console.error(formatSuccess(`Gate "${gate}" on "${opName}" resolved by ${record.resolvedBy}` +
+        (record.relayedBy ? `, relayed by ${record.relayedBy},` : "") +
+        ` at ${record.timestamp}` +
+        (record.url ? ` (${record.url})` : "") +
+        (record.seal ? `, signed with ${record.seal.key}` : "") +
+        push.suffix));
+    if (record.planDigest) {
+        console.error(formatInfo(`This approves the plan ${record.planDigest}` +
+            (record.environment !== undefined ? ` in environment "${record.environment}"` : "") +
+            ", and only that plan. A run whose fresh plan differs refuses rather than applying it."));
+    }
+    if (approval) {
+        for (const line of describeApprovalProgress(approval, record, ledger.resolutions, standingForOrigin, ledger.pending)) {
+            console.error(formatInfo(line));
+        }
+    }
+    return { ok: true, record, pushed: push.pushed };
+}
+/**
+ * What a just-recorded approval did to a gate with an `approval` block
+ * (#2508): the policy's decision and whether it binds, then the quorum count
+ * for this plan. The run decides the gate from the ledger; these lines only
+ * say what it will find.
+ */
+export function describeApprovalProgress(approval, record, prior, standing, pending = standing ? [standing] : []) {
+    const lines = [];
+    const decision = record.policyDecision;
+    if (decision) {
+        const rules = decision.determining.length > 0 ? ` (${decision.determining.join(", ")})` : "";
+        const binds = approval.mode === "enforce"
+            ? decision.decision === "allow"
+                ? "In enforce mode this permit passes the gate on its own."
+                : "In enforce mode only a permit passes the gate on its own, so this approval counts only toward the quorum."
+            : "The gate is in log-only mode, so the decision is recorded and does not change the outcome.";
+        lines.push(`Policy "${decision.policy}" ${decision.version}: ${decision.decision}${rules}. ${binds}`);
+        for (const error of decision.errors)
+            lines.push(`Policy evaluation error: ${error}`);
+    }
+    const since = standing?.timestamp ?? new Date(0).toISOString();
+    // #3206: count the humans the way the run will, back past facts re-recorded for this plan.
+    const humansSince = standing && samePlanDigest(standing.planDigest, record.planDigest) ? humanQuorumSince(pending, standing) : since;
+    const tally = tallyGateApprovals([...prior, record], record.gate, since, record.planDigest, approval, humansSince);
+    const roles = approval.quorum?.roles ? ` with role ${approval.quorum.roles.join(" or ")}` : "";
+    const who = tally.counted.map((r) => r.resolvedBy).join(", ") || "none yet";
+    lines.push(`Quorum: ${tally.counted.length} of ${tally.need} human approval(s)${roles} for this plan (${who}).`);
+    if (!tally.counted.includes(record)) {
+        lines.push(approverOf(record).kind === "agent"
+            ? "An agent's approval does not count toward the quorum."
+            : `This approval does not count toward the quorum: the approver claims none of its roles (${approval.quorum?.roles?.join(", ")}).`);
+    }
+    return lines;
+}