@indigoai-us/hq-cli 5.290.0 → 5.291.0

package/CHANGELOG.md

@@ -2,7 +2,34 @@
 
 ## [Unreleased]
 
+## [5.291.0] — 2026-09-29
+- Add native `hq core jobs schedule-parse` and `validate` commands behind the default-off `core-native-jobs` gate, retaining their shell rollback companions.
+
+- Offline mesh reconcile does not refresh person tokens or start interactive sign-in; valid cached tokens still validate device defaults.
+- Retry daemon state replacement briefly when Windows reports transient rename contention, while keeping the previous state file intact on failure.
+- When a lane has no Board story ID, `hq lanes` records the lane event without sending a story PATCH.
+- `hq core policy age-report` now matches the legacy script when a missing reference has no hidden sibling under a dot directory.
+- Keep bundled scaffold scripts current with staging and check their pinned source revision in CI.
+- Starter plan-limit refusals now show why and how to fix them. The CLI reads
+  hq-pro's hard-stop 402 body (and the older shapes) and prints the server
+  message, the usage, the fix options, the free-month offer when one stands,
+  and the upgrade link, including in non-interactive runs. `hq secrets set`,
+  `hq secrets generate-link`, `hq members invite` and `hq integrations connect`
+  all use this renderer and exit non-zero.
+- `hq sync push`, `hq sync push --all`, `hq sync now`, `hq sync now --all` and
+  `hq skill create` no longer print a success line when a plan limit refused a
+  file. They list the refused files the runner names, show the upgrade link and
+  exit non-zero. `hq sync push --json` adds `planLimitRefused` to its `complete`
+  event instead.
+
 ## [5.290.0] — 2026-09-29
+- Ignore stale but well-formed worker-profile queue details when another valid queue reason is stored, and remove them on the lane's next write.
+
+### Added
+
+- Gate `hq sync push --personal <paths>` behind the default-off `cli.personal-targeted-push-paths` flag; explicit paths are normalized and checked against personal-vault scope and exclusions before upload.
+
+## [5.289.0] — 2026-09-29
 - A failed `hq update` restores the previous working hq-cli install when it could be backed up, instead of leaving the CLI partially updated.
 
 ## [5.288.0] — 2026-09-29
@@ -20,6 +47,21 @@
 - `merge-copies --rewrite-refs` no longer holds a survivor as `merge_invalid` when it gains external ids but has no `web_domains` key (or the reverse).
 - `merge-copies` treats an annotation list item whose first key is `path:` as a link to the copy, so it no longer deletes a copy such an annotation still names.
 
+### Added
+
+- Add lead autopilot prompts to the lanes reconcile pass behind
+  `lanes.lead-autopilot` (off by default) and expose
+  `hq lanes autopilot run --dry-run --json`. It asks registered leads to review
+  finished, blocked, or missing workers or fill unused grant slots, starts a
+  ready worker after an
+  unanswered fill prompt ages 15 minutes, and relies on keep-alive to resume
+  completed leads with open work.
+
+### Fixed
+
+- Retry daemon state replacement briefly when Windows reports transient rename
+  contention, while keeping the previous state file intact on failure.
+
 ## [5.287.0] — 2026-09-29
 - Group hook-timeout events by script while preserving triage diagnostics.
 - Preserve safe slow-child script basenames in hook-timeout diagnostics.
@@ -29,6 +71,8 @@
   handoff scripts behind the default-off `core-native-handoff` flag. The
   original shell assets remain bundled as the rollback path.
 - Add default-off native `hq core handoff finalize`, `post`, and `open-steps` commands with the staging scripts retained as the rollback path.
+- Add a default-off `core-native-jobs` rollout gate for native `hq core jobs
+  schedule-parse` and `validate` commands.
 
 ### Fixed
 

package/assets/scaffold/core/scripts/hook-lib.sh

@@ -23,6 +23,26 @@
 
 HQ_LIB_JQ="$(command -v jq 2>/dev/null || true)"
 HQ_LIB_NODE="$(command -v node 2>/dev/null || true)"
+
+# Is "\" a path SEPARATOR on this host, or an ordinary filename character?
+#
+# On Windows-family shells (Git Bash/MSYS/Cygwin) it is a separator and must be
+# folded to "/". On POSIX it is a perfectly legal character IN a filename, and
+# folding it corrupts real paths — dangerously so in a guard: with a symlink
+# literally named `link\name` pointing into repos/, rewriting the input yields
+# the non-existent lexical path workspace/link/name/file.txt, which resolves to
+# nothing under repos/, so the hook exits 0 while the actual write follows the
+# symlink and lands in the checkout.
+#
+# Detected ONCE at source time — hq_normpath is on the hook hot path and must
+# not fork `uname` per call. Override with HQ_LIB_WINSEP=1|0 for tests.
+if [ -z "${HQ_LIB_WINSEP:-}" ]; then
+  HQ_LIB_WINSEP=0
+  case "${OSTYPE:-}" in msys*|cygwin*|win32*) HQ_LIB_WINSEP=1 ;; esac
+  if [ "$HQ_LIB_WINSEP" = "0" ]; then
+    case "$(uname -s 2>/dev/null || true)" in MINGW*|MSYS*|CYGWIN*) HQ_LIB_WINSEP=1 ;; esac
+  fi
+fi
 case "${HQ_HOOK_ENGINE:-}" in
   jq)   HQ_LIB_NODE="" ;;
   node) HQ_LIB_JQ="" ;;
@@ -79,35 +99,214 @@ hq_json_encode() {
 
 # hq_normpath <path>
 #   Lexical normalization (no filesystem access): backslashes -> "/", collapse
-#   "//" and "/./", resolve "x/..", trim trailing "/" (keeps root). Both
-#   engines produce IDENTICAL output, so equality checks between two
+#   interior "//" and "/./", resolve "x/..", trim trailing "/" (keeps root).
+#   Both engines produce IDENTICAL output, so equality checks between two
 #   hq_normpath results are stable regardless of engine or platform.
+#
+#   A LEADING "//" is preserved ONLY where it names a genuinely DISTINCT root:
+#   Windows Git Bash/MSYS/Cygwin UNC shares (//server/share). POSIX leaves the
+#   exactly-two-slash case implementation-defined; Linux resolves //tmp and /tmp
+#   to the SAME directory, so preserving the distinction there protects nothing
+#   and instead guarantees a mismatch whenever the two sides of a prefix check
+#   are spelled differently. Both directions are live bypasses: a "//" project
+#   root with a "/" file path, and a "/" root with a "//" file path, each let a
+#   write into repos/ through. `pwd -P` does preserve "//", so the collapse must
+#   happen HERE, after the physical resolution both helpers end with -- that is
+#   what makes every spelling of one physical path compare equal, which is the
+#   only property the repo guard actually depends on.
 hq_normpath() {
-  printf '%s' "$1" | awk '
-    {
-      p = $0
-      gsub(/\\/, "/", p)
-      isabs = (p ~ /^\//) ? 1 : 0
-      drive = ""
-      if (p ~ /^[A-Za-z]:/) { drive = substr(p, 1, 2); p = substr(p, 3); isabs = (p ~ /^\//) ? 1 : 0 }
-      n = split(p, seg, "/")
-      out_n = 0
-      for (i = 1; i <= n; i++) {
-        s = seg[i]
-        if (s == "" || s == ".") continue
-        if (s == "..") {
-          if (out_n > 0 && out[out_n] != "..") { out_n--; continue }
-          if (isabs) continue
-          out[++out_n] = ".."
-        } else out[++out_n] = s
-      }
-      r = ""
-      for (i = 1; i <= out_n; i++) r = r (i > 1 ? "/" : "") out[i]
-      if (isabs) r = "/" r
-      if (drive != "") r = drive r
-      if (r == "") r = (isabs ? "/" : ".")
-      print r
-    }'
+  local input="$1" p line remaining s out last r drive root
+  local isabs winsep
+  local nl='
+'
+  [ -n "$input" ] || return 0
+  winsep="${HQ_LIB_WINSEP:-0}"
+
+  # Preserve the prior record-by-record behavior for embedded newlines while
+  # keeping this hot path entirely within bash.
+  while :; do
+    case "$input" in
+      *"$nl"*)
+        line=${input%%"$nl"*}
+        input=${input#*"$nl"}
+        ;;
+      *)
+        line=$input
+        input=""
+        ;;
+    esac
+
+    p=$line
+    if [ "$winsep" = "1" ]; then
+      p=${p//\\//}
+    fi
+    isabs=0
+    drive=""
+    case "$p" in
+      /*) isabs=1 ;;
+    esac
+    case "$p" in
+      [A-Za-z]:*)
+        drive=${p:0:2}
+        p=${p:2}
+        case "$p" in
+          /*) isabs=1 ;;
+          *) isabs=0 ;;
+        esac
+        ;;
+    esac
+    root=""
+    if [ "$isabs" = "1" ]; then
+      if [ "$winsep" = "1" ]; then
+        case "$p" in
+          //|//[!/]*) root="//" ;;
+          *) root="/" ;;
+        esac
+      else
+        root="/"
+      fi
+    fi
+
+    out=""
+    remaining=$p
+    while :; do
+      case "$remaining" in
+        */*)
+          s=${remaining%%/*}
+          remaining=${remaining#*/}
+          ;;
+        *)
+          s=$remaining
+          remaining=""
+          ;;
+      esac
+      case "$s" in
+        ''|.) ;;
+        ..)
+          if [ -n "$out" ]; then
+            last=${out##*/}
+          else
+            last=""
+          fi
+          if [ -n "$out" ] && [ "$last" != ".." ]; then
+            case "$out" in
+              */*) out=${out%/*} ;;
+              *) out="" ;;
+            esac
+          elif [ "$isabs" != "1" ]; then
+            if [ -n "$out" ]; then
+              out="$out/.."
+            else
+              out=".."
+            fi
+          fi
+          ;;
+        *)
+          if [ -n "$out" ]; then
+            out="$out/$s"
+          else
+            out=$s
+          fi
+          ;;
+      esac
+      [ -n "$remaining" ] || break
+    done
+
+    r=$out
+    if [ "$isabs" = "1" ]; then
+      r="$root$r"
+    fi
+    if [ -n "$drive" ]; then
+      r="$drive$r"
+    fi
+    if [ -z "$r" ]; then
+      if [ "$isabs" = "1" ]; then
+        r=$root
+      else
+        r="."
+      fi
+    fi
+    printf '%s\n' "$r"
+    [ -n "$input" ] || break
+  done
+}
+
+# hq_realpath_lenient <path>
+#   Symlink-resolved path that tolerates a leaf which does not exist yet, and
+#   an arbitrarily deep tail of missing parents. Mirrors the semantics the repo
+#   guard previously got from `python3 os.path.realpath(dirname(p))` + join
+#   leaf: the PARENT chain is symlink-resolved, the leaf is kept verbatim.
+#
+#   Implementation is `cd -P` + POSIX shell only. `readlink -f` is deliberately
+#   NOT used: macOS ships BSD readlink, which has no -f. python3 is deliberately
+#   NOT used: it is absent on many Windows machines, and there the Store alias
+#   stub resolves on PATH while failing every call, so a `command -v python3`
+#   guard around it silently disables whatever the resolution was protecting.
+#
+#   ORDER IS LOAD-BEARING. The existing part of the path is handed to `cd -P`
+#   with its `..` segments INTACT, because `..` must be applied by the OS after
+#   symlinks are resolved, not collapsed lexically first. Given
+#   workspace/link -> repos/private/app/dir, the path
+#   workspace/link/../secret.txt really means repos/private/app/secret.txt;
+#   normalizing first yields workspace/secret.txt, which escapes a repos/ prefix
+#   check entirely. For the same reason `cd` must be `cd -P` — bash's default
+#   logical `cd` collapses link/.. to the link's parent, reintroducing the bug.
+#   Only the not-yet-existing tail is normalized lexically, since there is no
+#   filesystem there to consult (this is what python's realpath does too).
+hq_realpath_lenient() {
+  local p="$1" leaf parent head tail resolved
+  [ -n "$p" ] || { printf '%s' "$p"; return 0; }
+  # Separator folding ONLY where "\" is actually a separator; NO `..` collapsing
+  # here — see above. On POSIX a backslash is part of the filename and folding it
+  # would make this resolve a path the write will never touch.
+  if [ "${HQ_LIB_WINSEP:-0}" = "1" ]; then
+    case "$p" in
+      *\\*) p="$(printf '%s' "$p" | tr '\\' '/')" ;;
+    esac
+  fi
+  case "$p" in
+    */*) leaf="${p##*/}"; parent="${p%/*}"; [ -n "$parent" ] || parent="/" ;;
+    *)   leaf="$p"; parent="." ;;
+  esac
+  # Walk up to the deepest ancestor that actually exists; remember the rest.
+  # `[ -d ]` follows symlinks, so a head ending in `link/..` tests the real dir.
+  head="$parent"; tail=""
+  while [ "$head" != "/" ] && [ "$head" != "." ] && [ ! -d "$head" ]; do
+    tail="${head##*/}${tail:+/}${tail}"
+    case "$head" in
+      */*) head="${head%/*}"; [ -n "$head" ] || head="/" ;;
+      *)   head="." ;;
+    esac
+  done
+  resolved="$(cd -P "$head" 2>/dev/null && pwd -P)" || resolved="$(hq_normpath "$head")"
+  [ -n "$tail" ] && resolved="${resolved%/}/$tail"
+  hq_normpath "${resolved%/}/$leaf"
+}
+
+# hq_realpath_dir <dir>
+#   FULL symlink resolution for a directory that exists, including its own leaf;
+#   echoes the input unchanged if it is not a directory.
+#
+#   Use this for the ROOT side of a prefix comparison. hq_realpath_lenient
+#   deliberately leaves the leaf alone, which is right for a write target but
+#   wrong for a root: when HQ itself is reached through a symlink (/home/me/hq
+#   -> /mnt/data/hq), a leaf-preserving root stays "/home/me/hq" while every
+#   fully-resolved file path under it reads "/mnt/data/hq/...", so the prefix
+#   test silently never matches and the guard passes everything.
+#   `cd -P`, not plain `cd`, for the same reason as hq_realpath_lenient — and it
+#   matters MORE here, because the two sides of the prefix test must agree. With
+#   link -> real/other and both real/hq and hq existing, a logical `cd` on
+#   link/../hq lands on hq while the file side resolves to real/hq/..., the
+#   prefix comparison misses, and the guard exits 0.
+#   The result is passed through hq_normpath for the same reason: BOTH operands
+#   of a prefix comparison must go through the identical normalizer, or a form
+#   one side preserves and the other rewrites (a leading "//", a trailing "/")
+#   silently breaks the match. Do not "simplify" this by returning pwd -P raw.
+hq_realpath_dir() {
+  local d="$1" p
+  [ -d "$d" ] || { hq_normpath "$d"; return 0; }
+  p="$(cd -P "$d" 2>/dev/null && pwd -P)" || p="$d"
+  hq_normpath "$p"
 }
 
 # hq_shell_simple_commands <command>
@@ -129,8 +328,12 @@ hq_shell_simple_commands() {
       for (j in argv) delete argv[j]
       argc = 0
     }
-    {
-      text = $0 "\n"
+    { source = source $0 "\n" }
+    END {
+      # Parse the complete payload, not one physical input line at a time.
+      # A quoted `bash -c` program and a heredoc can span newlines; resetting
+      # quote state at each line silently discarded the command before it.
+      text = source
       n = length(text); quote = ""; escaped = 0; word = ""; argc = 0
       for (i = 1; i <= n; i++) {
         c = substr(text, i, 1)
@@ -155,7 +358,12 @@ hq_shell_simple_commands() {
         }
         if (c == ">" || c == "<") {
           push_word(); argv[++argc] = c
-          if (substr(text, i + 1, 1) == c) { argv[argc] = argv[argc] c; i++ }
+          # Keep the Bash noclobber-override redirection (>|) with its target.
+          # Treating the pipe byte as a command boundary would otherwise split
+          # `printf x >| target` into two harmless-looking records.
+          if (substr(text, i + 1, 1) == c || (c == ">" && substr(text, i + 1, 1) == "|")) {
+            argv[argc] = argv[argc] substr(text, i + 1, 1); i++
+          }
           continue
         }
         word = word c
@@ -174,14 +382,18 @@ hq_shell_command_executable() {
   local i=0
   while [ "$i" -lt "${#argv[@]}" ]; do
     token="${argv[$i]}"
+    if [[ "$token" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; then
+      i=$((i + 1)); continue
+    fi
     case "$token" in
-      [A-Za-z_][A-Za-z0-9_]*=*) i=$((i + 1)); continue ;;
       env)
         i=$((i + 1))
         while [ "$i" -lt "${#argv[@]}" ]; do
           token="${argv[$i]}"
+          if [[ "$token" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; then
+            i=$((i + 1)); continue
+          fi
           case "$token" in
-            [A-Za-z_][A-Za-z0-9_]*=*) i=$((i + 1)); continue ;;
             -*) i=$((i + 1)); continue ;;
           esac
           break
@@ -354,6 +566,34 @@ hq_path_matches_core_yaml_exclude() {
   return 1
 }
 
+# hq_strip_tokens_containing_literals <command> <literal>...
+#   Remove whitespace-delimited command tokens containing any literal needle,
+#   preserving separators. This stays in Bash so hook hot paths do not spawn a
+#   sed process per configured exclude entry.
+hq_strip_tokens_containing_literals() {
+  local input="$1" remaining token after_token separator consumed needle match
+  local whitespace_chars=$' \t\n\r'
+  shift
+  local -a needles=("$@")
+  local -a output_parts=()
+  remaining="$input"
+  while [ -n "$remaining" ]; do
+    token="${remaining%%[$whitespace_chars]*}"
+    after_token="${remaining:${#token}}"
+    separator="${after_token%%[!$whitespace_chars]*}"
+    match=no
+    for needle in "${needles[@]}"; do
+      [ -n "$needle" ] || continue
+      case "$token" in *"$needle"*) match=yes; break ;; esac
+    done
+    [ "$match" = yes ] || output_parts+=("$token")
+    output_parts+=("$separator")
+    consumed=$((${#token} + ${#separator}))
+    remaining="${remaining:$consumed}"
+  done
+  printf '%s' "${output_parts[@]}"
+}
+
 # hq_bash_strip_core_yaml_exclude_tokens <command> <hq_root> [<core_yaml>]
 #   Best-effort removal of command tokens that reference rules.exclude paths.
 #   Match full root-relative (and absolute) exclude paths — never basename
@@ -363,35 +603,44 @@ hq_bash_strip_core_yaml_exclude_tokens() {
   local cmd="$1"
   local hq_root="$2"
   local core_yaml="${3:-$hq_root/core/core.yaml}"
-  local exc_path rel abs esc esc_dir sed_script exclude_paths
+  local exc_path rel abs exclude_paths stripped abs_paths_text normalized_abs_paths
+  local -a exclude_needles=()
 
   [ -n "$cmd" ] || { printf '%s' "$cmd"; return 0; }
   [ -f "$core_yaml" ] || { printf '%s' "$cmd"; return 0; }
   command -v yq >/dev/null 2>&1 || { printf '%s' "$cmd"; return 0; }
 
   hq_root="$(hq_canonical_path "$hq_root")"
-  sed_script=''
   exclude_paths="$(yq eval '.rules.exclude[]' "$core_yaml" 2>/dev/null)" || exclude_paths=""
+  abs_paths_text=""
   while IFS= read -r exc_path; do
     [ -n "$exc_path" ] || continue
     rel="${exc_path%/}"
     [ -n "$rel" ] || continue
-
-    esc="$(printf '%s' "$rel" | sed 's/[][\\.*^$(){}?+|/]/\\&/g')"
-    sed_script="${sed_script}s|[^[:space:]]*${esc}[^[:space:]]*||g; s|${esc}||g;"
-
+    exclude_needles+=("$rel")
     if [[ "$exc_path" == */ ]]; then
-      esc_dir="$(printf '%s' "$exc_path" | sed 's/[][\\.*^$(){}?+|/]/\\&/g')"
-      sed_script="${sed_script}s|[^[:space:]]*${esc_dir}[^[:space:]]*||g; s|${esc_dir}||g;"
+      exclude_needles+=("$exc_path")
     fi
-
-    abs="$(hq_canonical_path "${hq_root}/${rel}")"
-    esc_abs="$(printf '%s' "$abs" | sed 's/[][\\.*^$(){}?+|/]/\\&/g')"
-    sed_script="${sed_script}s|[^[:space:]]*${esc_abs}[^[:space:]]*||g; s|${esc_abs}||g;"
+    # hq_root is already in canonical slash form. Normalize all absolute
+    # exclude paths in one Bash pass below instead of launching one command
+    # substitution (and, on MSYS, cygpath process) per entry.
+    abs_paths_text+="${hq_root%/}/${rel}"$'\n'
   done <<< "$exclude_paths"
 
-  [ -n "$sed_script" ] || { printf '%s' "$cmd"; return 0; }
-  printf '%s' "$cmd" | sed "$sed_script"
+  [ "${#exclude_needles[@]}" -gt 0 ] || { printf '%s' "$cmd"; return 0; }
+  normalized_abs_paths="$(hq_normpath "$abs_paths_text")" || normalized_abs_paths=""
+  while IFS= read -r abs; do
+    [ -n "$abs" ] && exclude_needles+=("$abs")
+  done <<< "$normalized_abs_paths"
+  stripped="$(hq_strip_tokens_containing_literals "$cmd" "${exclude_needles[@]}")" || stripped=""
+  # Never fail open. An empty helper result would make block-core-writes-bash
+  # treat the command as touching no protected paths and allow the write.
+  # Hand the original command back so the caller still sees the real targets.
+  if [ -z "$stripped" ]; then
+    printf '%s' "$cmd"
+    return 0
+  fi
+  printf '%s' "$stripped"
 }
 
 
@@ -434,6 +683,36 @@ hq_path_label() {
   esac
 }
 
+# Git Bash/MSYS chmod rewrites NTFS ACLs with DENY ACEs. That can make the
+# owner unable to read a file whose POSIX mode still looks like -rw-r--r--.
+# Never chmod HQ files on Windows; launch with bash instead.
+hq_windows_native_path() {
+  local p="${1:-}"
+  [ -n "$p" ] || return 1
+  if command -v cygpath >/dev/null 2>&1; then
+    cygpath -w "$p" 2>/dev/null || printf '%s' "$p"
+    return 0
+  fi
+  printf '%s' "$p"
+}
+
+hq_repair_windows_acl() {
+  local path="${1:-}" native user
+  [ -n "$path" ] || return 1
+  [ -e "$path" ] || return 1
+  [ -r "$path" ] && return 0
+  [ "${HQ_LIB_WINSEP:-0}" = 1 ] || return 1
+  command -v icacls >/dev/null 2>&1 || return 1
+  native="$(hq_windows_native_path "$path")" || return 1
+  user="${USERNAME:-${USER:-}}"
+  icacls "$native" /reset >/dev/null 2>&1 || true
+  if [ -n "$user" ]; then
+    icacls "$native" /remove:d "$user" >/dev/null 2>&1 || true
+    icacls "$native" /grant:r "${user}:(RX)" >/dev/null 2>&1 || true
+  fi
+  [ -r "$path" ]
+}
+
 hq_hook_repair_command() {
   local root="$1"
   local path="$2"
@@ -443,6 +722,10 @@ hq_hook_repair_command() {
   fi
   rel="$(hq_path_label "$root" "$path")"
   [ -n "$rel" ] || return 0
+  if [ "${HQ_LIB_WINSEP:-0}" = 1 ]; then
+    printf 'icacls "$(cygpath -w "$HQ_ROOT/%s")" /grant:r "%%USERNAME%%:(RX)"' "$rel"
+    return 0
+  fi
   printf 'chmod u+x "$HQ_ROOT/%s"' "$rel"
 }
 
@@ -520,13 +803,24 @@ hq_launch_shell_path() {
     return 127
   fi
 
-  if [ ! -x "$path" ] && hq_path_within_root "$root" "$path"; then
+  if [ ! -r "$path" ] && hq_path_within_root "$root" "$path"; then
+    hq_repair_windows_acl "$path" || true
+  fi
+
+  # chmod on Git Bash writes NTFS DENY ACEs; skip it on Windows.
+  if [ ! -x "$path" ] && hq_path_within_root "$root" "$path" \
+    && [ "${HQ_LIB_WINSEP:-0}" != 1 ]; then
     chmod u+x "$path" 2>/dev/null || true
   fi
 
   if [ -x "$path" ]; then
     printf '%s' "$payload" | "$path" "$@"
-    HQ_HOOK_LAST_STATUS=$?
+    # PIPESTATUS[1], never $?. A hook that exits before reading stdin (the
+    # `[ -n "${HQ_CONDUCT_RUN_DIR:-}" ] || exit 0` guard shape) closes the read
+    # end while printf is still writing, so printf dies with SIGPIPE. Under the
+    # `pipefail` that every HQ dispatcher sets, $? is then 141 and a hook that
+    # exited 0 is reported as having failed. Read the hook's own element.
+    HQ_HOOK_LAST_STATUS=${PIPESTATUS[1]}
     return "$HQ_HOOK_LAST_STATUS"
   fi
 
@@ -536,13 +830,14 @@ hq_launch_shell_path() {
   fi
   if [ -r "$path" ] && [ -n "$bash_bin" ]; then
     printf '%s' "$payload" | "$bash_bin" "$path" "$@"
-    HQ_HOOK_LAST_STATUS=$?
+    # Same contract as the exec path above: the hook's status, not the writer's.
+    HQ_HOOK_LAST_STATUS=${PIPESTATUS[1]}
     return "$HQ_HOOK_LAST_STATUS"
   fi
 
   if [ ! -r "$path" ]; then
     if hq_path_within_root "$root" "$path"; then
-      HQ_HOOK_LAST_CAUSE="chmod u+x could not repair the file and bash could not read it"
+      HQ_HOOK_LAST_CAUSE="the file is not readable (on Windows, NTFS DENY ACEs can hide it while ls still shows -rw-r--r--)"
     else
       HQ_HOOK_LAST_CAUSE="file is not executable or readable"
     fi