fix(diagnostics): report process startup failures

Author: robertvokac

CLAUDE.md

@@ -9,7 +9,7 @@
 ## Non-negotiable rules
 
 1. **Zero errors, zero warnings** before any commit. `cmake --build build --parallel 4` must be clean.
-2. **No test-count regression.** `scripts/run_component_tests.sh build` must show no failures. The verified baseline is 12,678 tests across 36 component executables and one integration executable; this floor should be raised as new tests are added and lowered only with an explicit, documented reason.
+2. **No test-count regression.** `scripts/run_component_tests.sh build` must show no failures. The verified baseline is 12,681 tests across 36 component executables and one integration executable; this floor should be raised as new tests are added and lowered only with an explicit, documented reason.
 3. **Push only to `feature/work`.** Never push to `develop` or `master`, and never create tags, without explicit per-action user approval.
 4. **SPDX header on every project source/header** — `// SPDX-License-Identifier: MIT` + copyright + .NET attribution. Vendored sources retain their upstream headers; Markdown uses an HTML SPDX comment where one is present.
 5. **Property naming:** always `getXxxProperty()` / `setXxxProperty()`. Exception: indexers

NEXT.md

@@ -4,9 +4,9 @@
 # NEXT.md
 
 *Last verified: 2026-07-25. Branch: `feature/work`. The P0 component-boundary
-repair, three P1 parity repairs, P1 portability revalidation, and twenty-one bounded
+repair, three P1 parity repairs, P1 portability revalidation, and twenty-two bounded
 P2 API slices are complete: 41 physical modules, 90 production dependency
-edges, and 12,678 tests across 37 executables.*
+edges, and 12,681 tests across 37 executables.*
 
 This is the cold-start handoff for the next working session. Keep it focused
 on verified facts, remaining bounded work, and commands needed to resume.
@@ -28,7 +28,7 @@ Historical session detail belongs in git history and `plan.sqlite3`.
 - The ten-job selective consumer matrix, including a direct
   `Collections.Blocking` consumer, is green. Text.Json retains its target
   absence and negative include-leakage assertions.
-- The full native baseline is a warning-free build with 12,678 passing tests
+- The full native baseline is a warning-free build with 12,681 passing tests
   across 36 component executables and one integration executable.
 - `TaskT<TResult>::ContinueWith` now supports both action and result-producing
   callbacks. It runs inline on completion; `NotOn*` and `OnlyOn*` filter the
@@ -83,6 +83,9 @@ Historical session detail belongs in git history and `plan.sqlite3`.
 - `ProcessStartInfo` now supplies explicit child-only environment overrides;
   unspecified values inherit, empty values remain empty, and invalid variable
   names are rejected before forking.
+- POSIX `Process::Start` now reports child setup and exec failures synchronously
+  with the executable path and native error text, rather than returning a
+  process that later exits with code 127.
 - MinGW-w64 GCC 14-win32/CMake 3.31.6 and Emscripten 5.0.7/CMake 3.31.6 both
   compile the post-modular `All` graph and selective `Text.Json` libraries.
   This is compile-only evidence: cross tests were deliberately disabled.
@@ -91,7 +94,7 @@ Historical session detail belongs in git history and `plan.sqlite3`.
   ASan/LSan ownership scenarios, including 100 continuation teardowns, pass.
 
 The local `plan.sqlite3` snapshot contains 16,201 classified `task` rows and
-1,763 completed tickets. Ticket #1737 records the completed P0 split, tickets
+1,764 completed tickets. Ticket #1737 records the completed P0 split, tickets
 #1738/#1739 the MemoryStream and generic-continuation repairs, ticket #1740 the
 XML whitespace repair, #1741 the completed cross-build revalidation and
 `WebProxy` portability fix, #1742 focused sanitizer evidence, and #1743 the
@@ -106,7 +109,8 @@ queries, #1755 for its comparer-aware binary search, #1756 for its default
 range sort, #1757 for `BigInteger` bitwise operators, #1758 for signed
 `BigInteger` shifts, #1759 for byte-vector conversion, and #1760 for the
 `ImmutableList<T>` Builder core, #1761 for RFC 2152 UTF-7, and #1762 for
-conditional Trace writes, and #1763 for ProcessStartInfo environment overrides;
+conditional Trace writes, #1763 for ProcessStartInfo environment overrides, and
+#1764 for synchronous Process startup-failure reporting;
 it is git-ignored and is not part of a fresh clone.
 
 ## P0 completion: restore Collections isolation

README.md

@@ -7,7 +7,7 @@ collector, or the complete .NET platform.
 
 The repository currently builds as 41 independently selectable CMake
 components. The verified Linux baseline on 2026-07-25 is a warning-free build
-with **12,678 passing tests across 37 test executables**.
+with **12,681 passing tests across 37 test executables**.
 
 ## What is included
 
@@ -181,7 +181,7 @@ Other platform evidence is narrower:
 
 | Platform/toolchain | Verified scope |
 |---|---|
-| Linux/GCC | Current full component build and all 12,678 tests. |
+| Linux/GCC | Current full component build and all 12,681 tests. |
 | Windows/MinGW | MinGW-w64 GCC 14-win32/CMake 3.31.6 compiled the post-component `All` and selective `Text.Json` library graphs under ticket #1741. GoogleTest was not cross-built and repository CI remains Ubuntu-only. |
 | Emscripten | Emscripten 5.0.7/CMake 3.31.6 compiled the post-component `All` and selective `Text.Json` library graphs under ticket #1741. Tests were not cross-built or run, and some runtime APIs deliberately throw `PlatformNotSupportedException`. |
 | macOS/Apple Clang | Real downstream Xcode 15.4 builds drove portability fixes on 2026-07-20; this repository has no macOS job or recorded full standalone test baseline. |

docs/CMakeComponents.md

@@ -131,7 +131,7 @@ are named `SharpRuntimeTests_<Component>`; genuinely cross-module scenarios
 are in `SharpRuntimeIntegrationTests`. CTest also discovers every individual
 GoogleTest case.
 
-The verified 2026-07-25 `All` baseline contains 12,678 tests across 36
+The verified 2026-07-25 `All` baseline contains 12,681 tests across 36
 component executables and one integration executable.
 
 ## Boundary validation and CI

modules/diagnostics/include/System/Diagnostics/Process.hpp

@@ -28,8 +28,10 @@ namespace System::Diagnostics {
      * three static overloads), WaitForExit (blocking and timeout forms), Kill (single process and
      * process-tree via killpg), ExitCode, HasExited, Id, GetCurrentProcess, and optional
      * captured-text stdout/stderr redirection (a deliberate simplification of real .NET's
-     * Stream-based StandardOutput/StandardError -- see getStandardOutputTextProperty). Explicitly
-     * NOT implemented, all deliberately out of scope for this pass: process enumeration
+     * Stream-based StandardOutput/StandardError -- see getStandardOutputTextProperty). Child
+     * setup and exec failures are reported synchronously by Start() rather than being exposed as
+     * a later exit code 127. The following surfaces are explicitly not implemented, all
+     * deliberately out of scope for this pass: process enumeration
      * (GetProcesses/GetProcessById), memory/CPU/priority/module/thread introspection properties,
      * the Exited/OutputDataReceived/ErrorDataReceived event-based async I/O model, UseShellExecute
      * (Windows-shell-specific), and the .NET 10 Run/RunAsync/RunAndCaptureText helper family.
@@ -54,7 +56,12 @@ namespace System::Diagnostics {
         [[nodiscard]] const ProcessStartInfo& getStartInfoProperty() const;
         void setStartInfoProperty(const ProcessStartInfo& value);
 
-        /** @brief Starts (or restarts) the process using getStartInfoProperty(). @return true if a process resource was started. */
+        /**
+         * @brief Starts (or restarts) the process using getStartInfoProperty().
+         * @return true if a process resource was started.
+         * @throws System::InvalidOperationException if child setup or exec fails; its message
+         * includes the executable name and native error text.
+         */
         bool Start();
 
         /**

modules/diagnostics/src/System/Diagnostics/Process.cpp

@@ -78,6 +78,21 @@ namespace {
         ::close(fd);
     }
 
+    // The child cannot throw back into the parent after fork().  A small status pipe, closed on
+    // successful exec(), lets Start() distinguish an actual launch from the historical
+    // "returned Process which immediately exits 127" failure mode.
+    [[noreturn]] void reportChildStartupFailure(int statusFd, int error) noexcept {
+        while (::write(statusFd, &error, sizeof(error)) < 0 && errno == EINTR) {}
+        ::_exit(127);
+    }
+
+    void closePipe(int fds[2]) noexcept {
+        if (fds[0] >= 0) ::close(fds[0]);
+        if (fds[1] >= 0) ::close(fds[1]);
+        fds[0] = -1;
+        fds[1] = -1;
+    }
+
 }
 
 void Process::reapIfNeeded(Impl& impl) {
@@ -161,6 +176,7 @@ bool Process::Start() {
 
     int stdoutPipe[2] = {-1, -1};
     int stderrPipe[2] = {-1, -1};
+    int startupStatusPipe[2] = {-1, -1};
     bool redirOut = si.getRedirectStandardOutputProperty();
     bool redirErr = si.getRedirectStandardErrorProperty();
     if (redirOut && ::pipe(stdoutPipe) != 0)
@@ -172,31 +188,87 @@ bool Process::Start() {
         if (redirOut) { ::close(stdoutPipe[0]); ::close(stdoutPipe[1]); }
         throw System::InvalidOperationException(std::string("Failed to create stderr pipe: ") + std::strerror(errno));
     }
+    if (::pipe(startupStatusPipe) != 0) {
+        closePipe(stdoutPipe);
+        closePipe(stderrPipe);
+        throw System::InvalidOperationException(
+            std::string("Failed to create process startup status pipe: ") + std::strerror(errno));
+    }
+    int startupStatusFlags = ::fcntl(startupStatusPipe[1], F_GETFD);
+    if (startupStatusFlags < 0 ||
+        ::fcntl(startupStatusPipe[1], F_SETFD, startupStatusFlags | FD_CLOEXEC) != 0) {
+        const int error = errno;
+        closePipe(stdoutPipe);
+        closePipe(stderrPipe);
+        closePipe(startupStatusPipe);
+        throw System::InvalidOperationException(
+            std::string("Failed to configure process startup status pipe: ") + std::strerror(error));
+    }
 
     pid_t pid = ::fork();
     if (pid < 0) {
-        if (redirOut) { ::close(stdoutPipe[0]); ::close(stdoutPipe[1]); }
-        if (redirErr) { ::close(stderrPipe[0]); ::close(stderrPipe[1]); }
+        closePipe(stdoutPipe);
+        closePipe(stderrPipe);
+        closePipe(startupStatusPipe);
         throw System::InvalidOperationException(std::string("Failed to fork: ") + std::strerror(errno));
     }
 
     if (pid == 0) {
+        ::close(startupStatusPipe[0]);
         // Child: put it in its own process group so Kill(entireProcessTree=true) can target the
         // whole tree via killpg without also signaling the parent's group.
         ::setpgid(0, 0);
-        if (redirOut) { ::dup2(stdoutPipe[1], STDOUT_FILENO); ::close(stdoutPipe[0]); ::close(stdoutPipe[1]); }
-        if (redirErr) { ::dup2(stderrPipe[1], STDERR_FILENO); ::close(stderrPipe[0]); ::close(stderrPipe[1]); }
+        if (redirOut) {
+            if (::dup2(stdoutPipe[1], STDOUT_FILENO) < 0)
+                reportChildStartupFailure(startupStatusPipe[1], errno);
+            ::close(stdoutPipe[0]);
+            ::close(stdoutPipe[1]);
+        }
+        if (redirErr) {
+            if (::dup2(stderrPipe[1], STDERR_FILENO) < 0)
+                reportChildStartupFailure(startupStatusPipe[1], errno);
+            ::close(stderrPipe[0]);
+            ::close(stderrPipe[1]);
+        }
         if (!si.getWorkingDirectoryProperty().empty()) {
-            if (::chdir(si.getWorkingDirectoryProperty().c_str()) != 0) ::_exit(127);
+            if (::chdir(si.getWorkingDirectoryProperty().c_str()) != 0)
+                reportChildStartupFailure(startupStatusPipe[1], errno);
         }
         for (const auto& [name, value] : si.getEnvironmentVariablesProperty()) {
-            if (::setenv(name.c_str(), value.c_str(), 1) != 0) ::_exit(127);
+            if (::setenv(name.c_str(), value.c_str(), 1) != 0)
+                reportChildStartupFailure(startupStatusPipe[1], errno);
         }
         ::execvp(argv[0], argv.data());
-        ::_exit(127); // execvp only returns on failure
+        reportChildStartupFailure(startupStatusPipe[1], errno); // execvp only returns on failure
     }
 
     // Parent
+    ::close(startupStatusPipe[1]);
+    startupStatusPipe[1] = -1;
+    int childStartupError = 0;
+    ssize_t statusRead = 0;
+    do {
+        statusRead = ::read(startupStatusPipe[0], &childStartupError, sizeof(childStartupError));
+    } while (statusRead < 0 && errno == EINTR);
+    const int statusReadError = errno;
+    ::close(startupStatusPipe[0]);
+    startupStatusPipe[0] = -1;
+    if (statusRead != 0) {
+        if (statusRead != static_cast<ssize_t>(sizeof(childStartupError))) {
+            ::kill(pid, SIGKILL);
+        }
+        int ignoredStatus = 0;
+        while (::waitpid(pid, &ignoredStatus, 0) < 0 && errno == EINTR) {}
+        closePipe(stdoutPipe);
+        closePipe(stderrPipe);
+        if (statusRead == static_cast<ssize_t>(sizeof(childStartupError))) {
+            throw System::InvalidOperationException(
+                "Failed to start process '" + si.getFileNameProperty() + "': " +
+                std::strerror(childStartupError));
+        }
+        throw System::InvalidOperationException(
+            std::string("Failed to receive process startup status: ") + std::strerror(statusReadError));
+    }
     if (redirOut) {
         ::close(stdoutPipe[1]);
         impl_->stdoutReader = std::thread(drainPipe, stdoutPipe[0], &impl_->stdoutText);

modules/diagnostics/tests/System/Diagnostics/ProcessStartupFailureTests.cpp

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) Robert Vokac and contributors
+
+#include <cerrno>
+#include <cstring>
+#include <string>
+
+#include <gtest/gtest.h>
+
+#include "System/Diagnostics/Process.hpp"
+#include "System/InvalidOperationException.hpp"
+
+using System::Diagnostics::Process;
+using System::Diagnostics::ProcessStartInfo;
+
+namespace {
+
+void expectStartupErrorFor(const ProcessStartInfo& startInfo, const std::string& expectedPath) {
+    try {
+        (void)Process::Start(startInfo);
+        FAIL() << "Process::Start unexpectedly succeeded";
+    } catch (const System::InvalidOperationException& error) {
+        const std::string message = error.getMessageProperty();
+        EXPECT_NE(message.find(expectedPath), std::string::npos);
+        EXPECT_NE(message.find(std::strerror(ENOENT)), std::string::npos);
+    }
+}
+
+} // namespace
+
+TEST(ProcessStartupFailureTest, MissingExecutableThrowsSynchronously) {
+    const std::string missingExecutable = "/definitely-missing-sharp-runtime-process-1764";
+    expectStartupErrorFor(ProcessStartInfo(missingExecutable), missingExecutable);
+}
+
+TEST(ProcessStartupFailureTest, MissingWorkingDirectoryThrowsSynchronously) {
+    const std::string missingDirectory = "/definitely-missing-sharp-runtime-directory-1764";
+    ProcessStartInfo startInfo("/bin/true");
+    startInfo.setWorkingDirectoryProperty(missingDirectory);
+    expectStartupErrorFor(startInfo, "/bin/true");
+}
+
+TEST(ProcessStartupFailureTest, SuccessfulLaunchStillReturnsRunningProcess) {
+    ProcessStartInfo startInfo("/bin/sh");
+    startInfo.getArgumentListProperty().push_back("-c");
+    startInfo.getArgumentListProperty().push_back("printf startup-ok");
+    startInfo.setRedirectStandardOutputProperty(true);
+
+    Process process = Process::Start(startInfo);
+    process.WaitForExit();
+
+    EXPECT_EQ(process.getExitCodeProperty(), 0);
+    EXPECT_EQ(process.getStandardOutputTextProperty(), "startup-ok");
+}

plan.md

@@ -1,7 +1,7 @@
 # Sharp Runtime plan
 
 *Last verified: 2026-07-25 — 41 physical components, 90 direct production
-dependency edges, a clean native build, 12,678 passing tests across 37
+dependency edges, a clean native build, 12,681 passing tests across 37
 executables, and a green ten-job selective matrix.*
 
 Sharp Runtime is in a consumer-driven expansion phase. The original type
@@ -32,7 +32,7 @@ was never created. Neither file should be linked as current documentation.
 ### Code and validation
 
 - Native Linux/GCC build: zero errors and zero warnings.
-- Tests: 12,678 passing across 36 component binaries plus one integration
+- Tests: 12,681 passing across 36 component binaries plus one integration
   binary.
 - Component graph: 41 physical modules and 90 direct production edges.
 - Boundary validator: no cycles, duplicate public include paths, orphan
@@ -52,7 +52,7 @@ The 2026-07-25 local snapshot contains:
 | Table | State |
 |---|---|
 | `task` | 16,201 rows: 1,082 `ported`, 140 `ignore`, 14,979 legacy `ignored`; no unclassified or `tobedecided` rows |
-| `ticket` | 1,763 rows, all `done`; no `todo`, `doing`, `blocked`, or `needs_user` rows |
+| `ticket` | 1,764 rows, all `done`; no `todo`, `doing`, `blocked`, or `needs_user` rows |
 
 Because `plan.sqlite3` is git-ignored, these counts describe the maintainer
 snapshot, not data shipped in a fresh clone.
@@ -154,6 +154,9 @@ assertion without an explicit architecture decision.
 - Added explicit ProcessStartInfo child environment overrides under ticket
   #1763. They are validated before fork, passed only to the child, and retain
   inherited values not explicitly overridden.
+- Added synchronous POSIX Process startup failure reporting under ticket #1764.
+  Child setup and exec errors now reach Start() with the executable name and
+  native error text instead of appearing later as exit code 127.
 - Added consumer-driven coverage across core, collections, IO, networking,
   threading/tasks, text/JSON, XML, numerics, globalization, and cryptographic
   hashing/random APIs.
@@ -214,7 +217,7 @@ The first consumer-driven ports after modularization added:
 - XML schema exception types.
 
 The verified test baseline grew from 12,494 at the modularization checkpoint
-to 12,678.
+to 12,681.
 
 ## Candidate roadmap