claude-dev-env 7.4.1 → 7.6.0

package/scripts/tests/test_policy_lint_rules_registry.py

@@ -22,6 +22,27 @@ from policy_lint.model import (
 
 _FUNCTION_SOURCE = "def work() -> None:\n    pass\n"
 _CHANGED_RULE_SETS = frozenset({"changed"})
+_UNDERCOUNTED_SUBPROCESS_BUDGET_TEXT = (
+    "import subprocess\n"
+    "PYTHON_FORMAT_TIMEOUT_SECONDS = 12\n"
+    "GIT_CHECK_TIMEOUT_SECONDS = 5\n"
+    "def worst_case_python_format_seconds() -> int:\n"
+    "    return PYTHON_FORMAT_TIMEOUT_SECONDS + PYTHON_FORMAT_TIMEOUT_SECONDS\n"
+    "def is_untracked_in_git(file_path: str) -> bool:\n"
+    "    git_check = subprocess.run(['git', 'ls-files', file_path], "
+    "timeout=GIT_CHECK_TIMEOUT_SECONDS)\n"
+    "    return git_check.returncode != 0\n"
+    "def run_format(file_path: str) -> None:\n"
+    "    subprocess.run(['ruff', 'format', file_path], "
+    "timeout=PYTHON_FORMAT_TIMEOUT_SECONDS)\n"
+    "def main(file_path: str) -> None:\n"
+    "    if is_untracked_in_git(file_path):\n"
+    "        return\n"
+    "    run_format(file_path)\n"
+)
+_GENERATED_CHANGELOG_TEXT = (
+    "## 7.5.0\n\n* **rules:** correct hook claims for gates that " + "no" + " longer run\n"
+)
 
 
 def _rule_named(rule_id: str) -> DocumentRule:
@@ -266,6 +287,51 @@ def test_hook_format_accepts_claude_settings() -> None:
     assert configuration_rule.accepts(settings_document) is False
 
 
+def test_prose_rules_skip_a_generated_changelog() -> None:
+    changelog_document = Document.from_text(
+        "packages/claude-dev-env/CHANGELOG.md", _GENERATED_CHANGELOG_TEXT
+    )
+    handwritten_document = Document.from_text("docs/notes.md", _GENERATED_CHANGELOG_TEXT)
+    stored_prompt_changelog = Document.from_text("rules/CHANGELOG.md", _GENERATED_CHANGELOG_TEXT)
+    stored_prompt_document = Document.from_text("rules/notes.md", _GENERATED_CHANGELOG_TEXT)
+    state_rule = _rule_named("state-description")
+    plain_language_rule = _rule_named("plain-language")
+    assert state_rule.accepts(changelog_document) is False
+    assert state_rule.accepts(handwritten_document) is True
+    assert plain_language_rule.accepts(stored_prompt_changelog) is False
+    assert plain_language_rule.accepts(stored_prompt_document) is True
+
+
+def test_lint_reports_the_changelog_phrase_only_in_the_handwritten_document(
+    tmp_path: Path,
+) -> None:
+    _ensure_git_repository(tmp_path)
+    document_set = DocumentSet(
+        (
+            Document.from_text("packages/claude-dev-env/CHANGELOG.md", _GENERATED_CHANGELOG_TEXT),
+            Document.from_text("docs/notes.md", _GENERATED_CHANGELOG_TEXT),
+        ),
+        SelectionKind.TEXT,
+        tmp_path,
+    )
+    lint_report = lint(
+        LintRequest(tmp_path, document_set), all_registry=(_rule_named("state-description"),)
+    )
+    all_reported_paths = {
+        each_diagnostic.location.path.as_posix()
+        for each_diagnostic in lint_report.diagnostics
+        if each_diagnostic.location is not None
+    }
+    assert all_reported_paths == {"docs/notes.md"}
+
+
+def test_non_prose_markdown_rules_still_run_on_a_generated_changelog() -> None:
+    changelog_document = Document.from_text(
+        "packages/claude-dev-env/CHANGELOG.md", _GENERATED_CHANGELOG_TEXT
+    )
+    assert _rule_named("docstring-gate-count").accepts(changelog_document) is True
+
+
 def test_workflow_substitution_accepts_workflow_js_suffix() -> None:
     workflow_document = Document.from_text("packages/foo/bar.workflow.js", "loop")
     directory_document = Document.from_text("docs/workflow/readme.md", "loop")
@@ -581,3 +647,53 @@ def test_lint_keeps_skipped_rules_out_of_executed_rules(tmp_path: Path) -> None:
     all_rules_report = lint(request, all_registry=(skipped_rule,))
     assert all_rules_report.executed_rules == ()
     assert all_rules_report.skipped_rules == ("skipped",)
+
+
+def test_subprocess_budget_skips_a_test_module_and_keeps_production() -> None:
+    subprocess_budget_rule = _rule_named("subprocess-budget")
+    prefixed_test_document = Document.from_text(
+        "packages/claude-dev-env/hooks/workflow/test_auto_formatter.py",
+        _UNDERCOUNTED_SUBPROCESS_BUDGET_TEXT,
+    )
+    repository_root_test_document = Document.from_text(
+        "tests/timing.py", _UNDERCOUNTED_SUBPROCESS_BUDGET_TEXT
+    )
+    production_document = Document.from_text(
+        "src/timing.py", _UNDERCOUNTED_SUBPROCESS_BUDGET_TEXT
+    )
+    assert subprocess_budget_rule.accepts(prefixed_test_document) is False
+    assert subprocess_budget_rule.accepts(repository_root_test_document) is False
+    assert subprocess_budget_rule.accepts(production_document) is True
+
+
+def _subprocess_budget_rule_identifiers(
+    repository_root: Path, document_path: str
+) -> tuple[str, ...]:
+    document_set = DocumentSet(
+        (Document.from_text(document_path, _UNDERCOUNTED_SUBPROCESS_BUDGET_TEXT),),
+        SelectionKind.TEXT,
+        repository_root,
+    )
+    lint_report = lint(
+        LintRequest(repository_root, document_set),
+        all_registry=(_rule_named("subprocess-budget"),),
+    )
+    return tuple(
+        each_diagnostic.rule_id for each_diagnostic in lint_report.diagnostics
+    )
+
+
+def test_lint_reports_an_undercounted_budget_only_in_the_production_module(
+    tmp_path: Path,
+) -> None:
+    _ensure_git_repository(tmp_path)
+    assert _subprocess_budget_rule_identifiers(tmp_path, "src/timing.py") == (
+        "subprocess-budget",
+    )
+    assert (
+        _subprocess_budget_rule_identifiers(
+            tmp_path, "packages/claude-dev-env/hooks/workflow/test_auto_formatter.py"
+        )
+        == ()
+    )
+    assert _subprocess_budget_rule_identifiers(tmp_path, "tests/timing.py") == ()

package/scripts/tests/test_policy_lint_rules_retired_hook_prose.py

@@ -0,0 +1,197 @@
+"""Tests for the retired-hook-prose rule over rules Markdown."""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+
+from policy_lint import adapter_retired_hook_prose, registry
+from policy_lint.model import ContentOrigin, Document, DocumentRule
+
+_RULE_ID = "retired-hook-prose"
+_RULES_DOCUMENT_PATH = "packages/claude-dev-env/rules/example.md"
+_INSTALLER_SOURCE = """
+export const RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS = new Set([
+    'blocking/destructive_command_blocker.py',
+]);
+"""
+_HOOKS_CONFIGURATION = """
+{
+  "hooks": {
+    "PostToolUse": [
+      {"hooks": [{"command": "python hooks/observability/session_file_edit_tracker.py"}]}
+    ]
+  }
+}
+"""
+_DISPATCHER_ROSTER_SOURCE = """
+ALL_HOSTED_HOOK_ENTRIES = (
+    HostedHookEntry("advisory/refactor_guard.py", is_blocking=False),
+)
+"""
+
+
+def _build_package(repository_root: Path) -> None:
+    package_root = repository_root / "packages" / "claude-dev-env"
+    hooks_root = package_root / "hooks"
+    (hooks_root / "blocking").mkdir(parents=True)
+    (hooks_root / "advisory").mkdir(parents=True)
+    (hooks_root / "observability").mkdir(parents=True)
+    (hooks_root / "hooks_constants").mkdir(parents=True)
+    (package_root / "bin").mkdir(parents=True)
+    (package_root / "rules").mkdir(parents=True)
+    (hooks_root / "blocking" / "windows_rmtree_blocker.py").write_text("", "utf-8")
+    (hooks_root / "advisory" / "refactor_guard.py").write_text("", "utf-8")
+    (hooks_root / "observability" / "session_file_edit_tracker.py").write_text(
+        "", "utf-8"
+    )
+    (hooks_root / "blocking" / "content_hash_store.py").write_text("", "utf-8")
+    (hooks_root / "hooks.json").write_text(_HOOKS_CONFIGURATION, "utf-8")
+    (
+        hooks_root / "hooks_constants" / "pre_tool_use_dispatcher_constants.py"
+    ).write_text(_DISPATCHER_ROSTER_SOURCE, "utf-8")
+    (package_root / "bin" / "install.mjs").write_text(_INSTALLER_SOURCE, "utf-8")
+
+
+def _diagnostics_for(repository_root: Path, prose: str) -> tuple[str, ...]:
+    document = Document(
+        PurePosixPath(_RULES_DOCUMENT_PATH),
+        prose,
+        None,
+        None,
+        ContentOrigin.WORKTREE,
+    )
+    all_diagnostics = adapter_retired_hook_prose.retired_hook_prose_diagnostics(
+        document, repository_root
+    )
+    return tuple(each_diagnostic.message for each_diagnostic in all_diagnostics)
+
+
+def test_a_live_claim_for_a_surviving_unregistered_hook_is_reported(
+    tmp_path: Path,
+) -> None:
+    _build_package(tmp_path)
+    all_messages = _diagnostics_for(
+        tmp_path,
+        "The `windows_rmtree_blocker.py` PreToolUse hook blocks the unsafe pattern.\n",
+    )
+    assert len(all_messages) == 1
+    assert "windows_rmtree_blocker" in all_messages[0]
+
+
+def test_a_live_claim_for_a_roster_hook_absent_from_disk_is_reported(
+    tmp_path: Path,
+) -> None:
+    _build_package(tmp_path)
+    all_messages = _diagnostics_for(
+        tmp_path,
+        "The `destructive_command_blocker` hook watches every Bash-tool command.\n",
+    )
+    assert len(all_messages) == 1
+    assert "destructive_command_blocker" in all_messages[0]
+
+
+def test_a_registered_hook_described_in_the_present_tense_passes(
+    tmp_path: Path,
+) -> None:
+    _build_package(tmp_path)
+    all_messages = _diagnostics_for(
+        tmp_path,
+        "`session_file_edit_tracker` records each Write path, and `refactor_guard` reports a risk.\n",
+    )
+    assert all_messages == ()
+
+
+def test_a_past_tense_retirement_sentence_passes(tmp_path: Path) -> None:
+    _build_package(tmp_path)
+    all_messages = _diagnostics_for(
+        tmp_path,
+        "Commit `0f21faf8e` retired the blocking hooks. "
+        "`destructive_command_blocker` was one of them.\n",
+    )
+    assert all_messages == ()
+
+
+def test_a_sentence_crediting_the_staged_policy_lint_passes(tmp_path: Path) -> None:
+    _build_package(tmp_path)
+    all_messages = _diagnostics_for(
+        tmp_path,
+        "`windows_rmtree_blocker.py` reports the unsafe pattern, "
+        "and the staged policy lint runs it over each changed file.\n",
+    )
+    assert all_messages == ()
+
+
+def test_a_hook_directory_support_module_passes(tmp_path: Path) -> None:
+    _build_package(tmp_path)
+    all_messages = _diagnostics_for(
+        tmp_path,
+        "`content_hash_store.py` holds the full contract in its module docstring.\n",
+    )
+    assert all_messages == ()
+
+
+def test_a_verb_before_the_hook_name_passes(tmp_path: Path) -> None:
+    _build_package(tmp_path)
+    all_messages = _diagnostics_for(
+        tmp_path,
+        "The staged lint runs `windows_rmtree_blocker.py` over each changed file.\n",
+    )
+    assert all_messages == ()
+
+
+def test_a_code_span_between_the_name_and_its_verb_does_not_hide_the_claim(
+    tmp_path: Path,
+) -> None:
+    _build_package(tmp_path)
+    all_messages = _diagnostics_for(
+        tmp_path,
+        "`destructive_command_blocker` (PreToolUse on Bash `git commit`) "
+        "denies a commit that drops session edits.",
+    )
+    assert len(all_messages) == 1
+    assert "destructive_command_blocker" in all_messages[0]
+
+
+def test_a_second_hook_name_bounds_the_first_claim(tmp_path: Path) -> None:
+    _build_package(tmp_path)
+    all_messages = _diagnostics_for(
+        tmp_path,
+        "`destructive_command_blocker` was retired, and `refactor_guard` reports a risk.",
+    )
+    assert all_messages == ()
+
+
+def test_the_rule_is_registered_for_changed_and_repository_selections() -> None:
+    all_matching_rules = tuple(
+        each_rule
+        for each_rule in registry.default_registry()
+        if each_rule.rule_id == _RULE_ID
+    )
+    assert len(all_matching_rules) == 1
+    registered_rule = all_matching_rules[0]
+    assert isinstance(registered_rule, DocumentRule)
+    assert registered_rule.rule_sets == frozenset({"changed", "repository"})
+
+
+def test_the_committed_rules_directory_names_no_gate_that_stopped_running() -> None:
+    repository_root = Path(__file__).resolve().parents[4]
+    rules_root = repository_root / "packages" / "claude-dev-env" / "rules"
+    all_messages: list[str] = []
+    for each_path in sorted(rules_root.glob("*.md")):
+        relative_path = each_path.relative_to(repository_root).as_posix()
+        document = Document(
+            PurePosixPath(relative_path),
+            each_path.read_text(encoding="utf-8"),
+            None,
+            None,
+            ContentOrigin.WORKTREE,
+        )
+        all_messages.extend(
+            f"{relative_path}:{each_diagnostic.location.start_line}: {each_diagnostic.message}"
+            for each_diagnostic in (
+                adapter_retired_hook_prose.retired_hook_prose_diagnostics(
+                    document, repository_root
+                )
+            )
+        )
+    assert all_messages == []

package/scripts/tests/test_policy_lint_selection.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import os
 import subprocess
+import sys
 from pathlib import Path, PurePosixPath
 
 import pytest
@@ -19,6 +20,13 @@ from policy_lint.model import (
 )
 from policy_lint.selection import SelectionRunFatal, select_documents
 
+WINDOWS_NO_WINDOW_FLAG = 0x08000000
+EXPECTED_HIDDEN_WINDOW_FLAGS = WINDOWS_NO_WINDOW_FLAG if sys.platform == "win32" else 0
+
+NON_UTF8_PNG_BYTES = bytes(
+    (0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0xFF, 0xFE, 0xFF)
+)
+
 
 def _git_environment() -> dict[str, str]:
     return {
@@ -66,6 +74,22 @@ def _commit_text(repository_root: Path, relative_path: str, text: str) -> None:
     _run_git(repository_root, "commit", "--quiet", "-m", "selection fixture")
 
 
+def _write_bytes(repository_root: Path, relative_path: str, raw_bytes: bytes) -> None:
+    file_path = repository_root / relative_path
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    file_path.write_bytes(raw_bytes)
+
+
+def _commit_bytes(repository_root: Path, relative_path: str, raw_bytes: bytes) -> None:
+    _write_bytes(repository_root, relative_path, raw_bytes)
+    _run_git(repository_root, "add", "--", relative_path)
+    _run_git(repository_root, "commit", "--quiet", "-m", "selection binary fixture")
+
+
+def _all_selected_paths(document_set: DocumentSet) -> set[str]:
+    return {each_document.path.as_posix() for each_document in document_set.documents}
+
+
 def _document_for(document_set: DocumentSet, relative_path: str) -> Document:
     for each_document in document_set.documents:
         if each_document.path.as_posix() == relative_path:
@@ -394,3 +418,120 @@ def test_tracked_worktree_document_preserves_git_path_spelling(
         tmp_path, "MiXeD.py"
     )
     assert selected_document.path == PurePosixPath("MiXeD.py")
+
+
+def test_base_added_binary_file_should_be_left_out_of_the_selection(
+    tmp_path: Path,
+) -> None:
+    repository_root = _initialize_repository(tmp_path)
+    _commit_text(repository_root, "file.py", "base-text\n")
+    _run_git(repository_root, "checkout", "--quiet", "-b", "feature")
+    _commit_text(repository_root, "file.py", "feature-text\n")
+    _commit_bytes(repository_root, "approved_design_overlay.png", NON_UTF8_PNG_BYTES)
+
+    document_set = select_documents(LintRequest.base(repository_root, "main"))
+
+    assert _all_selected_paths(document_set) == {"file.py"}
+    assert _document_for(document_set, "file.py").text == "feature-text\n"
+    assert document_set.deleted_paths == ()
+
+
+def test_base_modified_binary_file_should_be_left_out_of_the_selection(
+    tmp_path: Path,
+) -> None:
+    repository_root = _initialize_repository(tmp_path)
+    _commit_bytes(repository_root, "approved_design_overlay.png", NON_UTF8_PNG_BYTES)
+    _run_git(repository_root, "checkout", "--quiet", "-b", "feature")
+    _commit_bytes(
+        repository_root,
+        "approved_design_overlay.png",
+        NON_UTF8_PNG_BYTES + bytes((0xFF, 0x00, 0xFE)),
+    )
+    _commit_text(repository_root, "file.py", "feature-text\n")
+
+    document_set = select_documents(LintRequest.base(repository_root, "main"))
+
+    assert _all_selected_paths(document_set) == {"file.py"}
+    assert _document_for(document_set, "file.py").text == "feature-text\n"
+    assert document_set.deleted_paths == ()
+
+
+def test_staged_binary_file_should_be_left_out_of_the_selection(tmp_path: Path) -> None:
+    repository_root = _initialize_repository(tmp_path)
+    _commit_text(repository_root, "file.py", "committed\n")
+    _write_bytes(repository_root, "approved_design_overlay.png", NON_UTF8_PNG_BYTES)
+    _write_text(repository_root, "file.py", "staged\n")
+    _run_git(repository_root, "add", "--all", "--", ".")
+
+    document_set = select_documents(LintRequest.staged(repository_root))
+
+    assert _all_selected_paths(document_set) == {"file.py"}
+    assert _document_for(document_set, "file.py").text == "staged\n"
+    assert document_set.deleted_paths == ()
+
+
+def test_repository_source_should_leave_binary_tracked_files_out(
+    tmp_path: Path,
+) -> None:
+    repository_root = _initialize_repository(tmp_path)
+    _commit_text(repository_root, "tracked.py", "tracked\n")
+    _commit_bytes(repository_root, "approved_design_overlay.png", NON_UTF8_PNG_BYTES)
+
+    document_set = select_documents(LintRequest.repository(repository_root))
+
+    assert _all_selected_paths(document_set) == {"tracked.py"}
+    assert _document_for(document_set, "tracked.py").text == "tracked\n"
+
+
+def test_files_source_should_leave_a_named_binary_path_out(tmp_path: Path) -> None:
+    repository_root = _initialize_repository(tmp_path)
+    _commit_text(repository_root, "file.py", "committed\n")
+    _write_bytes(repository_root, "approved_design_overlay.png", NON_UTF8_PNG_BYTES)
+
+    document_set = select_documents(
+        LintRequest.files(
+            repository_root,
+            [Path("file.py"), Path("approved_design_overlay.png")],
+        )
+    )
+
+    assert _all_selected_paths(document_set) == {"file.py"}
+    assert _document_for(document_set, "file.py").text == "committed\n"
+
+
+def test_files_missing_path_should_still_raise(tmp_path: Path) -> None:
+    repository_root = _initialize_repository(tmp_path)
+    _commit_text(repository_root, "file.py", "committed\n")
+
+    with pytest.raises(SelectionRunFatal, match="does not exist"):
+        select_documents(LintRequest.files(repository_root, [Path("missing.py")]))
+
+
+def _record_git_creation_flags(monkeypatch: pytest.MonkeyPatch) -> dict[str, object]:
+    all_recorded_keyword_arguments: dict[str, object] = {}
+
+    def _record(*args: object, **kwargs: object) -> subprocess.CompletedProcess[bytes]:
+        del args
+        all_recorded_keyword_arguments.update(kwargs)
+        return subprocess.CompletedProcess([], 0, stdout=b"abc123\n", stderr=b"")
+
+    monkeypatch.setattr(selection_git.subprocess, "run", _record)
+    return all_recorded_keyword_arguments
+
+
+def test_git_bytes_for_should_start_without_a_console_window(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    all_recorded_keyword_arguments = _record_git_creation_flags(monkeypatch)
+
+    assert selection_git.git_bytes_for(tmp_path, ("status",)) == b"abc123\n"
+    assert all_recorded_keyword_arguments["creationflags"] == EXPECTED_HIDDEN_WINDOW_FLAGS
+
+
+def test_head_revision_should_start_without_a_console_window(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    all_recorded_keyword_arguments = _record_git_creation_flags(monkeypatch)
+
+    assert selection_git.head_revision(tmp_path) == "abc123"
+    assert all_recorded_keyword_arguments["creationflags"] == EXPECTED_HIDDEN_WINDOW_FLAGS

package/scripts/tests/test_subprocess_window_access.py

@@ -0,0 +1,118 @@
+"""Prove every deployed subprocess-window shim reaches the packaged helpers.
+
+Each shim sits beside the scripts of one deployed directory. A deployed
+profile carries no installed Python distribution, and the repository runs its
+scripts under ``python -S -E``, which hides installed packages from the child.
+So each check below drives a real ``-S -E`` child, imports the shim by the name
+its callers use, and reads back where the helper came from.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_PACKAGE_ROOT = Path(__file__).resolve().parents[2]
+_SHIM_MODULE_NAME = "subprocess_window_access"
+_SHIM_FILE_NAME = f"{_SHIM_MODULE_NAME}.py"
+_PACKAGED_HELPER_PATH = (
+    _PACKAGE_ROOT / "hooks" / "hooks_constants" / "subprocess_window.py"
+)
+_ALL_EXPORTED_HELPER_NAMES = (
+    "HiddenWindowStartupInfo",
+    "detached_hidden_window_creation_flags",
+    "hidden_window_creation_flags",
+    "inherited_stream_startup_info",
+)
+_ALL_SHIM_DIRECTORY_PATHS = (
+    "scripts",
+    "_shared/pr-loop/scripts",
+    "_shared/process-tree/scripts",
+    "hooks/git-hooks",
+    "hooks/validators",
+    ".agents/skills/fresh-branch/scripts",
+    ".agents/skills/syncing-submodules/scripts",
+    ".agents/skills/test-runner/scripts",
+)
+
+_IMPORT_PROBE_SOURCE = "\n".join(
+    (
+        "import json",
+        "import sys",
+        "shim_directory = sys.argv[1]",
+        "sys.path.insert(0, shim_directory)",
+        "head_before_import = sys.path[0]",
+        f"import {_SHIM_MODULE_NAME} as shim",
+        "print(json.dumps({",
+        "    'helper_path': sys.modules[",
+        "        shim.hidden_window_creation_flags.__module__",
+        "    ].__file__,",
+        "    'head_after_import': sys.path[0],",
+        "    'head_before_import': head_before_import,",
+        "    'exported_names': sorted(shim.__all__),",
+        "}))",
+    )
+)
+
+
+def _import_probe_results(shim_directory: Path) -> dict[str, object]:
+    """Import one shim in a ``-S -E`` child and read back what it resolved."""
+    completed_process = subprocess.run(
+        [
+            sys.executable,
+            "-S",
+            "-E",
+            "-c",
+            _IMPORT_PROBE_SOURCE,
+            str(shim_directory),
+        ],
+        cwd=str(_PACKAGE_ROOT),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert completed_process.returncode == 0, completed_process.stderr
+    return json.loads(completed_process.stdout)
+
+
+@pytest.mark.parametrize("shim_directory_path", _ALL_SHIM_DIRECTORY_PATHS)
+def test_every_deployed_directory_carries_a_shim(shim_directory_path: str) -> None:
+    """Each directory whose scripts import the shim also ships one."""
+    assert (_PACKAGE_ROOT / shim_directory_path / _SHIM_FILE_NAME).is_file()
+
+
+@pytest.mark.parametrize("shim_directory_path", _ALL_SHIM_DIRECTORY_PATHS)
+def test_shim_resolves_the_packaged_helper_without_an_installed_package(
+    shim_directory_path: str,
+) -> None:
+    """A ``-S -E`` child reaches the packaged helper through the shim alone."""
+    all_probe_results = _import_probe_results(_PACKAGE_ROOT / shim_directory_path)
+
+    assert Path(str(all_probe_results["helper_path"])) == _PACKAGED_HELPER_PATH
+
+
+@pytest.mark.parametrize("shim_directory_path", _ALL_SHIM_DIRECTORY_PATHS)
+def test_shim_leaves_the_head_of_the_search_path_alone(
+    shim_directory_path: str,
+) -> None:
+    """A caller that prepended its own roots keeps them ahead of the hooks tree."""
+    all_probe_results = _import_probe_results(_PACKAGE_ROOT / shim_directory_path)
+
+    assert (
+        all_probe_results["head_after_import"]
+        == (all_probe_results["head_before_import"])
+    )
+
+
+@pytest.mark.parametrize("shim_directory_path", _ALL_SHIM_DIRECTORY_PATHS)
+def test_shim_re_exports_every_hidden_window_helper(
+    shim_directory_path: str,
+) -> None:
+    """Every caller finds the name it needs on the shim it imports."""
+    all_probe_results = _import_probe_results(_PACKAGE_ROOT / shim_directory_path)
+
+    assert all_probe_results["exported_names"] == sorted(_ALL_EXPORTED_HELPER_NAMES)