claude-dev-env 2.28.1 → 2.30.0

package/hooks/session/AGENTS.md

@@ -1,38 +1 @@
-# hooks/session
 
-SessionStart and SessionEnd hooks for per-session setup and cleanup: removing stale session and plugin-data directories at startup, starting the session's task-list maintenance loop, injecting working-style guidance, and clearing PR-author swap state at shutdown. Also holds the UserPromptSubmit hook. It adds a style reminder to each message.
-
-The working-style projection uses `~/.claude/rules/asd-ste100-language.md` for
-user-facing word choice, sentence style, tone, punctuation, and prose form.
-
-## Key files
-
-| File | Event | What it does |
-|---|---|---|
-| `session_env_cleanup.py` | SessionStart | Removes the current session's pre-existing `~/.claude/session-env/<session_id>/` directory and prunes sibling entries older than the stale-age threshold. Prevents `EEXIST` errors from non-recursive `mkdir` calls in the Bash tool on Windows. |
-| `gh_pr_author_session_cleanup.py` | SessionEnd | Clears any PR-author swap state left over from the current session |
-| `session_edit_tracker_cleanup.py` | SessionStart, SessionEnd | Deletes the tracker file for the running Claude Code conversation from the system temp directory — at start for a clean slate and at end for a clean exit. A tracker is read only by the conversation that wrote it, so a live idle tracker is kept while a peer cleans up |
-| `plugin_data_dir_cleanup.py` | SessionStart | Removes empty plugin data directories at startup to prevent `EEXIST` when Claude Code recreates them |
-| `untracked_repo_detector.py` | — | Retired legacy script; no longer registered |
-| `task_list_loop_starter.py` | SessionStart | Emits an `additionalContext` directive telling Claude to keep the task list current on a 10-minute cadence, starting the `/loop` skill when one is not already running. Writes nothing and runs no tools itself. |
-| `orchestrator_auto_starter.py` | SessionStart | Opt-in (`CLAUDE_ORCHESTRATOR_AUTO_STARTER_ENABLED`) consumer of the shared SessionStart injector; emits orchestrator skill context when enabled. Manual `/orchestrator` unchanged. |
-| `issue_tracker_session_starter.py` | SessionStart | Opt-in (`CLAUDE_ISSUE_TRACKER_SESSION_STARTER_ENABLED`) and repository-gated (git root in `~/.claude/project-paths.json`) issue-tracker skill context. |
-| `_path_setup.py` | — | Inserts the hooks directory on `sys.path` so SessionStart scripts import `hooks_constants` with top-level imports. |
-| `test_orchestrator_auto_starter.py` | — | Tests for `orchestrator_auto_starter.py` |
-| `test_issue_tracker_session_starter.py` | — | Tests for `issue_tracker_session_starter.py` |
-| `working_style_prompt.py` | SessionStart | Emits an `additionalContext` block with the fixed working-style prompt (running ledger, canonical language policy, outcome-first finish, scope discipline). Writes nothing and runs no tools itself. |
-| `style_reminder_prompt.py` | UserPromptSubmit | Adds the style reminder ("small words. few words. always. forever.") to every message, as `hookSpecificOutput.additionalContext`. Codex reads the same shape, so a manually wired Codex `hooks.json` can reuse this script too (see `docs/codex-compatibility.md`). Prints text and stops. |
-| `test_style_reminder_prompt.py` | — | Tests for `style_reminder_prompt.py` |
-| `test_gh_pr_author_session_cleanup.py` | — | Tests for `gh_pr_author_session_cleanup.py` |
-| `test_session_edit_tracker_cleanup.py` | — | Tests for `session_edit_tracker_cleanup.py` |
-| `test_session_env_cleanup.py` | — | Tests for `session_env_cleanup.py` |
-| `test_untracked_repo_detector.py` | — | Tests for `untracked_repo_detector.py` |
-| `test_task_list_loop_starter.py` | — | Tests for `task_list_loop_starter.py` |
-| `test__path_setup.py` | — | Tests for `_path_setup.py` |
-| `test_working_style_prompt.py` | — | Tests for `working_style_prompt.py` |
-
-## Conventions
-
-- `session_env_cleanup.py` is Windows-specific in effect but safe to run on all platforms; it exits 0 when the target directory does not exist.
-- Constants (stale-age threshold, directory names) live in `hooks_constants/session_env_cleanup_constants.py`.
-- Tests run with `python -m pytest session/test_<name>.py`.

package/hooks/validation/AGENTS.md

@@ -1,20 +1 @@
-# hooks/validation
 
-PostToolUse hooks that validate code quality after Claude writes or edits a file. Unlike the blocking hooks (which fire PreToolUse and can deny the write), these hooks run after the write and report errors that need a follow-up fix.
-
-## Key files
-
-| File | Event | What it does |
-|---|---|---|
-| `mypy_validator.py` | PostToolUse (Write/Edit on `.py` files) | Runs mypy on the written file and blocks (via PostToolUse block decision) when type errors are found — catches missing attributes, wrong signatures, type mismatches, and import errors |
-| `hook_format_validator.py` | PostToolUse | Validates that a hook script's output JSON matches the expected Claude Code hook-output schema |
-| `test_mypy_validator.py` | — | Tests for `mypy_validator.py` |
-| `test_hook_format_validator.py` | — | Tests for `hook_format_validator.py` |
-
-## Conventions
-
-- `mypy_validator.py` resolves the project root via `CLAUDE_PROJECT_ROOT` or `git rev-parse --show-toplevel`.
-- It works on both WSL and Windows.
-- Constants (timeouts, max displayed errors) are inline in `mypy_validator.py`; longer tunables go in `hooks_constants/`.
-- The `eval_*.txt` files in this directory are evaluation exports used during development — not runtime artifacts.
-- Tests run with `python -m pytest validation/test_<name>.py`.

package/hooks/validators/AGENTS.md

@@ -1,52 +1 @@
-# hooks/validators
 
-A library of check modules used by the validation hooks. Each module focuses on one concern; `run_all_validators.py` runs them all and collects results. These modules do not hook into Claude Code directly — they are imported by the validation hooks.
-
-## Core infrastructure
-
-| File | Role |
-|---|---|
-| `validator_base.py` | Defines the `Violation` dataclass (`file`, `line`, `message`) used by every check module |
-| `validator_defaults.py` | Default configuration values shared across check modules |
-| `exempt_paths.py` | Path exemption logic — paths that checks skip (e.g. vendored code) |
-| `output_formatter.py` | Formats `Violation` lists into human-readable output |
-| `run_all_validators.py` | Entry point — runs every check module and aggregates results |
-| `health_check.py` | Verifies that all validator dependencies (ruff, mypy) are reachable |
-| `pyproject_config_discovery.py` | Shared walk-up primitive that resolves a tool's pyproject.toml config from an original target path, matching the `[tool.<name>]` table the tool owns |
-| `system_temporary_roots.py` | Shared membership for OS temp roots (`gettempdir` plus `TEMP` / `TMP` / `TMPDIR` / `RUNNER_TEMP`); mypy walk stop and PreToolUse staging both call it |
-| `python_style_helpers.py` | Shared source-line splitting and function-discovery helpers imported by `python_style_checks.py` |
-
-## Check modules
-
-| Module | What it checks |
-|---|---|
-| `abbreviation_checks.py` | Abbreviated names in Python code |
-| `code_quality_checks.py` | General code quality concerns (dead code, stub bodies, etc.) |
-| `comment_checks.py` | Inline comment presence and content |
-| `file_structure_checks.py` | File-level structural rules (line count, module layout) |
-| `git_checks.py` | Git-state checks (untracked files, merge conflicts) |
-| `magic_value_checks.py` | Magic numbers and strings |
-| `mypy_integration.py` | Runs mypy and converts its output to `Violation` objects; stops project-root walks at the system temp directory; detached gate files skip followed imports and time out as a skip (passed) |
-| `pr_reference_checks.py` | PR references in commit messages and changelogs |
-| `python_antipattern_checks.py` | Python-specific anti-patterns (bare `except`, `Any`, etc.) |
-| `python_style_checks.py` | Python style rules (naming, imports, type hints) |
-| `react_checks.py` | React/TSX-specific checks (class component patterns, PureComponent usage) |
-| `ruff_integration.py` | Runs ruff and converts its output to `Violation` objects |
-| `security_checks.py` | Security anti-patterns (hardcoded secrets, unsafe calls) |
-| `todo_checks.py` | TODO/FIXME markers without an associated issue reference |
-| `type_safety_checks.py` | Type-safety rules (no `Any`, no `cast`, no `# type: ignore`) |
-| `useless_test_checks.py` | Tests that check only existence or constant values |
-
-## Subdirectory
-
-| Directory | Role |
-|---|---|
-| `config/` | Constants module (`directory_exemption_constants.py`) holding the exemption directory-segment names that `validate_proposed_file` staging keeps |
-| `test_files/` | Fixture files used by the validator tests — not checked-in test code |
-
-## Conventions
-
-- Every check module exposes one or more functions that take file content or an AST and return a list of `Violation` objects.
-- Test files live beside the modules they test: `test_<module>.py`. Run with `python -m pytest validators/test_<name>.py`.
-- `conftest.py` provides shared test fixtures (sample files, fixture paths).
-- `README.md` in this directory documents the validator design and how to add a new check.

package/hooks/validators/README.md

@@ -2,7 +2,7 @@
 
 AST-based Python style checks for code quality enforcement.
 
-The checks live in `python_style_checks.py`; the shared source-line splitting and function-discovery helpers they build on live in `python_style_helpers.py`.
+The checks live in `python_style_checks.py`; the shared source-line splitting and function-discovery helpers they build on live in `python_style_helpers.py`. `hook_timing_harness.py` measures real wall-clock time for the Write/Edit hooks `hooks.json` registers, reporting p50 and p95 over a configurable run count.
 
 ## Checks Implemented
 

package/hooks/validators/config/hook_timing_harness_constants.py

@@ -0,0 +1,16 @@
+"""Constants for hook_timing_harness.py.
+
+Extracted to satisfy the constants-location rule: production constants outside
+``config/`` move here rather than sitting at module scope in the harness.
+"""
+
+DEFAULT_RUN_COUNT = 7
+P50_FRACTION = 0.50
+P95_FRACTION = 0.95
+DEFAULT_TARGET_RELATIVE_PATH = "hooks/blocking/code_rules_shared.py"
+SUBPROCESS_TIMEOUT_SECONDS = 60.0
+ALL_WRITE_EDIT_MATCHER_PATTERNS = frozenset({"Write|Edit", "Write|Edit|MultiEdit"})
+ALL_TIMED_EVENT_NAMES = ("PreToolUse", "PostToolUse")
+RUN_ALL_VALIDATORS_LABEL = "run_all_validators"
+CLAUDE_PLUGIN_ROOT_PLACEHOLDER = "${CLAUDE_PLUGIN_ROOT}"
+PARENT_LEVELS_TO_PACKAGE_ROOT = 2

package/hooks/validators/hook_timing_harness.py

@@ -0,0 +1,287 @@
+"""Measure real wall-clock time for the hooks.json-registered Write/Edit hooks.
+
+Each timed command is the literal ``hooks.json`` command string with
+``${CLAUDE_PLUGIN_ROOT}`` resolved to the real package root, run as its own
+subprocess against a real repository file, timed over a configurable run
+count, and reported as p50 and p95 milliseconds.
+
+::
+
+    $ python3 hook_timing_harness.py --runs 7
+    run_all_validators         p50=1948.3ms  p95=3020.1ms
+    pre_tool_use_dispatcher    p50=180.2ms   p95=230.4ms
+    post_tool_use_dispatcher   p50=80.1ms    p95=1200.5ms
+    session_file_edit_tracker  p50=31.0ms    p95=34.2ms
+
+A target under the OS temp root would return before any validator ran, so this
+harness refuses one. It always runs the whole command line ``hooks.json``
+registers, never a single hosted check module standing in for it, so neither
+shortcut can distort the numbers.
+
+The timed payload carries no ``session_id``, so ``session_file_edit_tracker``
+writes its edit record to the default-session file rather than to a
+caller-specific one.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import math
+import re
+import subprocess
+import sys
+import time
+from pathlib import Path
+from types import ModuleType
+from typing import TextIO
+
+
+def _load_module_from_path(module_name: str, module_path: Path) -> ModuleType:
+    """Load and execute the module found at module_path, under module_name.
+
+    Loads by absolute path rather than a package-qualified import, so this
+    harness resolves its own constants module the same way whether it runs
+    standalone (``python3 hook_timing_harness.py``) or loaded by a test —
+    neither invocation shape needs ``hooks/validators`` on ``sys.path``.
+    """
+    specification = importlib.util.spec_from_file_location(module_name, module_path)
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+_harness_constants = _load_module_from_path(
+    "hook_timing_harness_constants",
+    Path(__file__).resolve().parent / "config" / "hook_timing_harness_constants.py",
+)
+_system_temporary_roots = _load_module_from_path(
+    "hook_timing_harness_system_temporary_roots",
+    Path(__file__).resolve().parent / "system_temporary_roots.py",
+)
+
+
+def _hook_label_for_command(command: str) -> str:
+    """Return the short name a wall-time report row uses for one hook command.
+
+    ::
+
+        'python3 .../pre_tool_use_dispatcher.py'      -> 'pre_tool_use_dispatcher'
+        'python3 -c "... run_all_validators ..." ...' -> 'run_all_validators'
+    """
+    if _harness_constants.RUN_ALL_VALIDATORS_LABEL in command:
+        return _harness_constants.RUN_ALL_VALIDATORS_LABEL
+    script_basename_pattern = re.compile(r"([A-Za-z0-9_]+)\.py")
+    all_basename_matches = script_basename_pattern.findall(command)
+    if not all_basename_matches:
+        raise ValueError(f"cannot derive a hook label from command: {command!r}")
+    return all_basename_matches[-1]
+
+
+def _commands_in_matcher_group(all_matcher_group: dict[str, object]) -> list[tuple[str, str]]:
+    """Return the (label, command) pairs one hooks.json matcher group registers."""
+    if all_matcher_group.get("matcher") not in _harness_constants.ALL_WRITE_EDIT_MATCHER_PATTERNS:
+        return []
+    all_hosted_hooks = all_matcher_group.get("hooks", [])
+    if not isinstance(all_hosted_hooks, list):
+        return []
+    all_commands: list[tuple[str, str]] = []
+    for each_hook in all_hosted_hooks:
+        command = each_hook.get("command", "") if isinstance(each_hook, dict) else ""
+        all_commands.append((_hook_label_for_command(command), command))
+    return all_commands
+
+
+def write_edit_hook_commands(hooks_json_path: Path) -> list[tuple[str, str]]:
+    """Return the (label, command) pairs hooks.json registers for Write/Edit.
+
+    Reads the real ``PreToolUse`` and ``PostToolUse`` sections and keeps only
+    the matcher groups that fire on a Write or Edit tool call, so the harness
+    times the same roster a live edit exercises rather than every hook in the
+    file (session, lifecycle, and Bash-only hooks included).
+
+    Args:
+        hooks_json_path: Path to the ``hooks.json`` file to read.
+
+    Returns:
+        One ``(label, command)`` pair per Write/Edit-matching hook, in the
+        file's own declaration order.
+    """
+    hooks_document = json.loads(hooks_json_path.read_text(encoding="utf-8"))
+    all_commands: list[tuple[str, str]] = []
+    for each_event_name in _harness_constants.ALL_TIMED_EVENT_NAMES:
+        for each_matcher_group in hooks_document["hooks"].get(each_event_name, []):
+            all_commands.extend(_commands_in_matcher_group(each_matcher_group))
+    return all_commands
+
+
+def _is_under_directory(candidate: Path, directory: Path) -> bool:
+    """Return whether *candidate* equals *directory* or sits under it."""
+    return candidate == directory or directory in candidate.parents
+
+
+def ensure_real_repository_target(
+    target_path: Path, repository_root: Path | None = None
+) -> Path:
+    """Return *target_path* resolved, after refusing an ephemeral scratch path.
+
+    A target under a system temporary root (``tempfile.gettempdir()`` plus any
+    set ``TEMP`` / ``TMP`` / ``TMPDIR`` / ``RUNNER_TEMP``) trips
+    ``is_ephemeral_path`` inside the hooks and returns before any validator
+    runs. A target inside *repository_root* is always real, even when the
+    checkout itself sits under a system temporary root.
+
+    Raises:
+        ValueError: When the path sits under a system temporary root and
+            outside *repository_root*.
+    """
+    resolved_target = target_path.resolve()
+    if repository_root is not None and _is_under_directory(
+        resolved_target, repository_root.resolve()
+    ):
+        return resolved_target
+    enclosing_temporary_root = _system_temporary_roots.enclosing_system_temporary_root(
+        resolved_target
+    )
+    if enclosing_temporary_root is None:
+        return resolved_target
+    raise ValueError(
+        f"refusing an ephemeral timing target under {enclosing_temporary_root}: "
+        f"{resolved_target}"
+    )
+
+
+def _write_tool_payload(target_path: Path) -> str:
+    """Build a Write-tool PreToolUse/PostToolUse payload naming *target_path*."""
+    return json.dumps(
+        {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": str(target_path),
+                "content": target_path.read_text(encoding="utf-8"),
+            },
+        }
+    )
+
+
+def run_hosted_command_once_milliseconds(
+    command_template: str, package_root: Path, payload_text: str
+) -> float:
+    """Run one registered hooks.json command once and return its wall time.
+
+    Args:
+        command_template: The ``hooks.json`` command string, ``${CLAUDE_PLUGIN_ROOT}``
+            still unresolved.
+        package_root: The real package root ``${CLAUDE_PLUGIN_ROOT}`` resolves to.
+        payload_text: The JSON payload piped to the command's stdin.
+
+    Returns:
+        The wall-clock time the subprocess took, in milliseconds.
+    """
+    resolved_command = command_template.replace(
+        _harness_constants.CLAUDE_PLUGIN_ROOT_PLACEHOLDER, str(package_root)
+    )
+    started_at = time.perf_counter()
+    subprocess.run(
+        resolved_command,
+        shell=True,
+        input=payload_text,
+        capture_output=True,
+        text=True,
+        timeout=_harness_constants.SUBPROCESS_TIMEOUT_SECONDS,
+        check=False,
+    )
+    finished_at = time.perf_counter()
+    return (finished_at - started_at) * 1000.0
+
+
+def percentile(
+    all_sorted_wall_times_milliseconds: list[float], fraction: float
+) -> float:
+    """Return the nearest-rank percentile of an already-sorted sample.
+
+    ::
+
+        percentile([10, 20, 30, 40, 50, 60, 70], 0.95) -> 70  (rank 7 of 7)
+        percentile([10, 20, 30, 40, 50, 60, 70], 0.50) -> 40  (rank 4 of 7)
+
+    Args:
+        all_sorted_wall_times_milliseconds: Ascending wall-time samples.
+        fraction: The percentile as a fraction between 0 and 1.
+
+    Returns:
+        The nearest-rank percentile value.
+
+    Raises:
+        ValueError: When the sample is empty.
+    """
+    if not all_sorted_wall_times_milliseconds:
+        raise ValueError("cannot compute a percentile of an empty sample")
+    sample_size = len(all_sorted_wall_times_milliseconds)
+    rank_index = math.ceil(fraction * sample_size) - 1
+    return all_sorted_wall_times_milliseconds[max(0, min(rank_index, sample_size - 1))]
+
+
+def measure_hosted_command_wall_times(
+    hooks_json_path: Path,
+    package_root: Path,
+    target_path: Path,
+    run_count: int,
+    *,
+    repository_root: Path | None = None,
+) -> dict[str, list[float]]:
+    """Time every Write/Edit hooks.json command over *run_count* runs each.
+
+    ``repository_root`` is the root ``ensure_real_repository_target`` judges
+    ephemerality against; it defaults to ``package_root``.
+    """
+    real_target = ensure_real_repository_target(
+        target_path, repository_root if repository_root is not None else package_root
+    )
+    payload_text = _write_tool_payload(real_target)
+    all_wall_times_by_label: dict[str, list[float]] = {}
+    for each_label, each_command_template in write_edit_hook_commands(hooks_json_path):
+        all_wall_times_by_label[each_label] = [
+            run_hosted_command_once_milliseconds(each_command_template, package_root, payload_text)
+            for _ in range(run_count)
+        ]
+    return all_wall_times_by_label
+
+
+def _report_line(label: str, all_wall_times_milliseconds: list[float]) -> str:
+    sorted_wall_times_milliseconds = sorted(all_wall_times_milliseconds)
+    p50 = percentile(sorted_wall_times_milliseconds, _harness_constants.P50_FRACTION)
+    p95 = percentile(sorted_wall_times_milliseconds, _harness_constants.P95_FRACTION)
+    return f"{label:<26} p50={p50:.1f}ms  p95={p95:.1f}ms"
+
+
+def main(
+    all_arguments: list[str],
+    report_stream: TextIO = sys.stdout,
+    repository_root: Path | None = None,
+) -> int:
+    """Run the harness CLI; report_stream and repository_root are injectable seams."""
+    package_root = Path(__file__).resolve().parents[
+        _harness_constants.PARENT_LEVELS_TO_PACKAGE_ROOT
+    ]
+    hooks_json_path = Path(__file__).resolve().parent.parent / "hooks.json"
+    default_target_path = package_root / _harness_constants.DEFAULT_TARGET_RELATIVE_PATH
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--runs", type=int, default=_harness_constants.DEFAULT_RUN_COUNT)
+    parser.add_argument("--target", type=Path, default=default_target_path)
+    arguments = parser.parse_args(all_arguments)
+    effective_repository_root = repository_root if repository_root is not None else package_root
+    all_wall_times_by_label = measure_hosted_command_wall_times(
+        hooks_json_path, package_root, arguments.target, arguments.runs,
+        repository_root=effective_repository_root,
+    )
+    for each_label, each_wall_times in all_wall_times_by_label.items():
+        report_stream.write(_report_line(each_label, each_wall_times) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/hooks/validators/test_hook_timing_harness.py

@@ -0,0 +1,251 @@
+"""Tests for hook_timing_harness.py."""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import sys
+import tempfile
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+
+def _load_module_from_path(module_name: str, module_path: Path) -> ModuleType:
+    """Load and execute the module found at module_path, under module_name."""
+    specification = importlib.util.spec_from_file_location(module_name, module_path)
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+_VALIDATORS_DIRECTORY = Path(__file__).resolve().parent
+_PACKAGE_ROOT = _VALIDATORS_DIRECTORY.parents[1]
+_HOOKS_JSON_PATH = _VALIDATORS_DIRECTORY.parent / "hooks.json"
+_REAL_TARGET_FILE = _PACKAGE_ROOT / "hooks" / "blocking" / "code_rules_shared.py"
+
+if str(_VALIDATORS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_VALIDATORS_DIRECTORY))
+hook_timing_harness = _load_module_from_path(
+    "hook_timing_harness", _VALIDATORS_DIRECTORY / "hook_timing_harness.py"
+)
+
+
+def test_hook_label_for_command_names_run_all_validators() -> None:
+    command = (
+        'python3 -c "import sys; from validators.run_all_validators import main; '
+        'sys.exit(main())" --pre-tool-use'
+    )
+    assert hook_timing_harness._hook_label_for_command(command) == "run_all_validators"
+
+
+def test_hook_label_for_command_names_the_script_basename() -> None:
+    command = "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pre_tool_use_dispatcher.py"
+    assert hook_timing_harness._hook_label_for_command(command) == "pre_tool_use_dispatcher"
+
+
+def test_write_edit_hook_commands_reads_the_real_hooks_json_roster() -> None:
+    all_commands = hook_timing_harness.write_edit_hook_commands(_HOOKS_JSON_PATH)
+    all_labels = [each_label for each_label, _each_command in all_commands]
+    assert all_labels == [
+        "run_all_validators",
+        "pre_tool_use_dispatcher",
+        "post_tool_use_dispatcher",
+        "session_file_edit_tracker",
+    ]
+
+
+def test_percentile_returns_the_nearest_rank_value() -> None:
+    sample = [10.0, 20.0, 30.0, 40.0, 50.0, 60.0, 70.0]
+    assert hook_timing_harness.percentile(sample, 0.50) == 40.0
+    assert hook_timing_harness.percentile(sample, 0.95) == 70.0
+
+
+def test_percentile_raises_on_an_empty_sample() -> None:
+    with pytest.raises(ValueError):
+        hook_timing_harness.percentile([], 0.50)
+
+
+def test_ensure_real_repository_target_refuses_an_os_temp_path(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setenv("TMPDIR", str(tmp_path))
+    ephemeral_target = Path(tempfile.gettempdir()) / "scratch.py"
+    with pytest.raises(ValueError, match="ephemeral"):
+        hook_timing_harness.ensure_real_repository_target(ephemeral_target)
+
+
+def test_ensure_real_repository_target_accepts_a_real_repository_file() -> None:
+    resolved = hook_timing_harness.ensure_real_repository_target(
+        _REAL_TARGET_FILE, _PACKAGE_ROOT
+    )
+    assert resolved == _REAL_TARGET_FILE.resolve()
+
+
+def test_ensure_real_repository_target_accepts_a_repo_file_under_the_os_temp_root(
+    tmp_path: Path,
+) -> None:
+    """A checkout placed under the OS temp root still accepts its own real files.
+
+    Ephemerality is judged relative to the given repository root, not the OS
+    temp root alone, so a checkout that itself sits under the OS temp root (a
+    common sandbox layout) does not misclassify every real file inside it as
+    a throwaway scratch target.
+    """
+    repository_root = tmp_path / "repo"
+    real_file = repository_root / "hooks" / "blocking" / "code_rules_shared.py"
+    real_file.parent.mkdir(parents=True)
+    real_file.write_text("x = 1\n", encoding="utf-8")
+
+    resolved = hook_timing_harness.ensure_real_repository_target(real_file, repository_root)
+
+    assert resolved == real_file.resolve()
+
+
+def test_ensure_real_repository_target_refuses_a_scratch_path_outside_the_repository_root(
+    tmp_path: Path,
+) -> None:
+    repository_root = tmp_path / "repo"
+    repository_root.mkdir()
+    scratch_target = tmp_path / "scratch.py"
+
+    with pytest.raises(ValueError, match="ephemeral"):
+        hook_timing_harness.ensure_real_repository_target(scratch_target, repository_root)
+
+
+def test_ensure_real_repository_target_refuses_a_path_under_runner_temp_alone(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """GitHub Actions puts pytest basetemp under RUNNER_TEMP, not gettempdir().
+
+    ``gettempdir()`` stays ``/tmp`` on the hosted runner while pytest's own
+    ``tmp_path`` lives under ``RUNNER_TEMP`` (``/home/runner/work/_temp``), a
+    directory ``gettempdir()`` never reports. A refusal that judges
+    ephemerality against ``gettempdir()`` alone misses that target and reads
+    the runner's own scratch file as a real repository file.
+    """
+    fake_os_temporary_root = tmp_path / "os-temp"
+    fake_os_temporary_root.mkdir()
+    monkeypatch.setattr(tempfile, "gettempdir", lambda: str(fake_os_temporary_root))
+    runner_temporary_root = tmp_path / "runner-temp"
+    monkeypatch.setenv("RUNNER_TEMP", str(runner_temporary_root))
+    ephemeral_target = runner_temporary_root / "scratch.py"
+
+    with pytest.raises(ValueError, match="ephemeral"):
+        hook_timing_harness.ensure_real_repository_target(ephemeral_target)
+
+
+def test_run_hosted_command_once_milliseconds_drives_the_real_tracker() -> None:
+    """A live subprocess run against a real repository file measures a positive time.
+
+    ::
+
+        session_file_edit_tracker is the fastest hosted command, so this is the
+        cheap live end-to-end proof: it drives the actual registered
+        ``hooks.json`` command line, not a standalone hosted check module.
+    """
+    all_commands = hook_timing_harness.write_edit_hook_commands(_HOOKS_JSON_PATH)
+    tracker_command = next(
+        each_command
+        for each_label, each_command in all_commands
+        if each_label == "session_file_edit_tracker"
+    )
+    payload_text = hook_timing_harness._write_tool_payload(_REAL_TARGET_FILE)
+    elapsed_milliseconds = hook_timing_harness.run_hosted_command_once_milliseconds(
+        tracker_command, _PACKAGE_ROOT, payload_text
+    )
+    assert 0.0 < elapsed_milliseconds < 5000.0
+
+
+def test_measure_hosted_command_wall_times_covers_the_real_roster() -> None:
+    """A live run against the real hooks.json roster returns all four hooks.
+
+    Runs each registered command once against a real repository file,
+    including ``run_all_validators``, so this is the one place the suite pays
+    its full wall time to prove the roster end to end.
+    """
+    all_wall_times_by_label = hook_timing_harness.measure_hosted_command_wall_times(
+        _HOOKS_JSON_PATH, _PACKAGE_ROOT, _REAL_TARGET_FILE, 1
+    )
+    assert set(all_wall_times_by_label) == {
+        "run_all_validators",
+        "pre_tool_use_dispatcher",
+        "post_tool_use_dispatcher",
+        "session_file_edit_tracker",
+    }
+    assert all(
+        each_time > 0.0
+        for each_times in all_wall_times_by_label.values()
+        for each_time in each_times
+    )
+
+
+def test_measure_hosted_command_wall_times_honors_a_repository_root_override(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """The wrapper forwards repository_root to the delegate, not just accepts it.
+
+    ``ensure_real_repository_target`` already accepts ``repository_root``, but
+    until the wrapper's own signature exposes and forwards it, no caller of
+    ``measure_hosted_command_wall_times`` can reach that parameter — the exact
+    gap the wrapper-plumb-through check caught.
+    """
+    monkeypatch.setattr(hook_timing_harness, "write_edit_hook_commands", lambda path: [])
+    repository_root = tmp_path / "repo"
+    real_file = repository_root / "hooks" / "blocking" / "code_rules_shared.py"
+    real_file.parent.mkdir(parents=True)
+    real_file.write_text("x = 1\n", encoding="utf-8")
+
+    with pytest.raises(ValueError, match="ephemeral"):
+        hook_timing_harness.measure_hosted_command_wall_times(
+            _HOOKS_JSON_PATH, _PACKAGE_ROOT, real_file, 1
+        )
+
+    all_wall_times_by_label = hook_timing_harness.measure_hosted_command_wall_times(
+        _HOOKS_JSON_PATH, _PACKAGE_ROOT, real_file, 1, repository_root=repository_root
+    )
+    assert all_wall_times_by_label == {}
+
+
+def test_main_writes_one_report_line_per_label(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake_wall_times_by_label = {"pre_tool_use_dispatcher": [100.0, 200.0]}
+    monkeypatch.setattr(
+        hook_timing_harness,
+        "measure_hosted_command_wall_times",
+        lambda *args, **kwargs: fake_wall_times_by_label,
+    )
+    report_stream = io.StringIO()
+    exit_code = hook_timing_harness.main(["--runs", "2"], report_stream=report_stream)
+    report_text = report_stream.getvalue()
+    assert exit_code == 0
+    assert "pre_tool_use_dispatcher" in report_text
+    assert "p50=" in report_text and "p95=" in report_text
+
+
+def test_main_forwards_its_own_repository_root_to_the_wrapper(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """main() forwards a caller-supplied repository_root, not just accepts it.
+
+    Mirrors the wrapper-level gap: adding ``repository_root`` to
+    ``measure_hosted_command_wall_times`` alone leaves ``main`` as a second
+    wrapper dropping the same optional keyword.
+    """
+    all_captured_kwargs: dict[str, object] = {}
+
+    def _spy_measure_hosted_command_wall_times(*args: object, **kwargs: object) -> dict[str, list[float]]:
+        all_captured_kwargs.update(kwargs)
+        return {}
+
+    monkeypatch.setattr(
+        hook_timing_harness,
+        "measure_hosted_command_wall_times",
+        _spy_measure_hosted_command_wall_times,
+    )
+    override_root = tmp_path / "repo"
+    exit_code = hook_timing_harness.main([], repository_root=override_root)
+    assert exit_code == 0
+    assert all_captured_kwargs.get("repository_root") == override_root