@aldegad/safedeps 2.1.1 → 2.4.0

package/scripts/safedeps-pre-guard.sh

@@ -36,8 +36,26 @@ SAFEDEPS_MANIFEST_FILES=(
 umask 077
 mkdir -p "${GUARD_DIR}" "${SNAPSHOT_DIR}"
 
+# Observable record of any gate bypass / unavailability (AGENTS.md: no silent fallback —
+# every bypass must be observable and logged).
+log_advisory() {
+  printf '%s\t%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$1" >> "${GUARD_DIR}/advisory.log" 2>/dev/null || true
+}
+
 if ! command -v jq >/dev/null 2>&1; then
-  echo "safedeps: jq is not installed; skipping guard hook." >&2
+  # jq is required to parse the hook payload. Without it we cannot read the exact
+  # command, so do a best-effort fail-closed: read the raw payload and, if it
+  # looks like a dependency install, DENY (an install we cannot verify must not
+  # proceed). Non-install commands are allowed — jq absence must not block `ls`.
+  # Either branch is recorded in advisory.log; never a silent skip.
+  raw_input=$(cat)
+  log_advisory "pre-guard: jq missing — gate cannot parse the payload."
+  if printf '%s' "${raw_input}" | grep -qiE '(npm|pnpm|yarn|bun)([^"]*)(install|add|dlx)|[^a-z]npx[[:space:]]|pip[0-9]*[[:space:]]+install|poetry[[:space:]]+add|uv[[:space:]]+(add|pip[[:space:]]+install)|pipenv[[:space:]]+install|cargo[[:space:]]+(add|install)|go[[:space:]]+(get|install)|gem[[:space:]]+install|bundle[[:space:]]+add|mvn([^"]*)dependency:get|dotnet[[:space:]]+add[[:space:]]+package'; then
+    log_advisory "pre-guard DENY: jq missing on a likely dependency-install command — fail-closed."
+    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"safedeps: jq is required to gate dependency installs and is not installed — install blocked fail-closed. Install jq, then retry."}}\n'
+    exit 0
+  fi
+  echo "safedeps: jq is not installed — install gate disabled (non-install commands still allowed); logged to advisory.log." >&2
   exit 0
 fi
 
@@ -48,8 +66,10 @@ acquire_state_lock() {
     # Detect stale locks left by SIGKILL/OOM (V-005)
     if [[ -d "${STATE_LOCK_DIR}" ]]; then
       local lock_mtime=""
-      if lock_mtime=$(stat -f %m "${STATE_LOCK_DIR}" 2>/dev/null) || \
-         lock_mtime=$(stat -c %Y "${STATE_LOCK_DIR}" 2>/dev/null); then
+      # GNU (`-c %Y`, Linux) first, then BSD/macOS (`-f %m`): on Linux `stat -f`
+      # means --file-system and would not yield an mtime.
+      if lock_mtime=$(stat -c %Y "${STATE_LOCK_DIR}" 2>/dev/null) || \
+         lock_mtime=$(stat -f %m "${STATE_LOCK_DIR}" 2>/dev/null); then
         local now
         now=$(date +%s)
         if [[ $(( now - lock_mtime )) -gt 60 ]]; then
@@ -61,8 +81,11 @@ acquire_state_lock() {
     fi
 
     attempts=$((attempts + 1))
-    if [[ ${attempts} -ge 100 ]]; then
-      echo "safedeps: could not acquire state lock; skipping guard hook." >&2
+    if [[ ${attempts} -ge ${SAFEDEPS_LOCK_MAX_ATTEMPTS:-100} ]]; then
+      # acquire_state_lock is only reached for install candidates, so failing to
+      # serialize/snapshot means this install cannot be gated — fail CLOSED (deny).
+      log_advisory "pre-guard DENY: state lock unavailable for an install command — fail-closed."
+      jq -nc '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:"safedeps: could not acquire the state lock (another safedeps run may be active). Install blocked fail-closed — retry in a moment."}}'
       exit 0
     fi
     sleep 0.1
@@ -76,10 +99,16 @@ release_state_lock() {
 write_state_file() {
   local target_path="$1"
   local value="$2"
-  local temp_path="${target_path}.$$"
-
+  local target_dir
+  local target_base
+  local temp_path
+
+  target_dir=$(dirname "${target_path}")
+  target_base=$(basename "${target_path}")
+  mkdir -p "${target_dir}" || return 1
+  temp_path=$(mktemp "${target_dir}/.${target_base}.XXXXXX") || return 1
   printf '%s\n' "${value}" > "${temp_path}"
-  mv "${temp_path}" "${target_path}"
+  mv -f "${temp_path}" "${target_path}"
 }
 
 compute_dir_hash() {
@@ -99,10 +128,13 @@ command_is_dependency_install() {
   local scan_command
   local install_pattern
 
-  scan_command=$(command_scan_text "${command}")
-  install_pattern='(^|[;&|]+[[:space:]]*)((npm[[:space:]]+(install|i|add|update|up|upgrade))|npx[[:space:]]|pnpm[[:space:]]+(add|install|update|up|dlx)|yarn[[:space:]]+(add|install|upgrade|dlx)|((python3?|py)[[:space:]]+-m[[:space:]]+pip|pip3?)[[:space:]]+install|poetry[[:space:]]+add|uv[[:space:]]+(add|pip[[:space:]]+install)|pipenv[[:space:]]+install|cargo[[:space:]]+(add|install)|go[[:space:]]+(get|install)|gem[[:space:]]+install|bundle[[:space:]]+add|mvn[[:space:]]+dependency:get|dotnet[[:space:]]+add[[:space:]]+package)([[:space:]]|$)'
+  install_pattern='(^|[;&|]+[[:space:]]*)((npm([[:space:]]+--?[a-zA-Z0-9_-]+([=[:space:]][^[:space:]]+)?)?[[:space:]]+(install|i|add|ci|update|up|upgrade))|npx[[:space:]]|pnpm([[:space:]]+--?[a-zA-Z0-9_-]+([=[:space:]][^[:space:]]+)?)?[[:space:]]+(add|install|update|up|dlx)|yarn([[:space:]]+--?[a-zA-Z0-9_-]+([=[:space:]][^[:space:]]+)?)?[[:space:]]+(add|install|upgrade|dlx)|((python3?|py)[[:space:]]+-m[[:space:]]+pip|pip3?)[[:space:]]+install|poetry[[:space:]]+add|uv[[:space:]]+(add|pip[[:space:]]+install)|pipenv[[:space:]]+install|cargo[[:space:]]+(add|install)|go[[:space:]]+(get|install)|gem[[:space:]]+install|bundle[[:space:]]+add|mvn[[:space:]]+dependency:get|dotnet[[:space:]]+add[[:space:]]+package)([[:space:]]|$)'
 
-  echo "${scan_command}" | grep -qEi "${install_pattern}"
+  while IFS= read -r scan_command; do
+    scan_command=$(command_scan_text "${scan_command}")
+    echo "${scan_command}" | grep -qEi "${install_pattern}" && return 0
+  done < <(command_candidate_texts "${command}")
+  return 1
 }
 
 command_hides_dependency_install() {
@@ -113,7 +145,7 @@ command_hides_dependency_install() {
   manager_pattern='(npm|npx|pnpm|yarn|pip3?|python3?[[:space:]]+-m[[:space:]]+pip|poetry|uv|pipenv|cargo|go|gem|bundle|mvn|dotnet)'
   verb_pattern='(install|i|add|update|up|upgrade|dlx|get|dependency:get|package)'
 
-  echo "${command}" | grep -qEi '(eval[[:space:]]|\$\(|`)' && \
+  echo "${command}" | grep -qEi '(eval[[:space:]]|\$\(|`|(^|[[:space:];|&])(bash|sh|zsh)[[:space:]]+-[A-Za-z]*c[[:space:]])' && \
     echo "${command}" | grep -qEi "${manager_pattern}.*${verb_pattern}"
 }
 
@@ -154,6 +186,93 @@ command_scan_text() {
   printf '%s' "${output}"
 }
 
+normalize_install_text() {
+  local text="$1"
+
+  for _ in 1 2 3; do
+    text=$(printf '%s' "${text}" | sed -E \
+      -e 's#(^|[[:space:];|&])(/[^[:space:];|&]+/)(npm|npx|pnpm|yarn|pip3?|python3?|py|poetry|uv|pipenv|cargo|go|gem|bundle|mvn|dotnet)([[:space:];|&]|$)#\1\3\4#g' \
+      -e 's#(^|[;&|][[:space:]]*)(env[[:space:]]+([A-Za-z_][A-Za-z0-9_]*=[^[:space:]]+[[:space:]]+)*|command[[:space:]]+)#\1#g')
+  done
+  printf '%s' "${text}"
+}
+
+strip_heredoc_bodies() {
+  local input="$1"
+  local line
+  local delimiter=""
+  local heredoc_re="<<-?[[:space:]]*[\"']?([A-Za-z0-9_][A-Za-z0-9_.-]*)[\"']?"
+
+  while IFS= read -r line || [[ -n "${line}" ]]; do
+    if [[ -n "${delimiter}" ]]; then
+      if [[ "${line}" == "${delimiter}" ]]; then
+        delimiter=""
+      fi
+      continue
+    fi
+
+    if [[ "${line}" =~ ${heredoc_re} ]]; then
+      delimiter="${BASH_REMATCH[1]}"
+    fi
+    printf '%s\n' "${line}"
+  done <<< "${input}"
+}
+
+extract_shell_c_payloads() {
+  local rest="$1"
+
+  while [[ "${rest}" =~ (bash|sh|zsh)[[:space:]]+-[A-Za-z]*c[[:space:]]+\"([^\"]*)\" ]]; do
+    printf '%s\n' "${BASH_REMATCH[2]}"
+    rest="${rest#*"${BASH_REMATCH[0]}"}"
+  done
+
+  rest="$1"
+  while [[ "${rest}" =~ (bash|sh|zsh)[[:space:]]+-[A-Za-z]*c[[:space:]]+\'([^\']*)\' ]]; do
+    printf '%s\n' "${BASH_REMATCH[2]}"
+    rest="${rest#*"${BASH_REMATCH[0]}"}"
+  done
+}
+
+command_candidate_texts() {
+  local command="$1"
+  local payload
+
+  command=$(strip_heredoc_bodies "${command}")
+
+  normalize_install_text "${command}"
+  printf '\n'
+  while IFS= read -r payload; do
+    [[ -z "${payload}" ]] && continue
+    normalize_install_text "${payload}"
+    printf '\n'
+  done < <(extract_shell_c_payloads "${command}")
+}
+
+command_is_injectable_npm_install() {
+  local command="$1"
+  local scan_command
+  local npm_install_pattern
+
+  npm_install_pattern='(^|[;&|]+[[:space:]]*)npm([[:space:]]+--?[a-zA-Z0-9_-]+([=[:space:]][^[:space:]]+)?)?[[:space:]]+(install|i|add|ci|update|up|upgrade)([[:space:]]|$)'
+
+  while IFS= read -r scan_command; do
+    scan_command=$(command_scan_text "${scan_command}")
+    echo "${scan_command}" | grep -qEi "${npm_install_pattern}" && return 0
+  done < <(command_candidate_texts "${command}")
+  return 1
+}
+
+command_has_ignore_scripts_flag() {
+  local command="$1"
+  local scan_command
+
+  while IFS= read -r scan_command; do
+    scan_command=$(command_scan_text "${scan_command}")
+    echo "${scan_command}" | grep -qEi -- '(^|[[:space:]])--ignore-scripts([=[:space:]]|$)' && return 0
+  done < <(command_candidate_texts "${command}")
+  return 1
+}
+
 snapshot_project_file() {
   local relative_file="$1"
   local category="${2:-manifest}"
@@ -275,10 +394,24 @@ cat > "${SNAPSHOT_DIR}/${SNAPSHOT_ID}_meta.json" << META_EOF
   "timestamp": ${TIMESTAMP},
   "project_dir": $(printf '%s' "${PROJECT_DIR}" | jq -Rs .),
   "command": $(printf '%s' "${COMMAND}" | jq -Rs .),
+  "ignore_scripts_injected": false,
   "lock_files_found": ${SNAPSHOTTED}
 }
 META_EOF
 
+mark_ignore_scripts_injected() {
+  local meta_file="${SNAPSHOT_DIR}/${SNAPSHOT_ID}_meta.json"
+  local temp_file
+
+  [[ -f "${meta_file}" ]] || return 0
+  temp_file=$(mktemp "${SNAPSHOT_DIR}/.${SNAPSHOT_ID}_meta.XXXXXX") || return 0
+  if jq '.ignore_scripts_injected = true' "${meta_file}" > "${temp_file}"; then
+    mv -f "${temp_file}" "${meta_file}"
+  else
+    rm -f "${temp_file}"
+  fi
+}
+
 # --- Pre-flight security checks on the command itself ---
 
 SUSPICIOUS=false
@@ -320,46 +453,147 @@ fi
 
 # --- Phase 2 advisory gate — ledger enforcement -------------------------------
 # For commands that name specific packages, require an entry in the approved-
-# spec ledger. Miss/expired → block with a structured message that names the
-# exact `safedeps check` command the caller (agent or human) should run next.
+# spec ledger. Miss/expired → block with a structured message that names a
+# runnable `safedeps check` command the caller (agent or human) should run
+# next — PATH command when present, else an absolute path, so the self-heal
+# loop never dead-ends on a missing PATH symlink.
 #
 # Conservative: only block when at least one pkg@spec token is parseable. Bare
 # `npm install` (lockfile install) falls through to the v1 reorg checks.
 
-SAFEDEPS_LEDGER_LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/lib/ledger/ledger.sh"
+SAFEDEPS_LEDGER_LIB="${SAFEDEPS_LEDGER_LIB:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/lib/ledger/ledger.sh}"
 SAFEDEPS_REPO_BIN="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/bin/safedeps"
 
 guard_detect_ecosystem() {
   local cmd="$1"
   local scan_cmd
 
-  scan_cmd=$(command_scan_text "${cmd}")
-  if echo "${scan_cmd}" | grep -qEi '(^|[;&|]+[[:space:]]*)(npm|pnpm|yarn|npx)([[:space:]]|$)'; then
-    printf 'npm'
-  elif echo "${scan_cmd}" | grep -qEi '(^|[;&|]+[[:space:]]*)(pip3?|poetry|uv|pipenv|((python3?|py)[[:space:]]+-m[[:space:]]+pip))([[:space:]]|$)'; then
-    printf 'pypi'
-  elif echo "${scan_cmd}" | grep -qEi '(^|[;&|]+[[:space:]]*)cargo([[:space:]]|$)'; then
-    printf 'crates.io'
-  elif echo "${scan_cmd}" | grep -qEi '(^|[;&|]+[[:space:]]*)go([[:space:]]|$)'; then
-    printf 'go'
-  elif echo "${scan_cmd}" | grep -qEi '(^|[;&|]+[[:space:]]*)(gem|bundle)([[:space:]]|$)'; then
-    printf 'rubygems'
-  elif echo "${scan_cmd}" | grep -qEi '(^|[;&|]+[[:space:]]*)mvn([[:space:]]|$)'; then
-    printf 'maven'
-  elif echo "${scan_cmd}" | grep -qEi '(^|[;&|]+[[:space:]]*)dotnet([[:space:]]|$)'; then
-    printf 'nuget'
-  else
-    printf ''
-  fi
+  while IFS= read -r scan_cmd; do
+    scan_cmd=$(command_scan_text "${scan_cmd}")
+    if echo "${scan_cmd}" | grep -qEi '(^|[;&|]+[[:space:]]*)(npm|pnpm|yarn|npx)([[:space:]]|$)'; then
+      printf 'npm'
+      return 0
+    elif echo "${scan_cmd}" | grep -qEi '(^|[;&|]+[[:space:]]*)(pip3?|poetry|uv|pipenv|((python3?|py)[[:space:]]+-m[[:space:]]+pip))([[:space:]]|$)'; then
+      printf 'pypi'
+      return 0
+    elif echo "${scan_cmd}" | grep -qEi '(^|[;&|]+[[:space:]]*)cargo([[:space:]]|$)'; then
+      printf 'crates.io'
+      return 0
+    elif echo "${scan_cmd}" | grep -qEi '(^|[;&|]+[[:space:]]*)go([[:space:]]|$)'; then
+      printf 'go'
+      return 0
+    elif echo "${scan_cmd}" | grep -qEi '(^|[;&|]+[[:space:]]*)(gem|bundle)([[:space:]]|$)'; then
+      printf 'rubygems'
+      return 0
+    elif echo "${scan_cmd}" | grep -qEi '(^|[;&|]+[[:space:]]*)mvn([[:space:]]|$)'; then
+      printf 'maven'
+      return 0
+    elif echo "${scan_cmd}" | grep -qEi '(^|[;&|]+[[:space:]]*)dotnet([[:space:]]|$)'; then
+      printf 'nuget'
+      return 0
+    fi
+  done < <(command_candidate_texts "${cmd}")
+  printf ''
+}
+
+guard_runner_operands() {
+  # Runner forms (`npx`, `pnpm dlx`, `yarn dlx`) EXECUTE a package; tokens after
+  # the executed package are arguments to that program, NOT package specs. Emit
+  # only the spec-bearing operands: any `-p/--package <pkg>` value plus the first
+  # bare token (the executed package). This stops an argument such as an email
+  # (`dev1@block-s.io`) or a secret value passed to `npx wrangler ...` from being
+  # misread as a `pkg@spec` install.
+  local scan="$1"
+  local after want_value tok
+  after=$(printf '%s' "${scan}" | grep -oiE '(npx|dlx)[[:space:]].*' | head -n1 || true)
+  after="${after#* }"  # drop the runner keyword, keep its operands
+  [[ -z "${after}" ]] && return 0
+
+  want_value=false
+  for tok in ${after}; do
+    if [[ "${want_value}" == true ]]; then
+      printf '%s\n' "${tok}"
+      want_value=false
+      continue
+    fi
+    case "${tok}" in
+      -p|--package) want_value=true ;;
+      --package=*)  printf '%s\n' "${tok#--package=}" ;;
+      -*)           : ;;  # other flag (e.g. -y/--yes), skip
+      *)
+        printf '%s\n' "${tok}"  # executed package; rest are program args
+        break
+        ;;
+    esac
+  done
+}
+
+guard_extract_flagged_specs() {
+  awk '
+    {
+      for (i = 1; i <= NF; i++) {
+        if ($i ~ /^[A-Za-z][A-Za-z0-9._-]*==[A-Za-z0-9][A-Za-z0-9._+!~-]*$/) {
+          split($i, parts, "==")
+          print parts[1] "\t" parts[2]
+        }
+
+        if ($i == "gem" && $(i + 1) == "install") {
+          pkg = $(i + 2)
+          for (j = i + 3; j <= NF; j++) {
+            if (($j == "-v" || $j == "--version") && $(j + 1) != "") print pkg "\t" $(j + 1)
+            if ($j ~ /^--version=/) { sub(/^--version=/, "", $j); print pkg "\t" $j }
+          }
+        }
+
+        if ($i == "cargo" && $(i + 1) == "add") {
+          pkg = $(i + 2)
+          for (j = i + 3; j <= NF; j++) {
+            if (($j == "--vers" || $j == "--version") && $(j + 1) != "") print pkg "\t" $(j + 1)
+            if ($j ~ /^--(vers|version)=/) { sub(/^--(vers|version)=/, "", $j); print pkg "\t" $j }
+          }
+        }
+
+        if ($i == "dotnet" && $(i + 1) == "add" && $(i + 2) == "package") {
+          pkg = $(i + 3)
+          for (j = i + 4; j <= NF; j++) {
+            if ($j == "--version" && $(j + 1) != "") print pkg "\t" $(j + 1)
+            if ($j ~ /^--version=/) { sub(/^--version=/, "", $j); print pkg "\t" $j }
+          }
+        }
+      }
+    }
+  '
 }
 
 guard_extract_specs() {
-  # Echo one "pkg<TAB>spec" line per pkg@spec token found in the command.
-  # Captures @scope/name@spec and bare-name@spec forms.
+  # Echo one "pkg<TAB>spec" line per pkg@spec OPERAND genuinely being installed.
+  # Handles @scope/name@spec and bare-name@spec. Two precision rules keep
+  # non-package "@" tokens from being misread as an install:
+  #   1. Runner segments (npx / pnpm dlx / yarn dlx) contribute ONLY their
+  #      executed package — trailing tokens are program arguments, not specs
+  #      (so `npx wrangler ... dev1@block-s.io` is never read as a spec).
+  #   2. Email / host operands (user@domain.tld) are never package specs.
+  # Each shell segment is judged independently so a genuine install in one
+  # segment is still gated even when another segment just runs a tool via npx.
   local cmd="$1"
-  echo "${cmd}" \
-    | grep -oE '(@[a-zA-Z0-9._/-]+/)?[a-zA-Z][a-zA-Z0-9._-]*@[a-zA-Z0-9._^~|<>=*+-]+' \
+  local seg source=""
+
+  while IFS= read -r seg; do
+    [[ -z "${seg//[[:space:]]/}" ]] && continue
+    if printf '%s' "${seg}" | grep -qEi '(^|[[:space:]])(npx|dlx)([[:space:]]|$)'; then
+      source+="$(guard_runner_operands "${seg}")"$'\n'
+    else
+      source+="${seg}"$'\n'
+    fi
+  done < <(command_candidate_texts "${cmd}" | tr ';|&' '\n')
+
+  { printf '%s' "${source}" \
+    | grep -oE '(@[a-zA-Z0-9._/-]+/)?[a-zA-Z][a-zA-Z0-9._-]*@[a-zA-Z0-9._^~|<>=*+-]+' || true; } \
     | while IFS= read -r token; do
+        # An email / host operand (user@domain.tld) is never a package spec.
+        if [[ "${token}" =~ ^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$ ]]; then
+          continue
+        fi
         local pkg spec
         if [[ "${token}" =~ ^(@[^@]+)@(.+)$ ]]; then
           pkg="${BASH_REMATCH[1]}"
@@ -370,19 +604,45 @@ guard_extract_specs() {
         fi
         printf '%s\t%s\n' "${pkg}" "${spec}"
       done
+  printf '%s\n' "${source}" | guard_extract_flagged_specs
 }
 
 LEDGER_ECOSYSTEM=$(guard_detect_ecosystem "${COMMAND}")
 LEDGER_SPECS=()
 while IFS= read -r ledger_spec_line; do
   [[ -z "${ledger_spec_line}" ]] && continue
+  if [[ ${#LEDGER_SPECS[@]} -gt 0 ]]; then
+    for existing_spec_line in "${LEDGER_SPECS[@]}"; do
+      [[ "${existing_spec_line}" == "${ledger_spec_line}" ]] && continue 2
+    done
+  fi
   LEDGER_SPECS+=("${ledger_spec_line}")
 done < <(guard_extract_specs "${COMMAND}")
 
-if [[ -n "${LEDGER_ECOSYSTEM}" && ${#LEDGER_SPECS[@]} -gt 0 && -f "${SAFEDEPS_LEDGER_LIB}" ]]; then
+if [[ -n "${LEDGER_ECOSYSTEM}" && ${#LEDGER_SPECS[@]} -gt 0 ]]; then
+  if [[ ! -f "${SAFEDEPS_LEDGER_LIB}" ]]; then
+    # The ledger library is the gate for direct install specs. If it is missing
+    # (broken install / moved repo) the gate cannot run — fail CLOSED, observably,
+    # instead of falling through to allow.
+    log_advisory "pre-guard DENY: ledger library missing (${SAFEDEPS_LEDGER_LIB}) — cannot enforce ${LEDGER_ECOSYSTEM} install, fail-closed."
+    jq -nc --arg eco "${LEDGER_ECOSYSTEM}" \
+      '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:("safedeps: the ledger library is missing, so the " + $eco + " install gate cannot run — install blocked fail-closed. Reinstall safedeps: node scripts/install/install-safedeps-hooks.mjs")}}'
+    exit 0
+  fi
   # shellcheck source=../lib/ledger/ledger.sh
   source "${SAFEDEPS_LEDGER_LIB}"
 
+  # Resolve a runnable `safedeps` invocation for the block message so the
+  # self-heal loop works whether or not the CLI is on PATH. Prefer the PATH
+  # command (clean UX); otherwise name the absolute repo bin (quoted via %q so
+  # it survives spaces in $HOME). Keeps the gate self-contained — the install
+  # of a `~/.local/bin/safedeps` symlink is a convenience, never a requirement.
+  if command -v safedeps >/dev/null 2>&1; then
+    SAFEDEPS_INVOKE="safedeps"
+  else
+    printf -v SAFEDEPS_INVOKE '%q' "${SAFEDEPS_REPO_BIN}"
+  fi
+
   GUARD_BLOCKED_CMDS=()
   for entry in "${LEDGER_SPECS[@]}"; do
     pkg="${entry%%$'\t'*}"
@@ -390,7 +650,7 @@ if [[ -n "${LEDGER_ECOSYSTEM}" && ${#LEDGER_SPECS[@]} -gt 0 && -f "${SAFEDEPS_LE
     [[ -z "${pkg}" || -z "${spec}" ]] && continue
     if ! safedeps_ledger_check "${LEDGER_ECOSYSTEM}" "${pkg}" "${spec}" 2>/dev/null \
         | jq -e '.approved == true' >/dev/null 2>&1; then
-      GUARD_BLOCKED_CMDS+=("safedeps check ${LEDGER_ECOSYSTEM} ${pkg}@${spec}")
+      GUARD_BLOCKED_CMDS+=("${SAFEDEPS_INVOKE} check ${LEDGER_ECOSYSTEM} ${pkg}@${spec}")
     fi
   done
 
@@ -423,5 +683,15 @@ CURRENT_STATE=$(jq -n --arg sid "${SNAPSHOT_ID}" --arg pdir "${PROJECT_DIR}" --a
   '{snapshot_id: $sid, project_dir: $pdir, dir_hash: $dhash}')
 write_state_file "${GUARD_DIR}/current_state" "${CURRENT_STATE}"
 
+if ! jq -e 'has("turn_id")' <<< "${INPUT}" >/dev/null 2>&1 && \
+   command_is_injectable_npm_install "${COMMAND}" && \
+   ! command_has_ignore_scripts_flag "${COMMAND}"; then
+  UPDATED_COMMAND="${COMMAND} --ignore-scripts"
+  mark_ignore_scripts_injected
+  jq -nc --arg command "${UPDATED_COMMAND}" \
+    '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"allow",updatedInput:{command:$command}}}'
+  exit 0
+fi
+
 # Allow the command to proceed — PostToolUse will verify the result
 exit 0