@intentius/chant 0.62.0 → 0.63.0

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

@@ -6,9 +6,10 @@ import {
   parseDuration,
   OpRunFailure,
 } from "./local-executor";
-import { memoryGateLedgerPort } from "./gate";
+import { memoryGateLedgerPort, type GateLedgerPort } from "./gate";
+import { computePlanDigest } from "../lifecycle/plan-digest";
 import { renderHuman } from "./local-output";
-import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+import type { GateResolutionRecord, PendingGateRecord, PendingGateInput } from "../lifecycle/gate-ledger";
 import { stepOutput } from "./step-output-ref";
 
 // Fast profiles so retry/timeout tests run in milliseconds.
@@ -325,6 +326,33 @@ describe("runOpLocally — gate as fact (#2119)", () => {
     ]);
   });
 
+  // #2310: the gate still ends the run `gated` — an append that only reaches
+  // the local branch is still a correct local answer, and the #2309 author
+  // was right that this must not become a failure. But the run used to say
+  // nothing at all about the rejected push; now it does.
+  test("a pending fact whose push was rejected still ends the run gated, and says the push failed", async () => {
+    const { calls, activities } = tracked();
+    const port = {
+      async read() {
+        return { resolutions: [] as GateResolutionRecord[], pending: [] as PendingGateRecord[] };
+      },
+      async appendPending(input: PendingGateInput) {
+        return {
+          record: { version: 1 as const, kind: "pending" as const, ...input },
+          pushed: false,
+          pushWarning: "chant/lifecycle remote branch has moved since this run started",
+        };
+      },
+    };
+    const result = await runOpLocally(gatedOp(), activities, PROFILES, undefined, { gates: port, now: NOW });
+
+    expect(result.status).toBe("gated");
+    expect(calls).toEqual(["before"]);
+    expect(result.gate).toMatchObject({ op: "test-op", gate: "approve-prod" });
+    expect(result.gatePushed).toBe(false);
+    expect(result.gatePushWarning).toBe("chant/lifecycle remote branch has moved since this run started");
+  });
+
   // #2202: the gate step's name key is `gate`; `signalName` is read through
   // 0.59.0, so a step still spelling it that way reaches the same ledger entry.
   test("a gate step still using the deprecated `signalName` key names the same gate", async () => {
@@ -523,7 +551,7 @@ describe("runOpLocally — a failure inside the run says what it was (#2301)", (
       async read() {
         return { resolutions: [] as GateResolutionRecord[], pending: [] as PendingGateRecord[] };
       },
-      async appendPending(): Promise<PendingGateRecord> {
+      async appendPending(): Promise<never> {
         throw new Error(message);
       },
     };
@@ -612,3 +640,198 @@ describe("runOpLocally — a failure inside the run says what it was (#2301)", (
     expect(lines.some((l) => l.includes("progress sink exploded"))).toBe(true);
   });
 });
+
+/**
+ * #2300, measured on INTENTIUS/choudoufu#1026.
+ *
+ * The exact sequence that issue ran against a floci-backed root: `chant run
+ * live-apply` returns `gated`, `chant approve` writes the resolution, a
+ * resource in the root is renamed, and `chant run live-apply` runs again. It
+ * applied, with no refusal, because the resolution carried the op, the gate,
+ * the approver and a timestamp — and nothing about the plan. The approval had
+ * authorised the next run rather than the plan its approver read.
+ *
+ * These drive the same four steps through the executor, with a Plan phase
+ * whose digest moves when the root does.
+ */
+describe("runOpLocally — a gate approves a plan, not the next run (#2300)", () => {
+  const NOW = "2026-09-09T12:00:00.000Z";
+
+  /**
+   * A gate ledger a test can approve against, which `memoryGateLedgerPort`
+   * cannot: `chant approve` appends a resolution *between* two runs, and the
+   * shared port has to carry it into the second one.
+   */
+  function approvableLedger(): GateLedgerPort & {
+    approve(gate: string, planDigest: string | undefined, at: string): void;
+    pending: PendingGateRecord[];
+  } {
+    const resolutions: GateResolutionRecord[] = [];
+    const pending: PendingGateRecord[] = [];
+    return {
+      pending,
+      approve(gate, planDigest, at) {
+        resolutions.push({
+          version: 1, op: "live-apply", gate, resolvedBy: "alex", timestamp: at,
+          ...(planDigest !== undefined ? { planDigest } : {}),
+        });
+      },
+      async read() {
+        return { resolutions: [...resolutions], pending: [...pending] };
+      },
+      async appendPending(input) {
+        const record: PendingGateRecord = { version: 1, kind: "pending", ...input };
+        pending.push(record);
+        // No remote in an in-memory ledger — nothing to fail to reach (#2310).
+        return { record, pushed: true };
+      },
+    };
+  }
+
+  /**
+   * The root under test, and the Op over it. `terraformPlan` digests whatever
+   * `root.address` currently is, so renaming a resource between runs is one
+   * assignment — the test's stand-in for editing the `.tf` file.
+   */
+  function harness() {
+    const root = { address: "aws_s3_bucket.original" };
+    const applied: string[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["terraformPlan", async () => ({
+        planFile: "chant.tfplan",
+        planDigest: computePlanDigest("terraform-plan", { resourceChanges: [{ address: root.address }] }),
+      })],
+      ["terraformApply", async (args) => {
+        applied.push(String(args.planFile));
+        return { applied: true };
+      }],
+    ]);
+    const config = op({
+      name: "live-apply",
+      phases: [
+        { name: "Plan", steps: [{ kind: "activity", fn: "terraformPlan", id: "plan", args: { root: "app" } }] },
+        {
+          name: "Gate",
+          steps: [{ kind: "gate", gate: "approve-live-apply", plan: stepOutput("plan", "planDigest") }],
+        },
+        {
+          name: "Apply",
+          steps: [{ kind: "activity", fn: "terraformApply", args: { planFile: stepOutput("plan", "planFile") } }],
+        },
+      ],
+    });
+    const digestOf = (address: string) =>
+      computePlanDigest("terraform-plan", { resourceChanges: [{ address }] });
+    return { root, applied, activities, config, digestOf };
+  }
+
+  test("approve, rename a resource in the root, re-run — the Apply phase refuses, naming both digests", async () => {
+    const { root, applied, activities, config, digestOf } = harness();
+    const gates = approvableLedger();
+
+    // 1. `chant run live-apply` — gated, and the pending fact names the plan.
+    const first = await runOpLocally(config, activities, PROFILES, undefined, { gates, now: NOW });
+    expect(first.status).toBe("gated");
+    expect(first.gate?.planDigest).toBe(digestOf("aws_s3_bucket.original"));
+    expect(applied).toEqual([]);
+
+    // 2. `chant approve live-apply approve-live-apply` — for the plan above.
+    gates.approve("approve-live-apply", digestOf("aws_s3_bucket.original"), "2026-09-09T12:05:00.000Z");
+
+    // 3. A resource in the root is renamed.
+    root.address = "aws_s3_bucket.renamed";
+
+    // 4. `chant run live-apply` again. On the pre-#2300 rule this applied.
+    const second = await runOpLocally(config, activities, PROFILES, undefined, {
+      gates, now: "2026-09-09T12:10:00.000Z",
+    });
+
+    expect(second.status).toBe("gated");
+    expect(applied).toEqual([]);
+
+    const gateRecord = second.records.find((r) => r.fn === "gate:approve-live-apply");
+    expect(gateRecord?.refusal).toContain(`approved: ${digestOf("aws_s3_bucket.original")}`);
+    expect(gateRecord?.refusal).toContain(`planned: ${digestOf("aws_s3_bucket.renamed")}`);
+    expect(gateRecord?.refusal).toContain("chant approve live-apply approve-live-apply");
+    expect(gateRecord?.refusal).toContain("changed between that approval and this plan");
+    // The Apply step never ran, and says so.
+    expect(second.records.find((r) => r.fn === "terraformApply")?.status).toBe("skipped");
+
+    // The refusal reaches a reader, not just the record.
+    const lines: string[] = [];
+    renderHuman(second, (line) => lines.push(line));
+    expect(lines.some((l) => l.includes("[refused]") && l.includes("not for this plan"))).toBe(true);
+  });
+
+  test("approve, re-run with the root unchanged — it applies", async () => {
+    const { applied, activities, config, digestOf } = harness();
+    const gates = approvableLedger();
+
+    expect((await runOpLocally(config, activities, PROFILES, undefined, { gates, now: NOW })).status).toBe("gated");
+    gates.approve("approve-live-apply", digestOf("aws_s3_bucket.original"), "2026-09-09T12:05:00.000Z");
+
+    const second = await runOpLocally(config, activities, PROFILES, undefined, {
+      gates, now: "2026-09-09T12:10:00.000Z",
+    });
+
+    expect(second.status).toBe("ok");
+    expect(applied).toEqual(["chant.tfplan"]);
+    expect(second.records.find((r) => r.fn === "gate:approve-live-apply")?.approval?.resolvedBy).toBe("alex");
+  });
+
+  /**
+   * The migration (#2300). Every resolution written before this change has no
+   * `planDigest` at all, and the safe reading is that it matches nothing: such
+   * a record proves someone approved something and nothing about what.
+   * Accepting it once — the other candidate reading — would apply exactly the
+   * unreviewed change this check exists to catch, on the estates that have
+   * been running longest.
+   */
+  test("a resolution recorded before plan-bound gates does not pass, and the refusal says so", async () => {
+    const { applied, activities, config, digestOf } = harness();
+    const gates = approvableLedger();
+
+    expect((await runOpLocally(config, activities, PROFILES, undefined, { gates, now: NOW })).status).toBe("gated");
+    // A pre-#2300 resolution: newer than the pending fact, no plan on it.
+    gates.approve("approve-live-apply", undefined, "2026-09-09T12:05:00.000Z");
+
+    const second = await runOpLocally(config, activities, PROFILES, undefined, {
+      gates, now: "2026-09-09T12:10:00.000Z",
+    });
+
+    expect(second.status).toBe("gated");
+    expect(applied).toEqual([]);
+    const gateRecord = second.records.find((r) => r.fn === "gate:approve-live-apply");
+    expect(gateRecord?.refusal).toContain("approved: (none — recorded before plan-bound gates)");
+    expect(gateRecord?.refusal).toContain(`planned: ${digestOf("aws_s3_bucket.original")}`);
+    // ...and says why, which is not "something changed": nothing is known to
+    // have changed, the record just never said what it approved.
+    expect(gateRecord?.refusal).toContain("records no plan at all");
+  });
+
+  /**
+   * A gate with no `plan` is every gate that existed before #2300 — a
+   * component gate, an authored `gate()` with nothing to bind. Those decide
+   * exactly as they did: newest resolution since the pending fact wins.
+   */
+  test("a gate that binds no plan is unchanged", async () => {
+    const activities = new Map<string, ActivityFn>([["deploy", async () => ({ ok: true })]]);
+    const config = op({
+      name: "live-apply",
+      phases: [
+        { name: "Gate", steps: [{ kind: "gate", gate: "approve-live-apply" }] },
+        { name: "Deploy", steps: [{ kind: "activity", fn: "deploy" }] },
+      ],
+    });
+    const gates = approvableLedger();
+
+    expect((await runOpLocally(config, activities, PROFILES, undefined, { gates, now: NOW })).status).toBe("gated");
+    expect(gates.pending[0].planDigest).toBeUndefined();
+    gates.approve("approve-live-apply", undefined, "2026-09-09T12:05:00.000Z");
+
+    const second = await runOpLocally(config, activities, PROFILES, undefined, {
+      gates, now: "2026-09-09T12:10:00.000Z",
+    });
+    expect(second.status).toBe("ok");
+  });
+});

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 GateCheck, 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
@@ -129,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";
@@ -384,8 +404,16 @@ 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();
+  // #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, {
@@ -394,6 +422,7 @@ async function runGateStep(
       ...(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) {
@@ -436,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 } : {}),
   };
 }
 
@@ -463,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);
@@ -510,7 +557,7 @@ 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
@@ -522,7 +569,7 @@ async function runEffectStep(
         // 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;
     }
@@ -577,7 +624,7 @@ 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
@@ -591,7 +638,7 @@ async function runPhase(
         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);
@@ -622,7 +669,7 @@ 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
@@ -632,18 +679,18 @@ async function runPhase(
       }
       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);
@@ -813,6 +860,8 @@ 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),
       };
     }

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/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/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;
 }
 
 /**