@nickmeriano/task 0.5.0 → 0.7.0

package/README.md

@@ -3,10 +3,12 @@
 A task manager that lives in your repo.
 
 Tasks and their status are coupled to the code — so keep them next to it.
-State is a SQLite database in `.task/` at your project root: no accounts, no
-connectors, no drift between the board and the branch. Built for the way
-projects work now — you *and* your AI agents share one backlog, and the board
-updates live while agents move tickets from another terminal.
+State is plain text in `.task/` at your project root — one markdown file per
+ticket and per comment: no accounts, no connectors, no drift between the board
+and the branch. Ticket changes show up as readable diffs in PRs, and two
+branches editing different tickets merge cleanly. Built for the way projects
+work now — you *and* your AI agents share one backlog, and the board updates
+live while agents move tickets from another terminal.
 
 ```bash
 npx @nickmeriano/task init
@@ -46,10 +48,53 @@ task done 1                    # → done
 task link 2 --blocked-by 1     # dependency, visible from both tasks
 task update 1 --pr https://github.com/you/repo/pull/42
 task comment 1 "shipped in #42" --author claude
+task boards                    # every board in the repo, with prefixes
+task archive --all             # move finished tickets to .task/archive/
 task serve                     # opens the kanban + table UI, live
 task publish                   # same board, at a URL you can open on a phone
 ```
 
+## Claiming — so two workers never pick up the same ticket
+
+When agents (or agents *and* you) work one backlog, picking up a ticket needs
+a lock. `task claim` is that lock, built out of things git already guarantees:
+
+```bash
+task claim TAS-21            # claim it: branch + status flip + push
+task list --claimable        # the queue: what a worker may pick up next
+task claim --release TAS-21  # abandon a claim cleanly
+```
+
+- **The claim is the work branch.** `task claim TAS-21` branches
+  `task/claim/tas-21` off origin's default branch, flips the ticket to
+  `in_progress` as the branch's first commit, and pushes. The branch existing
+  on origin *is* the claim — nothing side-band to clean up, because the branch
+  was needed anyway and dies at merge.
+- **The namespace is yours.** `task/claim/` is only the default —
+  `"claimPrefix"` in `.task/config.json` moves the whole namespace, and it
+  lives in the committed config on purpose: every worker and every clone must
+  agree on what "claimed" looks like, or there is no lock. If your workers are
+  Claude Code cloud sessions, set `"claimPrefix": "claude/task/"` — that
+  runtime can push `claude/`-prefixed branches without extra ceremony. Pick
+  the value before the first claim; renaming later strands in-flight claims.
+- **Atomic by construction.** The push only succeeds if the branch doesn't
+  exist yet (a compare-and-swap on the ref), so two concurrent claimers of the
+  same ticket get exactly one winner. Exit codes are the contract: `0` claimed,
+  `1` already claimed (pick the next ticket), `2` not claimable — not `todo`,
+  blocked, `--needs-human`, or a dirty working tree.
+- **The lifecycle rides the branch.** Claim = `in_progress`; before the PR is
+  marked ready, `task done` + `task update --pr` on the branch; the merge lands
+  code and `done` together, and the branch auto-deletes. Between claim and
+  merge the default branch still says `todo` — the branch is the truth about
+  in-flight work, and `git ls-remote origin 'task/claim/*'` (or your
+  configured namespace) lists all of it.
+- **Claim before you work — humans too.** The same verb covers manual work:
+  run `task claim <id>` before starting a ticket yourself and any scheduled
+  agent will skip it. `task list --claimable` shows `todo` tickets in position
+  order minus blocked, needs-human, and already-claimed — the top entry is
+  what an autonomous worker takes next, which makes column order your priority
+  queue.
+
 ## From anywhere
 
 `task serve` is localhost, which is the right answer right up until you're not
@@ -83,9 +128,55 @@ one committing.
   immediately; your tasks are untouched, because they were only ever read from
   `.task/`. Changing your mind about *visibility* doesn't need that at all —
   `task publish --private` is enough.
+- **Any branch.** The board renders your default branch, but `?ref=<branch>`
+  renders any other — and the header grows a branch switcher when there's more
+  than one. That's PR review for board changes: see the board as the PR would
+  leave it, before merging. Locally none of this is needed — `task serve`
+  shows your working tree, so previewing a branch is `git checkout`.
+
+Since the preview URL is predictable, a small workflow in *your* repo can
+comment it on every PR that touches board state — the App itself stays
+read-only and never writes to your repository:
+
+```yaml
+# .github/workflows/board-preview.yml
+name: Board preview
+on:
+  pull_request:
+    paths: [".task/**", "**/.task/**"]
+permissions:
+  pull-requests: write
+jobs:
+  comment:
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const branch = context.payload.pull_request.head.ref
+            const url = `https://task.nickmeriano.com/${context.repo.owner}/${context.repo.repo}?ref=${encodeURIComponent(branch)}`
+            const marker = "<!-- board-preview -->"
+            const body = `${marker}\n📋 [Preview the board at \`${branch}\`](${url})`
+            const comments = await github.paginate(github.rest.issues.listComments, { ...context.repo, issue_number: context.issue.number })
+            const existing = comments.find((c) => c.body?.startsWith(marker))
+            if (existing) await github.rest.issues.updateComment({ ...context.repo, comment_id: existing.id, body })
+            else await github.rest.issues.createComment({ ...context.repo, issue_number: context.issue.number, body })
+```
 
 - Ids are `PREFIX-12` or just `12`; the prefix is the first three letters of
   the project name ("phone" → `PHO-1`), or whatever `task init --prefix` says.
+- Ids route by prefix: a bare `12` means the nearest board, while `TAS-12`
+  reaches the TAS board from anywhere in the monorepo. An unknown or ambiguous
+  prefix fails loudly instead of guessing. `task boards` lists every board —
+  prefix, name, path, open count — with a `*` on the one commands target from
+  the current directory.
+- `task archive <id>` moves a done/canceled ticket's directory to
+  `.task/archive/` — off the board and out of every hot path, so boards stay
+  fast as history accumulates. Archived tickets stay readable (`task show`,
+  `task list --archived`), keep their comments, and their numbers stay
+  reserved forever. `task archive --all` sweeps everything finished;
+  `task unarchive <id>` puts one back.
 - Statuses: `backlog` `todo` `in_progress` `done` `canceled`.
 - A task carries tags, at most one milestone, and a `--needs-human` flag for
   work an agent can't finish alone. `--tag a,b` matches either tag.
@@ -113,13 +204,18 @@ one committing.
   root and it serves every nested board from one server, with a board switcher
   in the header. Run it inside a package and you get just that board. Every
   other command stays scoped to the nearest `.task/`.
-- The database self-migrates when it's opened, so pulling a colleague's
-  `.task/` and running any command brings it up to date in place.
+- Boards from before 0.6 stored their state as a committed SQLite database;
+  those keep working as-is, and `task migrate` moves one onto text files
+  (the database stays on disk as an ignored backup).
 
 ## How it's built
 
-- **Zero dependencies.** Storage is Node's built-in `node:sqlite` (Node ≥
-  22.13) — nothing to compile, so `npx` starts in about a second.
+- **Zero dependencies.** Storage is markdown files with a tiny frontmatter
+  block — reviewable in a PR, mergeable by git, editable by hand. Comments are
+  one file each (append-only merges cleanly), and the `blocks`/`blocked-by`
+  relation is stored on one side only, so its two views can't disagree.
+  Legacy boards read through Node's built-in `node:sqlite` (Node ≥ 22.13) —
+  nothing to compile, so `npx` starts in about a second.
 - **Realtime is a file watch.** `task serve` is one `node:http` process: the
   prebuilt UI, a JSON API, and a server-sent-events stream that pings whenever
   anything writes to `.task/` — this UI, another terminal, an agent mid-run.

package/dist/claim.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `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 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 declare const DEFAULT_CLAIM_PREFIX = "task/claim/";
+/**
+ * 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 declare function claimNamespace(config: ProjectConfig): string;
+/** { prefix: "TAS" }, 21 → "task/claim/tas-21" (or under the configured namespace). */
+export declare function claimBranch(config: ProjectConfig, number: number): string;
+/**
+ * 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 declare class ClaimError extends Error {
+    readonly kind: "claimed" | "invalid";
+    constructor(message: string, kind: "claimed" | "invalid");
+}
+/** Every claim branch that exists on origin right now — one network call. */
+export declare function remoteClaims(cwd: string, namespace: string): Set<string>;
+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 declare function claim(store: Store, number: number): ClaimResult;
+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 declare function release(store: Store, number: number): ReleaseResult;
+/**
+ * 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 declare function claimableTasks(store: Store): Task[];
+//# sourceMappingURL=claim.d.ts.map

package/dist/claim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim.d.ts","sourceRoot":"","sources":["../src/claim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,gBAAgB,CAAA;AAKjD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAU5D;AAED,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAA;gBACxB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,SAAS;CAIzD;AA6CD,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAQxE;AA4BD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAkF/D;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,OAAO,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CA6BnE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,CAOnD"}

package/dist/claim.js

@@ -0,0 +1,237 @@
+/**
+ * `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.js";
+/**
+ * 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) {
+    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, number) {
+    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 {
+    kind;
+    constructor(message, kind) {
+        super(message);
+        this.kind = kind;
+    }
+}
+function git(cwd, ...args) {
+    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, ...args) {
+    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) {
+    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, namespace) {
+    const out = gitMust(cwd, "ls-remote", "--heads", "origin", `${namespace}*`);
+    const names = new Set();
+    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, branch) {
+    return gitMust(cwd, "ls-remote", "--heads", "origin", branch) !== "";
+}
+/** Blockers still in the way — anything not done or canceled still blocks. */
+function openBlockers(store, task) {
+    return task.blockedBy
+        .map((n) => store.get(n))
+        .filter((b) => b !== null && b.status !== "done" && b.status !== "canceled")
+        .map((b) => b.id);
+}
+/** Throws ClaimError("invalid") unless `task` is claimable right now. */
+function assertClaimable(store, task, number) {
+    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");
+    }
+}
+/**
+ * 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, number) {
+    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 = () => {
+        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 };
+}
+/**
+ * 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, number) {
+    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) {
+    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)));
+}
+//# sourceMappingURL=claim.js.map

package/dist/claim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim.js","sourceRoot":"","sources":["../src/claim.ts"],"names":[],"mappings":"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"}

package/dist/claim.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=claim.test.d.ts.map

package/dist/claim.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim.test.d.ts","sourceRoot":"","sources":["../src/claim.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}