@@ -678,6 +678,7 @@ export struct TestOptions {
     std::string        filter;   // substring match on the path-based test name; empty = all
     TestMessageFormat  format = TestMessageFormat::Human;
     bool               list = false;   // enumerate only, no build/run
+    int                timeoutSecs = 0;   // per-test run deadline; 0 = unlimited
 };
 
 // Minimal JSON string escaping for the --message-format json records. Same
@@ -881,6 +882,7 @@ export int run_tests(std::span<const std::string> passthrough,
         std::string compileOutput;
         std::string runOutput;
         long long   durationMs = 0;    // build+run wall time for THIS test
+        bool        timedOut = false;  // killed by --timeout
     };
     std::vector<TestResult> results;
 
@@ -895,9 +897,10 @@ export int run_tests(std::span<const std::string> passthrough,
         std::string signal = (r.exitCode > 128 && r.exitCode < 128 + 65)
             ? std::to_string(r.exitCode - 128) : "null";
         std::println("{{\"test\":\"{}\",\"status\":\"{}\",\"exit_code\":{},\"signal\":{},"
-                     "\"duration_ms\":{},"
+                     "\"duration_ms\":{},\"timed_out\":{},"
                      "\"compile_output\":\"{}\",\"run_output\":\"{}\"}}",
                      test_json_escape(r.name), st, r.exitCode, signal, r.durationMs,
+                     r.timedOut ? "true" : "false",
                      test_json_escape(r.compileOutput), test_json_escape(r.runOutput));
         std::fflush(stdout);
     };
@@ -1043,17 +1046,27 @@ export int run_tests(std::span<const std::string> passthrough,
 
         // JSON mode captures the test's combined stdout+stderr into the
         // record; human mode streams it to the terminal as before.
+        auto deadline = std::chrono::milliseconds(
+            static_cast<long long>(testOpts.timeoutSecs) * 1000);
+        bool timedOut = false;
         int exitCode;
         std::string runOutput;
         if (json) {
-            auto rr = mcpp::platform::process::capture_exec(argv, childEnv);
+            auto rr = mcpp::platform::process::capture_exec_deadline(
+                argv, childEnv, deadline, &timedOut);
             exitCode  = rr.exit_code;
             runOutput = std::move(rr.output);
         } else {
-            exitCode = mcpp::platform::process::run_exec(argv, childEnv);
+            exitCode = mcpp::platform::process::run_exec_deadline(
+                argv, childEnv, deadline, &timedOut);
         }
 
-        if (exitCode == 0) {
+        if (timedOut) {
+            if (!json) std::println("{} ... FAIL (timeout after {}s)",
+                                    lu.targetName, testOpts.timeoutSecs);
+            results.push_back({lu.targetName, TestResult::St::RunFail, exitCode, {},
+                               std::move(runOutput), test_ms(), true});
+        } else if (exitCode == 0) {
             if (!json) std::println("{} ... ok", lu.targetName);
             results.push_back({lu.targetName, TestResult::St::Pass, 0, {},
                                std::move(runOutput), test_ms()});
 
@@ -257,6 +257,8 @@ int run(int argc, char** argv) {
                 .help("Output format: human (default) | json (NDJSON, one record per test)"))
             .option(cl::Option("list")
                 .help("List (filtered) tests without building or running them"))
+            .option(cl::Option("timeout").takes_value().value_name("SECS")
+                .help("Kill a test still running after SECS seconds (reported as a timeout failure)"))
             .option(cl::Option("profile").takes_value().value_name("NAME")
                 .help("Build profile for the test build: release (default) | dev | dist | <[profile.*] name>"))
             .option(cl::Option("features").takes_value().value_name("LIST")
 
@@ -128,6 +128,15 @@ export int cmd_test(const mcpplibs::cmdline::ParsedArgs& parsed,
     mcpp::build::TestOptions to;
     if (parsed.positional_count() > 0) to.filter = parsed.positional(0);
     to.list = parsed.is_flag_set("list");
+    if (auto ts = parsed.value("timeout")) {
+        int secs = 0;
+        auto [p, ec] = std::from_chars(ts->data(), ts->data() + ts->size(), secs);
+        if (ec != std::errc{} || p != ts->data() + ts->size() || secs < 0) {
+            mcpp::ui::error(std::format("invalid --timeout '{}' (whole seconds >= 0)", *ts));
+            return 2;
+        }
+        to.timeoutSecs = secs;
+    }
     if (auto mf = parsed.value("message-format")) {
         if (*mf == "json")       to.format = mcpp::build::TestMessageFormat::Json;
         else if (*mf != "human") {
 
@@ -34,6 +34,11 @@ module;
 #include <unistd.h>    // pipe, dup2, close, read
 #include <sys/wait.h>  // waitpid
 #include <spawn.h>     // posix_spawnp, posix_spawn_file_actions_* (incl. addchdir_np)
+#include <signal.h>    // kill, SIGKILL (deadline runners)
+#include <cerrno>      // errno, EINTR (deadline wait loop)
+#include <poll.h>      // poll (deadline capture)
+#include <fcntl.h>     // fcntl O_NONBLOCK (deadline capture)
+#include <time.h>      // nanosleep (deadline wait loop)
 #if defined(__APPLE__)
 #include <crt_externs.h>  // _NSGetEnviron — direct `environ` is only linkable
                           // from executables on Apple, not from dylibs
@@ -88,6 +93,21 @@ RunResult capture_exec(
     const std::vector<std::pair<std::string, std::string>>& extraEnv = {},
     std::string_view cwd = {});
 
+// Deadline variants (POSIX): kill the child with SIGKILL once `deadline`
+// elapses and set *timed_out. A zero deadline means no limit. On Windows the
+// deadline is currently ignored (no supported kill-by-handle path in the
+// residual shell launcher) — callers must treat the timeout as best-effort.
+int run_exec_deadline(const std::vector<std::string>& argv,
+                      const std::vector<std::pair<std::string, std::string>>& extraEnv,
+                      std::chrono::milliseconds deadline,
+                      bool* timed_out);
+
+RunResult capture_exec_deadline(
+    const std::vector<std::string>& argv,
+    const std::vector<std::pair<std::string, std::string>>& extraEnv,
+    std::chrono::milliseconds deadline,
+    bool* timed_out);
+
 // Run `command` silently (discard stdout/stderr).
 // On POSIX, stdin is automatically redirected from /dev/null.
 int run_silent(std::string_view command);
@@ -451,4 +471,117 @@ RunResult capture_exec(
 #endif
 }
 
+int run_exec_deadline(const std::vector<std::string>& argv,
+                      const std::vector<std::pair<std::string, std::string>>& extraEnv,
+                      std::chrono::milliseconds deadline,
+                      bool* timed_out)
+{
+    if (timed_out) *timed_out = false;
+    if (deadline.count() <= 0) return run_exec(argv, extraEnv);
+    if (argv.empty()) return 127;
+#if defined(__linux__) || defined(__APPLE__)
+    auto envStore = merged_environ(extraEnv);
+    std::vector<char*> envp;
+    for (auto& s : envStore) envp.push_back(s.data());
+    envp.push_back(nullptr);
+    std::vector<char*> cargv;
+    for (auto& a : argv) cargv.push_back(const_cast<char*>(a.c_str()));
+    cargv.push_back(nullptr);
+
+    pid_t pid = 0;
+    if (::posix_spawnp(&pid, cargv[0], nullptr, nullptr, cargv.data(), envp.data()) != 0)
+        return 127;
+
+    auto until = std::chrono::steady_clock::now() + deadline;
+    int status = 0;
+    for (;;) {
+        pid_t r = ::waitpid(pid, &status, WNOHANG);
+        if (r == pid) return normalize_exit_code(status);
+        if (r < 0 && errno != EINTR) return 127;
+        if (std::chrono::steady_clock::now() >= until) {
+            ::kill(pid, SIGKILL);
+            while (::waitpid(pid, &status, 0) < 0) { /* EINTR retry */ }
+            if (timed_out) *timed_out = true;
+            return normalize_exit_code(status);
+        }
+        struct timespec ts{0, 20'000'000};   // 20ms
+        ::nanosleep(&ts, nullptr);
+    }
+#else
+    // Windows: the residual shell launcher has no kill-by-handle path yet —
+    // run untimed (documented best-effort semantics).
+    return run_exec(argv, extraEnv);
+#endif
+}
+
+RunResult capture_exec_deadline(
+    const std::vector<std::string>& argv,
+    const std::vector<std::pair<std::string, std::string>>& extraEnv,
+    std::chrono::milliseconds deadline,
+    bool* timed_out)
+{
+    if (timed_out) *timed_out = false;
+    if (deadline.count() <= 0) return capture_exec(argv, extraEnv);
+    RunResult result;
+    if (argv.empty()) { result.exit_code = 127; return result; }
+#if defined(__linux__) || defined(__APPLE__)
+    int fds[2];
+    if (::pipe(fds) != 0) { result.exit_code = 127; return result; }
+
+    auto envStore = merged_environ(extraEnv);
+    std::vector<char*> envp;
+    for (auto& s : envStore) envp.push_back(s.data());
+    envp.push_back(nullptr);
+    std::vector<char*> cargv;
+    for (auto& a : argv) cargv.push_back(const_cast<char*>(a.c_str()));
+    cargv.push_back(nullptr);
+
+    posix_spawn_file_actions_t fa;
+    ::posix_spawn_file_actions_init(&fa);
+    ::posix_spawn_file_actions_adddup2(&fa, fds[1], 1);
+    ::posix_spawn_file_actions_adddup2(&fa, fds[1], 2);
+    ::posix_spawn_file_actions_addclose(&fa, fds[0]);
+    ::posix_spawn_file_actions_addclose(&fa, fds[1]);
+
+    pid_t pid = 0;
+    int sp = ::posix_spawnp(&pid, cargv[0], &fa, nullptr, cargv.data(), envp.data());
+    ::posix_spawn_file_actions_destroy(&fa);
+    ::close(fds[1]);
+    if (sp != 0) { ::close(fds[0]); result.exit_code = 127; return result; }
+
+    ::fcntl(fds[0], F_SETFL, ::fcntl(fds[0], F_GETFL) | O_NONBLOCK);
+
+    auto until = std::chrono::steady_clock::now() + deadline;
+    bool killed = false;
+    std::array<char, 4096> buf{};
+    for (;;) {
+        struct pollfd pfd{fds[0], POLLIN, 0};
+        ::poll(&pfd, 1, 50);
+        for (;;) {
+            ssize_t n = ::read(fds[0], buf.data(), buf.size());
+            if (n > 0) { result.output.append(buf.data(), static_cast<size_t>(n)); continue; }
+            break;
+        }
+        int status = 0;
+        pid_t r = ::waitpid(pid, &status, WNOHANG);
+        if (r == pid) {
+            // Drain whatever is left in the pipe after exit.
+            ssize_t n;
+            while ((n = ::read(fds[0], buf.data(), buf.size())) > 0)
+                result.output.append(buf.data(), static_cast<size_t>(n));
+            ::close(fds[0]);
+            result.exit_code = normalize_exit_code(status);
+            if (timed_out) *timed_out = killed;
+            return result;
+        }
+        if (!killed && std::chrono::steady_clock::now() >= until) {
+            ::kill(pid, SIGKILL);
+            killed = true;
+        }
+    }
+#else
+    return capture_exec(argv, extraEnv);
+#endif
+}
+
 } // namespace mcpp::platform::process
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# requires:
+# `mcpp test --timeout <secs>`: a hung test is killed and reported as a
+# timeout failure; the rest of the suite still runs.
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+
+cd "$TMP"
+mkdir -p pkg/tests
+cd pkg
+cat > mcpp.toml <<'EOF'
+[package]
+name = "hang"
+version = "0.1.0"
+standard = "c++23"
+EOF
+cat > tests/sleepy.cpp <<'EOF'
+import std;
+int main() { std::this_thread::sleep_for(std::chrono::seconds(30)); return 0; }
+EOF
+cat > tests/quick.cpp <<'EOF'
+int main() { return 0; }
+EOF
+
+start=$(date +%s)
+set +e
+out=$("$MCPP" test --timeout 2 2>&1)
+code=$?
+set -e
+elapsed=$(( $(date +%s) - start ))
+[[ $code -eq 1 ]] || { echo "expected exit 1, got $code: $out"; exit 1; }
+[[ $elapsed -lt 25 ]] || { echo "timeout did not take effect (took ${elapsed}s)"; exit 1; }
+[[ "$out" == *"sleepy ... FAIL (timeout"* ]] || { echo "missing timeout marker: $out"; exit 1; }
+[[ "$out" == *"quick ... ok"* ]] || { echo "quick test did not run: $out"; exit 1; }
+
+set +e
+outj=$("$MCPP" test --timeout 2 --message-format json 2>/dev/null)
+set -e
+echo "$outj" | grep -q '"test":"sleepy","status":"run_fail"' || { echo "json: no run_fail"; exit 1; }
+echo "$outj" | grep -q '"timed_out":true' || { echo "json: timed_out missing: $outj"; exit 1; }
+echo OK