@intentius/chant 0.61.0 → 0.62.0

package/src/cli/handlers/operator.ts

@@ -34,7 +34,7 @@ import {
   latestResolutionSince, latestPendingGate, isPendingGateExpired,
   resolveApprovalUrl, isApprovalUrl,
 } from "../../lifecycle/gate-ledger";
-import { pushLifecycle } from "../../lifecycle/git";
+import { pushLifecycle, requireLifecycleLedger } from "../../lifecycle/git";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import type { CommandContext } from "../registry";
 
@@ -598,6 +598,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 +640,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 +667,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.`,
     ));
@@ -682,6 +733,21 @@ export async function recordGateApproval(
     }));
   }
 
+  // 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 };
+  }
+
   const resolvedBy = opts.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER ?? "unknown";
 
   // #2028: the resolution's link is typed. `--url` wins; otherwise, running
@@ -704,11 +770,15 @@ export async function recordGateApproval(
     ...(opts.note ? { note: opts.note } : {}),
     ...(url ? { url } : {}),
   });
-  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)"),
   ));
   return { ok: true, record };
 }

package/src/lexicon.ts

@@ -465,6 +465,25 @@ export interface ComponentPipelineOptions {
   image?: string;
   /** Top-level CI `variables:` block. */
   variables?: Record<string, string>;
+  /**
+   * The stage every generated Op job runs in, and (on GitLab) the default
+   * base of the generated file's own name (#2293). GitLab-only: a GitHub or
+   * Forgejo Op workflow is one file per Op with no shared stage, so this does
+   * nothing there. Default `"ops"` — every trigger kind (cron, merge-request,
+   * push) a project mixes into one Op pipeline lands under the same stage,
+   * unlike the pre-#2293 constant `"scheduled-ops"`, which named only the
+   * cron-only pipeline the generator used to emit. See `opsFileName` for the
+   * file name, which follows this unless overridden separately.
+   */
+  opsStage?: string;
+  /**
+   * The generated Op pipeline file's name — GitLab only (#2293). Defaults to
+   * `` `${opsStage}.gitlab-ci.yml` `` (`ops.gitlab-ci.yml` with no `opsStage`
+   * override), so setting `opsStage` alone renames both the stage GitLab's UI
+   * groups jobs under and the file a consumer's `include:` line names. Set
+   * this too when the file should land under some other name than its stage.
+   */
+  opsFileName?: string;
 }
 
 /** The synthesized CI pipeline for a component graph (generate mode). */
@@ -638,6 +657,38 @@ export interface ScheduledOpSpec {
    * own gate.
    */
   environment?: OpEnvironment;
+  /**
+   * Variables and secrets for this Op's generated job alone (#2290). Same
+   * shape as {@link ComponentPipelineOptions.variables} — chant draws no
+   * type-level line between a plain value and a credential, both are strings
+   * a generator drops into the job's environment — but scoped to one Op's job
+   * rather than the whole generated file, for the reason `setup` and
+   * `permissions` are per-Op already: what a job may hold is a property of
+   * that job. A `live-check` plan job that makes no cloud call declares none
+   * of this and inherits none of it.
+   *
+   * **The rule where both are set** (#2290): `ComponentPipelineOptions.variables`
+   * (forge-wide) keeps landing on the workflow/file-level `env:`
+   * (github/forgejo) or top-level `variables:` (gitlab) exactly as it always
+   * has — every caller that declares nothing here sees byte-identical output.
+   * This field lands one level down, on the job itself — github/forgejo emit
+   * it as the job's own `env:` mapping, gitlab merges it into the job's own
+   * `variables:` — and a key present in both wins at the job, the same
+   * last-one-wins precedence GitHub Actions and GitLab CI already give
+   * step/job env over workflow env. Declaring a credential here rather than
+   * in the forge-wide options is therefore how a caller keeps it off every
+   * *other* Op's job: nothing about the forge-wide options changes shape,
+   * only which of a project's own Ops asks for the credential at all.
+   *
+   * Supported everywhere a per-Op `env:`/`variables:` block is expressible:
+   * github and forgejo both emit job-level `env:`; gitlab merges these into
+   * the job's own `variables:` block (already used there for the gated
+   * apply's `CHANT_GATE_SUMMARY`, so the merge is native rather than bolted
+   * on). No generator refuses this option — unlike `setup`'s `uses:` shape or
+   * an additive `permissions` scope, every forge chant targets has some
+   * per-job environment mapping to put a value in.
+   */
+  variables?: Record<string, string>;
 }
 
 /**

package/src/lifecycle/git.test.ts

@@ -420,8 +420,18 @@ describe("lifecycle/git", () => {
     }
   });
 
-  test("concurrent write rejected: second push throws StaleLifecycleBranchError", async () => {
-    // Simulate two concurrent operators by setting up two clones of the same remote.
+  /**
+   * Rewritten for #2309's review. This used to assert that operator B's push
+   * was *rejected*: B had no local `chant/lifecycle`, so its write built an
+   * unrelated root commit, and the lease was the only thing standing between
+   * that fork and A's history on the remote.
+   *
+   * A write that has to be caught by a lease is the bug, not the contract.
+   * `writeBlobToPath` now brings the branch in before it creates one, so B
+   * never forks: it appends to A's history and pushes cleanly, and both
+   * snapshots survive. The genuine stale-lease case is the test below.
+   */
+  test("a second writer with no local ledger appends to the first's history rather than forking", async () => {
     const { clonePath: cloneA, remotePath, cleanup } = await setupClonePair();
     const cloneB = join(tmpdir(), `chant-state-clone-b-${Date.now()}-${Math.random()}`);
     try {
@@ -433,9 +443,43 @@ describe("lifecycle/git", () => {
       await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: cloneA });
       expect(await pushLifecycle({ cwd: cloneA })).toBe(true);
 
-      // Operator B writes from the same baseline (chant/lifecycle doesn't exist
-      // on cloneB's remote-tracking yet) and tries to push — should fail
-      // with StaleLifecycleBranchError because A's push moved the remote ref.
+      // Operator B has never seen `chant/lifecycle`.
+      expect(git(["rev-parse", "--verify", "refs/heads/chant/lifecycle"], cloneB).exitCode).not.toBe(0);
+      await writeSnapshot("staging", "gcp", JSON.stringify({ b: 2 }), { cwd: cloneB });
+      expect(await pushLifecycle({ cwd: cloneB })).toBe(true);
+
+      // Neither snapshot was lost.
+      expect(await readSnapshot("prod", "aws", { cwd: cloneB })).toBe(JSON.stringify({ a: 1 }));
+      expect(await readSnapshot("staging", "gcp", { cwd: cloneB })).toBe(JSON.stringify({ b: 2 }));
+    } finally {
+      await cleanup();
+      const { rm } = await import("node:fs/promises");
+      await rm(cloneB, { recursive: true, force: true });
+    }
+  });
+
+  test("concurrent write rejected: second push throws StaleLifecycleBranchError", async () => {
+    const { clonePath: cloneA, remotePath, cleanup } = await setupClonePair();
+    const cloneB = join(tmpdir(), `chant-state-clone-b-${Date.now()}-${Math.random()}`);
+    try {
+      git(["clone", "-q", remotePath, cloneB], tmpdir());
+      git(["config", "user.email", "test@chant.dev"], cloneB);
+      git(["config", "user.name", "Test"], cloneB);
+
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: cloneA });
+      expect(await pushLifecycle({ cwd: cloneA })).toBe(true);
+
+      // B takes a copy of the branch, so it has local history and a
+      // remote-tracking ref pinned to what it saw.
+      git(["fetch", "-q", "origin", "chant/lifecycle:chant/lifecycle"], cloneB);
+
+      // A moves the remote on again, behind B's back.
+      git(["fetch", "-q", "origin", "+refs/heads/chant/lifecycle:refs/remotes/origin/chant/lifecycle"], cloneA);
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 2 }), { cwd: cloneA });
+      expect(await pushLifecycle({ cwd: cloneA })).toBe(true);
+
+      // B appends to the tip it knows and pushes against a lease that no
+      // longer matches the remote.
       await writeSnapshot("staging", "gcp", JSON.stringify({ b: 2 }), { cwd: cloneB });
       await expect(pushLifecycle({ cwd: cloneB })).rejects.toBeInstanceOf(StaleLifecycleBranchError);
     } finally {

package/src/lifecycle/git.ts

@@ -8,6 +8,69 @@ import { getRuntime } from "../runtime-adapter";
 
 const STATE_BRANCH = "chant/lifecycle";
 
+/**
+ * The identity chant's ledger commits fall back to when the checkout has none
+ * of its own (#2301).
+ *
+ * A CI checkout is the ordinary case here, not an exotic one: GitLab CI,
+ * GitHub Actions and Forgejo Actions all clone without `user.email` or
+ * `user.name`, and `git commit-tree` refuses outright rather than inventing
+ * one — `fatal: unable to auto-detect email address`. Every write in this
+ * module goes through `commit-tree`, so before #2301 a gate's pending fact,
+ * a run record, a snapshot and a release record all died the same way the
+ * moment they ran anywhere but a developer's laptop.
+ *
+ * This is a *fallback*, applied per-invocation via `git -c` and field by
+ * field: only the half the checkout cannot supply is filled in. A configured
+ * `user.name` or `user.email` — a developer's, or a CI job that sets one
+ * deliberately — is left exactly as it is and still authors these commits, and
+ * nothing is written to the repository's config either way. Override the
+ * fallback with `CHANT_LIFECYCLE_COMMITTER_NAME` / `_EMAIL` when a project
+ * wants its ledger commits attributed to a bot account it controls.
+ */
+const LEDGER_COMMITTER_NAME = "chant";
+const LEDGER_COMMITTER_EMAIL = "chant@localhost";
+
+/**
+ * `git -c` arguments that give {@link writeBlobToPath}'s `commit-tree` a
+ * committer when — and only when — the checkout cannot supply one itself.
+ * Empty for any checkout that has an identity, which keeps every existing
+ * caller's commits byte-identical to what they were before #2301.
+ */
+async function ledgerCommitIdentityArgs(cwd?: string): Promise<string[]> {
+  const rt = getRuntime();
+  const probe = await rt.spawn(["git", "var", "GIT_COMMITTER_IDENT"], { cwd, env: C_LOCALE_ENV });
+  if (probe.exitCode === 0) return [];
+
+  // Per-field, not all-or-nothing (#2309 review). `git var` fails if *either*
+  // half is missing, so filling in both would overwrite a configured
+  // `user.name` in the checkout that has a name but no email — which is not
+  // what "a configured identity is left exactly as it is" promises.
+  const args: string[] = [];
+  for (const [key, envVar, fallback] of [
+    ["user.name", "CHANT_LIFECYCLE_COMMITTER_NAME", LEDGER_COMMITTER_NAME],
+    ["user.email", "CHANT_LIFECYCLE_COMMITTER_EMAIL", LEDGER_COMMITTER_EMAIL],
+  ] as const) {
+    const configured = await rt.spawn(["git", "config", "--get", key], { cwd, env: C_LOCALE_ENV });
+    if (configured.exitCode === 0 && configured.stdout.trim() !== "") continue;
+    args.push("-c", `${key}=${process.env[envVar]?.trim() || fallback}`);
+  }
+  return args;
+}
+
+/**
+ * Prefix every failure out of the ledger write path with what was being
+ * written and where (#2301 deliverable 2). `git commit-tree failed: <stderr>`
+ * on its own does not say that the thing that failed was chant recording a
+ * fact on its own branch, and the caller that swallows it is one stack frame
+ * away from printing nothing at all.
+ */
+function ledgerWriteError(stage: string, path: string, stderr: string): Error {
+  return new Error(
+    `cannot write ${path} on the ${STATE_BRANCH} branch: ${stage} failed: ${(stderr ?? "").trim()}`,
+  );
+}
+
 /**
  * Write a blob to an arbitrary `<environment>/<filename>` path on the orphan
  * branch, preserving every other env/file entry already on the branch.
@@ -56,13 +119,42 @@ export async function writeBlobToPath(
   // annotation) and no shell-quoting dance around embedded single quotes.
   // Content-addressed and idempotent, so this stays outside the retry loop
   // below — nothing about a CAS conflict on the ref ever invalidates it.
+  //
+  // `path` is resolved first only so every failure below can name it (#2301).
+  const path = `${environment}/${filename}`;
+
   const blobResult = await rt.spawn(["git", "hash-object", "-w", "--stdin"], { cwd, stdin: content });
   if (blobResult.exitCode !== 0) {
-    throw new Error(`git hash-object failed: ${blobResult.stderr}`);
+    throw ledgerWriteError("git hash-object", path, blobResult.stderr);
   }
   const blobSha = blobResult.stdout.trim();
 
-  const path = `${environment}/${filename}`;
+  // Resolved once, outside the retry loop: whether the checkout can name a
+  // committer does not change between attempts (#2301).
+  const identityArgs = await ledgerCommitIdentityArgs(cwd);
+
+  // Creating the ledger branch is a different act from extending it, and only
+  // one of them is safe to do blind (#2309 review). With no local
+  // `chant/lifecycle`, everything below builds a tree from an empty read and
+  // commits it with no parent — a brand-new root commit that *replaces* the
+  // branch rather than appending to it, which `updateRefCAS` cannot catch
+  // because "the ref does not exist" is perfectly true locally.
+  //
+  // Until #2301 this was mostly hidden: `commit-tree` died for want of a
+  // committer before it could happen. Supplying an identity turned that loud
+  // failure into a silent branch fabrication on every writer that reaches
+  // here without a ledger — a run record, a snapshot, a release, a build
+  // manifest — and a fabricated branch is precisely the fork the guard above
+  // exists to refuse. So the guard runs here, at the one seam they all pass
+  // through, rather than at each of their call sites.
+  //
+  // Only when the branch is absent: an extend costs no fetch, and the check
+  // that matters is whether the history this is about to discard exists
+  // somewhere. `requireLifecycleLedger` allows `no-remote` and `absent`, so a
+  // genuinely first write still creates the branch.
+  if ((await getStateBranchTip(cwd)) === null) {
+    await requireLifecycleLedger({ ...(cwd ? { cwd } : {}) });
+  }
 
   // 2-5. Read tree, build the commit, and CAS-update the branch ref — retried
   // on a conflict (#1959 finding 1). `writeBlobToPath` had no retry of its
@@ -127,7 +219,7 @@ export async function writeBlobToPath(
 
     const envTreeResult = await rt.spawn(["git", "mktree"], { cwd, stdin: `${envEntries}\n` });
     if (envTreeResult.exitCode !== 0) {
-      throw new Error(`git mktree (env) failed: ${envTreeResult.stderr}`);
+      throw ledgerWriteError("git mktree (env)", path, envTreeResult.stderr);
     }
     const envTreeSha = envTreeResult.stdout.trim();
 
@@ -150,7 +242,7 @@ export async function writeBlobToPath(
       stdin: `${rootEntries.join("\n")}\n`,
     });
     if (rootTreeResult.exitCode !== 0) {
-      throw new Error(`git mktree (root) failed: ${rootTreeResult.stderr}`);
+      throw ledgerWriteError("git mktree (root)", path, rootTreeResult.stderr);
     }
     const rootTreeSha = rootTreeResult.stdout.trim();
 
@@ -160,11 +252,11 @@ export async function writeBlobToPath(
     const parentRef = tip;
     const parentArgs = parentRef ? ["-p", parentRef] : [];
     const commitResult = await rt.spawn(
-      ["git", "commit-tree", ...parentArgs, "-m", commitMessage, rootTreeSha],
+      ["git", ...identityArgs, "commit-tree", ...parentArgs, "-m", commitMessage, rootTreeSha],
       { cwd },
     );
     if (commitResult.exitCode !== 0) {
-      throw new Error(`git commit-tree failed: ${commitResult.stderr}`);
+      throw ledgerWriteError("git commit-tree", path, commitResult.stderr);
     }
     const commitSha = commitResult.stdout.trim();
 
@@ -534,16 +626,225 @@ export async function pushLifecycle(opts?: { cwd?: string }): Promise<boolean> {
  * Fetch the state branch from remote.
  */
 export async function fetchLifecycle(opts?: { cwd?: string }): Promise<boolean> {
+  return (await fetchLifecycleStatus(opts)).status === "fetched";
+}
+
+/**
+ * Why a fetch of the ledger branch did or did not produce local history
+ * (#2303).
+ *
+ * `fetchLifecycle`'s boolean cannot answer the question the gate actually
+ * needs answered. "No local `chant/lifecycle`" has two causes that a reader
+ * of an empty ledger cannot tell apart, and they call for opposite
+ * behaviour: on a project whose ledger has never been written, an empty
+ * ledger is the truth; in a CI checkout that fetched only the pipeline's own
+ * ref, an empty ledger is history the checkout simply cannot see. Reading the
+ * second as the first is what makes a second pending fact look correct, so
+ * these are separate outcomes:
+ *
+ * - `fetched` — the branch is now in this checkout (or already was, and is
+ *   up to date). Whatever the ledger says is the whole truth.
+ * - `no-remote` — nothing to fetch from. A single-machine project; local is
+ *   authoritative by construction, the same assumption `chant operator`'s
+ *   lease already documents.
+ * - `absent` — the remote answered and has no `chant/lifecycle`. The ledger
+ *   is genuinely empty; this is a project's first gate.
+ * - `diverged` — both sides have the branch and neither contains the other.
+ *   Appending here would drop one side's facts.
+ * - `unreachable` — a remote is configured and did not answer (no network,
+ *   no credentials, a shallow-clone refspec that cannot resolve). Whether
+ *   anything is on the branch is unknown, which is exactly the state that
+ *   must not be read as "nothing has been approved".
+ */
+export type LifecycleFetchStatus =
+  | { status: "fetched" }
+  | { status: "no-remote" }
+  | { status: "absent"; remote: string }
+  | { status: "ahead"; remote: string }
+  | { status: "diverged"; remote: string; stderr: string }
+  | { status: "unreachable"; remote: string; stderr: string };
+
+/**
+ * git's wording when the remote answered and simply does not carry the ref.
+ *
+ * Matched against output forced to `LC_ALL=C` ({@link C_LOCALE_ENV}) — both of
+ * these strings are in git's translation catalogs, so on a distro git built
+ * with NLS and a non-C `LANG` an unpinned locale would fail to match and send
+ * a project's genuine first gate down the `unreachable` path, refusing it.
+ */
+const NO_SUCH_REMOTE_REF_RE = /couldn't find remote ref|no such ref was fetched/i;
+/** git's wording when the refspec would not fast-forward the local branch. Same locale caveat. */
+const NON_FAST_FORWARD_RE = /non-fast-forward|rejected/i;
+
+/**
+ * `git` invocations here are parsed by their output, so they are pinned to the
+ * C locale. `LC_ALL` alone is enough — it outranks `LC_MESSAGES` and `LANG` —
+ * but `LANGUAGE` is GNU gettext's own override and outranks all of them, so it
+ * is cleared too.
+ */
+const C_LOCALE_ENV = { LC_ALL: "C", LANGUAGE: "" };
+
+/**
+ * The remote the ledger lives on.
+ *
+ * `origin` when it exists, rather than whichever name sorts first — a repo
+ * with a `backup` remote alongside `origin` would otherwise fetch the ledger
+ * from `backup`. A non-zero exit is *not* read as "no remote": a git that
+ * failed to answer is not evidence that a project is single-machine, and
+ * treating it as one is what lets an unreadable ledger look empty.
+ */
+async function ledgerRemote(cwd?: string): Promise<{ remote: string } | { failed: true; stderr: string } | null> {
   const rt = getRuntime();
-  const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
-  if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;
+  const result = await rt.spawn(["git", "remote"], { cwd, env: C_LOCALE_ENV });
+  if (result.exitCode !== 0) return { failed: true, stderr: (result.stderr ?? "").trim() };
+  const names = result.stdout.trim().split("\n").map((n) => n.trim()).filter(Boolean);
+  if (names.length === 0) return null;
+  return { remote: names.includes("origin") ? "origin" : names[0] };
+}
+
+/** A scratch ref this module owns, used to resolve the remote tip without touching the ledger branch. */
+const PROBE_REF = "refs/chant/lifecycle-probe";
+
+/**
+ * Fetch `chant/lifecycle` and say what happened, in the terms
+ * {@link LifecycleFetchStatus} defines.
+ *
+ * The refspec is deliberately un-forced (`chant/lifecycle:chant/lifecycle`,
+ * no leading `+`), so a local branch holding facts the remote does not have is
+ * never rewound by a read.
+ *
+ * git reports "non-fast-forward" for two states that could not be more
+ * different, which is why the rejection is not taken at face value (#2309
+ * review): a local branch *ahead* of the remote — the ordinary state right
+ * after an append whose push has not landed yet — and a local branch that has
+ * genuinely *forked*. Resolving the remote tip into a scratch ref and asking
+ * whether it is an ancestor of the local tip separates them. Reading a fork as
+ * the ledger is what destroys approvals; refusing an append that is merely
+ * ahead would break the retry that is supposed to repair a failed push.
+ */
+export async function fetchLifecycleStatus(opts?: { cwd?: string }): Promise<LifecycleFetchStatus> {
+  const rt = getRuntime();
+  const cwd = opts?.cwd;
+  const found = await ledgerRemote(cwd);
+  if (found === null) return { status: "no-remote" };
+  if ("failed" in found) {
+    return { status: "unreachable", remote: "(unknown)", stderr: found.stderr };
+  }
+  const { remote } = found;
 
-  const remote = remoteResult.stdout.trim().split("\n")[0];
   const fetchResult = await rt.spawn(
     ["git", "fetch", remote, `${STATE_BRANCH}:${STATE_BRANCH}`],
-    { cwd: opts?.cwd },
+    { cwd, env: C_LOCALE_ENV },
   );
-  return fetchResult.exitCode === 0;
+  if (fetchResult.exitCode === 0) return { status: "fetched" };
+
+  const stderr = (fetchResult.stderr ?? "").trim();
+  if (NO_SUCH_REMOTE_REF_RE.test(stderr)) return { status: "absent", remote };
+  if (!NON_FAST_FORWARD_RE.test(stderr)) return { status: "unreachable", remote, stderr };
+
+  // Rejected. Resolve the remote tip into our own scratch ref (forced: the ref
+  // is this module's, and nothing reads it but the next two lines) and ask
+  // whether the local branch already contains it.
+  const probe = await rt.spawn(
+    ["git", "fetch", "--force", remote, `${STATE_BRANCH}:${PROBE_REF}`],
+    { cwd, env: C_LOCALE_ENV },
+  );
+  if (probe.exitCode !== 0) {
+    return { status: "unreachable", remote, stderr: (probe.stderr ?? "").trim() || stderr };
+  }
+  const contains = await rt.spawn(
+    ["git", "merge-base", "--is-ancestor", PROBE_REF, `refs/heads/${STATE_BRANCH}`],
+    { cwd, env: C_LOCALE_ENV },
+  );
+  await rt.spawn(["git", "update-ref", "-d", PROBE_REF], { cwd, env: C_LOCALE_ENV });
+  if (contains.exitCode === 0) return { status: "ahead", remote };
+  return { status: "diverged", remote, stderr };
+}
+
+/**
+ * Thrown when the ledger branch cannot be read, rather than being reported as
+ * empty (#2303).
+ */
+export class LifecycleLedgerUnreadableError extends Error {
+  constructor(
+    public readonly reason: "unreachable" | "diverged",
+    public readonly remote: string,
+    public readonly stderr: string,
+    detail: string,
+  ) {
+    super(
+      `the ${STATE_BRANCH} ledger branch ${detail}, so what is on it cannot be read. ` +
+        `Refusing rather than treating an unreadable ledger as an empty one.` +
+        (reason === "diverged"
+          ? `\n  Two histories claim to be the ledger; appending to either one drops the other's facts. ` +
+            `Inspect both before doing anything else:\n` +
+            `    git fetch ${remote} ${STATE_BRANCH}:refs/chant/remote-ledger\n` +
+            `    git log --oneline ${STATE_BRANCH} refs/chant/remote-ledger`
+          : `\n  Fetch it and retry: git fetch ${remote} ${STATE_BRANCH}:${STATE_BRANCH}`) +
+        (stderr ? `\n  git said: ${stderr.split("\n")[0]}` : ""),
+    );
+    this.name = "LifecycleLedgerUnreadableError";
+  }
+}
+
+/**
+ * Bring the ledger branch into this checkout before reading or appending to
+ * it, and refuse when it cannot be (#2303).
+ *
+ * The gate's read is the one that has to be right: `evaluateGate` decides
+ * whether to walk through or to record a *new* pending fact purely from what
+ * the ledger says, so a read that reports history it cannot see as an empty
+ * ledger makes the second run of an already-approved commit record a second
+ * pending fact and gate again. That is what a GitLab CI retry did on
+ * INTENTIUS/choudoufu#1026 — two pending records for one commit, with
+ * different expiries — because a GitLab checkout fetches the pipeline's own
+ * ref at depth 20 and nothing else. `GIT_DEPTH: 0` does not help: GitLab
+ * fetches refspecs, not all branches.
+ *
+ * There was a separate, laxer guard for the read until #2309's review, on the
+ * reasoning that a checkout which already has the branch "has real history to
+ * read". That reasoning is only sound when the local branch *is* the remote's
+ * history, and it let the worst case through: on a fork, the gate read a
+ * ledger missing every remote approval, recorded a fresh pending fact, and
+ * pushed. The push was not protected either — a rejected non-fast-forward
+ * fetch still updates `refs/remotes/<remote>/chant/lifecycle` opportunistically
+ * in a full clone, so `pushLifecycle`'s `--force-with-lease` matched the tip
+ * it had just learned and forced. Verified on git 2.50.1: a remote holding a
+ * pending fact and an approval ended up holding neither.
+ *
+ * So there is one rule now, for readers and writers alike:
+ *
+ * - `diverged` always refuses. A fork is not the ledger, and nothing good
+ *   comes of reading one as if it were.
+ * - `unreachable` refuses only when the checkout has no local history at all,
+ *   which is the case that would otherwise read as an empty ledger. With
+ *   local history and no answer from the remote, the read proceeds and the
+ *   push's lease fails safely on its own — refusing there would strand every
+ *   offline run.
+ * - `fetched`, `no-remote`, `absent` and `ahead` all proceed. `ahead` is the
+ *   ordinary state right after an append whose push has not landed, and is
+ *   exactly what a retry needs to be able to repair.
+ */
+export async function requireLifecycleLedger(opts?: { cwd?: string }): Promise<void> {
+  const hadLocal = (await getStateBranchTip(opts?.cwd)) !== null;
+  const result = await fetchLifecycleStatus(opts);
+
+  if (result.status === "diverged") {
+    throw new LifecycleLedgerUnreadableError(
+      "diverged",
+      result.remote,
+      result.stderr,
+      `has diverged from the copy on "${result.remote}" — neither contains the other`,
+    );
+  }
+  if (result.status === "unreachable" && !hadLocal) {
+    throw new LifecycleLedgerUnreadableError(
+      "unreachable",
+      result.remote,
+      result.stderr,
+      `is not in this checkout and could not be fetched from "${result.remote}"`,
+    );
+  }
 }
 
 // ── Generic ref CAS (#1485) ──────────────────────────────────────────────────