crewforth 0.0.1 → 3.0.0-rc.1

package/kit/hooks/board.sh

@@ -0,0 +1,962 @@
+#!/usr/bin/env bash
+# Team board engine — a distributed claim lock and shared item memory for a team sharing one repository.
+#
+# WHY THIS EXISTS
+#   Every kit install is local: docs/PLAN.md and docs/SESSION_STATE.md are gitignored, so item #1 being taken
+#   is invisible to everyone else and two people start the same work. This engine puts the item list, the
+#   claims and the per-item handover notes on a git ref that the whole team pushes to.
+#
+# WHY A GIT REF IS THE LOCK (measured, not assumed)
+#   `git push` to a ref is fast-forward-only unless forced. Two clones that build a claim commit on the SAME
+#   base and push it: the first wins, the second is rejected non-fast-forward (exit 1) and must re-read the
+#   board. That is an atomic compare-and-swap with zero infrastructure — no server, no token, no daemon.
+#   Verified against a bare remote: loser exit=1, remote kept the winner's claim.
+#
+# WHY PLUMBING AND NOT A CHECKOUT
+#   Commits are built with hash-object/read-tree/write-tree/commit-tree against a private index file. The
+#   working tree, the index, the current branch and any stash are untouched — you can claim an item in the
+#   middle of a feature branch with dirty files and nothing moves.
+#
+# NO NETWORK ON THE HOT PATH
+#   Only claim/done/drop/sync/probe talk to the remote, because those are the operations whose whole point is
+#   being atomic — reporting "you own it" without a confirmed push would be a lie. Session start and the
+#   commit gate read a local cache / the local ref and never open a socket.
+#
+# PORTABILITY
+#   No jq (Windows Git Bash has none). No `date -d` / `date -j` (GNU and BSD disagree) — timestamps are stored
+#   as BOTH an ISO string for humans and an epoch integer for arithmetic, so nothing ever has to be re-parsed.
+set -uo pipefail
+# The 2.x names of the variables a user can set still work (one helper: eval/lib/crew-env.sh).
+_crew_d="${BASH_SOURCE%/*}"; [ "$_crew_d" = "${BASH_SOURCE}" ] && _crew_d=.
+[ -f "$_crew_d/../eval/lib/crew-env.sh" ] && . "$_crew_d/../eval/lib/crew-env.sh"; unset _crew_d
+
+# ---------------------------------------------------------------- repo primitives
+
+_die(){ printf 'board: %s\n' "$1" >&2; exit "${2:-1}"; }
+
+_git_dir(){ git rev-parse --git-common-dir 2>/dev/null; }
+
+# How a message names a board action. /crew-board is a USER-ONLY skill (disable-model-invocation), so a message that
+# Claude reads must give it the command it can run itself — this script — and name the slash form for the user.
+# The plugin edition's copy lives outside the project, so it names its own absolute path. Only called when a message
+# is printed, never on the hot path.
+_selfcmd(){ local d; d="$(cd "${BASH_SOURCE%/*}" 2>/dev/null && pwd)"
+  if [ -f "$d/../.claude-plugin/plugin.json" ]; then printf 'bash "%s/board.sh"' "$d"; else printf 'bash .claude/hooks/board.sh'; fi; }
+_act(){ printf '%s %s (or the user can type /crew-board %s)' "$(_selfcmd)" "$1" "${2:-$1}"; }
+
+# Ref namespace. Default is a custom namespace so the board never shows up in `git branch` and never enters the
+# code history. Some servers refuse refs outside refs/heads|refs/tags; `probe` detects that and records the
+# fallback here, per clone.
+#
+# The board's settings are read ONCE per run, in one process: `crew.board`, `crew.boardRef`, `crew.boardRemote`,
+# and — for the 3.x line only, removed in 4.0 — their 2.x names under `csk.`. A `crew.` key always wins. Reading
+# them one `git config --get` at a time cost a process per call, and _ref alone is called a dozen times a run.
+_load_cfg(){
+  local line k v
+  _C_BOARD=""; _C_REF=""; _C_REMOTE=""; _L_BOARD=""; _L_REF=""; _L_REMOTE=""
+  while IFS= read -r line; do
+    k="${line%% *}"; v="${line#* }"; [ "$k" = "$line" ] && v=""
+    case "$k" in
+      crew.board) _C_BOARD="$v" ;; crew.boardref) _C_REF="$v" ;; crew.boardremote) _C_REMOTE="$v" ;;
+      csk.board) _L_BOARD="$v" ;; csk.boardref) _L_REF="$v" ;; csk.boardremote) _L_REMOTE="$v" ;;
+    esac
+  done <<EOF
+$(git config --get-regexp '^(crew|csk)\.board(ref|remote)?$' 2>/dev/null)
+EOF
+  # The ref, and where its fetched copy lands (see _fetch), resolved here so no caller forks for them.
+  _REF="${_C_REF:-$_L_REF}"
+  case "$_REF" in refs/csk/board|'') _REF='refs/crew/board' ;; refs/heads/csk-board) _REF='refs/heads/crew-board' ;; esac
+  case "$_REF" in refs/heads/*) _RN='refs/crew/remote/branch' ;; *) _RN='refs/crew/remote/board' ;; esac
+}
+_load_cfg
+_ref(){ printf '%s\n' "$_REF"; }
+_remote(){ printf '%s\n' "${_C_REMOTE:-${_L_REMOTE:-origin}}"; }
+
+# ---- network git: never block, never prompt ------------------------------------------------------------
+# Every git call that reaches a REMOTE goes through here, because a remote is where a hook stops being slow
+# and starts being infinite. Three ways that happens, all silent:
+#   * git asks for a username on the terminal. A hook has no terminal, so it waits — forever.
+#   * Git Credential Manager, the DEFAULT helper on Windows, opens a GUI dialog. In a hook nobody is looking
+#     at that window, and it waits forever too. This is the one that hurts: it looks like a frozen commit.
+#   * the remote accepts the connection and then stalls, which no prompt setting covers.
+# GIT_TERMINAL_PROMPT=0 turns the first into an immediate failure, GCM_INTERACTIVE=never disables the second,
+# and `timeout` bounds the third. Where timeout is absent the first two still apply.
+#
+# Bounding these is safe precisely because failure is ALREADY the graceful path: a non-zero _fetch means
+# "remote unreachable — showing the last known state", and a non-zero _commit_push means "kept locally, the
+# team cannot see it yet". So this converts a hang into a sentence the user can act on, and never into data
+# loss. CREW_NET_TIMEOUT overrides the bound for a slow link.
+# `timeout` is coreutils and macOS does not ship it; Homebrew's coreutils installs it as `gtimeout`. Looking for
+# both is not the same as ASSUMING one — an assumed binary would fail silently, a searched one either bounds the
+# call or is honestly absent. When neither exists the prompt suppression above still applies and the call is
+# NOT time-bounded: measured against a black-holed remote, 15s with the bound and 21s without, where the 21s is
+# git giving up on its own. So the unbounded case is slower, not infinite — the infinite case is the credential
+# prompt, and that one is closed on every platform.
+_TMO="$(command -v timeout 2>/dev/null || command -v gtimeout 2>/dev/null || true)"
+_gitnet(){
+  if [ -n "$_TMO" ]; then
+    GIT_TERMINAL_PROMPT=0 GCM_INTERACTIVE=never "$_TMO" "${CREW_NET_TIMEOUT:-15}" git "$@"
+  else
+    GIT_TERMINAL_PROMPT=0 GCM_INTERACTIVE=never git "$@"
+  fi
+}
+
+# Identity. The email is the claim owner; it is already configured in every clone that can commit.
+_me(){
+  local m; m="$(git config --get user.email 2>/dev/null)"
+  [ -n "$m" ] || m="$(git config --get user.name 2>/dev/null)"
+  [ -n "$m" ] || _die "no git identity: set user.email before claiming"
+  printf '%s' "$m"
+}
+
+# ---- the 2.x board, kept in step for the whole 3.x line (removed in 4.0) ---------------------------------
+# A 2.x teammate reads and writes only refs/csk/board (or the csk-board branch) and will never read the crew
+# name. So while that ref exists on the remote, it stays the team's lock: every 3.x write is built on whichever of
+# the two refs is ahead and pushed to BOTH in one `git push --atomic` — both move or neither does, so a claim can
+# never be granted on one ref and refused on the other. A 2.x claim is then refused against a 3.x claim and the
+# other way round, exactly as within one version. When the team deletes the old ref, 3.x stops writing it.
+# Histories that split before this (two boards made independently) are joined by a three-way merge built with
+# read-tree, which every git has — no merge-tree, which needs 2.38. On the one file both sides append to,
+# refusals.log, the lines are united; any other file changed on both sides keeps the 3.x side.
+_rev(){ git rev-parse -q --verify "$1^{commit}" 2>/dev/null; }
+_join(){ # _join <3.x commit> <2.x commit> -> a commit that has both as parents
+  local n="$1" l="$2" base bt idx p b t
+  base="$(git merge-base "$n" "$l" 2>/dev/null)"
+  if [ -n "$base" ]; then bt="$base^{tree}"; else bt="$(git hash-object -w -t tree /dev/null)"; fi
+  idx="$(_git_dir)/crew-index.$$"; rm -f "$idx"
+  GIT_INDEX_FILE="$idx" git read-tree -m -i --aggressive "$bt" "$n^{tree}" "$l^{tree}" 2>/dev/null || { rm -f "$idx"; return 1; }
+  while IFS= read -r p; do
+    [ -n "$p" ] || continue
+    if [ "$p" = refusals.log ]; then
+      b="$( { git cat-file -p "$n:$p" 2>/dev/null; git cat-file -p "$l:$p" 2>/dev/null; } | awk '!seen[$0]++' | _blob)"
+    else
+      b="$(git rev-parse -q --verify "$n:$p" 2>/dev/null || git rev-parse -q --verify "$l:$p" 2>/dev/null)"
+    fi
+    GIT_INDEX_FILE="$idx" git update-index --force-remove "$p" 2>/dev/null
+    [ -n "$b" ] && GIT_INDEX_FILE="$idx" git update-index --add --cacheinfo "100644,$b,$p" 2>/dev/null
+  done <<EOF
+$(GIT_INDEX_FILE="$idx" git ls-files -u 2>/dev/null | cut -f2 | sort -u)
+EOF
+  t="$(GIT_INDEX_FILE="$idx" git write-tree 2>/dev/null)"; rm -f "$idx"
+  [ -n "$t" ] || return 1
+  git commit-tree "$t" -p "$n" -p "$l" -m 'board: join the 2.x and 3.x boards'
+}
+# The 2.x ref this clone last saw on the remote, as "<local copy> <remote name>"; empty when there is none.
+# The copy that matches this clone's mode wins; otherwise the other form (a 2.x team on the other mode).
+_legacy(){
+  local found; found="$(git for-each-ref --format='%(refname)' refs/crew/legacy/ns/board refs/crew/legacy/branch 2>/dev/null)"
+  case "$_REF" in
+    refs/heads/*) case "$found" in *refs/crew/legacy/branch*) echo 'refs/crew/legacy/branch refs/heads/csk-board' ;; *refs/crew/legacy/ns/board*) echo 'refs/crew/legacy/ns/board refs/csk/board' ;; esac ;;
+    *)            case "$found" in *refs/crew/legacy/ns/board*) echo 'refs/crew/legacy/ns/board refs/csk/board' ;; *refs/crew/legacy/branch*) echo 'refs/crew/legacy/branch refs/heads/csk-board' ;; esac ;;
+  esac
+}
+
+# One for-each-ref answers both "is there a board" and "is there a 2.x one here to start from" — the commit gate
+# runs this on every commit, so a second process here would be paid by every repo, board or not. A local 2.x
+# board (one that was never pushed, or a clone updated without the updater) becomes the crew ref.
+_have_board(){
+  local found l; found="$(git for-each-ref --format='%(refname)' "$_REF" refs/csk/board refs/heads/csk-board 2>/dev/null)"
+  [ -n "$found" ] || return 1
+  case "$found" in *"$_REF"*) return 0 ;; esac
+  for l in refs/csk/board refs/heads/csk-board; do
+    case "$found" in *"$l"*) git update-ref "$_REF" "$(_rev "$l")" 2>/dev/null && return 0 ;; esac
+  done
+  return 1
+}
+
+# The board is OFF until somebody creates one — a repo with no board ref has no gates at all, which is what
+# every solo project and every pre-existing install stays. This is the separate question of switching it off
+# in a repo that HAS one: someone working alone on a shared repo for an afternoon, or a team pausing it.
+#   git config crew.board off            this clone
+#   git config --global crew.board off   every repo you touch
+#   CREW_NO_BOARD=1                      this session only
+# Honoured by every entry point, including the commit gate — a switch that turns off two of three gates is a
+# trap, not a switch.
+_enabled(){
+  [ -n "${CREW_NO_BOARD:-}" ] && return 1
+  case "${_C_BOARD:-$_L_BOARD}" in off|false|0|no) return 1 ;; esac
+  return 0
+}
+
+# Fetch the board. The remote is authoritative: local board state is never worth keeping over it — every mutation
+# re-derives itself from the fetched state (see _mutate). ONE fetch, whatever the team runs: the crew ref in both
+# modes and the 2.x ref in both modes, all as globs (a glob never fails for want of a match) into this clone's own
+# refs/crew/remote/* and refs/crew/legacy/* — never into refs/heads, where a glob would overwrite a user's branch
+# that merely starts with the same name. --prune drops a copy whose remote ref is gone, which is how 3.x learns the
+# team deleted the 2.x ref. Returns 0 board here · 1 remote unreachable · 4 reachable, no board anywhere.
+_fetch(){
+  _gitnet fetch -q --prune "$(_remote)" '+refs/crew/board*:refs/crew/remote/board*' '+refs/heads/crew-board*:refs/crew/remote/branch*' \
+    '+refs/csk/*:refs/crew/legacy/ns/*' '+refs/heads/csk-board*:refs/crew/legacy/branch*' >/dev/null 2>&1 || return 1
+  local rn lg lc b
+  # Only the teammate who ran `init` runs `probe`, so only that clone learns the team fell back to the orphan
+  # branch. Everyone else resolves it here from what the remote has, and records the answer once.
+  if [ -z "${_C_REF:-$_L_REF}" ] && [ -z "$(_rev refs/crew/remote/board)" ]; then
+    if [ -n "$(_rev refs/crew/remote/branch)" ] || { [ -z "$(_rev refs/crew/legacy/ns/board)" ] && [ -n "$(_rev refs/crew/legacy/branch)" ]; }; then
+      git config crew.boardRef 'refs/heads/crew-board'; _load_cfg
+    fi
+  fi
+  rn="$(_rev "$_RN")"; [ -n "$rn" ] || rn="$(_rev "$_REF")"     # nothing on the remote yet: a local board stands
+  lg="$(_legacy)"; lc="$(_rev "${lg%% *}")"
+  if [ -z "$lc" ]; then b="$rn"
+  elif [ -z "$rn" ] || git merge-base --is-ancestor "$rn" "$lc" 2>/dev/null; then b="$lc"
+  elif git merge-base --is-ancestor "$lc" "$rn" 2>/dev/null; then b="$rn"
+  else b="$(_join "$rn" "$lc")" || { b="$rn"; _JOIN_ERR=1
+    printf 'the 2.x board could not be joined in — its entries are not shown; run %s again\n' "$(_act sync)" > "$(_git_dir)/crew-board-lasterror"; }
+  fi
+  [ -n "$b" ] || return 4
+  git update-ref "$_REF" "$b"
+}
+_cat(){ git cat-file -p "$(_ref):$1" 2>/dev/null; }
+_item_paths(){ git ls-tree --name-only "$(_ref)" items/ 2>/dev/null; }
+
+_now_iso(){ date -u +%Y-%m-%dT%H:%M:%SZ; }
+_now_epoch(){ date -u +%s; }
+
+_age(){ # _age <epoch> -> "3h" / "12m" / "2d" / "-"   (how long a claim has been held)
+  local e="${1:-0}" now d
+  case "$e" in ''|*[!0-9]*) printf '%s' '-'; return 0 ;; esac
+  [ "$e" -gt 0 ] || { printf '%s' '-'; return 0; }
+  now="$(_now_epoch)"; d=$(( now - e )); [ "$d" -lt 0 ] && d=0
+  if   [ "$d" -lt 3600 ];  then printf '%dm' $(( d / 60 ))
+  elif [ "$d" -lt 172800 ];then printf '%dh' $(( d / 3600 ))
+  else                          printf '%dd' $(( d / 86400 )); fi
+}
+
+# ---------------------------------------------------------------- item format
+#
+#   id: 001
+#   title: Login API endpoint
+#   status: todo | in_progress | blocked | done
+#   deps: 001,002          (or "-")
+#   external: PROJ-142     (or "-")  — link only; the board never depends on a tracker
+#   owner: ali@example.com (or "-")
+#   since: <iso>           (or "-")
+#   since_epoch: <int>     (or 0)
+#   beat_epoch: <int>      (or 0)
+#   --
+#   ## Handover
+#   <free text: exactly where it was left, and why>
+#   ## Completion
+#   <free text: what shipped, commit/PR>
+
+_field(){ # _field <content> <key>
+  printf '%s\n' "$1" | sed -n '1,/^--$/p' | grep -m1 "^$2: " | cut -d' ' -f2-
+}
+_body(){ printf '%s\n' "$1" | sed -n '/^--$/,$p' | sed '1d'; }
+
+_section(){ # _section <content> <SectionName> -> text under "## Name" up to the next "## "
+  _body "$1" | awk -v s="## $2" 'BEGIN{p=0} $0==s{p=1;next} /^## /{p=0} p{print}'
+}
+
+_path_for(){ # _path_for <id> -> items/<id>-<slug>.md  (resolved from the tree; ids are unique)
+  _item_paths | grep -m1 "^items/$1-" || _item_paths | grep -m1 "^items/$1\.md$"
+}
+
+_load(){ # _load <id> -> item content on stdout, 1 if absent
+  local p; p="$(_path_for "$1")"; [ -n "$p" ] || return 1; _cat "$p"
+}
+
+_render_item(){ # _render_item <id> <title> <status> <deps> <external> <owner> <since> <since_epoch> <beat> <handover> <completion>
+  printf 'id: %s\ntitle: %s\nstatus: %s\ndeps: %s\nexternal: %s\nowner: %s\nsince: %s\nsince_epoch: %s\nbeat_epoch: %s\n--\n## Handover\n%s\n## Completion\n%s\n' \
+    "$1" "$2" "$3" "$4" "$5" "$6" "$7" "$8" "$9" "${10}" "${11}"
+}
+
+# ---------------------------------------------------------------- config (team-wide, stored IN the ref)
+
+_conf(){ # _conf <key> <default>
+  local v; v="$(_cat config 2>/dev/null | grep -m1 "^$1: " | cut -d' ' -f2-)"
+  [ -n "$v" ] && printf '%s' "$v" || printf '%s' "$2"
+}
+
+# ---------------------------------------------------------------- tree building (never touches the worktree)
+
+_blob(){ git hash-object -w --stdin; }
+
+_tree_with(){ # _tree_with <path> <blob>  [<path2> <blob2> ...] -> tree sha, based on the current board tree
+  local idx; idx="$(_git_dir)/crew-index.$$"
+  rm -f "$idx"
+  local rc=0
+  if _have_board; then
+    GIT_INDEX_FILE="$idx" git read-tree "$(_ref)^{tree}" 2>/dev/null || rc=1
+  fi
+  while [ $# -ge 2 ]; do
+    GIT_INDEX_FILE="$idx" git update-index --add --cacheinfo "100644,$2,$1" 2>/dev/null || rc=1
+    shift 2
+  done
+  local t; t="$(GIT_INDEX_FILE="$idx" git write-tree 2>/dev/null)" || rc=1
+  rm -f "$idx"
+  [ "$rc" = 0 ] || return 1
+  printf '%s' "$t"
+}
+
+_commit_push(){ # _commit_push <tree> <message> -> 0 pushed · 2 rejected (retry) · 3 unshared (offline/denied)
+  local tree="$1" msg="$2" sha lg err rc
+  if _have_board; then sha="$(git commit-tree "$tree" -p "$(_ref)" -m "$msg")"
+  else                 sha="$(git commit-tree "$tree" -m "$msg")"; fi
+  [ -n "$sha" ] || return 1
+  lg="$(_legacy)"
+  if [ -n "$lg" ]; then
+    # Both refs in one atomic push: the 2.x ref is still the team's lock (see _join's header).
+    err="$(LC_ALL=C _gitnet push --atomic --quiet "$(_remote)" "$sha:$(_ref)" "$sha:${lg#* }" 2>&1)"; rc=$?
+    case "$err" in *atomic*support*|*support*atomic*)
+      # A server without atomic push: the 2.x ref first, since it is the lock; the crew ref follows it and a
+      # failure there heals on the next write, which is built on whichever ref is ahead.
+      err="$(LC_ALL=C _gitnet push --quiet "$(_remote)" "$sha:${lg#* }" 2>&1)"; rc=$?
+      [ $rc -eq 0 ] && _gitnet push --quiet "$(_remote)" "$sha:$(_ref)" >/dev/null 2>&1 ;;
+    esac
+    [ $rc -eq 0 ] && git update-ref "${lg%% *}" "$sha"
+  else
+    err="$(LC_ALL=C _gitnet push --quiet "$(_remote)" "$sha:$(_ref)" 2>&1)"; rc=$?
+  fi
+  if [ $rc -eq 0 ]; then
+    git update-ref "$(_ref)" "$sha"
+    return 0
+  fi
+  # Non-fast-forward means somebody else claimed in between: that is the lock working, retry on fresh state.
+  case "$err" in
+    *non-fast-forward*|*fetch\ first*|*rejected*) return 2 ;;
+  esac
+  # Anything else (offline, no push rights, server refuses the namespace) is not a race. Keep the change
+  # locally so work is not lost, and say plainly that the team cannot see it.
+  git update-ref "$(_ref)" "$sha"
+  printf '%s\n' "$err" > "$(_git_dir)/crew-board-lasterror"
+  return 3
+}
+
+# ---------------------------------------------------------------- mutation with CAS retry
+#
+# The loop re-reads the board from the remote on every attempt and re-checks the precondition there, so a
+# claim can never be granted against a stale view. Three attempts is not a timeout: each rejection means a
+# real competing push landed, and re-evaluating usually turns the second attempt into a clean refusal
+# ("someone else owns it") rather than a retry.
+
+_mutate(){ # _mutate <action> <id> [note]
+  local action="$1" id="$2" note="${3:-}" attempt=1 rc
+  while [ "$attempt" -le 3 ]; do
+    _fetch || true                       # offline: fall through on the local ref, _commit_push reports unshared
+    _apply_once "$action" "$id" "$note"; rc=$?
+    case $rc in
+      0) return 0 ;;
+      1) return 1 ;;                     # precondition refused — not a race, do not retry
+      3) return 3 ;;                     # unshared
+      2) attempt=$((attempt+1)) ;;       # lost the race — re-read and re-decide
+    esac
+  done
+  printf 'board: the board changed under three consecutive attempts; run %s and retry\n' "$(_act status)" >&2
+  return 1
+}
+
+_apply_once(){ # -> 0 ok · 1 refused · 2 race · 3 unshared
+  local action="$1" id="$2" note="${3:-}" me c path
+  me="$(_me)"
+  c="$(_load "$id")" || { printf 'board: no item #%s (list them: %s)\n' "$id" "$(_act status)" >&2; return 1; }
+  path="$(_path_for "$id")"
+
+  local title status deps external owner since since_ep beat hand comp
+  title="$(_field "$c" title)"; status="$(_field "$c" status)"; deps="$(_field "$c" deps)"
+  external="$(_field "$c" external)"; owner="$(_field "$c" owner)"
+  since="$(_field "$c" since)"; since_ep="$(_field "$c" since_epoch)"; beat="$(_field "$c" beat_epoch)"
+  hand="$(_section "$c" Handover)"; comp="$(_section "$c" Completion)"
+
+  case "$action" in
+    claim)
+      if [ "$status" = done ]; then printf 'board: #%s is already done\n' "$id" >&2; return 1; fi
+      if [ -n "$owner" ] && [ "$owner" != "-" ] && [ "$owner" != "$me" ]; then
+        printf 'board: #%s belongs to %s since %s. Free: %s\n' "$id" "$owner" "$since" "$(_free_ids)" >&2
+        _log_refusal "$id" held "$owner"
+        return 1
+      fi
+      local blocked; blocked="$(_unmet_deps "$deps")"
+      if [ -n "$blocked" ]; then
+        printf 'board: #%s is blocked by #%s (not done). Free: %s\n' "$id" "$blocked" "$(_free_ids)" >&2
+        _log_refusal "$id" blocked "#$blocked"
+        return 1
+      fi
+      if [ "$owner" = "$me" ] && [ "$status" = in_progress ]; then
+        # Re-claiming what you already hold must NOT restart the clock. It used to rewrite `since`, so an item
+        # held since morning read as freshly started — which breaks the two things that age is for: telling a
+        # teammate how long it has been held, and letting a claim go stale when its owner has walked away.
+        # Only the heartbeat moves: re-claiming is evidence you are still on it, not that you just began.
+        beat="$(_now_epoch)"
+      else
+        status=in_progress; owner="$me"; since="$(_now_iso)"; since_ep="$(_now_epoch)"; beat="$since_ep"
+      fi
+      ;;
+    done)
+      if [ "$owner" != "$me" ]; then printf 'board: #%s is not yours (%s)\n' "$id" "${owner:--}" >&2; return 1; fi
+      status=done; owner='-'; beat="$(_now_epoch)"
+      [ -n "$note" ] && comp="$note"
+      ;;
+    drop)
+      if [ "$owner" != "$me" ]; then printf 'board: #%s is not yours (%s)\n' "$id" "${owner:--}" >&2; return 1; fi
+      # A drop without a handover note is the exact failure this board exists to prevent: the next person
+      # inherits the item with none of the context that made it hard.
+      [ -n "$note" ] || { printf 'board: drop needs a handover note (where it stands, and why)\n' >&2; return 1; }
+      status=todo; owner='-'; since='-'; since_ep=0; beat="$(_now_epoch)"; hand="$note"
+      ;;
+    beat)
+      [ "$owner" = "$me" ] || return 1
+      beat="$(_now_epoch)"
+      ;;
+    note)
+      if [ "$owner" != "$me" ]; then printf 'board: #%s is not yours (%s)\n' "$id" "${owner:--}" >&2; return 1; fi
+      hand="$note"; beat="$(_now_epoch)"
+      ;;
+    *) _die "unknown action '$action'" ;;
+  esac
+
+  local blob tree
+  blob="$(_render_item "$id" "$title" "$status" "$deps" "$external" "$owner" "$since" "$since_ep" "$beat" "$hand" "$comp" | _blob)"
+  tree="$(_tree_with "$path" "$blob")" || return 1
+  _commit_push "$tree" "board: $action #$id by $me"
+}
+
+_unmet_deps(){ # -> comma list of dependency ids that are not done
+  local deps="$1" out="" d dc
+  [ -n "$deps" ] && [ "$deps" != "-" ] || return 0
+  for d in $(printf '%s' "$deps" | tr ',' ' '); do
+    dc="$(_load "$d")" || continue
+    [ "$(_field "$dc" status)" = done ] || out="${out:+$out,}$d"
+  done
+  printf '%s' "$out"
+}
+
+_free_ids(){ # claimable right now: unowned, not done, no unmet dependency
+  local p c out="" id
+  for p in $(_item_paths); do
+    c="$(_cat "$p")"; id="$(_field "$c" id)"
+    [ "$(_field "$c" status)" = done ] && continue
+    local o; o="$(_field "$c" owner)"; [ -n "$o" ] && [ "$o" != "-" ] && continue
+    [ -n "$(_unmet_deps "$(_field "$c" deps)")" ] && continue
+    out="${out:+$out }#$id"
+  done
+  printf '%s' "${out:-none}"
+}
+
+# ---------------------------------------------------------------- commands
+
+cmd_add(){ # add <id> <title> [deps] [external]
+  local id="$1" title="$2" deps="${3:--}" ext="${4:--}" attempt=1 rc
+  case "$id" in ''|*[!0-9]*) _die "id must be numeric (e.g. 003)";; esac
+  local slug; slug="$(printf '%s' "$title" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-//;s/-$//' | cut -c1-40)"
+  while [ "$attempt" -le 3 ]; do
+    _fetch || true
+    if _load "$id" >/dev/null 2>&1; then _die "#$id already exists"; fi
+    local blob tree
+    blob="$(_render_item "$id" "$title" "$([ "$deps" != "-" ] && echo blocked || echo todo)" "$deps" "$ext" '-' '-' 0 0 '' '' | _blob)"
+    tree="$(_tree_with "items/$id-$slug.md" "$blob")" || _die "could not build the board tree"
+    _commit_push "$tree" "board: add #$id"; rc=$?
+    case $rc in 0) printf '+ #%s %s\n' "$id" "$title"; return 0;; 3) printf '+ #%s %s  [UNSHARED — remote unreachable]\n' "$id" "$title"; return 0;; esac
+    attempt=$((attempt+1))
+  done
+  _die "the board kept changing; retry"
+}
+
+_related(){ # _related <id> — the work this item is connected to, in the words of the people who did it.
+  # Storing a handover note is not the same as delivering it. Whoever picks up #3 has no reason to go and read
+  # #1, so the moment they take #3 is when what #1 actually delivered has to arrive on its own.
+  local id="$1" c deps d dc out="" body who
+  c="$(_load "$id")" || return 0
+  deps="$(_field "$c" deps)"
+  if [ -n "$deps" ] && [ "$deps" != "-" ]; then
+    for d in $(printf '%s' "$deps" | tr ',' ' '); do
+      dc="$(_load "$d")" || continue
+      body="$(_section "$dc" Completion | head -6)"; [ -n "$body" ] || body="$(_section "$dc" Handover | head -6)"
+      who="$(_field "$dc" owner)"; [ "$who" = "-" ] && who="$(_field "$dc" status)"
+      out="$out
+  #$d \"$(_field "$dc" title)\" [$(_field "$dc" status)] — depends-on
+${body:+$(printf '%s' "$body" | sed 's/^/      /')}"
+    done
+  fi
+  # Who is waiting on YOU: work that will be affected by what you are about to do, so it can be told.
+  local p pc pd
+  for p in $(_item_paths); do
+    pc="$(_cat "$p")"; pd="$(_field "$pc" deps)"
+    case ",$pd," in *",$id,"*)
+      out="$out
+  #$(_field "$pc" id) \"$(_field "$pc" title)\" [$(_field "$pc" status)$([ "$(_field "$pc" owner)" != "-" ] && printf ', %s' "$(_field "$pc" owner)")] — waits on this one" ;;
+    esac
+  done
+  # What everyone ELSE is mid-flight on, with whatever they last said about it. The dependency graph only knows
+  # the edges somebody declared; two items can collide without one. "What is Ali doing right now" is a question
+  # people ask out loud, so it is answered here without being asked, at the one moment it changes what you do.
+  local me ow st note
+  me="$(_me)"
+  for p in $(_item_paths); do
+    pc="$(_cat "$p")"; ow="$(_field "$pc" owner)"; st="$(_field "$pc" status)"
+    [ "$st" = in_progress ] && [ -n "$ow" ] && [ "$ow" != "-" ] && [ "$ow" != "$me" ] || continue
+    [ "$(_field "$pc" id)" = "$id" ] && continue
+    note="$(_section "$pc" Handover | head -2)"
+    out="$out
+  #$(_field "$pc" id) \"$(_field "$pc" title)\" — $ow is on this now ($(_age "$(_field "$pc" since_epoch)"))${note:+
+$(printf '%s' "$note" | sed 's/^/      /')}"
+  done
+
+  # Decisions this user has not read. Announcing them only at session start meant an item claimed later in the
+  # same session could be started against a constraint the team had already settled — which is the failure the
+  # decision was recorded to prevent. Starting work is the last honest moment to say it.
+  local dtotal dseen dnew
+  dtotal="$(_decision_paths | wc -l | tr -d ' ')"; dseen="$(_seen_count)"
+  dnew=$(( dtotal - dseen )); [ "$dnew" -lt 0 ] && dnew=0
+  if [ "$dnew" -gt 0 ]; then
+    for p in $(_decision_paths | tail -"$dnew"); do
+      c="$(_cat "$p")"
+      out="$out
+  DECISION $(_field "$c" id) \"$(_field "$c" title)\" — $(_field "$c" author), unread by you
+$(_body "$c" | head -4 | sed 's/^/      /')"
+    done
+  fi
+
+  [ -n "$out" ] && printf 'Connected work — read this before you start, and update it when you finish:%s\n' "$out"
+  return 0
+}
+
+# A refusal is the only proof the lock ever did anything, and it was the one event leaving no trace: the message
+# went to stderr and nowhere else. Nothing on the board, nothing in the history — so "how often did this actually
+# stop a collision?" was unanswerable, and would still be unanswerable after a trial, because the data would
+# never have existed. Measurement has to be installed BEFORE the thing it measures.
+#
+# Appended to the board so the count is the TEAM's, not one clone's. Refusals are rare by construction — they
+# happen only on real contention — so a push per refusal costs little, and it rides the same CAS retry as every
+# other write. Failure here is swallowed: a refusal that cannot be logged is still a refusal, and turning it
+# into an error would punish the user for the bookkeeping.
+_log_refusal(){ # _log_refusal <id> <reason> <holder>
+  _enabled || return 0
+  _have_board || return 0
+  local id="$1" reason="$2" holder="$3" attempt=1 prev line blob tree
+  line="$(_now_iso)|$id|$reason|$(_me)|${holder:--}"
+  while [ "$attempt" -le 3 ]; do
+    prev="$(_cat refusals.log 2>/dev/null)"
+    blob="$(printf '%s%s\n' "${prev:+$prev$NLR}" "$line" | _blob)"
+    tree="$(_tree_with refusals.log "$blob")" || return 0
+    _commit_push "$tree" "board: refusal #$id ($reason)" && return 0
+    _fetch >/dev/null 2>&1 || return 0
+    attempt=$((attempt+1))
+  done
+  return 0
+}
+NLR='
+'
+
+cmd_claim(){
+  _mutate claim "$1"; local rc=$?
+  case $rc in
+    0) printf '#%s is yours (%s)\n' "$1" "$(_me)"; _related "$1" ;;
+    3) # "Unshared" has two very different causes and one alarming message served both. A repo with no remote
+       # is a deliberate local board, not a failure, and telling that user their team cannot see it is noise
+       # about a team that does not exist.
+       if git remote get-url "$(_remote)" >/dev/null 2>&1; then
+         printf '#%s claimed LOCALLY ONLY — the remote is unreachable, your team cannot see it.\n   Run %s before you rely on it.\n' "$1" "$(_act sync)"
+       else
+         printf '#%s is yours (%s) — local board, no remote configured.\n' "$1" "$(_me)"
+         _related "$1"
+       fi ;;
+    *) return $rc ;;
+  esac
+  cmd_cache >/dev/null
+}
+
+cmd_done(){ _mutate done "$1" "${2:-}" || return $?; printf '#%s done. Now claimable: %s\n' "$1" "$(_free_ids)"; cmd_cache >/dev/null; }
+cmd_drop(){ _mutate drop "$1" "${2:-}" || return $?; printf '#%s released with a handover note.\n' "$1"; cmd_cache >/dev/null; }
+cmd_note(){ _mutate note "$1" "${2:-}" || return $?; printf '#%s handover note updated.\n' "$1"; }
+
+cmd_status(){
+  # This view fetches before it prints, and that is a deliberate reversal. It used to fetch only when there was
+  # no board at all, to keep the network off the foreground — and the result was a board that lied: caught in a
+  # real session, it showed an item as blocked while its dependency had already landed, and only the claim that
+  # followed corrected it. The "no network in the foreground" rule is about hooks that run on EVERY turn, not
+  # about a view a person asked for by name. A stale answer to "who has what" is worse than a slow one, because
+  # the next thing the reader does is decide what to work on.
+  #
+  # Fails open: an unreachable remote falls through to whatever is local, so the view still appears offline.
+  _fetch >/dev/null 2>&1 || true
+  _have_board || { echo "No board in this repo yet (and none on '$(_remote)'). Create one: $(_act init)"; return 0; }
+  local me p c id st ow ti dep bl now stale_h
+  me="$(_me)"; now="$(_now_epoch)"; stale_h="$(_conf stale_hours 8)"
+  # HELD is not decoration: "who holds it" without "for how long" is the question a teammate actually asks, and
+  # without it the only age signal was the STALE marker — i.e. nothing at all until 8 hours had passed.
+  echo "ITEM  STATUS         OWNER                 HELD  TITLE"
+  for p in $(_item_paths); do
+    c="$(_cat "$p")"; id="$(_field "$c" id)"; st="$(_field "$c" status)"; ow="$(_field "$c" owner)"; ti="$(_field "$c" title)"
+    # Blockedness is DERIVED from the dependency graph, never read from the stored field: an item added with a
+    # dependency is stored as `blocked` and nothing rewrites that field when the dependency lands, so trusting
+    # it printed "blocked" for items the same view was simultaneously listing as claimable.
+    dep="$(_unmet_deps "$(_field "$c" deps)")"
+    if [ "$st" != done ]; then
+      if [ -n "$dep" ];              then st="blocked(#$dep)"
+      elif [ -n "$ow" ] && [ "$ow" != "-" ]; then st="in_progress"
+      else                                st="todo"; fi
+    fi
+    bl=""
+    if [ "$ow" = "$me" ]; then bl=" <- you"; fi
+    if [ -n "$ow" ] && [ "$ow" != "-" ]; then
+      local b; b="$(_field "$c" beat_epoch)"; case "$b" in ''|*[!0-9]*) b=0;; esac
+      [ "$b" -gt 0 ] && [ $(( (now - b) / 3600 )) -ge "$stale_h" ] && bl="$bl [STALE $(( (now-b)/3600 ))h]"
+    fi
+    local age='-'
+    { [ -n "$ow" ] && [ "$ow" != "-" ]; } && age="$(_age "$(_field "$c" since_epoch)")"
+    printf '#%-4s %-14s %-21s %-5s %s%s\n' "$id" "$st" "${ow:--}" "$age" "$ti" "$bl"
+  done
+  echo
+  echo "Claimable now: $(_free_ids)"
+  [ -f "$(_git_dir)/crew-board-lasterror" ] && echo "Last sync error: $(cat "$(_git_dir)/crew-board-lasterror")"
+  return 0
+}
+
+cmd_show(){ # show <id> — the shared memory for one item
+  local c; c="$(_load "$1")" || _die "no item #$1"
+  printf '%s\n' "$c"
+}
+
+# ---------------------------------------------------------------- cache (what the session-start hook reads)
+
+cmd_cache(){ # rebuild the local cache; NEVER called on the foreground path with the network
+  # Switched off -> leave nothing behind for the other two gates to read. The write guard tests for the flag
+  # file and the session hook prints the cache file; removing both is what makes "off" cost exactly zero
+  # instead of merely suppressing the output of work still being done.
+  # The timestamp is written on EVERY path, including the two that produce no cache. It is what the session-start
+  # hook throttles on, and without it a repo that has no board (every solo project, and every install that
+  # upgraded into this feature) re-spawned a background fetch at every single session opening — looking, forever,
+  # for a ref nobody is ever going to create.
+  if ! _enabled; then rm -f "$(_git_dir)/crew-board-guard" "$(_git_dir)/crew-board-cache"; _now_epoch > "$(_git_dir)/crew-board-cache.at" 2>/dev/null; return 0; fi
+  _have_board || { _now_epoch > "$(_git_dir)/crew-board-cache.at" 2>/dev/null; return 0; }
+  local out me p c id st ow ti now stale_h b
+  me="$(_me)"; now="$(_now_epoch)"; stale_h="$(_conf stale_hours 8)"
+  local mine="" others="" free="" stale=""
+  for p in $(_item_paths); do
+    c="$(_cat "$p")"; id="$(_field "$c" id)"; st="$(_field "$c" status)"; ow="$(_field "$c" owner)"; ti="$(_field "$c" title)"
+    [ "$st" = done ] && continue
+    if [ "$ow" = "$me" ]; then mine="${mine:+$mine; }#$id $ti"
+    elif [ -n "$ow" ] && [ "$ow" != "-" ]; then
+      others="${others:+$others; }#$id $ow ($(_age "$(_field "$c" since_epoch)"))"
+      b="$(_field "$c" beat_epoch)"; case "$b" in ''|*[!0-9]*) b=0;; esac
+      [ "$b" -gt 0 ] && [ $(( (now - b) / 3600 )) -ge "$stale_h" ] && stale="${stale:+$stale, }#$id ($ow, $(( (now-b)/3600 ))h)"
+    fi
+  done
+  free="$(_free_ids)"
+  out="Team board — held by others: ${others:-none} · yours: ${mine:-none} · claimable: ${free}"
+
+  # Decisions the user has not looked at yet. A decision nobody reads is the same as one nobody wrote, and
+  # session start is the only moment it can arrive before the work it would have changed.
+  local dtotal dseen dnew p c
+  dtotal="$(_decision_paths | wc -l | tr -d ' ')"; dseen="$(_seen_count)"
+  dnew=$(( dtotal - dseen )); [ "$dnew" -lt 0 ] && dnew=0
+  if [ "$dnew" -gt 0 ]; then
+    out="$out
+$dnew team decision(s) recorded since you last looked — read them before planning: $(_act decisions)"
+    for p in $(_decision_paths | tail -"$dnew"); do
+      c="$(_cat "$p")"
+      out="$out
+  · $(_field "$c" id) $(_field "$c" title) — $(_field "$c" author)"
+    done
+  fi
+
+  # An open claim you have stopped feeding. Not a block — the damage from a forgotten claim is that the team
+  # reads the item as actively held, so it has to be said out loud rather than enforced.
+  local om ob
+  for p in $(_item_paths); do
+    c="$(_cat "$p")"; [ "$(_field "$c" owner)" = "$me" ] || continue
+    [ "$(_field "$c" status)" = in_progress ] || continue
+    ob="$(_field "$c" since_epoch)"; case "$ob" in ''|*[!0-9]*) ob=0;; esac
+    [ "$ob" -gt 0 ] && [ $(( (now - ob) / 3600 )) -ge 8 ] || continue
+    om="$(_section "$c" Handover)"
+    [ -n "$om" ] && continue
+    out="$out
+You have held #$(_field "$c" id) for $(_age "$ob") with an empty handover note. If you are still on it, say where it stands: $(_act "note $(_field "$c" id) \"<where it stands>\"" "note $(_field "$c" id)"); if not, release it: $(_act "drop $(_field "$c" id) \"<handover>\"" "drop $(_field "$c" id)")."
+  done
+  [ -n "$stale" ] && out="$out
+Stale claims (no activity for ${stale_h}h+): $stale — ask the owner before taking one over; never steal silently."
+  out="$out
+Claim before you start: $(_act "claim <id>"). Commits are gated on a live claim."
+  printf '%s\n' "$out" > "$(_git_dir)/crew-board-cache"
+  _now_epoch > "$(_git_dir)/crew-board-cache.at"
+
+  # One-bit flag for the PreToolUse write guard. The guard runs before EVERY file edit, so it must not shell out
+  # to this script — on Windows a process costs 62-135 ms and a hot-path fork loop is a freeze. It tests for this
+  # file and nothing else: present means "a board exists, it requires a claim, and this user holds none", which
+  # is the only state that blocks. Recomputed here, i.e. at session start and after every board command.
+  if [ -z "$mine" ] && [ "$(_conf require_item all)" = all ]; then
+    : > "$(_git_dir)/crew-board-guard"
+  else
+    rm -f "$(_git_dir)/crew-board-guard"
+  fi
+  printf '%s\n' "$out"
+}
+
+cmd_sync(){
+  _JOIN_ERR=""
+  if _fetch; then [ -n "$_JOIN_ERR" ] || rm -f "$(_git_dir)/crew-board-lasterror"
+  else echo "board: remote unreachable — showing the last known state"; fi
+  cmd_cache; }
+
+# ---------------------------------------------------------------- decisions
+#
+# The board carried per-item memory and nothing else, so a decision that shaped the whole project — "refresh
+# tokens travel in a header, mobile drops cookies" — reached the person who made it and nobody else. The `adr`
+# skill wrote to docs/adr/, and installs gitignore docs/, so those records never left the machine that made
+# them. That is the exact failure this board exists to close, one level up from an item.
+#
+# They live on the same ref as the items, so they travel with the board — including when the board is a
+# separate repository. A decision is append-only: superseding one writes a new record that names it.
+
+_decision_paths(){ git ls-tree --name-only "$(_ref)" decisions/ 2>/dev/null; }
+
+_next_decision_id(){
+  local last; last="$(_decision_paths | sed -n 's#decisions/\([0-9][0-9]*\)-.*#\1#p' | sort -n | tail -1)"
+  printf '%04d' $(( 10#${last:-0} + 1 ))
+}
+
+cmd_decide(){ # decide <title> [body] [items]
+  local title="${1:-}" body="${2:-}" items="${3:--}" attempt=1 rc
+  [ -n "$title" ] || _die 'decide needs a title: board.sh decide "<what was decided>" "<why + what it means for other work>"'
+  _enabled || _die "the board is off in this repo ($(_act on))"
+  while [ "$attempt" -le 3 ]; do
+    _fetch || true
+    _have_board || _die "no board here yet ($(_act init))"
+    local id slug blob tree
+    id="$(_next_decision_id)"
+    slug="$(printf '%s' "$title" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-//;s/-$//' | cut -c1-48)"
+    blob="$(printf 'id: %s\ntitle: %s\nauthor: %s\ndate: %s\nepoch: %s\nitems: %s\n--\n%s\n' \
+             "$id" "$title" "$(_me)" "$(_now_iso)" "$(_now_epoch)" "$items" "$body" | _blob)"
+    tree="$(_tree_with "decisions/$id-$slug.md" "$blob")" || _die "could not build the board tree"
+    _commit_push "$tree" "board: decision $id by $(_me)"; rc=$?
+    case $rc in
+      0) printf 'Decision %s recorded and shared: %s\n' "$id" "$title"; cmd_cache >/dev/null; return 0 ;;
+      3) printf 'Decision %s recorded LOCALLY ONLY (remote unreachable) — the team cannot see it yet.\n' "$id"; return 0 ;;
+    esac
+    attempt=$((attempt+1))   # somebody else recorded one first: re-read so the ids do not collide
+  done
+  _die "the board kept changing; retry"
+}
+
+cmd_decisions(){ # decisions [id]
+  _have_board || { echo "No board here ($(_act init))."; return 0; }
+  local p c
+  if [ -n "${1:-}" ]; then
+    p="$(_decision_paths | grep -m1 "^decisions/$1-")" || true
+    [ -n "$p" ] || _die "no decision $1"
+    _cat "$p"; _seen_now; return 0
+  fi
+  local n=0
+  for p in $(_decision_paths); do
+    c="$(_cat "$p")"
+    printf '%s  %s\n    %s · %s\n' "$(_field "$c" id)" "$(_field "$c" title)" "$(_field "$c" author)" "$(_field "$c" date)"
+    n=$((n+1))
+  done
+  [ "$n" = 0 ] && echo "No decisions recorded yet. Record one: $(_act 'decide "<what was decided>"' 'decide "<what was decided>"')"
+  _seen_now
+  return 0
+}
+
+# "New" means "recorded since you last looked at the board" — the marker moves when the user actually views
+# them, not when the cache is rebuilt, or a decision would be announced once to a session nobody was reading.
+_seen_now(){ local d; d="$(_git_dir)"; [ -n "$d" ] || return 0
+  _decision_paths | wc -l | tr -d ' ' > "$d/crew-board-seen" 2>/dev/null || true; }
+# Tested with [ -f ] rather than a redirect plus 2>/dev/null: bash applies redirections left to right, so an
+# input redirect from a missing file fails BEFORE stderr is silenced and the complaint reaches the terminal —
+# which is how a first-run read leaked an error line into a session-start hook.
+_seen_count(){ local d s=""; d="$(_git_dir)"
+  [ -n "$d" ] && [ -f "$d/crew-board-seen" ] && s="$(tr -cd '0-9' < "$d/crew-board-seen" 2>/dev/null)"
+  printf '%s' "${s:-0}"; }
+
+cmd_off(){ # off [--global]
+  git config ${1:+--global} crew.board off; _load_cfg
+  cmd_cache >/dev/null
+  echo "Board OFF${1:+ (global: every repo)}. No claim needed, no commit gate, no edit gate; the board itself is untouched."
+  echo "Back on: $(_act "on${1:+ --global}")"
+}
+cmd_on(){
+  git config ${1:+--global} --unset crew.board 2>/dev/null || true
+  git config ${1:+--global} --unset csk.board 2>/dev/null || true   # the 2.x key would otherwise keep it off
+  # A --global off would otherwise keep overriding a repo that just turned itself back on, and the user would
+  # see "on" printed while nothing changed.
+  [ -z "${1:-}" ] && case "$(git config --global --get crew.board 2>/dev/null || git config --global --get csk.board 2>/dev/null)" in
+    off|false|0|no) git config crew.board on ;;
+  esac
+  _load_cfg
+  cmd_cache >/dev/null
+  _enabled && echo "Board ON. Claim before you start: $(_act "claim <id>")" \
+           || echo "Still off — CREW_NO_BOARD is set in this session's environment; unset it."
+}
+
+cmd_beat(){
+  # "Still on it." A claim with no heartbeat eventually reads as abandoned, and the team is told to ask before
+  # taking it over — so an active owner has to publish liveness. Publishing costs a push, so this only ever runs
+  # from the DETACHED half of the session-start hook, and only once the mark is half-way to stale: without that
+  # guard every session start would add a commit per claim to a ref nobody reads.
+  _have_board || return 0
+  local me now half p c id ow b
+  me="$(_me)"; now="$(_now_epoch)"; half=$(( $(_conf stale_hours 8) * 3600 / 2 ))
+  for p in $(_item_paths); do
+    c="$(_cat "$p")"; ow="$(_field "$c" owner)"; [ "$ow" = "$me" ] || continue
+    [ "$(_field "$c" status)" = in_progress ] || continue
+    b="$(_field "$c" beat_epoch)"; case "$b" in ''|*[!0-9]*) b=0;; esac
+    [ $(( now - b )) -ge "$half" ] || continue
+    id="$(_field "$c" id)"
+    _mutate beat "$id" >/dev/null 2>&1 || true
+  done
+}
+
+# ---------------------------------------------------------------- capability probe + init
+
+cmd_probe(){
+  # Some servers refuse refs outside refs/heads|refs/tags (they reserve their own internal namespaces and may
+  # reject unknown ones). Rather than assume what a given GitHub/GitLab/Bitbucket install allows, push a tiny
+  # throwaway ref and read the answer from the server. On refusal, fall back to an orphan branch, which every
+  # server accepts and which enforces the same fast-forward rule the lock depends on.
+  #
+  # Measured 2026-08-09 against github.com: a custom refs/<name>/* namespace ACCEPTED, and the probe ref deleted cleanly afterwards
+  # (0 refs left). That is one server on one day, not a guarantee for every host and every org policy — which
+  # is why this stays a probe rather than becoming a hard-coded assumption.
+  local remote empty probe
+  remote="$(_remote)"
+  empty="$(git hash-object -w -t tree /dev/null)"
+  probe="$(git commit-tree "$empty" -m 'board: capability probe')"
+  if _gitnet push --quiet "$remote" "$probe:refs/crew/probe" 2>/dev/null; then
+    _gitnet push --quiet "$remote" ":refs/crew/probe" 2>/dev/null
+    git config crew.boardRef 'refs/crew/board'; _load_cfg
+    echo "probe: custom ref namespace accepted -> refs/crew/board (invisible to git branch)"
+  else
+    git config crew.boardRef 'refs/heads/crew-board'; _load_cfg
+    echo "probe: server refused refs/crew/* -> falling back to the orphan branch refs/heads/crew-board"
+    echo "       (same fast-forward lock; it will appear in the branch list — do not merge it)"
+  fi
+}
+
+cmd_init(){ # init [--remote <name|url>] [all|referenced]
+  # The board defaults to the code repo's own `origin`, which is the case that needs no decision at all: the
+  # team already shares it and already has push rights. `--remote` covers the two real reasons to separate them
+  # — a board shared across several repos, and members who may read the code repo but not push to it — without
+  # anybody having to know that the setting is a git config key.
+  if [ "${1:-}" = "--remote" ]; then
+    local target="${2:-}"; shift 2 2>/dev/null || true
+    [ -n "$target" ] || _die "init --remote needs a remote name or a URL"
+    # An existing remote NAME wins; anything else is treated as a location. Deciding by shape alone was wrong:
+    # `https://…` and `git@host:org/x.git` were recognised but a filesystem path (a self-hosted mirror, a share,
+    # a test fixture) was not, and it failed with "no remote named /srv/board.git" — which reads as a bug.
+    if git remote get-url "$target" >/dev/null 2>&1; then
+      git config crew.boardRemote "$target"; _load_cfg
+      echo "board remote: $target"
+    else
+      if git remote get-url crew-board >/dev/null 2>&1; then git remote set-url crew-board "$target"
+      else git remote add crew-board "$target"; fi
+      git config crew.boardRemote crew-board; _load_cfg
+      echo "board remote: crew-board -> $target"
+    fi
+  fi
+  if _have_board; then echo "board already initialised at $(_ref)"; return 0; fi
+  # No remote at all is a legitimate solo setup, not an error — a local board still gives you the item list,
+  # the dependency order and the commit gate. Say which one you are getting instead of failing at push time
+  # with "the remote refused", which reads as a broken tool.
+  if ! git remote get-url "$(_remote)" >/dev/null 2>&1; then
+    printf 'No remote named "%s" in this repo — creating a LOCAL board.\n' "$(_remote)"
+    printf 'It gives you the item list, dependency order and the commit gate, but nothing is shared.\n'
+    printf 'To share it later: add a remote, then %s. To point elsewhere now: %s.\n' "$(_act sync)" "$(_act 'init --remote <url>')"
+    local lblob ltree
+    lblob="$(printf 'require_item: %s\nstale_hours: 8\n' "${1:-all}" | _blob)"
+    ltree="$(_tree_with config "$lblob")" || _die "could not build the board tree"
+    git update-ref "$(_ref)" "$(git commit-tree "$ltree" -m 'board: initialise (local)')"
+    cmd_cache >/dev/null
+    echo "local board created at $(_ref)"
+    return 0
+  fi
+  local frc; _fetch; frc=$?
+  [ "$frc" = 0 ] && { echo "board already exists on the remote; fetched it"; cmd_cache >/dev/null; return 0; }
+  # Probe only a server that answered. An unreachable one refuses the probe push too, and recording that as
+  # "custom refs refused" pinned this clone to the branch form for good — away from where its team's board lives.
+  [ "$frc" = 4 ] && cmd_probe
+  local blob tree
+  blob="$(printf 'require_item: %s\nstale_hours: 8\n' "${1:-all}" | _blob)"
+  tree="$(_tree_with config "$blob")" || _die "could not build the board tree"
+  _commit_push "$tree" "board: initialise"
+  case $? in
+    0) echo "board initialised at $(_ref) on $(_remote)" ;;
+    3) echo "board created LOCALLY ONLY — the remote refused or is unreachable:"; cat "$(_git_dir)/crew-board-lasterror" ;;
+  esac
+}
+
+# ---------------------------------------------------------------- commit gate (called from commit-msg)
+
+cmd_gate(){ # gate <commit-msg-file>
+  local f="${1:-}"; [ -n "$f" ] && [ -f "$f" ] || return 0
+  # No board in this repo -> this gate does not exist. Solo users and repos that never ran init are untouched.
+  _enabled || return 0
+  _have_board || return 0
+  # Strip comments git adds to the message template before matching.
+  local msg; msg="$(grep -v '^#' "$f" 2>/dev/null)"
+  local id; id="$(printf '%s' "$msg" | grep -oE '\[#[0-9]+\]' | head -1 | tr -dc '0-9')"
+  if [ -z "$id" ]; then
+    printf '%s' "$msg" | grep -qE '\[chore\]' && return 0
+    [ "$(_conf require_item all)" = referenced ] && return 0
+    cat >&2 <<MSG
+BOARD GATE: this commit names no board item.
+  Put [#<id>] in the message for the item you are working on, or [chore] for work that
+  belongs to no item (it is recorded, not blocked).
+  See what is claimable: $(_act status)
+MSG
+    return 1
+  fi
+  local c owner status
+  c="$(_load "$id")" || { printf 'BOARD GATE: no item #%s on the board (stale board? run %s)\n' "$id" "$(_act sync)" >&2; return 1; }
+  owner="$(_field "$c" owner)"; status="$(_field "$c" status)"
+  local me; me="$(_me)"
+  if [ "$owner" != "$me" ]; then
+    printf 'BOARD GATE: #%s is held by %s, not you. Claim it or pick another: %s\n' "$id" "${owner:--}" "$(_act status)" >&2
+    printf '            (if you believe this is stale, run %s first)\n' "$(_act sync)" >&2
+    return 1
+  fi
+  [ "$status" = in_progress ] || { printf 'BOARD GATE: #%s is "%s", not in_progress. Run: %s\n' "$id" "$status" "$(_act "claim $id")" >&2; return 1; }
+  # Deliberately no heartbeat refresh here: publishing one costs a push, and a commit must work offline and
+  # must not be slowed by the network. The heartbeat is advanced by the board commands and at session start.
+  return 0
+}
+
+# ---------------------------------------------------------------- dispatch
+
+usage(){ cat <<'U'
+board.sh <command>
+  status                    board view: who holds what, what is claimable, what is blocked
+  show <id>                 one item with its shared handover / completion memory
+  claim <id>                atomic claim (fetch -> verify -> push; a lost race refuses, it never overwrites)
+  done <id> [note]          complete, record the note, unblock dependents
+  drop <id> <note>          release; the handover note is REQUIRED
+  note <id> <text>          update the item's handover memory without releasing it
+  add <id> <title> [deps] [external]
+  init [--remote <name|url>] [all|referenced]
+                            create the board (probes ref support first). Defaults to `origin`; --remote points
+                            it at a separate board repository (a URL gets its own `crew-board` remote).
+  probe                     ask the server whether it accepts the custom ref namespace
+  off [--global] / on       switch every board gate off (or back on) for this repo, or for every repo.
+                            A repo that never ran `init` has no gates in the first place.
+  decide "<what>" "<why + what it means for other work>" [items]
+                            record a team decision on the board so it reaches everyone, not just this machine
+  decisions [id]            list them, or read one
+  sync                      fetch the board and refresh the local cache
+  cache                     rebuild the local cache (no network)
+  gate <msgfile>            commit-msg claim gate
+U
+}
+
+git rev-parse --git-dir >/dev/null 2>&1 || _die "not a git repository"
+CMD="${1:-status}"; shift 2>/dev/null || true
+case "$CMD" in
+  status) cmd_status ;;
+  show)   cmd_show "$@" ;;
+  claim)  cmd_claim "$@" ;;
+  done)   cmd_done "$@" ;;
+  drop)   cmd_drop "$@" ;;
+  note)   cmd_note "$@" ;;
+  add)    cmd_add "$@" ;;
+  init)   cmd_init "$@" ;;
+  probe)  cmd_probe ;;
+  decide) cmd_decide "$@" ;;
+  decisions) cmd_decisions "$@" ;;
+  sync)   cmd_sync ;;
+  cache)  cmd_cache ;;
+  beat)   cmd_beat ;;
+  off)    cmd_off "$@" ;;
+  on)     cmd_on "$@" ;;
+  gate)   cmd_gate "$@" ;;
+  -h|--help|help) usage ;;
+  *) usage; exit 1 ;;
+esac