@aldegad/safedeps 2.4.0 → 2.5.0

package/ARCHITECTURE.md

@@ -43,7 +43,7 @@ safedeps owns security gates at two distinct moments, under one skill. It absorb
 
 The two lanes differ in timing and scope (one package's effect before/after install vs. the whole repo before a release). They live under one umbrella but stay separated by command namespace.
 
-**The secret-leak side of the release-time lane is per-repo and opt-in.** Its detection policy lives in the target repo, not in safedeps, so it does nothing until the repo provides a `.gitleaks` config and an active `.githooks/pre-commit`. `safedeps doctor` is the repo-entry diagnostic that closes that gap: it reports each piece of the secret-leak lane (`.gitleaks` policy, `pre-commit`, `core.hooksPath`, scanner availability) plus the global install-time gate, and exits non-zero when the per-repo lane has gaps. `safedeps doctor --fix` (= `safedeps hooks init` then `safedeps hooks install`) scaffolds a starter policy from `lib/gates/templates/` and activates the hooks. The scaffold is **non-destructive** — an existing repo-owned config is never overwritten — preserving the invariant that safedeps owns *execution*, not *policy*. The scaffolded `pre-commit` delegates to `safedeps scan secrets --staged` (a single canonical scanner path) and is fail-closed: an unresolvable `safedeps` or missing scanner blocks the commit rather than skipping silently.
+**The secret-leak side of the release-time lane is per-repo and opt-in.** Its detection policy lives in the target repo, not in safedeps, so it does nothing until the repo provides a `.gitleaks` config and an active `.githooks/pre-commit`. `safedeps doctor` is the repo-entry diagnostic that closes that gap: it reports each piece of the secret-leak lane (`.gitleaks` policy, `pre-commit`, `core.hooksPath`, scanner availability) plus the global install-time gate, and exits non-zero when the per-repo lane has gaps. `safedeps doctor --fix` (= `safedeps hooks init` then `safedeps hooks install`) scaffolds a starter policy from `lib/gates/templates/` and activates the hooks. The scaffold is **non-destructive** — an existing repo-owned config is never overwritten — preserving the invariant that safedeps owns *execution*, not *policy*. The scaffolded `pre-commit` runs two checks. The secret scan (`safedeps scan secrets --staged`) runs on every commit and is fail-closed: an unresolvable `safedeps` or a missing scanner blocks rather than skipping silently. The npm dependency audit (`safedeps audit npm`) also runs on every commit in a repo with an npm lockfile — not only when the lockfile changes — so a CVE disclosed *after* a package was installed is caught at the next commit by re-querying the advisory DB. The audit separates the security verdict from an availability failure via meaningful exit codes (0 clean / 1 vulnerable / 2 could-not-run): a real finding **blocks** (fail-closed), while an unreachable advisory DB makes the hook **warn and allow the commit** — an explicit, observable availability failover (per the no-silent-fallback invariant: it is logged to the commit output and does not change canonical truth), with CI and the daily re-check re-covering what the offline commit could not verify.
 
 **The effect-primary model is npm-only.** `pip`, `cargo`, `go`, `gem`, `maven`, and `nuget` stay on the v2.1 command-gate + reorg model until their closure resolvers land; they are not described as having PostToolUse closure authority.
 

package/README.ko.md

@@ -16,6 +16,19 @@
 
 ---
 
+## 배포 모델
+
+safedeps 에는 두 배포 surface 가 있다:
+
+1. **Agent skill + hooks (canonical)** -- repo 자체가 skill folder 다. `SKILL.md`, hook script, provider/ledger library, install helper 가 한 디렉터리에 함께 있다.
+2. **npm package (CLI convenience)** -- `@aldegad/safedeps` 는 `safedeps` command 를 설치한다. npm 설치만으로 Claude Code 나 Codex 가 skill 을 자동 discover 하지는 않는다. npm 설치 후에도 hook/skill installer 를 실행하거나 skill folder 를 수동 등록해야 한다.
+
+전체 skill/hook source tree 를 canonical artifact 로 원하면 GitHub release 를 쓴다. versioned global CLI 가 주목적이면 npm 을 쓴다.
+
+용어: safedeps 는 Claude/Codex hook 과 local CLI 로 동작하는 agent security skill 이다. plugin manifest 로 감싸기 전까지는 Codex plugin bundle 이 아니다.
+
+---
+
 ## 두 lane
 
 `safedeps` 는 두 보안 lane 을 소유한다 (전체 설계: [`ARCHITECTURE.md`](./ARCHITECTURE.md) §1):
@@ -23,7 +36,7 @@
 - **install-time** (이 README 의 초점) — advisory check + approved-spec ledger + 빠른 PreToolUse guard + PostToolUse effect enforcement + post-install reorg. 패키지 단위, install 명령과 실제 lockfile effect 주변.
 - **release-time** — `safedeps gates run`, `safedeps scan secrets [--repo|--worktree|--staged]`, `safedeps audit npm`, `safedeps hooks install|check`. repo 트리 secret scan, 의존성 audit, repo-local git hook 설치/검사 (push/release 전). repo-specific policy(gitleaks config, privacy 경로)는 대상 repo 에 남고 safedeps 는 실행 owner. *(옛 `security-release-gates` 흡수.)*
 
-release-time lane 의 secret 누출 쪽은 **repo 별이고 opt-in** 이다. `safedeps doctor` 가 그 repo-entry 점검이다 — repo 의 `.gitleaks` policy, `.githooks/pre-commit`, 활성 `core.hooksPath`, scanner 가용성을 진단하고(전역 install-time gate 상태도 같이 보고), `safedeps doctor --fix` 가 시작 policy 를 scaffold(`safedeps hooks init`)하고 활성화(`safedeps hooks install`)한다. scaffold 는 비파괴적이라 repo 가 소유한 기존 `.gitleaks.toml` 은 덮어쓰지 않으며, pre-commit hook 은 `safedeps scan secrets --staged` 에 위임하고 fail-closed 다. [secret 누출 lane (repo 별)](#secret-누출-lane-repo-별) 참고.
+release-time lane 의 secret 누출 쪽은 **repo 별이고 opt-in** 이다. `safedeps doctor` 가 그 repo-entry 점검이다 — repo 의 `.gitleaks` policy, `.githooks/pre-commit`, 활성 `core.hooksPath`, scanner 가용성을 진단하고(전역 install-time gate 상태도 같이 보고), `safedeps doctor --fix` 가 시작 policy 를 scaffold(`safedeps hooks init`)하고 활성화(`safedeps hooks install`)한다. scaffold 는 비파괴적이라 repo 가 소유한 기존 `.gitleaks.toml` 은 덮어쓰지 않으며, pre-commit hook 은 매 커밋 비밀키 스캔(`safedeps scan secrets --staged`)을 돌리고 npm repo 면 매 커밋 의존성 audit(`safedeps audit npm`)도 돌린다 — 실제 취약점은 차단(fail-closed)하고, 어드바이저리 DB 도달 불가 시에는 경고만 하고 커밋을 통과시킨다(관측 가능한 오프라인 failover). [secret 누출 lane (repo 별)](#secret-누출-lane-repo-별) 참고.
 
 ---
 
@@ -106,7 +119,11 @@ lane 구성 요소:
 
 - **`safedeps hooks init`** 가 시작용 `.gitleaks.toml`(private repo 면 `.gitleaks.private.toml`)과 `.githooks/pre-commit` 을 scaffold 한다. 기존 파일은 덮지 않고 유지 — policy 는 repo 가 소유한다.
 - **`safedeps hooks install`** 이 repo-local hook 을 활성화한다(`core.hooksPath = .githooks`).
-- **pre-commit hook 은 `safedeps scan secrets --staged` 에 위임**하고 **fail-closed** 다: scanner(로컬 `gitleaks` 또는 Docker)가 못 돌면 silent skip 이 아니라 커밋을 막는다. 의도된 우회는 사람이 소유하는 `git commit --no-verify` 뿐이다.
+- **pre-commit hook 은 두 검사를 돌린다**:
+  - **비밀키 스캔**(`safedeps scan secrets --staged`)을 매 커밋, **fail-closed**. scanner(로컬 `gitleaks` 또는 Docker)가 못 돌면 silent skip 이 아니라 커밋을 막는다.
+  - **npm 의존성 audit**(`safedeps audit npm`)을 npm lockfile 이 있는 repo 면 **매 커밋**. 취약한 직접·*transitive* 의존성을 잡는다 — 패키지를 깐 *뒤에* 공개된 CVE("그땐 안전해 보였는데 지금 발견됨")까지 포함해서, 사람이 손으로 절대 못 보는 그것. lockfile 이 바뀔 때만이 아니라 매 커밋 돌리는 게 핵심이다: 어드바이저리 DB 를 다시 조회하니까 이미 깔린 의존성에 *새로* 뜬 CVE 가 바로 다음 커밋에 드러난다. 보안 판정과 가용성 실패는 구분된다 — 실제 취약점은 **차단**(fail-closed)하지만, 어드바이저리 DB 가 **도달 불가**(오프라인/레지스트리 오류)면 **경고만 하고 커밋을 통과**시킨다(관측 가능한 가용성 failover, silent skip 아님). 오프라인 커밋이 못 본 건 CI 와 데일리 re-check 가 다시 메운다.
+
+  의도된 우회는 사람이 소유하는 `git commit --no-verify` 뿐이다.
 
 scaffold 된 `.gitleaks.toml` 은 **네가 손보는 시작점**이다: gitleaks 기본 ruleset 을 extend 하고, 값이 할당된 `.env` 커밋을 잡는 rule 을 더하며(`.env.example`/`.sample`/`.template` 변형은 allowlist), fixture 용 repo-owned `[allowlist]` 블록을 남겨둔다. safedeps 는 *실행* — `safedeps scan secrets` 로 gitleaks 구동 — 만 소유하고 policy 내용은 소유하지 않는다.
 

package/README.md

@@ -19,6 +19,8 @@ Safedeps has two distribution surfaces:
 
 Use the GitHub release when you want the full skill/hook source tree as the canonical artifact. Use npm when you mainly want a versioned global CLI.
 
+Terminology: safedeps is an agent security skill backed by Claude/Codex hooks and a local CLI. It is not a Codex plugin bundle unless it is later wrapped with a plugin manifest.
+
 ## Two Lanes
 
 `safedeps` owns two security lanes (full design in [`ARCHITECTURE.md`](./ARCHITECTURE.md) §1):
@@ -26,7 +28,7 @@ Use the GitHub release when you want the full skill/hook source tree as the cano
 - **Install-time** (the focus of this README) — advisory check + approved-spec ledger + fast PreToolUse guard + PostToolUse effect enforcement + post-install reorg. Per-package, around the install command and its actual lockfile effect.
 - **Release-time** — `safedeps gates run`, `safedeps scan secrets [--repo|--worktree|--staged]`, `safedeps audit npm`, `safedeps hooks install|check`. Repo-tree secret scan, dependency audit, and repo-local git hook install/check before push/release. Repo-specific policy (gitleaks config, privacy paths) stays in the target repo; safedeps owns execution. *(Absorbed the former `security-release-gates`.)*
 
-The secret-leak side of the release-time lane is **per-repo and opt-in**. `safedeps doctor` is its repo-entry check: it diagnoses the repo's `.gitleaks` policy, `.githooks/pre-commit`, the active `core.hooksPath`, and scanner availability (and reports the global install-time gate too), then `safedeps doctor --fix` scaffolds a starter policy (`safedeps hooks init`) and activates it (`safedeps hooks install`). The scaffold is non-destructive — an existing repo-owned `.gitleaks.toml` is never overwritten — and the pre-commit hook delegates to `safedeps scan secrets --staged`, fail-closed. See [Secret-Leak Lane (per-repo)](#secret-leak-lane-per-repo).
+The secret-leak side of the release-time lane is **per-repo and opt-in**. `safedeps doctor` is its repo-entry check: it diagnoses the repo's `.gitleaks` policy, `.githooks/pre-commit`, the active `core.hooksPath`, and scanner availability (and reports the global install-time gate too), then `safedeps doctor --fix` scaffolds a starter policy (`safedeps hooks init`) and activates it (`safedeps hooks install`). The scaffold is non-destructive — an existing repo-owned `.gitleaks.toml` is never overwritten — and the pre-commit hook runs a secret scan (`safedeps scan secrets --staged`) plus, on every commit in an npm repo, a dependency audit (`safedeps audit npm`): a real finding blocks (fail-closed), while an unreachable advisory DB only warns and lets the commit through (observable offline failover). See [Secret-Leak Lane (per-repo)](#secret-leak-lane-per-repo).
 
 ## How It Works
 
@@ -175,7 +177,11 @@ What the lane is made of:
 
 - **`safedeps hooks init`** scaffolds a starter `.gitleaks.toml` (or `.gitleaks.private.toml` for a private repo) and a `.githooks/pre-commit`. Existing files are kept, never overwritten — the repo owns the policy.
 - **`safedeps hooks install`** activates the repo-local hooks (`core.hooksPath = .githooks`).
-- The **pre-commit hook delegates to `safedeps scan secrets --staged`** and is **fail-closed**: if the scanner (local `gitleaks` or Docker) cannot run, it blocks the commit instead of skipping silently. The only intentional bypass is `git commit --no-verify`, which the human owns.
+- The **pre-commit hook runs two checks**:
+  - **Secret scan** (`safedeps scan secrets --staged`) on every commit, **fail-closed**. If the scanner (local `gitleaks` or Docker) cannot run, it blocks the commit instead of skipping silently.
+  - **npm dependency audit** (`safedeps audit npm`) on **every commit** in a repo that has an npm lockfile. This catches a vulnerable direct *or transitive* dependency — including a CVE that was published *after* you installed the package ("looked safe then, flagged now"), the kind of thing a human never reviews by hand. Running it every commit (not only when the lockfile changes) is the point: it re-queries the advisory DB so a newly-disclosed CVE on an already-installed dependency surfaces at the very next commit. The verdict and an availability failure are kept apart: a real finding **blocks** (fail-closed), but if the advisory DB is **unreachable** (offline / registry error) the hook **warns and lets the commit through** — an observable availability failover, never a silent skip. (CI and the daily re-check then re-cover what the offline commit could not verify.)
+
+  The only intentional bypass is `git commit --no-verify`, which the human owns.
 
 The scaffolded `.gitleaks.toml` is a **starter you tune**: it extends gitleaks' default ruleset, adds a rule for a committed `.env` with an assigned secret (the `.env.example`/`.sample`/`.template` variants are allowlisted), and leaves a repo-owned `[allowlist]` block for your fixtures. safedeps owns *execution* — running gitleaks via `safedeps scan secrets` — not the policy content.
 

package/ROADMAP.md

@@ -56,7 +56,7 @@ The internal engine keeps the v1 `reorg-guard` assets.
 
 ### Release notes
 
-- The npm package version in `package.json` is the single source of truth. `bin/safedeps` `SAFEDEPS_VERSION` tracks it and the smoke test reads `package.json` to compare (current: v2.4.0).
+- The npm package version in `package.json` is the single source of truth. `bin/safedeps` `SAFEDEPS_VERSION` tracks it and the smoke test reads `package.json` to compare (current: v2.5.0).
 - `npm test` runs the release smoke suite; the full fixture E2E lives under `v2.1-tests`.
 - The daily re-check uses no LLM tokens. It is opt-in: a macOS `launchd` user agent runs `safedeps re-check --json` daily, installed atomically by `install-safedeps-recheck-agent.mjs`. It writes `~/.safedeps/recheck.log` and `~/.safedeps/recheck-alerts.jsonl` and raises a macOS notification on a new CVE/KEV/revoke/provider-skip. Network is used only for OSV / CISA / GHSA queries.
 
@@ -129,10 +129,33 @@ Status: shipped as v2.4.0.
 ### Verification
 
 - lock-unavailable install denies fail-closed and logs to `advisory.log`
-- jq-missing is logged as an observable allow-with-warning, never a silent skip
+- jq-missing denies a likely install (best-effort fail-closed) and logs it; only non-install commands fall through
+- a missing ledger library denies fail-closed instead of falling through to allow
 - ShellCheck (`--severity=error`) is clean across all shell sources
 - existing smoke + e2e regression suite remains green on both Linux and macOS
 
+### v2.4.1 — concurrent-install race fix (#5)
+
+The pending state PreToolUse hands to PostToolUse was a single global `current_state` file, so two installs overlapping in one project could clobber each other and the effect gate could verify the wrong install (or skip one). Pending state is now keyed **per install** — `dir_hash` + a hash of the command with the inert-install rewrite normalized out — so PreToolUse and PostToolUse of the same install agree on a key while concurrent installs stay isolated. A concurrency harness (two installs → two pending files; a post consumes only its own) guards it.
+
+---
+
+## v2.5 — pre-commit dependency audit (shipped)
+
+Status: shipped as v2.5.0.
+
+### What changed
+
+- **Pre-commit dependency audit** — the scaffolded `.githooks/pre-commit` now runs `safedeps audit npm` on **every commit** in a repo with an npm lockfile, alongside the secret scan. It catches a vulnerable direct or *transitive* dependency — including a CVE disclosed *after* the package was installed ("looked safe then, flagged now") — at the next commit, by re-querying the advisory DB instead of waiting for the daily re-check. Real usage drove it: a transitive `hono` advisory that Dependabot missed was caught exactly this way.
+- **Meaningful `audit npm` exit codes** — `0` clean / `1` vulnerable / `2` could-not-run (no lockfile, npm/jq missing, advisory DB unreachable). This separates the **security verdict** from an **availability failure**; npm audit collapses both into exit 1 on its own.
+- **Observable offline failover** — when the advisory DB is unreachable the hook **warns and allows** the commit (exit 2) rather than fail-closing, so a network outage never blocks an offline commit; a real finding (exit 1) still **blocks**. Per the no-silent-fallback invariant the failover is loud (printed to the commit output), and CI / the daily re-check re-cover what the offline commit could not verify.
+
+### Verification
+
+- `audit npm` exit-code contract (clean=0 / vulnerable=1 / unreachable=2), deterministic via a fake npm
+- pre-commit blocks a commit carrying a vulnerable dependency; warns + allows when the advisory DB is unreachable
+- existing secret-lane + smoke + e2e regression suite remains green
+
 ---
 
 ## v3 (future)

package/SKILL.md

@@ -10,7 +10,9 @@ hooks:
 
 # Safedeps
 
-Two gates, one skill. You (the agent) are the primary user — drive both:
+Two gates, one skill. Safedeps is an agent security skill backed by Claude/Codex hooks and a local CLI. It is not a Codex plugin bundle unless it is later wrapped with a plugin manifest.
+
+You (the agent) are the primary user — drive both:
 
 - **Install-time gate** — clear every dependency install through an OSV-backed advisory check before it runs.
 - **Secret-leak gate** — stop a secret or a real `.env` from being committed (per-repo).
@@ -71,7 +73,7 @@ safedeps doctor --fix    # scaffold the policy + activate the hooks (non-destruc
 2. Gaps? Run `safedeps doctor --fix`. It scaffolds `.gitleaks.toml` (or `.gitleaks.private.toml`) and `.githooks/pre-commit`, then activates them. Existing repo files are never overwritten.
 3. Tune the scaffolded `.gitleaks.toml` for the repo — allowlist fixtures, add rules. You own the policy; safedeps runs it (gitleaks via `safedeps scan secrets`).
 
-The pre-commit hook delegates to `safedeps scan secrets --staged` and is **fail-closed**: no scanner → it blocks the commit. The only bypass is the human's `git commit --no-verify`.
+The pre-commit hook runs two checks: a secret scan (`safedeps scan secrets --staged`) on every commit (fail-closed), and an npm dependency audit (`safedeps audit npm`) on every commit in an npm repo — so a CVE published *after* you installed a package is caught at the next commit, not weeks later. `audit npm` exits 0 clean / 1 vulnerable / 2 could-not-run; the hook **blocks** on a real finding (1) but **warns and allows** when the advisory DB is unreachable (2 — observable offline failover). No secret scanner → blocks. The only bypass is the human's `git commit --no-verify`.
 
 ---
 

package/bin/safedeps

@@ -7,7 +7,7 @@
 
 set -euo pipefail
 
-SAFEDEPS_VERSION="2.4.0"
+SAFEDEPS_VERSION="2.5.0"
 
 # ---- repo / lib bootstrap ----------------------------------------------------
 

package/lib/gates/audit.sh

@@ -3,7 +3,17 @@ set -euo pipefail
 
 # safedeps audit npm — generic npm lockfile audit.
 # Absorbed from kuma-studio scripts/security/run-npm-audit.sh.
-# Missing lockfile stays fail-closed (no reproducible verdict without it).
+#
+# Exit codes are meaningful so a caller (e.g. the pre-commit hook) can tell a
+# security verdict apart from an availability problem — npm audit collapses both
+# into exit 1 on its own:
+#   0  clean — no advisory at or above the audit level
+#   1  vulnerable — at least one advisory at or above the level (BLOCK)
+#   2  could not produce a verdict — no lockfile, npm/jq missing, or the npm
+#      advisory database is unreachable (offline/registry error). This is an
+#      AVAILABILITY failure, not a clean bill of health; the caller decides
+#      whether to fail-closed or warn-and-continue.
+#  64  usage error
 
 REPO_ROOT=""
 AUDIT_LEVEL="${SAFEDEPS_NPM_AUDIT_LEVEL:-${KUMA_NPM_AUDIT_LEVEL:-moderate}}"
@@ -26,11 +36,53 @@ if [ -z "$REPO_ROOT" ]; then REPO_ROOT="$(pwd)"; fi
 REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
 cd "$REPO_ROOT"
 
-if [ ! -f package-lock.json ]; then
-  cat >&2 <<'EOF'
-ERROR: package-lock.json is missing, so npm audit cannot produce a reproducible dependency verdict.
-EOF
-  exit 1
+if [ ! -f package-lock.json ] && [ ! -f npm-shrinkwrap.json ]; then
+  printf 'safedeps audit: no package-lock.json/npm-shrinkwrap.json — cannot produce a reproducible verdict.\n' >&2
+  exit 2
+fi
+
+if ! command -v npm >/dev/null 2>&1; then
+  printf 'safedeps audit: npm not found — cannot produce a dependency verdict.\n' >&2
+  exit 2
 fi
 
-exec npm audit --audit-level="$AUDIT_LEVEL"
+# Without jq we cannot reliably separate an offline failure from a real finding,
+# so degrade to a plain, fail-closed audit: any non-zero exit blocks (safe).
+if ! command -v jq >/dev/null 2>&1; then
+  npm audit --audit-level="$AUDIT_LEVEL"
+  exit $?
+fi
+
+# One JSON run. npm audit shares exit 1 between "vulnerable" and "could not run",
+# so we read the verdict from the payload, not the exit code.
+audit_json="$(npm audit --json 2>/dev/null || true)"
+
+# Unreachable advisory DB / setup error → npm emits a top-level {"error":...},
+# or no/invalid JSON. Availability failure, not a verdict.
+if [ -z "$audit_json" ] \
+   || ! printf '%s' "$audit_json" | jq -e . >/dev/null 2>&1 \
+   || printf '%s' "$audit_json" | jq -e 'has("error")' >/dev/null 2>&1; then
+  printf 'safedeps audit: could not reach the npm advisory database (offline or registry error).\n' >&2
+  exit 2
+fi
+
+# Count advisories at or above the configured level.
+n_at_level="$(printf '%s' "$audit_json" | jq --arg lvl "$AUDIT_LEVEL" '
+  (.metadata.vulnerabilities // {}) as $v
+  | ["low","moderate","high","critical"] as $order
+  | (($order | index($lvl)) // 1) as $min
+  | reduce $order[$min:][] as $s (0; . + ($v[$s] // 0))
+')"
+
+if [ "${n_at_level:-0}" -gt 0 ]; then
+  printf '%s' "$audit_json" | jq -r '
+    (.metadata.vulnerabilities // {}) as $v
+    | "  severities: " +
+      ([ "critical","high","moderate","low" ]
+       | map(select(($v[.] // 0) > 0) | "\($v[.]) \(.)") | join(", "))
+  ' >&2
+  printf '%s' "$audit_json" | jq -r '(.vulnerabilities // {}) | keys[] | "  - " + .' 2>/dev/null | head -20 >&2 || true
+  printf 'safedeps audit: %s advisory(ies) at or above "%s" — blocking. Run `npm audit` for the full report.\n' "$n_at_level" "$AUDIT_LEVEL" >&2
+  exit 1
+fi
+exit 0

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

@@ -1,11 +1,17 @@
 #!/bin/bash
-# .githooks/pre-commit — safedeps secret-leak gate (scaffolded by `safedeps hooks init`).
+# .githooks/pre-commit — safedeps repo 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`.
+# Two checks:
+#   1. Secret scan (always, fail-closed) — blocks a commit when gitleaks finds a
+#      secret in the STAGED changes, so a key or a real .env never enters
+#      history. The detection POLICY lives in this repo's .gitleaks.toml
+#      (public) / .gitleaks.private.toml (private); safedeps owns execution.
+#   2. Dependency audit (npm) — on every commit when this repo has an npm
+#      lockfile. Catches a vulnerable direct or *transitive* dependency,
+#      including a CVE published AFTER you installed it ("looked safe then,
+#      flagged now"). A real finding blocks (fail-closed); only the advisory DB
+#      being unreachable (offline) warns and lets the commit through — an
+#      observable availability failover, never a silent skip.
 #
 # Intentional bypass (use sparingly — you own the risk):  git commit --no-verify
 set -euo pipefail
@@ -43,7 +49,30 @@ 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}"
+# 1. Secret scan (always). A non-zero exit means either a secret was found OR
+#    no scanner (gitleaks/docker) is available — both fail-closed, block commit.
+"${sd}" scan secrets --staged --root "${repo_root}"
+
+# 2. Dependency audit (npm) — every commit when this repo has an npm lockfile.
+#    `safedeps audit npm` exit codes: 0 clean / 1 vulnerable / 2 could-not-run.
+#      - vulnerable (1)  → BLOCK (fail-closed on the security verdict).
+#      - unreachable (2) → WARN and ALLOW (availability failover, observable):
+#        an offline commit is never silently dropped, and CI / the daily
+#        re-check still cover what this commit could not verify.
+if [ -f "${repo_root}/package-lock.json" ] || [ -f "${repo_root}/npm-shrinkwrap.json" ]; then
+  if "${sd}" audit npm --root "${repo_root}"; then
+    : # clean — no advisory at or above the audit level.
+  else
+    audit_rc=$?
+    if [ "${audit_rc}" -eq 2 ]; then
+      {
+        printf '\n'
+        printf 'safedeps pre-commit: dependency audit could not reach the advisory DB.\n'
+        printf '  -> commit ALLOWED without a fresh dependency verdict (offline failover).\n'
+        printf '  -> re-run `safedeps audit npm` once online; CI / the daily re-check also cover this.\n'
+      } >&2
+    else
+      exit "${audit_rc}"   # vulnerable (or unknown failure) -> fail-closed.
+    fi
+  fi
+fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aldegad/safedeps",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Dependency install safety gate with OSV-backed advisory checks, approved-spec ledger enforcement, and reorg rollback hooks",
   "main": "bin/safedeps",
   "bin": {

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

@@ -219,6 +219,51 @@ function unlinkBin() {
   removeSymlink(join(HOME, ".local", "bin", "safedeps"));
 }
 
+function safedepsOnPath() {
+  const dirs = (process.env.PATH || "").split(":").filter(Boolean);
+  return dirs.some((d) => {
+    try { return existsSync(join(d, "safedeps")); } catch { return false; }
+  });
+}
+
+// The dependency-install gate is global and now active. The rest of the
+// surface (secret-leak lane, dep audit) is per-repo and opt-in — its policy
+// lives in each repo. Nudge with a recommended setup; never auto-write.
+function printRecommendedSetup() {
+  const line = "─".repeat(58);
+  const out = [];
+  out.push("");
+  out.push("Recommended setup");
+  out.push(line);
+  out.push("  1. Dependency-install gate  ........  ✓ active now (global, all repos)");
+  out.push("       Every agent install is checked; for npm the installed");
+  out.push("       closure is reorged (rolled back) if it diverges.");
+  out.push("");
+  out.push("  The rest is per-repo and opt-in. Run these INSIDE a repo:");
+  out.push("");
+  out.push("  2. Pre-commit gate  ...............  recommended");
+  out.push("       safedeps doctor          # diagnose this repo (read-only)");
+  out.push("       safedeps doctor --fix    # scaffold .gitleaks.toml + pre-commit, then activate");
+  out.push("       → every commit: blocks a secret / real .env (fail-closed).");
+  out.push("       → every commit (npm repos): audits deps for vulnerable transitives;");
+  out.push("         a real finding blocks, an offline advisory DB only warns + allows.");
+  out.push("");
+  out.push("  3. Release / CI gate  .............  optional");
+  out.push("       safedeps gates run       # secret scan + npm dep audit + hook/CI check");
+  out.push("       → full-repo sweep for CI / pre-release: scans the whole tree (not just");
+  out.push("         the staged diff) and verifies the hooks themselves are installed.");
+  out.push("");
+  out.push("  Docs: README → \"Two Lanes\"");
+  if (!safedepsOnPath()) {
+    out.push("");
+    out.push("  Note: `safedeps` is not on your PATH. To run the commands above:");
+    out.push("    - re-run this installer with --link-bin (adds ~/.local/bin/safedeps), or");
+    out.push("    - use the full path: ~/.claude/skills/safedeps/bin/safedeps");
+  }
+  out.push("");
+  console.log(out.join("\n"));
+}
+
 function main() {
   if (!existsSync(REPO_PRE_HOOK) || !existsSync(REPO_POST_HOOK)) {
     throw new Error(`hook scripts not found at ${REPO_PRE_HOOK} / ${REPO_POST_HOOK}`);
@@ -242,9 +287,7 @@ 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).");
+    printRecommendedSetup();
   }
 }
 

package/scripts/safedeps-post-verify.sh

@@ -120,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"
 
@@ -376,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

package/scripts/safedeps-pre-guard.sh

@@ -123,6 +123,24 @@ compute_dir_hash() {
   fi
 }
 
+# Per-install pending-state key (issue #5): dir hash + a hash of the command with
+# the inert-install rewrite normalized out, so PreToolUse (original command) and
+# PostToolUse (possibly `--ignore-scripts`-appended) of the SAME install resolve to
+# the same key. This keeps concurrent installs in one project on separate pending
+# files instead of clobbering a single global one.
+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}"
+}
+
 command_is_dependency_install() {
   local command="$1"
   local scan_command
@@ -678,10 +696,24 @@ if [[ -n "${LEDGER_ECOSYSTEM}" && ${#LEDGER_SPECS[@]} -gt 0 ]]; then
   fi
 fi
 
-# Write current state atomically for PostToolUse (V-004: single file prevents TOCTOU)
+# Write per-install pending state for PostToolUse, keyed by (dir_hash, normalized
+# command) so concurrent installs in the same project keep separate state instead
+# of clobbering one global file (issue #5). The single-file write is still atomic
+# (write_state_file) to prevent TOCTOU within one install.
+PENDING_DIR="${GUARD_DIR}/pending"
+mkdir -p "${PENDING_DIR}"
+# GC pending entries whose PostToolUse never fired (crash/no-op). 24h is well past
+# any real install, so this never deletes an in-flight one (a 60-min window could
+# have reaped a slow native build that was still running).
+find "${PENDING_DIR}" -name '*.json' -type f -mmin +1440 -delete 2>/dev/null || true
+# Key = (dir, normalized command); the snapshot id suffix makes the filename unique
+# per install, so even two identical concurrent commands keep separate state.
+PENDING_KEY=$(compute_pending_key "${DIR_HASH}" "${COMMAND}")
 CURRENT_STATE=$(jq -n --arg sid "${SNAPSHOT_ID}" --arg pdir "${PROJECT_DIR}" --arg dhash "${DIR_HASH}" \
   '{snapshot_id: $sid, project_dir: $pdir, dir_hash: $dhash}')
-write_state_file "${GUARD_DIR}/current_state" "${CURRENT_STATE}"
+# $$ (this pre hook's PID) guarantees a unique filename even for two installs in
+# the same second (SNAPSHOT_ID has only 1s resolution).
+write_state_file "${PENDING_DIR}/${PENDING_KEY}__${SNAPSHOT_ID}_$$.json" "${CURRENT_STATE}"
 
 if ! jq -e 'has("turn_id")' <<< "${INPUT}" >/dev/null 2>&1 && \
    command_is_injectable_npm_install "${COMMAND}" && \

package/scripts/test/e2e.sh

@@ -146,7 +146,7 @@ cat > "${effect_project}/package-lock.json" <<'EOF'
 EOF
 effect_clean_post=$(
   scripts/safedeps-post-verify.sh <<EOF
-{"tool_name":"Bash","tool_input":{"command":"npm install fixture-parent@1.0.0"}}
+{"tool_name":"Bash","tool_input":{"command":"npm install fixture-parent@1.0.0"},"cwd":"${effect_project}"}
 EOF
 )
 [[ -z "${effect_clean_post}" ]] || fail "post hook passes approved full closure"
@@ -183,7 +183,7 @@ EOF
 chmod +x "${stub_bin}/npm"
 inert_post=$(
   PATH="${stub_bin}:${PATH}" scripts/safedeps-post-verify.sh <<EOF
-{"tool_name":"Bash","tool_input":{"command":"npm install fixture-parent@1.0.0 --ignore-scripts"}}
+{"tool_name":"Bash","tool_input":{"command":"npm install fixture-parent@1.0.0 --ignore-scripts"},"cwd":"${inert_project}"}
 EOF
 )
 [[ -z "${inert_post}" ]] || fail "post hook keeps verified inert rebuild success quiet"
@@ -220,7 +220,7 @@ cat > "${missing_project}/package-lock.json" <<'EOF'
 EOF
 missing_post=$(
   scripts/safedeps-post-verify.sh <<EOF
-{"tool_name":"Bash","tool_input":{"command":"npm install fixture-parent@1.0.0"}}
+{"tool_name":"Bash","tool_input":{"command":"npm install fixture-parent@1.0.0"},"cwd":"${missing_project}"}
 EOF
 )
 grep -q '의심스러운 패키지 변경 감지' <<< "${missing_post}" || fail "post hook reorgs unapproved transitive package"
@@ -328,4 +328,64 @@ else
   printf 'ok - pre-commit gate behavior SKIPPED (needs gitleaks + openssl)\n'
 fi
 
+# --- Dependency audit gate (npm) — v2.5.0 -----------------------------------
+# A fake `npm` makes the crucial distinction deterministic and offline: a
+# vulnerable verdict (block) must never be confused with an unreachable advisory
+# DB (warn + allow). If those two collapsed, an offline failover would silently
+# let real vulnerabilities through.
+fakebin="${tmp_root}/fakebin"
+mkdir -p "${fakebin}"
+cat > "${fakebin}/npm" <<'FAKE'
+#!/bin/bash
+[ "${1:-}" = "audit" ] || exit 0
+case "${FAKE_NPM_MODE:-clean}" in
+  clean)   printf '%s\n' '{"auditReportVersion":2,"vulnerabilities":{},"metadata":{"vulnerabilities":{"info":0,"low":0,"moderate":0,"high":0,"critical":0,"total":0}}}'; exit 0 ;;
+  vuln)    printf '%s\n' '{"auditReportVersion":2,"vulnerabilities":{"hono":{"name":"hono","severity":"moderate","via":[{"title":"JWT"}]}},"metadata":{"vulnerabilities":{"info":0,"low":0,"moderate":4,"high":0,"critical":0,"total":4}}}'; exit 1 ;;
+  offline) printf '%s\n' '{"error":{"code":"ENOTFOUND","summary":"registry unreachable"}}'; exit 1 ;;
+esac
+FAKE
+chmod +x "${fakebin}/npm"
+
+if command -v jq >/dev/null 2>&1; then
+  audit_repo="${tmp_root}/audit-repo"
+  mkdir -p "${audit_repo}"
+  printf '{"name":"a","lockfileVersion":3}\n' > "${audit_repo}/package-lock.json"
+  run_audit() {
+    PATH="${fakebin}:${PATH}" FAKE_NPM_MODE="$1" \
+      "${ROOT_DIR}/bin/safedeps" audit npm --root "${audit_repo}" >/dev/null 2>&1
+  }
+  run_audit clean   && rc=0 || rc=$?; [ "${rc}" = "0" ] || fail "audit exit 0 on a clean lockfile (got ${rc})"
+  run_audit vuln    && rc=0 || rc=$?; [ "${rc}" = "1" ] || fail "audit exit 1 on a vulnerable lockfile (got ${rc})"
+  run_audit offline && rc=0 || rc=$?; [ "${rc}" = "2" ] || fail "audit exit 2 when the advisory DB is unreachable (got ${rc})"
+  pass "audit npm exit-code contract: clean=0 / vulnerable=1 / unreachable=2"
+else
+  printf 'ok - audit exit-code contract SKIPPED (needs jq)\n'
+fi
+
+if command -v gitleaks >/dev/null 2>&1 && command -v jq >/dev/null 2>&1; then
+  dep_repo="${tmp_root}/dep-repo"
+  mkdir -p "${dep_repo}"
+  git -C "${dep_repo}" init -q
+  git -C "${dep_repo}" config user.email t@safedeps.test
+  git -C "${dep_repo}" config user.name safedeps-e2e
+  HOME="${tmp_root}/doc-home" "${ROOT_DIR}/bin/safedeps" doctor --fix --root "${dep_repo}" >/dev/null
+  printf '{"name":"a","lockfileVersion":3}\n' > "${dep_repo}/package-lock.json"
+  git -C "${dep_repo}" add package-lock.json
+
+  # Threat: a vulnerable dependency must BLOCK the commit (fail-closed verdict).
+  if PATH="${fakebin}:${PATH}" FAKE_NPM_MODE=vuln SAFEDEPS_BIN="${ROOT_DIR}/bin/safedeps" \
+       git -C "${dep_repo}" commit -q -m "vuln" 2>/dev/null; then
+    fail "pre-commit blocks a commit carrying a vulnerable dependency"
+  fi
+
+  # Availability failover: an unreachable advisory DB must WARN and ALLOW.
+  offline_out="$(PATH="${fakebin}:${PATH}" FAKE_NPM_MODE=offline SAFEDEPS_BIN="${ROOT_DIR}/bin/safedeps" \
+       git -C "${dep_repo}" commit -m "offline" 2>&1)" \
+    || fail "pre-commit allows the commit when the advisory DB is unreachable (offline failover)"
+  grep -q "offline failover" <<< "${offline_out}" || fail "offline failover prints an observable warning"
+  pass "pre-commit dep gate: blocks on vuln, warns+allows when offline"
+else
+  printf 'ok - pre-commit dep gate SKIPPED (needs gitleaks + jq)\n'
+fi
+
 printf 'e2e passed\n'

package/scripts/test/smoke.sh

@@ -103,7 +103,7 @@ allow_output=$(
 )
 [[ "$(jq -r '.hookSpecificOutput.permissionDecision' <<< "${allow_output}")" == "allow" ]] || fail "hook emits Claude allow decision for approved install"
 [[ "$(jq -r '.hookSpecificOutput.updatedInput.command' <<< "${allow_output}")" == "npm install left-pad@1.3.0 --ignore-scripts" ]] || fail "hook injects --ignore-scripts for Claude npm install"
-allow_sid=$(jq -r '.snapshot_id' "${tmp_root}/safe-hook-allow/current_state")
+allow_sid=$(jq -r '.snapshot_id' "${tmp_root}/safe-hook-allow/pending/"*.json)
 jq -e '.ignore_scripts_injected == true' "${tmp_root}/safe-hook-allow/snapshots/${allow_sid}_meta.json" >/dev/null || fail "hook records injected meta flag"
 pass "hook injects --ignore-scripts for Claude approved install"
 
@@ -113,7 +113,7 @@ codex_allow_output=$(
   run_codex_hook_command "${tmp_root}/home-hook-codex" "${tmp_root}/safe-hook-codex" "npm install left-pad@1.3.0"
 )
 [[ -z "${codex_allow_output}" ]] || fail "hook keeps Codex approved install as plain allow"
-codex_sid=$(jq -r '.snapshot_id' "${tmp_root}/safe-hook-codex/current_state")
+codex_sid=$(jq -r '.snapshot_id' "${tmp_root}/safe-hook-codex/pending/"*.json)
 jq -e '.ignore_scripts_injected == false' "${tmp_root}/safe-hook-codex/snapshots/${codex_sid}_meta.json" >/dev/null || fail "hook does not record injected meta flag for Codex"
 pass "hook keeps Codex approved install as plain allow"
 
@@ -129,7 +129,7 @@ ignore_scripts_output=$(
   run_hook_command "${tmp_root}/home-hook-ignore-scripts" "${tmp_root}/safe-hook-ignore-scripts" "npm install left-pad@1.3.0 --ignore-scripts"
 )
 [[ -z "${ignore_scripts_output}" ]] || fail "hook does not duplicate --ignore-scripts"
-ignore_sid=$(jq -r '.snapshot_id' "${tmp_root}/safe-hook-ignore-scripts/current_state")
+ignore_sid=$(jq -r '.snapshot_id' "${tmp_root}/safe-hook-ignore-scripts/pending/"*.json)
 jq -e '.ignore_scripts_injected == false' "${tmp_root}/safe-hook-ignore-scripts/snapshots/${ignore_sid}_meta.json" >/dev/null || fail "hook does not record injected meta flag when flag already exists"
 pass "hook does not duplicate --ignore-scripts"
 
@@ -224,6 +224,29 @@ fc_noledger=$(
 grep -q 'ledger library missing' "${fc_safe}/advisory.log" || fail "pre-guard logs the missing-ledger deny to advisory.log"
 pass "pre-guard fails closed when the ledger library is missing (observable)"
 
+# Concurrency (issue #5): two installs of the SAME command in one project must
+# keep separate pending state — the per-install snapshot+PID suffix isolates them,
+# not just the command hash — and a post hook must consume exactly one.
+conc_safe="${tmp_root}/safe-concurrency"
+mkdir -p "${conc_safe}"
+SAFEDEPS_HOME="${conc_safe}" lib/ledger/ledger.sh approve npm conc-a 1.0.0 1.0.0 smoke >/dev/null
+run_hook_command "${tmp_root}/home-conc" "${conc_safe}" "npm install conc-a@1.0.0" >/dev/null
+run_hook_command "${tmp_root}/home-conc" "${conc_safe}" "npm install conc-a@1.0.0" >/dev/null
+conc_pending=$(find "${conc_safe}/pending" -name '*.json' -type f | wc -l | tr -d ' ')
+[[ "${conc_pending}" == "2" ]] || fail "two identical concurrent installs keep two separate pending files (got ${conc_pending}, want 2)"
+jq -nc --arg c "npm install conc-a@1.0.0" --arg cwd "${project_dir}" '{tool_name:"Bash",tool_input:{command:$c},cwd:$cwd}' |
+  HOME="${tmp_root}/home-conc" SAFEDEPS_HOME="${conc_safe}" scripts/safedeps-post-verify.sh >/dev/null 2>&1 || true
+conc_left=$(find "${conc_safe}/pending" -name '*.json' -type f | wc -l | tr -d ' ')
+[[ "${conc_left}" == "1" ]] || fail "post hook consumes exactly one identical-command install's pending state (left ${conc_left}, want 1)"
+pass "concurrent installs (even identical commands) keep isolated pending state (issue #5)"
+
+# A dependency-install PostToolUse with no pending state (e.g. a payload missing
+# cwd) is recorded UNVERIFIED, not dropped silently (issue #5 review finding 3).
+jq -nc '{tool_name:"Bash",tool_input:{command:"npm install orphan@1.0.0"}}' |
+  HOME="${tmp_root}/home-conc" SAFEDEPS_HOME="${conc_safe}" scripts/safedeps-post-verify.sh >/dev/null 2>&1 || true
+grep -q 'UNVERIFIED: no pending state for an install-looking command' "${conc_safe}/advisory.log" || fail "post hook records an install with no pending state as UNVERIFIED"
+pass "post hook records an install-looking command with no pending state as UNVERIFIED"
+
 tamper_safe="${tmp_root}/safe-tamper"
 tamper_home="${tmp_root}/home-tamper"
 SAFEDEPS_HOME="${tamper_safe}" lib/ledger/ledger.sh approve npm ledger-tamper 1.0.0 1.0.0 smoke >/dev/null
@@ -236,7 +259,7 @@ cat > "${project_dir}/node_modules/ledger-tamper/package.json" <<'EOF'
 {"name":"ledger-tamper","version":"1.0.0","scripts":{"postinstall":"node -e \"require('fs').writeFileSync(process.env.HOME + '/.safedeps/approved-specs/evil.json', '{}')\""}}
 EOF
 tamper_post=$(
-  jq -nc '{tool_name:"Bash",tool_input:{command:"npm install ledger-tamper@1.0.0"}}' |
+  jq -nc --arg cwd "${project_dir}" '{tool_name:"Bash",tool_input:{command:"npm install ledger-tamper@1.0.0"},cwd:$cwd}' |
     HOME="${tamper_home}" SAFEDEPS_HOME="${tamper_safe}" scripts/safedeps-post-verify.sh
 )
 grep -q '의심스러운 패키지 변경 감지' <<< "${tamper_post}" || fail "post hook reorgs safedeps ledger tamper script"