@indigoai-us/hq-cli 5.315.0 → 5.316.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [5.316.0] — 2026-10-02
+- Add a default-off autopilot notice for registered lead headlines that remain stale for more than 55 minutes, using `headline_at` or the timestamp prefix in `now`.
+- Add a flag-gated per-job option to complete successful scheduled bot runs without an owner DM; failures still report normally.
+- Port `share-suggestion-state`, `repo-run-registry`, and `detect-stale-review-base` to native TypeScript on the fast route behind the default-off `core-native-hook-helpers` flag.
+- Detect the installed hq-cli drain entry in provider settings so lane messages do not warn when the running worker can drain its inbox.
+- Resolve hostless Outpost lane lookups by ULID without transporting the full lane list, including compatibility with older Outpost CLIs.
+- Refuse to publish a stable or rc release tag unless its commit is on main, its version is higher than npm latest, and it contains the commit npm latest was built from. This stops a tag on an old commit from putting older code on npm as latest.
+- Remove an unused file-exists helper and stop exporting four disk-guard internals. No behaviour change.
+
 ## [5.315.0] — 2026-10-02
 - The CLI loads the Sentry error-reporting library only when it first needs it, so commands that report nothing start with fewer imports. Reporting, scrubbing and flushing work as before.
 - Keep first-sync guidance enabled without its rollout gate and remove the obsolete plan-limit fallback flag-off test.

package/assets/scaffold/core/scripts/detect-stale-review-base.sh

@@ -0,0 +1,199 @@
+#!/usr/bin/env bash
+# detect-stale-review-base.sh — find remote-tracking refs in the HQ root that
+# have fallen so far behind local HEAD that a diff/review tool will pick one as
+# its comparison base and try to review the entire tree.
+#
+# Background: HQ autosaves one commit per edited file (.claude/hooks/hq-autocommit.sh)
+# and is never pushed to a remote (policy hq-root-never-push-remote). An HQ root
+# that is itself a git repo with a remote attached therefore accumulates local
+# commits the remote-tracking ref never receives. The gap only grows.
+#
+# Review tools that auto-select a base branch resolve it from refs/remotes/*.
+# Once the gap is large enough that base is effectively "the empty tree", so the
+# review payload becomes the whole repository instead of the working delta. The
+# observed failure (2026-07-28) was a Codex desktop git worker taking SIGTRAP on
+# a 108,434-path / 29.2 MB payload built against a remote-tracking ref 22,881
+# commits behind local main, retried until the app reached 5.5 GB RSS.
+#
+# Codex exposes no configuration for the review base — `review_model` only picks
+# the reviewing model, and `auto_review` governs the approval-reviewer subagent,
+# not code review. `codex review --base` is per-invocation and does not reach the
+# desktop app's automatic review. Removing the stale ref is therefore the only
+# lever available on the HQ side: with nothing stale to resolve, there is no
+# whole-tree base to pick.
+#
+# Modes:
+#   (default)  human-readable report; exit 0.
+#   --json     machine-readable JSON array; exit 0.
+#   --check    exit 0 if clean, 1 if any stale base exists (advisory gate).
+#   --fix      delete the offending remote-tracking refs; print each action.
+#
+# --fix deletes ONLY refs under refs/remotes/. It never touches refs/heads/,
+# never removes a configured remote, never fetches, and never pushes. The
+# deletion is recoverable: `git fetch <remote>` recreates the ref (and, on an HQ
+# root, recreates this condition — HQ roots are not meant to be fetched).
+#
+# Thresholds (override with flags or env):
+#   --max-paths N    changed paths tolerated vs. a base   (default 5000)
+#   --max-commits N  commits ahead tolerated vs. a base   (default 1000)
+# A ref is stale when EITHER threshold is exceeded. Path count is the primary
+# signal: it is what determines the review payload size.
+
+set -euo pipefail
+
+MODE="report"
+MAX_PATHS="${HQ_REVIEW_BASE_MAX_PATHS:-5000}"
+MAX_COMMITS="${HQ_REVIEW_BASE_MAX_COMMITS:-1000}"
+ROOT_OVERRIDE=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --json)        MODE="json"; shift ;;
+    --check)       MODE="check"; shift ;;
+    --fix)         MODE="fix"; shift ;;
+    --max-paths)   MAX_PATHS="${2:?--max-paths needs a value}"; shift 2 ;;
+    --max-commits) MAX_COMMITS="${2:?--max-commits needs a value}"; shift 2 ;;
+    --root)        ROOT_OVERRIDE="${2:?--root needs a value}"; shift 2 ;;
+    -h|--help)     sed -n '2,41p' "$0"; exit 0 ;;
+    *)
+      printf 'detect-stale-review-base: unknown argument: %s\n' "$1" >&2
+      printf 'usage: %s [--json|--check|--fix] [--max-paths N] [--max-commits N] [--root PATH]\n' "$0" >&2
+      exit 2 ;;
+  esac
+done
+
+case "$MAX_PATHS" in ''|*[!0-9]*)
+  echo "detect-stale-review-base: --max-paths must be a non-negative integer" >&2; exit 2 ;;
+esac
+case "$MAX_COMMITS" in ''|*[!0-9]*)
+  echo "detect-stale-review-base: --max-commits must be a non-negative integer" >&2; exit 2 ;;
+esac
+
+# Resolve HQ root: explicit flag wins, then env, then the tree this script ships in.
+# Physical paths (pwd -P) so the nesting guard below cannot be dodged through a
+# symlink to a clone.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+HQ_ROOT="${ROOT_OVERRIDE:-${HQ_ROOT:-${CLAUDE_PROJECT_DIR:-$(cd "$SCRIPT_DIR/../.." && pwd -P)}}}"
+
+if [ ! -d "$HQ_ROOT" ]; then
+  echo "detect-stale-review-base: no such directory: $HQ_ROOT" >&2
+  exit 2
+fi
+HQ_ROOT="$(cd "$HQ_ROOT" && pwd -P)"
+
+emit_clean() {
+  case "$MODE" in
+    json)  echo "[]" ;;
+    check) : ;;
+    fix)   printf 'detect-stale-review-base: nothing to fix (%s)\n' "$1" ;;
+    *)     printf 'detect-stale-review-base: clean (%s)\n' "$1" ;;
+  esac
+  exit 0
+}
+
+# Only ever operate on an HQ root. This guard is what keeps the tool away from
+# repos/ working clones, where a remote-tracking ref far behind local HEAD is
+# ordinary and its refs must never be deleted.
+if [ ! -f "$HQ_ROOT/core/core.yaml" ]; then
+  echo "detect-stale-review-base: $HQ_ROOT is not an HQ root (no core/core.yaml)" >&2
+  exit 2
+fi
+
+# A repos/ clone of hq-core is itself HQ-root-shaped — core/core.yaml ships in
+# the repo, so the check above cannot tell it from a real install. What does
+# distinguish a working clone is position: clones and worktree checkouts live
+# NESTED inside another HQ root (repos/, workspace/worktrees/), while a real HQ
+# root never does. Refuse any candidate with an HQ-root-shaped ancestor rather
+# than trusting the caller.
+ANCESTOR="$(dirname "$HQ_ROOT")"
+while [ -n "$ANCESTOR" ] && [ "$ANCESTOR" != "/" ] && [ "$ANCESTOR" != "." ]; do
+  if [ -f "$ANCESTOR/core/core.yaml" ]; then
+    echo "detect-stale-review-base: $HQ_ROOT is nested inside the HQ root $ANCESTOR — refusing. Working clones and worktree checkouts keep their remote-tracking refs; this tool only repairs a top-level HQ install." >&2
+    exit 2
+  fi
+  ANCESTOR="$(dirname "$ANCESTOR")"
+done
+
+if [ "$(git -C "$HQ_ROOT" rev-parse --show-toplevel 2>/dev/null || true)" != "$HQ_ROOT" ]; then
+  emit_clean "HQ root is not a git repository — no review base to go stale"
+fi
+
+if ! git -C "$HQ_ROOT" rev-parse --verify -q HEAD >/dev/null 2>&1; then
+  emit_clean "HQ root has no commits yet"
+fi
+
+REFS="$(git -C "$HQ_ROOT" for-each-ref --format='%(refname)' refs/remotes 2>/dev/null || true)"
+if [ -z "$REFS" ]; then
+  emit_clean "no remote-tracking refs in the HQ root"
+fi
+
+STALE_REFS=""
+STALE_JSON=""
+STALE_COUNT=0
+
+while IFS= read -r ref; do
+  [ -n "$ref" ] || continue
+  # Symbolic refs (refs/remotes/<remote>/HEAD) resolve to a ref already covered.
+  if git -C "$HQ_ROOT" symbolic-ref -q "$ref" >/dev/null 2>&1; then
+    continue
+  fi
+
+  commits="$(git -C "$HQ_ROOT" rev-list --count "$ref..HEAD" 2>/dev/null || true)"
+  [ -n "$commits" ] || continue
+
+  # Three-dot: paths changed since the merge base — what a review of
+  # "HEAD against this base" would actually carry. This is the expensive probe
+  # on exactly the repos this tool exists for (it IS the whole-tree diff), so
+  # skip it when the commit gap alone already proves staleness and the mode
+  # does not display counts. --json always measures both.
+  paths=""
+  if [ "$commits" -le "$MAX_COMMITS" ] || [ "$MODE" = "json" ]; then
+    paths="$(git -C "$HQ_ROOT" diff --name-only "$ref...HEAD" 2>/dev/null | wc -l | tr -d ' ')"
+    [ -n "$paths" ] || paths=0
+  fi
+
+  if [ "$commits" -le "$MAX_COMMITS" ] && [ "$paths" -le "$MAX_PATHS" ]; then
+    continue
+  fi
+
+  STALE_COUNT=$((STALE_COUNT + 1))
+  STALE_REFS="${STALE_REFS}${ref}"$'\n'
+  if [ "$MODE" = "json" ]; then
+    [ -z "$STALE_JSON" ] || STALE_JSON="${STALE_JSON},"
+    STALE_JSON="${STALE_JSON}{\"ref\":\"${ref}\",\"commits_ahead\":${commits},\"changed_paths\":${paths}}"
+  fi
+done <<EOF
+$REFS
+EOF
+
+if [ "$STALE_COUNT" -eq 0 ]; then
+  emit_clean "every remote-tracking ref is within ${MAX_PATHS} paths / ${MAX_COMMITS} commits of HEAD"
+fi
+
+case "$MODE" in
+  json)
+    printf '[%s]\n' "$STALE_JSON"
+    ;;
+  check)
+    printf 'detect-stale-review-base: %s stale review base(s) in %s\n' "$STALE_COUNT" "$HQ_ROOT" >&2
+    exit 1
+    ;;
+  fix)
+    printf '%s' "$STALE_REFS" | while IFS= read -r ref; do
+      [ -n "$ref" ] || continue
+      git -C "$HQ_ROOT" update-ref -d "$ref"
+      printf 'detect-stale-review-base: deleted %s\n' "$ref"
+    done
+    printf 'detect-stale-review-base: removed %s stale review base(s). A later `git fetch` in the HQ root recreates them — HQ roots are not meant to be fetched (policy hq-root-never-push-remote).\n' "$STALE_COUNT"
+    ;;
+  *)
+    printf 'detect-stale-review-base: %s stale review base(s) in %s\n\n' "$STALE_COUNT" "$HQ_ROOT"
+    printf '%s' "$STALE_REFS" | while IFS= read -r ref; do
+      [ -n "$ref" ] || continue
+      c="$(git -C "$HQ_ROOT" rev-list --count "$ref..HEAD" 2>/dev/null || echo '?')"
+      p="$(git -C "$HQ_ROOT" diff --name-only "$ref...HEAD" 2>/dev/null | wc -l | tr -d ' ')"
+      printf '  %s — HEAD is %s commits ahead, %s changed paths\n' "$ref" "$c" "$p"
+    done
+    printf '\nA review tool that auto-selects a base will pick one of these and build a\nwhole-tree payload from it. Remove them with:\n\n  bash core/scripts/detect-stale-review-base.sh --fix\n'
+    ;;
+esac

package/assets/scaffold/core/scripts/repo-run-registry.sh

@@ -0,0 +1,408 @@
+#!/bin/bash
+# repo-run-registry.sh — CLI for cross-session repo-level run coordination
+#
+# Manages workspace/orchestrator/active-runs.json: a global registry of
+# long-running Claude sessions that currently hold a repo (scope=repo) or
+# a specific worktree (scope=worktree:<path>). Other sessions consult this
+# registry at SessionStart and before Edit/Write/dangerous Bash to avoid
+# concurrent edit conflicts.
+#
+# See plan: ~/.claude/plans/structured-stargazing-candy.md
+# Policy: core/policies/repo-run-coordination.md
+#
+# Subcommands:
+#   register  --run-id X --pid N --session-id S --command C --project P --repo R --scope SC [--host H]
+#   deregister --run-id X
+#   heartbeat --run-id X
+#   list
+#   check --target PATH [--pid N] [--session-id S]
+#   clean-stale
+#   owner-of --path PATH
+#
+# Exit codes:
+#   0 = ok / not blocked
+#   2 = blocked by foreign owner (check only)
+#   1 = usage / internal error
+
+set -euo pipefail
+
+HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+# shellcheck source=core/scripts/lib/portable.sh
+. "$HQ_ROOT/core/scripts/lib/portable.sh"
+REG_DIR="$HQ_ROOT/workspace/orchestrator"
+REG_FILE="$REG_DIR/active-runs.json"
+LOCK_DIR="$REG_FILE.lock"
+# Resolve the orchestrator settings file. personal/settings is read DIRECTLY now
+# (the reindex symlink mirror into core/settings is retired). orchestrator.yaml
+# ships as a core default; unlike the list-shaped overlays (policies/workers/
+# knowledge, where core + personal BOTH surface), this is a singleton config
+# file — so a personal copy, when present, overrides the shipped default.
+ORCH_YAML="$HQ_ROOT/core/settings/orchestrator.yaml"
+if [[ -f "$HQ_ROOT/personal/settings/orchestrator.yaml" ]]; then
+  ORCH_YAML="$HQ_ROOT/personal/settings/orchestrator.yaml"
+fi
+
+# ---------- helpers ----------
+
+_log() { echo "[repo-run-registry] $*" >&2; }
+_die() { echo "ERROR: $*" >&2; exit 1; }
+
+_iso_now() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
+
+# ISO8601 (UTC, trailing Z) → epoch seconds. BSD date first, then GNU date.
+# A BSD-only parse returned 0 on Linux, so _prune_stale treated every live
+# run as stale and deleted it before any check could block on it.
+_iso_to_epoch() {
+  local iso="$1"
+  date -u -j -f "%Y-%m-%dT%H:%M:%SZ" "$iso" +%s 2>/dev/null \
+    || date -u -d "$iso" +%s 2>/dev/null \
+    || echo 0
+}
+
+_hostname() { hostname -s 2>/dev/null || echo "unknown"; }
+
+_abs_path() {
+  local p="$1"
+  if [[ "$p" = /* ]]; then
+    echo "$p"
+  else
+    (cd "$(dirname "$p")" 2>/dev/null && echo "$(pwd)/$(basename "$p")") || echo "$p"
+  fi
+}
+
+_ensure_reg() {
+  mkdir -p "$REG_DIR"
+  if [[ ! -f "$REG_FILE" ]]; then
+    echo '{"version":1,"runs":[]}' > "$REG_FILE"
+  fi
+}
+
+# Atomic mutex via mkdir — single-machine only
+_lock() { _try_lock || _die "registry lock timeout"; }
+
+# Returns 1 instead of exiting when the lock stays busy (~5s).
+_try_lock() {
+  local tries=0
+  local max=50
+  # register takes the lock before _ensure_reg; without its parent the mkdir
+  # below can never succeed and the first register on a fresh install timed out.
+  mkdir -p "$REG_DIR" 2>/dev/null || true
+  while ! mkdir "$LOCK_DIR" 2>/dev/null; do
+    tries=$((tries + 1))
+    if [[ $tries -ge $max ]]; then
+      # stale lock fallback: remove if older than 60s
+      if [[ -d "$LOCK_DIR" ]]; then
+        local age mtime
+        mtime="$(portable_stat_mtime "$LOCK_DIR" 2>/dev/null || echo 0)"
+        age=$(( $(date +%s) - mtime ))
+        if [[ $age -gt 60 ]]; then
+          rm -rf "$LOCK_DIR" 2>/dev/null || true
+          continue
+        fi
+      fi
+      return 1
+    fi
+    sleep 0.1
+  done
+}
+_unlock() { rm -rf "$LOCK_DIR" 2>/dev/null || true; }
+
+# list, owner-of and check prune too. Hold the lock so a reader cannot write an
+# older snapshot over a concurrent register or heartbeat. If the lock stays
+# busy, skip the prune and answer from the file as it is.
+_prune_stale_locked() {
+  _try_lock || return 0
+  trap '_unlock' EXIT
+  _prune_stale >/dev/null 2>&1 || true
+  _unlock
+  trap - EXIT
+}
+
+_is_pid_alive() {
+  local pid="$1"
+  [[ -z "$pid" || "$pid" == "null" ]] && return 1
+  kill -0 "$pid" 2>/dev/null
+}
+
+_stale_minutes() {
+  if [[ -f "$ORCH_YAML" ]] && command -v yq >/dev/null 2>&1; then
+    local v
+    v=$(yq eval '.repo_coordination.stale_heartbeat_minutes // 15' "$ORCH_YAML" 2>/dev/null)
+    [[ -n "$v" && "$v" != "null" ]] && { echo "$v"; return; }
+  fi
+  echo 15
+}
+
+# Given a target filesystem path, walk up to find the nearest ancestor that
+# is either a git repo root OR a HQ orchestrator-known repo path. Emits the
+# absolute path of the owning repo (or empty string if none).
+_find_owning_repo() {
+  local target
+  target=$(_abs_path "$1")
+  [[ -z "$target" ]] && return
+  # If target doesn't exist, walk up to an existing ancestor first
+  while [[ -n "$target" && ! -e "$target" ]]; do
+    local parent
+    parent=$(dirname "$target")
+    [[ "$parent" == "$target" ]] && return
+    target="$parent"
+  done
+  # Now walk up looking for .git
+  local dir="$target"
+  [[ -f "$dir" ]] && dir=$(dirname "$dir")
+  while [[ "$dir" != "/" && -n "$dir" ]]; do
+    if [[ -e "$dir/.git" ]]; then
+      echo "$dir"
+      return
+    fi
+    dir=$(dirname "$dir")
+  done
+  echo ""
+}
+
+# Prune stale entries: dead PID OR heartbeat older than stale_minutes.
+# Emits the number of pruned entries on stderr.
+_prune_stale() {
+  _ensure_reg
+  local stale_min
+  stale_min=$(_stale_minutes)
+  local now_epoch
+  now_epoch=$(date +%s)
+  local cutoff=$((now_epoch - stale_min * 60))
+
+  # Build a jq filter that keeps only entries with fresh heartbeat; then
+  # separately filter dead PIDs in bash.
+  local tmp="$REG_FILE.tmp.$$"
+  local kept='[]'
+  local runs
+  runs=$(jq -c '.runs[]' "$REG_FILE" 2>/dev/null || true)
+  local pruned=0
+  if [[ -n "$runs" ]]; then
+    while IFS= read -r entry; do
+      [[ -z "$entry" ]] && continue
+      local pid hb_iso hb_epoch
+      pid=$(echo "$entry" | jq -r '.pid // empty')
+      hb_iso=$(echo "$entry" | jq -r '.heartbeat_at // .started_at // empty')
+      hb_epoch=$(_iso_to_epoch "$hb_iso")
+      if ! _is_pid_alive "$pid"; then
+        pruned=$((pruned + 1))
+        continue
+      fi
+      if [[ $hb_epoch -lt $cutoff ]]; then
+        pruned=$((pruned + 1))
+        continue
+      fi
+      kept=$(echo "$kept" | jq --argjson e "$entry" '. + [$e]')
+    done <<< "$runs"
+  fi
+  jq --argjson runs "$kept" '.runs = $runs' "$REG_FILE" > "$tmp"
+  mv "$tmp" "$REG_FILE"
+  [[ $pruned -gt 0 ]] && _log "pruned $pruned stale entries"
+  return 0
+}
+
+# ---------- subcommands ----------
+
+_cmd_register() {
+  local run_id="" pid="" session_id="" command="" project="" repo="" scope="" host=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --run-id) run_id="$2"; shift 2 ;;
+      --pid) pid="$2"; shift 2 ;;
+      --session-id) session_id="$2"; shift 2 ;;
+      --command) command="$2"; shift 2 ;;
+      --project) project="$2"; shift 2 ;;
+      --repo) repo="$2"; shift 2 ;;
+      --scope) scope="$2"; shift 2 ;;
+      --host) host="$2"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+  [[ -z "$pid" || -z "$command" || -z "$repo" || -z "$scope" ]] && \
+    _die "register requires --pid --command --repo --scope"
+  repo=$(_abs_path "$repo")
+  [[ -z "$run_id" ]] && run_id="$(echo "$command" | tr '/' '-')-$(date +%s)-${project:-none}-$pid"
+  [[ -z "$host" ]] && host=$(_hostname)
+
+  _lock
+  trap '_unlock' EXIT
+  _ensure_reg
+  _prune_stale
+
+  local now
+  now=$(_iso_now)
+  local tmp="$REG_FILE.tmp.$$"
+  jq --arg run_id "$run_id" \
+     --arg pid "$pid" \
+     --arg session_id "$session_id" \
+     --arg command "$command" \
+     --arg project "$project" \
+     --arg repo "$repo" \
+     --arg scope "$scope" \
+     --arg host "$host" \
+     --arg now "$now" \
+    '.runs |= map(select(.run_id != $run_id)) |
+     .runs += [{
+       run_id: $run_id,
+       pid: ($pid | tonumber),
+       session_id: $session_id,
+       command: $command,
+       project: $project,
+       repo_path: $repo,
+       scope: $scope,
+       host: $host,
+       started_at: $now,
+       heartbeat_at: $now
+     }]' "$REG_FILE" > "$tmp"
+  mv "$tmp" "$REG_FILE"
+  _unlock
+  trap - EXIT
+  echo "$run_id"
+}
+
+_cmd_deregister() {
+  local run_id=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --run-id) run_id="$2"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+  [[ -z "$run_id" ]] && _die "deregister requires --run-id"
+  _lock
+  trap '_unlock' EXIT
+  _ensure_reg
+  local tmp="$REG_FILE.tmp.$$"
+  jq --arg run_id "$run_id" '.runs |= map(select(.run_id != $run_id))' "$REG_FILE" > "$tmp"
+  mv "$tmp" "$REG_FILE"
+  _unlock
+  trap - EXIT
+}
+
+_cmd_heartbeat() {
+  local run_id=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --run-id) run_id="$2"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+  [[ -z "$run_id" ]] && _die "heartbeat requires --run-id"
+  _lock
+  trap '_unlock' EXIT
+  _ensure_reg
+  local now
+  now=$(_iso_now)
+  local tmp="$REG_FILE.tmp.$$"
+  jq --arg run_id "$run_id" --arg now "$now" \
+    '.runs |= map(if .run_id == $run_id then .heartbeat_at = $now else . end)' \
+    "$REG_FILE" > "$tmp"
+  mv "$tmp" "$REG_FILE"
+  _unlock
+  trap - EXIT
+}
+
+_cmd_list() {
+  _ensure_reg
+  _prune_stale_locked
+  jq '.runs' "$REG_FILE"
+}
+
+_cmd_clean_stale() {
+  _lock
+  trap '_unlock' EXIT
+  _prune_stale
+  _unlock
+  trap - EXIT
+}
+
+_cmd_owner_of() {
+  local path=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --path) path="$2"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+  [[ -z "$path" ]] && _die "owner-of requires --path"
+  local repo
+  repo=$(_find_owning_repo "$path")
+  [[ -z "$repo" ]] && { echo ""; return; }
+  _ensure_reg
+  _prune_stale_locked
+  jq --arg repo "$repo" --arg target "$(_abs_path "$path")" \
+    '[.runs[] | select(
+       (.scope == "repo" and .repo_path == $repo)
+       or (.scope | startswith("worktree:")) and
+          ($target | startswith(.scope | sub("^worktree:"; "")))
+     )]' "$REG_FILE"
+}
+
+# Check if a target path is owned by a foreign run.
+# Exit 0 = clear / self-owned / no owner; exit 2 = blocked by foreign owner.
+_cmd_check() {
+  local target="" my_pid="" my_session=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --target) target="$2"; shift 2 ;;
+      --pid) my_pid="$2"; shift 2 ;;
+      --session-id) my_session="$2"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+  [[ -z "$target" ]] && _die "check requires --target"
+
+  _ensure_reg
+  _prune_stale_locked
+
+  local abs_target
+  abs_target=$(_abs_path "$target")
+  local repo
+  repo=$(_find_owning_repo "$abs_target")
+  [[ -z "$repo" ]] && return 0
+
+  # Collect foreign entries covering this target
+  local matches
+  matches=$(jq -c --arg repo "$repo" \
+                  --arg target "$abs_target" \
+                  --arg mypid "${my_pid:-0}" \
+                  --arg mysid "${my_session:-__none__}" \
+    '[.runs[] | select(
+       ((.scope == "repo" and .repo_path == $repo)
+         or ((.scope | startswith("worktree:")) and
+             ($target | startswith(.scope | sub("^worktree:"; "")))))
+       and ((.pid | tostring) != $mypid)
+       and (.session_id != $mysid)
+     )]' "$REG_FILE" 2>/dev/null || echo '[]')
+
+  local n
+  n=$(echo "$matches" | jq 'length')
+  if [[ "${n:-0}" -eq 0 ]]; then
+    return 0
+  fi
+
+  # Emit one summary line per owner to stderr for the calling hook
+  echo "$matches" | jq -r '.[] |
+    "run_id=\(.run_id) pid=\(.pid) command=\(.command) project=\(.project) scope=\(.scope) repo=\(.repo_path) started=\(.started_at) heartbeat=\(.heartbeat_at)"' >&2
+  return 2
+}
+
+# ---------- dispatch ----------
+
+main() {
+  local sub="${1:-}"
+  [[ -z "$sub" ]] && _die "usage: repo-run-registry.sh <subcommand> [args...]"
+  shift
+  case "$sub" in
+    register) _cmd_register "$@" ;;
+    deregister) _cmd_deregister "$@" ;;
+    heartbeat) _cmd_heartbeat "$@" ;;
+    list) _cmd_list "$@" ;;
+    check) _cmd_check "$@" ;;
+    clean-stale) _cmd_clean_stale "$@" ;;
+    owner-of) _cmd_owner_of "$@" ;;
+    *) _die "unknown subcommand: $sub" ;;
+  esac
+}
+
+main "$@"