@pmelab/gtd 59.0.0 → 59.0.1

package/src/gherkin/index.ts

@@ -21,6 +21,10 @@ import {
   type TestRepo,
   type WorkflowModule,
 } from "../testkit/index.js"
+import { assertContains, assertLacks, refusal, refusedWith, restDescription } from "./messages.js"
+
+// Kept off the class so the exported world's type stays as it is.
+const usedActors = new WeakMap<TestkitWorld, Set<string>>()
 
 export class TestkitWorld extends QuickPickleWorld {
   // Re-declared: under `nodenext` a subclass loses the base's members from TS's view.
@@ -88,6 +92,8 @@ export class TestkitWorld extends QuickPickleWorld {
 
   async drive(): Promise<void> {
     const actors: Record<string, Actor> = {}
+    const used = usedActors.get(this) ?? new Set<string>()
+    usedActors.set(this, used)
     for (const [step, actions] of this.actions) {
       actors[step] = async (beat, repo) => {
         for (const action of actions) await action(beat, repo)
@@ -115,7 +121,14 @@ export class TestkitWorld extends QuickPickleWorld {
         return hit[1]
       }
     }
-    await this.repo().drive(actors)
+    const tracked: Record<string, Actor> = {}
+    for (const [step, actor] of Object.entries(actors)) {
+      tracked[step] = (beat, repo) => {
+        used.add(step)
+        return actor(beat, repo)
+      }
+    }
+    await this.repo().drive(tracked)
   }
 }
 
@@ -125,6 +138,29 @@ const withNewline = (content: string): string => (content.endsWith("\n") ? conte
 
 const args = (list: string): string[] => list.split(" ").filter((arg) => arg !== "")
 
+const neverUsed = (world: TestkitWorld): string[] => {
+  const used = usedActors.get(world) ?? new Set<string>()
+  const scripted = new Set([
+    ...world.actions.keys(),
+    ...world.verdicts.keys(),
+    ...world.conditionalVerdicts.keys(),
+  ])
+  return [...scripted].filter((step) => !used.has(step))
+}
+
+/** An outcome step: a failure ends with where the process rests. */
+const outcome =
+  <A extends unknown[]>(check: (world: TestkitWorld, ...rest: A) => unknown) =>
+  async (world: TestkitWorld, ...rest: A): Promise<void> => {
+    try {
+      await check(world, ...rest)
+    } catch (error) {
+      const failure = error instanceof Error ? error : new Error(String(error))
+      failure.message += `\n\n${await restDescription(() => world.repo(), neverUsed(world))}`
+      throw failure
+    }
+  }
+
 Given("a gtd config with:", (world: TestkitWorld, source: string) => {
   world.configure(withNewline(source))
 })
@@ -337,74 +373,86 @@ When("the process is driven", async (world: TestkitWorld) => {
 
 Then(
   "opening door {string} is refused with {string}",
-  async (world: TestkitWorld, door: string, message: string) => {
-    await assert.rejects(world.repo().door(door), (error: Error) => error.message.includes(message))
-  },
+  outcome(async (world, door: string, message: string) => {
+    await refusedWith(world.repo().door(door), message)
+  }),
 )
 
 Then(
   "starting workflow {string} with {string} is refused with {string}",
-  async (world: TestkitWorld, workflow: string, list: string, message: string) => {
-    await assert.rejects(world.repo().start(workflow, ...args(list)), (error: Error) =>
-      error.message.includes(message),
-    )
-  },
+  outcome(async (world, workflow: string, list: string, message: string) => {
+    await refusedWith(world.repo().start(workflow, ...args(list)), message)
+  }),
 )
 
-Then("landing is refused with {string}", async (world: TestkitWorld, message: string) => {
-  await assert.rejects(world.repo().land(), (error: Error) => error.message.includes(message))
-})
+Then(
+  "landing is refused with {string}",
+  outcome(async (world, message: string) => {
+    await refusedWith(world.repo().land(), message)
+  }),
+)
 
 Then(
   "driving the process is refused with {string}",
-  async (world: TestkitWorld, message: string) => {
-    await assert.rejects(world.drive(), (error: Error) => error.message.includes(message))
-  },
+  outcome(async (world, message: string) => {
+    await refusedWith(world.drive(), message)
+  }),
 )
 
 Then(
   "driving the process is refused without {string}",
-  async (world: TestkitWorld, message: string) => {
-    await assert.rejects(world.drive(), (error: Error) => !error.message.includes(message))
-  },
+  outcome(async (world, message: string) => {
+    const got = await refusal(world.drive(), `without "${message}"`)
+    if (got.includes(message))
+      assert.fail(`expected a refusal without "${message}", but it was refused with:\n${got}`)
+  }),
 )
 
-Then("the process rests at {string}", async (world: TestkitWorld, step: string) => {
-  assert.strictEqual((await world.repo().next()).state, step)
-})
+Then(
+  "the process rests at {string}",
+  outcome(async (world, step: string) => {
+    assert.strictEqual((await world.repo().next()).state, step)
+  }),
+)
 
-Then("the resting step's content contains {string}", async (world: TestkitWorld, text: string) => {
-  const { content } = await world.repo().next()
-  assert.ok(content.includes(text), content)
-})
+Then(
+  "the resting step's content contains {string}",
+  outcome(async (world, text: string) => {
+    assertContains("the resting step's content", text, (await world.repo().next()).content)
+  }),
+)
 
 Then(
   "the resting step's content contains the hash of the commit {string}",
-  async (world: TestkitWorld, subject: string) => {
+  outcome(async (world, subject: string) => {
     const repo = world.repo()
     const hash = repo.hashes()[repo.subjects().lastIndexOf(subject)]
     assert.ok(hash !== undefined, `no commit "${subject}"`)
-    const { content } = await repo.next()
-    assert.ok(content.includes(hash), content)
-  },
+    assertContains("the resting step's content", hash, (await repo.next()).content)
+  }),
 )
 
 Then(
   "the resting step's content does not contain {string}",
-  async (world: TestkitWorld, text: string) => {
-    const { content } = await world.repo().next()
-    assert.ok(!content.includes(text), content)
-  },
+  outcome(async (world, text: string) => {
+    assertLacks("the resting step's content", text, (await world.repo().next()).content)
+  }),
 )
 
-Then("the last commit subject is {string}", (world: TestkitWorld, subject: string) => {
-  assert.strictEqual(world.repo().subjects().at(-1), subject)
-})
+Then(
+  "the last commit subject is {string}",
+  outcome((world, subject: string) => {
+    assert.strictEqual(world.repo().subjects().at(-1), subject)
+  }),
+)
 
-Then("the commit subjects end with:", (world: TestkitWorld, list: string) => {
-  const expected = list.split("\n").filter((line) => line.trim() !== "")
-  assert.deepStrictEqual(world.repo().subjects().slice(-expected.length), expected)
-})
+Then(
+  "the commit subjects end with:",
+  outcome((world, list: string) => {
+    const expected = list.split("\n").filter((line) => line.trim() !== "")
+    assert.deepStrictEqual(world.repo().subjects().slice(-expected.length), expected)
+  }),
+)
 
 const outputOf = async (world: TestkitWorld, list: string): Promise<string> => {
   const result = await world.repo().gtd(...args(list))
@@ -414,61 +462,77 @@ const outputOf = async (world: TestkitWorld, list: string): Promise<string> => {
 
 Then(
   "the output of gtd {string} contains {string}",
-  async (world: TestkitWorld, list: string, text: string) => {
-    const out = await outputOf(world, list)
-    assert.ok(out.includes(text), out)
-  },
+  outcome(async (world, list: string, text: string) => {
+    assertContains(`the output of gtd ${list}`, text, await outputOf(world, list))
+  }),
 )
 
 Then(
   "the output of gtd {string} does not contain {string}",
-  async (world: TestkitWorld, list: string, text: string) => {
-    const out = await outputOf(world, list)
-    assert.ok(!out.includes(text), out)
-  },
+  outcome(async (world, list: string, text: string) => {
+    assertLacks(`the output of gtd ${list}`, text, await outputOf(world, list))
+  }),
 )
 
 Then(
   "the output lines of gtd {string} start with:",
-  async (world: TestkitWorld, list: string, prefixes: string) => {
+  outcome(async (world, list: string, prefixes: string) => {
     const out = (await outputOf(world, list)).split("\n").filter((line) => line !== "")
     const expected = prefixes.split("\n").filter((line) => line.trim() !== "")
-    assert.strictEqual(out.length, expected.length, out.join("\n"))
-    out.forEach((line, i) => assert.ok(line.startsWith(expected[i]!), out.join("\n")))
-  },
+    const sides = `expected lines starting with:\n${expected.join("\n")}\ngot:\n${out.join("\n")}`
+    assert.strictEqual(out.length, expected.length, sides)
+    out.forEach((line, i) => assert.ok(line.startsWith(expected[i]!), sides))
+  }),
 )
 
-Then("{string} contains {string}", (world: TestkitWorld, path: string, text: string) => {
-  assert.ok(world.repo().read(path)?.includes(text), `${path}: ${world.repo().read(path)}`)
-})
+Then(
+  "{string} contains {string}",
+  outcome((world, path: string, text: string) => {
+    assertContains(`"${path}"`, text, world.repo().read(path))
+  }),
+)
 
-Then("{string} contains:", (world: TestkitWorld, path: string, text: string) => {
-  assert.ok(world.repo().read(path)?.includes(text), `${path}: ${world.repo().read(path)}`)
-})
+Then(
+  "{string} contains:",
+  outcome((world, path: string, text: string) => {
+    assertContains(`"${path}"`, text, world.repo().read(path))
+  }),
+)
 
 Then(
   "{string} contains the short hash of the commit {string}",
-  (world: TestkitWorld, path: string, subject: string) => {
+  outcome((world, path: string, subject: string) => {
     const repo = world.repo()
     const hash = repo.hashes()[repo.subjects().lastIndexOf(subject)]
     assert.ok(hash !== undefined, `no commit "${subject}"`)
-    assert.ok(repo.read(path)?.includes(hash.slice(0, 7)), `${path}: ${repo.read(path)}`)
-  },
+    assertContains(`"${path}"`, hash.slice(0, 7), repo.read(path))
+  }),
 )
 
 Then(
   "{string} contains {string} exactly once",
-  (world: TestkitWorld, path: string, text: string) => {
+  outcome((world, path: string, text: string) => {
     const content = world.repo().read(path) ?? ""
-    assert.strictEqual(content.split(text).length - 1, 1, `${path}: ${content}`)
-  },
+    const times = content.split(text).length - 1
+    assert.strictEqual(
+      times,
+      1,
+      `"${path}" contains "${text}" ${times} times; it holds:\n${content}`,
+    )
+  }),
 )
 
-Then("{string} does not contain {string}", (world: TestkitWorld, path: string, text: string) => {
-  const content = world.repo().read(path)
-  assert.ok(content !== undefined && !content.includes(text), `${path}: ${content}`)
-})
+Then(
+  "{string} does not contain {string}",
+  outcome((world, path: string, text: string) => {
+    assertLacks(`"${path}"`, text, world.repo().read(path))
+  }),
+)
 
-Then("{string} does not exist", (world: TestkitWorld, path: string) => {
-  assert.strictEqual(world.repo().read(path), undefined)
-})
+Then(
+  "{string} does not exist",
+  outcome((world, path: string) => {
+    const content = world.repo().read(path)
+    assert.strictEqual(content, undefined, `"${path}" exists; it holds:\n${content}`)
+  }),
+)

package/src/gherkin/messages.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest"
+import { agent, human } from "../flows/index.js"
+import { testRepo } from "../testkit/index.js"
+import { assertContains, assertLacks, refusedWith, restDescription } from "./messages.js"
+
+const flow = async (): Promise<void> => {
+  await agent("plan", "Write PLAN.md.\nKeep it short.\n3\n4\n5\n6\n7")
+  await human("sign-off")
+}
+
+const thrown = async (fn: () => unknown): Promise<string> => {
+  try {
+    await fn()
+  } catch (error) {
+    return (error as Error).message
+  }
+  throw new Error("did not throw")
+}
+
+describe("restDescription", () => {
+  it("names the step, its kind and actor, the content's head, the last commits and the unused actors", async () => {
+    const repo = testRepo({ workflow: { default: flow } })
+    repo.write("go", "\n")
+    await repo.drive({ plan: (_, r) => r.write("PLAN.md", "p\n") })
+    expect(await restDescription(() => repo, ["repair", "ready"])).toBe(
+      [
+        "where the process rests:",
+        '  step "sign-off" (message, human)',
+        "  content:",
+        "    | sign-off",
+        "  last commits:",
+        "    chore: initial commit",
+        "    gtd(agent): plan → sign-off",
+        '  actors never used: "repair", "ready"',
+      ].join("\n"),
+    )
+  })
+
+  it("cuts long content to its first lines", async () => {
+    const repo = testRepo({ workflow: { default: flow } })
+    repo.write("go", "\n")
+    const description = await restDescription(() => repo, [])
+    expect(description).toContain('step "plan" (prompt, agent)')
+    expect(description).toContain("    | 5\n    | … 2 more lines")
+    expect(description).not.toContain("actors never used")
+  })
+
+  it("says why the rest is unknown instead of throwing", async () => {
+    const description = await restDescription(() => {
+      throw new Error("no gtd config")
+    }, [])
+    expect(description).toBe("where the process rests:\n  unknown — no gtd config")
+  })
+})
+
+describe("refusedWith", () => {
+  it("says nothing was refused when the attempt succeeds", async () => {
+    expect(await thrown(() => refusedWith(Promise.resolve(), "nope"))).toBe(
+      'expected a refusal with "nope", but nothing was refused',
+    )
+  })
+
+  it("prints the refusal it got when the text is missing", async () => {
+    expect(await thrown(() => refusedWith(Promise.reject(new Error("other")), "nope"))).toBe(
+      'expected a refusal with "nope", but it was refused with:\nother',
+    )
+  })
+
+  it("passes on a refusal carrying the text", async () => {
+    await refusedWith(Promise.reject(new Error("a nope b")), "nope")
+  })
+})
+
+describe("contains", () => {
+  it("prints the text looked for and what was there", async () => {
+    expect(await thrown(() => assertContains('"a.md"', "x", "y\n"))).toBe(
+      '"a.md" does not contain "x"; it holds:\ny\n',
+    )
+    expect(await thrown(() => assertLacks('"a.md"', "y", "y\n"))).toBe(
+      '"a.md" contains "y"; it holds:\ny\n',
+    )
+  })
+
+  it("says a missing file does not exist", async () => {
+    expect(await thrown(() => assertContains('"a.md"', "x", undefined))).toBe(
+      '"a.md" does not exist, so it cannot contain "x"',
+    )
+    expect(await thrown(() => assertLacks('"a.md"', "x", undefined))).toBe('"a.md" does not exist')
+  })
+})

package/src/gherkin/messages.ts

@@ -0,0 +1,84 @@
+import assert from "node:assert"
+import type { TestRepo } from "../testkit/index.js"
+
+const CONTENT_LINES = 5
+const SUBJECTS = 5
+
+const reason = (error: unknown): string => (error instanceof Error ? error.message : String(error))
+
+const beatLines = async (repo: TestRepo): Promise<string[]> => {
+  try {
+    const beat = await repo.next()
+    const content = beat.content.trimEnd().split("\n")
+    const more = content.length - CONTENT_LINES
+    return [
+      `step "${beat.state}" (${beat.kind}, ${beat.actor}${beat.idle ? ", idle" : ""})`,
+      "content:",
+      ...content.slice(0, CONTENT_LINES).map((line) => `  | ${line}`),
+      ...(more > 0 ? [`  | … ${more} more lines`] : []),
+    ]
+  } catch (error) {
+    return [`unknown — gtd next failed: ${reason(error)}`]
+  }
+}
+
+/** Where the process rests, for a failed outcome to end with. Never throws: it describes a failure. */
+export const restDescription = async (
+  repo: () => TestRepo,
+  neverUsed: readonly string[],
+): Promise<string> => {
+  let lines: string[]
+  try {
+    const r = repo()
+    lines = [
+      ...(await beatLines(r)),
+      "last commits:",
+      ...r
+        .subjects()
+        .slice(-SUBJECTS)
+        .map((subject) => `  ${subject}`),
+    ]
+  } catch (error) {
+    lines = [`unknown — ${reason(error)}`]
+  }
+  if (neverUsed.length > 0)
+    lines.push(`actors never used: ${neverUsed.map((step) => `"${step}"`).join(", ")}`)
+  return ["where the process rests:", ...lines.map((line) => `  ${line}`)].join("\n")
+}
+
+/** Both sides of a failed `contains`: the text looked for, and what was there. */
+const containsFailure = (
+  where: string,
+  text: string,
+  content: string | undefined,
+  expected: boolean,
+): string =>
+  content === undefined
+    ? `${where} does not exist${expected ? `, so it cannot contain "${text}"` : ""}`
+    : `${where} ${expected ? "does not contain" : "contains"} "${text}"; it holds:\n${content}`
+
+/** What `attempt` was refused with; fails when it was not refused at all. */
+export const refusal = async (attempt: Promise<unknown>, expectation: string): Promise<string> => {
+  try {
+    await attempt
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error)
+  }
+  assert.fail(`expected a refusal ${expectation}, but nothing was refused`)
+}
+
+export const refusedWith = async (attempt: Promise<unknown>, message: string): Promise<void> => {
+  const got = await refusal(attempt, `with "${message}"`)
+  if (!got.includes(message))
+    assert.fail(`expected a refusal with "${message}", but it was refused with:\n${got}`)
+}
+
+export const assertContains = (where: string, text: string, content: string | undefined): void => {
+  if (content === undefined || !content.includes(text))
+    assert.fail(containsFailure(where, text, content, true))
+}
+
+export const assertLacks = (where: string, text: string, content: string | undefined): void => {
+  if (content === undefined || content.includes(text))
+    assert.fail(containsFailure(where, text, content, false))
+}

package/src/testkit/TestRepo.test.ts

@@ -16,13 +16,14 @@ import {
   agent,
   check,
   human,
+  judge,
   moveScript,
   read,
   removeScript,
   run,
   showScript,
 } from "../flows/index.js"
-import { runsItsScript, testRepo } from "./TestRepo.js"
+import { runsItsScript, testRepo, type Actor } from "./TestRepo.js"
 
 const tiny = async (): Promise<void> => {
   await agent("plan", "Write PLAN.md.")
@@ -201,7 +202,51 @@ describe("testRepo", () => {
     let n = 0
     await expect(
       repo.drive({ spin: (_, r) => r.write("n", `${++n}\n`) }, { maxBeats: 5 }),
-    ).rejects.toThrow(/did not rest within 5 beats/)
+    ).rejects.toThrow(
+      "did not rest within 5 beats; it passed through:\nspin → spin → spin → spin → spin",
+    )
+  })
+
+  describe("judge verdicts", () => {
+    const judged = async (): Promise<void> => {
+      await agent("plan", "Plan.")
+      const { answers } = await judge("ready", {
+        questions: [{ id: "ready", primitive: "noul", instructions: "Ready?", criteria: "" }],
+        evidence: { plan: "p" },
+      })
+      await human(answers.ready?.answer === "yes" ? "ship" : "rework")
+    }
+    const plan: Actor = (_, r) => r.write("PLAN.md", "p\n")
+    const template =
+      'expected a JSON array, one entry per question — answer a boolean for a noul, a string for a choice, a number for a score; p between 0 and 1:\n[{ "id": "ready", "answer": true, "p": 0.9 }]'
+
+    it("echoes a refused verdict and the shape it should have", async () => {
+      const repo = testRepo({ workflow: { default: judged } })
+      repo.write("go", "\n")
+      const error = await repo
+        .drive({ plan, ready: () => '{"ready": true}' })
+        .catch((e: Error) => e)
+      expect((error as Error).message).toContain(
+        `the actor for judge step "ready" sent a verdict gtd refused:\n{"ready": true}\n${template}\ngtd judge answer exited 2\n`,
+      )
+    })
+
+    it("says an actor returned an object rather than no verdict", async () => {
+      const repo = testRepo({ workflow: { default: judged } })
+      repo.write("go", "\n")
+      const actor = (() => [{ id: "ready", answer: true, p: 0.9 }]) as unknown as Actor
+      await expect(repo.drive({ plan, ready: actor })).rejects.toThrow(
+        `the actor for judge step "ready" returned an array, not a JSON string — JSON.stringify it\n${template}`,
+      )
+    })
+
+    it("says an actor returned nothing", async () => {
+      const repo = testRepo({ workflow: { default: judged } })
+      repo.write("go", "\n")
+      await expect(repo.drive({ plan, ready: () => undefined })).rejects.toThrow(
+        `the actor for judge step "ready" returned no verdict\n${template}`,
+      )
+    })
   })
 
   describe("canned commands", () => {

package/src/testkit/TestRepo.ts

@@ -204,6 +204,30 @@ const runLines = (repo: InMemRepo, commands: CommandTable, script: string): void
 const failed = (what: string, result: CapturedCliResult): Error =>
   new Error(`${what} exited ${result.exitCode}\n${result.stderr}${result.stdout}`)
 
+const ANSWER: Readonly<Record<string, string>> = {
+  noul: "true",
+  choice: '"<option>"',
+  score: "0.5",
+}
+
+/** The verdict a judge beat's questions take, as a template to copy. */
+const expectedVerdict = (doc: BeatDocument): string => {
+  let questions: readonly { id: string; primitive: string }[] = []
+  try {
+    questions = (JSON.parse(doc.judge ?? "") as { questions: typeof questions }).questions
+  } catch {
+    // An unreadable judge document leaves the template without entries.
+  }
+  const entries = questions.map(
+    ({ id, primitive }) =>
+      `{ "id": ${JSON.stringify(id)}, "answer": ${ANSWER[primitive] ?? '"<answer>"'}, "p": 0.9 }`,
+  )
+  return [
+    "expected a JSON array, one entry per question — answer a boolean for a noul, a string for a choice, a number for a score; p between 0 and 1:",
+    `[${entries.join(", ")}]`,
+  ].join("\n")
+}
+
 export const testRepo = (options: TestRepoOptions): TestRepo => {
   const repo = new InMemRepo()
   const env = { ...options.env }
@@ -261,11 +285,15 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
   }
 
   /** Runs a write command, then the script its `--json=script` twin prints. */
-  const runWrite = async (args: readonly string[], stdin?: string): Promise<CapturedCliResult> => {
+  const runWrite = async (
+    args: readonly string[],
+    stdin?: string,
+    refused: (error: Error) => Error = (error) => error,
+  ): Promise<CapturedCliResult> => {
     const call = (...extra: string[]) =>
       stdin === undefined ? gtd(...args, ...extra) : withStdin(stdin, () => gtd(...args, ...extra))
     const reported = await call()
-    if (reported.exitCode !== EXIT_OK) throw failed(`gtd ${args.join(" ")}`, reported)
+    if (reported.exitCode !== EXIT_OK) throw refused(failed(`gtd ${args.join(" ")}`, reported))
     const script = await call("--json=script")
     apply(`gtd ${args.join(" ")}`, script.stdout)
     return reported
@@ -286,16 +314,29 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
   }
 
   /** Lands what an actor did: a judge's verdict answered, anything else validated and landed. */
-  const act = async (doc: BeatDocument, verdict: void | string): Promise<void> => {
+  const act = async (doc: BeatDocument, verdict: unknown): Promise<void> => {
     if (doc.actor !== "judge") {
       if (doc.validate !== undefined) apply(`validating ${doc.file ?? doc.state}`, doc.validate)
       await runWrite(["land"])
       return
     }
+    const actor = `the actor for judge step "${doc.state}"`
+    if (verdict === undefined) {
+      throw new Error(`${actor} returned no verdict\n${expectedVerdict(doc)}`)
+    }
     if (typeof verdict !== "string") {
-      throw new Error(`the actor for judge step "${doc.state}" returned no verdict`)
+      throw new Error(
+        `${actor} returned ${Array.isArray(verdict) ? "an array" : typeof verdict === "object" ? "an object" : `a ${typeof verdict}`}, not a JSON string — JSON.stringify it\n${expectedVerdict(doc)}`,
+      )
     }
-    await runWrite(["judge", "answer"], verdict)
+    await runWrite(
+      ["judge", "answer"],
+      verdict,
+      (error) =>
+        new Error(
+          `${actor} sent a verdict gtd refused:\n${verdict}\n${expectedVerdict(doc)}\n${error.message}`,
+        ),
+    )
   }
 
   const self: TestRepo = {
@@ -327,8 +368,10 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
     land: () => runWrite(["land"]),
     next,
     drive: async (actors = {}, { maxBeats = 50 } = {}) => {
+      const passed: string[] = []
       for (let beat = 0; beat < maxBeats; beat++) {
         const doc = await next()
+        passed.push(doc.state)
         if (doc.kind === "stalled") return doc
         if (doc.kind === "capture") {
           await runWrite(["land"])
@@ -338,7 +381,9 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
         if (actor === undefined) return doc
         await act(doc, await actor(doc, self))
       }
-      throw new Error(`the process did not rest within ${maxBeats} beats`)
+      throw new Error(
+        `the process did not rest within ${maxBeats} beats; it passed through:\n${passed.join(" → ")}`,
+      )
     },
     subjects: () => repo.commitHistory().map(({ message }) => message.split("\n")[0] ?? ""),
     messages: () => repo.commitHistory().map(({ message }) => message),