@intentius/chant 0.61.0 → 0.63.0

package/src/op/local-executor.ts

@@ -25,7 +25,7 @@ import { resolveActivity, type ActivityFn, type ActivityProfile } from "./activi
 import type { ReceiptReadResult } from "./receipt-store";
 import { isStepOutputRef } from "./step-output-ref";
 import { parseDuration } from "./duration";
-import { evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "./gate";
+import { describeGateMismatch, evaluateGate, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "./gate";
 import { gateName } from "./gate-name";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import { appendRunRecord, buildRunRecord } from "../lifecycle/run-ledger";
@@ -58,6 +58,14 @@ export interface StepRecord {
   error?: string;
   /** Set on a `gate` step that passed (#2119): who resolved it, when, and at what address. */
   approval?: { gate: string; resolvedBy: string; timestamp: string; url?: string };
+  /**
+   * Why a step declined to proceed on something that is not a failure
+   * (#2300): a gate holding a standing approval for a *different* plan. Names
+   * both digests and the `chant approve` line that closes the gap. The step's
+   * status is `skipped` and the run's is `gated` — nothing broke, and nothing
+   * was applied.
+   */
+  refusal?: string;
 }
 
 export interface OpRunResult {
@@ -76,6 +84,15 @@ export interface OpRunResult {
   startedAt: string;
   /** Present when `status === "gated"`: the pending fact the run ended on. */
   gate?: PendingGateRecord;
+  /**
+   * Present when `status === "gated"` and this run's own append tried to push:
+   * whether it reached the remote (#2310). Absent when the run stopped on a
+   * pending fact an earlier run had already recorded — nothing was pushed
+   * this run.
+   */
+  gatePushed?: boolean;
+  /** Set when `gatePushed` is false: why, in one line. */
+  gatePushWarning?: string;
   /**
    * The run's ledger record (#2118) — always built, whether or not it was
    * appended. `chant run <op> --json` prints exactly this, so what a caller
@@ -87,11 +104,31 @@ export interface OpRunResult {
 
 // ── Errors ────────────────────────────────────────────────────────────────��─
 
-/** Thrown on terminal Op failure; carries the partial run result for rendering. */
+/**
+ * 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(public readonly result: OpRunResult) {
+  /** The error the run actually died on, when it was not a step's own failure. */
+  public readonly cause?: unknown;
+
+  constructor(
+    public readonly result: OpRunResult,
+    options?: { cause?: unknown },
+  ) {
     super(`Op "${result.op}" failed`);
     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;
   }
 }
 
@@ -109,6 +146,9 @@ class GateStop extends Error {
     public readonly records: StepRecord[],
     public readonly pending: PendingGateRecord,
     public readonly phase: string,
+    /** Whether this run's own append reached the remote — see {@link OpRunResult.gatePushed}. */
+    public readonly pushed?: boolean,
+    public readonly pushWarning?: string,
   ) {
     super(`gate "${pending.gate}" is pending approval`);
     this.name = "GateStop";
@@ -118,6 +158,14 @@ class GateStop extends Error {
 // ── 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 * 60_000;
 
 const isActivity = (s: StepDefinition): s is ActivityStep => s.kind === "activity";
@@ -356,16 +404,47 @@ async function runGateStep(
   step: GateStep,
   phaseName: string,
   gates: GateContext,
-): Promise<{ record: StepRecord; pending?: PendingGateRecord }> {
+  resultsById: ReadonlyMap<string, unknown> = new Map(),
+): Promise<{ record: StepRecord; pending?: PendingGateRecord; pushed?: boolean; pushWarning?: string }> {
   const start = Date.now();
-  const 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 } : {}),
-    ...(gates.now ? { now: gates.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;
+  let check: GateCheck;
+  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 } : {}),
+      ...(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;
@@ -386,9 +465,21 @@ async function runGateStep(
     };
   }
 
+  const refusal = check.mismatch
+    ? { refusal: describeGateMismatch(gates.op, gateName(step), check.mismatch) }
+    : {};
   return {
-    record: { phase: phaseName, fn: gateFn(step), args: {}, status: "skipped", durationMs: Date.now() - start },
+    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 } : {}),
   };
 }
 
@@ -413,7 +504,13 @@ async function runEffectStep(
   resultsById: Map<string, unknown>,
   gates: GateContext,
   signal?: AbortSignal,
-): Promise<{ records: StepRecord[]; failed: boolean; pending?: PendingGateRecord }> {
+): Promise<{
+  records: StepRecord[];
+  failed: boolean;
+  pending?: PendingGateRecord;
+  pushed?: boolean;
+  pushWarning?: string;
+}> {
   const records: StepRecord[] = [];
 
   const read = await runStep(receiptReadStep(step), phaseName, activities, profiles, resultsById, signal);
@@ -460,13 +557,19 @@ async function runEffectStep(
   for (let i = 0; i < step.steps.length; i++) {
     const nested = step.steps[i];
     if (isGate(nested)) {
-      const { record, pending } = await runGateStep(nested, phaseName, gates);
+      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 };
+        return { records, failed: false, pending, pushed, ...(pushWarning ? { pushWarning } : {}) };
       }
       continue;
     }
@@ -521,13 +624,21 @@ async function runPhase(
     // gate is about to strand would defeat the point of stopping at it.
     const gateRecords: StepRecord[] = [];
     for (const step of phase.steps.filter(isGate)) {
-      const { record, pending } = await runGateStep(step, phase.name, gates);
+      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);
+        throw new GateStop(gateRecords, pending, phase.name, pushed, pushWarning);
       }
     }
     const steps = phase.steps.filter(isActivity);
@@ -558,22 +669,28 @@ async function runPhase(
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
     if (isGate(step)) {
-      const { record, pending } = await runGateStep(step, phase.name, gates);
+      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);
+        throw new GateStop(records, pending, phase.name, pushed, pushWarning);
       }
       continue;
     }
     if (isEffect(step)) {
-      const { records: effRecords, failed, pending } = await runEffectStep(
+      const { records: effRecords, failed, pending, pushed, pushWarning } = await runEffectStep(
         step, phase.name, activities, profiles, resultsById, gates, signal,
       );
       records.push(...effRecords); // already emitted by runEffectStep
       if (pending) {
         skipRemaining(i + 1);
-        throw new GateStop(records, pending, phase.name);
+        throw new GateStop(records, pending, phase.name, pushed, pushWarning);
       }
       if (failed) {
         skipRemaining(i + 1);
@@ -743,11 +860,36 @@ export async function runOpLocally(
         status: "gated",
         startedAt,
         gate: err.pending,
+        ...(err.pushed !== undefined ? { gatePushed: err.pushed } : {}),
+        ...(err.pushWarning ? { gatePushWarning: err.pushWarning } : {}),
         record: await settle(records, "gated", err.pending),
       };
     }
 
-    if (err instanceof PhaseFailure) records.push(...err.records);
+    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),
+      });
+    }
 
     // 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.
@@ -756,19 +898,35 @@ export async function runOpLocally(
         try {
           records.push(...(await runPhase(phase, activities, profiles, resultsById, gates, signal)));
         } catch (compErr) {
-          if (compErr instanceof PhaseFailure || compErr instanceof GateStop) records.push(...compErr.records);
+          if (compErr instanceof PhaseFailure || compErr instanceof GateStop) {
+            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),
+            });
+          }
         }
       }
     }
 
-    throw new OpRunFailure({
-      op: config.name,
-      records,
-      totalMs: Date.now() - start,
-      status: "fail",
-      startedAt,
-      record: await settle(records, "fail"),
-    });
+    throw new OpRunFailure(
+      {
+        op: config.name,
+        records,
+        totalMs: Date.now() - start,
+        status: "fail",
+        startedAt,
+        record: await settle(records, "fail"),
+      },
+      { cause: err },
+    );
   }
 
   return {

package/src/op/local-output.test.ts

@@ -101,6 +101,27 @@ describe("renderHuman — gated (#2119)", () => {
   });
 });
 
+describe("renderHuman — a gated run whose own push never reached the remote (#2310)", () => {
+  test("warns that an operator elsewhere cannot see the pending fact, rather than staying silent", () => {
+    const lines: string[] = [];
+    renderHuman(
+      { ...GATED, gatePushed: false, gatePushWarning: "chant/lifecycle remote branch has moved since this run started" },
+      (l) => lines.push(l),
+    );
+    const out = lines.join("\n");
+    expect(out).toContain('Op "prod-apply" is gated on "rollout-gate"');
+    expect(out).toContain("was not pushed to the remote");
+    expect(out).toContain("chant/lifecycle remote branch has moved since this run started");
+    expect(out).toContain("An operator elsewhere cannot approve it");
+  });
+
+  test("stays as it was when the push landed", () => {
+    const lines: string[] = [];
+    renderHuman({ ...GATED, gatePushed: true }, (l) => lines.push(l));
+    expect(lines.join("\n")).not.toContain("was not pushed");
+  });
+});
+
 describe("renderJson", () => {
   test("prints the run's ledger record, not the raw result (#2118)", () => {
     const lines: string[] = [];
@@ -135,4 +156,21 @@ describe("renderJson", () => {
     expect(parsed.gate).toEqual({ name: "rollout-gate", since: "2026-09-05T12:00:00.000Z" });
     expect(parsed.approve).toBe("chant approve prod-apply rollout-gate");
   });
+
+  // #2310: a JSON consumer (CI tooling reading `chant run --json`) needs the
+  // same fact the human render shows — not just a silent success.
+  test("a gated record whose push failed carries pushed:false and why", () => {
+    const lines: string[] = [];
+    renderJson({ ...GATED, gatePushed: false, gatePushWarning: "no remote is configured" }, (l) => lines.push(l));
+    const parsed = JSON.parse(lines[0]) as { pushed?: boolean; pushWarning?: string };
+    expect(parsed.pushed).toBe(false);
+    expect(parsed.pushWarning).toBe("no remote is configured");
+  });
+
+  test("a gated record whose push landed carries no pushed field", () => {
+    const lines: string[] = [];
+    renderJson({ ...GATED, gatePushed: true }, (l) => lines.push(l));
+    const parsed = JSON.parse(lines[0]) as { pushed?: boolean };
+    expect(parsed.pushed).toBeUndefined();
+  });
 });

package/src/op/local-output.ts

@@ -47,6 +47,9 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
       write(`    [approved] ${record.approval.resolvedBy} at ${record.approval.timestamp}` +
         (record.approval.url ? ` (${record.approval.url})` : ""));
     }
+    if (record.refusal) {
+      write(`    [refused] ${record.refusal}`);
+    }
     if (record.error) {
       write(`    ${record.error}`);
     }
@@ -68,9 +71,23 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
   const { gate } = result;
   write(`Op "${result.op}" is gated on "${gate.gate}" after ${total}`);
   if (gate.description) write(`  ${gate.description}`);
+  // #2300: the plan the approval will be bound to. Printed before the
+  // command, because it is what the command approves.
+  if (gate.planDigest) write(`  plan    : ${gate.planDigest}`);
   write(`  approve : ${approveCommand(gate.op, gate.gate)}`);
   if (gate.url) write(`  approve at: ${gate.url}`);
   write(`  expires : ${gate.expiresAt}`);
+  // #2310: this run's own append reached only the local chant/lifecycle
+  // branch, not the remote. The pending fact is still correct — the gate is
+  // still right to stand — but an operator working from a clone of the
+  // remote cannot see it to approve it, and nothing else here says so.
+  if (result.gatePushed === false) {
+    write(
+      `  warning : the pending fact was not pushed to the remote — ` +
+        (result.gatePushWarning ?? "it exists only in this checkout") +
+        `. An operator elsewhere cannot approve it until it does.`,
+    );
+  }
 }
 
 /**
@@ -86,7 +103,13 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
  */
 export function renderJson(result: OpRunResult, write: Writer = stdout): void {
   const approve = result.gate ? { approve: approveCommand(result.gate.op, result.gate.gate) } : {};
-  write(JSON.stringify({ ...result.record, ...approve }));
+  // #2310: whether this run's own append reached the remote — not part of
+  // the persisted ledger record (a replay has nothing new to report), but a
+  // live run's JSON consumer needs it exactly where the human render shows it.
+  const push = result.gatePushed === false
+    ? { pushed: false, pushWarning: result.gatePushWarning ?? "the pending fact was recorded locally only" }
+    : {};
+  write(JSON.stringify({ ...result.record, ...approve, ...push }));
 }
 
 export type { OpRunResult, StepRecord };

package/src/op/op-ir.test.ts

@@ -222,6 +222,28 @@ describe("op.json IR", () => {
     expect(reconstructed.labels).toEqual({ Team: "infra", Env: "staging" });
   });
 
+  // #2300 — a gate can bind a plan by referencing the Plan step's digest, and
+  // the reference has to survive the IR: a foreign runtime resolves it the
+  // same way it resolves one in an activity's args.
+  it("carries a gate's plan reference through op.json and back", () => {
+    const config: OpConfig = {
+      name: "live-apply",
+      overview: "o",
+      phases: [
+        phase("Plan", [{ kind: "activity", fn: "shellCmd", id: "plan", args: { cmd: "plan" } }]),
+        phase("Gate", [{ kind: "gate", gate: "approve-live-apply", plan: stepOutput("plan", "planDigest") }]),
+      ],
+    };
+    const text = serializeOpIR(config);
+    const ir = JSON.parse(text) as OpIR;
+    const gate = ir.phases[1].steps[0];
+    expect(gate.kind).toBe("gate");
+    expect((gate as { plan?: unknown }).plan).toMatchObject({ step: "plan", path: "planDigest" });
+
+    const reconstructed = opConfigFromIR(ir);
+    expect(serializeOpIR(reconstructed)).toBe(text);
+  });
+
   it("round-trips a minimal Op (no gate, effect, onFailure or labels) too", () => {
     const original: OpConfig = { name: "minimal", overview: "o", phases: [phase("Only", [shell("echo hi")])] };
     const text = serializeOpIR(original);

package/src/op/op-ir.ts

@@ -137,6 +137,13 @@ export interface OpIRGateStep {
   /** Resolved to its effective value — `GateStep.timeout ?? "48h"`. */
   timeout: string;
   description?: string;
+  /**
+   * The plan this gate approves (#2300) — a digest string, or a
+   * {@link StepOutputRef} placeholder a foreign runtime resolves from the
+   * named step's result the same way it resolves one in an activity's args.
+   * Absent on a gate that binds no plan.
+   */
+  plan?: GateStep["plan"];
 }
 
 export interface OpIREffectStep {
@@ -232,6 +239,7 @@ function irGateStep(step: GateStep): OpIRGateStep {
     gate: gateName(step),
     timeout: step.timeout ?? "48h",
     ...(step.description ? { description: step.description } : {}),
+    ...(step.plan !== undefined ? { plan: step.plan } : {}),
   };
 }
 
@@ -380,6 +388,7 @@ function opStepFromIR(step: OpIRStep): StepDefinition {
       gate: step.gate,
       timeout: step.timeout,
       ...(step.description ? { description: step.description } : {}),
+      ...(step.plan !== undefined ? { plan: step.plan } : {}),
     };
   }
   return {

package/src/op/operator.test.ts

@@ -293,6 +293,26 @@ describe("runOperatorRound — lease + tick execution over a fixture ConvergeOp
     });
   });
 
+  /**
+   * #2309 review, finding 3. `chant operator` renders its own events rather
+   * than going through `renderHuman`, so fixing the executor's swallow (#2301)
+   * did nothing for this path: the message was the fixed string "see its
+   * ledger record for step-level detail", which sends the reader to an
+   * artifact that a failed ledger append means is not there.
+   */
+  test("a failing tick names the failing step, not just the ledger record", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const activities = fakeTickActivities(dir, "staging", "staging-converge", { throws: true });
+
+      const events = await runOperatorRound({ cwd: dir, holder: "op-a", activities, profiles: PROFILES });
+      const failed = events[0] as Extract<OperatorTickEvent, { kind: "tick-failed" }>;
+      expect(failed.error).not.toMatch(/see its ledger record/);
+      expect(failed.error).toMatch(/^Op "staging-converge" failed: /);
+    });
+  });
+
   test("ticks every discovered ConvergeOp across environments in one round", async () => {
     await withTestDir(async (dir) => {
       await initRepo(dir);

package/src/op/operator.ts

@@ -180,13 +180,31 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
     try {
       const result = await runOpLocally(config, opts.activities, opts.profiles, opts.signal, {
         ledger: { cwd: opts.cwd },
+        // #2301: without a sink, `settle` catches a failed ledger append and
+        // drops it. That is the failure this tick can least afford to lose —
+        // the message below points the reader at the ledger record, which is
+        // exactly the artifact a failed append means is not there.
+        onLedgerError: (err) =>
+          events.push({
+            kind: "tick-failed",
+            op: config.name,
+            env,
+            error:
+              `Op "${config.name}" ran, but its record could not be appended to the run ledger: ` +
+              `${err instanceof Error ? err.message : String(err)}`,
+          }),
       });
       const held = await stillHoldsLease(config.name, holder, lease.token, { cwd: opts.cwd });
       events.push(held ? { kind: "ticked", op: config.name, env, result } : { kind: "fenced", op: config.name, env });
     } catch (err) {
+      // #2301: "see its ledger record" was the whole message, and it sent the
+      // reader to an artifact that a failed ledger append means is missing —
+      // while `err.result` was carrying the failing steps all along. Name the
+      // failing steps here, and fall back to `cause` for a failure that
+      // produced no step record at all.
       const message =
         err instanceof OpRunFailure
-          ? `Op "${config.name}" failed — see its ledger record for step-level detail`
+          ? failureDetail(config.name, err)
           : err instanceof Error
             ? err.message
             : String(err);
@@ -197,6 +215,26 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
   return events;
 }
 
+/**
+ * What a failed tick says about itself (#2301).
+ *
+ * `chant operator` renders its own events rather than going through
+ * `renderHuman`, so the executor's step records reached nobody here even after
+ * the executor stopped dropping them. Every failing step's message, in order,
+ * or the underlying error when the run failed without producing one.
+ */
+function failureDetail(op: string, err: OpRunFailure): string {
+  const failed = err.result.records.filter((r) => r.status === "fail" && r.error);
+  if (failed.length > 0) {
+    return `Op "${op}" failed: ${failed.map((r) => `${r.fn}: ${r.error}`).join("; ")}`;
+  }
+  const cause = err.cause;
+  if (cause !== undefined) {
+    return `Op "${op}" failed: ${cause instanceof Error ? cause.message : String(cause)}`;
+  }
+  return `Op "${op}" failed — see its ledger record for step-level detail`;
+}
+
 /** Abortable sleep — resolves early (without throwing) if `signal` fires mid-wait, so the operator loop can stop promptly on Ctrl-C rather than finishing out a long interval. */
 function sleepAbortable(ms: number, signal?: AbortSignal): Promise<void> {
   return new Promise((resolve) => {

package/src/op/runtime.ts

@@ -49,6 +49,8 @@ export interface OpRunStepRecord {
   approval?: { gate: string; resolvedBy: string; timestamp: string; url?: string };
   /** The failure message, for `status: "fail"`. */
   error?: string;
+  /** Why a gate declined a standing approval that was for another plan (#2300) — see {@link StepRecord.refusal}. */
+  refusal?: string;
 }
 
 /** One phase's steps and the verdict they add up to. */

package/src/op/runtimes/local.ts

@@ -153,6 +153,17 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
               // appends it here, at the one seam every local run passes
               // through, rather than in the CLI handler above it.
               ledger: { cwd: projectPath },
+              // #2301: the run-ledger append goes through the same
+              // `chant/lifecycle` write as the gate does, so it dies for the
+              // same reasons — and this runtime declared no sink for it, so
+              // the failure was caught by `settle` and dropped on the floor.
+              // A run whose outcome never reached the ledger says so now;
+              // `chant run status` and `chant run log` will not have it.
+              onLedgerError: (err) =>
+                process.stderr.write(
+                  `warning: run "${runId}" of "${op.name}" finished, but its record could not be ` +
+                    `appended to the run ledger: ${err instanceof Error ? err.message : String(err)}\n`,
+                ),
               ...(startOpts.progress ? { onRecord: startOpts.progress } : {}),
             },
           );

package/src/op/types.ts

@@ -7,6 +7,7 @@
 
 import type { EffectReceiptRef } from "./receipt-store";
 import type { ActivityProfileName } from "./activity-profiles";
+import type { StepOutputRef } from "./step-output-ref";
 
 export interface OpConfig {
   /** Kebab-case identifier. Names the Op's output directory (`dist/ops/<name>/`), and is the name `chant run <name>` and another Op's `depends` refer to. */
@@ -177,6 +178,24 @@ export interface GateStepBase {
   timeout?: string;
   /** Human-readable description of the action required to unblock this gate. */
   description?: string;
+  /**
+   * The plan this gate approves (#2300), normally a {@link StepOutputRef}
+   * into the Plan phase's own digest — `plan.out.planDigest`. The executor
+   * resolves it the same way it resolves an activity step's args, and hands
+   * the result to `evaluateGate` as `planDigest`.
+   *
+   * With it, a resolution satisfies this gate only when it was recorded for
+   * that exact plan; a resolution for another plan is refused by name.
+   * Without it the gate authorises the next run rather than a plan, which is
+   * what every gate did before #2300 and what
+   * INTENTIUS/choudoufu#1026 measured.
+   *
+   * A `string` here is a digest computed elsewhere; anything else is a
+   * reference resolved at run time. A reference that resolves to no string
+   * leaves the gate unbound rather than failing the run — an Op whose Plan
+   * phase publishes no digest is not thereby unrunnable.
+   */
+  plan?: string | StepOutputRef;
 }
 
 /**