fix(process): introduce command.WithWaitDelay() defaulting to 10s to escalate SIGINT -> SIGKILL

Assisted-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Royce Remer <royceremer@gmail.com>

Author: rremer

modules/process/command.go

@@ -7,8 +7,12 @@ import (
 	"bytes"
 	"context"
 	"os/exec"
+	"time"
 )
 
+// defaultWaitDelay is how long CommandContext waits after sending SIGTERM before escalating to SIGKILL.
+const defaultWaitDelay = 10 * time.Second
+
 type Cmd struct {
 	*exec.Cmd
 
@@ -31,6 +35,11 @@ func (c *Cmd) WithDir(dir string) *Cmd {
 	return c
 }
 
+func (c *Cmd) WithWaitDelay(d time.Duration) *Cmd {
+	c.Cmd.WaitDelay = d
+	return c
+}
+
 func (c *Cmd) OutputString() (string, string, error) {
 	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
 	c.Cmd.Stdout = stdout
@@ -46,6 +55,7 @@ func CommandContext(ctx context.Context, name string, arg ...string) *Cmd {
 	c := &Cmd{Cmd: exec.CommandContext(ctx, name, arg...)}
 	setSysProcAttribute(c.Cmd)
 	c.Cmd.Cancel = c.onCancel
+	c.Cmd.WaitDelay = defaultWaitDelay
 	c.termGraceful = true
 	return c
 }

modules/process/command_unix.go

@@ -8,6 +8,7 @@ package process
 import (
 	"os/exec"
 	"syscall"
+	"time"
 
 	"gitea.dev/modules/util"
 )
@@ -25,6 +26,13 @@ func (c *Cmd) onCancel() error {
 		}
 	}
 	sig := util.Iif(c.termGraceful, syscall.SIGTERM, syscall.SIGKILL)
+	if sig == syscall.SIGTERM && c.Cmd.WaitDelay > 0 {
+		pgid, delay := c.Process.Pid, c.Cmd.WaitDelay
+		go func() {
+			time.Sleep(delay)
+			_ = syscall.Kill(-pgid, syscall.SIGKILL)
+		}()
+	}
 	// kill the whole process group
 	return syscall.Kill(-c.Process.Pid, sig)
 }

modules/process/command_unix_test.go

@@ -65,3 +65,72 @@ func TestCommandContextCancelKillProcessGroup(t *testing.T) {
 		return grandchild.Signal(syscall.Signal(0)) != nil
 	}, 5*time.Second, 10*time.Millisecond)
 }
+
+func TestCommandContextWaitDelayOrphansGrandchild(t *testing.T) {
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	r, w, err := os.Pipe()
+	require.NoError(t, err)
+
+	// Shell ignores SIGTERM; grandchild inherits SIG_IGN and also survives the group SIGTERM.
+	cmd := CommandContext(ctx, "sh", "-c", "trap '' TERM; sleep 600 & echo $!; wait").
+		WithWaitDelay(1 * time.Second)
+	cmd.Stdout = w
+	require.NoError(t, cmd.Start())
+	_ = w.Close()
+
+	var grandchildPID int
+	t.Cleanup(func() {
+		// Kill by process group — the PGID survives the group leader's death, so this reaches orphaned sleep.
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+		_ = cmd.Wait()
+		if grandchildPID > 0 {
+			_ = syscall.Kill(grandchildPID, syscall.SIGKILL)
+		}
+	})
+
+	scanner := bufio.NewScanner(r)
+	require.True(t, scanner.Scan(), "expected grandchild PID on stdout")
+	grandchildPID, err = strconv.Atoi(strings.TrimSpace(scanner.Text()))
+	require.NoError(t, err)
+	_ = r.Close()
+
+	grandchild, err := os.FindProcess(grandchildPID)
+	require.NoError(t, err)
+	require.NoError(t, grandchild.Signal(syscall.Signal(0)), "grandchild should be alive before cancel")
+
+	cancel()
+	_ = cmd.Wait() // blocks ~1s until WaitDelay SIGKILL kills the direct child (shell)
+
+	assert.Eventually(t, func() bool {
+		return grandchild.Signal(syscall.Signal(0)) != nil
+	}, 5*time.Second, 10*time.Millisecond, "grandchild was orphaned: WaitDelay SIGKILL did not reach the process group")
+}
+
+func TestCommandContextSIGTERMIgnoredHangs(t *testing.T) {
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	cmd := CommandContext(ctx, "sh", "-c", "trap '' TERM; sleep 600").WithWaitDelay(1 * time.Second)
+	require.NoError(t, cmd.Start())
+
+	waitDone := make(chan struct{})
+	go func() {
+		_ = cmd.Wait()
+		close(waitDone)
+	}()
+
+	t.Cleanup(func() {
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+		<-waitDone
+	})
+
+	cancel()
+
+	select {
+	case <-waitDone:
+	case <-time.After(5 * time.Second):
+		t.Fatal("process did not exit after context cancel: SIGTERM ignored and no SIGKILL escalation occurred")
+	}
+}