@aldegad/safedeps 2.2.0 → 2.4.1

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.1",
   "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
@@ -107,6 +120,21 @@ compute_dir_hash() {
   fi
 }
 
+# Per-install pending-state key (issue #5) — must match the PreToolUse derivation:
+# dir hash + a hash of the command with the inert-install rewrite normalized out.
+compute_pending_key() {
+  local dir_hash="$1" command="$2" norm cmd_hash
+  norm=$(printf '%s' "${command}" | sed -E 's/[[:space:]]+--ignore-scripts([[:space:]]|$)/ /g; s/[[:space:]]+/ /g; s/^ //; s/ $//')
+  if command -v md5sum >/dev/null 2>&1; then
+    cmd_hash=$(printf '%s' "${norm}" | md5sum | cut -d' ' -f1)
+  elif command -v md5 >/dev/null 2>&1; then
+    cmd_hash=$(md5 -q -s "${norm}")
+  else
+    cmd_hash=$(printf '%s' "${norm}" | cksum | cut -d' ' -f1)
+  fi
+  printf '%s_%s' "${dir_hash}" "${cmd_hash}"
+}
+
 hash_file() {
   local file_path="$1"
 
@@ -363,25 +391,56 @@ if [[ "${TOOL_NAME}" != "Bash" ]]; then
   exit 0
 fi
 
+# The command + cwd identify which pending install this PostToolUse belongs to
+# (issue #5), so concurrent installs do not consume each other's state.
+COMMAND=$(echo "${INPUT}" | jq -r '.tool_input.command // empty' 2>/dev/null)
+POST_CWD=$(echo "${INPUT}" | jq -r '.cwd // empty' 2>/dev/null)
+[[ -z "${POST_CWD}" ]] && POST_CWD=$(pwd)
+if command -v realpath >/dev/null 2>&1; then
+  POST_CWD=$(realpath "${POST_CWD}" 2>/dev/null || echo "${POST_CWD}")
+elif command -v readlink >/dev/null 2>&1; then
+  POST_CWD=$(readlink -f "${POST_CWD}" 2>/dev/null || echo "${POST_CWD}")
+fi
+POST_DIR_HASH=$(compute_dir_hash "${POST_CWD}")
+
 STATE_LOCK_HELD=true
 acquire_state_lock
 trap '[ "${STATE_LOCK_HELD:-}" = "true" ] && release_state_lock; STATE_LOCK_HELD=false' EXIT
 
-# Check if we have a pending snapshot to verify (V-004: atomic state file)
-if [[ ! -f "${GUARD_DIR}/current_state" ]]; then
-  # Legacy fallback for in-flight upgrades
-  if [[ ! -f "${GUARD_DIR}/current_snapshot_id" ]]; then
-    exit 0
-  fi
-  SNAPSHOT_ID=$(cat "${GUARD_DIR}/current_snapshot_id")
-  PROJECT_DIR=$(cat "${GUARD_DIR}/current_project_dir" 2>/dev/null || pwd)
-  rm -f "${GUARD_DIR}/current_snapshot_id" "${GUARD_DIR}/current_project_dir"
-else
+# Resolve THIS install's pending state by its per-install key (issue #5). The
+# filename also carries a snapshot id, so identical concurrent commands produce
+# several files; consume exactly one (they verify the same closure), leaving the
+# rest for their own post hooks. Fall back to the legacy global files for in-flight
+# upgrades from a pre-#5 PreToolUse.
+PENDING_PREFIX="${GUARD_DIR}/pending/$(compute_pending_key "${POST_DIR_HASH}" "${COMMAND}")__"
+PENDING_FILE=""
+for pending_candidate in "${PENDING_PREFIX}"*.json; do
+  [[ -f "${pending_candidate}" ]] && { PENDING_FILE="${pending_candidate}"; break; }
+done
+if [[ -n "${PENDING_FILE}" ]]; then
+  CURRENT_STATE=$(cat "${PENDING_FILE}")
+  SNAPSHOT_ID=$(echo "${CURRENT_STATE}" | jq -r '.snapshot_id // empty')
+  PROJECT_DIR=$(echo "${CURRENT_STATE}" | jq -r '.project_dir // empty')
+  DIR_HASH=$(echo "${CURRENT_STATE}" | jq -r '.dir_hash // empty')
+  rm -f "${PENDING_FILE}"
+elif [[ -f "${GUARD_DIR}/current_state" ]]; then
   CURRENT_STATE=$(cat "${GUARD_DIR}/current_state")
   SNAPSHOT_ID=$(echo "${CURRENT_STATE}" | jq -r '.snapshot_id // empty')
   PROJECT_DIR=$(echo "${CURRENT_STATE}" | jq -r '.project_dir // empty')
   DIR_HASH=$(echo "${CURRENT_STATE}" | jq -r '.dir_hash // empty')
   rm -f "${GUARD_DIR}/current_state"
+elif [[ -f "${GUARD_DIR}/current_snapshot_id" ]]; then
+  SNAPSHOT_ID=$(cat "${GUARD_DIR}/current_snapshot_id")
+  PROJECT_DIR=$(cat "${GUARD_DIR}/current_project_dir" 2>/dev/null || pwd)
+  rm -f "${GUARD_DIR}/current_snapshot_id" "${GUARD_DIR}/current_project_dir"
+else
+  # No pending state for this command. If it nonetheless looks like a dependency
+  # install, the effect gate could not verify it — record UNVERIFIED (observable)
+  # rather than disappearing silently (e.g. a payload with no `cwd`).
+  if printf '%s' "${COMMAND}" | grep -qiE '(npm|pnpm|yarn|bun)([^"]*)(install|add|dlx)|[^a-z]npx[[:space:]]|pip[0-9]*[[:space:]]+install|cargo[[:space:]]+(add|install)|go[[:space:]]+(get|install)|gem[[:space:]]+install|bundle[[:space:]]+add|poetry[[:space:]]+add|uv[[:space:]]+(add|pip)|pipenv[[:space:]]+install|mvn([^"]*)dependency:get|dotnet[[:space:]]+add[[:space:]]+package'; then
+    log_advisory "post-verify UNVERIFIED: no pending state for an install-looking command (missing cwd or pre hook never ran)."
+  fi
+  exit 0
 fi
 
 if [[ -z "${SNAPSHOT_ID}" ]]; then