fix(scripts): let issue.sh claim work on a write:issue-only token

`claim` is the one step the workflow requires before the first edit, and
it failed outright on a token scoped to the work it does: `me()` calls
`GET /user` purely to name the assignee, and that endpoint needs
read:user. So the documented process was blocked by its own tooling, and
the fallback was to do the assignment, the label and the comment by hand
— which is the half-made claim `claim` exists to prevent.

GITEA_USER short-circuits the lookup, so least privilege is enough. The
lookup stays as the fallback because it is right when the scope is there
and needs no setup. Failure is now actionable and says both remedies,
and it still happens before any of the three halves are mutated.

Closes #130

scripts/dev-headless.sh

@@ -97,55 +97,6 @@ if [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
 fi
 rm -f "$PID_FILE"
 
-# ── Refuse to inherit somebody else's port ───────────────────────────
-# The PID check above only knows about *this* worktree: `make dev-stop`
-# kills the pid in this .dev/app.pid and nothing else.  Several worktrees
-# of this repo share the default port, so an app orphaned by a deleted
-# worktree goes on listening with nothing left to stop it.
-#
-# Without this check the new app starts, fails to bind, exits — and every
-# curl and playwright-cli call afterwards goes to the *other* process, so
-# the harness reports facts about an app nobody asked for.  That is not a
-# quiet wrongness either: it presented as
-# "no such table: libraries" against a freshly created YJ_HOME, which
-# reads exactly like applySchema or staleshape.go having gone wrong and
-# is a frightening place to start looking.
-#
-# The startup wait below cannot catch it, because the health check is
-# satisfied by *any* app on the port — which is precisely the failure.
-# So it is refused here, before anything is launched, rather than warned
-# about.  --port already exists for the legitimate second-app case.
-port_holder() {
-	command -v ss >/dev/null || return 0
-	ss -lptn "sport = :$PORT" 2>/dev/null | grep -oP 'pid=\K[0-9]+' | head -n 1
-}
-
-if curl -sf -o /dev/null --max-time 2 "http://localhost:$PORT/" ||
-	[ -n "$(port_holder)" ]; then
-	holder="$(port_holder)"
-	echo "dev-headless: :$PORT is already in use; refusing to start" >&2
-	if [ -n "$holder" ]; then
-		# /proc/<pid>/cwd names the checkout it belongs to, and says
-		# "(deleted)" for the orphaned-worktree case that is the whole
-		# reason this is worth a check.
-		cwd="$(readlink "/proc/$holder/cwd" 2>/dev/null || echo unknown)"
-		cmd="$(tr '\0' ' ' <"/proc/$holder/cmdline" 2>/dev/null || echo unknown)"
-		echo "  pid  $holder  ($cmd)" >&2
-		echo "  cwd  $cwd" >&2
-		# The PID-file check above has already passed, so whatever this
-		# is, `make dev-stop` does not know about it — saying otherwise
-		# sends you to a command that will report success and change
-		# nothing.  Never `pkill -f` here either: the pattern would
-		# match this script's own command line.
-		echo "  'make dev-stop' will not touch it (it is not in" >&2
-		echo "  ${PID_FILE#"$REPO_ROOT"/}): kill $holder, or pass --port." >&2
-	else
-		echo "  The holder could not be identified (no ss, or it belongs" >&2
-		echo "  to another user). Try: ss -lptn 'sport = :$PORT'" >&2
-	fi
-	exit 1
-fi
-
 # ── Choose the YJ_HOME ───────────────────────────────────────────────
 # A seed is a YJ_HOME that a previous run of the app produced, tarred
 # up (see scripts/seed-sandbox.sh).  Restoring it means starting *in*
@@ -249,20 +200,6 @@ until curl -sf -o /dev/null "http://localhost:$PORT/"; do
 	sleep 0.25
 done
 
-# The loop above exits on the first answer from the port, and "something
-# answered" is not "the app we started answered".  The pre-launch guard
-# makes that unlikely rather than impossible — a race, or a listener
-# started in between — and the check is one signal, so it is worth making
-# here too.  An empty log beside a dead pid is the "it exited immediately
-# and nothing said so" case that the original report spent its time on.
-if ! kill -0 "$APP_PID" 2>/dev/null; then
-	echo "dev-headless: :$PORT answered, but the app we started (pid" >&2
-	echo "  $APP_PID) is gone — something else holds the port." >&2
-	tail -n 30 "$LOG_FILE" >&2
-	rm -f "$PID_FILE"
-	exit 1
-fi
-
 cat <<EOF
 dev-headless: up
   url      http://localhost:$PORT

scripts/issue.sh

@@ -38,8 +38,10 @@
 # Where a body is taken and no --body-file is given, it is read from stdin.
 #
 # Environment:
-#   GITEA_TOKEN   a PAT with write:issue (plus write:repository and read:user,
-#                 which the rest of this repo's tooling reaches for)
+#   GITEA_TOKEN   a PAT with write:issue.  `claim` and `mine` additionally
+#                 need to know your username: set GITEA_USER, or give the
+#                 token read:user and it is looked up.
+#   GITEA_USER    your Gitea login.  Optional; see above.
 #   GITEA_URL     defaults to https://git.ljones.me
 #   GITEA_REPO    defaults to yonlu/yellowjacket
 set -euo pipefail
@@ -81,7 +83,29 @@ read_body() {
 	if [ "$file" = "-" ]; then cat; else cat "$file"; fi
 }
 
-me() { curl -sS -H "Authorization: token $GITEA_TOKEN" "$server/api/v1/user" | python3 "$py" login; }
+# The one lookup in this script that needs a scope beyond write:issue.
+# `GET /user` requires read:user, and it is reached for exactly two reasons:
+# to name the assignee in `claim`, and to filter in `mine`.  A token scoped to
+# the work this script does — write:issue — therefore failed at `claim`, which
+# is the one step the workflow requires before the first edit, so the whole
+# documented process was blocked by its own tooling.
+#
+# GITEA_USER short-circuits it, which is what lets a least-privilege token do
+# the job.  The lookup stays as the fallback because it is right when the
+# scope is there and needs no setup at all.
+me() {
+	if [ -n "${GITEA_USER:-}" ]; then
+		printf '%s' "$GITEA_USER"
+		return
+	fi
+	curl -sS -H "Authorization: token $GITEA_TOKEN" "$server/api/v1/user" |
+		python3 "$py" login ||
+		{
+			echo "issue.sh: could not resolve your username. Set GITEA_USER, or" >&2
+			echo "issue.sh: re-issue GITEA_TOKEN with read:user." >&2
+			exit 1
+		}
+}
 
 label_id() { call GET "/labels?limit=100" | python3 "$py" label-id "$1"; }