Confine cleanup and use held session locks

internal/app/clean.go

@@ -11,6 +11,7 @@ import (
 
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
 // Clean removes local workspace/spool state while preserving durable cache
@@ -135,7 +136,7 @@ func reportCleanScopedDir(out io.Writer, root, target, policy string, dryRun boo
 		fmt.Fprintf(out, "Missing: %s\n", dir.TargetAbs)
 		return nil
 	}
-	if err := os.RemoveAll(dir.TargetAbs); err != nil {
+	if err := fileops.RemoveAllUnderRoot(dir.RootAbs, dir.TargetAbs); err != nil {
 		return fmt.Errorf("cleanup policy %s: remove %q: %w", policy, dir.TargetAbs, err)
 	}
 	fmt.Fprintf(out, "Deleted: %s\n", dir.TargetAbs)
@@ -160,7 +161,7 @@ func reportCleanRootChildren(out io.Writer, root, policy string, dryRun bool) er
 			fmt.Fprintf(out, "Would delete: %s\n", entry)
 			continue
 		}
-		if err := os.RemoveAll(entry); err != nil {
+		if err := fileops.RemoveAllUnderRoot(rootAbs, entry); err != nil {
 			return fmt.Errorf("cleanup policy %s: remove %q: %w", policy, entry, err)
 		}
 		fmt.Fprintf(out, "Deleted: %s\n", entry)
@@ -265,7 +266,7 @@ func reportCleanScopedFile(out io.Writer, root, target, policy string, dryRun bo
 		fmt.Fprintf(out, "Missing cache file: %s\n", file.TargetAbs)
 		return false, nil
 	}
-	if err := os.Remove(file.TargetAbs); err != nil {
+	if err := fileops.RemoveAllUnderRoot(file.RootAbs, file.TargetAbs); err != nil {
 		return false, fmt.Errorf("cleanup policy %s: remove %q: %w", policy, file.TargetAbs, err)
 	}
 	fmt.Fprintf(out, "Deleted cache file: %s\n", file.TargetAbs)

internal/app/post_publish_cleanup.go

@@ -3,12 +3,12 @@ package app
 import (
 	"context"
 	"fmt"
-	"os"
 	"path/filepath"
 	"strings"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 )
 
@@ -167,7 +167,7 @@ func removeRunScopedDir(root, target, policy string) error {
 	if !dir.Exists {
 		return nil
 	}
-	if err := os.RemoveAll(dir.TargetAbs); err != nil {
+	if err := fileops.RemoveAllUnderRoot(dir.RootAbs, dir.TargetAbs); err != nil {
 		return fmt.Errorf("cleanup policy %s: remove %q: %w", policy, dir.TargetAbs, err)
 	}
 	return nil

internal/app/restore.go

@@ -22,7 +22,7 @@ var buildRestorePlanFn = buildRestorePlan
 var executeRestorePlanFn = executeRestorePlan
 
 // Restore validates restore CLI/config inputs and storage preflight for future restore phases.
-func Restore(ctx context.Context, args []string, out io.Writer) error {
+func Restore(ctx context.Context, args []string, out io.Writer) (resultErr error) {
 	positionalSessionID, args := pullLeadingSessionID(args)
 	fs := flag.NewFlagSet("restore", flag.ContinueOnError)
 	fs.SetOutput(out)
@@ -96,12 +96,18 @@ func Restore(ctx context.Context, args []string, out io.Writer) error {
 	if _, err := artifactStore.EnsureLayoutFor(cfg.Session.Campaign, cfg.Session.SessionID); err != nil {
 		return fmt.Errorf("restore: prepare workdir: %w", err)
 	}
-	lock, err := artifactStore.AcquireSessionLockFor(cfg.Session.Campaign, cfg.Session.SessionID)
+	lock, err := artifactStore.AcquireSessionLockForContext(ctx, cfg.Session.Campaign, cfg.Session.SessionID)
 	if err != nil {
 		return fmt.Errorf("restore: acquire session lock: %w", err)
 	}
 	defer func() {
-		_ = artifactStore.ReleaseSessionLock(lock)
+		if releaseErr := artifactStore.ReleaseSessionLock(lock); releaseErr != nil {
+			if resultErr == nil {
+				resultErr = fmt.Errorf("restore: release session lock: %w", releaseErr)
+			} else {
+				resultErr = errors.Join(resultErr, fmt.Errorf("restore: release session lock: %w", releaseErr))
+			}
+		}
 	}()
 
 	if plan.ConflictCount > 0 && !force {

internal/app/runner.go

@@ -2,6 +2,7 @@ package app
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log/slog"
 	"os"
@@ -39,7 +40,7 @@ type RunSummary struct {
 
 var executeStagesFn = executeStages
 
-func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage, opts RunOptions) (*RunSummary, error) {
+func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage, opts RunOptions) (summary *RunSummary, resultErr error) {
 	env := opts.Env
 	if env == nil {
 		env = &Env{}
@@ -111,12 +112,18 @@ func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage
 		return nil, fmt.Errorf("prepare workdir: %w", err)
 	}
 
-	lock, err := artifactStore.AcquireSessionLockFor(cfg.Session.Campaign, cfg.Session.SessionID)
+	lock, err := artifactStore.AcquireSessionLockForContext(ctx, cfg.Session.Campaign, cfg.Session.SessionID)
 	if err != nil {
 		return nil, fmt.Errorf("acquire session lock: %w", err)
 	}
 	defer func() {
-		_ = artifactStore.ReleaseSessionLock(lock)
+		if releaseErr := artifactStore.ReleaseSessionLock(lock); releaseErr != nil {
+			if resultErr == nil {
+				resultErr = fmt.Errorf("release session lock: %w", releaseErr)
+			} else {
+				resultErr = errors.Join(resultErr, fmt.Errorf("release session lock: %w", releaseErr))
+			}
+		}
 	}()
 
 	manifestPath := paths.ManifestPath

internal/artifacts/local.go

@@ -1,6 +1,7 @@
 package artifacts
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"io"
@@ -14,7 +15,7 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
 )
 
-// ErrLockConflict is returned when a session lock already exists.
+// ErrLockConflict is returned when a session lock is currently held.
 var ErrLockConflict = errors.New("session workdir is already locked")
 
 // LockHandle tracks a held lock for a session work directory.
@@ -178,32 +179,74 @@ func (s *LocalStore) AcquireSessionLockFor(campaign, sessionID string) (*LockHan
 	return s.acquireSessionLockForPaths(paths)
 }
 
-func (s *LocalStore) acquireSessionLockForPaths(paths SessionPaths) (*LockHandle, error) {
-	f, err := os.OpenFile(paths.LockPath, os.O_CREATE|os.O_EXCL|os.O_WRONLY, fileops.WorkspaceFileMode)
+// AcquireSessionLockForContext waits for a session lock until it becomes
+// available or ctx is cancelled.
+func (s *LocalStore) AcquireSessionLockForContext(ctx context.Context, campaign, sessionID string) (*LockHandle, error) {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	paths, err := s.EnsureLayoutFor(campaign, sessionID)
 	if err != nil {
-		if errors.Is(err, os.ErrExist) {
-			return nil, fmt.Errorf("%w: %s", ErrLockConflict, paths.LockPath)
+		return nil, err
+	}
+	for {
+		lock, err := s.acquireSessionLockForPaths(paths)
+		if !errors.Is(err, ErrLockConflict) {
+			return lock, err
 		}
+		timer := time.NewTimer(100 * time.Millisecond)
+		select {
+		case <-ctx.Done():
+			if !timer.Stop() {
+				<-timer.C
+			}
+			return nil, fmt.Errorf("wait for session lock %q: %w", paths.LockPath, ctx.Err())
+		case <-timer.C:
+		}
+	}
+}
+
+func (s *LocalStore) acquireSessionLockForPaths(paths SessionPaths) (*LockHandle, error) {
+	f, err := fileops.OpenFileConfined(paths.LockPath, os.O_CREATE|os.O_RDWR, fileops.WorkspaceFileMode)
+	if err != nil {
 		return nil, fmt.Errorf("acquire lock %q: %w", paths.LockPath, err)
 	}
+	if err := acquireHeldFileLockFn(f); err != nil {
+		closeErr := f.Close()
+		if errors.Is(err, errHeldLockConflict) {
+			return nil, fmt.Errorf("%w: %s", ErrLockConflict, paths.LockPath)
+		}
+		if closeErr != nil {
+			return nil, errors.Join(fmt.Errorf("acquire lock %q: hold: %w", paths.LockPath, err), closeErr)
+		}
+		return nil, fmt.Errorf("acquire lock %q: hold: %w", paths.LockPath, err)
+	}
+	failed := true
+	defer func() {
+		if failed {
+			_ = releaseHeldFileLockFn(f)
+			_ = f.Close()
+		}
+	}()
 	if err := f.Chmod(fileops.WorkspaceFileMode); err != nil {
-		_ = f.Close()
-		_ = os.Remove(paths.LockPath)
 		return nil, fmt.Errorf("acquire lock %q: set permissions: %w", paths.LockPath, err)
 	}
+	if err := f.Truncate(0); err != nil {
+		return nil, fmt.Errorf("acquire lock %q: clear metadata: %w", paths.LockPath, err)
+	}
+	if _, err := f.Seek(0, io.SeekStart); err != nil {
+		return nil, fmt.Errorf("acquire lock %q: seek metadata: %w", paths.LockPath, err)
+	}
 
 	metadata := "pid=" + strconv.Itoa(os.Getpid()) + "\nacquired_at=" + time.Now().UTC().Format(time.RFC3339Nano) + "\n"
 	if _, err := io.WriteString(f, metadata); err != nil {
-		_ = f.Close()
-		_ = os.Remove(paths.LockPath)
 		return nil, fmt.Errorf("acquire lock %q: write metadata: %w", paths.LockPath, err)
 	}
 	if err := f.Sync(); err != nil {
-		_ = f.Close()
-		_ = os.Remove(paths.LockPath)
 		return nil, fmt.Errorf("acquire lock %q: sync: %w", paths.LockPath, err)
 	}
 
+	failed = false
 	return &LockHandle{path: paths.LockPath, file: f}, nil
 }
 
@@ -213,23 +256,21 @@ func (s *LocalStore) ReleaseSessionLock(lock *LockHandle) error {
 		return nil
 	}
 
-	var closeErr error
-	if lock.file != nil {
-		closeErr = lock.file.Close()
-		lock.file = nil
+	if lock.file == nil {
+		return nil
 	}
-
-	removeErr := os.Remove(lock.path)
-	if errors.Is(removeErr, os.ErrNotExist) {
-		removeErr = nil
+	releaseErr := releaseHeldFileLockFn(lock.file)
+	closeErr := closeHeldLockFile(lock.file)
+	lock.file = nil
+	if releaseErr != nil && closeErr != nil {
+		return fmt.Errorf("release lock %q: %w", lock.path, errors.Join(releaseErr, closeErr))
+	}
+	if releaseErr != nil {
+		return fmt.Errorf("release lock %q: unlock: %w", lock.path, releaseErr)
 	}
-
 	if closeErr != nil {
 		return fmt.Errorf("release lock %q: close: %w", lock.path, closeErr)
 	}
-	if removeErr != nil {
-		return fmt.Errorf("release lock %q: remove: %w", lock.path, removeErr)
-	}
 	return nil
 }
 

internal/artifacts/local_test.go

@@ -1,11 +1,14 @@
 package artifacts
 
 import (
+	"context"
 	"errors"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"strings"
 	"testing"
+	"time"
 )
 
 func TestEnsureLayoutCreatesExpectedDirectories(t *testing.T) {
@@ -93,8 +96,148 @@ func TestLockAcquireRelease(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Exists() error = %v", err)
 	}
-	if exists {
-		t.Fatalf("expected lock file %q to be removed", lock.path)
+	if !exists {
+		t.Fatalf("expected lock metadata file %q to remain", lock.path)
+	}
+	secondLock, err := store.AcquireSessionLockFor("sample-campaign", "session-1")
+	if err != nil {
+		t.Fatalf("AcquireSessionLockFor() after release error = %v", err)
+	}
+	if err := store.ReleaseSessionLock(secondLock); err != nil {
+		t.Fatalf("ReleaseSessionLock(second lock) error = %v", err)
+	}
+}
+
+func TestLockWaitHonorsCancellation(t *testing.T) {
+	store := NewLocalStore(t.TempDir())
+	lock, err := store.AcquireSessionLockFor("sample-campaign", "session-1")
+	if err != nil {
+		t.Fatalf("AcquireSessionLockFor() error = %v", err)
+	}
+	defer func() { _ = store.ReleaseSessionLock(lock) }()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, err = store.AcquireSessionLockForContext(ctx, "sample-campaign", "session-1")
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("AcquireSessionLockForContext() error = %v, want context cancellation", err)
+	}
+}
+
+func TestLockWaitsUntilRelease(t *testing.T) {
+	store := NewLocalStore(t.TempDir())
+	first, err := store.AcquireSessionLockFor("sample-campaign", "session-1")
+	if err != nil {
+		t.Fatalf("AcquireSessionLockFor() error = %v", err)
+	}
+	acquired := make(chan *LockHandle, 1)
+	errs := make(chan error, 1)
+	go func() {
+		lock, err := store.AcquireSessionLockForContext(context.Background(), "sample-campaign", "session-1")
+		if err != nil {
+			errs <- err
+			return
+		}
+		acquired <- lock
+	}()
+
+	select {
+	case err := <-errs:
+		t.Fatalf("AcquireSessionLockForContext() error = %v", err)
+	case lock := <-acquired:
+		_ = store.ReleaseSessionLock(lock)
+		t.Fatal("AcquireSessionLockForContext() acquired before the held lock was released")
+	case <-time.After(150 * time.Millisecond):
+	}
+	if err := store.ReleaseSessionLock(first); err != nil {
+		t.Fatalf("ReleaseSessionLock(first) error = %v", err)
+	}
+	select {
+	case err := <-errs:
+		t.Fatalf("AcquireSessionLockForContext() error = %v", err)
+	case lock := <-acquired:
+		if err := store.ReleaseSessionLock(lock); err != nil {
+			t.Fatalf("ReleaseSessionLock(waiting lock) error = %v", err)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("AcquireSessionLockForContext() did not acquire after release")
+	}
+}
+
+func TestLockRecoversAfterLockHolderDies(t *testing.T) {
+	if os.Getenv("NARRATIO_LOCK_PROCESS_HELPER") == "1" {
+		store := NewLocalStore(os.Getenv("NARRATIO_LOCK_PROCESS_ROOT"))
+		lock, err := store.AcquireSessionLockFor("sample-campaign", "session-1")
+		if err != nil {
+			os.Exit(2)
+		}
+		if err := os.WriteFile(os.Getenv("NARRATIO_LOCK_PROCESS_READY"), []byte(lock.path), 0o600); err != nil {
+			os.Exit(3)
+		}
+		select {}
+	}
+
+	root := t.TempDir()
+	ready := filepath.Join(t.TempDir(), "ready")
+	cmd := exec.Command(os.Args[0], "-test.run=^TestLockRecoversAfterLockHolderDies$")
+	cmd.Env = append(os.Environ(),
+		"NARRATIO_LOCK_PROCESS_HELPER=1",
+		"NARRATIO_LOCK_PROCESS_ROOT="+root,
+		"NARRATIO_LOCK_PROCESS_READY="+ready,
+	)
+	if err := cmd.Start(); err != nil {
+		t.Fatalf("start lock-holder process: %v", err)
+	}
+	defer func() {
+		if cmd.Process != nil {
+			_ = cmd.Process.Kill()
+		}
+		_ = cmd.Wait()
+	}()
+	deadline := time.Now().Add(2 * time.Second)
+	for {
+		if _, err := os.Stat(ready); err == nil {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatal("lock-holder process did not signal readiness")
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	store := NewLocalStore(root)
+	if _, err := store.AcquireSessionLockFor("sample-campaign", "session-1"); !errors.Is(err, ErrLockConflict) {
+		t.Fatalf("AcquireSessionLockFor() error = %v, want lock conflict", err)
+	}
+	if err := cmd.Process.Kill(); err != nil {
+		t.Fatalf("kill lock-holder process: %v", err)
+	}
+	if err := cmd.Wait(); err == nil {
+		t.Fatal("lock-holder process exited without being killed")
+	}
+	cmd.Process = nil
+
+	lock, err := store.AcquireSessionLockFor("sample-campaign", "session-1")
+	if err != nil {
+		t.Fatalf("AcquireSessionLockFor() after holder death error = %v", err)
+	}
+	if err := store.ReleaseSessionLock(lock); err != nil {
+		t.Fatalf("ReleaseSessionLock() error = %v", err)
+	}
+}
+
+func TestReleaseSessionLockReportsUnlockFailure(t *testing.T) {
+	store := NewLocalStore(t.TempDir())
+	lock, err := store.AcquireSessionLockFor("sample-campaign", "session-1")
+	if err != nil {
+		t.Fatalf("AcquireSessionLockFor() error = %v", err)
+	}
+
+	original := releaseHeldFileLockFn
+	releaseHeldFileLockFn = func(*os.File) error { return errors.New("unlock failed") }
+	t.Cleanup(func() { releaseHeldFileLockFn = original })
+	if err := store.ReleaseSessionLock(lock); err == nil || !strings.Contains(err.Error(), "unlock failed") {
+		t.Fatalf("ReleaseSessionLock() error = %v, want unlock failure", err)
 	}
 }
 

internal/artifacts/lock_common.go

@@ -0,0 +1,18 @@
+package artifacts
+
+import (
+	"errors"
+	"os"
+)
+
+var errHeldLockConflict = errors.New("held lock conflict")
+
+var acquireHeldFileLockFn = acquireHeldFileLock
+var releaseHeldFileLockFn = releaseHeldFileLock
+
+func closeHeldLockFile(file *os.File) error {
+	if file == nil {
+		return nil
+	}
+	return file.Close()
+}

internal/artifacts/lock_unix.go

@@ -0,0 +1,22 @@
+//go:build linux || darwin
+
+package artifacts
+
+import (
+	"errors"
+	"os"
+
+	"golang.org/x/sys/unix"
+)
+
+func acquireHeldFileLock(file *os.File) error {
+	err := unix.Flock(int(file.Fd()), unix.LOCK_EX|unix.LOCK_NB)
+	if errors.Is(err, unix.EWOULDBLOCK) || errors.Is(err, unix.EAGAIN) {
+		return errHeldLockConflict
+	}
+	return err
+}
+
+func releaseHeldFileLock(file *os.File) error {
+	return unix.Flock(int(file.Fd()), unix.LOCK_UN)
+}

internal/artifacts/lock_unsupported.go

@@ -0,0 +1,15 @@
+//go:build !linux && !darwin && !windows
+
+package artifacts
+
+import (
+	"fmt"
+	"os"
+	"runtime"
+)
+
+func acquireHeldFileLock(_ *os.File) error {
+	return fmt.Errorf("held file locks are unsupported on %s", runtime.GOOS)
+}
+
+func releaseHeldFileLock(_ *os.File) error { return nil }

internal/artifacts/lock_windows.go

@@ -0,0 +1,29 @@
+//go:build windows
+
+package artifacts
+
+import (
+	"errors"
+	"os"
+
+	"golang.org/x/sys/windows"
+)
+
+func acquireHeldFileLock(file *os.File) error {
+	err := windows.LockFileEx(
+		windows.Handle(file.Fd()),
+		windows.LOCKFILE_EXCLUSIVE_LOCK|windows.LOCKFILE_FAIL_IMMEDIATELY,
+		0,
+		1,
+		0,
+		&windows.Overlapped{},
+	)
+	if errors.Is(err, windows.ERROR_LOCK_VIOLATION) {
+		return errHeldLockConflict
+	}
+	return err
+}
+
+func releaseHeldFileLock(file *os.File) error {
+	return windows.UnlockFileEx(windows.Handle(file.Fd()), 0, 1, 0, &windows.Overlapped{})
+}

internal/artifacts/store.go

@@ -1,6 +1,7 @@
 package artifacts
 
 import (
+	"context"
 	"os"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/artifactmodel"
@@ -30,5 +31,6 @@ type Store interface {
 	WriteFileAtomic(path string, data []byte, perm os.FileMode) error
 	Checksum(path string) (string, error)
 	AcquireSessionLockFor(campaign, sessionID string) (*LockHandle, error)
+	AcquireSessionLockForContext(ctx context.Context, campaign, sessionID string) (*LockHandle, error)
 	ReleaseSessionLock(lock *LockHandle) error
 }

internal/fileops/cleanup.go

@@ -0,0 +1,165 @@
+package fileops
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// RemoveAllUnderRoot removes target and its contents only after opening root and
+// every target ancestor without following symbolic links. target must name a
+// proper descendant of root. Symlinks are rejected rather than followed or
+// removed so a failed cleanup never silently changes its scope.
+func RemoveAllUnderRoot(rootPath, target string) error {
+	root, targetName, err := openConfinedCleanupTarget(rootPath, target)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = root.Close() }()
+	return removeConfinedEntry(root, targetName)
+}
+
+func openConfinedCleanupTarget(rootPath, target string) (*os.Root, string, error) {
+	if strings.TrimSpace(rootPath) == "" {
+		return nil, "", fmt.Errorf("cleanup root is required")
+	}
+	if strings.TrimSpace(target) == "" {
+		return nil, "", fmt.Errorf("cleanup target is required")
+	}
+	rootAbs, err := filepath.Abs(rootPath)
+	if err != nil {
+		return nil, "", fmt.Errorf("resolve cleanup root: %w", err)
+	}
+	targetAbs, err := filepath.Abs(target)
+	if err != nil {
+		return nil, "", fmt.Errorf("resolve cleanup target: %w", err)
+	}
+	relative, err := filepath.Rel(rootAbs, targetAbs)
+	if err != nil {
+		return nil, "", fmt.Errorf("resolve cleanup target below root: %w", err)
+	}
+	if relative == "." || relative == ".." || strings.HasPrefix(relative, ".."+string(filepath.Separator)) {
+		return nil, "", fmt.Errorf("cleanup target %q must be below root %q", targetAbs, rootAbs)
+	}
+	parts, err := relativePathParts(relative)
+	if err != nil {
+		return nil, "", err
+	}
+	root, err := openConfinedDirectory(rootAbs)
+	if err != nil {
+		return nil, "", err
+	}
+	for _, part := range parts[:len(parts)-1] {
+		child, err := openConfinedChild(root, part, false, 0)
+		if err != nil {
+			_ = root.Close()
+			return nil, "", err
+		}
+		_ = root.Close()
+		root = child
+	}
+	return root, parts[len(parts)-1], nil
+}
+
+func openConfinedDirectory(path string) (*os.Root, error) {
+	abs, err := filepath.Abs(path)
+	if err != nil {
+		return nil, fmt.Errorf("resolve directory: %w", err)
+	}
+	parts, err := absolutePathParts(abs)
+	if err != nil {
+		return nil, err
+	}
+	rootPath := filesystemRoot(abs)
+	root, err := os.OpenRoot(rootPath)
+	if err != nil {
+		return nil, fmt.Errorf("open filesystem root %q: %w", rootPath, err)
+	}
+	for _, part := range parts {
+		child, err := openConfinedChild(root, part, false, 0)
+		if err != nil {
+			_ = root.Close()
+			return nil, err
+		}
+		_ = root.Close()
+		root = child
+	}
+	return root, nil
+}
+
+func relativePathParts(path string) ([]string, error) {
+	parts := strings.FieldsFunc(path, func(r rune) bool { return r == filepath.Separator || r == '/' || r == '\\' })
+	if len(parts) == 0 {
+		return nil, fmt.Errorf("cleanup target is required")
+	}
+	for _, part := range parts {
+		if part == "" || part == "." || part == ".." {
+			return nil, fmt.Errorf("unsafe cleanup path component %q", part)
+		}
+	}
+	return parts, nil
+}
+
+func removeConfinedEntry(parent *os.Root, name string) error {
+	info, err := parent.Lstat(name)
+	if errors.Is(err, os.ErrNotExist) {
+		return nil
+	}
+	if err != nil {
+		return fmt.Errorf("inspect cleanup entry %q: %w", name, err)
+	}
+	if info.Mode()&os.ModeSymlink != 0 {
+		return fmt.Errorf("refusing to delete symlink path %q", name)
+	}
+	if !info.IsDir() {
+		if err := parent.Remove(name); err != nil {
+			return fmt.Errorf("remove cleanup entry %q: %w", name, err)
+		}
+		return nil
+	}
+
+	child, err := openConfinedChild(parent, name, false, 0)
+	if err != nil {
+		return err
+	}
+	err = removeConfinedChildren(child)
+	closeErr := child.Close()
+	if err != nil {
+		if closeErr != nil {
+			return errors.Join(err, closeErr)
+		}
+		return err
+	}
+	if closeErr != nil {
+		return fmt.Errorf("close cleanup directory %q: %w", name, closeErr)
+	}
+	if err := parent.Remove(name); err != nil {
+		return fmt.Errorf("remove cleanup directory %q: %w", name, err)
+	}
+	return nil
+}
+
+func removeConfinedChildren(root *os.Root) error {
+	directory, err := root.Open(".")
+	if err != nil {
+		return fmt.Errorf("open cleanup directory: %w", err)
+	}
+	entries, readErr := directory.ReadDir(-1)
+	closeErr := directory.Close()
+	if readErr != nil {
+		return fmt.Errorf("read cleanup directory: %w", readErr)
+	}
+	if closeErr != nil {
+		return fmt.Errorf("close cleanup directory: %w", closeErr)
+	}
+	sort.Slice(entries, func(i, j int) bool { return entries[i].Name() < entries[j].Name() })
+	for _, entry := range entries {
+		if err := removeConfinedEntry(root, entry.Name()); err != nil {
+			return err
+		}
+	}
+	return nil
+}

internal/fileops/cleanup_test.go

@@ -0,0 +1,79 @@
+package fileops
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestRemoveAllUnderRootRemovesNestedTreeIdempotently(t *testing.T) {
+	root := t.TempDir()
+	target := filepath.Join(root, "runs", "run-1")
+	mustWriteFile(t, filepath.Join(target, "nested", "result.txt"), []byte("result"), 0o640)
+
+	if err := RemoveAllUnderRoot(root, target); err != nil {
+		t.Fatalf("RemoveAllUnderRoot() error = %v", err)
+	}
+	if _, err := os.Lstat(target); !os.IsNotExist(err) {
+		t.Fatalf("Lstat(%q) error = %v, want not exist", target, err)
+	}
+	if err := RemoveAllUnderRoot(root, target); err != nil {
+		t.Fatalf("second RemoveAllUnderRoot() error = %v", err)
+	}
+}
+
+func TestRemoveAllUnderRootRejectsUnsafeTargets(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	target := filepath.Join(root, "runs", "run-1")
+	mustWriteFile(t, filepath.Join(target, "result.txt"), []byte("result"), 0o640)
+	sentinel := filepath.Join(outside, "sentinel.txt")
+	mustWriteFile(t, sentinel, []byte("outside"), 0o640)
+
+	if err := RemoveAllUnderRoot(root, root); err == nil {
+		t.Fatal("RemoveAllUnderRoot(root, root) error = nil, want root rejection")
+	}
+	if err := RemoveAllUnderRoot(root, filepath.Join(outside, "target")); err == nil {
+		t.Fatal("RemoveAllUnderRoot(outside) error = nil, want outside-root rejection")
+	}
+	if err := os.Symlink(outside, filepath.Join(root, "runs")); err == nil {
+		t.Fatal("Symlink() error = nil, want collision because runs already exists")
+	}
+	if err := os.RemoveAll(filepath.Join(root, "runs")); err != nil {
+		t.Fatalf("RemoveAll(runs) error = %v", err)
+	}
+	if err := os.Symlink(outside, filepath.Join(root, "runs")); err != nil {
+		t.Fatalf("Symlink() error = %v", err)
+	}
+	if err := RemoveAllUnderRoot(root, target); err == nil {
+		t.Fatal("RemoveAllUnderRoot(symlinked ancestor) error = nil, want rejection")
+	}
+	data, err := os.ReadFile(sentinel)
+	if err != nil {
+		t.Fatalf("ReadFile(sentinel) error = %v", err)
+	}
+	if string(data) != "outside" {
+		t.Fatalf("sentinel content = %q, want outside", data)
+	}
+}
+
+func TestRemoveAllUnderRootRejectsSymlinkInTree(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	target := filepath.Join(root, "runs", "run-1")
+	if err := os.MkdirAll(target, 0o750); err != nil {
+		t.Fatalf("MkdirAll(target) error = %v", err)
+	}
+	sentinel := filepath.Join(outside, "sentinel.txt")
+	mustWriteFile(t, sentinel, []byte("outside"), 0o640)
+	if err := os.Symlink(outside, filepath.Join(target, "link")); err != nil {
+		t.Fatalf("Symlink() error = %v", err)
+	}
+
+	if err := RemoveAllUnderRoot(root, target); err == nil {
+		t.Fatal("RemoveAllUnderRoot() error = nil, want symlink rejection")
+	}
+	if _, err := os.Stat(sentinel); err != nil {
+		t.Fatalf("outside sentinel was changed: %v", err)
+	}
+}

internal/fileops/confined.go

@@ -183,6 +183,39 @@ func syncOpenedDirectory(parent *os.Root) error {
 	return syncDirectoryFile(directory, parent.Name())
 }
 
+// OpenFileConfined opens a file after verifying its parent hierarchy without
+// following symbolic links. Existing symbolic-link leaves are rejected.
+func OpenFileConfined(path string, flags int, mode os.FileMode) (*os.File, error) {
+	parent, name, err := openConfinedParent(path, false, 0)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = parent.Close() }()
+	if info, err := parent.Lstat(name); err == nil && info.Mode()&os.ModeSymlink != 0 {
+		return nil, fmt.Errorf("destination file %q is a symbolic link", name)
+	} else if err != nil && !errors.Is(err, os.ErrNotExist) {
+		return nil, fmt.Errorf("inspect destination file %q: %w", name, err)
+	}
+	file, err := parent.OpenFile(name, flags, mode)
+	if err != nil {
+		return nil, err
+	}
+	opened, err := file.Stat()
+	if err != nil {
+		_ = file.Close()
+		return nil, fmt.Errorf("inspect opened destination file %q: %w", name, err)
+	}
+	current, err := parent.Lstat(name)
+	if err != nil || current.Mode()&os.ModeSymlink != 0 || !os.SameFile(opened, current) {
+		_ = file.Close()
+		if err != nil {
+			return nil, fmt.Errorf("reinspect destination file %q: %w", name, err)
+		}
+		return nil, fmt.Errorf("destination file %q changed while being opened", name)
+	}
+	return file, nil
+}
+
 // DownloadedTempFile is a completed, destination-confined temporary file. It
 // keeps its parent directory open until the caller installs or cleans it up.
 type DownloadedTempFile struct {

internal/fileops/directory.go

@@ -1,6 +1,8 @@
 package fileops
 
 import (
+	"crypto/rand"
+	"encoding/hex"
 	"errors"
 	"fmt"
 	"io"
@@ -21,14 +23,257 @@ func PromoteDirectory(src, dst string) error {
 	if err := checkAtomicDirectoryPromotionSupport(); err != nil {
 		return err
 	}
-	parent, _, err := openConfinedParent(dst, false, 0)
+	parent, destinationName, err := openConfinedParent(dst, false, 0)
 	if err != nil {
 		return fmt.Errorf("open destination parent: %w", err)
 	}
-	if err := parent.Close(); err != nil {
-		return fmt.Errorf("close destination parent: %w", err)
+	defer func() { _ = parent.Close() }()
+	return promoteDirectoryConfined(src, dst, parent, destinationName, sourceTraversalHooks{})
+}
+
+func promoteDirectoryConfined(src, dst string, parent *os.Root, destinationName string, hooks sourceTraversalHooks) (resultErr error) {
+	if strings.TrimSpace(src) == "" || strings.TrimSpace(dst) == "" {
+		return fmt.Errorf("source and destination directory paths are required")
 	}
-	return promoteDirectory(src, dst, renameDirectoryNoReplace)
+	sourceInfo, err := os.Lstat(src)
+	if err != nil {
+		return fmt.Errorf("inspect source directory: %w", err)
+	}
+	if sourceInfo.Mode()&os.ModeSymlink != 0 || !sourceInfo.IsDir() {
+		return fmt.Errorf("source path %q is not a directory", src)
+	}
+	if _, err := parent.Lstat(destinationName); err == nil {
+		return fmt.Errorf("destination path %q already exists", dst)
+	} else if !errors.Is(err, os.ErrNotExist) {
+		return fmt.Errorf("inspect destination path: %w", err)
+	}
+	insideSource, err := pathWithin(src, dst)
+	if err != nil {
+		return err
+	}
+	if insideSource {
+		return fmt.Errorf("destination path %q must not be inside source directory %q", dst, src)
+	}
+
+	temporary, temporaryName, err := createSiblingTempDirectory(parent, destinationName)
+	if err != nil {
+		return err
+	}
+	removeTemporary := true
+	defer func() {
+		var closeErr error
+		if temporary != nil {
+			closeErr = temporary.Close()
+		}
+		if removeTemporary {
+			removeErr := removeConfinedEntry(parent, temporaryName)
+			if removeErr != nil {
+				resultErr = errors.Join(resultErr, fmt.Errorf("remove temporary destination directory: %w", removeErr))
+			}
+		}
+		if closeErr != nil {
+			resultErr = errors.Join(resultErr, fmt.Errorf("close temporary destination directory: %w", closeErr))
+		}
+	}()
+
+	sourceRoot, err := openVerifiedSourceRoot(src, sourceInfo, hooks)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = sourceRoot.Close() }()
+	if err := copyRegularTreeToRoot(sourceRoot, src, temporary, hooks); err != nil {
+		return err
+	}
+	if err := setOpenedDirectoryMode(temporary, WorkspaceDirectoryMode); err != nil {
+		return fmt.Errorf("set temporary root permissions: %w", err)
+	}
+	if err := syncOpenedDirectory(temporary); err != nil {
+		return fmt.Errorf("sync temporary root: %w", err)
+	}
+	if err := temporary.Close(); err != nil {
+		return fmt.Errorf("close temporary root: %w", err)
+	}
+	temporary = nil
+
+	directory, err := parent.Open(".")
+	if err != nil {
+		return fmt.Errorf("open destination parent for promotion: %w", err)
+	}
+	renameErr := renameDirectoryNoReplaceAt(directory, temporaryName, destinationName)
+	closeErr := directory.Close()
+	if renameErr != nil {
+		return fmt.Errorf("install promoted directory: %w", renameErr)
+	}
+	if closeErr != nil {
+		return fmt.Errorf("close destination parent after promotion: %w", closeErr)
+	}
+	removeTemporary = false
+	if err := syncOpenedDirectory(parent); err != nil {
+		return fmt.Errorf("sync destination parent: %w", err)
+	}
+	return nil
+}
+
+func createSiblingTempDirectory(parent *os.Root, base string) (*os.Root, string, error) {
+	for attempt := 0; attempt < 100; attempt++ {
+		var randomBytes [16]byte
+		if _, err := rand.Read(randomBytes[:]); err != nil {
+			return nil, "", fmt.Errorf("generate temporary directory name: %w", err)
+		}
+		name := "." + base + ".tmp-" + hex.EncodeToString(randomBytes[:])
+		if err := parent.Mkdir(name, WorkspaceDirectoryMode.Perm()); err != nil {
+			if errors.Is(err, os.ErrExist) {
+				continue
+			}
+			return nil, "", fmt.Errorf("create temporary destination directory: %w", err)
+		}
+		directory, err := openConfinedChild(parent, name, false, 0)
+		if err != nil {
+			_ = parent.Remove(name)
+			return nil, "", err
+		}
+		return directory, name, nil
+	}
+	return nil, "", fmt.Errorf("create unique temporary destination directory")
+}
+
+func copyRegularTreeToRoot(src *os.Root, sourcePath string, dst *os.Root, hooks sourceTraversalHooks) error {
+	directory, err := src.Open(".")
+	if err != nil {
+		return fmt.Errorf("open source directory %q for traversal: %w", sourcePath, err)
+	}
+	entries, readErr := directory.ReadDir(-1)
+	closeErr := directory.Close()
+	if readErr != nil {
+		return fmt.Errorf("read source directory %q: %w", sourcePath, readErr)
+	}
+	if closeErr != nil {
+		return fmt.Errorf("close source directory %q: %w", sourcePath, closeErr)
+	}
+	sort.Slice(entries, func(i, j int) bool { return entries[i].Name() < entries[j].Name() })
+	for _, entry := range entries {
+		entryPath := filepath.Join(sourcePath, entry.Name())
+		info, err := src.Lstat(entry.Name())
+		if err != nil {
+			return fmt.Errorf("inspect source entry %q: %w", entryPath, err)
+		}
+		if hooks.afterEntryInspect != nil {
+			hooks.afterEntryInspect(entryPath)
+		}
+		switch {
+		case info.Mode().IsRegular():
+			if err := copyRegularFileToRoot(src, dst, entry.Name(), entryPath, info); err != nil {
+				return err
+			}
+		case info.IsDir():
+			if err := copyRegularDirectoryToRoot(src, dst, entry.Name(), entryPath, info, hooks); err != nil {
+				return err
+			}
+		default:
+			return fmt.Errorf("source entry %q has unsupported file type %s", entryPath, info.Mode().Type())
+		}
+	}
+	return nil
+}
+
+func copyRegularDirectoryToRoot(sourceParent, destinationParent *os.Root, name, sourcePath string, inspected os.FileInfo, hooks sourceTraversalHooks) error {
+	source, err := openVerifiedChildDirectory(sourceParent, name, sourcePath, inspected)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = source.Close() }()
+	if err := destinationParent.Mkdir(name, WorkspaceDirectoryMode.Perm()); err != nil {
+		return fmt.Errorf("create destination directory %q: %w", sourcePath, err)
+	}
+	destination, err := openConfinedChild(destinationParent, name, false, 0)
+	if err != nil {
+		return err
+	}
+	err = copyRegularTreeToRoot(source, sourcePath, destination, hooks)
+	if err == nil {
+		err = setOpenedDirectoryMode(destination, WorkspaceDirectoryMode)
+	}
+	if err == nil {
+		err = syncOpenedDirectory(destination)
+	}
+	closeErr := destination.Close()
+	if err != nil {
+		return err
+	}
+	if closeErr != nil {
+		return fmt.Errorf("close destination directory %q: %w", sourcePath, closeErr)
+	}
+	return nil
+}
+
+func copyRegularFileToRoot(sourceRoot, destinationRoot *os.Root, name, sourcePath string, inspected os.FileInfo) error {
+	in, err := openVerifiedSourceFile(sourceRoot, name, sourcePath, inspected)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = in.Close() }()
+	out, err := destinationRoot.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_EXCL, WorkspaceFileMode)
+	if err != nil {
+		return fmt.Errorf("create destination file %q: %w", sourcePath, err)
+	}
+	if _, err := io.Copy(out, in); err != nil {
+		_ = out.Close()
+		return fmt.Errorf("copy source file %q: %w", sourcePath, err)
+	}
+	if err := out.Chmod(WorkspaceFileMode); err != nil {
+		_ = out.Close()
+		return fmt.Errorf("set destination file permissions %q: %w", sourcePath, err)
+	}
+	if err := out.Sync(); err != nil {
+		_ = out.Close()
+		return fmt.Errorf("sync destination file %q: %w", sourcePath, err)
+	}
+	if err := out.Close(); err != nil {
+		return fmt.Errorf("close destination file %q: %w", sourcePath, err)
+	}
+	return nil
+}
+
+func openVerifiedChildDirectory(parent *os.Root, name, sourcePath string, inspected os.FileInfo) (*os.Root, error) {
+	child, err := parent.OpenRoot(name)
+	if err != nil {
+		return nil, fmt.Errorf("open source directory %q: %w", sourcePath, err)
+	}
+	opened, err := child.Stat(".")
+	if err != nil {
+		_ = child.Close()
+		return nil, fmt.Errorf("inspect opened source directory %q: %w", sourcePath, err)
+	}
+	current, err := parent.Lstat(name)
+	if err != nil || current.Mode()&os.ModeSymlink != 0 || !current.IsDir() || !os.SameFile(opened, current) {
+		_ = child.Close()
+		if err != nil {
+			return nil, fmt.Errorf("reinspect source directory %q: %w", sourcePath, err)
+		}
+		return nil, fmt.Errorf("source directory %q changed while being copied", sourcePath)
+	}
+	return child, nil
+}
+
+func openVerifiedSourceFile(root *os.Root, name, sourcePath string, inspected os.FileInfo) (*os.File, error) {
+	in, err := root.Open(name)
+	if err != nil {
+		return nil, fmt.Errorf("open source file %q: %w", sourcePath, err)
+	}
+	opened, err := in.Stat()
+	if err != nil {
+		_ = in.Close()
+		return nil, fmt.Errorf("inspect opened source file %q: %w", sourcePath, err)
+	}
+	current, err := root.Lstat(name)
+	if err != nil || current.Mode()&os.ModeSymlink != 0 || !current.Mode().IsRegular() || !os.SameFile(opened, current) {
+		_ = in.Close()
+		if err != nil {
+			return nil, fmt.Errorf("reinspect source file %q: %w", sourcePath, err)
+		}
+		return nil, fmt.Errorf("source file %q changed while being copied", sourcePath)
+	}
+	return in, nil
 }
 
 func promoteDirectory(src, dst string, install func(string, string) error) error {
@@ -87,7 +332,7 @@ func promoteDirectoryWithHooks(
 	removeTemporary := true
 	defer func() {
 		if removeTemporary {
-			_ = os.RemoveAll(temporary)
+			_ = RemoveAllUnderRoot(destinationParent, temporary)
 		}
 	}()
 

internal/fileops/rename_noreplace_darwin.go

@@ -2,10 +2,18 @@
 
 package fileops
 
-import "golang.org/x/sys/unix"
+import (
+	"os"
+
+	"golang.org/x/sys/unix"
+)
 
 func checkAtomicDirectoryPromotionSupport() error { return nil }
 
 func renameDirectoryNoReplace(src, dst string) error {
 	return unix.RenamexNp(src, dst, unix.RENAME_EXCL)
 }
+
+func renameDirectoryNoReplaceAt(parent *os.File, src, dst string) error {
+	return unix.RenameatxNp(int(parent.Fd()), src, int(parent.Fd()), dst, unix.RENAME_EXCL)
+}

internal/fileops/rename_noreplace_linux.go

@@ -2,10 +2,18 @@
 
 package fileops
 
-import "golang.org/x/sys/unix"
+import (
+	"os"
+
+	"golang.org/x/sys/unix"
+)
 
 func checkAtomicDirectoryPromotionSupport() error { return nil }
 
 func renameDirectoryNoReplace(src, dst string) error {
 	return unix.Renameat2(unix.AT_FDCWD, src, unix.AT_FDCWD, dst, unix.RENAME_NOREPLACE)
 }
+
+func renameDirectoryNoReplaceAt(parent *os.File, src, dst string) error {
+	return unix.Renameat2(int(parent.Fd()), src, int(parent.Fd()), dst, unix.RENAME_NOREPLACE)
+}

internal/fileops/rename_noreplace_other.go

@@ -4,6 +4,7 @@ package fileops
 
 import (
 	"fmt"
+	"os"
 	"runtime"
 )
 
@@ -14,3 +15,7 @@ func checkAtomicDirectoryPromotionSupport() error {
 func renameDirectoryNoReplace(_, _ string) error {
 	return checkAtomicDirectoryPromotionSupport()
 }
+
+func renameDirectoryNoReplaceAt(_ *os.File, _, _ string) error {
+	return checkAtomicDirectoryPromotionSupport()
+}

internal/fileops/rename_noreplace_windows.go

@@ -2,18 +2,17 @@
 
 package fileops
 
-import "golang.org/x/sys/windows"
+import (
+	"fmt"
+	"os"
+)
 
-func checkAtomicDirectoryPromotionSupport() error { return nil }
-
-func renameDirectoryNoReplace(src, dst string) error {
-	from, err := windows.UTF16PtrFromString(src)
-	if err != nil {
-		return err
-	}
-	to, err := windows.UTF16PtrFromString(dst)
-	if err != nil {
-		return err
-	}
-	return windows.MoveFileEx(from, to, 0)
+func checkAtomicDirectoryPromotionSupport() error {
+	return fmt.Errorf("%w on windows", ErrAtomicDirectoryPromotionUnsupported)
+}
+
+func renameDirectoryNoReplace(src, dst string) error { return checkAtomicDirectoryPromotionSupport() }
+
+func renameDirectoryNoReplaceAt(parent *os.File, src, dst string) error {
+	return checkAtomicDirectoryPromotionSupport()
 }

internal/stage/prepare.go

@@ -515,7 +515,7 @@ func clearManagedPreviousState(paths artifacts.SessionPaths) error {
 	if filepath.Base(previousDir) != config.PathPreviousDirSegment {
 		return fmt.Errorf("refusing to clear non-previous path %q", previousDir)
 	}
-	if err := os.RemoveAll(previousDir); err != nil {
+	if err := fileops.RemoveAllUnderRoot(sessionRoot, previousDir); err != nil {
 		return err
 	}
 	return fileops.EnsureWorkspaceDirectory(previousDir)