@nickmeriano/task 0.8.0 → 0.10.0

package/src/claim.ts

@@ -10,17 +10,28 @@
  * (the implement-task skill, a human).
  */
 
-import { spawnSync } from "node:child_process"
-import { join } from "node:path"
-import { FileStore, TICKETS_DIR, openBoard } from "./file-store.ts"
+import { rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join, relative, sep } from "node:path"
+import { FileStore, TICKET_FILE, TICKETS_DIR, openBoard } from "./file-store.ts"
+import {
+  GIT_NETWORK_TIMEOUT_MS,
+  defaultBase,
+  git,
+  gitMust,
+  runGit,
+} from "./git.ts"
 import {
   boardConfig,
+  findBoards,
   findBoardsByPrefix,
   findRoot,
   findScopeRoot,
   type Store,
 } from "./store.ts"
-import type { ProjectConfig, Task } from "./types.ts"
+import { isTicketKey } from "./id.ts"
+import { parseTicket, parseTicketLenient, serializeTicket, type TicketDoc } from "./ticket-doc.ts"
+import type { ProjectConfig, Status, Task } from "./types.ts"
 
 /**
  * The branch namespace claims live under when the board doesn't configure
@@ -37,23 +48,23 @@ export const DEFAULT_CLAIM_PREFIX = "task/claim/"
 const CLAIM_PREFIX_SHAPE = /^([A-Za-z0-9._-]+\/)+$/
 
 /**
- * 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
+ * The board's claim namespace: `claims.branchPrefix` (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.
+ *
+ * The pre-0.8 top-level `claimPrefix` spelling is not honored — no consumers,
+ * no compat (TAS-41) — but silently *defaulting* over it would be worse than
+ * a shim: the board's committed lock convention would change under every
+ * worker at once. So its presence refuses, loudly, by name.
  */
 export function claimNamespace(config: ProjectConfig): string {
-  const raw = configuredBranchPrefix(config) ?? DEFAULT_CLAIM_PREFIX
+  if (config.claimPrefix !== undefined && config.claims?.branchPrefix === undefined) {
+    throw new ClaimError(
+      '`claimPrefix` in .task/config.json is the pre-0.8 spelling and is no longer read — rename it to `claims: { "branchPrefix": … }`',
+      "invalid",
+    )
+  }
+  const raw = config.claims?.branchPrefix ?? DEFAULT_CLAIM_PREFIX
   const prefix = raw.endsWith("/") ? raw : `${raw}/`
   if (!CLAIM_PREFIX_SHAPE.test(prefix) || prefix.includes("..") || /(^|\/)\./.test(prefix)) {
     throw new ClaimError(
@@ -79,9 +90,9 @@ export function openClaimCap(root: string): number | 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}`
+/** { prefix: "TAS" }, "x7k4m" → "task/claim/tas-x7k4m" (or under the configured namespace). */
+export function claimBranch(config: ProjectConfig, key: string): string {
+  return `${claimNamespace(config)}${config.prefix.toLowerCase()}-${key}`
 }
 
 /**
@@ -97,52 +108,18 @@ export class ClaimError extends Error {
   }
 }
 
-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)
+/** Network git that throws on failure, with the timeout a real remote deserves. */
+function gitNetMust(cwd: string, ...args: string[]): string {
+  const result = runGit(cwd, args, { timeoutMs: GIT_NETWORK_TIMEOUT_MS })
   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 out = gitNetMust(cwd, "ls-remote", "--heads", "origin", `${namespace}*`)
   const names = new Set<string>()
   for (const line of out.split("\n")) {
     const ref = line.split("\t")[1]
@@ -152,25 +129,48 @@ export function remoteClaims(cwd: string, namespace: string): Set<string> {
 }
 
 function remoteBranchExists(cwd: string, branch: string): boolean {
-  return gitMust(cwd, "ls-remote", "--heads", "origin", branch) !== ""
+  return gitNetMust(cwd, "ls-remote", "--heads", "origin", branch) !== ""
+}
+
+/**
+ * Delete a remote branch and verify the ref is actually gone (TAS-8b7s9).
+ * Some environments — git egress proxies in cloud sessions, notably — drop
+ * branch-deletion pushes while git reports success ("Everything up-to-date"),
+ * so trusting the exit code lets `--release` report a release that didn't
+ * happen: the branch lives on, occupying a WIP-cap slot and advertising a
+ * stale claim to every worker. One bounded ls-remote on a path that already
+ * made network calls turns that lie into a loud failure naming the remedies.
+ */
+function deleteRemoteBranchVerified(cwd: string, branch: string): void {
+  gitNetMust(cwd, "push", "--quiet", "origin", "--delete", branch)
+  if (remoteBranchExists(cwd, branch)) {
+    throw new Error(
+      `origin still has ${branch} after a deletion git reported as successful — this environment silently drops branch deletions. Delete it from one that can: locally, \`task sweep\` on a capable runner (CI), or the forge API/UI.`,
+    )
+  }
 }
 
 /** 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))
+    .map((k) => store.get(k))
     .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)
+/**
+ * Throws ClaimError("invalid") unless `task` is claimable right now. Open asks
+ * deliberately don't gate here: a ticket can be agent-implementable while a
+ * person owes it something in parallel — the done gate keeps that honest. An
+ * ask that must land *before* the work starts is a `blocked_by` on a thin
+ * human ticket, which the blocker check below already enforces.
+ */
+function assertClaimable(store: Store, task: Task | null, key: string): asserts task is Task {
+  const id = store.displayId(key)
   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")
@@ -181,6 +181,13 @@ export interface ClaimResult {
   task: Task
   branch: string
   base: string
+  /**
+   * Where the checkout was before the claim switched it — a branch name
+   * usually, a bare sha when HEAD was detached. The CLI uses it to warn a
+   * branch-pinned session that a plain claim just moved it off its assigned
+   * branch (the `--lock-only` case).
+   */
+  previous: string
 }
 
 export interface ClaimOptions {
@@ -215,7 +222,7 @@ function assertUnderCap(openClaims: Set<string>, root: string, namespace: string
  * 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, options: ClaimOptions = {}): ClaimResult {
+export function claim(store: Store, key: string, 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)) {
@@ -225,8 +232,8 @@ export function claim(store: Store, number: number, options: ClaimOptions = {}):
     )
   }
   const cwd = store.root
-  const branch = claimBranch(store.config, number)
-  const id = store.displayId(number)
+  const branch = claimBranch(store.config, key)
+  const id = store.displayId(key)
 
   // The local-branch check comes before ticket validation on purpose: on the
   // claim branch itself the ticket reads in_progress, and "already claimed"
@@ -246,7 +253,7 @@ export function claim(store: Store, number: number, options: ClaimOptions = {}):
     )
   }
 
-  assertClaimable(store, store.get(number), number)
+  assertClaimable(store, store.get(key), key)
   if (tree.stdout !== "") {
     throw new ClaimError(
       "working tree is dirty — commit or stash before claiming, the claim switches branches",
@@ -254,7 +261,7 @@ export function claim(store: Store, number: number, options: ClaimOptions = {}):
     )
   }
 
-  gitMust(cwd, "fetch", "--quiet", "origin")
+  gitNetMust(cwd, "fetch", "--quiet", "origin")
   // 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).
@@ -282,23 +289,19 @@ export function claim(store: Store, number: number, options: ClaimOptions = {}):
     // 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)))
+    assertClaimable(store, store.get(key), key)
+    store.update(key, { status: "in_progress" })
+    gitMust(cwd, "add", "--", join(store.taskDir, TICKETS_DIR, key))
     gitMust(cwd, "commit", "--quiet", "-m", `chore(board): claim ${id} → in_progress`)
   } catch (error) {
     undo()
     throw error
   }
 
-  const push = git(
+  const push = runGit(
     cwd,
-    "push",
-    "--quiet",
-    "-u",
-    "origin",
-    branch,
-    `--force-with-lease=refs/heads/${branch}:`,
+    ["push", "--quiet", "-u", "origin", branch, `--force-with-lease=refs/heads/${branch}:`],
+    { timeoutMs: GIT_NETWORK_TIMEOUT_MS },
   )
   if (push.status !== 0) {
     undo()
@@ -311,7 +314,210 @@ export function claim(store: Store, number: number, options: ClaimOptions = {}):
     )
   }
 
-  return { task: store.get(number)!, branch, base }
+  return { task: store.get(key)!, branch, base, previous }
+}
+
+// ── Lock-only claims ─────────────────────────────────────────────────────────
+
+/** A file's path relative to the git toplevel — git tree reads speak toplevel paths. */
+function ticketPathFromToplevel(store: Store, key: string): string {
+  const toplevel = gitMust(store.root, "rev-parse", "--show-toplevel")
+  return [relative(toplevel, store.taskDir).split(sep).join("/"), TICKETS_DIR, key, TICKET_FILE]
+    .filter(Boolean)
+    .join("/")
+}
+
+export interface LockOnlyClaimResult {
+  task: Task
+  branch: string
+  base: string
+  /** The checkout's branch at claim time, recorded in the flip commit's `delivered_by:` trailer. */
+  deliveredBy: string
+}
+
+/**
+ * `task claim <id> --lock-only`: mint the claim branch on origin without
+ * touching the checkout. For sessions pinned to a provisioned branch (a
+ * Claude web session, a CI job) the three roles plain `claim` bundles — the
+ * lock, the workspace, and the delivery branch — don't coincide: the session
+ * can't switch branches without breaking its harness contract, and working
+ * outside the lock is how two workers end up on the same ticket.
+ *
+ * So this takes just the lock: the `in_progress` flip commit is built against
+ * origin's default-branch tree in a temporary index (read-tree → hash-object →
+ * update-index → write-tree → commit-tree) and pushed with the same
+ * must-not-exist lease plain `claim` uses — the compare-and-swap is identical,
+ * only the checkout stays where it is (dirty or pinned, doesn't matter). The
+ * flip commit carries a `delivered_by: <branch>` trailer naming the checkout's
+ * branch, so a lock-only claim is legible state — anyone reading the claim
+ * branch sees where the work will actually land. Exit-code contract and
+ * `--release` behave exactly like plain claim.
+ *
+ * Validation reads the *base tree*, not the checkout: the commit is built on
+ * origin's default branch, and the pinned checkout's copy of the ticket may be
+ * stale or diverged — a promote that hasn't merged yet isn't claimable yet.
+ */
+export function claimLockOnly(
+  store: Store,
+  key: string,
+  options: ClaimOptions = {},
+): LockOnlyClaimResult {
+  if (!(store instanceof FileStore)) {
+    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, key)
+  const id = store.displayId(key)
+
+  if (git(cwd, "rev-parse", "--git-dir").status !== 0) {
+    throw new ClaimError(`not a git repository: ${cwd}`, "invalid")
+  }
+  // A local claim branch means some flow here already claimed it the plain way.
+  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",
+    )
+  }
+
+  gitNetMust(cwd, "fetch", "--quiet", "origin")
+  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)
+  const baseSha = gitMust(cwd, "rev-parse", base)
+  const path = ticketPathFromToplevel(store, key)
+  const bytes = git(cwd, "show", `${baseSha}:${path}`)
+  if (bytes.status !== 0) {
+    throw new ClaimError(`no such task on ${base}: ${id} — a lock-only claim is built on origin's default branch, so the ticket must exist there`, "invalid")
+  }
+  // Strict parse first — it carries unknown frontmatter through, so the flip
+  // commit can't silently drop a hand-added field — falling back to lenient
+  // for bytes another checkout or an older CLI wrote oddly (branch reads
+  // degrade, they don't refuse the tree).
+  let doc: TicketDoc | null
+  try {
+    doc = parseTicket(bytes.stdout, `${base}:${path}`)
+  } catch {
+    doc = parseTicketLenient(bytes.stdout)
+  }
+  if (!doc) {
+    throw new ClaimError(`${id} on ${base} isn't a readable ticket file`, "invalid")
+  }
+  if (doc.status !== "todo") {
+    throw new ClaimError(
+      `${id} is ${doc.status} on ${base} — only todo tickets can be claimed (a local promote counts once it lands on the default branch)`,
+      "invalid",
+    )
+  }
+  const blockers = doc.blockedBy.filter((blocker) => {
+    const raw = git(cwd, "show", `${baseSha}:${ticketPathFromToplevel(store, blocker)}`)
+    if (raw.status !== 0) return false // missing blocker doesn't block, as in openBlockers
+    const status = parseTicketLenient(raw.stdout)?.status
+    return status !== undefined && status !== "done" && status !== "canceled"
+  })
+  if (blockers.length) {
+    throw new ClaimError(
+      `${id} is blocked by ${blockers.map((b) => store.displayId(b)).join(", ")} — not claimable`,
+      "invalid",
+    )
+  }
+
+  const deliveredBy =
+    git(cwd, "symbolic-ref", "--quiet", "--short", "HEAD").stdout ||
+    gitMust(cwd, "rev-parse", "HEAD")
+  const flipped = serializeTicket({
+    ...doc,
+    status: "in_progress",
+    updatedAt: new Date().toISOString(),
+  })
+
+  // The temp-index dance claim-io.ts proved out: build the flip commit against
+  // the base tree without ever touching the checkout or its index.
+  const index = join(tmpdir(), `task-claim-index-${process.pid}-${Date.now()}`)
+  const env = { GIT_INDEX_FILE: index }
+  let commit: string
+  try {
+    if (runGit(cwd, ["read-tree", baseSha], { env }).status !== 0) {
+      throw new Error(`git read-tree failed on ${base}`)
+    }
+    const blob = runGit(cwd, ["hash-object", "-w", "--stdin"], { input: flipped })
+    if (blob.status !== 0) throw new Error("git hash-object failed")
+    if (
+      runGit(cwd, ["update-index", "--add", "--cacheinfo", `100644,${blob.stdout},${path}`], { env })
+        .status !== 0
+    ) {
+      throw new Error(`git update-index failed for ${path}`)
+    }
+    const tree = runGit(cwd, ["write-tree"], { env })
+    if (tree.status !== 0) throw new Error("git write-tree failed")
+    const made = git(
+      cwd,
+      "commit-tree",
+      tree.stdout,
+      "-p",
+      baseSha,
+      "-m",
+      `chore(board): claim ${id} → in_progress (lock-only)\n\ndelivered_by: ${deliveredBy}`,
+    )
+    if (made.status !== 0) {
+      throw new Error("git commit-tree failed — is git user.name/user.email configured?")
+    }
+    commit = made.stdout
+  } finally {
+    rmSync(index, { force: true })
+  }
+
+  // The same compare-and-swap as plain claim: the empty lease means "the ref
+  // must not exist", so two concurrent claimers still get exactly one winner.
+  const push = runGit(
+    cwd,
+    ["push", "--quiet", "origin", `${commit}:refs/heads/${branch}`, `--force-with-lease=refs/heads/${branch}:`],
+    { timeoutMs: GIT_NETWORK_TIMEOUT_MS },
+  )
+  if (push.status !== 0) {
+    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",
+    )
+  }
+  // Keep the remote-tracking ref in step so an immediate read (the inbox, the
+  // serve UI) sees the claim without another fetch.
+  git(cwd, "update-ref", `refs/remotes/origin/${branch}`, commit)
+
+  // The checkout's copy of the ticket wasn't touched — present the claim as
+  // made, preferring the local ticket (asks, relations) when it exists.
+  const local = store.get(key)
+  const task: Task = local
+    ? { ...local, status: "in_progress" }
+    : {
+        id,
+        key,
+        title: doc.title,
+        description: doc.description,
+        status: "in_progress",
+        tags: doc.tags,
+        goal: doc.goal,
+        needsHuman: false,
+        asks: [],
+        blocks: [],
+        blockedBy: doc.blockedBy,
+        prs: doc.prs,
+        position: doc.position,
+        createdAt: doc.createdAt,
+        updatedAt: doc.updatedAt,
+      }
+  return { task, branch, base, deliveredBy }
 }
 
 export interface ReleaseResult {
@@ -326,9 +532,9 @@ export interface ReleaseResult {
  * 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 {
+export function release(store: Store, key: string): ReleaseResult {
   const cwd = store.root
-  const branch = claimBranch(store.config, number)
+  const branch = claimBranch(store.config, key)
 
   const onBranch =
     git(cwd, "symbolic-ref", "--quiet", "--short", "HEAD").stdout === branch
@@ -353,22 +559,135 @@ export function release(store: Store, number: number): ReleaseResult {
 
   const local = git(cwd, "branch", "--quiet", "-D", branch).status === 0
   const remote = remoteBranchExists(cwd, branch)
-  if (remote) gitMust(cwd, "push", "--quiet", "origin", "--delete", branch)
+  if (remote) deleteRemoteBranchVerified(cwd, branch)
   return { branch, remote, local }
 }
 
+// ── Sweep — the janitor verb ─────────────────────────────────────────────────
+
+export interface SweptBranch {
+  branch: string
+  /** Display id of the ticket the branch locks — for "missing", the id the branch name claims. */
+  ticket: string
+  reason: "done" | "canceled" | "missing"
+}
+
+export interface SweepResult {
+  swept: SweptBranch[]
+  kept: { branch: string; ticket: string; status: Status }[]
+  /**
+   * Branches under the claim namespace whose name the claim protocol could
+   * not have minted — no board's `<prefix>-`, or a segment that isn't a valid
+   * ticket key (pre-migration numeric claims like `tas-31`, hand-made
+   * branches). Deliberately never deleted: sweep's jurisdiction is exactly
+   * the branches `task claim` creates, and a name outside the scheme may be
+   * an open PR's head or someone's parked work. Reported so a human can
+   * clean them up knowingly.
+   */
+  skipped: string[]
+  failed: { branch: string; error: string }[]
+}
+
+/**
+ * `task sweep`: for every claim branch on origin whose ticket is done,
+ * canceled, or missing on the current checkout, delete the branch — with the
+ * same deletion verification as `--release`, so a survivor is a failure, never
+ * a silent lie. This is the liveness half of the lock: environments that can't
+ * delete remote branches leave stale claims behind (`--release` there fails
+ * loudly rather than lying), and sweep, run from a runner that *can* delete
+ * (CI on push-to-main or cron, a laptop cron), heals them.
+ *
+ * Deliberately pure git and zero judgment — no vendor awareness, no agent in
+ * the loop — and scoped to exactly the branches the claim protocol mints:
+ * `<namespace><prefix>-<key>` with a valid ticket key. A branch under the
+ * namespace that doesn't fit the scheme (a pre-migration numeric claim, a
+ * hand-made branch) is *skipped and reported*, never deleted — it may be an
+ * open PR's head, and deleting what claiming didn't create isn't janitorial
+ * work, it's a judgment call. Within the scheme, the ticket's status on this
+ * checkout decides: done/canceled/missing → delete, anything live → keep.
+ * Boards are discovered repo-wide, the way `task serve` finds them, so one
+ * sweep covers every board's namespace.
+ */
+export function sweep(cwd: string): SweepResult {
+  const scope = findScopeRoot(cwd)
+  const boards: Store[] = []
+  for (const ref of findBoards(scope)) {
+    try {
+      boards.push(openBoard(ref.root))
+    } catch {
+      // An unreadable board can't vouch for its branches — skip it.
+    }
+  }
+  if (boards.length === 0) {
+    throw new ClaimError(
+      "no .task directory found in this directory or any parent — run `task init` first",
+      "invalid",
+    )
+  }
+
+  // One ls-remote per distinct namespace (normally exactly one — `task check`
+  // lints that boards agree), each branch matched to the board whose
+  // `<prefix>-` leads its final segment.
+  const namespaces = new Map<string, Store[]>()
+  for (const store of boards) {
+    let namespace: string
+    try {
+      namespace = claimNamespace(store.config)
+    } catch {
+      continue // a malformed prefix can't have minted branches worth sweeping
+    }
+    const list = namespaces.get(namespace) ?? []
+    list.push(store)
+    namespaces.set(namespace, list)
+  }
+
+  const result: SweepResult = { swept: [], kept: [], skipped: [], failed: [] }
+  for (const [namespace, stores] of namespaces) {
+    for (const branch of [...remoteClaims(scope, namespace)].sort()) {
+      const rest = branch.slice(namespace.length)
+      const store = stores.find((s) =>
+        rest.startsWith(`${s.config.prefix.toLowerCase()}-`),
+      )
+      const key = store ? rest.slice(store.config.prefix.length + 1) : null
+      if (!store || !key || !isTicketKey(key)) {
+        result.skipped.push(branch)
+        continue
+      }
+      const task = store.get(key)
+      if (task && task.status !== "done" && task.status !== "canceled") {
+        result.kept.push({ branch, ticket: task.id, status: task.status })
+        continue
+      }
+      const entry: SweptBranch = task
+        ? { branch, ticket: task.id, reason: task.status as "done" | "canceled" }
+        : { branch, ticket: store.displayId(key), reason: "missing" }
+      try {
+        deleteRemoteBranchVerified(scope, branch)
+        git(scope, "update-ref", "-d", `refs/remotes/origin/${branch}`)
+        result.swept.push(entry)
+      } catch (error) {
+        result.failed.push({
+          branch,
+          error: error instanceof Error ? error.message : String(error),
+        })
+      }
+    }
+  }
+  return result
+}
+
 /**
- * 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.
+ * The dispatcher's queue view: `todo` in position order, minus blocked, minus
+ * tickets whose claim branch already exists on origin (one ls-remote for the
+ * whole namespace). The top entry is next up. Open asks don't exclude a
+ * ticket — see assertClaimable.
  */
 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)))
+    .filter((t) => !claimed.has(claimBranch(store.config, t.key)))
 }
 
 export interface PromoteResult {
@@ -380,15 +699,16 @@ export interface PromoteResult {
 /**
  * `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.
+ * so a one-line backlog ticket is promotable. Blockers 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. Open asks aren't a hold at all: they don't gate
+ * claiming, only done. 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)
+export function promote(store: Store, key: string): PromoteResult {
+  const task = store.get(key)
+  const id = store.displayId(key)
   if (!task) throw new ClaimError(`no such task: ${id}`, "invalid")
   if (task.status !== "backlog") {
     throw new ClaimError(
@@ -396,9 +716,8 @@ export function promote(store: Store, number: number): PromoteResult {
       "invalid",
     )
   }
-  const updated = store.update(number, { status: "todo" })
+  const updated = store.update(key, { 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 }
@@ -474,7 +793,7 @@ export function claimNext(stores: Store[], options: ClaimOptions = {}): ClaimRes
   for (const store of stores) {
     for (const task of claimableTasks(store)) {
       try {
-        return claim(store, task.number, options)
+        return claim(store, task.key, options)
       } catch (error) {
         // Claimed out from under us, or changed since listing — next in line.
         if (error instanceof ClaimError) continue