@intentius/chant 0.101.0 → 0.104.0

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

@@ -158,12 +158,39 @@ describe("chant workspace work (#2732)", () => {
     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");
+    expect(verb.stderr).toContain("claim, renew, release, history or evidence");
     const noHolder = await chant(root, ["workspace", "work", "claim", "W-001"]);
     expect(noHolder.code).toBe(1);
     expect(noHolder.stderr).toContain("--holder");
   }, 120_000);
 
+  test("evidence (#3159): needs the holder, the token and the entry, runs only under the live lease, and names only a criterion the item lists", async () => {
+    const entry = JSON.stringify({ criterion: "AC-1", result: "pass", title: "The test", url: "https://example.com/ci/1" });
+    const usage = await chant(root, ["workspace", "work", "evidence", "W-002", "--holder", "a", "--from", "-"]);
+    expect(usage.code).toBe(1);
+    expect(JSON.parse(usage.stdout).error).toMatchObject({ code: "write-usage-invalid", message: expect.stringContaining("--token") });
+    const evidence = (holder: string, token: string) =>
+      new Promise<Run>((resolve) => {
+        const child = spawn(CHANT[0], [...CHANT.slice(1), "workspace", "work", "evidence", "W-002", "--holder", holder, "--token", token, "--from", "-"], { cwd: root, env: { ...process.env, NO_COLOR: "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 }));
+        child.stdin.end(entry);
+      });
+    // worker-d holds W-002 since the records test above: anyone else is refused.
+    const held = json(await chant(root, ["workspace", "work", "claim", "W-002", "--holder", "ev", "--json"])).refused.heldBy as { holder: string; token: string };
+    const other = await evidence("ev", "none");
+    expect(other.code).toBe(1);
+    expect(JSON.parse(other.stdout).error.code).toBe("lease-held");
+    const stale = await evidence(held.holder, "not-the-token");
+    expect(JSON.parse(stale.stdout).error.code).toBe("lease-token-mismatch");
+    const unlisted = await evidence(held.holder, held.token);
+    expect(unlisted.code).toBe(1);
+    expect(JSON.parse(unlisted.stdout).error.code).toBe("work-criterion-unknown");
+  }, 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);

package/src/workspace/work-cli.ts

@@ -4,6 +4,10 @@
  * workspace work history <id>` (#2785): the item's lease history, each claim
  * and how it ended, a read-contract output (`work-history.schema.json`).
  *
+ * And `chant workspace work evidence <id>` (#3159): the `workEvidence`
+ * activity as a command, so a writer outside an Op attaches evidence under
+ * the lease it holds.
+ *
  * 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
@@ -26,13 +30,18 @@ import type { CommandContext } from "../cli/registry";
 import { parseDuration } from "../op/duration";
 import {
   claimWorkLease,
+  isWorkLeaseOutcome,
   leaseHistoryPath,
+  listKeptAttempts,
   listWorkLeases,
+  outcomeCountsAsAttempt,
   readLeaseHistory,
   releaseWorkLease,
   renewWorkLease,
   workLeaseRef,
   WORK_ITEM_ID_PATTERN,
+  WORK_LEASE_OUTCOMES,
+  type KeptAttempt,
   type WorkLease,
   type WorkLeaseRefusal,
   type WorkLeaseResult,
@@ -46,6 +55,7 @@ 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";
+import { replicateAfter } from "./wip";
 
 /** The version of the `work` output this chant writes. */
 export const WORK_LEASE_CONTRACT_VERSION = 1;
@@ -53,11 +63,12 @@ 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";
+export { WORK_LEASE_REFUSALS, WORK_LEASE_OUTCOMES } 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 claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <outcome>] [--note <text>] [--json]",
   "chant workspace work history <id> [--kind <kind file>] [--json]",
+  "chant workspace work evidence <id> --holder <name> --token <token> --from <file|-> [--kind <kind file>]",
 ].join("\n");
 
 /** Exit code when the lease was refused rather than the command failing. */
@@ -193,6 +204,9 @@ export async function workLease(req: WorkLeaseRequest): Promise<WorkLeaseDocumen
   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 (req.outcome !== undefined && !isWorkLeaseOutcome(req.outcome)) {
+      throw new WorkError("write-usage-invalid", `${JSON.stringify(req.outcome)} is not a lease outcome: use one of ${WORK_LEASE_OUTCOMES.join(", ")}`);
+    }
     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)) {
@@ -210,6 +224,8 @@ export async function workLease(req: WorkLeaseRequest): Promise<WorkLeaseDocumen
       const heldBy = result.heldBy ? strip(result.heldBy) : null;
       return { ...head, refused: { code: result.reason, message: result.message, heldBy } };
     }
+    // #3172: a box's replicate policy may push its work in progress once a lease is released. Best effort; status shows what is behind.
+    if (req.verb === "release") replicateAfter("release", req.cwd);
     return { ...head, lease: strip(result.lease), history: result.history };
   } catch (err) {
     if (err instanceof WorkError) return { ...doc, error: { code: err.code, message: err.message } };
@@ -259,6 +275,27 @@ export interface LeaseClaim {
   ended: ClaimEnd;
   /** The release, when it was released. */
   release: { by: string; at: string; outcome: string | null; note: string | null } | null;
+  /**
+   * Whether the claim counts toward the item's attempt limit (#3147): one
+   * released `not_done` or `abandoned`, with no outcome or an outcome from
+   * before the list was closed, or one that expired or was lost unreleased.
+   * Not one that is held, and not one released with any other outcome.
+   */
+  attempt: boolean;
+  /** The ref keeping this claim's unfinished work, `refs/chant/kept/.../<item>/<token>`, or null. */
+  kept: string | null;
+}
+
+/** An item's attempts against its limit (#3147). */
+export interface WorkAttempts {
+  /** The claims that count as attempts. */
+  failed: number;
+  /** The item's limit: its own field, else its kind's default; null when neither declares one. */
+  limit: number | null;
+  /** How many attempts are left, never below 0; null without a limit. */
+  remaining: number | null;
+  /** True once failed reaches the limit: a runner leaves the item to people. */
+  exhausted: boolean;
 }
 
 /** What `work history --json` prints. */
@@ -283,17 +320,21 @@ export type WorkHistoryDocument =
       /** 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> };
+      /** The item's attempts against its limit (#3147). */
+      attempts: WorkAttempts;
+      /** Every kept attempt of the item, by ref (#3147). */
+      kept: KeptAttempt[];
     }
   | { $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[] {
+export function claimsOf(events: LeaseHistoryRecord[], live: Pick<WorkLeaseState, "token" | "state"> | null, kept: readonly KeptAttempt[] = []): 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 };
+      c = { token: e.token, holder: e.holder, acquiredAt: e.acquiredAt, expiresAt: e.expiresAt, renewals: 0, ended: "expired", release: null, attempt: false, kept: null };
       byToken.set(e.token, c);
       order.push(e.token);
     }
@@ -307,10 +348,30 @@ export function claimsOf(events: LeaseHistoryRecord[], live: Pick<WorkLeaseState
     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";
+    c.attempt = c.ended === "released" ? outcomeCountsAsAttempt(c.release?.outcome) : c.ended !== "held";
+    c.kept = kept.find((k) => k.token === token)?.ref ?? null;
     return c;
   });
 }
 
+/**
+ * The attempt limit of a work record (#3147): the integer in the field the
+ * kind's `work.attempts.field` names, else the kind's `work.attempts.max`;
+ * null when the kind declares no attempts.
+ */
+export function attemptLimit(kind: LoadedRecordKind["kind"], data: Record<string, unknown> | null): number | null {
+  const spec = kind.work?.attempts;
+  if (!spec) return null;
+  const own = data?.[spec.field];
+  return typeof own === "number" && Number.isInteger(own) && own >= 1 ? own : spec.max;
+}
+
+/** Count `claims`' attempts against `limit`. */
+export function attemptsOf(claims: readonly LeaseClaim[], limit: number | null): WorkAttempts {
+  const failed = claims.filter((c) => c.attempt).length;
+  return { failed, limit, remaining: limit === null ? null : Math.max(0, limit - failed), exhausted: limit !== null && failed >= limit };
+}
+
 /**
  * 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,
@@ -322,12 +383,13 @@ export async function workHistory(req: { id: string; cwd: string; kind?: string
   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 { loaded, root, record } = await findWorkItem(req.id, req.cwd, req.kind);
     const leaseCwd = dirname(loaded.file);
-    const { prefix } = await resolveMemberLedger(leaseCwd);
+    const { prefix, members } = 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 kept = await listKeptAttempts(req.id, { cwd: leaseCwd, members });
+    const claims = claimsOf(events, live, kept);
     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;
@@ -342,6 +404,8 @@ export async function workHistory(req: { id: string; cwd: string; kind?: string
       events,
       malformed,
       summary: { claims: claims.length, released: count("released"), held: count("held"), expired: count("expired"), lost: count("lost"), outcomes },
+      attempts: attemptsOf(claims, attemptLimit(loaded.kind, record.data)),
+      kept,
     };
   } catch (err) {
     if (err instanceof WorkError) return { ...head, error: { code: err.code as WorkHistoryErrorCode, message: err.message } };
@@ -357,10 +421,73 @@ export function formatWorkHistory(doc: Extract<WorkHistoryDocument, { claims: un
     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");
+  const a = doc.attempts;
+  if (a.limit !== null) lines.push(`  ${a.failed} of ${a.limit} attempt${a.limit === 1 ? "" : "s"} used${a.exhausted ? "; left to people" : ""}`);
+  else if (a.failed > 0) lines.push(`  ${a.failed} attempt${a.failed === 1 ? "" : "s"} counted; the kind declares no limit`);
+  for (const k of doc.kept) lines.push(`  kept: ${k.ref} (${k.commit.slice(0, 12)})`);
   if (doc.malformed > 0) lines.push(`  ${doc.malformed} malformed line${doc.malformed === 1 ? "" : "s"} left out`);
   return lines.join("\n");
 }
 
+/**
+ * `chant workspace work evidence <id> --holder <name> --token <token> --from
+ * <file|->` (#3159): the `workEvidence` activity (#2772) as a command, so a
+ * writer that is not an Op, such as hud, attaches evidence through chant under
+ * the lease it holds. `--from` gives the entry as JSON: criterion, result,
+ * title, a url or a path, and optionally as_of. It always prints the
+ * work-evidence document; exit 0 when the entry was appended, 1 otherwise.
+ */
+async function runWorkEvidence(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const { attachWorkEvidence, WORK_EVIDENCE_CONTRACT_VERSION, WORK_EVIDENCE_OUTPUT_SCHEMA_ID } = await import("./work-evidence");
+  const print = (doc: unknown, code: number): number => {
+    console.log(JSON.stringify(doc, null, 2));
+    return code;
+  };
+  const fail = (message: string): number =>
+    print({ $schema: WORK_EVIDENCE_OUTPUT_SCHEMA_ID, contract: WORK_EVIDENCE_CONTRACT_VERSION, error: { code: "write-usage-invalid", message: `${message}\n${USAGE}` } }, 1);
+  const id = args.extraPositional2;
+  if (!id) return fail("evidence needs a work item id");
+  if (!args.holder) return fail("evidence needs --holder <name>: the lease's holder");
+  if (!args.token) return fail("evidence needs --token <token>: the lease's fencing token, as its claim printed it");
+  if (args.migrateFrom === undefined) return fail("evidence needs --from <file|->: the entry as JSON, with criterion, result, title and a url or a path");
+  for (const [flag, v] of [["--ttl", args.ttl], ["--outcome", args.outcome], ["--note", args.note]] as const) {
+    if (v !== undefined) return fail(`evidence takes no ${flag}`);
+  }
+  let fields: Record<string, unknown>;
+  try {
+    const { readFileSync } = await import("node:fs");
+    const { resolve } = await import("node:path");
+    const text = readFileSync(args.migrateFrom === "-" ? 0 : resolve(process.cwd(), args.migrateFrom), "utf-8");
+    const parsed: unknown = JSON.parse(text);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("the entry is not a JSON object");
+    fields = parsed as Record<string, unknown>;
+  } catch (err) {
+    return print(
+      { $schema: WORK_EVIDENCE_OUTPUT_SCHEMA_ID, contract: WORK_EVIDENCE_CONTRACT_VERSION, error: { code: "write-input-invalid", message: `--from ${args.migrateFrom} could not be read: ${err instanceof Error ? err.message : String(err)}` } },
+      1,
+    );
+  }
+  const known = ["criterion", "result", "title", "url", "path", "as_of"];
+  const unknown = Object.keys(fields).filter((k) => !known.includes(k));
+  if (unknown.length > 0) return fail(`the entry takes ${known.join(", ")}, not ${unknown.join(", ")}`);
+  const str = (k: string): string | undefined => (typeof fields[k] === "string" ? (fields[k] as string) : undefined);
+  const doc = await attachWorkEvidence({
+    cwd: process.cwd(),
+    item: id,
+    kind: args.kind,
+    holder: args.holder,
+    token: args.token,
+    criterion: str("criterion") ?? "",
+    result: fields.result as never,
+    title: str("title") ?? "",
+    url: str("url"),
+    path: str("path"),
+    asOf: str("as_of"),
+  });
+  return print(doc, "error" in doc ? 1 : 0);
+}
+
 async function runWorkHistory(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const id = args.extraPositional2;
@@ -385,13 +512,14 @@ export async function runWorkspaceWork(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const verb = args.extraPositional;
   if (verb === "history") return runWorkHistory(ctx);
+  if (verb === "evidence") return runWorkEvidence(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");
+    return fail(verb ? `chant workspace work takes claim, renew, release, history or evidence, not ${verb}` : "chant workspace work needs claim, renew, release, history or evidence");
   }
   const id = args.extraPositional2;
   if (!id) return fail(`${verb} needs a work item id`);

package/src/workspace/work-evidence.schema.json

@@ -182,9 +182,14 @@
                 "amend-supersede-instead",
                 "record-sign-failed",
                 "ratify-quorum-not-met",
+                "record-conflict",
+                "write-lock-timeout",
+                "write-lock-not-held",
                 "write-scope-member",
                 "write-scope-kind",
+                "write-scope-class-unknown",
                 "agent-unknown",
+                "principal-unidentified",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",

package/src/workspace/work-history.schema.json

@@ -65,7 +65,7 @@
         },
         "outcome": {
           "type": "string",
-          "description": "How the work ended, on a release. Free text such as done, not_done, gated or waiting."
+          "description": "How the work ended, on a release: one of the closed list in work-lease.schema.json's $defs/outcome (#3147), done, not_done, abandoned, gated, waiting, dropped, redraft or ask. A line written before #3147 may hold other free text."
         },
         "note": {
           "type": "string"
@@ -146,6 +146,17 @@
               }
             }
           ]
+        },
+        "attempt": {
+          "type": "boolean",
+          "description": "Added in contract 1 by #3147. Whether the claim counts toward the item's attempt limit: released not_done or abandoned, released with no outcome or with free text from before the outcomes were closed, or ended expired or lost. Never one that is held, and never one released done, gated, waiting, dropped, redraft or ask."
+        },
+        "kept": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Added in contract 1 by #3147. The ref keeping the claim's unfinished work, refs/chant/kept/[<member>/]<item>/<token>, written when a run that changes the checkout ended not_done; null when there is none."
         }
       }
     },
@@ -300,6 +311,67 @@
               "description": "How many released claims gave each outcome."
             }
           }
+        },
+        "attempts": {
+          "type": "object",
+          "description": "Added in contract 1 by #3147. The item's attempts against its limit. limit is the item's own field named by the kind's work.attempts.field, else the kind's work.attempts.max, else null. A runner leaves an exhausted item to people.",
+          "required": [
+            "failed",
+            "limit",
+            "remaining",
+            "exhausted"
+          ],
+          "properties": {
+            "failed": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "The claims whose attempt is true."
+            },
+            "limit": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 1
+            },
+            "remaining": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0,
+              "description": "limit minus failed, never below 0; null without a limit."
+            },
+            "exhausted": {
+              "type": "boolean",
+              "description": "True once failed reaches the limit; false without one."
+            }
+          }
+        },
+        "kept": {
+          "type": "array",
+          "description": "Added in contract 1 by #3147. Every kept attempt of the item, from the local refs under refs/chant/kept/[<member>/]<item>/, sorted by ref.",
+          "items": {
+            "type": "object",
+            "required": [
+              "token",
+              "ref",
+              "commit"
+            ],
+            "properties": {
+              "token": {
+                "type": "string",
+                "description": "The lease token the attempt ran under."
+              },
+              "ref": {
+                "type": "string"
+              },
+              "commit": {
+                "type": "string",
+                "description": "The commit the ref points at."
+              }
+            }
+          }
         }
       }
     },

package/src/workspace/work-history.test.ts

@@ -9,14 +9,14 @@ import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { cleanScratch, contract, git, REPO, repo } from "./__fixtures__/contract-repo";
 import { claimWorkLease, releaseWorkLease, renewWorkLease, type LeaseHistoryRecord } from "../lifecycle/work-lease";
-import { claimsOf, formatWorkHistory, workHistory, type WorkHistoryDocument } from "./work-cli";
+import { claimsOf, formatWorkHistory, workHistory, workLease, type WorkHistoryDocument } from "./work-cli";
 import historySchema from "./work-history.schema.json";
 
 const REF = join(REPO, "reference-workspace");
 const { expectValid } = contract(historySchema);
 
-function work(id: string): 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: [] };
+function work(id: string, extra: 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: [], ...extra };
   return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
 }
 
@@ -46,6 +46,7 @@ beforeAll(() => {
     "design/work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
     "design/work/W-001-one.md": work("W-001"),
     "design/work/W-002-two.md": work("W-002"),
+    "design/work/W-004-four.md": work("W-004", { max_attempts: 2 }),
   });
   git(root, "config", "user.name", "History Test");
   git(root, "config", "user.email", "history@example.com");
@@ -88,6 +89,10 @@ describe("workspace work history (#2785)", () => {
     ]);
     expect(doc.events.map((e) => e.event)).toEqual(["claim", "renew", "release", "claim", "claim"]);
     expect(doc.summary).toEqual({ claims: 3, released: 1, held: 0, expired: 1, lost: 1, outcomes: { not_done: 1 } });
+    // Each of the three counts as an attempt (#3147): not_done, lost and expired, against the kind's default of 3.
+    expect(doc.claims.map((c) => c.attempt)).toEqual([true, true, true]);
+    expect(doc.attempts).toEqual({ failed: 3, limit: 3, remaining: 0, exhausted: true });
+    expect(formatWorkHistory(doc)).toContain("3 of 3 attempts used; left to people");
     // The history file is where git would find it, under the member's prefix.
     expect(git(root, "show", `chant/lifecycle:${doc.ledger.path}`).split("\n")).toHaveLength(5);
     expect(formatWorkHistory(doc)).toContain("released not_done by steward/dispatch@1");
@@ -107,6 +112,37 @@ describe("workspace work history (#2785)", () => {
     expect(doc.claims.map((c) => c.ended)).toEqual(["released", "held"]);
     expect(doc.lease).toMatchObject({ holder: "worker-b", token: live.lease.token, state: "active" });
     expect(doc.summary.outcomes).toEqual({ done: 1 });
+    expect(doc.attempts).toEqual({ failed: 0, limit: 3, remaining: 3, exhausted: false });
+  });
+
+  test("outcomes that built nothing don't count as attempts, the item's max_attempts overrides the kind's, and kept attempts are listed (#3147)", async () => {
+    const now = () => new Date();
+    const tokens: string[] = [];
+    for (const outcome of ["dropped", "redraft", "ask", "waiting", "gated", "not_done"]) {
+      const c = await claimWorkLease("W-004", "worker-a", { cwd: kindDir, now });
+      if (!c.ok) throw new Error(c.message);
+      tokens.push(c.lease.token);
+      await releaseWorkLease("W-004", "worker-a", { cwd: kindDir, now, token: c.lease.token, outcome });
+    }
+    // The not_done attempt's work, kept the way a run that changes the checkout keeps it.
+    const kept = `refs/chant/kept/design/W-004/${tokens[5]}`;
+    git(root, "update-ref", kept, "HEAD");
+
+    const doc = await workHistory({ id: "W-004", cwd: root });
+    expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.claims.map((c) => c.attempt)).toEqual([false, false, false, false, false, true]);
+    expect(doc.attempts).toEqual({ failed: 1, limit: 2, remaining: 1, exhausted: false });
+    expect(doc.claims.map((c) => c.kept)).toEqual([null, null, null, null, null, kept]);
+    expect(doc.kept).toEqual([{ token: tokens[5], ref: kept, commit: git(root, "rev-parse", "HEAD").trim() }]);
+    expect(formatWorkHistory(doc)).toContain(`kept: ${kept}`);
+  });
+
+  test("a release outside the closed list of outcomes is refused (#3147)", async () => {
+    await expect(releaseWorkLease("W-002", "worker-b", { cwd: kindDir, outcome: "skipped" })).rejects.toThrow(/not a work lease outcome/);
+    const doc = await workLease({ verb: "release", id: "W-002", holder: "worker-b", cwd: root, outcome: "skipped" });
+    expect(doc).toMatchObject({ error: { code: "write-usage-invalid" } });
+    expect((doc as { error: { message: string } }).error.message).toMatch(/done, not_done, abandoned, gated, waiting, dropped, redraft, ask/);
   });
 
   test("an item never claimed has no claims; an unknown item is an error", async () => {
@@ -142,12 +178,19 @@ describe("claimsOf", () => {
   });
 
   test("a release by someone closing out an expired lease keeps the holder and records who released it", () => {
-    const claims = claimsOf([e("claim", "a"), e("release", "a", { by: "janitor", outcome: "expired" })], null);
+    const claims = claimsOf([e("claim", "a"), e("release", "a", { by: "janitor", outcome: "abandoned" })], null);
     expect(claims).toEqual([
-      { token: "a", holder: "h-a", acquiredAt: "2026-09-25T00:00:00.000Z", expiresAt: "2026-09-25T00:10:00.000Z", renewals: 0, ended: "released", release: { by: "janitor", at: "2026-09-25T00:00:00.000Z", outcome: "expired", note: null } },
+      { token: "a", holder: "h-a", acquiredAt: "2026-09-25T00:00:00.000Z", expiresAt: "2026-09-25T00:10:00.000Z", renewals: 0, ended: "released", release: { by: "janitor", at: "2026-09-25T00:00:00.000Z", outcome: "abandoned", note: null }, attempt: true, kept: null },
     ]);
   });
 
+  test("a release with free text from before the outcomes were closed counts as an attempt, and one with no outcome too", () => {
+    expect(claimsOf([e("claim", "a"), e("release", "a", { outcome: "skipped" })], null)[0].attempt).toBe(true);
+    expect(claimsOf([e("claim", "a"), e("release", "a")], null)[0].attempt).toBe(true);
+    expect(claimsOf([e("claim", "a"), e("release", "a", { outcome: "done" })], null)[0].attempt).toBe(false);
+    expect(claimsOf([e("claim", "a")], { token: "a", state: "active" })[0].attempt).toBe(false);
+  });
+
   test("the live ref decides between held and expired for the newest claim", () => {
     expect(claimsOf([e("claim", "a")], { token: "a", state: "active" })[0].ended).toBe("held");
     expect(claimsOf([e("claim", "a")], { token: "a", state: "expired" })[0].ended).toBe("expired");