@intentius/chant 0.90.0 → 0.91.0

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

package/src/lifecycle/work-lease.ts

@@ -0,0 +1,426 @@
+/**
+ * The work lease (#2732, ws-055 option a): who is working on which work item,
+ * as a lease beside the operator lease.
+ *
+ * A work item's lease is the operator lease (./lease.ts) under the key
+ * `work/<id>`, so its ref is `refs/chant/lease/work/<id>`, or
+ * `refs/chant/lease/_members/<member>/work/<id>` in a workspace member's
+ * ledger (#2524 D7). It keeps every property the operator lease has: a claim
+ * is one compare-and-set of that ref, the record carries a fencing token that
+ * changes only when the lease changes hands, it expires after its time to
+ * live, and it is pushed to and fetched from the project's remote. Unlike the
+ * operator's, a work lease counts only once the remote has taken it
+ * (`requirePush`), so two workers in separate clones cannot both hold one
+ * item.
+ *
+ * The ref holds only the live lease. Every claim, renew and release also
+ * appends a line to `_leases/<id>.jsonl` on `chant/lifecycle`, the same
+ * append-only shape as `_gates/<op>.jsonl` (./gate-ledger.ts), so the history
+ * of an item's leases is a ledger like the others.
+ *
+ * The lease is coordination, not a record of work: it never touches the
+ * working branch, so it stays out of a release's nothing-to-ship test and out
+ * of the write-scope checks (ws-055, and chud's own leases.mjs before it).
+ *
+ * Which ledger an item's lease lives in is decided by the caller through
+ * `cwd`: `chant workspace work` passes the directory of the work kind file,
+ * so the member owning the kind owns its items' leases wherever the command
+ * runs from.
+ */
+import { sortedJsonReplacer } from "../utils";
+import { getRuntime } from "../runtime-adapter";
+import {
+  acquireLease,
+  leaseRef,
+  LEASE_REF_PREFIX,
+  LEASE_REMOTE_TRACKING_PREFIX,
+  readLease,
+  releaseLease,
+  type LeaseRecord,
+} from "./lease";
+import {
+  fetchLifecycleStatus,
+  pushLifecycle,
+  readBlobBySha,
+  readBlobFromPath,
+  readPathSha,
+  RefCASConflictError,
+  writeBlobToPath,
+} from "./git";
+import { dirname } from "node:path";
+import type { ReasonCode } from "../workspace/reason-codes";
+import { resolveMemberLedger } from "./member-ledger";
+
+/** The key prefix of a work lease under the operator lease's ref namespace. */
+export const WORK_LEASE_KEY_PREFIX = "work/";
+
+/** The directory on `chant/lifecycle` that holds lease histories, under a member's prefix when it has one. */
+export const LEASES_DIR = "_leases";
+
+/** How long a claim lasts unless renewed: chud's default, which its dispatcher renews at a third of. */
+export const DEFAULT_WORK_LEASE_TTL_MS = 10 * 60_000;
+
+/** A work item id a lease can be keyed by: one ref path segment and one file name. */
+export const WORK_ITEM_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+
+/** How long a claim waits out another process's lock on the ref before calling it stale. */
+const LOCK_WAIT_MS = 2_000;
+const APPEND_RETRY_ATTEMPTS = 5;
+
+/** The lease key of work item `id`. */
+export function workLeaseKey(id: string): string {
+  return `${WORK_LEASE_KEY_PREFIX}${id}`;
+}
+
+/** The lease ref of work item `id` in the ledger with `memberPrefix`. */
+export function workLeaseRef(id: string, memberPrefix = ""): string {
+  return leaseRef(workLeaseKey(id), memberPrefix);
+}
+
+/** The path of work item `id`'s lease history on `chant/lifecycle`. */
+export function leaseHistoryPath(id: string, memberPrefix = ""): string {
+  return `${memberPrefix}${LEASES_DIR}/${id}.jsonl`;
+}
+
+/** One work item's lease, as the read contract reports it. */
+export interface WorkLease {
+  /** The work item's id. */
+  item: string;
+  holder: string;
+  /** The fencing token: new on every claim, kept by every renew. */
+  token: string;
+  acquiredAt: string;
+  expiresAt: string;
+}
+
+/** A lease with whether it is still live at the time it was read. */
+export interface WorkLeaseState extends WorkLease {
+  state: "active" | "expired";
+  /** The lease ref. */
+  ref: string;
+}
+
+/** One line of `_leases/<id>.jsonl`. */
+export interface LeaseHistoryRecord {
+  version: 1;
+  event: "claim" | "renew" | "release";
+  item: string;
+  /** The lease's holder. */
+  holder: string;
+  /** Who wrote this line: the holder, or, for the release of an expired lease, whoever closed it out. */
+  by: string;
+  token: string;
+  acquiredAt: string;
+  /** The lease's expiry after this event; a release keeps the expiry it had. */
+  expiresAt: string;
+  /** When the event happened. */
+  timestamp: string;
+  /** How the work ended, on a release. Free text such as done, not_done or skipped. */
+  outcome?: string;
+  note?: string;
+}
+
+/** Why a claim, renew or release was refused. Closed: a new code is a contract change. */
+export const WORK_LEASE_REFUSALS = [
+  /** Someone holds the lease live: another worker, or, for a claim, the same one. */
+  "lease-held",
+  /** Nobody holds it live: it expired, was released or was never claimed. */
+  "lease-not-held",
+  /** The live lease has another token than the one given. */
+  "lease-token-mismatch",
+  /** Another writer changed the lease between the read and the write. */
+  "lease-race",
+  /** The remote refused the push: another clone got there first, or it could not be reached. */
+  "lease-push-rejected",
+] as const satisfies readonly ReasonCode[];
+export type WorkLeaseRefusal = (typeof WORK_LEASE_REFUSALS)[number];
+
+/** Where the history line went. */
+export interface LeaseHistoryWrite {
+  path: string;
+  commit: string;
+  /** Whether `chant/lifecycle` reached the remote; false with no remote too. */
+  pushed: boolean;
+}
+
+export type WorkLeaseResult =
+  | { ok: true; lease: WorkLease; history: LeaseHistoryWrite }
+  | { ok: false; reason: WorkLeaseRefusal; message: string; heldBy?: WorkLease };
+
+export interface WorkLeaseOptions {
+  /** A directory in the repository, inside the member whose ledger holds the lease. */
+  cwd: string;
+  now?: () => Date;
+}
+
+function toWorkLease(item: string, r: LeaseRecord): WorkLease {
+  return { item, holder: r.holder, token: r.token, acquiredAt: r.acquiredAt, expiresAt: r.expiresAt };
+}
+
+function checkId(id: string): void {
+  if (!WORK_ITEM_ID_PATTERN.test(id) || id.includes("..")) {
+    throw new Error(`${JSON.stringify(id)} can't key a work lease: use letters, digits, ".", "_" and "-", starting with a letter or digit`);
+  }
+}
+
+const REASONS: Record<string, WorkLeaseRefusal> = {
+  held: "lease-held",
+  "not-held": "lease-not-held",
+  "token-mismatch": "lease-token-mismatch",
+  race: "lease-race",
+  "push-rejected": "lease-push-rejected",
+};
+
+function refusalMessage(id: string, reason: WorkLeaseRefusal, heldBy: WorkLease | undefined): string {
+  const by = heldBy ? `${heldBy.holder} until ${heldBy.expiresAt}` : undefined;
+  switch (reason) {
+    case "lease-held":
+      return `${id} is held by ${by}`;
+    case "lease-not-held":
+      return `${id} is not held${heldBy ? ` by the caller: ${by}` : ""}; claim it again`;
+    case "lease-token-mismatch":
+      return `${id} is held with another token (${heldBy?.token}) by ${by}`;
+    case "lease-race":
+      return `${id} changed while it was being written${by ? `: it is held by ${by}` : ""}`;
+    case "lease-push-rejected":
+      return `the remote refused the lease on ${id}${by ? `: it is held there by ${by}` : ", or could not be reached"}`;
+  }
+}
+
+/**
+ * Claim work item `id` for `holder` for `ttlMs`. Refused with `lease-held`,
+ * naming the holder, when anyone holds it live, `holder` included; an expired
+ * lease does not refuse a claim, and the new claim gets a new token.
+ */
+export async function claimWorkLease(
+  id: string,
+  holder: string,
+  opts: WorkLeaseOptions & { ttlMs?: number; note?: string },
+): Promise<WorkLeaseResult> {
+  checkId(id);
+  const result = await acquireLease(workLeaseKey(id), holder, {
+    cwd: opts.cwd,
+    ttlMs: opts.ttlMs ?? DEFAULT_WORK_LEASE_TTL_MS,
+    now: opts.now,
+    mode: "claim",
+    requirePush: true,
+    lockWaitMs: LOCK_WAIT_MS,
+  });
+  return finish(id, "claim", holder, result, opts);
+}
+
+/**
+ * Move the expiry of `holder`'s live lease on `id` to `ttlMs` from now,
+ * keeping its token. With `token`, the live lease must carry it. Refused with
+ * `lease-not-held` once the lease has expired or was released: the holder
+ * claims it again, and gets a new token.
+ */
+export async function renewWorkLease(
+  id: string,
+  holder: string,
+  opts: WorkLeaseOptions & { ttlMs?: number; token?: string; note?: string },
+): Promise<WorkLeaseResult> {
+  checkId(id);
+  const result = await acquireLease(workLeaseKey(id), holder, {
+    cwd: opts.cwd,
+    ttlMs: opts.ttlMs ?? DEFAULT_WORK_LEASE_TTL_MS,
+    now: opts.now,
+    mode: "renew",
+    token: opts.token,
+    requirePush: true,
+    lockWaitMs: LOCK_WAIT_MS,
+  });
+  return finish(id, "renew", holder, result, opts);
+}
+
+async function finish(
+  id: string,
+  event: "claim" | "renew",
+  holder: string,
+  result: Awaited<ReturnType<typeof acquireLease>>,
+  opts: WorkLeaseOptions & { note?: string },
+): Promise<WorkLeaseResult> {
+  if (!result.acquired || !result.lease) {
+    const reason = REASONS[result.reason ?? "race"];
+    const heldBy = result.heldBy ? toWorkLease(id, result.heldBy) : undefined;
+    return { ok: false, reason, message: refusalMessage(id, reason, heldBy), ...(heldBy ? { heldBy } : {}) };
+  }
+  const lease = toWorkLease(id, result.lease);
+  const now = opts.now?.() ?? new Date();
+  const history = await appendLeaseHistory(
+    { version: 1, event, item: id, holder, by: holder, token: lease.token, acquiredAt: lease.acquiredAt, expiresAt: lease.expiresAt, timestamp: now.toISOString(), ...(opts.note ? { note: opts.note } : {}) },
+    opts,
+  );
+  return { ok: true, lease, history };
+}
+
+/**
+ * Give the lease on `id` back. The holder releases a live lease (with
+ * `token`, only that one); anyone may release an expired one, which is how an
+ * abandoned claim is closed out. `outcome` says how the work ended. Refused
+ * with `lease-not-held` when there is no lease, and `lease-held` when someone
+ * else holds it live.
+ */
+export async function releaseWorkLease(
+  id: string,
+  by: string,
+  opts: WorkLeaseOptions & { token?: string; outcome?: string; note?: string },
+): Promise<WorkLeaseResult> {
+  checkId(id);
+  const key = workLeaseKey(id);
+  const now = opts.now?.() ?? new Date();
+  const { record } = await readLease(key, { cwd: opts.cwd });
+  if (!record) return { ok: false, reason: "lease-not-held", message: refusalMessage(id, "lease-not-held", undefined) };
+  const current = toWorkLease(id, record);
+  const live = new Date(record.expiresAt).getTime() > now.getTime();
+  if (live && record.holder !== by) return { ok: false, reason: "lease-held", message: refusalMessage(id, "lease-held", current), heldBy: current };
+  if (opts.token !== undefined && record.token !== opts.token) {
+    return { ok: false, reason: "lease-token-mismatch", message: refusalMessage(id, "lease-token-mismatch", current), heldBy: current };
+  }
+  if (!(await releaseLease(key, record.holder, record.token, { cwd: opts.cwd }))) {
+    const after = (await readLease(key, { cwd: opts.cwd })).record;
+    const heldBy = after ? toWorkLease(id, after) : undefined;
+    return { ok: false, reason: "lease-race", message: refusalMessage(id, "lease-race", heldBy), ...(heldBy ? { heldBy } : {}) };
+  }
+  const history = await appendLeaseHistory(
+    {
+      version: 1,
+      event: "release",
+      item: id,
+      holder: record.holder,
+      by,
+      token: record.token,
+      acquiredAt: record.acquiredAt,
+      expiresAt: record.expiresAt,
+      timestamp: now.toISOString(),
+      ...(opts.outcome ? { outcome: opts.outcome } : {}),
+      ...(opts.note ? { note: opts.note } : {}),
+    },
+    opts,
+  );
+  return { ok: true, lease: current, history };
+}
+
+/**
+ * Append one line to `_leases/<id>.jsonl`, with the same read-then-CAS retry
+ * the gate ledger's appends use, then push `chant/lifecycle`. The branch is
+ * fetched first when it fast-forwards, and the push is best-effort: the lease
+ * ref is what coordinates, and a history that did not reach the remote is
+ * reported as `pushed: false` rather than failing a lease that was taken.
+ */
+async function appendLeaseHistory(record: LeaseHistoryRecord, opts: { cwd: string }): Promise<LeaseHistoryWrite> {
+  await fetchLifecycleStatus(opts).catch(() => undefined);
+  const file = `${record.item}.jsonl`;
+  const json = JSON.stringify(record, sortedJsonReplacer);
+  let commit: string | undefined;
+  let lastErr: unknown;
+  for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS && commit === undefined; attempt++) {
+    try {
+      const priorSha = await readPathSha(LEASES_DIR, file, opts);
+      const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
+      const content = existing ? `${existing.replace(/\n$/, "")}\n${json}` : json;
+      commit = await writeBlobToPath(LEASES_DIR, file, content, `Work lease ${record.event}: ${record.item} (${record.holder})`, {
+        ...opts,
+        expectPriorPathSha: priorSha,
+      });
+    } catch (err) {
+      if (!(err instanceof RefCASConflictError)) throw err;
+      lastErr = err;
+    }
+  }
+  if (commit === undefined) throw lastErr;
+  const pushed = await pushLifecycle(opts).catch(() => false);
+  const { prefix } = await resolveMemberLedger(opts.cwd);
+  return { path: leaseHistoryPath(record.item, prefix), commit, pushed };
+}
+
+/** Parse the text of a lease history file, oldest first. Malformed lines are counted and skipped. */
+export function parseLeaseHistory(content: string): { records: LeaseHistoryRecord[]; malformed: number } {
+  const records: LeaseHistoryRecord[] = [];
+  let malformed = 0;
+  for (const line of content.split("\n").map((l) => l.trim()).filter(Boolean)) {
+    try {
+      const r = JSON.parse(line) as Partial<LeaseHistoryRecord>;
+      const ok =
+        r.version === 1 &&
+        (r.event === "claim" || r.event === "renew" || r.event === "release") &&
+        [r.item, r.holder, r.by, r.token, r.acquiredAt, r.expiresAt, r.timestamp].every((v) => typeof v === "string");
+      if (ok) records.push(r as LeaseHistoryRecord);
+      else malformed++;
+    } catch {
+      malformed++;
+    }
+  }
+  return { records, malformed };
+}
+
+/** Read work item `id`'s lease history in the ledger of the project at `opts.cwd`. Empty when it has none. */
+export async function readLeaseHistory(id: string, opts: { cwd: string }): Promise<{ records: LeaseHistoryRecord[]; malformed: number }> {
+  checkId(id);
+  const content = await readBlobFromPath(LEASES_DIR, `${id}.jsonl`, opts);
+  return content ? parseLeaseHistory(content) : { records: [], malformed: 0 };
+}
+
+function parseRecord(raw: string): LeaseRecord | undefined {
+  try {
+    const v = JSON.parse(raw) as Partial<LeaseRecord>;
+    return typeof v.holder === "string" && typeof v.token === "string" && typeof v.acquiredAt === "string" && typeof v.expiresAt === "string"
+      ? (v as LeaseRecord)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Every work lease in the ledger with `memberPrefix`, read from the local
+ * refs only: the lease refs this clone wrote, and the remote's as last
+ * fetched (`refs/chant/lease-remote/`), the fresher of the two per item, as
+ * `readLease` picks. It never fetches, so a read-only report stays off the
+ * network; a claim or renew fetches before it decides. Released leases have
+ * no ref and are not listed; expired ones are, with `state: "expired"`.
+ * Sorted by item.
+ */
+export async function listWorkLeases(opts: { cwd: string; memberPrefix: string; now?: Date }): Promise<WorkLeaseState[]> {
+  const rt = getRuntime();
+  const now = (opts.now ?? new Date()).getTime();
+  const local = `${LEASE_REF_PREFIX}${opts.memberPrefix}${WORK_LEASE_KEY_PREFIX}`;
+  const remote = `${LEASE_REMOTE_TRACKING_PREFIX}${opts.memberPrefix}${WORK_LEASE_KEY_PREFIX}`;
+  const out = await rt.spawn(["git", "for-each-ref", "--format=%(refname) %(objectname)", local, remote], { cwd: opts.cwd });
+  if (out.exitCode !== 0) return [];
+  const best = new Map<string, LeaseRecord>();
+  for (const line of out.stdout.split("\n").filter(Boolean)) {
+    const [ref, sha] = line.split(" ");
+    const id = ref.startsWith(local) ? ref.slice(local.length) : ref.slice(remote.length);
+    if (!WORK_ITEM_ID_PATTERN.test(id)) continue;
+    const record = parseRecord((await readBlobBySha(sha, opts)) ?? "");
+    if (!record) continue;
+    const prior = best.get(id);
+    const key = (r: LeaseRecord) => `${r.acquiredAt} ${r.expiresAt}`;
+    if (!prior || key(record) > key(prior) || (key(record) === key(prior) && ref.startsWith(local))) best.set(id, record);
+  }
+  return [...best.entries()]
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([id, r]) => ({
+      ...toWorkLease(id, r),
+      state: new Date(r.expiresAt).getTime() > now ? ("active" as const) : ("expired" as const),
+      ref: workLeaseRef(id, opts.memberPrefix),
+    }));
+}
+
+/**
+ * The active lease of each work item of the kind at `kindFile`, by item id,
+ * for `chant workspace records --json`. Read from the local refs of the
+ * ledger owning the kind file's directory, without fetching. Empty when
+ * nothing can be read.
+ */
+export async function activeWorkLeases(kindFile: string, now = new Date()): Promise<Map<string, Omit<WorkLease, "item">>> {
+  const cwd = dirname(kindFile);
+  try {
+    const { prefix } = await resolveMemberLedger(cwd);
+    const leases = await listWorkLeases({ cwd, memberPrefix: prefix, now });
+    return new Map(leases.filter((l) => l.state === "active").map((l) => [l.item, { holder: l.holder, token: l.token, acquiredAt: l.acquiredAt, expiresAt: l.expiresAt }]));
+  } catch {
+    return new Map();
+  }
+}

package/src/op/builders.ts

@@ -1,4 +1,5 @@
 import { OpResource } from "./resource";
+import { workLeaseProblems } from "./work-lease-decl";
 import type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep } from "./types";
 import { isEffectReceipt, type EffectReceiptDeclaration } from "../effect-receipt";
 import { receiptCheckInput } from "./receipt-store";
@@ -51,6 +52,10 @@ export function Op(config: OpConfig): InstanceType<typeof OpResource> {
   if (config.schedule && !isValidCronExpression(config.schedule.cron)) {
     throw new Error(`Op "${config.name}": ${cronSyntaxMessage(config.schedule.cron)}`);
   }
+  // #2748: a work lease declared badly, or a change to the checkout with none,
+  // fails on `chant build` rather than on the first run.
+  const leaseProblems = workLeaseProblems(config);
+  if (leaseProblems.length > 0) throw new Error(leaseProblems.join("\n"));
   return new OpResource(config as unknown as Record<string, unknown>);
 }