@intentius/chant 0.90.0 → 0.93.0

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/run-ledger.ts

@@ -85,6 +85,8 @@ export function buildRunRecord(
     status: OpRunRecord["status"];
     id?: string;
     gate?: OpRunRecord["gate"];
+    point?: OpRunRecord["point"];
+    steward?: string;
   },
 ): OpRunRecordInput {
   const phases: OpRunPhaseRecord[] = [];
@@ -106,6 +108,8 @@ export function buildRunRecord(
       ...(record.approval ? { approval: record.approval } : {}),
       ...(record.error !== undefined ? { error: record.error } : {}),
       ...(record.refusal !== undefined ? { refusal: record.refusal } : {}),
+      ...(record.point ? { point: record.point } : {}),
+      ...(record.gate ? { gate: record.gate } : {}),
     });
     if (record.outcome) outcomes[record.outcome.name] = record.outcome.value;
   }
@@ -122,6 +126,8 @@ export function buildRunRecord(
     outcomes,
     phases,
     ...(times.gate ? { gate: times.gate } : {}),
+    ...(times.point ? { point: times.point } : {}),
+    ...(times.steward ? { steward: times.steward } : {}),
   };
 }
 

package/src/lifecycle/symptoms.ts

@@ -124,3 +124,98 @@ export const CONVERGE_SYMPTOM_FIELDS: ReadonlySet<string> = new Set([
   "unobservedReasons",
   "totalCount",
 ]);
+
+// ── Resources an observer step reports (#2778) ──────────────────────────────
+
+/**
+ * One resource's verdict, as an observer step reports it: `in-sync` when it
+ * is what its declaration says, `drifted` when it isn't, and `unknown` when
+ * the observer could not tell.
+ */
+export type ResourceStatus = "in-sync" | "drifted" | "unknown";
+
+/** One resource an observer step looked at. */
+export interface ObservedResource {
+  name: string;
+  status: ResourceStatus;
+  /** Why the observer gave that verdict, in one line. */
+  detail?: string;
+}
+
+/**
+ * What a `ConvergeOp`'s observer step returns (#2778), for resources no
+ * lexicon declares or observes: the processes a supervisor runs in a box,
+ * for example. `ConvergeOp({ observe })` evaluates its rules once per
+ * resource, against a {@link ResourceSymptom}.
+ */
+export interface ResourceObservation {
+  resources: ObservedResource[];
+}
+
+/**
+ * The record a `ConvergeOp` with an observer step evaluates each rule
+ * against, once per observed resource (#2778). A rule reads `status` (and
+ * may read `resource` to single one out); a `run()` it fires is dispatched
+ * for that resource, which the dispatched Op reads from
+ * `CHANT_CONVERGE_RESOURCE`.
+ */
+export interface ResourceSymptom {
+  env: string;
+  /** The resource's name, as the observer reported it. */
+  resource: string;
+  status: ResourceStatus;
+  /** The observer's one-line reason, or "". */
+  detail: string;
+}
+
+/**
+ * The environment variable a dispatched Op reads the resource from, when a
+ * ConvergeOp with an observer step fired its rule for one resource (#2778).
+ */
+export const CONVERGE_RESOURCE_ENV = "CHANT_CONVERGE_RESOURCE";
+
+/** Every field a {@link ResourceSymptom} produces: OPS014's whitelist for a ConvergeOp with an observer step. */
+export const RESOURCE_SYMPTOM_FIELDS: ReadonlySet<string> = new Set(["env", "resource", "status", "detail"]);
+
+const RESOURCE_STATUSES: ReadonlySet<string> = new Set(["in-sync", "drifted", "unknown"]);
+
+/**
+ * Read an observer step's result as a {@link ResourceObservation}. The
+ * result is the observation itself, or a `shell()` step's result whose
+ * stdout is the observation as JSON. Throws, naming what is wrong, on
+ * anything else: a tick must not converge from a reading it can't parse.
+ */
+export function parseResourceObservation(value: unknown): ResourceObservation {
+  let candidate: unknown = value;
+  if (candidate && typeof candidate === "object" && !("resources" in candidate) && typeof (candidate as { stdout?: unknown }).stdout === "string") {
+    const stdout = (candidate as { stdout: string }).stdout;
+    try {
+      candidate = JSON.parse(stdout);
+    } catch {
+      throw new Error(`the observer step's stdout is not JSON: ${stdout.slice(0, 120)}`);
+    }
+  }
+  const resources = (candidate as { resources?: unknown } | null)?.resources;
+  if (!Array.isArray(resources)) {
+    throw new Error("the observer step returned no `resources` array: it must return { resources: [{ name, status }] }, or print it as JSON");
+  }
+  const seen = new Set<string>();
+  const out: ObservedResource[] = [];
+  for (const [i, r] of resources.entries()) {
+    const entry = r as { name?: unknown; status?: unknown; detail?: unknown } | null;
+    if (!entry || typeof entry.name !== "string" || entry.name === "") {
+      throw new Error(`the observer step's resources[${i}] has no name`);
+    }
+    if (typeof entry.status !== "string" || !RESOURCE_STATUSES.has(entry.status)) {
+      throw new Error(`the observer step's resource "${entry.name}" has status ${JSON.stringify(entry.status)}: it must be in-sync, drifted or unknown`);
+    }
+    if (seen.has(entry.name)) throw new Error(`the observer step reported resource "${entry.name}" twice`);
+    seen.add(entry.name);
+    out.push({
+      name: entry.name,
+      status: entry.status as ResourceStatus,
+      ...(typeof entry.detail === "string" && entry.detail !== "" ? { detail: entry.detail } : {}),
+    });
+  }
+  return { resources: out };
+}

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 }));
+  });
+});