@nickmeriano/task 0.9.0 → 0.11.0

package/src/claim.ts

@@ -10,8 +10,10 @@
  * (the implement-task skill, a human).
  */
 
-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,
@@ -21,12 +23,16 @@ import {
 } 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 { boardCommitMessage } from "./trailers.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
@@ -127,6 +133,24 @@ function remoteBranchExists(cwd: string, branch: string): boolean {
   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
@@ -158,11 +182,30 @@ 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 {
   /** Claim past the root board's `claims.maxOpenCount` cap. */
   force?: boolean
+  /**
+   * Run the real claim's decision path — every validation, in order, against
+   * live origin state — and stop before the first write. No branch is
+   * created, no commit made, nothing pushed; the checkout is untouched. Exit
+   * semantics match the real command exactly, which is the point: automation
+   * (a scheduler deciding whether to wake a worker) asks "would a claim
+   * succeed right now?" through the same code that would perform it, so the
+   * answer can't drift from the rules. A "yes" is a reading, not a
+   * reservation — the dry run takes no lock, so a concurrent claimer can
+   * still win the ticket a moment later.
+   */
+  dryRun?: boolean
 }
 
 /**
@@ -248,6 +291,8 @@ export function claim(store: Store, key: string, options: ClaimOptions = {}): Cl
   const previous =
     git(cwd, "symbolic-ref", "--quiet", "--short", "HEAD").stdout ||
     gitMust(cwd, "rev-parse", "HEAD")
+  // Every gate is passed; the writes start here. A dry run stops instead.
+  if (options.dryRun) return { task: store.get(key)!, branch, base, previous }
   gitMust(cwd, "checkout", "--quiet", "-b", branch, base)
 
   const undo = (): void => {
@@ -262,7 +307,13 @@ export function claim(store: Store, key: string, options: ClaimOptions = {}): Cl
     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`)
+    gitMust(
+      cwd,
+      "commit",
+      "--quiet",
+      "-m",
+      boardCommitMessage(`chore(board): claim ${id} → in_progress`, "claim", id),
+    )
   } catch (error) {
     undo()
     throw error
@@ -284,7 +335,212 @@ export function claim(store: Store, key: string, options: ClaimOptions = {}): Cl
     )
   }
 
-  return { task: store.get(key)!, 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",
+      boardCommitMessage(`chore(board): claim ${id} → in_progress (lock-only)`, "claim", id, [
+        `Delivered-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,10 +582,123 @@ export function release(store: Store, key: string): ReleaseResult {
 
   const local = git(cwd, "branch", "--quiet", "-D", branch).status === 0
   const remote = remoteBranchExists(cwd, branch)
-  if (remote) gitNetMust(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 blocked, minus
  * tickets whose claim branch already exists on origin (one ls-remote for the