@intentius/chant 0.61.0 → 0.63.0

package/src/cli/handlers/operator.test.ts

@@ -16,6 +16,7 @@ const readGateResolutionsMock = vi.fn();
 const readGateLedgerMock = vi.fn();
 const readRunLedgerMock = vi.fn();
 const pushLifecycleMock = vi.fn();
+const requireLifecycleLedgerMock = vi.fn();
 
 vi.mock("../../op/operator", async () => {
   const actual = await vi.importActual<typeof import("../../op/operator")>("../../op/operator");
@@ -59,7 +60,13 @@ vi.mock("../../lifecycle/gate-ledger", async () => {
 });
 vi.mock("../../lifecycle/git", async () => {
   const actual = await vi.importActual<typeof import("../../lifecycle/git")>("../../lifecycle/git");
-  return { ...actual, pushLifecycle: (...args: unknown[]) => pushLifecycleMock(...args) };
+  return {
+    ...actual,
+    pushLifecycle: (...args: unknown[]) => pushLifecycleMock(...args),
+    // Mocked, not merely defaulted: the real one shells to `git fetch`, and
+    // these tests run in the chant checkout itself (#2303).
+    requireLifecycleLedger: (...args: unknown[]) => requireLifecycleLedgerMock(...args),
+  };
 });
 
 // Imported after the mocks above are registered.
@@ -80,6 +87,7 @@ beforeEach(() => {
   loadProfilesMock.mockResolvedValue({});
   discoverOpsMock.mockResolvedValue({ ops: new Map([["fountain-apply", {}]]), errors: [] });
   pushLifecycleMock.mockResolvedValue(true);
+  requireLifecycleLedgerMock.mockResolvedValue(undefined);
   readGateResolutionsMock.mockResolvedValue({ records: [], malformed: 0 });
   readGateLedgerMock.mockResolvedValue({ resolutions: [], pending: [], malformed: 0 });
 });
@@ -341,6 +349,29 @@ describe("runOperatorStatus", () => {
   });
 });
 
+/**
+ * A digest shaped the way `computePlanDigest` produces them (#2300).
+ */
+const PLAN_A = `sha256:${"a".repeat(64)}`;
+
+/**
+ * The standing pending fact `chant approve` reads the plan off since #2300.
+ * Every approve test seeds one, because a gate with nothing pending has no
+ * plan to approve and the command refuses rather than recording an approval
+ * of whatever runs next — which is its own test below.
+ */
+function seedPending(op: string, gate: string, planDigest: string | undefined): void {
+  readGateLedgerMock.mockResolvedValue({
+    resolutions: [],
+    pending: [{
+      version: 1, kind: "pending", op, gate,
+      timestamp: "2026-01-01T00:00:00.000Z", expiresAt: "2099-01-01T00:00:00.000Z",
+      ...(planDigest !== undefined ? { planDigest } : {}),
+    }],
+    malformed: 0,
+  });
+}
+
 describe("runApprove", () => {
   test("requires both <op> and <gate>", async () => {
     const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
@@ -350,6 +381,7 @@ describe("runApprove", () => {
   });
 
   test("appends a gate-resolution record and pushes, resolving --actor over env fallbacks", async () => {
+    seedPending("fountain-apply", "rollout-gate", PLAN_A);
     appendGateResolutionMock.mockResolvedValue({
       commit: "sha",
       record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
@@ -372,6 +404,7 @@ describe("runApprove", () => {
   test("--approver wins over --actor and over the CI/shell identity", async () => {
     vi.stubEnv("GITHUB_ACTOR", "ci-bot");
     vi.stubEnv("USER", "alex");
+    seedPending("deploy-gated", "approve-deploy", PLAN_A);
     appendGateResolutionMock.mockResolvedValue({
       commit: "sha",
       record: { version: 1, op: "deploy-gated", gate: "approve-deploy", resolvedBy: "you", timestamp: "2026-01-01T00:00:00.000Z" },
@@ -396,6 +429,7 @@ describe("runApprove", () => {
     vi.stubEnv("GITHUB_REF_NAME", "");
     vi.stubEnv("GITHUB_REPOSITORY", "");
     vi.stubEnv("CI_MERGE_REQUEST_PROJECT_URL", "");
+    seedPending("fountain-apply", "rollout-gate", PLAN_A);
     appendGateResolutionMock.mockResolvedValue({
       commit: "sha",
       record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z", url: "https://github.com/org/repo/pull/9" },
@@ -419,6 +453,7 @@ describe("runApprove", () => {
     vi.stubEnv("GITHUB_SERVER_URL", "https://github.com");
     vi.stubEnv("GITHUB_REPOSITORY", "INTENTIUS/chant");
     vi.stubEnv("GITHUB_REF_NAME", "2028/merge");
+    seedPending("fountain-apply", "g", PLAN_A);
     appendGateResolutionMock.mockResolvedValue({
       commit: "sha",
       record: { version: 1, op: "fountain-apply", gate: "g", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
@@ -480,6 +515,7 @@ describe("runApprove", () => {
 
   test("warns (but still records) when the op isn't among discovered *.op.ts declarations", async () => {
     discoverOpsMock.mockResolvedValue({ ops: new Map(), errors: [] });
+    seedPending("unknown-op", "g", PLAN_A);
     appendGateResolutionMock.mockResolvedValue({
       commit: "sha",
       record: { version: 1, op: "unknown-op", gate: "g", resolvedBy: "unknown", timestamp: "2026-01-01T00:00:00.000Z" },
@@ -726,3 +762,198 @@ describe("runOperatorLog", () => {
     errSpy.mockRestore();
   });
 });
+
+/**
+ * #2303 finding 2, at the handler. The mechanism is proved against real git
+ * in `op/gate.test.ts`; what these hold is that `chant approve` actually goes
+ * through the guard, and stops rather than writing when it refuses — the
+ * append must not be reached, because reaching it is what discarded the
+ * pending fact in the first place.
+ */
+/**
+ * #2300 — an approval is for a plan. `chant approve` records the plan it
+ * approves, so the resolution says what was reviewed rather than only who
+ * reviewed and when.
+ */
+describe("runApprove — the resolution names the plan it approves (#2300)", () => {
+  test("by default it approves the standing pending fact's plan, so the common path stays one command", async () => {
+    seedPending("fountain-apply", "rollout-gate", PLAN_A);
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z", planDigest: PLAN_A },
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }))).toBe(0);
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(expect.objectContaining({ planDigest: PLAN_A }));
+    expect(errSpy.mock.calls.map((c) => String(c[0])).join("\n")).toContain(`approves the plan ${PLAN_A}`);
+    errSpy.mockRestore();
+  });
+
+  test("--plan names one explicitly, and wins over the standing fact's", async () => {
+    const other = `sha256:${"b".repeat(64)}`;
+    seedPending("fountain-apply", "rollout-gate", PLAN_A);
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z", planDigest: other },
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex", plan: other }))).toBe(0);
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(expect.objectContaining({ planDigest: other }));
+    errSpy.mockRestore();
+  });
+
+  // With nothing pending there is no plan on the ledger to approve, and
+  // recording a resolution anyway is exactly how an approval came to mean
+  // "the next run" (INTENTIUS/choudoufu#1026).
+  test("with no pending record it refuses, writes nothing, and names the fix", async () => {
+    readGateLedgerMock.mockResolvedValue({ resolutions: [], pending: [], malformed: 0 });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    const code = await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }));
+
+    expect(code).toBe(1);
+    expect(appendGateResolutionMock).not.toHaveBeenCalled();
+    expect(pushLifecycleMock).not.toHaveBeenCalled();
+    const out = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(out).toContain("has no pending fact, so there is no plan to approve");
+    expect(out).toContain("chant run fountain-apply");
+    expect(out).toContain("--plan <digest>");
+    errSpy.mockRestore();
+  });
+
+  // ...but `--plan` is the escape hatch, so approving a plan whose digest you
+  // already hold does not need a run to have recorded a pending fact first.
+  test("--plan approves with nothing pending", async () => {
+    readGateLedgerMock.mockResolvedValue({ resolutions: [], pending: [], malformed: 0 });
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z", planDigest: PLAN_A },
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex", plan: PLAN_A }))).toBe(0);
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(expect.objectContaining({ planDigest: PLAN_A }));
+    errSpy.mockRestore();
+  });
+
+  test("a --plan that is not a digest is refused before anything is written", async () => {
+    seedPending("fountain-apply", "rollout-gate", PLAN_A);
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    const code = await runApprove(ctx({
+      path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex", plan: "chant.tfplan",
+    }));
+
+    expect(code).toBe(1);
+    expect(appendGateResolutionMock).not.toHaveBeenCalled();
+    expect(errSpy.mock.calls.map((c) => String(c[0])).join("\n")).toContain("--plan must be a plan digest");
+    errSpy.mockRestore();
+  });
+
+  // A gate that binds no plan records no digest on its pending fact, so the
+  // resolution carries none either — and nothing refuses, because nothing
+  // ever claimed to bind a plan there.
+  test("a gate that binds no plan approves as it always did", async () => {
+    seedPending("fountain-apply", "rollout-gate", undefined);
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }))).toBe(0);
+    expect(appendGateResolutionMock.mock.calls[0][0]).not.toHaveProperty("planDigest");
+    errSpy.mockRestore();
+  });
+});
+
+describe("runApprove — the ledger branch is read before it is appended to (#2303)", () => {
+  test("reads the branch before recording the resolution", async () => {
+    seedPending("fountain-apply", "rollout-gate", PLAN_A);
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }))).toBe(0);
+
+    expect(requireLifecycleLedgerMock).toHaveBeenCalled();
+    expect(requireLifecycleLedgerMock.mock.invocationCallOrder[0]).toBeLessThan(
+      appendGateResolutionMock.mock.invocationCallOrder[0],
+    );
+    errSpy.mockRestore();
+  });
+
+  test("refuses by name, and writes nothing, when the branch cannot be read", async () => {
+    requireLifecycleLedgerMock.mockRejectedValue(
+      new Error(
+        'the chant/lifecycle ledger branch is not in this checkout and could not be fetched from "origin"',
+      ),
+    );
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    const code = await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }));
+
+    expect(code).toBe(1);
+    expect(appendGateResolutionMock).not.toHaveBeenCalled();
+    expect(pushLifecycleMock).not.toHaveBeenCalled();
+    expect(errSpy.mock.calls.map((c) => String(c[0])).join("\n")).toContain("chant/lifecycle ledger branch");
+    errSpy.mockRestore();
+  });
+
+  test("--expire is guarded the same way", async () => {
+    requireLifecycleLedgerMock.mockRejectedValue(new Error("the chant/lifecycle ledger branch has diverged"));
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    const code = await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", expire: true }));
+
+    expect(code).toBe(1);
+    expect(appendPendingGateMock).not.toHaveBeenCalled();
+    errSpy.mockRestore();
+  });
+});
+
+/**
+ * #2309 review. `pushLifecycle().catch(() => undefined)` at both write sites
+ * meant a rejected push printed unconditional success and exited 0 — the
+ * operator walks away believing the gate is answered for everybody, while the
+ * resolution exists only in their own checkout.
+ */
+describe("runApprove — a push that does not land is reported (#2309 review)", () => {
+  test("a rejected push warns and marks the success line local-only", async () => {
+    seedPending("fountain-apply", "rollout-gate", PLAN_A);
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    pushLifecycleMock.mockRejectedValue(new Error("Another snapshot completed for chant/lifecycle"));
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    const code = await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }));
+
+    const out = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(out).toMatch(/push to the remote was rejected/);
+    expect(out).toMatch(/local only . the push did not land/);
+    // Still exit 0: the local append is a correct local fact.
+    expect(code).toBe(0);
+    errSpy.mockRestore();
+  });
+
+  test("a project with no remote says nothing was pushed", async () => {
+    seedPending("fountain-apply", "rollout-gate", PLAN_A);
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    pushLifecycleMock.mockResolvedValue(false);
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }));
+
+    expect(errSpy.mock.calls.map((c) => String(c[0])).join("\n")).toMatch(/No remote is configured/);
+    errSpy.mockRestore();
+  });
+});

package/src/cli/handlers/operator.ts

@@ -34,7 +34,8 @@ import {
   latestResolutionSince, latestPendingGate, isPendingGateExpired,
   resolveApprovalUrl, isApprovalUrl,
 } from "../../lifecycle/gate-ledger";
-import { pushLifecycle } from "../../lifecycle/git";
+import { isPlanDigest } from "../../lifecycle/plan-digest";
+import { pushLifecycle, requireLifecycleLedger } from "../../lifecycle/git";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import type { CommandContext } from "../registry";
 
@@ -598,6 +599,39 @@ export async function runOperatorLog(ctx: CommandContext): Promise<number> {
  * is already expired, which supersedes the standing one on an append-only
  * ledger, so the next run decides the gate from scratch.
  */
+/** The ledger branch, named in the warnings below so a reader can go look at it. */
+const LIFECYCLE_BRANCH = "chant/lifecycle";
+
+/**
+ * Push the ledger and say so when it does not land (#2309 review, refs #2310).
+ *
+ * Both write paths here used `pushLifecycle().catch(() => undefined)` and then
+ * printed unconditional success and exited 0. A rejected push — a stale lease,
+ * no credentials, no network — therefore read as a completed approval, which
+ * is the one thing an approval must never do: the operator walks away
+ * believing the gate is answered for everybody, while the resolution exists
+ * only in their own checkout.
+ *
+ * The append is still a correct *local* fact, so this is a warning and not a
+ * failure; the exit code is unchanged.
+ */
+async function reportedPush(consequence: string): Promise<boolean> {
+  try {
+    const pushed = await pushLifecycle();
+    if (pushed) return true;
+    console.error(formatWarning({
+      message: `No remote is configured, so nothing was pushed. ${consequence}`,
+    }));
+    return false;
+  } catch (err) {
+    console.error(formatWarning({
+      message: `The push to the remote was rejected: ${err instanceof Error ? err.message : String(err)}`,
+      hint: consequence,
+    }));
+    return false;
+  }
+}
+
 export async function runApprove(ctx: CommandContext): Promise<number> {
   const opName = ctx.args.path;
   const gate = ctx.args.extraPositional;
@@ -607,6 +641,18 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
   }
 
   if (ctx.args.expire) {
+    // Same guard as the approve path below (#2303): `--expire` reads the
+    // standing fact and appends beside it, so a clone that never fetched the
+    // branch would both fail to see the fact it is expiring and replace the
+    // branch with the expiry alone.
+    try {
+      await requireLifecycleLedger();
+    } catch (err) {
+      console.error(formatError({
+        message: `Cannot expire the gate: ${err instanceof Error ? err.message : String(err)}`,
+      }));
+      return 1;
+    }
     const now = new Date().toISOString();
     const standing = latestPendingGate((await readGateLedger(opName)).pending, gate);
     if (!standing || isPendingGateExpired(standing, now)) {
@@ -622,8 +668,14 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
       expiresAt: now,
       ...(standing.description ? { description: standing.description } : {}),
     });
-    await pushLifecycle().catch(() => undefined);
-    console.error(formatSuccess(`Gate "${gate}" on "${opName}" expired at ${now} — not approved`));
+    const pushed = await reportedPush(
+      `The expiry is recorded locally on ${LIFECYCLE_BRANCH}. Until it reaches the remote, ` +
+        `a run in another checkout still sees the old pending fact.`,
+    );
+    console.error(formatSuccess(
+      `Gate "${gate}" on "${opName}" expired at ${now} — not approved` +
+        (pushed ? "" : " (local only — the push did not land)"),
+    ));
     console.error(formatInfo(
       `The next \`chant run ${opName}\` decides this gate from scratch and records a fresh pending fact.`,
     ));
@@ -638,6 +690,7 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     actor: ctx.args.approver ?? ctx.args.actor,
     note: ctx.args.note,
     url: ctx.args.url,
+    plan: ctx.args.plan,
   });
   if (!outcome.ok) return 1;
 
@@ -656,6 +709,12 @@ export interface GateApprovalOptions {
   note?: string;
   /** `--url` — the approval surface, validated as absolute http/https. */
   url?: string;
+  /**
+   * `--plan <digest>` (#2300) — the plan this approval is for. Omitted, the
+   * digest is read off the gate's standing pending fact, so the common path
+   * stays one command: run, read what it planned, approve it.
+   */
+  plan?: string;
 }
 
 export type GateApprovalOutcome =
@@ -669,6 +728,13 @@ export type GateApprovalOutcome =
  *
  * Prints the same warning for an undiscovered op and the same success line as
  * `chant approve` always did; the caller adds whatever it does next.
+ *
+ * Since #2300 the resolution names the plan it approves. By default that is
+ * the standing pending fact's plan — the one the gated run produced — so the
+ * common path is still `chant run`, read, `chant approve`. With no pending
+ * fact and no `--plan`, this refuses: there is nothing on the ledger saying
+ * what would be approved, and writing a resolution anyway is what made an
+ * approval mean "the next run" instead of "this plan".
  */
 export async function recordGateApproval(
   opName: string,
@@ -682,7 +748,20 @@ export async function recordGateApproval(
     }));
   }
 
-  const resolvedBy = opts.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER ?? "unknown";
+  // Read the branch before appending to it (#2303 finding 2). Without this,
+  // an approve in a clone that never fetched `chant/lifecycle` builds its
+  // commit from an empty tree with no parent and replaces the branch with a
+  // single commit holding only this resolution — the pending fact it is
+  // answering is discarded rather than appended to.
+  try {
+    await requireLifecycleLedger();
+  } catch (err) {
+    console.error(formatError({
+      message: `Cannot record the approval: ${err instanceof Error ? err.message : String(err)}`,
+      hint: "The pending fact this answers lives on that branch; appending without it would drop it.",
+    }));
+    return { ok: false };
+  }
 
   // #2028: the resolution's link is typed. `--url` wins; otherwise, running
   // inside the PR/MR job that carries the change is itself the address, the
@@ -696,6 +775,40 @@ export async function recordGateApproval(
     return { ok: false };
   }
 
+  // #2300: an approval is for a plan, so this command has to know which one.
+  // `--plan` names it outright; otherwise it comes off the gate's standing
+  // pending fact — the plan the run that stopped at this gate produced, which
+  // is the plan whoever is typing this just read. There is deliberately no
+  // third fallback: approving with no plan in sight is the behaviour
+  // INTENTIUS/choudoufu#1026 measured, where the resolution authorised the
+  // next run rather than anything anyone had seen.
+  let planDigest: string | undefined;
+  if (opts.plan !== undefined) {
+    if (!isPlanDigest(opts.plan)) {
+      console.error(formatError({
+        message: `--plan must be a plan digest ("sha256:" and 64 hex characters), got "${opts.plan}"`,
+        hint: "Copy it from the gated run's `plan :` line, or from the pending-gate summary. It is not a plan file path.",
+      }));
+      return { ok: false };
+    }
+    planDigest = opts.plan;
+  } else {
+    const standing = latestPendingGate((await readGateLedger(opName)).pending, gate);
+    if (!standing) {
+      console.error(formatError({
+        message: `Gate "${gate}" on "${opName}" has no pending fact, so there is no plan to approve`,
+        hint:
+          `Run \`chant run ${opName}\` first — it plans, stops at the gate, and records the plan this ` +
+          `approval would be for. To approve a plan you already have the digest for, pass ` +
+          `\`--plan <digest>\`.`,
+      }));
+      return { ok: false };
+    }
+    planDigest = standing.planDigest;
+  }
+
+  const resolvedBy = opts.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER ?? "unknown";
+
   const { record } = await appendGateResolution({
     op: opName,
     gate,
@@ -703,12 +816,23 @@ export async function recordGateApproval(
     timestamp: new Date().toISOString(),
     ...(opts.note ? { note: opts.note } : {}),
     ...(url ? { url } : {}),
+    ...(planDigest !== undefined ? { planDigest } : {}),
   });
-  await pushLifecycle().catch(() => undefined);
+  const pushed = await reportedPush(
+    `The resolution is recorded locally on ${LIFECYCLE_BRANCH}. Until it reaches the remote, ` +
+      `a run in another checkout will not see it.`,
+  );
 
   console.error(formatSuccess(
     `Gate "${gate}" on "${opName}" resolved by ${record.resolvedBy} at ${record.timestamp}` +
-      (record.url ? ` (${record.url})` : ""),
+      (record.url ? ` (${record.url})` : "") +
+      (pushed ? "" : " (local only — the push did not land)"),
   ));
+  if (record.planDigest) {
+    console.error(formatInfo(
+      `This approves the plan ${record.planDigest}, and only that plan. A run whose fresh plan ` +
+        "differs refuses rather than applying it.",
+    ));
+  }
   return { ok: true, record };
 }

package/src/cli/handlers/run.ts

@@ -385,6 +385,7 @@ export async function runOpApprove(ctx: CommandContext): Promise<number> {
     actor: ctx.args.approver ?? ctx.args.actor,
     note: ctx.args.note,
     url: ctx.args.url,
+    plan: ctx.args.plan,
   });
   if (!outcome.ok) return 1;
 
@@ -744,6 +745,16 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
     console.error(formatInfo(`approve : ${approveCommand(gate.op, gate.gate)}`));
     if (gate.url) console.error(formatInfo(`approve at: ${gate.url}`));
     console.error(formatInfo(`expires : ${gate.expiresAt}`));
+    // #2310: this run's own append reached only the local chant/lifecycle
+    // branch. The gate is still right to stand, but an operator elsewhere
+    // cannot see the pending fact to approve it, and nothing else here says
+    // why not.
+    if (result.gated.pushed === false) {
+      console.error(formatWarning({
+        message: `the pending fact was not pushed to the remote: ${result.gated.pushWarning ?? "recorded locally only"}`,
+        hint: "an operator working from a clone of the remote cannot approve it until it does",
+      }));
+    }
     reportGatedRun(
       {
         op: gate.op,
@@ -751,6 +762,8 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
         ...(gate.description ? { description: gate.description } : {}),
         expiresAt: gate.expiresAt,
         ...(gate.url ? { url: gate.url } : {}),
+        ...(result.gated.pushed === false ? { pushed: false, pushWarning: result.gated.pushWarning } : {}),
+        ...(gate.planDigest ? { planDigest: gate.planDigest } : {}),
       },
       gatedExit,
     );
@@ -866,6 +879,12 @@ export async function runOpOnRuntime(ctx: CommandContext): Promise<number> {
             ...(pending?.description ? { description: pending.description } : {}),
             ...(pending?.expiresAt ? { expiresAt: pending.expiresAt } : {}),
             ...(pending?.url ? { url: pending.url } : {}),
+            // #2310: the local runtime knows whether this run's own append
+            // reached the remote; a runtime that reports only a state does not.
+            ...(status.result?.gatePushed === false
+              ? { pushed: false, pushWarning: status.result.gatePushWarning }
+              : {}),
+            ...(pending?.planDigest ? { planDigest: pending.planDigest } : {}),
           },
           gatedExit,
         );

package/src/cli/main.ts

@@ -404,6 +404,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.note = args[++i];
     } else if (arg === "--expire") {
       result.expire = true;
+    } else if (arg === "--plan") {
+      result.plan = args[++i];
     } else if (arg === "--url") {
       result.url = args[++i];
     } else if (arg === "--op") {

package/src/cli/registry.ts

@@ -318,6 +318,8 @@ export interface ParsedArgs {
   note?: string;
   /** `chant approve <op> <gate> --expire` (#2119) — clear the gate's standing pending fact instead of approving it, so the next run decides the gate from scratch and records a fresh one. Writes no resolution: nothing is approved, the wait is only restarted. */
   expire?: boolean;
+  /** `chant approve <op> <gate> --plan <digest>` (#2300) — the plan this approval is for, as `sha256:<64 hex>`. Omitted, the digest is taken from the gate's standing pending fact, which is the plan the run that stopped at the gate actually produced; pass it to approve a plan explicitly, or to approve one before any run has recorded a pending fact. */
+  plan?: string;
   /** `chant operator log --op <name>` (#2029) — restrict the tick history to one ConvergeOp by name. Omitted, every discovered ConvergeOp's ticks are merged into one timeline. */
   op?: string;
   /** `chant operator log --since <iso>` (#2029) — only entries at or after this ISO-8601 instant. */

package/src/components/cli-support.ts

@@ -425,7 +425,13 @@ export interface RunComponentsResult {
   selected: string[];
   error?: string;
   /** Set when the run stopped at a `gate` nobody has approved (#2119): the component it stopped at and the pending fact recorded for it. */
-  gated?: { component: string; gate: PendingGateRecord };
+  gated?: {
+    component: string;
+    gate: PendingGateRecord;
+    /** Whether this run's own append reached the remote (#2310); absent when the pending fact was already standing. */
+    pushed?: boolean;
+    pushWarning?: string;
+  };
   /** This run's resolved build-time parameters (chant #1108) — the component-driver counterpart of `../cli/commands/build.ts`'s `BuildResult.buildParams`. Present only once the run actually reached dispatch (mirrors `BuildResult.buildParams`, which is likewise absent on an early-error return). */
   buildParams?: BuildParamProvenance[];
 }
@@ -571,7 +577,14 @@ export async function runComponents(
         selected,
         buildParams: options.buildParams,
         ...(run.status === "gated" && run.gate
-          ? { gated: { component: run.gatedComponent ?? selected[0], gate: run.gate } }
+          ? {
+              gated: {
+                component: run.gatedComponent ?? selected[0],
+                gate: run.gate,
+                ...(run.gatePushed !== undefined ? { pushed: run.gatePushed } : {}),
+                ...(run.gatePushWarning ? { pushWarning: run.gatePushWarning } : {}),
+              },
+            }
           : {}),
       };
     }
@@ -613,7 +626,12 @@ export async function runComponents(
       status: componentResult.status,
       failedComponent: componentResult.status === "fail" ? componentResult.component : undefined,
       ...(componentResult.status === "gated"
-        ? { gatedComponent: componentResult.component, gate: componentResult.gate }
+        ? {
+            gatedComponent: componentResult.component,
+            gate: componentResult.gate,
+            ...(componentResult.gatePushed !== undefined ? { gatePushed: componentResult.gatePushed } : {}),
+            ...(componentResult.gatePushWarning ? { gatePushWarning: componentResult.gatePushWarning } : {}),
+          }
         : {}),
       componentOutputs,
     };
@@ -623,7 +641,14 @@ export async function runComponents(
       selected,
       buildParams: options.buildParams,
       ...(componentResult.status === "gated" && componentResult.gate
-        ? { gated: { component: componentResult.component, gate: componentResult.gate } }
+        ? {
+            gated: {
+              component: componentResult.component,
+              gate: componentResult.gate,
+              ...(componentResult.gatePushed !== undefined ? { pushed: componentResult.gatePushed } : {}),
+              ...(componentResult.gatePushWarning ? { pushWarning: componentResult.gatePushWarning } : {}),
+            },
+          }
         : {}),
     };
   } catch (err) {

package/src/components/driver-output.ts

@@ -72,6 +72,16 @@ export function renderDriverHuman(result: DriverRunResult, write: Writer = stder
     write(`interpret run completed (${result.order.length} component(s))`);
   } else if (result.status === "gated") {
     write(`interpret run is gated at component "${result.gatedComponent}"`);
+    // #2310: this run's own append reached only the local chant/lifecycle
+    // branch. The gate still stands correctly — but an operator elsewhere
+    // cannot see the pending fact to approve it.
+    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.`,
+      );
+    }
   } else {
     write(`interpret run failed at component "${result.failedComponent}"`);
   }