claude-dev-env 7.5.0 → 7.6.0

package/scripts/tests/test_policy_lint_rules_pairing.py

@@ -70,6 +70,37 @@ def test_approved_pairs_name_files_that_exist() -> None:
             assert (repository_root / each_test_path).is_file(), each_test_path
 
 
+def test_every_approved_pair_actually_waives_its_production_file(tmp_path: Path) -> None:
+    """Each mapping entry must silence the rule when its production file changes.
+
+    File existence alone leaves an entry inert when its key carries a suffix the
+    rule skips, or when its value is not a name the rule reads as a test.
+    """
+    for (
+        production_path,
+        all_test_paths,
+    ) in APPROVED_TEST_PATHS_BY_PRODUCTION_PATH.items():
+        production_document = Document(
+            production_path,
+            _BODY_AFTER,
+            _BODY_BEFORE,
+            frozenset({1}),
+            ContentOrigin.REVISION_DIFF,
+        )
+        for each_test_path in all_test_paths:
+            test_document = Document(
+                each_test_path,
+                _BODY_AFTER,
+                _BODY_BEFORE,
+                frozenset({1}),
+                ContentOrigin.REVISION_DIFF,
+            )
+            document_set = DocumentSet(
+                (production_document, test_document), SelectionKind.BASE, tmp_path
+            )
+            assert adapters.test_pairing_diagnostics(document_set) == (), production_path
+
+
 def test_pairing_ignores_python_docstring_only_changes(tmp_path: Path) -> None:
     all_diagnostics = _pairing_diagnostics(
         tmp_path,
@@ -161,3 +192,347 @@ def test_pairing_rejects_an_unrelated_module_beside_a_changed_approved_suite(
         _body_change_at(_APPROVED_TEST_PATH),
     )
     assert all_paths == (_UNRELATED_PRODUCTION_PATH,)
+
+
+_MECHANICAL_BEFORE = '''"""Before."""
+
+import subprocess
+
+TIMEOUT_SECONDS = 5
+
+
+def work(command: list[str]) -> int:
+    """Run one command."""
+    if TIMEOUT_SECONDS > 0:
+        completed = subprocess.run(command, timeout=TIMEOUT_SECONDS, check=False)
+        return completed.returncode
+    return 1
+'''
+_KEYWORD_ADDED = '''"""Before."""
+
+import subprocess
+
+TIMEOUT_SECONDS = 5
+
+
+def work(command: list[str]) -> int:
+    """Run one command."""
+    if TIMEOUT_SECONDS > 0:
+        completed = subprocess.run(
+            command, timeout=TIMEOUT_SECONDS, check=False, creationflags=0
+        )
+        return completed.returncode
+    return 1
+'''
+_IMPORT_AND_KEYWORD_ADDED = '''"""Before."""
+
+import os
+import subprocess
+
+TIMEOUT_SECONDS = 5
+
+
+def work(command: list[str]) -> int:
+    """Run one command."""
+    if TIMEOUT_SECONDS > 0:
+        completed = subprocess.run(
+            command, timeout=TIMEOUT_SECONDS, check=False, creationflags=os.O_RDONLY
+        )
+        return completed.returncode
+    return 1
+'''
+_DOCSTRING_AND_KEYWORD_CHANGED = '''"""After."""
+
+import subprocess
+
+TIMEOUT_SECONDS = 5
+
+
+def work(command: list[str]) -> int:
+    """Run one command and report its exit status."""
+    if TIMEOUT_SECONDS > 0:
+        completed = subprocess.run(
+            command, timeout=TIMEOUT_SECONDS, check=False, creationflags=0
+        )
+        return completed.returncode
+    return 1
+'''
+_KEYWORD_ADDED_AND_LITERAL_CHANGED = '''"""Before."""
+
+import subprocess
+
+TIMEOUT_SECONDS = 6
+
+
+def work(command: list[str]) -> int:
+    """Run one command."""
+    if TIMEOUT_SECONDS > 0:
+        completed = subprocess.run(
+            command, timeout=TIMEOUT_SECONDS, check=False, creationflags=0
+        )
+        return completed.returncode
+    return 1
+'''
+_KEYWORD_VALUE_CHANGED = '''"""Before."""
+
+import subprocess
+
+TIMEOUT_SECONDS = 5
+
+
+def work(command: list[str]) -> int:
+    """Run one command."""
+    if TIMEOUT_SECONDS > 0:
+        completed = subprocess.run(command, timeout=TIMEOUT_SECONDS, check=True)
+        return completed.returncode
+    return 1
+'''
+_KEYWORD_VALUE_TYPE_CHANGED = '''"""Before."""
+
+import subprocess
+
+TIMEOUT_SECONDS = 5
+
+
+def work(command: list[str]) -> int:
+    """Run one command."""
+    if TIMEOUT_SECONDS > 0:
+        completed = subprocess.run(command, timeout=TIMEOUT_SECONDS, check=0)
+        return completed.returncode
+    return 1
+'''
+_KEYWORD_REMOVED = '''"""Before."""
+
+import subprocess
+
+TIMEOUT_SECONDS = 5
+
+
+def work(command: list[str]) -> int:
+    """Run one command."""
+    if TIMEOUT_SECONDS > 0:
+        completed = subprocess.run(command, timeout=TIMEOUT_SECONDS)
+        return completed.returncode
+    return 1
+'''
+_POSITIONAL_CHANGED = '''"""Before."""
+
+import subprocess
+
+TIMEOUT_SECONDS = 5
+
+
+def work(command: list[str]) -> int:
+    """Run one command."""
+    if TIMEOUT_SECONDS > 0:
+        completed = subprocess.run(
+            command[:1], timeout=TIMEOUT_SECONDS, check=False, creationflags=0
+        )
+        return completed.returncode
+    return 1
+'''
+_STATEMENT_ADDED_IN_BODY = '''"""Before."""
+
+import subprocess
+
+TIMEOUT_SECONDS = 5
+
+
+def work(command: list[str]) -> int:
+    """Run one command."""
+    if TIMEOUT_SECONDS > 0:
+        completed = subprocess.run(
+            command, timeout=TIMEOUT_SECONDS, check=False, creationflags=0
+        )
+        completed.check_returncode()
+        return completed.returncode
+    return 1
+'''
+_CONDITION_CHANGED = '''"""Before."""
+
+import subprocess
+
+TIMEOUT_SECONDS = 5
+
+
+def work(command: list[str]) -> int:
+    """Run one command."""
+    if TIMEOUT_SECONDS > 1:
+        completed = subprocess.run(
+            command, timeout=TIMEOUT_SECONDS, check=False, creationflags=0
+        )
+        return completed.returncode
+    return 1
+'''
+_IMPORT_REMOVED = '''"""Before."""
+
+TIMEOUT_SECONDS = 5
+
+
+def work(command: list[str]) -> int:
+    """Run one command."""
+    if TIMEOUT_SECONDS > 0:
+        completed = subprocess.run(
+            command, timeout=TIMEOUT_SECONDS, check=False, creationflags=0
+        )
+        return completed.returncode
+    return 1
+'''
+_UNPARSEABLE = "def work(:\n    return None\n"
+
+
+def _mechanical_diagnostics(
+    temporary_path: Path, current_source: str, suffix: str = ".py"
+) -> tuple[Diagnostic, ...]:
+    return _pairing_diagnostics(
+        temporary_path,
+        _changed_document(current_source, _MECHANICAL_BEFORE, suffix),
+    )
+
+
+def test_pairing_waives_one_added_keyword_argument(tmp_path: Path) -> None:
+    assert _mechanical_diagnostics(tmp_path, _KEYWORD_ADDED) == ()
+
+
+def test_pairing_waives_an_added_import_beside_an_added_keyword(
+    tmp_path: Path,
+) -> None:
+    assert _mechanical_diagnostics(tmp_path, _IMPORT_AND_KEYWORD_ADDED) == ()
+
+
+def test_pairing_waives_a_docstring_edit_beside_an_added_keyword(
+    tmp_path: Path,
+) -> None:
+    assert _mechanical_diagnostics(tmp_path, _DOCSTRING_AND_KEYWORD_CHANGED) == ()
+
+
+def test_pairing_reports_an_added_keyword_beside_a_changed_literal(
+    tmp_path: Path,
+) -> None:
+    assert (
+        len(_mechanical_diagnostics(tmp_path, _KEYWORD_ADDED_AND_LITERAL_CHANGED)) == 1
+    )
+
+
+def test_pairing_reports_a_changed_keyword_value(tmp_path: Path) -> None:
+    assert len(_mechanical_diagnostics(tmp_path, _KEYWORD_VALUE_CHANGED)) == 1
+
+
+def test_pairing_reports_a_keyword_value_that_changed_literal_type(
+    tmp_path: Path,
+) -> None:
+    assert len(_mechanical_diagnostics(tmp_path, _KEYWORD_VALUE_TYPE_CHANGED)) == 1
+
+
+def test_pairing_reports_a_removed_keyword(tmp_path: Path) -> None:
+    assert len(_mechanical_diagnostics(tmp_path, _KEYWORD_REMOVED)) == 1
+
+
+def test_pairing_reports_a_changed_positional_argument(tmp_path: Path) -> None:
+    assert len(_mechanical_diagnostics(tmp_path, _POSITIONAL_CHANGED)) == 1
+
+
+def test_pairing_reports_a_statement_added_inside_a_function(tmp_path: Path) -> None:
+    assert len(_mechanical_diagnostics(tmp_path, _STATEMENT_ADDED_IN_BODY)) == 1
+
+
+def test_pairing_reports_a_changed_if_condition(tmp_path: Path) -> None:
+    assert len(_mechanical_diagnostics(tmp_path, _CONDITION_CHANGED)) == 1
+
+
+def test_pairing_reports_a_removed_import(tmp_path: Path) -> None:
+    assert len(_mechanical_diagnostics(tmp_path, _IMPORT_REMOVED)) == 1
+
+
+def test_pairing_reports_a_non_python_document_with_the_same_shape(
+    tmp_path: Path,
+) -> None:
+    assert len(_mechanical_diagnostics(tmp_path, _KEYWORD_ADDED, ".ts")) == 1
+
+
+def test_pairing_reports_unparseable_current_source(tmp_path: Path) -> None:
+    assert len(_mechanical_diagnostics(tmp_path, _UNPARSEABLE)) == 1
+
+
+def test_pairing_reports_unparseable_prior_source(tmp_path: Path) -> None:
+    all_diagnostics = _pairing_diagnostics(
+        tmp_path, _changed_document(_KEYWORD_ADDED, _UNPARSEABLE)
+    )
+    assert len(all_diagnostics) == 1
+
+
+def test_pairing_reports_an_added_document_without_prior_text(tmp_path: Path) -> None:
+    added_document = Document(
+        PurePosixPath("src/feature.py"),
+        _KEYWORD_ADDED,
+        None,
+        frozenset({1}),
+        ContentOrigin.REVISION_DIFF,
+    )
+    assert len(_pairing_diagnostics(tmp_path, added_document)) == 1
+
+
+_MAPPING_UNPACKING_ADDED = '''"""Before."""
+
+import subprocess
+
+TIMEOUT_SECONDS = 5
+
+
+def work(command: list[str]) -> int:
+    """Run one command."""
+    if TIMEOUT_SECONDS > 0:
+        completed = subprocess.run(
+            command, timeout=TIMEOUT_SECONDS, check=False, **{"creationflags": 0}
+        )
+        return completed.returncode
+    return 1
+'''
+
+
+def test_pairing_reports_added_mapping_unpacking_on_a_call(tmp_path: Path) -> None:
+    assert len(_mechanical_diagnostics(tmp_path, _MAPPING_UNPACKING_ADDED)) == 1
+_INSTALLER_PRODUCTION_PATHS = (
+    PurePosixPath("packages/claude-dev-env/bin/install-constants.mjs"),
+    PurePosixPath("packages/claude-dev-env/bin/install.mjs"),
+)
+_INSTALLER_SUITE_PATH = PurePosixPath(
+    "packages/claude-dev-env/bin/install.cursor-rules.test.mjs"
+)
+
+
+def test_pairing_accepts_installer_modules_with_the_cursor_rules_suite(
+    tmp_path: Path,
+) -> None:
+    all_paths = _diagnostic_paths(
+        tmp_path,
+        *(_body_change_at(each_path) for each_path in _INSTALLER_PRODUCTION_PATHS),
+        _body_change_at(_INSTALLER_SUITE_PATH),
+    )
+    assert all_paths == ()
+
+
+_COMMENT_RULES_PRODUCTION_PATH = PurePosixPath(
+    "packages/claude-dev-env/hooks/blocking/code_rules_comments.py"
+)
+_COMMENT_RULES_SUITE_PATH = PurePosixPath(
+    "packages/claude-dev-env/hooks/blocking/test_code_rules_enforcer_comment_string_awareness.py"
+)
+
+
+def test_pairing_accepts_comment_rules_module_with_one_approved_suite(
+    tmp_path: Path,
+) -> None:
+    all_paths = _diagnostic_paths(
+        tmp_path,
+        _body_change_at(_COMMENT_RULES_PRODUCTION_PATH),
+        _body_change_at(_COMMENT_RULES_SUITE_PATH),
+    )
+    assert all_paths == ()
+
+
+def test_pairing_rejects_comment_rules_module_without_any_approved_suite(
+    tmp_path: Path,
+) -> None:
+    all_paths = _diagnostic_paths(tmp_path, _body_change_at(_COMMENT_RULES_PRODUCTION_PATH))
+    assert all_paths == (_COMMENT_RULES_PRODUCTION_PATH,)

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_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,9 @@ 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)
 )
@@ -501,3 +505,33 @@ def test_files_missing_path_should_still_raise(tmp_path: Path) -> None:
 
     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)