@intentius/chant 0.89.0 → 0.91.0

package/src/workspace/status.ts

@@ -24,7 +24,11 @@
  * The JSON also lists each member's gates, read from its gate ledger on the
  * same branch (#2674, `status-gates.ts`): the state of each, the approvals
  * that count, and the `chant approve` line that answers it. The text view
- * doesn't show them.
+ * doesn't show them. So does each member's box block (#2726): the
+ * capabilities it reaches through a broker, with the broker and the scope a
+ * broker enforces, and, when the block names a host, the box's ports, state
+ * paths and cookie names resolved from its identity (#2727,
+ * `box-isolation.ts`), so a runtime reads them instead of choosing its own.
  */
 
 import { execFileSync } from "node:child_process";
@@ -35,10 +39,14 @@ import type { CommandContext } from "../cli/registry";
 import { GATES_DIR } from "../lifecycle/gate-ledger";
 import { readPathSha } from "../lifecycle/git";
 import { latestPerComponent, readReleaseLedger, type ReleaseRecord } from "../lifecycle/release-ledger";
+import { readReleasePlan, type ReleasePlan } from "../lifecycle/plan-ledger";
+import { listWorkLeases, type WorkLeaseState } from "../lifecycle/work-lease";
 import { findWorkspaceRoot } from "../project-root";
+import { resolveBoxes, type ResolvedIsolation } from "./box-isolation";
 import { readDeclaration, readerVersion, WorkspaceReadError, type ErrorLocation, type Member } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import { GATE_REASON_CODES, readMemberGates, type GateLedgerReader, type StatusGate, type StatusGateLedger } from "./status-gates";
+import { STEWARD_REASON_CODES, readMemberStewards, type StatusSteward, type StewardReasonCode } from "./status-stewards";
 import { gitTop, workingTree } from "./tree";
 import { handToRootChant } from "./which-chant";
 
@@ -71,6 +79,9 @@ export type StatusReasonCode = (typeof STATUS_REASON_CODES)[number];
 /** Why a member's gates can't be listed (#2674). Closed, like {@link STATUS_REASON_CODES}. */
 export const STATUS_GATE_REASON_CODES = GATE_REASON_CODES;
 
+/** Why a member's stewards can't be fully listed (#2731). Closed, like {@link STATUS_REASON_CODES}. */
+export const STATUS_STEWARD_REASON_CODES = STEWARD_REASON_CODES;
+
 /**
  * Why the status couldn't be read at all. The declaration's own codes, except
  * the two that only `--at` returns, and one for the environment name.
@@ -104,6 +115,15 @@ export interface StatusRelease {
   actor: string;
   /** Read flags, such as `legacy-digest` (#2514). */
   flags: string[];
+  /**
+   * The release plan `digest` names, read from `_plans/<digest>.json` on
+   * chant/lifecycle (ws-055, #2733) — the work items and evidence this
+   * release shipped, without the runner's own files. Null when this
+   * checkout has no plan stored under that digest: an ordinary component
+   * release (most releases carry no plan at all), or a plan this checkout
+   * hasn't fetched yet.
+   */
+  plan: ReleasePlan | null;
 }
 
 export interface StatusLedger {
@@ -145,6 +165,29 @@ export interface StatusMember {
   gateLedger: StatusGateLedger;
   /** Each gate in the member's gate ledger, one per environment asked for, sorted by component then gate. */
   gates: StatusGate[];
+  /** The member's box block as declared, or null when it declares none (#2726). A broker reads the scopes it enforces here. */
+  box: StatusBox | null;
+  /** The stewards the member declares (#2731), with their form in `env`, their Ops and each Op's last run. Sorted by name. */
+  stewards: StatusSteward[];
+  /** Why a steward or a last run may be missing from `stewards`. */
+  stewardReasons: { code: StewardReasonCode; message: string }[];
+}
+
+/** A box's brokered capabilities, from the declaration (#2726). */
+export interface StatusBox {
+  capabilities: { name: string; broker: string | null; scope: string[] }[];
+  /** The box's ports, state paths and cookie names, resolved from its identity, or null when the block declares no host (#2727). */
+  isolation: ResolvedIsolation | null;
+}
+
+/**
+ * One work lease (#2732): a work item's lease ref in the ledger of the member
+ * that owns its work kind, read from the local refs without fetching.
+ */
+export interface StatusLease extends Omit<WorkLeaseState, "ref"> {
+  /** The member whose ledger holds the lease, or null for the flat ledger (the root member, or a kind no member owns). */
+  member: string | null;
+  ref: string;
 }
 
 export type StatusDocument =
@@ -157,6 +200,8 @@ export type StatusDocument =
       lifecycle: { ref: string; commit: string | null };
       workspace: { name: string; root: string; file: string };
       members: StatusMember[];
+      /** Every work lease in the workspace's ledgers, active and expired, by member then item (#2732). A released lease has no ref and is not listed. */
+      leases: StatusLease[];
       summary: { members: number; released: number; unreadable: number; differing: number | null };
     }
   | {
@@ -179,6 +224,8 @@ export interface StatusQuery {
   readGates?: GateLedgerReader;
   /** The instant a gate's expiry is measured against; now by default. */
   now?: string;
+  /** Reads one member's stewards; the declaration and ledger reader unless a test swaps it. */
+  readStewards?: typeof readMemberStewards;
 }
 
 class StatusError extends Error {
@@ -240,8 +287,16 @@ async function readEnvironment(member: Member, env: string, cwd: string, read: L
       reason: { code: "ledger-unreadable", message: `${ledger.path}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}` },
     };
   }
-  const releases = [...latestPerComponent(records).values()]
-    .map((r) => ({
+  // A member's plans live beside its other lifecycle stores (#2524 D7,
+  // #2538): _members/<member>/_plans/ for the "members" layout, the flat
+  // top-level _plans/ for "flat" — the same split ledger.path already
+  // resolved above for releases.jsonl, mirrored here since readReleasePlan
+  // reads through one process for every member without changing cwd per
+  // member (see plan-ledger.ts's readReleasePlan doc).
+  const planPrefix = ledger.layout === "members" ? `${MEMBERS_DIR}/${member.name}/` : "";
+  const latest = [...latestPerComponent(records).values()].sort((a, b) => (a.component < b.component ? -1 : a.component > b.component ? 1 : 0));
+  const releases: StatusRelease[] = await Promise.all(
+    latest.map(async (r) => ({
       component: r.component,
       digest: r.digest,
       gitSha: r.gitSha,
@@ -250,8 +305,9 @@ async function readEnvironment(member: Member, env: string, cwd: string, read: L
       timestamp: r.timestamp,
       actor: r.actor,
       flags: [...(r.flags ?? [])],
-    }))
-    .sort((a, b) => (a.component < b.component ? -1 : a.component > b.component ? 1 : 0));
+      plan: await readReleasePlan(r.digest, { cwd, prefix: planPrefix }),
+    })),
+  );
   return {
     env,
     ledger: { ...ledger, shared: false },
@@ -303,12 +359,14 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
     const commit = lifecycleTip(found.dir);
     const now = query.now ?? new Date().toISOString();
 
+    const isolation = new Map(resolveBoxes(declaration).map((b) => [b.member.name, b.isolation]));
     const members: StatusMember[] = [];
     for (const m of declaration.members) {
       const environments: StatusEnvironment[] = [];
       for (const env of envs) environments.push(await readEnvironment(m, env, found.dir, read));
       const own = await hasMemberLedger(m, found.dir);
       const gates = await readMemberGates(own ? `${MEMBERS_DIR}/${m.name}/${GATES_DIR}` : GATES_DIR, own ? "members" : "flat", commit, envs, found.dir, now, query.readGates);
+      const stewards = await (query.readStewards ?? readMemberStewards)(resolve(found.dir, m.dir), query.env, now, m.kind, m.box);
       members.push({
         name: m.name,
         dir: m.dir,
@@ -318,6 +376,15 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
         readable: environments.every((e) => e.reason === null),
         gateLedger: gates.ledger,
         gates: gates.gates,
+        box:
+          m.box === null
+            ? null
+            : {
+                capabilities: m.box.capabilities.map((c) => ({ name: c.name, broker: c.broker, scope: [...c.scope] })),
+                isolation: isolation.get(m.name) ?? null,
+              },
+        stewards: stewards.stewards,
+        stewardReasons: stewards.reasons,
       });
     }
     // Several members read from one flat ledger see the same records; say so.
@@ -327,6 +394,8 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
     const flatGates = members.filter((m) => m.gateLedger.layout === "flat").length;
     for (const m of members) m.gateLedger.shared = m.gateLedger.layout === "flat" && flatGates > 1;
 
+    const leases = await readWorkspaceLeases(declaration.members, found.dir, new Date(now));
+
     return {
       ...head,
       env: query.env,
@@ -334,6 +403,7 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
       lifecycle: { ref: LIFECYCLE_REF, commit },
       workspace: { name: declaration.name, root: rootDir === "" ? "." : rootDir, file: declaration.file },
       members,
+      leases,
       summary: {
         members: members.length,
         released: members.filter((m) => m.environments[0].releases.length > 0).length,
@@ -351,6 +421,21 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
   }
 }
 
+/**
+ * The work leases of the flat ledger and of each member's (#2732). Leases are
+ * env-independent, so the environment asked for doesn't narrow them. Never
+ * fetches: the remote's leases are the ones last fetched.
+ */
+async function readWorkspaceLeases(members: Member[], cwd: string, now: Date): Promise<StatusLease[]> {
+  const ledgers: { member: string | null; prefix: string }[] = [{ member: null, prefix: "" }];
+  for (const m of members) if (m.dir !== ".") ledgers.push({ member: m.name, prefix: `${MEMBERS_DIR}/${m.name}/` });
+  const out: StatusLease[] = [];
+  for (const l of ledgers) {
+    for (const lease of await listWorkLeases({ cwd, memberPrefix: l.prefix, now })) out.push({ ...lease, member: l.member });
+  }
+  return out;
+}
+
 export async function runWorkspaceStatus(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const env = args.extraPositional;
@@ -434,6 +519,22 @@ export function formatStatus(doc: Extract<StatusDocument, { members: unknown }>)
       for (const n of notes.get(i) ?? []) lines.push(n);
     });
   }
+  if (doc.leases.length > 0) {
+    lines.push("");
+    const rows: string[][] = [["WORK ITEM", "HOLDER", "EXPIRES", "STATE"]];
+    for (const l of doc.leases) rows.push([l.member ? `${l.member}/${l.item}` : l.item, l.holder, l.expiresAt, l.state]);
+    lines.push(...table(rows));
+  }
+  const boxes = doc.members.filter((m) => m.box?.isolation);
+  if (boxes.length > 0) {
+    lines.push("");
+    const rows: string[][] = [["BOX", "HOST", "SLOT", "PORTS", "STATE"]];
+    for (const m of boxes) {
+      const i = m.box!.isolation!;
+      rows.push([m.name, i.host, String(i.slot), `${i.portRange.from}-${i.portRange.to}`, i.stateDir]);
+    }
+    lines.push(...table(rows));
+  }
   const s = doc.summary;
   lines.push("");
   lines.push(

package/src/workspace/work-cli.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 or release");
+    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,246 @@
+/**
+ * `chant workspace work claim|renew|release <id> --holder <name>` (#2732,
+ * ws-055): the work lease, who is working on which work item.
+ *
+ * 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,
+  releaseWorkLease,
+  renewWorkLease,
+  workLeaseRef,
+  WORK_ITEM_ID_PATTERN,
+  type WorkLease,
+  type WorkLeaseRefusal,
+  type WorkLeaseResult,
+  type LeaseHistoryWrite,
+} from "../lifecycle/work-lease";
+import { resolveMemberLedger } from "../lifecycle/member-ledger";
+import { WorkspaceReadError } from "./declaration";
+import { declaredKindFiles, readRecordsFor } from "./records-cli";
+import { loadRecordKind, RecordReadError, type LoadedRecordKind } 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]";
+
+/** 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 } }
+  );
+
+class WorkError extends Error {
+  constructor(
+    readonly code: WorkErrorCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** The work kind holding `id`: the one `kind` names, or the one declared work kind with a record `id`. */
+async function findWorkItem(id: string, cwd: string, kind: string | undefined): Promise<{ loaded: LoadedRecordKind; state: string | null; root: string }> {
+  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: { loaded: LoadedRecordKind; state: string | null; root: string }[] = [];
+  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, 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 };
+}
+
+export async function runWorkspaceWork(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const verb = args.extraPositional;
+  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 or release, not ${verb}` : "chant workspace work needs claim, renew or release");
+  }
+  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;
+}