@intentius/chant 0.89.0 → 0.91.0

package/src/lifecycle/plan-ledger.test.ts

@@ -0,0 +1,148 @@
+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 { join } from "node:path";
+import { persistReleasePlan, readReleasePlan, InvalidReleasePlanError, type ReleasePlan } from "./plan-ledger";
+import { readRefSha } 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);
+}
+
+function makePlan(digest: string, extra: Record<string, unknown> = {}): ReleasePlan {
+  return { digest, release: "r-abc12345", units: [{ id: "w-1", contract: "c-1" }], evidence: [], ...extra };
+}
+
+describe("lifecycle/plan-ledger", () => {
+  describe("persistReleasePlan / readReleasePlan", () => {
+    test("round-trips a plan by its own digest", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const plan = makePlan("sha256:" + "1".repeat(64));
+
+        const { commit, written } = await persistReleasePlan(plan, { cwd: dir });
+        expect(written).toBe(true);
+        expect(commit).toMatch(/^[0-9a-f]{40}$/);
+
+        const readBack = await readReleasePlan(plan.digest, { cwd: dir });
+        expect(readBack).toEqual(plan);
+      });
+    });
+
+    test("readReleasePlan returns null for an unknown digest", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        expect(await readReleasePlan("sha256:doesnotexist", { cwd: dir })).toBeNull();
+      });
+    });
+
+    test("a plan already written is never rewritten: no second commit, content unchanged", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const plan = makePlan("sha256:" + "2".repeat(64));
+
+        const first = await persistReleasePlan(plan, { cwd: dir });
+        expect(first.written).toBe(true);
+        const tipAfterFirst = await readRefSha("refs/heads/chant/lifecycle", { cwd: dir });
+
+        const second = await persistReleasePlan(plan, { cwd: dir });
+        expect(second.written).toBe(false);
+        expect(second.commit).toBeNull();
+        const tipAfterSecond = await readRefSha("refs/heads/chant/lifecycle", { cwd: dir });
+
+        // Not a new commit — the branch tip is unchanged.
+        expect(tipAfterSecond).toBe(tipAfterFirst);
+        expect(await readReleasePlan(plan.digest, { cwd: dir })).toEqual(plan);
+      });
+    });
+
+    test("a plan with a different digest is a separate entry, coexisting with the first", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const planA = makePlan("sha256:" + "a".repeat(64), { release: "r-a" });
+        const planB = makePlan("sha256:" + "b".repeat(64), { release: "r-b" });
+
+        await persistReleasePlan(planA, { cwd: dir });
+        await persistReleasePlan(planB, { cwd: dir });
+
+        expect(await readReleasePlan(planA.digest, { cwd: dir })).toEqual(planA);
+        expect(await readReleasePlan(planB.digest, { cwd: dir })).toEqual(planB);
+      });
+    });
+
+    test("refuses a plan with no digest field", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const plan = { release: "r-nodigest" } as unknown as ReleasePlan;
+        await expect(persistReleasePlan(plan, { cwd: dir })).rejects.toThrow(InvalidReleasePlanError);
+      });
+    });
+
+    test("release ledger and plan store coexist on the same orphan branch", async () => {
+      const { appendReleaseRecord, readReleaseLedger } = await import("./release-ledger");
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const plan = makePlan("sha256:" + "3".repeat(64));
+        await persistReleasePlan(plan, { cwd: dir });
+        await appendReleaseRecord(
+          {
+            component: "svc",
+            env: "prod",
+            digest: plan.digest,
+            gitSha: "deadbeef",
+            runId: "run-1",
+            timestamp: "2026-01-01T00:00:00.000Z",
+            actor: "ci-bot",
+          },
+          { cwd: dir },
+        );
+
+        expect(await readReleasePlan(plan.digest, { cwd: dir })).toEqual(plan);
+        const { records } = await readReleaseLedger("prod", { cwd: dir });
+        expect(records).toHaveLength(1);
+        expect(records[0].digest).toBe(plan.digest);
+      });
+    });
+
+    test("a member's plan lives under _members/<member>/_plans/ (#2524 D7), reached via the prefix readReleasePlan takes", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        mkdirSync(join(dir, "apps", "web"), { recursive: true });
+        writeFileSync(join(dir, "chant.workspace.json"), JSON.stringify({
+          name: "acme",
+          schema: 1,
+          members: [{ name: "web", dir: "apps/web", kind: "chant" }],
+        }));
+        writeFileSync(join(dir, "apps", "web", "chant.config.ts"), "");
+        git(["add", "-A"], dir);
+        git(["commit", "-q", "-m", "workspace"], dir);
+
+        const plan = makePlan("sha256:" + "4".repeat(64));
+        // Persisted from inside the member's own directory, the way `chant
+        // components release` runs there — writeBlobToPath resolves the
+        // _members/web/ prefix automatically from cwd.
+        const webDir = join(dir, "apps", "web");
+        await persistReleasePlan(plan, { cwd: webDir });
+
+        // readReleasePlan reads it back two ways: with the matching prefix
+        // (as ../workspace/status.ts resolves it for a "members"-layout
+        // release), and directly at the branch path it actually landed on.
+        expect(await readReleasePlan(plan.digest, { cwd: dir, prefix: "_members/web/" })).toEqual(plan);
+        const raw = git(["show", `chant/lifecycle:_members/web/_plans/sha256_${"4".repeat(64)}.json`], dir);
+        expect(raw.exitCode).toBe(0);
+        expect(JSON.parse(raw.stdout)).toEqual(plan);
+      });
+    });
+  });
+});

package/src/lifecycle/plan-ledger.ts

@@ -0,0 +1,158 @@
+/**
+ * Release plan store (ws-055, #2733, part of the chud retirement epic
+ * #2715): persists a release plan — the work items and evidence a release
+ * ships — to the `chant/lifecycle` orphan branch, content-addressed by the
+ * plan's own digest.
+ *
+ * **Why this exists.** ws-055 (docs/design/decisions/ws-055-dev-model-
+ * ledgers.md) decided where a development model's plans live: "a release
+ * plan is written content-addressed to `_plans/<digest>.json` on
+ * chant/lifecycle, and the release ledger record already names that
+ * digest." A `ReleaseRecord.digest` (../lifecycle/release-ledger.ts) is
+ * ordinarily an artifact digest; for a release a runner (the studio kit
+ * today, chud before it) plans work-item by work-item, that same field
+ * *is* the plan's own digest — the release ledger needs no new field to
+ * point at it, it already names the plan. Reading a release through the
+ * read contract (../workspace/status.ts) resolves that digest to the plan
+ * exactly the way it already resolves a build archive digest to a
+ * `BuildArchiveManifest` (./build-ledger-store.ts) — this module is that
+ * store's plan-shaped sibling, same plumbing, same directory-per-kind
+ * convention on the one orphan branch.
+ *
+ * **Storage.** Reuses `writeBlobToPath`/`readBlobFromPath` (./git.ts) —
+ * the identical hash-object -> mktree -> commit-tree -> update-ref
+ * pipeline `writeSnapshot`/`persistBuildManifest` already use. Plans live
+ * under a fixed top-level `_plans/` directory, a peer of `_builds/` and the
+ * per-env directories, never nested inside one — a plan is not env-scoped,
+ * it is named by its own content. Per #2524 D7 / #2538, `writeBlobToPath`'s
+ * `ledgerDir` already folds a workspace member's own `_members/<member>/`
+ * prefix in ahead of `_plans/`, so a member's plans live at
+ * `_members/<member>/_plans/<digest>.json` the same way its build records
+ * live at `_members/<member>/_builds/` — this module does nothing itself
+ * to earn that; it falls out of reusing the shared plumbing.
+ *
+ * **Content-addressed, keyed by the plan's own `digest`.** One file per
+ * plan, `_plans/<digest-with-":"->"_">.json` (`:` is not usable in a git
+ * tree entry name the way `readBlobFromPath`'s `<ref>:<path>` spelling
+ * reads it back, the same reason `./build-ledger-store.ts` substitutes it
+ * for `_builds/`). The digest is computed by whoever plans the release —
+ * the release Op, or a runner like the studio kit — not by chant; this
+ * module only trusts and stores it, exactly as `persistBuildManifest`
+ * trusts a manifest's own `manifestDigest`.
+ *
+ * **A plan already written is never rewritten (#2733 acceptance).**
+ * Unlike `persistBuildManifest`, which writes unconditionally every call
+ * (safe only because identical content produces an identical blob and,
+ * usually, an identical tree — but still a new, redundant commit on the
+ * branch each time), `persistReleasePlan` reads the path first and returns
+ * without writing when a plan is already stored under that digest. A plan
+ * is immutable by construction (it is named by a hash of its own content),
+ * so there is never a reason to overwrite one — only ever a reason to skip
+ * the write.
+ */
+
+import { sortedJsonReplacer } from "../utils";
+import { writeBlobToPath, readBlobFromPath, RefCASConflictError } from "./git";
+
+/** Fixed top-level directory on the `chant/lifecycle` orphan branch that holds every persisted release plan — a peer of `_builds/` and the per-env directories, never nested inside one (see module doc for why). */
+const PLANS_DIR = "_plans";
+
+/**
+ * A release plan (ws-055): the work items and evidence a release ships.
+ * chant does not own this shape — it is a runner's own record, the way a
+ * record kind's schema is the kind's own (../workspace/records.ts) — only
+ * `digest` is required, since it is the storage key. Every other field is
+ * read back and returned exactly as written.
+ */
+export interface ReleasePlan {
+  /**
+   * Content-addressed digest of this plan (`sha256:...`) — the same digest
+   * the release ledger record names (`ReleaseRecord.digest`,
+   * ../lifecycle/release-ledger.ts), so a record leads to its plan.
+   * Computed by the caller before persisting; this module trusts it rather
+   * than recomputing it, the same way `persistBuildManifest` trusts a
+   * manifest's own `manifestDigest`.
+   */
+  digest: string;
+  [key: string]: unknown;
+}
+
+/** Thrown by `persistReleasePlan` when the plan carries no usable `digest` — a plan can't be content-addressed without one. */
+export class InvalidReleasePlanError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidReleasePlanError";
+  }
+}
+
+/** Turn a `sha256:...`-style digest into a filesystem/git-tree-safe filename stem. */
+function digestToFilenameStem(digest: string): string {
+  return digest.replace(/:/g, "_");
+}
+
+function planFilename(digest: string): string {
+  return `${digestToFilenameStem(digest)}.json`;
+}
+
+/**
+ * Persist a release plan to the orphan branch, keyed by its own `digest`.
+ * Does not push to the remote — call `pushLifecycle` (./git.ts) afterward,
+ * the same two-step (`write` then `push`) shape `appendReleaseRecord`/
+ * `persistBuildManifest` use, so a caller persisting a plan alongside the
+ * release record it names can batch both into one push.
+ *
+ * Never rewrites a plan already stored under `plan.digest` (#2733
+ * acceptance) — reads the path first, and returns `{ commit: null, written:
+ * false }` without writing when it is already there. A `RefCASConflictError`
+ * from a genuine race (another writer persisted the same digest's plan
+ * between this call's read and its write) is treated the same way: the
+ * plan is content-addressed, so whatever is already at that path under this
+ * digest is authoritative, never overwritten.
+ */
+export async function persistReleasePlan(
+  plan: ReleasePlan,
+  opts?: { cwd?: string },
+): Promise<{ commit: string | null; written: boolean }> {
+  if (typeof plan.digest !== "string" || plan.digest.length === 0) {
+    throw new InvalidReleasePlanError("release plan is missing its own \"digest\" field — a release plan is content-addressed by its own digest");
+  }
+  const filename = planFilename(plan.digest);
+  const existing = await readBlobFromPath(PLANS_DIR, filename, opts);
+  if (existing !== null) return { commit: null, written: false };
+
+  const json = JSON.stringify(plan, sortedJsonReplacer);
+  try {
+    const commit = await writeBlobToPath(PLANS_DIR, filename, json, "Release plan", { ...opts, expectPriorPathSha: null });
+    return { commit, written: true };
+  } catch (err) {
+    if (err instanceof RefCASConflictError) return { commit: null, written: false };
+    throw err;
+  }
+}
+
+/**
+ * Read a persisted release plan back by its own digest — the same digest a
+ * `ReleaseRecord.digest` names. Returns `null` when no plan was ever
+ * persisted under that digest (never throws — most releases carry no plan
+ * at all, and reading one for status is a normal, expected miss), and when
+ * the stored blob fails to parse as JSON.
+ *
+ * `prefix` lets a multi-member reader (../workspace/status.ts) resolve a
+ * specific member's plan directory directly, the same way
+ * `readReleaseLedgerLines` is handed an already-member-prefixed path there
+ * — `cwd` alone can't do it, since one status read walks every member from
+ * one process without changing directory per member.
+ */
+export async function readReleasePlan(
+  digest: string,
+  opts?: { cwd?: string; prefix?: string },
+): Promise<ReleasePlan | null> {
+  const dir = `${opts?.prefix ?? ""}${PLANS_DIR}`;
+  const content = await readBlobFromPath(dir, planFilename(digest), opts);
+  if (!content) return null;
+  try {
+    return JSON.parse(content) as ReleasePlan;
+  } catch {
+    return null;
+  }
+}

package/src/lifecycle/work-lease.test.ts

@@ -0,0 +1,236 @@
+/**
+ * #2732 — the work lease: the operator lease under `work/<id>`, with a
+ * `_leases/<id>.jsonl` history, coordinating workers in one clone and across
+ * clones through a bare remote.
+ */
+import { afterAll, describe, expect, test } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  claimWorkLease,
+  listWorkLeases,
+  readLeaseHistory,
+  releaseWorkLease,
+  renewWorkLease,
+  workLeaseRef,
+  leaseHistoryPath,
+} from "./work-lease";
+import { readRefSha } from "./git";
+
+const dirs: string[] = [];
+afterAll(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+function tmp(prefix: string): string {
+  const d = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+  dirs.push(d);
+  return d;
+}
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function configure(dir: string): void {
+  git(dir, "config", "user.email", "test@chant.dev");
+  git(dir, "config", "user.name", "Test");
+  git(dir, "config", "commit.gpgsign", "false");
+}
+
+function initRepo(): string {
+  const dir = tmp("chant-work-lease-");
+  git(dir, "init", "-q", "-b", "main");
+  configure(dir);
+  writeFileSync(join(dir, "README.md"), "# t\n");
+  git(dir, "add", "README.md");
+  git(dir, "commit", "-q", "-m", "init");
+  return dir;
+}
+
+const at = (iso: string) => () => new Date(iso);
+
+describe("a work lease in one clone", () => {
+  test("a claim takes a free item, and a second claim is refused with the holder named, the same holder's included", async () => {
+    const cwd = initRepo();
+    const first = await claimWorkLease("W-001", "alice", { cwd, ttlMs: 60_000 });
+    expect(first.ok).toBe(true);
+    if (!first.ok) return;
+    expect(first.lease).toMatchObject({ item: "W-001", holder: "alice" });
+    expect(await readRefSha(workLeaseRef("W-001"), { cwd })).not.toBeNull();
+
+    const second = await claimWorkLease("W-001", "bob", { cwd });
+    expect(second).toMatchObject({ ok: false, reason: "lease-held", heldBy: { holder: "alice", token: first.lease.token } });
+    if (!second.ok) expect(second.message).toContain("alice");
+
+    const again = await claimWorkLease("W-001", "alice", { cwd });
+    expect(again).toMatchObject({ ok: false, reason: "lease-held" });
+  });
+
+  test("a renew moves the expiry and keeps the token; an expired lease can be claimed, with a new token", async () => {
+    const cwd = initRepo();
+    const claim = await claimWorkLease("W-002", "alice", { cwd, ttlMs: 60_000, now: at("2026-09-25T10:00:00.000Z") });
+    if (!claim.ok) throw new Error(claim.message);
+    expect(claim.lease.expiresAt).toBe("2026-09-25T10:01:00.000Z");
+
+    const renew = await renewWorkLease("W-002", "alice", { cwd, ttlMs: 60_000, token: claim.lease.token, now: at("2026-09-25T10:00:30.000Z") });
+    if (!renew.ok) throw new Error(renew.message);
+    expect(renew.lease.token).toBe(claim.lease.token);
+    expect(renew.lease.acquiredAt).toBe(claim.lease.acquiredAt);
+    expect(renew.lease.expiresAt).toBe("2026-09-25T10:01:30.000Z");
+
+    // Another holder can't renew it, and a stale token is refused.
+    expect(await renewWorkLease("W-002", "bob", { cwd, now: at("2026-09-25T10:00:40.000Z") })).toMatchObject({ ok: false, reason: "lease-held" });
+    expect(await renewWorkLease("W-002", "alice", { cwd, token: "stale", now: at("2026-09-25T10:00:40.000Z") })).toMatchObject({ ok: false, reason: "lease-token-mismatch" });
+
+    // Past its expiry: renew is refused, and a claim by anyone mints a new token.
+    const late = at("2026-09-25T10:02:00.000Z");
+    expect(await renewWorkLease("W-002", "alice", { cwd, now: late })).toMatchObject({ ok: false, reason: "lease-not-held" });
+    const reclaim = await claimWorkLease("W-002", "bob", { cwd, ttlMs: 60_000, now: late });
+    if (!reclaim.ok) throw new Error(reclaim.message);
+    expect(reclaim.lease.holder).toBe("bob");
+    expect(reclaim.lease.token).not.toBe(claim.lease.token);
+  });
+
+  test("release: the holder gives a live lease back; someone else can't, but anyone closes out an expired one", async () => {
+    const cwd = initRepo();
+    const t0 = "2026-09-25T10:00:00.000Z";
+    const claim = await claimWorkLease("W-003", "alice", { cwd, ttlMs: 60_000, now: at(t0) });
+    if (!claim.ok) throw new Error(claim.message);
+    expect(await releaseWorkLease("W-003", "bob", { cwd, now: at(t0) })).toMatchObject({ ok: false, reason: "lease-held", heldBy: { holder: "alice" } });
+    const released = await releaseWorkLease("W-003", "alice", { cwd, outcome: "done", now: at(t0) });
+    expect(released.ok).toBe(true);
+    expect(await readRefSha(workLeaseRef("W-003"), { cwd })).toBeNull();
+    expect(await releaseWorkLease("W-003", "alice", { cwd })).toMatchObject({ ok: false, reason: "lease-not-held" });
+
+    const again = await claimWorkLease("W-003", "carol", { cwd, ttlMs: 1_000, now: at(t0) });
+    if (!again.ok) throw new Error(again.message);
+    const closed = await releaseWorkLease("W-003", "dispatcher", { cwd, outcome: "expired", now: at("2026-09-25T11:00:00.000Z") });
+    expect(closed).toMatchObject({ ok: true, lease: { holder: "carol" } });
+  });
+
+  test("the history has one line per claim, renew and release, on chant/lifecycle", async () => {
+    const cwd = initRepo();
+    const claim = await claimWorkLease("W-004", "alice", { cwd, note: "starting" });
+    if (!claim.ok) throw new Error(claim.message);
+    expect(claim.history.path).toBe(leaseHistoryPath("W-004"));
+    expect(claim.history.pushed).toBe(false);
+    await renewWorkLease("W-004", "alice", { cwd });
+    await renewWorkLease("W-004", "alice", { cwd });
+    await releaseWorkLease("W-004", "alice", { cwd, outcome: "done" });
+
+    const { records, malformed } = await readLeaseHistory("W-004", { cwd });
+    expect(malformed).toBe(0);
+    expect(records.map((r) => r.event)).toEqual(["claim", "renew", "renew", "release"]);
+    expect(new Set(records.map((r) => r.token)).size).toBe(1);
+    expect(records[0]).toMatchObject({ version: 1, item: "W-004", holder: "alice", by: "alice", note: "starting" });
+    expect(records[3]).toMatchObject({ outcome: "done" });
+    expect(git(cwd, "show", `chant/lifecycle:_leases/W-004.jsonl`).split("\n")).toHaveLength(4);
+  });
+
+  test("listWorkLeases reports active and expired leases and leaves released ones out", async () => {
+    const cwd = initRepo();
+    const t0 = "2026-09-25T10:00:00.000Z";
+    await claimWorkLease("W-010", "alice", { cwd, ttlMs: 60_000, now: at(t0) });
+    await claimWorkLease("W-011", "bob", { cwd, ttlMs: 1_000, now: at(t0) });
+    await claimWorkLease("W-012", "carol", { cwd, ttlMs: 60_000, now: at(t0) });
+    await releaseWorkLease("W-012", "carol", { cwd, now: at(t0) });
+    const leases = await listWorkLeases({ cwd, memberPrefix: "", now: new Date("2026-09-25T10:00:30.000Z") });
+    expect(leases.map((l) => [l.item, l.holder, l.state])).toEqual([
+      ["W-010", "alice", "active"],
+      ["W-011", "bob", "expired"],
+    ]);
+    expect(leases[0].ref).toBe("refs/chant/lease/work/W-010");
+  });
+
+  test("an id that can't be one ref segment is refused", async () => {
+    const cwd = initRepo();
+    await expect(claimWorkLease("../x", "alice", { cwd })).rejects.toThrow(/can't key a work lease/);
+    await expect(claimWorkLease("a/b", "alice", { cwd })).rejects.toThrow(/can't key a work lease/);
+  });
+
+  test("a workspace member's leases and history sit under _members/<member>/ (D7)", async () => {
+    const cwd = initRepo();
+    writeFileSync(join(cwd, "chant.workspace.json"), JSON.stringify({ name: "acme", schema: 1, members: [{ name: "api", dir: "api", kind: "other", because: "t" }] }));
+    execFileSync("mkdir", ["-p", join(cwd, "api")]);
+    const member = join(cwd, "api");
+    const claim = await claimWorkLease("W-020", "alice", { cwd: member });
+    if (!claim.ok) throw new Error(claim.message);
+    expect(await readRefSha("refs/chant/lease/_members/api/work/W-020", { cwd })).not.toBeNull();
+    expect(await readRefSha("refs/chant/lease/work/W-020", { cwd })).toBeNull();
+    expect(claim.history.path).toBe("_members/api/_leases/W-020.jsonl");
+    expect(git(cwd, "show", "chant/lifecycle:_members/api/_leases/W-020.jsonl")).toContain('"event":"claim"');
+    expect((await listWorkLeases({ cwd, memberPrefix: "_members/api/" })).map((l) => l.item)).toEqual(["W-020"]);
+    expect(await listWorkLeases({ cwd, memberPrefix: "" })).toEqual([]);
+  });
+});
+
+describe("a work lease across clones, through a bare remote", () => {
+  function setup(): { remote: string; a: string; b: string } {
+    const root = tmp("chant-work-lease-remote-");
+    const remote = join(root, "remote.git");
+    git(root, "init", "-q", "--bare", "-b", "main", remote);
+    const a = join(root, "a");
+    git(root, "clone", "-q", remote, a);
+    configure(a);
+    writeFileSync(join(a, "README.md"), "# t\n");
+    git(a, "add", "README.md");
+    git(a, "commit", "-q", "-m", "init");
+    git(a, "push", "-q", "origin", "main");
+    const b = join(root, "b");
+    git(root, "clone", "-q", remote, b);
+    configure(b);
+    return { remote, a, b };
+  }
+
+  test("A claims; B is refused with A named; A renews and releases on the remote; then B claims and A is refused", async () => {
+    const { remote, a, b } = setup();
+    const claim = await claimWorkLease("W-001", "worker-a", { cwd: a, ttlMs: 60_000 });
+    if (!claim.ok) throw new Error(claim.message);
+    expect(git(remote, "rev-parse", workLeaseRef("W-001"))).toBe(await readRefSha(workLeaseRef("W-001"), { cwd: a }));
+
+    const refused = await claimWorkLease("W-001", "worker-b", { cwd: b });
+    expect(refused).toMatchObject({ ok: false, reason: "lease-held", heldBy: { holder: "worker-a", token: claim.lease.token } });
+
+    // A renew reaches the remote: the push expects the value A last pushed, not "absent".
+    const renew = await renewWorkLease("W-001", "worker-a", { cwd: a, ttlMs: 120_000 });
+    if (!renew.ok) throw new Error(renew.message);
+    expect(git(remote, "rev-parse", workLeaseRef("W-001"))).toBe(await readRefSha(workLeaseRef("W-001"), { cwd: a }));
+    const seen = await claimWorkLease("W-001", "worker-b", { cwd: b });
+    expect(seen).toMatchObject({ ok: false, heldBy: { expiresAt: renew.lease.expiresAt } });
+    // B's read-only listing now shows the remote's lease as last fetched.
+    expect((await listWorkLeases({ cwd: b, memberPrefix: "" })).map((l) => l.holder)).toEqual(["worker-a"]);
+
+    const released = await releaseWorkLease("W-001", "worker-a", { cwd: a, outcome: "done" });
+    expect(released.ok).toBe(true);
+    expect(() => git(remote, "rev-parse", "--verify", workLeaseRef("W-001"))).toThrow();
+
+    const taken = await claimWorkLease("W-001", "worker-b", { cwd: b, ttlMs: 60_000 });
+    if (!taken.ok) throw new Error(taken.message);
+    expect(taken.lease.token).not.toBe(claim.lease.token);
+    expect(await claimWorkLease("W-001", "worker-a", { cwd: a })).toMatchObject({ ok: false, reason: "lease-held", heldBy: { holder: "worker-b" } });
+
+    // Both clones' histories reached the remote's chant/lifecycle.
+    expect(claim.history.pushed).toBe(true);
+    const lines = git(remote, "show", "chant/lifecycle:_leases/W-001.jsonl").split("\n").map((l) => JSON.parse(l).event);
+    expect(lines).toEqual(["claim", "renew", "release", "claim"]);
+  });
+
+  test("a claim the remote refuses is undone locally: two clones can't both hold one item", async () => {
+    const { remote, a, b } = setup();
+    // B fetches from an empty remote, so it can't see A's claim, but pushes to the real one.
+    const blind = join(tmp("chant-work-lease-blind-"), "blind.git");
+    git(a, "init", "-q", "--bare", "-b", "main", blind);
+    git(b, "remote", "set-url", "origin", blind);
+    git(b, "remote", "set-url", "--push", "origin", remote);
+
+    const claim = await claimWorkLease("W-005", "worker-a", { cwd: a });
+    if (!claim.ok) throw new Error(claim.message);
+    const lost = await claimWorkLease("W-005", "worker-b", { cwd: b });
+    expect(lost).toMatchObject({ ok: false, reason: "lease-push-rejected" });
+    expect(await readRefSha(workLeaseRef("W-005"), { cwd: b })).toBeNull();
+    expect(git(remote, "rev-parse", workLeaseRef("W-005"))).toBe(await readRefSha(workLeaseRef("W-005"), { cwd: a }));
+  });
+});