@intentius/chant 0.124.13 → 0.124.14

package/dist/cli/handlers/run.js

@@ -0,0 +1,1191 @@
+import { lexiconNames } from "../../lexicon-module.js";
+import { resolve, dirname, basename } from "node:path";
+import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
+import { loadChantConfig, resolveAutoReleaseDisabled, InvalidChantConfigError } from "../../config.js";
+import { discoverOps, discoverStewards } from "../../op/discover.js";
+import { stewardWorkHolder } from "../../op/work-lease-run.js";
+import { DRIFT_EXIT_CODE } from "../../op/types.js";
+import { findPolicyGateStep, OpRunFailure } from "../../op/local-executor.js";
+import { approveCommand, describeGateMismatch, gateIsSealed } from "../../op/gate.js";
+import { summaryLedgerPrefix, writeGatedRunSummary } from "../../op/gate-summary.js";
+import { createLocalOpRuntime } from "../../op/runtimes/local.js";
+import { pointAnswerCommand, renderHuman, renderJson } from "../../op/local-output.js";
+import { loadPlugins } from "../plugins.js";
+import { recordGateApproval } from "./operator.js";
+import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format.js";
+import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli.js";
+import { stewardBesideFor, stewardFormFor, stewardTurnLeaseName, DEFAULT_STEWARD_ENV } from "../../op/steward.js";
+import { holdBesideLease } from "../../op/steward-beside.js";
+import { acquireStewardTurn, STEWARD_TURN_WAIT_MS } from "../../op/operator.js";
+import { releaseLease, currentHolderId } from "../../lifecycle/lease.js";
+import { StaleLockError } from "../../lifecycle/git.js";
+import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note.js";
+import { renderDriverHuman, renderDriverJson } from "../../components/driver-output.js";
+import { ndjsonProgressSink } from "../../components/run-progress.js";
+import { maybeRecordAutoRelease } from "../../components/auto-release.js";
+import { maybePersistBuildManifest } from "../../components/manifest-persistence.js";
+import { runOpGenerate } from "./run-generate.js";
+/**
+ * The exit code a run that stopped at an unapproved gate uses (#2119).
+ * Deliberately not 1: a gate is a standing fact waiting on a human, and a CI
+ * job that treats it as a failure would page someone for a decision nobody has
+ * made yet.
+ */
+export const GATED_EXIT_CODE = 3;
+/**
+ * The exit code this invocation gives a gated run — {@link GATED_EXIT_CODE}
+ * unless `--gated-exit <code>` asked for another one (#2243).
+ *
+ * The mapping lives here rather than in a shell wrapper in every generated
+ * pipeline, so one rule covers every forge: GitHub Actions has no neutral
+ * conclusion for a `run:` step, so a push-to-main apply that stops at its gate
+ * paints the branch red on every merge until someone approves. `--gated-exit
+ * 0` is how the job that knows a pending approval is not a failure says so.
+ *
+ * Only the gated outcome is remapped. A failed run still returns 1, so the
+ * flag can never hide a broken apply. Returns `undefined` after printing the
+ * refusal when the value is not a process exit status.
+ */
+function resolveGatedExitCode(ctx) {
+    const raw = ctx.args.gatedExit;
+    if (raw === undefined)
+        return GATED_EXIT_CODE;
+    if (!Number.isInteger(raw) || raw < 0 || raw > 255) {
+        console.error(formatError({
+            message: "--gated-exit expects a whole number from 0 to 255",
+            hint: `Got ${Number.isNaN(raw) ? "a non-numeric value" : String(raw)}. ` +
+                `Pass --gated-exit 0 to make a run that stopped at a gate a success for CI; ` +
+                `omit the flag for the default ${GATED_EXIT_CODE}.`,
+        }));
+        return undefined;
+    }
+    return raw;
+}
+/**
+ * Whether a settled run's records carry a true `Drift` outcome (#3675) — the
+ * one `lifecycleDiff` surfaces through `outcomeAttribute` on a WatchOp,
+ * ApplyOp, ReconcileOp or ConvergeOp step.
+ */
+export function runFoundDrift(records) {
+    for (const record of records ?? []) {
+        const outcomes = record.outcomes ?? (record.outcome ? [record.outcome] : []);
+        if (outcomes.some((o) => o.name === "Drift" && o.value === true))
+            return true;
+    }
+    return false;
+}
+/**
+ * The exit code for a completed run (#3675): 0, or {@link DRIFT_EXIT_CODE}
+ * when the run found drift and either `--fail-on-drift` or the Op's own
+ * `failOn: "drift"` asked for drift to fail the job. Says why on stderr when
+ * it remaps, since every step in the run succeeded.
+ */
+export function completedRunExitCode(opName, config, failOnDriftFlag, records) {
+    if (!(failOnDriftFlag || config.failOn === "drift"))
+        return 0;
+    if (!runFoundDrift(records))
+        return 0;
+    const why = failOnDriftFlag ? "--fail-on-drift" : `the Op declares failOn: "drift"`;
+    console.error(formatWarning({
+        message: `Op "${opName}" found drift; exiting ${DRIFT_EXIT_CODE} because ${why}`,
+    }));
+    return DRIFT_EXIT_CODE;
+}
+/**
+ * What a gated run leaves behind for CI, beyond the stderr block the renderers
+ * already print (#2243): the same gate, approve command and ledger path
+ * appended to whatever file `GITHUB_STEP_SUMMARY` names, so the run page says
+ * what is pending without anyone opening the log.
+ *
+ * Also says on stderr that the exit code was remapped, when it was. A job that
+ * passes `--gated-exit 0` reports success, and the one line that explains why
+ * a zero-exit run applied nothing belongs next to the gate itself.
+ */
+async function reportGatedRun(summary, exitCode) {
+    writeGatedRunSummary({ ...summary, sealed: await gateIsSealed(summary.gate) });
+    if (exitCode !== GATED_EXIT_CODE) {
+        console.error(formatInfo(`gated: exiting ${exitCode} because --gated-exit asked for it. Nothing after the gate ran.`));
+    }
+}
+/**
+ * `run list/status/log/cancel --components` reported a component's *durable*
+ * run state — a run that outlives the CLI process and can be queried, signalled
+ * or cancelled afterwards (#589). #2116 removed the runtime that provided it.
+ * The local driver runs a component to completion inside this process, so there
+ * is no separate run left to ask about once the command returns.
+ *
+ * Returns 1; the caller returns it straight back.
+ */
+function refuseDurableComponentSubcommand(what, hint) {
+    console.error(formatError({
+        message: `\`${what}\` read a component's durable run state, which #2116 removed`,
+        hint,
+    }));
+    return 1;
+}
+// ── The runtime seam (#2121) ────────────────────────────────────────────────
+/**
+ * Resolve the one runtime this invocation talks to.
+ *
+ * `--on <name>` picks the named lexicon's `opRuntime` (`../../lexicon.ts`).
+ * Without it, `run.on` in `chant.config.ts` does (#2523), and without either,
+ * core's built-in `local` provider runs the Op in this process. `local`, from
+ * either place, names the built-in provider. Every `chant run` subcommand goes
+ * through whichever comes back, so there is one dispatch path rather than a
+ * branch per runtime.
+ *
+ * A lexicon already loaded into the command context wins the lookup — that is
+ * how a test hands in a stub, and how a command that loaded plugins for its
+ * own reasons avoids loading them twice. Otherwise the project's configured
+ * lexicons are loaded on demand: `chant run` is not a `requiresPlugins`
+ * command, and a plain local run must not start paying for plugin resolution.
+ *
+ * Returns `undefined` after printing an actionable error — an unconfigured
+ * name is answered with the configured list, a configured lexicon that hosts
+ * nothing is named outright. A `run.on` default gets the same messages as
+ * `--on`, labelled `run.on` and the config file instead of `--on`.
+ */
+async function resolveOpRuntime(ctx) {
+    const choice = await chooseOpRuntime(ctx);
+    if (!choice)
+        return undefined;
+    const { on, source, configured } = choice;
+    if (!on || on === "local")
+        return createLocalOpRuntime({ projectPath: resolve(".") });
+    // How the error names the choice, and how to get the built-in runtime back.
+    const label = source === "flag" ? `--on ${on}` : `run.on "${on}" in ${choice.configFile}`;
+    const fallback = source === "flag"
+        ? "Omit --on to run on the built-in local runtime."
+        : `Fix \`run.on\` in ${choice.configFile}, or pass --on local to run on the built-in local runtime.`;
+    let plugin = ctx.plugins.find((p) => p.name === on);
+    if (!plugin && configured.includes(on)) {
+        plugin = (await loadPlugins([on]).catch(() => []))[0];
+    }
+    if (!plugin) {
+        const known = [...new Set([...ctx.plugins.map((p) => p.name), ...configured])];
+        console.error(formatError({
+            message: `${label}: "${on}" is not a configured lexicon`,
+            hint: known.length > 0
+                ? `Configured lexicons: ${known.join(", ")}. ${fallback}`
+                : `chant.config.ts configures no lexicons. ${fallback}`,
+        }));
+        return undefined;
+    }
+    if (!plugin.opRuntime) {
+        console.error(formatError({
+            message: `${label}: lexicon "${on}" does not host Op runs`,
+            hint: `It declares no opRuntime. ${fallback}`,
+        }));
+        return undefined;
+    }
+    return plugin.opRuntime;
+}
+/**
+ * The runtime name `--on`, then `run.on` in `chant.config.ts` (#2523), then
+ * the built-in default pick, without loading any lexicon.
+ *
+ * Reads the configured list straight from `chant.config.ts` rather than
+ * through `resolveProjectLexicons`: `--on` names a *configured* lexicon, and
+ * that helper's fallback is a source scan of the whole project, which is a
+ * long wait to be told a name is wrong.
+ *
+ * A config that fails to load leaves the flag's choice alone, as before. With
+ * no flag, a config whose `run` block is invalid is refused (printed, then
+ * `undefined`): running the Op locally would hide that the project asked for
+ * another runtime. Any other load failure falls back to the built-in runtime,
+ * which is what a project with no `run.on` got before. `quiet` skips printing
+ * that refusal, for a caller that only peeks at the choice and leaves the
+ * reporting to {@link resolveOpRuntime}.
+ */
+async function chooseOpRuntime(ctx, quiet = false) {
+    const flag = ctx.args.on;
+    if (flag === "local")
+        return { on: "local", source: "flag", configured: [], configFile: "chant.config.ts" };
+    let configured = [];
+    let configuredOn;
+    let configFile = "chant.config.ts";
+    try {
+        const { config, configPath } = await loadChantConfig(resolve("."));
+        configured = lexiconNames(config.lexicons ?? []);
+        configuredOn = config.run?.on;
+        if (configPath)
+            configFile = basename(configPath);
+    }
+    catch (err) {
+        if (!flag && err instanceof InvalidChantConfigError && err.key === "run") {
+            if (quiet)
+                return undefined;
+            console.error(formatError({
+                message: err.message,
+                hint: "`run.on` names the runtime that hosts this project's Op runs: a configured lexicon with an opRuntime, or \"local\". Fix it, or pass --on to pick the runtime for this run.",
+            }));
+            return undefined;
+        }
+        // No/unreadable chant.config.ts: an `--on` error says so by listing nothing.
+    }
+    if (flag)
+        return { on: flag, source: "flag", configured, configFile };
+    if (configuredOn)
+        return { on: configuredOn, source: "config", configured, configFile };
+    return { on: undefined, source: "default", configured, configFile };
+}
+/** An ISO-8601 instant trimmed to what a table cell has room for. */
+function shortInstant(iso) {
+    return iso ? iso.slice(0, 19).replace("T", " ") : "—";
+}
+/** Print what a runtime reports for a settled or in-flight run. */
+function renderRuntimeStatus(label, name, runtime, status) {
+    console.log(formatBold(`${label}: ${name}`));
+    console.log(`  Runtime     : ${runtime}`);
+    console.log(`  Run ID      : ${status.runId}`);
+    console.log(`  State       : ${status.state}`);
+    console.log(`  Started     : ${shortInstant(status.startedAt)}`);
+    if (status.endedAt)
+        console.log(`  Ended       : ${shortInstant(status.endedAt)}`);
+    if (status.records) {
+        const settled = status.records.filter((r) => r.status !== "skipped").length;
+        console.log(`  Steps       : ${settled}/${status.records.length} settled`);
+    }
+    if (status.gate) {
+        console.log(`  Gate        : ${status.gate.name} (pending since ${status.gate.since})`);
+    }
+    if (status.error)
+        console.log(`  Error       : ${status.error}`);
+}
+// ── chant run list ──────────────────────────────────���─────────────────────────
+export async function runOpList(ctx) {
+    if (ctx.args.components)
+        return runComponentsList();
+    return runOpListOnRuntime(ctx);
+}
+/**
+ * `chant run list` on the resolved runtime (#2121) — discover every Op, ask
+ * the runtime what it knows about each, print one row per Op. The runtime
+ * answers for all of them in one call (`list`), so a hosted runtime can do it
+ * in one round trip instead of N.
+ *
+ * An Op the runtime has no run for prints with no state annotation.
+ */
+async function runOpListOnRuntime(ctx) {
+    const runtime = await resolveOpRuntime(ctx);
+    if (!runtime)
+        return 1;
+    const { ops, errors } = await discoverOps();
+    for (const err of errors)
+        console.error(formatError({ message: err }));
+    if (ops.size === 0) {
+        console.error(formatWarning({ message: "No Op definitions found (*.op.ts)" }));
+        return 0;
+    }
+    let states;
+    try {
+        states = await runtime.list([...ops.values()].map((d) => d.config));
+    }
+    catch (err) {
+        console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        return 1;
+    }
+    console.log("NAME".padEnd(26) +
+        "PHASES".padEnd(8) +
+        "DEPENDS".padEnd(20) +
+        "OVERVIEW");
+    for (const [name, { config }] of ops) {
+        const phases = String(config.phases.length);
+        const deps = config.depends?.join(",") ?? "—";
+        const overview = config.overview.length > 36
+            ? config.overview.slice(0, 33) + "..."
+            : config.overview;
+        const state = states.get(name)?.state;
+        console.log((name + (state ? ` [${state}]` : "")).padEnd(26) +
+            phases.padEnd(8) +
+            deps.padEnd(20) +
+            overview);
+    }
+    return 0;
+}
+/**
+ * `chant run list --components` (#599) listed discovered components annotated
+ * with each one's durable run status. Discovery alone is what `chant list
+ * --components` already prints, so with the status column gone (#2116) this
+ * subcommand has nothing of its own left to say.
+ */
+function runComponentsList() {
+    return Promise.resolve(refuseDurableComponentSubcommand("chant run list --components", "Run `chant list --components` to see discovered components."));
+}
+// ── chant run status <name> ───────────────────────────────────────────────────
+export async function runOpStatus(ctx) {
+    const name = ctx.args.extraPositional;
+    if (!name) {
+        const label = ctx.args.components ? "Component" : "Op";
+        console.error(formatError({ message: `${label} name is required: chant run status <name>` }));
+        return 1;
+    }
+    if (ctx.args.components) {
+        return refuseDurableComponentSubcommand("chant run status --components", "Run `chant components status` for a component's release and build state.");
+    }
+    return runOpStatusOnRuntime(ctx, name);
+}
+/**
+ * `chant run status <name>` on the resolved runtime (#2121). A runtime with
+ * no record of the Op is not an error: it prints one line saying so and exits
+ * 0, because "this runtime has never run it" is a true answer to the question.
+ */
+async function runOpStatusOnRuntime(ctx, name) {
+    const runtime = await resolveOpRuntime(ctx);
+    if (!runtime)
+        return 1;
+    let status;
+    try {
+        status = await runtime.status(name);
+    }
+    catch (err) {
+        console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        return 1;
+    }
+    if (!status) {
+        console.error(formatInfo(`No run of Op "${name}" is recorded on the "${runtime.name}" runtime.`));
+        return 0;
+    }
+    renderRuntimeStatus("Op", name, runtime.name, status);
+    return 0;
+}
+// ── chant run log <name> ──────────────────────────────────────────────────────
+export async function runOpLog(ctx) {
+    const name = ctx.args.extraPositional;
+    if (!name) {
+        const label = ctx.args.components ? "Component" : "Op";
+        console.error(formatError({ message: `${label} name is required: chant run log <name>` }));
+        return 1;
+    }
+    if (ctx.args.components) {
+        return refuseDurableComponentSubcommand("chant run log --components", "Run `chant components status` for a component's recorded releases.");
+    }
+    return runOpLogOnRuntime(ctx, name);
+}
+/**
+ * `chant run log <name>` on the resolved runtime (#2121) — the runtime's own
+ * run history, newest first, `--limit <n>` rows at most.
+ */
+async function runOpLogOnRuntime(ctx, name) {
+    const runtime = await resolveOpRuntime(ctx);
+    if (!runtime)
+        return 1;
+    let records;
+    try {
+        records = await runtime.log(name, ctx.args.limit === undefined ? undefined : { limit: ctx.args.limit });
+    }
+    catch (err) {
+        console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        return 1;
+    }
+    if (records.length === 0) {
+        console.error(formatInfo(`No run of Op "${name}" is recorded on the "${runtime.name}" runtime.`));
+        return 0;
+    }
+    console.log("RUN-ID".padEnd(38) +
+        "STATUS".padEnd(10) +
+        "STARTED".padEnd(26) +
+        "ENDED");
+    for (const record of records) {
+        console.log(record.id.padEnd(38) +
+            record.status.padEnd(10) +
+            shortInstant(record.started).padEnd(26) +
+            shortInstant(record.ended));
+    }
+    return 0;
+}
+// ── chant run approve <op> <gate> ────────────────────────────────────────────
+/**
+ * `chant run approve <op> <gate> [--approver] [--url] [--note]` (#2121) — the
+ * rename of `chant run signal`, and a different act.
+ *
+ * A gate resolution is a fact, not a message: the ledger write is the whole
+ * of it, and it is the same write `chant approve` performs
+ * (`recordGateApproval`, ./operator.ts), so a resolution recorded here reads
+ * back identically. The runtime is told afterwards, through its optional
+ * `resolveGate`, purely so a runtime that parks a run mid-flight can wake it
+ * now rather than on its next tick. A runtime without that method is not a
+ * failure — the fact is recorded either way, and the next run re-reads it.
+ */
+export async function runOpApprove(ctx) {
+    const opName = ctx.args.extraPositional;
+    const gate = ctx.args.extraPositional2;
+    if (!opName || !gate) {
+        console.error(formatError({ message: "Usage: chant run approve <op> <gate>" }));
+        return 1;
+    }
+    const runtime = await resolveOpRuntime(ctx);
+    if (!runtime)
+        return 1;
+    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.sign !== undefined ? { sign: ctx.args.sign } : {}),
+        ...(ctx.args.relayedBy !== undefined ? { relayedBy: ctx.args.relayedBy } : {}),
+    });
+    if (!outcome.ok)
+        return 1;
+    if (!runtime.resolveGate) {
+        console.error(formatInfo(`The "${runtime.name}" runtime reads the resolution when the op next runs — re-run \`chant run ${opName}\`.`));
+        return 0;
+    }
+    try {
+        // `--env` on the approve line names the environment the woken run runs
+        // in (#3539); without it the runtime keeps the gated run's.
+        if (ctx.args.env !== undefined)
+            await runtime.resolveGate(opName, gate, outcome.record, { env: ctx.args.env });
+        else
+            await runtime.resolveGate(opName, gate, outcome.record);
+    }
+    catch (err) {
+        console.error(formatWarning({
+            message: `The resolution is recorded, but the "${runtime.name}" runtime could not be woken: ` +
+                (err instanceof Error ? err.message : String(err)),
+            hint: `Re-run \`chant run ${opName} --on ${runtime.name}\` once the runtime is reachable.`,
+        }));
+        return 1;
+    }
+    console.error(formatSuccess(`Runtime "${runtime.name}" was notified of the resolution.`));
+    return 0;
+}
+/**
+ * `chant run signal` was renamed `chant run approve` (#2121). Registered so
+ * the old spelling says where the verb went instead of being read as an Op
+ * named "signal".
+ */
+export function runOpSignalRenamed(ctx) {
+    const opName = ctx.args.extraPositional ?? "<op>";
+    const gate = ctx.args.extraPositional2 ?? "<gate>";
+    console.error(formatError({
+        message: "`chant run signal` is now `chant run approve`",
+        hint: `A gate is resolved by recording the fact, not by sending a message: chant run approve ${opName} ${gate}`,
+    }));
+    return Promise.resolve(1);
+}
+// ── chant run cancel <name> ───────────────────────────────────────────────────
+/** `chant run cancel <name>` — asks the resolved runtime (#2121) to stop the Op's active run. */
+export async function runOpCancel(ctx) {
+    const name = ctx.args.extraPositional;
+    if (!name) {
+        console.error(formatError({ message: "Op name is required: chant run cancel <name>" }));
+        return 1;
+    }
+    if (!ctx.args.force) {
+        console.error(formatWarning({
+            message: `Cancelling "${name}" will stop the active run`,
+            hint: "Use --force to confirm cancellation",
+        }));
+        return 1;
+    }
+    if (ctx.args.components) {
+        return refuseDurableComponentSubcommand("chant run cancel --components", "A component run lives and dies with the `chant run --components` process — interrupt that instead.");
+    }
+    return runOpCancelOnRuntime(ctx, name);
+}
+/**
+ * `chant run cancel <name>` on the resolved runtime (#2121). `--force` is
+ * already checked by the caller, so a runtime only ever sees a confirmed
+ * request; a runtime with nothing to cancel says so in its own words and the
+ * command exits non-zero.
+ */
+async function runOpCancelOnRuntime(ctx, name) {
+    const runtime = await resolveOpRuntime(ctx);
+    if (!runtime)
+        return 1;
+    try {
+        await runtime.cancel(name, { force: true });
+    }
+    catch (err) {
+        console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        return 1;
+    }
+    console.error(formatSuccess(`Cancellation requested for Op "${name}" on the "${runtime.name}" runtime`));
+    return 0;
+}
+// ── chant run <name> — main command ───────────────────────────────────────────
+/**
+ * `chant run <name>` dispatcher.
+ *
+ * Every run goes through the runtime resolved by `--on` (#2121); without it,
+ * core's built-in local provider runs the Op in this process, where a `gate`
+ * is decided against the gate ledger and ends the run pending approval
+ * (#2119), exit code 3.
+ *
+ * `chant run --components <name|all>` (#585) is a separate target: discovered
+ * `Component` declarations dispatched through the interpret driver
+ * (`../../components/driver.ts`) rather than a `*.op.ts` Op. Checked first,
+ * mirroring `runGraph`'s `if (ctx.args.components) return
+ * runComponentGraph(ctx)` branch (../handlers/graph.ts).
+ *
+ * chant #1116 — `--report` with `--components` is checked and hard-errored
+ * before that dispatch, and #2116 retired `--report` on the Op path too: it
+ * rendered a past durable run's workflow history, which no runtime keeps any
+ * more. Both refuse rather than falling through to a real dispatch — the
+ * component case was observed live reaching an actual cloud shell-out.
+ */
+/**
+ * Pre-flight for `chant run <op> --sandbox` on an Op containing a `policyGate`
+ * step (chant #2003). `--sandbox` is a global flag, and `../main.ts` arms the
+ * process-wide policy latch off it for every command — so the gate's
+ * `loadPolicyChecks` refuses mid-run with a message addressed to a chant
+ * maintainer ("This is a chant bug"), which is not an answer a user can act
+ * on. Refuse here instead, before anything runs, naming the combination and
+ * what to do about it.
+ *
+ * Keyed on the flag rather than on whether the project declares
+ * `lint.policies`: the flag is what arms the latch, and a gate that builds the
+ * project in this process is a divergence from what `--sandbox` promises
+ * whether or not a policy module happens to be declared. Returns true when the
+ * caller should stop.
+ */
+function refusesPolicyGateUnderSandbox(ctx, config, opName) {
+    if (!ctx.args.sandbox)
+        return false;
+    if (!findPolicyGateStep(config))
+        return false;
+    console.error(formatError({
+        message: `Op "${opName}" has a policyGate step, which cannot run under --sandbox: the gate builds this project and imports its lint.policies in the chant process, which --sandbox forbids.`,
+        hint: "Re-run without --sandbox, or drop the policyGate step from this Op. Running the gate itself inside the sandbox boundary is tracked on chant#1157.",
+    }));
+    return true;
+}
+/**
+ * `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".
+ *
+ * An Op the steward runs beside its turns (#2861) takes the Op's own lease
+ * instead, renewed for as long as the run lasts, and never the turn: the run
+ * is one at a time with the runs the operator starts of it, and holds none
+ * of the steward's other Ops up. Held already, it refuses at once, naming
+ * the holder.
+ *
+ * `undefined` (via the caller checking `owner`) when no steward lists this
+ * op — the ordinary, untouched path.
+ */
+async function stewardTurnGate(opName, ctx) {
+    const { stewards } = await discoverStewards().catch(() => ({ stewards: new Map() }));
+    let owner;
+    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") {
+        // `run.on: "fountain"` asks for the steward's thread as much as the flag
+        // does (#2523).
+        if ((await chooseOpRuntime(ctx, true))?.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.`,
+        };
+    }
+    if (stewardBesideFor(owner, opName))
+        return besideLeaseGate(opName, owner.name, ctx);
+    const holder = currentHolderId();
+    let turn;
+    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); } };
+}
+/**
+ * The lease a `chant run` of an Op beside a steward's turns holds (#2861):
+ * the Op's own, as `--holder` (the operator passes `<steward>/<op>@<its
+ * holder>`) or this process.
+ */
+async function besideLeaseGate(opName, steward, ctx) {
+    const holder = ctx.args.holder ?? currentHolderId();
+    let held;
+    try {
+        held = await holdBesideLease(opName, holder);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            message: `Op "${opName}" runs beside steward "${steward}"'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 a process was killed mid-write; check refs/chant/lease/${opName} for a stale lock.`,
+        };
+    }
+    if (!held.acquired) {
+        return {
+            ok: false,
+            message: `Op "${opName}" runs beside steward "${steward}"'s turns, one run at a time, and a run of it is in progress` +
+                (held.heldBy ? ` (held by ${held.heldBy})` : ""),
+            hint: `Wait for that run to end and re-run \`chant run ${opName}\`; \`chant workspace status --json\` lists it under the steward. Its lease expires on its own if the process holding it died.`,
+        };
+    }
+    return { ok: true, release: held.release };
+}
+export async function runOp(ctx) {
+    if (ctx.args.generate) {
+        if (ctx.args.components) {
+            console.error(formatError({
+                message: "`chant run --components --generate` is not a command",
+                hint: "Generate a component pipeline with `chant build --components --generate <lexicon>`, or Op pipelines with `chant run --generate <provider>`.",
+            }));
+            return 1;
+        }
+        return runOpGenerate(ctx);
+    }
+    if (ctx.args.components && ctx.args.report) {
+        console.error(formatError({
+            message: "--report is not supported with --components",
+            hint: "No preview/dry-run mode exists yet for the component driver (see chant#1116). Omit --report.",
+        }));
+        return 1;
+    }
+    if (ctx.args.components)
+        return runOpComponents(ctx);
+    if (ctx.args.report) {
+        console.error(formatError({
+            message: "`chant run --report` rendered a past durable run, which #2116 removed",
+            hint: "Run `chant run log <op>` for the runtime's own run history.",
+        }));
+        return 1;
+    }
+    return runOpOnRuntime(ctx);
+}
+// ── Auto-release recording post-run (#597) ──────────────────────────────────
+/**
+ * After a successful `chant run --components` (local executor), auto-emit
+ * one release record per successfully deployed component that published a
+ * digest-bearing artifact — reusing `maybeRecordAutoRelease`
+ * (../../components/auto-release.ts), which itself reuses
+ * `../../lifecycle/release-ledger.ts`'s `appendReleaseRecord` verbatim. Never
+ * called on a failed run: both call sites below only reach this after
+ * confirming `result.success`/`componentResult.ok`, so a failed deploy writes
+ * nothing, by construction.
+ *
+ * Also persists the component's accumulated `BuildArchiveManifest`, when its
+ * composition produced one, to the durable build-manifest store (#609,
+ * ../../components/manifest-persistence.ts, ../../lifecycle/build-ledger-
+ * store.ts) — the missing piece that lets `chant components status`'s
+ * `componentBom`/`build.reproducibility` resolve to a real manifest instead
+ * of always reporting `null`. Same `disabled` opt-out flag as the release
+ * record: both are "durably record this successful deploy" side effects, so
+ * `--no-release-record`/`release.autoRecord: false` gates persistence too
+ * rather than needing a second, easy-to-forget knob (see
+ * `ManifestPersistOptions.disabled`'s doc).
+ *
+ * Best-effort and silent on the happy path: a skip (opted out, no digest/
+ * manifest, no actor) is unremarkable and not printed; only an actual write
+ * failure (`reason: "error"`) is surfaced, as a warning — never a nonzero
+ * exit, since the deploy itself already succeeded and a ledger-write hiccup
+ * must not retroactively fail it.
+ *
+ * Exported for `chant components fan-out` (#2420), which applies components
+ * through a different runner and would otherwise leave no trace in the release
+ * ledger for work `chant run --components` records. Each result is filtered on
+ * its own `ok`, so a fan-out that partly succeeded records exactly the
+ * components that did.
+ *
+ * Returns the records it wrote, for `--digest-file` (#2602).
+ */
+export async function recordAutoReleasesForRun(results, env, runId, disabled) {
+    const recorded = [];
+    for (const componentResult of results) {
+        if (!componentResult.ok)
+            continue;
+        const outcome = await maybeRecordAutoRelease({
+            component: componentResult.component,
+            env,
+            success: true,
+            records: componentResult.records,
+            runId,
+            // A local-executor id resolves nowhere — say so in a field (#2045).
+            runOrigin: { forge: "local" },
+        }, { disabled });
+        if (!outcome.recorded && outcome.reason === "error") {
+            console.error(formatWarning({
+                message: `release record for "${componentResult.component}"@${env} was not recorded: ${outcome.error}`,
+            }));
+        }
+        else if (outcome.recorded) {
+            recorded.push(outcome.record);
+            console.error(formatInfo(`Recorded release: ${formatBold(componentResult.component)}@${env} -> ${outcome.record.digest} (commit ${outcome.commit.slice(0, 7)})`));
+        }
+        const manifestOutcome = await maybePersistBuildManifest({ success: true, records: componentResult.records }, { disabled });
+        if (!manifestOutcome.persisted && manifestOutcome.reason === "error") {
+            console.error(formatWarning({
+                message: `build manifest for "${componentResult.component}"@${env} was not persisted: ${manifestOutcome.error}`,
+            }));
+        }
+        else if (manifestOutcome.persisted) {
+            console.error(formatInfo(`Persisted build manifest: ${formatBold(componentResult.component)} -> ${manifestOutcome.manifestDigest} (commit ${manifestOutcome.commit.slice(0, 7)})`));
+        }
+    }
+    return recorded;
+}
+// ── chant run --components <name|all> ────────────────────────────────────────
+/**
+ * `chant run --components <name|all> [--env <env>]` (#585) — the interpret
+ * driver's CLI entrypoint, and since #2116 the only component run path there
+ * is. `args.path` is the component name (or `all`), matching `chant run
+ * <name>`'s Op-dispatch convention exactly (`args.path` is the Op name there
+ * too) rather than a project directory — components are always discovered from
+ * the current working directory, the same way Op discovery (`discoverOps()`)
+ * never takes a project-path argument either.
+ *
+ * The selector resolves through the runtime's `runComponents` and runs on the
+ * local in-process driver; a `gate` is decided against the gate ledger when
+ * the driver reaches it (#2119), and one nobody has approved ends the run with
+ * exit code 3 and the `chant approve` line, exactly as `chant run <op>` does.
+ *
+ * On a successful run, auto-emits one release-ledger record per component
+ * that published a digest (#597, `recordAutoReleasesForRun` above) — a
+ * *post-run* CLI step, not a change to the driver itself (`../../components/
+ * driver.ts` stays capability-agnostic and knows nothing about the ledger).
+ * Opt out with `--no-release-record` or `chant.config.ts`'s
+ * `release.autoRecord: false`; the default is ON. A failed run never reaches
+ * this step, so it writes nothing.
+ *
+ * chant #1108 — resolves this invocation's declared build-time parameters
+ * (`chant.config.ts`'s `buildParams`, against `--param`/`--params-file`/a
+ * declared `env` mapping) the exact same way `chant build` does
+ * (`resolveCliBuildParams`, shared with `buildCommand`), BEFORE anything
+ * discovers/imports a `*.component.ts` file.
+ * Before this, `params.*` (`@intentius/chant/params`) was always `{}` under
+ * this command, no matter what a component's `chant.config.ts` declared or a
+ * CI job's environment supplied — see chant #1108. `chant.config.ts` is
+ * loaded once here (with the same defensive fallback the post-run
+ * auto-release check below used to apply itself) and reused for that check,
+ * rather than loaded a second time.
+ */
+export async function runOpComponents(ctx) {
+    const selector = ctx.args.path;
+    if (!selector || selector === ".") {
+        console.error(formatError({
+            message: "Component name is required: chant run --components <name|all>",
+            hint: "Run `chant list --components` to see available components.",
+        }));
+        return 1;
+    }
+    const gatedExit = resolveGatedExitCode(ctx);
+    if (gatedExit === undefined)
+        return 1;
+    const projectPath = resolve(".");
+    const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} }));
+    const paramsResolution = resolveCliBuildParams(config.buildParams, {
+        cli: parseParamFlags(ctx.args.param),
+        paramsFile: ctx.args.paramsFile,
+        verbose: ctx.args.verbose,
+    });
+    if (!paramsResolution.success) {
+        for (const message of paramsResolution.errors)
+            console.error(message);
+        return 1;
+    }
+    const runtime = await resolveOpRuntime(ctx);
+    if (!runtime)
+        return 1;
+    if (!runtime.runComponents) {
+        console.error(formatError({
+            message: `--components is not supported on the "${runtime.name}" runtime`,
+            hint: "Omit --on to run components on the built-in local runtime.",
+        }));
+        return 1;
+    }
+    const env = ctx.args.env ?? "local";
+    // Seed cross-component/cross-stack outputs from upstream jobs' dumped files
+    // (`--seed-outputs`), so a single-component run resolves references to a
+    // component that ran in an earlier CI job.
+    const seededOutputs = {};
+    for (const file of ctx.args.seedOutputs ?? []) {
+        try {
+            Object.assign(seededOutputs, JSON.parse(readFileSync(resolve(file), "utf8")));
+        }
+        catch (err) {
+            console.error(formatError({
+                message: `--seed-outputs: could not read "${file}": ${err instanceof Error ? err.message : String(err)}`,
+            }));
+            return 1;
+        }
+    }
+    // `--progress-json` (#M3, behold roadmap): stream one NDJSON RunProgressEvent
+    // per line to stdout while the run executes, so a consumer (e.g. behold) can
+    // render live wave/component/phase/step progress instead of tailing raw
+    // logs. Purely additive: when the flag is absent, `onProgress` stays
+    // `undefined` and every `onProgress?.(...)` call in the driver is a no-op —
+    // behavior is byte-for-byte unchanged from before this flag existed.
+    const onProgress = ctx.args.progressJson ? ndjsonProgressSink() : undefined;
+    const result = await runtime.runComponents(projectPath, selector, {
+        env: ctx.args.env,
+        componentOutputs: seededOutputs,
+        onProgress,
+        sandbox: ctx.args.sandbox,
+        buildParams: paramsResolution.provenance,
+    });
+    // Dump the accumulated outputs for a downstream job to seed from. Written
+    // even on failure (partial outputs) so a resumed run still has what completed.
+    if (ctx.args.dumpOutputs && result.run) {
+        const dumpPath = resolve(ctx.args.dumpOutputs);
+        mkdirSync(dirname(dumpPath), { recursive: true });
+        writeFileSync(dumpPath, JSON.stringify(result.run.componentOutputs, null, 2));
+    }
+    if (!result.success && !result.run && !result.gated) {
+        console.error(formatError({ message: result.error ?? "Failed to run component(s)" }));
+        return 1;
+    }
+    if (result.run) {
+        if (ctx.args.json)
+            renderDriverJson(result.run);
+        else
+            renderDriverHuman(result.run);
+    }
+    // Gated (#2119): the same fact-and-stop the Op path takes, and the same
+    // exit code. Nothing to release — the component stopped short of finishing.
+    if (result.gated) {
+        const { gate } = result.gated;
+        console.error(formatWarning({
+            message: `component "${result.gated.component}" is gated on "${gate.gate}" — pending approval`,
+        }));
+        // #2574: an approval stands, but for another plan or for none. Say so,
+        // with the command that replaces it.
+        const sealed = await gateIsSealed(gate.gate);
+        if (result.gated.mismatch) {
+            console.error(formatWarning({ message: describeGateMismatch(gate.op, gate.gate, result.gated.mismatch, sealed) }));
+        }
+        console.error(formatInfo(`approve : ${approveCommand(gate.op, gate.gate, gate.environment, undefined, sealed)}`));
+        if (gate.url)
+            console.error(formatInfo(`approve at: ${gate.url}`));
+        console.error(formatInfo(`expires : ${gate.expiresAt}`));
+        // #2310: this run's own append reached only the local chant/lifecycle
+        // branch. The gate is still right to stand, but an operator elsewhere
+        // cannot see the pending fact to approve it, and nothing else here says
+        // why not.
+        if (result.gated.pushed === false && isLifecycleLocalNote(result.gated.pushWarning)) {
+            console.error(formatInfo(LIFECYCLE_LOCAL_NOTE));
+        }
+        else if (result.gated.pushed === false) {
+            console.error(formatWarning({
+                message: `the pending fact was not pushed to the remote: ${result.gated.pushWarning ?? "recorded locally only"}`,
+                hint: "an operator working from a clone of the remote cannot approve it until it does",
+            }));
+        }
+        await reportGatedRun({
+            op: gate.op,
+            gate: gate.gate,
+            ...(gate.description ? { description: gate.description } : {}),
+            expiresAt: gate.expiresAt,
+            ...(gate.url ? { url: gate.url } : {}),
+            ...(result.gated.pushed === false ? { pushed: false, pushWarning: result.gated.pushWarning } : {}),
+            ...(gate.planDigest ? { planDigest: gate.planDigest } : {}),
+            ...(await summaryLedgerPrefix()),
+            ...(gate.environment ? { environment: gate.environment } : {}),
+        }, gatedExit);
+        return gatedExit;
+    }
+    if (result.success && result.run) {
+        const disabled = resolveAutoReleaseDisabled(config, ctx.args.noReleaseRecord);
+        const recorded = await recordAutoReleasesForRun(result.run.results, env, `local-${Date.now()}`, disabled);
+        // `--digest-file` (#2602): the releases this run recorded, one
+        // `<component>=<digest>` line each, the form `chant components promote
+        // --digest` takes. A generated promote job reads it to promote exactly
+        // what this job built, not whatever is latest in the environment.
+        if (ctx.args.digestFile) {
+            const digestPath = resolve(ctx.args.digestFile);
+            mkdirSync(dirname(digestPath), { recursive: true });
+            writeFileSync(digestPath, recorded.map((r) => `${r.component}=${r.digest}\n`).join(""));
+        }
+    }
+    return result.success ? 0 : 1;
+}
+/**
+ * `chant run <name>` on the resolved runtime (#2121) — the built-in `local`
+ * provider by default, a lexicon's `opRuntime` under `--on <name>`.
+ *
+ * This function knows nothing about how a run happens. It discovers the Op,
+ * runs the CLI-level pre-flights that are about flags rather than execution
+ * (`--sandbox` over a `policyGate` step, #2003), hands the config to the
+ * runtime, and renders whatever comes back. On the local runtime that is the
+ * executor's own `OpRunResult`, so `--json` and the human render are exactly
+ * what they were before the seam existed; a runtime that reports only a state
+ * gets the terser render instead.
+ */
+export async function runOpOnRuntime(ctx) {
+    const opName = ctx.args.path;
+    if (!opName || opName === ".") {
+        console.error(formatError({
+            message: "Op name is required: chant run <name>",
+            hint: "Run `chant run list` to see available Ops",
+        }));
+        return 1;
+    }
+    const gatedExit = resolveGatedExitCode(ctx);
+    if (gatedExit === undefined)
+        return 1;
+    const { ops, errors } = await discoverOps();
+    for (const err of errors)
+        console.error(formatWarning({ message: err }));
+    const discovered = ops.get(opName);
+    if (!discovered) {
+        const names = [...ops.keys()];
+        console.error(formatError({
+            message: `Op "${opName}" not found`,
+            hint: names.length > 0
+                ? `Available: ${names.join(", ")}`
+                : "No *.op.ts files found — create one",
+        }));
+        return 1;
+    }
+    const { config } = discovered;
+    // 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) {
+        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
+    // runtime that carries it (fountain, #3555) is not this process.
+    const work = await resolveRunWork(ctx, config, runtime);
+    if (work === null) {
+        await stewardGate?.release?.();
+        return 1;
+    }
+    // `--progress-json` streams one NDJSON StepRecord per settled step, fed by
+    // whatever the runtime reports through `progress`.
+    const progress = ctx.args.progressJson ? ndjsonProgressSink() : undefined;
+    // Ctrl-C, or a SIGTERM (the signal a steward's operator sends this process
+    // when it runs beside the steward's turns and the operator itself stops,
+    // and what a plain `kill <pid>` sends with no signal named), aborts
+    // in-flight activities (kills their child processes) instead of orphaning
+    // them. `process.on`, not `.once` (chant#2872's shape, here too): a second
+    // signal arriving before the `finally` below has released this run's lease
+    // (`stewardGate`, for a beside run) must not fall through to Node's default
+    // disposition and skip that release. `stopping` makes a repeat a no-op; the
+    // listeners are removed only after the release, at the very end of
+    // `finally`, not before it.
+    const controller = new AbortController();
+    let stopping = false;
+    const onSigint = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        console.error(formatWarning({ message: "interrupted — stopping Op" }));
+        controller.abort();
+    };
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigint);
+    try {
+        // `--param name=value` reaches the runtime (#3539). The local runtime
+        // has no use for it; fountain reads `agent` to pick the steward and posts
+        // the rest on the command line it hands the sandbox.
+        const params = parseParamFlags(ctx.args.param);
+        const handle = await runtime.start(config, {
+            env: ctx.args.env,
+            ...(params ? { params } : {}),
+            ...(ctx.args.profile !== undefined ? { profile: ctx.args.profile } : {}),
+            progress,
+            signal: controller.signal,
+            ...(work ? { work } : {}),
+        });
+        const status = await handle.result();
+        if (status.result) {
+            // The executor's own render already prints a gate, its approve line
+            // and its expiry (#2119).
+            const sealed = status.result.gate ? await gateIsSealed(status.result.gate.gate) : false;
+            if (ctx.args.json)
+                renderJson(status.result, undefined, sealed);
+            else
+                renderHuman(status.result, undefined, sealed);
+        }
+        else {
+            renderRuntimeStatus("Op", opName, runtime.name, status);
+            if (status.state === "gated" && status.gate) {
+                console.error(formatWarning({
+                    message: `Op "${opName}" is waiting on gate "${status.gate.name}"`,
+                    hint: `Record the resolution with: ${approveCommand(opName, status.gate.name, undefined, undefined, await gateIsSealed(status.gate.name))}`,
+                }));
+            }
+        }
+        // Exit 3 for a gated run (#2119) — a distinct code so CI can tell
+        // "waiting on a human" from a broken op, and retry the one but not the
+        // other. `--gated-exit <code>` remaps that one outcome and nothing else
+        // (#2243).
+        if (status.state === "gated") {
+            // The local runtime carries the whole pending fact on its result; a
+            // runtime that reports only a state carries the gate's name alone.
+            const pending = status.result?.gate;
+            const gate = pending?.gate ?? status.gate?.name;
+            if (gate) {
+                await reportGatedRun({
+                    op: opName,
+                    gate,
+                    ...(pending?.description ? { description: pending.description } : {}),
+                    ...(pending?.expiresAt ? { expiresAt: pending.expiresAt } : {}),
+                    ...(pending?.url ? { url: pending.url } : {}),
+                    // #2310: the local runtime knows whether this run's own append
+                    // reached the remote; a runtime that reports only a state does not.
+                    ...(status.result?.gatePushed === false
+                        ? { pushed: false, pushWarning: status.result.gatePushWarning }
+                        : {}),
+                    ...(pending?.planDigest ? { planDigest: pending.planDigest } : {}),
+                    ...(await summaryLedgerPrefix()),
+                }, gatedExit);
+            }
+            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;
+        }
+        if (status.state !== "completed")
+            return 1;
+        // A completed run that found drift exits 2 when asked to (#3675), so a
+        // scheduled drift job turns red without a script that reads the ledger.
+        return completedRunExitCode(opName, config, ctx.args.failOnDrift, status.result?.records ?? status.records);
+    }
+    catch (err) {
+        if (err instanceof OpRunFailure) {
+            const sealed = err.result.gate ? await gateIsSealed(err.result.gate.gate) : false;
+            if (ctx.args.json)
+                renderJson(err.result, undefined, sealed);
+            else
+                renderHuman(err.result, undefined, sealed);
+            return 1;
+        }
+        console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        return 1;
+    }
+    finally {
+        // 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). The
+        // listeners stay registered until after this release (chant#2872): it is
+        // itself async, and removing them first would let a repeat signal in
+        // that window fall through to Node's default disposition and skip it.
+        await stewardGate?.release?.();
+        process.removeListener("SIGINT", onSigint);
+        process.removeListener("SIGTERM", onSigint);
+    }
+}
+/**
+ * The work item and holder a `chant run` passes to the runtime (#2748), or
+ * `null` after printing why the run is refused. The holder is `--holder`, or,
+ * for an Op a steward lists, `<steward>/<op>@<process>` so `workspace status`
+ * shows the lease beside the steward's Ops, or this process's id.
+ *
+ * A non-local runtime takes `--work` only when it declares `carriesWork`
+ * (#3555), and then gets just what the caller named: the holder is chosen
+ * where the run executes, not after this process.
+ */
+async function resolveRunWork(ctx, config, provider) {
+    const runtime = provider.name;
+    const item = ctx.args.work;
+    if (!config.workLease) {
+        if (item === undefined)
+            return undefined;
+        console.error(formatError({
+            message: `--work ${item}: Op "${config.name}" declares no work lease`,
+            hint: "Declare workLease on the Op to run it under a work item's lease.",
+        }));
+        return null;
+    }
+    if (runtime !== "local" && provider.carriesWork !== true && (item !== undefined || ctx.args.holder !== undefined)) {
+        console.error(formatError({
+            message: `--work and --holder run on the local runtime; "${runtime}" takes the work lease where it executes the run`,
+            hint: "Omit --on, or name the item in the Op's workLease.",
+        }));
+        return null;
+    }
+    if (runtime !== "local" && provider.carriesWork === true) {
+        const holderArg = ctx.args.holder;
+        if (item === undefined && holderArg === undefined)
+            return undefined;
+        return { ...(item !== undefined ? { item } : {}), ...(holderArg !== undefined ? { holder: holderArg } : {}) };
+    }
+    let holder = ctx.args.holder;
+    if (holder === undefined) {
+        try {
+            const { stewards } = await discoverStewards();
+            for (const { declaration } of stewards.values()) {
+                if (declaration.ops.some((op) => op.name === config.name)) {
+                    holder = stewardWorkHolder(declaration.name, config.name);
+                    break;
+                }
+            }
+        }
+        catch {
+            // No steward can be read: the run holds the lease as this process.
+        }
+    }
+    return { ...(item !== undefined ? { item } : {}), ...(holder !== undefined ? { holder } : {}) };
+}
+// ── fallback ────────────────────────────────────────────────────────────────���─
+export function runOpUnknown(ctx) {
+    console.error(formatError({
+        message: `Unknown run subcommand: ${ctx.args.extraPositional ?? ctx.args.path}`,
+        hint: "Available: chant run <name>, run list, run status, run approve, run cancel, run log",
+    }));
+    return Promise.resolve(1);
+}