@nickmeriano/task 0.5.0 → 0.7.0

package/skill/SKILL.md

@@ -2,7 +2,7 @@
 name: tasks
 description: >-
   Work with this repository's built-in task manager (the `task` CLI — a .task/
-  directory with a SQLite database, from @nickmeriano/task). Use this
+  directory of plain-text tickets, from @nickmeriano/task). Use this
   skill whenever the user mentions tasks, tickets, issues, todos, backlog,
   kanban, board, "what's next", "what should I work on", or asks you to plan,
   track, or report progress on work — and also on your own initiative: when you
@@ -13,11 +13,14 @@ description: >-
 
 # tasks — the repo's task manager
 
-This repository tracks its work in `.task/` at the project root: a SQLite
-database driven by the `task` CLI. Tasks live in the repo, next to the code
-they describe — when you update a task, the user sees it instantly (the board
-UI at `task serve` updates in realtime), and the state is committed with the
-code, so it survives sessions and travels with branches.
+This repository tracks its work in `.task/` at the project root: one markdown
+file per ticket under `.task/tickets/`, driven by the `task` CLI. Tasks live in
+the repo, next to the code they describe — when you update a task, the user
+sees it instantly (the board UI at `task serve` updates in realtime), and the
+state is committed with the code, so it survives sessions, travels with
+branches, and shows up as readable diffs in PRs. Always write through the CLI
+rather than editing ticket files by hand — it keeps numbering, positions and
+relations consistent.
 
 Run `task` from anywhere in the repo; it walks up to find `.task/` like git
 finds `.git`. If the CLI isn't on PATH, use `npx @nickmeriano/task` instead.
@@ -43,8 +46,15 @@ task move <id> <status>                # any status change
 task link <id> --blocked-by <id>       # mark a dependency (or --blocks)
 task unlink <id> --blocked-by <id>     # remove one (or --blocks)
 task update <id> --pr <url>            # attach a pull request (appends)
+task claim <id>                        # claim a ticket before working it
+task claim --release <id>              # abandon a claim cleanly
+task list --claimable --json           # the claim queue, top entry = next up
 task comment <id> "text" --author claude
 task delete <id>
+task boards --json                     # every board in the repo, with prefixes
+task archive <id> --json               # done/canceled ticket -> .task/archive/
+task archive --all --json              # archive everything done or canceled
+task unarchive <id> --json             # put one back on the board
 task whoami                            # who comments are attributed to
 ```
 
@@ -53,11 +63,19 @@ the user can read it from a phone, and take it away again. Both open a browser
 and wait for a human, so **never run either on your own initiative**; suggest
 `task publish` if the user wants to see the board remotely.
 
-- `<id>` is `PREFIX-12` or just `12`.
+- `<id>` is `PREFIX-12` or just `12`. A bare number means the nearest board;
+  a prefixed id routes to whichever board in the repo owns that prefix, so
+  `TAS-12` works from any directory. `task boards --json` lists them all.
 - Statuses: `backlog` `todo` `in_progress` `done` `canceled`.
 - `--tag a,b` matches a task carrying *either* tag, not both.
 - Clear a field by passing it empty: `--tags ""`, `--milestone ""`, `--prs ""`.
-- `task list` hides done/canceled by default; `--all` shows everything.
+- `task list` hides done/canceled by default; `--all` shows everything, and
+  `--archived` lists the archive instead of the board.
+- Archiving is history, not deletion: only done/canceled tickets qualify,
+  their numbers stay reserved, and `task show` still reads them. Archived
+  tickets refuse edits until unarchived. Don't archive on your own
+  initiative — suggest `task archive --all` when finished work is piling up,
+  and let the user decide.
 
 **Dependencies.** `task link A --blocked-by B` and `task link B --blocks A`
 write the same relation — each task's `task show` lists both its `blocked`
@@ -67,6 +85,25 @@ ordering ("this can't land until X does"), record it with `task link` instead
 of prose in a comment. Blocked tasks wear a red "Blocked" badge on the board
 until every blocker is done or canceled.
 
+**Claiming.** On a board worked by several sessions (scheduled agents, other
+humans), `task claim <id>` is the lock that keeps two workers off the same
+ticket: it branches `<claimPrefix><prefix>-<n>` off origin's default branch
+(`claimPrefix` in `.task/config.json`, default `task/claim/`), flips the
+ticket to `in_progress` as the branch's first commit, and pushes. The branch
+existing on origin *is* the claim — atomic, because the push only succeeds if
+the branch doesn't exist yet. Exit codes: `0` claimed (you're on the branch,
+start working), `1` already claimed (pick another ticket), `2` not claimable
+(not todo, blocked, needs-human, or dirty tree). **Claim before you work**:
+if you're about to implement a `todo` ticket in a repo that claims (a
+`claimPrefix` in the config, or claims visible in
+`git ls-remote origin '<claimPrefix>*'`), run `task claim <id>` first so no
+scheduled run picks it up under you — and do the whole ticket on the claim
+branch, `task done` + `--pr` included, so the merge lands code and status
+together. `task claim --release <id>` abandons a claim (deletes the branch
+both sides); `task list --claimable --json` is the queue. Never edit
+`claimPrefix` on your own initiative — it's the shared lock convention, and
+changing it strands every in-flight claim.
+
 **Pull requests.** When you open a PR for a task, attach it:
 `task update <id> --pr <url>`. Put the task id in the PR title too (e.g.
 `[TAS-6] Fix retry loop`) so the two reference each other from both sides.

package/src/claim.test.ts

@@ -0,0 +1,242 @@
+/**
+ * The properties TAS-21 exists for, checked from the outside — against a real
+ * bare "origin" and real CLI subprocesses, because the whole point of claiming
+ * is what happens between two independent checkouts:
+ *
+ * 1. Two concurrent `task claim <same-id>`: exactly one exits 0, the other
+ *    exits 1 — git's atomic ref creation is the lock.
+ * 2. Validation failures exit 2 before anything touches git.
+ * 3. `task list --claimable` is the queue: position order, minus blocked,
+ *    needs-human, and already-claimed tickets.
+ * 4. `task claim --release` deletes the branch both sides and the ticket is
+ *    claimable again.
+ */
+
+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 { readFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { initProject } from "./file-store.ts"
+
+const CLI = fileURLToPath(new URL("./cli.ts", import.meta.url))
+
+function tempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "task-claim-test-"))
+  process.on("exit", () => rmSync(dir, { recursive: true, force: true }))
+  return dir
+}
+
+function sh(cwd: string, command: string, ...args: string[]): string {
+  const result = spawnSync(command, args, { cwd, encoding: "utf8" })
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(" ")} failed: ${result.stderr}`)
+  }
+  return result.stdout.trim()
+}
+
+interface CliResult {
+  code: number
+  stdout: string
+  stderr: string
+}
+
+/** The CLI as callers see it — a subprocess with an exit code. */
+function cli(cwd: string, ...args: string[]): Promise<CliResult> {
+  return new Promise((resolve) => {
+    execFile(
+      process.execPath,
+      ["--experimental-strip-types", CLI, ...args],
+      { cwd },
+      (error, stdout, stderr) => {
+        resolve({ code: error ? ((error as { code?: number }).code ?? 1) : 0, stdout, stderr })
+      },
+    )
+  })
+}
+
+interface Fixture {
+  bare: string
+  clone: () => string
+}
+
+/**
+ * A bare origin holding a board with the claimable shapes:
+ *   1 "Ready one"    todo
+ *   2 "Ready two"    todo
+ *   3 "Blocked"      todo, blocked by 1
+ *   4 "For a person" todo, needs-human
+ *   5 "Not groomed"  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.
+ */
+function fixture(claimPrefix?: string): 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 store = initProject(seed, { name: "claim board", prefix: "CLM" })
+  if (claimPrefix !== undefined) {
+    const configPath = join(seed, ".task", "config.json")
+    const config = JSON.parse(readFileSync(configPath, "utf8")) as Record<string, unknown>
+    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" })
+  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" })
+  sh(seed, "git", "add", "-A")
+  sh(seed, "git", "commit", "--quiet", "-m", "board")
+  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("two concurrent claims of one ticket: exactly one wins", async () => {
+  const { bare, clone } = fixture()
+  const a = clone()
+  const b = clone()
+
+  const [ra, rb] = await Promise.all([cli(a, "claim", "1"), cli(b, "claim", "1")])
+  assert.deepEqual([ra.code, rb.code].sort(), [0, 1], `a: ${ra.stderr}\nb: ${rb.stderr}`)
+
+  const winner = ra.code === 0 ? a : b
+  const loser = ra.code === 0 ? rb : ra
+  assert.match(loser.stderr, /already claimed|rejected/)
+
+  // The winner is left on the claim branch, flip committed and pushed.
+  assert.equal(sh(winner, "git", "rev-parse", "--abbrev-ref", "HEAD"), "task/claim/clm-1")
+  assert.match(
+    readFileSync(join(winner, ".task", "tickets", "1", "ticket.md"), "utf8"),
+    /status: in_progress/,
+  )
+  assert.match(
+    sh(winner, "git", "ls-remote", "--heads", "origin", "task/claim/clm-1"),
+    /refs\/heads\/task\/claim\/clm-1/,
+  )
+  // Origin's default branch never saw the flip — the claim rides the branch.
+  assert.equal(sh(winner, "git", "diff", "--stat", "origin/main..HEAD", "--", "README.md"), "")
+  assert.match(sh(winner, "git", "show", "origin/main:.task/tickets/1/ticket.md"), /status: todo/)
+  void bare
+})
+
+test("unclaimable tickets exit 2, before anything touches origin", async () => {
+  const { clone } = fixture()
+  const dir = clone()
+
+  assert.equal((await cli(dir, "claim", "5")).code, 2) // backlog
+  assert.equal((await cli(dir, "claim", "3")).code, 2) // blocked
+  assert.equal((await cli(dir, "claim", "4")).code, 2) // needs a human
+  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")
+  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"))
+  assert.equal((await cli(dir, "claim", "2")).code, 0)
+
+  // Nothing above created a stray claim branch for the failed ids.
+  const remote = sh(dir, "git", "ls-remote", "--heads", "origin", "task/claim/*")
+  assert.deepEqual(
+    remote.split("\n").map((l) => l.split("refs/heads/")[1]),
+    ["task/claim/clm-2"],
+  )
+})
+
+test("list --claimable is the queue: position order, minus everything unclaimable", async () => {
+  const { clone } = fixture()
+  const a = clone()
+  assert.equal((await cli(a, "claim", "6")).code, 0)
+
+  const b = clone()
+  const listed = await cli(b, "list", "--claimable", "--json")
+  assert.equal(listed.code, 0)
+  const { tasks } = JSON.parse(listed.stdout) as { tasks: { number: number }[] }
+  // 6 claimed, 3 blocked, 4 needs-human, 5 not todo — position order keeps
+  // 1 before 2 (creation order within the column).
+  assert.deepEqual(tasks.map((t) => t.number), [1, 2])
+
+  assert.equal((await cli(b, "list", "--claimable", "--status", "todo")).code, 1)
+})
+
+test("release deletes the branch everywhere and reopens the claim", async () => {
+  const { clone } = fixture()
+  const dir = clone()
+  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")
+  assert.equal(released.code, 0, released.stderr)
+  assert.match(released.stdout, /released CLM-2/)
+
+  // Back on the default branch, branch gone on both sides, ticket todo again.
+  assert.equal(sh(dir, "git", "rev-parse", "--abbrev-ref", "HEAD"), "main")
+  assert.equal(sh(dir, "git", "ls-remote", "--heads", "origin", "task/claim/clm-2"), "")
+  assert.match(
+    readFileSync(join(dir, ".task", "tickets", "2", "ticket.md"), "utf8"),
+    /status: todo/,
+  )
+  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")
+  assert.equal(noop.code, 0)
+  assert.match(noop.stdout, /wasn't claimed/)
+})
+
+test("a configured claimPrefix moves the whole namespace", async () => {
+  const { clone } = fixture("claude/task/")
+  const dir = clone()
+
+  assert.equal((await cli(dir, "claim", "1")).code, 0)
+  assert.equal(sh(dir, "git", "rev-parse", "--abbrev-ref", "HEAD"), "claude/task/clm-1")
+  assert.match(
+    sh(dir, "git", "ls-remote", "--heads", "origin", "claude/task/*"),
+    /refs\/heads\/claude\/task\/clm-1/,
+  )
+
+  // Every side of the feature reads the same key: the queue looks for claims
+  // under the configured namespace, and release deletes there too.
+  const other = clone()
+  const listed = await cli(other, "list", "--claimable", "--json")
+  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(sh(dir, "git", "ls-remote", "--heads", "origin", "claude/task/*"), "")
+
+  // A missing trailing slash is forgiven; a malformed value fails loudly.
+  const bad = clone()
+  const configPath = join(bad, ".task", "config.json")
+  const config = JSON.parse(readFileSync(configPath, "utf8")) as Record<string, unknown>
+  config.claimPrefix = "spaces are not refs/"
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`)
+  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/)
+})

package/src/claim.ts

@@ -0,0 +1,302 @@
+/**
+ * `task claim` — atomic ticket claiming, for humans and scheduled agents alike
+ * (NIC-7 / TAS-21). The claim *is* the ticket's work branch: one deterministic
+ * name per ticket, creating it on origin is claiming it, and git's atomic ref
+ * creation is the lock. Branch existence = claimed; the branch dies at merge,
+ * so there is no claim state to clean up.
+ *
+ * The CLI stays board-level and forge-agnostic — everything here is plain git
+ * against `origin`. PR/session awareness belongs to whatever drives the claim
+ * (the implement-task skill, a human).
+ */
+
+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 type { ProjectConfig, Task } from "./types.ts"
+
+/**
+ * The branch namespace claims live under when the board doesn't configure
+ * one. Deliberately vendor-neutral: repos whose workers are Claude Code cloud
+ * sessions set `"claimPrefix": "claude/task/"` in `.task/config.json` — the
+ * one namespace that runtime can push without extra ceremony — and any other
+ * convention is equally valid. The key is committed with the board so every
+ * worker and every clone agree on what "claimed" looks like; a lock two
+ * sides spell differently is no lock at all.
+ */
+export const DEFAULT_CLAIM_PREFIX = "task/claim/"
+
+/** Slash-terminated path segments of ref-safe characters. */
+const CLAIM_PREFIX_SHAPE = /^([A-Za-z0-9._-]+\/)+$/
+
+/**
+ * The board's claim namespace: configured `claimPrefix` (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 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",
+    )
+  }
+  return prefix
+}
+
+/** { 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}`
+}
+
+/**
+ * Why a claim was refused: "claimed" (someone holds the branch — exit 1, pick
+ * the next ticket) vs "invalid" (the ticket or the tree isn't claimable —
+ * exit 2, fix something).
+ */
+export class ClaimError extends Error {
+  readonly kind: "claimed" | "invalid"
+  constructor(message: string, kind: "claimed" | "invalid") {
+    super(message)
+    this.kind = kind
+  }
+}
+
+interface GitResult {
+  status: number
+  stdout: string
+  stderr: string
+}
+
+function git(cwd: string, ...args: string[]): GitResult {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8" })
+  if (result.error) throw result.error
+  return {
+    status: result.status ?? 1,
+    stdout: (result.stdout ?? "").trim(),
+    stderr: (result.stderr ?? "").trim(),
+  }
+}
+
+/** Run git and throw on failure — for the steps that have no soft outcome. */
+function gitMust(cwd: string, ...args: string[]): string {
+  const result = git(cwd, ...args)
+  if (result.status !== 0) {
+    throw new Error(`git ${args[0]} failed: ${result.stderr || result.stdout}`)
+  }
+  return result.stdout
+}
+
+/**
+ * The base every claim branch starts from: origin's default branch. Resolved
+ * from `origin/HEAD` when the clone recorded it, with a main/master fallback
+ * for repos wired up by hand (`git remote add` + push never sets origin/HEAD).
+ */
+function defaultBase(cwd: string): string {
+  const head = git(cwd, "symbolic-ref", "--quiet", "refs/remotes/origin/HEAD")
+  if (head.status === 0) return head.stdout.replace(/^refs\/remotes\//, "")
+  for (const name of ["main", "master"]) {
+    if (git(cwd, "show-ref", "--verify", "--quiet", `refs/remotes/origin/${name}`).status === 0) {
+      return `origin/${name}`
+    }
+  }
+  throw new Error(
+    "couldn't resolve origin's default branch — origin/HEAD is unset and neither origin/main nor origin/master exists",
+  )
+}
+
+/** Every claim branch that exists on origin right now — one network call. */
+export function remoteClaims(cwd: string, namespace: string): Set<string> {
+  const out = gitMust(cwd, "ls-remote", "--heads", "origin", `${namespace}*`)
+  const names = new Set<string>()
+  for (const line of out.split("\n")) {
+    const ref = line.split("\t")[1]
+    if (ref?.startsWith("refs/heads/")) names.add(ref.slice("refs/heads/".length))
+  }
+  return names
+}
+
+function remoteBranchExists(cwd: string, branch: string): boolean {
+  return gitMust(cwd, "ls-remote", "--heads", "origin", branch) !== ""
+}
+
+/** Blockers still in the way — anything not done or canceled still blocks. */
+function openBlockers(store: Store, task: Task): string[] {
+  return task.blockedBy
+    .map((n) => store.get(n))
+    .filter((b): b is Task => b !== null && b.status !== "done" && b.status !== "canceled")
+    .map((b) => b.id)
+}
+
+/** Throws ClaimError("invalid") unless `task` is claimable right now. */
+function assertClaimable(store: Store, task: Task | null, number: number): asserts task is Task {
+  const id = store.displayId(number)
+  if (!task) throw new ClaimError(`no such task: ${id}`, "invalid")
+  if (task.status !== "todo") {
+    throw new ClaimError(`${id} is ${task.status} — only todo tickets can be claimed`, "invalid")
+  }
+  if (task.needsHuman) throw new ClaimError(`${id} needs a human — not claimable`, "invalid")
+  const blockers = openBlockers(store, task)
+  if (blockers.length) {
+    throw new ClaimError(`${id} is blocked by ${blockers.join(", ")} — not claimable`, "invalid")
+  }
+}
+
+export interface ClaimResult {
+  task: Task
+  branch: string
+  base: string
+}
+
+/**
+ * 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
+ * carries `--force-with-lease=<branch>:` (empty expectation = "the ref must
+ * not exist"), so creating the remote branch is a compare-and-swap: two
+ * concurrent claimers of the same ticket, exactly one wins — and a branch
+ * 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 {
+  if (!(store instanceof FileStore)) {
+    throw new ClaimError("claiming needs a text-format board — run `task migrate` first", "invalid")
+  }
+  const cwd = store.root
+  const branch = claimBranch(store.config, number)
+  const id = store.displayId(number)
+
+  // 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")
+  if (tree.status !== 0) {
+    throw new ClaimError(`not a git repository: ${cwd}`, "invalid")
+  }
+  if (git(cwd, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`).status === 0) {
+    throw new ClaimError(
+      `${id} is already claimed — ${branch} exists locally (finish it, or \`task claim --release ${id}\`)`,
+      "claimed",
+    )
+  }
+
+  assertClaimable(store, store.get(number), number)
+  if (tree.stdout !== "") {
+    throw new ClaimError(
+      "working tree is dirty — commit or stash before claiming, the claim switches branches",
+      "invalid",
+    )
+  }
+
+  gitMust(cwd, "fetch", "--quiet", "origin")
+  if (remoteBranchExists(cwd, branch)) {
+    throw new ClaimError(`${id} is already claimed — ${branch} exists on origin`, "claimed")
+  }
+
+  const base = defaultBase(cwd)
+  // So a failed claim can put the checkout back exactly where it was —
+  // a branch name usually, a bare sha when HEAD was detached.
+  const previous =
+    git(cwd, "symbolic-ref", "--quiet", "--short", "HEAD").stdout ||
+    gitMust(cwd, "rev-parse", "HEAD")
+  gitMust(cwd, "checkout", "--quiet", "-b", branch, base)
+
+  const undo = (): void => {
+    git(cwd, "checkout", "--quiet", previous)
+    git(cwd, "branch", "--quiet", "-D", branch)
+  }
+
+  try {
+    // Re-validate against the base branch: the pre-checkout validation read
+    // whatever happened to be checked out, this one reads the truth the claim
+    // will actually be built on.
+    assertClaimable(store, store.get(number), number)
+    store.update(number, { status: "in_progress" })
+    gitMust(cwd, "add", "--", join(store.taskDir, TICKETS_DIR, String(number)))
+    gitMust(cwd, "commit", "--quiet", "-m", `chore(board): claim ${id} → in_progress`)
+  } catch (error) {
+    undo()
+    throw error
+  }
+
+  const push = git(
+    cwd,
+    "push",
+    "--quiet",
+    "-u",
+    "origin",
+    branch,
+    `--force-with-lease=refs/heads/${branch}:`,
+  )
+  if (push.status !== 0) {
+    undo()
+    if (remoteBranchExists(cwd, branch)) {
+      throw new ClaimError(`${id} is already claimed — ${branch} was just created on origin`, "claimed")
+    }
+    throw new ClaimError(
+      `${id}: push of ${branch} was rejected (likely a concurrent claim) — ${push.stderr || "no detail from git"}`,
+      "claimed",
+    )
+  }
+
+  return { task: store.get(number)!, branch, base }
+}
+
+export interface ReleaseResult {
+  branch: string
+  /** Whether a branch was actually there to delete, per side. */
+  remote: boolean
+  local: boolean
+}
+
+/**
+ * Abandon a claim cleanly: delete the branch on origin and locally. The status
+ * flip only ever existed as a commit on that branch, so deleting it *is* the
+ * revert — the default branch never saw in_progress.
+ */
+export function release(store: Store, number: number): ReleaseResult {
+  const cwd = store.root
+  const branch = claimBranch(store.config, number)
+
+  const onBranch =
+    git(cwd, "symbolic-ref", "--quiet", "--short", "HEAD").stdout === branch
+  if (onBranch) {
+    const tree = gitMust(cwd, "status", "--porcelain")
+    if (tree !== "") {
+      throw new ClaimError(
+        `working tree on ${branch} is dirty — commit elsewhere or discard before releasing`,
+        "invalid",
+      )
+    }
+    // Step off the branch so it can be deleted: onto the local default branch
+    // when there is one, detached onto the remote base otherwise.
+    const base = defaultBase(cwd)
+    const local = base.replace(/^origin\//, "")
+    if (git(cwd, "show-ref", "--verify", "--quiet", `refs/heads/${local}`).status === 0) {
+      gitMust(cwd, "checkout", "--quiet", local)
+    } else {
+      gitMust(cwd, "checkout", "--quiet", "--detach", base)
+    }
+  }
+
+  const local = git(cwd, "branch", "--quiet", "-D", branch).status === 0
+  const remote = remoteBranchExists(cwd, branch)
+  if (remote) gitMust(cwd, "push", "--quiet", "origin", "--delete", branch)
+  return { branch, remote, local }
+}
+
+/**
+ * The dispatcher's queue view: `todo` in position order, minus needs-human,
+ * minus blocked, minus tickets whose claim branch already exists on origin
+ * (one ls-remote for the whole namespace). The top entry is next up.
+ */
+export function claimableTasks(store: Store): Task[] {
+  const claimed = remoteClaims(store.root, claimNamespace(store.config))
+  return store
+    .list({ statuses: ["todo"] })
+    .filter((t) => !t.needsHuman)
+    .filter((t) => openBlockers(store, t).length === 0)
+    .filter((t) => !claimed.has(claimBranch(store.config, t.number)))
+}