@intentius/chant 0.124.13 → 0.124.15

package/dist/op/local-executor.js

@@ -0,0 +1,1164 @@
+/**
+ * Local Op executor — runs an Op's phases in this process.
+ *
+ * The default runtime (#2121), and the one dev loops, CI, and drift/observation
+ * Ops use. Provides phase sequencing, parallel phases, per-step retry + timeout via
+ * activity profiles, `outcomeAttribute` capture, and `onFailure` compensation.
+ *
+ * A gate is a fact, not a wait (#2119). Reaching one, the executor consults the
+ * gate ledger through `./gate.ts`: a resolution newer than the gate's newest
+ * pending fact lets the step pass, carrying the approver onto its record;
+ * anything else records the pending fact and ends the run with status `gated`.
+ * No later phase runs and `onFailure` does not run — a gate is not a failure,
+ * and there is nothing to compensate for. The next run re-evaluates from the
+ * ledger, so `chant approve <op> <gate>` followed by `chant run <op>` is the
+ * whole loop.
+ *
+ * The executor is deliberately decoupled from any lexicon: activity
+ * implementations and profiles are passed in (loaded dynamically by the CLI),
+ * so core never statically depends on one.
+ */
+import { outcomeAttributesOf } from "./types.js";
+import { resolveActivity } from "./activity-registry.js";
+import { isStepOutputRef } from "./step-output-ref.js";
+import { parseDuration } from "./duration.js";
+import { stepTimeoutProblem } from "./activity-profiles.js";
+import { describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort } from "./gate.js";
+import { gateName } from "./gate-name.js";
+import { gatePointOf } from "./gate-point.js";
+import { evaluatePointGate, workspaceGatePointAsker } from "./gate-point-run.js";
+import { GATE_PLAN_CONTEXT_KEY, gatePlanSummaryOfResult } from "./gate-plan-context.js";
+import { withOpRunContext } from "./run-context.js";
+import { isPointWait } from "./steward-points.js";
+import { isGateWait } from "./gate-wait.js";
+import { currentStewardTurn, enterStewardTurn } from "./steward-turn.js";
+import { appendRunRecord, buildRunRecord } from "../lifecycle/run-ledger.js";
+import { randomUUID } from "node:crypto";
+import { RunWorkLease, LEASE_LOST, workLeaseProblems, workLeaseNeedsRunItem } from "./work-lease-run.js";
+import { WORK_LEASE_STEP_ID } from "./types.js";
+import { LiveRun, currentLiveRun, withLiveRun } from "./run-live.js";
+import { runEnvOf } from "../lifecycle/run-ledger.js";
+export { parseDuration } from "./duration.js";
+// ── Errors ────────────────────────────────────────────────────────────────��─
+/**
+ * Thrown on terminal Op failure; carries the partial run result for rendering.
+ *
+ * `cause` is what actually went wrong (#2301). Before it, this class was the
+ * end of the line for any error that was not a `PhaseFailure` — the executor
+ * caught it, built an `OpRunFailure` from the records it had, and never
+ * referenced the error again. Anything thrown outside a step's own
+ * error-capturing path therefore reached the operator as `Op "x" failed` and
+ * nothing else: no error line, no failing step, exit 1. That is how a gate
+ * whose ledger write died on a CI checkout with no `user.email` produced no
+ * text naming git, the ledger, or the identity, on INTENTIUS/choudoufu#1026.
+ */
+export class OpRunFailure extends Error {
+    constructor(result, options) {
+        super(`Op "${result.op}" failed`);
+        this.result = result;
+        this.name = "OpRunFailure";
+        // Assigned rather than passed to `super` — the lib this package compiles
+        // against predates Error's `options` parameter.
+        if (options && "cause" in options)
+            this.cause = options.cause;
+    }
+}
+/** Internal: a phase aborted; carries records produced before the abort. */
+class PhaseFailure extends Error {
+    constructor(records) {
+        super("phase failed");
+        this.records = records;
+        this.name = "PhaseFailure";
+    }
+}
+/** Internal: a phase stopped on an unapproved gate. Not a failure — no compensation follows it. */
+class GateStop extends Error {
+    constructor(records, pending, phase, 
+    /** Whether this run's own append reached the remote — see {@link OpRunResult.gatePushed}. */
+    pushed, pushWarning) {
+        super(`gate "${pending.gate}" is pending approval`);
+        this.records = records;
+        this.pending = pending;
+        this.phase = phase;
+        this.pushed = pushed;
+        this.pushWarning = pushWarning;
+        this.name = "GateStop";
+    }
+}
+/** Internal: a step asked a decision point that is still open (#2749). Not a failure — no compensation follows it. */
+class PointStop extends Error {
+    constructor(records, question, phase) {
+        super(`waiting on decision point ${question.id}`);
+        this.records = records;
+        this.question = question;
+        this.phase = phase;
+        this.name = "PointStop";
+    }
+}
+/**
+ * Internal: a step boundary found the run can't go on under its work lease
+ * (#2748). `lost` false is a claim that found nothing to claim: not a
+ * failure, the run ends `ok` with the rest skipped. `lost` true is a lease
+ * that was lost: the run fails with `lease-lost`.
+ */
+class WorkStop extends Error {
+    constructor(records, phase, lost) {
+        super(lost ? LEASE_LOST : "nothing to claim");
+        this.records = records;
+        this.phase = phase;
+        this.lost = lost;
+        this.name = "WorkStop";
+    }
+}
+// ── Helpers ───────────────────────────────────────────────────────────────��─
+const DEFAULT_PROFILE = "fastIdempotent";
+/**
+ * The phase a synthetic failure record is filed under when the error did not
+ * come from a step (#2301) — a ledger write, an abort, a malformed phase.
+ * Named rather than blank so a reader of `--json` or of the run ledger can
+ * tell it apart from an authored phase.
+ */
+const UNATTRIBUTED_PHASE = "run";
+const FALLBACK_TIMEOUT_MS = 5 * 60000;
+const isActivity = (s) => s.kind === "activity";
+const isGate = (s) => s.kind === "gate";
+const isEffect = (s) => s.kind === "effect";
+/** Resolve a dot-path into a value; returns the whole value when path is absent. */
+function resolvePath(value, path) {
+    if (!path)
+        return value;
+    return path.split(".").reduce((acc, key) => (acc == null ? acc : acc[key]), value);
+}
+/**
+ * Deep-walk `value`, replacing every {@link StepOutputRef} with the recorded
+ * result of its producer step, resolved through the ref's optional dot-path
+ * exactly like the serializer's compiled `__rN?.path?.segments` (chant #1290)
+ * — `resolvePath` gives the same "undefined intermediate resolves to
+ * undefined, never throws" semantics. A reference to a step whose result
+ * isn't in `resultsById` (never ran, or ran out of the scope
+ * `validateStepOutputRefs` allows) resolves to `undefined`, the same way a
+ * producer whose declared field is absent would.
+ */
+function resolveStepOutputRefs(value, resultsById) {
+    if (isStepOutputRef(value))
+        return resolvePath(resultsById.get(value.step), value.path);
+    if (Array.isArray(value))
+        return value.map((v) => resolveStepOutputRefs(v, resultsById));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolveStepOutputRefs(v, resultsById)]));
+    }
+    return value;
+}
+/**
+ * Find the first `policyGate` step anywhere in the Op (phases + `onFailure`,
+ * including steps nested inside effect steps), if any.
+ *
+ * chant #2003 — `--sandbox` is a GLOBAL flag (`../cli/registry.ts`), and
+ * `../cli/main.ts` arms the process-wide policy latch off it for every command,
+ * `chant run` included. A `policyGate` step then reaches `loadPolicyChecks`,
+ * which refuses while armed with a message written for a chant maintainer —
+ * shown to a user who passed a documented flag. The combination cannot be
+ * honoured until the gate can build and load policies inside the boundary
+ * (#1157), so both `chant run` paths pre-flight it with this and refuse before
+ * any phase executes. This is the one pre-flight refusal left on the Op path —
+ * a `gate` no longer is one (#2119).
+ */
+export function findPolicyGateStep(config) {
+    const all = [...config.phases, ...(config.onFailure ?? [])];
+    const isPolicyGate = (s) => isActivity(s) && s.fn === "policyGate";
+    for (const phase of all) {
+        for (const step of phase.steps) {
+            if (isPolicyGate(step))
+                return step;
+            if (isEffect(step)) {
+                const nested = step.steps.find(isPolicyGate);
+                if (nested)
+                    return nested;
+            }
+        }
+    }
+    return undefined;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Race a single activity attempt against its start-to-close timeout. On timeout
+ * (or when the run-level `parentSignal` aborts, e.g. Ctrl-C) the attempt's
+ * `AbortSignal` fires so the activity can kill its child process, then the call
+ * rejects so the retry loop can react. The losing promise is swallowed to keep
+ * its eventual rejection from surfacing as an unhandled rejection.
+ */
+async function callWithTimeout(fn, args, timeoutMs, parentSignal) {
+    const controller = new AbortController();
+    const onParentAbort = () => controller.abort();
+    if (parentSignal) {
+        if (parentSignal.aborted)
+            controller.abort();
+        else
+            parentSignal.addEventListener("abort", onParentAbort, { once: true });
+    }
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new Error(`activity timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    const call = Promise.resolve(fn(args, controller.signal));
+    call.catch(() => { }); // losing-race rejection must not become unhandled
+    try {
+        return await Promise.race([call, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        if (parentSignal)
+            parentSignal.removeEventListener("abort", onParentAbort);
+    }
+}
+/**
+ * Run one activity step with retry + timeout. Never throws — returns a
+ * record. Any {@link StepOutputRef} in `step.args` is resolved against
+ * `resultsById` before the activity is called (#1290) — an unresolved
+ * placeholder must never reach an activity function, on this runtime or any
+ * other; see `resolveStepOutputRefs`.
+ */
+async function runStep(step, phaseName, activities, profiles, resultsById, signal) {
+    const args = resolveStepOutputRefs(step.args ?? {}, resultsById);
+    const base = { phase: phaseName, fn: step.fn, args };
+    const start = Date.now();
+    let fn;
+    try {
+        fn = resolveActivity(activities, step.fn);
+    }
+    catch (err) {
+        return { record: { ...base, status: "fail", durationMs: 0, error: errMessage(err) } };
+    }
+    const profile = profiles[step.profile ?? DEFAULT_PROFILE] ?? {};
+    // A step's own timeout (#2787) replaces the profile's and keeps its retries.
+    if (step.timeout !== undefined) {
+        const problem = stepTimeoutProblem(step.timeout);
+        if (problem)
+            return { record: { ...base, status: "fail", durationMs: 0, error: problem } };
+    }
+    const timeoutMs = step.timeout !== undefined
+        ? parseDuration(step.timeout)
+        : profile.timeout
+            ? parseDuration(profile.timeout)
+            : FALLBACK_TIMEOUT_MS;
+    const maxAttempts = profile.retry?.maximumAttempts && profile.retry.maximumAttempts > 0
+        ? profile.retry.maximumAttempts
+        : 1;
+    const initial = profile.retry?.initialInterval ? parseDuration(profile.retry.initialInterval) : 0;
+    const backoff = profile.retry?.backoffCoefficient ?? 1;
+    const maxInterval = profile.retry?.maximumInterval
+        ? parseDuration(profile.retry.maximumInterval)
+        : Infinity;
+    const nonRetryable = profile.retry?.nonRetryableErrorTypes ?? [];
+    // The in-flight record names the step while it runs.
+    const ended = currentLiveRun()?.stepStarted(step.fn, step.id);
+    try {
+        return await attempts();
+    }
+    finally {
+        ended?.();
+    }
+    async function attempts() {
+        let lastErr;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                const result = await callWithTimeout(fn, args, timeoutMs, signal);
+                if (step.id)
+                    resultsById.set(step.id, result);
+                const record = { ...base, status: "ok", durationMs: Date.now() - start };
+                const attrs = outcomeAttributesOf(step);
+                // An attribute whose path the result does not hold is left off, rather than recorded as undefined.
+                const outcomes = attrs.map((a) => ({ name: a.name, value: resolvePath(result, a.from) })).filter((o) => o.value !== undefined);
+                if (outcomes.length > 0) {
+                    record.outcomes = outcomes;
+                    record.outcome = outcomes[0];
+                }
+                return { record, result };
+            }
+            catch (err) {
+                // An open decision point (#2749) is not a failure and not worth a retry:
+                // the answer comes from a person, on a later run.
+                if (isPointWait(err)) {
+                    return { record: { ...base, status: "skipped", durationMs: Date.now() - start, point: err.question } };
+                }
+                // Nor is a command that stopped at a gate of its own (#2779): the run
+                // ends `gated` there, and the next run asks the command again.
+                if (isGateWait(err)) {
+                    const gate = { op: err.pending.op, gate: err.pending.gate };
+                    return { record: { ...base, status: "skipped", durationMs: Date.now() - start, gate }, pending: err.pending };
+                }
+                lastErr = err;
+                // Stop retrying on abort (Ctrl-C / timeout cascade) or a non-retryable error.
+                const fatal = signal?.aborted || (err instanceof Error && nonRetryable.includes(err.name));
+                if (!fatal && attempt < maxAttempts) {
+                    const wait = Math.min(initial * Math.pow(backoff, attempt - 1), maxInterval);
+                    if (wait > 0)
+                        await sleep(wait);
+                    continue;
+                }
+                break;
+            }
+        }
+        return { record: { ...base, status: "fail", durationMs: Date.now() - start, error: errMessage(lastErr) } };
+    }
+}
+// ── Effect steps (#1834) ──────────────────────────────────────────────────────
+/** The step data the executor synthesizes to read a receipt through the store
+ * activities (`receiptRead`/`receiptWrite` — provided by the receipt row's
+ * lexicon, #1835, or a mock store in tests via `receiptActivities`). */
+function receiptReadStep(step) {
+    return {
+        kind: "activity",
+        fn: "receiptRead",
+        args: {
+            receipt: step.receipt,
+            ...(step.expectation !== undefined ? { expectation: step.expectation } : {}),
+        },
+        profile: "fastIdempotent",
+        outcomeAttribute: { name: "EffectApplied", from: "applied" },
+    };
+}
+/** A skipped-record for a step that will not run. */
+function skippedRecord(phaseName, fn, args) {
+    return { phase: phaseName, fn, args: args ?? {}, status: "skipped", durationMs: 0 };
+}
+/**
+ * The work lease at a step boundary (#2748): claim it when it is due, and
+ * say whether the run can go on. The claim's record is pushed onto `sink`.
+ * Returns `undefined` to go on, `"unclaimed"` when nothing could be claimed,
+ * and `"lost"` when the lease was lost.
+ */
+async function workBoundary(phaseName, ctx, resultsById, sink) {
+    const work = ctx.work;
+    if (!work)
+        return undefined;
+    if (work.due(resultsById)) {
+        const start = Date.now();
+        let claimed;
+        try {
+            claimed = await work.claim(resultsById);
+        }
+        catch (err) {
+            pushRecord(sink, ctx, {
+                phase: phaseName,
+                fn: "workLease:claim",
+                args: {},
+                status: "fail",
+                durationMs: Date.now() - start,
+                error: errMessage(err),
+            });
+            throw new PhaseFailure(sink);
+        }
+        if (claimed.kind === "unclaimed") {
+            pushRecord(sink, ctx, {
+                phase: phaseName,
+                fn: "workLease:claim",
+                args: { items: claimed.tried },
+                status: "skipped",
+                durationMs: Date.now() - start,
+                refusal: claimed.refusal,
+                outcome: { name: "WorkItem", value: null },
+                outcomes: [{ name: "WorkItem", value: null }],
+            });
+            return "unclaimed";
+        }
+        resultsById.set(WORK_LEASE_STEP_ID, claimed.lease);
+        currentLiveRun()?.item(claimed.lease.item);
+        pushRecord(sink, ctx, {
+            phase: phaseName,
+            fn: "workLease:claim",
+            args: { items: claimed.tried },
+            status: "ok",
+            durationMs: Date.now() - start,
+            outcome: { name: "WorkItem", value: claimed.lease.item },
+            outcomes: [
+                { name: "WorkItem", value: claimed.lease.item },
+                { name: "WorkLeaseToken", value: claimed.lease.token },
+            ],
+        });
+    }
+    return work.lost !== undefined ? "lost" : undefined;
+}
+/** Collect records and hand each to the caller's progress sink in one move. */
+function pushRecord(sink, ctx, ...recs) {
+    sink.push(...recs);
+    for (const r of recs)
+        ctx.onRecord?.(r);
+}
+/** The record name a gate step lands under, so a reader (and a JSON consumer) can pick it out of `records`. */
+function gateFn(step) {
+    return `gate:${gateName(step)}`;
+}
+/**
+ * A gate's `approval` block as this run resolves it (#2508): each context
+ * value that is a step-output reference is replaced by what that step
+ * returned, the same walk `plan` goes through. A reference that resolves to
+ * nothing is dropped rather than failing the run, so a policy reading it sees
+ * the attribute as absent.
+ */
+function resolveGateApproval(step, resultsById) {
+    const authored = step.approval;
+    if (!authored)
+        return undefined;
+    let context;
+    if (authored.context) {
+        context = {};
+        for (const [key, value] of Object.entries(authored.context)) {
+            const resolved = resolveStepOutputRefs(value, resultsById);
+            if (resolved !== undefined && resolved !== null)
+                context[key] = resolved;
+        }
+    }
+    // #3182: a policy also sees what the plan does. When the gate's `plan`
+    // names the step that planned it and that step returned a change set, its
+    // summary lands under `context.plan` with no context code in the Op.
+    if (authored.policy && isStepOutputRef(step.plan)) {
+        const summary = gatePlanSummaryOfResult(resultsById.get(step.plan.step));
+        if (summary)
+            context = { ...(context ?? {}), [GATE_PLAN_CONTEXT_KEY]: summary };
+    }
+    return {
+        ...(authored.quorum ? { quorum: authored.quorum } : {}),
+        ...(authored.policy ? { policy: authored.policy } : {}),
+        mode: authored.mode ?? "log-only",
+        ...(context ? { context } : {}),
+    };
+}
+/**
+ * Decide one gate against the ledger. A resolution newer than the gate's
+ * newest pending fact passes it, and the approver lands on the step record; a
+ * pending fact is recorded (or left standing) otherwise, and the caller stops
+ * the run.
+ */
+async function runGateStep(step, phaseName, gates, resultsById = new Map()) {
+    if (step.point !== undefined)
+        return runPointGateStep(step, phaseName, gates, resultsById);
+    const start = Date.now();
+    // #2300: `plan` is authored as a reference into the Plan phase's result
+    // (`plan.out.planDigest`), and is resolved here through the same walk an
+    // activity's args go through. A reference that resolves to anything but a
+    // string leaves the gate unbound — the pre-#2300 rule — rather than failing
+    // a run over a missing digest.
+    const resolvedPlan = resolveStepOutputRefs(step.plan, resultsById);
+    const planDigest = typeof resolvedPlan === "string" && resolvedPlan !== "" ? resolvedPlan : undefined;
+    const approval = resolveGateApproval(step, resultsById);
+    let check;
+    try {
+        check = await evaluateGate(gates.port, {
+            op: gates.op,
+            gate: gateName(step),
+            ...(step.description ? { description: step.description } : {}),
+            ...(step.timeout ? { timeout: step.timeout } : {}),
+            ...(gates.runId ? { runId: gates.runId } : {}),
+            ...(planDigest !== undefined ? { planDigest } : {}),
+            ...(approval ? { approval } : {}),
+            ...(gates.now ? { now: gates.now } : {}),
+        });
+    }
+    catch (err) {
+        // Deciding a gate reads and writes the `chant/lifecycle` branch, so it
+        // fails for all the ordinary git reasons — no committer identity, an
+        // unfetched ledger, a rejected ref update. `runStep` has always turned an
+        // activity's throw into a failing `StepRecord` carrying the message
+        // ("Never throws — returns a record"); `runGateStep` did not, which made
+        // the gate the one step kind whose failure produced no record and so no
+        // rendered output at all (#2301). It does now, and the phase treats it
+        // like any other failing step.
+        return {
+            record: {
+                phase: phaseName,
+                fn: gateFn(step),
+                args: {},
+                status: "fail",
+                durationMs: Date.now() - start,
+                error: errMessage(err),
+            },
+        };
+    }
+    if (check.satisfied) {
+        const { resolution } = check;
+        const passedApproval = {
+            gate: gateName(step),
+            resolvedBy: resolution.resolvedBy,
+            timestamp: resolution.timestamp,
+            ...(resolution.url ? { url: resolution.url } : {}),
+            ...(check.via ? { via: check.via } : {}),
+            ...(check.approvals ? { approvers: check.approvals.map((r) => r.resolvedBy) } : {}),
+        };
+        // #2522: a later step reads this gate's approval from the run context
+        // rather than re-tallying the ledger, so it sees the decision this run made.
+        gates.passed?.push({ gate: gateName(step), approval: passedApproval });
+        return {
+            record: {
+                phase: phaseName,
+                fn: gateFn(step),
+                args: {},
+                status: "ok",
+                durationMs: Date.now() - start,
+                approval: passedApproval,
+            },
+        };
+    }
+    const refusal = check.mismatch
+        ? { refusal: describeGateMismatch(gates.op, gateName(step), check.mismatch, await gateIsSealed(gateName(step))) }
+        : {};
+    return {
+        record: {
+            phase: phaseName,
+            fn: gateFn(step),
+            args: {},
+            status: "skipped",
+            durationMs: Date.now() - start,
+            ...refusal,
+        },
+        pending: check.pending,
+        pushed: check.pushed,
+        ...(check.pushWarning ? { pushWarning: check.pushWarning } : {}),
+    };
+}
+/**
+ * Decide a gate that asks a decision point (#3170, `./gate-point-run.ts`).
+ * An answer it passes on lands on the step record as the approval, citing
+ * the answer record; an open question puts the question on the record, as an
+ * activity's open point does, and the caller ends the run `waiting`; any
+ * other answer fails the step.
+ */
+async function runPointGateStep(step, phaseName, gates, resultsById) {
+    const start = Date.now();
+    const point = gatePointOf(step.point);
+    const base = { phase: phaseName, fn: gateFn(step), args: {} };
+    const resolvedPlan = resolveStepOutputRefs(step.plan, resultsById);
+    const planDigest = typeof resolvedPlan === "string" && resolvedPlan !== "" ? resolvedPlan : undefined;
+    const inputs = point.inputs ? resolveStepOutputRefs(point.inputs, resultsById) : undefined;
+    try {
+        const check = await evaluatePointGate(gates.port, gates.points ?? workspaceGatePointAsker(process.cwd()), {
+            op: gates.op,
+            gate: gateName(step),
+            point,
+            ...(inputs ? { inputs } : {}),
+            ...(step.description ? { description: step.description } : {}),
+            ...(step.timeout ? { timeout: step.timeout } : {}),
+            ...(gates.runId ? { runId: gates.runId } : {}),
+            ...(planDigest !== undefined ? { planDigest } : {}),
+            ...(gates.env !== undefined ? { env: gates.env } : {}),
+            ...(gates.now ? { now: gates.now } : {}),
+        });
+        if (check.satisfied) {
+            const approval = {
+                gate: gateName(step),
+                resolvedBy: check.resolution.resolvedBy,
+                timestamp: check.resolution.timestamp,
+                via: "point",
+                ...(check.answer.answeredBy ? { approvers: check.answer.answeredBy } : {}),
+                answer: check.answer,
+            };
+            gates.passed?.push({ gate: gateName(step), approval });
+            return { record: { ...base, status: "ok", durationMs: Date.now() - start, approval }, pushed: check.pushed, ...(check.pushWarning ? { pushWarning: check.pushWarning } : {}) };
+        }
+        if ("refused" in check)
+            return { record: { ...base, status: "fail", durationMs: Date.now() - start, error: check.refused } };
+        return { record: { ...base, status: "skipped", durationMs: Date.now() - start, point: check.waiting }, pushed: check.pushed, ...(check.pushWarning ? { pushWarning: check.pushWarning } : {}) };
+    }
+    catch (err) {
+        return { record: { ...base, status: "fail", durationMs: Date.now() - start, error: errMessage(err) } };
+    }
+}
+/**
+ * Run one effect step: read-compare-run-write. On a match the nested steps are
+ * recorded as skipped ("effect already applied") and nothing is written. On a
+ * mismatch the nested steps run in authored order; only when every one
+ * succeeds is the receipt written — last, once (the sole writer, #1703
+ * decision 3). Any failure leaves the receipt untouched (stale), so the next
+ * run re-proposes the effect.
+ *
+ * A nested `gate` is decided in authored order like any other nested step
+ * (#2119). Unapproved, it stops the effect before the receipt is written, so
+ * the next run re-reads the receipt, re-proposes the effect, and re-evaluates
+ * the gate — the receipt stays honest about what actually happened.
+ */
+async function runEffectStep(step, phaseName, activities, profiles, resultsById, gates, signal) {
+    const records = [];
+    const read = await runStep(receiptReadStep(step), phaseName, activities, profiles, resultsById, signal);
+    pushRecord(records, gates, read.record);
+    if (read.record.status === "fail")
+        return { records, failed: true };
+    const result = read.result;
+    if (typeof result?.expectation !== "string") {
+        pushRecord(records, gates, {
+            phase: phaseName,
+            fn: `effect:${step.receipt.name}`,
+            args: {},
+            status: "fail",
+            durationMs: 0,
+            error: "receiptRead returned no expectation — the receipt store activity must return { current, expectation }",
+        });
+        return { records, failed: true };
+    }
+    const expectation = result.expectation;
+    if (result.current === expectation) {
+        // Effect already applied — skip the nested steps, write nothing.
+        for (const nested of step.steps) {
+            pushRecord(records, gates, nested.kind === "activity"
+                ? skippedRecord(phaseName, nested.fn, nested.args)
+                : skippedRecord(phaseName, gateFn(nested)));
+        }
+        return { records, failed: false };
+    }
+    const skipRest = (from) => {
+        for (const skipped of step.steps.slice(from)) {
+            pushRecord(records, gates, skipped.kind === "activity"
+                ? skippedRecord(phaseName, skipped.fn, skipped.args)
+                : skippedRecord(phaseName, gateFn(skipped)));
+        }
+        pushRecord(records, gates, skippedRecord(phaseName, "receiptWrite"));
+    };
+    for (let i = 0; i < step.steps.length; i++) {
+        const nested = step.steps[i];
+        if (isGate(nested)) {
+            const { record, pending, pushed, pushWarning } = await runGateStep(nested, phaseName, gates, resultsById);
+            pushRecord(records, gates, record);
+            if (record.status === "fail") {
+                // Receipt left untouched, as for any other failing nested step
+                // (#2301) — the effect is not applied and the next run re-proposes it.
+                skipRest(i + 1);
+                return { records, failed: true };
+            }
+            if (pending) {
+                // Receipt left untouched — the next run re-proposes the effect and
+                // re-evaluates the gate against whatever the ledger says by then.
+                skipRest(i + 1);
+                return { records, failed: false, pending, pushed, ...(pushWarning ? { pushWarning } : {}) };
+            }
+            if (record.point) {
+                // A gate's open decision point (#3170): as for an activity's.
+                skipRest(i + 1);
+                return { records, failed: false, point: record.point };
+            }
+            continue;
+        }
+        const ran = await runStep(nested, phaseName, activities, profiles, resultsById, signal);
+        pushRecord(records, gates, ran.record);
+        if (ran.pending) {
+            // A command's own gate (#2779): the receipt is left untouched, as for a
+            // pending gate step.
+            skipRest(i + 1);
+            return { records, failed: false, pending: ran.pending };
+        }
+        if (ran.record.point) {
+            // Receipt left untouched, as for a pending gate: the next run re-proposes
+            // the effect and asks the point again, and finds the answer by then.
+            skipRest(i + 1);
+            return { records, failed: false, point: ran.record.point };
+        }
+        if (ran.record.status === "fail") {
+            // Receipt left untouched (stale) — the next run re-proposes the effect.
+            skipRest(i + 1);
+            return { records, failed: true };
+        }
+    }
+    // Sole writer of the receipt: on success of every nested step, last.
+    const wrote = await runStep({
+        kind: "activity",
+        fn: "receiptWrite",
+        args: { receipt: step.receipt, expectation },
+        profile: "fastIdempotent",
+    }, phaseName, activities, profiles, resultsById, signal);
+    pushRecord(records, gates, wrote.record);
+    return { records, failed: wrote.record.status === "fail" };
+}
+/**
+ * Run a phase. Throws `PhaseFailure` (with the records so far) if any step
+ * fails, or `GateStop` if a `gate` step in it is still pending approval.
+ */
+async function runPhase(phase, activities, profiles, resultsById, gates, signal) {
+    if (phase.parallel) {
+        const eff = phase.steps.find(isEffect);
+        if (eff) {
+            throw new Error(`effect step "${eff.receipt.name}" cannot run in a parallel phase — read-compare-run-write is ordered`);
+        }
+        // Gates in a parallel phase are decided before the fan-out: a gate is a
+        // read of the ledger, not work, and starting activities that a pending
+        // gate is about to strand would defeat the point of stopping at it.
+        const gateRecords = [];
+        const stop = await workBoundary(phase.name, gates, resultsById, gateRecords);
+        if (stop) {
+            for (const skipped of phase.steps) {
+                pushRecord(gateRecords, gates, isGate(skipped) ? skippedRecord(phase.name, gateFn(skipped)) : skippedRecord(phase.name, skipped.fn, skipped.args));
+            }
+            throw new WorkStop(gateRecords, phase.name, stop === "lost");
+        }
+        for (const step of phase.steps.filter(isGate)) {
+            const { record, pending, pushed, pushWarning } = await runGateStep(step, phase.name, gates, resultsById);
+            pushRecord(gateRecords, gates, record);
+            if (record.status === "fail") {
+                // The gate could not be decided at all (#2301). Same treatment as a
+                // pending one: nothing fans out, the activities are recorded skipped.
+                for (const skipped of phase.steps.filter(isActivity)) {
+                    pushRecord(gateRecords, gates, skippedRecord(phase.name, skipped.fn, skipped.args));
+                }
+                throw new PhaseFailure(gateRecords);
+            }
+            if (pending) {
+                for (const skipped of phase.steps.filter(isActivity)) {
+                    pushRecord(gateRecords, gates, skippedRecord(phase.name, skipped.fn, skipped.args));
+                }
+                throw new GateStop(gateRecords, pending, phase.name, pushed, pushWarning);
+            }
+            if (record.point) {
+                // A gate's open decision point (#3170): nothing fans out.
+                for (const skipped of phase.steps.filter(isActivity)) {
+                    pushRecord(gateRecords, gates, skippedRecord(phase.name, skipped.fn, skipped.args));
+                }
+                throw new PointStop(gateRecords, record.point, phase.name);
+            }
+        }
+        const steps = phase.steps.filter(isActivity);
+        const settled = await Promise.all(steps.map((s) => runStep(s, phase.name, activities, profiles, resultsById, signal)));
+        const ran = settled.map((r) => r.record);
+        for (const r of ran)
+            gates.onRecord?.(r);
+        const records = gateRecords.concat(ran);
+        if (records.some((r) => r.status === "fail"))
+            throw new PhaseFailure(records);
+        // A step whose command stopped at its own gate (#2779) stops the run at
+        // this phase, as a gate step would, once its siblings have finished.
+        const gated = settled.find((r) => r.pending)?.pending;
+        if (gated)
+            throw new GateStop(records, gated, phase.name);
+        // The fan-out has already run, so the siblings of an open decision point
+        // finished; the run still stops at this phase (#2749).
+        const waiting = ran.find((r) => r.point);
+        if (waiting?.point)
+            throw new PointStop(records, waiting.point, phase.name);
+        return records;
+    }
+    const steps = phase.steps;
+    const records = [];
+    const skipRemaining = (from) => {
+        for (const skipped of steps.slice(from)) {
+            if (isEffect(skipped)) {
+                pushRecord(records, gates, skippedRecord(phase.name, `effect:${skipped.receipt.name}`));
+            }
+            else if (isGate(skipped)) {
+                pushRecord(records, gates, skippedRecord(phase.name, gateFn(skipped)));
+            }
+            else {
+                pushRecord(records, gates, skippedRecord(phase.name, skipped.fn, skipped.args));
+            }
+        }
+    };
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        // The work lease (#2748): claimed here when it is due, and checked before
+        // every step, so no step starts once the lease is lost.
+        const stop = await workBoundary(phase.name, gates, resultsById, records);
+        if (stop) {
+            skipRemaining(i);
+            throw new WorkStop(records, phase.name, stop === "lost");
+        }
+        if (isGate(step)) {
+            const { record, pending, pushed, pushWarning } = await runGateStep(step, phase.name, gates, resultsById);
+            pushRecord(records, gates, record);
+            if (record.status === "fail") {
+                // A gate that could not be decided is a failed step, not a pending
+                // one (#2301) — the run failed, and the record says why.
+                skipRemaining(i + 1);
+                throw new PhaseFailure(records);
+            }
+            if (pending) {
+                skipRemaining(i + 1);
+                throw new GateStop(records, pending, phase.name, pushed, pushWarning);
+            }
+            if (record.point) {
+                // A gate that asks a decision point (#3170) and found it open: the
+                // run waits on the question, as at an activity's open point.
+                skipRemaining(i + 1);
+                throw new PointStop(records, record.point, phase.name);
+            }
+            continue;
+        }
+        if (isEffect(step)) {
+            const { records: effRecords, failed, pending, pushed, pushWarning, point } = await runEffectStep(step, phase.name, activities, profiles, resultsById, gates, signal);
+            records.push(...effRecords); // already emitted by runEffectStep
+            if (point) {
+                skipRemaining(i + 1);
+                throw new PointStop(records, point, phase.name);
+            }
+            if (pending) {
+                skipRemaining(i + 1);
+                throw new GateStop(records, pending, phase.name, pushed, pushWarning);
+            }
+            if (failed) {
+                skipRemaining(i + 1);
+                throw new PhaseFailure(records);
+            }
+            continue;
+        }
+        const { record, pending } = await runStep(step, phase.name, activities, profiles, resultsById, signal);
+        pushRecord(records, gates, record);
+        if (pending) {
+            // The step's command stopped at its own gate (#2779): the run ends
+            // `gated` there, as at a pending gate step.
+            skipRemaining(i + 1);
+            throw new GateStop(records, pending, phase.name);
+        }
+        if (record.point) {
+            // An open decision point (#2749) ends the run as a pending gate does.
+            skipRemaining(i + 1);
+            throw new PointStop(records, record.point, phase.name);
+        }
+        if (record.status === "fail") {
+            // Mark the remaining steps in this phase as skipped, then abort.
+            skipRemaining(i + 1);
+            throw new PhaseFailure(records);
+        }
+    }
+    return records;
+}
+/**
+ * Execute an Op locally.
+ *
+ * Resolves with the run result when every phase succeeds (`status: "ok"`), and
+ * also when the run stopped at an unapproved gate (`status: "gated"`, with the
+ * pending fact on `result.gate`) — a gate is a fact, not an error, so it is not
+ * thrown. So does an activity's open decision point (`status: "waiting"`, with
+ * the question on `result.point`, #2749). Rejects with `OpRunFailure` (carrying the partial result) on terminal
+ * failure, after running any `onFailure` phases in reverse order; a gated or
+ * waiting run runs no `onFailure` phase, because nothing failed and nothing was left
+ * half-applied to compensate for.
+ *
+ * Whichever of the three ways it settles, the run carries an
+ * {@link OpRunRecord} on `result.record` (#2118). With `options.ledger` that
+ * record is also appended to `<env>/runs__<op>.jsonl` on the lifecycle branch
+ * before this returns or rejects, so an Op's outcome outlives the process that
+ * produced it.
+ */
+export async function runOpLocally(config, activities, profiles, signal, options = {}) {
+    // The run id is the gate ledger's and the run ledger's alike: a pending gate
+    // fact and the record naming that gate carry the same string.
+    const runId = options.runId ?? randomUUID();
+    // In a steward's turn (#2749: `chant operator --steward`, or `chant acp
+    // --steward` on Fountain) the run is the steward's: its record names the
+    // steward, and a decision point asked during it names this run.
+    const turn = currentStewardTurn();
+    const steward = options.steward ?? turn?.steward;
+    const restore = turn && turn.run !== runId ? enterStewardTurn({ ...turn, run: runId }) : undefined;
+    // #2522: every activity in this run can read the run it is in.
+    const run = {
+        op: config.name,
+        runId,
+        ...(options.env !== undefined ? { env: options.env } : {}),
+        passedGates: [],
+    };
+    // A run that writes to the ledger also says what it is doing while it runs
+    // (./run-live.ts), and removes that once its record is written.
+    const live = options.ledger
+        ? await LiveRun.open({
+            cwd: options.ledger.cwd ?? options.cwd ?? process.cwd(),
+            env: runEnvOf(config),
+            op: config.name,
+            id: runId,
+            started: options.now ?? new Date().toISOString(),
+            ...(steward ? { steward } : {}),
+        })
+        : undefined;
+    try {
+        return await withLiveRun(live, () => withOpRunContext(run, () => runOpInTurn(config, activities, profiles, signal, { ...options, runId, ...(steward ? { steward } : {}) }, run)));
+    }
+    finally {
+        live?.close();
+        restore?.();
+    }
+}
+async function runOpInTurn(config, activities, profiles, signal, options, run) {
+    const runId = options.runId;
+    const gates = {
+        op: config.name,
+        port: options.gates ?? gitGateLedgerPort(options.cwd ? { cwd: options.cwd } : undefined),
+        ...(options.now ? { now: options.now } : {}),
+        runId,
+        ...(options.onRecord ? { onRecord: options.onRecord } : {}),
+        passed: run.passedGates,
+        points: options.points ?? workspaceGatePointAsker(options.cwd ?? process.cwd()),
+        ...(options.env !== undefined ? { env: options.env } : {}),
+    };
+    // Effect steps are ordered (read-compare-run-write): refuse them in a
+    // parallel phase up front, with the phase named, rather than mid-run.
+    for (const phase of [...config.phases, ...(config.onFailure ?? [])]) {
+        const eff = phase.parallel ? phase.steps.find(isEffect) : undefined;
+        if (eff) {
+            throw new Error(`phase "${phase.name}": effect step "${eff.receipt.name}" cannot run in a ` +
+                `parallel phase — read-compare-run-write is ordered`);
+        }
+    }
+    // The work lease (#2748). An Op that changes the checkout without one, or
+    // whose lease names no item and whose run names none, is refused before
+    // anything runs.
+    const workProblems = workLeaseProblems(config);
+    if (workProblems.length > 0)
+        throw new Error(workProblems.join("\n"));
+    if (workLeaseNeedsRunItem(config) && !options.work?.item) {
+        throw new Error(`Op "${config.name}" runs under a work item's lease and names no item: pass one with \`chant run ${config.name} --work <id>\``);
+    }
+    const work = config.workLease
+        ? new RunWorkLease(config, {
+            cwd: options.ledger?.cwd ?? options.cwd ?? process.cwd(),
+            ...(options.work?.holder ? { holder: options.work.holder } : {}),
+            ...(options.work?.item ? { item: options.work.item } : {}),
+            ...(options.onWorkLeaseWarning ? { onRenewError: options.onWorkLeaseWarning } : {}),
+        })
+        : undefined;
+    if (work)
+        gates.work = work;
+    // Steps run under a signal that also fires when the work lease is lost, so
+    // the step in flight stops (chud's dispatcher stopped its agent the same way).
+    let stepSignal = signal;
+    if (work) {
+        const both = new AbortController();
+        const forward = () => both.abort();
+        if (signal?.aborted)
+            both.abort();
+        else
+            signal?.addEventListener("abort", forward, { once: true });
+        work.lostSignal.addEventListener("abort", forward, { once: true });
+        stepSignal = both.signal;
+    }
+    /** Release (or not) the work lease once the run's outcome is settled. */
+    const finishWork = async (status) => work ? { workLease: await work.finish(status, resultsById) } : {};
+    /** The record a lost lease leaves, naming why. */
+    const lostRecord = () => ({
+        phase: UNATTRIBUTED_PHASE,
+        fn: "workLease:lost",
+        args: {},
+        status: "fail",
+        durationMs: 0,
+        error: `${LEASE_LOST}: ${work?.lost ?? "the lease was lost"}. The run stopped and was not recorded as done.`,
+    });
+    const skipLaterPhases = (after) => {
+        const stoppedAt = config.phases.findIndex((p) => p.name === after);
+        if (stoppedAt < 0)
+            return;
+        for (const phase of config.phases.slice(stoppedAt + 1)) {
+            for (const step of phase.steps) {
+                records.push(isEffect(step)
+                    ? skippedRecord(phase.name, `effect:${step.receipt.name}`)
+                    : isGate(step)
+                        ? skippedRecord(phase.name, gateFn(step))
+                        : skippedRecord(phase.name, step.fn, step.args));
+            }
+        }
+    };
+    const records = [];
+    const start = Date.now();
+    // Each phase's wall-clock time, for the run record and the in-flight one.
+    const phaseDurations = {};
+    const timedPhase = async (phase, ctx, phaseSignal) => {
+        const live = currentLiveRun();
+        const t0 = Date.now();
+        live?.phaseStarted(phase.name);
+        try {
+            const ran = await runPhase(phase, activities, profiles, resultsById, ctx, phaseSignal);
+            live?.phaseEnded(phase.name, phaseVerdict(ran), Date.now() - t0);
+            return ran;
+        }
+        finally {
+            phaseDurations[phase.name] = (phaseDurations[phase.name] ?? 0) + (Date.now() - t0);
+        }
+    };
+    const startedAt = options.now ?? new Date(start).toISOString();
+    /**
+     * Build the run's ledger record, append it when asked, and hand it back for
+     * the result. Called once, at whichever of the three exits the run takes.
+     */
+    const settle = async (settled, status, gate, point) => {
+        const ended = options.now ?? new Date().toISOString();
+        const input = buildRunRecord(config, settled, {
+            started: startedAt,
+            ended,
+            status,
+            id: runId,
+            // A gate recorded under another op (#2779: a command's own gate) names it.
+            ...(gate ? { gate: { name: gate.gate, since: gate.timestamp, ...(gate.op !== config.name ? { op: gate.op } : {}) } } : {}),
+            ...(point ? { point: { ...point, since: ended } } : {}),
+            ...(options.steward ? { steward: options.steward } : {}),
+            phaseDurations,
+        });
+        const record = { version: 1, ...input, id: runId };
+        if (!options.ledger)
+            return record;
+        try {
+            return (await appendRunRecord(input, options.ledger)).record;
+        }
+        catch (err) {
+            options.onLedgerError?.(err);
+            return record;
+        }
+    };
+    // Completed step id → its activity result (#1290). Populated as main-phase
+    // steps finish, so a later step's step-output references resolve to real
+    // values before reaching an activity function — see `runStep`.
+    const resultsById = new Map();
+    try {
+        for (const phase of config.phases) {
+            if (signal?.aborted)
+                throw new PhaseFailure([]);
+            records.push(...(await timedPhase(phase, gates, stepSignal)));
+        }
+        // The last renewal before the run is recorded (#2748): a run whose lease
+        // was lost is never recorded as done.
+        if (work && !(await work.fence()))
+            throw new WorkStop([], UNATTRIBUTED_PHASE, true);
+    }
+    catch (err) {
+        // Nothing to claim, or every candidate held (#2748): not a failure. The
+        // rest of the run is skipped and the claim's record says why.
+        if (err instanceof WorkStop && !err.lost) {
+            records.push(...err.records);
+            skipLaterPhases(err.phase);
+            const record = await settle(records, "ok");
+            return {
+                op: config.name,
+                records,
+                totalMs: Date.now() - start,
+                status: "ok",
+                startedAt,
+                record,
+                ...(await finishWork("ok")),
+            };
+        }
+        // An open decision point ends the run the way a pending gate does (#2749):
+        // no later phase and no compensation, and the run is `waiting`.
+        if (err instanceof PointStop) {
+            records.push(...err.records);
+            skipLaterPhases(err.phase);
+            const record = await settle(records, "waiting", undefined, err.question);
+            return {
+                op: config.name,
+                records,
+                totalMs: Date.now() - start,
+                status: "waiting",
+                startedAt,
+                point: err.question,
+                record,
+                ...(await finishWork("waiting")),
+            };
+        }
+        // A pending gate ends the run where it stands: no later phase, and no
+        // `onFailure` compensation — nothing failed, so there is nothing to undo.
+        if (err instanceof GateStop) {
+            records.push(...err.records);
+            skipLaterPhases(err.phase);
+            const record = await settle(records, "gated", err.pending);
+            return {
+                op: config.name,
+                records,
+                totalMs: Date.now() - start,
+                status: "gated",
+                startedAt,
+                gate: err.pending,
+                ...(err.pushed !== undefined ? { gatePushed: err.pushed } : {}),
+                ...(err.pushWarning ? { gatePushWarning: err.pushWarning } : {}),
+                record,
+                ...(await finishWork("gated")),
+            };
+        }
+        if (err instanceof WorkStop) {
+            // The lease was lost (#2748): the rest is skipped, and the lost record
+            // below says why.
+            records.push(...err.records);
+            skipLaterPhases(err.phase);
+        }
+        else if (err instanceof PhaseFailure) {
+            records.push(...err.records);
+        }
+        else {
+            // Everything else the phase loop can throw (#2301). `PhaseFailure` and
+            // `GateStop` are the two shapes that carry their own records; anything
+            // else — a git failure inside a ledger write, a bad phase definition, a
+            // bug — used to be dropped here without being read, leaving a result
+            // whose `records` hold nothing marked failed and nothing carrying a
+            // message. The renderer prints text only from records, so the operator
+            // got `Op "x" failed after 43.8s` and no cause at all.
+            //
+            // A synthetic record is what makes it visible: it renders as a failing
+            // step like any other, lands in the run ledger, and appears in
+            // `--json`. `cause` on the thrown `OpRunFailure` carries the original
+            // error for a caller that wants the object rather than the text.
+            records.push({
+                phase: UNATTRIBUTED_PHASE,
+                fn: "opFailure",
+                args: {},
+                status: "fail",
+                durationMs: 0,
+                error: errMessage(err),
+            });
+        }
+        // A step that failed because the lease was lost mid-step, or a lease lost
+        // at any boundary: one record names it (#2748).
+        if (work?.lost !== undefined)
+            records.push(lostRecord());
+        // Compensation: run onFailure phases in reverse order (best-effort). Skipped
+        // on abort (Ctrl-C) — the user asked to stop, so don't start new work.
+        // It runs whatever the work lease did, so it takes no work boundary.
+        const compensation = { ...gates, work: undefined };
+        if (!signal?.aborted) {
+            for (const phase of [...(config.onFailure ?? [])].reverse()) {
+                try {
+                    records.push(...(await timedPhase(phase, compensation, signal)));
+                }
+                catch (compErr) {
+                    if (compErr instanceof PhaseFailure || compErr instanceof GateStop || compErr instanceof PointStop) {
+                        records.push(...compErr.records);
+                    }
+                    else {
+                        // The same swallow, one level down (#2301): a compensation phase
+                        // that threw something else left no trace whatsoever.
+                        records.push({
+                            phase: phase.name,
+                            fn: "onFailure",
+                            args: {},
+                            status: "fail",
+                            durationMs: 0,
+                            error: errMessage(compErr),
+                        });
+                    }
+                }
+            }
+        }
+        const failed = await settle(records, "fail");
+        throw new OpRunFailure({
+            op: config.name,
+            records,
+            totalMs: Date.now() - start,
+            status: "fail",
+            startedAt,
+            record: failed,
+            ...(await finishWork("fail")),
+        }, { cause: err });
+    }
+    const record = await settle(records, "ok");
+    return {
+        op: config.name,
+        records,
+        totalMs: Date.now() - start,
+        status: "ok",
+        startedAt,
+        record,
+        ...(await finishWork("ok")),
+    };
+}
+/** A finished phase's verdict, as the run ledger folds it: `fail`, `skipped` when every step was, else `ok`. */
+function phaseVerdict(records) {
+    if (records.some((r) => r.status === "fail"))
+        return "fail";
+    if (records.length > 0 && records.every((r) => r.status === "skipped"))
+        return "skipped";
+    return "ok";
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}