From 1058661389b502ee66781f0b833d05d22887a81d Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Tue, 24 Feb 2026 17:36:42 +0100
Subject: [PATCH 01/38] refactor(handlers): refactor prepareOutput to
 prepareOutputAndRunCommand

---
 pkg/router/handlers/execution_handler.go | 37 ++++++++++++++++--------
 1 file changed, 25 insertions(+), 12 deletions(-)

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index ea047cd..d9f2d1d 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -22,6 +22,8 @@ import (
 	"github.com/dkarczmarski/webcmd/pkg/httpx"
 )
 
+var ErrCommandFailed = errors.New("command failed")
+
 // ExecutionHandler returns a WebHandler that executes the command associated with the URLCommand stored in the
 // request context.
 // It builds the command from the configured template and request parameters, prepares the response output,
@@ -52,19 +54,12 @@ func ExecutionHandler(runner cmdrunner.Runner, registry *callgate.Registry) http
 			return err
 		}
 
-		writer, async, err := prepareOutput(responseWriter, cmd.CommandConfig.OutputType)
-		if err != nil {
-			return err
-		}
-
-		return runCommand(
+		return prepareOutputAndRunCommand(
 			request.Context(),
 			runner,
 			registry,
 			cmd,
 			cmdResult,
-			writer,
-			async,
 			responseWriter,
 		)
 	})
@@ -220,19 +215,28 @@ func executeCommand(
 	return handleSyncWait(ctx, runner, cmd, graceTerminationTimeout)
 }
 
-func prepareOutput(responseWriter http.ResponseWriter, outputType string) (io.Writer, bool, error) {
+func prepareOutputAndRunCommand(
+	ctx context.Context,
+	runner cmdrunner.Runner,
+	registry *callgate.Registry,
+	cmd *config.URLCommand,
+	cmdResult *cmdbuilder.Result,
+	responseWriter http.ResponseWriter,
+) error {
 	var (
 		writer io.Writer
 		async  bool
 	)
 
+	outputType := cmd.CommandConfig.OutputType
+
 	switch outputType {
 	case "none":
 		writer = io.Discard
 		async = true
 	case "stream":
 		if _, ok := responseWriter.(http.Flusher); !ok {
-			return nil, false, httpx.NewWebError(
+			return httpx.NewWebError(
 				fmt.Errorf("streaming not supported: %w", ErrBadConfiguration),
 				http.StatusInternalServerError,
 				"",
@@ -250,14 +254,23 @@ func prepareOutput(responseWriter http.ResponseWriter, outputType string) (io.Wr
 
 		responseWriter.Header().Set("Content-Type", "text/plain; charset=utf-8")
 	default:
-		return nil, false, httpx.NewWebError(
+		return httpx.NewWebError(
 			fmt.Errorf("%w: unknown output type %q", ErrBadConfiguration, outputType),
 			http.StatusInternalServerError,
 			"",
 		)
 	}
 
-	return writer, async, nil
+	return runCommand(
+		ctx,
+		runner,
+		registry,
+		cmd,
+		cmdResult,
+		writer,
+		async,
+		responseWriter,
+	)
 }
 
 func extractQueryParams(request *http.Request) map[string]string {

From 872049d8cd906ab6e96e0cd092c0a6251ad2aba8 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 25 Feb 2026 16:41:04 +0100
Subject: [PATCH 02/38] refactor(handlers): prepareOutputAndRunCommand

---
 pkg/router/handlers/execution_handler.go | 97 ++++++++++++++++++------
 1 file changed, 72 insertions(+), 25 deletions(-)

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index d9f2d1d..f680611 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -223,36 +223,15 @@ func prepareOutputAndRunCommand(
 	cmdResult *cmdbuilder.Result,
 	responseWriter http.ResponseWriter,
 ) error {
-	var (
-		writer io.Writer
-		async  bool
-	)
-
 	outputType := cmd.CommandConfig.OutputType
 
 	switch outputType {
 	case "none":
-		writer = io.Discard
-		async = true
+		return prepareOutputAndRunAsyncCommand(ctx, runner, registry, cmd, cmdResult, responseWriter)
 	case "stream":
-		if _, ok := responseWriter.(http.Flusher); !ok {
-			return httpx.NewWebError(
-				fmt.Errorf("streaming not supported: %w", ErrBadConfiguration),
-				http.StatusInternalServerError,
-				"",
-			)
-		}
-
-		writer = newFlushResponseWriter(responseWriter)
-
-		responseWriter.Header().Set("Content-Type", "text/plain; charset=utf-8")
-		responseWriter.Header().Set("Cache-Control", "no-cache")
-		// nginx:
-		responseWriter.Header().Set("X-Accel-Buffering", "no")
+		return prepareOutputAndRunStreamCommand(ctx, runner, registry, cmd, cmdResult, responseWriter)
 	case "", "text":
-		writer = responseWriter
-
-		responseWriter.Header().Set("Content-Type", "text/plain; charset=utf-8")
+		return prepareOutputAndRunSyncCommand(ctx, runner, registry, cmd, cmdResult, responseWriter)
 	default:
 		return httpx.NewWebError(
 			fmt.Errorf("%w: unknown output type %q", ErrBadConfiguration, outputType),
@@ -260,6 +239,74 @@ func prepareOutputAndRunCommand(
 			"",
 		)
 	}
+}
+
+func prepareOutputAndRunAsyncCommand(
+	ctx context.Context,
+	runner cmdrunner.Runner,
+	registry *callgate.Registry,
+	cmd *config.URLCommand,
+	cmdResult *cmdbuilder.Result,
+	responseWriter http.ResponseWriter,
+) error {
+	return runCommand(
+		ctx,
+		runner,
+		registry,
+		cmd,
+		cmdResult,
+		io.Discard,
+		true,
+		responseWriter,
+	)
+}
+
+func prepareOutputAndRunStreamCommand(
+	ctx context.Context,
+	runner cmdrunner.Runner,
+	registry *callgate.Registry,
+	cmd *config.URLCommand,
+	cmdResult *cmdbuilder.Result,
+	responseWriter http.ResponseWriter,
+) error {
+	if _, ok := responseWriter.(http.Flusher); !ok {
+		return httpx.NewWebError(
+			fmt.Errorf("streaming not supported: %w", ErrBadConfiguration),
+			http.StatusInternalServerError,
+			"",
+		)
+	}
+
+	writer := newFlushResponseWriter(responseWriter)
+
+	responseWriter.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	responseWriter.Header().Set("Cache-Control", "no-cache")
+	// nginx:
+	responseWriter.Header().Set("X-Accel-Buffering", "no")
+
+	return runCommand(
+		ctx,
+		runner,
+		registry,
+		cmd,
+		cmdResult,
+		writer,
+		false,
+		responseWriter,
+	)
+}
+
+func prepareOutputAndRunSyncCommand(
+	ctx context.Context,
+	runner cmdrunner.Runner,
+	registry *callgate.Registry,
+	cmd *config.URLCommand,
+	cmdResult *cmdbuilder.Result,
+	responseWriter http.ResponseWriter,
+) error {
+	writer := responseWriter
+
+	responseWriter.Header().Set("Content-Type", "text/plain; charset=utf-8")
 
 	return runCommand(
 		ctx,
@@ -268,7 +315,7 @@ func prepareOutputAndRunCommand(
 		cmd,
 		cmdResult,
 		writer,
-		async,
+		false,
 		responseWriter,
 	)
 }

From 849c0b991a03174313edbf9e818ce760cf5e1acb Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 25 Feb 2026 16:56:09 +0100
Subject: [PATCH 03/38] refactor(handlers): refactor ExecutionHandler to
 translate errors

---
 pkg/router/handlers/execution_handler.go | 59 +++++++++++++++---------
 1 file changed, 36 insertions(+), 23 deletions(-)

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index f680611..dc6d4cd 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -36,33 +36,46 @@ var ErrCommandFailed = errors.New("command failed")
 // response body.
 func ExecutionHandler(runner cmdrunner.Runner, registry *callgate.Registry) httpx.WebHandler { //nolint:ireturn
 	return httpx.WebHandlerFunc(func(responseWriter http.ResponseWriter, request *http.Request) error {
-		rid := requestIDFromContext(request.Context())
-		log.Printf("[INFO] rid=%s Executing command for: %s %s", rid, request.Method, request.URL.Path)
+		return translateError(executionHandler(responseWriter, request, runner, registry))
+	})
+}
 
-		cmd, err := getURLCommandFromContext(request)
-		if err != nil {
-			return httpx.NewWebError(err, http.StatusNotFound, "Command not found")
-		}
+func executionHandler(
+	responseWriter http.ResponseWriter,
+	request *http.Request,
+	runner cmdrunner.Runner,
+	registry *callgate.Registry,
+) error {
+	rid := requestIDFromContext(request.Context())
+	log.Printf("[INFO] rid=%s Executing command for: %s %s", rid, request.Method, request.URL.Path)
 
-		params, err := extractParams(request, cmd)
-		if err != nil {
-			return err
-		}
+	cmd, err := getURLCommandFromContext(request)
+	if err != nil {
+		return httpx.NewWebError(err, http.StatusNotFound, "Command not found")
+	}
 
-		cmdResult, err := buildCommand(cmd.CommandConfig.CommandTemplate, params)
-		if err != nil {
-			return err
-		}
+	params, err := extractParams(request, cmd)
+	if err != nil {
+		return err
+	}
 
-		return prepareOutputAndRunCommand(
-			request.Context(),
-			runner,
-			registry,
-			cmd,
-			cmdResult,
-			responseWriter,
-		)
-	})
+	cmdResult, err := buildCommand(cmd.CommandConfig.CommandTemplate, params)
+	if err != nil {
+		return err
+	}
+
+	return prepareOutputAndRunCommand(
+		request.Context(),
+		runner,
+		registry,
+		cmd,
+		cmdResult,
+		responseWriter,
+	)
+}
+
+func translateError(err error) error {
+	return err
 }
 
 func runCommand(

From acac9984edbce15902e9c6048f9812bf5b3a7a35 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 25 Feb 2026 18:14:17 +0100
Subject: [PATCH 04/38] refactor(handlers): refactor tests to use
 X-Error-Message instead of body string

---
 pkg/router/handlers/execution_handler.go      |  6 +--
 pkg/router/handlers/execution_handler_test.go | 41 ++++++++++++++++---
 2 files changed, 39 insertions(+), 8 deletions(-)

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index dc6d4cd..98f87f3 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -249,7 +249,7 @@ func prepareOutputAndRunCommand(
 		return httpx.NewWebError(
 			fmt.Errorf("%w: unknown output type %q", ErrBadConfiguration, outputType),
 			http.StatusInternalServerError,
-			"",
+			"unknown output type",
 		)
 	}
 }
@@ -286,7 +286,7 @@ func prepareOutputAndRunStreamCommand(
 		return httpx.NewWebError(
 			fmt.Errorf("streaming not supported: %w", ErrBadConfiguration),
 			http.StatusInternalServerError,
-			"",
+			"response writer does not support flushing",
 		)
 	}
 
@@ -377,7 +377,7 @@ func processBodyAsJSON(bodyBytes []byte, params map[string]interface{}) error {
 		return httpx.NewWebError(
 			fmt.Errorf("failed to parse JSON body: %w", err),
 			http.StatusBadRequest,
-			"",
+			"must be a JSON object",
 		)
 	}
 
diff --git a/pkg/router/handlers/execution_handler_test.go b/pkg/router/handlers/execution_handler_test.go
index 017ab6b..0e4c554 100644
--- a/pkg/router/handlers/execution_handler_test.go
+++ b/pkg/router/handlers/execution_handler_test.go
@@ -171,8 +171,9 @@ func TestExecutionHandler_NoCommandInContext(t *testing.T) {
 		t.Errorf("expected status 404, got %d", rr.Code)
 	}
 
-	if !strings.Contains(rr.Body.String(), "Command not found") {
-		t.Errorf("expected body to contain 'Command not found', got %q", rr.Body.String())
+	errMsg := rr.Header().Get("X-Error-Message")
+	if !strings.Contains(errMsg, "Command not found") {
+		t.Errorf("expected X-Error-Message to contain 'Command not found', got %q", errMsg)
 	}
 }
 
@@ -305,6 +306,11 @@ func TestExecutionHandler_ExtractParams_BodyReadError(t *testing.T) {
 	if rr.Code != http.StatusInternalServerError {
 		t.Errorf("expected status 500, got %d", rr.Code)
 	}
+
+	errMsg := rr.Header().Get("X-Error-Message")
+	if !strings.Contains(errMsg, "read error") {
+		t.Errorf("expected X-Error-Message to contain 'read error', got %q", errMsg)
+	}
 }
 
 //nolint:dupl
@@ -438,6 +444,11 @@ func TestExecutionHandler_BodyAsJSON_Invalid(t *testing.T) {
 	if rr.Code != http.StatusBadRequest {
 		t.Errorf("expected status 400, got %d", rr.Code)
 	}
+
+	errMsg := rr.Header().Get("X-Error-Message")
+	if !strings.Contains(errMsg, "must be a JSON object") {
+		t.Errorf("expected X-Error-Message to contain 'must be a JSON object', got %q", errMsg)
+	}
 }
 
 func TestExecutionHandler_BodyAsJSON_NonObject(t *testing.T) {
@@ -485,6 +496,11 @@ func TestExecutionHandler_BodyAsJSON_NonObject(t *testing.T) {
 			if rr.Code != http.StatusBadRequest {
 				t.Errorf("%s: expected status 400, got %d", tc.name, rr.Code)
 			}
+
+			errMsg := rr.Header().Get("X-Error-Message")
+			if !strings.Contains(errMsg, "must be a JSON object") {
+				t.Errorf("%s: expected X-Error-Message to contain 'must be a JSON object', got %q", tc.name, errMsg)
+			}
 		})
 	}
 }
@@ -578,6 +594,11 @@ func TestExecutionHandler_BuildCommand_Error(t *testing.T) {
 			if rr.Code != http.StatusInternalServerError {
 				t.Errorf("%s: expected status 500, got %d", tc.name, rr.Code)
 			}
+
+			errMsg := rr.Header().Get("X-Error-Message")
+			if !strings.Contains(errMsg, "error building command") {
+				t.Errorf("%s: expected X-Error-Message to contain 'error building command', got %q", tc.name, errMsg)
+			}
 		})
 	}
 }
@@ -751,6 +772,11 @@ func TestExecutionHandler_PrepareOutput_Stream_Failure(t *testing.T) {
 	if rr.Code != http.StatusInternalServerError {
 		t.Errorf("expected status 500, got %d", rr.Code)
 	}
+
+	errMsg := rr.Header().Get("X-Error-Message")
+	if !strings.Contains(errMsg, "response writer does not support flushing") {
+		t.Errorf("expected X-Error-Message to contain 'response writer does not support flushing', got %q", errMsg)
+	}
 }
 
 func TestExecutionHandler_PrepareOutput_None(t *testing.T) {
@@ -884,9 +910,9 @@ func TestExecutionHandler_UnknownCallGateMode(t *testing.T) {
 		t.Fatalf("expected non-200 status for invalid callgate mode, got %d, body=%q", rr.Code, rr.Body.String())
 	}
 
-	body := rr.Body.String()
-	if !strings.Contains(body, "callgate registry") {
-		t.Errorf("expected response body to contain %q, got %q", "callgate registry", body)
+	errMsg := rr.Header().Get("X-Error-Message")
+	if !strings.Contains(errMsg, "callgate registry") {
+		t.Errorf("expected X-Error-Message to contain %q, got %q", "callgate registry", errMsg)
 	}
 }
 
@@ -919,6 +945,11 @@ func TestExecutionHandler_PrepareOutput_Unknown(t *testing.T) {
 	if rr.Code != http.StatusInternalServerError {
 		t.Errorf("expected status 500, got %d", rr.Code)
 	}
+
+	errMsg := rr.Header().Get("X-Error-Message")
+	if !strings.Contains(errMsg, "unknown output type") {
+		t.Errorf("expected X-Error-Message to contain 'unknown output type', got %q", errMsg)
+	}
 }
 
 func TestExecutionHandler_ExecuteCommand_StartError_WritesFailedToStart(t *testing.T) {

From cf1f5ca22c8ce59f198a0206e826fb097f00b120 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 25 Feb 2026 18:20:47 +0100
Subject: [PATCH 05/38] refactor(handlers): refactor error handling

---
 pkg/router/handlers/execution_handler.go | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index 98f87f3..fe43a3d 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -75,6 +75,14 @@ func executionHandler(
 }
 
 func translateError(err error) error {
+	if err == nil {
+		return nil
+	}
+
+	if errors.Is(err, callgate.ErrBusy) {
+		return httpx.NewWebError(err, http.StatusTooManyRequests, "Too many requests")
+	}
+
 	return err
 }
 
@@ -111,14 +119,12 @@ func runCommand(
 
 		gate, gateErr := registry.GetOrCreate(groupName, cmd.CallGate.Mode)
 		if gateErr != nil {
-			return httpx.NewWebError(
-				gateErr, http.StatusInternalServerError, fmt.Sprintf("callgate registry: %v", gateErr),
-			)
+			return fmt.Errorf("callgate registry: %w", gateErr)
 		}
 
 		exitCode, err = runWithGate(ctx, action, gate)
-		if err != nil && errors.Is(err, callgate.ErrBusy) {
-			return httpx.NewWebError(err, http.StatusTooManyRequests, "Too many requests")
+		if err != nil {
+			return err
 		}
 	} else {
 		exitCode, err = action(ctx)

From 77810d7f6e5b4e815f68c6a6f5c309fd04df06a4 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 25 Feb 2026 18:39:24 +0100
Subject: [PATCH 06/38] refactor(handlers): refactor logging

---
 pkg/router/handlers/execution_handler.go | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index fe43a3d..a9c8f26 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -99,8 +99,13 @@ func runCommand(
 	rid := requestIDFromContext(ctx)
 
 	action := func(ctx context.Context) (int, error) {
+		command := cmdResult.Command
+		arguments := cmdResult.Arguments
+		rid := requestIDFromContext(ctx)
+		log.Printf("[INFO] rid=%s Executing command: %s %v", rid, command, arguments)
+
 		return executeCommand(
-			ctx, runner, cmdResult.Command, cmdResult.Arguments, writer, async, cmd.GraceTerminationTimeout,
+			ctx, runner, command, arguments, writer, async, cmd.GraceTerminationTimeout,
 		)
 	}
 
@@ -209,9 +214,6 @@ func executeCommand(
 	async bool,
 	graceTerminationTimeout *time.Duration,
 ) (int, error) {
-	rid := requestIDFromContext(ctx)
-	log.Printf("[INFO] rid=%s Executing command: %s %v", rid, command, arguments)
-
 	cmd := runner.Command(command, arguments...)
 
 	//nolint:exhaustruct

From 362cade5b74d2be7ff534af03b54cae432137787 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 25 Feb 2026 18:53:04 +0100
Subject: [PATCH 07/38] refactor(handlers): extract executeCommand logic into
 processrunner package

---
 pkg/processrunner/process_runner.go      | 183 +++++++++++++++++++++++
 pkg/router/handlers/execution_handler.go | 153 ++-----------------
 pkg/router/handlers/handlers.go          |   8 +-
 3 files changed, 198 insertions(+), 146 deletions(-)
 create mode 100644 pkg/processrunner/process_runner.go

diff --git a/pkg/processrunner/process_runner.go b/pkg/processrunner/process_runner.go
new file mode 100644
index 0000000..19a5c95
--- /dev/null
+++ b/pkg/processrunner/process_runner.go
@@ -0,0 +1,183 @@
+package processrunner
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"os/exec"
+	"syscall"
+	"time"
+
+	"github.com/dkarczmarski/webcmd/pkg/cmdrunner"
+)
+
+type contextKey string
+
+const RequestIDKey contextKey = "requestID"
+
+type Process struct {
+	cmd     cmdrunner.Command
+	runner  cmdrunner.Runner
+	timeout *time.Duration
+}
+
+func StartProcess(
+	runner cmdrunner.Runner,
+	command string,
+	args []string,
+	writer io.Writer,
+	graceTimeout *time.Duration,
+) (*Process, error) {
+	cmd := runner.Command(command, args...)
+
+	//nolint:exhaustruct
+	cmd.SetSysProcAttr(&syscall.SysProcAttr{
+		Setpgid: true,
+	})
+	cmd.SetStdout(writer)
+	cmd.SetStderr(writer)
+
+	if err := cmd.Start(); err != nil {
+		return nil, fmt.Errorf("failed to start command: %w", err)
+	}
+
+	return &Process{
+		cmd:     cmd,
+		runner:  runner,
+		timeout: graceTimeout,
+	}, nil
+}
+
+func (p *Process) WaitSync(ctx context.Context) (int, error) {
+	done := make(chan struct{})
+
+	go func() {
+		p.terminateOnContextDone(ctx, done)
+	}()
+
+	err := p.cmd.Wait()
+
+	close(done)
+
+	return p.determineExitCodeAndError(ctx, err)
+}
+
+func (p *Process) WaitAsync(ctx context.Context) {
+	rid := requestIDFromContext(ctx)
+	done := make(chan struct{})
+
+	go func() {
+		log.Printf("[INFO] rid=%s Asynchronously waiting for command to finish", rid)
+
+		waitErr := p.cmd.Wait()
+
+		close(done)
+
+		if waitErr != nil {
+			log.Printf("[ERROR] rid=%s Asynchronous command failed, error: %v", rid, waitErr)
+		} else {
+			log.Printf("[INFO] rid=%s Asynchronous command finished successfully", rid)
+		}
+	}()
+
+	go func() {
+		p.terminateOnContextDone(ctx, done)
+	}()
+}
+
+func (p *Process) terminateOnContextDone(
+	ctx context.Context,
+	done <-chan struct{},
+) {
+	rid := requestIDFromContext(ctx)
+	select {
+	case <-ctx.Done():
+		pid := p.cmd.Pid()
+
+		if p.timeout == nil {
+			log.Printf(
+				"[INFO] rid=%s Context closed, no grace termination timeout set, sending SIGKILL to process group",
+				rid,
+			)
+			p.signalProcessGroup(pid, syscall.SIGKILL)
+
+			return
+		}
+
+		log.Printf("[INFO] rid=%s Context closed, sending SIGTERM to process group", rid)
+		p.signalProcessGroup(pid, syscall.SIGTERM)
+
+		t := time.NewTimer(*p.timeout)
+		defer t.Stop()
+
+		select {
+		case <-t.C:
+			log.Printf("[INFO] rid=%s Process still running after %v, sending SIGKILL to process group",
+				rid, *p.timeout)
+			p.signalProcessGroup(pid, syscall.SIGKILL)
+		case <-done:
+		}
+
+	case <-done:
+	}
+}
+
+func (p *Process) signalProcessGroup(pid int, sig syscall.Signal) {
+	if pid <= 0 {
+		log.Printf("[WARN] Cannot send %s to process group: PID is %d", sig, pid)
+
+		return
+	}
+
+	pgid := -pid
+	if err := p.runner.Kill(pgid, sig); err != nil {
+		log.Printf("[ERROR] Failed to send %s to process group %d: %v", sig, pgid, err)
+	}
+}
+
+func (p *Process) determineExitCodeAndError(ctx context.Context, err error) (int, error) {
+	if err != nil {
+		if p.isTimeoutOrCanceled(ctx) {
+			// Timeout or cancellation takes precedence over other errors as this is intentional.
+			//nolint:wrapcheck
+			return -1, ctx.Err()
+		}
+
+		var exitError *exec.ExitError
+		if errors.As(err, &exitError) {
+			return exitError.ExitCode(), err
+		}
+
+		return -1, err
+	}
+
+	if p.cmd.ProcessState() != nil {
+		return p.cmd.ProcessState().ExitCode(), nil
+	}
+
+	return 0, nil
+}
+
+func (p *Process) isTimeoutOrCanceled(ctx context.Context) bool {
+	return ctx.Err() != nil && (errors.Is(ctx.Err(), context.DeadlineExceeded) || errors.Is(ctx.Err(), context.Canceled))
+}
+
+// requestIDFromContext extracts request ID from context.
+func requestIDFromContext(ctx context.Context) string {
+	if v := ctx.Value(RequestIDKey); v != nil {
+		if rid, ok := v.(string); ok && rid != "" {
+			return rid
+		}
+	}
+
+	// Try with string key for compatibility
+	if v := ctx.Value("requestID"); v != nil {
+		if rid, ok := v.(string); ok && rid != "" {
+			return rid
+		}
+	}
+
+	return "-"
+}
diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index a9c8f26..006c2b3 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -10,9 +10,7 @@ import (
 	"io"
 	"log"
 	"net/http"
-	"os/exec"
 	"strings"
-	"syscall"
 	"time"
 
 	"github.com/dkarczmarski/webcmd/pkg/callgate"
@@ -20,6 +18,7 @@ import (
 	"github.com/dkarczmarski/webcmd/pkg/cmdrunner"
 	"github.com/dkarczmarski/webcmd/pkg/config"
 	"github.com/dkarczmarski/webcmd/pkg/httpx"
+	"github.com/dkarczmarski/webcmd/pkg/processrunner"
 )
 
 var ErrCommandFailed = errors.New("command failed")
@@ -214,26 +213,23 @@ func executeCommand(
 	async bool,
 	graceTerminationTimeout *time.Duration,
 ) (int, error) {
-	cmd := runner.Command(command, arguments...)
-
-	//nolint:exhaustruct
-	cmd.SetSysProcAttr(&syscall.SysProcAttr{
-		Setpgid: true,
-	})
-	cmd.SetStdout(writer)
-	cmd.SetStderr(writer)
-
-	if err := cmd.Start(); err != nil {
-		return -1, fmt.Errorf("failed to start command: %w", err)
+	proc, err := processrunner.StartProcess(runner, command, arguments, writer, graceTerminationTimeout)
+	if err != nil {
+		return -1, fmt.Errorf("failed to start process: %w", err)
 	}
 
 	if async {
-		handleAsyncWait(ctx, runner, cmd, graceTerminationTimeout)
+		proc.WaitAsync(ctx)
 
 		return 0, nil
 	}
 
-	return handleSyncWait(ctx, runner, cmd, graceTerminationTimeout)
+	exitCode, err := proc.WaitSync(ctx)
+	if err != nil {
+		return exitCode, fmt.Errorf("process wait failed: %w", err)
+	}
+
+	return exitCode, nil
 }
 
 func prepareOutputAndRunCommand(
@@ -394,133 +390,6 @@ func processBodyAsJSON(bodyBytes []byte, params map[string]interface{}) error {
 	return nil
 }
 
-func handleSyncWait(
-	ctx context.Context,
-	runner cmdrunner.Runner,
-	cmd cmdrunner.Command,
-	graceTerminationTimeout *time.Duration,
-) (int, error) {
-	done := make(chan struct{})
-
-	go func() {
-		terminateOnContextDone(ctx, runner, done, cmd, graceTerminationTimeout)
-	}()
-
-	err := cmd.Wait()
-
-	close(done)
-
-	return determineExitCodeAndError(ctx, cmd, err)
-}
-
-func handleAsyncWait(
-	ctx context.Context,
-	runner cmdrunner.Runner,
-	cmd cmdrunner.Command,
-	graceTerminationTimeout *time.Duration,
-) {
-	rid := requestIDFromContext(ctx)
-	done := make(chan struct{})
-
-	go func() {
-		log.Printf("[INFO] rid=%s Asynchronously waiting for command to finish", rid)
-
-		waitErr := cmd.Wait()
-
-		close(done)
-
-		if waitErr != nil {
-			log.Printf("[ERROR] rid=%s Asynchronous command failed, error: %v", rid, waitErr)
-		} else {
-			log.Printf("[INFO] rid=%s Asynchronous command finished successfully", rid)
-		}
-	}()
-
-	go func() {
-		terminateOnContextDone(ctx, runner, done, cmd, graceTerminationTimeout)
-	}()
-}
-
-func terminateOnContextDone(
-	ctx context.Context,
-	runner cmdrunner.Runner,
-	done <-chan struct{},
-	cmd cmdrunner.Command,
-	graceTerminationTimeout *time.Duration,
-) {
-	rid := requestIDFromContext(ctx)
-	select {
-	case <-ctx.Done():
-		pid := cmd.Pid()
-
-		if graceTerminationTimeout == nil {
-			log.Printf(
-				"[INFO] rid=%s Context closed, no grace termination timeout set, sending SIGKILL to process group",
-				rid,
-			)
-			signalProcessGroup(runner, pid, syscall.SIGKILL)
-
-			return
-		}
-
-		log.Printf("[INFO] rid=%s Context closed, sending SIGTERM to process group", rid)
-		signalProcessGroup(runner, pid, syscall.SIGTERM)
-
-		t := time.NewTimer(*graceTerminationTimeout)
-		defer t.Stop()
-
-		select {
-		case <-t.C:
-			log.Printf("[INFO] rid=%s Process still running after %v, sending SIGKILL to process group",
-				rid, *graceTerminationTimeout)
-			signalProcessGroup(runner, pid, syscall.SIGKILL)
-		case <-done:
-		}
-
-	case <-done:
-	}
-}
-
-func signalProcessGroup(runner cmdrunner.Runner, pid int, sig syscall.Signal) {
-	if pid <= 0 {
-		log.Printf("[WARN] Cannot send %s to process group: PID is %d", sig, pid)
-
-		return
-	}
-
-	pgid := -pid
-	if err := runner.Kill(pgid, sig); err != nil {
-		log.Printf("[ERROR] Failed to send %s to process group %d: %v", sig, pgid, err)
-	}
-}
-
-func determineExitCodeAndError(ctx context.Context, cmd cmdrunner.Command, err error) (int, error) {
-	if err != nil {
-		if isTimeoutOrCanceled(ctx) {
-			// Timeout or cancellation takes precedence over other errors as this is intentional.
-			//nolint:wrapcheck
-			return -1, ctx.Err()
-		}
-
-		var exitError *exec.ExitError
-		if errors.As(err, &exitError) {
-			return exitError.ExitCode(), err
-		}
-
-		return -1, err
-	}
-
-	if cmd.ProcessState() != nil {
-		return cmd.ProcessState().ExitCode(), nil
-	}
-
-	return 0, nil
-}
-
-func isTimeoutOrCanceled(ctx context.Context) bool {
-	return ctx.Err() != nil && (errors.Is(ctx.Err(), context.DeadlineExceeded) || errors.Is(ctx.Err(), context.Canceled))
-}
-
 func setNestedParam(params map[string]interface{}, parentKey, childKey string, value interface{}) {
 	if _, ok := params[parentKey]; !ok {
 		params[parentKey] = make(map[string]interface{})
diff --git a/pkg/router/handlers/handlers.go b/pkg/router/handlers/handlers.go
index de0954f..16d72a3 100644
--- a/pkg/router/handlers/handlers.go
+++ b/pkg/router/handlers/handlers.go
@@ -20,16 +20,16 @@ var (
 	ErrBadConfiguration      = errors.New("bad configuration")
 )
 
-type contextKey string
+type ContextKey string
 
 // AuthNameKey is the context key used to store and retrieve the authorization name.
-const AuthNameKey contextKey = "authName"
+const AuthNameKey ContextKey = "authName"
 
 // URLCommandKey is the context key used to store and retrieve the URL command.
-const URLCommandKey contextKey = "urlCommand"
+const URLCommandKey ContextKey = "urlCommand"
 
 // RequestIDKey is the context key used to store and retrieve the request ID.
-const RequestIDKey contextKey = "requestID"
+const RequestIDKey ContextKey = "requestID"
 
 // RequestIDMiddleware creates a new Middleware that extracts the request ID from the X-Request-Id header,
 // or generates a new one if not present, and adds it to the request context under RequestIDKey.

From e3c7fdaff04c9bd28103480d6d81d6f3f128f922 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 25 Feb 2026 19:10:33 +0100
Subject: [PATCH 08/38] refactor(processrunner): refactor WaitAsync()

---
 pkg/processrunner/process_runner.go      | 23 +++++++++--------------
 pkg/router/handlers/execution_handler.go | 12 +++++++++++-
 2 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/pkg/processrunner/process_runner.go b/pkg/processrunner/process_runner.go
index 19a5c95..bb6865a 100644
--- a/pkg/processrunner/process_runner.go
+++ b/pkg/processrunner/process_runner.go
@@ -64,27 +64,22 @@ func (p *Process) WaitSync(ctx context.Context) (int, error) {
 	return p.determineExitCodeAndError(ctx, err)
 }
 
-func (p *Process) WaitAsync(ctx context.Context) {
-	rid := requestIDFromContext(ctx)
+func (p *Process) WaitAsync(ctx context.Context) error {
 	done := make(chan struct{})
 
 	go func() {
-		log.Printf("[INFO] rid=%s Asynchronously waiting for command to finish", rid)
-
-		waitErr := p.cmd.Wait()
+		p.terminateOnContextDone(ctx, done)
+	}()
 
+	if err := p.cmd.Wait(); err != nil {
 		close(done)
 
-		if waitErr != nil {
-			log.Printf("[ERROR] rid=%s Asynchronous command failed, error: %v", rid, waitErr)
-		} else {
-			log.Printf("[INFO] rid=%s Asynchronous command finished successfully", rid)
-		}
-	}()
+		return fmt.Errorf("command wait: %w", err)
+	}
 
-	go func() {
-		p.terminateOnContextDone(ctx, done)
-	}()
+	close(done)
+
+	return nil
 }
 
 func (p *Process) terminateOnContextDone(
diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index 006c2b3..c48fca0 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -219,7 +219,17 @@ func executeCommand(
 	}
 
 	if async {
-		proc.WaitAsync(ctx)
+		rid := requestIDFromContext(ctx)
+
+		go func() {
+			log.Printf("[INFO] rid=%s Asynchronously waiting for command to finish", rid)
+
+			if err := proc.WaitAsync(ctx); err != nil {
+				log.Printf("[ERROR] rid=%s Asynchronous command failed, error: %v", rid, err)
+			} else {
+				log.Printf("[INFO] rid=%s Asynchronous command finished successfully", rid)
+			}
+		}()
 
 		return 0, nil
 	}

From 51ac46b885565f4609cd173f6cfa3f040296a8a8 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 25 Feb 2026 20:13:30 +0100
Subject: [PATCH 09/38] refactor(processrunner): refactor WaitAsync()

---
 pkg/processrunner/process_runner.go      | 30 +++++++++++++++++-------
 pkg/router/handlers/execution_handler.go |  9 ++++---
 2 files changed, 27 insertions(+), 12 deletions(-)

diff --git a/pkg/processrunner/process_runner.go b/pkg/processrunner/process_runner.go
index bb6865a..c4f477f 100644
--- a/pkg/processrunner/process_runner.go
+++ b/pkg/processrunner/process_runner.go
@@ -64,22 +64,34 @@ func (p *Process) WaitSync(ctx context.Context) (int, error) {
 	return p.determineExitCodeAndError(ctx, err)
 }
 
-func (p *Process) WaitAsync(ctx context.Context) error {
+type Result struct {
+	ExitCode int
+	Err      error
+}
+
+func (p *Process) WaitAsync(ctx context.Context) <-chan Result {
+	resultCh := make(chan Result, 1)
 	done := make(chan struct{})
 
 	go func() {
-		p.terminateOnContextDone(ctx, done)
-	}()
+		defer close(done)
+		defer close(resultCh)
 
-	if err := p.cmd.Wait(); err != nil {
-		close(done)
+		err := p.cmd.Wait()
 
-		return fmt.Errorf("command wait: %w", err)
-	}
+		exitCode, finalErr := p.determineExitCodeAndError(ctx, err)
 
-	close(done)
+		resultCh <- Result{
+			ExitCode: exitCode,
+			Err:      finalErr,
+		}
+	}()
+
+	go func() {
+		p.terminateOnContextDone(ctx, done)
+	}()
 
-	return nil
+	return resultCh
 }
 
 func (p *Process) terminateOnContextDone(
diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index c48fca0..aedb4fe 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -224,10 +224,13 @@ func executeCommand(
 		go func() {
 			log.Printf("[INFO] rid=%s Asynchronously waiting for command to finish", rid)
 
-			if err := proc.WaitAsync(ctx); err != nil {
-				log.Printf("[ERROR] rid=%s Asynchronous command failed, error: %v", rid, err)
+			result := <-proc.WaitAsync(ctx)
+			if result.Err != nil {
+				log.Printf("[ERROR] rid=%s Asynchronous command failed (exit code: %d), error: %v",
+					rid, result.ExitCode, result.Err)
 			} else {
-				log.Printf("[INFO] rid=%s Asynchronous command finished successfully", rid)
+				log.Printf("[INFO] rid=%s Asynchronous command finished successfully (exit code: %d)",
+					rid, result.ExitCode)
 			}
 		}()
 

From 95646cf2a46fba5a5219e53c6612985cf2d75b9f Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 25 Feb 2026 21:07:56 +0100
Subject: [PATCH 10/38] refactor(handlers): extract runCommand logic into
 gateexec package

---
 pkg/gateexec/gateexec.go                 | 58 ++++++++++++++++++++++
 pkg/router/handlers/execution_handler.go | 63 ++++++++++--------------
 2 files changed, 83 insertions(+), 38 deletions(-)
 create mode 100644 pkg/gateexec/gateexec.go

diff --git a/pkg/gateexec/gateexec.go b/pkg/gateexec/gateexec.go
new file mode 100644
index 0000000..10e2e30
--- /dev/null
+++ b/pkg/gateexec/gateexec.go
@@ -0,0 +1,58 @@
+package gateexec
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/dkarczmarski/webcmd/pkg/callgate"
+	"github.com/dkarczmarski/webcmd/pkg/config"
+)
+
+type Action func(context.Context) (result int, done <-chan struct{}, err error)
+
+type Executor struct {
+	registry *callgate.Registry
+}
+
+func New(registry *callgate.Registry) *Executor {
+	return &Executor{registry: registry}
+}
+
+func (e *Executor) Run(
+	ctx context.Context,
+	gateCfg *config.CallGateConfig,
+	defaultGroup string,
+	action Action,
+) (int, error) {
+	if gateCfg == nil || e.registry == nil {
+		exit, _, err := action(ctx)
+
+		return exit, err
+	}
+
+	group := defaultGroup
+	if gateCfg.GroupName != nil {
+		group = *gateCfg.GroupName
+	}
+
+	gate, err := e.registry.GetOrCreate(group, gateCfg.Mode)
+	if err != nil {
+		return -1, fmt.Errorf("callgate registry: %w", err)
+	}
+
+	release, err := gate.Acquire(ctx)
+	if err != nil {
+		return -1, fmt.Errorf("callgate acquire: %w", err)
+	}
+
+	exit, done, runErr := action(ctx)
+
+	release()
+
+	//nolint:godox
+	// TODO: This channel will be used in the future to keep the gate held until async process finishes.
+	// Currently, the lock is released immediately after StartProcess, which is a known bug for async mode.
+	_ = done
+
+	return exit, runErr
+}
diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index aedb4fe..88dc5de 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -17,6 +17,7 @@ import (
 	"github.com/dkarczmarski/webcmd/pkg/cmdbuilder"
 	"github.com/dkarczmarski/webcmd/pkg/cmdrunner"
 	"github.com/dkarczmarski/webcmd/pkg/config"
+	"github.com/dkarczmarski/webcmd/pkg/gateexec"
 	"github.com/dkarczmarski/webcmd/pkg/httpx"
 	"github.com/dkarczmarski/webcmd/pkg/processrunner"
 )
@@ -97,47 +98,44 @@ func runCommand(
 ) error {
 	rid := requestIDFromContext(ctx)
 
-	action := func(ctx context.Context) (int, error) {
+	exec := gateexec.New(registry)
+
+	action := func(ctx context.Context) (int, <-chan struct{}, error) {
 		command := cmdResult.Command
 		arguments := cmdResult.Arguments
+
 		rid := requestIDFromContext(ctx)
 		log.Printf("[INFO] rid=%s Executing command: %s %v", rid, command, arguments)
 
-		return executeCommand(
-			ctx, runner, command, arguments, writer, async, cmd.GraceTerminationTimeout,
-		)
-	}
+		exit, err := executeCommand(ctx, runner, command, arguments, writer, async, cmd.GraceTerminationTimeout)
 
-	var (
-		exitCode int
-		err      error
-	)
+		//nolint:godox
+		// TODO: Currently we don't have done signaling (because async returns immediately)
+		return exit, nil, err
+	}
 
-	if cmd.CallGate != nil && registry != nil {
-		// Default to the unique endpoint identifier (Verb + Path) if groupName is not explicitly provided.
-		// This ensures that concurrency limits apply per-endpoint by default.
-		groupName := cmd.URL
-		if cmd.CallGate.GroupName != nil {
-			groupName = *cmd.CallGate.GroupName
+	// Default to the unique endpoint identifier (Verb + Path) from cmd.URL if groupName is not explicitly provided.
+	// This ensures that concurrency limits apply per-endpoint by default.
+	exitCode, err := exec.Run(ctx, cmd.CallGate, cmd.URL, action)
+	if err != nil {
+		if errors.Is(err, callgate.ErrBusy) || strings.Contains(err.Error(), "callgate registry") {
+			return translateError(err)
 		}
 
-		gate, gateErr := registry.GetOrCreate(groupName, cmd.CallGate.Mode)
-		if gateErr != nil {
-			return fmt.Errorf("callgate registry: %w", gateErr)
-		}
+		log.Printf("[WARN] rid=%s Command failed with exit code: %d, error: %v", rid, exitCode, err)
 
-		exitCode, err = runWithGate(ctx, action, gate)
-		if err != nil {
-			return err
+		errorMessage := fmt.Sprintf("Command failed with exit code: %d, error: %v", exitCode, err)
+		if _, writeErr := responseWriter.Write([]byte(errorMessage)); writeErr != nil {
+			log.Printf("[ERROR] rid=%s Failed to write error message: %v", rid, writeErr)
 		}
-	} else {
-		exitCode, err = action(ctx)
+
+		return nil
 	}
 
-	if exitCode != 0 || err != nil {
-		log.Printf("[WARN] rid=%s Command failed with exit code: %d, error: %v", rid, exitCode, err)
+	if exitCode != 0 {
+		log.Printf("[WARN] rid=%s Command failed with exit code: %d", rid, exitCode)
 
-		errorMessage := fmt.Sprintf("Command failed with exit code: %d, error: %v", exitCode, err)
+		errorMessage := fmt.Sprintf("Command failed with exit code: %d", exitCode)
 		if _, writeErr := responseWriter.Write([]byte(errorMessage)); writeErr != nil {
 			log.Printf("[ERROR] rid=%s Failed to write error message: %v", rid, writeErr)
 		}
@@ -412,14 +410,3 @@ func setNestedParam(params map[string]interface{}, parentKey, childKey string, v
 		parentMap[childKey] = value
 	}
 }
-
-func runWithGate(ctx context.Context, action func(context.Context) (int, error), gate callgate.CallGate) (int, error) {
-	release, err := gate.Acquire(ctx)
-	if err != nil {
-		return -1, fmt.Errorf("callgate acquire: %w", err)
-	}
-
-	defer release()
-
-	return action(ctx)
-}

From 78c1b3e2f48bab3c543c65b5db76d881200956b9 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 25 Feb 2026 21:14:51 +0100
Subject: [PATCH 11/38] refactor(gateexec): refactor error handling

---
 pkg/gateexec/gateexec.go                      | 10 ++++++++--
 pkg/router/handlers/execution_handler.go      |  6 +++++-
 pkg/router/handlers/execution_handler_test.go |  8 ++++----
 3 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/pkg/gateexec/gateexec.go b/pkg/gateexec/gateexec.go
index 10e2e30..4913f01 100644
--- a/pkg/gateexec/gateexec.go
+++ b/pkg/gateexec/gateexec.go
@@ -2,12 +2,18 @@ package gateexec
 
 import (
 	"context"
+	"errors"
 	"fmt"
 
 	"github.com/dkarczmarski/webcmd/pkg/callgate"
 	"github.com/dkarczmarski/webcmd/pkg/config"
 )
 
+var (
+	ErrRegistry = errors.New("gate executor: registry error")
+	ErrAcquire  = errors.New("gate executor: acquire error")
+)
+
 type Action func(context.Context) (result int, done <-chan struct{}, err error)
 
 type Executor struct {
@@ -37,12 +43,12 @@ func (e *Executor) Run(
 
 	gate, err := e.registry.GetOrCreate(group, gateCfg.Mode)
 	if err != nil {
-		return -1, fmt.Errorf("callgate registry: %w", err)
+		return -1, fmt.Errorf("%w: %w", ErrRegistry, err)
 	}
 
 	release, err := gate.Acquire(ctx)
 	if err != nil {
-		return -1, fmt.Errorf("callgate acquire: %w", err)
+		return -1, fmt.Errorf("%w: %w", ErrAcquire, err)
 	}
 
 	exit, done, runErr := action(ctx)
diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index 88dc5de..2a851d4 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -83,6 +83,10 @@ func translateError(err error) error {
 		return httpx.NewWebError(err, http.StatusTooManyRequests, "Too many requests")
 	}
 
+	if errors.Is(err, gateexec.ErrRegistry) {
+		return httpx.NewWebError(err, http.StatusInternalServerError, "Invalid callgate configuration")
+	}
+
 	return err
 }
 
@@ -118,7 +122,7 @@ func runCommand(
 	// This ensures that concurrency limits apply per-endpoint by default.
 	exitCode, err := exec.Run(ctx, cmd.CallGate, cmd.URL, action)
 	if err != nil {
-		if errors.Is(err, callgate.ErrBusy) || strings.Contains(err.Error(), "callgate registry") {
+		if errors.Is(err, callgate.ErrBusy) || errors.Is(err, gateexec.ErrRegistry) || errors.Is(err, gateexec.ErrAcquire) {
 			return translateError(err)
 		}
 
diff --git a/pkg/router/handlers/execution_handler_test.go b/pkg/router/handlers/execution_handler_test.go
index 0e4c554..6a4aff9 100644
--- a/pkg/router/handlers/execution_handler_test.go
+++ b/pkg/router/handlers/execution_handler_test.go
@@ -906,13 +906,13 @@ func TestExecutionHandler_UnknownCallGateMode(t *testing.T) {
 	rr := httptest.NewRecorder()
 	h.ServeHTTP(rr, req)
 
-	if rr.Code == http.StatusOK {
-		t.Fatalf("expected non-200 status for invalid callgate mode, got %d, body=%q", rr.Code, rr.Body.String())
+	if rr.Code != http.StatusInternalServerError {
+		t.Errorf("expected status 500 for invalid callgate mode, got %d, body=%q", rr.Code, rr.Body.String())
 	}
 
 	errMsg := rr.Header().Get("X-Error-Message")
-	if !strings.Contains(errMsg, "callgate registry") {
-		t.Errorf("expected X-Error-Message to contain %q, got %q", "callgate registry", errMsg)
+	if !strings.Contains(errMsg, "Invalid callgate configuration") {
+		t.Errorf("expected X-Error-Message to contain %q, got %q", "Invalid callgate configuration", errMsg)
 	}
 }
 

From 91189cdef84210e0ea42dfb0091086cfdc038ae1 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 25 Feb 2026 21:34:14 +0100
Subject: [PATCH 12/38] fix(gateexec): release lock after process completion in
 async mode

---
 pkg/gateexec/gateexec.go | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/pkg/gateexec/gateexec.go b/pkg/gateexec/gateexec.go
index 4913f01..ebace16 100644
--- a/pkg/gateexec/gateexec.go
+++ b/pkg/gateexec/gateexec.go
@@ -53,12 +53,14 @@ func (e *Executor) Run(
 
 	exit, done, runErr := action(ctx)
 
-	release()
-
-	//nolint:godox
-	// TODO: This channel will be used in the future to keep the gate held until async process finishes.
-	// Currently, the lock is released immediately after StartProcess, which is a known bug for async mode.
-	_ = done
+	if done != nil {
+		go func() {
+			<-done
+			release()
+		}()
+	} else {
+		release()
+	}
 
 	return exit, runErr
 }

From 9aa4acea9cb2bc08f5257c0e80c4846960354c83 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 25 Feb 2026 21:50:06 +0100
Subject: [PATCH 13/38] fix(handlers): release lock after process completion in
 async mode

---
 pkg/router/handlers/execution_handler.go | 118 ++++++++++++-----------
 1 file changed, 63 insertions(+), 55 deletions(-)

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index 2a851d4..e50b22e 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -111,16 +111,50 @@ func runCommand(
 		rid := requestIDFromContext(ctx)
 		log.Printf("[INFO] rid=%s Executing command: %s %v", rid, command, arguments)
 
-		exit, err := executeCommand(ctx, runner, command, arguments, writer, async, cmd.GraceTerminationTimeout)
+		proc, err := startCommandProcess(runner, command, arguments, writer, cmd.GraceTerminationTimeout)
+		if err != nil {
+			return -1, nil, err
+		}
+
+		if async {
+			return 0, waitAsyncAndLog(ctx, proc, rid), nil
+		}
 
-		//nolint:godox
-		// TODO: Currently we don't have done signaling (because async returns immediately)
-		return exit, nil, err
+		exitCode, err := proc.WaitSync(ctx)
+		if err != nil {
+			return exitCode, nil, fmt.Errorf("process wait failed: %w", err)
+		}
+
+		return exitCode, nil, nil
 	}
 
-	// Default to the unique endpoint identifier (Verb + Path) from cmd.URL if groupName is not explicitly provided.
-	// This ensures that concurrency limits apply per-endpoint by default.
 	exitCode, err := exec.Run(ctx, cmd.CallGate, cmd.URL, action)
+
+	return handleCommandResult(rid, exitCode, err, responseWriter)
+}
+
+func waitAsyncAndLog(ctx context.Context, proc *processrunner.Process, rid string) <-chan struct{} {
+	resCh := proc.WaitAsync(ctx)
+
+	done := make(chan struct{})
+
+	go func() {
+		defer close(done)
+
+		result := <-resCh
+		if result.Err != nil {
+			log.Printf("[ERROR] rid=%s Asynchronous command failed (exit code: %d), error: %v",
+				rid, result.ExitCode, result.Err)
+		} else {
+			log.Printf("[INFO] rid=%s Asynchronous command finished successfully (exit code: %d)",
+				rid, result.ExitCode)
+		}
+	}()
+
+	return done
+}
+
+func handleCommandResult(rid string, exitCode int, err error, responseWriter http.ResponseWriter) error {
 	if err != nil {
 		if errors.Is(err, callgate.ErrBusy) || errors.Is(err, gateexec.ErrRegistry) || errors.Is(err, gateexec.ErrAcquire) {
 			return translateError(err)
@@ -128,10 +162,7 @@ func runCommand(
 
 		log.Printf("[WARN] rid=%s Command failed with exit code: %d, error: %v", rid, exitCode, err)
 
-		errorMessage := fmt.Sprintf("Command failed with exit code: %d, error: %v", exitCode, err)
-		if _, writeErr := responseWriter.Write([]byte(errorMessage)); writeErr != nil {
-			log.Printf("[ERROR] rid=%s Failed to write error message: %v", rid, writeErr)
-		}
+		writeErrorMessage(rid, responseWriter, fmt.Sprintf("Command failed with exit code: %d, error: %v", exitCode, err))
 
 		return nil
 	}
@@ -139,15 +170,33 @@ func runCommand(
 	if exitCode != 0 {
 		log.Printf("[WARN] rid=%s Command failed with exit code: %d", rid, exitCode)
 
-		errorMessage := fmt.Sprintf("Command failed with exit code: %d", exitCode)
-		if _, writeErr := responseWriter.Write([]byte(errorMessage)); writeErr != nil {
-			log.Printf("[ERROR] rid=%s Failed to write error message: %v", rid, writeErr)
-		}
+		writeErrorMessage(rid, responseWriter, fmt.Sprintf("Command failed with exit code: %d", exitCode))
 	}
 
 	return nil
 }
 
+func writeErrorMessage(rid string, responseWriter http.ResponseWriter, message string) {
+	if _, writeErr := responseWriter.Write([]byte(message)); writeErr != nil {
+		log.Printf("[ERROR] rid=%s Failed to write error message: %v", rid, writeErr)
+	}
+}
+
+func startCommandProcess(
+	runner cmdrunner.Runner,
+	command string,
+	arguments []string,
+	writer io.Writer,
+	graceTerminationTimeout *time.Duration,
+) (*processrunner.Process, error) {
+	proc, err := processrunner.StartProcess(runner, command, arguments, writer, graceTerminationTimeout)
+	if err != nil {
+		return nil, fmt.Errorf("failed to start process: %w", err)
+	}
+
+	return proc, nil
+}
+
 func getURLCommandFromContext(request *http.Request) (*config.URLCommand, error) {
 	valCmd := request.Context().Value(URLCommandKey)
 	if valCmd == nil {
@@ -206,47 +255,6 @@ func buildCommand(
 	return &cmdResult, nil
 }
 
-func executeCommand(
-	ctx context.Context,
-	runner cmdrunner.Runner,
-	command string,
-	arguments []string,
-	writer io.Writer,
-	async bool,
-	graceTerminationTimeout *time.Duration,
-) (int, error) {
-	proc, err := processrunner.StartProcess(runner, command, arguments, writer, graceTerminationTimeout)
-	if err != nil {
-		return -1, fmt.Errorf("failed to start process: %w", err)
-	}
-
-	if async {
-		rid := requestIDFromContext(ctx)
-
-		go func() {
-			log.Printf("[INFO] rid=%s Asynchronously waiting for command to finish", rid)
-
-			result := <-proc.WaitAsync(ctx)
-			if result.Err != nil {
-				log.Printf("[ERROR] rid=%s Asynchronous command failed (exit code: %d), error: %v",
-					rid, result.ExitCode, result.Err)
-			} else {
-				log.Printf("[INFO] rid=%s Asynchronous command finished successfully (exit code: %d)",
-					rid, result.ExitCode)
-			}
-		}()
-
-		return 0, nil
-	}
-
-	exitCode, err := proc.WaitSync(ctx)
-	if err != nil {
-		return exitCode, fmt.Errorf("process wait failed: %w", err)
-	}
-
-	return exitCode, nil
-}
-
 func prepareOutputAndRunCommand(
 	ctx context.Context,
 	runner cmdrunner.Runner,

From 480ac26aed4e3106f0d2ed77bbd808fbf0d17783 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 25 Feb 2026 22:13:34 +0100
Subject: [PATCH 14/38] refactor(processrunner): remove logging and request ID
 handling

---
 pkg/processrunner/process_runner.go | 63 +++++++++--------------------
 1 file changed, 19 insertions(+), 44 deletions(-)

diff --git a/pkg/processrunner/process_runner.go b/pkg/processrunner/process_runner.go
index c4f477f..518f184 100644
--- a/pkg/processrunner/process_runner.go
+++ b/pkg/processrunner/process_runner.go
@@ -1,3 +1,6 @@
+// Package processrunner provides process lifecycle management:
+// start process in its own process group, wait synchronously/asynchronously,
+// and terminate the process group on context cancellation with optional grace timeout.
 package processrunner
 
 import (
@@ -5,7 +8,6 @@ import (
 	"errors"
 	"fmt"
 	"io"
-	"log"
 	"os/exec"
 	"syscall"
 	"time"
@@ -13,9 +15,11 @@ import (
 	"github.com/dkarczmarski/webcmd/pkg/cmdrunner"
 )
 
-type contextKey string
-
-const RequestIDKey contextKey = "requestID"
+var (
+	ErrStartCommand       = errors.New("failed to start command")
+	ErrInvalidPID         = errors.New("invalid PID")
+	ErrProcessGroupSignal = errors.New("failed to send signal to process group")
+)
 
 type Process struct {
 	cmd     cmdrunner.Command
@@ -40,7 +44,7 @@ func StartProcess(
 	cmd.SetStderr(writer)
 
 	if err := cmd.Start(); err != nil {
-		return nil, fmt.Errorf("failed to start command: %w", err)
+		return nil, fmt.Errorf("%w: %w", ErrStartCommand, err)
 	}
 
 	return &Process{
@@ -69,6 +73,7 @@ type Result struct {
 	Err      error
 }
 
+// WaitAsync starts waiting in background and returns a channel that receives exactly one Result.
 func (p *Process) WaitAsync(ctx context.Context) <-chan Result {
 	resultCh := make(chan Result, 1)
 	done := make(chan struct{})
@@ -78,7 +83,6 @@ func (p *Process) WaitAsync(ctx context.Context) <-chan Result {
 		defer close(resultCh)
 
 		err := p.cmd.Wait()
-
 		exitCode, finalErr := p.determineExitCodeAndError(ctx, err)
 
 		resultCh <- Result{
@@ -94,36 +98,25 @@ func (p *Process) WaitAsync(ctx context.Context) <-chan Result {
 	return resultCh
 }
 
-func (p *Process) terminateOnContextDone(
-	ctx context.Context,
-	done <-chan struct{},
-) {
-	rid := requestIDFromContext(ctx)
+func (p *Process) terminateOnContextDone(ctx context.Context, done <-chan struct{}) {
 	select {
 	case <-ctx.Done():
 		pid := p.cmd.Pid()
 
 		if p.timeout == nil {
-			log.Printf(
-				"[INFO] rid=%s Context closed, no grace termination timeout set, sending SIGKILL to process group",
-				rid,
-			)
-			p.signalProcessGroup(pid, syscall.SIGKILL)
+			_ = p.signalProcessGroup(pid, syscall.SIGKILL)
 
 			return
 		}
 
-		log.Printf("[INFO] rid=%s Context closed, sending SIGTERM to process group", rid)
-		p.signalProcessGroup(pid, syscall.SIGTERM)
+		_ = p.signalProcessGroup(pid, syscall.SIGTERM)
 
 		t := time.NewTimer(*p.timeout)
 		defer t.Stop()
 
 		select {
 		case <-t.C:
-			log.Printf("[INFO] rid=%s Process still running after %v, sending SIGKILL to process group",
-				rid, *p.timeout)
-			p.signalProcessGroup(pid, syscall.SIGKILL)
+			_ = p.signalProcessGroup(pid, syscall.SIGKILL)
 		case <-done:
 		}
 
@@ -131,17 +124,17 @@ func (p *Process) terminateOnContextDone(
 	}
 }
 
-func (p *Process) signalProcessGroup(pid int, sig syscall.Signal) {
+func (p *Process) signalProcessGroup(pid int, sig syscall.Signal) error {
 	if pid <= 0 {
-		log.Printf("[WARN] Cannot send %s to process group: PID is %d", sig, pid)
-
-		return
+		return fmt.Errorf("cannot send %s to process group: pid=%d: %w", sig, pid, ErrInvalidPID)
 	}
 
 	pgid := -pid
 	if err := p.runner.Kill(pgid, sig); err != nil {
-		log.Printf("[ERROR] Failed to send %s to process group %d: %v", sig, pgid, err)
+		return fmt.Errorf("failed to send %s to process group %d: %w: %w", sig, pgid, err, ErrProcessGroupSignal)
 	}
+
+	return nil
 }
 
 func (p *Process) determineExitCodeAndError(ctx context.Context, err error) (int, error) {
@@ -170,21 +163,3 @@ func (p *Process) determineExitCodeAndError(ctx context.Context, err error) (int
 func (p *Process) isTimeoutOrCanceled(ctx context.Context) bool {
 	return ctx.Err() != nil && (errors.Is(ctx.Err(), context.DeadlineExceeded) || errors.Is(ctx.Err(), context.Canceled))
 }
-
-// requestIDFromContext extracts request ID from context.
-func requestIDFromContext(ctx context.Context) string {
-	if v := ctx.Value(RequestIDKey); v != nil {
-		if rid, ok := v.(string); ok && rid != "" {
-			return rid
-		}
-	}
-
-	// Try with string key for compatibility
-	if v := ctx.Value("requestID"); v != nil {
-		if rid, ok := v.(string); ok && rid != "" {
-			return rid
-		}
-	}
-
-	return "-"
-}

From b076e52291b2c37a28fc3d4512adba23b5eff83a Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 25 Feb 2026 22:29:39 +0100
Subject: [PATCH 15/38] feat(processrunner): treat non-zero exit codes as
 normal process completion

---
 pkg/processrunner/process_runner.go           | 45 +++++++++++++------
 pkg/router/handlers/execution_handler_test.go |  4 --
 2 files changed, 32 insertions(+), 17 deletions(-)

diff --git a/pkg/processrunner/process_runner.go b/pkg/processrunner/process_runner.go
index 518f184..e17d7e2 100644
--- a/pkg/processrunner/process_runner.go
+++ b/pkg/processrunner/process_runner.go
@@ -138,26 +138,45 @@ func (p *Process) signalProcessGroup(pid int, sig syscall.Signal) error {
 }
 
 func (p *Process) determineExitCodeAndError(ctx context.Context, err error) (int, error) {
-	if err != nil {
-		if p.isTimeoutOrCanceled(ctx) {
-			// Timeout or cancellation takes precedence over other errors as this is intentional.
-			//nolint:wrapcheck
-			return -1, ctx.Err()
-		}
+	// If the context was canceled or timed out,
+	// it means the process was terminated externally.
+	if p.isTimeoutOrCanceled(ctx) {
+		// Return -1 and the context error.
+		//nolint:wrapcheck
+		return -1, ctx.Err()
+	}
 
-		var exitError *exec.ExitError
-		if errors.As(err, &exitError) {
-			return exitError.ExitCode(), err
+	// If Wait() returned no error,
+	// the process exited normally (exit code available in ProcessState).
+	if err == nil {
+		if ps := p.cmd.ProcessState(); ps != nil {
+			return ps.ExitCode(), nil
 		}
 
-		return -1, err
+		// This should not normally happen after Wait(),
+		// but return 0 as a safe default.
+		return 0, nil
 	}
 
-	if p.cmd.ProcessState() != nil {
-		return p.cmd.ProcessState().ExitCode(), nil
+	// If the error is *exec.ExitError,
+	// the process exited by itself (possibly with non-zero exit code)
+	// OR it was terminated by a signal.
+	var exitErr *exec.ExitError
+	if errors.As(err, &exitErr) {
+		// On Unix systems, we can check the WaitStatus.
+		// If the process was terminated by a signal,
+		// it means external intervention (SIGTERM/SIGKILL).
+		if status, ok := exitErr.Sys().(syscall.WaitStatus); ok && status.Signaled() {
+			return -1, err
+		}
+
+		// Otherwise, the process exited normally (even if exit code != 0).
+		// In this case, exit code is a valid result and error is nil.
+		return exitErr.ExitCode(), nil
 	}
 
-	return 0, nil
+	// Any other error from Wait() is treated as an external/infrastructure error.
+	return -1, err
 }
 
 func (p *Process) isTimeoutOrCanceled(ctx context.Context) bool {
diff --git a/pkg/router/handlers/execution_handler_test.go b/pkg/router/handlers/execution_handler_test.go
index 6a4aff9..8e4dbeb 100644
--- a/pkg/router/handlers/execution_handler_test.go
+++ b/pkg/router/handlers/execution_handler_test.go
@@ -1775,10 +1775,6 @@ func TestExecutionHandler_RunCommand_AppendsErrorMessageToBody_OnNonZeroExit(t *
 	if !strings.Contains(body, "Command failed with exit code: 7") {
 		t.Errorf("expected body to contain exit code 7 failure message, got %q", body)
 	}
-
-	if !strings.Contains(body, "error:") {
-		t.Errorf("expected body to contain 'error:' part, got %q", body)
-	}
 }
 
 type erroringResponseWriter struct {

From 69356bfe412a22facc0714588ad441b7570a725a Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Fri, 27 Feb 2026 17:26:35 +0100
Subject: [PATCH 16/38] fix(handlers): fix context cancellation in async mode

---
 pkg/router/handlers/execution_handler.go | 27 +++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index e50b22e..a335f80 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -117,7 +117,15 @@ func runCommand(
 		}
 
 		if async {
-			return 0, waitAsyncAndLog(ctx, proc, rid), nil
+			asyncCtx := context.WithoutCancel(ctx)
+
+			var cancel context.CancelFunc = func() {}
+
+			if cmd.CommandConfig.Timeout != nil {
+				asyncCtx, cancel = context.WithTimeout(asyncCtx, *cmd.CommandConfig.Timeout)
+			}
+
+			return 0, waitAsyncAndLog(asyncCtx, proc, cancel), nil
 		}
 
 		exitCode, err := proc.WaitSync(ctx)
@@ -133,22 +141,31 @@ func runCommand(
 	return handleCommandResult(rid, exitCode, err, responseWriter)
 }
 
-func waitAsyncAndLog(ctx context.Context, proc *processrunner.Process, rid string) <-chan struct{} {
+func waitAsyncAndLog(
+	ctx context.Context,
+	proc *processrunner.Process,
+	cancel context.CancelFunc,
+) <-chan struct{} {
 	resCh := proc.WaitAsync(ctx)
 
 	done := make(chan struct{})
 
 	go func() {
 		defer close(done)
+		defer cancel()
+
+		rid := requestIDFromContext(ctx)
 
 		result := <-resCh
 		if result.Err != nil {
 			log.Printf("[ERROR] rid=%s Asynchronous command failed (exit code: %d), error: %v",
 				rid, result.ExitCode, result.Err)
-		} else {
-			log.Printf("[INFO] rid=%s Asynchronous command finished successfully (exit code: %d)",
-				rid, result.ExitCode)
+
+			return
 		}
+
+		log.Printf("[INFO] rid=%s Asynchronous command finished successfully (exit code: %d)",
+			rid, result.ExitCode)
 	}()
 
 	return done

From 3a2dbf2176465945013d8a9094d4592b8c32ac4e Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Fri, 27 Feb 2026 19:30:11 +0100
Subject: [PATCH 17/38] refactor(handlers): simplify error handling

---
 pkg/router/handlers/execution_handler.go | 42 +++++++++++-------------
 1 file changed, 19 insertions(+), 23 deletions(-)

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index a335f80..14b3fe3 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -22,7 +22,11 @@ import (
 	"github.com/dkarczmarski/webcmd/pkg/processrunner"
 )
 
-var ErrCommandFailed = errors.New("command failed")
+var (
+	ErrCommandFailed   = errors.New("command failed")
+	ErrCommandNotFound = errors.New("command not found")
+	ErrInvalidJSONBody = errors.New("invalid JSON body")
+)
 
 // ExecutionHandler returns a WebHandler that executes the command associated with the URLCommand stored in the
 // request context.
@@ -51,7 +55,7 @@ func executionHandler(
 
 	cmd, err := getURLCommandFromContext(request)
 	if err != nil {
-		return httpx.NewWebError(err, http.StatusNotFound, "Command not found")
+		return err
 	}
 
 	params, err := extractParams(request, cmd)
@@ -87,6 +91,14 @@ func translateError(err error) error {
 		return httpx.NewWebError(err, http.StatusInternalServerError, "Invalid callgate configuration")
 	}
 
+	if errors.Is(err, ErrCommandNotFound) {
+		return httpx.NewWebError(err, http.StatusNotFound, "Command not found")
+	}
+
+	if errors.Is(err, ErrInvalidJSONBody) {
+		return httpx.NewWebError(err, http.StatusBadRequest, "must be a JSON object")
+	}
+
 	return err
 }
 
@@ -217,7 +229,7 @@ func startCommandProcess(
 func getURLCommandFromContext(request *http.Request) (*config.URLCommand, error) {
 	valCmd := request.Context().Value(URLCommandKey)
 	if valCmd == nil {
-		return nil, fmt.Errorf("URLCommand not found in context: %w", ErrInvalidRequestContext)
+		return nil, fmt.Errorf("URLCommand not found in context: %w", ErrCommandNotFound)
 	}
 
 	cmd, ok := valCmd.(*config.URLCommand)
@@ -238,11 +250,7 @@ func extractParams(request *http.Request, cmd *config.URLCommand) (map[string]in
 
 	bodyBytes, err := io.ReadAll(request.Body)
 	if err != nil {
-		return nil, httpx.NewWebError(
-			fmt.Errorf("failed to read request body: %w", err),
-			http.StatusInternalServerError,
-			"",
-		)
+		return nil, fmt.Errorf("failed to read request body: %w", err)
 	}
 
 	setNestedParam(params, "body", "text", string(bodyBytes))
@@ -262,11 +270,7 @@ func buildCommand(
 ) (*cmdbuilder.Result, error) {
 	cmdResult, err := cmdbuilder.BuildCommand(template, params)
 	if err != nil {
-		return nil, httpx.NewWebError(
-			fmt.Errorf("error building command: %w", err),
-			http.StatusInternalServerError,
-			"",
-		)
+		return nil, fmt.Errorf("error building command: %w", err)
 	}
 
 	return &cmdResult, nil
@@ -290,11 +294,7 @@ func prepareOutputAndRunCommand(
 	case "", "text":
 		return prepareOutputAndRunSyncCommand(ctx, runner, registry, cmd, cmdResult, responseWriter)
 	default:
-		return httpx.NewWebError(
-			fmt.Errorf("%w: unknown output type %q", ErrBadConfiguration, outputType),
-			http.StatusInternalServerError,
-			"unknown output type",
-		)
+		return fmt.Errorf("%w: unknown output type %q", ErrBadConfiguration, outputType)
 	}
 }
 
@@ -418,11 +418,7 @@ func (j JSONBody) String() string {
 func processBodyAsJSON(bodyBytes []byte, params map[string]interface{}) error {
 	var bodyJSON JSONBody
 	if err := json.Unmarshal(bodyBytes, &bodyJSON); err != nil {
-		return httpx.NewWebError(
-			fmt.Errorf("failed to parse JSON body: %w", err),
-			http.StatusBadRequest,
-			"must be a JSON object",
-		)
+		return fmt.Errorf("%w: failed to parse JSON body: %w", ErrInvalidJSONBody, err)
 	}
 
 	setNestedParam(params, "body", "json", bodyJSON)

From f6950272d61c5e5ffd124402b6827cb57715404e Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Fri, 27 Feb 2026 20:19:32 +0100
Subject: [PATCH 18/38] refactor(handlers): extract createGateAction from
 runCommand

---
 pkg/router/handlers/execution_handler.go | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index 14b3fe3..0832f23 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -113,10 +113,22 @@ func runCommand(
 	responseWriter http.ResponseWriter,
 ) error {
 	rid := requestIDFromContext(ctx)
-
 	exec := gateexec.New(registry)
+	action := createGateAction(runner, cmd, cmdResult, writer, async)
+
+	exitCode, err := exec.Run(ctx, cmd.CallGate, cmd.URL, action)
+
+	return handleCommandResult(rid, exitCode, err, responseWriter)
+}
 
-	action := func(ctx context.Context) (int, <-chan struct{}, error) {
+func createGateAction(
+	runner cmdrunner.Runner,
+	cmd *config.URLCommand,
+	cmdResult *cmdbuilder.Result,
+	writer io.Writer,
+	async bool,
+) gateexec.Action {
+	return func(ctx context.Context) (int, <-chan struct{}, error) {
 		command := cmdResult.Command
 		arguments := cmdResult.Arguments
 
@@ -147,10 +159,6 @@ func runCommand(
 
 		return exitCode, nil, nil
 	}
-
-	exitCode, err := exec.Run(ctx, cmd.CallGate, cmd.URL, action)
-
-	return handleCommandResult(rid, exitCode, err, responseWriter)
 }
 
 func waitAsyncAndLog(

From a5017c0b9eb2232c558111b8beabe9226ddb5c1d Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Fri, 27 Feb 2026 23:30:59 +0100
Subject: [PATCH 19/38] feat(handlers): add command execution status headers to
 response

---
 pkg/router/handlers/execution_handler.go      | 93 ++++++++++---------
 pkg/router/handlers/execution_handler_test.go | 65 +++++++------
 test/integration/server_test.go               | 22 +++--
 3 files changed, 97 insertions(+), 83 deletions(-)

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index 0832f23..b1d876b 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -3,6 +3,7 @@ package handlers
 //go:generate go run go.uber.org/mock/mockgen -typed -destination=./internal/mocks/mock_cmdrunner.go -package=mocks github.com/dkarczmarski/webcmd/pkg/cmdrunner Runner,Command
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
@@ -10,6 +11,7 @@ import (
 	"io"
 	"log"
 	"net/http"
+	"strconv"
 	"strings"
 	"time"
 
@@ -23,9 +25,9 @@ import (
 )
 
 var (
-	ErrCommandFailed   = errors.New("command failed")
-	ErrCommandNotFound = errors.New("command not found")
-	ErrInvalidJSONBody = errors.New("invalid JSON body")
+	ErrStreamingNotSupported = errors.New("streaming not supported")
+	ErrCommandNotFound       = errors.New("command not found")
+	ErrInvalidJSONBody       = errors.New("invalid JSON body")
 )
 
 // ExecutionHandler returns a WebHandler that executes the command associated with the URLCommand stored in the
@@ -40,7 +42,12 @@ var (
 // response body.
 func ExecutionHandler(runner cmdrunner.Runner, registry *callgate.Registry) httpx.WebHandler { //nolint:ireturn
 	return httpx.WebHandlerFunc(func(responseWriter http.ResponseWriter, request *http.Request) error {
-		return translateError(executionHandler(responseWriter, request, runner, registry))
+		err := executionHandler(responseWriter, request, runner, registry)
+		if err != nil {
+			return translateError(err)
+		}
+
+		return nil
 	})
 }
 
@@ -83,6 +90,10 @@ func translateError(err error) error {
 		return nil
 	}
 
+	if errors.Is(err, ErrStreamingNotSupported) {
+		return httpx.NewWebError(err, http.StatusInternalServerError, ErrStreamingNotSupported.Error())
+	}
+
 	if errors.Is(err, callgate.ErrBusy) {
 		return httpx.NewWebError(err, http.StatusTooManyRequests, "Too many requests")
 	}
@@ -117,8 +128,25 @@ func runCommand(
 	action := createGateAction(runner, cmd, cmdResult, writer, async)
 
 	exitCode, err := exec.Run(ctx, cmd.CallGate, cmd.URL, action)
+	if err != nil {
+		if errors.Is(err, callgate.ErrBusy) || errors.Is(err, gateexec.ErrRegistry) || errors.Is(err, gateexec.ErrAcquire) {
+			return fmt.Errorf("failed to start command: %w", err)
+		}
+
+		responseWriter.Header().Set("X-Success", "false")
+		responseWriter.Header().Set("X-Error-Message", err.Error())
+		responseWriter.Header().Set("X-Exit-Code", "")
+		log.Printf("[ERROR] rid=%s Command failed with error: %v", rid, err)
 
-	return handleCommandResult(rid, exitCode, err, responseWriter)
+		return httpx.NewSilentError(err)
+	}
+
+	responseWriter.Header().Set("X-Success", strconv.FormatBool(exitCode == 0))
+	responseWriter.Header().Set("X-Error-Message", "")
+	responseWriter.Header().Set("X-Exit-Code", strconv.Itoa(exitCode))
+	log.Printf("[INFO] rid=%s Command failed with exit code: %d", rid, exitCode)
+
+	return nil
 }
 
 func createGateAction(
@@ -191,34 +219,6 @@ func waitAsyncAndLog(
 	return done
 }
 
-func handleCommandResult(rid string, exitCode int, err error, responseWriter http.ResponseWriter) error {
-	if err != nil {
-		if errors.Is(err, callgate.ErrBusy) || errors.Is(err, gateexec.ErrRegistry) || errors.Is(err, gateexec.ErrAcquire) {
-			return translateError(err)
-		}
-
-		log.Printf("[WARN] rid=%s Command failed with exit code: %d, error: %v", rid, exitCode, err)
-
-		writeErrorMessage(rid, responseWriter, fmt.Sprintf("Command failed with exit code: %d, error: %v", exitCode, err))
-
-		return nil
-	}
-
-	if exitCode != 0 {
-		log.Printf("[WARN] rid=%s Command failed with exit code: %d", rid, exitCode)
-
-		writeErrorMessage(rid, responseWriter, fmt.Sprintf("Command failed with exit code: %d", exitCode))
-	}
-
-	return nil
-}
-
-func writeErrorMessage(rid string, responseWriter http.ResponseWriter, message string) {
-	if _, writeErr := responseWriter.Write([]byte(message)); writeErr != nil {
-		log.Printf("[ERROR] rid=%s Failed to write error message: %v", rid, writeErr)
-	}
-}
-
 func startCommandProcess(
 	runner cmdrunner.Runner,
 	command string,
@@ -335,20 +335,20 @@ func prepareOutputAndRunStreamCommand(
 	responseWriter http.ResponseWriter,
 ) error {
 	if _, ok := responseWriter.(http.Flusher); !ok {
-		return httpx.NewWebError(
-			fmt.Errorf("streaming not supported: %w", ErrBadConfiguration),
-			http.StatusInternalServerError,
-			"response writer does not support flushing",
-		)
+		return ErrStreamingNotSupported
 	}
 
-	writer := newFlushResponseWriter(responseWriter)
+	responseWriter.Header().Add("Trailer", "X-Success")
+	responseWriter.Header().Add("Trailer", "X-Error-Message")
+	responseWriter.Header().Add("Trailer", "X-Exit-Code")
 
 	responseWriter.Header().Set("Content-Type", "text/plain; charset=utf-8")
 	responseWriter.Header().Set("Cache-Control", "no-cache")
 	// nginx:
 	responseWriter.Header().Set("X-Accel-Buffering", "no")
 
+	writer := newFlushResponseWriter(responseWriter)
+
 	return runCommand(
 		ctx,
 		runner,
@@ -369,20 +369,29 @@ func prepareOutputAndRunSyncCommand(
 	cmdResult *cmdbuilder.Result,
 	responseWriter http.ResponseWriter,
 ) error {
-	writer := responseWriter
+	var buf bytes.Buffer
 
 	responseWriter.Header().Set("Content-Type", "text/plain; charset=utf-8")
 
-	return runCommand(
+	err := runCommand(
 		ctx,
 		runner,
 		registry,
 		cmd,
 		cmdResult,
-		writer,
+		&buf,
 		false,
 		responseWriter,
 	)
+	if err != nil {
+		return err
+	}
+
+	if _, writeErr := responseWriter.Write(buf.Bytes()); writeErr != nil {
+		log.Printf("[ERROR] failed to write buffered output: %v", writeErr)
+	}
+
+	return nil
 }
 
 func extractQueryParams(request *http.Request) map[string]string {
diff --git a/pkg/router/handlers/execution_handler_test.go b/pkg/router/handlers/execution_handler_test.go
index 8e4dbeb..70698c0 100644
--- a/pkg/router/handlers/execution_handler_test.go
+++ b/pkg/router/handlers/execution_handler_test.go
@@ -774,8 +774,8 @@ func TestExecutionHandler_PrepareOutput_Stream_Failure(t *testing.T) {
 	}
 
 	errMsg := rr.Header().Get("X-Error-Message")
-	if !strings.Contains(errMsg, "response writer does not support flushing") {
-		t.Errorf("expected X-Error-Message to contain 'response writer does not support flushing', got %q", errMsg)
+	if !strings.Contains(errMsg, "streaming not supported") {
+		t.Errorf("expected X-Error-Message to contain 'streaming not supported', got %q", errMsg)
 	}
 }
 
@@ -989,14 +989,13 @@ func TestExecutionHandler_ExecuteCommand_StartError_WritesFailedToStart(t *testi
 	rr := httptest.NewRecorder()
 	h.ServeHTTP(rr, req)
 
-	// runCommand returns nil and only writes the error to the response body, so the status is typically 200.
 	if rr.Code != http.StatusOK {
 		t.Errorf("expected status 200, got %d, body=%q", rr.Code, rr.Body.String())
 	}
 
-	body := rr.Body.String()
-	if !strings.Contains(body, "failed to start command") {
-		t.Errorf("expected body to contain %q, got %q", "failed to start command", body)
+	errMsg := rr.Header().Get("X-Error-Message")
+	if !strings.Contains(errMsg, "failed to start command") {
+		t.Errorf("expected X-Error-Message header to contain %q, got %q", "failed to start command", errMsg)
 	}
 }
 
@@ -1176,9 +1175,9 @@ func TestExecutionHandler_SyncWait_ExitError_NonZeroExit_WritesFailureMessage(t
 		t.Errorf("expected status 200, got %d", rr.Code)
 	}
 
-	body := rr.Body.String()
-	if !strings.Contains(body, "Command failed with exit code: 7") {
-		t.Errorf("expected body to contain exit code 7, got %q", body)
+	exitCodeHeader := rr.Header().Get("X-Exit-Code")
+	if exitCodeHeader != "7" {
+		t.Errorf("expected X-Exit-Code header to be 7, got %q", exitCodeHeader)
 	}
 }
 
@@ -1223,14 +1222,14 @@ func TestExecutionHandler_SyncWait_WaitReturnsNonExitError_WritesFailureMessage(
 		t.Errorf("expected status 200, got %d", rr.Code)
 	}
 
-	body := rr.Body.String()
-
-	if !strings.Contains(body, "Command failed with exit code: -1") {
-		t.Errorf("expected body to contain exit code -1, got %q", body)
+	exitCodeHeader := rr.Header().Get("X-Exit-Code")
+	if exitCodeHeader != "" {
+		t.Errorf("expected X-Exit-Code header to be empty, got %q", exitCodeHeader)
 	}
 
-	if !strings.Contains(body, "wait boom") {
-		t.Errorf("expected body to contain %q, got %q", "wait boom", body)
+	errorMessageHeader := rr.Header().Get("X-Error-Message")
+	if !strings.Contains(errorMessageHeader, "wait boom") {
+		t.Errorf("expected X-Error-Message header to contain %q, got %q", "wait boom", errorMessageHeader)
 	}
 }
 
@@ -1348,8 +1347,9 @@ func TestExecutionHandler_TerminateOnCancel_NoGrace_SendsSIGKILL(t *testing.T) {
 		t.Errorf("expected status 200, got %d", rr.Code)
 	}
 
-	if !strings.Contains(rr.Body.String(), "context canceled") {
-		t.Errorf("expected body to contain %q, got %q", "context canceled", rr.Body.String())
+	errMsg := rr.Header().Get("X-Error-Message")
+	if !strings.Contains(errMsg, "context canceled") {
+		t.Errorf("expected X-Error-Message header to contain %q, got %q", "context canceled", errMsg)
 	}
 }
 
@@ -1528,19 +1528,19 @@ func TestExecutionHandler_DeadlineExceeded_PrioritizesCtxErrOverExitError(t *tes
 		t.Errorf("expected status 200, got %d", rr.Code)
 	}
 
-	body := rr.Body.String()
-
-	if !strings.Contains(body, "context deadline exceeded") {
-		t.Errorf("expected body to contain %q, got %q", "context deadline exceeded", body)
+	exitCodeHeader := rr.Header().Get("X-Exit-Code")
+	if exitCodeHeader != "" {
+		t.Errorf("expected X-Exit-Code header to be empty, got %q", exitCodeHeader)
 	}
 
-	if !strings.Contains(body, "Command failed with exit code: -1") {
-		t.Errorf("expected body to contain exit code -1, got %q", body)
+	errMsg := rr.Header().Get("X-Error-Message")
+	if !strings.Contains(errMsg, "context deadline exceeded") {
+		t.Errorf("expected X-Error-Message header to contain %q, got %q", "context deadline exceeded", errMsg)
 	}
 
 	// Make sure it did not report the process exit code (7) as primary.
-	if strings.Contains(body, "Command failed with exit code: 7") {
-		t.Errorf("did not expect exit code 7 to be reported, got %q", body)
+	if exitCodeHeader == "7" {
+		t.Errorf("did not expect exit code 7 to be reported, got %q", exitCodeHeader)
 	}
 }
 
@@ -1713,7 +1713,7 @@ func TestExecutionHandler_AsyncNone_WaitError_LogsButDoesNotAffectResponse(t *te
 	}
 }
 
-func TestExecutionHandler_RunCommand_AppendsErrorMessageToBody_OnNonZeroExit(t *testing.T) {
+func TestExecutionHandler_RunCommand_SetsExitCodeHeader_OnNonZeroExit(t *testing.T) {
 	t.Parallel()
 
 	ctrl := gomock.NewController(t)
@@ -1743,7 +1743,7 @@ func TestExecutionHandler_RunCommand_AppendsErrorMessageToBody_OnNonZeroExit(t *
 
 	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
 	mockCmd.EXPECT().SetStdout(gomock.Any()).Do(func(w io.Writer) {
-		// simulate process output written before failure is appended
+		// simulate process output
 		_, _ = w.Write([]byte("PROC_OUT\n"))
 	})
 	mockCmd.EXPECT().SetStderr(gomock.Any())
@@ -1766,14 +1766,13 @@ func TestExecutionHandler_RunCommand_AppendsErrorMessageToBody_OnNonZeroExit(t *
 	}
 
 	body := rr.Body.String()
-
-	// may be mixed with earlier output; we only assert that the error message is appended somewhere
 	if !strings.Contains(body, "PROC_OUT") {
 		t.Errorf("expected body to contain process output, got %q", body)
 	}
 
-	if !strings.Contains(body, "Command failed with exit code: 7") {
-		t.Errorf("expected body to contain exit code 7 failure message, got %q", body)
+	exitCodeHeader := rr.Header().Get("X-Exit-Code")
+	if exitCodeHeader != "7" {
+		t.Errorf("expected X-Exit-Code header to be 7, got %q", exitCodeHeader)
 	}
 }
 
@@ -1857,7 +1856,7 @@ func TestExecutionHandler_RunCommand_WriteErrorMessageWriteFails_LogsError(t *te
 		logs := buf.String()
 		mu.Unlock()
 
-		if strings.Contains(logs, "Failed to write error message") {
+		if strings.Contains(logs, "failed to write buffered output") {
 			if !strings.Contains(logs, "write failed") {
 				t.Fatalf("expected logs to contain %q, got %q", "write failed", logs)
 			}
@@ -1866,7 +1865,7 @@ func TestExecutionHandler_RunCommand_WriteErrorMessageWriteFails_LogsError(t *te
 		}
 
 		if time.Now().After(deadline) {
-			t.Fatalf("expected logs to contain %q, got %q", "Failed to write error message", logs)
+			t.Fatalf("expected logs to contain %q, got %q", "failed to write buffered output", logs)
 		}
 
 		time.Sleep(5 * time.Millisecond)
diff --git a/test/integration/server_test.go b/test/integration/server_test.go
index 8c30efe..24f190c 100644
--- a/test/integration/server_test.go
+++ b/test/integration/server_test.go
@@ -176,7 +176,7 @@ func TestServerIntegration(t *testing.T) {
 		}
 	})
 
-	t.Run("504 Gateway Timeout", func(t *testing.T) {
+	t.Run("Execution Timeout", func(t *testing.T) {
 		t.Parallel()
 		srv := setupServer(t)
 
@@ -185,15 +185,17 @@ func TestServerIntegration(t *testing.T) {
 
 		srv.ServeHTTP(rec, req)
 
-		// Intentional decision to return 200 OK because the command's exit status
-		// is unknown when headers are sent (especially for streaming).
-		// Error messages are appended to the response body.
 		if rec.Code != http.StatusOK {
 			t.Errorf("Expected status code %d, got %d", http.StatusOK, rec.Code)
 		}
 
-		if !strings.Contains(rec.Body.String(), "context deadline exceeded") {
-			t.Errorf("Expected timeout error message in body, got %q", rec.Body.String())
+		if rec.Header().Get("X-Success") != "false" {
+			t.Errorf("Expected X-Success: false, got %q", rec.Header().Get("X-Success"))
+		}
+
+		errMsg := rec.Header().Get("X-Error-Message")
+		if !strings.Contains(errMsg, "context deadline exceeded") {
+			t.Errorf("Expected timeout error message in X-Error-Message header, got %q", errMsg)
 		}
 	})
 
@@ -210,8 +212,12 @@ func TestServerIntegration(t *testing.T) {
 			t.Errorf("Expected status code %d, got %d", http.StatusOK, rec.Code)
 		}
 
-		if !strings.Contains(rec.Body.String(), "Command failed with exit code: 1") {
-			t.Errorf("Expected error message in body, got %q", rec.Body.String())
+		if rec.Header().Get("X-Success") != "false" {
+			t.Errorf("Expected X-Success: false, got %q", rec.Header().Get("X-Success"))
+		}
+
+		if rec.Header().Get("X-Exit-Code") != "1" {
+			t.Errorf("Expected X-Exit-Code: 1, got %q", rec.Header().Get("X-Exit-Code"))
 		}
 	})
 

From c1ff384dab18bbe71e87ef6fcc69b2b192b75cc6 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Sat, 28 Feb 2026 19:38:33 +0100
Subject: [PATCH 20/38] refactor(gateexec): simplify error handling

---
 pkg/gateexec/gateexec.go                      | 9 +++------
 pkg/router/handlers/execution_handler.go      | 6 +-----
 pkg/router/handlers/execution_handler_test.go | 4 ++--
 3 files changed, 6 insertions(+), 13 deletions(-)

diff --git a/pkg/gateexec/gateexec.go b/pkg/gateexec/gateexec.go
index ebace16..0744960 100644
--- a/pkg/gateexec/gateexec.go
+++ b/pkg/gateexec/gateexec.go
@@ -9,10 +9,7 @@ import (
 	"github.com/dkarczmarski/webcmd/pkg/config"
 )
 
-var (
-	ErrRegistry = errors.New("gate executor: registry error")
-	ErrAcquire  = errors.New("gate executor: acquire error")
-)
+var ErrPreAction = errors.New("gate executor: pre-action")
 
 type Action func(context.Context) (result int, done <-chan struct{}, err error)
 
@@ -43,12 +40,12 @@ func (e *Executor) Run(
 
 	gate, err := e.registry.GetOrCreate(group, gateCfg.Mode)
 	if err != nil {
-		return -1, fmt.Errorf("%w: %w", ErrRegistry, err)
+		return -1, fmt.Errorf("%w: %w", ErrPreAction, err)
 	}
 
 	release, err := gate.Acquire(ctx)
 	if err != nil {
-		return -1, fmt.Errorf("%w: %w", ErrAcquire, err)
+		return -1, fmt.Errorf("%w: %w", ErrPreAction, err)
 	}
 
 	exit, done, runErr := action(ctx)
diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index b1d876b..e57b115 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -98,10 +98,6 @@ func translateError(err error) error {
 		return httpx.NewWebError(err, http.StatusTooManyRequests, "Too many requests")
 	}
 
-	if errors.Is(err, gateexec.ErrRegistry) {
-		return httpx.NewWebError(err, http.StatusInternalServerError, "Invalid callgate configuration")
-	}
-
 	if errors.Is(err, ErrCommandNotFound) {
 		return httpx.NewWebError(err, http.StatusNotFound, "Command not found")
 	}
@@ -129,7 +125,7 @@ func runCommand(
 
 	exitCode, err := exec.Run(ctx, cmd.CallGate, cmd.URL, action)
 	if err != nil {
-		if errors.Is(err, callgate.ErrBusy) || errors.Is(err, gateexec.ErrRegistry) || errors.Is(err, gateexec.ErrAcquire) {
+		if errors.Is(err, gateexec.ErrPreAction) {
 			return fmt.Errorf("failed to start command: %w", err)
 		}
 
diff --git a/pkg/router/handlers/execution_handler_test.go b/pkg/router/handlers/execution_handler_test.go
index 70698c0..9e0c8fc 100644
--- a/pkg/router/handlers/execution_handler_test.go
+++ b/pkg/router/handlers/execution_handler_test.go
@@ -911,8 +911,8 @@ func TestExecutionHandler_UnknownCallGateMode(t *testing.T) {
 	}
 
 	errMsg := rr.Header().Get("X-Error-Message")
-	if !strings.Contains(errMsg, "Invalid callgate configuration") {
-		t.Errorf("expected X-Error-Message to contain %q, got %q", "Invalid callgate configuration", errMsg)
+	if !strings.Contains(errMsg, "invalid callgate mode") {
+		t.Errorf("expected X-Error-Message to contain %q, got %q", "invalid callgate mode", errMsg)
 	}
 }
 

From 31f0b58205572857382b4fb0e1957a79b07ccd16 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Sat, 28 Feb 2026 20:06:38 +0100
Subject: [PATCH 21/38] docs(gateexec): add godoc

---
 pkg/gateexec/gateexec.go | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/pkg/gateexec/gateexec.go b/pkg/gateexec/gateexec.go
index 0744960..9daa9b3 100644
--- a/pkg/gateexec/gateexec.go
+++ b/pkg/gateexec/gateexec.go
@@ -1,3 +1,7 @@
+// Package gateexec provides a mechanism for executing actions under the control of call gates.
+//
+// It wraps an Action with gate-based concurrency control, handling gate acquisition,
+// execution, and release (including asynchronous cleanup).
 package gateexec
 
 import (
@@ -9,8 +13,14 @@ import (
 	"github.com/dkarczmarski/webcmd/pkg/config"
 )
 
+// ErrPreAction is returned when an error occurs before the actual action starts,
+// such as during gate acquisition or retrieval.
 var ErrPreAction = errors.New("gate executor: pre-action")
 
+// Action represents a function to be executed under gate control.
+// It returns a result code (e.g. process exit code), an optional channel
+// that indicates when the action is fully finished (for async cleanup),
+// and any execution error.
 type Action func(context.Context) (result int, done <-chan struct{}, err error)
 
 type Executor struct {

From efd7eef0511c51a7b62dce6bb5dddf14c1e04ec9 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Sat, 28 Feb 2026 22:34:12 +0100
Subject: [PATCH 22/38] test(gateexec): add unit tests

---
 pkg/gateexec/fakes_test.go    |  64 ++++++++
 pkg/gateexec/gateexec.go      |  18 ++-
 pkg/gateexec/gateexec_test.go | 289 ++++++++++++++++++++++++++++++++++
 pkg/gateexec/helpers_test.go  |  42 +++++
 4 files changed, 410 insertions(+), 3 deletions(-)
 create mode 100644 pkg/gateexec/fakes_test.go
 create mode 100644 pkg/gateexec/gateexec_test.go
 create mode 100644 pkg/gateexec/helpers_test.go

diff --git a/pkg/gateexec/fakes_test.go b/pkg/gateexec/fakes_test.go
new file mode 100644
index 0000000..0227b7c
--- /dev/null
+++ b/pkg/gateexec/fakes_test.go
@@ -0,0 +1,64 @@
+package gateexec_test
+
+import (
+	"context"
+	"sync/atomic"
+
+	"github.com/dkarczmarski/webcmd/pkg/callgate"
+)
+
+type fakeRegistry struct {
+	calls     int32
+	lastGroup string
+	lastMode  string
+
+	gateToReturn callgate.CallGate
+	errToReturn  error
+}
+
+func (r *fakeRegistry) GetOrCreate(group string, mode string) (callgate.CallGate, error) { //nolint:ireturn
+	atomic.AddInt32(&r.calls, 1)
+	r.lastGroup = group
+	r.lastMode = mode
+
+	return r.gateToReturn, r.errToReturn
+}
+
+func (r *fakeRegistry) callCount() int {
+	return int(atomic.LoadInt32(&r.calls))
+}
+
+type fakeGate struct {
+	acquireCalls int32
+	lastCtx      context.Context //nolint:containedctx
+
+	acquireErr error
+
+	releaseCalls int32
+}
+
+func (g *fakeGate) Acquire(ctx context.Context) (func(), error) {
+	atomic.AddInt32(&g.acquireCalls, 1)
+	g.lastCtx = ctx
+
+	if g.acquireErr != nil {
+		return nil, g.acquireErr
+	}
+
+	release := func() {
+		atomic.AddInt32(&g.releaseCalls, 1)
+	}
+
+	return release, nil
+}
+
+func (g *fakeGate) acquireCount() int {
+	return int(atomic.LoadInt32(&g.acquireCalls))
+}
+
+func (g *fakeGate) releaseCount() int {
+	return int(atomic.LoadInt32(&g.releaseCalls))
+}
+
+// compile-time interface check.
+var _ callgate.CallGate = (*fakeGate)(nil)
diff --git a/pkg/gateexec/gateexec.go b/pkg/gateexec/gateexec.go
index 9daa9b3..d8bfe99 100644
--- a/pkg/gateexec/gateexec.go
+++ b/pkg/gateexec/gateexec.go
@@ -23,11 +23,23 @@ var ErrPreAction = errors.New("gate executor: pre-action")
 // and any execution error.
 type Action func(context.Context) (result int, done <-chan struct{}, err error)
 
+// Registry provides access to execution gates identified
+// by a group and mode name.
+//
+// Executor uses Registry to obtain or lazily create
+// a Gate instance before running an action.
+//
+// Implementations are responsible for ensuring that
+// repeated calls with the same group return the same Gate.
+type Registry interface {
+	GetOrCreate(group string, name string) (callgate.CallGate, error)
+}
+
 type Executor struct {
-	registry *callgate.Registry
+	registry Registry
 }
 
-func New(registry *callgate.Registry) *Executor {
+func New(registry Registry) *Executor {
 	return &Executor{registry: registry}
 }
 
@@ -37,7 +49,7 @@ func (e *Executor) Run(
 	defaultGroup string,
 	action Action,
 ) (int, error) {
-	if gateCfg == nil || e.registry == nil {
+	if gateCfg == nil {
 		exit, _, err := action(ctx)
 
 		return exit, err
diff --git a/pkg/gateexec/gateexec_test.go b/pkg/gateexec/gateexec_test.go
new file mode 100644
index 0000000..ef43218
--- /dev/null
+++ b/pkg/gateexec/gateexec_test.go
@@ -0,0 +1,289 @@
+package gateexec_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/dkarczmarski/webcmd/pkg/config"
+	"github.com/dkarczmarski/webcmd/pkg/gateexec"
+)
+
+func TestExecutor_Run_BasicPaths(t *testing.T) {
+	t.Parallel()
+
+	t.Run("nil gate config: action called once, registry not used, exit/error propagated", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := t.Context()
+		reg := &fakeRegistry{}
+		exec := gateexec.New(reg)
+
+		wantExit := 42
+		wantErr := errors.New("action error")
+
+		actionCalls := 0
+		action := func(context.Context) (int, <-chan struct{}, error) {
+			actionCalls++
+
+			return wantExit, nil, wantErr
+		}
+
+		gotExit, gotErr := exec.Run(ctx, nil, "X", action)
+
+		assertEqual(t, actionCalls, 1, "action calls")
+		assertEqual(t, reg.callCount(), 0, "registry calls")
+		assertEqual(t, gotExit, wantExit, "exit")
+		assertIs(t, gotErr, wantErr)
+	})
+
+	cases := []struct {
+		name       string
+		cfg        *config.CallGateConfig
+		defaultGrp string
+		wantGroup  string
+		wantMode   string
+	}{
+		{
+			name:       "default group used when GroupName is nil",
+			cfg:        &config.CallGateConfig{GroupName: nil, Mode: "single"},
+			defaultGrp: "X",
+			wantGroup:  "X",
+			wantMode:   "single",
+		},
+		{
+			name:       "GroupName overrides default group",
+			cfg:        &config.CallGateConfig{GroupName: strPtr("Y"), Mode: "single"},
+			defaultGrp: "X",
+			wantGroup:  "Y",
+			wantMode:   "single",
+		},
+		{
+			name:       "mode is passed to registry as second argument",
+			cfg:        &config.CallGateConfig{GroupName: nil, Mode: "custom-mode"},
+			defaultGrp: "X",
+			wantGroup:  "X",
+			wantMode:   "custom-mode",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			ctx := t.Context()
+			gate := &fakeGate{}
+			reg := &fakeRegistry{gateToReturn: gate}
+			exec := gateexec.New(reg)
+
+			actionCalls := 0
+			action := func(context.Context) (int, <-chan struct{}, error) {
+				actionCalls++
+
+				return 0, nil, nil
+			}
+
+			_, _ = exec.Run(ctx, tc.cfg, tc.defaultGrp, action)
+
+			assertEqual(t, actionCalls, 1, "action calls")
+			assertEqual(t, reg.callCount(), 1, "registry calls")
+			assertEqual(t, reg.lastGroup, tc.wantGroup, "registry group argument")
+			assertEqual(t, reg.lastMode, tc.wantMode, "registry mode argument")
+		})
+	}
+}
+
+//nolint:lll
+func TestExecutor_Run_PreActionErrors(t *testing.T) {
+	t.Parallel()
+
+	t.Run("GetOrCreate error: returns -1 and wraps ErrPreAction and original error; does not call action or Acquire", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := t.Context()
+		someErr := errors.New("registry failure")
+
+		gate := &fakeGate{}
+		reg := &fakeRegistry{
+			gateToReturn: gate,
+			errToReturn:  someErr,
+		}
+		exec := gateexec.New(reg)
+
+		actionCalls := 0
+		action := func(context.Context) (int, <-chan struct{}, error) {
+			actionCalls++
+
+			return 0, nil, nil
+		}
+
+		cfg := &config.CallGateConfig{Mode: "single"}
+		exit, err := exec.Run(ctx, cfg, "X", action)
+
+		assertEqual(t, exit, -1, "exit")
+		assertIs(t, err, gateexec.ErrPreAction)
+		assertIs(t, err, someErr)
+
+		assertEqual(t, actionCalls, 0, "action calls")
+		assertEqual(t, reg.callCount(), 1, "registry calls")
+		assertEqual(t, gate.acquireCount(), 0, "gate Acquire calls")
+	})
+
+	t.Run("Acquire error: returns -1 and wraps ErrPreAction and original error; does not call action; does not call release", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := t.Context()
+		someErr := errors.New("acquire failure")
+
+		gate := &fakeGate{acquireErr: someErr}
+		reg := &fakeRegistry{gateToReturn: gate}
+		exec := gateexec.New(reg)
+
+		actionCalls := 0
+		action := func(context.Context) (int, <-chan struct{}, error) {
+			actionCalls++
+
+			return 0, nil, nil
+		}
+
+		cfg := &config.CallGateConfig{Mode: "single"}
+		exit, err := exec.Run(ctx, cfg, "X", action)
+
+		assertEqual(t, exit, -1, "exit")
+		assertIs(t, err, gateexec.ErrPreAction)
+		assertIs(t, err, someErr)
+
+		assertEqual(t, actionCalls, 0, "action calls")
+		assertEqual(t, gate.acquireCount(), 1, "gate Acquire calls")
+		assertEqual(t, gate.releaseCount(), 0, "release calls")
+	})
+
+	t.Run("Acquire receives the same context passed to Run", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := context.WithValue(t.Context(), struct{}{}, "marker") //nolint:staticcheck
+
+		gate := &fakeGate{}
+		reg := &fakeRegistry{gateToReturn: gate}
+		exec := gateexec.New(reg)
+
+		action := func(context.Context) (int, <-chan struct{}, error) {
+			return 0, nil, nil
+		}
+
+		cfg := &config.CallGateConfig{Mode: "single"}
+		_, _ = exec.Run(ctx, cfg, "X", action)
+
+		if gate.lastCtx != ctx {
+			t.Fatalf("Acquire context: got %v, want the exact same instance", gate.lastCtx)
+		}
+	})
+}
+
+//nolint:lll
+func TestExecutor_Run_ReleaseAndDone(t *testing.T) {
+	t.Parallel()
+
+	t.Run("done is nil: release is called synchronously before Run returns", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := t.Context()
+		gate := &fakeGate{}
+		reg := &fakeRegistry{gateToReturn: gate}
+		exec := gateexec.New(reg)
+
+		action := func(context.Context) (int, <-chan struct{}, error) {
+			return 0, nil, nil
+		}
+
+		cfg := &config.CallGateConfig{Mode: "single"}
+		_, _ = exec.Run(ctx, cfg, "X", action)
+
+		// If release is synchronous, it must already be 1 here.
+		assertEqual(t, gate.releaseCount(), 1, "release calls")
+	})
+
+	t.Run("done is not nil: release is not called immediately; called once after done is closed", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := t.Context()
+		gate := &fakeGate{}
+		reg := &fakeRegistry{gateToReturn: gate}
+		exec := gateexec.New(reg)
+
+		doneCh := make(chan struct{})
+
+		action := func(context.Context) (int, <-chan struct{}, error) {
+			return 0, doneCh, nil
+		}
+
+		cfg := &config.CallGateConfig{Mode: "single"}
+		_, _ = exec.Run(ctx, cfg, "X", action)
+
+		assertEqual(t, gate.releaseCount(), 0, "release calls immediately after Run")
+
+		close(doneCh)
+
+		eventually(t, 300*time.Millisecond, func() bool {
+			return gate.releaseCount() == 1
+		})
+
+		assertEqual(t, gate.releaseCount(), 1, "release calls after done is closed")
+	})
+
+	t.Run("action returns error with done=nil: release still called once and Run returns the action error", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := t.Context()
+		gate := &fakeGate{}
+		reg := &fakeRegistry{gateToReturn: gate}
+		exec := gateexec.New(reg)
+
+		runErr := errors.New("run failed")
+		action := func(context.Context) (int, <-chan struct{}, error) {
+			return 123, nil, runErr
+		}
+
+		cfg := &config.CallGateConfig{Mode: "single"}
+		exit, err := exec.Run(ctx, cfg, "X", action)
+
+		assertEqual(t, exit, 123, "exit")
+		assertIs(t, err, runErr)
+
+		assertEqual(t, gate.releaseCount(), 1, "release calls")
+	})
+
+	t.Run("action returns error with done!=nil: Run returns the action error; release happens only after done is closed", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := t.Context()
+		gate := &fakeGate{}
+		reg := &fakeRegistry{gateToReturn: gate}
+		exec := gateexec.New(reg)
+
+		doneCh := make(chan struct{})
+		runErr := errors.New("run failed")
+
+		action := func(context.Context) (int, <-chan struct{}, error) {
+			return 5, doneCh, runErr
+		}
+
+		cfg := &config.CallGateConfig{Mode: "single"}
+		exit, err := exec.Run(ctx, cfg, "X", action)
+
+		assertEqual(t, exit, 5, "exit")
+		assertIs(t, err, runErr)
+
+		// Not yet released until done is closed.
+		assertEqual(t, gate.releaseCount(), 0, "release calls immediately after Run")
+
+		close(doneCh)
+
+		eventually(t, 300*time.Millisecond, func() bool {
+			return gate.releaseCount() == 1
+		})
+
+		assertEqual(t, gate.releaseCount(), 1, "release calls after done is closed")
+	})
+}
diff --git a/pkg/gateexec/helpers_test.go b/pkg/gateexec/helpers_test.go
new file mode 100644
index 0000000..244ef07
--- /dev/null
+++ b/pkg/gateexec/helpers_test.go
@@ -0,0 +1,42 @@
+package gateexec_test
+
+import (
+	"errors"
+	"testing"
+	"time"
+)
+
+func strPtr(s string) *string {
+	return &s
+}
+
+func assertIs(t *testing.T, err error, target error) {
+	t.Helper()
+
+	if !errors.Is(err, target) {
+		t.Fatalf("expected errors.Is(err, %v) == true, got false; err=%v", target, err)
+	}
+}
+
+func assertEqual[T comparable](t *testing.T, got, want T, msg string) {
+	t.Helper()
+
+	if got != want {
+		t.Fatalf("%s: got %v, want %v", msg, got, want)
+	}
+}
+
+func eventually(t *testing.T, timeout time.Duration, check func() bool) {
+	t.Helper()
+
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		if check() {
+			return
+		}
+
+		time.Sleep(5 * time.Millisecond)
+	}
+
+	t.Fatalf("condition not satisfied within %s", timeout)
+}

From a527cd3209fab85eb31b3342d25c712aa98bfec6 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Mon, 2 Mar 2026 20:29:04 +0100
Subject: [PATCH 23/38] fix(callgate): Sequence serves waiters in FIFO

---
 pkg/callgate/callgate_queue.go      |  87 +++++++--
 pkg/callgate/callgate_queue_test.go | 263 ++++++++++++++++++++++++++++
 2 files changed, 336 insertions(+), 14 deletions(-)

diff --git a/pkg/callgate/callgate_queue.go b/pkg/callgate/callgate_queue.go
index de373fa..6c148da 100644
--- a/pkg/callgate/callgate_queue.go
+++ b/pkg/callgate/callgate_queue.go
@@ -7,32 +7,61 @@ import (
 )
 
 type Sequence struct {
-	token chan struct{}
+	mu    sync.Mutex
+	busy  bool
+	queue []chan struct{} // FIFO of waiters
 }
 
 func NewSequence() *Sequence {
-	l := &Sequence{
-		token: make(chan struct{}, 1),
-	}
-	l.token <- struct{}{}
-
-	return l
+	return &Sequence{} //nolint:exhaustruct
 }
 
 // Acquire blocks until the execution slot is available.
 //
-// This gate allows only one execution at a time. Calls are processed in sequence:
-// if one is running, the next call waits until it completes.
+// This gate allows only one execution at a time.
+// Waiters are served in strict FIFO order.
 //
-// When the slot is acquired, Acquire returns a release function. The caller must
-// call release() when the work is done.
+// When the slot is acquired, Acquire returns a release function.
+// The caller must call release() when the work is done.
 //
 // If the context is canceled before acquiring the slot, Acquire returns ctx.Err().
 func (cg *Sequence) Acquire(ctx context.Context) (func(), error) {
+	// Fast path: not busy and no queue => acquire immediately.
+	cg.mu.Lock()
+	if !cg.busy && len(cg.queue) == 0 {
+		cg.busy = true
+
+		cg.mu.Unlock()
+
+		return cg.releaseFunc(), nil
+	}
+
+	// Otherwise, enqueue and wait for our turn.
+	waiter := make(chan struct{})
+
+	cg.queue = append(cg.queue, waiter)
+	cg.mu.Unlock()
+
 	select {
 	case <-ctx.Done():
-		return nil, fmt.Errorf("acquire sequence: %w", ctx.Err())
-	case <-cg.token:
+		// Remove ourselves from the queue if we haven't been granted the slot yet.
+		cg.mu.Lock()
+		removed := cg.removeWaiterLocked(waiter)
+		cg.mu.Unlock()
+
+		// If we were NOT removed, it means we were already granted (channel closed)
+		// roughly concurrently. In that case, we must return success, not ctx.Err().
+		// We detect "granted" by checking removed==false; but there is a race:
+		// - if channel closed just before we locked, removeWaiterLocked won't find it.
+		// In that case, proceed as acquired.
+		if removed {
+			return nil, fmt.Errorf("acquire sequence: %w", ctx.Err())
+		}
+
+		return cg.releaseFunc(), nil
+
+	case <-waiter:
+		// Granted in FIFO order.
 		return cg.releaseFunc(), nil
 	}
 }
@@ -42,7 +71,37 @@ func (cg *Sequence) releaseFunc() func() {
 
 	return func() {
 		once.Do(func() {
-			cg.token <- struct{}{}
+			cg.mu.Lock()
+			defer cg.mu.Unlock()
+
+			// If someone is waiting, grant the next one in FIFO order.
+			if len(cg.queue) > 0 {
+				next := cg.queue[0]
+				// pop front
+				copy(cg.queue[0:], cg.queue[1:])
+				cg.queue = cg.queue[:len(cg.queue)-1]
+
+				// Keep busy=true, transfer ownership to the next waiter.
+				close(next)
+
+				return
+			}
+
+			// No waiters => free the slot.
+			cg.busy = false
 		})
 	}
 }
+
+func (cg *Sequence) removeWaiterLocked(waiter chan struct{}) bool {
+	for i := range cg.queue {
+		if cg.queue[i] == waiter {
+			copy(cg.queue[i:], cg.queue[i+1:])
+			cg.queue = cg.queue[:len(cg.queue)-1]
+
+			return true
+		}
+	}
+
+	return false
+}
diff --git a/pkg/callgate/callgate_queue_test.go b/pkg/callgate/callgate_queue_test.go
index b3c24d2..45a0097 100644
--- a/pkg/callgate/callgate_queue_test.go
+++ b/pkg/callgate/callgate_queue_test.go
@@ -252,3 +252,266 @@ func TestSequence_SerializesCriticalSection_NoOverlap(t *testing.T) {
 		t.Fatalf("critical section overlapped: max concurrent inCS = %d, want 1", maxSeen)
 	}
 }
+
+// FIFO / fairness: waiters should be granted in the same order they started waiting.
+func TestSequence_Acquire_FIFOOrder(t *testing.T) {
+	t.Parallel()
+
+	ctx := t.Context()
+	g := callgate.NewSequence()
+
+	release1, err := g.Acquire(ctx)
+	if err != nil {
+		t.Fatalf("Acquire #1 error: %v", err)
+	}
+
+	const n = 500
+	orderCh := make(chan int, n)
+
+	var (
+		releases [n]func()
+		errs     [n]error
+	)
+
+	// Start goroutines in a known order.
+	// Small sleeps help ensure they enqueue in that same order (keeps the test stable).
+	for i := range n {
+		go func(i int) {
+			releases[i], errs[i] = g.Acquire(ctx)
+			orderCh <- i
+		}(i)
+
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	// Let the first waiter through.
+	release1()
+
+	// We expect acquisition order in strict FIFO.
+	for want := range n {
+		select {
+		case got := <-orderCh:
+			if got != want {
+				t.Fatalf("FIFO violated: got=%d, want=%d", got, want)
+			}
+
+			if errs[got] != nil {
+				t.Fatalf("Acquire waiter #%d error: %v", got, errs[got])
+			}
+
+			if releases[got] == nil {
+				t.Fatalf("Acquire waiter #%d returned nil release", got)
+			}
+
+			// Release to allow the next waiter.
+			releases[got]()
+
+		case <-time.After(2 * time.Second):
+			t.Fatalf("timed out waiting for waiter #%d to acquire", want)
+		}
+	}
+}
+
+// Race: ctx cancel vs grant happening "at the same time".
+// Invariant:
+//   - If Acquire returns error => release must be nil.
+//   - If Acquire returns success => it must truly own the slot (next Acquire blocks until release()).
+func TestSequence_Acquire_CancelVsGrantRace(t *testing.T) {
+	t.Parallel()
+
+	root := t.Context()
+	g := callgate.NewSequence()
+
+	const iters = 500
+
+	for iter := range iters {
+		// Hold the slot.
+		release1, err := g.Acquire(root)
+		if err != nil {
+			t.Fatalf("iter %d: Acquire #1 error: %v", iter, err)
+		}
+
+		ctx, cancel := context.WithCancel(root)
+
+		var (
+			release2 func()
+			err2     error
+		)
+
+		done := make(chan struct{})
+
+		go func() {
+			release2, err2 = g.Acquire(ctx)
+
+			close(done)
+		}()
+
+		// Give the waiter a moment to enqueue.
+		time.Sleep(1 * time.Millisecond)
+
+		// Try to make cancel and release happen as simultaneously as possible.
+		start := make(chan struct{})
+
+		var wg sync.WaitGroup
+
+		wg.Add(2)
+
+		go func() {
+			defer wg.Done()
+			<-start
+			cancel()
+		}()
+		go func() {
+			defer wg.Done()
+			<-start
+			release1()
+		}()
+
+		close(start)
+		wg.Wait()
+
+		select {
+		case <-done:
+		case <-time.After(2 * time.Second):
+			t.Fatalf("iter %d: waiter did not finish", iter)
+		}
+
+		if err2 != nil {
+			// If canceled "won", must be an error and release must be nil.
+			if release2 != nil {
+				t.Fatalf("iter %d: expected nil release on error, got non-nil", iter)
+			}
+
+			if !errors.Is(err2, context.Canceled) && !errors.Is(err2, context.DeadlineExceeded) {
+				t.Fatalf("iter %d: expected ctx error, got: %v", iter, err2)
+			}
+
+			continue
+		}
+
+		// Success path: must have a release func.
+		if release2 == nil {
+			t.Fatalf("iter %d: Acquire succeeded but release is nil", iter)
+		}
+
+		// Verify it *really* owns the slot: a third Acquire should block until release2().
+		acquired3 := make(chan struct{})
+		go func() {
+			rel3, err3 := g.Acquire(root)
+			if err3 == nil && rel3 != nil {
+				rel3()
+			}
+
+			close(acquired3)
+		}()
+
+		select {
+		case <-acquired3:
+			// If it returned immediately, then release2 didn't actually own the slot.
+			t.Fatalf("iter %d: Acquire #3 returned early; release2 likely didn't own the slot", iter)
+		case <-time.After(30 * time.Millisecond):
+		}
+
+		release2()
+
+		select {
+		case <-acquired3:
+		case <-time.After(2 * time.Second):
+			t.Fatalf("iter %d: Acquire #3 did not return after release2()", iter)
+		}
+	}
+}
+
+// A canceled waiter should be removed from the queue and not block later waiters.
+// Scenario:
+//   - Hold slot with #1.
+//   - Waiter #2 times out while waiting (must return error).
+//   - Waiter #3 waits normally.
+//   - Release #1: waiter #3 must acquire (i.e., canceled waiter must not "sit" at the head forever).
+func TestSequence_Acquire_CanceledWaiterDoesNotBlockQueue(t *testing.T) {
+	t.Parallel()
+
+	root := t.Context()
+	g := callgate.NewSequence()
+
+	release1, err := g.Acquire(root)
+	if err != nil {
+		t.Fatalf("Acquire #1 error: %v", err)
+	}
+	defer release1()
+
+	// Waiter #2: should time out while waiting.
+	ctx2, cancel2 := context.WithTimeout(root, 30*time.Millisecond)
+	defer cancel2()
+
+	done2 := make(chan struct{})
+
+	var (
+		release2 func()
+		err2     error
+	)
+
+	go func() {
+		release2, err2 = g.Acquire(ctx2)
+
+		close(done2)
+	}()
+
+	select {
+	case <-done2:
+	case <-time.After(2 * time.Second):
+		t.Fatalf("waiter #2 did not return")
+	}
+
+	if release2 != nil {
+		t.Fatalf("expected nil release for waiter #2, got non-nil")
+	}
+
+	if err2 == nil {
+		t.Fatalf("expected error for waiter #2, got nil")
+	}
+
+	if !errors.Is(err2, context.DeadlineExceeded) {
+		t.Fatalf("expected waiter #2 to wrap context.DeadlineExceeded, got: %v", err2)
+	}
+
+	// Waiter #3: should be able to acquire once #1 releases.
+	acquired3 := make(chan struct{})
+
+	var (
+		release3 func()
+		err3     error
+	)
+
+	go func() {
+		release3, err3 = g.Acquire(root)
+
+		close(acquired3)
+	}()
+
+	// Should still be blocked because #1 is held.
+	select {
+	case <-acquired3:
+		t.Fatalf("Acquire #3 unexpectedly returned early (err=%v)", err3)
+	case <-time.After(30 * time.Millisecond):
+	}
+
+	// Now release #1: #3 must get it (canceled #2 must not block).
+	release1()
+
+	select {
+	case <-acquired3:
+	case <-time.After(2 * time.Second):
+		t.Fatalf("Acquire #3 did not return after release #1")
+	}
+
+	if err3 != nil {
+		t.Fatalf("Acquire #3 error: %v", err3)
+	}
+
+	if release3 == nil {
+		t.Fatalf("Acquire #3 returned nil release")
+	}
+
+	release3()
+}

From a1067d57c0bd4bf65d86d83f744d6d4d864b2919 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Mon, 2 Mar 2026 11:36:54 +0100
Subject: [PATCH 24/38] test(gateexec): add integration tests

---
 pkg/gateexec/gateexec_integration_test.go | 207 ++++++++++++++++++++++
 1 file changed, 207 insertions(+)
 create mode 100644 pkg/gateexec/gateexec_integration_test.go

diff --git a/pkg/gateexec/gateexec_integration_test.go b/pkg/gateexec/gateexec_integration_test.go
new file mode 100644
index 0000000..25c63ac
--- /dev/null
+++ b/pkg/gateexec/gateexec_integration_test.go
@@ -0,0 +1,207 @@
+package gateexec_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/dkarczmarski/webcmd/pkg/callgate"
+	"github.com/dkarczmarski/webcmd/pkg/config"
+	"github.com/dkarczmarski/webcmd/pkg/gateexec"
+)
+
+func TestExecutor_Integration_Single_ConcurrentSecondGetsErrBusy(t *testing.T) {
+	t.Parallel()
+
+	ctx := t.Context()
+
+	// Real registry with default gates.
+	registry := callgate.NewRegistry(callgate.WithDefaults())
+	exec := gateexec.New(registry)
+
+	cfg := &config.CallGateConfig{
+		Mode:      "single",
+		GroupName: strPtr("G"),
+	}
+
+	firstStarted := make(chan struct{})
+	firstDone := make(chan struct{})
+
+	// Action #1 acquires the slot and holds it until firstDone is closed.
+	action1 := func(context.Context) (int, <-chan struct{}, error) { //nolint:unparam
+		close(firstStarted)
+
+		return 1, firstDone, nil
+	}
+
+	// Action #2 should not run; it should fail with ErrBusy at Acquire time.
+	action2Called := make(chan struct{}, 1)
+	action2 := func(context.Context) (int, <-chan struct{}, error) {
+		action2Called <- struct{}{}
+
+		return 2, nil, nil
+	}
+
+	// Start action1 and wait until it definitely holds the slot.
+	errCh1 := make(chan error, 1)
+	go func() {
+		_, err := exec.Run(ctx, cfg, "DEFAULT", action1)
+		errCh1 <- err
+	}()
+
+	waitClosed(t, firstStarted, 700*time.Millisecond, "firstStarted")
+
+	// Now attempt to run action2 while action1 is still holding the slot.
+	exit2, err2 := exec.Run(ctx, cfg, "DEFAULT", action2)
+
+	// Ensure action2 wasn't called (Acquire should fail before action is executed).
+	select {
+	case <-action2Called:
+		t.Fatalf("action2 should not be called when gate is busy")
+	default:
+	}
+
+	// gateexec should report a pre-action error and include ErrBusy.
+	if exit2 != -1 {
+		t.Fatalf("expected exit=-1 for pre-action error, got %d", exit2)
+	}
+
+	if err2 == nil {
+		t.Fatalf("expected non-nil error")
+	}
+
+	if !errors.Is(err2, gateexec.ErrPreAction) {
+		t.Fatalf("expected errors.Is(err, gateexec.ErrPreAction)=true, err=%v", err2)
+	}
+
+	if !errors.Is(err2, callgate.ErrBusy) {
+		t.Fatalf("expected errors.Is(err, callgate.ErrBusy)=true, err=%v", err2)
+	}
+
+	// Now release action1 and ensure it completes without error.
+	close(firstDone)
+
+	select {
+	case err1 := <-errCh1:
+		if err1 != nil {
+			t.Fatalf("action1 Run returned unexpected error: %v", err1)
+		}
+	case <-time.After(700 * time.Millisecond):
+		t.Fatalf("timeout waiting for action1 Run to finish")
+	}
+}
+
+func TestExecutor_Integration_Sequence_SerializesAndMakesProgress(t *testing.T) {
+	t.Parallel()
+
+	const (
+		N       = 50
+		timeout = 700 * time.Millisecond
+	)
+
+	ctx := t.Context()
+
+	// Real registry with default gates (production-like).
+	registry := callgate.NewRegistry(callgate.WithDefaults())
+	exec := gateexec.New(registry)
+
+	cfg := &config.CallGateConfig{
+		Mode:      "sequence",
+		GroupName: strPtr("G"),
+	}
+
+	started := make(chan int, N)
+	errCh := make(chan error, N)
+
+	// Each action will block until its done[i] is closed.
+	done := make([]chan struct{}, N)
+	for i := range N {
+		done[i] = make(chan struct{})
+
+		//nolint:unparam
+		action := func(context.Context) (int, <-chan struct{}, error) {
+			// If gate is correct, this should happen strictly one-at-a-time.
+			started <- i
+
+			return i, done[i], nil
+		}
+
+		go func() {
+			_, err := exec.Run(ctx, cfg, "DEFAULT", action)
+			errCh <- err
+		}()
+	}
+
+	// Wait for the first action to enter.
+	var current int
+	select {
+	case current = <-started:
+	case <-time.After(timeout):
+		t.Fatalf("timeout waiting for first action to start")
+	}
+
+	seen := make(map[int]bool, N)
+	seen[current] = true
+
+	// While current is holding the slot, nobody else should enter.
+	select {
+	case v := <-started:
+		t.Fatalf("unexpected concurrent entry (sequence broken): %d", v)
+	default: // OK
+	}
+
+	// Now release actions one by one. Each release should allow exactly one next entry.
+	for step := 1; step < N; step++ {
+		close(done[current])
+
+		select {
+		case next := <-started:
+			if seen[next] {
+				t.Fatalf("action %d started more than once", next)
+			}
+
+			seen[next] = true
+			current = next
+		case <-time.After(timeout):
+			t.Fatalf("timeout waiting for next action to start (step=%d)", step)
+		}
+
+		// Again: still only one action can be in at a time.
+		select {
+		case v := <-started:
+			t.Fatalf("unexpected concurrent entry (sequence broken): %d", v)
+		default: // OK
+		}
+	}
+
+	// Release the last one.
+	close(done[current])
+
+	// All Run() calls should complete with nil error.
+	for range N {
+		select {
+		case err := <-errCh:
+			if err != nil {
+				t.Fatalf("Run returned unexpected error: %v", err)
+			}
+		case <-time.After(timeout):
+			t.Fatalf("timeout waiting for Run results")
+		}
+	}
+
+	// Sanity: everyone entered exactly once.
+	if len(seen) != N {
+		t.Fatalf("expected %d actions to start, got %d", N, len(seen))
+	}
+}
+
+func waitClosed(t *testing.T, ch <-chan struct{}, timeout time.Duration, name string) {
+	t.Helper()
+	select {
+	case <-ch:
+		return
+	case <-time.After(timeout):
+		t.Fatalf("timeout waiting for %s (%s)", name, timeout)
+	}
+}

From 349106969ddaa132d95e5a29d45088ceb431d4b0 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Tue, 3 Mar 2026 11:55:55 +0100
Subject: [PATCH 25/38] fix(processrunner): prioritize Wait() result over
 context cancellation

---
 pkg/processrunner/process_runner.go           | 114 ++++++++++++------
 pkg/router/handlers/execution_handler_test.go |  28 +++--
 test/integration/server_test.go               |   6 +-
 3 files changed, 95 insertions(+), 53 deletions(-)

diff --git a/pkg/processrunner/process_runner.go b/pkg/processrunner/process_runner.go
index e17d7e2..74a45fb 100644
--- a/pkg/processrunner/process_runner.go
+++ b/pkg/processrunner/process_runner.go
@@ -1,6 +1,8 @@
 // Package processrunner provides process lifecycle management:
-// start process in its own process group, wait synchronously/asynchronously,
-// and terminate the process group on context cancellation with optional grace timeout.
+//   - starts a process in its own process group,
+//   - allows synchronous and asynchronous waiting,
+//   - and terminates the whole process group on context cancellation
+//     with an optional grace timeout (SIGTERM -> SIGKILL).
 package processrunner
 
 import (
@@ -16,14 +18,25 @@ import (
 )
 
 var (
-	ErrStartCommand       = errors.New("failed to start command")
-	ErrInvalidPID         = errors.New("invalid PID")
+	// ErrStartCommand indicates that the underlying command failed to start.
+	ErrStartCommand = errors.New("failed to start command")
+
+	// ErrInvalidPID indicates that an invalid PID was used when attempting to signal.
+	ErrInvalidPID = errors.New("invalid PID")
+
+	// ErrProcessGroupSignal indicates failure when sending a signal to a process group.
 	ErrProcessGroupSignal = errors.New("failed to send signal to process group")
 )
 
 type Process struct {
-	cmd     cmdrunner.Command
-	runner  cmdrunner.Runner
+	// cmd is the underlying command abstraction.
+	cmd cmdrunner.Command
+
+	// runner is used to send signals (e.g., kill process group).
+	runner cmdrunner.Runner
+
+	// timeout defines how long to wait after SIGTERM before sending SIGKILL.
+	// If nil, the process group is killed immediately with SIGKILL.
 	timeout *time.Duration
 }
 
@@ -36,10 +49,15 @@ func StartProcess(
 ) (*Process, error) {
 	cmd := runner.Command(command, args...)
 
+	// Ensure the command runs in its own process group.
+	// This allows signaling the entire group (including children)
+	// by sending a signal to -pid.
 	//nolint:exhaustruct
 	cmd.SetSysProcAttr(&syscall.SysProcAttr{
 		Setpgid: true,
 	})
+
+	// Redirect both stdout and stderr to the provided writer.
 	cmd.SetStdout(writer)
 	cmd.SetStderr(writer)
 
@@ -55,17 +73,24 @@ func StartProcess(
 }
 
 func (p *Process) WaitSync(ctx context.Context) (int, error) {
+	// done is closed when Wait() finishes.
+	// It is used to coordinate with terminateOnContextDone
+	// to avoid sending signals after the process already exited.
 	done := make(chan struct{})
+	defer close(done)
 
+	// Start a goroutine that listens for context cancellation
+	// and attempts to terminate the process group if needed.
 	go func() {
 		p.terminateOnContextDone(ctx, done)
 	}()
 
+	// Wait blocks until the process exits.
+	// According to the intended semantics, the result of Wait()
+	// has priority over a later ctx.Done().
 	err := p.cmd.Wait()
 
-	close(done)
-
-	return p.determineExitCodeAndError(ctx, err)
+	return p.exitFromWaitError(err)
 }
 
 type Result struct {
@@ -83,12 +108,9 @@ func (p *Process) WaitAsync(ctx context.Context) <-chan Result {
 		defer close(resultCh)
 
 		err := p.cmd.Wait()
-		exitCode, finalErr := p.determineExitCodeAndError(ctx, err)
+		exitCode, finalErr := p.exitFromWaitError(err)
 
-		resultCh <- Result{
-			ExitCode: exitCode,
-			Err:      finalErr,
-		}
+		resultCh <- Result{ExitCode: exitCode, Err: finalErr}
 	}()
 
 	go func() {
@@ -101,26 +123,46 @@ func (p *Process) WaitAsync(ctx context.Context) <-chan Result {
 func (p *Process) terminateOnContextDone(ctx context.Context, done <-chan struct{}) {
 	select {
 	case <-ctx.Done():
+		// If Wait() has already completed (done is closed),
+		// do not attempt to signal the process group.
+		// The result from Wait() is considered authoritative.
+		select {
+		case <-done:
+			return
+		default:
+		}
+
 		pid := p.cmd.Pid()
+		if pid <= 0 {
+			// Invalid PID: nothing to signal.
+			return
+		}
 
+		// If no grace timeout is defined,
+		// immediately kill the entire process group.
 		if p.timeout == nil {
 			_ = p.signalProcessGroup(pid, syscall.SIGKILL)
 
 			return
 		}
 
+		// First attempt graceful shutdown with SIGTERM.
 		_ = p.signalProcessGroup(pid, syscall.SIGTERM)
 
+		// Wait for either:
+		// - the grace timeout to expire (then send SIGKILL),
+		// - or the process to exit naturally (done closed).
 		t := time.NewTimer(*p.timeout)
 		defer t.Stop()
 
 		select {
 		case <-t.C:
 			_ = p.signalProcessGroup(pid, syscall.SIGKILL)
-		case <-done:
+		case <-done: // Process exited during grace period.
 		}
 
-	case <-done:
+	case <-done: // Process exited before context cancellation.
+		return
 	}
 }
 
@@ -129,25 +171,25 @@ func (p *Process) signalProcessGroup(pid int, sig syscall.Signal) error {
 		return fmt.Errorf("cannot send %s to process group: pid=%d: %w", sig, pid, ErrInvalidPID)
 	}
 
+	// Negative PID means: send signal to the process group
+	// whose PGID equals the absolute value of pid.
 	pgid := -pid
+
 	if err := p.runner.Kill(pgid, sig); err != nil {
-		return fmt.Errorf("failed to send %s to process group %d: %w: %w", sig, pgid, err, ErrProcessGroupSignal)
+		return fmt.Errorf(
+			"failed to send %s to process group %d: %w: %w",
+			sig,
+			pgid,
+			err,
+			ErrProcessGroupSignal,
+		)
 	}
 
 	return nil
 }
 
-func (p *Process) determineExitCodeAndError(ctx context.Context, err error) (int, error) {
-	// If the context was canceled or timed out,
-	// it means the process was terminated externally.
-	if p.isTimeoutOrCanceled(ctx) {
-		// Return -1 and the context error.
-		//nolint:wrapcheck
-		return -1, ctx.Err()
-	}
-
-	// If Wait() returned no error,
-	// the process exited normally (exit code available in ProcessState).
+func (p *Process) exitFromWaitError(err error) (int, error) {
+	// No error from Wait(): process exited normally.
 	if err == nil {
 		if ps := p.cmd.ProcessState(); ps != nil {
 			return ps.ExitCode(), nil
@@ -163,22 +205,18 @@ func (p *Process) determineExitCodeAndError(ctx context.Context, err error) (int
 	// OR it was terminated by a signal.
 	var exitErr *exec.ExitError
 	if errors.As(err, &exitErr) {
-		// On Unix systems, we can check the WaitStatus.
-		// If the process was terminated by a signal,
-		// it means external intervention (SIGTERM/SIGKILL).
+		// On Unix systems, WaitStatus allows distinguishing
+		// between normal exit and signal-based termination.
 		if status, ok := exitErr.Sys().(syscall.WaitStatus); ok && status.Signaled() {
+			// Terminated by a signal (e.g., SIGTERM/SIGKILL).
 			return -1, err
 		}
 
-		// Otherwise, the process exited normally (even if exit code != 0).
-		// In this case, exit code is a valid result and error is nil.
+		// Exited normally with a non-zero exit code.
+		// In this case, the exit code is returned and error is nil.
 		return exitErr.ExitCode(), nil
 	}
 
-	// Any other error from Wait() is treated as an external/infrastructure error.
+	// Any other error from Wait() is treated as an infrastructure/runtime error.
 	return -1, err
 }
-
-func (p *Process) isTimeoutOrCanceled(ctx context.Context) bool {
-	return ctx.Err() != nil && (errors.Is(ctx.Err(), context.DeadlineExceeded) || errors.Is(ctx.Err(), context.Canceled))
-}
diff --git a/pkg/router/handlers/execution_handler_test.go b/pkg/router/handlers/execution_handler_test.go
index 9e0c8fc..28257ec 100644
--- a/pkg/router/handlers/execution_handler_test.go
+++ b/pkg/router/handlers/execution_handler_test.go
@@ -1348,8 +1348,12 @@ func TestExecutionHandler_TerminateOnCancel_NoGrace_SendsSIGKILL(t *testing.T) {
 	}
 
 	errMsg := rr.Header().Get("X-Error-Message")
-	if !strings.Contains(errMsg, "context canceled") {
-		t.Errorf("expected X-Error-Message header to contain %q, got %q", "context canceled", errMsg)
+	if errMsg == "" {
+		t.Fatalf("expected X-Error-Message header to be set")
+	}
+
+	if !strings.Contains(errMsg, "wait error") {
+		t.Errorf("expected X-Error-Message header to contain %q, got %q", "wait error", errMsg)
 	}
 }
 
@@ -1471,7 +1475,7 @@ func TestExecutionHandler_TerminateOnCancel_WithGrace_ProcessEndsBeforeTimer_Sen
 	}
 }
 
-func TestExecutionHandler_DeadlineExceeded_PrioritizesCtxErrOverExitError(t *testing.T) {
+func TestExecutionHandler_DeadlineExceeded_DoesNotOverrideWaitResult(t *testing.T) {
 	t.Parallel()
 
 	ctrl := gomock.NewController(t)
@@ -1484,7 +1488,6 @@ func TestExecutionHandler_DeadlineExceeded_PrioritizesCtxErrOverExitError(t *tes
 	runErr := exec.Command("sh", "-c", "exit 7").Run()
 
 	var exitErr *exec.ExitError
-
 	if !errors.As(runErr, &exitErr) {
 		t.Fatalf("expected *exec.ExitError, got %T: %v", runErr, runErr)
 	}
@@ -1507,6 +1510,7 @@ func TestExecutionHandler_DeadlineExceeded_PrioritizesCtxErrOverExitError(t *tes
 	// Prevent signalProcessGroup from calling runner.Kill.
 	mockCmd.EXPECT().Pid().Return(0).AnyTimes()
 
+	// Wait returns exit error (exit code 7).
 	mockCmd.EXPECT().Wait().Return(exitErr)
 	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
 
@@ -1528,19 +1532,17 @@ func TestExecutionHandler_DeadlineExceeded_PrioritizesCtxErrOverExitError(t *tes
 		t.Errorf("expected status 200, got %d", rr.Code)
 	}
 
+	// Wait() result wins over context cancellation, so we should report exit code 7.
 	exitCodeHeader := rr.Header().Get("X-Exit-Code")
-	if exitCodeHeader != "" {
-		t.Errorf("expected X-Exit-Code header to be empty, got %q", exitCodeHeader)
+	if exitCodeHeader != "7" {
+		t.Errorf("expected X-Exit-Code header to be %q, got %q", "7", exitCodeHeader)
 	}
 
+	// Since non-zero exit is treated as a normal result (exit code + nil error),
+	// there should be no context-related error message.
 	errMsg := rr.Header().Get("X-Error-Message")
-	if !strings.Contains(errMsg, "context deadline exceeded") {
-		t.Errorf("expected X-Error-Message header to contain %q, got %q", "context deadline exceeded", errMsg)
-	}
-
-	// Make sure it did not report the process exit code (7) as primary.
-	if exitCodeHeader == "7" {
-		t.Errorf("did not expect exit code 7 to be reported, got %q", exitCodeHeader)
+	if errMsg != "" {
+		t.Errorf("expected X-Error-Message header to be empty, got %q", errMsg)
 	}
 }
 
diff --git a/test/integration/server_test.go b/test/integration/server_test.go
index 24f190c..631cdd6 100644
--- a/test/integration/server_test.go
+++ b/test/integration/server_test.go
@@ -194,8 +194,10 @@ func TestServerIntegration(t *testing.T) {
 		}
 
 		errMsg := rec.Header().Get("X-Error-Message")
-		if !strings.Contains(errMsg, "context deadline exceeded") {
-			t.Errorf("Expected timeout error message in X-Error-Message header, got %q", errMsg)
+		expectedMsg := "process wait failed: signal: killed"
+
+		if errMsg != expectedMsg {
+			t.Errorf("Expected timeout error message in X-Error-Message header to be %q, got %q", expectedMsg, errMsg)
 		}
 	})
 

From 7ae3ccb1d64a866a3aaa93e6f4494c77ba9d7b93 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Tue, 3 Mar 2026 21:14:14 +0100
Subject: [PATCH 26/38] fix(cmdrunner): send signal to provided PID without
 implicit PGID negation

---
 pkg/cmdrunner/cmdrunner.go | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/pkg/cmdrunner/cmdrunner.go b/pkg/cmdrunner/cmdrunner.go
index 648ac80..2560252 100644
--- a/pkg/cmdrunner/cmdrunner.go
+++ b/pkg/cmdrunner/cmdrunner.go
@@ -60,6 +60,9 @@ func (c *realCommand) Pid() int {
 	return c.Cmd.Process.Pid
 }
 
+// compile-time interface check.
+var _ Command = (*realCommand)(nil)
+
 // RealRunner is a real implementation of the Runner interface.
 type RealRunner struct{}
 
@@ -68,8 +71,13 @@ func (r *RealRunner) Command(name string, arg ...string) Command {
 	return &realCommand{exec.Command(name, arg...)}
 }
 
-// Kill sends a signal to a process group.
+// Kill sends a signal to a process or process group.
+// If pid > 0, the signal is sent to the process with that PID.
+// If pid < 0, the signal is sent to the process group with ID = -pid.
 func (r *RealRunner) Kill(pid int, sig syscall.Signal) error {
 	//nolint:wrapcheck
-	return syscall.Kill(-pid, sig)
+	return syscall.Kill(pid, sig)
 }
+
+// compile-time interface check.
+var _ Runner = (*RealRunner)(nil)

From 61c3fac3e652d9f77d62b5fe658939e3692483cb Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 4 Mar 2026 09:56:15 +0100
Subject: [PATCH 27/38] test(cmdrunner): add integration tests

---
 .gitignore                                  |   4 +
 pkg/cmdrunner/cmdrunner_integration_test.go | 368 ++++++++++++++++++++
 2 files changed, 372 insertions(+)
 create mode 100644 pkg/cmdrunner/cmdrunner_integration_test.go

diff --git a/.gitignore b/.gitignore
index e6495f0..9ed6936 100644
--- a/.gitignore
+++ b/.gitignore
@@ -35,3 +35,7 @@ webcmd
 
 key.pem
 cert.pem
+
+*notes*.txt
+*notes*.md
+
diff --git a/pkg/cmdrunner/cmdrunner_integration_test.go b/pkg/cmdrunner/cmdrunner_integration_test.go
new file mode 100644
index 0000000..9edb218
--- /dev/null
+++ b/pkg/cmdrunner/cmdrunner_integration_test.go
@@ -0,0 +1,368 @@
+//go:build integration
+
+//nolint:paralleltest
+package cmdrunner_test
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os/exec"
+	"strings"
+	"sync"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/dkarczmarski/webcmd/pkg/cmdrunner"
+)
+
+const (
+	shortTimeout = 2 * time.Second
+	longTimeout  = 5 * time.Second
+)
+
+func TestSuccessfulCommandExitCodeZero(t *testing.T) {
+	r := &cmdrunner.RealRunner{}
+
+	c := startShellCommand(t, r, "echo hello")
+	if err := waitWithTimeout(t, c, shortTimeout); err != nil {
+		t.Fatalf("Wait() returned error for successful command: %v", err)
+	}
+
+	ps := c.ProcessState()
+	if ps == nil {
+		t.Fatalf("expected ProcessState() to be non-nil after Wait()")
+	}
+
+	if got := ps.ExitCode(); got != 0 {
+		t.Fatalf("expected exit code 0, got %d", got)
+	}
+}
+
+func TestFailingCommandExitCodeNonZero(t *testing.T) {
+	r := &cmdrunner.RealRunner{}
+
+	c := startShellCommand(t, r, "exit 42")
+	err := waitWithTimeout(t, c, shortTimeout)
+
+	if err == nil {
+		t.Fatalf("expected Wait() to return error for non-zero exit")
+	}
+
+	var ee *exec.ExitError
+	if !errors.As(err, &ee) {
+		t.Fatalf("expected *exec.ExitError, got %T: %v", err, err)
+	}
+
+	ps := c.ProcessState()
+	if ps == nil {
+		t.Fatalf("expected ProcessState() to be non-nil after Wait()")
+	}
+
+	if got := ps.ExitCode(); got != 42 {
+		t.Fatalf("expected exit code 42, got %d", got)
+	}
+}
+
+func TestStartNonExistingBinaryReturnsError(t *testing.T) {
+	r := &cmdrunner.RealRunner{}
+
+	c := r.Command("__not_a_cmd__")
+	if err := c.Start(); err == nil {
+		t.Fatalf("expected Start() to fail for non-existing binary")
+	}
+
+	// Pid() should remain 0 because the process was never started.
+	if got := c.Pid(); got != 0 {
+		t.Fatalf("expected Pid() == 0 when Start() fails, got %d", got)
+	}
+}
+
+func TestStdoutRedirectionWorks(t *testing.T) {
+	r := &cmdrunner.RealRunner{}
+
+	var out bytes.Buffer
+
+	c := r.Command("sh", "-c", "printf 'abc'")
+	c.SetStdout(&out)
+
+	if err := c.Start(); err != nil {
+		t.Fatalf("Start() failed: %v", err)
+	}
+
+	if err := waitWithTimeout(t, c, shortTimeout); err != nil {
+		t.Fatalf("Wait() failed: %v", err)
+	}
+
+	if got := out.String(); got != "abc" {
+		t.Fatalf("expected stdout %q, got %q", "abc", got)
+	}
+}
+
+func TestStderrRedirectionWorks(t *testing.T) {
+	r := &cmdrunner.RealRunner{}
+
+	var errBuf bytes.Buffer
+
+	c := r.Command("sh", "-c", "printf 'err' 1>&2")
+
+	c.SetStderr(&errBuf)
+
+	if err := c.Start(); err != nil {
+		t.Fatalf("Start() failed: %v", err)
+	}
+
+	if err := waitWithTimeout(t, c, shortTimeout); err != nil {
+		t.Fatalf("Wait() failed: %v", err)
+	}
+
+	if got := errBuf.String(); got != "err" {
+		t.Fatalf("expected stderr %q, got %q", "err", got)
+	}
+}
+
+func TestCombinedStdoutAndStderrToSingleWriter(t *testing.T) {
+	r := &cmdrunner.RealRunner{}
+
+	var combined bytes.Buffer
+
+	c := r.Command("sh", "-c", "echo out; echo err 1>&2")
+
+	c.SetStdout(&combined)
+	c.SetStderr(&combined)
+
+	if err := c.Start(); err != nil {
+		t.Fatalf("Start() failed: %v", err)
+	}
+
+	if err := waitWithTimeout(t, c, shortTimeout); err != nil {
+		t.Fatalf("Wait() failed: %v", err)
+	}
+
+	got := combined.String()
+	// Order is not guaranteed; just verify both are present.
+	if !strings.Contains(got, "out") || !strings.Contains(got, "err") {
+		t.Fatalf("expected combined output to contain both 'out' and 'err', got %q", got)
+	}
+}
+
+func TestKillProcessByPidSIGTERM(t *testing.T) {
+	r := &cmdrunner.RealRunner{}
+
+	c := startShellCommand(t, r, "sleep 30")
+	pid := c.Pid()
+
+	if pid <= 0 {
+		t.Fatalf("expected valid pid, got %d", pid)
+	}
+
+	if err := r.Kill(pid, syscall.SIGTERM); err != nil {
+		t.Fatalf("Kill(pid, SIGTERM) failed: %v", err)
+	}
+
+	// Process should exit quickly after SIGTERM.
+	_ = waitWithTimeout(t, c, longTimeout)
+
+	// We avoid asserting a specific exit code because shells/wrappers can map signals differently.
+
+	ps := c.ProcessState()
+	if ps == nil {
+		t.Fatalf("expected ProcessState() to be non-nil after Wait()")
+	}
+}
+
+func TestKillProcessGroupByNegativePidSIGTERM(t *testing.T) {
+	r := &cmdrunner.RealRunner{}
+
+	// This command creates a new process group so that killing -pid targets the group.
+	// The script starts a background sleep plus a foreground sleep.
+	c := r.Command("sh", "-c", "(sleep 30) & sleep 30")
+	c.SetSysProcAttr(&syscall.SysProcAttr{Setpgid: true})
+
+	if err := c.Start(); err != nil {
+		t.Fatalf("Start() failed: %v", err)
+	}
+
+	pid := c.Pid()
+	if pid <= 0 {
+		t.Fatalf("expected valid pid, got %d", pid)
+	}
+
+	// Give the shell a moment to spawn the background process.
+	time.Sleep(150 * time.Millisecond)
+
+	// Kill the entire process group: pid < 0 targets process group id = -pid.
+	if err := r.Kill(-pid, syscall.SIGTERM); err != nil {
+		t.Fatalf("Kill(-pid, SIGTERM) failed: %v", err)
+	}
+
+	// The group should terminate quickly.
+	_ = waitWithTimeout(t, c, longTimeout)
+
+	ps := c.ProcessState()
+	if ps == nil {
+		t.Fatalf("expected ProcessState() to be non-nil after Wait()")
+	}
+}
+
+func TestKillAfterProcessExitReturnsESRCH(t *testing.T) {
+	r := &cmdrunner.RealRunner{}
+
+	c := startShellCommand(t, r, "true")
+	pid := c.Pid()
+
+	if pid <= 0 {
+		t.Fatalf("expected valid pid, got %d", pid)
+	}
+
+	if err := waitWithTimeout(t, c, shortTimeout); err != nil {
+		t.Fatalf("Wait() failed: %v", err)
+	}
+
+	err := r.Kill(pid, syscall.SIGTERM)
+	if err == nil {
+		t.Fatalf("expected Kill() to fail for already-exited process")
+	}
+
+	// On Linux, killing a non-existing pid typically returns ESRCH.
+	if !errors.Is(err, syscall.ESRCH) {
+		t.Fatalf("expected ESRCH, got %T: %v", err, err)
+	}
+}
+
+func TestParallelStartsAndWaits(t *testing.T) {
+	r := &cmdrunner.RealRunner{}
+
+	const n = 10
+
+	var wg sync.WaitGroup
+
+	wg.Add(n)
+
+	errCh := make(chan error, n)
+
+	for i := range n {
+		go func(i int) {
+			defer wg.Done()
+
+			// Each command prints a unique token.
+			script := fmt.Sprintf("echo token_%d", i)
+			c := r.Command("sh", "-c", script)
+
+			var out bytes.Buffer
+
+			c.SetStdout(&out)
+
+			if err := c.Start(); err != nil {
+				errCh <- fmt.Errorf("function Start() failed (i=%d): %w", i, err)
+
+				return
+			}
+
+			if c.Pid() <= 0 {
+				errCh <- fmt.Errorf("invalid pid (i=%d): %d", i, c.Pid())
+
+				return
+			}
+
+			if err := waitWithTimeout(t, c, shortTimeout); err != nil {
+				errCh <- fmt.Errorf("function Wait() failed (i=%d): %w", i, err)
+
+				return
+			}
+
+			if !strings.Contains(out.String(), fmt.Sprintf("token_%d", i)) {
+				errCh <- fmt.Errorf("unexpected stdout (i=%d): %q", i, out.String())
+
+				return
+			}
+		}(i)
+	}
+
+	wg.Wait()
+	close(errCh)
+
+	for err := range errCh {
+		t.Error(err)
+	}
+}
+
+func TestPidIsZeroBeforeStartAndNonZeroAfterStart(t *testing.T) {
+	r := &cmdrunner.RealRunner{}
+
+	c := r.Command("sh", "-c", "sleep 0.2")
+	if got := c.Pid(); got != 0 {
+		t.Fatalf("expected Pid() == 0 before Start(), got %d", got)
+	}
+
+	if err := c.Start(); err != nil {
+		t.Fatalf("Start() failed: %v", err)
+	}
+
+	if got := c.Pid(); got <= 0 {
+		t.Fatalf("expected Pid() > 0 after Start(), got %d", got)
+	}
+
+	_ = waitWithTimeout(t, c, shortTimeout)
+}
+
+func TestProcessStateNilBeforeWaitNonNilAfterWait(t *testing.T) {
+	r := &cmdrunner.RealRunner{}
+
+	c := r.Command("sh", "-c", "sleep 0.2")
+
+	// Before Start(), ProcessState should be nil.
+	if ps := c.ProcessState(); ps != nil {
+		t.Fatalf("expected ProcessState() == nil before Start(), got %+v", ps)
+	}
+
+	if err := c.Start(); err != nil {
+		t.Fatalf("Start() failed: %v", err)
+	}
+
+	// After Start() but before Wait(), ProcessState is typically still nil.
+	if ps := c.ProcessState(); ps != nil {
+		// We keep this as a strict assertion to catch unexpected behavior changes.
+		t.Fatalf("expected ProcessState() == nil before Wait(), got %+v", ps)
+	}
+
+	if err := waitWithTimeout(t, c, shortTimeout); err != nil {
+		t.Fatalf("Wait() failed: %v", err)
+	}
+
+	if ps := c.ProcessState(); ps == nil {
+		t.Fatalf("expected ProcessState() to be non-nil after Wait()")
+	}
+}
+
+// startShellCommand creates and starts: sh -c <script>.
+func startShellCommand(t *testing.T, r cmdrunner.Runner, script string) cmdrunner.Command {
+	t.Helper()
+
+	c := r.Command("sh", "-c", script)
+	if err := c.Start(); err != nil {
+		t.Fatalf("Start() failed: %v (script=%q)", err, script)
+	}
+
+	return c
+}
+
+// waitWithTimeout waits for cmd.Wait() with a timeout to avoid hanging tests.
+func waitWithTimeout(t *testing.T, c cmdrunner.Command, timeout time.Duration) error {
+	t.Helper()
+
+	errCh := make(chan error, 1)
+	go func() {
+		errCh <- c.Wait()
+	}()
+
+	select {
+	case err := <-errCh:
+		return err
+	case <-time.After(timeout):
+		t.Fatalf("command did not exit within %s", timeout)
+
+		return nil
+	}
+}

From 262f763714132987a2c6a3911dcf309e989b5eef Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 4 Mar 2026 10:06:00 +0100
Subject: [PATCH 28/38] refactor(processrunner): rename file

---
 pkg/processrunner/{process_runner.go => processrunner.go} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename pkg/processrunner/{process_runner.go => processrunner.go} (100%)

diff --git a/pkg/processrunner/process_runner.go b/pkg/processrunner/processrunner.go
similarity index 100%
rename from pkg/processrunner/process_runner.go
rename to pkg/processrunner/processrunner.go

From 84646194cb9d1a86d311780f243c2ae24dd04000 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 4 Mar 2026 19:00:59 +0100
Subject: [PATCH 29/38] feat(processrunner): expose process PID and PGID

---
 pkg/processrunner/processrunner.go | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/pkg/processrunner/processrunner.go b/pkg/processrunner/processrunner.go
index 74a45fb..93d3c61 100644
--- a/pkg/processrunner/processrunner.go
+++ b/pkg/processrunner/processrunner.go
@@ -220,3 +220,23 @@ func (p *Process) exitFromWaitError(err error) (int, error) {
 	// Any other error from Wait() is treated as an infrastructure/runtime error.
 	return -1, err
 }
+
+// Pid returns PID of the underlying process (0 if not started / unknown).
+func (p *Process) Pid() int {
+	if p == nil || p.cmd == nil {
+		return 0
+	}
+
+	return p.cmd.Pid()
+}
+
+// ProcessGroupID returns PGID (on Unix). On error returns 0 and error.
+func (p *Process) ProcessGroupID() (int, error) {
+	pid := p.Pid()
+	if pid <= 0 {
+		return 0, ErrInvalidPID
+	}
+
+	//nolint: wrapcheck
+	return syscall.Getpgid(pid)
+}

From 6c8ebf71dc85babcc84822366f3647fa85ca94af Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 4 Mar 2026 19:11:13 +0100
Subject: [PATCH 30/38] feat(processrunner): add WithSignalObserver option for
 observing sent signals

---
 pkg/processrunner/processrunner.go | 26 ++++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/pkg/processrunner/processrunner.go b/pkg/processrunner/processrunner.go
index 93d3c61..a702cf4 100644
--- a/pkg/processrunner/processrunner.go
+++ b/pkg/processrunner/processrunner.go
@@ -28,6 +28,8 @@ var (
 	ErrProcessGroupSignal = errors.New("failed to send signal to process group")
 )
 
+type SignalObserver func(pgid int, sig syscall.Signal)
+
 type Process struct {
 	// cmd is the underlying command abstraction.
 	cmd cmdrunner.Command
@@ -38,6 +40,14 @@ type Process struct {
 	// timeout defines how long to wait after SIGTERM before sending SIGKILL.
 	// If nil, the process group is killed immediately with SIGKILL.
 	timeout *time.Duration
+
+	onSignal SignalObserver
+}
+
+type Option func(*Process)
+
+func WithSignalObserver(obs SignalObserver) Option {
+	return func(p *Process) { p.onSignal = obs }
 }
 
 func StartProcess(
@@ -46,6 +56,7 @@ func StartProcess(
 	args []string,
 	writer io.Writer,
 	graceTimeout *time.Duration,
+	opts ...Option,
 ) (*Process, error) {
 	cmd := runner.Command(command, args...)
 
@@ -65,11 +76,18 @@ func StartProcess(
 		return nil, fmt.Errorf("%w: %w", ErrStartCommand, err)
 	}
 
-	return &Process{
+	//nolint:exhaustruct
+	proc := &Process{
 		cmd:     cmd,
 		runner:  runner,
 		timeout: graceTimeout,
-	}, nil
+	}
+
+	for _, opt := range opts {
+		opt(proc)
+	}
+
+	return proc, nil
 }
 
 func (p *Process) WaitSync(ctx context.Context) (int, error) {
@@ -175,6 +193,10 @@ func (p *Process) signalProcessGroup(pid int, sig syscall.Signal) error {
 	// whose PGID equals the absolute value of pid.
 	pgid := -pid
 
+	if p.onSignal != nil {
+		p.onSignal(pgid, sig)
+	}
+
 	if err := p.runner.Kill(pgid, sig); err != nil {
 		return fmt.Errorf(
 			"failed to send %s to process group %d: %w: %w",

From b2ab10ed9e4310722db9d6b05325fd59ce0e4030 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Wed, 4 Mar 2026 21:45:20 +0100
Subject: [PATCH 31/38] test(processrunner): add intergration tests

---
 pkg/processrunner/helpers_test.go             | 134 ++++
 .../processrunner_integration_test.go         | 579 ++++++++++++++++++
 2 files changed, 713 insertions(+)
 create mode 100644 pkg/processrunner/helpers_test.go
 create mode 100644 pkg/processrunner/processrunner_integration_test.go

diff --git a/pkg/processrunner/helpers_test.go b/pkg/processrunner/helpers_test.go
new file mode 100644
index 0000000..755cc92
--- /dev/null
+++ b/pkg/processrunner/helpers_test.go
@@ -0,0 +1,134 @@
+package processrunner_test
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"strings"
+	"sync"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/dkarczmarski/webcmd/pkg/cmdrunner"
+	"github.com/dkarczmarski/webcmd/pkg/processrunner"
+)
+
+// syncBuffer is a thread-safe bytes.Buffer.
+// We need it because the process writes stdout/stderr concurrently.
+type syncBuffer struct {
+	mu sync.Mutex
+	b  bytes.Buffer
+}
+
+//nolint:wrapcheck
+func (s *syncBuffer) Write(p []byte) (int, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	return s.b.Write(p)
+}
+
+func (s *syncBuffer) String() string {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	return s.b.String()
+}
+
+func mustStartShell(
+	t *testing.T,
+	runner cmdrunner.Runner,
+	w *syncBuffer,
+	grace *time.Duration,
+	opts []processrunner.Option,
+	script string,
+) *processrunner.Process {
+	t.Helper()
+
+	p, err := processrunner.StartProcess(
+		runner,
+		"sh",
+		[]string{"-c", script},
+		w,
+		grace,
+		opts...,
+	)
+	if err != nil {
+		t.Fatalf("StartProcess failed: %v", err)
+	}
+
+	return p
+}
+
+func waitForSubstring(t *testing.T, w *syncBuffer, sub string, timeout time.Duration) {
+	t.Helper()
+
+	// Polling is intentional: stdout/stderr is asynchronous and ordering is not guaranteed.
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		if strings.Contains(w.String(), sub) {
+			return
+		}
+
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	t.Fatalf("timeout waiting for substring %q in output. got=%q", sub, w.String())
+}
+
+func waitSyncWithTimeout(
+	t *testing.T,
+	ctx context.Context, //nolint:revive
+	p *processrunner.Process,
+	timeout time.Duration, //nolint:unparam
+) (int, error) {
+	t.Helper()
+
+	// WaitSync is blocking; run it in a goroutine so we can enforce an upper bound.
+	type res struct {
+		code int
+		err  error
+	}
+
+	ch := make(chan res, 1)
+
+	go func() {
+		code, err := p.WaitSync(ctx)
+		ch <- res{code: code, err: err}
+	}()
+
+	select {
+	case r := <-ch:
+		return r.code, r.err
+	case <-time.After(timeout):
+		t.Fatalf("WaitSync timed out after %s", timeout)
+
+		// Unreachable because Fatalf stops the test, but required for compilation.
+		return 0, errors.New("unreachable")
+	}
+}
+
+func waitForProcessGone(t *testing.T, pid int, timeout time.Duration) {
+	t.Helper()
+
+	// kill(pid, 0) is an existence check.
+	// We poll because the process may briefly remain as a zombie / not yet be reaped.
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		err := syscall.Kill(pid, 0)
+		if err != nil && errors.Is(err, syscall.ESRCH) {
+			return
+		}
+
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	// One last check for a better error message.
+	err := syscall.Kill(pid, 0)
+	if err == nil {
+		t.Fatalf("expected process %d to be gone, but kill(0) still succeeds", pid)
+	}
+
+	t.Fatalf("expected process %d to be gone; last kill(0) err=%v", pid, err)
+}
diff --git a/pkg/processrunner/processrunner_integration_test.go b/pkg/processrunner/processrunner_integration_test.go
new file mode 100644
index 0000000..5e8465b
--- /dev/null
+++ b/pkg/processrunner/processrunner_integration_test.go
@@ -0,0 +1,579 @@
+//go:build integration
+
+//nolint:paralleltest
+package processrunner_test
+
+import (
+	"context"
+	"errors"
+	"regexp"
+	"strconv"
+	"strings"
+	"sync"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/dkarczmarski/webcmd/pkg/cmdrunner"
+	"github.com/dkarczmarski/webcmd/pkg/processrunner"
+)
+
+func Test_StartProcess_RedirectsStdoutAndStderrToWriter(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	p := mustStartShell(t, runner, &w, nil, nil, `echo out; echo err 1>&2`)
+
+	code, err := p.WaitSync(t.Context())
+	if err != nil {
+		t.Fatalf("expected nil error, got: %v", err)
+	}
+
+	if code != 0 {
+		t.Fatalf("expected exit code 0, got: %d", code)
+	}
+
+	out := w.String()
+
+	if !strings.Contains(out, "out") {
+		t.Fatalf("expected output to contain %q, got: %q", "out", out)
+	}
+
+	if !strings.Contains(out, "err") {
+		t.Fatalf("expected output to contain %q, got: %q", "err", out)
+	}
+}
+
+func Test_StartProcess_ReturnsErrStartCommand_WhenBinaryMissing(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	_, err := processrunner.StartProcess(runner, "__no_such_binary__", nil, &w, nil)
+	if err == nil {
+		t.Fatalf("expected error, got nil")
+	}
+
+	if !errors.Is(err, processrunner.ErrStartCommand) {
+		t.Fatalf("expected ErrStartCommand, got: %v", err)
+	}
+}
+
+func Test_StartProcess_SetsOwnProcessGroup_Setpgid(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	p := mustStartShell(t, runner, &w, nil, nil, `sleep 10`)
+
+	t.Cleanup(func() {
+		// Ensure cleanup even if the test fails early.
+		ctx, cancel := context.WithCancel(t.Context())
+		cancel()
+
+		_, _ = waitSyncWithTimeout(t, ctx, p, 2*time.Second)
+	})
+
+	pid := p.Pid()
+	if pid <= 0 {
+		t.Fatalf("expected pid > 0, got: %d", pid)
+	}
+
+	pgid, err := p.ProcessGroupID()
+	if err != nil {
+		t.Fatalf("ProcessGroupID failed: %v", err)
+	}
+
+	// With Setpgid=true we expect the process to be the leader of its own group.
+	if pgid != pid {
+		t.Fatalf("expected pgid == pid (setpgid), got pgid=%d pid=%d", pgid, pid)
+	}
+}
+
+func Test_WaitSync_Exit0_ReturnsZeroAndNil(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	p := mustStartShell(t, runner, &w, nil, nil, `exit 0`)
+
+	code, err := p.WaitSync(t.Context())
+	if err != nil || code != 0 {
+		t.Fatalf("expected (0,nil), got (%d,%v)", code, err)
+	}
+}
+
+func Test_WaitSync_NonZeroExit_ReturnsExitCodeAndNilError(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	p := mustStartShell(t, runner, &w, nil, nil, `exit 7`)
+
+	code, err := p.WaitSync(t.Context())
+	// By design: normal non-zero exit returns the exit code and nil error.
+	if err != nil {
+		t.Fatalf("expected nil error for normal non-zero exit, got: %v", err)
+	}
+
+	if code != 7 {
+		t.Fatalf("expected exit code 7, got: %d", code)
+	}
+}
+
+func Test_WaitAsync_EmitsExactlyOneResult_ThenClosesChannel(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	p := mustStartShell(t, runner, &w, nil, nil, `exit 0`)
+
+	ch := p.WaitAsync(t.Context())
+
+	res, ok := <-ch
+	if !ok {
+		t.Fatalf("expected one result, channel closed")
+	}
+
+	if res.Err != nil || res.ExitCode != 0 {
+		t.Fatalf("expected {0,nil}, got {%d,%v}", res.ExitCode, res.Err)
+	}
+
+	_, ok = <-ch
+	if ok {
+		t.Fatalf("expected channel to be closed after one result")
+	}
+}
+
+func Test_WaitAsync_NonZeroExit_ReturnsExitCodeAndNilError(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	p := mustStartShell(t, runner, &w, nil, nil, `exit 13`)
+
+	ch := p.WaitAsync(t.Context())
+
+	res := <-ch
+
+	if res.Err != nil {
+		t.Fatalf("expected nil error for normal non-zero exit, got: %v", res.Err)
+	}
+
+	if res.ExitCode != 13 {
+		t.Fatalf("expected exit code 13, got: %d", res.ExitCode)
+	}
+}
+
+func Test_CancelCtx_KillsProcessGroupImmediately_WithSIGKILL_WhenNoGraceTimeout(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	var (
+		observedMu sync.Mutex
+		observed   []syscall.Signal
+	)
+
+	// SignalObserver gives deterministic assertions without timing-based heuristics.
+	obs := func(_ int, sig syscall.Signal) {
+		observedMu.Lock()
+		defer observedMu.Unlock()
+
+		observed = append(observed, sig)
+	}
+
+	opts := []processrunner.Option{processrunner.WithSignalObserver(obs)}
+
+	p := mustStartShell(t, runner, &w, nil, opts, `trap "" TERM; while true; do sleep 1; done`)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	done := make(chan struct{})
+
+	var (
+		code int
+		err  error
+	)
+
+	go func() {
+		defer close(done)
+
+		code, err = p.WaitSync(ctx)
+	}()
+
+	cancel()
+
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatalf("process did not terminate promptly after cancel")
+	}
+
+	if code != -1 {
+		t.Fatalf("expected exit code -1 for signal termination, got: %d", code)
+	}
+
+	if err == nil {
+		t.Fatalf("expected non-nil error for signal termination, got nil")
+	}
+
+	observedMu.Lock()
+	defer observedMu.Unlock()
+
+	foundKILL := false
+
+	for _, s := range observed {
+		if s == syscall.SIGKILL {
+			foundKILL = true
+
+			continue
+		}
+
+		if s == syscall.SIGTERM {
+			t.Fatalf("did not expect SIGTERM when graceTimeout is nil; observed=%v", observed)
+		}
+	}
+
+	if !foundKILL {
+		t.Fatalf("expected SIGKILL to be sent; observed=%v", observed)
+	}
+}
+
+func Test_CancelCtx_KillsChildProcess_UsingProcessGroupKill(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	p := mustStartShell(t, runner, &w, nil, nil, `sleep 100 & child=$!; echo child:$child; wait`)
+
+	waitForSubstring(t, &w, "child:", 1*time.Second)
+
+	re := regexp.MustCompile(`child:(\d+)`)
+	m := re.FindStringSubmatch(w.String())
+
+	if len(m) != 2 {
+		t.Fatalf("failed to parse child pid from output: %q", w.String())
+	}
+
+	childPID, err := strconv.Atoi(m[1])
+	if err != nil {
+		t.Fatalf("invalid child pid %q: %v", m[1], err)
+	}
+
+	ctx, cancel := context.WithCancel(t.Context())
+	cancel()
+
+	code, werr := waitSyncWithTimeout(t, ctx, p, 2*time.Second)
+	if code != -1 || werr == nil {
+		t.Fatalf("expected (-1, non-nil) after cancel kill, got (%d,%v)", code, werr)
+	}
+
+	// Main promise: cancelling context kills the whole process group, including background children.
+	waitForProcessGone(t, childPID, 1*time.Second)
+}
+
+func Test_CancelCtx_SendsSIGTERM_ThenSIGKILL_AfterGraceTimeout_WhenProcessIgnoresTERM(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	var (
+		observedMu sync.Mutex
+		observed   []syscall.Signal
+	)
+
+	obs := func(_ int, sig syscall.Signal) {
+		observedMu.Lock()
+		defer observedMu.Unlock()
+
+		observed = append(observed, sig)
+	}
+
+	grace := 200 * time.Millisecond
+	opts := []processrunner.Option{processrunner.WithSignalObserver(obs)}
+
+	// "ready" is printed AFTER trap is installed.
+	// Without this barrier, the test can cancel too early and kill the process
+	// before it starts ignoring SIGTERM, making the test flaky.
+	p := mustStartShell(t, runner, &w, &grace, opts, `trap "" TERM; echo ready; while true; do sleep 1; done`)
+
+	waitForSubstring(t, &w, "ready", 1*time.Second)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	cancel()
+
+	code, err := waitSyncWithTimeout(t, ctx, p, 2*time.Second)
+	if code != -1 || err == nil {
+		t.Fatalf("expected (-1, non-nil) after forced kill, got (%d,%v)", code, err)
+	}
+
+	observedMu.Lock()
+	defer observedMu.Unlock()
+
+	termIdx := -1
+	killIdx := -1
+
+	for i, s := range observed {
+		if s == syscall.SIGTERM && termIdx == -1 {
+			termIdx = i
+
+			continue
+		}
+
+		if s == syscall.SIGKILL && killIdx == -1 {
+			killIdx = i
+		}
+	}
+
+	if termIdx == -1 || killIdx == -1 {
+		t.Fatalf("expected to observe SIGTERM and SIGKILL; observed=%v", observed)
+	}
+
+	if termIdx > killIdx {
+		t.Fatalf("expected SIGTERM before SIGKILL; observed=%v", observed)
+	}
+}
+
+func Test_CancelCtx_AllowsGracefulExit_DuringGracePeriod_WithoutSIGKILL(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	var (
+		observedMu sync.Mutex
+		observed   []syscall.Signal
+	)
+
+	obs := func(_ int, sig syscall.Signal) {
+		observedMu.Lock()
+		defer observedMu.Unlock()
+
+		observed = append(observed, sig)
+	}
+
+	grace := 1 * time.Second
+	opts := []processrunner.Option{processrunner.WithSignalObserver(obs)}
+
+	// "ready" is printed AFTER trap is installed to avoid cancel-race flakiness.
+	p := mustStartShell(t, runner, &w, &grace, opts, `trap "exit 0" TERM; echo ready; while true; do sleep 1; done`)
+
+	waitForSubstring(t, &w, "ready", 1*time.Second)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	cancel()
+
+	code, err := waitSyncWithTimeout(t, ctx, p, 2*time.Second)
+	if err != nil {
+		t.Fatalf("expected nil error for graceful exit, got: %v", err)
+	}
+
+	if code != 0 {
+		t.Fatalf("expected exit code 0 for graceful exit, got: %d", code)
+	}
+
+	observedMu.Lock()
+	defer observedMu.Unlock()
+
+	foundTERM := false
+
+	for _, s := range observed {
+		if s == syscall.SIGTERM {
+			foundTERM = true
+
+			continue
+		}
+
+		if s == syscall.SIGKILL {
+			t.Fatalf("did not expect SIGKILL for graceful exit; observed=%v", observed)
+		}
+	}
+
+	if !foundTERM {
+		t.Fatalf("expected SIGTERM to be sent; observed=%v", observed)
+	}
+}
+
+func Test_WaitResultHasPriorityOverLaterContextCancel(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	p := mustStartShell(t, runner, &w, nil, nil, `sleep 0.05; exit 5`)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	// Cancel after the process has already exited; the Wait() result should win.
+	time.AfterFunc(80*time.Millisecond, cancel)
+
+	code, err := waitSyncWithTimeout(t, ctx, p, 2*time.Second)
+	if err != nil {
+		t.Fatalf("expected nil error for normal exit, got: %v", err)
+	}
+
+	if code != 5 {
+		t.Fatalf("expected exit code 5, got: %d", code)
+	}
+}
+
+func Test_CancelAfterWaitCompleted_HasNoSideEffects(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	p := mustStartShell(t, runner, &w, nil, nil, `exit 0`)
+
+	ch := p.WaitAsync(ctx)
+
+	res := <-ch
+	if res.Err != nil || res.ExitCode != 0 {
+		t.Fatalf("expected {0,nil}, got {%d,%v}", res.ExitCode, res.Err)
+	}
+
+	// Cancel after completion should not hang or panic.
+	cancel()
+
+	select {
+	case _, ok := <-ch:
+		if ok {
+			t.Fatalf("expected channel closed")
+		}
+	default:
+	}
+}
+
+func Test_CancelledContextBeforeWaitSync_KillsRunningProcess(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	p := mustStartShell(t, runner, &w, nil, nil, `while true; do sleep 1; done`)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	cancel()
+
+	code, err := waitSyncWithTimeout(t, ctx, p, 2*time.Second)
+	if code != -1 {
+		t.Fatalf("expected exit code -1 for signal termination, got: %d", code)
+	}
+
+	if err == nil {
+		t.Fatalf("expected non-nil error for signal termination, got nil")
+	}
+}
+
+func Test_OutputIsStreamedBeforeWaitCompletes(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	var w syncBuffer
+
+	p := mustStartShell(t, runner, &w, nil, nil, `echo one; sleep 0.2; echo two`)
+
+	// Verify streaming output: writer receives data before Wait completes.
+	waitForSubstring(t, &w, "one", 500*time.Millisecond)
+
+	code, err := p.WaitSync(t.Context())
+	if err != nil {
+		t.Fatalf("expected nil error, got: %v", err)
+	}
+
+	if code != 0 {
+		t.Fatalf("expected exit code 0, got: %d", code)
+	}
+
+	out := w.String()
+	if !strings.Contains(out, "two") {
+		t.Fatalf("expected output to contain %q, got: %q", "two", out)
+	}
+}
+
+func Test_WaitSyncAndWaitAsync_SemanticsAreConsistent(t *testing.T) {
+	runner := &cmdrunner.RealRunner{}
+
+	t.Run("exit 0", func(t *testing.T) {
+		var (
+			w1 syncBuffer
+			w2 syncBuffer
+		)
+
+		p1 := mustStartShell(t, runner, &w1, nil, nil, `exit 0`)
+
+		code1, err1 := p1.WaitSync(t.Context())
+
+		p2 := mustStartShell(t, runner, &w2, nil, nil, `exit 0`)
+
+		res2 := <-p2.WaitAsync(t.Context())
+
+		if code1 != res2.ExitCode || (err1 != nil) != (res2.Err != nil) {
+			t.Fatalf(
+				"mismatch: WaitSync=(%d,%v) WaitAsync={%d,%v}",
+				code1,
+				err1,
+				res2.ExitCode,
+				res2.Err,
+			)
+		}
+	})
+
+	t.Run("exit 9", func(t *testing.T) {
+		var (
+			w1 syncBuffer
+			w2 syncBuffer
+		)
+
+		p1 := mustStartShell(t, runner, &w1, nil, nil, `exit 9`)
+
+		code1, err1 := p1.WaitSync(t.Context())
+
+		p2 := mustStartShell(t, runner, &w2, nil, nil, `exit 9`)
+
+		res2 := <-p2.WaitAsync(t.Context())
+
+		if code1 != 9 || err1 != nil {
+			t.Fatalf("expected WaitSync=(9,nil), got (%d,%v)", code1, err1)
+		}
+
+		if res2.ExitCode != 9 || res2.Err != nil {
+			t.Fatalf("expected WaitAsync={9,nil}, got {%d,%v}", res2.ExitCode, res2.Err)
+		}
+	})
+
+	t.Run("killed by cancel", func(t *testing.T) {
+		var (
+			w1 syncBuffer
+			w2 syncBuffer
+		)
+
+		p1 := mustStartShell(t, runner, &w1, nil, nil, `while true; do sleep 1; done`)
+
+		ctx1, cancel1 := context.WithCancel(t.Context())
+		cancel1()
+
+		code1, err1 := waitSyncWithTimeout(t, ctx1, p1, 2*time.Second)
+
+		p2 := mustStartShell(t, runner, &w2, nil, nil, `while true; do sleep 1; done`)
+
+		ctx2, cancel2 := context.WithCancel(t.Context())
+		cancel2()
+
+		res2 := <-p2.WaitAsync(ctx2)
+
+		if code1 != -1 || err1 == nil {
+			t.Fatalf("expected WaitSync=(-1,non-nil), got (%d,%v)", code1, err1)
+		}
+
+		if res2.ExitCode != -1 || res2.Err == nil {
+			t.Fatalf("expected WaitAsync={-1,non-nil}, got {%d,%v}", res2.ExitCode, res2.Err)
+		}
+	})
+}

From 1f2457a811e28789092f8a57523db55237fc00a7 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Thu, 5 Mar 2026 16:25:22 +0100
Subject: [PATCH 32/38] refactor(processrunner): add ProcessRunner wrapper to
 decouple command runner

---
 pkg/processrunner/processrunner.go | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/pkg/processrunner/processrunner.go b/pkg/processrunner/processrunner.go
index a702cf4..aacdbb0 100644
--- a/pkg/processrunner/processrunner.go
+++ b/pkg/processrunner/processrunner.go
@@ -50,6 +50,28 @@ func WithSignalObserver(obs SignalObserver) Option {
 	return func(p *Process) { p.onSignal = obs }
 }
 
+// ProcessRunner is a small convenience wrapper that binds cmdrunner.Runner,
+// so callers don't have to pass it to StartProcess each time.
+// This is useful for dependency injection (e.g. in handlers/tests).
+type ProcessRunner struct {
+	runner cmdrunner.Runner
+}
+
+func New(runner cmdrunner.Runner) *ProcessRunner {
+	return &ProcessRunner{runner: runner}
+}
+
+// StartProcess starts a new process using the runner held by ProcessRunner.
+func (r *ProcessRunner) StartProcess(
+	command string,
+	args []string,
+	writer io.Writer,
+	graceTimeout *time.Duration,
+	opts ...Option,
+) (*Process, error) {
+	return StartProcess(r.runner, command, args, writer, graceTimeout, opts...)
+}
+
 func StartProcess(
 	runner cmdrunner.Runner,
 	command string,

From 97afd655908914fe144360f6c71919fd1b8a63a1 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Thu, 5 Mar 2026 17:57:40 +0100
Subject: [PATCH 33/38] refactor(tests): move handler tests to server
 integration tests

---
 test/integration/server_test.go             | 423 ++++++++++++++++----
 test/integration/test-data/test-config.yaml | 100 ++++-
 2 files changed, 450 insertions(+), 73 deletions(-)

diff --git a/test/integration/server_test.go b/test/integration/server_test.go
index 631cdd6..156cf3d 100644
--- a/test/integration/server_test.go
+++ b/test/integration/server_test.go
@@ -4,10 +4,12 @@ package integration_test
 
 import (
 	_ "embed"
+	"io"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/dkarczmarski/webcmd/pkg/config"
 	"github.com/dkarczmarski/webcmd/pkg/server"
@@ -16,30 +18,106 @@ import (
 //go:embed test-data/test-config.yaml
 var testConfigYaml string
 
-func TestServerIntegration(t *testing.T) {
+func setupServer(t *testing.T) *server.Server {
+	t.Helper()
+
+	configuration, err := config.LoadConfigFromString(testConfigYaml)
+	if err != nil {
+		t.Fatalf("Failed to load config: %v", err)
+	}
+
+	return server.New(configuration)
+}
+
+func TestServer_RoutingAndAuth(t *testing.T) {
 	t.Parallel()
 
-	setupServer := func(t *testing.T) *server.Server {
-		t.Helper()
+	t.Run("404 Not Found", func(t *testing.T) {
+		t.Parallel()
+		srv := setupServer(t)
 
-		configuration, err := config.LoadConfigFromString(testConfigYaml)
-		if err != nil {
-			t.Fatalf("Failed to load config: %v", err)
+		req := httptest.NewRequest(http.MethodGet, "/cmd/non-existent", nil)
+		req.Header.Set("X-Api-Key", "ABC111")
+
+		rec := httptest.NewRecorder()
+		srv.ServeHTTP(rec, req)
+
+		if rec.Code != http.StatusNotFound {
+			t.Errorf("Expected status code %d, got %d", http.StatusNotFound, rec.Code)
 		}
+	})
 
-		return server.New(configuration)
-	}
+	t.Run("401 Unauthorized - No API Key", func(t *testing.T) {
+		t.Parallel()
+		srv := setupServer(t)
+
+		req := httptest.NewRequest(http.MethodPost, "/cmd/echo", nil)
+		rec := httptest.NewRecorder()
+
+		srv.ServeHTTP(rec, req)
+
+		if rec.Code != http.StatusUnauthorized {
+			t.Errorf("Expected status code %d, got %d", http.StatusUnauthorized, rec.Code)
+		}
+	})
+
+	t.Run("401 Unauthorized - Invalid API Key", func(t *testing.T) {
+		t.Parallel()
+		srv := setupServer(t)
+
+		req := httptest.NewRequest(http.MethodPost, "/cmd/echo", nil)
+		req.Header.Set("X-Api-Key", "INVALID")
+
+		rec := httptest.NewRecorder()
+		srv.ServeHTTP(rec, req)
+
+		if rec.Code != http.StatusUnauthorized {
+			t.Errorf("Expected status code %d, got %d", http.StatusUnauthorized, rec.Code)
+		}
+	})
+
+	t.Run("403 Forbidden - Insufficient Permissions", func(t *testing.T) {
+		t.Parallel()
+		srv := setupServer(t)
+
+		req := httptest.NewRequest(http.MethodPost, "/cmd/forbidden", nil)
+		req.Header.Set("X-Api-Key", "ABC222") // auth-name2, but command needs auth-name1
+
+		rec := httptest.NewRecorder()
+		srv.ServeHTTP(rec, req)
+
+		if rec.Code != http.StatusForbidden {
+			t.Errorf("Expected status code %d, got %d", http.StatusForbidden, rec.Code)
+		}
+	})
+
+	t.Run("Method Not Allowed (treated as 404)", func(t *testing.T) {
+		t.Parallel()
+		srv := setupServer(t)
+
+		// /cmd/echo is POST, trying GET
+		req := httptest.NewRequest(http.MethodGet, "/cmd/echo", nil)
+		rec := httptest.NewRecorder()
+
+		srv.ServeHTTP(rec, req)
+
+		if rec.Code != http.StatusNotFound {
+			t.Errorf("Expected status code %d, got %d", http.StatusNotFound, rec.Code)
+		}
+	})
+}
+
+func TestServer_CommandExecution(t *testing.T) {
+	t.Parallel()
 
 	t.Run("POST /cmd/echo", func(t *testing.T) {
 		t.Parallel()
 		srv := setupServer(t)
 
 		req := httptest.NewRequest(http.MethodPost, "/cmd/echo?param1=hello", nil)
-
 		req.Header.Set("X-Api-Key", "ABC111")
 
 		rec := httptest.NewRecorder()
-
 		srv.ServeHTTP(rec, req)
 
 		if rec.Code != http.StatusOK {
@@ -71,6 +149,57 @@ func TestServerIntegration(t *testing.T) {
 		}
 	})
 
+	t.Run("Command failure - Exit Code 1", func(t *testing.T) {
+		t.Parallel()
+		srv := setupServer(t)
+
+		req := httptest.NewRequest(http.MethodGet, "/cmd/false", nil)
+		rec := httptest.NewRecorder()
+
+		srv.ServeHTTP(rec, req)
+
+		if rec.Code != http.StatusOK {
+			t.Errorf("Expected status code %d, got %d", http.StatusOK, rec.Code)
+		}
+
+		if rec.Header().Get("X-Success") != "false" {
+			t.Errorf("Expected X-Success: false, got %q", rec.Header().Get("X-Success"))
+		}
+
+		if rec.Header().Get("X-Exit-Code") != "1" {
+			t.Errorf("Expected X-Exit-Code: 1, got %q", rec.Header().Get("X-Exit-Code"))
+		}
+	})
+
+	t.Run("Execution Timeout", func(t *testing.T) {
+		t.Parallel()
+		srv := setupServer(t)
+
+		req := httptest.NewRequest(http.MethodGet, "/cmd/sleep", nil)
+		rec := httptest.NewRecorder()
+
+		srv.ServeHTTP(rec, req)
+
+		if rec.Code != http.StatusOK {
+			t.Errorf("Expected status code %d, got %d", http.StatusOK, rec.Code)
+		}
+
+		if rec.Header().Get("X-Success") != "false" {
+			t.Errorf("Expected X-Success: false, got %q", rec.Header().Get("X-Success"))
+		}
+
+		errMsg := rec.Header().Get("X-Error-Message")
+		expectedMsg := "process wait failed: signal: killed"
+
+		if errMsg != expectedMsg {
+			t.Errorf("Expected timeout error message in X-Error-Message header to be %q, got %q", expectedMsg, errMsg)
+		}
+	})
+}
+
+func TestServer_RequestParams(t *testing.T) {
+	t.Parallel()
+
 	t.Run("POST /cmd/echo-text", func(t *testing.T) {
 		t.Parallel()
 		srv := setupServer(t)
@@ -91,6 +220,24 @@ func TestServerIntegration(t *testing.T) {
 		}
 	})
 
+	t.Run("POST /cmd/echo-text - empty body", func(t *testing.T) {
+		t.Parallel()
+		srv := setupServer(t)
+
+		req := httptest.NewRequest(http.MethodPost, "/cmd/echo-text", nil)
+		rec := httptest.NewRecorder()
+
+		srv.ServeHTTP(rec, req)
+
+		if rec.Code != http.StatusOK {
+			t.Fatalf("Expected status %d, got %d. Body: %q", http.StatusOK, rec.Code, rec.Body.String())
+		}
+
+		if rec.Body.String() != "" {
+			t.Fatalf("Expected empty output, got %q", rec.Body.String())
+		}
+	})
+
 	t.Run("POST /cmd/echo-json", func(t *testing.T) {
 		t.Parallel()
 		srv := setupServer(t)
@@ -100,7 +247,6 @@ func TestServerIntegration(t *testing.T) {
 		req.Header.Set("Content-Type", "application/json")
 
 		rec := httptest.NewRecorder()
-
 		srv.ServeHTTP(rec, req)
 
 		if rec.Code != http.StatusOK {
@@ -113,99 +259,136 @@ func TestServerIntegration(t *testing.T) {
 		}
 	})
 
-	t.Run("404 Not Found", func(t *testing.T) {
+	t.Run("Invalid JSON Body", func(t *testing.T) {
 		t.Parallel()
 		srv := setupServer(t)
 
-		req := httptest.NewRequest(http.MethodGet, "/cmd/non-existent", nil)
+		req := httptest.NewRequest(http.MethodPost, "/cmd/echo-json", strings.NewReader(`{invalid json`))
+		req.Header.Set("Content-Type", "application/json")
 
-		req.Header.Set("X-Api-Key", "ABC111")
+		rec := httptest.NewRecorder()
+		srv.ServeHTTP(rec, req)
+
+		if rec.Code != http.StatusBadRequest {
+			t.Errorf("Expected status code %d, got %d", http.StatusBadRequest, rec.Code)
+		}
+	})
+
+	t.Run("POST /cmd/echo-json - non-object JSON returns 400", func(t *testing.T) {
+		t.Parallel()
+		srv := setupServer(t)
+
+		req := httptest.NewRequest(http.MethodPost, "/cmd/echo-json", strings.NewReader(`[1,2,3]`))
+		req.Header.Set("Content-Type", "application/json")
 
 		rec := httptest.NewRecorder()
 
 		srv.ServeHTTP(rec, req)
 
-		if rec.Code != http.StatusNotFound {
-			t.Errorf("Expected status code %d, got %d", http.StatusNotFound, rec.Code)
+		if rec.Code != http.StatusBadRequest {
+			t.Fatalf("Expected status %d, got %d. Body: %q", http.StatusBadRequest, rec.Code, rec.Body.String())
 		}
 	})
 
-	t.Run("401 Unauthorized - No API Key", func(t *testing.T) {
+	t.Run("GET /cmd/query-first - uses only first query value", func(t *testing.T) {
 		t.Parallel()
 		srv := setupServer(t)
 
-		req := httptest.NewRequest(http.MethodPost, "/cmd/echo", nil)
+		req := httptest.NewRequest(http.MethodGet, "/cmd/query-first?a=1&a=2", nil)
 		rec := httptest.NewRecorder()
 
 		srv.ServeHTTP(rec, req)
 
-		if rec.Code != http.StatusUnauthorized {
-			t.Errorf("Expected status code %d, got %d", http.StatusUnauthorized, rec.Code)
+		if rec.Code != http.StatusOK {
+			t.Fatalf("Expected status %d, got %d. Body: %q", http.StatusOK, rec.Code, rec.Body.String())
+		}
+
+		if rec.Body.String() != "1" {
+			t.Fatalf("Expected output %q, got %q", "1", rec.Body.String())
 		}
 	})
 
-	t.Run("401 Unauthorized - Invalid API Key", func(t *testing.T) {
+	t.Run("GET /cmd/headers - normalizes headers and joins multiple values", func(t *testing.T) {
 		t.Parallel()
 		srv := setupServer(t)
 
-		req := httptest.NewRequest(http.MethodPost, "/cmd/echo", nil)
-		req.Header.Set("X-Api-Key", "INVALID")
+		req := httptest.NewRequest(http.MethodGet, "/cmd/headers", nil)
+		req.Header.Add("X-Test-Header", "a")
+		req.Header.Add("X-Test", "val1")
+		req.Header.Add("X-Test", "val2")
 
 		rec := httptest.NewRecorder()
-
 		srv.ServeHTTP(rec, req)
 
-		if rec.Code != http.StatusUnauthorized {
-			t.Errorf("Expected status code %d, got %d", http.StatusUnauthorized, rec.Code)
+		if rec.Code != http.StatusOK {
+			t.Fatalf("Expected status %d, got %d. Body: %q", http.StatusOK, rec.Code, rec.Body.String())
+		}
+
+		expected := "a val1; val2"
+		if rec.Body.String() != expected {
+			t.Fatalf("Expected output %q, got %q", expected, rec.Body.String())
 		}
 	})
 
-	t.Run("403 Forbidden - Insufficient Permissions", func(t *testing.T) {
+	t.Run("POST /cmd/echo-json-disabled - BodyAsJSON=false does not populate body.json", func(t *testing.T) {
 		t.Parallel()
 		srv := setupServer(t)
 
-		req := httptest.NewRequest(http.MethodPost, "/cmd/forbidden", nil)
-		req.Header.Set("X-Api-Key", "ABC222") // auth-name2, but command needs auth-name1
+		body := `{"a":1}`
+		req := httptest.NewRequest(http.MethodPost, "/cmd/echo-json-disabled", strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
 
 		rec := httptest.NewRecorder()
 
 		srv.ServeHTTP(rec, req)
 
-		if rec.Code != http.StatusForbidden {
-			t.Errorf("Expected status code %d, got %d", http.StatusForbidden, rec.Code)
+		if rec.Code != http.StatusOK {
+			t.Fatalf("Expected status %d, got %d. Body: %q", http.StatusOK, rec.Code, rec.Body.String())
+		}
+
+		expected := body + " <no value>"
+		if rec.Body.String() != expected {
+			t.Fatalf("Expected output %q, got %q", expected, rec.Body.String())
 		}
 	})
 
-	t.Run("Execution Timeout", func(t *testing.T) {
+	t.Run("POST /cmd/echo-text - request body read error returns 500", func(t *testing.T) {
 		t.Parallel()
 		srv := setupServer(t)
 
-		req := httptest.NewRequest(http.MethodGet, "/cmd/sleep", nil)
+		req := httptest.NewRequest(http.MethodPost, "/cmd/echo-text", nil)
+		req.Body = io.NopCloser(&errorReader{}) // force ReadAll to fail
 		rec := httptest.NewRecorder()
 
 		srv.ServeHTTP(rec, req)
 
-		if rec.Code != http.StatusOK {
-			t.Errorf("Expected status code %d, got %d", http.StatusOK, rec.Code)
+		if rec.Code != http.StatusInternalServerError {
+			t.Fatalf("Expected status %d, got %d. Body: %q", http.StatusInternalServerError, rec.Code, rec.Body.String())
 		}
 
-		if rec.Header().Get("X-Success") != "false" {
-			t.Errorf("Expected X-Success: false, got %q", rec.Header().Get("X-Success"))
+		errMsg := rec.Header().Get("X-Error-Message")
+		if errMsg == "" {
+			t.Fatalf("Expected X-Error-Message to be set")
 		}
 
-		errMsg := rec.Header().Get("X-Error-Message")
-		expectedMsg := "process wait failed: signal: killed"
+		if !strings.Contains(errMsg, "failed to read request body") {
+			t.Fatalf("Expected X-Error-Message to contain %q, got %q", "failed to read request body", errMsg)
+		}
 
-		if errMsg != expectedMsg {
-			t.Errorf("Expected timeout error message in X-Error-Message header to be %q, got %q", expectedMsg, errMsg)
+		if !strings.Contains(errMsg, "unexpected EOF") {
+			t.Fatalf("Expected X-Error-Message to contain %q, got %q", "unexpected EOF", errMsg)
 		}
 	})
+}
 
-	t.Run("Command failure - Exit Code 1", func(t *testing.T) {
+func TestServer_OutputTypes(t *testing.T) {
+	t.Parallel()
+
+	t.Run("Output Type Stream", func(t *testing.T) {
 		t.Parallel()
 		srv := setupServer(t)
 
-		req := httptest.NewRequest(http.MethodGet, "/cmd/false", nil)
+		req := httptest.NewRequest(http.MethodGet, "/cmd/stream", nil)
 		rec := httptest.NewRecorder()
 
 		srv.ServeHTTP(rec, req)
@@ -214,83 +397,179 @@ func TestServerIntegration(t *testing.T) {
 			t.Errorf("Expected status code %d, got %d", http.StatusOK, rec.Code)
 		}
 
-		if rec.Header().Get("X-Success") != "false" {
-			t.Errorf("Expected X-Success: false, got %q", rec.Header().Get("X-Success"))
+		if rec.Header().Get("Content-Type") != "text/plain; charset=utf-8" {
+			t.Errorf("Expected Content-Type text/plain, got %q", rec.Header().Get("Content-Type"))
 		}
 
-		if rec.Header().Get("X-Exit-Code") != "1" {
-			t.Errorf("Expected X-Exit-Code: 1, got %q", rec.Header().Get("X-Exit-Code"))
+		if rec.Body.String() != "stream-output\n" {
+			t.Errorf("Expected %q, got %q", "stream-output\n", rec.Body.String())
 		}
 	})
 
-	t.Run("Invalid JSON Body", func(t *testing.T) {
+	t.Run("Output Type None", func(t *testing.T) {
 		t.Parallel()
 		srv := setupServer(t)
 
-		req := httptest.NewRequest(http.MethodPost, "/cmd/echo-json", strings.NewReader(`{invalid json`))
-		req.Header.Set("Content-Type", "application/json")
-
+		req := httptest.NewRequest(http.MethodGet, "/cmd/none", nil)
 		rec := httptest.NewRecorder()
 
 		srv.ServeHTTP(rec, req)
 
-		if rec.Code != http.StatusBadRequest {
-			t.Errorf("Expected status code %d, got %d", http.StatusBadRequest, rec.Code)
+		if rec.Code != http.StatusOK {
+			t.Errorf("Expected status code %d, got %d", http.StatusOK, rec.Code)
+		}
+
+		if rec.Body.Len() != 0 {
+			t.Errorf("Expected empty body, got %q", rec.Body.String())
 		}
 	})
 
-	t.Run("Method Not Allowed (treated as 404)", func(t *testing.T) {
+	t.Run("GET /cmd/bad-output - unknown output type returns 500", func(t *testing.T) {
 		t.Parallel()
 		srv := setupServer(t)
 
-		// /cmd/echo is POST, trying GET
-		req := httptest.NewRequest(http.MethodGet, "/cmd/echo", nil)
+		req := httptest.NewRequest(http.MethodGet, "/cmd/bad-output", nil)
 		rec := httptest.NewRecorder()
 
 		srv.ServeHTTP(rec, req)
 
-		if rec.Code != http.StatusNotFound {
-			t.Errorf("Expected status code %d, got %d", http.StatusNotFound, rec.Code)
+		if rec.Code != http.StatusInternalServerError {
+			t.Fatalf("Expected status %d, got %d. Body: %q", http.StatusInternalServerError, rec.Code, rec.Body.String())
+		}
+
+		errMsg := rec.Header().Get("X-Error-Message")
+		if errMsg == "" || !strings.Contains(errMsg, "unknown output type") {
+			t.Fatalf("Expected X-Error-Message to contain %q, got %q", "unknown output type", errMsg)
 		}
 	})
+}
 
-	t.Run("Output Type Stream", func(t *testing.T) {
+func TestServer_Templates(t *testing.T) {
+	t.Parallel()
+
+	t.Run("GET /cmd/bad-template - template syntax error returns 500", func(t *testing.T) {
 		t.Parallel()
 		srv := setupServer(t)
 
-		req := httptest.NewRequest(http.MethodGet, "/cmd/stream", nil)
+		req := httptest.NewRequest(http.MethodGet, "/cmd/bad-template", nil)
 		rec := httptest.NewRecorder()
 
 		srv.ServeHTTP(rec, req)
 
-		if rec.Code != http.StatusOK {
-			t.Errorf("Expected status code %d, got %d", http.StatusOK, rec.Code)
+		if rec.Code != http.StatusInternalServerError {
+			t.Fatalf("Expected status %d, got %d. Body: %q", http.StatusInternalServerError, rec.Code, rec.Body.String())
 		}
 
-		if rec.Header().Get("Content-Type") != "text/plain; charset=utf-8" {
-			t.Errorf("Expected Content-Type text/plain, got %q", rec.Header().Get("Content-Type"))
+		errMsg := rec.Header().Get("X-Error-Message")
+		if errMsg == "" || !strings.Contains(errMsg, "error building command") {
+			t.Fatalf("Expected X-Error-Message to contain %q, got %q", "error building command", errMsg)
 		}
+	})
+}
 
-		if rec.Body.String() != "stream-output\n" {
-			t.Errorf("Expected %q, got %q", "stream-output\n", rec.Body.String())
+func TestServer_CallGate(t *testing.T) {
+	t.Parallel()
+
+	t.Run("CallGate busy returns 429 (same explicit group)", func(t *testing.T) {
+		t.Parallel()
+		srv := setupServer(t)
+
+		req1 := httptest.NewRequest(http.MethodGet, "/cmd/gated-sleep", nil)
+		rec1 := httptest.NewRecorder()
+
+		done1 := make(chan struct{})
+		go func() {
+			srv.ServeHTTP(rec1, req1)
+			close(done1)
+		}()
+
+		time.Sleep(50 * time.Millisecond)
+
+		req2 := httptest.NewRequest(http.MethodGet, "/cmd/gated-sleep", nil)
+		rec2 := httptest.NewRecorder()
+		srv.ServeHTTP(rec2, req2)
+
+		if rec2.Code != http.StatusTooManyRequests {
+			t.Fatalf("Expected status %d, got %d. Body: %q", http.StatusTooManyRequests, rec2.Code, rec2.Body.String())
 		}
+
+		<-done1
 	})
 
-	t.Run("Output Type None", func(t *testing.T) {
+	t.Run("CallGate implicit group name isolates different URLs", func(t *testing.T) {
 		t.Parallel()
 		srv := setupServer(t)
 
-		req := httptest.NewRequest(http.MethodGet, "/cmd/none", nil)
+		req1 := httptest.NewRequest(http.MethodGet, "/cmd/gated-implicit-a", nil)
+		rec1 := httptest.NewRecorder()
+
+		done1 := make(chan struct{})
+		go func() {
+			srv.ServeHTTP(rec1, req1)
+			close(done1)
+		}()
+
+		time.Sleep(50 * time.Millisecond)
+
+		req2 := httptest.NewRequest(http.MethodGet, "/cmd/gated-implicit-b", nil)
+		rec2 := httptest.NewRecorder()
+		srv.ServeHTTP(rec2, req2)
+
+		if rec2.Code != http.StatusOK {
+			t.Fatalf("Expected status %d, got %d. Body: %q", http.StatusOK, rec2.Code, rec2.Body.String())
+		}
+
+		<-done1
+	})
+
+	t.Run("CallGate empty group name shared across URLs => second returns 429", func(t *testing.T) {
+		t.Parallel()
+		srv := setupServer(t)
+
+		req1 := httptest.NewRequest(http.MethodGet, "/cmd/gated-empty-a", nil)
+		rec1 := httptest.NewRecorder()
+
+		done1 := make(chan struct{})
+		go func() {
+			srv.ServeHTTP(rec1, req1)
+			close(done1)
+		}()
+
+		time.Sleep(50 * time.Millisecond)
+
+		req2 := httptest.NewRequest(http.MethodGet, "/cmd/gated-empty-b", nil)
+		rec2 := httptest.NewRecorder()
+		srv.ServeHTTP(rec2, req2)
+
+		if rec2.Code != http.StatusTooManyRequests {
+			t.Fatalf("Expected status %d, got %d. Body: %q", http.StatusTooManyRequests, rec2.Code, rec2.Body.String())
+		}
+
+		<-done1
+	})
+
+	t.Run("CallGate invalid mode returns 500", func(t *testing.T) {
+		t.Parallel()
+		srv := setupServer(t)
+
+		req := httptest.NewRequest(http.MethodGet, "/cmd/gated-invalid-mode", nil)
 		rec := httptest.NewRecorder()
 
 		srv.ServeHTTP(rec, req)
 
-		if rec.Code != http.StatusOK {
-			t.Errorf("Expected status code %d, got %d", http.StatusOK, rec.Code)
+		if rec.Code != http.StatusInternalServerError {
+			t.Fatalf("Expected status %d, got %d. Body: %q", http.StatusInternalServerError, rec.Code, rec.Body.String())
 		}
 
-		if rec.Body.Len() != 0 {
-			t.Errorf("Expected empty body, got %q", rec.Body.String())
+		errMsg := rec.Header().Get("X-Error-Message")
+		if errMsg == "" || !strings.Contains(errMsg, "invalid callgate mode") {
+			t.Fatalf("Expected X-Error-Message to contain %q, got %q", "invalid callgate mode", errMsg)
 		}
 	})
 }
+
+type errorReader struct{}
+
+func (e *errorReader) Read(_ []byte) (int, error) {
+	return 0, io.ErrUnexpectedEOF
+}
diff --git a/test/integration/test-data/test-config.yaml b/test/integration/test-data/test-config.yaml
index b113ce6..e198b91 100644
--- a/test/integration/test-data/test-config.yaml
+++ b/test/integration/test-data/test-config.yaml
@@ -1,3 +1,5 @@
+server:
+  withErrorHeader: true
 authorization:
   - name: auth-name1
     key: ABC111
@@ -51,4 +53,100 @@ urlCommands:
     commandTemplate: |
       /bin/echo
       no-output
-    outputType: none
\ No newline at end of file
+    outputType: none
+
+
+  - url: GET /cmd/query-first
+    commandTemplate: |
+      /bin/echo
+      -n
+      {{.url.a}}
+    timeout: 5s
+
+  - url: GET /cmd/headers
+    commandTemplate: |
+      /bin/echo
+      -n
+      {{.headers.X_Test_Header}} {{.headers.X_Test}}
+    timeout: 5s
+
+  - url: POST /cmd/echo-json-disabled
+    commandTemplate: |
+      /bin/echo
+      -n
+      {{.body.text}} {{index .body "json"}}
+    params:
+      bodyAsJson: false
+    timeout: 5s
+
+  - url: GET /cmd/bad-output
+    commandTemplate: |
+      /bin/echo
+      hello
+    outputType: invalid
+    timeout: 5s
+
+  - url: GET /cmd/bad-template
+    commandTemplate: |
+      /bin/echo
+      {{.url.name
+    timeout: 5s
+
+  # CallGate: explicit group, same URL, should return 429 on concurrency
+  - url: GET /cmd/gated-sleep
+    commandTemplate: |
+      /bin/sleep
+      1
+    timeout: 5s
+    callGate:
+      mode: single
+      groupName: test-group
+
+  # CallGate: implicit group name (omit groupName) => different URLs should not block each other
+  - url: GET /cmd/gated-implicit-a
+    commandTemplate: |
+      /bin/sleep
+      1
+    timeout: 5s
+    callGate:
+      mode: single
+
+  - url: GET /cmd/gated-implicit-b
+    commandTemplate: |
+      /bin/echo
+      -n
+      ok
+    timeout: 5s
+    callGate:
+      mode: single
+
+  # CallGate: empty groupName shared across URLs => should block
+  - url: GET /cmd/gated-empty-a
+    commandTemplate: |
+      /bin/sleep
+      1
+    timeout: 5s
+    callGate:
+      mode: single
+      groupName: ""
+
+  - url: GET /cmd/gated-empty-b
+    commandTemplate: |
+      /bin/echo
+      -n
+      ok
+    timeout: 5s
+    callGate:
+      mode: single
+      groupName: ""
+
+  # CallGate: invalid mode => 500
+  - url: GET /cmd/gated-invalid-mode
+    commandTemplate: |
+      /bin/echo
+      -n
+      ok
+    timeout: 5s
+    callGate:
+      mode: invalid-mode
+      groupName: test-group
\ No newline at end of file

From 7e133c0c16e056695ecae3cd6c74c3b445f8b557 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Thu, 5 Mar 2026 20:56:11 +0100
Subject: [PATCH 34/38] refactor(handlers): decouple ExecutionHandler from
 processrunner using ProcessStarter interface

---
 pkg/router/handlers/execution_handler.go      |   60 +-
 pkg/router/handlers/execution_handler_test.go | 1950 +++--------------
 pkg/router/handlers/fakes_test.go             |  173 ++
 pkg/router/router.go                          |    4 +-
 4 files changed, 571 insertions(+), 1616 deletions(-)
 create mode 100644 pkg/router/handlers/fakes_test.go

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index e57b115..4f55cad 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -17,7 +17,6 @@ import (
 
 	"github.com/dkarczmarski/webcmd/pkg/callgate"
 	"github.com/dkarczmarski/webcmd/pkg/cmdbuilder"
-	"github.com/dkarczmarski/webcmd/pkg/cmdrunner"
 	"github.com/dkarczmarski/webcmd/pkg/config"
 	"github.com/dkarczmarski/webcmd/pkg/gateexec"
 	"github.com/dkarczmarski/webcmd/pkg/httpx"
@@ -30,6 +29,19 @@ var (
 	ErrInvalidJSONBody       = errors.New("invalid JSON body")
 )
 
+// ProcessStarter abstracts starting a process for a command execution.
+// It is implemented by processrunner.ProcessRunner, which binds cmdrunner.Runner internally.
+// This keeps the handler decoupled from cmdrunner.Runner and makes testing easier.
+type ProcessStarter interface {
+	StartProcess(
+		command string,
+		args []string,
+		writer io.Writer,
+		graceTimeout *time.Duration,
+		opts ...processrunner.Option,
+	) (*processrunner.Process, error)
+}
+
 // ExecutionHandler returns a WebHandler that executes the command associated with the URLCommand stored in the
 // request context.
 // It builds the command from the configured template and request parameters, prepares the response output,
@@ -40,9 +52,15 @@ var (
 // discarding output).
 // When execution fails (non-zero exit code or error), it logs the failure and writes an error message to the
 // response body.
-func ExecutionHandler(runner cmdrunner.Runner, registry *callgate.Registry) httpx.WebHandler { //nolint:ireturn
+func ExecutionHandler(pr *processrunner.ProcessRunner, registry *callgate.Registry) httpx.WebHandler { //nolint:ireturn
+	return ExecutionHandlerWithProcessRunner(pr, registry)
+}
+
+// ExecutionHandlerWithProcessRunner is a test-friendly variant of ExecutionHandler that accepts an abstract
+// ProcessStarter (implemented by processrunner.ProcessRunner).
+func ExecutionHandlerWithProcessRunner(starter ProcessStarter, registry *callgate.Registry) httpx.WebHandler { //nolint:ireturn,lll
 	return httpx.WebHandlerFunc(func(responseWriter http.ResponseWriter, request *http.Request) error {
-		err := executionHandler(responseWriter, request, runner, registry)
+		err := executionHandler(responseWriter, request, starter, registry)
 		if err != nil {
 			return translateError(err)
 		}
@@ -54,7 +72,7 @@ func ExecutionHandler(runner cmdrunner.Runner, registry *callgate.Registry) http
 func executionHandler(
 	responseWriter http.ResponseWriter,
 	request *http.Request,
-	runner cmdrunner.Runner,
+	starter ProcessStarter,
 	registry *callgate.Registry,
 ) error {
 	rid := requestIDFromContext(request.Context())
@@ -77,7 +95,7 @@ func executionHandler(
 
 	return prepareOutputAndRunCommand(
 		request.Context(),
-		runner,
+		starter,
 		registry,
 		cmd,
 		cmdResult,
@@ -111,7 +129,7 @@ func translateError(err error) error {
 
 func runCommand(
 	ctx context.Context,
-	runner cmdrunner.Runner,
+	starter ProcessStarter,
 	registry *callgate.Registry,
 	cmd *config.URLCommand,
 	cmdResult *cmdbuilder.Result,
@@ -121,7 +139,7 @@ func runCommand(
 ) error {
 	rid := requestIDFromContext(ctx)
 	exec := gateexec.New(registry)
-	action := createGateAction(runner, cmd, cmdResult, writer, async)
+	action := createGateAction(starter, cmd, cmdResult, writer, async)
 
 	exitCode, err := exec.Run(ctx, cmd.CallGate, cmd.URL, action)
 	if err != nil {
@@ -146,7 +164,7 @@ func runCommand(
 }
 
 func createGateAction(
-	runner cmdrunner.Runner,
+	starter ProcessStarter,
 	cmd *config.URLCommand,
 	cmdResult *cmdbuilder.Result,
 	writer io.Writer,
@@ -159,7 +177,7 @@ func createGateAction(
 		rid := requestIDFromContext(ctx)
 		log.Printf("[INFO] rid=%s Executing command: %s %v", rid, command, arguments)
 
-		proc, err := startCommandProcess(runner, command, arguments, writer, cmd.GraceTerminationTimeout)
+		proc, err := startCommandProcess(starter, command, arguments, writer, cmd.GraceTerminationTimeout)
 		if err != nil {
 			return -1, nil, err
 		}
@@ -216,13 +234,13 @@ func waitAsyncAndLog(
 }
 
 func startCommandProcess(
-	runner cmdrunner.Runner,
+	starter ProcessStarter,
 	command string,
 	arguments []string,
 	writer io.Writer,
 	graceTerminationTimeout *time.Duration,
 ) (*processrunner.Process, error) {
-	proc, err := processrunner.StartProcess(runner, command, arguments, writer, graceTerminationTimeout)
+	proc, err := starter.StartProcess(command, arguments, writer, graceTerminationTimeout)
 	if err != nil {
 		return nil, fmt.Errorf("failed to start process: %w", err)
 	}
@@ -282,7 +300,7 @@ func buildCommand(
 
 func prepareOutputAndRunCommand(
 	ctx context.Context,
-	runner cmdrunner.Runner,
+	starter ProcessStarter,
 	registry *callgate.Registry,
 	cmd *config.URLCommand,
 	cmdResult *cmdbuilder.Result,
@@ -292,11 +310,11 @@ func prepareOutputAndRunCommand(
 
 	switch outputType {
 	case "none":
-		return prepareOutputAndRunAsyncCommand(ctx, runner, registry, cmd, cmdResult, responseWriter)
+		return prepareOutputAndRunAsyncCommand(ctx, starter, registry, cmd, cmdResult, responseWriter)
 	case "stream":
-		return prepareOutputAndRunStreamCommand(ctx, runner, registry, cmd, cmdResult, responseWriter)
+		return prepareOutputAndRunStreamCommand(ctx, starter, registry, cmd, cmdResult, responseWriter)
 	case "", "text":
-		return prepareOutputAndRunSyncCommand(ctx, runner, registry, cmd, cmdResult, responseWriter)
+		return prepareOutputAndRunSyncCommand(ctx, starter, registry, cmd, cmdResult, responseWriter)
 	default:
 		return fmt.Errorf("%w: unknown output type %q", ErrBadConfiguration, outputType)
 	}
@@ -304,7 +322,7 @@ func prepareOutputAndRunCommand(
 
 func prepareOutputAndRunAsyncCommand(
 	ctx context.Context,
-	runner cmdrunner.Runner,
+	starter ProcessStarter,
 	registry *callgate.Registry,
 	cmd *config.URLCommand,
 	cmdResult *cmdbuilder.Result,
@@ -312,7 +330,7 @@ func prepareOutputAndRunAsyncCommand(
 ) error {
 	return runCommand(
 		ctx,
-		runner,
+		starter,
 		registry,
 		cmd,
 		cmdResult,
@@ -324,7 +342,7 @@ func prepareOutputAndRunAsyncCommand(
 
 func prepareOutputAndRunStreamCommand(
 	ctx context.Context,
-	runner cmdrunner.Runner,
+	starter ProcessStarter,
 	registry *callgate.Registry,
 	cmd *config.URLCommand,
 	cmdResult *cmdbuilder.Result,
@@ -347,7 +365,7 @@ func prepareOutputAndRunStreamCommand(
 
 	return runCommand(
 		ctx,
-		runner,
+		starter,
 		registry,
 		cmd,
 		cmdResult,
@@ -359,7 +377,7 @@ func prepareOutputAndRunStreamCommand(
 
 func prepareOutputAndRunSyncCommand(
 	ctx context.Context,
-	runner cmdrunner.Runner,
+	starter ProcessStarter,
 	registry *callgate.Registry,
 	cmd *config.URLCommand,
 	cmdResult *cmdbuilder.Result,
@@ -371,7 +389,7 @@ func prepareOutputAndRunSyncCommand(
 
 	err := runCommand(
 		ctx,
-		runner,
+		starter,
 		registry,
 		cmd,
 		cmdResult,
diff --git a/pkg/router/handlers/execution_handler_test.go b/pkg/router/handlers/execution_handler_test.go
index 28257ec..6753cb5 100644
--- a/pkg/router/handlers/execution_handler_test.go
+++ b/pkg/router/handlers/execution_handler_test.go
@@ -4,47 +4,39 @@ import (
 	"context"
 	"errors"
 	"io"
-	"log"
 	"net/http"
 	"net/http/httptest"
 	"os/exec"
 	"strings"
-	"sync"
-	"syscall"
 	"testing"
 	"time"
 
 	"github.com/dkarczmarski/webcmd/pkg/callgate"
 	"github.com/dkarczmarski/webcmd/pkg/config"
 	"github.com/dkarczmarski/webcmd/pkg/httpx"
+	"github.com/dkarczmarski/webcmd/pkg/processrunner"
 	"github.com/dkarczmarski/webcmd/pkg/router/handlers"
-	"github.com/dkarczmarski/webcmd/pkg/router/handlers/internal/mocks"
-	"go.uber.org/mock/gomock"
 )
 
-type syncedWriter struct {
-	io.Writer
-	mu *sync.Mutex
-}
-
-//nolint:wrapcheck
-func (s *syncedWriter) Write(p []byte) (int, error) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-
-	return s.Writer.Write(p)
-}
-
-func TestExecutionHandler_HappyPath(t *testing.T) {
+func TestExecutionHandler_HappyPath_Stream(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
+	fr := &fakeRunner{}
+	fr.cmd = &fakeCommand{
+		pid: 123,
+		// Simulate a running process writing to stdout when the command starts.
+		// This allows the handler to stream the output to the HTTP response.
+		onStart: func(c *fakeCommand) {
+			c.mu.Lock()
+			defer c.mu.Unlock()
+			_, _ = c.stdout.Write([]byte("process output"))
+		},
+	}
 
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
+	pr := processrunner.New(fr)
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
-	// Setup URLCommand in context
 	cmdCfg := &config.URLCommand{
 		URL: "POST /exec",
 		CommandConfig: config.CommandConfig{
@@ -53,58 +45,59 @@ func TestExecutionHandler_HappyPath(t *testing.T) {
 		},
 	}
 
-	// ExecutionHandler expectations
-	mockRunner.EXPECT().
-		Command("echo", "test-name", "test-header", "test-body").
-		Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any()).Do(func(w io.Writer) {
-		_, _ = w.Write([]byte("process output"))
-	})
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Wait().Return(nil)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	// We need to use ErrorSink to get the 200 status code and handle errors
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
 	req := httptest.NewRequest(http.MethodPost, "/exec?name=test-name", strings.NewReader("test-body"))
 	req.Header.Set("X-Test", "test-header")
+	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
-	// Manually put URLCommand into context as the middleware would do
-	ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-	req = req.WithContext(ctx)
-
-	rr := httptest.NewRecorder()
+	// flusherRecorder lets us verify that streaming handlers call Flush(),
+	// which is required to send data incrementally to the client.
+	rr := &flusherRecorder{ResponseRecorder: httptest.NewRecorder()}
 	h.ServeHTTP(rr, req)
 
 	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
+		t.Fatalf("expected status 200, got %d body=%q", rr.Code, rr.Body.String())
+	}
+
+	if rr.Body.String() != "process output" {
+		t.Fatalf("expected body %q, got %q", "process output", rr.Body.String())
+	}
+
+	if ct := rr.Header().Get("Content-Type"); ct != "text/plain; charset=utf-8" {
+		t.Fatalf("expected Content-Type %q, got %q", "text/plain; charset=utf-8", ct)
+	}
+
+	if !rr.flushed {
+		t.Fatalf("expected Flush() to be called")
 	}
 
-	expectedBody := "process output"
-	if rr.Body.String() != expectedBody {
-		t.Errorf("expected body %q, got %q", expectedBody, rr.Body.String())
+	// Verify that the template was rendered correctly and split into command + args.
+	gotCmd, gotArgs := fr.SnapshotCommand()
+
+	if gotCmd != "echo" {
+		t.Fatalf("expected command %q, got %q (args=%v)", "echo", gotCmd, gotArgs)
 	}
 
-	contentType := rr.Header().Get("Content-Type")
-	if !strings.Contains(contentType, "text/plain") {
-		t.Errorf("expected Content-Type to contain text/plain, got %q", contentType)
+	if strings.Join(gotArgs, "|") != "test-name|test-header|test-body" {
+		t.Fatalf("expected args %v, got %v", []string{"test-name", "test-header", "test-body"}, gotArgs)
 	}
 }
 
-func TestExecutionHandler_EmptyBody(t *testing.T) {
+func TestExecutionHandler_Text_EmptyBody(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
+	fr := &fakeRunner{}
+	fr.cmd = &fakeCommand{
+		pid: 123,
+		onStart: func(c *fakeCommand) {
+			c.mu.Lock()
+			defer c.mu.Unlock()
+			_, _ = c.stdout.Write([]byte("empty body output"))
+		},
+	}
 
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
+	pr := processrunner.New(fr)
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
 		URL: "POST /exec",
@@ -114,177 +107,130 @@ func TestExecutionHandler_EmptyBody(t *testing.T) {
 		},
 	}
 
-	// For empty body, body.text should be ""
-	mockRunner.EXPECT().
-		Command("echo ''").
-		Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any()).Do(func(w io.Writer) {
-		_, _ = w.Write([]byte("empty body output"))
-	})
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Wait().Return(nil)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	// Body is empty
 	req := httptest.NewRequest(http.MethodPost, "/exec", nil)
-	ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-	req = req.WithContext(ctx)
+	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
 	rr := httptest.NewRecorder()
 	h.ServeHTTP(rr, req)
 
 	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
+		t.Fatalf("expected status 200, got %d body=%q", rr.Code, rr.Body.String())
 	}
 
 	if rr.Body.String() != "empty body output" {
-		t.Errorf("expected output 'empty body output', got %q", rr.Body.String())
+		t.Fatalf("expected body %q, got %q", "empty body output", rr.Body.String())
+	}
+
+	gotCmd, gotArgs := fr.SnapshotCommand()
+	// Template is a single line => the whole rendered output becomes the command (no args).
+	if gotCmd != "echo ''" || len(gotArgs) != 0 {
+		t.Fatalf("expected Command(%q) with no args, got cmd=%q args=%v", "echo ''", gotCmd, gotArgs)
 	}
 }
 
-func TestExecutionHandler_NoCommandInContext(t *testing.T) {
+func TestExecutionHandler_NoCommandInContext_404(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
+	fr := &fakeRunner{}
+	pr := processrunner.New(fr)
 
-	mockRunner := mocks.NewMockRunner(ctrl)
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	// Using ErrorSink to translate WebError to HTTP status code
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
-	// No URLCommand in context
 	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
 	rr := httptest.NewRecorder()
-
 	h.ServeHTTP(rr, req)
 
 	if rr.Code != http.StatusNotFound {
-		t.Errorf("expected status 404, got %d", rr.Code)
+		t.Fatalf("expected status 404, got %d", rr.Code)
 	}
 
-	errMsg := rr.Header().Get("X-Error-Message")
-	if !strings.Contains(errMsg, "Command not found") {
-		t.Errorf("expected X-Error-Message to contain 'Command not found', got %q", errMsg)
+	if msg := rr.Header().Get("X-Error-Message"); !strings.Contains(msg, "Command not found") {
+		t.Fatalf("expected X-Error-Message to contain %q, got %q", "Command not found", msg)
 	}
 }
 
-func TestExecutionHandler_ExtractParams_Query(t *testing.T) {
+func TestExecutionHandler_ExtractParams_Query_FirstValueOnly(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
+	fr := &fakeRunner{}
+	pr := processrunner.New(fr)
 
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
 		URL: "GET /exec",
 		CommandConfig: config.CommandConfig{
 			CommandTemplate: "echo {{.url.a}}",
+			OutputType:      "text",
 		},
 	}
 
-	// Expect only the first value of 'a' to be used
-	mockRunner.EXPECT().
-		Command("echo 1").
-		Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Wait().Return(nil)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	// URL with multiple values for parameter 'a'
+	// When multiple query values exist, the handler should use only the first one.
 	req := httptest.NewRequest(http.MethodGet, "/exec?a=1&a=2", nil)
-	ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-	req = req.WithContext(ctx)
+	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
 	rr := httptest.NewRecorder()
 	h.ServeHTTP(rr, req)
 
 	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
+		t.Fatalf("expected status 200, got %d body=%q", rr.Code, rr.Body.String())
+	}
+
+	gotCmd, gotArgs := fr.SnapshotCommand()
+	if gotCmd != "echo 1" || len(gotArgs) != 0 {
+		t.Fatalf("expected cmd=%q args=[], got cmd=%q args=%v", "echo 1", gotCmd, gotArgs)
 	}
 }
 
-func TestExecutionHandler_ExtractParams_Headers(t *testing.T) {
+func TestExecutionHandler_ExtractParams_Headers_NormalizeAndJoin(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
+	fr := &fakeRunner{}
+	pr := processrunner.New(fr)
 
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
 		URL: "GET /exec",
 		CommandConfig: config.CommandConfig{
 			CommandTemplate: "echo '{{.headers.X_Test_Header}}' '{{.headers.X_Test}}'",
+			OutputType:      "text",
 		},
 	}
 
-	// Expect:
-	// 1. X-Test-Header normalized to X_Test_Header
-	// 2. Multiple values for X-Test joined with "; "
-	mockRunner.EXPECT().
-		Command("echo 'a' 'val1; val2'").
-		Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Wait().Return(nil)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
+	// Header names are normalized for templates:
+	//   X-Test-Header -> X_Test_Header
+	// Multiple values are joined with "; ".
 	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
 	req.Header.Add("X-Test-Header", "a")
 	req.Header.Add("X-Test", "val1")
 	req.Header.Add("X-Test", "val2")
-
-	ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-	req = req.WithContext(ctx)
+	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
 	rr := httptest.NewRecorder()
 	h.ServeHTTP(rr, req)
 
 	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
+		t.Fatalf("expected status 200, got %d body=%q", rr.Code, rr.Body.String())
 	}
-}
-
-type errorReader struct{}
 
-func (e *errorReader) Read(_ []byte) (int, error) {
-	return 0, errors.New("read error")
+	gotCmd, gotArgs := fr.SnapshotCommand()
+	if gotCmd != "echo 'a' 'val1; val2'" || len(gotArgs) != 0 {
+		t.Fatalf("expected cmd=%q args=[], got cmd=%q args=%v", "echo 'a' 'val1; val2'", gotCmd, gotArgs)
+	}
 }
 
-func TestExecutionHandler_ExtractParams_BodyReadError(t *testing.T) {
+func TestExecutionHandler_BodyReadError_500(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
+	fr := &fakeRunner{}
+	pr := processrunner.New(fr)
 
-	mockRunner := mocks.NewMockRunner(ctrl)
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
 		URL: "POST /exec",
@@ -293,285 +239,131 @@ func TestExecutionHandler_ExtractParams_BodyReadError(t *testing.T) {
 		},
 	}
 
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	req := httptest.NewRequest(http.MethodPost, "/exec", &errorReader{})
-	ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-	req = req.WithContext(ctx)
+	req := httptest.NewRequest(http.MethodPost, "/exec", io.NopCloser(&errorReader{}))
+	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
 	rr := httptest.NewRecorder()
 	h.ServeHTTP(rr, req)
 
 	if rr.Code != http.StatusInternalServerError {
-		t.Errorf("expected status 500, got %d", rr.Code)
-	}
-
-	errMsg := rr.Header().Get("X-Error-Message")
-	if !strings.Contains(errMsg, "read error") {
-		t.Errorf("expected X-Error-Message to contain 'read error', got %q", errMsg)
+		t.Fatalf("expected status 500, got %d body=%q", rr.Code, rr.Body.String())
 	}
-}
-
-//nolint:dupl
-func TestExecutionHandler_BodyAsJSON_Disabled(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
 
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
+	msg := rr.Header().Get("X-Error-Message")
 
-	falseVal := false
-	cmdCfg := &config.URLCommand{
-		URL: "POST /exec",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate: "echo '{{.body.text}}' '{{index .body \"json\"}}'",
-			Params: config.ParamsConfig{
-				BodyAsJSON: &falseVal,
-			},
-		},
+	if !strings.Contains(msg, "failed to read request body") {
+		t.Fatalf("expected X-Error-Message to contain %q, got %q", "failed to read request body", msg)
 	}
 
-	// Expect: body.json should be empty/nil, and template will render <no value> for it
-	mockRunner.EXPECT().
-		Command("echo '{\"a\": 1}' '<no value>'").
-		Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Wait().Return(nil)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	req := httptest.NewRequest(http.MethodPost, "/exec", strings.NewReader(`{"a": 1}`))
-	ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-	req = req.WithContext(ctx)
-
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
+	if !strings.Contains(msg, "read error") {
+		t.Fatalf("expected X-Error-Message to contain %q, got %q", "read error", msg)
 	}
 }
 
-//nolint:dupl
-func TestExecutionHandler_BodyAsJSON_Valid(t *testing.T) {
+func TestExecutionHandler_BodyAsJSON_Invalid_400(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	trueVal := true
-	cmdCfg := &config.URLCommand{
-		URL: "POST /exec",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate: "echo '{{.body.text}}' '{{.body.json.a}}'",
-			Params: config.ParamsConfig{
-				BodyAsJSON: &trueVal,
-			},
-		},
-	}
-
-	// Expect: body.text is raw string, body.json.a is 1
-	mockRunner.EXPECT().
-		Command("echo '{\"a\": 1}' '1'").
-		Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Wait().Return(nil)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
+	fr := &fakeRunner{}
+	pr := processrunner.New(fr)
 
-	handler := handlers.ExecutionHandler(mockRunner, nil)
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
-	req := httptest.NewRequest(http.MethodPost, "/exec", strings.NewReader(`{"a": 1}`))
-	ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-	req = req.WithContext(ctx)
-
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
-	}
-}
-
-func TestExecutionHandler_BodyAsJSON_Invalid(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-
 	trueVal := true
 	cmdCfg := &config.URLCommand{
 		URL: "POST /exec",
 		CommandConfig: config.CommandConfig{
 			CommandTemplate: "echo",
+			// BodyAsJSON=true means the handler attempts to parse the body as JSON
+			// and expose it under .body.json in the template context.
 			Params: config.ParamsConfig{
 				BodyAsJSON: &trueVal,
 			},
 		},
 	}
 
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	// Invalid JSON body
 	req := httptest.NewRequest(http.MethodPost, "/exec", strings.NewReader(`{invalid json}`))
-	ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-	req = req.WithContext(ctx)
+	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
 	rr := httptest.NewRecorder()
 	h.ServeHTTP(rr, req)
 
 	if rr.Code != http.StatusBadRequest {
-		t.Errorf("expected status 400, got %d", rr.Code)
+		t.Fatalf("expected status 400, got %d body=%q", rr.Code, rr.Body.String())
 	}
 
 	errMsg := rr.Header().Get("X-Error-Message")
 	if !strings.Contains(errMsg, "must be a JSON object") {
-		t.Errorf("expected X-Error-Message to contain 'must be a JSON object', got %q", errMsg)
+		t.Fatalf("expected X-Error-Message to contain %q, got %q", "must be a JSON object", errMsg)
 	}
 }
 
-func TestExecutionHandler_BodyAsJSON_NonObject(t *testing.T) {
+func TestExecutionHandler_BodyAsJSON_NonObject_400(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
+	fr := &fakeRunner{}
+	pr := processrunner.New(fr)
 
-	mockRunner := mocks.NewMockRunner(ctrl)
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	trueVal := true
 	cmdCfg := &config.URLCommand{
 		URL: "POST /exec",
 		CommandConfig: config.CommandConfig{
 			CommandTemplate: "echo",
+			// Non-object JSON values are rejected because templates expect a JSON object.
 			Params: config.ParamsConfig{
 				BodyAsJSON: &trueVal,
 			},
 		},
 	}
 
-	testCases := []struct {
+	for _, tc := range []struct {
 		name string
 		body string
 	}{
 		{"array", `[1, 2, 3]`},
 		{"number", `123`},
 		{"string", `"some string"`},
-	}
-
-	for _, tc := range testCases {
+	} {
 		t.Run(tc.name, func(t *testing.T) {
 			t.Parallel()
 
-			handler := handlers.ExecutionHandler(mockRunner, nil)
-			h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
 			req := httptest.NewRequest(http.MethodPost, "/exec", strings.NewReader(tc.body))
-			ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-			req = req.WithContext(ctx)
+			req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
 			rr := httptest.NewRecorder()
 			h.ServeHTTP(rr, req)
 
 			if rr.Code != http.StatusBadRequest {
-				t.Errorf("%s: expected status 400, got %d", tc.name, rr.Code)
-			}
-
-			errMsg := rr.Header().Get("X-Error-Message")
-			if !strings.Contains(errMsg, "must be a JSON object") {
-				t.Errorf("%s: expected X-Error-Message to contain 'must be a JSON object', got %q", tc.name, errMsg)
+				t.Fatalf("expected status 400, got %d body=%q", rr.Code, rr.Body.String())
 			}
 		})
 	}
 }
 
-func TestExecutionHandler_BuildCommand_Success(t *testing.T) {
+func TestExecutionHandler_BuildCommand_Error_500(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate: "bash\n-c\necho {{.url.name}}",
-		},
-	}
-
-	// Expect command: bash, args: [-c, echo test]
-	mockRunner.EXPECT().
-		Command("bash", "-c", "echo test").
-		Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Wait().Return(nil)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
+	fr := &fakeRunner{}
+	pr := processrunner.New(fr)
 
-	handler := handlers.ExecutionHandler(mockRunner, nil)
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
-	req := httptest.NewRequest(http.MethodGet, "/exec?name=test", nil)
-	ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-	req = req.WithContext(ctx)
-
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
-	}
-}
-
-func TestExecutionHandler_BuildCommand_Error(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-
-	testCases := []struct {
+	for _, tc := range []struct {
 		name     string
 		template string
-		url      string
 	}{
-		{"syntax_error", "echo {{.url.name", "/exec?name=test"},
-		// Template execution error: in non-strict mode missing variables just render as <no value>
-		// To force an execution error, we can use a non-existent function or other template error.
-		{"execution_error", "echo {{.url.name | nonExistentFunc}}", "/exec?name=test"},
-	}
-
-	for _, tc := range testCases {
+		{"syntax_error", "echo {{.url.name"},
+		{"execution_error", "echo {{.url.name | nonExistentFunc}}"},
+	} {
 		t.Run(tc.name, func(t *testing.T) {
 			t.Parallel()
 
+			// Both syntax errors and execution errors should be surfaced as
+			// "error building command".
 			cmdCfg := &config.URLCommand{
 				URL: "GET /exec",
 				CommandConfig: config.CommandConfig{
@@ -579,216 +371,111 @@ func TestExecutionHandler_BuildCommand_Error(t *testing.T) {
 				},
 			}
 
-			handler := handlers.ExecutionHandler(mockRunner, nil)
-			h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-			req := httptest.NewRequest(http.MethodGet, tc.url, nil)
-			ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-			req = req.WithContext(ctx)
+			req := httptest.NewRequest(http.MethodGet, "/exec?name=test", nil)
+			req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
 			rr := httptest.NewRecorder()
 			h.ServeHTTP(rr, req)
 
-			// Both syntax error and execution error should result in 500 (default for unknown errors in ErrorSink)
-			// with message wrapped in "error building command"
 			if rr.Code != http.StatusInternalServerError {
-				t.Errorf("%s: expected status 500, got %d", tc.name, rr.Code)
-			}
-
-			errMsg := rr.Header().Get("X-Error-Message")
-			if !strings.Contains(errMsg, "error building command") {
-				t.Errorf("%s: expected X-Error-Message to contain 'error building command', got %q", tc.name, errMsg)
-			}
-		})
-	}
-}
-
-func TestExecutionHandler_PrepareOutput_Text(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	testCases := []struct {
-		name       string
-		outputType string
-	}{
-		{"default", ""},
-		{"explicit_text", "text"},
-	}
-
-	for _, tc := range testCases {
-		t.Run(tc.name, func(t *testing.T) {
-			t.Parallel()
-
-			cmdCfg := &config.URLCommand{
-				URL: "GET /exec",
-				CommandConfig: config.CommandConfig{
-					CommandTemplate: "echo hello",
-					OutputType:      tc.outputType,
-				},
-			}
-
-			mockRunner.EXPECT().Command("echo hello").Return(mockCmd)
-			mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-			mockCmd.EXPECT().SetStdout(gomock.Any())
-			mockCmd.EXPECT().SetStderr(gomock.Any())
-			mockCmd.EXPECT().Start().Return(nil)
-			mockCmd.EXPECT().Wait().Return(nil)
-			mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-			mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-
-			handler := handlers.ExecutionHandler(mockRunner, nil)
-			h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-			req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-			ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-			req = req.WithContext(ctx)
-
-			rr := httptest.NewRecorder()
-			h.ServeHTTP(rr, req)
-
-			if rr.Code != http.StatusOK {
-				t.Errorf("expected status 200, got %d", rr.Code)
+				t.Fatalf("expected status 500, got %d body=%q", rr.Code, rr.Body.String())
 			}
 
-			contentType := rr.Header().Get("Content-Type")
-			if contentType != "text/plain; charset=utf-8" {
-				t.Errorf("expected Content-Type 'text/plain; charset=utf-8', got %q", contentType)
+			msg := rr.Header().Get("X-Error-Message")
+			if !strings.Contains(msg, "error building command") {
+				t.Fatalf("expected X-Error-Message to contain %q, got %q", "error building command", msg)
 			}
 		})
 	}
 }
 
-type flusherRecorder struct {
-	*httptest.ResponseRecorder
-	flushed bool
-}
-
-func (f *flusherRecorder) Flush() {
-	f.flushed = true
-}
-
-func TestExecutionHandler_PrepareOutput_Stream_Success(t *testing.T) {
+func TestExecutionHandler_Stream_RequiresFlusher_500(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
+	fr := &fakeRunner{}
+	pr := processrunner.New(fr)
 
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
 		URL: "GET /exec",
 		CommandConfig: config.CommandConfig{
-			CommandTemplate: "test-command",
+			CommandTemplate: "echo hello",
 			OutputType:      "stream",
 		},
 	}
 
-	mockRunner.EXPECT().Command("test-command").Return(mockCmd)
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any()).Do(func(w io.Writer) {
-		_, _ = w.Write([]byte("stream data"))
-	})
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Wait().Return(nil)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
 	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-	req = req.WithContext(ctx)
-
-	fr := &flusherRecorder{ResponseRecorder: httptest.NewRecorder(), flushed: false}
-	h.ServeHTTP(fr, req)
-
-	if fr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", fr.Code)
-	}
-
-	headers := fr.Header()
-
-	if headers.Get("Content-Type") != "text/plain; charset=utf-8" {
-		t.Errorf("expected Content-Type 'text/plain; charset=utf-8', got %q", headers.Get("Content-Type"))
-	}
+	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
-	if headers.Get("Cache-Control") != "no-cache" {
-		t.Errorf("expected Cache-Control 'no-cache', got %q", headers.Get("Cache-Control"))
-	}
+	// Streaming responses require http.Flusher.
+	// This custom wrapper intentionally removes the Flusher interface
+	// to verify that the handler returns an error in this situation.
+	type nonFlusher struct{ http.ResponseWriter }
 
-	if headers.Get("X-Accel-Buffering") != "no" {
-		t.Errorf("expected X-Accel-Buffering 'no', got %q", headers.Get("X-Accel-Buffering"))
-	}
+	rr := httptest.NewRecorder()
+	h.ServeHTTP(nonFlusher{ResponseWriter: rr}, req)
 
-	if !fr.flushed {
-		t.Errorf("expected Flush() to be called")
+	if rr.Code != http.StatusInternalServerError {
+		t.Fatalf("expected status 500, got %d body=%q", rr.Code, rr.Body.String())
 	}
 
-	if fr.Body.String() != "stream data" {
-		t.Errorf("expected body 'stream data', got %q", fr.Body.String())
+	msg := rr.Header().Get("X-Error-Message")
+	if !strings.Contains(msg, "streaming not supported") {
+		t.Fatalf("expected X-Error-Message to contain %q, got %q", "streaming not supported", msg)
 	}
 }
 
-func TestExecutionHandler_PrepareOutput_Stream_Failure(t *testing.T) {
+func TestExecutionHandler_UnknownOutputType_500(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
+	fr := &fakeRunner{}
+	pr := processrunner.New(fr)
 
-	mockRunner := mocks.NewMockRunner(ctrl)
-	// We do NOT expect mockRunner.Command to be called because prepareOutput should return an error first.
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
 		URL: "GET /exec",
 		CommandConfig: config.CommandConfig{
-			CommandTemplate: "test-command",
-			OutputType:      "stream",
+			CommandTemplate: "echo hello",
+			OutputType:      "invalid",
 		},
 	}
 
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
 	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-	req = req.WithContext(ctx)
-
-	// Custom response writer that does NOT implement http.Flusher
-	type nonFlusherResponseWriter struct {
-		http.ResponseWriter
-	}
+	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
 	rr := httptest.NewRecorder()
-	h.ServeHTTP(nonFlusherResponseWriter{ResponseWriter: rr}, req)
+	h.ServeHTTP(rr, req)
 
 	if rr.Code != http.StatusInternalServerError {
-		t.Errorf("expected status 500, got %d", rr.Code)
+		t.Fatalf("expected status 500, got %d body=%q", rr.Code, rr.Body.String())
 	}
 
-	errMsg := rr.Header().Get("X-Error-Message")
-	if !strings.Contains(errMsg, "streaming not supported") {
-		t.Errorf("expected X-Error-Message to contain 'streaming not supported', got %q", errMsg)
+	msg := rr.Header().Get("X-Error-Message")
+	if !strings.Contains(msg, "unknown output type") {
+		t.Fatalf("expected X-Error-Message to contain %q, got %q", "unknown output type", msg)
 	}
 }
 
-func TestExecutionHandler_PrepareOutput_None(t *testing.T) {
+func TestExecutionHandler_OutputNone_ReturnsBeforeWait(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	// We do NOT use Cleanup(ctrl.Finish) here because we can't reliably wait for the async goroutine
-	// to call Wait() before the test finishes, which would cause a "missing call" error if Finish()
-	// is called too early.
+	// Block Wait() so we can verify that the handler returns immediately
+	// when outputType=none (asynchronous execution).
+	block := make(chan struct{})
 
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
+	fr := &fakeRunner{}
+	fr.cmd = &fakeCommand{
+		pid:       123,
+		waitBlock: block,
+	}
+	pr := processrunner.New(fr)
+
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
 		URL: "GET /exec",
@@ -798,345 +485,256 @@ func TestExecutionHandler_PrepareOutput_None(t *testing.T) {
 		},
 	}
 
-	mockRunner.EXPECT().Command("echo hello").Return(mockCmd)
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(io.Discard)
-	mockCmd.EXPECT().SetStderr(io.Discard)
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Wait().Return(nil).AnyTimes() // Use AnyTimes to avoid missing call if it finishes late
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
 	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-	req = req.WithContext(ctx)
+	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
 	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
+
+	// Run handler in a goroutine because we expect it to return
+	// before the command finishes.
+	done := make(chan struct{})
+	go func() {
+		h.ServeHTTP(rr, req)
+		close(done)
+	}()
+
+	// Handler should return quickly without waiting for Wait().
+	// If it blocks, asynchronous execution is broken.
+	select {
+	case <-done:
+		// ok
+	case <-time.After(80 * time.Millisecond):
+		close(block)
+		t.Fatalf("handler did not return quickly for outputType=none")
+	}
 
 	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
+		close(block)
+		t.Fatalf("expected status 200, got %d body=%q", rr.Code, rr.Body.String())
 	}
 
-	if rr.Body.Len() > 0 {
-		t.Errorf("expected empty body for outputType 'none', got %q", rr.Body.String())
+	if rr.Body.Len() != 0 {
+		close(block)
+		t.Fatalf("expected empty body, got %q", rr.Body.String())
 	}
+
+	// Cleanup: unblock Wait() so the fake command can finish.
+	close(block)
 }
 
-func TestExecutionHandler_CallGate(t *testing.T) {
+func TestExecutionHandler_CallGate_InvalidMode_500(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	defer ctrl.Finish()
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	mockRunner.EXPECT().
-		Command("echo hello").
-		Return(mockCmd).
-		AnyTimes()
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any()).AnyTimes()
-	mockCmd.EXPECT().SetStdout(gomock.Any()).AnyTimes()
-	mockCmd.EXPECT().SetStderr(gomock.Any()).AnyTimes()
-	mockCmd.EXPECT().Start().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Wait().Return(nil).AnyTimes()
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(1234).AnyTimes()
+	fr := &fakeRunner{}
+	pr := processrunner.New(fr)
 
 	registry := callgate.NewRegistry(callgate.WithDefaults())
-
-	handler := handlers.ExecutionHandler(mockRunner, registry)
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, registry)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
-	urlCmd := &config.URLCommand{
+	cmdCfg := &config.URLCommand{
 		URL: "GET /exec",
 		CommandConfig: config.CommandConfig{
 			CommandTemplate: "echo hello",
+			OutputType:      "text",
 			CallGate: &config.CallGateConfig{
 				GroupName: ptrString("test-group"),
-				Mode:      "single",
+				Mode:      "invalid-mode",
 			},
 		},
 	}
 
 	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	ctx := context.WithValue(req.Context(), handlers.URLCommandKey, urlCmd)
-	req = req.WithContext(ctx)
+	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
 	rr := httptest.NewRecorder()
 	h.ServeHTTP(rr, req)
 
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status OK, got %v", rr.Code)
+	if rr.Code != http.StatusInternalServerError {
+		t.Fatalf("expected status 500, got %d body=%q", rr.Code, rr.Body.String())
+	}
+
+	msg := rr.Header().Get("X-Error-Message")
+	if !strings.Contains(msg, "invalid callgate mode") {
+		t.Fatalf("expected X-Error-Message to contain %q, got %q", "invalid callgate mode", msg)
 	}
 }
 
-func TestExecutionHandler_UnknownCallGateMode(t *testing.T) {
+func TestExecutionHandler_CallGate_Busy_429(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	defer ctrl.Finish()
+	fr := &fakeRunner{}
+	pr := processrunner.New(fr)
 
-	mockRunner := mocks.NewMockRunner(ctrl)
 	registry := callgate.NewRegistry(callgate.WithDefaults())
-
-	handler := handlers.ExecutionHandler(mockRunner, registry)
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, registry)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
-	urlCmd := &config.URLCommand{
+	cmdCfg := &config.URLCommand{
 		URL: "GET /exec",
 		CommandConfig: config.CommandConfig{
 			CommandTemplate: "echo hello",
 			OutputType:      "text",
 			CallGate: &config.CallGateConfig{
 				GroupName: ptrString("test-group"),
-				Mode:      "invalid-mode",
+				Mode:      "single",
 			},
 		},
 	}
 
+	// Acquire the gate manually to simulate another request already running.
+	// The handler should detect this and return HTTP 429.
+	gate, _ := registry.GetOrCreate("test-group", "single")
+	release, _ := gate.Acquire(t.Context())
+
+	defer release()
+
 	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, urlCmd))
+	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
 	rr := httptest.NewRecorder()
 	h.ServeHTTP(rr, req)
 
-	if rr.Code != http.StatusInternalServerError {
-		t.Errorf("expected status 500 for invalid callgate mode, got %d, body=%q", rr.Code, rr.Body.String())
-	}
-
-	errMsg := rr.Header().Get("X-Error-Message")
-	if !strings.Contains(errMsg, "invalid callgate mode") {
-		t.Errorf("expected X-Error-Message to contain %q, got %q", "invalid callgate mode", errMsg)
+	if rr.Code != http.StatusTooManyRequests {
+		t.Fatalf("expected status 429, got %d body=%q", rr.Code, rr.Body.String())
 	}
 }
 
-func TestExecutionHandler_PrepareOutput_Unknown(t *testing.T) {
+func TestExecutionHandler_CallGate_ImplicitGroupName_IsolatesDifferentURLs(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
+	fr := &fakeRunner{}
+	fr.cmd = &fakeCommand{
+		pid: 123,
+		onStart: func(c *fakeCommand) {
+			c.mu.Lock()
+			defer c.mu.Unlock()
+			_, _ = c.stdout.Write([]byte("ok"))
+		},
+	}
+	pr := processrunner.New(fr)
 
-	mockRunner := mocks.NewMockRunner(ctrl)
+	registry := callgate.NewRegistry(callgate.WithDefaults())
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, registry)
+	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
+	cmdCfg1 := &config.URLCommand{
+		URL: "GET /exec1",
 		CommandConfig: config.CommandConfig{
 			CommandTemplate: "echo hello",
-			OutputType:      "invalid",
+			OutputType:      "text",
+			CallGate: &config.CallGateConfig{
+				// If GroupName is nil, the handler uses the URL definition (e.g. "GET /exec1")
+				// as the implicit callgate group name.
+				GroupName: nil,
+				Mode:      "single",
+			},
 		},
 	}
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	ctx := context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg)
-	req = req.WithContext(ctx)
-
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
-
-	if rr.Code != http.StatusInternalServerError {
-		t.Errorf("expected status 500, got %d", rr.Code)
-	}
-
-	errMsg := rr.Header().Get("X-Error-Message")
-	if !strings.Contains(errMsg, "unknown output type") {
-		t.Errorf("expected X-Error-Message to contain 'unknown output type', got %q", errMsg)
-	}
-}
-
-func TestExecutionHandler_ExecuteCommand_StartError_WritesFailedToStart(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
+	cmdCfg2 := &config.URLCommand{
+		URL: "GET /exec2",
 		CommandConfig: config.CommandConfig{
 			CommandTemplate: "echo hello",
 			OutputType:      "text",
+			CallGate: &config.CallGateConfig{
+				GroupName: nil,
+				Mode:      "single",
+			},
 		},
 	}
 
-	mockRunner.EXPECT().
-		Command("echo hello").
-		Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-
-	mockCmd.EXPECT().Start().Return(errors.New("start boom"))
-	mockCmd.EXPECT().Wait().Times(0)
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
+	// Block the implicit group for /exec1 only.
+	g1, _ := registry.GetOrCreate("GET /exec1", "single")
+	release, _ := g1.Acquire(t.Context())
 
-	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
+	defer release()
 
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
+	req1 := httptest.NewRequest(http.MethodGet, "/exec1", nil)
+	req1 = req1.WithContext(context.WithValue(req1.Context(), handlers.URLCommandKey, cmdCfg1))
+	rr1 := httptest.NewRecorder()
+	h.ServeHTTP(rr1, req1)
 
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d, body=%q", rr.Code, rr.Body.String())
+	if rr1.Code != http.StatusTooManyRequests {
+		t.Fatalf("expected status 429 for /exec1, got %d body=%q", rr1.Code, rr1.Body.String())
 	}
 
-	errMsg := rr.Header().Get("X-Error-Message")
-	if !strings.Contains(errMsg, "failed to start command") {
-		t.Errorf("expected X-Error-Message header to contain %q, got %q", "failed to start command", errMsg)
+	// /exec2 uses a different implicit group name and should not be blocked.
+	req2 := httptest.NewRequest(http.MethodGet, "/exec2", nil)
+	req2 = req2.WithContext(context.WithValue(req2.Context(), handlers.URLCommandKey, cmdCfg2))
+	rr2 := httptest.NewRecorder()
+	h.ServeHTTP(rr2, req2)
+
+	if rr2.Code != http.StatusOK {
+		t.Fatalf("expected status 200 for /exec2, got %d body=%q", rr2.Code, rr2.Body.String())
 	}
 }
 
-func TestExecutionHandler_ExecuteCommand_StdoutAndStderr_WriteToSameResponseWriter(t *testing.T) {
+func TestExecutionHandler_CallGate_SharedGroupName_SharedAcrossURLs(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
+	fr := &fakeRunner{}
+	pr := processrunner.New(fr)
 
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
+	registry := callgate.NewRegistry(callgate.WithDefaults())
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, registry)
+	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
+	// When an explicit GroupName is provided, multiple URLs share the same gate.
+	shared := "shared"
+
+	cmdCfg1 := &config.URLCommand{
+		URL: "GET /exec1",
 		CommandConfig: config.CommandConfig{
 			CommandTemplate: "echo hello",
 			OutputType:      "text",
+			CallGate: &config.CallGateConfig{
+				GroupName: &shared,
+				Mode:      "single",
+			},
 		},
 	}
-
-	var (
-		gotStdout io.Writer
-		gotStderr io.Writer
-	)
-
-	mockRunner.EXPECT().
-		Command("echo hello").
-		Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-
-	mockCmd.EXPECT().SetStdout(gomock.Any()).Do(func(w io.Writer) {
-		gotStdout = w
-		_, _ = w.Write([]byte("OUT\n"))
-	})
-
-	mockCmd.EXPECT().SetStderr(gomock.Any()).Do(func(w io.Writer) {
-		gotStderr = w
-		_, _ = w.Write([]byte("ERR\n"))
-	})
-
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Wait().Return(nil)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
-
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
-	}
-
-	if gotStdout == nil || gotStderr == nil {
-		t.Fatalf("expected stdout and stderr writers to be captured, got stdout=%v stderr=%v", gotStdout, gotStderr)
-	}
-
-	// Both should reference the same writer instance.
-	if gotStdout != gotStderr {
-		t.Errorf("expected stdout and stderr to be the same writer, got stdout=%T(%p) stderr=%T(%p)",
-			gotStdout, gotStdout, gotStderr, gotStderr)
-	}
-
-	body := rr.Body.String()
-	if !strings.Contains(body, "OUT") || !strings.Contains(body, "ERR") {
-		t.Errorf("expected response body to contain both OUT and ERR, got %q", body)
-	}
-}
-
-func TestExecutionHandler_ExecuteCommand_SetsSetpgidTrue(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
+	cmdCfg2 := &config.URLCommand{
+		URL: "GET /exec2",
 		CommandConfig: config.CommandConfig{
 			CommandTemplate: "echo hello",
 			OutputType:      "text",
+			CallGate: &config.CallGateConfig{
+				GroupName: &shared,
+				Mode:      "single",
+			},
 		},
 	}
 
-	mockRunner.EXPECT().
-		Command("echo hello").
-		Return(mockCmd)
-
-	mockCmd.EXPECT().
-		SetSysProcAttr(gomock.Any()).
-		Do(func(attr *syscall.SysProcAttr) {
-			if attr == nil {
-				t.Errorf("expected non-nil SysProcAttr")
-
-				return
-			}
-
-			if attr.Setpgid != true {
-				t.Errorf("expected Setpgid=true, got %v", attr.Setpgid)
-			}
-		})
+	// Hold the shared gate so both endpoints should be rejected.
+	g, _ := registry.GetOrCreate("shared", "single")
+	release, _ := g.Acquire(t.Context())
 
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Wait().Return(nil)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
+	defer release()
 
-	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
+	for _, tc := range []struct {
+		path   string
+		cmdCfg *config.URLCommand
+	}{
+		{"/exec1", cmdCfg1},
+		{"/exec2", cmdCfg2},
+	} {
+		req := httptest.NewRequest(http.MethodGet, tc.path, nil)
+		req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, tc.cmdCfg))
 
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
+		rr := httptest.NewRecorder()
+		h.ServeHTTP(rr, req)
 
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
+		if rr.Code != http.StatusTooManyRequests {
+			t.Fatalf("expected status 429 for %s, got %d body=%q", tc.path, rr.Code, rr.Body.String())
+		}
 	}
 }
 
-func TestExecutionHandler_SyncWait_ExitError_NonZeroExit_WritesFailureMessage(t *testing.T) {
+func TestExecutionHandler_NonZeroExit_SetsExitCodeHeader(t *testing.T) {
 	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	// Create a real *exec.ExitError to exercise errors.As(..., *exec.ExitError).
+	// Create a real *exec.ExitError to simulate a command exiting with code 7.
+	// This ensures the handler correctly extracts exit codes from errors.
 	runErr := exec.Command("sh", "-c", "exit 7").Run()
 
 	var exitErr *exec.ExitError
@@ -1144,125 +742,29 @@ func TestExecutionHandler_SyncWait_ExitError_NonZeroExit_WritesFailureMessage(t
 		t.Fatalf("expected *exec.ExitError, got %T: %v", runErr, runErr)
 	}
 
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate: "test-command",
-			OutputType:      "text",
-		},
-	}
-
-	mockRunner.EXPECT().Command("test-command").Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-
-	mockCmd.EXPECT().Wait().Return(exitErr)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
-
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
-	}
-
-	exitCodeHeader := rr.Header().Get("X-Exit-Code")
-	if exitCodeHeader != "7" {
-		t.Errorf("expected X-Exit-Code header to be 7, got %q", exitCodeHeader)
-	}
-}
-
-func TestExecutionHandler_SyncWait_WaitReturnsNonExitError_WritesFailureMessage(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate: "test-command",
-			OutputType:      "text",
+	fr := &fakeRunner{}
+	fr.cmd = &fakeCommand{
+		pid:     123,
+		waitErr: exitErr,
+		onStart: func(c *fakeCommand) {
+			c.mu.Lock()
+			defer c.mu.Unlock()
+			_, _ = c.stdout.Write([]byte("OUT\n"))
 		},
 	}
+	pr := processrunner.New(fr)
 
-	mockRunner.EXPECT().Command("test-command").Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-
-	waitErr := errors.New("wait boom")
-	mockCmd.EXPECT().Wait().Return(waitErr)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
+	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
-	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
-
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
-	}
-
-	exitCodeHeader := rr.Header().Get("X-Exit-Code")
-	if exitCodeHeader != "" {
-		t.Errorf("expected X-Exit-Code header to be empty, got %q", exitCodeHeader)
-	}
-
-	errorMessageHeader := rr.Header().Get("X-Error-Message")
-	if !strings.Contains(errorMessageHeader, "wait boom") {
-		t.Errorf("expected X-Error-Message header to contain %q, got %q", "wait boom", errorMessageHeader)
-	}
-}
-
-func TestExecutionHandler_SyncWait_NoError_ProcessStateNil_DoesNotWriteFailureMessage(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
 	cmdCfg := &config.URLCommand{
 		URL: "GET /exec",
 		CommandConfig: config.CommandConfig{
-			CommandTemplate: "test-command",
+			CommandTemplate: "echo hello",
 			OutputType:      "text",
 		},
 	}
 
-	mockRunner.EXPECT().Command("test-command").Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-
-	mockCmd.EXPECT().Wait().Return(nil)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
 	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
 	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
@@ -1270,757 +772,17 @@ func TestExecutionHandler_SyncWait_NoError_ProcessStateNil_DoesNotWriteFailureMe
 	h.ServeHTTP(rr, req)
 
 	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
-	}
-
-	if strings.Contains(rr.Body.String(), "Command failed with exit code:") {
-		t.Errorf("expected no failure message, got %q", rr.Body.String())
-	}
-}
-
-func TestExecutionHandler_TerminateOnCancel_NoGrace_SendsSIGKILL(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate:         "echo hello",
-			OutputType:              "text",
-			GraceTerminationTimeout: nil,
-		},
-	}
-
-	mockRunner.EXPECT().Command("echo hello").Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-
-	waitUnblock := make(chan struct{})
-
-	mockCmd.EXPECT().Wait().DoAndReturn(func() error {
-		<-waitUnblock
-
-		return errors.New("wait error")
-	})
-
-	killed := make(chan struct{})
-
-	mockRunner.EXPECT().
-		Kill(-123, syscall.SIGKILL).
-		DoAndReturn(func(_ int, _ syscall.Signal) error {
-			close(killed)
-			close(waitUnblock)
-
-			return nil
-		})
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	ctx, cancel := context.WithCancel(req.Context())
-
-	cancel() // cancel before handler runs
-
-	req = req.WithContext(context.WithValue(ctx, handlers.URLCommandKey, cmdCfg))
-
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
-
-	select {
-	case <-killed:
-	default:
-		t.Fatalf("expected SIGKILL to be sent")
-	}
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
-	}
-
-	errMsg := rr.Header().Get("X-Error-Message")
-	if errMsg == "" {
-		t.Fatalf("expected X-Error-Message header to be set")
-	}
-
-	if !strings.Contains(errMsg, "wait error") {
-		t.Errorf("expected X-Error-Message header to contain %q, got %q", "wait error", errMsg)
-	}
-}
-
-func TestExecutionHandler_TerminateOnCancel_WithGrace_Timeout_SendsSIGTERMThenSIGKILL(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	grace := 10 * time.Millisecond
-
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate:         "echo hello",
-			OutputType:              "text",
-			GraceTerminationTimeout: &grace,
-		},
-	}
-
-	mockRunner.EXPECT().Command("echo hello").Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-
-	// Block long enough so grace timer fires.
-	mockCmd.EXPECT().Wait().DoAndReturn(func() error {
-		time.Sleep(50 * time.Millisecond)
-
-		return errors.New("wait error")
-	})
-
-	gomock.InOrder(
-		mockRunner.EXPECT().Kill(-123, syscall.SIGTERM).Return(nil),
-		mockRunner.EXPECT().Kill(-123, syscall.SIGKILL).Return(nil),
-	)
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	ctx, cancel := context.WithCancel(req.Context())
-
-	cancel()
-
-	req = req.WithContext(context.WithValue(ctx, handlers.URLCommandKey, cmdCfg))
-
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
+		t.Fatalf("expected status 200, got %d body=%q", rr.Code, rr.Body.String())
 	}
-}
-
-func TestExecutionHandler_TerminateOnCancel_WithGrace_ProcessEndsBeforeTimer_SendsOnlySIGTERM(t *testing.T) {
-	t.Parallel()
 
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	grace := 100 * time.Millisecond
-
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate:         "echo hello",
-			OutputType:              "text",
-			GraceTerminationTimeout: &grace,
-		},
+	// Non-zero exit codes are treated as valid results,
+	// so the handler returns HTTP 200 and exposes the exit code via header.
+	if rr.Header().Get("X-Exit-Code") != "7" {
+		t.Fatalf("expected X-Exit-Code=7, got %q", rr.Header().Get("X-Exit-Code"))
 	}
 
-	mockRunner.EXPECT().Command("echo hello").Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-
-	// Finish quickly (before grace expires).
-	mockCmd.EXPECT().Wait().DoAndReturn(func() error {
-		time.Sleep(5 * time.Millisecond)
-
-		return errors.New("wait error")
-	})
-
-	mockRunner.EXPECT().Kill(-123, syscall.SIGTERM).Return(nil)
-	mockRunner.EXPECT().Kill(-123, syscall.SIGKILL).Times(0)
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	ctx, cancel := context.WithCancel(req.Context())
-
-	cancel()
-
-	req = req.WithContext(context.WithValue(ctx, handlers.URLCommandKey, cmdCfg))
-
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
-	}
-}
-
-func TestExecutionHandler_DeadlineExceeded_DoesNotOverrideWaitResult(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	// Create a real *exec.ExitError with a non-zero exit code.
-	runErr := exec.Command("sh", "-c", "exit 7").Run()
-
-	var exitErr *exec.ExitError
-	if !errors.As(runErr, &exitErr) {
-		t.Fatalf("expected *exec.ExitError, got %T: %v", runErr, runErr)
-	}
-
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate: "echo hello",
-			OutputType:      "text",
-		},
-	}
-
-	mockRunner.EXPECT().Command("echo hello").Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-
-	// Prevent signalProcessGroup from calling runner.Kill.
-	mockCmd.EXPECT().Pid().Return(0).AnyTimes()
-
-	// Wait returns exit error (exit code 7).
-	mockCmd.EXPECT().Wait().Return(exitErr)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-
-	// Deadline already exceeded.
-	ctx, cancel := context.WithDeadline(req.Context(), time.Now().Add(-1*time.Second))
-	defer cancel()
-
-	req = req.WithContext(context.WithValue(ctx, handlers.URLCommandKey, cmdCfg))
-
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
-	}
-
-	// Wait() result wins over context cancellation, so we should report exit code 7.
-	exitCodeHeader := rr.Header().Get("X-Exit-Code")
-	if exitCodeHeader != "7" {
-		t.Errorf("expected X-Exit-Code header to be %q, got %q", "7", exitCodeHeader)
-	}
-
-	// Since non-zero exit is treated as a normal result (exit code + nil error),
-	// there should be no context-related error message.
-	errMsg := rr.Header().Get("X-Error-Message")
-	if errMsg != "" {
-		t.Errorf("expected X-Error-Message header to be empty, got %q", errMsg)
-	}
-}
-
-func TestExecutionHandler_AsyncNone_ReturnsBeforeWait(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate: "echo hello",
-			OutputType:      "none", // async
-		},
-	}
-
-	mockRunner.EXPECT().Command("echo hello").Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(io.Discard)
-	mockCmd.EXPECT().SetStderr(io.Discard)
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-
-	waitStarted := make(chan struct{})
-	unblockWait := make(chan struct{})
-
-	mockCmd.EXPECT().Wait().DoAndReturn(func() error {
-		close(waitStarted) // signal: goroutine reached Wait()
-		<-unblockWait      // block until test allows it
-
-		return nil
-	})
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
-
-	rr := httptest.NewRecorder()
-
-	done := make(chan struct{})
-	go func() {
-		h.ServeHTTP(rr, req)
-		close(done)
-	}()
-
-	// Handler should finish quickly without waiting for Wait()
-	select {
-	case <-done:
-		// ok
-	case <-time.After(50 * time.Millisecond):
-		t.Fatalf("handler did not return quickly; it may be waiting for Wait()")
-	}
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
-	}
-
-	if rr.Body.Len() != 0 {
-		t.Errorf("expected empty body for outputType 'none', got %q", rr.Body.String())
-	}
-
-	// Ensure Wait() actually ran in a goroutine
-	select {
-	case <-waitStarted:
-		// ok
-	case <-time.After(200 * time.Millisecond):
-		t.Fatalf("expected Wait() to be called asynchronously")
-	}
-
-	// cleanup: allow Wait() to finish so gomock expectations can be satisfied
-	close(unblockWait)
-}
-
-//nolint:paralleltest
-func TestExecutionHandler_AsyncNone_WaitError_LogsButDoesNotAffectResponse(t *testing.T) {
-	// Do NOT run in parallel: log.SetOutput is global.
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate: "echo hello",
-			OutputType:      "none",
-		},
-	}
-
-	mockRunner.EXPECT().Command("echo hello").Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(io.Discard)
-	mockCmd.EXPECT().SetStderr(io.Discard)
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-
-	waitDone := make(chan struct{})
-
-	mockCmd.EXPECT().Wait().DoAndReturn(func() error {
-		defer close(waitDone)
-
-		return errors.New("wait boom")
-	})
-
-	var (
-		buf strings.Builder
-		mu  sync.Mutex
-	)
-
-	origOut := log.Writer()
-
-	log.SetOutput(&syncedWriter{Writer: &buf, mu: &mu})
-	t.Cleanup(func() { log.SetOutput(origOut) })
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
-
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
-	}
-
-	if rr.Body.Len() != 0 {
-		t.Errorf("expected empty body, got %q", rr.Body.String())
-	}
-
-	// Wait() returned, but the goroutine may not have logged yet.
-	select {
-	case <-waitDone:
-	case <-time.After(200 * time.Millisecond):
-		t.Fatalf("expected async Wait() to finish")
-	}
-
-	// Poll logs until the error line appears (or timeout).
-	deadline := time.Now().Add(300 * time.Millisecond)
-
-	for {
-		mu.Lock()
-		logs := buf.String()
-		mu.Unlock()
-
-		if strings.Contains(logs, "Asynchronous command failed") && strings.Contains(logs, "wait boom") {
-			break
-		}
-
-		if time.Now().After(deadline) {
-			t.Fatalf(
-				"expected logs to contain %q and %q, got %q",
-				"Asynchronous command failed", "wait boom", logs,
-			)
-		}
-
-		time.Sleep(5 * time.Millisecond)
-	}
-}
-
-func TestExecutionHandler_RunCommand_SetsExitCodeHeader_OnNonZeroExit(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	// real *exec.ExitError with exit code 7
-	runErr := exec.Command("sh", "-c", "exit 7").Run()
-
-	var exitErr *exec.ExitError
-
-	if !errors.As(runErr, &exitErr) {
-		t.Fatalf("expected *exec.ExitError, got %T: %v", runErr, runErr)
-	}
-
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate: "echo hello",
-			OutputType:      "text",
-		},
-	}
-
-	mockRunner.EXPECT().Command("echo hello").Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any()).Do(func(w io.Writer) {
-		// simulate process output
-		_, _ = w.Write([]byte("PROC_OUT\n"))
-	})
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Wait().Return(exitErr)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
-
-	rr := httptest.NewRecorder()
-	h.ServeHTTP(rr, req)
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status 200, got %d", rr.Code)
-	}
-
-	body := rr.Body.String()
-	if !strings.Contains(body, "PROC_OUT") {
-		t.Errorf("expected body to contain process output, got %q", body)
-	}
-
-	exitCodeHeader := rr.Header().Get("X-Exit-Code")
-	if exitCodeHeader != "7" {
-		t.Errorf("expected X-Exit-Code header to be 7, got %q", exitCodeHeader)
-	}
-}
-
-type erroringResponseWriter struct {
-	*httptest.ResponseRecorder
-	writeErr error
-}
-
-func (e *erroringResponseWriter) Write(p []byte) (int, error) {
-	_, _ = e.ResponseRecorder.Write(p)
-
-	return 0, e.writeErr
-}
-
-//nolint:paralleltest
-func TestExecutionHandler_RunCommand_WriteErrorMessageWriteFails_LogsError(t *testing.T) {
-	// Do NOT run in parallel: log.SetOutput is global.
-	ctrl := gomock.NewController(t)
-
-	t.Cleanup(ctrl.Finish)
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	// real *exec.ExitError with exit code 7 -> triggers errorMessage write
-	runErr := exec.Command("sh", "-c", "exit 7").Run()
-
-	var exitErr *exec.ExitError
-	if !errors.As(runErr, &exitErr) {
-		t.Fatalf("expected *exec.ExitError, got %T: %v", runErr, runErr)
-	}
-
-	cmdCfg := &config.URLCommand{
-		URL: "GET /exec",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate: "echo hello",
-			OutputType:      "text",
-		},
-	}
-
-	mockRunner.EXPECT().Command("echo hello").Return(mockCmd)
-
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any())
-	mockCmd.EXPECT().SetStdout(gomock.Any())
-	mockCmd.EXPECT().SetStderr(gomock.Any())
-	mockCmd.EXPECT().Start().Return(nil)
-	mockCmd.EXPECT().Wait().Return(exitErr)
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(123).AnyTimes()
-
-	// capture logs
-	var (
-		buf strings.Builder
-		mu  sync.Mutex
-	)
-
-	origOut := log.Writer()
-
-	log.SetOutput(&syncedWriter{Writer: &buf, mu: &mu})
-	t.Cleanup(func() { log.SetOutput(origOut) })
-
-	handler := handlers.ExecutionHandler(mockRunner, nil)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
-	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
-
-	rw := &erroringResponseWriter{
-		ResponseRecorder: httptest.NewRecorder(),
-		writeErr:         errors.New("write failed"),
-	}
-
-	h.ServeHTTP(rw, req)
-
-	// We only care that it logged the failure to write the error message.
-	// Poll a bit because logging happens synchronously here, but polling makes it robust.
-	deadline := time.Now().Add(200 * time.Millisecond)
-
-	for {
-		mu.Lock()
-		logs := buf.String()
-		mu.Unlock()
-
-		if strings.Contains(logs, "failed to write buffered output") {
-			if !strings.Contains(logs, "write failed") {
-				t.Fatalf("expected logs to contain %q, got %q", "write failed", logs)
-			}
-
-			break
-		}
-
-		if time.Now().After(deadline) {
-			t.Fatalf("expected logs to contain %q, got %q", "failed to write buffered output", logs)
-		}
-
-		time.Sleep(5 * time.Millisecond)
-	}
-}
-
-func ptrString(s string) *string {
-	return &s
-}
-
-func TestExecutionHandler_CallGate_ImplicitGroupName(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	defer ctrl.Finish()
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	mockRunner.EXPECT().Command("echo hello").Return(mockCmd).Times(1)
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any()).AnyTimes()
-	mockCmd.EXPECT().SetStdout(gomock.Any()).AnyTimes()
-	mockCmd.EXPECT().SetStderr(gomock.Any()).AnyTimes()
-	mockCmd.EXPECT().Start().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Wait().Return(nil).AnyTimes()
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(1234).AnyTimes()
-
-	registry := callgate.NewRegistry(callgate.WithDefaults())
-
-	handler := handlers.ExecutionHandler(mockRunner, registry)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	// URL 1
-	urlCmd1 := &config.URLCommand{
-		URL: "GET /exec1",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate: "echo hello",
-			CallGate: &config.CallGateConfig{
-				GroupName: nil, // Implicitly "GET /exec1"
-				Mode:      "single",
-			},
-		},
-	}
-
-	// URL 2 - same template, different URL, no GroupName -> should have DIFFERENT implicit group names
-	urlCmd2 := &config.URLCommand{
-		URL: "GET /exec2",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate: "echo hello",
-			CallGate: &config.CallGateConfig{
-				GroupName: nil, // Implicitly "GET /exec2"
-				Mode:      "single",
-			},
-		},
-	}
-
-	// 1. Run URL 1
-	req1 := httptest.NewRequest(http.MethodGet, "/exec1", nil)
-	req1 = req1.WithContext(context.WithValue(req1.Context(), handlers.URLCommandKey, urlCmd1))
-	rr1 := httptest.NewRecorder()
-
-	// Simulating a long running command for URL 1 would be better, but here we just check if they don't interfere.
-	// Actually, let's use a shared group name to see it blocks, and then use nil to see it doesn't.
-
-	// Test isolation:
-	// We'll use a gate to block URL 1, and see if URL 2 is still allowed.
-
-	gate1, _ := registry.GetOrCreate("GET /exec1", "single")
-	release, _ := gate1.Acquire(t.Context())
-
-	defer release()
-
-	// Now GET /exec1 is busy.
-	h.ServeHTTP(rr1, req1)
-
-	if rr1.Code != http.StatusTooManyRequests {
-		t.Errorf("expected status 429 for /exec1, got %v", rr1.Code)
-	}
-
-	// But GET /exec2 should be FREE because it has a different implicit group name.
-	req2 := httptest.NewRequest(http.MethodGet, "/exec2", nil)
-	req2 = req2.WithContext(context.WithValue(req2.Context(), handlers.URLCommandKey, urlCmd2))
-	rr2 := httptest.NewRecorder()
-	h.ServeHTTP(rr2, req2)
-
-	if rr2.Code != http.StatusOK {
-		t.Errorf("expected status 200 for /exec2, got %v", rr2.Code)
-	}
-}
-
-func TestExecutionHandler_CallGate_EmptyGroupName(t *testing.T) {
-	t.Parallel()
-
-	ctrl := gomock.NewController(t)
-	defer ctrl.Finish()
-
-	mockRunner := mocks.NewMockRunner(ctrl)
-	mockCmd := mocks.NewMockCommand(ctrl)
-
-	mockRunner.EXPECT().Command("echo hello").Return(mockCmd).AnyTimes()
-	mockCmd.EXPECT().SetSysProcAttr(gomock.Any()).AnyTimes()
-	mockCmd.EXPECT().SetStdout(gomock.Any()).AnyTimes()
-	mockCmd.EXPECT().SetStderr(gomock.Any()).AnyTimes()
-	mockCmd.EXPECT().Start().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Wait().Return(nil).AnyTimes()
-	mockCmd.EXPECT().ProcessState().Return(nil).AnyTimes()
-	mockCmd.EXPECT().Pid().Return(1234).AnyTimes()
-
-	registry := callgate.NewRegistry(callgate.WithDefaults())
-	handler := handlers.ExecutionHandler(mockRunner, registry)
-	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
-
-	// URL 1 with empty groupName
-	urlCmd1 := &config.URLCommand{
-		URL: "GET /exec1",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate: "echo hello",
-			CallGate: &config.CallGateConfig{
-				GroupName: ptrString(""),
-				Mode:      "single",
-			},
-		},
-	}
-
-	// URL 2 with empty groupName -> should SHARE the same "" group
-	urlCmd2 := &config.URLCommand{
-		URL: "GET /exec2",
-		CommandConfig: config.CommandConfig{
-			CommandTemplate: "echo hello",
-			CallGate: &config.CallGateConfig{
-				GroupName: ptrString(""),
-				Mode:      "single",
-			},
-		},
-	}
-
-	// Block the "" group
-	gate, _ := registry.GetOrCreate("", "single")
-	release, _ := gate.Acquire(t.Context())
-
-	defer release()
-
-	// Both should be blocked
-	for _, cmd := range []*config.URLCommand{urlCmd1, urlCmd2} {
-		req := httptest.NewRequest(http.MethodGet, strings.Split(cmd.URL, " ")[1], nil)
-		req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmd))
-		rr := httptest.NewRecorder()
-
-		h.ServeHTTP(rr, req)
-
-		if rr.Code != http.StatusTooManyRequests {
-			t.Errorf("expected status 429 for %s, got %v", cmd.URL, rr.Code)
-		}
+	// Non-zero exit is treated as "normal" in this API => no error message.
+	if rr.Header().Get("X-Error-Message") != "" {
+		t.Fatalf("expected empty X-Error-Message, got %q", rr.Header().Get("X-Error-Message"))
 	}
 }
diff --git a/pkg/router/handlers/fakes_test.go b/pkg/router/handlers/fakes_test.go
new file mode 100644
index 0000000..d3d7aa6
--- /dev/null
+++ b/pkg/router/handlers/fakes_test.go
@@ -0,0 +1,173 @@
+package handlers_test
+
+import (
+	"errors"
+	"io"
+	"net/http/httptest"
+	"os"
+	"sync"
+	"syscall"
+
+	"github.com/dkarczmarski/webcmd/pkg/cmdrunner"
+)
+
+// fakeRunner is a lightweight test double for cmdrunner.Runner.
+// It records the last command invocation and returns a configurable fakeCommand.
+type fakeRunner struct {
+	mu sync.Mutex
+
+	gotCommand string
+	gotArgs    []string
+
+	cmd *fakeCommand
+
+	killMu    sync.Mutex
+	killCalls []killCall
+	killHook  func(pid int, sig syscall.Signal) error
+}
+
+type killCall struct {
+	pid int
+	sig syscall.Signal
+}
+
+// Command records the command invocation and returns a fake command instance.
+// A shallow copy of args is stored to avoid accidental mutation by the caller.
+func (r *fakeRunner) Command(command string, args ...string) cmdrunner.Command {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	r.gotCommand = command
+
+	r.gotArgs = append([]string(nil), args...)
+
+	if r.cmd == nil {
+		r.cmd = &fakeCommand{pid: 123}
+	}
+
+	return r.cmd
+}
+
+// Kill records kill signals sent to the process group.
+// Tests can optionally inject a hook to simulate failures or synchronization.
+func (r *fakeRunner) Kill(pid int, sig syscall.Signal) error {
+	r.killMu.Lock()
+	r.killCalls = append(r.killCalls, killCall{pid: pid, sig: sig})
+	hook := r.killHook
+	r.killMu.Unlock()
+
+	if hook != nil {
+		return hook(pid, sig)
+	}
+
+	return nil
+}
+
+// SnapshotCommand returns the last recorded command and a copy of its args.
+// Copying prevents data races if tests read the values while the handler runs.
+func (r *fakeRunner) SnapshotCommand() (string, []string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	return r.gotCommand, append([]string(nil), r.gotArgs...)
+}
+
+// fakeCommand simulates cmdrunner.Command.
+// It allows tests to control process lifecycle behavior (Start/Wait)
+// and capture stdout/stderr writers configured by the handler.
+type fakeCommand struct {
+	mu sync.Mutex
+
+	stdout io.Writer
+	stderr io.Writer
+
+	sys *syscall.SysProcAttr
+
+	startErr error
+	waitErr  error
+
+	// waitBlock allows tests to artificially block Wait().
+	// This is useful for testing asynchronous behavior where the handler
+	// must return before the command finishes.
+	waitBlock <-chan struct{}
+
+	pid int
+
+	// onStart allows tests to simulate process output immediately after Start().
+	// This mimics a running command writing to stdout/stderr.
+	onStart func(c *fakeCommand)
+}
+
+func (c *fakeCommand) SetSysProcAttr(attr *syscall.SysProcAttr) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.sys = attr
+}
+
+func (c *fakeCommand) SetStdout(w io.Writer) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.stdout = w
+}
+
+func (c *fakeCommand) SetStderr(w io.Writer) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.stderr = w
+}
+
+// Start simulates starting the command.
+// If startErr is set, the start fails.
+// Otherwise an optional hook can simulate process output.
+func (c *fakeCommand) Start() error {
+	c.mu.Lock()
+	err := c.startErr
+	onStart := c.onStart
+	c.mu.Unlock()
+
+	if err != nil {
+		return err
+	}
+
+	if onStart != nil {
+		onStart(c)
+	}
+
+	return nil
+}
+
+// Wait simulates process completion.
+// Tests can block this call using waitBlock to verify async behavior.
+func (c *fakeCommand) Wait() error {
+	if c.waitBlock != nil {
+		<-c.waitBlock
+	}
+
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	return c.waitErr
+}
+
+func (c *fakeCommand) ProcessState() *os.ProcessState { //nolint:forbidigo // explicit nil is what we need for tests
+	return nil
+}
+
+func (c *fakeCommand) Pid() int { return c.pid }
+
+// flusherRecorder extends httptest.ResponseRecorder to track Flush() calls.
+// Streaming handlers require http.Flusher, which ResponseRecorder does not track.
+type flusherRecorder struct {
+	*httptest.ResponseRecorder
+	flushed bool
+}
+
+func (f *flusherRecorder) Flush() { f.flushed = true }
+
+func ptrString(s string) *string { return &s }
+
+type errorReader struct{}
+
+// errorReader simulates a request body that fails during Read(),
+// allowing the handler's error path to be tested.
+func (e *errorReader) Read(_ []byte) (int, error) { return 0, errors.New("read error") }
diff --git a/pkg/router/router.go b/pkg/router/router.go
index 3561ff4..ee0b0db 100644
--- a/pkg/router/router.go
+++ b/pkg/router/router.go
@@ -9,11 +9,13 @@ import (
 	"github.com/dkarczmarski/webcmd/pkg/cmdrunner"
 	"github.com/dkarczmarski/webcmd/pkg/config"
 	"github.com/dkarczmarski/webcmd/pkg/httpx"
+	"github.com/dkarczmarski/webcmd/pkg/processrunner"
 	"github.com/dkarczmarski/webcmd/pkg/router/handlers"
 )
 
 // New creates and initializes a new http.ServeMux instance with the given configuration.
 func New(configuration *config.Config) *http.ServeMux {
+	processRunner := processrunner.New(&cmdrunner.RealRunner{})
 	registry := callgate.NewRegistry(callgate.WithDefaults())
 	mux := http.NewServeMux()
 	mux.Handle("/", httpx.ToHandler(
@@ -26,7 +28,7 @@ func New(configuration *config.Config) *http.ServeMux {
 				handlers.AuthorizationMiddleware(),
 				handlers.TimeoutMiddleware(),
 			),
-			handlers.ExecutionHandler(&cmdrunner.RealRunner{}, registry),
+			handlers.ExecutionHandler(processRunner, registry),
 		)))
 
 	return mux

From 10e668f217005c5c29961a4a80d3bdd101d9787d Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Fri, 6 Mar 2026 12:14:39 +0100
Subject: [PATCH 35/38] refactor(handlers): decouple ExecutionHandler from
 gateexec using GateExecutor interface

---
 pkg/router/handlers/execution_handler.go      |  56 +++---
 pkg/router/handlers/execution_handler_test.go | 179 ++++++++++--------
 pkg/router/handlers/fakes_test.go             | 161 ++++++++++++++--
 pkg/router/router.go                          |   5 +-
 4 files changed, 279 insertions(+), 122 deletions(-)

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index 4f55cad..2c09b41 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -42,25 +42,26 @@ type ProcessStarter interface {
 	) (*processrunner.Process, error)
 }
 
+// GateExecutor abstracts gateexec behavior so handlers don't need callgate.Registry.
+// A concrete implementation can internally bind the registry and delegate to gateexec.
+type GateExecutor interface {
+	Run(ctx context.Context, gateConfig *config.CallGateConfig, key string, action gateexec.Action) (int, error)
+}
+
 // ExecutionHandler returns a WebHandler that executes the command associated with the URLCommand stored in the
 // request context.
-// It builds the command from the configured template and request parameters, prepares the response output,
-// and runs the command using the provided runner.
-// If CallGate is configured for the URLCommand, it uses the shared registry to obtain a gate for the group and
-// applies the selected gate mode (e.g. single/sequence) to limit concurrent executions.
-// The handler supports output modes: "text" (default), "stream" (flushes as data arrives), and "none" (async,
-// discarding output).
-// When execution fails (non-zero exit code or error), it logs the failure and writes an error message to the
-// response body.
-func ExecutionHandler(pr *processrunner.ProcessRunner, registry *callgate.Registry) httpx.WebHandler { //nolint:ireturn
-	return ExecutionHandlerWithProcessRunner(pr, registry)
+//
+// This variant keeps construction simple for production wiring: it accepts the concrete
+// implementations that already bind their dependencies (process runner and gate executor).
+func ExecutionHandler(pr *processrunner.ProcessRunner, exec GateExecutor) httpx.WebHandler { //nolint:ireturn
+	return ExecutionHandlerWithDeps(pr, exec)
 }
 
-// ExecutionHandlerWithProcessRunner is a test-friendly variant of ExecutionHandler that accepts an abstract
-// ProcessStarter (implemented by processrunner.ProcessRunner).
-func ExecutionHandlerWithProcessRunner(starter ProcessStarter, registry *callgate.Registry) httpx.WebHandler { //nolint:ireturn,lll
+// ExecutionHandlerWithDeps is a test-friendly variant of ExecutionHandler that accepts abstractions
+// for starting processes and executing under a gate.
+func ExecutionHandlerWithDeps(starter ProcessStarter, exec GateExecutor) httpx.WebHandler { //nolint:ireturn
 	return httpx.WebHandlerFunc(func(responseWriter http.ResponseWriter, request *http.Request) error {
-		err := executionHandler(responseWriter, request, starter, registry)
+		err := executionHandler(responseWriter, request, starter, exec)
 		if err != nil {
 			return translateError(err)
 		}
@@ -73,7 +74,7 @@ func executionHandler(
 	responseWriter http.ResponseWriter,
 	request *http.Request,
 	starter ProcessStarter,
-	registry *callgate.Registry,
+	exec GateExecutor,
 ) error {
 	rid := requestIDFromContext(request.Context())
 	log.Printf("[INFO] rid=%s Executing command for: %s %s", rid, request.Method, request.URL.Path)
@@ -96,7 +97,7 @@ func executionHandler(
 	return prepareOutputAndRunCommand(
 		request.Context(),
 		starter,
-		registry,
+		exec,
 		cmd,
 		cmdResult,
 		responseWriter,
@@ -130,7 +131,7 @@ func translateError(err error) error {
 func runCommand(
 	ctx context.Context,
 	starter ProcessStarter,
-	registry *callgate.Registry,
+	exec GateExecutor,
 	cmd *config.URLCommand,
 	cmdResult *cmdbuilder.Result,
 	writer io.Writer,
@@ -138,7 +139,6 @@ func runCommand(
 	responseWriter http.ResponseWriter,
 ) error {
 	rid := requestIDFromContext(ctx)
-	exec := gateexec.New(registry)
 	action := createGateAction(starter, cmd, cmdResult, writer, async)
 
 	exitCode, err := exec.Run(ctx, cmd.CallGate, cmd.URL, action)
@@ -301,7 +301,7 @@ func buildCommand(
 func prepareOutputAndRunCommand(
 	ctx context.Context,
 	starter ProcessStarter,
-	registry *callgate.Registry,
+	exec GateExecutor,
 	cmd *config.URLCommand,
 	cmdResult *cmdbuilder.Result,
 	responseWriter http.ResponseWriter,
@@ -310,11 +310,11 @@ func prepareOutputAndRunCommand(
 
 	switch outputType {
 	case "none":
-		return prepareOutputAndRunAsyncCommand(ctx, starter, registry, cmd, cmdResult, responseWriter)
+		return prepareOutputAndRunAsyncCommand(ctx, starter, exec, cmd, cmdResult, responseWriter)
 	case "stream":
-		return prepareOutputAndRunStreamCommand(ctx, starter, registry, cmd, cmdResult, responseWriter)
+		return prepareOutputAndRunStreamCommand(ctx, starter, exec, cmd, cmdResult, responseWriter)
 	case "", "text":
-		return prepareOutputAndRunSyncCommand(ctx, starter, registry, cmd, cmdResult, responseWriter)
+		return prepareOutputAndRunSyncCommand(ctx, starter, exec, cmd, cmdResult, responseWriter)
 	default:
 		return fmt.Errorf("%w: unknown output type %q", ErrBadConfiguration, outputType)
 	}
@@ -323,7 +323,7 @@ func prepareOutputAndRunCommand(
 func prepareOutputAndRunAsyncCommand(
 	ctx context.Context,
 	starter ProcessStarter,
-	registry *callgate.Registry,
+	exec GateExecutor,
 	cmd *config.URLCommand,
 	cmdResult *cmdbuilder.Result,
 	responseWriter http.ResponseWriter,
@@ -331,7 +331,7 @@ func prepareOutputAndRunAsyncCommand(
 	return runCommand(
 		ctx,
 		starter,
-		registry,
+		exec,
 		cmd,
 		cmdResult,
 		io.Discard,
@@ -343,7 +343,7 @@ func prepareOutputAndRunAsyncCommand(
 func prepareOutputAndRunStreamCommand(
 	ctx context.Context,
 	starter ProcessStarter,
-	registry *callgate.Registry,
+	exec GateExecutor,
 	cmd *config.URLCommand,
 	cmdResult *cmdbuilder.Result,
 	responseWriter http.ResponseWriter,
@@ -366,7 +366,7 @@ func prepareOutputAndRunStreamCommand(
 	return runCommand(
 		ctx,
 		starter,
-		registry,
+		exec,
 		cmd,
 		cmdResult,
 		writer,
@@ -378,7 +378,7 @@ func prepareOutputAndRunStreamCommand(
 func prepareOutputAndRunSyncCommand(
 	ctx context.Context,
 	starter ProcessStarter,
-	registry *callgate.Registry,
+	exec GateExecutor,
 	cmd *config.URLCommand,
 	cmdResult *cmdbuilder.Result,
 	responseWriter http.ResponseWriter,
@@ -390,7 +390,7 @@ func prepareOutputAndRunSyncCommand(
 	err := runCommand(
 		ctx,
 		starter,
-		registry,
+		exec,
 		cmd,
 		cmdResult,
 		&buf,
diff --git a/pkg/router/handlers/execution_handler_test.go b/pkg/router/handlers/execution_handler_test.go
index 6753cb5..7140bbe 100644
--- a/pkg/router/handlers/execution_handler_test.go
+++ b/pkg/router/handlers/execution_handler_test.go
@@ -11,7 +11,6 @@ import (
 	"testing"
 	"time"
 
-	"github.com/dkarczmarski/webcmd/pkg/callgate"
 	"github.com/dkarczmarski/webcmd/pkg/config"
 	"github.com/dkarczmarski/webcmd/pkg/httpx"
 	"github.com/dkarczmarski/webcmd/pkg/processrunner"
@@ -24,8 +23,6 @@ func TestExecutionHandler_HappyPath_Stream(t *testing.T) {
 	fr := &fakeRunner{}
 	fr.cmd = &fakeCommand{
 		pid: 123,
-		// Simulate a running process writing to stdout when the command starts.
-		// This allows the handler to stream the output to the HTTP response.
 		onStart: func(c *fakeCommand) {
 			c.mu.Lock()
 			defer c.mu.Unlock()
@@ -34,7 +31,9 @@ func TestExecutionHandler_HappyPath_Stream(t *testing.T) {
 	}
 
 	pr := processrunner.New(fr)
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	ge := newFakeGateExecutor()
+
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
@@ -49,8 +48,6 @@ func TestExecutionHandler_HappyPath_Stream(t *testing.T) {
 	req.Header.Set("X-Test", "test-header")
 	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
-	// flusherRecorder lets us verify that streaming handlers call Flush(),
-	// which is required to send data incrementally to the client.
 	rr := &flusherRecorder{ResponseRecorder: httptest.NewRecorder()}
 	h.ServeHTTP(rr, req)
 
@@ -70,7 +67,6 @@ func TestExecutionHandler_HappyPath_Stream(t *testing.T) {
 		t.Fatalf("expected Flush() to be called")
 	}
 
-	// Verify that the template was rendered correctly and split into command + args.
 	gotCmd, gotArgs := fr.SnapshotCommand()
 
 	if gotCmd != "echo" {
@@ -96,7 +92,9 @@ func TestExecutionHandler_Text_EmptyBody(t *testing.T) {
 	}
 
 	pr := processrunner.New(fr)
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	ge := newFakeGateExecutor()
+
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
@@ -122,7 +120,6 @@ func TestExecutionHandler_Text_EmptyBody(t *testing.T) {
 	}
 
 	gotCmd, gotArgs := fr.SnapshotCommand()
-	// Template is a single line => the whole rendered output becomes the command (no args).
 	if gotCmd != "echo ''" || len(gotArgs) != 0 {
 		t.Fatalf("expected Command(%q) with no args, got cmd=%q args=%v", "echo ''", gotCmd, gotArgs)
 	}
@@ -133,8 +130,9 @@ func TestExecutionHandler_NoCommandInContext_404(t *testing.T) {
 
 	fr := &fakeRunner{}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
@@ -155,8 +153,9 @@ func TestExecutionHandler_ExtractParams_Query_FirstValueOnly(t *testing.T) {
 
 	fr := &fakeRunner{}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
@@ -167,7 +166,6 @@ func TestExecutionHandler_ExtractParams_Query_FirstValueOnly(t *testing.T) {
 		},
 	}
 
-	// When multiple query values exist, the handler should use only the first one.
 	req := httptest.NewRequest(http.MethodGet, "/exec?a=1&a=2", nil)
 	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
@@ -189,8 +187,9 @@ func TestExecutionHandler_ExtractParams_Headers_NormalizeAndJoin(t *testing.T) {
 
 	fr := &fakeRunner{}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
@@ -201,9 +200,6 @@ func TestExecutionHandler_ExtractParams_Headers_NormalizeAndJoin(t *testing.T) {
 		},
 	}
 
-	// Header names are normalized for templates:
-	//   X-Test-Header -> X_Test_Header
-	// Multiple values are joined with "; ".
 	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
 	req.Header.Add("X-Test-Header", "a")
 	req.Header.Add("X-Test", "val1")
@@ -228,8 +224,9 @@ func TestExecutionHandler_BodyReadError_500(t *testing.T) {
 
 	fr := &fakeRunner{}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
@@ -250,13 +247,8 @@ func TestExecutionHandler_BodyReadError_500(t *testing.T) {
 	}
 
 	msg := rr.Header().Get("X-Error-Message")
-
-	if !strings.Contains(msg, "failed to read request body") {
-		t.Fatalf("expected X-Error-Message to contain %q, got %q", "failed to read request body", msg)
-	}
-
-	if !strings.Contains(msg, "read error") {
-		t.Fatalf("expected X-Error-Message to contain %q, got %q", "read error", msg)
+	if !strings.Contains(msg, "failed to read request body") || !strings.Contains(msg, "read error") {
+		t.Fatalf("expected X-Error-Message to contain read failure, got %q", msg)
 	}
 }
 
@@ -265,8 +257,9 @@ func TestExecutionHandler_BodyAsJSON_Invalid_400(t *testing.T) {
 
 	fr := &fakeRunner{}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	trueVal := true
@@ -274,8 +267,6 @@ func TestExecutionHandler_BodyAsJSON_Invalid_400(t *testing.T) {
 		URL: "POST /exec",
 		CommandConfig: config.CommandConfig{
 			CommandTemplate: "echo",
-			// BodyAsJSON=true means the handler attempts to parse the body as JSON
-			// and expose it under .body.json in the template context.
 			Params: config.ParamsConfig{
 				BodyAsJSON: &trueVal,
 			},
@@ -303,8 +294,9 @@ func TestExecutionHandler_BodyAsJSON_NonObject_400(t *testing.T) {
 
 	fr := &fakeRunner{}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	trueVal := true
@@ -312,7 +304,6 @@ func TestExecutionHandler_BodyAsJSON_NonObject_400(t *testing.T) {
 		URL: "POST /exec",
 		CommandConfig: config.CommandConfig{
 			CommandTemplate: "echo",
-			// Non-object JSON values are rejected because templates expect a JSON object.
 			Params: config.ParamsConfig{
 				BodyAsJSON: &trueVal,
 			},
@@ -348,8 +339,9 @@ func TestExecutionHandler_BuildCommand_Error_500(t *testing.T) {
 
 	fr := &fakeRunner{}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	for _, tc := range []struct {
@@ -362,8 +354,6 @@ func TestExecutionHandler_BuildCommand_Error_500(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			t.Parallel()
 
-			// Both syntax errors and execution errors should be surfaced as
-			// "error building command".
 			cmdCfg := &config.URLCommand{
 				URL: "GET /exec",
 				CommandConfig: config.CommandConfig{
@@ -394,8 +384,9 @@ func TestExecutionHandler_Stream_RequiresFlusher_500(t *testing.T) {
 
 	fr := &fakeRunner{}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
@@ -409,12 +400,10 @@ func TestExecutionHandler_Stream_RequiresFlusher_500(t *testing.T) {
 	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
 	req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, cmdCfg))
 
-	// Streaming responses require http.Flusher.
-	// This custom wrapper intentionally removes the Flusher interface
-	// to verify that the handler returns an error in this situation.
 	type nonFlusher struct{ http.ResponseWriter }
 
 	rr := httptest.NewRecorder()
+
 	h.ServeHTTP(nonFlusher{ResponseWriter: rr}, req)
 
 	if rr.Code != http.StatusInternalServerError {
@@ -432,8 +421,9 @@ func TestExecutionHandler_UnknownOutputType_500(t *testing.T) {
 
 	fr := &fakeRunner{}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
@@ -463,18 +453,14 @@ func TestExecutionHandler_UnknownOutputType_500(t *testing.T) {
 func TestExecutionHandler_OutputNone_ReturnsBeforeWait(t *testing.T) {
 	t.Parallel()
 
-	// Block Wait() so we can verify that the handler returns immediately
-	// when outputType=none (asynchronous execution).
 	block := make(chan struct{})
 
 	fr := &fakeRunner{}
-	fr.cmd = &fakeCommand{
-		pid:       123,
-		waitBlock: block,
-	}
+	fr.cmd = &fakeCommand{pid: 123, waitBlock: block}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
@@ -490,19 +476,14 @@ func TestExecutionHandler_OutputNone_ReturnsBeforeWait(t *testing.T) {
 
 	rr := httptest.NewRecorder()
 
-	// Run handler in a goroutine because we expect it to return
-	// before the command finishes.
 	done := make(chan struct{})
 	go func() {
 		h.ServeHTTP(rr, req)
 		close(done)
 	}()
 
-	// Handler should return quickly without waiting for Wait().
-	// If it blocks, asynchronous execution is broken.
 	select {
 	case <-done:
-		// ok
 	case <-time.After(80 * time.Millisecond):
 		close(block)
 		t.Fatalf("handler did not return quickly for outputType=none")
@@ -518,7 +499,6 @@ func TestExecutionHandler_OutputNone_ReturnsBeforeWait(t *testing.T) {
 		t.Fatalf("expected empty body, got %q", rr.Body.String())
 	}
 
-	// Cleanup: unblock Wait() so the fake command can finish.
 	close(block)
 }
 
@@ -527,9 +507,9 @@ func TestExecutionHandler_CallGate_InvalidMode_500(t *testing.T) {
 
 	fr := &fakeRunner{}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	registry := callgate.NewRegistry(callgate.WithDefaults())
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, registry)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
@@ -565,9 +545,9 @@ func TestExecutionHandler_CallGate_Busy_429(t *testing.T) {
 
 	fr := &fakeRunner{}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	registry := callgate.NewRegistry(callgate.WithDefaults())
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, registry)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
@@ -582,11 +562,7 @@ func TestExecutionHandler_CallGate_Busy_429(t *testing.T) {
 		},
 	}
 
-	// Acquire the gate manually to simulate another request already running.
-	// The handler should detect this and return HTTP 429.
-	gate, _ := registry.GetOrCreate("test-group", "single")
-	release, _ := gate.Acquire(t.Context())
-
+	release := ge.hold("single", "test-group")
 	defer release()
 
 	req := httptest.NewRequest(http.MethodGet, "/exec", nil)
@@ -613,9 +589,9 @@ func TestExecutionHandler_CallGate_ImplicitGroupName_IsolatesDifferentURLs(t *te
 		},
 	}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	registry := callgate.NewRegistry(callgate.WithDefaults())
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, registry)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg1 := &config.URLCommand{
@@ -624,8 +600,6 @@ func TestExecutionHandler_CallGate_ImplicitGroupName_IsolatesDifferentURLs(t *te
 			CommandTemplate: "echo hello",
 			OutputType:      "text",
 			CallGate: &config.CallGateConfig{
-				// If GroupName is nil, the handler uses the URL definition (e.g. "GET /exec1")
-				// as the implicit callgate group name.
 				GroupName: nil,
 				Mode:      "single",
 			},
@@ -643,10 +617,7 @@ func TestExecutionHandler_CallGate_ImplicitGroupName_IsolatesDifferentURLs(t *te
 		},
 	}
 
-	// Block the implicit group for /exec1 only.
-	g1, _ := registry.GetOrCreate("GET /exec1", "single")
-	release, _ := g1.Acquire(t.Context())
-
+	release := ge.hold("single", "GET /exec1")
 	defer release()
 
 	req1 := httptest.NewRequest(http.MethodGet, "/exec1", nil)
@@ -658,7 +629,6 @@ func TestExecutionHandler_CallGate_ImplicitGroupName_IsolatesDifferentURLs(t *te
 		t.Fatalf("expected status 429 for /exec1, got %d body=%q", rr1.Code, rr1.Body.String())
 	}
 
-	// /exec2 uses a different implicit group name and should not be blocked.
 	req2 := httptest.NewRequest(http.MethodGet, "/exec2", nil)
 	req2 = req2.WithContext(context.WithValue(req2.Context(), handlers.URLCommandKey, cmdCfg2))
 	rr2 := httptest.NewRecorder()
@@ -669,17 +639,71 @@ func TestExecutionHandler_CallGate_ImplicitGroupName_IsolatesDifferentURLs(t *te
 	}
 }
 
+func TestExecutionHandler_CallGate_EmptyGroupName_SharedAcrossURLs(t *testing.T) {
+	t.Parallel()
+
+	fr := &fakeRunner{}
+	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
+
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
+	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
+
+	cmdCfg1 := &config.URLCommand{
+		URL: "GET /exec1",
+		CommandConfig: config.CommandConfig{
+			CommandTemplate: "echo hello",
+			OutputType:      "text",
+			CallGate: &config.CallGateConfig{
+				GroupName: ptrString(""),
+				Mode:      "single",
+			},
+		},
+	}
+	cmdCfg2 := &config.URLCommand{
+		URL: "GET /exec2",
+		CommandConfig: config.CommandConfig{
+			CommandTemplate: "echo hello",
+			OutputType:      "text",
+			CallGate: &config.CallGateConfig{
+				GroupName: ptrString(""),
+				Mode:      "single",
+			},
+		},
+	}
+
+	release := ge.hold("single", "")
+	defer release()
+
+	for _, tc := range []struct {
+		path   string
+		cmdCfg *config.URLCommand
+	}{
+		{"/exec1", cmdCfg1},
+		{"/exec2", cmdCfg2},
+	} {
+		req := httptest.NewRequest(http.MethodGet, tc.path, nil)
+		req = req.WithContext(context.WithValue(req.Context(), handlers.URLCommandKey, tc.cmdCfg))
+
+		rr := httptest.NewRecorder()
+		h.ServeHTTP(rr, req)
+
+		if rr.Code != http.StatusTooManyRequests {
+			t.Fatalf("expected status 429 for %s, got %d body=%q", tc.path, rr.Code, rr.Body.String())
+		}
+	}
+}
+
 func TestExecutionHandler_CallGate_SharedGroupName_SharedAcrossURLs(t *testing.T) {
 	t.Parallel()
 
 	fr := &fakeRunner{}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	registry := callgate.NewRegistry(callgate.WithDefaults())
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, registry)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
-	// When an explicit GroupName is provided, multiple URLs share the same gate.
 	shared := "shared"
 
 	cmdCfg1 := &config.URLCommand{
@@ -705,10 +729,7 @@ func TestExecutionHandler_CallGate_SharedGroupName_SharedAcrossURLs(t *testing.T
 		},
 	}
 
-	// Hold the shared gate so both endpoints should be rejected.
-	g, _ := registry.GetOrCreate("shared", "single")
-	release, _ := g.Acquire(t.Context())
-
+	release := ge.hold("single", "shared")
 	defer release()
 
 	for _, tc := range []struct {
@@ -733,8 +754,6 @@ func TestExecutionHandler_CallGate_SharedGroupName_SharedAcrossURLs(t *testing.T
 func TestExecutionHandler_NonZeroExit_SetsExitCodeHeader(t *testing.T) {
 	t.Parallel()
 
-	// Create a real *exec.ExitError to simulate a command exiting with code 7.
-	// This ensures the handler correctly extracts exit codes from errors.
 	runErr := exec.Command("sh", "-c", "exit 7").Run()
 
 	var exitErr *exec.ExitError
@@ -753,8 +772,9 @@ func TestExecutionHandler_NonZeroExit_SetsExitCodeHeader(t *testing.T) {
 		},
 	}
 	pr := processrunner.New(fr)
+	ge := newFakeGateExecutor()
 
-	handler := handlers.ExecutionHandlerWithProcessRunner(pr, nil)
+	handler := handlers.ExecutionHandlerWithDeps(pr, ge)
 	h := httpx.ToHandler(httpx.ErrorSink(nil, true), handler)
 
 	cmdCfg := &config.URLCommand{
@@ -775,13 +795,10 @@ func TestExecutionHandler_NonZeroExit_SetsExitCodeHeader(t *testing.T) {
 		t.Fatalf("expected status 200, got %d body=%q", rr.Code, rr.Body.String())
 	}
 
-	// Non-zero exit codes are treated as valid results,
-	// so the handler returns HTTP 200 and exposes the exit code via header.
 	if rr.Header().Get("X-Exit-Code") != "7" {
 		t.Fatalf("expected X-Exit-Code=7, got %q", rr.Header().Get("X-Exit-Code"))
 	}
 
-	// Non-zero exit is treated as "normal" in this API => no error message.
 	if rr.Header().Get("X-Error-Message") != "" {
 		t.Fatalf("expected empty X-Error-Message, got %q", rr.Header().Get("X-Error-Message"))
 	}
diff --git a/pkg/router/handlers/fakes_test.go b/pkg/router/handlers/fakes_test.go
index d3d7aa6..e128c9d 100644
--- a/pkg/router/handlers/fakes_test.go
+++ b/pkg/router/handlers/fakes_test.go
@@ -1,14 +1,19 @@
 package handlers_test
 
 import (
+	"context"
 	"errors"
 	"io"
 	"net/http/httptest"
 	"os"
+	"strings"
 	"sync"
 	"syscall"
 
+	"github.com/dkarczmarski/webcmd/pkg/callgate"
 	"github.com/dkarczmarski/webcmd/pkg/cmdrunner"
+	"github.com/dkarczmarski/webcmd/pkg/config"
+	"github.com/dkarczmarski/webcmd/pkg/gateexec"
 )
 
 // fakeRunner is a lightweight test double for cmdrunner.Runner.
@@ -73,8 +78,6 @@ func (r *fakeRunner) SnapshotCommand() (string, []string) {
 }
 
 // fakeCommand simulates cmdrunner.Command.
-// It allows tests to control process lifecycle behavior (Start/Wait)
-// and capture stdout/stderr writers configured by the handler.
 type fakeCommand struct {
 	mu sync.Mutex
 
@@ -87,14 +90,11 @@ type fakeCommand struct {
 	waitErr  error
 
 	// waitBlock allows tests to artificially block Wait().
-	// This is useful for testing asynchronous behavior where the handler
-	// must return before the command finishes.
 	waitBlock <-chan struct{}
 
 	pid int
 
 	// onStart allows tests to simulate process output immediately after Start().
-	// This mimics a running command writing to stdout/stderr.
 	onStart func(c *fakeCommand)
 }
 
@@ -117,8 +117,6 @@ func (c *fakeCommand) SetStderr(w io.Writer) {
 }
 
 // Start simulates starting the command.
-// If startErr is set, the start fails.
-// Otherwise an optional hook can simulate process output.
 func (c *fakeCommand) Start() error {
 	c.mu.Lock()
 	err := c.startErr
@@ -137,7 +135,6 @@ func (c *fakeCommand) Start() error {
 }
 
 // Wait simulates process completion.
-// Tests can block this call using waitBlock to verify async behavior.
 func (c *fakeCommand) Wait() error {
 	if c.waitBlock != nil {
 		<-c.waitBlock
@@ -149,14 +146,156 @@ func (c *fakeCommand) Wait() error {
 	return c.waitErr
 }
 
-func (c *fakeCommand) ProcessState() *os.ProcessState { //nolint:forbidigo // explicit nil is what we need for tests
+func (c *fakeCommand) ProcessState() *os.ProcessState { //nolint:forbidigo
 	return nil
 }
 
 func (c *fakeCommand) Pid() int { return c.pid }
 
+// fakeGateExecutor mimics the behavior expected by handlers.RunCommand:
+//
+// IMPORTANT:
+//   - "busy" must be returned as gateexec.ErrPreAction-wrapped error,
+//     otherwise handler treats it as a "command failure" (silent error => HTTP 200).
+//   - invalid mode is also treated as pre-action/config error => HTTP 500 via ErrorSink.
+type fakeGateExecutor struct {
+	mu   sync.Mutex
+	busy map[string]bool // gateID -> held?
+}
+
+func newFakeGateExecutor() *fakeGateExecutor {
+	return &fakeGateExecutor{busy: make(map[string]bool)}
+}
+
+// hold simulates an in-flight request holding the gate.
+// Useful for testing 429 responses.
+//
+//nolint:unparam
+func (g *fakeGateExecutor) hold(mode, group string) func() {
+	gid := gateID(mode, group)
+
+	g.mu.Lock()
+	g.busy[gid] = true
+	g.mu.Unlock()
+
+	return func() {
+		g.mu.Lock()
+		delete(g.busy, gid)
+		g.mu.Unlock()
+	}
+}
+
+func (g *fakeGateExecutor) Run(
+	ctx context.Context,
+	gateConfig *config.CallGateConfig,
+	key string,
+	action gateexec.Action,
+) (int, error) {
+	// No gate => no gating.
+	if gateConfig == nil {
+		exitCode, done, err := action(ctx)
+		if done != nil {
+			go func() { <-done }()
+		}
+
+		return exitCode, err
+	}
+
+	mode := gateConfig.Mode
+	if mode == "" {
+		mode = "single"
+	}
+
+	// In production this kind of error typically happens before action runs,
+	// so it should behave like "pre-action" failure.
+	if mode != "single" {
+		return -1, fmtPreActionf("invalid callgate mode: %s", mode)
+	}
+
+	group := key
+	if gateConfig.GroupName != nil {
+		// Explicit group (can be empty string).
+		group = *gateConfig.GroupName
+	}
+
+	gid := gateID(mode, group)
+
+	// TryAcquire: if busy => return PRE-ACTION busy.
+	g.mu.Lock()
+	if g.busy[gid] {
+		g.mu.Unlock()
+		// Critical: wrap busy as gateexec.ErrPreAction so handler translates it to HTTP 429.
+		return -1, fmtPreActionWrap(callgate.ErrBusy)
+	}
+
+	g.busy[gid] = true
+	g.mu.Unlock()
+
+	exitCode, done, err := action(ctx)
+	if err != nil {
+		g.mu.Lock()
+		delete(g.busy, gid)
+		g.mu.Unlock()
+
+		return exitCode, err
+	}
+
+	if done != nil {
+		// Async: release when done closes.
+		go func() {
+			<-done
+			g.mu.Lock()
+			delete(g.busy, gid)
+			g.mu.Unlock()
+		}()
+
+		return exitCode, nil
+	}
+
+	// Sync: release immediately.
+	g.mu.Lock()
+	delete(g.busy, gid)
+	g.mu.Unlock()
+
+	return exitCode, nil
+}
+
+func gateID(mode, group string) string { return mode + "|" + group }
+
+// fmtPreActionWrap wraps an underlying error as gateexec.ErrPreAction.
+func fmtPreActionWrap(err error) error {
+	// This shape makes errors.Is(x, gateexec.ErrPreAction) AND errors.Is(x, err) both true.
+	return errors.Join(gateexec.ErrPreAction, err)
+}
+
+// fmtPreActionf creates a pre-action error with message.
+// We still wrap gateexec.ErrPreAction so handler treats it as "failed to start command".
+func fmtPreActionf(format string, args ...any) error {
+	return errors.Join(gateexec.ErrPreAction, errors.New(sprintf(format, args...)))
+}
+
+// sprintf avoids importing fmt just for Sprintf in tests (optional).
+func sprintf(format string, args ...any) string {
+	// Minimal formatter, good enough for our messages used in assertions.
+	// If you prefer, replace this whole helper with fmt.Sprintf and import fmt.
+	s := format
+	for _, a := range args {
+		s = strings.Replace(s, "%s", toString(a), 1)
+	}
+
+	return s
+}
+
+func toString(v any) string {
+	switch x := v.(type) {
+	case string:
+		return x
+	default:
+		return "<?>"
+	}
+}
+
 // flusherRecorder extends httptest.ResponseRecorder to track Flush() calls.
-// Streaming handlers require http.Flusher, which ResponseRecorder does not track.
 type flusherRecorder struct {
 	*httptest.ResponseRecorder
 	flushed bool
@@ -168,6 +307,4 @@ func ptrString(s string) *string { return &s }
 
 type errorReader struct{}
 
-// errorReader simulates a request body that fails during Read(),
-// allowing the handler's error path to be tested.
 func (e *errorReader) Read(_ []byte) (int, error) { return 0, errors.New("read error") }
diff --git a/pkg/router/router.go b/pkg/router/router.go
index ee0b0db..6f1d05e 100644
--- a/pkg/router/router.go
+++ b/pkg/router/router.go
@@ -8,6 +8,7 @@ import (
 	"github.com/dkarczmarski/webcmd/pkg/callgate"
 	"github.com/dkarczmarski/webcmd/pkg/cmdrunner"
 	"github.com/dkarczmarski/webcmd/pkg/config"
+	"github.com/dkarczmarski/webcmd/pkg/gateexec"
 	"github.com/dkarczmarski/webcmd/pkg/httpx"
 	"github.com/dkarczmarski/webcmd/pkg/processrunner"
 	"github.com/dkarczmarski/webcmd/pkg/router/handlers"
@@ -17,7 +18,9 @@ import (
 func New(configuration *config.Config) *http.ServeMux {
 	processRunner := processrunner.New(&cmdrunner.RealRunner{})
 	registry := callgate.NewRegistry(callgate.WithDefaults())
+	exec := gateexec.New(registry)
 	mux := http.NewServeMux()
+
 	mux.Handle("/", httpx.ToHandler(
 		httpx.ErrorSink(log.Default(), configuration.Server.WithErrorHeader),
 		httpx.WithMiddleware(
@@ -28,7 +31,7 @@ func New(configuration *config.Config) *http.ServeMux {
 				handlers.AuthorizationMiddleware(),
 				handlers.TimeoutMiddleware(),
 			),
-			handlers.ExecutionHandler(processRunner, registry),
+			handlers.ExecutionHandler(processRunner, exec),
 		)))
 
 	return mux

From 14742e3bc0e4712952f50af250ea996a49967e2d Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Fri, 6 Mar 2026 12:21:18 +0100
Subject: [PATCH 36/38] test(handlers): remove obsolete gomock-generated mocks

---
 pkg/router/handlers/execution_handler.go      |   2 -
 .../handlers/internal/mocks/mock_cmdrunner.go | 409 ------------------
 2 files changed, 411 deletions(-)
 delete mode 100644 pkg/router/handlers/internal/mocks/mock_cmdrunner.go

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index 2c09b41..a2473a8 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -1,7 +1,5 @@
 package handlers
 
-//go:generate go run go.uber.org/mock/mockgen -typed -destination=./internal/mocks/mock_cmdrunner.go -package=mocks github.com/dkarczmarski/webcmd/pkg/cmdrunner Runner,Command
-
 import (
 	"bytes"
 	"context"
diff --git a/pkg/router/handlers/internal/mocks/mock_cmdrunner.go b/pkg/router/handlers/internal/mocks/mock_cmdrunner.go
deleted file mode 100644
index b62423d..0000000
--- a/pkg/router/handlers/internal/mocks/mock_cmdrunner.go
+++ /dev/null
@@ -1,409 +0,0 @@
-// Code generated by MockGen. DO NOT EDIT.
-// Source: github.com/dkarczmarski/webcmd/pkg/cmdrunner (interfaces: Runner,Command)
-//
-// Generated by this command:
-//
-//	mockgen -typed -destination=./internal/mocks/mock_cmdrunner.go -package=mocks github.com/dkarczmarski/webcmd/pkg/cmdrunner Runner,Command
-//
-
-// Package mocks is a generated GoMock package.
-package mocks
-
-import (
-	io "io"
-	os "os"
-	reflect "reflect"
-	syscall "syscall"
-
-	cmdrunner "github.com/dkarczmarski/webcmd/pkg/cmdrunner"
-	gomock "go.uber.org/mock/gomock"
-)
-
-// MockRunner is a mock of Runner interface.
-type MockRunner struct {
-	ctrl     *gomock.Controller
-	recorder *MockRunnerMockRecorder
-	isgomock struct{}
-}
-
-// MockRunnerMockRecorder is the mock recorder for MockRunner.
-type MockRunnerMockRecorder struct {
-	mock *MockRunner
-}
-
-// NewMockRunner creates a new mock instance.
-func NewMockRunner(ctrl *gomock.Controller) *MockRunner {
-	mock := &MockRunner{ctrl: ctrl}
-	mock.recorder = &MockRunnerMockRecorder{mock}
-	return mock
-}
-
-// EXPECT returns an object that allows the caller to indicate expected use.
-func (m *MockRunner) EXPECT() *MockRunnerMockRecorder {
-	return m.recorder
-}
-
-// Command mocks base method.
-func (m *MockRunner) Command(name string, arg ...string) cmdrunner.Command {
-	m.ctrl.T.Helper()
-	varargs := []any{name}
-	for _, a := range arg {
-		varargs = append(varargs, a)
-	}
-	ret := m.ctrl.Call(m, "Command", varargs...)
-	ret0, _ := ret[0].(cmdrunner.Command)
-	return ret0
-}
-
-// Command indicates an expected call of Command.
-func (mr *MockRunnerMockRecorder) Command(name any, arg ...any) *MockRunnerCommandCall {
-	mr.mock.ctrl.T.Helper()
-	varargs := append([]any{name}, arg...)
-	call := mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Command", reflect.TypeOf((*MockRunner)(nil).Command), varargs...)
-	return &MockRunnerCommandCall{Call: call}
-}
-
-// MockRunnerCommandCall wrap *gomock.Call
-type MockRunnerCommandCall struct {
-	*gomock.Call
-}
-
-// Return rewrite *gomock.Call.Return
-func (c *MockRunnerCommandCall) Return(arg0 cmdrunner.Command) *MockRunnerCommandCall {
-	c.Call = c.Call.Return(arg0)
-	return c
-}
-
-// Do rewrite *gomock.Call.Do
-func (c *MockRunnerCommandCall) Do(f func(string, ...string) cmdrunner.Command) *MockRunnerCommandCall {
-	c.Call = c.Call.Do(f)
-	return c
-}
-
-// DoAndReturn rewrite *gomock.Call.DoAndReturn
-func (c *MockRunnerCommandCall) DoAndReturn(f func(string, ...string) cmdrunner.Command) *MockRunnerCommandCall {
-	c.Call = c.Call.DoAndReturn(f)
-	return c
-}
-
-// Kill mocks base method.
-func (m *MockRunner) Kill(pid int, sig syscall.Signal) error {
-	m.ctrl.T.Helper()
-	ret := m.ctrl.Call(m, "Kill", pid, sig)
-	ret0, _ := ret[0].(error)
-	return ret0
-}
-
-// Kill indicates an expected call of Kill.
-func (mr *MockRunnerMockRecorder) Kill(pid, sig any) *MockRunnerKillCall {
-	mr.mock.ctrl.T.Helper()
-	call := mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Kill", reflect.TypeOf((*MockRunner)(nil).Kill), pid, sig)
-	return &MockRunnerKillCall{Call: call}
-}
-
-// MockRunnerKillCall wrap *gomock.Call
-type MockRunnerKillCall struct {
-	*gomock.Call
-}
-
-// Return rewrite *gomock.Call.Return
-func (c *MockRunnerKillCall) Return(arg0 error) *MockRunnerKillCall {
-	c.Call = c.Call.Return(arg0)
-	return c
-}
-
-// Do rewrite *gomock.Call.Do
-func (c *MockRunnerKillCall) Do(f func(int, syscall.Signal) error) *MockRunnerKillCall {
-	c.Call = c.Call.Do(f)
-	return c
-}
-
-// DoAndReturn rewrite *gomock.Call.DoAndReturn
-func (c *MockRunnerKillCall) DoAndReturn(f func(int, syscall.Signal) error) *MockRunnerKillCall {
-	c.Call = c.Call.DoAndReturn(f)
-	return c
-}
-
-// MockCommand is a mock of Command interface.
-type MockCommand struct {
-	ctrl     *gomock.Controller
-	recorder *MockCommandMockRecorder
-	isgomock struct{}
-}
-
-// MockCommandMockRecorder is the mock recorder for MockCommand.
-type MockCommandMockRecorder struct {
-	mock *MockCommand
-}
-
-// NewMockCommand creates a new mock instance.
-func NewMockCommand(ctrl *gomock.Controller) *MockCommand {
-	mock := &MockCommand{ctrl: ctrl}
-	mock.recorder = &MockCommandMockRecorder{mock}
-	return mock
-}
-
-// EXPECT returns an object that allows the caller to indicate expected use.
-func (m *MockCommand) EXPECT() *MockCommandMockRecorder {
-	return m.recorder
-}
-
-// Pid mocks base method.
-func (m *MockCommand) Pid() int {
-	m.ctrl.T.Helper()
-	ret := m.ctrl.Call(m, "Pid")
-	ret0, _ := ret[0].(int)
-	return ret0
-}
-
-// Pid indicates an expected call of Pid.
-func (mr *MockCommandMockRecorder) Pid() *MockCommandPidCall {
-	mr.mock.ctrl.T.Helper()
-	call := mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Pid", reflect.TypeOf((*MockCommand)(nil).Pid))
-	return &MockCommandPidCall{Call: call}
-}
-
-// MockCommandPidCall wrap *gomock.Call
-type MockCommandPidCall struct {
-	*gomock.Call
-}
-
-// Return rewrite *gomock.Call.Return
-func (c *MockCommandPidCall) Return(arg0 int) *MockCommandPidCall {
-	c.Call = c.Call.Return(arg0)
-	return c
-}
-
-// Do rewrite *gomock.Call.Do
-func (c *MockCommandPidCall) Do(f func() int) *MockCommandPidCall {
-	c.Call = c.Call.Do(f)
-	return c
-}
-
-// DoAndReturn rewrite *gomock.Call.DoAndReturn
-func (c *MockCommandPidCall) DoAndReturn(f func() int) *MockCommandPidCall {
-	c.Call = c.Call.DoAndReturn(f)
-	return c
-}
-
-// ProcessState mocks base method.
-func (m *MockCommand) ProcessState() *os.ProcessState {
-	m.ctrl.T.Helper()
-	ret := m.ctrl.Call(m, "ProcessState")
-	ret0, _ := ret[0].(*os.ProcessState)
-	return ret0
-}
-
-// ProcessState indicates an expected call of ProcessState.
-func (mr *MockCommandMockRecorder) ProcessState() *MockCommandProcessStateCall {
-	mr.mock.ctrl.T.Helper()
-	call := mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "ProcessState", reflect.TypeOf((*MockCommand)(nil).ProcessState))
-	return &MockCommandProcessStateCall{Call: call}
-}
-
-// MockCommandProcessStateCall wrap *gomock.Call
-type MockCommandProcessStateCall struct {
-	*gomock.Call
-}
-
-// Return rewrite *gomock.Call.Return
-func (c *MockCommandProcessStateCall) Return(arg0 *os.ProcessState) *MockCommandProcessStateCall {
-	c.Call = c.Call.Return(arg0)
-	return c
-}
-
-// Do rewrite *gomock.Call.Do
-func (c *MockCommandProcessStateCall) Do(f func() *os.ProcessState) *MockCommandProcessStateCall {
-	c.Call = c.Call.Do(f)
-	return c
-}
-
-// DoAndReturn rewrite *gomock.Call.DoAndReturn
-func (c *MockCommandProcessStateCall) DoAndReturn(f func() *os.ProcessState) *MockCommandProcessStateCall {
-	c.Call = c.Call.DoAndReturn(f)
-	return c
-}
-
-// SetStderr mocks base method.
-func (m *MockCommand) SetStderr(w io.Writer) {
-	m.ctrl.T.Helper()
-	m.ctrl.Call(m, "SetStderr", w)
-}
-
-// SetStderr indicates an expected call of SetStderr.
-func (mr *MockCommandMockRecorder) SetStderr(w any) *MockCommandSetStderrCall {
-	mr.mock.ctrl.T.Helper()
-	call := mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "SetStderr", reflect.TypeOf((*MockCommand)(nil).SetStderr), w)
-	return &MockCommandSetStderrCall{Call: call}
-}
-
-// MockCommandSetStderrCall wrap *gomock.Call
-type MockCommandSetStderrCall struct {
-	*gomock.Call
-}
-
-// Return rewrite *gomock.Call.Return
-func (c *MockCommandSetStderrCall) Return() *MockCommandSetStderrCall {
-	c.Call = c.Call.Return()
-	return c
-}
-
-// Do rewrite *gomock.Call.Do
-func (c *MockCommandSetStderrCall) Do(f func(io.Writer)) *MockCommandSetStderrCall {
-	c.Call = c.Call.Do(f)
-	return c
-}
-
-// DoAndReturn rewrite *gomock.Call.DoAndReturn
-func (c *MockCommandSetStderrCall) DoAndReturn(f func(io.Writer)) *MockCommandSetStderrCall {
-	c.Call = c.Call.DoAndReturn(f)
-	return c
-}
-
-// SetStdout mocks base method.
-func (m *MockCommand) SetStdout(w io.Writer) {
-	m.ctrl.T.Helper()
-	m.ctrl.Call(m, "SetStdout", w)
-}
-
-// SetStdout indicates an expected call of SetStdout.
-func (mr *MockCommandMockRecorder) SetStdout(w any) *MockCommandSetStdoutCall {
-	mr.mock.ctrl.T.Helper()
-	call := mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "SetStdout", reflect.TypeOf((*MockCommand)(nil).SetStdout), w)
-	return &MockCommandSetStdoutCall{Call: call}
-}
-
-// MockCommandSetStdoutCall wrap *gomock.Call
-type MockCommandSetStdoutCall struct {
-	*gomock.Call
-}
-
-// Return rewrite *gomock.Call.Return
-func (c *MockCommandSetStdoutCall) Return() *MockCommandSetStdoutCall {
-	c.Call = c.Call.Return()
-	return c
-}
-
-// Do rewrite *gomock.Call.Do
-func (c *MockCommandSetStdoutCall) Do(f func(io.Writer)) *MockCommandSetStdoutCall {
-	c.Call = c.Call.Do(f)
-	return c
-}
-
-// DoAndReturn rewrite *gomock.Call.DoAndReturn
-func (c *MockCommandSetStdoutCall) DoAndReturn(f func(io.Writer)) *MockCommandSetStdoutCall {
-	c.Call = c.Call.DoAndReturn(f)
-	return c
-}
-
-// SetSysProcAttr mocks base method.
-func (m *MockCommand) SetSysProcAttr(attr *syscall.SysProcAttr) {
-	m.ctrl.T.Helper()
-	m.ctrl.Call(m, "SetSysProcAttr", attr)
-}
-
-// SetSysProcAttr indicates an expected call of SetSysProcAttr.
-func (mr *MockCommandMockRecorder) SetSysProcAttr(attr any) *MockCommandSetSysProcAttrCall {
-	mr.mock.ctrl.T.Helper()
-	call := mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "SetSysProcAttr", reflect.TypeOf((*MockCommand)(nil).SetSysProcAttr), attr)
-	return &MockCommandSetSysProcAttrCall{Call: call}
-}
-
-// MockCommandSetSysProcAttrCall wrap *gomock.Call
-type MockCommandSetSysProcAttrCall struct {
-	*gomock.Call
-}
-
-// Return rewrite *gomock.Call.Return
-func (c *MockCommandSetSysProcAttrCall) Return() *MockCommandSetSysProcAttrCall {
-	c.Call = c.Call.Return()
-	return c
-}
-
-// Do rewrite *gomock.Call.Do
-func (c *MockCommandSetSysProcAttrCall) Do(f func(*syscall.SysProcAttr)) *MockCommandSetSysProcAttrCall {
-	c.Call = c.Call.Do(f)
-	return c
-}
-
-// DoAndReturn rewrite *gomock.Call.DoAndReturn
-func (c *MockCommandSetSysProcAttrCall) DoAndReturn(f func(*syscall.SysProcAttr)) *MockCommandSetSysProcAttrCall {
-	c.Call = c.Call.DoAndReturn(f)
-	return c
-}
-
-// Start mocks base method.
-func (m *MockCommand) Start() error {
-	m.ctrl.T.Helper()
-	ret := m.ctrl.Call(m, "Start")
-	ret0, _ := ret[0].(error)
-	return ret0
-}
-
-// Start indicates an expected call of Start.
-func (mr *MockCommandMockRecorder) Start() *MockCommandStartCall {
-	mr.mock.ctrl.T.Helper()
-	call := mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Start", reflect.TypeOf((*MockCommand)(nil).Start))
-	return &MockCommandStartCall{Call: call}
-}
-
-// MockCommandStartCall wrap *gomock.Call
-type MockCommandStartCall struct {
-	*gomock.Call
-}
-
-// Return rewrite *gomock.Call.Return
-func (c *MockCommandStartCall) Return(arg0 error) *MockCommandStartCall {
-	c.Call = c.Call.Return(arg0)
-	return c
-}
-
-// Do rewrite *gomock.Call.Do
-func (c *MockCommandStartCall) Do(f func() error) *MockCommandStartCall {
-	c.Call = c.Call.Do(f)
-	return c
-}
-
-// DoAndReturn rewrite *gomock.Call.DoAndReturn
-func (c *MockCommandStartCall) DoAndReturn(f func() error) *MockCommandStartCall {
-	c.Call = c.Call.DoAndReturn(f)
-	return c
-}
-
-// Wait mocks base method.
-func (m *MockCommand) Wait() error {
-	m.ctrl.T.Helper()
-	ret := m.ctrl.Call(m, "Wait")
-	ret0, _ := ret[0].(error)
-	return ret0
-}
-
-// Wait indicates an expected call of Wait.
-func (mr *MockCommandMockRecorder) Wait() *MockCommandWaitCall {
-	mr.mock.ctrl.T.Helper()
-	call := mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Wait", reflect.TypeOf((*MockCommand)(nil).Wait))
-	return &MockCommandWaitCall{Call: call}
-}
-
-// MockCommandWaitCall wrap *gomock.Call
-type MockCommandWaitCall struct {
-	*gomock.Call
-}
-
-// Return rewrite *gomock.Call.Return
-func (c *MockCommandWaitCall) Return(arg0 error) *MockCommandWaitCall {
-	c.Call = c.Call.Return(arg0)
-	return c
-}
-
-// Do rewrite *gomock.Call.Do
-func (c *MockCommandWaitCall) Do(f func() error) *MockCommandWaitCall {
-	c.Call = c.Call.Do(f)
-	return c
-}
-
-// DoAndReturn rewrite *gomock.Call.DoAndReturn
-func (c *MockCommandWaitCall) DoAndReturn(f func() error) *MockCommandWaitCall {
-	c.Call = c.Call.DoAndReturn(f)
-	return c
-}

From 56d1d305b7cfc186b1eb5f5ef3e3c19e6d6128a6 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Fri, 6 Mar 2026 12:27:49 +0100
Subject: [PATCH 37/38] docs(handlers): document ExecutionHandler HTTP status
 semantics

---
 pkg/router/handlers/execution_handler.go | 67 ++++++++++++++++++++++--
 1 file changed, 64 insertions(+), 3 deletions(-)

diff --git a/pkg/router/handlers/execution_handler.go b/pkg/router/handlers/execution_handler.go
index a2473a8..da17978 100644
--- a/pkg/router/handlers/execution_handler.go
+++ b/pkg/router/handlers/execution_handler.go
@@ -46,10 +46,71 @@ type GateExecutor interface {
 	Run(ctx context.Context, gateConfig *config.CallGateConfig, key string, action gateexec.Action) (int, error)
 }
 
-// ExecutionHandler returns a WebHandler that executes the command associated with the URLCommand stored in the
-// request context.
+// ExecutionHandler returns a WebHandler that executes the command associated with
+// the URLCommand stored in the request context.
 //
-// This variant keeps construction simple for production wiring: it accepts the concrete
+// The handler performs the following steps:
+//
+//   - reads the URLCommand from request context,
+//   - extracts request parameters (query, headers, body text, optional body JSON),
+//   - renders the configured command template,
+//   - selects output mode ("text", "stream", or "none"),
+//   - executes the command through the provided GateExecutor and ProcessStarter.
+//
+// Output modes:
+//
+//   - "text" (default):
+//     command output is buffered and written to the response after the process exits,
+//   - "stream":
+//     command output is forwarded to the response as it is produced;
+//     requires http.Flusher support from the ResponseWriter,
+//   - "none":
+//     command is started asynchronously and output is discarded.
+//
+// HTTP status code behavior:
+//
+//   - 200 OK
+//     returned when the command starts successfully, regardless of whether the command
+//     later exits with code 0 or non-zero, or fails while waiting/executing.
+//     In other words, runtime/process execution failures are reported via response
+//     headers, not via non-200 status codes.
+//
+//     In this case the handler sets:
+//
+//   - X-Success: "true" if exit code == 0, otherwise "false"
+//
+//   - X-Exit-Code: process exit code if available
+//
+//   - X-Error-Message: empty on success, otherwise execution error message
+//
+//   - 429 Too Many Requests
+//     returned when command execution cannot start because the call gate rejects the
+//     request as busy (callgate.ErrBusy).
+//
+//   - 404 Not Found
+//     returned when URLCommand is missing from request context.
+//
+//   - 400 Bad Request
+//     returned when bodyAsJson is enabled but the request body is not a valid JSON object.
+//
+//   - 500 Internal Server Error
+//     returned when the command cannot be prepared or started at all, for example:
+//
+//   - streaming was requested but ResponseWriter does not support flushing,
+//
+//   - command template rendering/building failed,
+//
+//   - gate/pre-action setup failed before the process was started,
+//
+//   - handler configuration is invalid (for example unknown output type).
+//
+// Important distinction:
+//
+// A command that starts successfully but later fails is still treated as an HTTP-level
+// success and therefore returns 200 OK. Such failures are exposed through X-Success,
+// X-Exit-Code and X-Error-Message headers.
+//
+// This variant keeps construction simple for production wiring: it accepts concrete
 // implementations that already bind their dependencies (process runner and gate executor).
 func ExecutionHandler(pr *processrunner.ProcessRunner, exec GateExecutor) httpx.WebHandler { //nolint:ireturn
 	return ExecutionHandlerWithDeps(pr, exec)

From 86aac3caa62c3f053d2f19768d1daca3a68a4529 Mon Sep 17 00:00:00 2001
From: dkarczmarski <dkarczmarski@protonmail.com>
Date: Fri, 6 Mar 2026 13:29:46 +0100
Subject: [PATCH 38/38] chore: README.md

---
 README.md              | 31 +++++++++++++++++++++++++++++++
 config.sample-ssl.yaml |  1 +
 config.sample.yaml     |  1 +
 3 files changed, 33 insertions(+)

diff --git a/README.md b/README.md
index 3301873..93e65d6 100644
--- a/README.md
+++ b/README.md
@@ -228,6 +228,35 @@ The `commandTemplate` uses Go's `text/template` syntax to inject data from the H
   Header names are normalized by replacing hyphens (`-`) with underscores (`_`).
   Example: `{{.headers.X_Api_Key}}` or `{{.headers.User_Agent}}` .
 
+## HTTP Response and Error Handling
+
+The server returns different HTTP status codes depending on the outcome of the request and the command execution:
+
+- **200 OK**
+  Returned when the command starts successfully, regardless of whether the command later exits with code 0 or non-zero, or fails while executing.
+  In this case, the handler sets the following response headers:
+  - `X-Success`: `"true"` if the process exit code is 0, otherwise `"false"`.
+  - `X-Exit-Code`: The process exit code (if available).
+  - `X-Error-Message`: Empty on success, or contains the execution error message if the command fails (only if `server.withErrorHeader` is enabled in the configuration).
+
+- **429 Too Many Requests**
+  Returned when command execution cannot start because the call gate rejects the request as busy (e.g., when `mode: single` is used).
+
+- **404 Not Found**
+  Returned when the URL command is missing or the endpoint is not configured.
+
+- **400 Bad Request**
+  Returned when `bodyAsJson` is enabled but the request body is not a valid JSON object.
+
+- **500 Internal Server Error**
+  Returned when the command cannot be prepared or started at all, for example:
+  - Streaming was requested but the `ResponseWriter` does not support flushing.
+  - Command template rendering/building failed.
+  - Gate or pre-action setup failed before the process was started.
+  - Handler configuration is invalid.
+
+**Important distinction:** A command that starts successfully but later fails (e.g., returns a non-zero exit code) is still treated as an HTTP-level success and returns **200 OK**. Detailed information about the process outcome is available in the `X-Success` and `X-Exit-Code` headers. The `X-Error-Message` header is also provided if `server.withErrorHeader` is set to `true` in the configuration.
+
 ## Configuration (`config.yaml`)
 
 ### `server`
@@ -240,6 +269,8 @@ The `commandTemplate` uses Go's `text/template` syntax to inject data from the H
 
 * `shutdownGracePeriod` *(optional)* - the time to wait for active requests to finish before the server shuts down (e.g., `5s`, `30s`). Format: [Go Duration](https://pkg.go.dev/time#ParseDuration). Default: `5s`.
 
+* `withErrorHeader` *(optional)* - if set to `true`, the `X-Error-Message` header will be included in the HTTP response when a command execution fails. Default: `false`.
+
 * `https` *(optional)* - HTTPS configuration:
     * `enabled` - enable or disable HTTPS. Default: `false`.
     * `certFile` - path to the SSL certificate file.
diff --git a/config.sample-ssl.yaml b/config.sample-ssl.yaml
index e621c6f..9784f6b 100644
--- a/config.sample-ssl.yaml
+++ b/config.sample-ssl.yaml
@@ -1,5 +1,6 @@
 server:
 #  address: "127.0.0.1:8443"
+  withErrorHeader: true
   shutdownGracePeriod: 5s
   https:
     enabled: true
diff --git a/config.sample.yaml b/config.sample.yaml
index 915c42b..3ce1be4 100644
--- a/config.sample.yaml
+++ b/config.sample.yaml
@@ -1,5 +1,6 @@
 server:
   # address: "127.0.0.1:8080"
+  withErrorHeader: true
   shutdownGracePeriod: 5s
 authorization:
   - name: auth-name1