From 1cac743952f9c51852b7892e33c98e65cda36b77 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 13:58:34 -0700
Subject: [PATCH 01/18] feat(hm-common): add process capture helper

Add hm_common::process: a `.captured()` extension on std and tokio
Command that spawns, captures stdout/stderr + exit status, and returns
a typed Captured. `Captured::success()` splits a zero exit (CapturedOk)
from a failure (CapturedError, a std::error::Error whose Display names
the program, status, and a trimmed stderr snippet). Output is read via
the sealed CapturedStreams trait: byte-first `stdout()`, strict
`stdout_str`/`stdout_string`, panicking `_unwrap` variants, and lossy
`stdout_lossy` (stderr mirrors). Covered by rstest cases + a tokio test.

Replace the four hand-rolled spawn/status/utf8 blocks:
- hm-dsl-engine python_engine: async `.captured().await?.success()?`,
  dropping the manual Stdio piping and the bail! error construction.
- hm run git_metadata / git_remote_url / git_default_branch: one
  `git_at()` builder + `.captured()`, collapsing the duplicated
  Command/output/filter/from_utf8_lossy chains.
---
 Cargo.lock                                |   2 +
 crates/hm-common/Cargo.toml               |   1 +
 crates/hm-common/src/lib.rs               |   1 +
 crates/hm-common/src/process.rs           | 335 ++++++++++++++++++++++
 crates/hm-dsl-engine/Cargo.toml           |   1 +
 crates/hm-dsl-engine/src/python_engine.rs |  23 +-
 crates/hm/src/commands/run/mod.rs         |  48 ++--
 7 files changed, 373 insertions(+), 38 deletions(-)
 create mode 100644 crates/hm-common/src/process.rs

diff --git a/Cargo.lock b/Cargo.lock
index bceb2f8b..7090bb32 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1264,6 +1264,7 @@ dependencies = [
  "serde",
  "serde_json",
  "tempfile",
+ "thiserror 2.0.18",
  "tokio",
  "tracing",
  "which 7.0.3",
@@ -1291,6 +1292,7 @@ dependencies = [
  "anyhow",
  "async-trait",
  "derive_more",
+ "hm-common",
  "include_dir",
  "rstest",
  "serde",
diff --git a/crates/hm-common/Cargo.toml b/crates/hm-common/Cargo.toml
index 0e6cd49a..1a571cd2 100644
--- a/crates/hm-common/Cargo.toml
+++ b/crates/hm-common/Cargo.toml
@@ -17,6 +17,7 @@ async-trait = { workspace = true }
 derive_more = { workspace = true }
 serde       = { workspace = true }
 serde_json  = { workspace = true }
+thiserror   = { workspace = true }
 include_dir = "0.7"
 tempfile    = "3"
 tokio       = { version = "1", features = ["process", "fs"] }
diff --git a/crates/hm-common/src/lib.rs b/crates/hm-common/src/lib.rs
index df5bdfbd..a3115457 100644
--- a/crates/hm-common/src/lib.rs
+++ b/crates/hm-common/src/lib.rs
@@ -2,3 +2,4 @@
 
 pub mod format;
 pub mod fs;
+pub mod process;
diff --git a/crates/hm-common/src/process.rs b/crates/hm-common/src/process.rs
new file mode 100644
index 00000000..889912c0
--- /dev/null
+++ b/crates/hm-common/src/process.rs
@@ -0,0 +1,335 @@
+//! Subprocess execution: spawn a command, capture its output, and inspect the
+//! result with a typed success/failure split and byte-first accessors.
+//!
+//! [`CommandExt`] and [`AsyncCommandExt`] add `.captured()` to
+//! [`std::process::Command`] and [`tokio::process::Command`]. It returns a
+//! [`Captured`]; call [`Captured::success`] to separate a zero exit from a
+//! failure, then read output through the [`CapturedStreams`] accessors.
+//!
+//! ```no_run
+//! use hm_common::process::{CommandExt, CapturedStreams};
+//!
+//! let out = std::process::Command::new("git")
+//!     .args(["rev-parse", "HEAD"])
+//!     .captured()?          // io::Error if git can't be spawned
+//!     .success()?;          // CapturedError if git exits non-zero
+//! let sha = out.stdout_string()?;
+//! # Ok::<(), Box<dyn std::error::Error>>(())
+//! ```
+
+use std::borrow::Cow;
+use std::future::Future;
+use std::io;
+use std::process::ExitStatus;
+use std::str::Utf8Error;
+
+mod sealed {
+    pub trait Sealed {}
+    impl Sealed for std::process::Command {}
+    impl Sealed for tokio::process::Command {}
+    impl Sealed for super::CapturedOk {}
+    impl Sealed for super::CapturedError {}
+}
+
+/// A finished process: its captured stdout/stderr and exit status.
+///
+/// The output bytes are only readable after resolving the exit status with
+/// [`success`](Captured::success) — success and failure both expose the
+/// [`CapturedStreams`] accessors, so the check can't be skipped by accident.
+#[derive(Debug, Clone)]
+pub struct Captured {
+    program: String,
+    stdout: Vec<u8>,
+    stderr: Vec<u8>,
+    status: ExitStatus,
+}
+
+impl Captured {
+    /// Split on the exit status: `Ok` if the process exited 0, else `Err`.
+    ///
+    /// # Errors
+    /// Returns [`CapturedError`] when the process exited non-zero (or was
+    /// killed by a signal).
+    pub fn success(self) -> Result<CapturedOk, CapturedError> {
+        if self.status.success() {
+            Ok(CapturedOk(self))
+        } else {
+            Err(CapturedError(self))
+        }
+    }
+
+    /// The raw exit status.
+    #[must_use]
+    pub const fn status(&self) -> ExitStatus {
+        self.status
+    }
+
+    /// The exit code, or `None` if the process was killed by a signal.
+    #[must_use]
+    pub fn code(&self) -> Option<i32> {
+        self.status.code()
+    }
+}
+
+/// A process that exited successfully (status 0). Read output via
+/// [`CapturedStreams`].
+#[derive(Debug, Clone)]
+pub struct CapturedOk(Captured);
+
+/// A process that exited non-zero.
+///
+/// Implements [`std::error::Error`]; its `Display` names the program, the exit
+/// status, and a trimmed snippet of stderr. Output is still readable via
+/// [`CapturedStreams`].
+#[derive(Debug, Clone, thiserror::Error)]
+#[error("{}", render_capture_error(.0))]
+pub struct CapturedError(Captured);
+
+fn describe_status(status: ExitStatus) -> String {
+    status.code().map_or_else(
+        || "terminated by signal".to_string(),
+        |code| format!("exited with status {code}"),
+    )
+}
+
+fn render_capture_error(c: &Captured) -> String {
+    use std::fmt::Write as _;
+
+    let mut msg = format!("`{}` {}", c.program, describe_status(c.status));
+    let stderr = String::from_utf8_lossy(&c.stderr);
+    let stderr = stderr.trim();
+    if !stderr.is_empty() {
+        const MAX: usize = 2000;
+        let snippet: String = stderr.chars().take(MAX).collect();
+        let ellipsis = if snippet.len() < stderr.len() { "…" } else { "" };
+        let _ = write!(msg, ": {snippet}{ellipsis}");
+    }
+    msg
+}
+
+/// Byte-first accessors over a captured process's output, implemented by
+/// [`CapturedOk`] and [`CapturedError`]. Sealed; not implementable downstream.
+pub trait CapturedStreams: sealed::Sealed {
+    /// Raw stdout bytes.
+    fn stdout(&self) -> &[u8];
+    /// Raw stderr bytes.
+    fn stderr(&self) -> &[u8];
+    /// The exit status.
+    fn status(&self) -> ExitStatus;
+
+    /// The exit code, or `None` if killed by a signal.
+    fn code(&self) -> Option<i32> {
+        self.status().code()
+    }
+
+    /// stdout as UTF-8, borrowed.
+    ///
+    /// # Errors
+    /// Returns [`Utf8Error`] if stdout is not valid UTF-8.
+    fn stdout_str(&self) -> Result<&str, Utf8Error> {
+        std::str::from_utf8(self.stdout())
+    }
+    /// stderr as UTF-8, borrowed.
+    ///
+    /// # Errors
+    /// Returns [`Utf8Error`] if stderr is not valid UTF-8.
+    fn stderr_str(&self) -> Result<&str, Utf8Error> {
+        std::str::from_utf8(self.stderr())
+    }
+
+    /// stdout as an owned UTF-8 `String`.
+    ///
+    /// # Errors
+    /// Returns [`Utf8Error`] if stdout is not valid UTF-8.
+    fn stdout_string(&self) -> Result<String, Utf8Error> {
+        self.stdout_str().map(str::to_owned)
+    }
+    /// stderr as an owned UTF-8 `String`.
+    ///
+    /// # Errors
+    /// Returns [`Utf8Error`] if stderr is not valid UTF-8.
+    fn stderr_string(&self) -> Result<String, Utf8Error> {
+        self.stderr_str().map(str::to_owned)
+    }
+
+    /// stdout as `&str`, **panicking** if not valid UTF-8.
+    #[allow(clippy::expect_used, reason = "callers opt into panic-on-invalid by calling _unwrap")]
+    fn stdout_str_unwrap(&self) -> &str {
+        self.stdout_str().expect("stdout was not valid UTF-8")
+    }
+    /// stderr as `&str`, **panicking** if not valid UTF-8.
+    #[allow(clippy::expect_used, reason = "callers opt into panic-on-invalid by calling _unwrap")]
+    fn stderr_str_unwrap(&self) -> &str {
+        self.stderr_str().expect("stderr was not valid UTF-8")
+    }
+
+    /// stdout as an owned `String`, **panicking** if not valid UTF-8.
+    #[allow(clippy::expect_used, reason = "callers opt into panic-on-invalid by calling _unwrap")]
+    fn stdout_string_unwrap(&self) -> String {
+        self.stdout_string().expect("stdout was not valid UTF-8")
+    }
+    /// stderr as an owned `String`, **panicking** if not valid UTF-8.
+    #[allow(clippy::expect_used, reason = "callers opt into panic-on-invalid by calling _unwrap")]
+    fn stderr_string_unwrap(&self) -> String {
+        self.stderr_string().expect("stderr was not valid UTF-8")
+    }
+
+    /// stdout decoded lossily (invalid sequences become U+FFFD). Never fails.
+    fn stdout_lossy(&self) -> Cow<'_, str> {
+        String::from_utf8_lossy(self.stdout())
+    }
+    /// stderr decoded lossily (invalid sequences become U+FFFD). Never fails.
+    fn stderr_lossy(&self) -> Cow<'_, str> {
+        String::from_utf8_lossy(self.stderr())
+    }
+}
+
+impl CapturedStreams for CapturedOk {
+    fn stdout(&self) -> &[u8] {
+        &self.0.stdout
+    }
+    fn stderr(&self) -> &[u8] {
+        &self.0.stderr
+    }
+    fn status(&self) -> ExitStatus {
+        self.0.status
+    }
+}
+
+impl CapturedStreams for CapturedError {
+    fn stdout(&self) -> &[u8] {
+        &self.0.stdout
+    }
+    fn stderr(&self) -> &[u8] {
+        &self.0.stderr
+    }
+    fn status(&self) -> ExitStatus {
+        self.0.status
+    }
+}
+
+/// Adds [`captured`](CommandExt::captured) to [`std::process::Command`].
+pub trait CommandExt: sealed::Sealed {
+    /// Spawn, wait for completion, and capture stdout/stderr and exit status.
+    ///
+    /// # Errors
+    /// Returns the [`io::Error`] from spawning (e.g. the program is not found).
+    fn captured(&mut self) -> io::Result<Captured>;
+}
+
+impl CommandExt for std::process::Command {
+    fn captured(&mut self) -> io::Result<Captured> {
+        let program = self.get_program().to_string_lossy().into_owned();
+        let out = self.output()?;
+        Ok(Captured {
+            program,
+            stdout: out.stdout,
+            stderr: out.stderr,
+            status: out.status,
+        })
+    }
+}
+
+/// Adds [`captured`](AsyncCommandExt::captured) to [`tokio::process::Command`].
+pub trait AsyncCommandExt: sealed::Sealed {
+    /// Spawn, await completion, and capture stdout/stderr and exit status.
+    ///
+    /// # Errors
+    /// Returns the [`io::Error`] from spawning (e.g. the program is not found).
+    fn captured(&mut self) -> impl Future<Output = io::Result<Captured>>;
+}
+
+impl AsyncCommandExt for tokio::process::Command {
+    async fn captured(&mut self) -> io::Result<Captured> {
+        let program = self.as_std().get_program().to_string_lossy().into_owned();
+        let out = self.output().await?;
+        Ok(Captured {
+            program,
+            stdout: out.stdout,
+            stderr: out.stderr,
+            status: out.status,
+        })
+    }
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used, reason = "test setup and assertions")]
+mod tests {
+    use super::*;
+    use rstest::rstest;
+
+    /// `sh -c <script>` — portable across this repo's unix CI targets.
+    fn sh(script: &str) -> std::process::Command {
+        let mut cmd = std::process::Command::new("sh");
+        cmd.arg("-c").arg(script);
+        cmd
+    }
+
+    #[rstest]
+    #[case::plain("printf hello", "hello")]
+    #[case::trailing_newline("echo hi", "hi\n")]
+    #[case::multiline("printf 'a\\nb'", "a\nb")]
+    #[case::empty("true", "")]
+    fn captures_stdout_on_success(#[case] script: &str, #[case] expected: &str) {
+        let ok = sh(script).captured().unwrap().success().unwrap();
+        assert_eq!(ok.stdout_string().unwrap(), expected);
+    }
+
+    #[rstest]
+    #[case::exit_1("exit 1", 1)]
+    #[case::exit_3("exit 3", 3)]
+    #[case::false_builtin("false", 1)]
+    fn nonzero_exit_is_error_carrying_the_code(#[case] script: &str, #[case] code: i32) {
+        let err = sh(script).captured().unwrap().success().unwrap_err();
+        assert_eq!(err.code(), Some(code));
+    }
+
+    #[rstest]
+    fn error_display_names_program_status_and_stderr() {
+        let err = sh("echo boom 1>&2; exit 2")
+            .captured()
+            .unwrap()
+            .success()
+            .unwrap_err();
+        let msg = err.to_string();
+        assert!(msg.contains("sh"), "program missing: {msg}");
+        assert!(msg.contains("status 2"), "status missing: {msg}");
+        assert!(msg.contains("boom"), "stderr missing: {msg}");
+    }
+
+    #[rstest]
+    fn stderr_is_captured_on_success() {
+        let ok = sh("echo note 1>&2").captured().unwrap().success().unwrap();
+        assert_eq!(ok.stderr_string().unwrap().trim(), "note");
+    }
+
+    #[rstest]
+    fn spawn_failure_is_an_io_error() {
+        let result = std::process::Command::new("hm-common-no-such-binary-xyz").captured();
+        assert!(result.is_err());
+    }
+
+    #[rstest]
+    fn non_utf8_stdout_reads_as_bytes_and_lossy() {
+        let ok = sh(r"printf '\377'").captured().unwrap().success().unwrap();
+        assert_eq!(ok.stdout(), b"\xff");
+        assert!(ok.stdout_str().is_err());
+        assert!(ok.stdout_lossy().contains('\u{FFFD}'));
+    }
+
+    #[rstest]
+    #[should_panic(expected = "not valid UTF-8")]
+    fn string_unwrap_panics_on_invalid_utf8() {
+        let ok = sh(r"printf '\377'").captured().unwrap().success().unwrap();
+        let _ = ok.stdout_string_unwrap();
+    }
+
+    #[rstest]
+    #[tokio::test]
+    async fn async_captured_reads_stdout() {
+        let mut cmd = tokio::process::Command::new("sh");
+        cmd.arg("-c").arg("printf async-hi");
+        let ok = cmd.captured().await.unwrap().success().unwrap();
+        assert_eq!(ok.stdout_string().unwrap(), "async-hi");
+    }
+}
diff --git a/crates/hm-dsl-engine/Cargo.toml b/crates/hm-dsl-engine/Cargo.toml
index 91a0dd62..11e5d79c 100644
--- a/crates/hm-dsl-engine/Cargo.toml
+++ b/crates/hm-dsl-engine/Cargo.toml
@@ -12,6 +12,7 @@ categories = ["command-line-utilities"]
 path = "src/lib.rs"
 
 [dependencies]
+hm-common   = { workspace = true }
 anyhow      = { workspace = true }
 async-trait = { workspace = true }
 derive_more = { workspace = true }
diff --git a/crates/hm-dsl-engine/src/python_engine.rs b/crates/hm-dsl-engine/src/python_engine.rs
index 6c386320..ba63c1b6 100644
--- a/crates/hm-dsl-engine/src/python_engine.rs
+++ b/crates/hm-dsl-engine/src/python_engine.rs
@@ -1,8 +1,8 @@
 use std::path::Path;
-use std::process::Stdio;
 
-use anyhow::{Context, Result, bail};
+use anyhow::{Context, Result};
 use async_trait::async_trait;
+use hm_common::process::{AsyncCommandExt as _, CapturedStreams as _};
 use tracing::debug;
 
 use crate::bundled_sources;
@@ -91,22 +91,15 @@ impl SubprocessPythonEngine {
             .args(extra_args)
             .current_dir(project_dir)
             .env("PYTHONPATH", tmp.path())
-            .env("PYTHONDONTWRITEBYTECODE", "1")
-            .stdin(Stdio::null())
-            .stdout(Stdio::piped())
-            .stderr(Stdio::piped());
+            .env("PYTHONDONTWRITEBYTECODE", "1");
 
         debug!(?cmd, "running python3 subprocess");
 
-        let output = cmd.output().await.context("spawning python3")?;
-
-        if !output.status.success() {
-            let stderr = String::from_utf8_lossy(&output.stderr);
-            let code = output.status.code().unwrap_or(-1);
-            bail!("python3 exited with code {code}:\n{stderr}");
-        }
-
-        String::from_utf8(output.stdout).context("python3 stdout is not valid UTF-8")
+        // `.captured()` pipes stdout/stderr and nulls stdin; `.success()`
+        // surfaces a non-zero exit (with stderr) as an error via `?`.
+        let ok = cmd.captured().await.context("spawning python3")?.success()?;
+        ok.stdout_string()
+            .context("python3 stdout is not valid UTF-8")
     }
 }
 
diff --git a/crates/hm/src/commands/run/mod.rs b/crates/hm/src/commands/run/mod.rs
index ba541cc1..5a7e07ec 100644
--- a/crates/hm/src/commands/run/mod.rs
+++ b/crates/hm/src/commands/run/mod.rs
@@ -2,6 +2,7 @@ use std::collections::HashMap;
 
 use anyhow::{Context, Result};
 
+use hm_common::process::{CapturedStreams as _, CommandExt as _};
 use hm_dsl_engine::{DslEngine, detect};
 use human_units::FormatSize as _;
 
@@ -240,16 +241,21 @@ fn parse_env(pairs: &[String]) -> HashMap<String, String> {
 
 /// Resolve `(branch, commit)` from git at `root`, best-effort. An explicit
 /// `branch_override` wins; missing values fall back to `HEAD` / the zero SHA.
+/// `git -C <root> <args...>`, ready to `.captured()`.
+fn git_at(root: &std::path::Path, args: &[&str]) -> std::process::Command {
+    let mut cmd = std::process::Command::new("git");
+    cmd.arg("-C").arg(root).args(args);
+    cmd
+}
+
 fn git_metadata(root: &std::path::Path, branch_override: Option<String>) -> (String, String) {
     let run = |a: &[&str]| {
-        std::process::Command::new("git")
-            .arg("-C")
-            .arg(root)
-            .args(a)
-            .output()
+        git_at(root, a)
+            .captured()
             .ok()
-            .filter(|o| o.status.success())
-            .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+            .and_then(|c| c.success().ok())
+            .and_then(|ok| ok.stdout_string().ok())
+            .map(|s| s.trim().to_string())
     };
     let branch = branch_override
         .or_else(|| run(&["rev-parse", "--abbrev-ref", "HEAD"]))
@@ -296,28 +302,24 @@ fn parse_default_branch(symbolic_ref: &str) -> Option<String> {
 
 /// The worktree's raw `origin` remote URL (the pipeline's `repository`).
 fn git_remote_url(root: &std::path::Path) -> Option<String> {
-    let out = std::process::Command::new("git")
-        .arg("-C")
-        .arg(root)
-        .args(["config", "--get", "remote.origin.url"])
-        .output()
-        .ok()
-        .filter(|o| o.status.success())?;
-    let url = String::from_utf8_lossy(&out.stdout).trim().to_string();
+    let out = git_at(root, &["config", "--get", "remote.origin.url"])
+        .captured()
+        .ok()?
+        .success()
+        .ok()?;
+    let url = out.stdout_lossy().trim().to_string();
     (!url.is_empty()).then_some(url)
 }
 
 /// The repo's default branch, from `origin/HEAD`. `None` when `origin/HEAD`
 /// isn't set (common on fresh clones without `git remote set-head`).
 fn git_default_branch(root: &std::path::Path) -> Option<String> {
-    let out = std::process::Command::new("git")
-        .arg("-C")
-        .arg(root)
-        .args(["symbolic-ref", "refs/remotes/origin/HEAD"])
-        .output()
-        .ok()
-        .filter(|o| o.status.success())?;
-    parse_default_branch(&String::from_utf8_lossy(&out.stdout))
+    let out = git_at(root, &["symbolic-ref", "refs/remotes/origin/HEAD"])
+        .captured()
+        .ok()?
+        .success()
+        .ok()?;
+    parse_default_branch(&out.stdout_lossy())
 }
 
 /// Best-effort `owner/repo` from the worktree's `origin` remote.

From 838a972128adb5199deed8b12bd1ab25fc9a3d6c Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 14:37:46 -0700
Subject: [PATCH 02/18] refactor(hm-common): split process module into capture
 + which

Move process.rs to process/capture.rs (git-tracked rename) and add
process/mod.rs, which re-exports the capture API so the public path
`hm_common::process::{CommandExt, CapturedStreams, ...}` is unchanged.
Add an empty process/which.rs as the home for the forthcoming
require_on_path helper.
---
 .../src/{process.rs => process/capture.rs}    | 19 +------------------
 crates/hm-common/src/process/mod.rs           |  8 ++++++++
 crates/hm-common/src/process/which.rs         |  3 +++
 3 files changed, 12 insertions(+), 18 deletions(-)
 rename crates/hm-common/src/{process.rs => process/capture.rs} (92%)
 create mode 100644 crates/hm-common/src/process/mod.rs
 create mode 100644 crates/hm-common/src/process/which.rs

diff --git a/crates/hm-common/src/process.rs b/crates/hm-common/src/process/capture.rs
similarity index 92%
rename from crates/hm-common/src/process.rs
rename to crates/hm-common/src/process/capture.rs
index 889912c0..ea59f39d 100644
--- a/crates/hm-common/src/process.rs
+++ b/crates/hm-common/src/process/capture.rs
@@ -1,21 +1,4 @@
-//! Subprocess execution: spawn a command, capture its output, and inspect the
-//! result with a typed success/failure split and byte-first accessors.
-//!
-//! [`CommandExt`] and [`AsyncCommandExt`] add `.captured()` to
-//! [`std::process::Command`] and [`tokio::process::Command`]. It returns a
-//! [`Captured`]; call [`Captured::success`] to separate a zero exit from a
-//! failure, then read output through the [`CapturedStreams`] accessors.
-//!
-//! ```no_run
-//! use hm_common::process::{CommandExt, CapturedStreams};
-//!
-//! let out = std::process::Command::new("git")
-//!     .args(["rev-parse", "HEAD"])
-//!     .captured()?          // io::Error if git can't be spawned
-//!     .success()?;          // CapturedError if git exits non-zero
-//! let sha = out.stdout_string()?;
-//! # Ok::<(), Box<dyn std::error::Error>>(())
-//! ```
+//! Spawn a command and capture its output, with a typed success/failure split.
 
 use std::borrow::Cow;
 use std::future::Future;
diff --git a/crates/hm-common/src/process/mod.rs b/crates/hm-common/src/process/mod.rs
new file mode 100644
index 00000000..f269d501
--- /dev/null
+++ b/crates/hm-common/src/process/mod.rs
@@ -0,0 +1,8 @@
+//! Subprocess utilities.
+
+pub mod capture;
+pub mod which;
+
+pub use capture::{
+    AsyncCommandExt, Captured, CapturedError, CapturedOk, CapturedStreams, CommandExt,
+};
diff --git a/crates/hm-common/src/process/which.rs b/crates/hm-common/src/process/which.rs
new file mode 100644
index 00000000..3ef92772
--- /dev/null
+++ b/crates/hm-common/src/process/which.rs
@@ -0,0 +1,3 @@
+//! Locating executables on `PATH`.
+//!
+//! Placeholder — the `which` helper (`require_on_path`) lands here.

From 2e727cee2ac9d3fc01113bd965e986bee13d0149 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 15:52:12 -0700
Subject: [PATCH 03/18] feat(hm-common): add process::pathbin for PATH lookup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implement pathbin in process/which.rs: resolve a program to its
absolute path on PATH, returning a typed ExecutableNotFound (naming the
program) on miss. Re-export it (and the error) at process::. A presence
check is pathbin(x).is_ok() — no separate helper.

Replace the last which::which sites:
- hm-dsl-engine python_engine: pathbin("python3"), with the install
  hint moved to a .context() at the call site.
- the six python3 test skip-guards across hm and hm-dsl-engine tests.

With no which::which callers left outside hm-common, drop the now-unused
`which` dependency from hm and hm-dsl-engine and hm-common's redundant
dev-dependency copy.
---
 Cargo.lock                                    | 54 +++----------------
 crates/hm-common/Cargo.toml                   |  1 -
 crates/hm-common/src/process/mod.rs           |  1 +
 crates/hm-common/src/process/which.rs         | 54 ++++++++++++++++++-
 crates/hm-dsl-engine/Cargo.toml               |  2 -
 crates/hm-dsl-engine/src/python_engine.rs     |  5 +-
 .../hm-dsl-engine/tests/python_engine_test.rs |  4 +-
 crates/hm/Cargo.toml                          |  2 -
 crates/hm/tests/cmd_init.rs                   |  2 +-
 crates/hm/tests/cmd_pipelines.rs              |  2 +-
 crates/hm/tests/cmd_render.rs                 |  4 +-
 11 files changed, 67 insertions(+), 64 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 7090bb32..3650ff33 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1161,7 +1161,6 @@ dependencies = [
  "url",
  "uuid",
  "webbrowser",
- "which 6.0.3",
  "wiremock",
 ]
 
@@ -1267,7 +1266,7 @@ dependencies = [
  "thiserror 2.0.18",
  "tokio",
  "tracing",
- "which 7.0.3",
+ "which",
 ]
 
 [[package]]
@@ -1300,7 +1299,6 @@ dependencies = [
  "tempfile",
  "tokio",
  "tracing",
- "which 7.0.3",
 ]
 
 [[package]]
@@ -1432,15 +1430,6 @@ dependencies = [
  "tracing",
 ]
 
-[[package]]
-name = "home"
-version = "0.5.12"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cc627f471c528ff0c4a49e1d5e60450c8f6461dd6d10ba9dcd3a61d3dff7728d"
-dependencies = [
- "windows-sys 0.61.2",
-]
-
 [[package]]
 name = "http"
 version = "1.4.0"
@@ -1955,12 +1944,6 @@ dependencies = [
  "vcpkg",
 ]
 
-[[package]]
-name = "linux-raw-sys"
-version = "0.4.15"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab"
-
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
@@ -2729,19 +2712,6 @@ dependencies = [
  "semver",
 ]
 
-[[package]]
-name = "rustix"
-version = "0.38.44"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154"
-dependencies = [
- "bitflags",
- "errno",
- "libc",
- "linux-raw-sys 0.4.15",
- "windows-sys 0.59.0",
-]
-
 [[package]]
 name = "rustix"
 version = "1.1.4"
@@ -2751,7 +2721,7 @@ dependencies = [
  "bitflags",
  "errno",
  "libc",
- "linux-raw-sys 0.12.1",
+ "linux-raw-sys",
  "windows-sys 0.61.2",
 ]
 
@@ -3250,7 +3220,7 @@ dependencies = [
  "fastrand",
  "getrandom 0.4.2",
  "once_cell",
- "rustix 1.1.4",
+ "rustix",
  "windows-sys 0.61.2",
 ]
 
@@ -3260,7 +3230,7 @@ version = "0.4.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "230a1b821ccbd75b185820a1f1ff7b14d21da1e442e22c0863ea5f08771a8874"
 dependencies = [
- "rustix 1.1.4",
+ "rustix",
  "windows-sys 0.61.2",
 ]
 
@@ -3986,18 +3956,6 @@ dependencies = [
  "rustls-pki-types",
 ]
 
-[[package]]
-name = "which"
-version = "6.0.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b4ee928febd44d98f2f459a4a79bd4d928591333a494a10a868418ac1b39cf1f"
-dependencies = [
- "either",
- "home",
- "rustix 0.38.44",
- "winsafe",
-]
-
 [[package]]
 name = "which"
 version = "7.0.3"
@@ -4006,7 +3964,7 @@ checksum = "24d643ce3fd3e5b54854602a080f34fb10ab75e0b813ee32d00ca2b44fa74762"
 dependencies = [
  "either",
  "env_home",
- "rustix 1.1.4",
+ "rustix",
  "winsafe",
 ]
 
@@ -4396,7 +4354,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32e45ad4206f6d2479085147f02bc2ef834ac85886624a23575ae137c8aa8156"
 dependencies = [
  "libc",
- "rustix 1.1.4",
+ "rustix",
 ]
 
 [[package]]
diff --git a/crates/hm-common/Cargo.toml b/crates/hm-common/Cargo.toml
index 1a571cd2..888a08ee 100644
--- a/crates/hm-common/Cargo.toml
+++ b/crates/hm-common/Cargo.toml
@@ -27,7 +27,6 @@ which       = "7"
 [dev-dependencies]
 tempfile    = "3"
 tokio       = { version = "1", features = ["macros", "rt-multi-thread"] }
-which       = "7"
 rstest      = { workspace = true }
 proptest    = { workspace = true }
 
diff --git a/crates/hm-common/src/process/mod.rs b/crates/hm-common/src/process/mod.rs
index f269d501..0aa90a80 100644
--- a/crates/hm-common/src/process/mod.rs
+++ b/crates/hm-common/src/process/mod.rs
@@ -6,3 +6,4 @@ pub mod which;
 pub use capture::{
     AsyncCommandExt, Captured, CapturedError, CapturedOk, CapturedStreams, CommandExt,
 };
+pub use which::{ExecutableNotFound, pathbin};
diff --git a/crates/hm-common/src/process/which.rs b/crates/hm-common/src/process/which.rs
index 3ef92772..261965e4 100644
--- a/crates/hm-common/src/process/which.rs
+++ b/crates/hm-common/src/process/which.rs
@@ -1,3 +1,53 @@
 //! Locating executables on `PATH`.
-//!
-//! Placeholder — the `which` helper (`require_on_path`) lands here.
+
+use std::ffi::OsStr;
+use std::path::PathBuf;
+
+/// The requested program was not found on `PATH`.
+#[derive(Debug, thiserror::Error)]
+#[error("`{program}` was not found on PATH")]
+pub struct ExecutableNotFound {
+    program: String,
+}
+
+/// Resolve `program` to its absolute path on `PATH`.
+///
+/// For a presence check, call `pathbin(program).is_ok()`.
+///
+/// # Errors
+/// Returns [`ExecutableNotFound`] if `program` is not an executable on `PATH`.
+pub fn pathbin(program: impl AsRef<OsStr>) -> Result<PathBuf, ExecutableNotFound> {
+    let program = program.as_ref();
+    which::which(program).map_err(|_| ExecutableNotFound {
+        program: program.to_string_lossy().into_owned(),
+    })
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used, reason = "test setup and assertions")]
+mod tests {
+    use super::*;
+    use rstest::rstest;
+
+    #[rstest]
+    #[case::present("sh", true)]
+    #[case::absent("hm-common-no-such-binary-xyz", false)]
+    fn pathbin_reports_resolvability(#[case] program: &str, #[case] resolvable: bool) {
+        assert_eq!(pathbin(program).is_ok(), resolvable);
+    }
+
+    #[rstest]
+    fn pathbin_resolves_to_an_absolute_path() {
+        let path = pathbin("sh").unwrap();
+        assert!(path.is_absolute(), "expected absolute path, got {path:?}");
+        assert_eq!(path.file_name(), Some(OsStr::new("sh")));
+    }
+
+    #[rstest]
+    fn error_names_the_missing_program() {
+        let err = pathbin("hm-common-no-such-binary-xyz").unwrap_err();
+        let msg = err.to_string();
+        assert!(msg.contains("hm-common-no-such-binary-xyz"), "program: {msg}");
+        assert!(msg.contains("not found on PATH"), "phrasing: {msg}");
+    }
+}
diff --git a/crates/hm-dsl-engine/Cargo.toml b/crates/hm-dsl-engine/Cargo.toml
index 11e5d79c..1cf968d4 100644
--- a/crates/hm-dsl-engine/Cargo.toml
+++ b/crates/hm-dsl-engine/Cargo.toml
@@ -22,13 +22,11 @@ include_dir = "0.7"
 tempfile    = "3"
 tokio       = { version = "1", features = ["process", "fs"] }
 tracing     = "0.1"
-which       = "7"
 
 [dev-dependencies]
 rstest      = { workspace = true }
 tempfile    = "3"
 tokio       = { version = "1", features = ["macros", "rt-multi-thread"] }
-which       = "7"
 
 [lints]
 workspace = true
diff --git a/crates/hm-dsl-engine/src/python_engine.rs b/crates/hm-dsl-engine/src/python_engine.rs
index ba63c1b6..38ae5498 100644
--- a/crates/hm-dsl-engine/src/python_engine.rs
+++ b/crates/hm-dsl-engine/src/python_engine.rs
@@ -2,7 +2,7 @@ use std::path::Path;
 
 use anyhow::{Context, Result};
 use async_trait::async_trait;
-use hm_common::process::{AsyncCommandExt as _, CapturedStreams as _};
+use hm_common::process::{AsyncCommandExt as _, CapturedStreams as _, pathbin};
 use tracing::debug;
 
 use crate::bundled_sources;
@@ -70,8 +70,7 @@ impl SubprocessPythonEngine {
     ///
     /// Returns an error if `python3` is not found on `PATH`.
     pub fn new() -> Result<Self> {
-        let python_bin =
-            which::which("python3").context("python3 not found on PATH — install Python 3.11+")?;
+        let python_bin = pathbin("python3").context("install Python 3.11+")?;
         Ok(Self { python_bin })
     }
 
diff --git a/crates/hm-dsl-engine/tests/python_engine_test.rs b/crates/hm-dsl-engine/tests/python_engine_test.rs
index 81c29184..92967569 100644
--- a/crates/hm-dsl-engine/tests/python_engine_test.rs
+++ b/crates/hm-dsl-engine/tests/python_engine_test.rs
@@ -10,7 +10,7 @@ use hm_dsl_engine::DslEngine;
 #[tokio::test]
 async fn python_roundtrip() {
     // Skip if python3 not available or harmont deps missing
-    if which::which("python3").is_err() {
+    if hm_common::process::pathbin("python3").is_err() {
         eprintln!("skipping: python3 not on PATH");
         return;
     }
@@ -43,7 +43,7 @@ def ci() -> hm.Step:
 
 #[tokio::test]
 async fn python_registry_json_carries_triggers_and_allow_manual() {
-    if which::which("python3").is_err() {
+    if hm_common::process::pathbin("python3").is_err() {
         eprintln!("skipping: python3 not on PATH");
         return;
     }
diff --git a/crates/hm/Cargo.toml b/crates/hm/Cargo.toml
index a51d4f9b..aea2a5cb 100644
--- a/crates/hm/Cargo.toml
+++ b/crates/hm/Cargo.toml
@@ -56,7 +56,6 @@ bytes = "1"
 human-units = { workspace = true }
 futures = "0.3"
 futures-util = "0.3"
-which = "6"
 hm-pipeline-ir     = { workspace = true }
 hm-plugin-protocol = { workspace = true }
 hm-common = { workspace = true }
@@ -87,7 +86,6 @@ assert_cmd = "2"
 predicates = "3"
 assert_fs = "1"
 tempfile = "3"
-which = "6"
 rstest = { workspace = true }
 
 [lints]
diff --git a/crates/hm/tests/cmd_init.rs b/crates/hm/tests/cmd_init.rs
index b053419b..daa89369 100644
--- a/crates/hm/tests/cmd_init.rs
+++ b/crates/hm/tests/cmd_init.rs
@@ -193,7 +193,7 @@ fn init_all_templates_create_files(#[case] slug: &str) {
 // ── roundtrip: init → render ──────────────────────────────────
 
 fn has_python() -> bool {
-    which::which("python3").is_ok()
+    hm_common::process::pathbin("python3").is_ok()
 }
 
 #[rstest]
diff --git a/crates/hm/tests/cmd_pipelines.rs b/crates/hm/tests/cmd_pipelines.rs
index d15713d5..cce399e0 100644
--- a/crates/hm/tests/cmd_pipelines.rs
+++ b/crates/hm/tests/cmd_pipelines.rs
@@ -13,7 +13,7 @@ use rstest::rstest;
 
 #[rstest]
 fn pipelines_emits_discovery_envelope() {
-    if which::which("python3").is_err() {
+    if hm_common::process::pathbin("python3").is_err() {
         eprintln!("skipping: python3 not on PATH");
         return;
     }
diff --git a/crates/hm/tests/cmd_render.rs b/crates/hm/tests/cmd_render.rs
index dfe358b8..8c6c3bbf 100644
--- a/crates/hm/tests/cmd_render.rs
+++ b/crates/hm/tests/cmd_render.rs
@@ -28,7 +28,7 @@ def ci() -> hm.Step:
 
 #[rstest]
 fn render_emits_v0_ir_for_slug() {
-    if which::which("python3").is_err() {
+    if hm_common::process::pathbin("python3").is_err() {
         eprintln!("skipping: python3 not on PATH");
         return;
     }
@@ -58,7 +58,7 @@ fn render_emits_v0_ir_for_slug() {
 
 #[rstest]
 fn render_unknown_slug_fails_with_available_on_stderr() {
-    if which::which("python3").is_err() {
+    if hm_common::process::pathbin("python3").is_err() {
         eprintln!("skipping: python3 not on PATH");
         return;
     }

From f942a3b02ab6f4c867f747f22f4395a38e5f8c8e Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 16:04:57 -0700
Subject: [PATCH 04/18] deslop

---
 crates/hm-common/src/process/capture.rs | 24 ++++--------------------
 1 file changed, 4 insertions(+), 20 deletions(-)

diff --git a/crates/hm-common/src/process/capture.rs b/crates/hm-common/src/process/capture.rs
index ea59f39d..ae47c072 100644
--- a/crates/hm-common/src/process/capture.rs
+++ b/crates/hm-common/src/process/capture.rs
@@ -17,8 +17,7 @@ mod sealed {
 /// A finished process: its captured stdout/stderr and exit status.
 ///
 /// The output bytes are only readable after resolving the exit status with
-/// [`success`](Captured::success) — success and failure both expose the
-/// [`CapturedStreams`] accessors, so the check can't be skipped by accident.
+/// [`success`](Captured::success).
 #[derive(Debug, Clone)]
 pub struct Captured {
     program: String,
@@ -29,10 +28,6 @@ pub struct Captured {
 
 impl Captured {
     /// Split on the exit status: `Ok` if the process exited 0, else `Err`.
-    ///
-    /// # Errors
-    /// Returns [`CapturedError`] when the process exited non-zero (or was
-    /// killed by a signal).
     pub fn success(self) -> Result<CapturedOk, CapturedError> {
         if self.status.success() {
             Ok(CapturedOk(self))
@@ -54,16 +49,11 @@ impl Captured {
     }
 }
 
-/// A process that exited successfully (status 0). Read output via
-/// [`CapturedStreams`].
+/// A process that exited successfully (status 0). Read output via [`CapturedStreams`].
 #[derive(Debug, Clone)]
 pub struct CapturedOk(Captured);
 
 /// A process that exited non-zero.
-///
-/// Implements [`std::error::Error`]; its `Display` names the program, the exit
-/// status, and a trimmed snippet of stderr. Output is still readable via
-/// [`CapturedStreams`].
 #[derive(Debug, Clone, thiserror::Error)]
 #[error("{}", render_capture_error(.0))]
 pub struct CapturedError(Captured);
@@ -90,8 +80,8 @@ fn render_capture_error(c: &Captured) -> String {
     msg
 }
 
-/// Byte-first accessors over a captured process's output, implemented by
-/// [`CapturedOk`] and [`CapturedError`]. Sealed; not implementable downstream.
+/// Accessors over a captured process's output, implemented by [`CapturedOk`] and
+/// [`CapturedError`].
 pub trait CapturedStreams: sealed::Sealed {
     /// Raw stdout bytes.
     fn stdout(&self) -> &[u8];
@@ -194,9 +184,6 @@ impl CapturedStreams for CapturedError {
 /// Adds [`captured`](CommandExt::captured) to [`std::process::Command`].
 pub trait CommandExt: sealed::Sealed {
     /// Spawn, wait for completion, and capture stdout/stderr and exit status.
-    ///
-    /// # Errors
-    /// Returns the [`io::Error`] from spawning (e.g. the program is not found).
     fn captured(&mut self) -> io::Result<Captured>;
 }
 
@@ -216,9 +203,6 @@ impl CommandExt for std::process::Command {
 /// Adds [`captured`](AsyncCommandExt::captured) to [`tokio::process::Command`].
 pub trait AsyncCommandExt: sealed::Sealed {
     /// Spawn, await completion, and capture stdout/stderr and exit status.
-    ///
-    /// # Errors
-    /// Returns the [`io::Error`] from spawning (e.g. the program is not found).
     fn captured(&mut self) -> impl Future<Output = io::Result<Captured>>;
 }
 

From 7f8310192a021f8a5a685493d7f80bd6d1529a49 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 16:10:56 -0700
Subject: [PATCH 05/18] feat(hm-common): add pathbin aliases and SystemBins
 bundle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add git()/python3() aliases over pathbin, and SystemBins — the external
executables Harmont shells out to, resolved from PATH via resolve().
python3 is required; git resolves to Option since git metadata is
best-effort. Adopt the python3() alias in the DSL engine.

Also restore the # Errors docs on capture's success()/captured() that a
prior module-doc edit dropped.
---
 crates/hm-common/src/process/capture.rs   |  9 +++
 crates/hm-common/src/process/mod.rs       |  2 +-
 crates/hm-common/src/process/which.rs     | 76 ++++++++++++++++++++++-
 crates/hm-dsl-engine/src/python_engine.rs |  4 +-
 4 files changed, 87 insertions(+), 4 deletions(-)

diff --git a/crates/hm-common/src/process/capture.rs b/crates/hm-common/src/process/capture.rs
index ae47c072..af852851 100644
--- a/crates/hm-common/src/process/capture.rs
+++ b/crates/hm-common/src/process/capture.rs
@@ -28,6 +28,9 @@ pub struct Captured {
 
 impl Captured {
     /// Split on the exit status: `Ok` if the process exited 0, else `Err`.
+    ///
+    /// # Errors
+    /// [`CapturedError`] when the process exited non-zero or was killed by a signal.
     pub fn success(self) -> Result<CapturedOk, CapturedError> {
         if self.status.success() {
             Ok(CapturedOk(self))
@@ -184,6 +187,9 @@ impl CapturedStreams for CapturedError {
 /// Adds [`captured`](CommandExt::captured) to [`std::process::Command`].
 pub trait CommandExt: sealed::Sealed {
     /// Spawn, wait for completion, and capture stdout/stderr and exit status.
+    ///
+    /// # Errors
+    /// The spawn [`io::Error`] (e.g. the program is not found).
     fn captured(&mut self) -> io::Result<Captured>;
 }
 
@@ -203,6 +209,9 @@ impl CommandExt for std::process::Command {
 /// Adds [`captured`](AsyncCommandExt::captured) to [`tokio::process::Command`].
 pub trait AsyncCommandExt: sealed::Sealed {
     /// Spawn, await completion, and capture stdout/stderr and exit status.
+    ///
+    /// # Errors
+    /// The spawn [`io::Error`] (e.g. the program is not found).
     fn captured(&mut self) -> impl Future<Output = io::Result<Captured>>;
 }
 
diff --git a/crates/hm-common/src/process/mod.rs b/crates/hm-common/src/process/mod.rs
index 0aa90a80..fc443b4f 100644
--- a/crates/hm-common/src/process/mod.rs
+++ b/crates/hm-common/src/process/mod.rs
@@ -6,4 +6,4 @@ pub mod which;
 pub use capture::{
     AsyncCommandExt, Captured, CapturedError, CapturedOk, CapturedStreams, CommandExt,
 };
-pub use which::{ExecutableNotFound, pathbin};
+pub use which::{ExecutableNotFound, SystemBins, git, pathbin, python3};
diff --git a/crates/hm-common/src/process/which.rs b/crates/hm-common/src/process/which.rs
index 261965e4..95da2f16 100644
--- a/crates/hm-common/src/process/which.rs
+++ b/crates/hm-common/src/process/which.rs
@@ -1,7 +1,7 @@
 //! Locating executables on `PATH`.
 
 use std::ffi::OsStr;
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 
 /// The requested program was not found on `PATH`.
 #[derive(Debug, thiserror::Error)]
@@ -23,6 +23,55 @@ pub fn pathbin(program: impl AsRef<OsStr>) -> Result<PathBuf, ExecutableNotFound
     })
 }
 
+/// Resolve `git` to its absolute path on `PATH`.
+///
+/// # Errors
+/// [`ExecutableNotFound`] if `git` is not on `PATH`.
+pub fn git() -> Result<PathBuf, ExecutableNotFound> {
+    pathbin("git")
+}
+
+/// Resolve `python3` to its absolute path on `PATH`.
+///
+/// # Errors
+/// [`ExecutableNotFound`] if `python3` is not on `PATH`.
+pub fn python3() -> Result<PathBuf, ExecutableNotFound> {
+    pathbin("python3")
+}
+
+/// The external executables Harmont shells out to, resolved from `PATH`.
+#[derive(Debug, Clone)]
+pub struct SystemBins {
+    python3: PathBuf,
+    git: Option<PathBuf>,
+}
+
+impl SystemBins {
+    /// Resolve the toolchain from `PATH`.
+    ///
+    /// # Errors
+    /// [`ExecutableNotFound`] if a required executable (`python3`) is missing.
+    /// Optional executables absent from `PATH` resolve to `None`.
+    pub fn resolve() -> Result<Self, ExecutableNotFound> {
+        Ok(Self {
+            python3: python3()?,
+            git: git().ok(),
+        })
+    }
+
+    /// Path to `python3`.
+    #[must_use]
+    pub fn python3(&self) -> &Path {
+        &self.python3
+    }
+
+    /// Path to `git`, or `None` if it was not on `PATH` at resolution.
+    #[must_use]
+    pub fn git(&self) -> Option<&Path> {
+        self.git.as_deref()
+    }
+}
+
 #[cfg(test)]
 #[allow(clippy::unwrap_used, reason = "test setup and assertions")]
 mod tests {
@@ -50,4 +99,29 @@ mod tests {
         assert!(msg.contains("hm-common-no-such-binary-xyz"), "program: {msg}");
         assert!(msg.contains("not found on PATH"), "phrasing: {msg}");
     }
+
+    #[rstest]
+    #[case::git("git")]
+    #[case::python3("python3")]
+    fn alias_matches_pathbin(#[case] program: &str) {
+        let via_alias = if program == "git" { git() } else { python3() };
+        assert_eq!(via_alias.ok(), pathbin(program).ok());
+    }
+
+    #[rstest]
+    fn resolve_succeeds_when_python3_is_present() {
+        assert_eq!(SystemBins::resolve().is_ok(), python3().is_ok());
+    }
+
+    #[rstest]
+    #[case::with_git(Some(PathBuf::from("/opt/git")))]
+    #[case::without_git(None)]
+    fn system_bins_exposes_paths(#[case] git: Option<PathBuf>) {
+        let bins = SystemBins {
+            python3: PathBuf::from("/opt/python3"),
+            git: git.clone(),
+        };
+        assert_eq!(bins.python3(), Path::new("/opt/python3"));
+        assert_eq!(bins.git(), git.as_deref());
+    }
 }
diff --git a/crates/hm-dsl-engine/src/python_engine.rs b/crates/hm-dsl-engine/src/python_engine.rs
index 38ae5498..0c85f6b7 100644
--- a/crates/hm-dsl-engine/src/python_engine.rs
+++ b/crates/hm-dsl-engine/src/python_engine.rs
@@ -2,7 +2,7 @@ use std::path::Path;
 
 use anyhow::{Context, Result};
 use async_trait::async_trait;
-use hm_common::process::{AsyncCommandExt as _, CapturedStreams as _, pathbin};
+use hm_common::process::{AsyncCommandExt as _, CapturedStreams as _, python3};
 use tracing::debug;
 
 use crate::bundled_sources;
@@ -70,7 +70,7 @@ impl SubprocessPythonEngine {
     ///
     /// Returns an error if `python3` is not found on `PATH`.
     pub fn new() -> Result<Self> {
-        let python_bin = pathbin("python3").context("install Python 3.11+")?;
+        let python_bin = python3().context("install Python 3.11+")?;
         Ok(Self { python_bin })
     }
 

From a33bca5ab32bc88dd5c2519e9d1c5c98038f5cab Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 16:16:16 -0700
Subject: [PATCH 06/18] refactor(hm-common): make git required in SystemBins

git is a hard dependency for a developer tool, so SystemBins.git is a
PathBuf (not Option) and resolve() fails fast when git is absent from
PATH. Simplifies git() to return &Path.
---
 crates/hm-common/src/process/which.rs | 25 +++++++++++--------------
 1 file changed, 11 insertions(+), 14 deletions(-)

diff --git a/crates/hm-common/src/process/which.rs b/crates/hm-common/src/process/which.rs
index 95da2f16..247667d4 100644
--- a/crates/hm-common/src/process/which.rs
+++ b/crates/hm-common/src/process/which.rs
@@ -43,19 +43,18 @@ pub fn python3() -> Result<PathBuf, ExecutableNotFound> {
 #[derive(Debug, Clone)]
 pub struct SystemBins {
     python3: PathBuf,
-    git: Option<PathBuf>,
+    git: PathBuf,
 }
 
 impl SystemBins {
     /// Resolve the toolchain from `PATH`.
     ///
     /// # Errors
-    /// [`ExecutableNotFound`] if a required executable (`python3`) is missing.
-    /// Optional executables absent from `PATH` resolve to `None`.
+    /// [`ExecutableNotFound`] if `python3` or `git` is not on `PATH`.
     pub fn resolve() -> Result<Self, ExecutableNotFound> {
         Ok(Self {
             python3: python3()?,
-            git: git().ok(),
+            git: git()?,
         })
     }
 
@@ -65,10 +64,10 @@ impl SystemBins {
         &self.python3
     }
 
-    /// Path to `git`, or `None` if it was not on `PATH` at resolution.
+    /// Path to `git`.
     #[must_use]
-    pub fn git(&self) -> Option<&Path> {
-        self.git.as_deref()
+    pub fn git(&self) -> &Path {
+        &self.git
     }
 }
 
@@ -109,19 +108,17 @@ mod tests {
     }
 
     #[rstest]
-    fn resolve_succeeds_when_python3_is_present() {
-        assert_eq!(SystemBins::resolve().is_ok(), python3().is_ok());
+    fn resolve_succeeds_when_python3_and_git_present() {
+        assert_eq!(SystemBins::resolve().is_ok(), python3().is_ok() && git().is_ok());
     }
 
     #[rstest]
-    #[case::with_git(Some(PathBuf::from("/opt/git")))]
-    #[case::without_git(None)]
-    fn system_bins_exposes_paths(#[case] git: Option<PathBuf>) {
+    fn system_bins_exposes_paths() {
         let bins = SystemBins {
             python3: PathBuf::from("/opt/python3"),
-            git: git.clone(),
+            git: PathBuf::from("/opt/git"),
         };
         assert_eq!(bins.python3(), Path::new("/opt/python3"));
-        assert_eq!(bins.git(), git.as_deref());
+        assert_eq!(bins.git(), Path::new("/opt/git"));
     }
 }

From 9937ee785811f4fdd9a9d0bfa52995b0d48fa1ec Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 16:31:36 -0700
Subject: [PATCH 07/18] feat(hm-common): add AppRuntime behind app-runtime
 feature

Add a process-global runtime context, gated behind the opt-in
`app-runtime` feature. AppRuntime::init() resolves SystemBins and
captures the absolute cwd once, installing them in a OnceLock; the
associated bins()/cwd() accessors read the global from anywhere with no
threading, panicking only if used before init. init() fails fast with a
typed InitError when a required executable is missing.
---
 crates/hm-common/Cargo.toml         |   5 ++
 crates/hm-common/src/app_runtime.rs | 125 ++++++++++++++++++++++++++++
 crates/hm-common/src/lib.rs         |   2 +
 3 files changed, 132 insertions(+)
 create mode 100644 crates/hm-common/src/app_runtime.rs

diff --git a/crates/hm-common/Cargo.toml b/crates/hm-common/Cargo.toml
index 888a08ee..6f9dee16 100644
--- a/crates/hm-common/Cargo.toml
+++ b/crates/hm-common/Cargo.toml
@@ -11,6 +11,11 @@ categories = ["command-line-utilities"]
 [lib]
 path = "src/lib.rs"
 
+[features]
+# Process-global application runtime (AppRuntime). Opt-in — only the binary
+# that owns process startup should enable it.
+app-runtime = []
+
 [dependencies]
 anyhow      = { workspace = true }
 async-trait = { workspace = true }
diff --git a/crates/hm-common/src/app_runtime.rs b/crates/hm-common/src/app_runtime.rs
new file mode 100644
index 00000000..c7215b80
--- /dev/null
+++ b/crates/hm-common/src/app_runtime.rs
@@ -0,0 +1,125 @@
+//! Application runtime context.
+
+use std::path::{Path, PathBuf};
+use std::sync::OnceLock;
+
+use crate::process::{ExecutableNotFound, SystemBins};
+
+/// Failure to initialize the [`AppRuntime`].
+#[derive(Debug, thiserror::Error)]
+pub enum InitError {
+    /// A required executable was missing from `PATH`.
+    #[error(transparent)]
+    Executables(#[from] ExecutableNotFound),
+    /// The current directory could not be read.
+    #[error("reading the current directory")]
+    Cwd(#[source] std::io::Error),
+}
+
+/// Process-wide runtime context, resolved once at startup.
+///
+/// Install it with [`init`](Self::init), then read it from anywhere through the
+/// associated accessors — no threading required.
+#[derive(Debug)]
+pub struct AppRuntime {
+    bins: SystemBins,
+    cwd: PathBuf,
+}
+
+static RUNTIME: OnceLock<AppRuntime> = OnceLock::new();
+
+impl AppRuntime {
+    /// Resolve the runtime and install it as the process-wide singleton.
+    ///
+    /// Call once, early in `main`, before any accessor. A later call is ignored.
+    ///
+    /// # Errors
+    /// [`InitError`] if a required executable is missing from `PATH` or the
+    /// current directory cannot be read.
+    pub fn init() -> Result<(), InitError> {
+        let runtime = Self::resolve()?;
+        let _ = RUNTIME.set(runtime);
+        Ok(())
+    }
+
+    fn resolve() -> Result<Self, InitError> {
+        Ok(Self {
+            bins: SystemBins::resolve()?,
+            cwd: std::env::current_dir().map_err(InitError::Cwd)?,
+        })
+    }
+
+    #[allow(
+        clippy::expect_used,
+        reason = "accessing the runtime before init is a startup bug, not a runtime error"
+    )]
+    fn get() -> &'static Self {
+        RUNTIME
+            .get()
+            .expect("AppRuntime::init must be called before the runtime is accessed")
+    }
+
+    /// The resolved system executables.
+    ///
+    /// # Panics
+    /// If [`init`](Self::init) has not been called.
+    #[must_use]
+    pub fn bins() -> &'static SystemBins {
+        &Self::get().bins
+    }
+
+    /// The absolute working directory captured at initialization.
+    ///
+    /// # Panics
+    /// If [`init`](Self::init) has not been called.
+    #[must_use]
+    pub fn cwd() -> &'static Path {
+        &Self::get().cwd
+    }
+}
+
+#[cfg(test)]
+#[allow(
+    clippy::unwrap_used,
+    clippy::print_stderr,
+    reason = "test setup, assertions, and skip diagnostics"
+)]
+mod tests {
+    use super::*;
+    use crate::process::{git, pathbin, python3};
+    use rstest::rstest;
+
+    #[rstest]
+    fn resolve_reports_toolchain_availability() {
+        assert_eq!(
+            AppRuntime::resolve().is_ok(),
+            python3().is_ok() && git().is_ok()
+        );
+    }
+
+    #[rstest]
+    fn resolve_captures_an_absolute_cwd() {
+        let Ok(runtime) = AppRuntime::resolve() else {
+            eprintln!("skipping: toolchain unavailable");
+            return;
+        };
+        assert!(runtime.cwd.is_absolute(), "cwd was {:?}", runtime.cwd);
+    }
+
+    #[rstest]
+    fn init_installs_a_globally_accessible_runtime() {
+        if AppRuntime::resolve().is_err() {
+            eprintln!("skipping: toolchain unavailable");
+            return;
+        }
+        AppRuntime::init().unwrap();
+        assert!(AppRuntime::cwd().is_absolute());
+        assert!(AppRuntime::bins().git().is_absolute());
+    }
+
+    #[rstest]
+    fn init_error_wraps_a_missing_executable() {
+        let err: InitError = pathbin("hm-common-no-such-binary-xyz").unwrap_err().into();
+        assert!(matches!(err, InitError::Executables(_)));
+    }
+}
diff --git a/crates/hm-common/src/lib.rs b/crates/hm-common/src/lib.rs
index a3115457..ee6ba357 100644
--- a/crates/hm-common/src/lib.rs
+++ b/crates/hm-common/src/lib.rs
@@ -1,5 +1,7 @@
 //! Harmont common utilities shared across the `hm` workspace.
 
+#[cfg(feature = "app-runtime")]
+pub mod app_runtime;
 pub mod format;
 pub mod fs;
 pub mod process;

From b72a27677cde71e81e20b3b8f3ce8565d316cc90 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 16:50:26 -0700
Subject: [PATCH 08/18] deslop

---
 crates/hm-common/src/process/capture.rs | 21 ---------------------
 crates/hm/Cargo.toml                    |  2 +-
 crates/hm/src/commands/run/mod.rs       |  9 +++++++--
 3 files changed, 8 insertions(+), 24 deletions(-)

diff --git a/crates/hm-common/src/process/capture.rs b/crates/hm-common/src/process/capture.rs
index af852851..c7697724 100644
--- a/crates/hm-common/src/process/capture.rs
+++ b/crates/hm-common/src/process/capture.rs
@@ -28,9 +28,6 @@ pub struct Captured {
 
 impl Captured {
     /// Split on the exit status: `Ok` if the process exited 0, else `Err`.
-    ///
-    /// # Errors
-    /// [`CapturedError`] when the process exited non-zero or was killed by a signal.
     pub fn success(self) -> Result<CapturedOk, CapturedError> {
         if self.status.success() {
             Ok(CapturedOk(self))
@@ -99,31 +96,19 @@ pub trait CapturedStreams: sealed::Sealed {
     }
 
     /// stdout as UTF-8, borrowed.
-    ///
-    /// # Errors
-    /// Returns [`Utf8Error`] if stdout is not valid UTF-8.
     fn stdout_str(&self) -> Result<&str, Utf8Error> {
         std::str::from_utf8(self.stdout())
     }
     /// stderr as UTF-8, borrowed.
-    ///
-    /// # Errors
-    /// Returns [`Utf8Error`] if stderr is not valid UTF-8.
     fn stderr_str(&self) -> Result<&str, Utf8Error> {
         std::str::from_utf8(self.stderr())
     }
 
     /// stdout as an owned UTF-8 `String`.
-    ///
-    /// # Errors
-    /// Returns [`Utf8Error`] if stdout is not valid UTF-8.
     fn stdout_string(&self) -> Result<String, Utf8Error> {
         self.stdout_str().map(str::to_owned)
     }
     /// stderr as an owned UTF-8 `String`.
-    ///
-    /// # Errors
-    /// Returns [`Utf8Error`] if stderr is not valid UTF-8.
     fn stderr_string(&self) -> Result<String, Utf8Error> {
         self.stderr_str().map(str::to_owned)
     }
@@ -187,9 +172,6 @@ impl CapturedStreams for CapturedError {
 /// Adds [`captured`](CommandExt::captured) to [`std::process::Command`].
 pub trait CommandExt: sealed::Sealed {
     /// Spawn, wait for completion, and capture stdout/stderr and exit status.
-    ///
-    /// # Errors
-    /// The spawn [`io::Error`] (e.g. the program is not found).
     fn captured(&mut self) -> io::Result<Captured>;
 }
 
@@ -209,9 +191,6 @@ impl CommandExt for std::process::Command {
 /// Adds [`captured`](AsyncCommandExt::captured) to [`tokio::process::Command`].
 pub trait AsyncCommandExt: sealed::Sealed {
     /// Spawn, await completion, and capture stdout/stderr and exit status.
-    ///
-    /// # Errors
-    /// The spawn [`io::Error`] (e.g. the program is not found).
     fn captured(&mut self) -> impl Future<Output = io::Result<Captured>>;
 }
 
diff --git a/crates/hm/Cargo.toml b/crates/hm/Cargo.toml
index aea2a5cb..eb69c570 100644
--- a/crates/hm/Cargo.toml
+++ b/crates/hm/Cargo.toml
@@ -58,7 +58,7 @@ futures = "0.3"
 futures-util = "0.3"
 hm-pipeline-ir     = { workspace = true }
 hm-plugin-protocol = { workspace = true }
-hm-common = { workspace = true }
+hm-common = { workspace = true, features = ["app-runtime"] }
 hm-util = { workspace = true }
 hm-config = { workspace = true }
 hm-plugin-cloud = { workspace = true }
diff --git a/crates/hm/src/commands/run/mod.rs b/crates/hm/src/commands/run/mod.rs
index 5a7e07ec..ed200c50 100644
--- a/crates/hm/src/commands/run/mod.rs
+++ b/crates/hm/src/commands/run/mod.rs
@@ -2,6 +2,7 @@ use std::collections::HashMap;
 
 use anyhow::{Context, Result};
 
+use hm_common::app_runtime::AppRuntime;
 use hm_common::process::{CapturedStreams as _, CommandExt as _};
 use hm_dsl_engine::{DslEngine, detect};
 use human_units::FormatSize as _;
@@ -34,6 +35,10 @@ use crate::error::{ErrorCategory, HmError};
 /// unreachable, the local daemon is down, or the pipeline fails to render.
 #[allow(clippy::too_many_lines)] // thin top-level driver: linear, no good split point
 pub async fn handle(args: RunArgs, ctx: RunContext) -> Result<i32> {
+    // `hm run` needs the build toolchain (git + python3). Resolve it once up
+    // front, failing fast with a clear error when anything is missing.
+    AppRuntime::init().context("resolving the build toolchain")?;
+
     // 1. Resolve the backend name: explicit --backend > legacy --cloud alias >
     //    config.backend (figment-layered default "docker").
     let backend_name = args
@@ -243,7 +248,7 @@ fn parse_env(pairs: &[String]) -> HashMap<String, String> {
 /// `branch_override` wins; missing values fall back to `HEAD` / the zero SHA.
 /// `git -C <root> <args...>`, ready to `.captured()`.
 fn git_at(root: &std::path::Path, args: &[&str]) -> std::process::Command {
-    let mut cmd = std::process::Command::new("git");
+    let mut cmd = std::process::Command::new(AppRuntime::bins().git());
     cmd.arg("-C").arg(root).args(args);
     cmd
 }
@@ -345,7 +350,7 @@ async fn render_pipeline(
 ) -> Result<(std::path::PathBuf, String, String)> {
     let repo_root = match args.dir.clone() {
         Some(p) => p,
-        None => std::env::current_dir().context("cannot determine current directory")?,
+        None => AppRuntime::cwd().to_path_buf(),
     };
 
     detect::check_python(&repo_root).map_err(|e| HmError::DslEngine(format!("{e:#}")))?;

From aa1cec62639b3e833cedf7191f91010863780057 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 16:51:11 -0700
Subject: [PATCH 09/18] more deslop

---
 crates/hm-common/src/process/which.rs | 12 ------------
 crates/hm/src/commands/run/mod.rs     |  2 +-
 2 files changed, 1 insertion(+), 13 deletions(-)

diff --git a/crates/hm-common/src/process/which.rs b/crates/hm-common/src/process/which.rs
index 247667d4..65ef0eba 100644
--- a/crates/hm-common/src/process/which.rs
+++ b/crates/hm-common/src/process/which.rs
@@ -13,9 +13,6 @@ pub struct ExecutableNotFound {
 /// Resolve `program` to its absolute path on `PATH`.
 ///
 /// For a presence check, call `pathbin(program).is_ok()`.
-///
-/// # Errors
-/// Returns [`ExecutableNotFound`] if `program` is not an executable on `PATH`.
 pub fn pathbin(program: impl AsRef<OsStr>) -> Result<PathBuf, ExecutableNotFound> {
     let program = program.as_ref();
     which::which(program).map_err(|_| ExecutableNotFound {
@@ -24,17 +21,11 @@ pub fn pathbin(program: impl AsRef<OsStr>) -> Result<PathBuf, ExecutableNotFound
 }
 
 /// Resolve `git` to its absolute path on `PATH`.
-///
-/// # Errors
-/// [`ExecutableNotFound`] if `git` is not on `PATH`.
 pub fn git() -> Result<PathBuf, ExecutableNotFound> {
     pathbin("git")
 }
 
 /// Resolve `python3` to its absolute path on `PATH`.
-///
-/// # Errors
-/// [`ExecutableNotFound`] if `python3` is not on `PATH`.
 pub fn python3() -> Result<PathBuf, ExecutableNotFound> {
     pathbin("python3")
 }
@@ -48,9 +39,6 @@ pub struct SystemBins {
 
 impl SystemBins {
     /// Resolve the toolchain from `PATH`.
-    ///
-    /// # Errors
-    /// [`ExecutableNotFound`] if `python3` or `git` is not on `PATH`.
     pub fn resolve() -> Result<Self, ExecutableNotFound> {
         Ok(Self {
             python3: python3()?,
diff --git a/crates/hm/src/commands/run/mod.rs b/crates/hm/src/commands/run/mod.rs
index ed200c50..e2f47860 100644
--- a/crates/hm/src/commands/run/mod.rs
+++ b/crates/hm/src/commands/run/mod.rs
@@ -248,7 +248,7 @@ fn parse_env(pairs: &[String]) -> HashMap<String, String> {
 /// `branch_override` wins; missing values fall back to `HEAD` / the zero SHA.
 /// `git -C <root> <args...>`, ready to `.captured()`.
 fn git_at(root: &std::path::Path, args: &[&str]) -> std::process::Command {
-    let mut cmd = std::process::Command::new(AppRuntime::bins().git());
+    let mut cmd = std::process::Command::new("git");
     cmd.arg("-C").arg(root).args(args);
     cmd
 }

From 4bd3b95b3531763c6d5b67a629d0381c12a66c2b Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 16:55:34 -0700
Subject: [PATCH 10/18] refactor(hm-common): drop git()/python3() pathbin
 aliases

Remove the git()/python3() convenience wrappers; callers and
SystemBins::resolve use pathbin("git")/pathbin("python3") directly.
---
 crates/hm-common/Cargo.toml               |  2 --
 crates/hm-common/src/app_runtime.rs       |  4 ++--
 crates/hm-common/src/process/mod.rs       |  2 +-
 crates/hm-common/src/process/which.rs     | 27 +++++------------------
 crates/hm-dsl-engine/src/python_engine.rs |  4 ++--
 5 files changed, 11 insertions(+), 28 deletions(-)

diff --git a/crates/hm-common/Cargo.toml b/crates/hm-common/Cargo.toml
index 6f9dee16..d401bac2 100644
--- a/crates/hm-common/Cargo.toml
+++ b/crates/hm-common/Cargo.toml
@@ -12,8 +12,6 @@ categories = ["command-line-utilities"]
 path = "src/lib.rs"
 
 [features]
-# Process-global application runtime (AppRuntime). Opt-in — only the binary
-# that owns process startup should enable it.
 app-runtime = []
 
 [dependencies]
diff --git a/crates/hm-common/src/app_runtime.rs b/crates/hm-common/src/app_runtime.rs
index c7215b80..d13c259d 100644
--- a/crates/hm-common/src/app_runtime.rs
+++ b/crates/hm-common/src/app_runtime.rs
@@ -86,14 +86,14 @@ impl AppRuntime {
 )]
 mod tests {
     use super::*;
-    use crate::process::{git, pathbin, python3};
+    use crate::process::pathbin;
     use rstest::rstest;
 
     #[rstest]
     fn resolve_reports_toolchain_availability() {
         assert_eq!(
             AppRuntime::resolve().is_ok(),
-            python3().is_ok() && git().is_ok()
+            pathbin("python3").is_ok() && pathbin("git").is_ok()
         );
     }
 
diff --git a/crates/hm-common/src/process/mod.rs b/crates/hm-common/src/process/mod.rs
index fc443b4f..4d55220c 100644
--- a/crates/hm-common/src/process/mod.rs
+++ b/crates/hm-common/src/process/mod.rs
@@ -6,4 +6,4 @@ pub mod which;
 pub use capture::{
     AsyncCommandExt, Captured, CapturedError, CapturedOk, CapturedStreams, CommandExt,
 };
-pub use which::{ExecutableNotFound, SystemBins, git, pathbin, python3};
+pub use which::{ExecutableNotFound, SystemBins, pathbin};
diff --git a/crates/hm-common/src/process/which.rs b/crates/hm-common/src/process/which.rs
index 65ef0eba..cf2f534b 100644
--- a/crates/hm-common/src/process/which.rs
+++ b/crates/hm-common/src/process/which.rs
@@ -20,16 +20,6 @@ pub fn pathbin(program: impl AsRef<OsStr>) -> Result<PathBuf, ExecutableNotFound
     })
 }
 
-/// Resolve `git` to its absolute path on `PATH`.
-pub fn git() -> Result<PathBuf, ExecutableNotFound> {
-    pathbin("git")
-}
-
-/// Resolve `python3` to its absolute path on `PATH`.
-pub fn python3() -> Result<PathBuf, ExecutableNotFound> {
-    pathbin("python3")
-}
-
 /// The external executables Harmont shells out to, resolved from `PATH`.
 #[derive(Debug, Clone)]
 pub struct SystemBins {
@@ -41,8 +31,8 @@ impl SystemBins {
     /// Resolve the toolchain from `PATH`.
     pub fn resolve() -> Result<Self, ExecutableNotFound> {
         Ok(Self {
-            python3: python3()?,
-            git: git()?,
+            python3: pathbin("python3")?,
+            git: pathbin("git")?,
         })
     }
 
@@ -87,17 +77,12 @@ mod tests {
         assert!(msg.contains("not found on PATH"), "phrasing: {msg}");
     }
 
-    #[rstest]
-    #[case::git("git")]
-    #[case::python3("python3")]
-    fn alias_matches_pathbin(#[case] program: &str) {
-        let via_alias = if program == "git" { git() } else { python3() };
-        assert_eq!(via_alias.ok(), pathbin(program).ok());
-    }
-
     #[rstest]
     fn resolve_succeeds_when_python3_and_git_present() {
-        assert_eq!(SystemBins::resolve().is_ok(), python3().is_ok() && git().is_ok());
+        assert_eq!(
+            SystemBins::resolve().is_ok(),
+            pathbin("python3").is_ok() && pathbin("git").is_ok()
+        );
     }
 
     #[rstest]
diff --git a/crates/hm-dsl-engine/src/python_engine.rs b/crates/hm-dsl-engine/src/python_engine.rs
index 0c85f6b7..38ae5498 100644
--- a/crates/hm-dsl-engine/src/python_engine.rs
+++ b/crates/hm-dsl-engine/src/python_engine.rs
@@ -2,7 +2,7 @@ use std::path::Path;
 
 use anyhow::{Context, Result};
 use async_trait::async_trait;
-use hm_common::process::{AsyncCommandExt as _, CapturedStreams as _, python3};
+use hm_common::process::{AsyncCommandExt as _, CapturedStreams as _, pathbin};
 use tracing::debug;
 
 use crate::bundled_sources;
@@ -70,7 +70,7 @@ impl SubprocessPythonEngine {
     ///
     /// Returns an error if `python3` is not found on `PATH`.
     pub fn new() -> Result<Self> {
-        let python_bin = python3().context("install Python 3.11+")?;
+        let python_bin = pathbin("python3").context("install Python 3.11+")?;
         Ok(Self { python_bin })
     }
 

From cdb5b3d4e5caf1be0fea60604007500cf551e058 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 17:02:31 -0700
Subject: [PATCH 11/18] refactor(hm): resolve the build toolchain in main, for
 every command

Move AppRuntime::init() out of `hm run` and into run() in main, so the
toolchain (git + python3) is resolved once for every command and a
missing tool fails fast with a clear error. It runs after arg parsing,
so --help/--version and parse errors are not gated on it.
---
 crates/hm/src/commands/run/mod.rs | 4 ----
 crates/hm/src/main.rs             | 6 ++++++
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/crates/hm/src/commands/run/mod.rs b/crates/hm/src/commands/run/mod.rs
index e2f47860..0a304bc4 100644
--- a/crates/hm/src/commands/run/mod.rs
+++ b/crates/hm/src/commands/run/mod.rs
@@ -35,10 +35,6 @@ use crate::error::{ErrorCategory, HmError};
 /// unreachable, the local daemon is down, or the pipeline fails to render.
 #[allow(clippy::too_many_lines)] // thin top-level driver: linear, no good split point
 pub async fn handle(args: RunArgs, ctx: RunContext) -> Result<i32> {
-    // `hm run` needs the build toolchain (git + python3). Resolve it once up
-    // front, failing fast with a clear error when anything is missing.
-    AppRuntime::init().context("resolving the build toolchain")?;
-
     // 1. Resolve the backend name: explicit --backend > legacy --cloud alias >
     //    config.backend (figment-layered default "docker").
     let backend_name = args
diff --git a/crates/hm/src/main.rs b/crates/hm/src/main.rs
index 84e9c93c..dae1a46e 100644
--- a/crates/hm/src/main.rs
+++ b/crates/hm/src/main.rs
@@ -3,7 +3,9 @@
     reason = "transitive dependency version conflicts in rand/windows-sys/thiserror chains; not fixable without upstream updates"
 )]
 
+use anyhow::Context as _;
 use clap::Parser;
+use hm_common::app_runtime::AppRuntime;
 use tracing_subscriber::EnvFilter;
 use tracing_subscriber::Layer;
 use tracing_subscriber::filter::Targets;
@@ -89,6 +91,10 @@ async fn main() {
 }
 
 async fn run(args: Cli) -> Result<i32, anyhow::Error> {
+    // Every command runs against the build toolchain (git + python3); resolve it
+    // once up front and fail fast with a clear error if anything is missing.
+    AppRuntime::init().context("resolving the build toolchain")?;
+
     let command = args.command.clone();
     let ctx = RunContext::from_cli(&args)?;
     cli::dispatch(command, ctx).await

From 42a996e2f5f3043d8bb8289b97128f048c880910 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 17:45:00 -0700
Subject: [PATCH 12/18] feat(hm-common): add git module; wire hm run onto it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add hm_common::git: a typed handle hierarchy over the git CLI —
Git(bin) → GitRepo(repo) → GitBranch / GitRemote — driven through
process::capture. GitRepo::repo() validates the work tree
(InvalidRepoError); operations are best-effort (Option). Raw git output
is exposed as bstr BString/BStr. Every method that shells out is
#[instrument]-ed.

Refactor hm run to use it: git_metadata / git_remote_url /
git_default_branch / git_remote_repo_name now take a Git built from
AppRuntime::bins().git() (finally consuming the resolved git path), and
the git_at helper plus the repo-name / default-branch parsers (with
their tests) move into the git module.

Also instrument process::capture::captured (sync + async) and
which::pathbin, per the observability goal. Adds bstr to hm-common and
hm.
---
 Cargo.lock                              |   2 +
 crates/hm-common/Cargo.toml             |   1 +
 crates/hm-common/src/git.rs             | 275 ++++++++++++++++++++++++
 crates/hm-common/src/lib.rs             |   1 +
 crates/hm-common/src/process/capture.rs |   2 +
 crates/hm-common/src/process/which.rs   |   1 +
 crates/hm/Cargo.toml                    |   1 +
 crates/hm/src/commands/run/mod.rs       | 141 +++---------
 8 files changed, 318 insertions(+), 106 deletions(-)
 create mode 100644 crates/hm-common/src/git.rs

diff --git a/Cargo.lock b/Cargo.lock
index 3650ff33..018a5aa6 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1112,6 +1112,7 @@ dependencies = [
  "axum",
  "backon",
  "base64",
+ "bstr",
  "bytes",
  "chrono",
  "clap",
@@ -1256,6 +1257,7 @@ version = "0.0.0-dev"
 dependencies = [
  "anyhow",
  "async-trait",
+ "bstr",
  "derive_more",
  "include_dir",
  "proptest",
diff --git a/crates/hm-common/Cargo.toml b/crates/hm-common/Cargo.toml
index d401bac2..a87154cd 100644
--- a/crates/hm-common/Cargo.toml
+++ b/crates/hm-common/Cargo.toml
@@ -21,6 +21,7 @@ derive_more = { workspace = true }
 serde       = { workspace = true }
 serde_json  = { workspace = true }
 thiserror   = { workspace = true }
+bstr        = "1"
 include_dir = "0.7"
 tempfile    = "3"
 tokio       = { version = "1", features = ["process", "fs"] }
diff --git a/crates/hm-common/src/git.rs b/crates/hm-common/src/git.rs
new file mode 100644
index 00000000..61dc2473
--- /dev/null
+++ b/crates/hm-common/src/git.rs
@@ -0,0 +1,275 @@
+//! Running git.
+
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use bstr::{BStr, BString, ByteSlice};
+
+use crate::process::{CapturedStreams as _, CommandExt as _};
+
+/// A path that is not a git repository.
+#[derive(Debug, thiserror::Error)]
+#[error("`{path}` is not a git repository")]
+pub struct InvalidRepoError {
+    path: PathBuf,
+}
+
+/// A resolved `git` executable.
+#[derive(Debug, Clone, Copy)]
+pub struct Git<'bin> {
+    bin: &'bin Path,
+}
+
+impl<'bin> Git<'bin> {
+    /// Wrap a `git` executable, typically `AppRuntime::bins().git()`.
+    #[must_use]
+    pub const fn new(bin: &'bin Path) -> Self {
+        Self { bin }
+    }
+
+    /// Bind to the git work tree at `repo`.
+    ///
+    /// # Errors
+    /// [`InvalidRepoError`] if `repo` is not inside a git work tree.
+    #[tracing::instrument(skip(self))]
+    pub fn repo<'g>(&'g self, repo: &'g Path) -> Result<GitRepo<'g, 'bin>, InvalidRepoError> {
+        let bound = GitRepo { git: self, repo };
+        if bound.run(&["rev-parse", "--git-dir"]).is_some() {
+            Ok(bound)
+        } else {
+            Err(InvalidRepoError {
+                path: repo.to_path_buf(),
+            })
+        }
+    }
+}
+
+/// A git work tree, bound to a [`Git`] and a repository path.
+#[derive(Debug, Clone, Copy)]
+pub struct GitRepo<'g, 'bin> {
+    git: &'g Git<'bin>,
+    repo: &'g Path,
+}
+
+impl<'g, 'bin> GitRepo<'g, 'bin> {
+    /// Run `git -C <repo> <args>`, returning trimmed stdout on a zero exit.
+    /// `None` on spawn failure, a non-zero exit, or empty output.
+    fn run(&self, args: &[&str]) -> Option<BString> {
+        let mut cmd = Command::new(self.git.bin);
+        cmd.arg("-C").arg(self.repo).args(args);
+        let out = cmd.captured().ok()?.success().ok()?;
+        let trimmed = out.stdout().trim();
+        (!trimmed.is_empty()).then(|| BString::from(trimmed))
+    }
+
+    /// The checked-out branch (`HEAD` when detached). `None` if git fails.
+    #[tracing::instrument(skip(self))]
+    pub fn current_branch(&self) -> Option<GitBranch<'_, 'g, 'bin>> {
+        let name = self.run(&["rev-parse", "--abbrev-ref", "HEAD"])?;
+        Some(GitBranch { repo: self, name })
+    }
+
+    /// The named remote, or `None` when it is not configured.
+    #[tracing::instrument(skip(self))]
+    pub fn remote(&self, name: &str) -> Option<GitRemote<'_, 'g, 'bin>> {
+        let url = self.run(&["config", "--get", &format!("remote.{name}.url")])?;
+        Some(GitRemote {
+            repo: self,
+            name: name.to_owned(),
+            url,
+        })
+    }
+}
+
+/// A branch in a [`GitRepo`].
+#[derive(Debug, Clone)]
+pub struct GitBranch<'r, 'g, 'bin> {
+    repo: &'r GitRepo<'g, 'bin>,
+    name: BString,
+}
+
+impl<'r, 'g, 'bin> GitBranch<'r, 'g, 'bin> {
+    /// The branch name (e.g. `main`, or `HEAD` when detached).
+    #[must_use]
+    pub fn name(&self) -> &BStr {
+        self.name.as_bstr()
+    }
+
+    /// The commit the branch points at, as a hex object id. `None` if git fails.
+    #[tracing::instrument(skip(self))]
+    pub fn head_commit(&self) -> Option<BString> {
+        let name = self.name.to_str().ok()?;
+        self.repo.run(&["rev-parse", name])
+    }
+}
+
+/// A remote of a [`GitRepo`].
+#[derive(Debug, Clone)]
+pub struct GitRemote<'r, 'g, 'bin> {
+    repo: &'r GitRepo<'g, 'bin>,
+    name: String,
+    url: BString,
+}
+
+impl<'r, 'g, 'bin> GitRemote<'r, 'g, 'bin> {
+    /// The remote's name (e.g. `origin`).
+    #[must_use]
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    /// The remote's configured URL.
+    #[must_use]
+    pub fn url(&self) -> &BStr {
+        self.url.as_bstr()
+    }
+
+    /// `owner/repo` parsed from the remote URL, mirroring the backend's
+    /// `Harmont.Pipelines.RepoName`. `None` when fewer than two path segments
+    /// remain.
+    #[must_use]
+    pub fn gh_repo_name(&self) -> Option<BString> {
+        parse_gh_repo_name(self.url.as_bstr())
+    }
+
+    /// The remote's default branch, from its `HEAD` symbolic ref. `None` when
+    /// `<remote>/HEAD` is unset (common on fresh clones).
+    #[tracing::instrument(skip(self))]
+    pub fn default_branch(&self) -> Option<GitBranch<'r, 'g, 'bin>> {
+        let line = self
+            .repo
+            .run(&["symbolic-ref", &format!("refs/remotes/{}/HEAD", self.name)])?;
+        let name = parse_default_branch(line.as_bstr(), &self.name)?;
+        Some(GitBranch {
+            repo: self.repo,
+            name,
+        })
+    }
+}
+
+/// Extract `owner/repo` from a remote URL: drop scheme/host and a trailing
+/// `.git`, then take the last two non-empty path segments.
+fn parse_gh_repo_name(url: &BStr) -> Option<BString> {
+    let url = url.to_str().ok()?.trim();
+    let path = if let Some((_, rest)) = url.split_once("://") {
+        rest.split_once('/').map_or(rest, |(_, p)| p)
+    } else if url.contains('@') && url.contains(':') {
+        let after_at = url.split_once('@').map_or(url, |(_, r)| r);
+        after_at.split_once(':').map_or(after_at, |(_, p)| p)
+    } else {
+        url.split_once('/').map_or(url, |(_, p)| p)
+    };
+    let path = path.trim_end_matches('/');
+    let path = path.strip_suffix(".git").unwrap_or(path);
+    let segs: Vec<&str> = path.split('/').filter(|s| !s.is_empty()).collect();
+    if segs.len() < 2 {
+        return None;
+    }
+    Some(BString::from(segs[segs.len() - 2..].join("/")))
+}
+
+/// Extract the branch name from a `symbolic-ref refs/remotes/<remote>/HEAD`
+/// result (e.g. `refs/remotes/origin/main` → `main`).
+fn parse_default_branch(line: &BStr, remote: &str) -> Option<BString> {
+    let line = line.to_str().ok()?.trim();
+    let branch = line.strip_prefix(&format!("refs/remotes/{remote}/"))?;
+    (!branch.is_empty()).then(|| BString::from(branch))
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used, reason = "test setup and assertions")]
+mod tests {
+    use super::*;
+    use rstest::rstest;
+
+    #[rstest]
+    #[case::https("https://github.com/acme/web.git", Some("acme/web"))]
+    #[case::https_no_suffix("https://github.com/acme/web", Some("acme/web"))]
+    #[case::scp("git@github.com:acme/web.git", Some("acme/web"))]
+    #[case::ssh("ssh://git@github.com/acme/web", Some("acme/web"))]
+    #[case::trailing_slash("https://github.com/acme/web/", Some("acme/web"))]
+    #[case::nested("https://gitlab.com/group/sub/web.git", Some("sub/web"))]
+    #[case::deep_path("https://example.com/a/b/c/repo", Some("c/repo"))]
+    #[case::too_short("https://github.com/web", None)]
+    #[case::empty("", None)]
+    #[case::not_a_url("not-a-url", None)]
+    fn parses_gh_repo_name(#[case] url: &str, #[case] expected: Option<&str>) {
+        let got = parse_gh_repo_name(url.into());
+        assert_eq!(got, expected.map(BString::from));
+    }
+
+    #[rstest]
+    #[case::main("refs/remotes/origin/main", "origin", Some("main"))]
+    #[case::trailing_newline("refs/remotes/origin/main\n", "origin", Some("main"))]
+    #[case::slash("refs/remotes/origin/feature/x", "origin", Some("feature/x"))]
+    #[case::other_remote("refs/remotes/upstream/dev", "upstream", Some("dev"))]
+    #[case::wrong_prefix("refs/heads/main", "origin", None)]
+    #[case::trailing_slash("refs/remotes/origin/", "origin", None)]
+    #[case::empty("", "origin", None)]
+    fn parses_default_branch(#[case] line: &str, #[case] remote: &str, #[case] expected: Option<&str>) {
+        let got = parse_default_branch(line.into(), remote);
+        assert_eq!(got, expected.map(BString::from));
+    }
+
+    /// A throwaway git repo with one commit and an `origin` remote.
+    fn temp_repo() -> tempfile::TempDir {
+        let dir = tempfile::tempdir().unwrap();
+        let git = |args: &[&str]| {
+            let ok = Command::new("git")
+                .arg("-C")
+                .arg(dir.path())
+                .args(args)
+                .captured()
+                .unwrap()
+                .success();
+            assert!(ok.is_ok(), "git {args:?} failed");
+        };
+        git(&["init", "-q", "-b", "main"]);
+        git(&["config", "user.email", "t@t.dev"]);
+        git(&["config", "user.name", "t"]);
+        git(&["commit", "-q", "--allow-empty", "-m", "init"]);
+        git(&["remote", "add", "origin", "git@github.com:acme/web.git"]);
+        dir
+    }
+
+    #[rstest]
+    fn repo_rejects_a_non_repo_dir() {
+        let dir = tempfile::tempdir().unwrap();
+        let git = Git::new(Path::new("git"));
+        assert!(git.repo(dir.path()).is_err());
+    }
+
+    #[rstest]
+    fn reads_branch_commit_and_remote() {
+        let dir = temp_repo();
+        let git = Git::new(Path::new("git"));
+        let repo = git.repo(dir.path()).unwrap();
+
+        let branch = repo.current_branch().unwrap();
+        assert_eq!(branch.name(), "main");
+        assert_eq!(branch.head_commit().unwrap().len(), 40);
+
+        let remote = repo.remote("origin").unwrap();
+        assert_eq!(remote.name(), "origin");
+        assert_eq!(remote.gh_repo_name(), Some(BString::from("acme/web")));
+    }
+
+    #[rstest]
+    fn default_branch_reads_origin_head() {
+        let dir = temp_repo();
+        let git = Git::new(Path::new("git"));
+        let repo = git.repo(dir.path()).unwrap();
+        // Point origin/HEAD at a fabricated remote-tracking ref.
+        Command::new("git")
+            .arg("-C")
+            .arg(dir.path())
+            .args(["symbolic-ref", "refs/remotes/origin/HEAD", "refs/remotes/origin/main"])
+            .captured()
+            .unwrap()
+            .success()
+            .unwrap();
+
+        let branch = repo.remote("origin").unwrap().default_branch().unwrap();
+        assert_eq!(branch.name(), "main");
+    }
+}
diff --git a/crates/hm-common/src/lib.rs b/crates/hm-common/src/lib.rs
index ee6ba357..e901fe96 100644
--- a/crates/hm-common/src/lib.rs
+++ b/crates/hm-common/src/lib.rs
@@ -4,4 +4,5 @@
 pub mod app_runtime;
 pub mod format;
 pub mod fs;
+pub mod git;
 pub mod process;
diff --git a/crates/hm-common/src/process/capture.rs b/crates/hm-common/src/process/capture.rs
index c7697724..abf0f496 100644
--- a/crates/hm-common/src/process/capture.rs
+++ b/crates/hm-common/src/process/capture.rs
@@ -176,6 +176,7 @@ pub trait CommandExt: sealed::Sealed {
 }
 
 impl CommandExt for std::process::Command {
+    #[tracing::instrument(skip(self), fields(program = %self.get_program().to_string_lossy()))]
     fn captured(&mut self) -> io::Result<Captured> {
         let program = self.get_program().to_string_lossy().into_owned();
         let out = self.output()?;
@@ -195,6 +196,7 @@ pub trait AsyncCommandExt: sealed::Sealed {
 }
 
 impl AsyncCommandExt for tokio::process::Command {
+    #[tracing::instrument(skip(self), fields(program = %self.as_std().get_program().to_string_lossy()))]
     async fn captured(&mut self) -> io::Result<Captured> {
         let program = self.as_std().get_program().to_string_lossy().into_owned();
         let out = self.output().await?;
diff --git a/crates/hm-common/src/process/which.rs b/crates/hm-common/src/process/which.rs
index cf2f534b..b5fdd444 100644
--- a/crates/hm-common/src/process/which.rs
+++ b/crates/hm-common/src/process/which.rs
@@ -13,6 +13,7 @@ pub struct ExecutableNotFound {
 /// Resolve `program` to its absolute path on `PATH`.
 ///
 /// For a presence check, call `pathbin(program).is_ok()`.
+#[tracing::instrument(skip_all, fields(program = %program.as_ref().to_string_lossy()))]
 pub fn pathbin(program: impl AsRef<OsStr>) -> Result<PathBuf, ExecutableNotFound> {
     let program = program.as_ref();
     which::which(program).map_err(|_| ExecutableNotFound {
diff --git a/crates/hm/Cargo.toml b/crates/hm/Cargo.toml
index eb69c570..0e718dad 100644
--- a/crates/hm/Cargo.toml
+++ b/crates/hm/Cargo.toml
@@ -53,6 +53,7 @@ webbrowser = "1"
 rand = "0.8"
 uuid = { version = "1", features = ["serde"] }
 bytes = "1"
+bstr = "1"
 human-units = { workspace = true }
 futures = "0.3"
 futures-util = "0.3"
diff --git a/crates/hm/src/commands/run/mod.rs b/crates/hm/src/commands/run/mod.rs
index 0a304bc4..90ca4edd 100644
--- a/crates/hm/src/commands/run/mod.rs
+++ b/crates/hm/src/commands/run/mod.rs
@@ -2,8 +2,9 @@ use std::collections::HashMap;
 
 use anyhow::{Context, Result};
 
+use bstr::ByteSlice as _;
 use hm_common::app_runtime::AppRuntime;
-use hm_common::process::{CapturedStreams as _, CommandExt as _};
+use hm_common::git::Git;
 use hm_dsl_engine::{DslEngine, detect};
 use human_units::FormatSize as _;
 
@@ -130,8 +131,9 @@ pub async fn handle(args: RunArgs, ctx: RunContext) -> Result<i32> {
     }
 
     // 7. Assemble the run request.
-    let (branch, commit) = git_metadata(&repo_root, args.branch.clone());
-    let repo_name = git_remote_repo_name(&repo_root);
+    let git = Git::new(AppRuntime::bins().git());
+    let (branch, commit) = git_metadata(git, &repo_root, args.branch.clone());
+    let repo_name = git_remote_repo_name(git, &repo_root);
     let mut req = hm_exec::RunRequest {
         plan,
         repo_root,
@@ -160,8 +162,8 @@ pub async fn handle(args: RunArgs, ctx: RunContext) -> Result<i32> {
         if let Some(slug) = ctx.config.cloud.pipeline.clone() {
             req.cloud_pipeline_slug = Some(slug);
         } else if req.source.repo_name.is_none() {
-            let default_branch =
-                git_default_branch(&req.repo_root).unwrap_or_else(|| req.source.branch.clone());
+            let default_branch = git_default_branch(git, &req.repo_root)
+                .unwrap_or_else(|| req.source.branch.clone());
             let slug = register_remoteless_pipeline(
                 client,
                 org,
@@ -181,9 +183,9 @@ pub async fn handle(args: RunArgs, ctx: RunContext) -> Result<i32> {
         client,
         org,
         repo_name: req.source.repo_name.clone(),
-        repository: git_remote_url(&req.repo_root),
+        repository: git_remote_url(git, &req.repo_root),
         name: req.pipeline_slug.clone(),
-        default_branch: git_default_branch(&req.repo_root)
+        default_branch: git_default_branch(git, &req.repo_root)
             .unwrap_or_else(|| req.source.branch.clone()),
     });
 
@@ -242,90 +244,46 @@ fn parse_env(pairs: &[String]) -> HashMap<String, String> {
 
 /// Resolve `(branch, commit)` from git at `root`, best-effort. An explicit
 /// `branch_override` wins; missing values fall back to `HEAD` / the zero SHA.
-/// `git -C <root> <args...>`, ready to `.captured()`.
-fn git_at(root: &std::path::Path, args: &[&str]) -> std::process::Command {
-    let mut cmd = std::process::Command::new("git");
-    cmd.arg("-C").arg(root).args(args);
-    cmd
-}
-
-fn git_metadata(root: &std::path::Path, branch_override: Option<String>) -> (String, String) {
-    let run = |a: &[&str]| {
-        git_at(root, a)
-            .captured()
-            .ok()
-            .and_then(|c| c.success().ok())
-            .and_then(|ok| ok.stdout_string().ok())
-            .map(|s| s.trim().to_string())
-    };
+fn git_metadata(
+    git: Git<'_>,
+    root: &std::path::Path,
+    branch_override: Option<String>,
+) -> (String, String) {
+    let repo = git.repo(root).ok();
+    let head = repo.as_ref().and_then(|r| r.current_branch());
     let branch = branch_override
-        .or_else(|| run(&["rev-parse", "--abbrev-ref", "HEAD"]))
+        .or_else(|| head.as_ref().map(|b| b.name().to_str_lossy().into_owned()))
         .filter(|s| !s.is_empty())
         .unwrap_or_else(|| "HEAD".to_string());
-    let commit = run(&["rev-parse", "HEAD"])
+    let commit = head
+        .as_ref()
+        .and_then(|b| b.head_commit())
+        .map(|c| c.to_str_lossy().into_owned())
         .filter(|s| !s.is_empty())
         .unwrap_or_else(|| "0".repeat(40));
     (branch, commit)
 }
 
-/// Parse `owner/repo` from a git remote URL, mirroring the backend's
-/// `Harmont.Pipelines.RepoName`: drop scheme/host and a trailing `.git`, then
-/// take the last two non-empty path segments. `None` when fewer than two
-/// segments remain.
-fn parse_repo_name(url: &str) -> Option<String> {
-    let url = url.trim();
-    let path = if let Some((_, rest)) = url.split_once("://") {
-        // scheme://host/owner/repo  → strip host
-        rest.split_once('/').map_or(rest, |(_, p)| p)
-    } else if url.contains('@') && url.contains(':') {
-        // scp-style git@host:owner/repo → strip "git@host:"
-        let after_at = url.split_once('@').map_or(url, |(_, r)| r);
-        after_at.split_once(':').map_or(after_at, |(_, p)| p)
-    } else {
-        url.split_once('/').map_or(url, |(_, p)| p)
-    };
-    let path = path.trim_end_matches('/');
-    let path = path.strip_suffix(".git").unwrap_or(path);
-    let segs: Vec<&str> = path.split('/').filter(|s| !s.is_empty()).collect();
-    if segs.len() < 2 {
-        return None;
-    }
-    Some(segs[segs.len() - 2..].join("/"))
-}
-
-/// Extract the default branch name from a `git symbolic-ref
-/// refs/remotes/origin/HEAD` result (e.g. `refs/remotes/origin/main` → `main`).
-/// `None` when the line is empty or lacks the expected prefix.
-fn parse_default_branch(symbolic_ref: &str) -> Option<String> {
-    let branch = symbolic_ref.trim().strip_prefix("refs/remotes/origin/")?;
-    (!branch.is_empty()).then(|| branch.to_string())
-}
-
-/// The worktree's raw `origin` remote URL (the pipeline's `repository`).
-fn git_remote_url(root: &std::path::Path) -> Option<String> {
-    let out = git_at(root, &["config", "--get", "remote.origin.url"])
-        .captured()
-        .ok()?
-        .success()
-        .ok()?;
-    let url = out.stdout_lossy().trim().to_string();
+/// The worktree's `origin` remote URL (the pipeline's `repository`).
+fn git_remote_url(git: Git<'_>, root: &std::path::Path) -> Option<String> {
+    let repo = git.repo(root).ok()?;
+    let url = repo.remote("origin")?.url().to_str_lossy().into_owned();
     (!url.is_empty()).then_some(url)
 }
 
 /// The repo's default branch, from `origin/HEAD`. `None` when `origin/HEAD`
 /// isn't set (common on fresh clones without `git remote set-head`).
-fn git_default_branch(root: &std::path::Path) -> Option<String> {
-    let out = git_at(root, &["symbolic-ref", "refs/remotes/origin/HEAD"])
-        .captured()
-        .ok()?
-        .success()
-        .ok()?;
-    parse_default_branch(&out.stdout_lossy())
+fn git_default_branch(git: Git<'_>, root: &std::path::Path) -> Option<String> {
+    let repo = git.repo(root).ok()?;
+    let branch = repo.remote("origin")?.default_branch()?;
+    Some(branch.name().to_str_lossy().into_owned())
 }
 
 /// Best-effort `owner/repo` from the worktree's `origin` remote.
-fn git_remote_repo_name(root: &std::path::Path) -> Option<String> {
-    parse_repo_name(&git_remote_url(root)?)
+fn git_remote_repo_name(git: Git<'_>, root: &std::path::Path) -> Option<String> {
+    let repo = git.repo(root).ok()?;
+    let name = repo.remote("origin")?.gh_repo_name()?;
+    Some(name.to_str_lossy().into_owned())
 }
 
 /// Resolve repo root, detect the DSL, select the pipeline slug, and render
@@ -737,36 +695,6 @@ mod tests {
         assert_eq!(is_missing_pipeline(&err), expected);
     }
 
-    #[rstest]
-    #[case::https(
-        "https://github.com/harmont-dev/harmont-cli.git",
-        Some("harmont-dev/harmont-cli")
-    )]
-    #[case::scp(
-        "git@github.com:harmont-dev/harmont-cli.git",
-        Some("harmont-dev/harmont-cli")
-    )]
-    #[case::ssh(
-        "ssh://git@github.com/harmont-dev/harmont-cli",
-        Some("harmont-dev/harmont-cli")
-    )]
-    #[case::deep_path("https://example.com/a/b/c/repo", Some("c/repo"))]
-    #[case::empty("", None)]
-    #[case::not_a_url("not-a-url", None)]
-    fn parse_repo_name_cases(#[case] url: &str, #[case] expected: Option<&str>) {
-        assert_eq!(parse_repo_name(url).as_deref(), expected);
-    }
-
-    #[rstest]
-    #[case::main_trailing_newline("refs/remotes/origin/main\n", Some("main"))]
-    #[case::master("refs/remotes/origin/master", Some("master"))]
-    #[case::empty("", None)]
-    #[case::refs_heads("refs/heads/main", None)]
-    #[case::trailing_slash("refs/remotes/origin/", None)]
-    fn parse_default_branch_cases(#[case] input: &str, #[case] expected: Option<&str>) {
-        assert_eq!(parse_default_branch(input).as_deref(), expected);
-    }
-
     #[rstest]
     fn parse_env_splits_pairs() {
         let m = parse_env(&["A=1".into(), "B=x=y".into(), "bad".into()]);
@@ -777,7 +705,8 @@ mod tests {
 
     #[rstest]
     fn git_metadata_falls_back_outside_repo() {
-        let (b, c) = git_metadata(std::path::Path::new("/"), None);
+        let git = Git::new(std::path::Path::new("git"));
+        let (b, c) = git_metadata(git, std::path::Path::new("/"), None);
         assert!(!b.is_empty() && !c.is_empty());
         assert_eq!(c.len(), 40); // zero-sha fallback
     }

From 8732103de5c2023ec46c0efe8047dd30f70ce851 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 17:57:33 -0700
Subject: [PATCH 13/18] feat(hm-common): add AppRuntime::git() accessor

Expose the system git as a bound Git handle, so callers use
AppRuntime::git() instead of Git::new(AppRuntime::bins().git()). Returns
Git by value (it is Copy; a stored &Git would be self-referential). Adopt
it in hm run.
---
 crates/hm-common/src/app_runtime.rs | 13 +++++++++++++
 crates/hm/src/commands/run/mod.rs   |  2 +-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/crates/hm-common/src/app_runtime.rs b/crates/hm-common/src/app_runtime.rs
index d13c259d..60664846 100644
--- a/crates/hm-common/src/app_runtime.rs
+++ b/crates/hm-common/src/app_runtime.rs
@@ -3,6 +3,7 @@
 use std::path::{Path, PathBuf};
 use std::sync::OnceLock;
 
+use crate::git::Git;
 use crate::process::{ExecutableNotFound, SystemBins};
 
 /// Failure to initialize the [`AppRuntime`].
@@ -76,6 +77,15 @@ impl AppRuntime {
     pub fn cwd() -> &'static Path {
         &Self::get().cwd
     }
+
+    /// The system `git`, bound to a [`Git`] handle.
+    ///
+    /// # Panics
+    /// If [`init`](Self::init) has not been called.
+    #[must_use]
+    pub fn git() -> Git<'static> {
+        Git::new(Self::bins().git())
+    }
 }
 
 #[cfg(test)]
@@ -115,6 +125,9 @@ mod tests {
         AppRuntime::init().unwrap();
         assert!(AppRuntime::cwd().is_absolute());
         assert!(AppRuntime::bins().git().is_absolute());
+        // git() binds the resolved git; a fresh temp dir is not a repo.
+        let dir = tempfile::tempdir().unwrap();
+        assert!(AppRuntime::git().repo(dir.path()).is_err());
     }
 
     #[rstest]
diff --git a/crates/hm/src/commands/run/mod.rs b/crates/hm/src/commands/run/mod.rs
index 90ca4edd..b08ffe37 100644
--- a/crates/hm/src/commands/run/mod.rs
+++ b/crates/hm/src/commands/run/mod.rs
@@ -131,7 +131,7 @@ pub async fn handle(args: RunArgs, ctx: RunContext) -> Result<i32> {
     }
 
     // 7. Assemble the run request.
-    let git = Git::new(AppRuntime::bins().git());
+    let git = AppRuntime::git();
     let (branch, commit) = git_metadata(git, &repo_root, args.branch.clone());
     let repo_name = git_remote_repo_name(git, &repo_root);
     let mut req = hm_exec::RunRequest {

From 88262a43f40aa4dcf7f54a9aa9e1b306cefe4ab9 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 18:05:50 -0700
Subject: [PATCH 14/18] refactor(hm): inline git accessors in run, drop
 free-floating helpers

Replace git_metadata, git_remote_url, git_default_branch, and
git_remote_repo_name with inline GitRepo accessor calls at their sole
call sites in the run-request assembly. The branch/commit/repo-name read
now shares a single borrow of repo_root in one block; the default-branch
and remote-url reads inline directly into the cloud-target and
auto-create paths. Removes the git_metadata unit test (its target is
gone).
---
 crates/hm/src/commands/run/mod.rs | 115 +++++++++++++++---------------
 1 file changed, 56 insertions(+), 59 deletions(-)

diff --git a/crates/hm/src/commands/run/mod.rs b/crates/hm/src/commands/run/mod.rs
index b08ffe37..c4499552 100644
--- a/crates/hm/src/commands/run/mod.rs
+++ b/crates/hm/src/commands/run/mod.rs
@@ -4,7 +4,6 @@ use anyhow::{Context, Result};
 
 use bstr::ByteSlice as _;
 use hm_common::app_runtime::AppRuntime;
-use hm_common::git::Git;
 use hm_dsl_engine::{DslEngine, detect};
 use human_units::FormatSize as _;
 
@@ -130,10 +129,32 @@ pub async fn handle(args: RunArgs, ctx: RunContext) -> Result<i32> {
         );
     }
 
-    // 7. Assemble the run request.
+    // 7. Assemble the run request. Read branch, commit, and repo name from git
+    // in one borrow of `repo_root` (best-effort; an explicit `--branch` wins,
+    // and missing values fall back to `HEAD` / the zero SHA). The block yields
+    // owned strings so `repo_root` is free to move into the request below.
     let git = AppRuntime::git();
-    let (branch, commit) = git_metadata(git, &repo_root, args.branch.clone());
-    let repo_name = git_remote_repo_name(git, &repo_root);
+    let (branch, commit, repo_name) = {
+        let repo = git.repo(&repo_root).ok();
+        let head = repo.as_ref().and_then(hm_common::git::GitRepo::current_branch);
+        let branch = args
+            .branch
+            .clone()
+            .or_else(|| head.as_ref().map(|b| b.name().to_str_lossy().into_owned()))
+            .filter(|s| !s.is_empty())
+            .unwrap_or_else(|| "HEAD".to_string());
+        let commit = head
+            .as_ref()
+            .and_then(hm_common::git::GitBranch::head_commit)
+            .map(|c| c.to_str_lossy().into_owned())
+            .filter(|s| !s.is_empty())
+            .unwrap_or_else(|| "0".repeat(40));
+        let repo_name = repo
+            .as_ref()
+            .and_then(|r| r.remote("origin")?.gh_repo_name())
+            .map(|n| n.to_str_lossy().into_owned());
+        (branch, commit, repo_name)
+    };
     let mut req = hm_exec::RunRequest {
         plan,
         repo_root,
@@ -162,7 +183,20 @@ pub async fn handle(args: RunArgs, ctx: RunContext) -> Result<i32> {
         if let Some(slug) = ctx.config.cloud.pipeline.clone() {
             req.cloud_pipeline_slug = Some(slug);
         } else if req.source.repo_name.is_none() {
-            let default_branch = git_default_branch(git, &req.repo_root)
+            // Default branch from `origin/HEAD`; falls back to the run's branch
+            // when unset (fresh clones without `git remote set-head`).
+            let default_branch = git
+                .repo(&req.repo_root)
+                .ok()
+                .and_then(|r| {
+                    Some(
+                        r.remote("origin")?
+                            .default_branch()?
+                            .name()
+                            .to_str_lossy()
+                            .into_owned(),
+                    )
+                })
                 .unwrap_or_else(|| req.source.branch.clone());
             let slug = register_remoteless_pipeline(
                 client,
@@ -183,9 +217,24 @@ pub async fn handle(args: RunArgs, ctx: RunContext) -> Result<i32> {
         client,
         org,
         repo_name: req.source.repo_name.clone(),
-        repository: git_remote_url(git, &req.repo_root),
+        // The pipeline's `repository`: the worktree's `origin` remote URL.
+        repository: git.repo(&req.repo_root).ok().and_then(|r| {
+            let url = r.remote("origin")?.url().to_str_lossy().into_owned();
+            (!url.is_empty()).then_some(url)
+        }),
         name: req.pipeline_slug.clone(),
-        default_branch: git_default_branch(git, &req.repo_root)
+        default_branch: git
+            .repo(&req.repo_root)
+            .ok()
+            .and_then(|r| {
+                Some(
+                    r.remote("origin")?
+                        .default_branch()?
+                        .name()
+                        .to_str_lossy()
+                        .into_owned(),
+                )
+            })
             .unwrap_or_else(|| req.source.branch.clone()),
     });
 
@@ -242,50 +291,6 @@ fn parse_env(pairs: &[String]) -> HashMap<String, String> {
         .collect()
 }
 
-/// Resolve `(branch, commit)` from git at `root`, best-effort. An explicit
-/// `branch_override` wins; missing values fall back to `HEAD` / the zero SHA.
-fn git_metadata(
-    git: Git<'_>,
-    root: &std::path::Path,
-    branch_override: Option<String>,
-) -> (String, String) {
-    let repo = git.repo(root).ok();
-    let head = repo.as_ref().and_then(|r| r.current_branch());
-    let branch = branch_override
-        .or_else(|| head.as_ref().map(|b| b.name().to_str_lossy().into_owned()))
-        .filter(|s| !s.is_empty())
-        .unwrap_or_else(|| "HEAD".to_string());
-    let commit = head
-        .as_ref()
-        .and_then(|b| b.head_commit())
-        .map(|c| c.to_str_lossy().into_owned())
-        .filter(|s| !s.is_empty())
-        .unwrap_or_else(|| "0".repeat(40));
-    (branch, commit)
-}
-
-/// The worktree's `origin` remote URL (the pipeline's `repository`).
-fn git_remote_url(git: Git<'_>, root: &std::path::Path) -> Option<String> {
-    let repo = git.repo(root).ok()?;
-    let url = repo.remote("origin")?.url().to_str_lossy().into_owned();
-    (!url.is_empty()).then_some(url)
-}
-
-/// The repo's default branch, from `origin/HEAD`. `None` when `origin/HEAD`
-/// isn't set (common on fresh clones without `git remote set-head`).
-fn git_default_branch(git: Git<'_>, root: &std::path::Path) -> Option<String> {
-    let repo = git.repo(root).ok()?;
-    let branch = repo.remote("origin")?.default_branch()?;
-    Some(branch.name().to_str_lossy().into_owned())
-}
-
-/// Best-effort `owner/repo` from the worktree's `origin` remote.
-fn git_remote_repo_name(git: Git<'_>, root: &std::path::Path) -> Option<String> {
-    let repo = git.repo(root).ok()?;
-    let name = repo.remote("origin")?.gh_repo_name()?;
-    Some(name.to_str_lossy().into_owned())
-}
-
 /// Resolve repo root, detect the DSL, select the pipeline slug, and render
 /// the v0 IR JSON. Shared by local and cloud runs.
 ///
@@ -703,14 +708,6 @@ mod tests {
         assert!(!m.contains_key("bad"));
     }
 
-    #[rstest]
-    fn git_metadata_falls_back_outside_repo() {
-        let git = Git::new(std::path::Path::new("git"));
-        let (b, c) = git_metadata(git, std::path::Path::new("/"), None);
-        assert!(!b.is_empty() && !c.is_empty());
-        assert_eq!(c.len(), 40); // zero-sha fallback
-    }
-
     #[rstest]
     #[case::unauthorized(E::Unauthorized, "error[auth_required]")]
     #[case::not_found(E::NotFound("x".into()), "error[not_found]")]

From c13576351a45fc0a16b4e2dfb2290de9288fde84 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 18:11:46 -0700
Subject: [PATCH 15/18] refactor(hm): read all git fields from one repo+remote
 open

The inlined accessors re-opened the worktree repo and its origin remote
up to three more times on the cloud paths (remoteless registration and
auto-create each re-shelled to git). Open repo + origin once in step 7,
read branch/commit/repo_name/remote_url/default_branch from that single
pair of handles into owned strings, and have the cloud paths reuse those
values. Net fewer git subprocesses on cloud runs; local runs pay one
extra symbolic-ref for default_branch, which they don't consume.
---
 crates/hm/src/commands/run/mod.rs | 79 +++++++++++++------------------
 1 file changed, 33 insertions(+), 46 deletions(-)

diff --git a/crates/hm/src/commands/run/mod.rs b/crates/hm/src/commands/run/mod.rs
index c4499552..07315ae8 100644
--- a/crates/hm/src/commands/run/mod.rs
+++ b/crates/hm/src/commands/run/mod.rs
@@ -4,6 +4,7 @@ use anyhow::{Context, Result};
 
 use bstr::ByteSlice as _;
 use hm_common::app_runtime::AppRuntime;
+use hm_common::git::{GitBranch, GitRemote, GitRepo};
 use hm_dsl_engine::{DslEngine, detect};
 use human_units::FormatSize as _;
 
@@ -129,14 +130,18 @@ pub async fn handle(args: RunArgs, ctx: RunContext) -> Result<i32> {
         );
     }
 
-    // 7. Assemble the run request. Read branch, commit, and repo name from git
-    // in one borrow of `repo_root` (best-effort; an explicit `--branch` wins,
-    // and missing values fall back to `HEAD` / the zero SHA). The block yields
-    // owned strings so `repo_root` is free to move into the request below.
-    let git = AppRuntime::git();
-    let (branch, commit, repo_name) = {
+    // 7. Assemble the run request. Open the worktree's repo and its `origin`
+    // remote once, and read every git-derived field from that single pair of
+    // handles — all best-effort. An explicit `--branch` wins; a missing branch
+    // or commit falls back to `HEAD` / the zero SHA. The block yields owned
+    // strings so `repo_root` can move into the request, and the cloud paths
+    // below reuse `remote_url` / `default_branch` instead of re-shelling to git.
+    let (branch, commit, repo_name, remote_url, default_branch) = {
+        let git = AppRuntime::git();
         let repo = git.repo(&repo_root).ok();
-        let head = repo.as_ref().and_then(hm_common::git::GitRepo::current_branch);
+        let head = repo.as_ref().and_then(GitRepo::current_branch);
+        let remote = repo.as_ref().and_then(|r| r.remote("origin"));
+
         let branch = args
             .branch
             .clone()
@@ -145,15 +150,25 @@ pub async fn handle(args: RunArgs, ctx: RunContext) -> Result<i32> {
             .unwrap_or_else(|| "HEAD".to_string());
         let commit = head
             .as_ref()
-            .and_then(hm_common::git::GitBranch::head_commit)
+            .and_then(GitBranch::head_commit)
             .map(|c| c.to_str_lossy().into_owned())
             .filter(|s| !s.is_empty())
             .unwrap_or_else(|| "0".repeat(40));
-        let repo_name = repo
+        let repo_name = remote
             .as_ref()
-            .and_then(|r| r.remote("origin")?.gh_repo_name())
+            .and_then(GitRemote::gh_repo_name)
             .map(|n| n.to_str_lossy().into_owned());
-        (branch, commit, repo_name)
+        let remote_url = remote
+            .as_ref()
+            .map(|r| r.url().to_str_lossy().into_owned())
+            .filter(|u| !u.is_empty());
+        // `origin/HEAD`; `None` when unset (fresh clones without `set-head`).
+        let default_branch = remote
+            .as_ref()
+            .and_then(GitRemote::default_branch)
+            .map(|b| b.name().to_str_lossy().into_owned());
+
+        (branch, commit, repo_name, remote_url, default_branch)
     };
     let mut req = hm_exec::RunRequest {
         plan,
@@ -183,20 +198,8 @@ pub async fn handle(args: RunArgs, ctx: RunContext) -> Result<i32> {
         if let Some(slug) = ctx.config.cloud.pipeline.clone() {
             req.cloud_pipeline_slug = Some(slug);
         } else if req.source.repo_name.is_none() {
-            // Default branch from `origin/HEAD`; falls back to the run's branch
-            // when unset (fresh clones without `git remote set-head`).
-            let default_branch = git
-                .repo(&req.repo_root)
-                .ok()
-                .and_then(|r| {
-                    Some(
-                        r.remote("origin")?
-                            .default_branch()?
-                            .name()
-                            .to_str_lossy()
-                            .into_owned(),
-                    )
-                })
+            let default_branch = default_branch
+                .clone()
                 .unwrap_or_else(|| req.source.branch.clone());
             let slug = register_remoteless_pipeline(
                 client,
@@ -210,32 +213,16 @@ pub async fn handle(args: RunArgs, ctx: RunContext) -> Result<i32> {
         }
     }
 
-    // Cloud-only auto-create context. Borrow `req` here (before it's moved into
-    // `start`): the repository URL and default branch come from the worktree's
-    // git remote; the pipeline name is the in-repo source slug.
+    // Cloud-only auto-create context, from the git fields read in step 7: the
+    // `origin` remote URL is the pipeline's `repository`, `default_branch` falls
+    // back to the run's branch, and the pipeline name is the in-repo source slug.
     let autocreate = autocreate_client.map(|(client, org)| AutoCreate {
         client,
         org,
         repo_name: req.source.repo_name.clone(),
-        // The pipeline's `repository`: the worktree's `origin` remote URL.
-        repository: git.repo(&req.repo_root).ok().and_then(|r| {
-            let url = r.remote("origin")?.url().to_str_lossy().into_owned();
-            (!url.is_empty()).then_some(url)
-        }),
+        repository: remote_url,
         name: req.pipeline_slug.clone(),
-        default_branch: git
-            .repo(&req.repo_root)
-            .ok()
-            .and_then(|r| {
-                Some(
-                    r.remote("origin")?
-                        .default_branch()?
-                        .name()
-                        .to_str_lossy()
-                        .into_owned(),
-                )
-            })
-            .unwrap_or_else(|| req.source.branch.clone()),
+        default_branch: default_branch.unwrap_or_else(|| req.source.branch.clone()),
     });
 
     // 8. Start, drive events, own Ctrl-C, await the outcome.

From 8eb62172f1097662cd6d8029ef800d4f7b5cb1f7 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 19:47:05 -0700
Subject: [PATCH 16/18] feat(hm-common): add python module, port DSL engine
 onto it

A git-style runner for python3: `Python` (interpreter handle, from
`AppRuntime::python()`), `PyCommand` (derefs to tokio::process::Command,
adds pythonpath + a run terminal), and `PyOutput` (derefs to CapturedOk,
adds JSON decoding). Failures surface as `PyError` carrying stderr;
stdout decoding is the caller's choice on the output.

Replaces the ad-hoc Command dance in SubprocessPythonEngine with
`AppRuntime::python()`-shaped calls; the harmont-py bundling stays in
hm-dsl-engine. Covered by rstest against a real python3.
---
 crates/hm-common/src/app_runtime.rs       |  10 +
 crates/hm-common/src/lib.rs               |   1 +
 crates/hm-common/src/python.rs            | 315 ++++++++++++++++++++++
 crates/hm-dsl-engine/src/python_engine.rs |  29 +-
 4 files changed, 337 insertions(+), 18 deletions(-)
 create mode 100644 crates/hm-common/src/python.rs

diff --git a/crates/hm-common/src/app_runtime.rs b/crates/hm-common/src/app_runtime.rs
index 60664846..66bb7535 100644
--- a/crates/hm-common/src/app_runtime.rs
+++ b/crates/hm-common/src/app_runtime.rs
@@ -5,6 +5,7 @@ use std::sync::OnceLock;
 
 use crate::git::Git;
 use crate::process::{ExecutableNotFound, SystemBins};
+use crate::python::Python;
 
 /// Failure to initialize the [`AppRuntime`].
 #[derive(Debug, thiserror::Error)]
@@ -86,6 +87,15 @@ impl AppRuntime {
     pub fn git() -> Git<'static> {
         Git::new(Self::bins().git())
     }
+
+    /// The system `python3`, bound to a [`Python`] handle.
+    ///
+    /// # Panics
+    /// If [`init`](Self::init) has not been called.
+    #[must_use]
+    pub fn python() -> Python<'static> {
+        Python::new(Self::bins().python3())
+    }
 }
 
 #[cfg(test)]
diff --git a/crates/hm-common/src/lib.rs b/crates/hm-common/src/lib.rs
index e901fe96..c7dab2f5 100644
--- a/crates/hm-common/src/lib.rs
+++ b/crates/hm-common/src/lib.rs
@@ -6,3 +6,4 @@ pub mod format;
 pub mod fs;
 pub mod git;
 pub mod process;
+pub mod python;
diff --git a/crates/hm-common/src/python.rs b/crates/hm-common/src/python.rs
new file mode 100644
index 00000000..17b9b91c
--- /dev/null
+++ b/crates/hm-common/src/python.rs
@@ -0,0 +1,315 @@
+//! Running python3.
+
+use std::ffi::OsStr;
+use std::ops::{Deref, DerefMut};
+use std::path::{Path, PathBuf};
+
+use serde::de::DeserializeOwned;
+
+use crate::process::{AsyncCommandExt as _, CapturedError, CapturedOk, CapturedStreams as _};
+
+/// A resolved `python3` interpreter.
+#[derive(Debug, Clone, Copy)]
+pub struct Python<'bin> {
+    bin: &'bin Path,
+}
+
+impl<'bin> Python<'bin> {
+    /// Wrap a `python3` executable, typically `AppRuntime::bins().python3()`.
+    #[must_use]
+    pub const fn new(bin: &'bin Path) -> Self {
+        Self { bin }
+    }
+
+    /// An inline program: `python3 -c <script>`. Trailing [`arg`](PyCommand)s
+    /// become `sys.argv[1:]`.
+    pub fn program(&self, script: impl AsRef<OsStr>) -> PyCommand {
+        let mut cmd = tokio::process::Command::new(self.bin);
+        cmd.arg("-c").arg(script);
+        PyCommand::wrap(cmd)
+    }
+
+    /// A module run: `python3 -m <module>`.
+    pub fn module(&self, module: impl AsRef<OsStr>) -> PyCommand {
+        let mut cmd = tokio::process::Command::new(self.bin);
+        cmd.arg("-m").arg(module);
+        PyCommand::wrap(cmd)
+    }
+
+    /// A script file: `python3 <path>`.
+    pub fn script(&self, path: impl AsRef<Path>) -> PyCommand {
+        let mut cmd = tokio::process::Command::new(self.bin);
+        cmd.arg(path.as_ref());
+        PyCommand::wrap(cmd)
+    }
+}
+
+/// A `python3` invocation. Derefs to [`tokio::process::Command`].
+#[derive(Debug)]
+#[must_use = "a PyCommand does nothing until run"]
+pub struct PyCommand {
+    cmd: tokio::process::Command,
+}
+
+impl PyCommand {
+    fn wrap(mut cmd: tokio::process::Command) -> Self {
+        cmd.env("PYTHONDONTWRITEBYTECODE", "1");
+        Self { cmd }
+    }
+
+    /// Append a `PYTHONPATH` entry.
+    pub fn pythonpath(&mut self, path: impl AsRef<Path>) -> &mut Self {
+        let mut entries: Vec<PathBuf> = self
+            .cmd
+            .as_std()
+            .get_envs()
+            .find(|(key, _)| *key == OsStr::new("PYTHONPATH"))
+            .and_then(|(_, value)| value)
+            .map(|value| std::env::split_paths(value).collect())
+            .unwrap_or_default();
+        entries.push(path.as_ref().to_path_buf());
+        if let Ok(joined) = std::env::join_paths(entries) {
+            self.cmd.env("PYTHONPATH", joined);
+        }
+        self
+    }
+
+    /// Run to completion.
+    ///
+    /// # Errors
+    /// [`PyError::Spawn`] if `python3` cannot be spawned; [`PyError::Failed`]
+    /// if it exits non-zero.
+    pub async fn run(&mut self) -> Result<PyOutput, PyError> {
+        let ok = self
+            .cmd
+            .captured()
+            .await
+            .map_err(PyError::Spawn)?
+            .success()
+            .map_err(PyError::Failed)?;
+        Ok(PyOutput(ok))
+    }
+}
+
+impl Deref for PyCommand {
+    type Target = tokio::process::Command;
+    fn deref(&self) -> &Self::Target {
+        &self.cmd
+    }
+}
+
+impl DerefMut for PyCommand {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.cmd
+    }
+}
+
+/// A successful `python3` run: [`CapturedOk`] plus JSON decoding of stdout.
+#[derive(Debug)]
+pub struct PyOutput(CapturedOk);
+
+impl PyOutput {
+    /// Deserialize stdout as JSON.
+    ///
+    /// # Errors
+    /// If stdout is not valid JSON for `T`.
+    pub fn json<T: DeserializeOwned>(&self) -> Result<T, serde_json::Error> {
+        serde_json::from_slice(self.0.stdout())
+    }
+
+    /// The underlying captured output.
+    #[must_use]
+    pub fn into_inner(self) -> CapturedOk {
+        self.0
+    }
+}
+
+impl Deref for PyOutput {
+    type Target = CapturedOk;
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+/// A `python3` invocation that produced no output.
+#[derive(Debug, thiserror::Error)]
+pub enum PyError {
+    /// `python3` could not be spawned.
+    #[error("spawning `python3`")]
+    Spawn(#[source] std::io::Error),
+    /// `python3` exited non-zero.
+    #[error(transparent)]
+    Failed(#[from] CapturedError),
+}
+
+#[cfg(test)]
+#[allow(
+    clippy::unwrap_used,
+    clippy::print_stderr,
+    clippy::panic,
+    reason = "test setup, assertions, and skip diagnostics"
+)]
+mod tests {
+    use super::*;
+    use rstest::rstest;
+
+    /// The system `python3`, or `None` to skip on hosts without it.
+    fn python3() -> Option<PathBuf> {
+        crate::process::pathbin("python3").ok()
+    }
+
+    #[rstest]
+    #[case::print("print('hello')", "hello\n")]
+    #[case::no_newline("import sys; sys.stdout.write('hi')", "hi")]
+    #[case::empty("pass", "")]
+    #[tokio::test]
+    async fn program_captures_stdout(#[case] script: &str, #[case] expected: &str) {
+        let Some(bin) = python3() else {
+            eprintln!("skipping: python3 not on PATH");
+            return;
+        };
+        let out = Python::new(&bin).program(script).run().await.unwrap();
+        assert_eq!(out.stdout_string().unwrap(), expected);
+    }
+
+    #[rstest]
+    #[tokio::test]
+    async fn nonzero_exit_is_failed_carrying_stderr() {
+        let Some(bin) = python3() else {
+            eprintln!("skipping: python3 not on PATH");
+            return;
+        };
+        let err = Python::new(&bin)
+            .program("import sys; sys.stderr.write('boom'); sys.exit(3)")
+            .run()
+            .await
+            .unwrap_err();
+        match err {
+            PyError::Failed(e) => {
+                assert_eq!(e.code(), Some(3));
+                assert!(e.stderr_string().unwrap().contains("boom"));
+            }
+            PyError::Spawn(e) => panic!("expected Failed, got Spawn({e:?})"),
+        }
+    }
+
+    #[rstest]
+    #[tokio::test]
+    async fn missing_interpreter_is_a_spawn_error() {
+        let bin = PathBuf::from("hm-common-no-such-python-xyz");
+        let err = Python::new(&bin)
+            .program("print(1)")
+            .run()
+            .await
+            .unwrap_err();
+        assert!(matches!(err, PyError::Spawn(_)));
+    }
+
+    #[rstest]
+    #[tokio::test]
+    async fn json_decodes_stdout() {
+        let Some(bin) = python3() else {
+            eprintln!("skipping: python3 not on PATH");
+            return;
+        };
+        let out = Python::new(&bin)
+            .program("import json; print(json.dumps({'a': 1, 'b': [2, 3]}))")
+            .run()
+            .await
+            .unwrap();
+        let value: serde_json::Value = out.json().unwrap();
+        assert_eq!(value["a"], 1);
+        assert_eq!(value["b"][1], 3);
+    }
+
+    #[rstest]
+    #[tokio::test]
+    async fn positional_args_become_sys_argv() {
+        let Some(bin) = python3() else {
+            eprintln!("skipping: python3 not on PATH");
+            return;
+        };
+        let mut py = Python::new(&bin).program("import sys; print(' '.join(sys.argv[1:]))");
+        py.args(["one", "two"]);
+        let out = py.run().await.unwrap();
+        assert_eq!(out.stdout_string().unwrap(), "one two\n");
+    }
+
+    #[rstest]
+    #[tokio::test]
+    async fn current_dir_sets_the_working_directory() {
+        let Some(bin) = python3() else {
+            eprintln!("skipping: python3 not on PATH");
+            return;
+        };
+        let dir = tempfile::tempdir().unwrap();
+        let mut py = Python::new(&bin).program("import os; print(os.getcwd())");
+        py.current_dir(dir.path());
+        let out = py.run().await.unwrap();
+        let got = std::fs::canonicalize(out.stdout_string().unwrap().trim()).unwrap();
+        let want = std::fs::canonicalize(dir.path()).unwrap();
+        assert_eq!(got, want);
+    }
+
+    #[rstest]
+    #[tokio::test]
+    async fn pythonpath_makes_a_module_importable() {
+        let Some(bin) = python3() else {
+            eprintln!("skipping: python3 not on PATH");
+            return;
+        };
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::write(dir.path().join("mymod.py"), "VALUE = 42\n").unwrap();
+        let mut py = Python::new(&bin).program("import mymod; print(mymod.VALUE)");
+        py.pythonpath(dir.path());
+        let out = py.run().await.unwrap();
+        assert_eq!(out.stdout_string().unwrap().trim(), "42");
+    }
+
+    #[rstest]
+    #[tokio::test]
+    async fn pythonpath_appends_across_calls() {
+        let Some(bin) = python3() else {
+            eprintln!("skipping: python3 not on PATH");
+            return;
+        };
+        let a = tempfile::tempdir().unwrap();
+        let b = tempfile::tempdir().unwrap();
+        std::fs::write(a.path().join("mod_a.py"), "A = 1\n").unwrap();
+        std::fs::write(b.path().join("mod_b.py"), "B = 2\n").unwrap();
+        let mut py = Python::new(&bin).program("import mod_a, mod_b; print(mod_a.A + mod_b.B)");
+        py.pythonpath(a.path());
+        py.pythonpath(b.path());
+        let out = py.run().await.unwrap();
+        assert_eq!(out.stdout_string().unwrap().trim(), "3");
+    }
+
+    #[rstest]
+    #[tokio::test]
+    async fn module_form_runs_a_module() {
+        let Some(bin) = python3() else {
+            eprintln!("skipping: python3 not on PATH");
+            return;
+        };
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::write(dir.path().join("mymod.py"), "print('from module')\n").unwrap();
+        let mut py = Python::new(&bin).module("mymod");
+        py.pythonpath(dir.path());
+        let out = py.run().await.unwrap();
+        assert_eq!(out.stdout_string().unwrap(), "from module\n");
+    }
+
+    #[rstest]
+    #[tokio::test]
+    async fn script_form_runs_a_file() {
+        let Some(bin) = python3() else {
+            eprintln!("skipping: python3 not on PATH");
+            return;
+        };
+        let dir = tempfile::tempdir().unwrap();
+        let script = dir.path().join("s.py");
+        std::fs::write(&script, "print('from file')\n").unwrap();
+        let out = Python::new(&bin).script(&script).run().await.unwrap();
+        assert_eq!(out.stdout_string().unwrap(), "from file\n");
+    }
+}
diff --git a/crates/hm-dsl-engine/src/python_engine.rs b/crates/hm-dsl-engine/src/python_engine.rs
index 38ae5498..2f30bff0 100644
--- a/crates/hm-dsl-engine/src/python_engine.rs
+++ b/crates/hm-dsl-engine/src/python_engine.rs
@@ -1,8 +1,9 @@
-use std::path::Path;
+use std::path::{Path, PathBuf};
 
 use anyhow::{Context, Result};
 use async_trait::async_trait;
-use hm_common::process::{AsyncCommandExt as _, CapturedStreams as _, pathbin};
+use hm_common::process::{CapturedStreams as _, pathbin};
+use hm_common::python::Python;
 use tracing::debug;
 
 use crate::bundled_sources;
@@ -60,7 +61,7 @@ print(json.dumps(match['definition']))
 
 #[derive(Debug)]
 pub struct SubprocessPythonEngine {
-    python_bin: std::path::PathBuf,
+    python_bin: PathBuf,
 }
 
 impl SubprocessPythonEngine {
@@ -84,21 +85,13 @@ impl SubprocessPythonEngine {
         let harmont_pkg = tmp.path().join("harmont");
         bundled_sources::extract_to(&bundled_sources::HARMONT_PY, &harmont_pkg)?;
 
-        let mut cmd = tokio::process::Command::new(&self.python_bin);
-        cmd.arg("-c")
-            .arg(script)
-            .args(extra_args)
-            .current_dir(project_dir)
-            .env("PYTHONPATH", tmp.path())
-            .env("PYTHONDONTWRITEBYTECODE", "1");
-
-        debug!(?cmd, "running python3 subprocess");
-
-        // `.captured()` pipes stdout/stderr and nulls stdin; `.success()`
-        // surfaces a non-zero exit (with stderr) as an error via `?`.
-        let ok = cmd.captured().await.context("spawning python3")?.success()?;
-        ok.stdout_string()
-            .context("python3 stdout is not valid UTF-8")
+        let mut py = Python::new(&self.python_bin).program(script);
+        py.args(extra_args).current_dir(project_dir);
+        py.pythonpath(tmp.path());
+
+        debug!(?py, "running python3 subprocess");
+
+        Ok(py.run().await?.stdout_string()?)
     }
 }
 

From 5ebbca49bfdc37d92ae71181adfd383a0fcac685 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 19:59:16 -0700
Subject: [PATCH 17/18] refactor: fold SystemBins into AppRuntime; engine grabs
 the runtime
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Remove the SystemBins struct; AppRuntime now holds the resolved git and
python3 paths directly and resolves them in ::init via pathbin. Drop the
AppRuntime::bins() accessor (git()/python() read the fields).

SubprocessPythonEngine loses its python_bin field and fallible new() —
it is a unit struct that runs python3 through AppRuntime::python(), so
the DSL engine now depends on AppRuntime being initialized (feature +
init-or-skip in the integration tests; the hm binary already inits in
main). Mark AppRuntime with a TODO to thread an explicit handle later.
---
 crates/hm-common/src/app_runtime.rs           | 27 +++++-----
 crates/hm-common/src/git.rs                   |  2 +-
 crates/hm-common/src/process/mod.rs           |  2 +-
 crates/hm-common/src/process/which.rs         | 49 +------------------
 crates/hm-common/src/python.rs                |  2 +-
 crates/hm-dsl-engine/Cargo.toml               |  2 +-
 crates/hm-dsl-engine/src/python_engine.rs     | 37 ++++++--------
 .../hm-dsl-engine/tests/python_engine_test.rs | 14 +++---
 crates/hm/src/cli/pipelines.rs                |  2 +-
 crates/hm/src/cli/render.rs                   |  2 +-
 crates/hm/src/commands/run/mod.rs             |  3 +-
 11 files changed, 40 insertions(+), 102 deletions(-)

diff --git a/crates/hm-common/src/app_runtime.rs b/crates/hm-common/src/app_runtime.rs
index 66bb7535..8844ff4f 100644
--- a/crates/hm-common/src/app_runtime.rs
+++ b/crates/hm-common/src/app_runtime.rs
@@ -4,7 +4,7 @@ use std::path::{Path, PathBuf};
 use std::sync::OnceLock;
 
 use crate::git::Git;
-use crate::process::{ExecutableNotFound, SystemBins};
+use crate::process::{ExecutableNotFound, pathbin};
 use crate::python::Python;
 
 /// Failure to initialize the [`AppRuntime`].
@@ -18,13 +18,18 @@ pub enum InitError {
     Cwd(#[source] std::io::Error),
 }
 
+// TODO: This is a process-wide singleton (a global `OnceLock`), which is
+// convenient but couples every caller to hidden global state. Consider
+// threading an explicit `AppRuntime` handle through the application instead,
+// so dependencies are visible in signatures and tests can inject their own.
 /// Process-wide runtime context, resolved once at startup.
 ///
 /// Install it with [`init`](Self::init), then read it from anywhere through the
 /// associated accessors — no threading required.
 #[derive(Debug)]
 pub struct AppRuntime {
-    bins: SystemBins,
+    git: PathBuf,
+    python3: PathBuf,
     cwd: PathBuf,
 }
 
@@ -46,7 +51,8 @@ impl AppRuntime {
 
     fn resolve() -> Result<Self, InitError> {
         Ok(Self {
-            bins: SystemBins::resolve()?,
+            git: pathbin("git")?,
+            python3: pathbin("python3")?,
             cwd: std::env::current_dir().map_err(InitError::Cwd)?,
         })
     }
@@ -61,15 +67,6 @@ impl AppRuntime {
             .expect("AppRuntime::init must be called before the runtime is accessed")
     }
 
-    /// The resolved system executables.
-    ///
-    /// # Panics
-    /// If [`init`](Self::init) has not been called.
-    #[must_use]
-    pub fn bins() -> &'static SystemBins {
-        &Self::get().bins
-    }
-
     /// The absolute working directory captured at initialization.
     ///
     /// # Panics
@@ -85,7 +82,7 @@ impl AppRuntime {
     /// If [`init`](Self::init) has not been called.
     #[must_use]
     pub fn git() -> Git<'static> {
-        Git::new(Self::bins().git())
+        Git::new(&Self::get().git)
     }
 
     /// The system `python3`, bound to a [`Python`] handle.
@@ -94,7 +91,7 @@ impl AppRuntime {
     /// If [`init`](Self::init) has not been called.
     #[must_use]
     pub fn python() -> Python<'static> {
-        Python::new(Self::bins().python3())
+        Python::new(&Self::get().python3)
     }
 }
 
@@ -106,7 +103,6 @@ impl AppRuntime {
 )]
 mod tests {
     use super::*;
-    use crate::process::pathbin;
     use rstest::rstest;
 
     #[rstest]
@@ -134,7 +130,6 @@ mod tests {
         }
         AppRuntime::init().unwrap();
         assert!(AppRuntime::cwd().is_absolute());
-        assert!(AppRuntime::bins().git().is_absolute());
         // git() binds the resolved git; a fresh temp dir is not a repo.
         let dir = tempfile::tempdir().unwrap();
         assert!(AppRuntime::git().repo(dir.path()).is_err());
diff --git a/crates/hm-common/src/git.rs b/crates/hm-common/src/git.rs
index 61dc2473..d4f021e4 100644
--- a/crates/hm-common/src/git.rs
+++ b/crates/hm-common/src/git.rs
@@ -21,7 +21,7 @@ pub struct Git<'bin> {
 }
 
 impl<'bin> Git<'bin> {
-    /// Wrap a `git` executable, typically `AppRuntime::bins().git()`.
+    /// Wrap a `git` executable, typically via `AppRuntime::git()`.
     #[must_use]
     pub const fn new(bin: &'bin Path) -> Self {
         Self { bin }
diff --git a/crates/hm-common/src/process/mod.rs b/crates/hm-common/src/process/mod.rs
index 4d55220c..0aa90a80 100644
--- a/crates/hm-common/src/process/mod.rs
+++ b/crates/hm-common/src/process/mod.rs
@@ -6,4 +6,4 @@ pub mod which;
 pub use capture::{
     AsyncCommandExt, Captured, CapturedError, CapturedOk, CapturedStreams, CommandExt,
 };
-pub use which::{ExecutableNotFound, SystemBins, pathbin};
+pub use which::{ExecutableNotFound, pathbin};
diff --git a/crates/hm-common/src/process/which.rs b/crates/hm-common/src/process/which.rs
index b5fdd444..3f44d250 100644
--- a/crates/hm-common/src/process/which.rs
+++ b/crates/hm-common/src/process/which.rs
@@ -1,7 +1,7 @@
 //! Locating executables on `PATH`.
 
 use std::ffi::OsStr;
-use std::path::{Path, PathBuf};
+use std::path::PathBuf;
 
 /// The requested program was not found on `PATH`.
 #[derive(Debug, thiserror::Error)]
@@ -21,35 +21,6 @@ pub fn pathbin(program: impl AsRef<OsStr>) -> Result<PathBuf, ExecutableNotFound
     })
 }
 
-/// The external executables Harmont shells out to, resolved from `PATH`.
-#[derive(Debug, Clone)]
-pub struct SystemBins {
-    python3: PathBuf,
-    git: PathBuf,
-}
-
-impl SystemBins {
-    /// Resolve the toolchain from `PATH`.
-    pub fn resolve() -> Result<Self, ExecutableNotFound> {
-        Ok(Self {
-            python3: pathbin("python3")?,
-            git: pathbin("git")?,
-        })
-    }
-
-    /// Path to `python3`.
-    #[must_use]
-    pub fn python3(&self) -> &Path {
-        &self.python3
-    }
-
-    /// Path to `git`.
-    #[must_use]
-    pub fn git(&self) -> &Path {
-        &self.git
-    }
-}
-
 #[cfg(test)]
 #[allow(clippy::unwrap_used, reason = "test setup and assertions")]
 mod tests {
@@ -77,22 +48,4 @@ mod tests {
         assert!(msg.contains("hm-common-no-such-binary-xyz"), "program: {msg}");
         assert!(msg.contains("not found on PATH"), "phrasing: {msg}");
     }
-
-    #[rstest]
-    fn resolve_succeeds_when_python3_and_git_present() {
-        assert_eq!(
-            SystemBins::resolve().is_ok(),
-            pathbin("python3").is_ok() && pathbin("git").is_ok()
-        );
-    }
-
-    #[rstest]
-    fn system_bins_exposes_paths() {
-        let bins = SystemBins {
-            python3: PathBuf::from("/opt/python3"),
-            git: PathBuf::from("/opt/git"),
-        };
-        assert_eq!(bins.python3(), Path::new("/opt/python3"));
-        assert_eq!(bins.git(), Path::new("/opt/git"));
-    }
 }
diff --git a/crates/hm-common/src/python.rs b/crates/hm-common/src/python.rs
index 17b9b91c..f0b6b9a8 100644
--- a/crates/hm-common/src/python.rs
+++ b/crates/hm-common/src/python.rs
@@ -15,7 +15,7 @@ pub struct Python<'bin> {
 }
 
 impl<'bin> Python<'bin> {
-    /// Wrap a `python3` executable, typically `AppRuntime::bins().python3()`.
+    /// Wrap a `python3` executable, typically via `AppRuntime::python()`.
     #[must_use]
     pub const fn new(bin: &'bin Path) -> Self {
         Self { bin }
diff --git a/crates/hm-dsl-engine/Cargo.toml b/crates/hm-dsl-engine/Cargo.toml
index 1cf968d4..db718a23 100644
--- a/crates/hm-dsl-engine/Cargo.toml
+++ b/crates/hm-dsl-engine/Cargo.toml
@@ -12,7 +12,7 @@ categories = ["command-line-utilities"]
 path = "src/lib.rs"
 
 [dependencies]
-hm-common   = { workspace = true }
+hm-common   = { workspace = true, features = ["app-runtime"] }
 anyhow      = { workspace = true }
 async-trait = { workspace = true }
 derive_more = { workspace = true }
diff --git a/crates/hm-dsl-engine/src/python_engine.rs b/crates/hm-dsl-engine/src/python_engine.rs
index 2f30bff0..666f158f 100644
--- a/crates/hm-dsl-engine/src/python_engine.rs
+++ b/crates/hm-dsl-engine/src/python_engine.rs
@@ -1,9 +1,9 @@
-use std::path::{Path, PathBuf};
+use std::path::Path;
 
 use anyhow::{Context, Result};
 use async_trait::async_trait;
-use hm_common::process::{CapturedStreams as _, pathbin};
-use hm_common::python::Python;
+use hm_common::app_runtime::AppRuntime;
+use hm_common::process::CapturedStreams as _;
 use tracing::debug;
 
 use crate::bundled_sources;
@@ -59,20 +59,15 @@ if match is None:
 print(json.dumps(match['definition']))
 ";
 
-#[derive(Debug)]
-pub struct SubprocessPythonEngine {
-    python_bin: PathBuf,
-}
+#[derive(Debug, Default)]
+pub struct SubprocessPythonEngine;
 
 impl SubprocessPythonEngine {
-    /// Create engine, verifying `python3` is available on PATH.
-    ///
-    /// # Errors
-    ///
-    /// Returns an error if `python3` is not found on `PATH`.
-    pub fn new() -> Result<Self> {
-        let python_bin = pathbin("python3").context("install Python 3.11+")?;
-        Ok(Self { python_bin })
+    /// Create the engine. It runs `python3` through [`AppRuntime::python`], so
+    /// [`AppRuntime::init`] must have been called first.
+    #[must_use]
+    pub const fn new() -> Self {
+        Self
     }
 
     async fn run_script(
@@ -85,7 +80,7 @@ impl SubprocessPythonEngine {
         let harmont_pkg = tmp.path().join("harmont");
         bundled_sources::extract_to(&bundled_sources::HARMONT_PY, &harmont_pkg)?;
 
-        let mut py = Python::new(&self.python_bin).program(script);
+        let mut py = AppRuntime::python().program(script);
         py.args(extra_args).current_dir(project_dir);
         py.pythonpath(tmp.path());
 
@@ -121,13 +116,9 @@ impl DslEngine for SubprocessPythonEngine {
     }
 }
 
-/// Instanciates a python engine.
-/// Shorthand for [`SubprocessPythonEngine`].
-///
-/// # Errors
-///
-/// Returns an error if `python3` is not found on `PATH`.
+/// Instantiates a python engine. Shorthand for [`SubprocessPythonEngine::new`].
 #[inline]
-pub fn engine() -> Result<SubprocessPythonEngine> {
+#[must_use]
+pub const fn engine() -> SubprocessPythonEngine {
     SubprocessPythonEngine::new()
 }
diff --git a/crates/hm-dsl-engine/tests/python_engine_test.rs b/crates/hm-dsl-engine/tests/python_engine_test.rs
index 92967569..5c2de205 100644
--- a/crates/hm-dsl-engine/tests/python_engine_test.rs
+++ b/crates/hm-dsl-engine/tests/python_engine_test.rs
@@ -9,9 +9,9 @@ use hm_dsl_engine::DslEngine;
 
 #[tokio::test]
 async fn python_roundtrip() {
-    // Skip if python3 not available or harmont deps missing
-    if hm_common::process::pathbin("python3").is_err() {
-        eprintln!("skipping: python3 not on PATH");
+    // Skip if the toolchain (python3 + git) is unavailable.
+    if hm_common::app_runtime::AppRuntime::init().is_err() {
+        eprintln!("skipping: build toolchain unavailable");
         return;
     }
 
@@ -31,7 +31,7 @@ def ci() -> hm.Step:
 
     hm_dsl_engine::detect::check_python(dir.path()).unwrap();
 
-    let engine = hm_dsl_engine::python_engine().unwrap();
+    let engine = hm_dsl_engine::python_engine();
     let metas = engine.list_pipelines(dir.path()).await.unwrap();
     assert_eq!(metas.len(), 1);
     assert_eq!(metas[0].slug, "ci");
@@ -43,8 +43,8 @@ def ci() -> hm.Step:
 
 #[tokio::test]
 async fn python_registry_json_carries_triggers_and_allow_manual() {
-    if hm_common::process::pathbin("python3").is_err() {
-        eprintln!("skipping: python3 not on PATH");
+    if hm_common::app_runtime::AppRuntime::init().is_err() {
+        eprintln!("skipping: build toolchain unavailable");
         return;
     }
 
@@ -62,7 +62,7 @@ def ci() -> hm.Step:
     )
     .unwrap();
 
-    let engine = hm_dsl_engine::python_engine().unwrap();
+    let engine = hm_dsl_engine::python_engine();
     let json = engine.registry_json(dir.path()).await.unwrap();
     let v: serde_json::Value = serde_json::from_str(&json).unwrap();
 
diff --git a/crates/hm/src/cli/pipelines.rs b/crates/hm/src/cli/pipelines.rs
index 5ee250ee..0be5b3dd 100644
--- a/crates/hm/src/cli/pipelines.rs
+++ b/crates/hm/src/cli/pipelines.rs
@@ -39,7 +39,7 @@ pub async fn run(args: PipelinesArgs) -> Result<()> {
     }
 
     detect::check_python(&repo_root).context("detecting pipeline language")?;
-    let engine = python_engine().context("initializing DSL engine")?;
+    let engine = python_engine();
     let json = engine
         .registry_json(&repo_root)
         .await
diff --git a/crates/hm/src/cli/render.rs b/crates/hm/src/cli/render.rs
index cc10ca99..374160b6 100644
--- a/crates/hm/src/cli/render.rs
+++ b/crates/hm/src/cli/render.rs
@@ -32,7 +32,7 @@ pub async fn run(args: RenderArgs) -> Result<()> {
     };
 
     detect::check_python(&repo_root).context("detecting pipeline language")?;
-    let engine = python_engine().context("initializing DSL engine")?;
+    let engine = python_engine();
     let json = engine
         .render_pipeline_json(&repo_root, &args.slug)
         .await
diff --git a/crates/hm/src/commands/run/mod.rs b/crates/hm/src/commands/run/mod.rs
index 07315ae8..c4a66717 100644
--- a/crates/hm/src/commands/run/mod.rs
+++ b/crates/hm/src/commands/run/mod.rs
@@ -300,8 +300,7 @@ async fn render_pipeline(
     };
 
     detect::check_python(&repo_root).map_err(|e| HmError::DslEngine(format!("{e:#}")))?;
-    let engine =
-        hm_dsl_engine::python_engine().map_err(|e| HmError::DslEngine(format!("{e:#}")))?;
+    let engine = hm_dsl_engine::python_engine();
 
     let slug = if let Some(s) = &args.pipeline {
         s.clone()

From 49330b8a2a21a3f40399ada6c97afa2fd979cb92 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Sat, 25 Jul 2026 20:03:43 -0700
Subject: [PATCH 18/18] refactor(hm-dsl-engine): drop redundant engine() for
 SubprocessPythonEngine::new()

The free function was a bare shorthand for the constructor; callers now
use SubprocessPythonEngine::new() directly.
---
 crates/hm-dsl-engine/src/lib.rs                  | 2 +-
 crates/hm-dsl-engine/src/python_engine.rs        | 7 -------
 crates/hm-dsl-engine/tests/python_engine_test.rs | 4 ++--
 crates/hm/src/cli/pipelines.rs                   | 4 ++--
 crates/hm/src/cli/render.rs                      | 4 ++--
 crates/hm/src/commands/run/mod.rs                | 2 +-
 6 files changed, 8 insertions(+), 15 deletions(-)

diff --git a/crates/hm-dsl-engine/src/lib.rs b/crates/hm-dsl-engine/src/lib.rs
index 6430b520..4a1eb54b 100644
--- a/crates/hm-dsl-engine/src/lib.rs
+++ b/crates/hm-dsl-engine/src/lib.rs
@@ -6,7 +6,7 @@ use serde::Deserialize;
 pub mod detect;
 mod python_engine;
 
-pub use python_engine::{SubprocessPythonEngine, engine as python_engine};
+pub use python_engine::SubprocessPythonEngine;
 
 mod bundled_sources;
 
diff --git a/crates/hm-dsl-engine/src/python_engine.rs b/crates/hm-dsl-engine/src/python_engine.rs
index 666f158f..9980898a 100644
--- a/crates/hm-dsl-engine/src/python_engine.rs
+++ b/crates/hm-dsl-engine/src/python_engine.rs
@@ -115,10 +115,3 @@ impl DslEngine for SubprocessPythonEngine {
             .context("dumping pipeline registry via python3")
     }
 }
-
-/// Instantiates a python engine. Shorthand for [`SubprocessPythonEngine::new`].
-#[inline]
-#[must_use]
-pub const fn engine() -> SubprocessPythonEngine {
-    SubprocessPythonEngine::new()
-}
diff --git a/crates/hm-dsl-engine/tests/python_engine_test.rs b/crates/hm-dsl-engine/tests/python_engine_test.rs
index 5c2de205..76b37cc5 100644
--- a/crates/hm-dsl-engine/tests/python_engine_test.rs
+++ b/crates/hm-dsl-engine/tests/python_engine_test.rs
@@ -31,7 +31,7 @@ def ci() -> hm.Step:
 
     hm_dsl_engine::detect::check_python(dir.path()).unwrap();
 
-    let engine = hm_dsl_engine::python_engine();
+    let engine = hm_dsl_engine::SubprocessPythonEngine::new();
     let metas = engine.list_pipelines(dir.path()).await.unwrap();
     assert_eq!(metas.len(), 1);
     assert_eq!(metas[0].slug, "ci");
@@ -62,7 +62,7 @@ def ci() -> hm.Step:
     )
     .unwrap();
 
-    let engine = hm_dsl_engine::python_engine();
+    let engine = hm_dsl_engine::SubprocessPythonEngine::new();
     let json = engine.registry_json(dir.path()).await.unwrap();
     let v: serde_json::Value = serde_json::from_str(&json).unwrap();
 
diff --git a/crates/hm/src/cli/pipelines.rs b/crates/hm/src/cli/pipelines.rs
index 0be5b3dd..3f94d018 100644
--- a/crates/hm/src/cli/pipelines.rs
+++ b/crates/hm/src/cli/pipelines.rs
@@ -2,7 +2,7 @@ use std::path::PathBuf;
 
 use anyhow::{Context, Result};
 use clap::Parser;
-use hm_dsl_engine::{DslEngine, detect, python_engine};
+use hm_dsl_engine::{DslEngine, SubprocessPythonEngine, detect};
 
 #[derive(Debug, Clone, Parser)]
 pub struct PipelinesArgs {
@@ -39,7 +39,7 @@ pub async fn run(args: PipelinesArgs) -> Result<()> {
     }
 
     detect::check_python(&repo_root).context("detecting pipeline language")?;
-    let engine = python_engine();
+    let engine = SubprocessPythonEngine::new();
     let json = engine
         .registry_json(&repo_root)
         .await
diff --git a/crates/hm/src/cli/render.rs b/crates/hm/src/cli/render.rs
index 374160b6..ca907647 100644
--- a/crates/hm/src/cli/render.rs
+++ b/crates/hm/src/cli/render.rs
@@ -2,7 +2,7 @@ use std::path::PathBuf;
 
 use anyhow::{Context, Result};
 use clap::Parser;
-use hm_dsl_engine::{DslEngine, detect, python_engine};
+use hm_dsl_engine::{DslEngine, SubprocessPythonEngine, detect};
 
 #[derive(Debug, Clone, Parser)]
 pub struct RenderArgs {
@@ -32,7 +32,7 @@ pub async fn run(args: RenderArgs) -> Result<()> {
     };
 
     detect::check_python(&repo_root).context("detecting pipeline language")?;
-    let engine = python_engine();
+    let engine = SubprocessPythonEngine::new();
     let json = engine
         .render_pipeline_json(&repo_root, &args.slug)
         .await
diff --git a/crates/hm/src/commands/run/mod.rs b/crates/hm/src/commands/run/mod.rs
index c4a66717..ce2ef283 100644
--- a/crates/hm/src/commands/run/mod.rs
+++ b/crates/hm/src/commands/run/mod.rs
@@ -300,7 +300,7 @@ async fn render_pipeline(
     };
 
     detect::check_python(&repo_root).map_err(|e| HmError::DslEngine(format!("{e:#}")))?;
-    let engine = hm_dsl_engine::python_engine();
+    let engine = hm_dsl_engine::SubprocessPythonEngine::new();
 
     let slug = if let Some(s) = &args.pipeline {
         s.clone()