@intentius/chant 0.90.0 → 0.93.0

package/src/workspace/work-cli.e2e.test.ts

@@ -0,0 +1,180 @@
+/**
+ * #2732 — `chant workspace work claim|renew|release`, run as the CLI: two
+ * processes racing for one work item, the lease in `records --json` and
+ * `workspace status --json`, and both over MCP.
+ */
+
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { McpServer } from "../cli/mcp/server";
+import { cleanScratch, contract, git, REPO, repo, writeFiles } from "./__fixtures__/contract-repo";
+import recordsSchema from "./records.schema.json";
+import statusSchema from "./status.schema.json";
+import workSchema from "./work-lease.schema.json";
+
+const REF = join(REPO, "reference-workspace");
+const MAIN = join(REPO, "packages/core/src/cli/main.ts");
+const LOADER = pathToFileURL(join(REPO, "node_modules/tsx/dist/loader.mjs")).href;
+const CHANT = [process.execPath, "--import", LOADER, MAIN];
+const WORK = "work/work.kind.mjs";
+
+function work(id: string, fields: Record<string, unknown> = {}): string {
+  const data = { schema: 1, id, title: `Work ${id}`, state: "open", implements: [], needs: [], constrains: ["path:app/server.mjs"], evidence: [], opened_on: "2026-09-25", source: { kind: "workspace", member: "app" }, supersedes: [], ...fields };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+interface Run {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+function chant(cwd: string, args: string[]): Promise<Run> {
+  return new Promise((resolve) => {
+    const child = spawn(CHANT[0], [...CHANT.slice(1), ...args], { cwd, env: { ...process.env, NO_COLOR: "1", TSX_DISABLE_CACHE: "1" } });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+const json = (r: Run) => {
+  const doc = JSON.parse(r.stdout);
+  if ("item" in doc || "error" in doc) contract(workSchema).expectValid(doc);
+  return doc;
+};
+
+let root: string;
+beforeAll(() => {
+  root = repo({
+    "chant.workspace.json": JSON.stringify(
+      {
+        name: "studio",
+        schema: 1,
+        members: [{ name: "app", dir: "app", kind: "other", because: "a plain Node server" }],
+        records: [{ kind: "decisions/decision.kind.mjs" }, { kind: WORK }],
+      },
+      null,
+      2,
+    ),
+    "app/server.mjs": "export const port = 8080;\n",
+    "decisions/decision.kind.mjs": readFileSync(join(REF, "decisions", "decision.kind.mjs"), "utf-8"),
+    "decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
+    "work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
+    "work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
+    "work/W-001-server.md": work("W-001"),
+    "work/W-002-next.md": work("W-002"),
+    "work/W-003-done.md": work("W-003", { state: "done", closed_on: "2026-09-25", evidence: [{ title: "The review", url: "https://example.com/review" }] }),
+  });
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", "the queue");
+});
+afterAll(cleanScratch);
+
+describe("chant workspace work (#2732)", () => {
+  test("two processes claiming one work item: one wins, and the other is refused with the holder named", async () => {
+    const [a, b] = await Promise.all([
+      chant(root, ["workspace", "work", "claim", "W-001", "--holder", "worker-a", "--ttl", "600", "--json"]),
+      chant(root, ["workspace", "work", "claim", "W-001", "--holder", "worker-b", "--ttl", "600", "--json"]),
+    ]);
+    const runs = [a, b];
+    const won = runs.filter((r) => r.code === 0);
+    const lost = runs.filter((r) => r.code === 2);
+    expect(won, `${a.stderr}\n${b.stderr}`).toHaveLength(1);
+    expect(lost).toHaveLength(1);
+    const winner = json(won[0]);
+    expect(winner).toMatchObject({ item: "W-001", event: "claim", kind: WORK, ref: "refs/chant/lease/work/W-001", history: { path: "_leases/W-001.jsonl" } });
+    const refusal = json(lost[0]);
+    expect(refusal.refused.heldBy.holder).toBe(winner.lease.holder);
+    expect(refusal.refused.code).toMatch(/^lease-(held|race)$/);
+    expect(refusal.refused.message).toContain(winner.lease.holder);
+    expect(git(root, "show", "chant/lifecycle:_leases/W-001.jsonl").split("\n")).toHaveLength(1);
+  }, 120_000);
+
+  test("records --json gives each work item its active lease, and status --json lists active and expired leases", async () => {
+    const claim = await chant(root, ["workspace", "work", "claim", "W-002", "--holder", "worker-c", "--ttl", "1", "--json"]);
+    expect(claim.code, claim.stderr).toBe(0);
+    await new Promise((r) => setTimeout(r, 1_100));
+
+    const records = await chant(root, ["workspace", "records", "--kind", WORK, "--json"]);
+    expect(records.code, records.stderr).toBe(0);
+    const doc = json(records);
+    contract(recordsSchema).expectValid(doc);
+    const byId = new Map((doc.records as { id: string; lease?: unknown }[]).map((r) => [r.id, r.lease]));
+    expect(byId.get("W-001")).toMatchObject({ holder: expect.stringMatching(/^worker-[ab]$/) });
+    expect(byId.get("W-002")).toBeNull(); // expired, so not active
+    expect(byId.get("W-003")).toBeNull();
+
+    const status = await chant(root, ["workspace", "status", "dev", "--json"]);
+    expect(status.code, status.stderr).toBe(0);
+    const sdoc = json(status);
+    contract(statusSchema).expectValid(sdoc);
+    expect(sdoc.leases.map((l: { item: string; state: string; member: string | null }) => [l.item, l.state, l.member])).toEqual([
+      ["W-001", "active", null],
+      ["W-002", "expired", null],
+    ]);
+
+    // An expired lease can be claimed again, with a new token.
+    const again = await chant(root, ["workspace", "work", "claim", "W-002", "--holder", "worker-d", "--json"]);
+    expect(again.code, again.stderr).toBe(0);
+    expect(json(again).lease.token).not.toBe(json(claim).lease.token);
+  }, 120_000);
+
+  test("renew keeps the token and moves the expiry; release frees the item; the history has a line for each", async () => {
+    const claim = json(await chant(root, ["workspace", "work", "claim", "W-001", "--holder", "nobody", "--json"]));
+    const holder = claim.refused.heldBy.holder as string;
+    const token = claim.refused.heldBy.token as string;
+
+    const renew = await chant(root, ["workspace", "work", "renew", "W-001", "--holder", holder, "--token", token, "--ttl", "20m", "--json"]);
+    expect(renew.code, renew.stderr).toBe(0);
+    const renewed = json(renew).lease;
+    expect(renewed.token).toBe(token);
+    expect(Date.parse(renewed.expiresAt)).toBeGreaterThan(Date.parse(claim.refused.heldBy.expiresAt));
+
+    const wrong = await chant(root, ["workspace", "work", "release", "W-001", "--holder", "nobody", "--json"]);
+    expect(wrong.code).toBe(2);
+    expect(json(wrong).refused.code).toBe("lease-held");
+
+    const release = await chant(root, ["workspace", "work", "release", "W-001", "--holder", holder, "--outcome", "done"]);
+    expect(release.code, release.stderr).toBe(0);
+    expect(release.stdout).toContain("W-001 released by");
+
+    const events = git(root, "show", "chant/lifecycle:_leases/W-001.jsonl").split("\n").map((l) => JSON.parse(l));
+    expect(events.map((e) => e.event)).toEqual(["claim", "renew", "release"]);
+    expect(events[2]).toMatchObject({ holder, by: holder, outcome: "done", token });
+  }, 120_000);
+
+  test("an unknown item, a closed item and a bad verb are errors, not refusals", async () => {
+    const unknown = await chant(root, ["workspace", "work", "claim", "W-999", "--holder", "a", "--json"]);
+    expect(unknown.code).toBe(1);
+    expect(json(unknown).error.code).toBe("work-item-unknown");
+    const closed = await chant(root, ["workspace", "work", "claim", "W-003", "--holder", "a", "--json"]);
+    expect(closed.code).toBe(1);
+    expect(json(closed).error.code).toBe("work-item-closed");
+    const verb = await chant(root, ["workspace", "work", "grab", "W-001", "--holder", "a"]);
+    expect(verb.code).toBe(1);
+    expect(verb.stderr).toContain("claim, renew, release or history");
+    const noHolder = await chant(root, ["workspace", "work", "claim", "W-001"]);
+    expect(noHolder.code).toBe(1);
+    expect(noHolder.stderr).toContain("--holder");
+  }, 120_000);
+
+  test("the lease fields reach an MCP client through workspace-records and workspace-status", async () => {
+    const claim = await chant(root, ["workspace", "work", "claim", "W-001", "--holder", "mcp-worker", "--json"]);
+    expect(claim.code, claim.stderr).toBe(0);
+    const server = new McpServer([], { workspace: { cwd: root, chantCommand: CHANT } });
+    const call = async (name: string, args: Record<string, unknown>) => {
+      const res = await server.handleRequest({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } });
+      return (res.result as { structuredContent: Record<string, unknown> }).structuredContent;
+    };
+    const records = (await call("workspace-records", { kind: WORK })) as { records: { id: string; lease: { holder: string } | null }[] };
+    expect(records.records.find((r) => r.id === "W-001")?.lease?.holder).toBe("mcp-worker");
+    const status = (await call("workspace-status", { env: "dev" })) as { leases: { item: string; holder: string; state: string }[] };
+    expect(status.leases.find((l) => l.item === "W-001")).toMatchObject({ holder: "mcp-worker", state: "active" });
+  }, 120_000);
+});

package/src/workspace/work-cli.ts

@@ -0,0 +1,429 @@
+/**
+ * `chant workspace work claim|renew|release <id> --holder <name>` (#2732,
+ * ws-055): the work lease, who is working on which work item. And `chant
+ * workspace work history <id>` (#2785): the item's lease history, each claim
+ * and how it ended, a read-contract output (`work-history.schema.json`).
+ *
+ * The lease itself is `../lifecycle/work-lease.ts`, the operator lease under
+ * the key `work/<id>`. This file finds the work item first: in the work kind
+ * `--kind` names, or in the one work kind the declaration names that has a
+ * record with the id. A claim on an id no work record has is refused, and so
+ * is a claim on a closed item (done or dropped); renew and release are not,
+ * so a lease can always be given back.
+ *
+ * The lease lives in the ledger of the member that owns the work kind file
+ * (#2524 D7), whatever directory the command runs in: `records --json`
+ * reports it from there too.
+ *
+ * Exit codes: 0 when the lease was written, 2 when it was refused (someone
+ * holds it, it expired, another clone got there first), 1 when the command
+ * could not run (usage, an unreadable kind, an unknown item).
+ */
+
+import { dirname, relative } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { parseDuration } from "../op/duration";
+import {
+  claimWorkLease,
+  leaseHistoryPath,
+  listWorkLeases,
+  readLeaseHistory,
+  releaseWorkLease,
+  renewWorkLease,
+  workLeaseRef,
+  WORK_ITEM_ID_PATTERN,
+  type WorkLease,
+  type WorkLeaseRefusal,
+  type WorkLeaseResult,
+  type LeaseHistoryWrite,
+  type LeaseHistoryRecord,
+  type WorkLeaseState,
+} from "../lifecycle/work-lease";
+import { resolveMemberLedger } from "../lifecycle/member-ledger";
+import { readerVersion, WorkspaceReadError } from "./declaration";
+import { declaredKindFiles, readRecordsFor } from "./records-cli";
+import { loadRecordKind, RecordReadError, type LoadedRecordKind, type RecordEntry } from "./records";
+import { gitRoot } from "./record-source";
+import type { ReasonCode } from "./reason-codes";
+
+/** The version of the `work` output this chant writes. */
+export const WORK_LEASE_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for the `--json` output, shipped beside this file. */
+export const WORK_LEASE_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/work-lease/v1/work-lease.schema.json";
+
+export { WORK_LEASE_REFUSALS } from "../lifecycle/work-lease";
+
+const USAGE = [
+  "chant workspace work claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <text>] [--note <text>] [--json]",
+  "chant workspace work history <id> [--kind <kind file>] [--json]",
+].join("\n");
+
+/** Exit code when the lease was refused rather than the command failing. */
+export const EXIT_LEASE_REFUSED = 2;
+
+export type WorkVerb = "claim" | "renew" | "release";
+
+/** Why the command could not run. Closed. */
+export const WORK_ERROR_CODES = [
+  "write-usage-invalid",
+  "kind-unreadable",
+  "work-kind-missing",
+  "work-kind-ambiguous",
+  "work-item-unknown",
+  "work-item-closed",
+  "not-a-git-repository",
+] as const satisfies readonly ReasonCode[];
+export type WorkErrorCode = (typeof WORK_ERROR_CODES)[number];
+
+interface DocHead {
+  $schema: string;
+  contract: number;
+}
+
+/** What `--json` prints. */
+export type WorkLeaseDocument = DocHead &
+  (
+  | {
+      item: string;
+      event: WorkVerb;
+      /** The work kind file, from the repository root. */
+      kind: string;
+      ref: string;
+      lease: Omit<WorkLease, "item">;
+      history: LeaseHistoryWrite;
+    }
+  | {
+      item: string;
+      event: WorkVerb;
+      kind: string;
+      ref: string;
+      refused: { code: WorkLeaseRefusal; message: string; heldBy: Omit<WorkLease, "item"> | null };
+    }
+  | { error: { code: WorkErrorCode; message: string } }
+  );
+
+/** Why a work command could not run, with its code. */
+export class WorkError extends Error {
+  constructor(
+    readonly code: WorkErrorCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** A work item found by id: its kind, its state, its record, and the repository root its path is from. */
+export interface FoundWorkItem {
+  loaded: LoadedRecordKind;
+  state: string | null;
+  record: RecordEntry;
+  root: string;
+}
+
+/**
+ * The work kind holding `id`: the one `kind` names, or the one declared work
+ * kind with a record `id`. Throws a {@link WorkError}.
+ */
+export async function findWorkItem(id: string, cwd: string, kind: string | undefined): Promise<FoundWorkItem> {
+  let candidates: string[];
+  if (kind !== undefined) {
+    candidates = [kind];
+  } else {
+    try {
+      candidates = declaredKindFiles(cwd).map((k) => k.file);
+    } catch (err) {
+      if (!(err instanceof WorkspaceReadError)) throw err;
+      throw new WorkError("work-kind-missing", `${err.code}: ${err.describe()}; without --kind, the declaration names the work kind`);
+    }
+  }
+  const found: FoundWorkItem[] = [];
+  let workKinds = 0;
+  for (const file of candidates) {
+    let loaded: LoadedRecordKind;
+    try {
+      loaded = await loadRecordKind(file, cwd);
+    } catch (err) {
+      if (err instanceof RecordReadError && kind !== undefined) throw new WorkError("kind-unreadable", `${err.code}: ${err.message}`);
+      if (err instanceof RecordReadError) continue;
+      throw err;
+    }
+    if (!loaded.kind.work) {
+      if (kind !== undefined) throw new WorkError("work-kind-missing", `${kind} is the ${loaded.kind.name} kind, which has no work block`);
+      continue;
+    }
+    workKinds++;
+    let read;
+    try {
+      read = await readRecordsFor({ kind: loaded.file, cwd });
+    } catch (err) {
+      if (err instanceof RecordReadError) throw new WorkError("kind-unreadable", `${err.code}: ${err.message}`);
+      throw err;
+    }
+    const record = read.result.records.find((r) => r.id === id);
+    if (record) found.push({ loaded, state: record.state, record, root: read.root });
+  }
+  if (workKinds === 0) throw new WorkError("work-kind-missing", "the declaration names no work kind; pass --kind <kind file>");
+  if (found.length === 0) throw new WorkError("work-item-unknown", `no work record has the id ${id}`);
+  if (found.length > 1) throw new WorkError("work-kind-ambiguous", `${found.length} work kinds have a record ${id}; pass --kind <kind file>`);
+  return found[0];
+}
+
+/** Parse `--ttl`: a whole number of seconds, or a duration such as 10m. */
+export function parseTtl(raw: string): number {
+  if (/^\d+$/.test(raw)) return Number(raw) * 1000;
+  return parseDuration(raw);
+}
+
+export interface WorkLeaseRequest {
+  verb: WorkVerb;
+  id: string;
+  holder: string;
+  cwd: string;
+  kind?: string;
+  ttlMs?: number;
+  token?: string;
+  outcome?: string;
+  note?: string;
+}
+
+/** Run one claim, renew or release and build the document `--json` prints. */
+export async function workLease(req: WorkLeaseRequest): Promise<WorkLeaseDocument> {
+  const doc = { $schema: WORK_LEASE_OUTPUT_SCHEMA_ID, contract: WORK_LEASE_CONTRACT_VERSION };
+  try {
+    if (!WORK_ITEM_ID_PATTERN.test(req.id) || req.id.includes("..")) throw new WorkError("write-usage-invalid", `${JSON.stringify(req.id)} is not a work item id`);
+    if (!gitRoot(req.cwd)) throw new WorkError("not-a-git-repository", "a work lease is a git ref, and this directory is not in a git repository");
+    const { loaded, state, root } = await findWorkItem(req.id, req.cwd, req.kind);
+    if (req.verb === "claim" && state !== null && (loaded.kind.closedStates ?? []).includes(state)) {
+      throw new WorkError("work-item-closed", `${req.id} is ${state}, a closed state; there is no work left to claim`);
+    }
+    const leaseCwd = dirname(loaded.file);
+    const { prefix } = await resolveMemberLedger(leaseCwd);
+    const opts = { cwd: leaseCwd, ...(req.note ? { note: req.note } : {}) };
+    let result: WorkLeaseResult;
+    if (req.verb === "claim") result = await claimWorkLease(req.id, req.holder, { ...opts, ttlMs: req.ttlMs });
+    else if (req.verb === "renew") result = await renewWorkLease(req.id, req.holder, { ...opts, ttlMs: req.ttlMs, token: req.token });
+    else result = await releaseWorkLease(req.id, req.holder, { ...opts, token: req.token, outcome: req.outcome });
+    const head = { ...doc, item: req.id, event: req.verb, kind: relative(root, loaded.file).split("\\").join("/"), ref: workLeaseRef(req.id, prefix) };
+    if (!result.ok) {
+      const heldBy = result.heldBy ? strip(result.heldBy) : null;
+      return { ...head, refused: { code: result.reason, message: result.message, heldBy } };
+    }
+    return { ...head, lease: strip(result.lease), history: result.history };
+  } catch (err) {
+    if (err instanceof WorkError) return { ...doc, error: { code: err.code, message: err.message } };
+    throw err;
+  }
+}
+
+function strip(l: WorkLease): Omit<WorkLease, "item"> {
+  return { holder: l.holder, token: l.token, acquiredAt: l.acquiredAt, expiresAt: l.expiresAt };
+}
+
+// ── work history (#2785) ────────────────────────────────────────────────────
+
+/** The version of the `work history` output this chant writes: read contract 1. */
+export const WORK_HISTORY_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for `work history --json`, shipped beside this file. */
+export const WORK_HISTORY_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/work-history/v1/work-history.schema.json";
+
+/** Why `work history` read nothing. Closed. */
+export const WORK_HISTORY_ERROR_CODES = [
+  "kind-unreadable",
+  "work-kind-missing",
+  "work-kind-ambiguous",
+  "work-item-unknown",
+  "not-a-git-repository",
+] as const satisfies readonly ReasonCode[];
+export type WorkHistoryErrorCode = (typeof WORK_HISTORY_ERROR_CODES)[number];
+
+/**
+ * How a claim ended. `released`: its holder, or someone closing out an
+ * expired lease, gave it back, with an outcome when one was given. `held`: it
+ * is the live lease now. `expired`: it ran out and nobody released it or
+ * claimed the item since. `lost`: it ran out unreleased and another claim
+ * took the item.
+ */
+export type ClaimEnd = "released" | "held" | "expired" | "lost";
+
+/** One claim of a work item: one fencing token, from its claim to how it ended. */
+export interface LeaseClaim {
+  token: string;
+  holder: string;
+  acquiredAt: string;
+  /** The expiry its last claim or renew set. */
+  expiresAt: string;
+  renewals: number;
+  ended: ClaimEnd;
+  /** The release, when it was released. */
+  release: { by: string; at: string; outcome: string | null; note: string | null } | null;
+}
+
+/** What `work history --json` prints. */
+export type WorkHistoryDocument =
+  | {
+      $schema: string;
+      contract: number;
+      chant: string;
+      item: string;
+      /** The work kind file, from the repository root. */
+      kind: string;
+      /** The lease ref. */
+      ref: string;
+      /** The history file on the branch, under the member's prefix when the kind's member has one. */
+      ledger: { branch: string; path: string };
+      /** The lease ref's record now, live or expired, or null when there is none. Read from local refs, without fetching. */
+      lease: (Omit<WorkLease, "item"> & { state: "active" | "expired" }) | null;
+      /** Each claim, oldest first. */
+      claims: LeaseClaim[];
+      /** Every line of the history, oldest first. */
+      events: LeaseHistoryRecord[];
+      /** Lines of the history that are not lease events, left out. */
+      malformed: number;
+      summary: { claims: number; released: number; held: number; expired: number; lost: number; outcomes: Record<string, number> };
+    }
+  | { $schema: string; contract: number; chant: string; error: { code: WorkHistoryErrorCode; message: string } };
+
+/** Fold a history into its claims: one per token, in the order they were first seen. */
+export function claimsOf(events: LeaseHistoryRecord[], live: Pick<WorkLeaseState, "token" | "state"> | null): LeaseClaim[] {
+  const byToken = new Map<string, LeaseClaim>();
+  const order: string[] = [];
+  for (const e of events) {
+    let c = byToken.get(e.token);
+    if (!c) {
+      c = { token: e.token, holder: e.holder, acquiredAt: e.acquiredAt, expiresAt: e.expiresAt, renewals: 0, ended: "expired", release: null };
+      byToken.set(e.token, c);
+      order.push(e.token);
+    }
+    if (e.event === "renew") c.renewals++;
+    if (e.event !== "release") c.expiresAt = e.expiresAt;
+    if (e.event === "release") c.release = { by: e.by, at: e.timestamp, outcome: e.outcome ?? null, note: e.note ?? null };
+  }
+  return order.map((token, i) => {
+    const c = byToken.get(token)!;
+    if (c.release) c.ended = "released";
+    else if (live && live.token === token) c.ended = live.state === "active" ? "held" : "expired";
+    else if (i < order.length - 1) c.ended = "lost";
+    else c.ended = "expired";
+    return c;
+  });
+}
+
+/**
+ * Read work item `id`'s lease history (#2785): every claim, renew and release
+ * on `_leases/<id>.jsonl` in the ledger of the member owning the work kind,
+ * folded into claims. Read from the local `chant/lifecycle` branch and lease
+ * refs; it never fetches, like the other read-contract reads.
+ */
+export async function workHistory(req: { id: string; cwd: string; kind?: string }): Promise<WorkHistoryDocument> {
+  const head = { $schema: WORK_HISTORY_OUTPUT_SCHEMA_ID, contract: WORK_HISTORY_CONTRACT_VERSION, chant: readerVersion() };
+  try {
+    if (!WORK_ITEM_ID_PATTERN.test(req.id) || req.id.includes("..")) throw new WorkError("work-item-unknown", `${JSON.stringify(req.id)} is not a work item id`);
+    if (!gitRoot(req.cwd)) throw new WorkError("not-a-git-repository", "a work lease's history is on the chant/lifecycle branch, and this directory is not in a git repository");
+    const { loaded, root } = await findWorkItem(req.id, req.cwd, req.kind);
+    const leaseCwd = dirname(loaded.file);
+    const { prefix } = await resolveMemberLedger(leaseCwd);
+    const { records: events, malformed } = await readLeaseHistory(req.id, { cwd: leaseCwd });
+    const live = (await listWorkLeases({ cwd: leaseCwd, memberPrefix: prefix })).find((l) => l.item === req.id) ?? null;
+    const claims = claimsOf(events, live);
+    const count = (end: ClaimEnd) => claims.filter((c) => c.ended === end).length;
+    const outcomes: Record<string, number> = {};
+    for (const c of claims) if (c.release?.outcome) outcomes[c.release.outcome] = (outcomes[c.release.outcome] ?? 0) + 1;
+    return {
+      ...head,
+      item: req.id,
+      kind: relative(root, loaded.file).split("\\").join("/"),
+      ref: workLeaseRef(req.id, prefix),
+      ledger: { branch: "chant/lifecycle", path: leaseHistoryPath(req.id, prefix) },
+      lease: live ? { holder: live.holder, token: live.token, acquiredAt: live.acquiredAt, expiresAt: live.expiresAt, state: live.state } : null,
+      claims,
+      events,
+      malformed,
+      summary: { claims: claims.length, released: count("released"), held: count("held"), expired: count("expired"), lost: count("lost"), outcomes },
+    };
+  } catch (err) {
+    if (err instanceof WorkError) return { ...head, error: { code: err.code as WorkHistoryErrorCode, message: err.message } };
+    throw err;
+  }
+}
+
+/** The history as lines for a person. */
+export function formatWorkHistory(doc: Extract<WorkHistoryDocument, { claims: unknown }>): string {
+  const lines = [`${doc.item}: ${doc.ledger.branch}:${doc.ledger.path}`];
+  for (const c of doc.claims) {
+    const how = c.release ? `released${c.release.outcome ? ` ${c.release.outcome}` : ""} by ${c.release.by} at ${c.release.at}` : c.ended === "held" ? `held until ${c.expiresAt}` : `${c.ended}, never released (expired ${c.expiresAt})`;
+    lines.push(`  ${c.acquiredAt}  ${c.holder}  token ${c.token}  ${c.renewals} renewal${c.renewals === 1 ? "" : "s"}  ${how}`);
+  }
+  if (doc.claims.length === 0) lines.push("  never claimed");
+  if (doc.malformed > 0) lines.push(`  ${doc.malformed} malformed line${doc.malformed === 1 ? "" : "s"} left out`);
+  return lines.join("\n");
+}
+
+async function runWorkHistory(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const id = args.extraPositional2;
+  if (!id) {
+    console.error(formatError({ message: "history needs a work item id", hint: USAGE }));
+    return 1;
+  }
+  for (const [flag, v] of [["--holder", args.holder], ["--ttl", args.ttl], ["--token", args.token], ["--outcome", args.outcome], ["--note", args.note]] as const) {
+    if (v !== undefined) {
+      console.error(formatError({ message: `history is a read and takes no ${flag}`, hint: USAGE }));
+      return 1;
+    }
+  }
+  const doc = await workHistory({ id, cwd: process.cwd(), kind: args.kind });
+  if (args.json) console.log(JSON.stringify(doc, null, 2));
+  else if ("error" in doc) console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+  else console.log(formatWorkHistory(doc));
+  return "error" in doc ? 1 : 0;
+}
+
+export async function runWorkspaceWork(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const verb = args.extraPositional;
+  if (verb === "history") return runWorkHistory(ctx);
+  const fail = (message: string): number => {
+    if (args.json) console.log(JSON.stringify({ $schema: WORK_LEASE_OUTPUT_SCHEMA_ID, contract: WORK_LEASE_CONTRACT_VERSION, error: { code: "write-usage-invalid", message } }, null, 2));
+    else console.error(formatError({ message, hint: USAGE }));
+    return 1;
+  };
+  if (verb !== "claim" && verb !== "renew" && verb !== "release") {
+    return fail(verb ? `chant workspace work takes claim, renew, release or history, not ${verb}` : "chant workspace work needs claim, renew, release or history");
+  }
+  const id = args.extraPositional2;
+  if (!id) return fail(`${verb} needs a work item id`);
+  if (!args.holder) return fail(`${verb} needs --holder <name>: who ${verb === "release" ? "gives the lease back" : "holds the lease"}`);
+  if (verb === "release" && args.ttl !== undefined) return fail("release takes no --ttl");
+  if (verb !== "release" && args.outcome !== undefined) return fail(`${verb} takes no --outcome; it is for release`);
+  if (verb === "claim" && args.token !== undefined) return fail("claim takes no --token; a claim mints one");
+  let ttlMs: number | undefined;
+  if (args.ttl !== undefined) {
+    try {
+      ttlMs = parseTtl(args.ttl);
+    } catch {
+      return fail(`--ttl takes seconds or a duration such as 10m, not ${JSON.stringify(args.ttl)}`);
+    }
+    if (ttlMs <= 0) return fail("--ttl must be more than zero");
+  }
+
+  const doc = await workLease({ verb, id, holder: args.holder, cwd: process.cwd(), kind: args.kind, ttlMs, token: args.token, outcome: args.outcome, note: args.note });
+  if (args.json) console.log(JSON.stringify(doc, null, 2));
+  if ("error" in doc) {
+    if (!args.json) console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+    return 1;
+  }
+  if ("refused" in doc) {
+    if (!args.json) console.error(formatError({ message: `${doc.refused.code}: ${doc.refused.message}` }));
+    return EXIT_LEASE_REFUSED;
+  }
+  if (!args.json) {
+    const what = verb === "claim" ? "claimed" : verb === "renew" ? "renewed" : "released";
+    const until = verb === "release" ? "" : ` until ${doc.lease.expiresAt}`;
+    console.log(`${id} ${what} by ${args.holder}${until} (token ${doc.lease.token})`);
+    console.log(`  ${doc.ref}; history ${doc.history.path}${doc.history.pushed ? "" : " (not pushed)"}`);
+  }
+  return 0;
+}