@aldegad/safedeps 2.2.0 → 2.4.0

package/lib/gates/doctor.sh

@@ -0,0 +1,212 @@
+#!/bin/bash
+set -euo pipefail
+
+# safedeps doctor — repo security posture check.
+#
+# Diagnoses whether the per-repo secret-leak lane is set up (.gitleaks policy +
+# .githooks/pre-commit + active core.hooksPath + an available scanner) and
+# reports the global dependency-install gate too. Read-only by default; `--fix`
+# scaffolds the missing pieces (hooks init) and activates them (hooks install).
+#
+# Exit codes: 0 = no gaps in the secret-leak lane, 1 = gaps remain.
+
+GATES_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./repo-profile.sh
+source "$GATES_LIB_DIR/repo-profile.sh"
+
+REPO_ROOT=""
+FIX=0
+JSON_MODE="${SAFEDEPS_JSON_MODE:-0}"
+
+usage() {
+  printf 'Usage: safedeps doctor [--root <repo>] [--fix] [--json]\n' >&2
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --root) REPO_ROOT="${2:?--root needs a path}"; shift 2 ;;
+    --fix) FIX=1; shift ;;
+    --json) JSON_MODE=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) usage; exit 64 ;;
+  esac
+done
+
+if [ -z "$REPO_ROOT" ]; then REPO_ROOT="$(pwd)"; fi
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
+
+# --- check collection ---------------------------------------------------------
+# Each check appends a row: <lane>\t<status>\t<label>\t<remedy>
+# status ∈ ok | gap | na
+CHECK_ROWS=()
+GAPS=0
+
+add_check() {
+  local lane="$1" status="$2" label="$3" remedy="${4:-}"
+  CHECK_ROWS+=("${lane}"$'\t'"${status}"$'\t'"${label}"$'\t'"${remedy}")
+  # The exit code reflects the per-repo secret-leak lane only. The global
+  # dependency-install gate is reported (✗) but is a per-machine concern, so it
+  # does not gate this repo's posture result.
+  if [ "$status" = "gap" ] && [ "$lane" = "secret" ]; then GAPS=$((GAPS + 1)); fi
+}
+
+scanner_available() {
+  if command -v gitleaks >/dev/null 2>&1; then printf 'gitleaks'; return 0; fi
+  if command -v docker >/dev/null 2>&1; then printf 'docker'; return 0; fi
+  return 1
+}
+
+dependency_gate_root() {
+  # The dependency-install gate is installed globally as a skill symlink for
+  # whichever engine(s) are present.
+  local found=""
+  [ -e "$HOME/.claude/skills/safedeps" ] && found="${found:+${found}, }~/.claude/skills/safedeps"
+  [ -e "$HOME/.codex/skills/safedeps" ] && found="${found:+${found}, }~/.codex/skills/safedeps"
+  printf '%s' "$found"
+}
+
+run_checks() {
+  CHECK_ROWS=()
+  GAPS=0
+
+  local is_git=0
+  if git -C "$REPO_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then is_git=1; fi
+
+  local profile="(n/a)"
+  if [ "$is_git" = 1 ]; then
+    add_check secret ok "git worktree"
+    profile="$(safedeps_repo_profile "$REPO_ROOT")"
+
+    local config_path config_label
+    config_path="$(safedeps_gitleaks_config "$REPO_ROOT" "$profile")"
+    config_label="gitleaks config ($(basename "$config_path"))"
+    if [ -f "$config_path" ]; then
+      add_check secret ok "$config_label"
+    else
+      add_check secret gap "$config_label" "safedeps hooks init --root \"$REPO_ROOT\""
+    fi
+
+    local hook_file="$REPO_ROOT/.githooks/pre-commit"
+    if [ -x "$hook_file" ]; then
+      add_check secret ok ".githooks/pre-commit (executable)"
+    elif [ -f "$hook_file" ]; then
+      add_check secret gap ".githooks/pre-commit (not executable)" "chmod +x \"$hook_file\""
+    else
+      add_check secret gap ".githooks/pre-commit (present)" "safedeps hooks init --root \"$REPO_ROOT\""
+    fi
+
+    local hooks_path
+    hooks_path="$(git -C "$REPO_ROOT" config --get core.hooksPath || true)"
+    if [ "$hooks_path" = ".githooks" ]; then
+      add_check secret ok "git hooks active (core.hooksPath=.githooks)"
+    else
+      add_check secret gap "git hooks active (core.hooksPath=${hooks_path:-<unset>})" "safedeps hooks install --root \"$REPO_ROOT\""
+    fi
+  else
+    add_check secret na "git worktree (secret lane needs git)"
+  fi
+
+  local scanner
+  if scanner="$(scanner_available)"; then
+    add_check secret ok "secret scanner available (${scanner})"
+  else
+    add_check secret gap "secret scanner available (gitleaks or docker)" "brew install gitleaks"
+  fi
+
+  local gate_root
+  gate_root="$(dependency_gate_root)"
+  if [ -n "$gate_root" ]; then
+    add_check deps ok "dependency-install gate installed (${gate_root})"
+  else
+    add_check deps gap "dependency-install gate installed" "node scripts/install/install-safedeps-hooks.mjs"
+  fi
+
+  DOCTOR_PROFILE="$profile"
+}
+
+emit_human() {
+  local sym
+  printf 'safedeps doctor — repo security posture\n'
+  printf 'repo:    %s\n' "$REPO_ROOT"
+  printf 'profile: %s\n\n' "$DOCTOR_PROFILE"
+
+  printf 'Secret-leak lane (per-repo)\n'
+  local row lane status label remedy
+  for row in "${CHECK_ROWS[@]}"; do
+    IFS=$'\t' read -r lane status label remedy <<< "$row"
+    [ "$lane" = "secret" ] || continue
+    case "$status" in
+      ok) sym='✓' ;;
+      gap) sym='✗' ;;
+      *) sym='–' ;;
+    esac
+    if [ "$status" = "gap" ] && [ -n "$remedy" ]; then
+      printf '  %s %-44s → %s\n' "$sym" "$label" "$remedy"
+    else
+      printf '  %s %s\n' "$sym" "$label"
+    fi
+  done
+
+  printf '\nDependency-install gate (global, all repos)\n'
+  for row in "${CHECK_ROWS[@]}"; do
+    IFS=$'\t' read -r lane status label remedy <<< "$row"
+    [ "$lane" = "deps" ] || continue
+    case "$status" in
+      ok) sym='✓' ;;
+      gap) sym='✗' ;;
+      *) sym='–' ;;
+    esac
+    if [ "$status" = "gap" ] && [ -n "$remedy" ]; then
+      printf '  %s %-44s → %s\n' "$sym" "$label" "$remedy"
+    else
+      printf '  %s %s\n' "$sym" "$label"
+    fi
+  done
+
+  printf '\n'
+  if [ "$GAPS" -eq 0 ]; then
+    printf 'No gaps in the secret-leak lane. The agent is on guard.\n'
+  else
+    printf '%d gap(s) in the secret-leak lane.\n' "$GAPS"
+    printf 'Fix all at once:  safedeps doctor --fix --root "%s"\n' "$REPO_ROOT"
+  fi
+}
+
+emit_json() {
+  local rows_json="[]" row lane status label remedy
+  for row in "${CHECK_ROWS[@]}"; do
+    IFS=$'\t' read -r lane status label remedy <<< "$row"
+    rows_json="$(jq -c \
+      --arg lane "$lane" --arg status "$status" --arg label "$label" --arg remedy "$remedy" \
+      '. + [{lane:$lane, status:$status, label:$label, remedy:($remedy|select(length>0))}]' \
+      <<< "$rows_json")"
+  done
+  jq -nc \
+    --arg repo "$REPO_ROOT" \
+    --arg profile "$DOCTOR_PROFILE" \
+    --argjson gaps "$GAPS" \
+    --argjson checks "$rows_json" \
+    '{command:"doctor", repo:$repo, profile:$profile, gaps:$gaps, ok:($gaps==0), checks:$checks}'
+}
+
+# --- fix pass -----------------------------------------------------------------
+if [ "$FIX" -eq 1 ]; then
+  if ! git -C "$REPO_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    printf 'ERROR: --fix needs a git worktree (the secret lane is git-scoped): %s\n' "$REPO_ROOT" >&2
+    exit 1
+  fi
+  [ "$JSON_MODE" -eq 1 ] || printf 'safedeps doctor --fix: scaffolding + activating the secret-leak lane...\n\n'
+  bash "$GATES_LIB_DIR/hooks.sh" init --root "$REPO_ROOT"
+  bash "$GATES_LIB_DIR/hooks.sh" install --root "$REPO_ROOT"
+  [ "$JSON_MODE" -eq 1 ] || printf '\n'
+fi
+
+run_checks
+
+if [ "$JSON_MODE" -eq 1 ]; then
+  emit_json
+else
+  emit_human
+fi
+
+[ "$GAPS" -eq 0 ]

package/lib/gates/hooks.sh

@@ -16,12 +16,12 @@ HOOKS_PATH=".githooks"
 AUTO=0
 
 usage() {
-  printf 'Usage: safedeps hooks <install|check> [--root <repo>] [--hooks-path <dir>] [--auto]\n' >&2
+  printf 'Usage: safedeps hooks <install|check|init> [--root <repo>] [--hooks-path <dir>] [--auto]\n' >&2
 }
 
 while [ $# -gt 0 ]; do
   case "$1" in
-    install|check) SUB="$1"; shift ;;
+    install|check|init) SUB="$1"; shift ;;
     --root) REPO_ROOT="${2:?--root needs a path}"; shift 2 ;;
     --hooks-path) HOOKS_PATH="${2:?--hooks-path needs a dir}"; shift 2 ;;
     --auto) AUTO=1; shift ;;
@@ -46,6 +46,44 @@ fi
 HOOK_FILE="$REPO_ROOT/$HOOKS_PATH/pre-commit"
 
 case "$SUB" in
+  init)
+    # Scaffold the repo's secret-leak policy from starter templates. Non-destructive:
+    # an existing file is reported and skipped, so repo-owned edits survive a re-run.
+    # `init` only drops files; `install` activates them (core.hooksPath).
+    TEMPLATES_DIR="$GATES_LIB_DIR/templates"
+    PROFILE="$(safedeps_repo_profile "$REPO_ROOT")"
+    created=0
+
+    scaffold() {
+      local dest="$1" tmpl="$2" mode="$3"
+      if [ -e "$dest" ]; then
+        printf 'safedeps hooks init: exists, skipped: %s\n' "$dest"
+        return 0
+      fi
+      if [ ! -f "$tmpl" ]; then
+        printf 'ERROR: template missing: %s\n' "$tmpl" >&2
+        exit 1
+      fi
+      mkdir -p "$(dirname "$dest")"
+      cp "$tmpl" "$dest"
+      chmod "$mode" "$dest"
+      printf 'safedeps hooks init: created %s\n' "$dest"
+      created=$((created + 1))
+    }
+
+    if [ "$PROFILE" = "private" ]; then
+      scaffold "$REPO_ROOT/.gitleaks.private.toml" "$TEMPLATES_DIR/gitleaks.private.toml.tmpl" 0644
+    else
+      scaffold "$REPO_ROOT/.gitleaks.toml" "$TEMPLATES_DIR/gitleaks.toml.tmpl" 0644
+    fi
+    scaffold "$REPO_ROOT/$HOOKS_PATH/pre-commit" "$TEMPLATES_DIR/pre-commit.tmpl" 0755
+
+    printf 'safedeps hooks init: profile=%s, %d file(s) created.\n' "$PROFILE" "$created"
+    if [ "$created" -gt 0 ]; then
+      printf '       Review the scaffolded .gitleaks policy, then activate:\n'
+      printf '         safedeps hooks install --root "%s"\n' "$REPO_ROOT"
+    fi
+    ;;
   install)
     if [ ! -f "$HOOK_FILE" ]; then
       printf 'ERROR: hook file not found: %s\n' "$HOOK_FILE" >&2

package/lib/gates/templates/gitleaks.private.toml.tmpl

@@ -0,0 +1,45 @@
+# .gitleaks.private.toml — safedeps starter secret-scan policy (PRIVATE profile).
+#
+# Resolved when the repo's origin slug or directory leaf ends in "-private",
+# or when SAFEDEPS_REPO_PROFILE=private. Use this for the stricter policy a
+# private repo wants on top of the public defaults.
+#
+# safedeps OWNS execution; THIS FILE is the repo's POLICY — you own it.
+# `safedeps hooks init` scaffolds this once and will NOT overwrite your edits.
+
+title = "safedeps secret-scan policy (private)"
+
+# Inherit gitleaks' built-in ruleset. To also layer the repo's public policy,
+# point `path` at it instead of (or in addition to) useDefault.
+[extend]
+useDefault = true
+# path = ".gitleaks.toml"
+
+# --- Extra rules layered on top of the defaults -------------------------------
+
+[[rules]]
+id = "safedeps-dotenv-file"
+description = "Committed .env file with an assigned secret value"
+path = '''(^|/)\.env(\.[\w.-]+)?$'''
+regex = '''(?i)(secret|token|password|passwd|api[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret)\s*[:=]\s*\S{6,}'''
+  [rules.allowlist]
+  paths = [
+    '''(^|/)\.env\.example$''',
+    '''(^|/)\.env\.sample$''',
+    '''(^|/)\.env\.template$''',
+  ]
+
+# Private repos often also flag internal identifiers (infra hosts, account ids).
+# Add your own, e.g.:
+# [[rules]]
+# id = "safedeps-internal-host"
+# description = "Internal hostname / infra endpoint"
+# regex = '''(?i)\b[\w.-]+\.internal\.example\.com\b'''
+
+# --- Repo-owned allowlist — CUSTOMIZE FOR THIS REPO ---------------------------
+[allowlist]
+description = "Repo-specific allowlist (tune me)"
+paths = [
+  '''(^|/)\.gitleaks\.toml$''',
+  '''(^|/)\.gitleaks\.private\.toml$''',
+]

package/lib/gates/templates/gitleaks.toml.tmpl

@@ -0,0 +1,43 @@
+# .gitleaks.toml — safedeps starter secret-scan policy (public repo profile).
+#
+# safedeps OWNS execution (it runs gitleaks via `safedeps scan secrets`).
+# THIS FILE is the repo's POLICY — you own it. Tune the [allowlist] below for
+# this repo. `safedeps hooks init` scaffolds this file once and will NOT
+# overwrite it on a re-run, so your edits are safe.
+#
+# gitleaks config reference: https://github.com/gitleaks/gitleaks#configuration
+
+title = "safedeps secret-scan policy"
+
+# Inherit gitleaks' built-in ruleset (AWS / GCP / private keys / OAuth tokens /
+# generic high-entropy secrets, etc.). This is the bulk of the coverage.
+[extend]
+useDefault = true
+
+# --- Extra rules layered on top of the defaults -------------------------------
+
+# Flag a committed real dotenv file with an assigned secret. The .example /
+# .sample / .template variants are allowlisted below so docs stay committable.
+[[rules]]
+id = "safedeps-dotenv-file"
+description = "Committed .env file with an assigned secret value"
+path = '''(^|/)\.env(\.[\w.-]+)?$'''
+regex = '''(?i)(secret|token|password|passwd|api[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret)\s*[:=]\s*\S{6,}'''
+  [rules.allowlist]
+  paths = [
+    '''(^|/)\.env\.example$''',
+    '''(^|/)\.env\.sample$''',
+    '''(^|/)\.env\.template$''',
+  ]
+
+# --- Repo-owned allowlist — CUSTOMIZE FOR THIS REPO ---------------------------
+[allowlist]
+description = "Repo-specific allowlist (tune me)"
+paths = [
+  '''(^|/)\.gitleaks\.toml$''',
+  '''(^|/)\.gitleaks\.private\.toml$''',
+  # Add test fixtures / docs that legitimately contain secret-shaped strings:
+  # '''(^|/)test/fixtures/''',
+]
+# regexes = ['''EXAMPLE_PLACEHOLDER_[A-Z0-9]+''']
+# stopwords = ["example", "dummy", "placeholder"]

package/lib/gates/templates/pre-commit.tmpl

@@ -0,0 +1,49 @@
+#!/bin/bash
+# .githooks/pre-commit — safedeps secret-leak gate (scaffolded by `safedeps hooks init`).
+#
+# Blocks a commit when gitleaks finds a secret in the STAGED changes, so a key
+# or a real .env never enters the repo's history. The detection POLICY lives in
+# this repo's .gitleaks.toml (public) / .gitleaks.private.toml (private);
+# safedeps owns execution. This hook delegates to one canonical scanner path:
+# `safedeps scan secrets --staged`.
+#
+# Intentional bypass (use sparingly — you own the risk):  git commit --no-verify
+set -euo pipefail
+
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+# Resolve the safedeps CLI: PATH first, then the known skill install locations.
+resolve_safedeps() {
+  if command -v safedeps >/dev/null 2>&1; then printf 'safedeps'; return 0; fi
+  local candidate
+  for candidate in \
+    "${SAFEDEPS_BIN:-}" \
+    "${HOME}/.claude/skills/safedeps/bin/safedeps" \
+    "${HOME}/.codex/skills/safedeps/bin/safedeps"; do
+    if [ -n "${candidate}" ] && [ -x "${candidate}" ]; then
+      printf '%s' "${candidate}"
+      return 0
+    fi
+  done
+  return 1
+}
+
+if ! sd=$(resolve_safedeps); then
+  cat >&2 <<'EOF'
+safedeps pre-commit: cannot locate the `safedeps` CLI.
+
+The secret-scan gate is FAIL-CLOSED — the commit is blocked because the scanner
+could not run (no silent skip). Fix one of:
+  - put `safedeps` on PATH, or
+  - export SAFEDEPS_BIN=/path/to/bin/safedeps, or
+  - install the skill: node scripts/install/install-safedeps-hooks.mjs
+
+To bypass intentionally (you own the risk):  git commit --no-verify
+EOF
+  exit 1
+fi
+
+# Delegate to the single canonical scanner. A non-zero exit means either a
+# secret was found OR no scanner (gitleaks/docker) is available — both
+# fail-closed and block the commit.
+exec "${sd}" scan secrets --staged --root "${repo_root}"

package/lib/providers/providers.sh

@@ -93,7 +93,10 @@ safedeps_hash_text() {
 safedeps_file_mtime() {
   local path="$1"
 
-  stat -f %m "${path}" 2>/dev/null || stat -c %Y "${path}" 2>/dev/null
+  # GNU coreutils (Linux) uses `-c %Y`; BSD/macOS uses `-f %m`. GNU must run
+  # first: on Linux `stat -f` means --file-system and prints filesystem info to
+  # stdout, which would pollute the mtime and break the arithmetic downstream.
+  stat -c %Y "${path}" 2>/dev/null || stat -f %m "${path}" 2>/dev/null
 }
 
 safedeps_cache_is_fresh() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aldegad/safedeps",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Dependency install safety gate with OSV-backed advisory checks, approved-spec ledger enforcement, and reorg rollback hooks",
   "main": "bin/safedeps",
   "bin": {
@@ -16,6 +16,7 @@
     "ARCHITECTURE.md",
     "ROADMAP.md",
     "SKILL.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "scripts": {

package/scripts/install/install-safedeps-hooks.mjs

@@ -242,6 +242,9 @@ function main() {
     log("uninstall done.");
   } else {
     log("install done. New hook events fire on the next session start.");
+    // The dependency-install gate is global. The secret-leak lane is per-repo
+    // and stays opt-in (its policy lives in each repo). Nudge, do not auto-write.
+    log("secret-leak lane is per-repo — in a repo run: safedeps doctor (then `safedeps doctor --fix` to scaffold + activate).");
   }
 }
 

package/scripts/safedeps-post-verify.sh

@@ -35,8 +35,16 @@ SAFEDEPS_MANIFEST_FILES=(
 umask 077
 mkdir -p "${GUARD_DIR}" "${SNAPSHOT_DIR}"
 
+# Observable record when the effect gate cannot run (AGENTS.md: no silent fallback).
+# The install already happened by PostToolUse, so we cannot block it; what we can
+# guarantee is that an un-runnable gate is recorded as UNVERIFIED, never a silent pass.
+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 verify hook." >&2
+  log_advisory "post-verify UNVERIFIED: jq missing — could not verify the install closure. Install jq to restore the effect gate."
+  echo "safedeps: jq is not installed — the post-install effect gate could not run; this install is UNVERIFIED (logged to advisory.log)." >&2
   exit 0
 fi
 
@@ -55,8 +63,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
@@ -68,8 +78,11 @@ acquire_state_lock() {
     fi
 
     attempts=$((attempts + 1))
-    if [[ ${attempts} -ge 100 ]]; then
-      echo "safedeps: could not acquire state lock; skipping verify hook." >&2
+    if [[ ${attempts} -ge ${SAFEDEPS_LOCK_MAX_ATTEMPTS:-100} ]]; then
+      # Install already ran; another safedeps run holds the lock. Record UNVERIFIED
+      # rather than silently passing — the other run, or a re-check, owns verification.
+      log_advisory "post-verify UNVERIFIED: state lock unavailable (another safedeps run active) — install not verified by this run."
+      echo "safedeps: could not acquire state lock; this install is UNVERIFIED by this run (logged to advisory.log)." >&2
       exit 0
     fi
     sleep 0.1

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
@@ -438,7 +461,7 @@ fi
 # 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() {
@@ -596,7 +619,16 @@ while IFS= read -r ledger_spec_line; do
   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}"
 

package/scripts/test/e2e.sh

@@ -280,4 +280,52 @@ if jq -e '[.. | strings] | any(contains("npm-reorg-guard"))' "${installer_home}/
 fi
 pass "installer legacy hook cleanup"
 
+# --- Secret-leak lane: pre-commit gate must DENY a secret, PASS clean/example -
+# The real bypass harness for the secret lane. Needs a scanner (gitleaks or
+# docker) and openssl for a synthetic high-entropy secret; skip explicitly
+# (not silently) when either is missing.
+secret_repo="${tmp_root}/secret-repo"
+mkdir -p "${secret_repo}"
+git -C "${secret_repo}" init -q
+git -C "${secret_repo}" config user.email t@safedeps.test
+git -C "${secret_repo}" config user.name safedeps-e2e
+
+# doctor flags gaps on the bare repo, then --fix scaffolds + activates the lane.
+if HOME="${tmp_root}/doc-home" "${ROOT_DIR}/bin/safedeps" doctor --root "${secret_repo}" >/dev/null 2>&1; then
+  fail "doctor flags gaps on an unconfigured repo"
+fi
+HOME="${tmp_root}/doc-home" "${ROOT_DIR}/bin/safedeps" doctor --fix --root "${secret_repo}" >/dev/null
+[[ -f "${secret_repo}/.gitleaks.toml" ]] || fail "doctor --fix scaffolds .gitleaks.toml"
+[[ -x "${secret_repo}/.githooks/pre-commit" ]] || fail "doctor --fix scaffolds executable pre-commit"
+[[ "$(git -C "${secret_repo}" config --get core.hooksPath)" == ".githooks" ]] || fail "doctor --fix activates core.hooksPath"
+pass "doctor --fix scaffolds + activates the secret lane"
+
+# The scaffolded pre-commit resolves `safedeps` via PATH, then SAFEDEPS_BIN, then
+# the skill install paths. In CI none of those exist, so point it at this repo's
+# binary; the git commit subprocess inherits the env and the hook resolves it.
+export SAFEDEPS_BIN="${ROOT_DIR}/bin/safedeps"
+
+if command -v gitleaks >/dev/null 2>&1 && command -v openssl >/dev/null 2>&1; then
+  # Regression: a clean file commits cleanly.
+  echo "hello" > "${secret_repo}/readme.txt"
+  git -C "${secret_repo}" add readme.txt
+  git -C "${secret_repo}" commit -q -m "clean" || fail "pre-commit allows a clean commit"
+
+  # Threat: a literal .env with an assigned (synthetic) secret must be blocked.
+  printf 'API_KEY=%s\n' "$(openssl rand -hex 20)" > "${secret_repo}/.env"
+  git -C "${secret_repo}" add .env
+  if git -C "${secret_repo}" commit -q -m "leak" 2>/dev/null; then
+    fail "pre-commit blocks a committed .env secret"
+  fi
+  git -C "${secret_repo}" reset -q HEAD .env >/dev/null 2>&1 || true
+
+  # Regression: the .env.example placeholder is allowlisted and commits.
+  printf 'API_KEY=your_api_key_here\n' > "${secret_repo}/.env.example"
+  git -C "${secret_repo}" add .env.example
+  git -C "${secret_repo}" commit -q -m "example" || fail "pre-commit allows the .env.example placeholder"
+  pass "pre-commit gate denies a secret, passes clean and example commits"
+else
+  printf 'ok - pre-commit gate behavior SKIPPED (needs gitleaks + openssl)\n'
+fi
+
 printf 'e2e passed\n'