@deftai/directive-content 0.55.2 → 0.56.0

package/scripts/_relocate_states.py

@@ -0,0 +1,343 @@
+"""_relocate_states.py -- state detection helpers for scripts/relocate.py (#992 PR2).
+
+Extracted from :mod:`scripts.relocate` to keep the parent module under the
+deft 1000-line MUST limit (mirrors the
+``scripts/cache.py`` / ``scripts/_cache_validate.py`` /
+``scripts/_cache_fetch.py`` split pattern from #883).
+
+Public API:
+
+- :func:`detect_install_state`         -- A/B/C/D/E/F/G classification.
+- :func:`detect_active_swarm`          -- True iff any vbrief/active is running.
+- :func:`active_swarm_paths`           -- list of running active vBRIEFs.
+- :func:`is_framework_customized`      -- True iff framework dir != source.
+- :func:`customization_paths`          -- list of customized files.
+- :func:`advise_external_hardcodes`    -- legacy ``deft/run`` grep.
+- :func:`iter_files`                   -- recursive regular-file walker.
+
+This module is intentionally pure-stdlib + pathlib so it imports cleanly
+under the same UTF-8 + Python 3.11 baseline as the rest of ``scripts/``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Iterator
+from pathlib import Path
+
+# Mirror the constants used by the parent module verbatim so a future
+# rename in scripts/relocate.py only needs to update one place. The
+# parent module re-imports these at module load.
+CANONICAL_FRAMEWORK_DIR: str = ".deft/core"
+LEGACY_FRAMEWORK_DIR: str = "deft"
+
+AGENTS_MANAGED_OPEN: str = "<!-- deft:managed-section v3 -->"
+AGENTS_MANAGED_CLOSE: str = "<!-- /deft:managed-section -->"
+
+# v2 -> v3 marker bump (#1046 PR-B AC-5). Detection MUST accept both forms
+# for one release cycle so consumers on v0.27.x still classify as having a
+# managed section after marker drift -- the relocator's regenerate path
+# will rewrite them to v3. The bare ``v3`` form is the template literal;
+# the regex's optional attribute group covers the per-refresh
+# ``sha=<sha> refreshed=<iso> session=<id>`` tokens emitted by
+# ``run::cmd_agents_refresh``.
+_AGENTS_MANAGED_OPEN_RE = re.compile(
+    r"<!--\s*deft:managed-section\s+v(2|3)(?:\s+[^>]*?)?\s*-->"
+)
+
+ADVISORY_LEGACY_TOKEN: str = "deft/run"
+
+ADVISORY_GREP_SKIP_DIRS: tuple[str, ...] = (
+    ".deft",
+    ".deft-cache",
+    LEGACY_FRAMEWORK_DIR,
+    ".git",
+    ".github",
+    ".venv",
+    ".pytest_cache",
+    "__pycache__",
+    "node_modules",
+    "dist",
+    "build",
+)
+
+ADVISORY_GREP_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        ".md",
+        ".txt",
+        ".yml",
+        ".yaml",
+        ".json",
+        ".toml",
+        ".sh",
+        ".ps1",
+        ".bat",
+        ".py",
+        ".go",
+        ".js",
+        ".ts",
+        ".rs",
+        ".rb",
+    }
+)
+
+_ADVISORY_GREP_MAX_BYTES: int = 1_000_000
+
+
+__all__ = [
+    "ADVISORY_GREP_EXTENSIONS",
+    "ADVISORY_GREP_SKIP_DIRS",
+    "ADVISORY_LEGACY_TOKEN",
+    "active_swarm_paths",
+    "advise_external_hardcodes",
+    "customization_paths",
+    "detect_active_swarm",
+    "detect_install_state",
+    "is_framework_customized",
+    "iter_files",
+]
+
+
+# ---------------------------------------------------------------------------
+# Filesystem walker
+# ---------------------------------------------------------------------------
+
+
+def iter_files(root: Path) -> Iterator[Path]:
+    """Yield every regular file under ``root`` recursively (no symlinks)."""
+    if not root.is_dir():
+        return
+    for entry in root.iterdir():
+        if entry.is_dir() and not entry.is_symlink():
+            yield from iter_files(entry)
+        elif entry.is_file():
+            yield entry
+
+
+# ---------------------------------------------------------------------------
+# State A / B / C / D / E / F / G classifier
+# ---------------------------------------------------------------------------
+
+
+def _has_managed_markers(text: str) -> bool:
+    # Accept both the v3 (canonical, #1046 PR-B AC-5) and v2 (legacy,
+    # one-release back-compat window) open markers so a v0.27.x consumer
+    # still classifies as state CANONICAL until the relocator rewrites the
+    # marker to v3. The close marker is shared across versions.
+    return (
+        _AGENTS_MANAGED_OPEN_RE.search(text) is not None
+        and AGENTS_MANAGED_CLOSE in text
+    )
+
+
+def detect_install_state(
+    project_root: Path,
+    *,
+    framework_source: Path | None = None,
+) -> str:
+    """Classify the consumer install layout (A/B/C/D/E/F/G/CANONICAL).
+
+    State G (active swarm) and state E (customized framework) are
+    pre-flight gates that take precedence over the layout states A-D
+    when present. The relocator's plan-builder consults the customization
+    + active-swarm probes independently so the full state vector is
+    available even on layout state C / D / etc.
+    """
+    legacy = project_root / LEGACY_FRAMEWORK_DIR
+    canonical = project_root / CANONICAL_FRAMEWORK_DIR
+    agents_md = project_root / "AGENTS.md"
+    vbrief_root = project_root / "vbrief"
+
+    legacy_present = legacy.is_dir()
+    canonical_present = canonical.is_dir()
+    agents_md_present = agents_md.is_file()
+    vbrief_present = vbrief_root.is_dir()
+
+    if detect_active_swarm(project_root):
+        return "G"
+
+    if framework_source is not None and (
+        (legacy_present and is_framework_customized(legacy, framework_source))
+        or (canonical_present and is_framework_customized(canonical, framework_source))
+    ):
+        return "E"
+
+    if legacy_present and canonical_present:
+        return "C"
+    if legacy_present and not canonical_present:
+        return "A"
+    if canonical_present and not legacy_present:
+        if not agents_md_present:
+            return "B"
+        try:
+            text = agents_md.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            return "B"
+        if not _has_managed_markers(text):
+            return "B"
+        return "CANONICAL"
+
+    if agents_md_present:
+        return "D"
+
+    return "F" if not vbrief_present else "D"
+
+
+# ---------------------------------------------------------------------------
+# State G -- active swarm probe
+# ---------------------------------------------------------------------------
+
+
+def detect_active_swarm(project_root: Path) -> bool:
+    """Return True iff any ``vbrief/active/*.vbrief.json`` has ``plan.status == "running"``."""
+    return bool(active_swarm_paths(project_root))
+
+
+def active_swarm_paths(project_root: Path) -> list[str]:
+    """Return the list of running-status active vBRIEF paths (project-relative)."""
+    active_dir = project_root / "vbrief" / "active"
+    if not active_dir.is_dir():
+        return []
+    paths: list[str] = []
+    for candidate in sorted(active_dir.glob("*.vbrief.json")):
+        try:
+            payload = json.loads(candidate.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        plan = payload.get("plan") if isinstance(payload, dict) else None
+        if not isinstance(plan, dict):
+            continue
+        if plan.get("status") == "running":
+            try:
+                rel = candidate.relative_to(project_root)
+            except ValueError:
+                rel = candidate
+            paths.append(rel.as_posix())
+    return paths
+
+
+# ---------------------------------------------------------------------------
+# State E -- customization detection
+# ---------------------------------------------------------------------------
+
+
+def _sha256_of(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(65_536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def is_framework_customized(framework_dir: Path, framework_source: Path) -> bool:
+    """Return True iff any file under ``framework_dir`` differs from ``framework_source``.
+
+    Two signals, in order:
+
+    1. Sentinel-marker fast-path -- ``framework_dir/.deft-customized``.
+       Test fixtures use this for deterministic state-E construction.
+    2. SHA-256 hash compare against the matching file in
+       ``framework_source``. A file present only in ``framework_dir`` (an
+       extra) also counts as customization.
+
+    The reverse direction (files in source but absent in framework_dir)
+    is NOT customization -- it just means the consumer is behind, which
+    is the relocator's whole job.
+    """
+    return bool(customization_paths(framework_dir, framework_source))
+
+
+def customization_paths(framework_dir: Path, framework_source: Path) -> list[str]:
+    """Return the project-relative paths that differ from ``framework_source``."""
+    if not framework_dir.is_dir():
+        return []
+
+    sentinel = framework_dir / ".deft-customized"
+    paths: list[str] = []
+    if sentinel.is_file():
+        try:
+            paths.append(sentinel.relative_to(framework_dir.parent).as_posix())
+        except ValueError:
+            paths.append(sentinel.name)
+
+    if not framework_source.is_dir():
+        return paths
+
+    for src_path in iter_files(framework_dir):
+        try:
+            rel = src_path.relative_to(framework_dir)
+        except ValueError:
+            continue
+        if rel.as_posix() == ".deft-customized":
+            continue
+        canonical = framework_source / rel
+        try:
+            project_rel = src_path.relative_to(framework_dir.parent).as_posix()
+        except ValueError:
+            project_rel = rel.as_posix()
+        if not canonical.is_file():
+            paths.append(project_rel)
+            continue
+        try:
+            if _sha256_of(src_path) != _sha256_of(canonical):
+                paths.append(project_rel)
+        except OSError:
+            paths.append(project_rel)
+    return paths
+
+
+# ---------------------------------------------------------------------------
+# Advisory grep -- find legacy `deft/run` hardcodes outside .deft/core/
+# ---------------------------------------------------------------------------
+
+
+def advise_external_hardcodes(
+    project_root: Path,
+    *,
+    token: str = ADVISORY_LEGACY_TOKEN,
+) -> list[tuple[str, int, str]]:
+    """Return the ``(rel_path, line_number, line_text)`` tuples for legacy hardcodes.
+
+    Skips ``.deft/``, ``.deft-cache/``, ``deft/`` (the legacy framework
+    dir, which the relocator may not have wiped yet on a dry-run), plus
+    standard development noise. Inspects only the curated set of text
+    extensions to keep the walk fast on large consumer repos.
+    """
+    hits: list[tuple[str, int, str]] = []
+    for path in _iter_consumer_text_files(project_root):
+        try:
+            rel = path.relative_to(project_root).as_posix()
+        except ValueError:
+            continue
+        try:
+            stat = path.stat()
+        except OSError:
+            continue
+        if stat.st_size > _ADVISORY_GREP_MAX_BYTES:
+            continue
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except (OSError, UnicodeDecodeError):
+            continue
+        if token not in text:
+            continue
+        for idx, line in enumerate(text.splitlines(), start=1):
+            if token in line:
+                hits.append((rel, idx, line.rstrip()))
+    return hits
+
+
+def _iter_consumer_text_files(project_root: Path) -> Iterator[Path]:
+    for path in iter_files(project_root):
+        try:
+            rel = path.relative_to(project_root)
+        except ValueError:
+            continue
+        first = rel.parts[0] if rel.parts else ""
+        if first in ADVISORY_GREP_SKIP_DIRS:
+            continue
+        if path.suffix.lower() not in ADVISORY_GREP_EXTENSIONS:
+            continue
+        yield path

package/scripts/_resolve_preflight_path.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""_resolve_preflight_path.py -- resolve preflight_implementation.py
+(#1046 PR-C AC-6 / absorbs #1047).
+
+Probes for the wrapped ``preflight_implementation.py`` script in three
+canonical locations under the supplied project root and prints the
+resolved absolute path on stdout, OR exits non-zero with a structured
+fail-closed error message that names the failure class and points the
+operator at ``task framework:doctor`` (the PR-B install-integrity probe
+landed in #1057).
+
+Why this helper exists
+----------------------
+
+The Implementation Intent Gate (#810) is a safety gate, not a routing
+gate. Its failure mode is silent fail-open: if the Taskfile target
+``tasks/vbrief.yml::preflight`` wraps a hardcoded path that does not
+resolve on the consumer's install layout, ``task vbrief:preflight``
+either errors loudly (and the agent treats the gate as unreachable and
+routes around it) or accidentally returns exit 0 (the gate emits
+"preflight passed" reasoning without ever evaluating the vBRIEF). Per
+issue #1047 the agent-side contract says #810 is in force on every
+``.deft/core/`` install, but the gate was structurally unreachable on
+those installs.
+
+Three layouts must resolve correctly:
+
+    1. ``<project-root>/.deft/core/scripts/preflight_implementation.py``
+       -- the v0.27+ canonical install layout (#992).
+    2. ``<project-root>/deft/scripts/preflight_implementation.py`` --
+       the legacy v0.20-v0.26 install layout.
+    3. ``<project-root>/scripts/preflight_implementation.py`` -- the
+       in-repo case when the deft framework itself is the project root.
+
+The resolver tries them in that order and returns the first match.
+When none match the resolver exits 2 with the structured error
+``gate misconfigured: cannot resolve preflight_implementation.py at
+any expected path -- run `task framework:doctor` for diagnostics`` so
+the wrapping Taskfile target propagates the non-zero exit instead of
+silently invoking ``uv run python <missing>`` and letting the gate's
+failure shape leak through to the agent.
+
+Mirrors the shape of ``scripts/resolve_version.py`` (#723): pure
+stdlib, ``main(argv) -> int``, a public Python API
+(``resolve_preflight_path(project_root)``) for tests and future
+callers, and a CLI for the Taskfile body.
+
+Refs:
+- #1046 (cohort)
+- #1047 (absorbed by PR-C)
+- #810 (the gate this resolver wraps)
+- #992 (the install layout flip that made the legacy hardcoded path stale)
+- #1054 (PR-A canonical-path enforcement)
+- #1057 (PR-B framework:doctor + manifest + v3 sentinel)
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+#: Candidate subpaths probed under the supplied project root, in
+#: priority order. The first existing file wins. Each entry is a tuple
+#: of path parts so :func:`pathlib.Path.joinpath` reconstructs the
+#: location with native separators on every platform.
+CANDIDATE_SUBPATHS: tuple[tuple[str, ...], ...] = (
+    (".deft", "core", "scripts", "preflight_implementation.py"),
+    ("deft", "scripts", "preflight_implementation.py"),
+    ("scripts", "preflight_implementation.py"),
+)
+
+#: Structured fail-closed error message. Names the failure class
+#: (``gate misconfigured``) so operators (and downstream parsers) can
+#: classify the exit without parsing free-form text, enumerates the
+#: probed layouts so a misconfigured install surfaces the expected
+#: locations, and points at ``task framework:doctor`` (the PR-B
+#: install-integrity probe from #1057) for the diagnostic surface.
+FAIL_CLOSED_MESSAGE = (
+    "gate misconfigured: cannot resolve preflight_implementation.py "
+    "at any expected path (.deft/core/scripts/, deft/scripts/, scripts/) "
+    "under project root {project_root} -- "
+    "run `task framework:doctor` for diagnostics."
+)
+
+
+def resolve_preflight_path(project_root: Path | str) -> Path | None:
+    """Probe the candidate subpaths under ``project_root``.
+
+    Returns the absolute resolved path of the first existing
+    ``preflight_implementation.py``, or ``None`` if no candidate
+    resolves. Pure function -- no I/O beyond ``Path.is_file()``.
+
+    The project root is resolved to an absolute path first so callers
+    that pass a relative path (e.g. ``"."`` from a Taskfile target
+    invoked under ``USER_WORKING_DIR``) get a stable absolute result.
+    """
+    root = Path(project_root).resolve()
+    for parts in CANDIDATE_SUBPATHS:
+        candidate = root.joinpath(*parts)
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="_resolve_preflight_path.py",
+        description=(
+            "Resolve preflight_implementation.py under the supplied "
+            "project root (#1046 PR-C / #1047). Probes the v0.27+ "
+            "canonical install layout (.deft/core/scripts/), the "
+            "legacy install layout (deft/scripts/), and the in-repo "
+            "case (scripts/) in that order. Prints the resolved "
+            "absolute path on stdout, or exits 2 with a structured "
+            "fail-closed error message naming the failure class and "
+            "pointing at `task framework:doctor`."
+        ),
+    )
+    parser.add_argument(
+        "--project-root",
+        default=".",
+        help=(
+            "Project root to probe. Defaults to the current working "
+            "directory so `task vbrief:preflight` can pass "
+            "{{.USER_WORKING_DIR}} through unchanged."
+        ),
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    project_root = Path(args.project_root)
+    resolved = resolve_preflight_path(project_root)
+    if resolved is None:
+        print(
+            FAIL_CLOSED_MESSAGE.format(project_root=project_root.resolve()),
+            file=sys.stderr,
+        )
+        return 2
+    # Print the resolved path on stdout WITHOUT a trailing newline so
+    # the Taskfile body can capture it via $(...) without trimming
+    # whitespace -- matches the convention from scripts/resolve_version.py
+    # which also uses raw stdout writes for the same reason.
+    sys.stdout.write(str(resolved))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/_safe_subprocess.py

@@ -0,0 +1,167 @@
+"""_safe_subprocess.py -- UTF-8-safe subprocess capture helper (#1366).
+
+Wraps :func:`subprocess.run` with the defaults required for reliable text
+capture under Windows hosts where the system codepage (cp1252 / cp437)
+otherwise corrupts non-ASCII bytes emitted by ``gh`` / Greptile rolling
+summaries and crashes one of Python's internal reader threads with
+``UnicodeDecodeError`` (the canonical ``Thread-3 (_readerthread)`` stack
+seen across the #1166 swarm session).
+
+Background
+----------
+The default ``subprocess.run(..., capture_output=True, text=True)`` binding
+uses ``locale.getpreferredencoding()`` to decode the child process's
+stdout / stderr streams. On Windows + Grok Build that resolves to the
+active codepage rather than UTF-8, so any byte the codepage cannot decode
+raises ``UnicodeDecodeError`` from inside the helper thread that drains
+the pipe. Once that thread crashes, the calling script returns no valid
+output on stdout (or crashes outright), and any dependent monitor that
+parses the JSON sees ``head: None`` / empty data.
+
+The fix is to force ``encoding="utf-8"`` and ``errors="replace"`` on every
+text-capturing subprocess call. ``replace`` substitutes the U+FFFD
+replacement character for any undecodable byte rather than raising; the
+parser downstream then sees a well-formed string with at most a handful
+of replacement glyphs in the otherwise-clean Greptile body.
+
+Usage
+-----
+
+    from _safe_subprocess import run_text
+
+    result = run_text(["gh", "api", "repos/<owner>/<repo>/pulls/<N>"])
+    if result.returncode == 0:
+        body = result.stdout
+
+Scope
+-----
+This helper covers the read-side text capture path that the #1366 root
+cause analysis identified. It is NOT a general-purpose ``subprocess.run``
+replacement -- callers that need binary streams (``capture_output=True``
+with ``text=False``) or process redirection should keep using
+``subprocess.run`` directly. The helper deliberately rejects ``shell=True``
+to keep injection-prone usage out of the framework's surface (per
+``coding/security.md`` Input Validation rules).
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+# Default timeout (seconds) when callers do not specify one. Mirrors the
+# 60s ceiling used by ``scripts/pr_merge_readiness.py::_run_gh`` so the
+# helper does not silently relax existing call-site timeouts.
+_DEFAULT_TIMEOUT_SECONDS = 60
+
+
+def run_text(  # noqa: A002 -- `input` parameter name mirrors subprocess.run
+    cmd: Sequence[str],
+    *,
+    timeout: float | None = _DEFAULT_TIMEOUT_SECONDS,
+    input: str | None = None,  # noqa: A002
+    cwd: str | None = None,
+    env: Mapping[str, str] | None = None,
+    check: bool = False,
+    **extra: Any,
+) -> subprocess.CompletedProcess[str]:
+    """Run ``cmd`` capturing stdout / stderr as UTF-8 text safely.
+
+    Equivalent to::
+
+        subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            ...,
+        )
+
+    with the following guarantees:
+
+    - ``encoding="utf-8"`` and ``errors="replace"`` are FORCED -- callers
+      cannot override them via ``**extra``. Any attempt is ignored so a
+      typo cannot reintroduce the cp1252 decode bug.
+    - ``capture_output=True`` is FORCED -- callers cannot accidentally
+      pass ``stdout=None`` / ``stderr=None`` and lose the captured streams.
+    - ``shell=False`` is FORCED -- callers cannot opt into shell expansion
+      via ``**extra`` (mirrors ``coding/security.md`` "no shell=True on
+      untrusted input").
+    - ``timeout`` defaults to 60s. Pass ``timeout=None`` explicitly to
+      disable; pass an explicit value to override. ``subprocess.run``
+      raises :class:`subprocess.TimeoutExpired` on overrun -- callers
+      handle that the same way they would with the bare API.
+
+    The returned :class:`subprocess.CompletedProcess` exposes ``returncode``,
+    ``stdout``, and ``stderr`` exactly as ``subprocess.run`` would. The
+    ``check=False`` default mirrors the bare API; pass ``check=True`` to
+    raise :class:`subprocess.CalledProcessError` on non-zero exit.
+
+    Args:
+        cmd: Argument vector for the child process. MUST be a sequence
+            (list / tuple) -- the helper rejects ``str`` to discourage
+            shell-quoting bugs (mirrors ``subprocess.run``'s
+            ``shell=False`` requirement).
+        timeout: Seconds to wait for the child to exit. Defaults to 60.
+            Pass ``None`` to wait indefinitely.
+        input: Optional UTF-8 text to feed into the child's stdin.
+        cwd: Optional working directory for the child.
+        env: Optional environment mapping. ``None`` inherits the parent's
+            env (the default :func:`subprocess.run` behavior).
+        check: If ``True``, raise :class:`subprocess.CalledProcessError`
+            on non-zero exit (mirrors :func:`subprocess.run`).
+        **extra: Forwarded to :func:`subprocess.run`. Keys that would
+            conflict with the forced safety defaults (``capture_output``,
+            ``text``, ``encoding``, ``errors``, ``shell``, ``stdout``,
+            ``stderr``) are silently dropped.
+
+    Returns:
+        :class:`subprocess.CompletedProcess` with ``stdout`` and ``stderr``
+        as UTF-8 strings (any undecodable bytes replaced with U+FFFD).
+
+    Raises:
+        subprocess.TimeoutExpired: If the child does not exit within
+            ``timeout`` seconds.
+        subprocess.CalledProcessError: If ``check=True`` and the child
+            exits non-zero.
+        FileNotFoundError: If the executable cannot be found.
+        TypeError: If ``cmd`` is a bare string (callers should pass a
+            sequence so argv quoting is unambiguous).
+    """
+    if isinstance(cmd, (str, bytes)):
+        raise TypeError(
+            "run_text requires a sequence of arguments (e.g. ['gh', 'api', ...]); "
+            "passing a single string would require shell=True which is forbidden."
+        )
+
+    # Drop any caller-provided keys that conflict with the forced safety
+    # defaults. Silently ignoring beats raising because most callers are
+    # mechanically refactoring existing subprocess.run sites that may
+    # have redundant text=True / encoding=... kwargs.
+    forbidden_keys = {
+        "capture_output",
+        "text",
+        "encoding",
+        "errors",
+        "shell",
+        "stdout",
+        "stderr",
+    }
+    sanitized = {k: v for k, v in extra.items() if k not in forbidden_keys}
+
+    return subprocess.run(
+        list(cmd),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        shell=False,
+        timeout=timeout,
+        input=input,
+        cwd=cwd,
+        env=dict(env) if env is not None else None,
+        check=check,
+        **sanitized,
+    )