@intentius/chant 0.46.0 → 0.50.0

package/src/lifecycle/lease.test.ts

@@ -0,0 +1,343 @@
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  acquireLease,
+  releaseLease,
+  readLease,
+  stillHoldsLease,
+  currentHolderId,
+  leaseRef,
+  LEASE_REF_PREFIX,
+} from "./lease";
+import { writeBlob, updateRefCAS, readRefSha, pushRef, StaleLockError, RefCASConflictError } from "./git";
+
+function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 };
+}
+
+async function initRepo(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+describe("lifecycle/lease", () => {
+  test("leaseRef namespaces under refs/chant/lease/, distinct from the lifecycle branch", () => {
+    expect(leaseRef("fountain-converge")).toBe(`${LEASE_REF_PREFIX}fountain-converge`);
+    expect(leaseRef("fountain-converge")).not.toMatch(/^refs\/heads\//);
+  });
+
+  test("currentHolderId is stable-shaped (host:pid:random) and unique per call", () => {
+    const a = currentHolderId();
+    const b = currentHolderId();
+    expect(a).toMatch(/^.+:\d+:[0-9a-f]{8}$/);
+    expect(a).not.toBe(b);
+  });
+
+  test("readLease on a never-acquired op returns no record", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const { sha, record } = await readLease("no-such-op", { cwd: dir });
+      expect(sha).toBeNull();
+      expect(record).toBeUndefined();
+    });
+  });
+
+  describe("acquireLease — single-writer fencing (#1485)", () => {
+    test("first acquire succeeds and mints a fresh token", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const result = await acquireLease("fountain-converge", "holder-a", { cwd: dir });
+        expect(result.acquired).toBe(true);
+        expect(result.lease?.holder).toBe("holder-a");
+        expect(result.lease?.token).toMatch(/^[0-9a-f-]{36}$/);
+      });
+    });
+
+    test("a second holder cannot acquire a live, unexpired lease — the CAS loser stops, not queues", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const first = await acquireLease("fountain-converge", "holder-a", { cwd: dir, ttlMs: 60_000 });
+        expect(first.acquired).toBe(true);
+
+        const second = await acquireLease("fountain-converge", "holder-b", { cwd: dir, ttlMs: 60_000 });
+        expect(second.acquired).toBe(false);
+        expect(second.heldBy?.holder).toBe("holder-a");
+        expect(second.heldBy?.token).toBe(first.lease?.token);
+      });
+    });
+
+    test("the same holder renewing keeps its token but pushes out expiresAt", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const t0 = new Date("2026-01-01T00:00:00.000Z");
+        const first = await acquireLease("fountain-converge", "holder-a", { cwd: dir, ttlMs: 60_000, now: () => t0 });
+
+        const t1 = new Date("2026-01-01T00:00:30.000Z");
+        const renewed = await acquireLease("fountain-converge", "holder-a", { cwd: dir, ttlMs: 60_000, now: () => t1 });
+
+        expect(renewed.acquired).toBe(true);
+        expect(renewed.lease?.token).toBe(first.lease?.token);
+        expect(renewed.lease?.acquiredAt).toBe(first.lease?.acquiredAt);
+        expect(new Date(renewed.lease!.expiresAt).getTime()).toBeGreaterThan(new Date(first.lease!.expiresAt).getTime());
+      });
+    });
+
+    test("a new holder can acquire once the previous lease has expired, and mints a new token", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const t0 = new Date("2026-01-01T00:00:00.000Z");
+        const first = await acquireLease("fountain-converge", "holder-a", { cwd: dir, ttlMs: 1_000, now: () => t0 });
+        expect(first.acquired).toBe(true);
+
+        // holder-a crashes and never renews; holder-b tries after the TTL passes.
+        const tExpired = new Date("2026-01-01T00:00:05.000Z");
+        const second = await acquireLease("fountain-converge", "holder-b", { cwd: dir, ttlMs: 1_000, now: () => tExpired });
+
+        expect(second.acquired).toBe(true);
+        expect(second.lease?.holder).toBe("holder-b");
+        expect(second.lease?.token).not.toBe(first.lease?.token);
+      });
+    });
+
+    // ── #1959 finding 2 ──────────────────────────────────────────────────
+    //
+    // Before this fix, `updateRefCAS` turned ANY nonzero git exit —
+    // including a stale `.lock` file left by a killed process — into
+    // RefCASConflictError, and `acquireLease` folded that straight into
+    // "someone else holds it" (`heldBy`). That's wrong: a stale lock isn't
+    // contention, it's wreckage from the exact crash this feature must
+    // recover from, and TTL expiry never fixes it (the ref update itself
+    // can't land while the lock file sits there) — so a project would get
+    // permanently, silently stuck acquiring that op's lease.
+    test("a stale .lock file surfaces as StaleLockError, NOT as \"lease held by someone else\" (#1959 finding 2)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        // Acquire once for real, so the ref exists.
+        const first = await acquireLease("fountain-converge", "holder-a", { cwd: dir, ttlMs: 60_000 });
+        expect(first.acquired).toBe(true);
+
+        // Simulate holder-a's own process getting killed mid-renewal: git's
+        // lockfile-then-rename never completed, so the `.lock` file it
+        // created is still there.
+        mkdirSync(join(dir, ".git", "refs", "chant", "lease"), { recursive: true });
+        writeFileSync(join(dir, ".git", "refs", "chant", "lease", "fountain-converge.lock"), "");
+
+        // The SAME holder trying to renew must actually attempt the write
+        // (it owns the lease, so acquireLease doesn't short-circuit before
+        // touching git) — and hit the lock file. It must not read this as
+        // "held by someone else": it must throw a diagnosable
+        // StaleLockError, distinct from the ordinary
+        // `{ acquired: false, heldBy }` contention outcome.
+        const err = await acquireLease("fountain-converge", "holder-a", { cwd: dir, ttlMs: 60_000 }).catch((e) => e);
+        expect(err).toBeInstanceOf(StaleLockError);
+        expect(err).not.toBeInstanceOf(RefCASConflictError);
+        expect((err as StaleLockError).message).toContain("fountain-converge.lock");
+      });
+    });
+
+    test("a stale .lock file also blocks a FRESH holder once the previous lease has expired — surfaced as StaleLockError, not misread as expiry succeeding or as contention (#1959 finding 2)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const t0 = new Date("2026-01-01T00:00:00.000Z");
+        const first = await acquireLease("fountain-converge", "holder-a", { cwd: dir, ttlMs: 1_000, now: () => t0 });
+        expect(first.acquired).toBe(true);
+
+        mkdirSync(join(dir, ".git", "refs", "chant", "lease"), { recursive: true });
+        writeFileSync(join(dir, ".git", "refs", "chant", "lease", "fountain-converge.lock"), "");
+
+        // holder-a's lease has since expired — a normal crash-recovery
+        // acquire should be able to proceed to a CAS write here (nothing is
+        // "held" any more), but the same leftover lock file still blocks
+        // the write itself.
+        const tExpired = new Date("2026-01-01T00:00:05.000Z");
+        const err = await acquireLease("fountain-converge", "holder-b", { cwd: dir, ttlMs: 1_000, now: () => tExpired }).catch(
+          (e) => e,
+        );
+        expect(err).toBeInstanceOf(StaleLockError);
+        expect(err).not.toBeInstanceOf(RefCASConflictError);
+      });
+    });
+  });
+
+  describe("stillHoldsLease — the fencing check a tick uses before trusting its own work", () => {
+    test("true while the same holder+token is still live", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const acquired = await acquireLease("fountain-converge", "holder-a", { cwd: dir, ttlMs: 60_000 });
+        expect(await stillHoldsLease("fountain-converge", "holder-a", acquired.lease!.token, { cwd: dir })).toBe(true);
+      });
+    });
+
+    test("false once another holder has taken over (stale token refused)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const t0 = new Date("2026-01-01T00:00:00.000Z");
+        const a = await acquireLease("fountain-converge", "holder-a", { cwd: dir, ttlMs: 1_000, now: () => t0 });
+
+        const tExpired = new Date("2026-01-01T00:00:05.000Z");
+        await acquireLease("fountain-converge", "holder-b", { cwd: dir, ttlMs: 1_000, now: () => tExpired });
+
+        // holder-a's tick, still carrying its now-stale token, checks in after
+        // holder-b has already reclaimed the lease.
+        expect(await stillHoldsLease("fountain-converge", "holder-a", a.lease!.token, { cwd: dir })).toBe(false);
+      });
+    });
+
+    test("false for an op with no lease at all", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        expect(await stillHoldsLease("no-such-op", "holder-a", "any-token", { cwd: dir })).toBe(false);
+      });
+    });
+  });
+
+  describe("releaseLease", () => {
+    test("releases when holder+token match, and the lease becomes acquirable again immediately", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const acquired = await acquireLease("fountain-converge", "holder-a", { cwd: dir, ttlMs: 60_000 });
+        expect(await releaseLease("fountain-converge", "holder-a", acquired.lease!.token, { cwd: dir })).toBe(true);
+
+        const { record } = await readLease("fountain-converge", { cwd: dir });
+        expect(record).toBeUndefined();
+
+        const second = await acquireLease("fountain-converge", "holder-b", { cwd: dir, ttlMs: 60_000 });
+        expect(second.acquired).toBe(true);
+      });
+    });
+
+    test("refuses to release a lease held by someone else, or with a stale token — never drops another holder's lease", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const acquired = await acquireLease("fountain-converge", "holder-a", { cwd: dir, ttlMs: 60_000 });
+
+        expect(await releaseLease("fountain-converge", "holder-b", acquired.lease!.token, { cwd: dir })).toBe(false);
+        expect(await releaseLease("fountain-converge", "holder-a", "wrong-token", { cwd: dir })).toBe(false);
+
+        const { record } = await readLease("fountain-converge", { cwd: dir });
+        expect(record?.holder).toBe("holder-a");
+      });
+    });
+
+    test("releasing a non-existent lease is a harmless false, not a throw", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        expect(await releaseLease("no-such-op", "holder-a", "t", { cwd: dir })).toBe(false);
+      });
+    });
+  });
+
+  // ── Cross-machine contention (#1485 acceptance criterion: "two operators, one remote") ──
+
+  describe("two operators, one remote — the lease arbitrates across clones, not just within one", () => {
+    async function setupClonePair(): Promise<{ clonePath: string; remotePath: string; cleanup: () => Promise<void> }> {
+      const remotePath = join(tmpdir(), `chant-lease-remote-${Date.now()}-${Math.random()}`);
+      const clonePath = join(tmpdir(), `chant-lease-clone-${Date.now()}-${Math.random()}`);
+      const { mkdir, rm } = await import("node:fs/promises");
+      await mkdir(remotePath, { recursive: true });
+      git(["init", "-q", "--bare", "-b", "main"], remotePath);
+      git(["clone", "-q", remotePath, clonePath], tmpdir());
+      git(["config", "user.email", "test@chant.dev"], clonePath);
+      git(["config", "user.name", "Test"], clonePath);
+      writeFileSync(join(clonePath, "README.md"), "fixture\n");
+      git(["add", "README.md"], clonePath);
+      git(["commit", "-q", "-m", "init"], clonePath);
+      git(["push", "-q", "origin", "main"], clonePath);
+      return {
+        clonePath,
+        remotePath,
+        cleanup: async () => {
+          await rm(remotePath, { recursive: true, force: true });
+          await rm(clonePath, { recursive: true, force: true });
+        },
+      };
+    }
+
+    test("operator A acquires and pushes; operator B (a second clone) sees it as held and loses the race", 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());
+        git(["config", "user.email", "test@chant.dev"], cloneB);
+        git(["config", "user.name", "Test"], cloneB);
+
+        const a = await acquireLease("fountain-converge", "operator-a", { cwd: cloneA, ttlMs: 60_000 });
+        expect(a.acquired).toBe(true);
+
+        // Operator B, on a different clone of the same remote, tries next —
+        // acquireLease fetches the ref first, so A's push is visible.
+        const b = await acquireLease("fountain-converge", "operator-b", { cwd: cloneB, ttlMs: 60_000 });
+        expect(b.acquired).toBe(false);
+        expect(b.heldBy?.holder).toBe("operator-a");
+      } finally {
+        await cleanup();
+        const { rm } = await import("node:fs/promises");
+        await rm(cloneB, { recursive: true, force: true });
+      }
+    });
+
+    // ── #1959 finding 3 ──────────────────────────────────────────────────
+    //
+    // `readLease` used to fetch the remote lease ref directly into the same
+    // local ref name (`+ref:ref`) before every read — including the read
+    // `chant operator status` does. That force-overwrites the local ref, so
+    // a concurrent `status` call landing in the exact acquire→push window
+    // (the local CAS write has landed, but the push to remote hasn't yet)
+    // would revert the just-acquired local lease back to whatever the
+    // remote still had — silently, in the SAME clone, with no other process
+    // racing at all. `readLease` now fetches into a side tracking ref
+    // instead, so the canonical local ref is never touched by a read.
+    test("a concurrent read in the SAME clone, during the acquire→push window, must not clobber the just-acquired local lease (#1959 finding 3)", async () => {
+      const { clonePath, remotePath, cleanup } = await setupClonePair();
+      try {
+        // An older, now-stale lease already sits on the remote (some earlier holder, long expired).
+        const stale = {
+          op: "fountain-converge",
+          holder: "old-holder",
+          token: "old-token",
+          acquiredAt: "2020-01-01T00:00:00.000Z",
+          expiresAt: "2020-01-01T00:05:00.000Z",
+        };
+        const staleBlobSha = await writeBlob(JSON.stringify(stale), { cwd: clonePath });
+        await updateRefCAS(leaseRef("fountain-converge"), staleBlobSha, null, { cwd: clonePath });
+        expect(await pushRef(leaseRef("fountain-converge"), { cwd: clonePath })).toBe(true);
+
+        // Simulate the local half of a fresh acquire that has landed the
+        // local CAS write but has NOT pushed yet — the exact acquire→push
+        // window this finding is about (acquireLease itself always pushes
+        // right after its own CAS write; this reproduces the in-between
+        // moment deterministically rather than racing real concurrency).
+        const fresh = {
+          op: "fountain-converge",
+          holder: "new-holder",
+          token: "new-token",
+          acquiredAt: new Date().toISOString(),
+          expiresAt: new Date(Date.now() + 60_000).toISOString(),
+        };
+        const freshBlobSha = await writeBlob(JSON.stringify(fresh), { cwd: clonePath });
+        await updateRefCAS(leaseRef("fountain-converge"), freshBlobSha, staleBlobSha, { cwd: clonePath });
+
+        // A concurrent `chant operator status` in the SAME clone reads the lease now.
+        const { record } = await readLease("fountain-converge", { cwd: clonePath });
+        expect(record?.holder).toBe("new-holder");
+        expect(record?.token).toBe("new-token");
+
+        // And the canonical local ref itself must still hold the
+        // freshly-acquired value — not force-reverted to the stale remote
+        // one readLease's own fetch pulled down.
+        expect(await readRefSha(leaseRef("fountain-converge"), { cwd: clonePath })).toBe(freshBlobSha);
+      } finally {
+        await cleanup();
+      }
+    });
+  });
+});

package/src/lifecycle/lease.ts

@@ -0,0 +1,270 @@
+/**
+ * Operator lease (#1485, epic #1487) — single-writer coordination for a
+ * `ConvergeOp`'s tick loop, entirely over git. No new state store: the lease
+ * lives on a dedicated ref namespace (`refs/chant/lease/<op>`), separate
+ * from the `chant/lifecycle` orphan branch's own commit history, whose
+ * value IS a lease-record blob — no tree, no commit (./git.ts's
+ * `writeBlob`/`readBlobBySha`). Acquiring or renewing a lease is one
+ * `updateRefCAS` call (./git.ts): the caller reads the ref's current SHA,
+ * and the write only lands if the ref still points there. No `flock` file
+ * either — `git update-ref` is already an atomic local mutex (its own
+ * lockfile-then-rename), so a second local process racing the same acquire
+ * loses outright without any second locking mechanism to reason about.
+ *
+ * Cross-machine contention is settled by pushing/fetching this one ref
+ * through the project's remote (best-effort — see `acquireLease`). A
+ * project with no remote is single-machine by construction: the local CAS
+ * above is then the *entire* coordination story, which is exactly what
+ * issue #1485's open question 5 asks be stated loudly — `chant operator`'s
+ * own docs page says so explicitly; nothing here silently upgrades a
+ * remote-less lease to team-visible durability.
+ *
+ * The record's `token` is the fencing token the issue asks for: a fresh
+ * value is minted only when the lease actually changes hands (first
+ * acquire, or a re-acquire after the previous holder's lease expired or was
+ * released) — never on a same-holder renewal, so an in-flight tick's token
+ * stays valid across the operator loop's own heartbeats. `stillHoldsLease`
+ * is what a caller uses, right before trusting a finished tick's own work,
+ * to notice its token has since changed (the lease was stolen mid-tick,
+ * e.g. the process stalled past its TTL) — see `../op/operator.ts`'s tick
+ * loop for how that's handled: never a hard failure, since a converge tick
+ * is idempotent by design (it re-observes and re-derives everything), so a
+ * late, fenced-out write is redundant, not corrupting.
+ */
+import { hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+import { readRefSha, updateRefCAS, deleteRefCAS, writeBlob, readBlobBySha, pushRef, fetchRefInto, RefCASConflictError } from "./git";
+
+export const LEASE_REF_PREFIX = "refs/chant/lease/";
+
+/**
+ * Side namespace `readLease` fetches remote lease state into (#1959 finding
+ * 3), rather than into `refs/chant/lease/<op>` itself. That ref is the CAS
+ * write path's alone (`acquireLease`/`releaseLease`, both via
+ * `updateRefCAS`/`deleteRefCAS`); a read path force-fetching directly into
+ * it would risk clobbering a just-acquired, not-yet-pushed local lease with
+ * the still-stale remote value — the exact race a concurrent `chant operator
+ * status` in the same clone could hit during the acquire→push window. See
+ * `readLease`'s doc for how the two are reconciled without that risk.
+ */
+export const LEASE_REMOTE_TRACKING_PREFIX = "refs/chant/lease-remote/";
+
+/**
+ * Default lease TTL — long enough that a normal tick (observe, classify,
+ * a budget-bounded number of dispatches) finishes well inside it; short
+ * enough that a crashed operator's environment resumes converging soon
+ * after, without a human intervening. The operator loop renews well before
+ * this elapses (every round it still owns the lease for), so under normal
+ * operation the TTL is never actually reached.
+ */
+export const DEFAULT_LEASE_TTL_MS = 5 * 60_000;
+
+export function leaseRef(opName: string): string {
+  return `${LEASE_REF_PREFIX}${opName}`;
+}
+
+function leaseRemoteTrackingRef(opName: string): string {
+  return `${LEASE_REMOTE_TRACKING_PREFIX}${opName}`;
+}
+
+/**
+ * Sort key for "which of two lease records is more current" — a plain
+ * string comparison works because `acquiredAt`/`expiresAt` are always
+ * `Date.prototype.toISOString()` output (fixed-width, UTC), which sorts
+ * lexicographically in time order. Compares `acquiredAt` first (a genuine
+ * handoff to a new holder always mints a strictly later one; see
+ * `acquireLease`), falling back to `expiresAt` to break a tie between two
+ * renewals of the *same* holder/token, which share `acquiredAt` by design.
+ * `undefined` sorts before every real record.
+ */
+function leaseFreshnessKey(record?: LeaseRecord): string {
+  return record ? `${record.acquiredAt} ${record.expiresAt}` : "";
+}
+
+/** One lease's live state — the entire durable record; there is no history, only the current holder (see this module's doc on why no separate ledger). */
+export interface LeaseRecord {
+  op: string;
+  /** `<hostname>:<pid>:<random>` — a diagnostic identity, not itself the fencing mechanism (`token` is). */
+  holder: string;
+  /** Fencing token — new only when the lease actually changes hands; see module doc. */
+  token: string;
+  acquiredAt: string;
+  expiresAt: string;
+}
+
+/** A stable-enough identity for "who holds this lease", for logs and `chant operator status` — hostname:pid, plus a short random suffix so two processes started in the same pid-reuse window never read as the same holder. */
+export function currentHolderId(): string {
+  return `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`;
+}
+
+function isExpired(record: LeaseRecord, now: Date): boolean {
+  return new Date(record.expiresAt).getTime() <= now.getTime();
+}
+
+function parseLease(raw: string): LeaseRecord | undefined {
+  try {
+    const v = JSON.parse(raw) as Partial<LeaseRecord>;
+    if (
+      typeof v.op === "string" &&
+      typeof v.holder === "string" &&
+      typeof v.token === "string" &&
+      typeof v.acquiredAt === "string" &&
+      typeof v.expiresAt === "string"
+    ) {
+      return v as LeaseRecord;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export interface ReadLeaseResult {
+  /** The ref's current SHA (the CAS anchor for the next write), or `null` if no lease has ever been written. */
+  sha: string | null;
+  record?: LeaseRecord;
+}
+
+/**
+ * Read the live lease for `opName`, fetching the remote ref first (best-
+ * effort) so a lease held by another machine is visible before deciding
+ * whether to acquire.
+ *
+ * The fetch lands in a side tracking ref (`refs/chant/lease-remote/<op>`),
+ * never directly into `refs/chant/lease/<op>` itself (#1959 finding 3) — the
+ * canonical local ref is written *only* by the CAS path
+ * (`acquireLease`/`releaseLease`), so a read (this function is called
+ * before every `acquireLease`, and directly by `chant operator status`) can
+ * never force it back to a stale remote value out from under a concurrent
+ * local acquirer. The returned `record` is whichever of the local/remote
+ * views is more current by `leaseFreshnessKey` (ties keep local): this
+ * still gives full cross-machine visibility — a genuinely newer remote
+ * holder wins — while a just-acquired, not-yet-pushed local lease (freshest
+ * by construction) always survives a same-clone concurrent read. `sha`
+ * — the CAS anchor a subsequent `acquireLease`/`releaseLease` writes
+ * against — is always the local ref's own actual value; only the local
+ * canonical ref is ever a valid basis for a `updateRefCAS`/`deleteRefCAS`
+ * call against it, regardless of what the comparison decided about `record`.
+ */
+export async function readLease(opName: string, opts?: { cwd?: string }): Promise<ReadLeaseResult> {
+  const ref = leaseRef(opName);
+  const trackingRef = leaseRemoteTrackingRef(opName);
+  await fetchRefInto(ref, trackingRef, opts).catch(() => undefined);
+
+  const sha = await readRefSha(ref, opts);
+  const localRecord = sha ? parseLease((await readBlobBySha(sha, opts)) ?? "") : undefined;
+
+  const remoteSha = await readRefSha(trackingRef, opts);
+  const remoteRecord = remoteSha ? parseLease((await readBlobBySha(remoteSha, opts)) ?? "") : undefined;
+
+  const record = leaseFreshnessKey(remoteRecord) > leaseFreshnessKey(localRecord) ? remoteRecord : localRecord;
+  return { sha, record };
+}
+
+export interface AcquireLeaseResult {
+  acquired: boolean;
+  lease?: LeaseRecord;
+  /** Present when not acquired: the lease record currently held by someone else. */
+  heldBy?: LeaseRecord;
+}
+
+/**
+ * Acquire or renew the lease for `opName` as `holder`. Succeeds when the ref
+ * doesn't exist yet, is expired, or is already held by `holder` (a renewal:
+ * same token, pushed-out expiry). Fails — returns `acquired: false`, without
+ * throwing — when it's live-held by someone else, or when a concurrent CAS
+ * write is lost to a race that happened between this call's read and its
+ * write ({@link RefCASConflictError}); both read identically to a caller
+ * deciding whether to tick this round ("someone else has it right now,
+ * skip").
+ *
+ * Deliberately does NOT swallow a `StaleLockError` (./git.ts) into that same
+ * "someone else has it" outcome (#1959 finding 2): a leftover `.lock` file
+ * from a killed process is not contention, it's wreckage, and treating it as
+ * "held by someone else" would make `chant operator` back off forever
+ * against a lease nobody can ever actually acquire again without manual
+ * intervention. It propagates instead, so the caller (`../op/operator.ts`'s
+ * `runOperatorRound`) can surface it as its own distinct, diagnosable event
+ * rather than a silent, permanent skip.
+ */
+export async function acquireLease(
+  opName: string,
+  holder: string,
+  opts?: { cwd?: string; ttlMs?: number; now?: () => Date },
+): Promise<AcquireLeaseResult> {
+  const ttlMs = opts?.ttlMs ?? DEFAULT_LEASE_TTL_MS;
+  const now = opts?.now?.() ?? new Date();
+
+  const { sha, record: current } = await readLease(opName, opts);
+  const expired = !current || isExpired(current, now);
+  const ownedByUs = current?.holder === holder;
+
+  if (current && !expired && !ownedByUs) {
+    return { acquired: false, heldBy: current };
+  }
+
+  const renewing = !!current && ownedByUs && !expired;
+  const record: LeaseRecord = {
+    op: opName,
+    holder,
+    token: renewing ? current.token : randomUUID(),
+    acquiredAt: renewing ? current.acquiredAt : now.toISOString(),
+    expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+  };
+
+  const blobSha = await writeBlob(JSON.stringify(record), opts);
+  try {
+    await updateRefCAS(leaseRef(opName), blobSha, sha, opts);
+  } catch (err) {
+    if (err instanceof RefCASConflictError) {
+      const retry = await readLease(opName, opts);
+      return { acquired: false, heldBy: retry.record };
+    }
+    // A StaleLockError (or any other non-CAS failure) is NOT "someone else
+    // has it" — propagate it as its own distinct error rather than folding
+    // it into `heldBy`, per this function's doc.
+    throw err;
+  }
+  await pushRef(leaseRef(opName), opts).catch(() => undefined);
+  return { acquired: true, lease: record };
+}
+
+/**
+ * Release the lease, but only when `holder`/`token` still match the live
+ * value — releasing a lease this caller no longer actually holds would
+ * silently drop someone else's. Best-effort courtesy: a lease nobody
+ * releases is reclaimed anyway once its TTL passes, so a failed release
+ * (returns `false`, never throws) is not itself a correctness problem.
+ */
+export async function releaseLease(
+  opName: string,
+  holder: string,
+  token: string,
+  opts?: { cwd?: string },
+): Promise<boolean> {
+  const { sha, record } = await readLease(opName, opts);
+  if (!sha || !record || record.holder !== holder || record.token !== token) return false;
+  try {
+    await deleteRefCAS(leaseRef(opName), sha, opts);
+  } catch {
+    return false;
+  }
+  await pushRef(leaseRef(opName), opts).catch(() => undefined);
+  return true;
+}
+
+/**
+ * Does `holder`/`token` still match the live lease? The fencing check a
+ * tick uses right before trusting its own work as authoritative (see
+ * `../op/operator.ts`). Fetches first, so a lease stolen by another machine
+ * is detected, not just a stale local read.
+ */
+export async function stillHoldsLease(
+  opName: string,
+  holder: string,
+  token: string,
+  opts?: { cwd?: string },
+): Promise<boolean> {
+  const { record } = await readLease(opName, opts);
+  return record?.holder === holder && record?.token === token;
+}

package/src/lifecycle/observation-baseline.test.ts

@@ -97,3 +97,49 @@ describe("acceptDeviations", () => {
     expect(countAccepted(null)).toBe(0);
   });
 });
+
+describe("acceptDeviations refuses effect receipts (#1833)", () => {
+  const now = "2026-08-24T00:00:00.000Z";
+
+  test("refuses a deviation whose type is the core receipt entityType", () => {
+    expect(() =>
+      acceptDeviations(emptyBaseline("prod"), "chant", [
+        { entity: "seededReceipt", type: "Chant::EffectReceipt", path: "value", value: "gone" },
+      ], { now }),
+    ).toThrow(/effect receipt "seededReceipt"/);
+  });
+
+  test("refuses a deviation on an entity the caller recognized as a receipt (materialized row)", () => {
+    expect(() =>
+      acceptDeviations(emptyBaseline("prod"), "aws", [
+        { entity: "migratedReceipt", type: "AWS::SSM::Parameter", path: "Value", value: "stale" },
+      ], { now, receipts: new Set(["migratedReceipt"]) }),
+    ).toThrow(/effect receipt "migratedReceipt"/);
+  });
+
+  test("the refusal names the receipt and the effect step as sole writer, and records nothing", () => {
+    const before = emptyBaseline("prod");
+    let error: Error | undefined;
+    try {
+      acceptDeviations(before, "aws", [
+        { entity: "Role", type: "AWS::IAM::Role", path: "MaxSessionDuration", value: 7200 },
+        { entity: "migratedReceipt", type: "AWS::SSM::Parameter", path: "Value", value: "stale" },
+      ], { now, receipts: new Set(["migratedReceipt"]) });
+    } catch (e) {
+      error = e as Error;
+    }
+    expect(error).toBeDefined();
+    expect(error!.message).toContain('effect receipt "migratedReceipt"');
+    expect(error!.message).toContain("only writer");
+    expect(error!.message).toContain("defuse the effect");
+    // The whole acceptance aborts — the non-receipt row was not recorded either.
+    expect(before.lexicons).toEqual({});
+  });
+
+  test("passes: non-receipt deviations accept as before, receipts set present", () => {
+    const b = acceptDeviations(emptyBaseline("prod"), "aws", [
+      { entity: "Role", type: "AWS::IAM::Role", path: "MaxSessionDuration", value: 7200 },
+    ], { now, receipts: new Set(["migratedReceipt"]) });
+    expect(baselineForLexicon(b, "aws").Role.accepted).toHaveLength(1);
+  });
+});