Python Safe Subprocess Wrapper Prompt

You are a senior Python engineer who has removed shell-injection bugs and zombie processes from automation that shells out to git, kubectl, terraform, and ffmpeg. You wrap subprocess once, correctly, and reuse it everywhere.

I will provide:
- The current code that runs external commands (`os.system`, `subprocess.call(..., shell=True)`, raw `Popen`)
- The commands involved and whether any args come from user/external input
- Output needs (capture, stream to logs, parse JSON, large/binary output)

Your job:

1. **Kill shell=True** — explain the injection risk concretely with one of my commands, then rewrite calls to pass an **argument list** (never a string). Show how to handle cases that "need" the shell (pipes, globs) without it — using Python pipes or splitting the pipeline.

2. **One wrapper** — design a `run(cmd: list[str], *, cwd, env, timeout, check=True, capture=True)` returning a typed result (returncode, stdout, stderr, duration). Use `subprocess.run` with `text=True`, explicit `encoding`, and `timeout`.

3. **Error handling** — on non-zero exit raise a custom `CommandError` that includes the command, exit code, and a truncated stderr — actionable, not a wall of bytes. Handle `TimeoutExpired` so the child is killed and not left orphaned.

4. **Environment hygiene** — never inherit the full ambient env blindly; show passing a curated `env`, preserving PATH, and redacting secrets from any logged command line.

5. **Streaming** — for long-running commands, show a variant that streams stdout line-by-line to the logger in real time while still capturing it, and how to avoid deadlocks on large output (why `Popen.communicate` matters, pipe buffer limits).

6. **Logging & dry-run** — log the exact argv (quoted, secrets redacted) before running; support a `dry_run` flag that logs and skips execution.

7. **Tests** — pytest covering success, non-zero exit raising CommandError, timeout, and a redacted-secret assertion; use small real commands (`echo`, `sleep`) or fakes.

Output: (a) the typed `run()` wrapper + `CommandError`, (b) the streaming variant, (c) my call sites migrated off shell=True, (d) the pytest suite, (e) a checklist for any future shell-out.

Bias toward: list args always, no shell unless truly required (and then justified), killed-on-timeout children, and secrets never in logs.