@biffo/cli 0.247.8 → 0.248.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.247.8",
+  "version": "0.248.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",

package/scripts/claim.sh

@@ -91,6 +91,9 @@ set -u
 
 ISSUE=""
 REPO=""
+HOLDER=""
+RELEASE=""
+HOLDER_MARK="claim-holder:"
 CHECK_ONLY=""
 GUARD_BRANCH=""
 
@@ -106,6 +109,15 @@ while [ $# -gt 0 ]; do
       shift 2
       ;;
     --check) CHECK_ONLY=1; shift ;;
+    --as)
+      HOLDER="${2:-}"
+      shift 2
+      ;;
+    --release)
+      HOLDER="${2:-}"
+      RELEASE=1
+      shift 2
+      ;;
     --guard)
       GUARD_BRANCH="${2:-}"
       shift 2
@@ -128,6 +140,46 @@ gh_issue() { if [ -n "$REPO" ]; then gh issue "$@" --repo "$REPO"; else gh issue
 gh_pr() { if [ -n "$REPO" ]; then gh pr "$@" --repo "$REPO"; else gh pr "$@"; fi; }
 gh_label() { if [ -n "$REPO" ]; then gh label "$@" --repo "$REPO"; else gh label "$@"; fi; }
 
+# Does the newest claim comment on $1 carry holder token $2? (#1279)
+#
+# Reads the LAST claim comment rather than any, so a re-claim by a different
+# session supersedes an older one rather than both matching for ever. Returns
+# non-zero when it cannot tell -- an unreadable comment list must never read as
+# "yours", or the flag becomes a way to steal a claim by guessing.
+claim_held_by() {
+  _c=$(gh_issue view "$1" --json comments \
+    --jq "[.comments[]? | select(.body | contains(\"$HOLDER_MARK\"))] | last | .body // \"\"" \
+    2>/dev/null) || return 1
+  [ -n "$_c" ] || return 1
+  case "$_c" in
+    *"$HOLDER_MARK$2"*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# This repo as `owner/name`, so a closing reference can be checked against it.
+# GitHub records a CROSS-REPO closing reference in the same list as a local one
+# -- tabsii-lms#43 closes tabsii-platform#553 -- so the number alone is not an
+# answer, and matching on it reproduces the very defect this replaces (#1281).
+#
+# Resolved LAZILY, on first use. Computing it at load cost a `gh repo view` on
+# every single push, including the overwhelmingly common case where `--guard`
+# skips silently because the branch names no issue -- a guard that is meant to
+# touch nothing was suddenly making a network call per push.
+SLUG=""
+SLUG_RESOLVED=""
+repo_slug() {
+  if [ -z "$SLUG_RESOLVED" ]; then
+    SLUG_RESOLVED=1
+    if [ -n "$REPO" ]; then
+      SLUG="$REPO"
+    else
+      SLUG=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null || echo "")
+    fi
+  fi
+  printf '%s' "$SLUG"
+}
+
 # `git ls-remote --heads ""` fails outright ("fatal: bad repository ''") rather
 # than falling back to the default remote — `${REPO:+url}` expands to an empty
 # STRING ARGUMENT when $REPO is unset, not to no argument at all. That silently
@@ -144,11 +196,51 @@ remote_branches() {
 }
 
 LABEL=in-progress
+
+# --- holder identity (#1279) -------------------------------------------------
+#
+# A claim used to record WHEN and WHO, and every session on a workstation claims
+# under the same GitHub actor. So a delegated agent could not distinguish
+# "my orchestrator claimed this for me" from "a stranger claimed it 90 seconds
+# ago", and the safe reading is to stop. On 2026-08-04 four agents were
+# dispatched onto pre-claimed issues; one ran the check first and correctly
+# refused to start, producing nothing. Whether a delegate works or stalls
+# depended on whether it happened to check before starting.
+#
+# `--as <token>` makes the claim answerable: an existing claim carrying the same
+# token reads as YOUR claim and returns free. `--release <token>` refuses to
+# clear somebody else's.
+#
+# The token is opaque and never a secret -- it identifies a session, not a
+# person, and appears in a public comment.
+
 TAKEN=0
 REASONS=""
 
 note() { REASONS="${REASONS}  $1\n"; TAKEN=1; }
 
+# --- --release <token>: only the holder clears it (#1279) --------------------
+#
+# A claim nobody can prove ownership of is one anybody can clear, and a stale
+# label left behind by a crashed session is indistinguishable from a live one.
+# Refusing a mismatched release is what makes the token worth recording.
+if [ -n "$RELEASE" ]; then
+  if claim_held_by "$ISSUE" "$HOLDER"; then
+    gh_issue edit "$ISSUE" --remove-label "$LABEL" >/dev/null 2>&1 || {
+      echo "${RED}claim: could not remove the '$LABEL' label.${OFF}" >&2
+      exit 2
+    }
+    echo "${GREEN}Released.${OFF} ${DIM}(held by $HOLDER)${OFF}"
+    exit 0
+  fi
+  echo "${RED}claim: #$ISSUE is not held by '$HOLDER' — refusing to release it.${OFF}" >&2
+  echo "${DIM}  Clearing somebody else's claim is how two sessions end up on one issue.${OFF}" >&2
+  echo "${DIM}  If the claim is genuinely stale (AGENTS.md: over an hour, no branch, no PR),${OFF}" >&2
+  echo "${DIM}  remove the label by hand and say so in a comment.${OFF}" >&2
+  exit 1
+fi
+
+
 # --- --guard <branch>: the enforced pre-push gate -----------------------------
 #
 # Deliberately short-circuits before any of the four-signal machinery below —
@@ -171,9 +263,11 @@ if [ -n "$GUARD_BRANCH" ]; then
   cannot_tell_reasons=""
 
   # --- an open PR referencing the issue, excluding our own branch's PR --------
+  slug=$(repo_slug)
   pr_err=$(mktemp)
-  open_prs=$(gh_pr list --state open --limit 100 --json number,title,body,headRefName \
-    --jq "[.[] | select(((.title + \" \" + .body) | test(\"(^|[^0-9])#$guard_issue([^0-9]|\$)\")) or (.headRefName | test(\"(^|[^0-9])$guard_issue([^0-9]|\$)\")))] | .[] | select(.headRefName != \"$GUARD_BRANCH\") | \"#\(.number) \(.headRefName)\"" \
+  slug=$(repo_slug)
+open_prs=$(gh_pr list --state open --limit 100 --json number,headRefName,closingIssuesReferences \
+    --jq "[.[] | select(([.closingIssuesReferences[]? | select(.number == $guard_issue and ((.repository.owner.login + \"/\" + .repository.name) == \"$slug\"))] | length > 0) or (.headRefName | test(\"(^|[^0-9])$guard_issue([^0-9]|\$)\")))] | .[] | select(.headRefName != \"$GUARD_BRANCH\") | \"#\(.number) \(.headRefName)\"" \
     2>"$pr_err")
   pr_status=$?
   pr_err_text=$(cat "$pr_err")
@@ -265,7 +359,15 @@ fi
 case ",$labels," in
   *",$LABEL,"*)
     updated=$(gh_issue view "$ISSUE" --json updatedAt --jq .updatedAt 2>/dev/null)
-    note "${YELLOW}label${OFF}      carries '$LABEL' (issue last updated $updated)"
+    # Whose claim is it? (#1279) A claim carrying OUR token is not a collision --
+    # it is the orchestrator that dispatched us. Without this a delegated agent
+    # cannot tell its own reservation from a stranger's and correctly refuses to
+    # start, which is the failure this flag exists to remove.
+    if [ -n "$HOLDER" ] && claim_held_by "$ISSUE" "$HOLDER"; then
+      echo "${DIM}label      carries '$LABEL', held by ${HOLDER} — that is you${OFF}"
+    else
+      note "${YELLOW}label${OFF}      carries '$LABEL' (issue last updated $updated)"
+    fi
     ;;
 esac
 
@@ -275,8 +377,9 @@ esac
 # Matches the issue number in the title or body as a whole number, so #118 does
 # not match #1188.
 
-open_prs=$(gh_pr list --state open --limit 100 --json number,title,body,headRefName \
-  --jq "[.[] | select(((.title + \" \" + .body) | test(\"(^|[^0-9])#$ISSUE([^0-9]|\$)\")) or (.headRefName | test(\"(^|[^0-9])$ISSUE([^0-9]|\$)\")))] | .[] | \"#\(.number) \(.headRefName)\"" 2>/dev/null)
+slug=$(repo_slug)
+open_prs=$(gh_pr list --state open --limit 100 --json number,headRefName,closingIssuesReferences \
+  --jq "[.[] | select(([.closingIssuesReferences[]? | select(.number == $ISSUE and ((.repository.owner.login + \"/\" + .repository.name) == \"$slug\"))] | length > 0) or (.headRefName | test(\"(^|[^0-9])$ISSUE([^0-9]|\$)\")))] | .[] | \"#\(.number) \(.headRefName)\"" 2>/dev/null)
 
 if [ -n "$open_prs" ]; then
   printf '%s\n' "$open_prs" | while IFS= read -r pr; do
@@ -305,8 +408,9 @@ fi
 # Not "taken" — "possibly already done". #1165 was built and merged in three
 # minutes; the only trace afterwards is a merged PR.
 
-merged=$(gh_pr list --state merged --limit 30 --json number,title,body,mergedAt \
-  --jq "[.[] | select((.title + \" \" + .body) | test(\"(^|[^0-9])#$ISSUE([^0-9]|\$)\"))] | .[0] | select(. != null) | \"#\(.number) merged \(.mergedAt[0:16])\"" 2>/dev/null)
+slug=$(repo_slug)
+merged=$(gh_pr list --state merged --limit 30 --json number,mergedAt,closingIssuesReferences \
+  --jq "[.[] | select(([.closingIssuesReferences[]? | select(.number == $ISSUE and ((.repository.owner.login + \"/\" + .repository.name) == \"$slug\"))] | length > 0))] | .[0] | select(. != null) | \"#\(.number) merged \(.mergedAt[0:16])\"" 2>/dev/null)
 
 if [ -n "$merged" ]; then
   echo "  ${YELLOW}merged${OFF}     $merged"
@@ -361,7 +465,7 @@ gh_issue edit "$ISSUE" --add-label "$LABEL" >/dev/null 2>&1 || {
   exit 2
 }
 gh_issue comment "$ISSUE" \
-  --body "Claimed at $(date -u +%FT%TZ) by \`$(git config user.name 2>/dev/null || echo agent)\`. Release it — remove the label — on merge, or if you stop." \
+  --body "Claimed at $(date -u +%FT%TZ) by \`$(git config user.name 2>/dev/null || echo agent)\`.${HOLDER:+ ${HOLDER_MARK}${HOLDER}} Release it — remove the label — on merge, or if you stop." \
   >/dev/null 2>&1
 
 echo "${GREEN}Claimed.${OFF}"