claude-dev-env 1.31.0 → 1.32.0

package/hooks/session/test_session_env_cleanup.py

@@ -0,0 +1,278 @@
+"""Tests for session_env_cleanup — SessionStart hook for Bash EEXIST workaround."""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import stat
+import sys
+import time
+from pathlib import Path
+from unittest.mock import patch
+
+_SESSION_DIR = Path(__file__).resolve().parent
+_HOOKS_ROOT = _SESSION_DIR.parent
+for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
+    if each_sys_path_entry not in sys.path:
+        sys.path.insert(0, each_sys_path_entry)
+
+import session_env_cleanup as cleanup
+
+SECONDS_PER_DAY = 24 * 60 * 60
+SEVEN_DAYS_IN_SECONDS = 7 * SECONDS_PER_DAY
+
+
+def _set_mtime_days_ago(target_path: Path, days_ago: float) -> None:
+    target_mtime_seconds = time.time() - (days_ago * SECONDS_PER_DAY)
+    os.utime(target_path, (target_mtime_seconds, target_mtime_seconds))
+
+
+class TestRemovesCurrentSessionDirectory:
+    def test_removes_directory_matching_session_id(self, tmp_path: Path) -> None:
+        current_session_id = "abc-123"
+        current_session_directory = tmp_path / current_session_id
+        current_session_directory.mkdir()
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id=current_session_id,
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert not current_session_directory.exists()
+
+    def test_removes_current_session_directory_with_contents(
+        self, tmp_path: Path
+    ) -> None:
+        current_session_id = "abc-123"
+        current_session_directory = tmp_path / current_session_id
+        current_session_directory.mkdir()
+        (current_session_directory / "leftover.txt").write_text("data")
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id=current_session_id,
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert not current_session_directory.exists()
+
+    def test_no_current_session_removal_when_session_id_empty(
+        self, tmp_path: Path
+    ) -> None:
+        sibling_directory = tmp_path / "some-other-session"
+        sibling_directory.mkdir()
+        _set_mtime_days_ago(sibling_directory, days_ago=0)
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id="",
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert sibling_directory.exists()
+
+
+class TestPrunesStaleEntries:
+    def test_removes_entry_older_than_threshold(self, tmp_path: Path) -> None:
+        stale_directory = tmp_path / "old-session"
+        stale_directory.mkdir()
+        _set_mtime_days_ago(stale_directory, days_ago=10)
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id="",
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert not stale_directory.exists()
+
+    def test_keeps_entry_within_threshold(self, tmp_path: Path) -> None:
+        fresh_directory = tmp_path / "fresh-session"
+        fresh_directory.mkdir()
+        _set_mtime_days_ago(fresh_directory, days_ago=2)
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id="",
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert fresh_directory.exists()
+
+    def test_removes_stale_directory_with_contents(self, tmp_path: Path) -> None:
+        stale_directory = tmp_path / "stale-with-content"
+        stale_directory.mkdir()
+        (stale_directory / "leftover.txt").write_text("old data")
+        _set_mtime_days_ago(stale_directory, days_ago=14)
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id="",
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert not stale_directory.exists()
+
+    def test_keeps_fresh_when_pruning_among_mixed_ages(self, tmp_path: Path) -> None:
+        fresh_directory = tmp_path / "fresh-keep"
+        stale_directory = tmp_path / "stale-remove"
+        fresh_directory.mkdir()
+        stale_directory.mkdir()
+        _set_mtime_days_ago(fresh_directory, days_ago=1)
+        _set_mtime_days_ago(stale_directory, days_ago=30)
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id="",
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert fresh_directory.exists()
+        assert not stale_directory.exists()
+
+
+class TestRemovesReadOnlyDirectories:
+    def test_removes_session_directory_with_read_only_contents(
+        self, tmp_path: Path
+    ) -> None:
+        current_session_id = "readonly-session"
+        current_session_directory = tmp_path / current_session_id
+        current_session_directory.mkdir()
+        leftover_file = current_session_directory / "leftover.txt"
+        leftover_file.write_text("data")
+        leftover_file.chmod(stat.S_IREAD)
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id=current_session_id,
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert not current_session_directory.exists()
+
+    def test_prunes_stale_directory_with_read_only_contents(
+        self, tmp_path: Path
+    ) -> None:
+        stale_directory = tmp_path / "stale-readonly"
+        stale_directory.mkdir()
+        stale_file = stale_directory / "old.txt"
+        stale_file.write_text("old data")
+        stale_file.chmod(stat.S_IREAD)
+        _set_mtime_days_ago(stale_directory, days_ago=14)
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id="",
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert not stale_directory.exists()
+
+
+class TestParentDirectoryMissing:
+    def test_returns_silently_when_parent_missing(self, tmp_path: Path) -> None:
+        absent_path = tmp_path / "does-not-exist"
+        cleanup.prune_session_env(
+            session_env_directory=str(absent_path),
+            session_id="abc-123",
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert not absent_path.exists()
+
+
+class TestMainReadsSessionIdFromStdin:
+    def test_main_invokes_prune_with_stdin_session_id(self, tmp_path: Path) -> None:
+        captured_call = {}
+
+        def fake_prune(
+            session_env_directory: str,
+            session_id: str,
+            stale_age_seconds: float,
+        ) -> None:
+            captured_call["session_id"] = session_id
+
+        stdin_payload = io.StringIO(json.dumps({"session_id": "session-from-stdin"}))
+        with (
+            patch.object(cleanup, "prune_session_env", side_effect=fake_prune),
+            patch("sys.stdin", stdin_payload),
+        ):
+            cleanup.main()
+        assert captured_call["session_id"] == "session-from-stdin"
+
+    def test_main_passes_empty_session_id_when_stdin_invalid(self) -> None:
+        captured_call = {}
+
+        def fake_prune(
+            session_env_directory: str,
+            session_id: str,
+            stale_age_seconds: float,
+        ) -> None:
+            captured_call["session_id"] = session_id
+
+        stdin_payload = io.StringIO("not json at all")
+        with (
+            patch.object(cleanup, "prune_session_env", side_effect=fake_prune),
+            patch("sys.stdin", stdin_payload),
+        ):
+            cleanup.main()
+        assert captured_call["session_id"] == ""
+
+    def test_main_rejects_session_id_with_path_separator(self) -> None:
+        captured_call = {}
+
+        def fake_prune(
+            session_env_directory: str,
+            session_id: str,
+            stale_age_seconds: float,
+        ) -> None:
+            captured_call["session_id"] = session_id
+
+        stdin_payload = io.StringIO(json.dumps({"session_id": "../../../etc/passwd"}))
+        with (
+            patch.object(cleanup, "prune_session_env", side_effect=fake_prune),
+            patch("sys.stdin", stdin_payload),
+            patch.object(cleanup.sys, "platform", "win32"),
+        ):
+            cleanup.main()
+        assert captured_call["session_id"] == ""
+
+    def test_main_rejects_absolute_windows_path_session_id(self) -> None:
+        captured_call = {}
+
+        def fake_prune(
+            session_env_directory: str,
+            session_id: str,
+            stale_age_seconds: float,
+        ) -> None:
+            captured_call["session_id"] = session_id
+
+        stdin_payload = io.StringIO(json.dumps({"session_id": "C:\\Windows\\Temp"}))
+        with (
+            patch.object(cleanup, "prune_session_env", side_effect=fake_prune),
+            patch("sys.stdin", stdin_payload),
+            patch.object(cleanup.sys, "platform", "win32"),
+        ):
+            cleanup.main()
+        assert captured_call["session_id"] == ""
+
+
+class TestMainPlatformGuard:
+    def test_main_no_ops_on_non_windows(self) -> None:
+        captured_call = {"called": False}
+
+        def fake_prune(
+            session_env_directory: str,
+            session_id: str,
+            stale_age_seconds: float,
+        ) -> None:
+            captured_call["called"] = True
+
+        stdin_payload = io.StringIO(json.dumps({"session_id": "abc-123"}))
+        with (
+            patch.object(cleanup, "prune_session_env", side_effect=fake_prune),
+            patch("sys.stdin", stdin_payload),
+            patch.object(cleanup.sys, "platform", "linux"),
+        ):
+            cleanup.main()
+        assert captured_call["called"] is False
+
+
+class TestPruneHandlesListdirFailure:
+    def test_prune_returns_silently_when_listdir_raises(self, tmp_path: Path) -> None:
+        existing_session_directory = tmp_path / "still-there"
+        existing_session_directory.mkdir()
+
+        def raise_oserror(path: str) -> list[str]:
+            raise OSError("simulated listdir failure")
+
+        with patch("os.listdir", side_effect=raise_oserror):
+            cleanup.prune_session_env(
+                session_env_directory=str(tmp_path),
+                session_id="",
+                stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+            )
+        assert existing_session_directory.exists()

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.31.0",
+    "version": "1.32.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/windows-filesystem-safe.md

@@ -0,0 +1,93 @@
+# Windows Filesystem Safety
+
+**When this applies:** Any code that recursively deletes directory trees, or that creates directories on Windows where the path may already exist with a `ReadOnly` attribute set.
+
+## Rule 1 — Never use `shutil.rmtree(..., ignore_errors=True)`
+
+`shutil.rmtree` on Windows raises `PermissionError` when it encounters a file carrying the `ReadOnly` attribute (`FILE_ATTRIBUTE_READONLY`). Linux never hits this case because `unlink` on Linux only requires write on the parent directory, not on the file itself. With `ignore_errors=True` the failure is swallowed and the tree stays on disk — cleanup *looks* successful but pruned nothing.
+
+Tests run inside `pytest`'s `tmp_path` do not exercise the regression path because tmp directories do not carry the attribute. The only place this surfaces is real Windows checkouts (notably git working trees, where `.git/objects/pack/` files are read-only by design).
+
+### Tell-tale sign
+
+`rmtree`-based cleanup that "succeeds" against a real Windows directory but the count of removed entries is zero.
+
+### Safe pattern (inline `force_rmtree`)
+
+Replace `ignore_errors=True` with an `onexc`/`onerror` handler that strips the attribute and retries the same syscall:
+
+```python
+import os
+import shutil
+import stat
+import sys
+
+
+def _strip_read_only_and_retry(removal_function, target_path, *_exc_info):
+    try:
+        os.chmod(target_path, stat.S_IWRITE)
+        removal_function(target_path)
+    except OSError:
+        pass
+
+
+def force_rmtree(target_path: str) -> None:
+    handler_kw = (
+        {"onexc": _strip_read_only_and_retry}
+        if sys.version_info >= (3, 12)
+        else {"onerror": _strip_read_only_and_retry}
+    )
+    try:
+        shutil.rmtree(target_path, **handler_kw)
+    except OSError:
+        pass
+```
+
+Two things to know about the handler:
+
+- `*_exc_info` collapses the signature difference. `onerror` passes `(type, value, traceback)`; `onexc` (Python 3.12+) passes a single exception. The variadic absorbs both.
+- `removal_function` is whichever syscall `rmtree` was attempting when it failed — `os.unlink` for files, `os.rmdir` for directories. Re-calling it after `chmod` finishes the work that originally failed.
+
+### One-liner safe pattern (when shell context demands it)
+
+If a skill or runbook genuinely needs a one-line shell invocation, the equivalent without `ignore_errors=True` is:
+
+```bash
+python -c "import os, shutil, stat, sys; \
+def _h(f, p, *_): os.chmod(p, stat.S_IWRITE); f(p); \
+shutil.rmtree(r'<path>', **({'onexc': _h} if sys.version_info >= (3, 12) else {'onerror': _h}))"
+```
+
+Prefer the multi-line `force_rmtree` helper — the one-liner is hard to read and easy to mis-quote.
+
+## Rule 2 — `mkdirSync` without `{ recursive: true }` on possibly-existing paths
+
+Windows directories can also carry the `ReadOnly` attribute (e.g. anything Claude Code creates under `~/.claude/teams/<name>/`, `~/.claude/session-env/<id>/`). The attribute does not break `shutil.rmtree` directly — it breaks Node's `fs.mkdirSync` when called *without* `{ recursive: true }` on a path that already exists.
+
+### Safe pattern
+
+```javascript
+import { mkdirSync } from 'node:fs';
+
+mkdirSync(targetPath, { recursive: true });
+```
+
+`recursive: true` makes `mkdirSync` idempotent — it succeeds whether the directory exists or not, and skips the attribute check on the existing path.
+
+### When you cannot use `{ recursive: true }`
+
+If the call must be non-recursive for reasons specific to that code path (the existing `bin/git_hooks_installer.mjs` uses `recursive: false` deliberately to assert non-existence), strip the attribute first:
+
+```powershell
+(Get-Item $path -Force).Attributes = "Directory"
+```
+
+```python
+os.chmod(path, stat.S_IWRITE)
+```
+
+…and only then call the non-recursive `mkdir`.
+
+## Enforcement
+
+A `PreToolUse` hook (`windows_rmtree_blocker.py`) blocks any `Write`, `Edit`, or `Bash` invocation whose payload contains `shutil.rmtree(..., ignore_errors=True)` and returns this rule's safe pattern as the corrective message.

package/skills/bugteam/SKILL.md

@@ -65,6 +65,14 @@ python "${CLAUDE_SKILL_DIR}/scripts/bugteam_preflight.py"
 
 Non-zero → fix before grant. `BUGTEAM_PREFLIGHT_SKIP=1` emergency only. `--pre-commit` if `.pre-commit-config.yaml` exists.
 
+**Auto-remediation for `core.hooksPath`:** when preflight fails with stderr containing `core.hooksPath` (the message starts with `bugteam_preflight: core.hooksPath is`, or `Git-side CODE_RULES enforcement is not active`), Claude must auto-invoke the fix script — do not fall through to `AskUserQuestion`, do not punt to the user, do not ask for confirmation:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/bugteam_fix_hookspath.py"
+```
+
+The fix script removes any non-canonical local-scope override on the active repository, sets the global `core.hooksPath` to `~/.claude/hooks/git-hooks` if missing or wrong, and re-runs `bugteam_preflight.py`. Its exit code becomes the preflight outcome. Exit 0 → continue to Step 0. Non-zero only when the canonical hooks directory is missing (run `npx claude-dev-env .` first) or `git config --global` writes are blocked. Other preflight failures (pytest, pre-commit) still require manual fixes — the auto-remediation only applies to the `core.hooksPath` failure mode.
+
 ## The Process
 
 ### Progress checklist
@@ -283,7 +291,13 @@ Pass finding comment URLs/ids from `loop_comment_index` in XML. Replies: `Fixed
 
 2. `TeamDelete()`
 
-3. `python -c "import shutil; shutil.rmtree(r'<team_temp_dir>', ignore_errors=True)"`
+3. Windows-safe teardown — `ignore_errors=True` silently swallows ReadOnly-attribute failures on Windows (see `~/.claude/rules/windows-filesystem-safe.md`). Use the inline `force_rmtree` helper:
+
+   ```bash
+   python -c "import os, shutil, stat, sys; \
+   h = lambda f, p, *_: (os.chmod(p, stat.S_IWRITE), f(p)); \
+   shutil.rmtree(r'<team_temp_dir>', **({'onexc': h} if sys.version_info >= (3, 12) else {'onerror': h}))"
+   ```
 
 ### Step 4.5: PR description
 

package/skills/bugteam/SKILL_EVALS.md

@@ -124,7 +124,7 @@ The harness does not yet exist; this document defines its contract.
 | 17 | `Read(".bugteam-loop-2.outcomes.xml")` — zero findings | `SKILL.md` § AUDIT action |
 | 18 | `SendMessage(to="bugfind", message={type: "shutdown_request", reason: "audit loop 2 complete; zero findings"})` | `SKILL.md` § AUDIT action (**Shutdown** fallback) |
 | 19 | `TeamDelete()` | `SKILL.md` § Step 4 |
-| 20 | `Bash("python -c \"import shutil; shutil.rmtree(r'<team_temp_dir>', ignore_errors=True)\"")` | `SKILL.md` § Step 4 |
+| 20 | `Bash("python -c \"import os, shutil, stat, sys; h = lambda f, p, *_: (os.chmod(p, stat.S_IWRITE), f(p)); shutil.rmtree(r'<team_temp_dir>', **({'onexc': h} if sys.version_info >= (3, 12) else {'onerror': h}))\"")` | `SKILL.md` § Step 4 (Windows-safe teardown) |
 | 21 | `Bash("gh pr diff 42 -R ... > .bugteam-final.diff")` | `SKILL.md` § Step 4.5 step 1 |
 | 22 | `Bash("gh pr view 42 -R ... --json body --jq .body > .bugteam-original-body.md")` | `SKILL.md` § Step 4.5 step 2 |
 | 23 | `Agent(subagent_type="pr-description-writer", description=..., prompt=<brief>)` | `SKILL.md` § Step 4.5 |

package/skills/bugteam/reference/teardown-publish-permissions.md

@@ -24,7 +24,7 @@ When the cycle exits (any reason), run these steps in order from **this** sessio
 
 2. **Clean up the team** with `TeamDelete()` (no arguments — reads `<team_name>` from session context). Maps to “clean up the team” in the docs; quote: [`../sources.md`](../sources.md).
 
-3. **Delete the per-team temp directory** using the Python one-liner in `SKILL.md` with the same literal `<team_temp_dir>` from Step 2. `shutil.rmtree(..., ignore_errors=True)` is portable across Windows and Unix.
+3. **Delete the per-team temp directory** using the Python one-liner in `SKILL.md` with the same literal `<team_temp_dir>` from Step 2. The one-liner uses an `onexc`/`onerror` handler that strips the Windows ReadOnly attribute and retries the failing syscall — `ignore_errors=True` is unsafe on Windows because it silently swallows ReadOnly-attribute failures (see `~/.claude/rules/windows-filesystem-safe.md`).
 
 ## Step 4.5 — Finalize the PR description (mandatory)
 

package/skills/bugteam/scripts/README.md

@@ -5,6 +5,7 @@ Scripts in this directory are **executed** by the lead or teammates. They are no
 | Script | Purpose |
 |--------|---------|
 | `bugteam_preflight.py` | Run pytest (when configured) and optional `pre-commit` before `/bugteam`. |
+| `bugteam_fix_hookspath.py` | Auto-remediate a stale local `core.hooksPath` override, set canonical global value, re-run `bugteam_preflight.py`. Invoked by Claude when preflight reports a `core.hooksPath` failure. |
 | `bugteam_code_rules_gate.py` | Run `validate_content` from `code-rules-enforcer.py` on PR-scoped files (`git diff` vs merge-base). Exit `1` if any mandatory rule fails. Invoked **before each audit**; the fixer clears it before the auditor runs. |
 | `grant_project_claude_permissions.py` | Idempotent grant of Edit/Write/Read on `cwd/.claude/**` into `~/.claude/settings.json`. |
 | `revoke_project_claude_permissions.py` | Removes the matching grant entries from `~/.claude/settings.json`. |
@@ -24,6 +25,22 @@ python "${CLAUDE_SKILL_DIR}/scripts/bugteam_preflight.py"
 - Pytest exit code `5` (no tests collected) is treated as success.
 - Add `--pre-commit` to run `pre-commit run --all-files` when `.pre-commit-config.yaml` exists.
 
+## `bugteam_fix_hookspath.py`
+
+From the repository root:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/bugteam_fix_hookspath.py"
+```
+
+- Removes any local-scope `core.hooksPath` value that does not end in `hooks/git-hooks`.
+- Sets `git config --global core.hooksPath ~/.claude/hooks/git-hooks` when the global value is unset or non-canonical.
+- Refuses to run (exit non-zero) when `~/.claude/hooks/git-hooks` does not exist on disk — install via `npx claude-dev-env .` first.
+- Idempotent: a second invocation is a clean no-op.
+- Re-runs `bugteam_preflight.py --no-pytest` and propagates its exit code.
+
+The bugteam SKILL invokes this automatically when preflight stderr indicates a `core.hooksPath` failure, so Claude does not surface the error to the user.
+
 ## `bugteam_code_rules_gate.py`
 
 From the repository root (same merge-base rules as the PR head vs base — default `--base origin/main`):