@intentius/chant 0.49.0 → 0.50.0

package/src/lifecycle/gate-ledger.ts

@@ -0,0 +1,140 @@
+/**
+ * Gate resolution ledger (#1485, epic #1487) — the durable counterpart to a
+ * converge tick's gate-as-fact outcome (`./converge-ledger.ts`'s
+ * `ConvergeRuleOutcome.action === "gated"`). Same append-only, content-
+ * addressed shape as the converge/release ledgers, reusing
+ * `writeBlobToPath`/`readBlobFromPath` (./git.ts) directly — one line per
+ * resolution at `_gates/<op>.jsonl` on the `chant/lifecycle` orphan branch.
+ *
+ * Keyed by op name rather than environment (`_gates`, not `<env>/gates...`)
+ * because a gate belongs to the *dispatched* op — the thing a converge
+ * rule's `run()` action names — and that op's own env, if it declares one at
+ * all, isn't always the calling `ConvergeOp`'s env. `writeBlobToPath`'s own
+ * doc already establishes this generic-namespace pattern
+ * (`./build-ledger-store.ts`'s `_builds`); this is the same move for a
+ * second non-env top-level directory.
+ *
+ * `chant approve <op> <gate>` (`../cli/handlers/operator.ts`) is what
+ * appends here — issue #1485's "resolution is an out-of-band act that
+ * writes the counterpart fact". Per the issue's own leaning on open
+ * question 3 ("local trust in v1, signature as an additive follow-up"),
+ * this record is *not* itself an authorization check — anyone who can run
+ * `chant approve` locally can write one, the same trust boundary a local
+ * `git commit` already has. What it changes: `chant operator status` (and
+ * any future gate-aware dispatch retry) can tell a resolved gate from a
+ * still-pending one by finding a resolution newer than the tick that
+ * recorded it. It does **not** (v1) retroactively make a gated op's local
+ * dispatch succeed — the local executor still refuses any op containing a
+ * gate outright (`../op/local-executor.ts`'s `LocalGateUnsupportedError`),
+ * unconditionally, gate resolution or not. Wiring an approved gate back
+ * into the local executor's dispatch path is the GateStep semantic change
+ * issue #1485 itself flags as open question 1 ("suspension → fact... does
+ * it land as its own issue first? Leaning: yes, split it out") — deferred
+ * here for the same reason the issue defers it: it touches both the local
+ * executor and the generated Temporal workflow, and has migration impact on
+ * shipped ops. `chant approve` in v1 is the durable, queryable record of
+ * "this gate is cleared" that a human (or a future auto-resume path) reads;
+ * it is not itself the unblock.
+ */
+import { sortedJsonReplacer } from "../utils";
+import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
+
+const DIR = "_gates";
+const APPEND_RETRY_ATTEMPTS = 5;
+
+/** One immutable gate-resolution record. */
+export interface GateResolutionRecord {
+  /** Schema version, so an incompatible future shape is detected before being misread. */
+  version: 1;
+  /** The dispatched op the gate belongs to. */
+  op: string;
+  /** The gate's signal name (matches `ConvergeRuleOutcome.gateName`). */
+  gate: string;
+  /** Who resolved it — an actor name, the same convention `components release --actor` and `run signal --approver` use. */
+  resolvedBy: string;
+  /** ISO-8601 timestamp, caller-supplied (library code never calls `Date.now()` internally). */
+  timestamp: string;
+  /** Optional free-text context (e.g. a PR URL — "or a merged PR" is the issue's other resolution path; recording its link here keeps both paths visible from one ledger). */
+  note?: string;
+}
+
+export type GateResolutionInput = Omit<GateResolutionRecord, "version">;
+
+function filename(op: string): string {
+  return `${op}.jsonl`;
+}
+
+/** Append one immutable gate-resolution record. Does not push to the remote — call `pushLifecycle` (./git.ts) afterward, same two-step shape every other ledger write here uses. Retries on `RefCASConflictError` the same way `appendConvergeRecord` does (./converge-ledger.ts) — a concurrent writer to a different op's/env's file on the same orphan branch is the ordinary case, not an edge case. The baseline read must be `readPathSha` + `readBlobBySha` rather than `readBlobFromPath`, so the exact sha `existing` came from can be passed as `expectPriorPathSha` — see `writeBlobToPath` (./git.ts) for the race that closes. */
+export async function appendGateResolution(
+  input: GateResolutionInput,
+  opts?: { cwd?: string },
+): Promise<{ commit: string; record: GateResolutionRecord }> {
+  const record: GateResolutionRecord = { version: 1, ...input };
+  const json = JSON.stringify(record, sortedJsonReplacer);
+
+  let lastErr: unknown;
+  for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS; attempt++) {
+    try {
+      const priorSha = await readPathSha(DIR, filename(record.op), opts);
+      const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
+      const content = existing ? `${existing.replace(/\n$/, "")}\n${json}` : json;
+      const commit = await writeBlobToPath(DIR, filename(record.op), content, "Gate resolution record", {
+        ...opts,
+        expectPriorPathSha: priorSha,
+      });
+      return { commit, record };
+    } catch (err) {
+      if (!(err instanceof RefCASConflictError)) throw err;
+      lastErr = err;
+    }
+  }
+  throw lastErr;
+}
+
+/** Read every gate-resolution record for `op`, oldest first. Malformed lines are skipped, not thrown on, the same graceful-degradation stance `readConvergeLedger` takes. Returns `[]` (never throws) when `op` has no resolutions recorded yet. */
+export async function readGateResolutions(
+  op: string,
+  opts?: { cwd?: string },
+): Promise<{ records: GateResolutionRecord[]; malformed: number }> {
+  const content = await readBlobFromPath(DIR, filename(op), opts);
+  if (!content) return { records: [], malformed: 0 };
+
+  const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
+  const records: GateResolutionRecord[] = [];
+  let malformed = 0;
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line) as Partial<GateResolutionRecord>;
+      if (
+        parsed.version !== 1 ||
+        typeof parsed.op !== "string" ||
+        typeof parsed.gate !== "string" ||
+        typeof parsed.resolvedBy !== "string" ||
+        typeof parsed.timestamp !== "string"
+      ) {
+        malformed++;
+        continue;
+      }
+      records.push(parsed as GateResolutionRecord);
+    } catch {
+      malformed++;
+    }
+  }
+  return { records, malformed };
+}
+
+/** The most recent resolution for `gate` recorded after `sinceIso` (a gated tick's own timestamp) — what `chant operator status` uses to tell a resolved gate from a still-pending one. `undefined` when no such resolution exists. */
+export function latestResolutionSince(
+  records: GateResolutionRecord[],
+  gate: string,
+  sinceIso: string,
+): GateResolutionRecord | undefined {
+  const since = new Date(sinceIso).getTime();
+  let latest: GateResolutionRecord | undefined;
+  for (const r of records) {
+    if (r.gate !== gate) continue;
+    if (new Date(r.timestamp).getTime() < since) continue;
+    if (!latest || new Date(r.timestamp).getTime() >= new Date(latest.timestamp).getTime()) latest = r;
+  }
+  return latest;
+}

package/src/lifecycle/git.test.ts

@@ -19,6 +19,16 @@ import {
   writeBlobToPath,
   readBlobFromPath,
   listFilesInDir,
+  readRefSha,
+  updateRefCAS,
+  deleteRefCAS,
+  writeBlob,
+  readBlobBySha,
+  pushRef,
+  fetchRef,
+  fetchRefInto,
+  RefCASConflictError,
+  StaleLockError,
 } from "./git";
 
 function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
@@ -157,6 +167,181 @@ describe("lifecycle/git", () => {
     });
   });
 
+  // ── Concurrent writers (#1959 finding 1) ────────────────────────────────
+  //
+  // writeBlobToPath's own CAS-guarded ref update (#1485) closed the silent
+  // clobber two concurrent local writers used to hit, but replaced it with
+  // an outright throw on ANY conflict — breaking every pre-existing caller
+  // that never learned to retry the moment a live `chant operator` (or any
+  // other concurrent writer) touched the orphan branch in between. These
+  // tests pin the fix: a conflict caused by a DIFFERENT path is absorbed
+  // internally (every caller — even ones with no retry logic of their own —
+  // is safe); a conflict on the SAME path a read-modify-write caller is
+  // writing is NOT blindly retried (that would silently drop data), so it
+  // still surfaces for a content-aware caller's own retry to handle.
+  describe("writeBlobToPath — concurrent writers on the same branch tip (#1959 finding 1)", () => {
+    test("two interleaved writers to DIFFERENT paths both survive with no caller-level retry needed", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        // Seed the branch so both writers race against a real, non-null parent tip.
+        await writeBlobToPath("_seed", "seed.json", "{}", "seed", { cwd: dir });
+
+        // Two "callers" that — like writeObservationBaseline/writeSnapshot/
+        // persistBuildManifest — pass a self-contained `content`, computed
+        // before either write starts, and have NO retry loop of their own.
+        const [shaA, shaB] = await Promise.all([
+          writeBlobToPath("prod", "baseline.json", '{"owner":"A"}', "A's write", { cwd: dir }),
+          writeBlobToPath("staging", "baseline.json", '{"owner":"B"}', "B's write", { cwd: dir }),
+        ]);
+        expect(shaA).toMatch(/^[0-9a-f]{40}$/);
+        expect(shaB).toMatch(/^[0-9a-f]{40}$/);
+
+        // Both landed — neither writer's tree update was lost to the other's race.
+        expect(await readBlobFromPath("prod", "baseline.json", { cwd: dir })).toBe('{"owner":"A"}');
+        expect(await readBlobFromPath("staging", "baseline.json", { cwd: dir })).toBe('{"owner":"B"}');
+      });
+    });
+
+    test("a caller with no retry loop still throws RefCASConflictError (not a silent clobber) when TWO writers race the exact same path", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await writeBlobToPath("prod", "solo.json", '{"v":0}', "seed", { cwd: dir });
+
+        // Both writers read the SAME starting content and race to replace it —
+        // exactly the scenario a bare (non-retrying) caller cannot safely
+        // resolve on its own, since neither knows about the other's write.
+        const results = await Promise.allSettled([
+          writeBlobToPath("prod", "solo.json", '{"v":"A"}', "A", { cwd: dir }),
+          writeBlobToPath("prod", "solo.json", '{"v":"B"}', "B", { cwd: dir }),
+        ]);
+
+        const fulfilled = results.filter((r) => r.status === "fulfilled");
+        const rejected = results.filter((r) => r.status === "rejected");
+        // At least one must land; if both raced hard enough that one lost,
+        // it must fail loudly as a RefCASConflictError, never silently.
+        expect(fulfilled.length).toBeGreaterThanOrEqual(1);
+        for (const r of rejected) {
+          expect((r as PromiseRejectedResult).reason).toBeInstanceOf(RefCASConflictError);
+        }
+      });
+    });
+
+    test("appendReleaseRecordLine: two interleaved writers appending to the SAME env's ledger both survive (#1959 finding 1)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const recordA = JSON.stringify({ version: 1, component: "svc-a", digest: "sha256:a" });
+        const recordB = JSON.stringify({ version: 1, component: "svc-b", digest: "sha256:b" });
+
+        await Promise.all([
+          appendReleaseRecordLine("prod", recordA, { cwd: dir }),
+          appendReleaseRecordLine("prod", recordB, { cwd: dir }),
+        ]);
+
+        const lines = await readReleaseLedgerLines("prod", { cwd: dir });
+        expect(lines).toHaveLength(2);
+        expect(lines).toContain(recordA);
+        expect(lines).toContain(recordB);
+      });
+    });
+
+    // Needs more writers than a single retry cycle serializes. A two-writer
+    // race is absorbed by `expectPriorPathSha` alone (the test above); it
+    // takes a third to expose a commit landing between the tree read and a
+    // re-resolved branch tip, where the CAS matches but the committed tree
+    // is stale.
+    test("appendReleaseRecordLine: five interleaved writers appending to the SAME env's ledger all survive (#1973)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const records = Array.from({ length: 5 }, (_, i) =>
+          JSON.stringify({ version: 1, component: `svc-${i}`, digest: `sha256:${i}` }),
+        );
+
+        await Promise.all(records.map((r) => appendReleaseRecordLine("prod", r, { cwd: dir })));
+
+        const lines = await readReleaseLedgerLines("prod", { cwd: dir });
+        expect(lines).toHaveLength(5);
+        for (const r of records) expect(lines).toContain(r);
+      });
+    });
+  });
+
+  // ── Backslash-escape content round-trips byte-identical (#1936) ────────────
+  //
+  // writeBlobToPath used to shell out to `sh -c "echo '<content>' | git
+  // hash-object -w --stdin"`. sh's `echo` reinterprets backslash-escape
+  // sequences (`\n`, `\t`, `\\`, ...) in single-quoted content, so any content
+  // embedding a literal two-character `\n` (as opposed to an actual newline
+  // byte) — e.g. a serialized `kubectl.kubernetes.io/last-applied-configuration`
+  // annotation, which is itself JSON whose string values are JSON-escaped —
+  // got silently corrupted in the stored blob. Content is now written
+  // directly to spawn's stdin, with no shell in the loop.
+  describe("writeBlobToPath preserves literal backslash-escape sequences (#1936)", () => {
+    test("literal \\n, \\t, \\\\ two-character sequences survive the write/read round trip", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const content = String.raw`before\nmiddle\ttab\\backslash\nafter`;
+        await writeBlobToPath("prod", "raw.txt", content, "raw content", { cwd: dir });
+        const out = await readBlobFromPath("prod", "raw.txt", { cwd: dir });
+        expect(out).toBe(content);
+      });
+    });
+
+    test("single quotes combined with backslash sequences survive the round trip", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const content = String.raw`it's a \path\to\thing with 'nested' quotes and \n \t escapes`;
+        await writeBlobToPath("prod", "mixed.txt", content, "mixed content", { cwd: dir });
+        const out = await readBlobFromPath("prod", "mixed.txt", { cwd: dir });
+        expect(out).toBe(content);
+      });
+    });
+
+    test("a realistic last-applied-configuration-style JSON payload survives byte-identical", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        // The annotation value is itself JSON-serialized, so a multi-line
+        // shell script embedded in the manifest shows up as literal `\n`
+        // and `\t` two-character sequences in the annotation string — the
+        // exact shape that `sh`'s `echo` used to mangle.
+        const innerManifest = {
+          apiVersion: "v1",
+          kind: "ConfigMap",
+          metadata: { name: "test-cm", namespace: "default" },
+          data: { "init.sh": "#!/bin/sh\necho 'hello world'\ncd /tmp\n\techo done" },
+        };
+        const manifest = {
+          apiVersion: "v1",
+          kind: "ConfigMap",
+          metadata: {
+            name: "test-cm",
+            namespace: "default",
+            annotations: {
+              "kubectl.kubernetes.io/last-applied-configuration": JSON.stringify(innerManifest),
+            },
+          },
+        };
+        const content = JSON.stringify(manifest);
+        // Sanity-check the fixture actually contains literal backslash-n /
+        // backslash-t sequences (the corruption trigger), not real newlines.
+        expect(content).toContain("\\n");
+        expect(content).toContain("\\t");
+
+        const sha = await writeBlobToPath("prod", "annotation.json", content, "annotated manifest", { cwd: dir });
+        expect(sha).toMatch(/^[0-9a-f]{40}$/);
+
+        const out = await readBlobFromPath("prod", "annotation.json", { cwd: dir });
+        expect(out).toBe(content);
+        expect(JSON.parse(out!)).toEqual(manifest);
+
+        // Cross-check via git plumbing directly (not just the readBlobFromPath
+        // helper), to rule out corruption in the stored blob itself.
+        const catFile = git(["cat-file", "-p", `chant/lifecycle:prod/annotation.json`], dir);
+        expect(catFile.exitCode).toBe(0);
+        expect(catFile.stdout).toBe(content);
+      });
+    });
+  });
+
   test("listSnapshots returns commit history of the orphan branch", async () => {
     await withTestDir(async (dir) => {
       await initRepo(dir);
@@ -327,4 +512,249 @@ describe("lifecycle/git", () => {
       });
     });
   });
+
+  // ── Generic ref CAS (#1485) ────────────────────────────────────────────────
+
+  describe("readRefSha / updateRefCAS / deleteRefCAS / writeBlob / readBlobBySha", () => {
+    const REF = "refs/chant/lease/test-op";
+
+    test("readRefSha returns null for a ref that doesn't exist", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        expect(await readRefSha(REF, { cwd: dir })).toBeNull();
+      });
+    });
+
+    test("writeBlob + updateRefCAS(old=null) creates a ref pointing at a bare blob (no tree, no commit)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const blobSha = await writeBlob('{"holder":"a"}', { cwd: dir });
+        await updateRefCAS(REF, blobSha, null, { cwd: dir });
+
+        expect(await readRefSha(REF, { cwd: dir })).toBe(blobSha);
+        expect(await readBlobBySha(blobSha, { cwd: dir })).toBe('{"holder":"a"}');
+      });
+    });
+
+    test("updateRefCAS(old=null) fails if the ref already exists — RefCASConflictError, not a silent overwrite", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const first = await writeBlob('{"holder":"a"}', { cwd: dir });
+        await updateRefCAS(REF, first, null, { cwd: dir });
+
+        const second = await writeBlob('{"holder":"b"}', { cwd: dir });
+        await expect(updateRefCAS(REF, second, null, { cwd: dir })).rejects.toBeInstanceOf(RefCASConflictError);
+        // The first writer's value is untouched.
+        expect(await readRefSha(REF, { cwd: dir })).toBe(first);
+      });
+    });
+
+    test("updateRefCAS succeeds when oldValue matches the ref's current value (a correct renewal)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const first = await writeBlob('{"holder":"a","expiresAt":"t1"}', { cwd: dir });
+        await updateRefCAS(REF, first, null, { cwd: dir });
+
+        const renewed = await writeBlob('{"holder":"a","expiresAt":"t2"}', { cwd: dir });
+        await updateRefCAS(REF, renewed, first, { cwd: dir });
+
+        expect(await readRefSha(REF, { cwd: dir })).toBe(renewed);
+      });
+    });
+
+    test("updateRefCAS fails when oldValue is stale — the exact race writeBlobToPath's own final ref update now guards against", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const first = await writeBlob('{"holder":"a"}', { cwd: dir });
+        await updateRefCAS(REF, first, null, { cwd: dir });
+
+        // Simulate a second writer who moved the ref concurrently.
+        const interloper = await writeBlob('{"holder":"b"}', { cwd: dir });
+        await updateRefCAS(REF, interloper, first, { cwd: dir });
+
+        // The first writer, still holding its stale `first` as `oldValue`,
+        // tries to write again — must fail loudly, not clobber `interloper`.
+        const staleWrite = await writeBlob('{"holder":"a","stale":true}', { cwd: dir });
+        await expect(updateRefCAS(REF, staleWrite, first, { cwd: dir })).rejects.toBeInstanceOf(RefCASConflictError);
+        expect(await readRefSha(REF, { cwd: dir })).toBe(interloper);
+      });
+    });
+
+    test("deleteRefCAS removes the ref only when oldValue matches; a mismatch is a conflict, not a silent no-op", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const sha = await writeBlob('{"holder":"a"}', { cwd: dir });
+        await updateRefCAS(REF, sha, null, { cwd: dir });
+
+        const wrongSha = await writeBlob("garbage", { cwd: dir });
+        await expect(deleteRefCAS(REF, wrongSha, { cwd: dir })).rejects.toBeInstanceOf(RefCASConflictError);
+        expect(await readRefSha(REF, { cwd: dir })).toBe(sha); // untouched
+
+        await deleteRefCAS(REF, sha, { cwd: dir });
+        expect(await readRefSha(REF, { cwd: dir })).toBeNull();
+      });
+    });
+
+    test("readBlobBySha returns null for a sha that was never written", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        expect(await readBlobBySha("0".repeat(40), { cwd: dir })).toBeNull();
+      });
+    });
+  });
+
+  // ── Failure classification (#1959 finding 2) ────────────────────────────
+  //
+  // Before this fix, updateRefCAS/deleteRefCAS turned ANY nonzero git exit
+  // into RefCASConflictError. That's wrong for at least two other real
+  // failure modes git itself distinguishes: a stale `.lock` file (what a
+  // killed process leaves behind — the exact crash this feature must
+  // recover from) and an outright bad ref name. These tests pin the
+  // corrected classification.
+  describe("updateRefCAS / deleteRefCAS — classifying real git failures, not just any nonzero exit (#1959 finding 2)", () => {
+    test("a stale .lock file is reported as StaleLockError, never as RefCASConflictError", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const ref = "refs/chant/lease/stale-lock-op";
+        const blobSha = await writeBlob('{"holder":"a"}', { cwd: dir });
+        await updateRefCAS(ref, blobSha, null, { cwd: dir });
+
+        // Simulate a `chant operator` killed mid-write: git's own
+        // lockfile-then-rename never completed, so the `.lock` file it
+        // created is still sitting there.
+        const { mkdirSync, writeFileSync: write } = await import("node:fs");
+        mkdirSync(join(dir, ".git", "refs", "chant", "lease"), { recursive: true });
+        write(join(dir, ".git", "refs", "chant", "lease", "stale-lock-op.lock"), "");
+
+        const renewed = await writeBlob('{"holder":"a","renewed":true}', { cwd: dir });
+        const err = await updateRefCAS(ref, renewed, blobSha, { cwd: dir }).catch((e) => e);
+        expect(err).toBeInstanceOf(StaleLockError);
+        expect(err).not.toBeInstanceOf(RefCASConflictError);
+        expect((err as StaleLockError).lockPath).toContain("stale-lock-op.lock");
+        expect((err as StaleLockError).message).toContain("stale-lock-op.lock");
+
+        // The ref itself is untouched — the write never happened.
+        expect(await readRefSha(ref, { cwd: dir })).toBe(blobSha);
+      });
+    });
+
+    test("deleteRefCAS also reports a stale .lock file as StaleLockError", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const ref = "refs/chant/lease/stale-lock-delete-op";
+        const blobSha = await writeBlob('{"holder":"a"}', { cwd: dir });
+        await updateRefCAS(ref, blobSha, null, { cwd: dir });
+
+        const { mkdirSync, writeFileSync: write } = await import("node:fs");
+        mkdirSync(join(dir, ".git", "refs", "chant", "lease"), { recursive: true });
+        write(join(dir, ".git", "refs", "chant", "lease", "stale-lock-delete-op.lock"), "");
+
+        const err = await deleteRefCAS(ref, blobSha, { cwd: dir }).catch((e) => e);
+        expect(err).toBeInstanceOf(StaleLockError);
+        expect(err).not.toBeInstanceOf(RefCASConflictError);
+      });
+    });
+
+    test("a genuine value mismatch is still RefCASConflictError (no lock file involved)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const ref = "refs/chant/lease/mismatch-op";
+        const first = await writeBlob('{"holder":"a"}', { cwd: dir });
+        await updateRefCAS(ref, first, null, { cwd: dir });
+        const interloper = await writeBlob('{"holder":"b"}', { cwd: dir });
+        await updateRefCAS(ref, interloper, first, { cwd: dir });
+
+        const staleWrite = await writeBlob('{"holder":"a","stale":true}', { cwd: dir });
+        const err = await updateRefCAS(ref, staleWrite, first, { cwd: dir }).catch((e) => e);
+        expect(err).toBeInstanceOf(RefCASConflictError);
+        expect(err).not.toBeInstanceOf(StaleLockError);
+      });
+    });
+
+    test("a bad ref name is a plain Error, not RefCASConflictError or StaleLockError — the ref's value never actually diverged from oldValue", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const badRef = "refs/chant/lease/bad..name";
+        const blobSha = await writeBlob('{"holder":"a"}', { cwd: dir });
+
+        const err = await updateRefCAS(badRef, blobSha, null, { cwd: dir }).catch((e) => e);
+        expect(err).toBeInstanceOf(Error);
+        expect(err).not.toBeInstanceOf(RefCASConflictError);
+        expect(err).not.toBeInstanceOf(StaleLockError);
+      });
+    });
+  });
+
+  describe("pushRef / fetchRef — a lease ref survives a round trip through a shared remote", () => {
+    test("pushRef pushes a non-branch ref; a second clone sees it via fetchRef", async () => {
+      const { clonePath: cloneA, remotePath, cleanup } = await setupClonePair();
+      const cloneB = join(tmpdir(), `chant-lease-clone-b-${Date.now()}-${Math.random()}`);
+      try {
+        git(["clone", "-q", remotePath, cloneB], tmpdir());
+
+        const ref = "refs/chant/lease/fountain-converge";
+        const blobSha = await writeBlob('{"holder":"a","token":"t1"}', { cwd: cloneA });
+        await updateRefCAS(ref, blobSha, null, { cwd: cloneA });
+        expect(await pushRef(ref, { cwd: cloneA })).toBe(true);
+
+        expect(await fetchRef(ref, { cwd: cloneB })).toBe(true);
+        expect(await readRefSha(ref, { cwd: cloneB })).toBe(blobSha);
+        expect(await readBlobBySha(blobSha, { cwd: cloneB })).toBe('{"holder":"a","token":"t1"}');
+      } finally {
+        await cleanup();
+        const { rm } = await import("node:fs/promises");
+        await rm(cloneB, { recursive: true, force: true });
+      }
+    });
+
+    test("pushRef / fetchRef return false (never throw) when no remote is configured", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const ref = "refs/chant/lease/local-only";
+        const blobSha = await writeBlob('{"holder":"a"}', { cwd: dir });
+        await updateRefCAS(ref, blobSha, null, { cwd: dir });
+        expect(await pushRef(ref, { cwd: dir })).toBe(false);
+        expect(await fetchRef(ref, { cwd: dir })).toBe(false);
+      });
+    });
+
+    test("fetchRefInto lands the remote's value under a DIFFERENT local ref name, leaving the same-named local ref (if any) untouched (#1959 finding 3)", async () => {
+      const { clonePath: cloneA, remotePath, cleanup } = await setupClonePair();
+      const cloneB = join(tmpdir(), `chant-lease-clone-b-${Date.now()}-${Math.random()}`);
+      try {
+        git(["clone", "-q", remotePath, cloneB], tmpdir());
+
+        const ref = "refs/chant/lease/fountain-converge";
+        const remoteBlobSha = await writeBlob('{"holder":"a","token":"t1"}', { cwd: cloneA });
+        await updateRefCAS(ref, remoteBlobSha, null, { cwd: cloneA });
+        expect(await pushRef(ref, { cwd: cloneA })).toBe(true);
+
+        // cloneB already has its OWN local value at `ref` — simulating a
+        // just-acquired, not-yet-pushed local lease. fetchRefInto must not
+        // touch it.
+        const localBlobSha = await writeBlob('{"holder":"b","token":"t2"}', { cwd: cloneB });
+        await updateRefCAS(ref, localBlobSha, null, { cwd: cloneB });
+
+        const trackingRef = "refs/chant/lease-remote/fountain-converge";
+        expect(await fetchRefInto(ref, trackingRef, { cwd: cloneB })).toBe(true);
+
+        // The tracking ref reflects the remote's value...
+        expect(await readRefSha(trackingRef, { cwd: cloneB })).toBe(remoteBlobSha);
+        // ...but cloneB's own local `ref` is completely untouched.
+        expect(await readRefSha(ref, { cwd: cloneB })).toBe(localBlobSha);
+      } finally {
+        await cleanup();
+        const { rm } = await import("node:fs/promises");
+        await rm(cloneB, { recursive: true, force: true });
+      }
+    });
+  });
+
+  test("RefCASConflictError carries the ref and expected value", () => {
+    const err = new RefCASConflictError("refs/chant/lease/x", "abc123", "stale info");
+    expect(err.name).toBe("RefCASConflictError");
+    expect(err.ref).toBe("refs/chant/lease/x");
+    expect(err.expected).toBe("abc123");
+    expect(err.message).toContain("moved concurrently");
+  });
 });