claude-dev-env 2.14.1 → 2.15.1

package/scripts/AGENTS.md

@@ -37,7 +37,6 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 |---|---|
 | `ci/` | CI-only adapters; `windows-installer-lifecycle.ps1` runs the Node installer 16-check driver under isolated HOME/USERPROFILE/GIT_CONFIG_GLOBAL and writes bounded evidence |
 | `dev_env_scripts_constants/` | Named constants (`timing.py`, `grok_worker_constants.py`, …) for scripts in this directory, including worker-advisor placeholder launcher/model/effort, four verdict signals, correction cap, and advisor timeout |
-| `profile-isolation-launchers/` | Profile-launcher contract plus MCP activation, Windows shortcut source semantics, and version preflight: profiles manifest, shared-path allowlist, profile resolver, `CLAUDE_CONFIG_DIR` authority, lean/full MCP bundle materialization into profile `mcp.json`, pure CLI/Desktop version-compatibility classifier consumed by launcher preflight, read-only shortcut inventory and preview reconcile under `windows/`. Live launcher execution, provenance pin, live shortcut mutation, and L1 deploy stay residual |
 | `sync_to_cursor/` | Package that builds Cursor `.mdc` files from Claude rules and docs |
 | `tests/` | pytest suite for the Python scripts and Pester (`*.Tests.ps1`) suite for the PowerShell scripts in this directory |
 
@@ -49,12 +48,6 @@ Python scripts (pytest):
 python -m pytest packages/claude-dev-env/scripts/tests/
 ```
 
-Profile-isolation launcher contract (node:test):
-
-```bash
-node --test packages/claude-dev-env/scripts/profile-isolation-launchers/**/*.test.mjs
-```
-
 PowerShell scripts (Pester 5+, `*.Tests.ps1`):
 
 ```powershell

package/scripts/claude_chain_runner.py

@@ -48,7 +48,9 @@ import os
 import subprocess
 import sys
 import tempfile
-from collections.abc import Callable, Sequence
+import threading
+from collections.abc import Callable, Iterator, Sequence
+from contextlib import contextmanager
 from dataclasses import dataclass, field
 from pathlib import Path
 from types import ModuleType
@@ -327,6 +329,35 @@ class WeeklyUsageAccountReport(Protocol):
 
 
 chain_subprocess_runner = _run_captured_subprocess
+_shared_chain_subprocess_lock = threading.Lock()
+
+
+def chain_subprocess_runner_lock() -> threading.Lock:
+    """Return the lock for adapters that temporarily configure the runner."""
+    return _shared_chain_subprocess_lock
+
+
+@contextmanager
+def override_chain_subprocess_runner(
+    replacement_runner: Callable[..., subprocess.CompletedProcess[str]],
+) -> Iterator[Callable[..., subprocess.CompletedProcess[str]]]:
+    """Temporarily replace the chain subprocess seam under its shared lock.
+
+    Args:
+        replacement_runner: Callable used for subprocess invocations during the
+            context.
+
+    Yields:
+        The runner that was active before the replacement.
+    """
+    global chain_subprocess_runner
+    with chain_subprocess_runner_lock():
+        previous_runner = chain_subprocess_runner
+        chain_subprocess_runner = replacement_runner
+        try:
+            yield previous_runner
+        finally:
+            chain_subprocess_runner = previous_runner
 
 
 def _load_chain_usage_module() -> ModuleType:
@@ -1138,6 +1169,22 @@ def _persist_served_affinity(
         return
 
 
+def _run_cli_chain(
+    all_claude_arguments: list[str],
+    *,
+    timeout_seconds: int,
+    stdin_text: str | None,
+    routing_mode: str,
+) -> ChainInvocationOutcome:
+    """Run the CLI-selected chain arguments through the public runner."""
+    return run_claude(
+        all_claude_arguments,
+        timeout_seconds=timeout_seconds,
+        stdin_text=stdin_text,
+        routing_mode=routing_mode,
+    )
+
+
 def _build_argument_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         description="Run a claude invocation through the fallback chain."
@@ -1206,7 +1253,7 @@ def main(all_command_arguments: list[str]) -> int:
     all_claude_arguments = _strip_leading_separator(parsed_arguments.passthrough)
     maybe_stdin_text = _read_piped_stdin_text()
     try:
-        chain_outcome = run_claude(
+        chain_outcome = _run_cli_chain(
             all_claude_arguments,
             timeout_seconds=parsed_arguments.timeout_seconds,
             stdin_text=maybe_stdin_text,

package/scripts/invoke_code_review.py

@@ -28,20 +28,30 @@ import argparse
 import json
 import subprocess
 import sys
-import threading
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass
 from pathlib import Path
 
-if str(Path(__file__).resolve().parent) not in sys.path:
-    sys.path.insert(0, str(Path(__file__).resolve().parent))
+_scripts_directory_path = Path(__file__).resolve().parent
+_scripts_directory = str(_scripts_directory_path)
+sys.path[:] = [
+    each_existing_entry
+    for each_existing_entry in sys.path
+    if each_existing_entry != _scripts_directory
+]
+sys.path[:0] = [_scripts_directory]
 
 _advisor_scripts_path = str(
-    Path(__file__).resolve().parent.parent / "_shared" / "advisor" / "scripts"
+    _scripts_directory_path.parent / "_shared" / "advisor" / "scripts"
 )
-if _advisor_scripts_path not in sys.path:
-    sys.path.insert(0, _advisor_scripts_path)
+sys.path[:] = [
+    each_existing_entry
+    for each_existing_entry in sys.path
+    if each_existing_entry != _advisor_scripts_path
+]
+sys.path[:0] = [_advisor_scripts_path]
 
+from tier_model_ids import detect_host_profile  # noqa: E402
 from advisor_scripts_constants.model_tier_run_validator_constants import (  # noqa: E402
     HOST_PROFILE_CLAUDE,
 )
@@ -93,14 +103,6 @@ from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
 from dev_env_scripts_constants.timing import (  # noqa: E402
     DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS,
 )
-from tier_model_ids import detect_host_profile  # noqa: E402
-
-_CHAIN_RUNNER_LOCK = threading.Lock()
-
-
-def _chain_runner_lock() -> threading.Lock:
-    """Return the module lock that serializes chain-runner stdin/cwd swaps."""
-    return _CHAIN_RUNNER_LOCK
 
 
 @dataclass(frozen=True)
@@ -302,44 +304,39 @@ def _run_claude_with_empty_stdin(
     working_directory: Path,
 ) -> ChainInvocationOutcome:
     working_directory_path = str(working_directory)
-    with _CHAIN_RUNNER_LOCK:
-        previous_runner: TextCapturingSubprocessRunner = (
-            chain_runner.chain_subprocess_runner
-        )
 
-        def _runner_with_empty_stdin(
-            all_invocation_tokens: Sequence[str],
-            *all_positionals: object,
-            **all_keywords: object,
-        ) -> subprocess.CompletedProcess[str]:
-            del all_positionals
-            maybe_timeout = all_keywords.get("timeout")
-            timeout_for_run: float | None
-            if isinstance(maybe_timeout, (int, float)):
-                timeout_for_run = float(maybe_timeout)
-            else:
-                timeout_for_run = None
-            forwarded_text_codec = collect_forwarded_text_codec(all_keywords)
-            completed_process: subprocess.CompletedProcess[str] = previous_runner(
-                all_invocation_tokens,
-                capture_output=True,
-                text=True,
-                timeout=timeout_for_run,
-                check=False,
-                stdin=subprocess.DEVNULL,
-                cwd=working_directory_path,
-                **forwarded_text_codec,
-            )
-            return completed_process
-
-        empty_stdin_runner: TextCapturingSubprocessRunner = _runner_with_empty_stdin
-        setattr(chain_runner, "chain_subprocess_runner", empty_stdin_runner)
-        try:
-            return review_claude_runner(
-                all_claude_arguments, timeout_seconds=timeout_seconds
-            )
-        finally:
-            setattr(chain_runner, "chain_subprocess_runner", previous_runner)
+    def _runner_with_empty_stdin(
+        all_invocation_tokens: Sequence[str],
+        *all_positionals: object,
+        **all_keywords: object,
+    ) -> subprocess.CompletedProcess[str]:
+        del all_positionals
+        maybe_timeout = all_keywords.get("timeout")
+        timeout_for_run: float | None
+        if isinstance(maybe_timeout, (int, float)):
+            timeout_for_run = float(maybe_timeout)
+        else:
+            timeout_for_run = None
+        forwarded_text_codec = collect_forwarded_text_codec(all_keywords)
+        completed_process: subprocess.CompletedProcess[str] = previous_runner(
+            all_invocation_tokens,
+            capture_output=True,
+            text=True,
+            timeout=timeout_for_run,
+            check=False,
+            stdin=subprocess.DEVNULL,
+            cwd=working_directory_path,
+            **forwarded_text_codec,
+        )
+        return completed_process
+
+    empty_stdin_runner: TextCapturingSubprocessRunner = _runner_with_empty_stdin
+    with chain_runner.override_chain_subprocess_runner(
+        empty_stdin_runner
+    ) as previous_runner:
+        return review_claude_runner(
+            all_claude_arguments, timeout_seconds=timeout_seconds
+        )
 
 
 def _in_session_outcome() -> CodeReviewOutcome:

package/scripts/resolve_worker_spawn.py

@@ -26,21 +26,31 @@ import argparse
 import json
 import subprocess
 import sys
-import threading
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass
 from pathlib import Path
 from typing import IO
 
-if str(Path(__file__).resolve().parent) not in sys.path:
-    sys.path.insert(0, str(Path(__file__).resolve().parent))
+_scripts_directory_path = Path(__file__).resolve().parent
+_scripts_directory = str(_scripts_directory_path)
+sys.path[:] = [
+    each_existing_entry
+    for each_existing_entry in sys.path
+    if each_existing_entry != _scripts_directory
+]
+sys.path[:0] = [_scripts_directory]
 
 _advisor_scripts_path = str(
-    Path(__file__).resolve().parent.parent / "_shared" / "advisor" / "scripts"
+    _scripts_directory_path.parent / "_shared" / "advisor" / "scripts"
 )
-if _advisor_scripts_path not in sys.path:
-    sys.path.insert(0, _advisor_scripts_path)
+sys.path[:] = [
+    each_existing_entry
+    for each_existing_entry in sys.path
+    if each_existing_entry != _advisor_scripts_path
+]
+sys.path[:0] = [_advisor_scripts_path]
 
+from tier_model_ids import detect_host_profile  # noqa: E402
 from advisor_scripts_constants.model_tier_run_validator_constants import (  # noqa: E402
     HOST_PROFILE_CLAUDE,
 )
@@ -94,14 +104,6 @@ from grok_headless_runner import (  # noqa: E402
     run_headless_worker,
 )
 from grok_worker_preflight import PreflightOutcome, run_preflight  # noqa: E402
-from tier_model_ids import detect_host_profile  # noqa: E402
-
-_HEADLESS_CHAIN_RUNNER_LOCK = threading.Lock()
-
-
-def _headless_chain_runner_lock() -> threading.Lock:
-    """Return the module lock that serializes headless chain-runner swaps."""
-    return _HEADLESS_CHAIN_RUNNER_LOCK
 
 
 @dataclass(frozen=True)
@@ -184,41 +186,34 @@ def _run_claude_with_headless_overrides(
     prompt_stdin: IO[str],
 ) -> ChainInvocationOutcome:
     working_directory_path = str(working_directory)
-    with _HEADLESS_CHAIN_RUNNER_LOCK:
-        previous_runner: TextCapturingSubprocessRunner = (
-            chain_runner.chain_subprocess_runner
-        )
 
-        def _runner_with_headless_overrides(
-            all_invocation_tokens: Sequence[str],
-            *all_positionals: object,
-            **all_keywords: object,
-        ) -> subprocess.CompletedProcess[str]:
-            del all_positionals
-            prompt_stdin.seek(0)
-            forwarded_text_codec = collect_forwarded_text_codec(all_keywords)
-            completed_process: subprocess.CompletedProcess[str] = previous_runner(
-                all_invocation_tokens,
-                capture_output=True,
-                text=True,
-                timeout=_timeout_seconds_from_keywords(all_keywords),
-                check=False,
-                stdin=prompt_stdin,
-                cwd=working_directory_path,
-                **forwarded_text_codec,
-            )
-            return completed_process
-
-        headless_runner: TextCapturingSubprocessRunner = (
-            _runner_with_headless_overrides
+    def _runner_with_headless_overrides(
+        all_invocation_tokens: Sequence[str],
+        *all_positionals: object,
+        **all_keywords: object,
+    ) -> subprocess.CompletedProcess[str]:
+        del all_positionals
+        prompt_stdin.seek(0)
+        forwarded_text_codec = collect_forwarded_text_codec(all_keywords)
+        completed_process: subprocess.CompletedProcess[str] = previous_runner(
+            all_invocation_tokens,
+            capture_output=True,
+            text=True,
+            timeout=_timeout_seconds_from_keywords(all_keywords),
+            check=False,
+            stdin=prompt_stdin,
+            cwd=working_directory_path,
+            **forwarded_text_codec,
+        )
+        return completed_process
+
+    headless_runner: TextCapturingSubprocessRunner = _runner_with_headless_overrides
+    with chain_runner.override_chain_subprocess_runner(
+        headless_runner
+    ) as previous_runner:
+        return spawn_claude_runner(
+            all_claude_arguments, timeout_seconds=timeout_seconds
         )
-        setattr(chain_runner, "chain_subprocess_runner", headless_runner)
-        try:
-            return spawn_claude_runner(
-                all_claude_arguments, timeout_seconds=timeout_seconds
-            )
-        finally:
-            setattr(chain_runner, "chain_subprocess_runner", previous_runner)
 
 
 def _prompt_file_unreadable_outcome(

package/scripts/sync_to_cursor/AGENTS.md

@@ -6,12 +6,12 @@ Python package that syncs Claude rules and docs to Cursor `.mdc` files. Entry po
 
 | File | Purpose |
 |---|---|
-| `engine.py` | Main sync logic: loads the manifest, builds rule mappings, hashes sources, writes `.mdc` files, and updates the manifest |
-| `rules.py` | Builds `RuleMapping` objects from Claude rule markdown files; applies transforms to fit Cursor's `.mdc` format |
+| `engine.py` | Main sync logic: loads the manifest, builds rule mappings, hashes sources, writes `.mdc` files, and updates the manifest; `--claude-root` and `--cursor-root` select explicit layouts |
+| `rules.py` | Builds `RuleMapping` objects from Claude rule markdown files; applies transforms to fit Cursor's `.mdc` format; maps remaining `rules/*.md` files to `<stem>.mdc` |
 | `canonical_docs.py` | Checks and syncs canonical documentation files (`CODE_RULES.md`, `TEST_QUALITY.md`) to the Cursor rules directory |
 | `paths.py` | Resolves the Claude and Cursor layout paths; respects the `LLM_SETTINGS_ROOT` env var for non-home layouts |
 | `hashing.py` | SHA-256 helpers that detect whether source files changed since the last sync run |
-| `config.py` | Package-level constants: `GENERATOR_VERSION`, `CANONICAL_DOC_FILES`, `MAX_RULE_BODY_LINES` |
+| `config/` | Package-level constants: `GENERATOR_VERSION`, `ALL_CANONICAL_DOC_FILES`, `MAX_RULE_BODY_LINES`, skipped inventory filenames, markdown suffix |
 | `__init__.py` | Empty package marker |
 
 ## Layout resolution

package/scripts/sync_to_cursor/canonical_docs.py

@@ -3,7 +3,7 @@
 import shutil
 from pathlib import Path
 
-from sync_to_cursor.config import CANONICAL_DOC_FILES
+from sync_to_cursor.config import ALL_CANONICAL_DOC_FILES
 from sync_to_cursor.hashing import sha256_bytes
 
 
@@ -17,19 +17,19 @@ def sync_canonical_docs(
     if not dry_run:
         docs_out.mkdir(parents=True, exist_ok=True)
     new_docs: dict = {}
-    for name in CANONICAL_DOC_FILES:
-        src = claude / "docs" / name
-        dst = docs_out / name
+    for each_name in ALL_CANONICAL_DOC_FILES:
+        src = claude / "docs" / each_name
+        dst = docs_out / each_name
         if not src.is_file():
             if dst.is_file():
                 if not dry_run:
                     dst.unlink()
                 if not quiet:
-                    print(f"WARN     docs/{name} (source removed — deleted stale copy at {dst})")
+                    print(f"WARN     docs/{each_name} (source removed — deleted stale copy at {dst})")
             elif not quiet:
-                print(f"WARN     docs/{name} (missing source: {src})")
+                print(f"WARN     docs/{each_name} (missing source: {src})")
             continue
-        key = f"docs/{name}"
+        key = f"docs/{each_name}"
         src_hash = sha256_bytes(src.read_bytes())
         if dry_run:
             if dst.is_file():
@@ -44,10 +44,10 @@ def sync_canonical_docs(
 
 
 def check_canonical_docs(claude: Path, cursor: Path, docs_entries: dict) -> bool:
-    for name in CANONICAL_DOC_FILES:
-        key = f"docs/{name}"
-        src = claude / "docs" / name
-        dst = cursor / "docs" / name
+    for each_name in ALL_CANONICAL_DOC_FILES:
+        key = f"docs/{each_name}"
+        src = claude / "docs" / each_name
+        dst = cursor / "docs" / each_name
         if not src.is_file():
             if key in docs_entries:
                 return False

package/scripts/sync_to_cursor/config/__init__.py

@@ -0,0 +1,8 @@
+"""Shared configuration for the sync-to-cursor package."""
+
+GENERATOR_VERSION: str = "1.3.0"
+ALL_CANONICAL_DOC_FILES: tuple[str, ...] = ("CODE_RULES.md", "TEST_QUALITY.md")
+MAX_RULE_BODY_LINES: int = 50
+ALL_SKIPPED_RULE_FILE_NAMES: frozenset[str] = frozenset({"CLAUDE.md", "AGENTS.md"})
+MARKDOWN_SUFFIX: str = ".md"
+CLAUDE_RULES_DIRECTORY_NAME: str = "rules"

package/scripts/sync_to_cursor/engine.py

@@ -140,15 +140,40 @@ def _sync_rules(
     return summary, new_entries
 
 
+def _layout_from_args(args: argparse.Namespace) -> tuple[Path, Path, Path, Path]:
+    """Resolve Claude and Cursor roots from flags or the default layout.
+
+    Args:
+        args: Parsed CLI arguments.
+
+    Returns:
+        Claude root, Cursor root, rules output directory, and manifest path.
+
+    Raises:
+        SystemExit: When only one of `--claude-root` / `--cursor-root` is set.
+    """
+    claude_root = args.claude_root
+    cursor_root = args.cursor_root
+    if (claude_root is None) != (cursor_root is None):
+        raise SystemExit("both --claude-root and --cursor-root are required")
+    if claude_root is None:
+        return llm_layout_paths()
+    claude = Path(claude_root).expanduser().resolve()
+    cursor = Path(cursor_root).expanduser().resolve()
+    return claude, cursor, cursor / "rules", cursor / ".sync-manifest.json"
+
+
 def run(argv: list[str] | None = None) -> int:
     argument_parser = argparse.ArgumentParser(description="Sync Claude rules to Cursor .mdc files")
     argument_parser.add_argument("--force", action="store_true", help="Regenerate all outputs")
     argument_parser.add_argument("--dry-run", action="store_true", help="Print actions only")
     argument_parser.add_argument("--check", action="store_true", help="Exit 1 if anything stale")
     argument_parser.add_argument("--quiet", action="store_true", help="Minimal output when up to date")
+    argument_parser.add_argument("--claude-root", help="Claude layout root holding rules/ and docs/")
+    argument_parser.add_argument("--cursor-root", help="Cursor layout root receiving rules/ and docs/")
     args = argument_parser.parse_args(argv)
 
-    claude, cursor, out_dir, manifest_path = llm_layout_paths()
+    claude, cursor, out_dir, manifest_path = _layout_from_args(args)
     mappings = build_mappings(claude)
     old_manifest = _load_manifest(manifest_path)
     entries_meta: dict = old_manifest.get("entries", {})

package/scripts/sync_to_cursor/rules.py

@@ -7,7 +7,12 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Literal
 
-from sync_to_cursor.config import MAX_RULE_BODY_LINES
+from sync_to_cursor.config import (
+    ALL_SKIPPED_RULE_FILE_NAMES,
+    CLAUDE_RULES_DIRECTORY_NAME,
+    MARKDOWN_SUFFIX,
+    MAX_RULE_BODY_LINES,
+)
 
 
 def _parse_h2_sections(markdown: str) -> dict[str, str]:
@@ -412,6 +417,61 @@ def _path_scoped_mappings(rules_directory: Path, docs_directory: Path) -> tuple[
     )
 
 
+def _description_from_rule_file(rule_file: Path, fallback_key: str) -> str:
+    """Return the first markdown heading, or the rule key with spaces.
+
+    Args:
+        rule_file: Claude rule markdown to read.
+        fallback_key: Stem used when the file has no heading.
+
+    Returns:
+        A one-line Cursor `description` value.
+    """
+    for each_line in rule_file.read_text(encoding="utf-8").splitlines():
+        stripped = each_line.strip()
+        if stripped.startswith("# "):
+            return stripped[2:].strip()
+    return fallback_key.replace("-", " ")
+
+
+def _discovered_mappings(
+    rules_directory: Path, all_covered_source_names: set[str]
+) -> tuple[RuleMapping, ...]:
+    """Map remaining `*.md` rule files to `<stem>.mdc` Cursor rules.
+
+    Args:
+        rules_directory: Claude `rules/` directory.
+        all_covered_source_names: Rule filenames already claimed by curated mappings.
+
+    Returns:
+        One mapping per remaining markdown rule, sorted by filename.
+    """
+    if not rules_directory.is_dir():
+        return ()
+    all_discovered: list[RuleMapping] = []
+    for each_rule_file in sorted(rules_directory.glob("*.md")):
+        if each_rule_file.name in ALL_SKIPPED_RULE_FILE_NAMES:
+            continue
+        if each_rule_file.name in all_covered_source_names:
+            continue
+        key = each_rule_file.stem
+        paths_glob = _read_paths_glob(each_rule_file)
+        has_paths = paths_glob is not None
+        all_discovered.append(
+            RuleMapping(
+                key,
+                (each_rule_file,),
+                f"{key}.mdc",
+                not has_paths,
+                paths_glob,
+                _description_from_rule_file(each_rule_file, key),
+                "verbatim",
+                strip_leading_frontmatter=has_paths,
+            )
+        )
+    return tuple(all_discovered)
+
+
 def build_mappings(claude: Path) -> tuple[RuleMapping, ...]:
     """Resolve every rule into a concrete Cursor mapping against a Claude layout.
 
@@ -420,14 +480,25 @@ def build_mappings(claude: Path) -> tuple[RuleMapping, ...]:
 
     Returns:
         One RuleMapping per rule, each path-scoped rule carrying a glob derived
-        from its source rule's `paths:` frontmatter.
+        from its source rule's `paths:` frontmatter. Curated mappings come first,
+        then one generated mapping per remaining `rules/*.md` file.
     """
     rules_directory = claude / "rules"
     docs_directory = claude / "docs"
-    all_mappings = (
+    all_curated = (
         *_always_apply_mappings(rules_directory, docs_directory),
         *_path_scoped_mappings(rules_directory, docs_directory),
     )
-    mapping_by_key = {each_mapping.key: each_mapping for each_mapping in all_mappings}
+    mapping_by_key = {each_mapping.key: each_mapping for each_mapping in all_curated}
     assert set(mapping_by_key) == set(_merged_mapping_key_order)
-    return tuple(mapping_by_key[each_key] for each_key in _merged_mapping_key_order)
+    ordered_curated = tuple(mapping_by_key[each_key] for each_key in _merged_mapping_key_order)
+    all_covered_source_names = {
+        each_source.name
+        for each_mapping in ordered_curated
+        for each_source in each_mapping.sources
+        if each_source.suffix == MARKDOWN_SUFFIX
+        and each_source.parent.name == CLAUDE_RULES_DIRECTORY_NAME
+    }
+    return ordered_curated + _discovered_mappings(
+        rules_directory, all_covered_source_names
+    )

package/scripts/test_claude_chain_runner.py

@@ -17,6 +17,8 @@ import claude_chain_runner as runner  # noqa: E402
 import claude_chain_usage as chain_usage  # noqa: E402
 from claude_chain_runner import (  # noqa: E402
     ChainEntry,
+    chain_subprocess_runner_lock,
+    override_chain_subprocess_runner,
     default_affinity_state_path,
     extract_resume_session_id,
     load_affinity_store,
@@ -78,6 +80,32 @@ from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
 
 _LARGE_CAPTURE_BYTE_COUNT = 400_000
 _LARGE_CAPTURE_MARKER = "X"
+
+
+def test_chain_subprocess_runner_lock_is_shared() -> None:
+    first_lock = chain_subprocess_runner_lock()
+    second_lock = chain_subprocess_runner_lock()
+
+    assert first_lock is second_lock
+
+
+def test_override_chain_subprocess_runner_restores_previous_runner() -> None:
+    previous_runner = runner.chain_subprocess_runner
+
+    def replacement_runner(
+        all_invocation_tokens: list[str],
+        **all_keywords: object,
+    ) -> subprocess.CompletedProcess[str]:
+        del all_invocation_tokens, all_keywords
+        return subprocess.CompletedProcess([], 0, "", "")
+
+    with override_chain_subprocess_runner(replacement_runner) as active_runner:
+        assert active_runner is previous_runner
+        assert runner.chain_subprocess_runner is replacement_runner
+
+    assert runner.chain_subprocess_runner is previous_runner
+
+
 _STDIN_ECHO_PAYLOAD = "charter body for spool path"
 _UNDECODABLE_STDOUT_BYTES = b"ok \x90 end"
 _DECODED_UNDECODABLE_STDOUT = "ok \ufffd end"