dirsql 0.3.57__tar.gz → 0.3.59__tar.gz

{dirsql-0.3.57 → dirsql-0.3.59}/Cargo.lock

@@ -500,7 +500,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.3.57"
+version = "0.3.59"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.3.57 → dirsql-0.3.59}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.57
+Version: 0.3.59
 Requires-Dist: pytest>=8 ; extra == 'dev'
 Requires-Dist: pytest-describe>=2 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'

{dirsql-0.3.57 → dirsql-0.3.59}/docs/cli/config.md

@@ -244,6 +244,13 @@ file is skipped (it contributes no rows) and a one-line warning naming the file
 and the error is written to stderr. One bad file never aborts the scan; the
 other files' rows are indexed normally.
 
+**Timeout.** Each run is bounded by the default 30-second timeout. When a
+command legitimately needs longer — it downloads a model on first run, or calls
+a rate-limited API — raise the bound with the global
+[`[dirsql].hook-timeout`](#command-execution) key (positive whole seconds). A
+run exceeding the bound is killed and handled with the per-file error isolation
+above (the file is skipped with a stderr warning).
+
 See [Command execution](#command-execution) for the full contract (argv
 splitting, injection safety, cwd, environment, timeout, and output framing).
 
@@ -279,7 +286,8 @@ key and the `{"sql": …}` contract returns.
 **On failure** — a non-zero exit, a timeout, or a spawn error — the request
 returns `500 Internal Server Error` with the command's stderr tail in the JSON
 `error` body. The command runs in the config file's directory and is bounded by
-a fixed **30-second** timeout.
+a **30-second** timeout by default; a slow translator (e.g. LLM-backed) can
+raise it with the global [`[dirsql].hook-timeout`](#command-execution) key.
 
 #### The hook owns SQL safety
 
@@ -361,7 +369,8 @@ returns.
 **On failure** — a non-zero exit, a timeout, or a spawn error — the request
 returns `500 Internal Server Error` with the command's stderr tail in the JSON
 `error` body. The command runs in the config file's directory and is bounded by
-a fixed **30-second** timeout.
+a **30-second** timeout by default; raise it with the global
+[`[dirsql].hook-timeout`](#command-execution) key.
 
 See [Command execution](#command-execution) for the full contract (argv
 splitting, injection safety, cwd, environment, timeout, and output framing).
@@ -409,9 +418,18 @@ Config keys that run an external command — today `on-file`, `pre-query`, and
 - **Output framing.** The command's result is the **last non-empty line of
   stdout**; any log/chatter lines above it are ignored. stderr is never data —
   it is captured only to enrich error messages.
-- **Timeout.** Each command run is bounded by a fixed **30-second** timeout (no
-  per-table override yet); a command that exceeds it is killed and treated as a
-  failure.
+- **Timeout.** Each command run is bounded by a **30-second** timeout by
+  default; a command that exceeds it is killed and treated as a failure. Raise
+  (or tighten) it for **all** hooks — `on-file`, `pre-query`, and `post-query`
+  alike — with a single global `[dirsql].hook-timeout` key, in positive whole
+  seconds:
+
+  ```toml
+  [dirsql]
+  hook-timeout = 300
+  ```
+
+  Zero and negative values are rejected as a config error.
 - **Errors.** A non-zero exit, a timeout, a spawn failure, or output that does
   not parse as expected is a per-file failure: the file is skipped with a
   stderr warning and the scan continues.

{dirsql-0.3.57 → dirsql-0.3.59}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.3.57"
+version = "0.3.59"
 edition.workspace = true
 publish = false
 readme = "README.md"

{dirsql-0.3.57/packages/rust → dirsql-0.3.59/packages/python}/docs/cli/config.md

@@ -244,6 +244,13 @@ file is skipped (it contributes no rows) and a one-line warning naming the file
 and the error is written to stderr. One bad file never aborts the scan; the
 other files' rows are indexed normally.
 
+**Timeout.** Each run is bounded by the default 30-second timeout. When a
+command legitimately needs longer — it downloads a model on first run, or calls
+a rate-limited API — raise the bound with the global
+[`[dirsql].hook-timeout`](#command-execution) key (positive whole seconds). A
+run exceeding the bound is killed and handled with the per-file error isolation
+above (the file is skipped with a stderr warning).
+
 See [Command execution](#command-execution) for the full contract (argv
 splitting, injection safety, cwd, environment, timeout, and output framing).
 
@@ -279,7 +286,8 @@ key and the `{"sql": …}` contract returns.
 **On failure** — a non-zero exit, a timeout, or a spawn error — the request
 returns `500 Internal Server Error` with the command's stderr tail in the JSON
 `error` body. The command runs in the config file's directory and is bounded by
-a fixed **30-second** timeout.
+a **30-second** timeout by default; a slow translator (e.g. LLM-backed) can
+raise it with the global [`[dirsql].hook-timeout`](#command-execution) key.
 
 #### The hook owns SQL safety
 
@@ -361,7 +369,8 @@ returns.
 **On failure** — a non-zero exit, a timeout, or a spawn error — the request
 returns `500 Internal Server Error` with the command's stderr tail in the JSON
 `error` body. The command runs in the config file's directory and is bounded by
-a fixed **30-second** timeout.
+a **30-second** timeout by default; raise it with the global
+[`[dirsql].hook-timeout`](#command-execution) key.
 
 See [Command execution](#command-execution) for the full contract (argv
 splitting, injection safety, cwd, environment, timeout, and output framing).
@@ -409,9 +418,18 @@ Config keys that run an external command — today `on-file`, `pre-query`, and
 - **Output framing.** The command's result is the **last non-empty line of
   stdout**; any log/chatter lines above it are ignored. stderr is never data —
   it is captured only to enrich error messages.
-- **Timeout.** Each command run is bounded by a fixed **30-second** timeout (no
-  per-table override yet); a command that exceeds it is killed and treated as a
-  failure.
+- **Timeout.** Each command run is bounded by a **30-second** timeout by
+  default; a command that exceeds it is killed and treated as a failure. Raise
+  (or tighten) it for **all** hooks — `on-file`, `pre-query`, and `post-query`
+  alike — with a single global `[dirsql].hook-timeout` key, in positive whole
+  seconds:
+
+  ```toml
+  [dirsql]
+  hook-timeout = 300
+  ```
+
+  Zero and negative values are rejected as a config error.
 - **Errors.** A non-zero exit, a timeout, a spawn failure, or output that does
   not parse as expected is a per-file failure: the file is skipped with a
   stderr warning and the scan continues.

{dirsql-0.3.57 → dirsql-0.3.59}/packages/python/e2e-attestation.json

@@ -1,6 +1,6 @@
 {
   "command": "uv run python -m pytest tests/e2e/ -x -q",
-  "ran_at": 1783105847,
+  "ran_at": 1783120355,
   "exit_code": 0,
-  "commit": "d94d40b0448b03171f2e8ffd60635575da1353d5"
+  "commit": "c460b738d83c83b4c76b10cd967e3641cbe35c7c"
 }

{dirsql-0.3.57/packages/python → dirsql-0.3.59/packages/rust}/docs/cli/config.md

@@ -244,6 +244,13 @@ file is skipped (it contributes no rows) and a one-line warning naming the file
 and the error is written to stderr. One bad file never aborts the scan; the
 other files' rows are indexed normally.
 
+**Timeout.** Each run is bounded by the default 30-second timeout. When a
+command legitimately needs longer — it downloads a model on first run, or calls
+a rate-limited API — raise the bound with the global
+[`[dirsql].hook-timeout`](#command-execution) key (positive whole seconds). A
+run exceeding the bound is killed and handled with the per-file error isolation
+above (the file is skipped with a stderr warning).
+
 See [Command execution](#command-execution) for the full contract (argv
 splitting, injection safety, cwd, environment, timeout, and output framing).
 
@@ -279,7 +286,8 @@ key and the `{"sql": …}` contract returns.
 **On failure** — a non-zero exit, a timeout, or a spawn error — the request
 returns `500 Internal Server Error` with the command's stderr tail in the JSON
 `error` body. The command runs in the config file's directory and is bounded by
-a fixed **30-second** timeout.
+a **30-second** timeout by default; a slow translator (e.g. LLM-backed) can
+raise it with the global [`[dirsql].hook-timeout`](#command-execution) key.
 
 #### The hook owns SQL safety
 
@@ -361,7 +369,8 @@ returns.
 **On failure** — a non-zero exit, a timeout, or a spawn error — the request
 returns `500 Internal Server Error` with the command's stderr tail in the JSON
 `error` body. The command runs in the config file's directory and is bounded by
-a fixed **30-second** timeout.
+a **30-second** timeout by default; raise it with the global
+[`[dirsql].hook-timeout`](#command-execution) key.
 
 See [Command execution](#command-execution) for the full contract (argv
 splitting, injection safety, cwd, environment, timeout, and output framing).
@@ -409,9 +418,18 @@ Config keys that run an external command — today `on-file`, `pre-query`, and
 - **Output framing.** The command's result is the **last non-empty line of
   stdout**; any log/chatter lines above it are ignored. stderr is never data —
   it is captured only to enrich error messages.
-- **Timeout.** Each command run is bounded by a fixed **30-second** timeout (no
-  per-table override yet); a command that exceeds it is killed and treated as a
-  failure.
+- **Timeout.** Each command run is bounded by a **30-second** timeout by
+  default; a command that exceeds it is killed and treated as a failure. Raise
+  (or tighten) it for **all** hooks — `on-file`, `pre-query`, and `post-query`
+  alike — with a single global `[dirsql].hook-timeout` key, in positive whole
+  seconds:
+
+  ```toml
+  [dirsql]
+  hook-timeout = 300
+  ```
+
+  Zero and negative values are rejected as a config error.
 - **Errors.** A non-zero exit, a timeout, a spawn failure, or output that does
   not parse as expected is a per-file failure: the file is skipped with a
   stderr warning and the scan continues.

{dirsql-0.3.57 → dirsql-0.3.59}/packages/rust/src/bin/dirsql.rs

@@ -228,9 +228,14 @@ fn load_pre_query(cli: &Cli) -> Option<PreQuery> {
         return None;
     }
     let resolved = config_path.canonicalize().ok()?;
-    let command = dirsql::config::load_config(&resolved).ok()?.pre_query?;
+    let config = dirsql::config::load_config(&resolved).ok()?;
+    let command = config.pre_query?;
     let config_dir = resolved.parent()?.to_path_buf();
-    Some(PreQuery::new(command, config_dir))
+    let mut pre_query = PreQuery::new(command, config_dir);
+    if let Some(timeout) = config.hook_timeout {
+        pre_query = pre_query.with_timeout(timeout);
+    }
+    Some(pre_query)
 }
 
 /// Extract the server-wide `post-query` hook from the config, if any.
@@ -245,9 +250,14 @@ fn load_post_query(cli: &Cli) -> Option<PostQuery> {
         return None;
     }
     let resolved = config_path.canonicalize().ok()?;
-    let command = dirsql::config::load_config(&resolved).ok()?.post_query?;
+    let config = dirsql::config::load_config(&resolved).ok()?;
+    let command = config.post_query?;
     let config_dir = resolved.parent()?.to_path_buf();
-    Some(PostQuery::new(command, config_dir))
+    let mut post_query = PostQuery::new(command, config_dir);
+    if let Some(timeout) = config.hook_timeout {
+        post_query = post_query.with_timeout(timeout);
+    }
+    Some(post_query)
 }
 
 /// Zero-config fallback. When no `.dirsql.toml` is found, dirsql indexes the

{dirsql-0.3.57 → dirsql-0.3.59}/packages/rust/src/cli/init.rs

@@ -149,4 +149,21 @@ mod tests {
         let msg = format!("{err}").to_lowercase();
         assert!(msg.contains("claude"));
     }
+
+    /// `run` bails before spawning the agent when the output already exists and
+    /// `--force` was not passed (the temp dir itself is an existing path).
+    #[test]
+    fn run_bails_when_output_exists_without_force() {
+        let dir = tempfile::tempdir().unwrap();
+        let opts = InitOptions {
+            root: dir.path().to_path_buf(),
+            output: dir.path().to_path_buf(),
+            force: false,
+        };
+        let err = run(opts).unwrap_err();
+        assert!(
+            matches!(err, InitError::AlreadyExists { .. }),
+            "got: {err:?}"
+        );
+    }
 }

{dirsql-0.3.57 → dirsql-0.3.59}/packages/rust/src/cli/mod.rs

@@ -27,6 +27,7 @@ use tokio::task::JoinError;
 use tokio::task::JoinHandle;
 
 use crate::DirSQL;
+use crate::command::DEFAULT_COMMAND_TIMEOUT;
 
 pub mod init;
 pub mod router;
@@ -51,16 +52,29 @@ pub struct PreQuery {
     pub command: String,
     /// The command's working directory — the config file's parent.
     pub config_dir: PathBuf,
+    /// Per-run timeout. Defaults to the shared 30-second
+    /// [`DEFAULT_COMMAND_TIMEOUT`]; override it via [`Self::with_timeout`]
+    /// (the CLI wires the global `[dirsql].hook-timeout` here, #351).
+    pub timeout: Duration,
 }
 
 impl PreQuery {
-    /// Build a [`PreQuery`] from a command template and its working directory.
+    /// Build a [`PreQuery`] from a command template and its working directory,
+    /// with the default 30-second timeout.
     pub fn new(command: impl Into<String>, config_dir: impl Into<PathBuf>) -> Self {
         Self {
             command: command.into(),
             config_dir: config_dir.into(),
+            timeout: DEFAULT_COMMAND_TIMEOUT,
         }
     }
+
+    /// Override the per-run timeout (from the global `[dirsql].hook-timeout`).
+    /// A run exceeding it is killed and the request returns 500.
+    pub fn with_timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = timeout;
+        self
+    }
 }
 
 /// A server-wide `post-query` command hook, carrying the command template plus
@@ -76,16 +90,29 @@ pub struct PostQuery {
     pub command: String,
     /// The command's working directory — the config file's parent.
     pub config_dir: PathBuf,
+    /// Per-run timeout. Defaults to the shared 30-second
+    /// [`DEFAULT_COMMAND_TIMEOUT`]; override it via [`Self::with_timeout`]
+    /// (the CLI wires the global `[dirsql].hook-timeout` here, #351).
+    pub timeout: Duration,
 }
 
 impl PostQuery {
-    /// Build a [`PostQuery`] from a command template and its working directory.
+    /// Build a [`PostQuery`] from a command template and its working directory,
+    /// with the default 30-second timeout.
     pub fn new(command: impl Into<String>, config_dir: impl Into<PathBuf>) -> Self {
         Self {
             command: command.into(),
             config_dir: config_dir.into(),
+            timeout: DEFAULT_COMMAND_TIMEOUT,
         }
     }
+
+    /// Override the per-run timeout (from the global `[dirsql].hook-timeout`).
+    /// A run exceeding it is killed and the request returns 500.
+    pub fn with_timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = timeout;
+        self
+    }
 }
 
 /// Configure how the server binds. Defaults to `localhost:7117` with a
@@ -258,10 +285,17 @@ mod tests {
     #[test]
     fn pre_query_constructor_carries_command_and_dir() {
         // `PreQuery::new` is pure data plumbing: the command template and the
-        // working directory it will run in.
+        // working directory it will run in, with the shared default timeout.
         let pq = PreQuery::new("to_sql.py {args}", "/proj");
         assert_eq!(pq.command, "to_sql.py {args}");
         assert_eq!(pq.config_dir, PathBuf::from("/proj"));
+        assert_eq!(pq.timeout, Duration::from_secs(30));
+    }
+
+    #[test]
+    fn pre_query_with_timeout_overrides_the_default() {
+        let pq = PreQuery::new("cmd {args}", "/proj").with_timeout(Duration::from_secs(60));
+        assert_eq!(pq.timeout, Duration::from_secs(60));
     }
 
     #[test]
@@ -275,10 +309,17 @@ mod tests {
     #[test]
     fn post_query_constructor_carries_command_and_dir() {
         // `PostQuery::new` is pure data plumbing: the command template and the
-        // working directory it will run in.
+        // working directory it will run in, with the shared default timeout.
         let pq = PostQuery::new("jq '{results: .}'", "/proj");
         assert_eq!(pq.command, "jq '{results: .}'");
         assert_eq!(pq.config_dir, PathBuf::from("/proj"));
+        assert_eq!(pq.timeout, Duration::from_secs(30));
+    }
+
+    #[test]
+    fn post_query_with_timeout_overrides_the_default() {
+        let pq = PostQuery::new("reshape {args}", "/proj").with_timeout(Duration::from_secs(60));
+        assert_eq!(pq.timeout, Duration::from_secs(60));
     }
 
     #[test]

{dirsql-0.3.57 → dirsql-0.3.59}/packages/rust/src/cli/router.rs

@@ -21,15 +21,6 @@ use super::{AppState, PostQuery, PreQuery};
 use crate::command::{Placeholder, run_command};
 use crate::{DirSQL, DirSqlError};
 
-/// Fixed timeout for a server-wide `pre-query` command. There is no override
-/// key yet; this module constant is the documented current default (mirrors
-/// `on-file`'s `ON_FILE_TIMEOUT`).
-const PRE_QUERY_TIMEOUT: Duration = Duration::from_secs(30);
-
-/// Fixed timeout for a server-wide `post-query` command (mirrors
-/// `PRE_QUERY_TIMEOUT`).
-const POST_QUERY_TIMEOUT: Duration = Duration::from_secs(30);
-
 /// Cap on the serialized result payload passed as the `{args}` argv token.
 /// Beyond this, `{args}` is emptied and the operator is directed to stdin
 /// (which always carries the full payload) — comfortably under Linux's 128 KiB
@@ -155,15 +146,17 @@ fn parse_sql_body(body: &str) -> Result<String, Response> {
 async fn run_pre_query(pq: &PreQuery, raw_body: String) -> Result<String, Response> {
     let command = pq.command.clone();
     let config_dir = pq.config_dir.clone();
+    let timeout = pq.timeout;
     // `run_command` is blocking — it spawns a child and joins drain threads —
-    // so run it off the async runtime. It enforces `PRE_QUERY_TIMEOUT`
-    // internally, so no outer `tokio::time::timeout` is needed.
+    // so run it off the async runtime. It enforces the hook's timeout
+    // (the global `[dirsql].hook-timeout`, default 30s) internally, so no outer
+    // `tokio::time::timeout` is needed.
     let outcome = tokio::task::spawn_blocking(move || {
         run_command(
             &command,
             &[Placeholder::new("args", &raw_body)],
             &config_dir,
-            PRE_QUERY_TIMEOUT,
+            timeout,
             None,
         )
     })
@@ -198,9 +191,11 @@ async fn run_post_query(
         .map_err(|err| error_response(StatusCode::INTERNAL_SERVER_ERROR, err.to_string()))?;
     let command = pq.command.clone();
     let config_dir = pq.config_dir.clone();
+    let timeout = pq.timeout;
     // `run_command` is blocking — it spawns a child and joins drain threads —
-    // so run it off the async runtime. It enforces `POST_QUERY_TIMEOUT`
-    // internally, so no outer `tokio::time::timeout` is needed.
+    // so run it off the async runtime. It enforces the hook's timeout
+    // (the global `[dirsql].hook-timeout`, default 30s) internally, so no outer
+    // `tokio::time::timeout` is needed.
     let outcome = tokio::task::spawn_blocking(move || {
         let args_value = if payload.len() <= POST_QUERY_ARGS_MAX {
             payload.clone()
@@ -217,7 +212,7 @@ async fn run_post_query(
             &command,
             &[Placeholder::new("args", &args_value)],
             &config_dir,
-            POST_QUERY_TIMEOUT,
+            timeout,
             Some(payload.as_bytes()),
         )
     })

{dirsql-0.3.57 → dirsql-0.3.59}/packages/rust/src/cli/server.rs

@@ -114,4 +114,33 @@ mod tests {
 
         handle.shutdown().await.expect("graceful shutdown");
     }
+
+    // A `Ready` state drives the `serve` convenience wrapper plus
+    // `start_watch_task` (which attaches `DirSQL::watch` and pumps its stream
+    // into the broadcast channel). Built over an empty temp dir so the scan
+    // touches nothing; the port-0 bind and graceful shutdown are real.
+    #[tokio::test]
+    async fn serve_with_a_ready_db_attaches_the_watcher_then_shuts_down() {
+        let dir = tempfile::tempdir().unwrap();
+        let db = DirSQL::new(dir.path(), Vec::new()).unwrap();
+        let config = ServerConfig::bind("127.0.0.1".to_string(), 0);
+        let handle = serve(config, db).await.expect("bind on an ephemeral port");
+        assert_ne!(handle.local_addr().port(), 0);
+        handle.shutdown().await.expect("graceful shutdown");
+    }
+
+    // Binding to a non-local TEST-NET address (RFC 5737) fails with
+    // "cannot assign requested address", surfacing `ServerError::Bind` rather
+    // than panicking — deterministic and DNS-free.
+    #[tokio::test]
+    async fn serve_with_state_surfaces_a_bind_error_for_a_nonlocal_address() {
+        let config = ServerConfig::bind("192.0.2.1".to_string(), 9);
+        // `serve_with_state` returns `Result<ServerHandle, _>`; ServerHandle is
+        // not Debug, so match rather than `unwrap_err`.
+        let err = match serve_with_state(config, AppState::Unavailable("x".to_string())).await {
+            Ok(_) => panic!("expected a bind error"),
+            Err(e) => e,
+        };
+        assert!(matches!(err, ServerError::Bind { .. }), "got: {err:?}");
+    }
 }

{dirsql-0.3.57 → dirsql-0.3.59}/packages/rust/src/command.rs

@@ -36,6 +36,11 @@ use std::time::Duration;
 
 use wait_timeout::ChildExt;
 
+/// The default timeout for every command-backed event (`on-file`,
+/// `pre-query`, `post-query`) when the config declares no override
+/// (`[dirsql].hook-timeout`, positive whole seconds).
+pub const DEFAULT_COMMAND_TIMEOUT: Duration = Duration::from_secs(30);
+
 /// A named placeholder substituted into a command's argv.
 ///
 /// `name` is the bare identifier (no braces): a `name` of `path` matches the
@@ -484,4 +489,103 @@ mod tests {
         assert!(!Placeholder::new("a", "b").append_if_absent);
         assert!(Placeholder::append("a", "b").append_if_absent);
     }
+
+    // ----- run_command end-to-end (spawns trivial POSIX commands) ----------
+    //
+    // `run_command` can only be exercised by actually spawning a child, so
+    // these drive `sh`/`echo`/`cat` — universally present on the Linux CI
+    // runners. The test code itself statically references only `super::` items,
+    // `Duration`, and `std::path::Path`, so the `unit lint` isolation rule is
+    // satisfied; the effectful process/thread work lives in production code.
+
+    fn cwd() -> std::path::PathBuf {
+        std::path::PathBuf::from(".")
+    }
+
+    #[test]
+    fn run_command_returns_last_nonempty_stdout_line() {
+        let out = run_command(
+            "sh -c 'echo chatter; echo PAYLOAD'",
+            &[],
+            &cwd(),
+            Duration::from_secs(30),
+            None,
+        )
+        .unwrap();
+        assert_eq!(out.payload, "PAYLOAD");
+    }
+
+    #[test]
+    fn run_command_writes_stdin_payload_to_the_child() {
+        // `cat` echoes its stdin, so the payload round-trips through the
+        // stdin-writer thread and the stdout drain.
+        let out = run_command(
+            "cat",
+            &[],
+            &cwd(),
+            Duration::from_secs(30),
+            Some(b"hello-stdin"),
+        )
+        .unwrap();
+        assert_eq!(out.payload, "hello-stdin");
+    }
+
+    #[test]
+    fn run_command_reports_nonzero_exit_with_stderr_tail() {
+        let err = run_command(
+            "sh -c 'echo oops >&2; exit 3'",
+            &[],
+            &cwd(),
+            Duration::from_secs(30),
+            None,
+        )
+        .unwrap_err();
+        match err {
+            CommandError::NonZeroExit {
+                code, stderr_tail, ..
+            } => {
+                assert_eq!(code, "3");
+                assert!(stderr_tail.contains("oops"), "got: {stderr_tail}");
+            }
+            other => panic!("expected NonZeroExit, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn run_command_reports_empty_output_when_stdout_is_blank() {
+        let err = run_command("true", &[], &cwd(), Duration::from_secs(30), None).unwrap_err();
+        assert!(
+            matches!(err, CommandError::EmptyOutput { .. }),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn run_command_reports_spawn_failure_for_a_missing_program() {
+        let err = run_command(
+            "definitely-not-a-real-binary-xyzzy",
+            &[],
+            &cwd(),
+            Duration::from_secs(30),
+            None,
+        )
+        .unwrap_err();
+        assert!(matches!(err, CommandError::Spawn { .. }), "got: {err:?}");
+    }
+
+    #[test]
+    fn run_command_kills_and_reports_timeout_even_with_stdin() {
+        // A short timeout against a long sleep drives the timeout branch,
+        // including joining the stdin-writer thread. `sh` ignoring stdin closes
+        // the pipe early, which the writer treats as a clean EOF.
+        let err = run_command(
+            "sh -c 'sleep 30'",
+            &[],
+            &cwd(),
+            Duration::from_millis(50),
+            Some(b"x"),
+        )
+        .unwrap_err();
+        assert!(matches!(err, CommandError::Timeout { .. }), "got: {err:?}");
+    }
 }