fix: repair free-disk-space build on FreeBSD (#1098)

`Statfs_t.Bavail` is unsigned on Linux but signed on FreeBSD, so `Bavail * uint64(Bsize)` in `internal/app/run/disk_unix.go` fails to compile for the freebsd targets goreleaser cross-builds, breaking the nightly release (introduced in https://gitea.com/gitea/runner/pulls/1090). The `checks` workflow only builds for the host, so it never cross-compiles freebsd and stayed green.

Casting both operands to `uint64` makes the arithmetic signedness-agnostic across all unix variants.

Reviewed-on: https://gitea.com/gitea/runner/pulls/1098
Reviewed-by: bircni <bircni@icloud.com>
Co-authored-by: silverwind <me@silverwind.io>

.gitea/workflows/pull-pr-title.yml

@@ -19,7 +19,7 @@ jobs:
     timeout-minutes: 5
     steps:
     - uses: actions/checkout@v7
-    - uses: actions/setup-node@v6
+    - uses: actions/setup-node@v7
       with:
         node-version: 24
     - run: make lint-pr-title

act/common/git/git.go

@@ -261,6 +261,10 @@ type NewGitCloneExecutorInput struct {
 	// 0 for full clone.
 	Depth int
 
+	// Quiet drops the informational clone line to debug level, for callers that log their own
+	// download summary (the setup section's action report).
+	Quiet bool
+
 	// For Gitea
 	InsecureSkipTLS bool
 }
@@ -347,7 +351,11 @@ func gitOptions(token string) (fetchOptions git.FetchOptions, pullOptions git.Pu
 func NewGitCloneExecutor(input NewGitCloneExecutorInput) common.Executor {
 	return func(ctx context.Context) error {
 		logger := common.Logger(ctx)
+		if input.Quiet {
+			logger.Debugf("git clone '%s' # ref=%s", input.URL, input.Ref)
+		} else {
 			logger.Infof("git clone '%s' # ref=%s", input.URL, input.Ref)
+		}
 		logger.Debugf("  cloning %s to %s", input.URL, input.Dir)
 
 		defer AcquireCloneLock(input.Dir)()

act/common/git/git_test.go

@@ -17,6 +17,10 @@ import (
 	"testing"
 	"time"
 
+	"gitea.com/gitea/runner/act/common"
+
+	log "github.com/sirupsen/logrus"
+	logrustest "github.com/sirupsen/logrus/hooks/test"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -404,6 +408,44 @@ func TestGitCloneExecutorOfflineMode(t *testing.T) {
 	})
 }
 
+func TestGitCloneExecutorQuietDemotesCloneLine(t *testing.T) {
+	remoteDir := t.TempDir()
+	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
+	workDir := t.TempDir()
+	require.NoError(t, gitCmd("clone", remoteDir, workDir))
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "initial"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
+
+	// Quiet callers report the download themselves, so the clone line must not reach the job log.
+	for name, quiet := range map[string]bool{"quiet": true, "not quiet": false} {
+		t.Run(name, func(t *testing.T) {
+			logger, hook := logrustest.NewNullLogger()
+			logger.SetLevel(log.InfoLevel)
+			ctx := common.WithLogger(context.Background(), logger.WithField("job", "j1"))
+
+			require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+				URL:   remoteDir,
+				Ref:   "main",
+				Dir:   t.TempDir(),
+				Quiet: quiet,
+			})(ctx))
+
+			var cloneLines int
+			for _, entry := range hook.AllEntries() {
+				if strings.HasPrefix(entry.Message, "git clone ") {
+					cloneLines++
+				}
+			}
+			if quiet {
+				assert.Zero(t, cloneLines)
+			} else {
+				assert.Equal(t, 1, cloneLines)
+			}
+		})
+	}
+}
+
 func TestGitCloneExecutorShallow(t *testing.T) {
 	// Build a local "remote" with several commits on main plus a tag, so a full clone would pull noticeably more history than a shallow one.
 	remoteDir := t.TempDir()

act/container/docker_run.go

@@ -376,6 +376,11 @@ func (cr *containerReference) find() common.Executor {
 	}
 }
 
+// isContainerGone reports whether a failed remove still left the container gone (NotFound or Conflict).
+func isContainerGone(err error) bool {
+	return cerrdefs.IsNotFound(err) || cerrdefs.IsConflict(err)
+}
+
 func (cr *containerReference) remove() common.Executor {
 	return func(ctx context.Context) error {
 		if cr.id == "" {
@@ -387,7 +392,7 @@ func (cr *containerReference) remove() common.Executor {
 			RemoveVolumes: true,
 			Force:         true,
 		})
-		if err != nil {
+		if err != nil && !isContainerGone(err) {
 			logger.Error(fmt.Errorf("failed to remove container: %w", err))
 		}
 

act/container/docker_run_test.go

@@ -116,6 +116,11 @@ func (m *mockDockerClient) ContainerList(ctx context.Context, opts mobyclient.Co
 	return args.Get(0).(mobyclient.ContainerListResult), args.Error(1)
 }
 
+func (m *mockDockerClient) ContainerRemove(ctx context.Context, id string, opts mobyclient.ContainerRemoveOptions) (mobyclient.ContainerRemoveResult, error) {
+	args := m.Called(ctx, id, opts)
+	return args.Get(0).(mobyclient.ContainerRemoveResult), args.Error(1)
+}
+
 type endlessReader struct {
 	io.Reader
 }
@@ -381,6 +386,40 @@ func TestDockerCopyTarStreamErrorInMkdir(t *testing.T) {
 	client.AssertExpectations(t)
 }
 
+// A remove that raced the daemon's AutoRemove teardown is not a failure and must not
+// be logged as one.
+func TestRemoveIgnoresAutoRemoveRace(t *testing.T) {
+	removeOpts := mobyclient.ContainerRemoveOptions{RemoveVolumes: true, Force: true}
+	for _, tc := range []struct {
+		name     string
+		err      error
+		wantLogs bool
+	}{
+		{name: "removal in progress", err: cerrdefs.ErrConflict.WithMessage("removal of container abc is already in progress")},
+		{name: "already removed", err: cerrdefs.ErrNotFound.WithMessage("No such container: abc")},
+		{name: "removed cleanly", err: nil},
+		{name: "real failure", err: errors.New("driver failed to remove root filesystem"), wantLogs: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			logger, hook := test.NewNullLogger()
+			ctx := common.WithLogger(context.Background(), logger)
+			client := &mockDockerClient{}
+			client.On("ContainerRemove", ctx, "abc", removeOpts).Return(mobyclient.ContainerRemoveResult{}, tc.err)
+			cr := &containerReference{id: "abc", cli: client}
+
+			require.NoError(t, cr.remove()(ctx))
+			assert.Empty(t, cr.id)
+
+			if tc.wantLogs {
+				assert.Len(t, hook.AllEntries(), 1)
+			} else {
+				assert.Empty(t, hook.AllEntries())
+			}
+			client.AssertExpectations(t)
+		})
+	}
+}
+
 // find() must drop a stale cached id so later Copy/Exec don't hit the
 // daemon with a torn-down container.
 func TestFindRevalidatesStaleID(t *testing.T) {

act/container/host_environment.go

@@ -17,6 +17,7 @@ import (
 	"path/filepath"
 	"runtime"
 	"strings"
+	"sync"
 	"sync/atomic"
 	"time"
 
@@ -43,6 +44,25 @@ type HostEnvironment struct {
 	CleanUp      func()
 	StdOut       io.Writer
 	AllocatePTY  bool // allocate a pseudo-TTY for each step's process
+
+	// procGroup owns every process the job's steps start. Atomic: Remove may read
+	// it while a step is still starting.
+	procGroupOnce sync.Once
+	procGroup     atomic.Pointer[process.Group]
+}
+
+// processGroup returns the job-scoped process group, creating it on first use.
+// Returns nil if the job object could not be created; Group is nil-safe.
+func (e *HostEnvironment) processGroup(ctx context.Context) *process.Group {
+	e.procGroupOnce.Do(func() {
+		group, err := process.NewGroup()
+		if err != nil {
+			common.Logger(ctx).Warnf("could not create the job's process group; processes a step leaves behind can only be reclaimed by the workspace scan: %v", err)
+			return
+		}
+		e.procGroup.Store(group)
+	})
+	return e.procGroup.Load()
 }
 
 func (e *HostEnvironment) Create(_, _ []string) common.Executor {
@@ -324,11 +344,8 @@ func (e *HostEnvironment) exec(ctx context.Context, command []string, cmdline st
 	cmd.Dir = wd
 	cmd.SysProcAttr = process.SysProcAttr(cmdline, false)
 
-	// Kill the step's whole process tree on cancellation (a step often launches a
+	// Kills the step's whole tree on cancellation and bounds the post-exit I/O
-	// shell that spawns further background or GUI children) and bound the post-exit
+	// wait, so an orphan holding cmd's stdout pipe cannot hang cmd.Wait().
-	// I/O wait, so an orphan inheriting cmd's stdout/stderr pipe can never hang
-	// cmd.Wait() and the runner. See process.TreeKill. The PTY path below may
-	// override SysProcAttr, but never touches Cancel/WaitDelay.
 	treeKill := process.NewTreeKill(cmd)
 
 	var ppty *os.File
@@ -360,6 +377,11 @@ func (e *HostEnvironment) exec(ctx context.Context, command []string, cmdline st
 	if err := cmd.Start(); err != nil {
 		return err
 	}
+	// Assign before the step's Killer so the step's job nests inside the group's;
+	// cancellation still scopes to this step's tree.
+	if err := e.processGroup(ctx).Assign(cmd.Process); err != nil {
+		common.Logger(ctx).Warnf("could not assign the step's process to the job's process group; a process it leaves behind may outlive the job: %v", err)
+	}
 	if k, kerr := treeKill.Capture(cmd.Process); kerr != nil {
 		common.Logger(ctx).Warnf("process tree kill setup failed, falling back to single-process kill: %v", kerr)
 	} else {
@@ -407,13 +429,12 @@ func (e *HostEnvironment) UpdateFromEnv(srcPath string, env *map[string]string)
 	return parseEnvFile(e, srcPath, env)
 }
 
-// removeAll is the filesystem delete used by removeAllWithContext. A package
+// removeAll is a var so tests can substitute a blocking stub.
-// var so tests can substitute a blocking stub without patching os.RemoveAll.
 var removeAll = os.RemoveAll
 
-// removeAllWithContext runs removeAll in a goroutine and returns once it
+// removeAllWithContext returns once the delete finishes or ctx is cancelled. On
-// finishes or ctx is cancelled. On cancellation the goroutine is left running —
+// cancellation the goroutine leaks: a delete inside a syscall cannot be
-// a delete blocked inside a syscall cannot be interrupted (see runWithTimeout).
+// interrupted (see runWithTimeout).
 func removeAllWithContext(ctx context.Context, path string) error {
 	done := make(chan error, 1)
 	go func() { done <- removeAll(path) }()
@@ -455,17 +476,12 @@ func removePathWithRetry(ctx context.Context, path string) error {
 	return lastErr
 }
 
-// buildWindowsWorkspaceKillScript builds a PowerShell command that `taskkill
+// buildWindowsWorkspaceKillScript builds a PowerShell command that taskkills
-// /T /F`s every process tree whose ExecutablePath or CommandLine references one
+// every process tree whose ExecutablePath or CommandLine references one of the
-// of the given absolute workspace dirs, releasing file handles for cleanup.
+// given workspace dirs, releasing file handles for cleanup. Win32_Process
-//
+// exposes both fields (Get-Process doesn't, wmic is deprecated); matching is on
-// Win32_Process is used because it exposes both ExecutablePath and CommandLine
+// the dir+separator prefix via ordinal String methods, so a name-prefix sibling
-// (Get-Process doesn't, wmic is deprecated). Both match the dir+separator
+// (job1 vs job10) is spared and path metacharacters stay literal.
-// prefix, so a sibling dir sharing a name prefix (job1 vs job10) is spared.
-// Ordinal String methods, not -like, so path metacharacters ([ ] ? *) stay
-// literal.
-//
-// Pure function so the quote-escaping can be unit-tested without PowerShell.
 func buildWindowsWorkspaceKillScript(dirs []string) string {
 	quoted := make([]string, len(dirs))
 	for i, d := range dirs {
@@ -501,9 +517,8 @@ func (e *HostEnvironment) terminateRunningProcesses(ctx context.Context) {
 
 	logger := common.Logger(ctx)
 
-	// Workspace dirs we own. Any process running from or referencing one is a
+	// Dirs we own; a process referencing one is a leftover. ToolCache is shared
-	// leftover job process. ToolCache is shared across jobs; Workdir only when
+	// across jobs, and Workdir may be a caller-owned checkout.
-	// we own it (else it's a caller-provided checkout, e.g. act local mode).
 	owned := []string{e.Path, e.TmpDir}
 	if e.CleanWorkdir {
 		owned = append(owned, e.Workdir)
@@ -530,21 +545,24 @@ func (e *HostEnvironment) terminateRunningProcesses(ctx context.Context) {
 	if err != nil {
 		logger.Debugf("workspace process-tree kill via PowerShell failed: %v output=%s", err, strings.TrimSpace(string(out)))
 	}
+
+	// Win32_Process exposes no working directory, so the scan above misses a
+	// process that merely runs in a workspace dir while pinning a handle on it.
+	if killed, err := process.KillProcessesWithCWDUnder(killCtx, dirs); err != nil {
+		logger.Debugf("workspace process kill by working directory reported errors: %v", err)
+	} else if killed > 0 {
+		logger.Debugf("terminated %d leftover process(es) by workspace working directory", killed)
+	}
 }
 
-// hostCleanupTimeout bounds each filesystem-teardown phase of the host
+// hostCleanupTimeout bounds each teardown phase so one stalled delete cannot
-// environment so a single stalled delete cannot wedge the runner slot forever.
+// wedge the runner slot. A var so tests can shrink it.
-// A var (not const) so tests can shrink it.
 var hostCleanupTimeout = 30 * time.Second
 
-// runWithTimeout runs fn in a goroutine and returns once it finishes or timeout
+// runWithTimeout returns context.DeadlineExceeded once timeout elapses, leaking
-// elapses, whichever comes first. On timeout the goroutine is left running — an
+// the goroutine: a delete blocked in a syscall (AV filter driver, dead network
-// os.RemoveAll blocked inside a delete syscall (AV/EDR filter drivers, an
+// mount) cannot be interrupted, and leaking scratch state beats losing the
-// unresponsive network mount, a dying disk) cannot be interrupted — and
+// runner's capacity slot forever. The idle stale-dir sweep reclaims it later.
-// context.DeadlineExceeded is returned. Leaking the goroutine and the scratch
-// state it was deleting is strictly better than blocking the caller forever and
-// permanently losing the runner's capacity slot; the leaked scratch dir is
-// reclaimed later by the runner's idle stale-dir sweep.
 func runWithTimeout(fn func(), timeout time.Duration) error {
 	done := make(chan struct{})
 	go func() {
@@ -565,14 +583,15 @@ func (e *HostEnvironment) Remove() common.Executor {
 	return func(ctx context.Context) error {
 		logger := common.Logger(ctx)
 
-		// Ensure any lingering child processes are ended before attempting
+		// End lingering processes before removing the workspace; on Windows their
-		// to remove the workspace (Windows file locks otherwise prevent cleanup).
+		// file locks block cleanup. Closing the group is deterministic, the scan a net.
+		if err := e.procGroup.Load().Close(); err != nil {
+			logger.Debugf("closing the job's process group failed: %v", err)
+		}
 		e.terminateRunningProcesses(ctx)
 
-		// Only removes per-job misc state. Must not remove the cache/toolcache root.
+		// Removes per-job misc state only, never the toolcache root. Bounded because
-		// Bound it: CleanUp is a caller-supplied, typically unbounded os.RemoveAll,
+		// CleanUp is a caller-supplied, typically unbounded os.RemoveAll.
-		// and a delete stalled by a filesystem filter driver would otherwise hang
-		// the job forever at "Cleaning up container" and hold the capacity slot.
 		if e.CleanUp != nil {
 			logger.Debugf("running host environment cleanup callback")
 			if err := runWithTimeout(e.CleanUp, hostCleanupTimeout); err != nil {
@@ -603,8 +622,7 @@ func (e *HostEnvironment) Remove() common.Executor {
 				return errors.Join(errs...)
 			}
 		}
-		// Bounded teardown timed out; warnings already logged above. Do not
+		// Teardown timed out; warned above. Do not fail job completion over it.
-		// fail job completion — leaked scratch is reclaimed by the idle sweep.
 		return nil
 	}
 }

act/exprparser/functions.go

@@ -274,8 +274,17 @@ func (impl *interperterImpl) jobSuccess() (bool, error) { //nolint:unparam // pr
 	return true, nil
 }
 
+// jobStatus returns the current job status, treating a nil Job context as an
+// empty status so status-check functions never panic on a nil dereference.
+func (impl *interperterImpl) jobStatus() string {
+	if impl.env.Job == nil {
+		return ""
+	}
+	return impl.env.Job.Status
+}
+
 func (impl *interperterImpl) stepSuccess() (bool, error) { //nolint:unparam // pre-existing issue from nektos/act
-	return impl.env.Job.Status == "success", nil
+	return impl.jobStatus() == "success", nil
 }
 
 func (impl *interperterImpl) jobFailure() (bool, error) { //nolint:unparam // pre-existing issue from nektos/act
@@ -292,9 +301,9 @@ func (impl *interperterImpl) jobFailure() (bool, error) { //nolint:unparam // pr
 }
 
 func (impl *interperterImpl) stepFailure() (bool, error) { //nolint:unparam // pre-existing issue from nektos/act
-	return impl.env.Job.Status == "failure", nil
+	return impl.jobStatus() == "failure", nil
 }
 
 func (impl *interperterImpl) cancelled() (bool, error) { //nolint:unparam // pre-existing issue from nektos/act
-	return impl.env.Job.Status == "cancelled", nil
+	return impl.jobStatus() == "cancelled", nil
 }

act/exprparser/functions_test.go

@@ -254,3 +254,27 @@ func TestFunctionFormat(t *testing.T) {
 		})
 	}
 }
+
+func TestStatusFunctionsNilJob(t *testing.T) {
+	// A nil Job context must not panic: the status-check functions should treat
+	// it as an empty status and return false rather than dereferencing nil.
+	env := &EvaluationEnvironment{}
+
+	table := []struct {
+		input   string
+		context string
+		name    string
+	}{
+		{"cancelled()", "job", "cancelled-nil-job"},
+		{"success()", "step", "step-success-nil-job"},
+		{"failure()", "step", "step-failure-nil-job"},
+	}
+
+	for _, tt := range table {
+		t.Run(tt.name, func(t *testing.T) {
+			output, err := NewInterpeter(env, Config{Context: tt.context}).Evaluate(tt.input, DefaultStatusCheckNone)
+			assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
+			assert.Equal(t, false, output)
+		})
+	}
+}

act/runner/action.go

@@ -405,7 +405,7 @@ func execAsDocker(ctx context.Context, step actionStep, actionName, actionDir, b
 		stepContainer.Create(rc.Config.ContainerCapAdd, rc.Config.ContainerCapDrop),
 		stepContainer.Start(true),
 	).Finally(
-		stepContainer.Remove().IfBool(!rc.Config.ReuseContainers),
+		stepContainer.Remove().IfBool(!rc.Config.ReuseContainers && !rc.Config.AutoRemove),
 	).Finally(stepContainer.Close())(ctx)
 }
 

act/runner/action_test.go

@@ -20,6 +20,7 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/mock"
+	"github.com/stretchr/testify/require"
 )
 
 type closerMock struct {
@@ -150,6 +151,44 @@ runs:
 	}
 }
 
+// With AutoRemove the daemon reaps the container on exit, so act must not remove it afterwards.
+func TestExecAsDockerAutoRemove(t *testing.T) {
+	orig := ContainerNewContainer
+	defer func() { ContainerNewContainer = orig }()
+
+	for _, tc := range []struct {
+		autoRemove bool
+		removes    int
+	}{
+		{false, 2}, // stale + post-run
+		{true, 1},  // post-run skipped
+	} {
+		cm := &containerMock{}
+		ContainerNewContainer = func(*container.NewContainerInput) container.ExecutionsEnvironment { return cm }
+
+		step := &stepActionRemote{
+			Step: &model.Step{ID: "1", Uses: "org/action@v1"},
+			RunContext: &RunContext{
+				Config:       &Config{AutoRemove: tc.autoRemove},
+				Run:          &model.Run{JobID: "1", Workflow: &model.Workflow{Jobs: map[string]*model.Job{"1": {}}}},
+				JobContainer: cm,
+			},
+			action: &model.Action{Runs: model.ActionRuns{Using: "docker", Image: "docker://node:14"}},
+		}
+
+		removes := 0
+		cm.On("Pull", false).Return(func(context.Context) error { return nil })
+		cm.On("Remove").Return(func(context.Context) error { removes++; return nil })
+		cm.On("Create", []string(nil), []string(nil)).Return(func(context.Context) error { return nil })
+		cm.On("Start", true).Return(func(context.Context) error { return nil })
+		cm.On("Close").Return(func(context.Context) error { return nil })
+
+		require.NoError(t, execAsDocker(context.Background(), step, "action", t.TempDir(), t.TempDir(), false))
+		cm.AssertExpectations(t)
+		assert.Equal(t, tc.removes, removes)
+	}
+}
+
 func TestActionRunner(t *testing.T) {
 	table := []struct {
 		name        string

act/runner/cancellation_test.go

@@ -283,3 +283,30 @@ func TestPostStepsContextDeadlinePreservesJobError(t *testing.T) {
 	require.NoError(t, postCtx.Err(), "post context must not carry the expired deadline")
 	assert.ErrorIs(t, common.JobError(postCtx), assert.AnError, "the timeout job error must be preserved")
 }
+
+// reportStepError must treat a context.Canceled (e.g. a teardown-cancelled read) as an
+// interruption, never a job failure.
+func TestReportStepErrorTreatsCancelAsInterruption(t *testing.T) {
+	rc := &RunContext{}
+
+	// stray read cancellation while the job context is live: ignored, not a failure
+	live := common.WithJobErrorContainer(context.Background())
+	reportStepError(live, rc, context.Canceled)
+	require.NoError(t, common.JobError(live))
+	assert.False(t, rc.jobFailed)
+	assert.False(t, rc.jobCancelled)
+
+	// genuine job cancellation: recorded as cancelled, still not a failure
+	cancelled, cancel := context.WithCancel(common.WithJobErrorContainer(context.Background()))
+	cancel()
+	reportStepError(cancelled, rc, context.Canceled)
+	require.NoError(t, common.JobError(cancelled))
+	assert.False(t, rc.jobFailed)
+	assert.True(t, rc.jobCancelled)
+
+	// a real error still fails the job
+	failed := common.WithJobErrorContainer(context.Background())
+	reportStepError(failed, rc, assert.AnError)
+	require.ErrorIs(t, common.JobError(failed), assert.AnError)
+	assert.True(t, rc.jobFailed)
+}

act/runner/job_executor.go

@@ -10,6 +10,7 @@ import (
 	"context"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -56,17 +57,81 @@ type jobInfo interface {
 	result(result string)
 }
 
-// reportStepError emits the GitHub Actions ##[error] annotation and records
+// reportStepError records a step error so the job is reported failed — except a
-// the error against the job so the job is reported as failed.
+// cancellation, which is an interruption, not a failure.
 func reportStepError(ctx context.Context, rc *RunContext, err error) {
+	if errors.Is(err, context.Canceled) {
+		// Defer to the job context: a genuine cancel reports cancelled, a stray teardown
+		// cancellation on a live ctx is ignored — never a step FAILURE.
+		rc.markInterrupted(ctx.Err())
+		return
+	}
 	common.Logger(ctx).Errorf("##[error]%v", err)
 	common.SetJobError(ctx, err)
 	rc.markFailed()
 }
 
+// actionPreparer is implemented by steps that download an action before they run, so the job
+// executor can fetch all of them up front.
+type actionPreparer interface {
+	prepareActionExecutor() common.Executor
+	actionDownloadInfo() (reference, sha string, ok bool)
+}
+
+// printPrepareActions downloads every action the job uses before its first step runs and reports
+// them as actions/runner's "Prepare all required actions" section does. The steps still call
+// prepareActionExecutor themselves; it is a no-op once the action is resolved here.
+func printPrepareActions(rc *RunContext, preparers []actionPreparer) common.Executor {
+	return func(ctx context.Context) error {
+		if len(preparers) == 0 {
+			return nil
+		}
+
+		rawLogger := common.Logger(ctx).WithField(rawOutputField, true)
+		rawLogger.Infof("Prepare all required actions")
+
+		for _, preparer := range preparers {
+			if err := preparer.prepareActionExecutor()(ctx); err != nil {
+				// No step has run yet, so the failure belongs to the job.
+				reportStepError(ctx, rc, err)
+				return err
+			}
+			reference, sha, ok := preparer.actionDownloadInfo()
+			if !ok {
+				continue
+			}
+			if sha == "" {
+				rawLogger.Infof("Download action repository '%s'", reference)
+			} else {
+				rawLogger.Infof("Download action repository '%s' (SHA:%s)", reference, sha)
+			}
+		}
+		return nil
+	}
+}
+
+// printCompleteJobName closes the setup section the way actions/runner ends its "Set up job" step.
+func printCompleteJobName(rc *RunContext) common.Executor {
+	return func(ctx context.Context) error {
+		// Name holds a matrix combination; JobName is the shared name GitHub reports.
+		name := rc.JobName
+		if name == "" {
+			name = rc.Name
+		}
+		if name == "" && rc.Run != nil {
+			name = rc.Run.JobID
+		}
+		common.Logger(ctx).WithField(rawOutputField, true).Infof("Complete job name: %s", name)
+		return nil
+	}
+}
+
 func newJobExecutor(info jobInfo, sf stepFactory, rc *RunContext) common.Executor {
 	steps := make([]common.Executor, 0)
 	preSteps := make([]common.Executor, 0)
+	// Collected separately: every action is downloaded before the first pre step runs.
+	stepPreSteps := make([]common.Executor, 0)
+	preparers := make([]actionPreparer, 0)
 	var postExecutor common.Executor
 
 	steps = append(steps, func(ctx context.Context) error {
@@ -113,9 +178,13 @@ func newJobExecutor(info jobInfo, sf stepFactory, rc *RunContext) common.Executo
 			return common.NewErrorExecutor(err)
 		}
 
+		if preparer, ok := step.(actionPreparer); ok {
+			preparers = append(preparers, preparer)
+		}
+
 		stepIdx := stepModel.Number
 		preExec := step.pre()
-		preSteps = append(preSteps, useStepLogger(rc, stepModel, stepStagePre, func(ctx context.Context) error {
+		stepPreSteps = append(stepPreSteps, useStepLogger(rc, stepModel, stepStagePre, func(ctx context.Context) error {
 			rc.CurrentStepIndex = stepIdx
 			preErr := preExec(ctx)
 			if preErr != nil {
@@ -157,6 +226,11 @@ func newJobExecutor(info jobInfo, sf stepFactory, rc *RunContext) common.Executo
 		}
 	}
 
+	// The setup section of the job log: download the actions, run the pre steps, then name the job.
+	preSteps = append(preSteps, printPrepareActions(rc, preparers))
+	preSteps = append(preSteps, stepPreSteps...)
+	preSteps = append(preSteps, printCompleteJobName(rc))
+
 	postExecutor = postExecutor.Finally(func(ctx context.Context) error {
 		jobError := common.JobError(ctx)
 		var err error

act/runner/job_executor_test.go

@@ -24,6 +24,7 @@ import (
 	"gitea.com/gitea/runner/act/container"
 	"gitea.com/gitea/runner/act/model"
 
+	log "github.com/sirupsen/logrus"
 	logrustest "github.com/sirupsen/logrus/hooks/test"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/mock"
@@ -111,6 +112,182 @@ func (sfm *stepFactoryMock) newStep(model *model.Step, rc *RunContext) (step, er
 	return args.Get(0).(step), args.Error(1)
 }
 
+// actionPreparerMock stands in for a step whose action is downloaded before the job's first step.
+type actionPreparerMock struct {
+	reference string
+	sha       string
+	ok        bool
+	err       error
+	prepared  int
+}
+
+func (apm *actionPreparerMock) prepareActionExecutor() common.Executor {
+	return func(context.Context) error {
+		apm.prepared++
+		return apm.err
+	}
+}
+
+func (apm *actionPreparerMock) actionDownloadInfo() (string, string, bool) {
+	return apm.reference, apm.sha, apm.ok
+}
+
+func TestPrintPrepareActionsGolden(t *testing.T) {
+	buf := &bytes.Buffer{}
+	logger := log.New()
+	logger.SetOutput(buf)
+	logger.SetLevel(log.InfoLevel)
+	logger.SetFormatter(&jobLogFormatter{color: cyan})
+	ctx := common.WithLogger(context.Background(), logger.WithFields(log.Fields{"job": "j1"}))
+
+	preparers := []actionPreparer{
+		&actionPreparerMock{reference: "actions/checkout@v7", sha: "9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0", ok: true},
+		// A resolved commit is best effort; the ref alone is reported when it is unknown.
+		&actionPreparerMock{reference: "actions/setup-go@v6", ok: true},
+		// A step that downloads nothing, such as the checkout of the workflow's own repository.
+		&actionPreparerMock{ok: false},
+	}
+	require.NoError(t, printPrepareActions(&RunContext{}, preparers)(ctx))
+
+	want := strings.Join([]string{
+		"[j1]   | Prepare all required actions",
+		"[j1]   | Download action repository 'actions/checkout@v7' (SHA:9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0)",
+		"[j1]   | Download action repository 'actions/setup-go@v6'",
+		"",
+	}, "\n")
+	assert.Equal(t, want, buf.String())
+}
+
+func TestPrintPrepareActionsSkipsWithoutActions(t *testing.T) {
+	buf := &bytes.Buffer{}
+	logger := log.New()
+	logger.SetOutput(buf)
+	logger.SetFormatter(&jobLogFormatter{color: cyan})
+	ctx := common.WithLogger(context.Background(), logger.WithFields(log.Fields{"job": "j1"}))
+
+	require.NoError(t, printPrepareActions(&RunContext{}, nil)(ctx))
+
+	assert.Empty(t, buf.String())
+}
+
+func TestPrintPrepareActionsFailsJobOnDownloadError(t *testing.T) {
+	logger, _ := logrustest.NewNullLogger()
+	ctx := common.WithJobErrorContainer(common.WithLogger(context.Background(), logger.WithField("job", "j1")))
+
+	downloadErr := errors.New("failed to fetch \"actions/checkout\"")
+	rc := &RunContext{}
+	remaining := &actionPreparerMock{reference: "actions/setup-go@v6", ok: true}
+
+	err := printPrepareActions(rc, []actionPreparer{
+		&actionPreparerMock{err: downloadErr},
+		remaining,
+	})(ctx)
+
+	require.ErrorIs(t, err, downloadErr)
+	// No step has run yet, so the failure has to be recorded against the job itself.
+	assert.Equal(t, downloadErr, common.JobError(ctx))
+	assert.True(t, rc.jobFailed)
+	assert.Zero(t, remaining.prepared)
+}
+
+func TestPrintCompleteJobName(t *testing.T) {
+	for name, tt := range map[string]struct {
+		rc   *RunContext
+		want string
+	}{
+		"job name":            {rc: &RunContext{JobName: "lint", Name: "lint-1"}, want: "lint"},
+		"falls back to name":  {rc: &RunContext{Name: "lint-1"}, want: "lint-1"},
+		"falls back to jobID": {rc: &RunContext{Run: &model.Run{JobID: "lint"}}, want: "lint"},
+	} {
+		t.Run(name, func(t *testing.T) {
+			buf := &bytes.Buffer{}
+			logger := log.New()
+			logger.SetOutput(buf)
+			logger.SetFormatter(&jobLogFormatter{color: cyan})
+			ctx := common.WithLogger(context.Background(), logger.WithFields(log.Fields{"job": "j1"}))
+
+			require.NoError(t, printCompleteJobName(tt.rc)(ctx))
+
+			assert.Equal(t, "[j1]   | Complete job name: "+tt.want+"\n", buf.String())
+		})
+	}
+}
+
+// actionStepMock is a step whose action has to be downloaded before it can run.
+type actionStepMock struct {
+	*stepMock
+	*actionPreparerMock
+}
+
+// TestNewJobExecutorDownloadsAllActionsBeforeTheFirstStep pins the shape of the setup section:
+// every action is downloaded before any step runs, and the job name closes the section. A pre
+// step that downloaded its own action would leave the log interleaved with the downloads.
+func TestNewJobExecutorDownloadsAllActionsBeforeTheFirstStep(t *testing.T) {
+	ctx := common.WithJobErrorContainer(context.Background())
+	jim := &jobInfoMock{}
+	sfm := &stepFactoryMock{}
+	rc := &RunContext{
+		JobContainer: &jobContainerMock{},
+		Run: &model.Run{
+			JobID: "test",
+			Workflow: &model.Workflow{
+				Jobs: map[string]*model.Job{"test": {}},
+			},
+		},
+		Config: &Config{},
+	}
+	rc.ExprEval = rc.NewExpressionEvaluator(ctx)
+
+	steps := []*model.Step{{ID: "1"}, {ID: "2"}}
+	executorOrder := make([]string, 0)
+
+	jim.On("steps").Return(steps)
+	jim.On("matrix").Return(map[string]any{})
+	jim.On("startContainer").Return(func(context.Context) error { return nil })
+	jim.On("stopContainer").Return(func(context.Context) error { return nil })
+	jim.On("closeContainer").Return(func(context.Context) error { return nil })
+	jim.On("interpolateOutputs").Return(func(context.Context) error { return nil })
+	jim.On("result", "success")
+
+	for _, stepModel := range steps {
+		sm := &stepMock{}
+		apm := &actionPreparerMock{reference: "actions/checkout@v" + stepModel.ID, ok: true}
+		sfm.On("newStep", stepModel, rc).Return(&actionStepMock{stepMock: sm, actionPreparerMock: apm}, nil)
+
+		sm.On("pre").Return(func(context.Context) error {
+			executorOrder = append(executorOrder, "pre"+stepModel.ID)
+			return nil
+		})
+		sm.On("main").Return(func(context.Context) error {
+			executorOrder = append(executorOrder, "step"+stepModel.ID)
+			return nil
+		})
+		sm.On("post").Return(func(context.Context) error { return nil })
+
+		defer sm.AssertExpectations(t)
+	}
+
+	logger, hook := logrustest.NewNullLogger()
+	err := newJobExecutor(jim, sfm, rc)(common.WithLogger(ctx, logger.WithField("job", "test")))
+	require.NoError(t, err)
+
+	assert.Equal(t, []string{"pre1", "pre2", "step1", "step2"}, executorOrder)
+
+	setup := make([]string, 0)
+	for _, entry := range hook.AllEntries() {
+		if strings.HasPrefix(entry.Message, "Prepare all required actions") || strings.HasPrefix(entry.Message, "Download action") ||
+			strings.HasPrefix(entry.Message, "Complete job name") {
+			setup = append(setup, entry.Message)
+		}
+	}
+	assert.Equal(t, []string{
+		"Prepare all required actions",
+		"Download action repository 'actions/checkout@v1'",
+		"Download action repository 'actions/checkout@v2'",
+		"Complete job name: test",
+	}, setup)
+}
+
 func TestNewJobExecutor(t *testing.T) {
 	table := []struct {
 		name          string

act/runner/step.go

@@ -107,7 +107,13 @@ func runStepExecutor(step step, stage stepStage, executor common.Executor) commo
 		if strings.Contains(stepString, "::add-mask::") {
 			stepString = "add-mask command"
 		}
+		if stage == stepStageMain {
+			// Main steps print their own raw "Run <title>" header, so this line is redundant and
+			// only leaks into the "Set up job" section for the first step; keep it as a debug trace.
+			logger.Debugf("Run %s %s", stage, stepString)
+		} else {
 			logger.Infof("Run %s %s", stage, stepString)
+		}
 
 		// Prepare and clean Runner File Commands
 		actPath := rc.JobContainer.GetActPath()

act/runner/step_action_remote.go

@@ -131,6 +131,8 @@ func (sar *stepActionRemote) prepareActionExecutor() common.Executor {
 			Token:       token,
 			OfflineMode: sar.RunContext.Config.ActionOfflineMode,
 			Depth:       sar.RunContext.Config.ActionCloneDepth,
+			// printPrepareActions reports the download with its resolved commit.
+			Quiet: true,
 
 			InsecureSkipTLS: sar.cloneSkipTLS(), // For Gitea
 		})
@@ -146,6 +148,13 @@ func (sar *stepActionRemote) prepareActionExecutor() common.Executor {
 			}
 		}
 
+		// Best effort: the download report falls back to the ref alone when the commit is unknown.
+		if _, sha, err := git.FindGitRevision(ctx, actionDir); err != nil {
+			common.Logger(ctx).Debugf("unable to resolve the commit of %s: %v", sar.remoteAction.Reference(), err)
+		} else {
+			sar.resolvedSha = sha
+		}
+
 		remoteReader := func(ctx context.Context) actionYamlReader { //nolint:unparam // pre-existing issue from nektos/act
 			return func(filename string) (io.Reader, io.Closer, error) {
 				f, err := os.Open(filepath.Join(actionDir, sar.remoteAction.Path, filename))
@@ -165,6 +174,15 @@ func (sar *stepActionRemote) prepareActionExecutor() common.Executor {
 	}
 }
 
+// actionDownloadInfo reports the action this step downloaded and the commit it resolved to. ok is
+// false when nothing was fetched, as for the local checkout of the workflow's own repository.
+func (sar *stepActionRemote) actionDownloadInfo() (reference, sha string, ok bool) {
+	if sar.remoteAction == nil || sar.action == nil {
+		return "", "", false
+	}
+	return sar.remoteAction.Reference(), sar.resolvedSha, true
+}
+
 func (sar *stepActionRemote) pre() common.Executor {
 	sar.env = map[string]string{}
 
@@ -313,6 +331,16 @@ func (ra *remoteAction) CloneURL(u string) string {
 	return fmt.Sprintf("%s/%s/%s", u, ra.Org, ra.Repo)
 }
 
+// Reference renders the action as {org}/{repo}[/path]@{ref}, omitting the download source, which
+// can be interpolated from a secret.
+func (ra *remoteAction) Reference() string {
+	repo := fmt.Sprintf("%s/%s", ra.Org, ra.Repo)
+	if ra.Path != "" {
+		repo = fmt.Sprintf("%s/%s", repo, ra.Path)
+	}
+	return fmt.Sprintf("%s@%s", repo, ra.Ref)
+}
+
 func (ra *remoteAction) IsCheckout() bool {
 	if ra.Org == "actions" && ra.Repo == "checkout" {
 		return true

act/runner/step_action_remote_test.go

@@ -10,6 +10,9 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
 	"strings"
 	"testing"
 	"time"
@@ -818,6 +821,97 @@ func Test_newRemoteAction(t *testing.T) {
 	}
 }
 
+func Test_remoteActionReference(t *testing.T) {
+	tests := []struct {
+		uses string
+		want string
+	}{
+		{uses: "actions/checkout@v7", want: "actions/checkout@v7"},
+		{uses: "actions/aws/ec2@main", want: "actions/aws/ec2@main"},
+		// The download source can be interpolated from a secret and must stay out of the log.
+		{uses: "https://gitea.example.com/actions/checkout@v7", want: "actions/checkout@v7"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.uses, func(t *testing.T) {
+			assert.Equal(t, tt.want, newRemoteAction(tt.uses).Reference())
+		})
+	}
+}
+
+// TestStepActionRemotePreResolvesDownloadedCommit runs the real download path against a local
+// git repository standing in for the actions instance, so the reported commit is the one the
+// clone actually checked out.
+func TestStepActionRemotePreResolvesDownloadedCommit(t *testing.T) {
+	instance := t.TempDir()
+	actionDir := filepath.Join(instance, "actions", "setup-go")
+	require.NoError(t, os.MkdirAll(actionDir, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(actionDir, "action.yml"),
+		[]byte("name: setup-go\nruns:\n  using: node20\n  main: index.js\n"), 0o600))
+
+	// Supply an identity on the commit so the test does not depend on a
+	// git identity being configured in the environment; a CI runner without
+	// user.name/user.email would otherwise fail "commit" with exit code 128.
+	for _, args := range [][]string{
+		{"init", "--initial-branch=main", actionDir},
+		{"-C", actionDir, "add", "action.yml"},
+		{"-C", actionDir, "-c", "user.name=runner", "-c", "user.email=runner@example.com", "-c", "commit.gpgsign=false", "commit", "-m", "action"},
+	} {
+		cmd := exec.Command("git", args...)
+		require.NoError(t, cmd.Run(), "git %v", args)
+	}
+	out, err := exec.Command("git", "-C", actionDir, "rev-parse", "HEAD").Output()
+	require.NoError(t, err)
+	wantSha := strings.TrimSpace(string(out))
+
+	sar := &stepActionRemote{
+		Step: &model.Step{Uses: "actions/setup-go@main"},
+		RunContext: &RunContext{
+			Config: &Config{
+				GitHubInstance:        "https://gitea.example.com",
+				DefaultActionInstance: instance,
+				ActionCacheDir:        t.TempDir(),
+			},
+			Run: &model.Run{
+				JobID:    "1",
+				Workflow: &model.Workflow{Jobs: map[string]*model.Job{"1": {}}},
+			},
+		},
+		readAction: readActionImpl,
+	}
+
+	require.NoError(t, sar.prepareActionExecutor()(context.Background()))
+
+	reference, sha, ok := sar.actionDownloadInfo()
+	assert.True(t, ok)
+	assert.Equal(t, "actions/setup-go@main", reference)
+	assert.Equal(t, wantSha, sha)
+}
+
+func TestStepActionRemoteActionDownloadInfo(t *testing.T) {
+	t.Run("reports the action and its resolved commit", func(t *testing.T) {
+		sar := &stepActionRemote{
+			remoteAction: newRemoteAction("actions/checkout@v7"),
+			action:       &model.Action{},
+			resolvedSha:  "9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0",
+		}
+
+		reference, sha, ok := sar.actionDownloadInfo()
+
+		assert.True(t, ok)
+		assert.Equal(t, "actions/checkout@v7", reference)
+		assert.Equal(t, "9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0", sha)
+	})
+
+	t.Run("reports nothing when no action was downloaded", func(t *testing.T) {
+		// The local checkout of the workflow's own repository resolves no action.
+		sar := &stepActionRemote{remoteAction: newRemoteAction("actions/checkout@v7")}
+
+		_, _, ok := sar.actionDownloadInfo()
+
+		assert.False(t, ok)
+	})
+}
+
 func Test_safeFilename(t *testing.T) {
 	tests := []struct {
 		s    string

act/runner/step_docker.go

@@ -85,7 +85,7 @@ func (sd *stepDocker) runUsesContainer() common.Executor {
 			stepContainer.Create(rc.Config.ContainerCapAdd, rc.Config.ContainerCapDrop),
 			stepContainer.Start(true),
 		).Finally(
-			stepContainer.Remove().IfBool(!rc.Config.ReuseContainers),
+			stepContainer.Remove().IfBool(!rc.Config.ReuseContainers && !rc.Config.AutoRemove),
 		).Finally(stepContainer.Close())(ctx)
 	}
 }

act/runner/step_docker_test.go

@@ -16,6 +16,7 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/mock"
+	"github.com/stretchr/testify/require"
 )
 
 func TestStepDockerMain(t *testing.T) {
@@ -118,6 +119,43 @@ func TestStepDockerMain(t *testing.T) {
 	cm.AssertExpectations(t)
 }
 
+// With AutoRemove the daemon reaps the container on exit, so act must not remove it afterwards.
+func TestStepDockerAutoRemove(t *testing.T) {
+	orig := ContainerNewContainer
+	defer func() { ContainerNewContainer = orig }()
+
+	for _, tc := range []struct {
+		autoRemove bool
+		removes    int
+	}{
+		{false, 2}, // stale + post-run
+		{true, 1},  // post-run skipped
+	} {
+		cm := &containerMock{}
+		ContainerNewContainer = func(*container.NewContainerInput) container.ExecutionsEnvironment { return cm }
+
+		sd := &stepDocker{
+			RunContext: &RunContext{
+				Config:       &Config{AutoRemove: tc.autoRemove},
+				Run:          &model.Run{JobID: "1", Workflow: &model.Workflow{Jobs: map[string]*model.Job{"1": {}}}},
+				JobContainer: cm,
+			},
+			Step: &model.Step{ID: "1", Uses: "docker://node:14"},
+		}
+
+		removes := 0
+		cm.On("Pull", false).Return(func(context.Context) error { return nil })
+		cm.On("Remove").Return(func(context.Context) error { removes++; return nil })
+		cm.On("Create", []string(nil), []string(nil)).Return(func(context.Context) error { return nil })
+		cm.On("Start", true).Return(func(context.Context) error { return nil })
+		cm.On("Close").Return(func(context.Context) error { return nil })
+
+		require.NoError(t, sd.runUsesContainer()(context.Background()))
+		cm.AssertExpectations(t)
+		assert.Equal(t, tc.removes, removes)
+	}
+}
+
 func TestStepDockerNewStepContainerAllocatePTY(t *testing.T) {
 	for _, tc := range []struct {
 		name     string

go.mod

@@ -11,7 +11,7 @@ require (
 	github.com/containerd/errdefs v1.0.0
 	github.com/creack/pty v1.1.24
 	github.com/distribution/reference v0.6.0
-	github.com/docker/cli v29.6.1+incompatible
+	github.com/docker/cli v29.6.2+incompatible
 	github.com/docker/go-connections v0.7.0
 	github.com/go-git/go-billy/v5 v5.9.0
 	github.com/go-git/go-git/v5 v5.19.1
@@ -20,7 +20,7 @@ require (
 	github.com/joho/godotenv v1.5.1
 	github.com/julienschmidt/httprouter v1.3.0
 	github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51
-	github.com/mattn/go-isatty v0.0.22
+	github.com/mattn/go-isatty v0.0.23
 	github.com/moby/go-archive v0.2.0
 	github.com/moby/moby/api v1.55.0
 	github.com/moby/moby/client v0.5.0

go.sum

@@ -49,6 +49,8 @@ github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5Qvfr
 github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
 github.com/docker/cli v29.6.1+incompatible h1:oO7F4nn3Ovr/5TlfTUWFbMwBSS/B7Xs6Epv26gBrUP8=
 github.com/docker/cli v29.6.1+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8=
+github.com/docker/cli v29.6.2+incompatible h1:/bjePvcbbFTnRrMfWJBY7AjfICdsiLVgHn6LwTVOcqw=
+github.com/docker/cli v29.6.2+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8=
 github.com/docker/docker-credential-helpers v0.9.6 h1:cT2PbRPSlnMmNTfT2TDMXRyQ1KMWHG7xoTLBcn1ZNv0=
 github.com/docker/docker-credential-helpers v0.9.6/go.mod h1:v1S+hepowrQXITkEfw6o4+BMbGot02wiKpzWhGUZK6c=
 github.com/docker/go-connections v0.7.0 h1:6SsRfJddP22WMrCkj19x9WKjEDTB+ahsdiGYf0mN39c=
@@ -119,6 +121,8 @@ github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHP
 github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
 github.com/mattn/go-isatty v0.0.22 h1:j8l17JJ9i6VGPUFUYoTUKPSgKe/83EYU2zBC7YNKMw4=
 github.com/mattn/go-isatty v0.0.22/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
+github.com/mattn/go-isatty v0.0.23 h1:cYwCQTQf3HB6xUC+BtyCLZNr7IzbOmoZbmssVNzSyiQ=
+github.com/mattn/go-isatty v0.0.23/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
 github.com/mattn/go-runewidth v0.0.21 h1:jJKAZiQH+2mIinzCJIaIG9Be1+0NR+5sz/lYEEjdM8w=
 github.com/mattn/go-runewidth v0.0.21/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
 github.com/mattn/go-shellwords v1.0.12 h1:M2zGm7EW6UQJvDeQxo4T51eKPurbeFbe8WtebGE2xrk=

internal/app/cmd/daemon.go

@@ -147,17 +147,19 @@ func runDaemon(ctx context.Context, daemArgs *daemonArgs, configFile *string) fu
 		}
 		runner.SetCapabilitiesFromDeclare(resp)
 
+		poller := poll.New(cfg, cli, runner)
+
 		if cfg.Metrics.Enabled {
 			metrics.Init()
 			metrics.RunnerInfo.WithLabelValues(ver.Version(), resp.Msg.Runner.Name).Set(1)
 			metrics.RunnerCapacity.Set(float64(cfg.Runner.Capacity))
 			metrics.RegisterUptimeFunc(time.Now())
 			metrics.RegisterRunningJobsFunc(runner.RunningCount, cfg.Runner.Capacity)
-			metrics.StartServer(ctx, cfg.Metrics.Addr)
+			metrics.StartServer(ctx, cfg.Metrics.Addr, func() (bool, string) {
+				return poller.Ready(cfg.Metrics.ReadinessGrace)
+			})
 		}
 
-		poller := poll.New(cfg, cli, runner)
-
 		if daemArgs.Once || reg.Ephemeral {
 			done := make(chan struct{})
 			go func() {

internal/app/poll/poller.go

@@ -32,6 +32,12 @@ type IdleRunner interface {
 	OnIdle(ctx context.Context)
 }
 
+// AvailabilityRunner can temporarily pause task fetching for local resource
+// conditions such as low disk space without changing server-side scheduling.
+type AvailabilityRunner interface {
+	CanAcceptTask(ctx context.Context) (bool, string)
+}
+
 type Poller struct {
 	client       client.Client
 	runner       TaskRunner
@@ -49,6 +55,11 @@ type Poller struct {
 	// unregistered is set when the server rejects the runner with an
 	// Unauthenticated response, meaning the runner is no longer registered.
 	unregistered       atomic.Bool
+	lastHealthyPoll    atomic.Int64
+	lastPollFailed     atomic.Bool
+	availabilityMu     sync.Mutex
+	availabilityReady  bool
+	availabilityReason string
 }
 
 // workerState holds the single poller's backoff state. Consecutive empty or
@@ -70,7 +81,7 @@ func New(cfg *config.Config, client client.Client, runner TaskRunner) *Poller {
 
 	done := make(chan struct{})
 
-	return &Poller{
+	p := &Poller{
 		client: client,
 		runner: runner,
 		cfg:    cfg,
@@ -83,6 +94,10 @@ func New(cfg *config.Config, client client.Client, runner TaskRunner) *Poller {
 
 		done: done,
 	}
+	p.lastHealthyPoll.Store(time.Now().UnixNano())
+	p.availabilityReady = true
+	p.availabilityReason = "ok"
+	return p
 }
 
 func (p *Poller) Poll() {
@@ -102,6 +117,17 @@ func (p *Poller) Poll() {
 			return
 		}
 
+		ready, reason := p.localAvailability(p.pollingCtx)
+		p.reportAvailability(ready, reason)
+		if !ready {
+			p.runIdleMaintenance()
+			<-sem
+			if !p.waitBackoff(s) {
+				return
+			}
+			continue
+		}
+
 		task, ok := p.fetchTask(p.pollingCtx, s)
 		if !ok {
 			p.runIdleMaintenance()
@@ -127,6 +153,15 @@ func (p *Poller) PollOnce() {
 	defer close(p.done)
 	s := &workerState{}
 	for {
+		ready, reason := p.localAvailability(p.pollingCtx)
+		p.reportAvailability(ready, reason)
+		if !ready {
+			p.runIdleMaintenance()
+			if !p.waitBackoff(s) {
+				return
+			}
+			continue
+		}
 		task, ok := p.fetchTask(p.pollingCtx, s)
 		if !ok {
 			p.runIdleMaintenance()
@@ -154,6 +189,48 @@ func (p *Poller) Unregistered() bool {
 	return p.unregistered.Load()
 }
 
+// Ready reports whether the daemon can currently communicate with Gitea and
+// accept work, reusing the availability the poll loop last observed rather than
+// re-running the check. Transient transport failures are tolerated for grace.
+func (p *Poller) Ready(grace time.Duration) (bool, string) {
+	if p.unregistered.Load() {
+		return false, "runner is no longer registered"
+	}
+	p.availabilityMu.Lock()
+	ready, reason := p.availabilityReady, p.availabilityReason
+	p.availabilityMu.Unlock()
+	if !ready {
+		return false, reason
+	}
+	if !p.lastPollFailed.Load() {
+		return true, "ok"
+	}
+	if time.Since(time.Unix(0, p.lastHealthyPoll.Load())) <= grace {
+		return true, "polling errors within grace period"
+	}
+	return false, "unable to poll Gitea"
+}
+
+func (p *Poller) localAvailability(ctx context.Context) (bool, string) {
+	if available, ok := p.runner.(AvailabilityRunner); ok {
+		return available.CanAcceptTask(ctx)
+	}
+	return true, "ok"
+}
+
+func (p *Poller) reportAvailability(ready bool, reason string) {
+	p.availabilityMu.Lock()
+	defer p.availabilityMu.Unlock()
+	switch {
+	case !ready && p.availabilityReady:
+		log.Warnf("runner temporarily unavailable: %s", reason)
+	case ready && !p.availabilityReady:
+		log.Info("runner local health recovered, resuming task polling")
+	}
+	p.availabilityReady = ready
+	p.availabilityReason = reason
+}
+
 func (p *Poller) runIdleMaintenance() {
 	if idleRunner, ok := p.runner.(IdleRunner); ok {
 		idleRunner.OnIdle(p.jobsCtx)
@@ -273,6 +350,7 @@ func (p *Poller) fetchTask(ctx context.Context, s *workerState) (*runnerv1.Task,
 	// found no work within FetchTimeout. Treat it as an empty response and do
 	// not record the duration — the timeout value would swamp the histogram.
 	if errors.Is(err, context.DeadlineExceeded) {
+		p.markHealthyPoll()
 		s.consecutiveEmpty++
 		s.consecutiveErrors = 0 // timeout is a healthy idle response
 		metrics.PollFetchTotal.WithLabelValues(metrics.LabelResultEmpty).Inc()
@@ -291,11 +369,13 @@ func (p *Poller) fetchTask(ctx context.Context, s *workerState) (*runnerv1.Task,
 			return nil, false
 		}
 		log.WithError(err).Error("failed to fetch task")
+		p.lastPollFailed.Store(true)
 		s.consecutiveErrors++
 		metrics.PollFetchTotal.WithLabelValues(metrics.LabelResultError).Inc()
 		metrics.ClientErrors.WithLabelValues(metrics.LabelMethodFetchTask).Inc()
 		return nil, false
 	}
+	p.markHealthyPoll()
 
 	// Successful response — reset error counter.
 	s.consecutiveErrors = 0
@@ -322,3 +402,8 @@ func (p *Poller) fetchTask(ctx context.Context, s *workerState) (*runnerv1.Task,
 	metrics.PollFetchTotal.WithLabelValues(metrics.LabelResultTask).Inc()
 	return resp.Msg.Task, true
 }
+
+func (p *Poller) markHealthyPoll() {
+	p.lastHealthyPoll.Store(time.Now().UnixNano())
+	p.lastPollFailed.Store(false)
+}

internal/app/poll/poller_test.go

@@ -159,6 +159,81 @@ type idleAwareRunner struct {
 	idleCalls atomic.Int64
 }
 
+type availabilityRunner struct {
+	mockRunner
+	ready  atomic.Bool
+	reason string
+}
+
+func (r *availabilityRunner) CanAcceptTask(_ context.Context) (bool, string) {
+	if r.ready.Load() {
+		return true, "ok"
+	}
+	return false, r.reason
+}
+
+func TestPollerReady(t *testing.T) {
+	cfg, err := config.LoadDefault("")
+	require.NoError(t, err)
+	poller := New(cfg, nil, &availabilityRunner{})
+
+	// /readyz reuses the availability the poll loop last recorded.
+	ready, reason := poller.Ready(time.Second)
+	assert.True(t, ready)
+	assert.Equal(t, "ok", reason)
+
+	poller.reportAvailability(false, "low disk space")
+	ready, reason = poller.Ready(time.Second)
+	assert.False(t, ready)
+	assert.Equal(t, "low disk space", reason)
+
+	poller.reportAvailability(true, "ok")
+	poller.lastPollFailed.Store(true)
+	poller.lastHealthyPoll.Store(time.Now().UnixNano())
+	ready, _ = poller.Ready(time.Second)
+	assert.True(t, ready, "transient polling errors should remain ready during grace")
+
+	poller.lastHealthyPoll.Store(time.Now().Add(-2 * time.Second).UnixNano())
+	ready, reason = poller.Ready(time.Second)
+	assert.False(t, ready)
+	assert.Equal(t, "unable to poll Gitea", reason)
+
+	poller.unregistered.Store(true)
+	ready, reason = poller.Ready(time.Second)
+	assert.False(t, ready)
+	assert.Equal(t, "runner is no longer registered", reason)
+}
+
+func TestPollerPausesAndResumesForLocalAvailability(t *testing.T) {
+	var fetches atomic.Int64
+	cli := mocks.NewClient(t)
+	cli.On("FetchTask", mock.Anything, mock.Anything).Maybe().Run(func(mock.Arguments) {
+		fetches.Add(1)
+	}).Return(connect_go.NewResponse(&runnerv1.FetchTaskResponse{}), nil)
+
+	cfg, err := config.LoadDefault("")
+	require.NoError(t, err)
+	cfg.Runner.FetchInterval = 10 * time.Millisecond
+	cfg.Runner.FetchIntervalMax = 10 * time.Millisecond
+	runner := &availabilityRunner{reason: "low disk space"}
+	poller := New(cfg, cli, runner)
+
+	var wg sync.WaitGroup
+	wg.Go(poller.Poll)
+	time.Sleep(40 * time.Millisecond)
+	assert.Zero(t, fetches.Load(), "an unavailable runner must not fetch a task")
+
+	runner.ready.Store(true)
+	require.Eventually(t, func() bool {
+		return fetches.Load() > 0
+	}, time.Second, 10*time.Millisecond, "polling should resume after local recovery")
+
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	require.NoError(t, poller.Shutdown(shutdownCtx))
+	wg.Wait()
+}
+
 func (m *mockRunner) Run(ctx context.Context, _ *runnerv1.Task) error {
 	atomicMax(&m.maxConcurrent, m.running.Add(1))
 	select {

internal/app/run/disk_other.go

@@ -0,0 +1,12 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !aix && !darwin && !dragonfly && !freebsd && !linux && !netbsd && !openbsd && !solaris && !windows
+
+package run
+
+import "fmt"
+
+func freeDiskBytes(path string) (uint64, error) {
+	return 0, fmt.Errorf("free disk space checks are not supported for %s", path)
+}

internal/app/run/disk_test.go

@@ -0,0 +1,53 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package run
+
+import (
+	"testing"
+
+	"gitea.com/gitea/runner/internal/pkg/config"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCanAcceptTaskDiskGuard(t *testing.T) {
+	cfg, err := config.LoadDefault("")
+	require.NoError(t, err)
+	cfg.Host.WorkdirParent = t.TempDir()
+	cfg.HealthCheck.Enabled = true
+	r := &Runner{cfg: cfg}
+
+	ready, _ := r.CanAcceptTask(t.Context())
+	assert.True(t, ready)
+
+	cfg.HealthCheck.MinFreeDiskSpaceMB = 1 << 40
+	ready, reason := r.CanAcceptTask(t.Context())
+	assert.False(t, ready)
+	assert.Contains(t, reason, "low disk space")
+}
+
+func TestDiskCheckDeferredWhileJobRuns(t *testing.T) {
+	cfg, err := config.LoadDefault("")
+	require.NoError(t, err)
+	cfg.HealthCheck.Enabled = true
+	cfg.HealthCheck.MinFreeDiskSpaceMB = 1
+	cfg.Host.WorkdirParent = t.TempDir()
+	r := &Runner{cfg: cfg}
+
+	ready, reason := r.CanAcceptTask(t.Context())
+	assert.True(t, ready)
+	assert.Equal(t, "ok", reason)
+
+	cfg.HealthCheck.MinFreeDiskSpaceMB = 1 << 40
+	r.runningCount.Store(1)
+	ready, reason = r.CanAcceptTask(t.Context())
+	assert.True(t, ready, "the disk check must not run while a job is active")
+	assert.Equal(t, "ok", reason)
+
+	r.runningCount.Store(0)
+	ready, reason = r.CanAcceptTask(t.Context())
+	assert.False(t, ready)
+	assert.Contains(t, reason, "low disk space")
+}

internal/app/run/disk_unix.go

@@ -0,0 +1,16 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build aix || darwin || dragonfly || freebsd || linux || netbsd || openbsd || solaris
+
+package run
+
+import "golang.org/x/sys/unix"
+
+func freeDiskBytes(path string) (uint64, error) {
+	var stat unix.Statfs_t
+	if err := unix.Statfs(path, &stat); err != nil {
+		return 0, err
+	}
+	return uint64(stat.Bavail) * uint64(stat.Bsize), nil //nolint:unconvert // Bavail/Bsize signedness differs by platform
+}

internal/app/run/disk_windows.go

@@ -0,0 +1,20 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build windows
+
+package run
+
+import "golang.org/x/sys/windows"
+
+func freeDiskBytes(path string) (uint64, error) {
+	pathPtr, err := windows.UTF16PtrFromString(path)
+	if err != nil {
+		return 0, err
+	}
+	var available uint64
+	if err := windows.GetDiskFreeSpaceEx(pathPtr, &available, nil, nil); err != nil {
+		return 0, err
+	}
+	return available, nil
+}

internal/app/run/health_check.go

@@ -0,0 +1,106 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package run
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"maps"
+	"os"
+	"os/exec"
+	"strconv"
+	"strings"
+	"time"
+
+	"gitea.com/gitea/runner/act/common"
+	"gitea.com/gitea/runner/internal/pkg/process"
+)
+
+func (r *Runner) checkConfiguredHealth(ctx context.Context) (bool, string) {
+	script := r.cfg.HealthCheck.Script
+	if script == "" {
+		return true, "ok"
+	}
+
+	now := time.Now()
+	if r.now != nil {
+		now = r.now()
+	}
+	if !r.healthCheckLast.IsZero() && now.Sub(r.healthCheckLast) < r.cfg.HealthCheck.Interval {
+		return r.healthCheckReady, r.healthCheckReason
+	}
+
+	env := processEnvironment()
+	maps.Copy(env, r.cloneEnvs())
+	env["GITEA_RUNNER_HEALTH_CHECK"] = "true"
+	env["GITEA_RUNNER_NAME"] = r.name
+	if r.client != nil {
+		env["GITEA_INSTANCE_URL"] = r.client.Address()
+	}
+	env["GITEA_RUNNER_RUNNING_JOBS"] = strconv.FormatInt(r.RunningCount(), 10)
+
+	runner := r.runHealthCheck
+	if runner == nil {
+		runner = executeHealthCheck
+	}
+	err := runner(ctx, script, r.cfg.HealthCheck.Timeout, env)
+	r.healthCheckLast = now
+	r.healthCheckReady = err == nil
+	if err != nil {
+		r.healthCheckReason = "runner health check failed: " + err.Error()
+	} else {
+		r.healthCheckReason = "ok"
+	}
+	return r.healthCheckReady, r.healthCheckReason
+}
+
+func executeHealthCheck(ctx context.Context, script string, timeout time.Duration, env map[string]string) error {
+	checkCtx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+	cmd := exec.CommandContext(checkCtx, script)
+	cmd.Env = envListFromMap(env)
+	cmd.SysProcAttr = process.SysProcAttr(script, false)
+	writer := common.NewLineWriter(func(line string) bool {
+		line = strings.TrimRight(line, "\r\n")
+		if line != "" {
+			common.Logger(ctx).Infof("health check: %s", line)
+		}
+		return true
+	})
+	cmd.Stdout = writer
+	cmd.Stderr = writer
+
+	treeKill := process.NewTreeKill(cmd)
+	if err := cmd.Start(); err != nil {
+		return fmt.Errorf("start: %w", err)
+	}
+	if killer, err := treeKill.Capture(cmd.Process); err == nil {
+		defer killer.Close()
+	}
+	err := cmd.Wait()
+	common.FlushWriter(writer)
+	if errors.Is(checkCtx.Err(), context.DeadlineExceeded) {
+		return fmt.Errorf("timed out after %s", timeout)
+	}
+	if err == nil {
+		return nil
+	}
+	var exitErr *exec.ExitError
+	if errors.As(err, &exitErr) {
+		return fmt.Errorf("exited with code %d", exitErr.ExitCode())
+	}
+	return err
+}
+
+func processEnvironment() map[string]string {
+	environ := os.Environ()
+	env := make(map[string]string, len(environ))
+	for _, value := range environ {
+		if key, item, ok := strings.Cut(value, "="); ok {
+			env[key] = item
+		}
+	}
+	return env
+}

internal/app/run/health_check_test.go

@@ -0,0 +1,148 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package run
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"gitea.com/gitea/runner/internal/pkg/config"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestConfiguredHealthCheckCachesAndRecovers(t *testing.T) {
+	cfg, err := config.LoadDefault("")
+	require.NoError(t, err)
+	cfg.HealthCheck.Enabled = true
+	cfg.HealthCheck.Script = "/health-check"
+	cfg.HealthCheck.Interval = time.Minute
+	cfg.HealthCheck.Timeout = time.Second
+
+	now := time.Now()
+	calls := 0
+	fail := true
+	r := &Runner{
+		cfg:  cfg,
+		name: "runner-1",
+		now:  func() time.Time { return now },
+		runHealthCheck: func(_ context.Context, script string, timeout time.Duration, env map[string]string) error {
+			calls++
+			assert.Equal(t, "/health-check", script)
+			assert.Equal(t, time.Second, timeout)
+			assert.Equal(t, "true", env["GITEA_RUNNER_HEALTH_CHECK"])
+			assert.Equal(t, "runner-1", env["GITEA_RUNNER_NAME"])
+			if fail {
+				return errors.New("unhealthy")
+			}
+			return nil
+		},
+	}
+
+	ready, reason := r.CanAcceptTask(t.Context())
+	assert.False(t, ready)
+	assert.Contains(t, reason, "unhealthy")
+	assert.Equal(t, 1, calls)
+
+	fail = false
+	ready, _ = r.CanAcceptTask(t.Context())
+	assert.False(t, ready, "the failed result should remain cached")
+	assert.Equal(t, 1, calls)
+
+	now = now.Add(time.Minute)
+	ready, reason = r.CanAcceptTask(t.Context())
+	assert.True(t, ready)
+	assert.Equal(t, "ok", reason)
+	assert.Equal(t, 2, calls)
+}
+
+func TestConfiguredHealthCheckDisabled(t *testing.T) {
+	cfg, err := config.LoadDefault("")
+	require.NoError(t, err)
+	cfg.HealthCheck.MinFreeDiskSpaceMB = 1 << 40
+	cfg.HealthCheck.Script = "/must-not-run"
+	r := &Runner{
+		cfg: cfg,
+		runHealthCheck: func(_ context.Context, _ string, _ time.Duration, _ map[string]string) error {
+			t.Fatal("disabled health check executed")
+			return nil
+		},
+	}
+	ready, reason := r.CanAcceptTask(t.Context())
+	assert.True(t, ready)
+	assert.Equal(t, "ok", reason)
+}
+
+func TestConfiguredHealthCheckDeferredWhileJobRuns(t *testing.T) {
+	cfg, err := config.LoadDefault("")
+	require.NoError(t, err)
+	cfg.HealthCheck.Enabled = true
+	cfg.HealthCheck.Script = "/health-check"
+	cfg.HealthCheck.Interval = time.Minute
+
+	now := time.Now()
+	calls := 0
+	fail := false
+	r := &Runner{
+		cfg: cfg,
+		now: func() time.Time { return now },
+		runHealthCheck: func(_ context.Context, _ string, _ time.Duration, _ map[string]string) error {
+			calls++
+			if fail {
+				return errors.New("unhealthy")
+			}
+			return nil
+		},
+	}
+
+	ready, reason := r.CanAcceptTask(t.Context())
+	assert.True(t, ready)
+	assert.Equal(t, "ok", reason)
+	assert.Equal(t, 1, calls)
+
+	now = now.Add(time.Minute)
+	fail = true
+	r.runningCount.Store(1)
+	ready, reason = r.CanAcceptTask(t.Context())
+	assert.True(t, ready, "the last result should be reused while a job runs")
+	assert.Equal(t, "ok", reason)
+	assert.Equal(t, 1, calls)
+
+	r.runningCount.Store(0)
+	ready, reason = r.CanAcceptTask(t.Context())
+	assert.False(t, ready)
+	assert.Contains(t, reason, "unhealthy")
+	assert.Equal(t, 2, calls)
+}
+
+func TestConfiguredHealthCheckInitialRunDeferredWhileJobRuns(t *testing.T) {
+	cfg, err := config.LoadDefault("")
+	require.NoError(t, err)
+	cfg.HealthCheck.Enabled = true
+	cfg.HealthCheck.Script = "/health-check"
+
+	calls := 0
+	r := &Runner{
+		cfg: cfg,
+		runHealthCheck: func(_ context.Context, _ string, _ time.Duration, _ map[string]string) error {
+			calls++
+			return nil
+		},
+	}
+	r.runningCount.Store(1)
+
+	ready, reason := r.CanAcceptTask(t.Context())
+	assert.True(t, ready)
+	assert.Contains(t, reason, "deferred")
+	assert.Zero(t, calls)
+
+	r.runningCount.Store(0)
+	ready, reason = r.CanAcceptTask(t.Context())
+	assert.True(t, ready)
+	assert.Equal(t, "ok", reason)
+	assert.Equal(t, 1, calls)
+}

internal/app/run/runner.go

@@ -66,6 +66,13 @@ type Runner struct {
 	runningCount            atomic.Int64
 	lastIdleCleanupUnixNano atomic.Int64
 	now                     func() time.Time
+	healthCheckLast         time.Time
+	healthCheckReady        bool
+	healthCheckReason       string
+	healthStatusSet         bool
+	healthStatusReady       bool
+	healthStatusReason      string
+	runHealthCheck          func(context.Context, string, time.Duration, map[string]string) error
 }
 
 func NewRunner(cfg *config.Config, reg *config.Registration, cli client.Client) *Runner {
@@ -116,6 +123,7 @@ func NewRunner(cfg *config.Config, reg *config.Registration, cli client.Client)
 		envs:           envs,
 		cacheHandler:   cacheHandler,
 		now:            time.Now,
+		runHealthCheck: executeHealthCheck,
 	}
 	return runner
 }
@@ -315,7 +323,7 @@ func (r *Runner) run(ctx context.Context, task *runnerv1.Task, reporter *report.
 		}
 	}()
 
-	reporter.Logf("%s(version:%s) received task %v of job %v, be triggered by event: %s", r.name, ver.Version(), task.Id, task.Context.Fields["job"].GetStringValue(), task.Context.Fields["event_name"].GetStringValue())
+	r.reportSetup(reporter, task)
 
 	workflow, jobID, err := generateWorkflow(task)
 	if err != nil {
@@ -579,6 +587,67 @@ func (r *Runner) RunningCount() int64 {
 	return r.runningCount.Load()
 }
 
+// CanAcceptTask checks local admission conditions without consuming a task. It is
+// called only from the poll loop, so the cached health fields need no lock.
+func (r *Runner) CanAcceptTask(ctx context.Context) (bool, string) {
+	if !r.cfg.HealthCheck.Enabled {
+		return true, "ok"
+	}
+
+	if r.RunningCount() > 0 {
+		if !r.healthStatusSet {
+			return true, "health checks deferred while jobs are running"
+		}
+		return r.healthStatusReady, r.healthStatusReason
+	}
+
+	if ready, reason := checkFreeDisk(r.cfg); !ready {
+		r.setHealthStatus(ready, reason)
+		return false, reason
+	}
+	ready, reason := r.checkConfiguredHealth(ctx)
+	r.setHealthStatus(ready, reason)
+	return ready, reason
+}
+
+func (r *Runner) setHealthStatus(ready bool, reason string) {
+	r.healthStatusSet = true
+	r.healthStatusReady = ready
+	r.healthStatusReason = reason
+}
+
+// checkFreeDisk evaluates the configured task-admission disk threshold.
+func checkFreeDisk(cfg *config.Config) (bool, string) {
+	root := cfg.Host.WorkdirParent
+	if cfg.Container.BindWorkdir {
+		root = filepath.FromSlash("/" + strings.TrimLeft(cfg.Container.WorkdirParent, "/"))
+	}
+	root = nearestExistingPath(root)
+	available, err := freeDiskBytes(root)
+	if err != nil {
+		return false, fmt.Sprintf("cannot determine free disk space for %s: %v", root, err)
+	}
+	availableMB := available / (1024 * 1024)
+	if availableMB < uint64(cfg.HealthCheck.MinFreeDiskSpaceMB) {
+		return false, fmt.Sprintf("low disk space on %s: %d MiB available, %d MiB required", root, availableMB, cfg.HealthCheck.MinFreeDiskSpaceMB)
+	}
+	return true, "ok"
+}
+
+func nearestExistingPath(path string) string {
+	for path != "" {
+		if _, err := os.Stat(path); err == nil {
+			return path
+		}
+		parent := filepath.Dir(path)
+		if parent == path {
+			return parent
+		}
+		path = parent
+	}
+	return "."
+}
+
 func (r *Runner) Declare(ctx context.Context, labels []string) (*connect.Response[runnerv1.DeclareResponse], error) {
 	return r.client.Declare(ctx, connect.NewRequest(&runnerv1.DeclareRequest{
 		Version:      ver.Version(),

internal/app/run/setup.go

@@ -0,0 +1,83 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package run
+
+import (
+	"fmt"
+	"os"
+	"runtime"
+	"strconv"
+	"strings"
+
+	"gitea.com/gitea/runner/internal/pkg/report"
+	"gitea.com/gitea/runner/internal/pkg/ver"
+
+	runnerv1 "gitea.dev/actions-proto-go/runner/v1"
+)
+
+// osReleasePath describes the host distribution on Linux; absent elsewhere, where the platform
+// falls back to the Go runtime alone. A var so tests can point it at a fixture.
+var osReleasePath = "/etc/os-release"
+
+// reportSetup opens the job log the way actions/runner opens its "Set up job" step. The action
+// downloads and the closing job name are written later, as the job starts.
+func (r *Runner) reportSetup(reporter *report.Reporter, task *runnerv1.Task) {
+	for _, line := range r.setupLines(task) {
+		reporter.Logf("%s", line)
+	}
+}
+
+// setupLines names the runner, then reports what it was asked to run and the host it runs on, each
+// in its own group.
+func (r *Runner) setupLines(task *runnerv1.Task) []string {
+	fields := task.Context.Fields
+	lines := []string{
+		fmt.Sprintf("%s(version:%s)", r.name, ver.Version()),
+		"::group::Runner Information",
+	}
+	if names := r.labels.Names(); len(names) > 0 {
+		lines = append(lines, "Runner labels: "+strings.Join(names, ", "))
+	}
+	lines = append(lines,
+		// The task id correlates the job log with the runner's log and the server's task list.
+		fmt.Sprintf("Task: %d", task.Id),
+		"Job: "+fields["job"].GetStringValue(),
+		"Repository: "+fields["repository"].GetStringValue(),
+		"Triggered by event: "+fields["event_name"].GetStringValue(),
+		"::endgroup::",
+		"::group::Operating System",
+	)
+	lines = append(lines, osInfo()...)
+	return append(lines, "::endgroup::")
+}
+
+// osInfo describes the host the runner executes on.
+func osInfo() []string {
+	lines := make([]string, 0, 2)
+	if name := prettyOSName(); name != "" {
+		lines = append(lines, name)
+	}
+	return append(lines, fmt.Sprintf("%s/%s", runtime.GOOS, runtime.GOARCH))
+}
+
+// prettyOSName reads PRETTY_NAME (e.g. "Ubuntu 24.04.4 LTS") from os-release, or "" when absent.
+func prettyOSName() string {
+	data, err := os.ReadFile(osReleasePath)
+	if err != nil {
+		return ""
+	}
+
+	for line := range strings.SplitSeq(string(data), "\n") {
+		key, value, ok := strings.Cut(strings.TrimSpace(line), "=")
+		if !ok || key != "PRETTY_NAME" {
+			continue
+		}
+		// Values are shell-quoted, but the quotes are optional.
+		if unquoted, err := strconv.Unquote(value); err == nil {
+			return unquoted
+		}
+		return value
+	}
+	return ""
+}

internal/app/run/setup_test.go

@@ -0,0 +1,103 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package run
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"gitea.com/gitea/runner/internal/pkg/labels"
+	"gitea.com/gitea/runner/internal/pkg/ver"
+
+	runnerv1 "gitea.dev/actions-proto-go/runner/v1"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/protobuf/types/known/structpb"
+)
+
+func TestSetupLines(t *testing.T) {
+	original := osReleasePath
+	path := filepath.Join(t.TempDir(), "os-release")
+	require.NoError(t, os.WriteFile(path, []byte("PRETTY_NAME=\"Ubuntu 24.04.4 LTS\"\n"), 0o600))
+	osReleasePath = path
+	defer func() { osReleasePath = original }()
+
+	r := &Runner{
+		name: "gitea-com-gitea-0003",
+		labels: labels.Labels{
+			{Name: "ubuntu-latest", Schema: labels.SchemeDocker, Arg: "//node:20"},
+			{Name: "ubuntu-22.04", Schema: labels.SchemeDocker, Arg: "//node:20"},
+		},
+	}
+	taskCtx, err := structpb.NewStruct(map[string]any{
+		"job":        "lint",
+		"repository": "gitea/runner",
+		"event_name": "pull_request",
+	})
+	require.NoError(t, err)
+
+	assert.Equal(t, []string{
+		"gitea-com-gitea-0003(version:" + ver.Version() + ")",
+		"::group::Runner Information",
+		"Runner labels: ubuntu-latest, ubuntu-22.04",
+		"Task: 268506",
+		"Job: lint",
+		"Repository: gitea/runner",
+		"Triggered by event: pull_request",
+		"::endgroup::",
+		"::group::Operating System",
+		"Ubuntu 24.04.4 LTS",
+		fmt.Sprintf("%s/%s", runtime.GOOS, runtime.GOARCH),
+		"::endgroup::",
+	}, r.setupLines(&runnerv1.Task{Id: 268506, Context: taskCtx}))
+}
+
+func TestPrettyOSName(t *testing.T) {
+	tests := map[string]struct {
+		osRelease string
+		want      string
+	}{
+		"quoted value": {
+			osRelease: "NAME=\"Ubuntu\"\nVERSION_ID=\"24.04\"\nPRETTY_NAME=\"Ubuntu 24.04.4 LTS\"\n",
+			want:      "Ubuntu 24.04.4 LTS",
+		},
+		"unquoted value": {
+			osRelease: "PRETTY_NAME=Alpine Linux v3.21\n",
+			want:      "Alpine Linux v3.21",
+		},
+		"no pretty name": {
+			osRelease: "NAME=\"Ubuntu\"\nVERSION_ID=\"24.04\"\n",
+			want:      "",
+		},
+		// A key that merely ends in PRETTY_NAME must not be mistaken for it.
+		"similar key": {
+			osRelease: "IMAGE_PRETTY_NAME=\"Ubuntu Core 24\"\n",
+			want:      "",
+		},
+	}
+
+	for name, tt := range tests {
+		t.Run(name, func(t *testing.T) {
+			path := filepath.Join(t.TempDir(), "os-release")
+			require.NoError(t, os.WriteFile(path, []byte(tt.osRelease), 0o600))
+
+			original := osReleasePath
+			osReleasePath = path
+			defer func() { osReleasePath = original }()
+
+			assert.Equal(t, tt.want, prettyOSName())
+		})
+	}
+
+	t.Run("missing file", func(t *testing.T) {
+		original := osReleasePath
+		osReleasePath = filepath.Join(t.TempDir(), "absent")
+		defer func() { osReleasePath = original }()
+
+		assert.Empty(t, prettyOSName())
+	})
+}

internal/pkg/config/config.example.yaml

@@ -199,11 +199,29 @@ host:
   # If it's empty, $HOME/.cache/act/ will be used.
   workdir_parent:
 
+# Optional local task-admission checks. Disabled by default. When enabled, low
+# disk space or a failing script pauses new task fetching; existing jobs continue.
+# No health checks run while any job is active; the last result is reused until idle.
+health_check:
+  enabled: false
+  # Minimum free space required on the filesystem holding runner workspaces.
+  # Defaults to 1024 MiB when omitted or set to zero.
+  min_free_disk_space_mb: 1024
+  # Optional additional executable. A non-zero exit, timeout, or startup failure
+  # marks the runner unavailable.
+  script: ''
+  # How long a script result is cached and its maximum execution time.
+  interval: 30s
+  timeout: 10s
+
 metrics:
   # Enable the Prometheus metrics endpoint.
-  # When enabled, metrics are served at http://<addr>/metrics and a liveness check at /healthz.
+  # When enabled, metrics are served at /metrics, liveness at /healthz, and
+  # task-admission readiness at /readyz.
   enabled: false
   # The address for the metrics HTTP server to listen on.
   # Defaults to localhost only. Set to ":9101" to allow external access,
   # but ensure the port is firewall-protected as there is no authentication.
   addr: "127.0.0.1:9101"
+  # Consecutive polling failures may last this long before /readyz returns 503.
+  readiness_grace: 30s

internal/pkg/config/config.go

@@ -97,6 +97,17 @@ type Host struct {
 type Metrics struct {
 	Enabled        bool          `yaml:"enabled"`         // Enabled indicates whether the metrics endpoint is exposed.
 	Addr           string        `yaml:"addr"`            // Addr specifies the listen address for the metrics HTTP server (e.g., ":9101").
+	ReadinessGrace time.Duration `yaml:"readiness_grace"` // ReadinessGrace permits transient polling errors before /readyz becomes unhealthy.
+}
+
+// HealthCheck represents local checks that control whether the runner accepts
+// new tasks. The entire feature is opt-in through Enabled.
+type HealthCheck struct {
+	Enabled            bool          `yaml:"enabled"`                // Enabled activates local task-admission health checks.
+	MinFreeDiskSpaceMB int64         `yaml:"min_free_disk_space_mb"` // MinFreeDiskSpaceMB is the minimum free space required on the work volume.
+	Script             string        `yaml:"script"`                 // Script is an optional executable used as an additional health check.
+	Interval           time.Duration `yaml:"interval"`               // Interval controls how long a script result is cached.
+	Timeout            time.Duration `yaml:"timeout"`                // Timeout caps one health-check script invocation.
 }
 
 // Config represents the overall configuration.
@@ -107,6 +118,7 @@ type Config struct {
 	Container   Container   `yaml:"container"`    // Container represents the configuration for the container.
 	Host        Host        `yaml:"host"`         // Host represents the configuration for the host.
 	Metrics     Metrics     `yaml:"metrics"`      // Metrics represents the configuration for the Prometheus metrics endpoint.
+	HealthCheck HealthCheck `yaml:"health_check"` // HealthCheck controls opt-in local task-admission checks.
 }
 
 // LoadDefault returns the default configuration.
@@ -220,9 +232,21 @@ func LoadDefault(file string) (*Config, error) {
 	if cfg.Runner.PostTaskScript != "" && cfg.Runner.PostTaskScriptTimeout <= 0 {
 		cfg.Runner.PostTaskScriptTimeout = DefaultPostTaskScriptTimeout
 	}
+	if cfg.HealthCheck.MinFreeDiskSpaceMB <= 0 {
+		cfg.HealthCheck.MinFreeDiskSpaceMB = 1024
+	}
+	if cfg.HealthCheck.Interval <= 0 {
+		cfg.HealthCheck.Interval = 30 * time.Second
+	}
+	if cfg.HealthCheck.Timeout <= 0 {
+		cfg.HealthCheck.Timeout = 10 * time.Second
+	}
 	if cfg.Metrics.Addr == "" {
 		cfg.Metrics.Addr = "127.0.0.1:9101"
 	}
+	if cfg.Metrics.ReadinessGrace <= 0 {
+		cfg.Metrics.ReadinessGrace = 30 * time.Second
+	}
 
 	// Validate and fix invalid config combinations to prevent confusing behavior.
 	if cfg.Runner.FetchIntervalMax < cfg.Runner.FetchInterval {

internal/pkg/config/config_test.go

@@ -48,6 +48,41 @@ func TestLoadDefault_DefaultsWorkdirCleanupAge(t *testing.T) {
 	assert.Equal(t, 10*time.Minute, cfg.Runner.IdleCleanupInterval)
 }
 
+func TestLoadDefault_HealthChecksAreOptIn(t *testing.T) {
+	cfg, err := LoadDefault("")
+	require.NoError(t, err)
+	assert.False(t, cfg.HealthCheck.Enabled)
+	assert.Equal(t, int64(1024), cfg.HealthCheck.MinFreeDiskSpaceMB)
+	assert.Empty(t, cfg.HealthCheck.Script)
+	assert.Equal(t, 30*time.Second, cfg.HealthCheck.Interval)
+	assert.Equal(t, 10*time.Second, cfg.HealthCheck.Timeout)
+	assert.False(t, cfg.Metrics.Enabled)
+}
+
+func TestLoadDefault_DiskAndReadinessSettings(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	require.NoError(t, os.WriteFile(path, []byte(`
+health_check:
+  enabled: true
+  min_free_disk_space_mb: 4096
+  script: /usr/local/bin/runner-health
+  interval: 15s
+  timeout: 3s
+metrics:
+  readiness_grace: 45s
+`), 0o600))
+
+	cfg, err := LoadDefault(path)
+	require.NoError(t, err)
+	assert.True(t, cfg.HealthCheck.Enabled)
+	assert.Equal(t, int64(4096), cfg.HealthCheck.MinFreeDiskSpaceMB)
+	assert.Equal(t, "/usr/local/bin/runner-health", cfg.HealthCheck.Script)
+	assert.Equal(t, 15*time.Second, cfg.HealthCheck.Interval)
+	assert.Equal(t, 3*time.Second, cfg.HealthCheck.Timeout)
+	assert.Equal(t, 45*time.Second, cfg.Metrics.ReadinessGrace)
+}
+
 func TestLoadDefault_UsesConfiguredWorkdirCleanupAge(t *testing.T) {
 	dir := t.TempDir()
 	path := filepath.Join(dir, "config.yaml")

internal/pkg/metrics/metrics_test.go

@@ -81,7 +81,7 @@ func TestRegisterRunningJobsFuncZeroCapacity(t *testing.T) {
 
 func TestStartServerCanBeCancelled(t *testing.T) {
 	ctx, cancel := context.WithCancel(context.Background())
-	StartServer(ctx, "127.0.0.1:0")
+	StartServer(ctx, "127.0.0.1:0", nil)
 	cancel()
 }
 

internal/pkg/metrics/server.go

@@ -13,19 +13,12 @@ import (
 )
 
 // StartServer starts an HTTP server that serves Prometheus metrics on /metrics
-// and a liveness check on /healthz. The server shuts down when ctx is cancelled.
+// and health checks. The server shuts down when ctx is cancelled.
 // Call Init() before StartServer to register metrics with the Registry.
-func StartServer(ctx context.Context, addr string) {
+func StartServer(ctx context.Context, addr string, readiness func() (bool, string)) {
-	mux := http.NewServeMux()
-	mux.Handle("/metrics", promhttp.HandlerFor(Registry, promhttp.HandlerOpts{}))
-	mux.HandleFunc("/healthz", func(w http.ResponseWriter, _ *http.Request) {
-		w.WriteHeader(http.StatusOK)
-		_, _ = w.Write([]byte("ok"))
-	})
-
 	srv := &http.Server{
 		Addr:              addr,
-		Handler:           mux,
+		Handler:           NewHTTPHandler(readiness),
 		ReadHeaderTimeout: 5 * time.Second,
 		ReadTimeout:       10 * time.Second,
 		WriteTimeout:      10 * time.Second,
@@ -48,3 +41,25 @@ func StartServer(ctx context.Context, addr string) {
 		}
 	}()
 }
+
+// NewHTTPHandler returns the metrics and health endpoints used by StartServer.
+func NewHTTPHandler(readiness func() (bool, string)) http.Handler {
+	mux := http.NewServeMux()
+	mux.Handle("/metrics", promhttp.HandlerFor(Registry, promhttp.HandlerOpts{}))
+	mux.HandleFunc("/healthz", func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("ok"))
+	})
+	mux.HandleFunc("/readyz", func(w http.ResponseWriter, _ *http.Request) {
+		ready, reason := true, "ok"
+		if readiness != nil {
+			ready, reason = readiness()
+		}
+		if !ready {
+			w.WriteHeader(http.StatusServiceUnavailable)
+		}
+		_, _ = w.Write([]byte(reason))
+	})
+
+	return mux
+}

internal/pkg/metrics/server_test.go

@@ -0,0 +1,43 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package metrics
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestReadyEndpoint(t *testing.T) {
+	tests := []struct {
+		name   string
+		ready  bool
+		reason string
+		status int
+	}{
+		{"ready", true, "ok", http.StatusOK},
+		{"not ready", false, "low disk space", http.StatusServiceUnavailable},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			handler := NewHTTPHandler(func() (bool, string) { return test.ready, test.reason })
+			request := httptest.NewRequest(http.MethodGet, "/readyz", nil)
+			response := httptest.NewRecorder()
+			handler.ServeHTTP(response, request)
+			assert.Equal(t, test.status, response.Code)
+			assert.Equal(t, test.reason, response.Body.String())
+		})
+	}
+}
+
+func TestHealthEndpointStaysLiveWhenNotReady(t *testing.T) {
+	handler := NewHTTPHandler(func() (bool, string) { return false, "low disk space" })
+	request := httptest.NewRequest(http.MethodGet, "/healthz", nil)
+	response := httptest.NewRecorder()
+	handler.ServeHTTP(response, request)
+	assert.Equal(t, http.StatusOK, response.Code)
+	assert.Equal(t, "ok", response.Body.String())
+}

internal/pkg/process/group_others.go

@@ -0,0 +1,28 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !windows
+
+package process
+
+import "os"
+
+// Group is a no-op outside Windows: process groups already reclaim a step's
+// tree, and an orphan does not block workspace deletion the way an open Windows
+// handle does.
+type Group struct{}
+
+// NewGroup returns a Group that owns nothing.
+func NewGroup() (*Group, error) {
+	return &Group{}, nil
+}
+
+// Assign does nothing.
+func (g *Group) Assign(_ *os.Process) error {
+	return nil
+}
+
+// Close does nothing.
+func (g *Group) Close() error {
+	return nil
+}

internal/pkg/process/group_windows.go

@@ -0,0 +1,86 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package process
+
+import (
+	"os"
+	"sync"
+	"unsafe"
+
+	"golang.org/x/sys/windows"
+)
+
+// Group is a job-scoped Windows Job Object holding every process the job's steps
+// start; closing it terminates whatever is still assigned, reaching orphans the
+// per-step Killer misses (a completed step's leftover has no parent to walk from).
+type Group struct {
+	mu  sync.Mutex
+	job windows.Handle
+}
+
+// NewGroup creates the job object. Closing it is what terminates the leftovers,
+// so the caller must Close it when the job ends.
+func NewGroup() (*Group, error) {
+	job, err := windows.CreateJobObject(nil, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	info := windows.JOBOBJECT_EXTENDED_LIMIT_INFORMATION{
+		BasicLimitInformation: windows.JOBOBJECT_BASIC_LIMIT_INFORMATION{
+			LimitFlags: windows.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
+		},
+	}
+	if _, err := windows.SetInformationJobObject(
+		job,
+		windows.JobObjectExtendedLimitInformation,
+		uintptr(unsafe.Pointer(&info)),
+		uint32(unsafe.Sizeof(info)),
+	); err != nil {
+		_ = windows.CloseHandle(job)
+		return nil, err
+	}
+
+	return &Group{job: job}, nil
+}
+
+// Assign adds a started process to the job; anything it spawns afterwards joins
+// too. Call before NewKiller so the step's job nests inside this one. Nil-safe.
+func (g *Group) Assign(p *os.Process) error {
+	if g == nil || p == nil {
+		return nil
+	}
+
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if g.job == 0 {
+		return nil
+	}
+
+	h, err := windows.OpenProcess(windows.PROCESS_SET_QUOTA|windows.PROCESS_TERMINATE, false, uint32(p.Pid))
+	if err != nil {
+		return err
+	}
+	defer func() { _ = windows.CloseHandle(h) }()
+
+	return windows.AssignProcessToJobObject(g.job, h)
+}
+
+// Close drops the job handle, terminating every process still assigned to it.
+// Nil-safe and idempotent.
+func (g *Group) Close() error {
+	if g == nil {
+		return nil
+	}
+
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if g.job == 0 {
+		return nil
+	}
+
+	h := g.job
+	g.job = 0
+	return windows.CloseHandle(h)
+}

internal/pkg/process/group_windows_test.go

@@ -0,0 +1,113 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package process
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// startOrphanMaker starts a process that spawns a detached, long-lived child and
+// exits, leaving the child parentless. Returns the cmd and the child's PID file.
+func startOrphanMaker(t *testing.T) (*exec.Cmd, string) {
+	t.Helper()
+
+	pidFile := filepath.Join(t.TempDir(), "child.pid")
+	script := fmt.Sprintf(
+		`$c = Start-Process powershell -PassThru -ArgumentList '-NoProfile','-Command','Start-Sleep -Seconds 600'; `+
+			`Set-Content -LiteralPath %q -Value $c.Id`, pidFile)
+
+	cmd := exec.Command("powershell.exe", "-NoProfile", "-Command", script)
+	require.NoError(t, cmd.Start())
+	t.Cleanup(func() { _ = cmd.Process.Kill() })
+
+	return cmd, pidFile
+}
+
+// awaitChildPID waits until the spawned child has reported its PID and is running.
+func awaitChildPID(t *testing.T, pidFile string) int {
+	t.Helper()
+
+	var childPID int
+	require.Eventually(t, func() bool {
+		b, err := os.ReadFile(pidFile)
+		if err != nil {
+			return false
+		}
+		s := strings.TrimSpace(string(b))
+		if s == "" {
+			return false
+		}
+		childPID, _ = strconv.Atoi(s)
+		return childPID > 0 && processAlive(childPID)
+	}, 20*time.Second, 200*time.Millisecond, "child process should start")
+
+	return childPID
+}
+
+// TestGroupClosePropagatesToOrphan covers what the per-step Killer cannot: a
+// completed step's orphan, reachable only by closing the job object.
+func TestGroupClosePropagatesToOrphan(t *testing.T) {
+	group, err := NewGroup()
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = group.Close() })
+
+	cmd, pidFile := startOrphanMaker(t)
+	require.NoError(t, group.Assign(cmd.Process))
+
+	childPID := awaitChildPID(t, pidFile)
+
+	require.NoError(t, cmd.Wait()) // the step process exits cleanly, like a passing step
+	require.Eventually(t, func() bool {
+		return !processAlive(cmd.Process.Pid)
+	}, 20*time.Second, 200*time.Millisecond, "the step process should have exited on its own")
+
+	require.True(t, processAlive(childPID), "orphan should outlive its parent")
+
+	require.NoError(t, group.Close())
+	require.Eventually(t, func() bool {
+		return !processAlive(childPID)
+	}, 20*time.Second, 200*time.Millisecond, "closing the job must terminate the orphan")
+}
+
+// TestGroupNestsWithKiller: assigned to the group first and the step's Killer
+// second, cancelling the step still kills exactly that step's tree.
+func TestGroupNestsWithKiller(t *testing.T) {
+	group, err := NewGroup()
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = group.Close() })
+
+	cmd := exec.Command("powershell.exe", "-NoProfile", "-Command", "Start-Sleep -Seconds 600")
+	require.NoError(t, cmd.Start())
+	t.Cleanup(func() { _ = cmd.Process.Kill() })
+
+	require.NoError(t, group.Assign(cmd.Process))
+
+	// Nesting must be accepted, else cancellation falls back to a single-process kill.
+	killer, err := NewKiller(cmd.Process)
+	require.NoError(t, err, "the step's job object must nest inside the group's")
+	defer killer.Close()
+
+	require.NoError(t, killer.Kill())
+	require.Eventually(t, func() bool {
+		return !processAlive(cmd.Process.Pid)
+	}, 20*time.Second, 200*time.Millisecond, "cancelling the step should still kill its tree")
+}
+
+// TestGroupNilSafe covers the fallback path: when the job object cannot be
+// created the caller holds a nil *Group and must still be able to use it.
+func TestGroupNilSafe(t *testing.T) {
+	var group *Group
+	require.NoError(t, group.Assign(nil))
+	require.NoError(t, group.Close())
+	require.NoError(t, group.Close())
+}

internal/pkg/process/leftover.go

@@ -0,0 +1,29 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package process
+
+import (
+	"path/filepath"
+	"strings"
+)
+
+// pathWithin is the OS-agnostic core of dirContainsPath: dir and target must
+// already be cleaned, and fold folds case.
+func pathWithin(dir, target string, fold bool) bool {
+	if dir == "" || target == "" || dir == "." || target == "." {
+		return false
+	}
+	if fold {
+		dir = strings.ToLower(dir)
+		target = strings.ToLower(target)
+	}
+	if dir == target {
+		return true
+	}
+	sep := string(filepath.Separator)
+	if !strings.HasSuffix(dir, sep) {
+		dir += sep
+	}
+	return strings.HasPrefix(target, dir)
+}

internal/pkg/process/leftover_others.go

@@ -0,0 +1,14 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !windows
+
+package process
+
+import "context"
+
+// KillProcessesWithCWDUnder is a no-op outside Windows: an open handle does not
+// block os.RemoveAll there.
+func KillProcessesWithCWDUnder(_ context.Context, _ []string) (int, error) {
+	return 0, nil
+}

internal/pkg/process/leftover_test.go

@@ -0,0 +1,41 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package process
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+func TestPathWithin(t *testing.T) {
+	base := filepath.Join("base", "job1")
+
+	cases := []struct {
+		name   string
+		dir    string
+		target string
+		fold   bool
+		want   bool
+	}{
+		{"same dir", base, base, false, true},
+		{"direct child", base, filepath.Join(base, "app.exe"), false, true},
+		{"deep child", base, filepath.Join(base, "sub", "sub", "app.exe"), false, true},
+		{"parent is not within child", filepath.Join(base, "sub"), base, false, false},
+		{"name-prefix sibling spared", base, filepath.Join("base", "job10", "app.exe"), false, false},
+		{"unrelated", base, filepath.Join("other", "app.exe"), false, false},
+		{"empty dir", "", base, false, false},
+		{"empty target", base, "", false, false},
+		{"dot dir", ".", base, false, false},
+		{"case-sensitive miss", base, filepath.Join("base", "JOB1", "app.exe"), false, false},
+		{"case-insensitive hit", base, filepath.Join("base", "JOB1", "app.exe"), true, true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := pathWithin(filepath.Clean(tc.dir), filepath.Clean(tc.target), tc.fold)
+			if got != tc.want {
+				t.Fatalf("pathWithin(%q, %q, fold=%v) = %v, want %v", tc.dir, tc.target, tc.fold, got, tc.want)
+			}
+		})
+	}
+}

internal/pkg/process/leftover_windows.go

@@ -0,0 +1,182 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package process
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"unsafe"
+
+	"golang.org/x/sys/windows"
+)
+
+// dirContainsPath reports whether target is dir or lives beneath it,
+// case-insensitively, so a name-prefix sibling (job1 vs job10) is not a match.
+func dirContainsPath(dir, target string) bool {
+	return pathWithin(filepath.Clean(dir), filepath.Clean(target), true)
+}
+
+// KillProcessesWithCWDUnder terminates every process in the runner's session
+// whose cwd is one of dirs or below, catching leftovers the path scan misses
+// (Win32_Process exposes no cwd) that still pin a handle. Best-effort.
+func KillProcessesWithCWDUnder(ctx context.Context, dirs []string) (int, error) {
+	if len(dirs) == 0 {
+		return 0, nil
+	}
+
+	pids, err := listProcessIDs()
+	if err != nil {
+		return 0, err
+	}
+
+	self := uint32(os.Getpid())
+	var ownSession uint32
+	if err := windows.ProcessIdToSessionId(self, &ownSession); err != nil {
+		return 0, fmt.Errorf("look up own session: %w", err)
+	}
+
+	var killed int
+	var errs []error
+	for _, pid := range pids {
+		if ctx.Err() != nil {
+			break
+		}
+		// Never touch ourselves, System Idle (0) or System (4).
+		if pid == self || pid == 0 || pid == 4 {
+			continue
+		}
+		var session uint32
+		if err := windows.ProcessIdToSessionId(pid, &session); err != nil || session != ownSession {
+			continue
+		}
+		ok, err := terminateIfCWDUnder(pid, dirs)
+		if err != nil {
+			errs = append(errs, err)
+			continue
+		}
+		if ok {
+			killed++
+		}
+	}
+
+	return killed, errors.Join(errs...)
+}
+
+// terminateIfCWDUnder opens pid once and both reads its cwd and terminates it
+// through that one handle, so a PID recycled between the two cannot be hit.
+func terminateIfCWDUnder(pid uint32, dirs []string) (bool, error) {
+	h, err := windows.OpenProcess(windows.PROCESS_QUERY_INFORMATION|windows.PROCESS_VM_READ|windows.PROCESS_TERMINATE, false, pid)
+	if err != nil {
+		return false, nil // best-effort: gone, higher integrity, or another user
+	}
+	defer func() { _ = windows.CloseHandle(h) }()
+
+	cwd, err := processCWDHandle(h)
+	if err != nil || cwd == "" {
+		return false, nil
+	}
+
+	for _, d := range dirs {
+		if dirContainsPath(d, cwd) {
+			if err := windows.TerminateProcess(h, 1); err != nil {
+				return false, fmt.Errorf("terminate pid %d: %w", pid, err)
+			}
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
+// listProcessIDs returns the PIDs of every process in a Toolhelp snapshot.
+func listProcessIDs() ([]uint32, error) {
+	snap, err := windows.CreateToolhelp32Snapshot(windows.TH32CS_SNAPPROCESS, 0)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = windows.CloseHandle(snap) }()
+
+	var entry windows.ProcessEntry32
+	entry.Size = uint32(unsafe.Sizeof(entry))
+
+	pids := make([]uint32, 0, 256)
+	err = windows.Process32First(snap, &entry)
+	for err == nil {
+		pids = append(pids, entry.ProcessID)
+		err = windows.Process32Next(snap, &entry)
+	}
+	if !errors.Is(err, windows.ERROR_NO_MORE_FILES) {
+		return pids, err
+	}
+	return pids, nil
+}
+
+// processCWDHandle reads a process's working directory from its PEB (walking
+// PEB -> ProcessParameters -> CurrentDirectory.DosPath). h must carry
+// PROCESS_QUERY_INFORMATION|PROCESS_VM_READ.
+func processCWDHandle(h windows.Handle) (string, error) {
+	var pbi windows.PROCESS_BASIC_INFORMATION
+	var retLen uint32
+	if err := windows.NtQueryInformationProcess(h, windows.ProcessBasicInformation, unsafe.Pointer(&pbi), uint32(unsafe.Sizeof(pbi)), &retLen); err != nil {
+		return "", err
+	}
+	if pbi.PebBaseAddress == nil {
+		return "", errors.New("nil PEB base address")
+	}
+	pebAddr := uintptr(unsafe.Pointer(pbi.PebBaseAddress))
+
+	paramsAddr, err := readRemotePtr(h, pebAddr+unsafe.Offsetof(windows.PEB{}.ProcessParameters))
+	if err != nil || paramsAddr == 0 {
+		return "", err
+	}
+
+	// DosPath is the leading NTUnicodeString of CURDIR, so it shares CurrentDirectory's address.
+	dosPathAddr := paramsAddr + unsafe.Offsetof(windows.RTL_USER_PROCESS_PARAMETERS{}.CurrentDirectory)
+	length, err := readRemoteU16(h, dosPathAddr+unsafe.Offsetof(windows.NTUnicodeString{}.Length))
+	if err != nil || length == 0 {
+		return "", err
+	}
+	bufAddr, err := readRemotePtr(h, dosPathAddr+unsafe.Offsetof(windows.NTUnicodeString{}.Buffer))
+	if err != nil || bufAddr == 0 {
+		return "", err
+	}
+
+	u16 := make([]uint16, (length+1)/2) // round up so an odd Length cannot overflow the buffer
+	var n uintptr
+	if err := windows.ReadProcessMemory(h, bufAddr, (*byte)(unsafe.Pointer(&u16[0])), uintptr(length), &n); err != nil {
+		return "", err
+	}
+	if n != uintptr(length) {
+		return "", errors.New("short read of working directory")
+	}
+	return windows.UTF16ToString(u16), nil
+}
+
+// readRemotePtr reads a single pointer-sized value from another process.
+func readRemotePtr(h windows.Handle, addr uintptr) (uintptr, error) {
+	var v uintptr
+	var n uintptr
+	if err := windows.ReadProcessMemory(h, addr, (*byte)(unsafe.Pointer(&v)), unsafe.Sizeof(v), &n); err != nil {
+		return 0, err
+	}
+	if n != unsafe.Sizeof(v) {
+		return 0, errors.New("short pointer read")
+	}
+	return v, nil
+}
+
+// readRemoteU16 reads a single uint16 from another process.
+func readRemoteU16(h windows.Handle, addr uintptr) (uint16, error) {
+	var v uint16
+	var n uintptr
+	if err := windows.ReadProcessMemory(h, addr, (*byte)(unsafe.Pointer(&v)), unsafe.Sizeof(v), &n); err != nil {
+		return 0, err
+	}
+	if n != unsafe.Sizeof(v) {
+		return 0, errors.New("short uint16 read")
+	}
+	return v, nil
+}

internal/pkg/process/leftover_windows_test.go

@@ -0,0 +1,91 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package process
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"golang.org/x/sys/windows"
+)
+
+// startSleeperIn launches a long-running child whose cwd is dir but whose
+// executable lives outside it — what the path scan cannot see.
+func startSleeperIn(t *testing.T, dir string) *exec.Cmd {
+	t.Helper()
+	ping := filepath.Join(os.Getenv("SystemRoot"), "System32", "ping.exe")
+	cmd := exec.Command(ping, "-n", "60", "127.0.0.1")
+	cmd.Dir = dir
+	cmd.SysProcAttr = &syscall.SysProcAttr{HideWindow: true}
+	require.NoError(t, cmd.Start())
+	t.Cleanup(func() {
+		_ = cmd.Process.Kill()
+		_, _ = cmd.Process.Wait()
+	})
+	return cmd
+}
+
+// processCWD opens pid and reads its working directory. Test-only; the reaper
+// shares one handle across read and kill via processCWDHandle.
+func processCWD(pid uint32) (string, error) {
+	h, err := windows.OpenProcess(windows.PROCESS_QUERY_INFORMATION|windows.PROCESS_VM_READ, false, pid)
+	if err != nil {
+		return "", err
+	}
+	defer func() { _ = windows.CloseHandle(h) }()
+	return processCWDHandle(h)
+}
+
+// awaitCWD waits until pid's PEB reports a readable cwd (not populated the
+// instant the process starts) and returns it.
+func awaitCWD(t *testing.T, pid int) string {
+	t.Helper()
+	var cwd string
+	require.Eventually(t, func() bool {
+		var err error
+		cwd, err = processCWD(uint32(pid))
+		return err == nil && cwd != ""
+	}, 5*time.Second, 50*time.Millisecond, "process cwd should become readable")
+	return cwd
+}
+
+func TestProcessCWDReadsWorkingDirectory(t *testing.T) {
+	dir := t.TempDir()
+	cmd := startSleeperIn(t, dir)
+	cwd := awaitCWD(t, cmd.Process.Pid)
+	require.True(t, dirContainsPath(dir, cwd), "cwd %q should be within %q", cwd, dir)
+}
+
+func TestKillProcessesWithCWDUnderTerminatesMatch(t *testing.T) {
+	dir := t.TempDir()
+	// Executable outside dir and arguments carry no workspace path, so only the
+	// working directory links this process to dir.
+	cmd := startSleeperIn(t, dir)
+	awaitCWD(t, cmd.Process.Pid)
+
+	killed, err := KillProcessesWithCWDUnder(context.Background(), []string{dir})
+	require.NoError(t, err)
+	require.GreaterOrEqual(t, killed, 1)
+
+	require.Eventually(t, func() bool {
+		return !processAlive(cmd.Process.Pid)
+	}, 5*time.Second, 50*time.Millisecond, "matched process should exit")
+}
+
+func TestKillProcessesWithCWDUnderSparesUnrelated(t *testing.T) {
+	workspace := t.TempDir()
+	elsewhere := t.TempDir()
+	cmd := startSleeperIn(t, elsewhere)
+	awaitCWD(t, cmd.Process.Pid)
+
+	_, err := KillProcessesWithCWDUnder(context.Background(), []string{workspace})
+	require.NoError(t, err)
+	require.True(t, processAlive(cmd.Process.Pid), "process outside owned dirs must be spared")
+}