@intentius/chant 0.62.0 → 0.63.0

package/src/op/gate-summary.test.ts

@@ -28,6 +28,39 @@ describe("gatedRunSummaryMarkdown (#2243)", () => {
     expect(md).toContain("chant approve app-apply approve-app-apply --approver <you>");
     expect(md).toContain("_gates/app-apply.jsonl");
   });
+
+  // #2310: `recordGateApproval`'s push was already reported (#2309); the
+  // gate's own `appendPending` push was not. The GitHub/Forgejo/Gitea step
+  // summary is exactly the surface an operator working from a different
+  // checkout would open, so it is where the gap mattered most.
+  test("says so when this run's own append never reached the remote", () => {
+    const md = gatedRunSummaryMarkdown({
+      ...summary,
+      pushed: false,
+      pushWarning: "chant/lifecycle remote branch has moved since this run started",
+    });
+    expect(md).toContain("was not pushed to the remote");
+    expect(md).toContain("chant/lifecycle remote branch has moved since this run started");
+    expect(md).toContain("cannot see it to approve it");
+  });
+
+  test("says nothing extra when the push landed or nothing was pushed this run", () => {
+    const md = gatedRunSummaryMarkdown(summary);
+    expect(md).not.toContain("was not pushed");
+  });
+
+  // #2300 — the block is where a CI approver reads what they are approving,
+  // so it names the plan and says the approval does not carry to the next one.
+  test("names the plan the approval binds to, when the gate binds one", () => {
+    const digest = `sha256:${"d".repeat(64)}`;
+    const md = gatedRunSummaryMarkdown({ ...summary, planDigest: digest });
+    expect(md).toContain(digest);
+    expect(md).toContain("and not the next run");
+  });
+
+  test("a gate that binds no plan says nothing about one", () => {
+    expect(gatedRunSummaryMarkdown(summary)).not.toContain("and not the next run");
+  });
 });
 
 describe("writeGatedRunSummary surfaces (#2243, #2256)", () => {

package/src/op/gate-summary.ts

@@ -34,6 +34,22 @@ export interface GatedRunSummary {
   expiresAt?: string;
   /** The approval surface the run resolved, when it knew one. */
   url?: string;
+  /**
+   * False when this run's own append reached only the local chant/lifecycle
+   * branch, not the remote (#2310) — the reason lives in `pushWarning`.
+   * Absent when this run left an already-standing pending fact alone, or when
+   * the push landed.
+   */
+  pushed?: boolean;
+  /** Set when `pushed` is false. */
+  pushWarning?: string;
+  /**
+   * The plan the pending fact was recorded against (#2300), when the gate
+   * binds one. Shown because it is what the `chant approve` line below
+   * approves — and because a reader who comes back to a stale summary needs
+   * to see that the digest has moved on.
+   */
+  planDigest?: string;
 }
 
 /**
@@ -51,6 +67,13 @@ export function gatedRunSummaryMarkdown(summary: GatedRunSummary): string {
   if (summary.description) {
     lines.push(summary.description, "");
   }
+  if (summary.planDigest) {
+    lines.push(
+      `This approves one plan, \`${summary.planDigest}\`, and not the next run (#2300). ` +
+        "Change the configuration after approving and the next run refuses rather than applying.",
+      "",
+    );
+  }
   lines.push(
     "Approve it, then re-run this workflow:",
     "",
@@ -62,6 +85,14 @@ export function gatedRunSummaryMarkdown(summary: GatedRunSummary): string {
   );
   if (summary.expiresAt) lines.push(`Expires: ${summary.expiresAt}`);
   if (summary.url) lines.push(`Approve at: ${summary.url}`);
+  if (summary.pushed === false) {
+    lines.push(
+      "",
+      `**This pending fact was not pushed to the remote** (${summary.pushWarning ?? "no reason given"}). ` +
+        "It exists only in this job's checkout. An operator working from a clone of the remote cannot " +
+        "see it to approve it until it reaches \`chant/lifecycle\` there.",
+    );
+  }
   lines.push("");
   return lines.join("\n");
 }

package/src/op/gate.test.ts

@@ -16,7 +16,7 @@ import { writeFileSync } from "node:fs";
 import { mkdir, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { evaluateGate, gitGateLedgerPort } from "./gate";
+import { evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "./gate";
 import { appendGateResolution, readGateLedger } from "../lifecycle/gate-ledger";
 import {
   requireLifecycleLedger,
@@ -500,5 +500,115 @@ describe("op/gate — a CI checkout that never fetched the ledger (#2303)", () =
     });
     expect(check.satisfied).toBe(false);
     await expect(requireLifecycleLedger({ cwd: dir })).resolves.toBeUndefined();
+    // #2310: no remote to have failed against, but still worth saying —
+    // nothing this run just recorded left the checkout.
+    if (check.satisfied) throw new Error("unreachable");
+    expect(check.recorded).toBe(true);
+    expect(check.pushed).toBe(false);
+    expect(check.pushWarning).toMatch(/no remote/i);
+  });
+});
+
+/**
+ * #2310 — `recordGateApproval`'s push (`../cli/handlers/operator.ts`) was
+ * already reported by #2309's review; `evaluateGate`'s own `appendPending`
+ * push, right below it in the same file, still swallowed the rejection into
+ * `undefined` and let a gated run print as if the pending fact had reached
+ * everyone. It had not: an operator working from a clone of the remote
+ * cannot see a pending fact that never got there, and the run gave no hint
+ * that this was why their `chant approve` found nothing to resolve.
+ *
+ * Before this fix, `gitGateLedgerPort({ cwd }).appendPending(...)`'s
+ * resolved value was the bare `PendingGateRecord` — there was no `pushed`
+ * field to assert on at all, so the rejection above was genuinely invisible
+ * to any caller. That is the "red" state: this suite fails to typecheck
+ * against the old `Promise<PendingGateRecord>` return type, and a rejected
+ * push at `gate.ts:71` produced no failure text anywhere.
+ */
+describe("op/gate — a rejected ledger push is reported, not swallowed (#2310)", () => {
+  test("gitGateLedgerPort's appendPending reports pushed:false and the rejection reason", async () => {
+    const { remote, author } = await clonePair();
+    const other = tmp("other");
+    git(["clone", "-q", remote, other], tmpdir());
+    git(["config", "user.email", "other@chant.dev"], other);
+    git(["config", "user.name", "Other"], other);
+
+    const port = gitGateLedgerPort({ cwd: author });
+
+    // `author` records and pushes the branch's first pending fact — this
+    // both creates `chant/lifecycle` on the remote and pins `author`'s own
+    // remote-tracking ref to the commit it just pushed.
+    const first = await port.appendPending({
+      op: "live-apply",
+      gate: "approve-live-apply",
+      timestamp: "2026-09-09T05:00:00.000Z",
+      expiresAt: "2026-09-10T05:00:00.000Z",
+    });
+    expect(first.pushed).toBe(true);
+    expect(first.pushWarning).toBeUndefined();
+
+    // `other` fetches that commit, appends a second pending fact on top of
+    // it, and pushes — moving the remote on behind `author`'s back. `author`
+    // never re-fetches, so its remote-tracking ref still names the first
+    // commit alone.
+    git(["fetch", "-q", "origin", "chant/lifecycle:chant/lifecycle"], other);
+    const otherPort = gitGateLedgerPort({ cwd: other });
+    const second = await otherPort.appendPending({
+      op: "live-apply",
+      gate: "approve-other-gate",
+      timestamp: "2026-09-09T05:05:00.000Z",
+      expiresAt: "2026-09-10T05:05:00.000Z",
+    });
+    expect(second.pushed).toBe(true);
+
+    // `author` appends its own third fact on the tip it still knows (the
+    // first commit) and pushes against a lease the remote has since moved
+    // past — the same `StaleLifecycleBranchError` `chant approve` could hit
+    // (#2310's issue).
+    const third = await port.appendPending({
+      op: "live-apply",
+      gate: "approve-third-gate",
+      timestamp: "2026-09-09T05:10:00.000Z",
+      expiresAt: "2026-09-10T05:10:00.000Z",
+    });
+    expect(third.pushed).toBe(false);
+    expect(third.pushWarning).toBeTruthy();
+    expect(third.pushWarning).toMatch(/chant\/lifecycle remote branch has moved|stale|rejected|non-fast-forward/i);
+    // The append itself still landed locally — a correct local answer, per
+    // the #2309 author's reasoning; only the report was missing.
+    expect(third.record.gate).toBe("approve-third-gate");
+  });
+
+  test("evaluateGate carries the rejection onto the gate check it returns, recorded but not pushed", async () => {
+    // A minimal port whose read side is inert and whose write side reports
+    // the exact rejection a stale `chant/lifecycle` lease produces — the
+    // shape `evaluateGate` has to propagate regardless of which port
+    // implementation is behind it.
+    const rejectingPort = {
+      async read() {
+        return { resolutions: [], pending: [] };
+      },
+      async appendPending(input: Parameters<GateLedgerPort["appendPending"]>[0]) {
+        return {
+          record: { version: 1 as const, kind: "pending" as const, ...input },
+          pushed: false,
+          pushWarning:
+            "chant/lifecycle remote branch has moved since this run started — another snapshot was pushed concurrently.",
+        };
+      },
+    };
+
+    const check = await evaluateGate(rejectingPort, {
+      op: "live-apply",
+      gate: "approve-live-apply",
+      now: "2026-09-09T05:00:00.000Z",
+    });
+    if (check.satisfied) throw new Error("unreachable — nothing resolved this gate");
+    expect(check.recorded).toBe(true);
+    expect(check.pushed).toBe(false);
+    expect(check.pushWarning).toContain("another snapshot was pushed concurrently");
+    // The pending fact is still the one that was recorded — gating is still
+    // correct, only silent about reaching the remote.
+    expect(check.pending.gate).toBe("approve-live-apply");
   });
 });

package/src/op/gate.ts

@@ -19,6 +19,14 @@
  * pre-authorize a future run's gate that has since been recorded pending; a
  * resolution from last month does not answer the fact this run just wrote.
  *
+ * Since #2300 a gate can also bind a plan. `GateCheckInput.planDigest` is
+ * what this run's Plan phase produced (`../lifecycle/plan-digest.ts`), and a
+ * resolution counts only when it was recorded for that same plan — recency
+ * demoted from the criterion to the tiebreak. Approve, edit the root, re-run,
+ * and the gate refuses by name instead of applying something no approver saw,
+ * which is what INTENTIUS/choudoufu#1026 measured it doing. A gate with no
+ * `planDigest` decides exactly as it did before.
+ *
  * Ledger access goes through {@link GateLedgerPort} rather than straight to
  * git, so a test (and the operator's own in-memory paths) can drive the
  * decision without an orphan branch on disk.
@@ -28,7 +36,7 @@ import {
   appendPendingGate,
   isPendingGateExpired,
   latestPendingGate,
-  latestResolutionSince,
+  latestResolutionForPlan,
   readGateLedger,
   resolveApprovalUrl,
   DEFAULT_GATE_EXPIRY,
@@ -36,21 +44,46 @@ import {
   type PendingGateInput,
   type PendingGateRecord,
 } from "../lifecycle/gate-ledger";
+import { describePlanDigest } from "../lifecycle/plan-digest";
 import { pushLifecycle, requireLifecycleLedger } from "../lifecycle/git";
 import { parseDuration } from "./duration";
 
+/**
+ * What appending a pending fact learned about reaching the remote.
+ *
+ * The append to the local `chant/lifecycle` branch always lands — that half
+ * was fixed by #2309's fetch-before-append. This is the other half: whether
+ * the push that follows it did, and why not when it didn't, in one line a
+ * renderer can show directly (#2310).
+ */
+export interface PendingGatePush {
+  record: PendingGateRecord;
+  /**
+   * True when the push reached the remote. False when there was no remote
+   * configured, or the push was rejected — `pushWarning` says which.
+   */
+  pushed: boolean;
+  /** Set when `pushed` is false. */
+  pushWarning?: string;
+}
+
 /** The gate ledger, as the two executors need it: read both kinds of line, append a pending fact. */
 export interface GateLedgerPort {
   read(op: string): Promise<{ resolutions: GateResolutionRecord[]; pending: PendingGateRecord[] }>;
-  appendPending(input: PendingGateInput): Promise<PendingGateRecord>;
+  appendPending(input: PendingGateInput): Promise<PendingGatePush>;
 }
 
 /**
- * The real port: the `chant/lifecycle` orphan branch. Pushes best-effort after
- * appending, the same two-step-collapsed-into-one shape `chant approve` uses
- * (`../cli/handlers/operator.ts` calls `pushLifecycle().catch(...)` right after
- * its append) — a pending fact that only ever reaches the local branch is still
- * a correct local answer, so a missing remote never fails the run.
+ * The real port: the `chant/lifecycle` orphan branch.
+ *
+ * Appending is always local-first and always lands (#2309's fetch-before-
+ * append). The push that follows is reported rather than swallowed (#2310):
+ * a pending fact that never reaches the remote is still a correct local
+ * answer — the run is right to gate, and does — but an operator elsewhere
+ * cannot approve a gate whose pending record they cannot see, so the caller
+ * gets `pushed: false` and a reason instead of silence. Mirrors the shape
+ * `chant approve` reports through (`../cli/handlers/operator.ts`'s
+ * `reportedPush`, #2309 review).
  */
 export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
   return {
@@ -68,8 +101,23 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
     },
     async appendPending(input) {
       const { record } = await appendPendingGate(input, opts);
-      await pushLifecycle(opts).catch(() => undefined);
-      return record;
+      try {
+        const pushed = await pushLifecycle(opts);
+        return pushed
+          ? { record, pushed }
+          : {
+              record,
+              pushed,
+              pushWarning:
+                "no remote is configured for chant/lifecycle — the pending fact was recorded locally only",
+            };
+      } catch (err) {
+        return {
+          record,
+          pushed: false,
+          pushWarning: err instanceof Error ? err.message : String(err),
+        };
+      }
     },
   };
 }
@@ -90,7 +138,8 @@ export function memoryGateLedgerPort(
       const record: PendingGateRecord = { version: 1, kind: "pending", ...input };
       pending.push(record);
       appended.push(record);
-      return record;
+      // No remote in an in-memory ledger — there is nothing to fail to reach.
+      return { record, pushed: true };
     },
   };
 }
@@ -106,14 +155,82 @@ export interface GateCheckInput {
   timeout?: string;
   /** Identifies the run that reached the gate, when the caller has one. */
   runId?: string;
+  /**
+   * The plan this run reached the gate with (#2300) — `computePlanDigest`'s
+   * output (`../lifecycle/plan-digest.ts`), from the Plan phase that ran a
+   * moment ago.
+   *
+   * Supplying it makes the gate plan-bound: only a resolution recorded for
+   * this exact digest satisfies it, and one recorded for a different plan (or
+   * for no plan at all) is reported as a {@link GateDigestMismatch} instead.
+   * Omitting it keeps the pre-#2300 rule, where the newest resolution since
+   * the standing pending fact satisfies the gate whatever has changed since.
+   */
+  planDigest?: string;
   /** ISO-8601 "now" — supplied by the caller, so the decision is deterministic under test. */
   now?: string;
 }
 
+/**
+ * A standing resolution that answers this gate but not this plan (#2300) —
+ * what a refusal names.
+ */
+export interface GateDigestMismatch {
+  /** The plan that was approved. `undefined` for a resolution written before #2300, which recorded no plan at all. */
+  approved?: string;
+  /** The plan this run's Plan phase produced. */
+  planned: string;
+  /** Who recorded the approval that does not apply here. */
+  resolvedBy: string;
+  /** When they recorded it. */
+  timestamp: string;
+}
+
+/**
+ * The refusal line for a {@link GateDigestMismatch}: which plan was approved,
+ * which was planned, and what closes the gap. One function so the executor's
+ * step record, the human render and the CI summary say the same thing.
+ *
+ * The two cases get different prose because they are different facts. A
+ * resolution for another plan means something changed between the approval
+ * and this run. A resolution with no plan on it means nothing is known to
+ * have changed — the record simply never said what it approved, which is
+ * every record written before #2300.
+ */
+export function describeGateMismatch(op: string, gate: string, mismatch: GateDigestMismatch): string {
+  const why =
+    mismatch.approved === undefined
+      ? "That resolution predates plan-bound gates (#2300) and records no plan at all, so it cannot " +
+        "answer for this one. Approving again binds it:"
+      : "The configuration or the live system changed between that approval and this plan, so it needs " +
+        "a fresh one:";
+  return (
+    `Gate "${gate}" is approved, but not for this plan. ` +
+    `approved: ${describePlanDigest(mismatch.approved)} (by ${mismatch.resolvedBy} at ${mismatch.timestamp}); ` +
+    `planned: ${mismatch.planned}. ` +
+    `${why} ${approveCommand(op, gate)}`
+  );
+}
+
 /** Either the gate is answered, or it is a standing fact. */
 export type GateCheck =
   | { satisfied: true; resolution: GateResolutionRecord }
-  | { satisfied: false; pending: PendingGateRecord; recorded: boolean };
+  | {
+      satisfied: false;
+      pending: PendingGateRecord;
+      recorded: boolean;
+      /**
+       * Whether this run's own append reached the remote — set only when
+       * `recorded` is true. A gate left standing from an earlier run pushed
+       * (or didn't) on that run; this one wrote nothing, so it has nothing
+       * new to report (#2310).
+       */
+      pushed?: boolean;
+      /** Set when `pushed` is false. */
+      pushWarning?: string;
+      /** Present when a resolution stands for this gate but for another plan (#2300). */
+      mismatch?: GateDigestMismatch;
+    };
 
 /** The beginning of time — the anchor for a gate that has never been recorded pending, so any resolution for it counts. */
 const EPOCH = new Date(0).toISOString();
@@ -122,28 +239,61 @@ const EPOCH = new Date(0).toISOString();
  * Decide a gate against the ledger, recording the pending fact when it isn't
  * answered.
  *
- * - A resolution newer than the newest pending fact satisfies the gate.
- * - Otherwise, a pending fact that hasn't expired stands as it is: the run
- *   ends `gated` and the ledger is left alone, so an operator ticking every
- *   minute against an unapproved gate does not append a line a minute.
- * - Otherwise (no pending fact, or the newest one has expired) a fresh pending
- *   fact is appended and the run ends `gated`. `recorded` says which of the
- *   two happened, so a renderer can tell "just recorded" from "still standing".
+ * - A resolution recorded for this run's own plan, newer than the newest
+ *   pending fact, satisfies the gate. On a gate that binds no plan
+ *   (`input.planDigest` absent) the plan half of that drops out and the rule
+ *   is the pre-#2300 one: any resolution newer than the pending fact.
+ * - A resolution that stands for the gate but for a different plan does not
+ *   satisfy it (#2300). The run is gated, `mismatch` names both plans, and a
+ *   fresh pending fact is recorded for the plan that actually ran — so
+ *   `chant approve` has something current to approve and the loop closes in
+ *   one more command rather than needing the digest typed out.
+ * - Otherwise, a pending fact that hasn't expired *and was recorded for this
+ *   same plan* stands as it is: the run ends `gated` and the ledger is left
+ *   alone, so an operator ticking every minute against an unapproved gate
+ *   does not append a line a minute. A pending fact for a different plan is
+ *   stale in the way that matters and is replaced.
+ * - Otherwise (no pending fact, or the newest one has expired, or it is for
+ *   another plan) a fresh pending fact is appended and the run ends `gated`.
+ *   `recorded` says which of the two happened, so a renderer can tell "just
+ *   recorded" from "still standing".
  */
 export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput): Promise<GateCheck> {
   const now = input.now ?? new Date().toISOString();
   const { resolutions, pending } = await port.read(input.op);
 
   const standing = latestPendingGate(pending, input.gate);
-  const resolution = latestResolutionSince(resolutions, input.gate, standing?.timestamp ?? EPOCH);
+  const { resolution, mismatched } = latestResolutionForPlan(
+    resolutions,
+    input.gate,
+    standing?.timestamp ?? EPOCH,
+    input.planDigest,
+  );
   if (resolution) return { satisfied: true, resolution };
 
-  if (standing && !isPendingGateExpired(standing, now)) {
-    return { satisfied: false, pending: standing, recorded: false };
+  // `input.planDigest` is defined whenever `mismatched` is — `latestResolutionForPlan`
+  // returns a mismatch only on the plan-bound path.
+  const mismatch: GateDigestMismatch | undefined = mismatched
+    ? {
+        ...(mismatched.planDigest !== undefined ? { approved: mismatched.planDigest } : {}),
+        planned: input.planDigest!,
+        resolvedBy: mismatched.resolvedBy,
+        timestamp: mismatched.timestamp,
+      }
+    : undefined;
+  const asMismatch = mismatch ? { mismatch } : {};
+
+  // A standing fact only stands for the plan it was recorded against. When
+  // the plan has moved, re-recording is what gives `chant approve` (which
+  // defaults to the newest pending fact's digest) the current plan to
+  // approve; leaving the old fact standing would make the common path
+  // approve a plan that is no longer the one being run.
+  if (standing && !isPendingGateExpired(standing, now) && standing.planDigest === input.planDigest) {
+    return { satisfied: false, pending: standing, recorded: false, ...asMismatch };
   }
 
   const url = resolveApprovalUrl();
-  const record = await port.appendPending({
+  const { record, pushed, pushWarning } = await port.appendPending({
     op: input.op,
     gate: input.gate,
     timestamp: now,
@@ -153,8 +303,16 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
     ...(input.description ? { description: input.description } : {}),
     ...(input.runId ? { runId: input.runId } : {}),
     ...(url ? { url } : {}),
+    ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
   });
-  return { satisfied: false, pending: record, recorded: true };
+  return {
+    satisfied: false,
+    pending: record,
+    recorded: true,
+    pushed,
+    ...(pushWarning ? { pushWarning } : {}),
+    ...asMismatch,
+  };
 }
 
 /** The line every renderer prints to say how a pending gate is cleared. */

package/src/op/index.ts

@@ -50,8 +50,11 @@ export type { ActivityProfile, ActivityProfileName } from "./activity-profiles";
 export { NonRetryableActivityError, nonRetryableFailure } from "./activity-failure";
 export { runOpLocally, parseDuration, OpRunFailure } from "./local-executor";
 export type { StepRecord, OpRunResult, RunOpOptions } from "./local-executor";
-export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand } from "./gate";
-export type { GateLedgerPort, GateCheck, GateCheckInput } from "./gate";
+export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand, describeGateMismatch } from "./gate";
+export type { GateLedgerPort, GateCheck, GateCheckInput, PendingGatePush, GateDigestMismatch } from "./gate";
+export {
+  computePlanDigest, isPlanDigest, describePlanDigest, PLAN_DIGEST_ALGORITHM,
+} from "../lifecycle/plan-digest";
 export { gateName, usesDeprecatedGateKey, DEPRECATED_GATE_KEY_WARNING } from "./gate-name";
 export type { GateNamed } from "./gate-name";
 export { createLocalOpRuntime } from "./runtimes/local";