@nickmeriano/task 0.8.0 → 0.10.0

package/dist/claim.d.ts

@@ -10,7 +10,7 @@
  * (the implement-task skill, a human).
  */
 import { type Store } from "./store.ts";
-import type { ProjectConfig, Task } from "./types.ts";
+import type { ProjectConfig, Status, 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
@@ -22,17 +22,14 @@ import type { ProjectConfig, Task } from "./types.ts";
  */
 export declare const DEFAULT_CLAIM_PREFIX = "task/claim/";
 /**
- * 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 declare function configuredBranchPrefix(config: ProjectConfig): string | undefined;
-/**
- * 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 declare function claimNamespace(config: ProjectConfig): string;
 /**
@@ -42,8 +39,8 @@ export declare function claimNamespace(config: ProjectConfig): string;
  * Absent, unparseable or nonsensical values all mean "no cap".
  */
 export declare function openClaimCap(root: string): number | undefined;
-/** { prefix: "TAS" }, 21 → "task/claim/tas-21" (or under the configured namespace). */
-export declare function claimBranch(config: ProjectConfig, number: number): string;
+/** { prefix: "TAS" }, "x7k4m" → "task/claim/tas-x7k4m" (or under the configured namespace). */
+export declare function claimBranch(config: ProjectConfig, key: string): 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 —
@@ -59,6 +56,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 {
     /** Claim past the root board's `claims.maxOpenCount` cap. */
@@ -73,7 +77,37 @@ export interface ClaimOptions {
  * 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, options?: ClaimOptions): ClaimResult;
+export declare function claim(store: Store, key: string, options?: ClaimOptions): ClaimResult;
+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 declare function claimLockOnly(store: Store, key: string, options?: ClaimOptions): LockOnlyClaimResult;
 export interface ReleaseResult {
     branch: string;
     /** Whether a branch was actually there to delete, per side. */
@@ -85,11 +119,61 @@ 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 declare function release(store: Store, number: number): ReleaseResult;
+export declare function release(store: Store, key: string): ReleaseResult;
+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 declare function sweep(cwd: string): SweepResult;
 /**
- * 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 declare function claimableTasks(store: Store): Task[];
 export interface PromoteResult {
@@ -100,13 +184,14 @@ 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 declare function promote(store: Store, number: number): PromoteResult;
+export declare function promote(store: Store, key: string): PromoteResult;
 /**
  * The boards `claim --next` and `list --claimable` select over, in priority
  * order. Resolution: an explicit `--board` list > the root board's top-level

package/dist/claim.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claim.d.ts","sourceRoot":"","sources":["../src/claim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAKL,KAAK,KAAK,EACX,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,gBAAgB,CAAA;AAKjD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAU5D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO7D;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,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAoBD;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,WAAW,CAiG3F;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;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,CAAA;IACV,2EAA2E;IAC3E,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAgBnE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,CA+BzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,GAAE,YAAiB,GAAG,WAAW,GAAG,IAAI,CA6BzF"}
+{"version":3,"file":"claim.d.ts","sourceRoot":"","sources":["../src/claim.ts"],"names":[],"mappings":"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"}