@nickmeriano/task 0.7.0 → 0.8.0

package/src/claim.test.ts

@@ -15,7 +15,7 @@
 import assert from "node:assert/strict"
 import { test } from "node:test"
 import { execFile, spawnSync } from "node:child_process"
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
 import { readFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
@@ -69,7 +69,7 @@ interface Fixture {
  *   2 "Ready two"    todo
  *   3 "Blocked"      todo, blocked by 1
  *   4 "For a person" todo, needs-human
- *   5 "Not groomed"  backlog
+ *   5 "Still parked" backlog
  *   6 "Jumped queue" todo, moved to the top of the column after creation —
  *                    claimable order must be [6, 1, 2], proving position
  *                    order beats number order.
@@ -90,11 +90,11 @@ function fixture(claimPrefix?: string): Fixture {
     config.claimPrefix = claimPrefix
     writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`)
   }
-  store.create({ title: "Ready one" })
-  store.create({ title: "Ready two" })
-  store.create({ title: "Blocked", blockedBy: [1] })
-  store.create({ title: "For a person", needsHuman: true })
-  store.create({ title: "Not groomed", status: "backlog" })
+  store.create({ title: "Ready one", status: "todo" })
+  store.create({ title: "Ready two", status: "todo" })
+  store.create({ title: "Blocked", status: "todo", blockedBy: [1] })
+  store.create({ title: "For a person", status: "todo", needsHuman: true })
+  store.create({ title: "Still parked", status: "backlog" })
   const jumper = store.create({ title: "Jumped queue", status: "backlog" })
   // A status move without an explicit slot lands on top of the new column.
   store.update(jumper.number, { status: "todo" })
@@ -151,12 +151,16 @@ test("unclaimable tickets exit 2, before anything touches origin", async () => {
   assert.equal((await cli(dir, "claim", "99")).code, 2) // missing
   assert.match((await cli(dir, "claim", "3")).stderr, /blocked by CLM-1/)
 
-  // A dirty tree refuses too — claiming switches branches.
-  writeFileSync(join(dir, "scratch.txt"), "wip")
+  // A dirty tree refuses too — claiming switches branches. Only *tracked*
+  // modifications count: untracked files ride a branch switch untouched
+  // (release deliberately leaves one — the reason comment).
+  const gitignore = join(dir, ".task", ".gitignore")
+  writeFileSync(gitignore, `${readFileSync(gitignore, "utf8")}\nwip\n`)
   const dirty = await cli(dir, "claim", "2")
   assert.equal(dirty.code, 2)
   assert.match(dirty.stderr, /working tree is dirty/)
-  rmSync(join(dir, "scratch.txt"))
+  sh(dir, "git", "checkout", "--", ".task/.gitignore")
+  writeFileSync(join(dir, "scratch.txt"), "untracked is fine")
   assert.equal((await cli(dir, "claim", "2")).code, 0)
 
   // Nothing above created a stray claim branch for the failed ids.
@@ -189,7 +193,7 @@ test("release deletes the branch everywhere and reopens the claim", async () =>
   assert.equal((await cli(dir, "claim", "2")).code, 0)
   assert.equal((await cli(dir, "claim", "2")).code, 1) // locally claimed too
 
-  const released = await cli(dir, "claim", "--release", "2")
+  const released = await cli(dir, "claim", "--release", "2", "--comment", "trying another shape")
   assert.equal(released.code, 0, released.stderr)
   assert.match(released.stdout, /released CLM-2/)
 
@@ -203,7 +207,7 @@ test("release deletes the branch everywhere and reopens the claim", async () =>
   assert.equal((await cli(dir, "claim", "2")).code, 0)
 
   // Releasing an unclaimed ticket is a quiet no-op, not an error.
-  const noop = await cli(dir, "claim", "--release", "1")
+  const noop = await cli(dir, "claim", "--release", "1", "--comment", "noop")
   assert.equal(noop.code, 0)
   assert.match(noop.stdout, /wasn't claimed/)
 })
@@ -226,7 +230,7 @@ test("a configured claimPrefix moves the whole namespace", async () => {
   const { tasks } = JSON.parse(listed.stdout) as { tasks: { number: number }[] }
   assert.deepEqual(tasks.map((t) => t.number), [6, 2])
   assert.equal((await cli(other, "claim", "1")).code, 1)
-  assert.equal((await cli(dir, "claim", "--release", "1")).code, 0)
+  assert.equal((await cli(dir, "claim", "--release", "1", "--comment", "handing it back")).code, 0)
   assert.equal(sh(dir, "git", "ls-remote", "--heads", "origin", "claude/task/*"), "")
 
   // A missing trailing slash is forgiven; a malformed value fails loudly.
@@ -238,5 +242,189 @@ test("a configured claimPrefix moves the whole namespace", async () => {
   sh(bad, "git", "commit", "--quiet", "-am", "bad prefix")
   const invalid = await cli(bad, "claim", "2")
   assert.equal(invalid.code, 2)
-  assert.match(invalid.stderr, /invalid claimPrefix/)
+  assert.match(invalid.stderr, /invalid claims\.branchPrefix/)
+})
+
+/**
+ * A monorepo with two boards for the multi-board selection paths (TAS-27):
+ * a root board (ROO, one ready ticket) and a nested one under pkg/ (NES,
+ * one ready ticket). The root config carries the new `claims` block and,
+ * optionally, the top-level `boards` list — NES deliberately ahead of ROO,
+ * so priority provably follows list order, not nearness.
+ */
+function multiFixture(options: { boards?: string[]; maxOpenCount?: number } = {}): Fixture {
+  const home = tempDir()
+  const bare = join(home, "origin.git")
+  sh(home, "git", "init", "--quiet", "--bare", "-b", "main", bare)
+
+  const seed = join(home, "seed")
+  sh(home, "git", "clone", "--quiet", bare, seed)
+  sh(seed, "git", "config", "user.name", "Test")
+  sh(seed, "git", "config", "user.email", "test@example.com")
+
+  const root = initProject(seed, { name: "root board", prefix: "ROO" })
+  const configPath = join(seed, ".task", "config.json")
+  const config = JSON.parse(readFileSync(configPath, "utf8")) as Record<string, unknown>
+  if (options.boards) config.boards = options.boards
+  config.claims = { branchPrefix: "task/claim/", maxOpenCount: options.maxOpenCount }
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`)
+  root.create({ title: "Root ready", status: "todo" })
+
+  mkdirSync(join(seed, "pkg"), { recursive: true })
+  const nested = initProject(join(seed, "pkg"), { name: "nested board", prefix: "NES" })
+  nested.create({ title: "Nested ready", status: "todo" })
+
+  sh(seed, "git", "add", "-A")
+  sh(seed, "git", "commit", "--quiet", "-m", "boards")
+  sh(seed, "git", "push", "--quiet", "-u", "origin", "main")
+
+  let clones = 0
+  const clone = (): string => {
+    const dir = join(home, `clone-${++clones}`)
+    sh(home, "git", "clone", "--quiet", bare, dir)
+    sh(dir, "git", "config", "user.name", "Test")
+    sh(dir, "git", "config", "user.email", "test@example.com")
+    return dir
+  }
+  return { bare, clone }
+}
+
+test("claim --next drains the queue in position order and exits 1 when empty", async () => {
+  const { clone } = fixture()
+  const dir = clone()
+
+  const order: number[] = []
+  for (;;) {
+    const result = await cli(dir, "claim", "--next", "--json")
+    if (result.code === 1) {
+      assert.equal(JSON.parse(result.stdout).task, null)
+      break
+    }
+    assert.equal(result.code, 0, result.stderr)
+    const { task, branch } = JSON.parse(result.stdout) as { task: { number: number }; branch: string }
+    order.push(task.number)
+    assert.equal(sh(dir, "git", "rev-parse", "--abbrev-ref", "HEAD"), branch)
+  }
+  // The jumper leads (position order), then creation order; blocked,
+  // needs-human and backlog tickets never surface.
+  assert.deepEqual(order, [6, 1, 2])
+})
+
+test("two concurrent claim --next calls land on different tickets", async () => {
+  const { clone } = fixture()
+  const a = clone()
+  const b = clone()
+
+  const [ra, rb] = await Promise.all([
+    cli(a, "claim", "--next", "--json"),
+    cli(b, "claim", "--next", "--json"),
+  ])
+  assert.equal(ra.code, 0, ra.stderr)
+  assert.equal(rb.code, 0, rb.stderr)
+  const ids = [ra, rb].map((r) => (JSON.parse(r.stdout) as { task: { id: string } }).task.id)
+  assert.notEqual(ids[0], ids[1], `both claimed ${ids[0]}`)
+})
+
+test("--next walks the root boards list in priority order; --board overrides it", async () => {
+  const { clone } = multiFixture({ boards: ["NES", "ROO"] })
+  const a = clone()
+
+  // list --claimable reads the same scope, in the same order.
+  const listed = await cli(a, "list", "--claimable", "--json")
+  assert.equal(listed.code, 0, listed.stderr)
+  const { tasks } = JSON.parse(listed.stdout) as { tasks: { id: string }[] }
+  assert.deepEqual(tasks.map((t) => t.id), ["NES-1", "ROO-1"])
+
+  // The nested board wins despite the root board being nearest.
+  const next = await cli(a, "claim", "--next", "--json")
+  assert.equal(next.code, 0, next.stderr)
+  const claimed = JSON.parse(next.stdout) as { task: { id: string }; branch: string }
+  assert.equal(claimed.task.id, "NES-1")
+  assert.equal(claimed.branch, "task/claim/nes-1")
+
+  // An explicit --board list is the whole scope, in the given order.
+  const b = clone()
+  const overridden = await cli(b, "claim", "--next", "--board", "ROO", "--json")
+  assert.equal(overridden.code, 0, overridden.stderr)
+  assert.equal((JSON.parse(overridden.stdout) as { task: { id: string } }).task.id, "ROO-1")
+
+  const unknown = await cli(b, "claim", "--next", "--board", "NOPE")
+  assert.equal(unknown.code, 2)
+  assert.match(unknown.stderr, /no board with prefix NOPE/)
+})
+
+test("without a boards list, --next sees the nearest board only", async () => {
+  const { clone } = multiFixture()
+  const dir = clone()
+
+  const next = await cli(dir, "claim", "--next", "--json")
+  assert.equal(next.code, 0, next.stderr)
+  assert.equal((JSON.parse(next.stdout) as { task: { id: string } }).task.id, "ROO-1")
+
+  // ROO's queue is drained and NES never entered the scope.
+  const empty = await cli(dir, "claim", "--next", "--json")
+  assert.equal(empty.code, 1)
+})
+
+test("maxOpenCount caps every claim repo-wide; --force is the escape", async () => {
+  const { clone } = multiFixture({ boards: ["NES", "ROO"], maxOpenCount: 1 })
+  const a = clone()
+  assert.equal((await cli(a, "claim", "--next", "--json")).code, 0)
+
+  // At the cap, --next and explicit-id claims both refuse with exit 2 —
+  // the fix is to finish or release a claim, not to pick another ticket.
+  const b = clone()
+  const capped = await cli(b, "claim", "--next")
+  assert.equal(capped.code, 2)
+  assert.match(capped.stderr, /maxOpenCount cap \(1\)/)
+  const explicit = await cli(b, "claim", "ROO-1")
+  assert.equal(explicit.code, 2)
+  assert.match(explicit.stderr, /maxOpenCount cap \(1\)/)
+
+  const forced = await cli(b, "claim", "--next", "--force", "--json")
+  assert.equal(forced.code, 0, forced.stderr)
+  assert.equal((JSON.parse(forced.stdout) as { task: { id: string } }).task.id, "ROO-1")
+})
+
+test("release requires a reason and leaves it as a comment on the ticket", async () => {
+  const { clone } = fixture()
+  const dir = clone()
+  assert.equal((await cli(dir, "claim", "1")).code, 0)
+
+  // No comment, and an empty one, are both refused before anything happens.
+  const missing = await cli(dir, "claim", "--release", "1")
+  assert.equal(missing.code, 1)
+  assert.match(missing.stderr, /requires --comment/)
+  const empty = await cli(dir, "claim", "--release", "1", "--comment", "")
+  assert.equal(empty.code, 1)
+  assert.match(empty.stderr, /requires --comment/)
+  assert.match(
+    sh(dir, "git", "ls-remote", "--heads", "origin", "task/claim/clm-1"),
+    /clm-1/,
+  )
+
+  const released = await cli(
+    dir, "claim", "--release", "1",
+    "--comment", "the migration kept flaking — needs a fixture, not a retry",
+    "--author", "claude",
+  )
+  assert.equal(released.code, 0, released.stderr)
+
+  // The reason survives the branch: an ordinary attributed comment, sitting
+  // uncommitted in the working tree on the default branch.
+  const shown = await cli(dir, "show", "1", "--json")
+  const { comments } = JSON.parse(shown.stdout) as {
+    comments: { author: string; body: string }[]
+  }
+  assert.equal(comments.length, 1)
+  assert.equal(comments[0].author, "claude")
+  assert.match(comments[0].body, /kept flaking/)
+  assert.match(sh(dir, "git", "status", "--porcelain"), /tickets\/1\/comments/)
+
+  // Releasing an unclaimed ticket stays a no-op — no second comment.
+  const noop = await cli(dir, "claim", "--release", "1", "--comment", "again")
+  assert.equal(noop.code, 0)
+  assert.match(noop.stdout, /wasn't claimed/)
+  const after = await cli(dir, "show", "1", "--json")
+  assert.equal((JSON.parse(after.stdout) as { comments: unknown[] }).comments.length, 1)
 })

package/src/claim.ts

@@ -12,8 +12,14 @@
 
 import { spawnSync } from "node:child_process"
 import { join } from "node:path"
-import { FileStore, TICKETS_DIR } from "./file-store.ts"
-import type { Store } from "./store.ts"
+import { FileStore, TICKETS_DIR, openBoard } from "./file-store.ts"
+import {
+  boardConfig,
+  findBoardsByPrefix,
+  findRoot,
+  findScopeRoot,
+  type Store,
+} from "./store.ts"
 import type { ProjectConfig, Task } from "./types.ts"
 
 /**
@@ -31,22 +37,48 @@ export const DEFAULT_CLAIM_PREFIX = "task/claim/"
 const CLAIM_PREFIX_SHAPE = /^([A-Za-z0-9._-]+\/)+$/
 
 /**
- * The board's claim namespace: configured `claimPrefix` (a trailing slash is
+ * The board's configured claim namespace before validation or defaulting —
+ * `claims.branchPrefix`, falling back to the pre-0.8 top-level `claimPrefix`
+ * (still read for one release so a version bump can't strand in-flight
+ * claims; `task check` nags, `--fix` migrates). Exported for `task check`,
+ * which wants the raw value to lint without the throw below.
+ */
+export function configuredBranchPrefix(config: ProjectConfig): string | undefined {
+  return config.claims?.branchPrefix ?? config.claimPrefix
+}
+
+/**
+ * The board's claim namespace: configured branch prefix (a trailing slash is
  * implied) or the default. Validated here because it becomes a git ref and an
  * ls-remote glob — a malformed value must fail the claim, not corrupt it.
  */
 export function claimNamespace(config: ProjectConfig): string {
-  const raw = config.claimPrefix ?? DEFAULT_CLAIM_PREFIX
+  const raw = configuredBranchPrefix(config) ?? DEFAULT_CLAIM_PREFIX
   const prefix = raw.endsWith("/") ? raw : `${raw}/`
   if (!CLAIM_PREFIX_SHAPE.test(prefix) || prefix.includes("..") || /(^|\/)\./.test(prefix)) {
     throw new ClaimError(
-      `invalid claimPrefix in .task/config.json: ${JSON.stringify(raw)} — use slash-separated segments like "task/claim/" or "claude/task/"`,
+      `invalid claims.branchPrefix in .task/config.json: ${JSON.stringify(raw)} — use slash-separated segments like "task/claim/" or "claude/task/"`,
       "invalid",
     )
   }
   return prefix
 }
 
+/**
+ * The repo-wide cap on open claims: `claims.maxOpenCount` read from the
+ * *root* board's config (the outermost `.task/` above `root`), never the
+ * nearest one — a WIP cap each board could set for itself is no cap at all.
+ * Absent, unparseable or nonsensical values all mean "no cap".
+ */
+export function openClaimCap(root: string): number | undefined {
+  try {
+    const cap = boardConfig(findScopeRoot(root)).claims?.maxOpenCount
+    return typeof cap === "number" && Number.isInteger(cap) && cap > 0 ? cap : undefined
+  } catch {
+    return undefined
+  }
+}
+
 /** { prefix: "TAS" }, 21 → "task/claim/tas-21" (or under the configured namespace). */
 export function claimBranch(config: ProjectConfig, number: number): string {
   return `${claimNamespace(config)}${config.prefix.toLowerCase()}-${number}`
@@ -151,6 +183,29 @@ export interface ClaimResult {
   base: string
 }
 
+export interface ClaimOptions {
+  /** Claim past the root board's `claims.maxOpenCount` cap. */
+  force?: boolean
+}
+
+/**
+ * The WIP-cap gate every claim passes through: while `maxOpenCount` claim
+ * branches exist on origin, claiming more is refused (exit 2 — the fix is to
+ * finish or release one, not to pick a different ticket). Existence on origin
+ * is the definition of "open": a claim branch dies at merge or release, so a
+ * lingering merged branch counts — deliberate pressure to clean it up. The
+ * cap applies to humans and agents alike; `--force` is the escape.
+ */
+function assertUnderCap(openClaims: Set<string>, root: string, namespace: string): void {
+  const cap = openClaimCap(root)
+  if (cap !== undefined && openClaims.size >= cap) {
+    throw new ClaimError(
+      `${openClaims.size} claim branch${openClaims.size === 1 ? "" : "es"} already open under ${namespace} — at the root board's maxOpenCount cap (${cap}); finish or \`task claim --release\` one, or pass --force`,
+      "invalid",
+    )
+  }
+}
+
 /**
  * Claim `number`: validate, branch off origin's default branch, flip the
  * ticket to in_progress as the branch's first commit, and push. The push
@@ -160,9 +215,14 @@ export interface ClaimResult {
  * someone pre-created without a claim commit can't be hijacked by a plain
  * fast-forward. Leaves the winner checked out on the claim branch.
  */
-export function claim(store: Store, number: number): ClaimResult {
+export function claim(store: Store, number: number, options: ClaimOptions = {}): ClaimResult {
+  // Unreachable since openBoard refuses pre-0.6 boards, kept as the narrowing
+  // that lets the rest of this function assume text-canonical semantics.
   if (!(store instanceof FileStore)) {
-    throw new ClaimError("claiming needs a text-format board — run `task migrate` first", "invalid")
+    throw new ClaimError(
+      "claiming needs a text-format board — run `npx @nickmeriano/task@0.6 migrate` once",
+      "invalid",
+    )
   }
   const cwd = store.root
   const branch = claimBranch(store.config, number)
@@ -171,7 +231,11 @@ export function claim(store: Store, number: number): ClaimResult {
   // The local-branch check comes before ticket validation on purpose: on the
   // claim branch itself the ticket reads in_progress, and "already claimed"
   // (exit 1, move on) is the truthful answer there — not a validation failure.
-  const tree = git(cwd, "status", "--porcelain")
+  // -uno everywhere a claim reads the tree: only *tracked* modifications block
+  // a branch switch. Untracked files ride along untouched — and the release
+  // flow deliberately leaves one (the reason comment), so counting them would
+  // wedge the release-then-claim-next loop this exists for.
+  const tree = git(cwd, "status", "--porcelain", "-uno")
   if (tree.status !== 0) {
     throw new ClaimError(`not a git repository: ${cwd}`, "invalid")
   }
@@ -191,9 +255,15 @@ export function claim(store: Store, number: number): ClaimResult {
   }
 
   gitMust(cwd, "fetch", "--quiet", "origin")
-  if (remoteBranchExists(cwd, branch)) {
+  // One ls-remote answers both gates: is this ticket taken, and is the repo
+  // at its WIP cap. "Already claimed" wins — that's exit 1 (pick the next
+  // ticket), where the cap is exit 2 (fix something).
+  const namespace = claimNamespace(store.config)
+  const openClaims = remoteClaims(cwd, namespace)
+  if (openClaims.has(branch)) {
     throw new ClaimError(`${id} is already claimed — ${branch} exists on origin`, "claimed")
   }
+  if (!options.force) assertUnderCap(openClaims, cwd, namespace)
 
   const base = defaultBase(cwd)
   // So a failed claim can put the checkout back exactly where it was —
@@ -263,7 +333,7 @@ export function release(store: Store, number: number): ReleaseResult {
   const onBranch =
     git(cwd, "symbolic-ref", "--quiet", "--short", "HEAD").stdout === branch
   if (onBranch) {
-    const tree = gitMust(cwd, "status", "--porcelain")
+    const tree = gitMust(cwd, "status", "--porcelain", "-uno")
     if (tree !== "") {
       throw new ClaimError(
         `working tree on ${branch} is dirty — commit elsewhere or discard before releasing`,
@@ -300,3 +370,117 @@ export function claimableTasks(store: Store): Task[] {
     .filter((t) => openBlockers(store, t).length === 0)
     .filter((t) => !claimed.has(claimBranch(store.config, t.number)))
 }
+
+export interface PromoteResult {
+  task: Task
+  /** Claim-time gates still in the way — promoted, but not claimable yet. */
+  holds: string[]
+}
+
+/**
+ * `task promote` — the human "build this" call, as a verb: `backlog` → `todo`.
+ * No quality gate: planning happens at claim time (the worker's plan tick),
+ * so a one-line backlog ticket is promotable. Blocked and needs-human are
+ * claim-time facts that `claim`/`--claimable` already enforce live, so
+ * promoting a blocked ticket is legitimate sequencing ("build this once
+ * NIC-11 lands") — reported as a hold, never refused. Writes the ticket like
+ * `update` does; committing is the caller's job.
+ */
+export function promote(store: Store, number: number): PromoteResult {
+  const task = store.get(number)
+  const id = store.displayId(number)
+  if (!task) throw new ClaimError(`no such task: ${id}`, "invalid")
+  if (task.status !== "backlog") {
+    throw new ClaimError(
+      `${id} is ${task.status} — only backlog tickets can be promoted`,
+      "invalid",
+    )
+  }
+  const updated = store.update(number, { status: "todo" })
+  const holds: string[] = []
+  if (updated.needsHuman) holds.push("flagged needs-human")
+  const blockers = openBlockers(store, updated)
+  if (blockers.length) holds.push(`blocked by ${blockers.join(", ")}`)
+  return { task: updated, holds }
+}
+
+/**
+ * The boards `claim --next` and `list --claimable` select over, in priority
+ * order. Resolution: an explicit `--board` list > the root board's top-level
+ * `boards` key > the nearest board alone. The list is *selection scope*, not
+ * permission — `task claim <id>` works on any board regardless — and it's
+ * read from the repo's root board only, so a vendored board can't opt itself
+ * into a repo's automation by shipping a config.
+ */
+export function selectionBoards(cwd: string, prefixes?: string[]): Store[] {
+  const scope = findScopeRoot(cwd)
+  let wanted = prefixes?.length ? prefixes : undefined
+  if (!wanted) {
+    try {
+      const boards = boardConfig(scope).boards
+      if (Array.isArray(boards) && boards.length > 0) wanted = boards.map(String)
+    } catch {
+      // No readable root board — same answer as no boards list.
+    }
+  }
+  if (!wanted) {
+    const nearest = findRoot(cwd)
+    if (!nearest) {
+      throw new ClaimError(
+        "no .task directory found in this directory or any parent — run `task init` first",
+        "invalid",
+      )
+    }
+    return [openBoard(nearest)]
+  }
+  return wanted.map((prefix) => {
+    const matches = findBoardsByPrefix(scope, prefix)
+    if (matches.length === 1) return openBoard(matches[0].root)
+    throw new ClaimError(
+      matches.length === 0
+        ? `no board with prefix ${prefix.toUpperCase()} in this repo — check --board and the root board's "boards" list`
+        : `prefix ${prefix.toUpperCase()} is ambiguous — boards at: ${matches.map((m) => m.id).join(", ")}`,
+      "invalid",
+    )
+  })
+}
+
+/**
+ * `task claim --next`: walk the selection scope in priority order and claim
+ * the first ticket that sticks. Losing a race for one ticket (another worker
+ * pushed its branch first) means *try the next*, so every ClaimError inside
+ * the loop is a skip — which is why the repo-level preconditions (dirty tree,
+ * malformed prefix, WIP cap) are asserted up front, where they still mean
+ * "stop and fix something" (exit 2) instead of draining the queue to a bogus
+ * "nothing claimable". Returns null when the queue really is empty (exit 1).
+ */
+export function claimNext(stores: Store[], options: ClaimOptions = {}): ClaimResult | null {
+  const first = stores[0]
+  const tree = git(first.root, "status", "--porcelain", "-uno")
+  if (tree.status !== 0) {
+    throw new ClaimError(`not a git repository: ${first.root}`, "invalid")
+  }
+  if (tree.stdout !== "") {
+    throw new ClaimError(
+      "working tree is dirty — commit or stash before claiming, the claim switches branches",
+      "invalid",
+    )
+  }
+  for (const store of stores) claimNamespace(store.config)
+  if (!options.force) {
+    const namespace = claimNamespace(first.config)
+    assertUnderCap(remoteClaims(first.root, namespace), first.root, namespace)
+  }
+  for (const store of stores) {
+    for (const task of claimableTasks(store)) {
+      try {
+        return claim(store, task.number, options)
+      } catch (error) {
+        // Claimed out from under us, or changed since listing — next in line.
+        if (error instanceof ClaimError) continue
+        throw error
+      }
+    }
+  }
+  return null
+}