diff --git a/bgworker.go b/bgworker.go
new file mode 100644
index 0000000000..9b4b3cf0d0
--- /dev/null
+++ b/bgworker.go
@@ -0,0 +1,471 @@
+package frankenphp
+
+// #include "frankenphp.h"
+import "C"
+import (
+	"errors"
+	"fmt"
+	"log/slog"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+	"unsafe"
+)
+
+const (
+	// defaultMaxBackgroundWorkers is the default safety cap for catch-all
+	// background workers when the user doesn't set max_threads. Caps the
+	// number of distinct lazy-started instances from a single catch-all.
+	defaultMaxBackgroundWorkers = 16
+
+	// defaultEnsureTimeout is the default deadline applied when ensure() is
+	// called without an explicit timeout.
+	defaultEnsureTimeout = 30 * time.Second
+)
+
+// backgroundWorkerExtras holds bg-only lifecycle state.
+type backgroundWorkerExtras struct {
+	// ready is shared by named workers and a catch-all's eager pool;
+	// lazy-spawned catch-all instances each get their own slot in
+	// catchAllNames.
+	ready *backgroundWorkerState
+
+	// catchAllNames != nil marks this *worker as a scope's catch-all
+	// template. Lazy-spawned threads register here, up to catchAllCap.
+	catchAllCap   int
+	catchAllMu    sync.Mutex
+	catchAllNames map[string]*backgroundWorkerState
+
+	// lazyMu/lazyStarted gate the first thread spawn for a num=0 named
+	// bg worker. Unused for eager (num > 0) or catch-all templates.
+	lazyMu      sync.Mutex
+	lazyStarted bool
+}
+
+// backgroundWorkerState is the per-instance readiness signal ensure()
+// blocks on. ready closes once the worker calls
+// frankenphp_get_worker_handle(); aborted closes on max_consecutive_failures
+// before that.
+type backgroundWorkerState struct {
+	ready     chan struct{}
+	readyOnce sync.Once
+
+	aborted   chan struct{}
+	abortOnce sync.Once
+	abortErr  error
+
+	// bootFailure carries the most recent pre-readiness crash so a
+	// timing-out ensure() can report it.
+	bootFailure atomic.Pointer[bootFailureInfo]
+}
+
+// bootFailureInfo is the boot-phase crash metadata surfaced by ensure().
+type bootFailureInfo struct {
+	entrypoint   string
+	exitStatus   int
+	failureCount int
+	// TODO(sidekicks): capture PG(last_error_message) once the C-side
+	// helper lands in the set_vars/get_vars step.
+	phpError string
+}
+
+func newBackgroundWorkerState() *backgroundWorkerState {
+	return &backgroundWorkerState{
+		ready:   make(chan struct{}),
+		aborted: make(chan struct{}),
+	}
+}
+
+// markReady fires on the first frankenphp_get_worker_handle() call after
+// each (re)boot. Idempotent: the channel only closes once.
+func (r *backgroundWorkerState) markReady() {
+	r.readyOnce.Do(func() { close(r.ready) })
+}
+
+// abort unblocks ensure() waiters when the boot sequence is abandoned
+// (max_consecutive_failures hit before readiness). Idempotent.
+func (r *backgroundWorkerState) abort(err error) {
+	r.abortOnce.Do(func() {
+		r.abortErr = err
+		close(r.aborted)
+	})
+}
+
+// Scope isolates background workers between php_server blocks; the
+// zero value is the global/embed scope. Obtain values via NextScope.
+type Scope uint64
+
+var scopeCounter atomic.Uint64
+
+// NextScope returns a fresh scope value. Each php_server block should
+// call this once during provisioning.
+func NextScope() Scope {
+	return Scope(scopeCounter.Add(1))
+}
+
+// scopeLabels maps Scope -> human-readable label registered by the
+// embedder (e.g. the Caddy module).
+var scopeLabels sync.Map
+
+// SetScopeLabel attaches a human-readable label to a scope; the bg-worker
+// metric emitter renders it as e.g. server="api.example.com" instead of
+// an opaque numeric id. Empty labels are ignored.
+func SetScopeLabel(s Scope, label string) {
+	if label == "" {
+		return
+	}
+	scopeLabels.Store(s, label)
+}
+
+// scopeLabelOrID returns the label registered for s, or the numeric id
+// when none is set (including the zero/global scope), so callers always
+// get a non-empty value.
+func scopeLabelOrID(s Scope) string {
+	if label, ok := lookupScopeLabel(s); ok {
+		return label
+	}
+	return strconv.FormatUint(uint64(s), 10)
+}
+
+// lookupScopeLabel reports whether a label has been registered for s,
+// returning ("", false) when none has. Distinguishes "unset" from
+// "explicitly empty" without the numeric fallback.
+func lookupScopeLabel(s Scope) (string, bool) {
+	v, ok := scopeLabels.Load(s)
+	if !ok {
+		return "", false
+	}
+	return v.(string), true
+}
+
+// bgWorkerMetricName formats the metric label for a background worker:
+// "m#<scopeLabel>:<runtimeName>". scopeLabel is empty when the scope
+// has no registered label (embed/global, or before the embedder calls
+// SetScopeLabel). The "m#" prefix mirrors the m# convention used for
+// module workers; the colon keeps the format uniform so a single regex
+// (m#([^:]*):(.+)) parses both labelled and unlabelled forms.
+func bgWorkerMetricName(scope Scope, runtimeName string) string {
+	label, _ := lookupScopeLabel(scope)
+	return "m#" + label + ":" + runtimeName
+}
+
+// backgroundLookups maps scope -> lookup. Scope 0 is the global/embed scope.
+var backgroundLookups map[Scope]*backgroundWorkerLookup
+
+// backgroundWorkerLookup resolves a user-facing worker name to its *worker;
+// catchAll is the fallback when byName misses.
+type backgroundWorkerLookup struct {
+	byName   map[string]*worker
+	catchAll *worker
+}
+
+func newBackgroundWorkerLookup() *backgroundWorkerLookup {
+	return &backgroundWorkerLookup{
+		byName: make(map[string]*worker),
+	}
+}
+
+// resolve returns the worker for the given name, falling back to catchAll.
+func (l *backgroundWorkerLookup) resolve(name string) *worker {
+	if w, ok := l.byName[name]; ok {
+		return w
+	}
+	return l.catchAll
+}
+
+// isCatchAllName reports whether (name, fileName) designates a catch-all
+// (no user-supplied name; newWorker defaults the name to the absolute
+// file path). m# is stripped because module workers carry the prefix.
+func isCatchAllName(name, fileName string) bool {
+	phpName := strings.TrimPrefix(name, "m#")
+	return phpName == "" || phpName == fileName
+}
+
+func isCatchAllByName(w *worker) bool {
+	return isCatchAllName(w.name, w.fileName)
+}
+
+// buildBackgroundWorkerLookups maps each declared bg worker into its scope's
+// lookup. Per-scope name collisions are caught here because bg workers
+// intentionally skip the global workersByName map (so two scopes can share
+// a user-facing name).
+func buildBackgroundWorkerLookups(workers []*worker, opts []workerOpt) (map[Scope]*backgroundWorkerLookup, error) {
+	lookups := make(map[Scope]*backgroundWorkerLookup)
+
+	for i, o := range opts {
+		if !o.isBackgroundWorker {
+			continue
+		}
+
+		scope := o.scope
+		lookup, ok := lookups[scope]
+		if !ok {
+			lookup = newBackgroundWorkerLookup()
+			lookups[scope] = lookup
+		}
+
+		w := workers[i]
+		w.scope = scope
+
+		if isCatchAllByName(w) {
+			if lookup.catchAll != nil {
+				return nil, fmt.Errorf("duplicate catch-all background worker in the same scope")
+			}
+			w.bg.catchAllCap = defaultMaxBackgroundWorkers
+			if o.maxThreads > 0 {
+				w.bg.catchAllCap = o.maxThreads
+			}
+			w.bg.catchAllNames = make(map[string]*backgroundWorkerState)
+			lookup.catchAll = w
+		} else {
+			phpName := strings.TrimPrefix(w.name, "m#")
+			if _, exists := lookup.byName[phpName]; exists {
+				return nil, fmt.Errorf("duplicate background worker name %q in the same scope", phpName)
+			}
+			lookup.byName[phpName] = w
+		}
+	}
+
+	if len(lookups) == 0 {
+		return nil, nil
+	}
+	return lookups, nil
+}
+
+// reserveBackgroundWorkerThreads resolves max_threads defaults and
+// returns the thread budget to add to the pool. Mutates opt.workers
+// in place and pre-registers totalWorkers so a bg-only deployment
+// has the metric initialised.
+func reserveBackgroundWorkerThreads(opt *opt) int {
+	reserved := 0
+	for i, w := range opt.workers {
+		if !w.isBackgroundWorker {
+			continue
+		}
+		isCatchAll := isCatchAllName(w.name, w.fileName)
+
+		if w.maxThreads == 0 {
+			switch {
+			case isCatchAll:
+				// Lazy cap default for any catch-all.
+				opt.workers[i].maxThreads = defaultMaxBackgroundWorkers
+			case w.num == 0:
+				// Single-thread budget for a lazy named worker.
+				opt.workers[i].maxThreads = 1
+			}
+		}
+
+		var extra int
+		if isCatchAll {
+			// eager pool + lazy cap (independent budgets)
+			extra = w.num + opt.workers[i].maxThreads
+		} else {
+			extra = w.num
+			if opt.workers[i].maxThreads > extra {
+				extra = opt.workers[i].maxThreads
+			}
+		}
+		if extra < 1 {
+			extra = 1
+		}
+		reserved += extra
+		metrics.TotalWorkers(bgWorkerMetricName(w.scope, w.name), extra)
+	}
+	return reserved
+}
+
+// getLookup returns the background-worker lookup for the calling thread,
+// resolving the scope via worker handler -> request context -> global. A
+// scope with no declared workers falls through to scope 0 so embed-mode
+// workers stay reachable; declared scopes stay strictly isolated.
+func getLookup(thread *phpThread) *backgroundWorkerLookup {
+	if backgroundLookups == nil {
+		return nil
+	}
+	var scope Scope
+	if thread != nil {
+		if w := thread.handler.scopedWorker(); w != nil {
+			scope = w.scope
+		} else if fc, ok := fromContext(thread.context()); ok {
+			scope = fc.scope
+		}
+	}
+	if scope != 0 {
+		if l := backgroundLookups[scope]; l != nil {
+			return l
+		}
+	}
+	return backgroundLookups[0]
+}
+
+// ensureBackgroundWorker lazy-starts the named worker if needed and blocks
+// until it reaches readiness, aborts (max_consecutive_failures during boot),
+// or times out. Safe to call concurrently.
+func ensureBackgroundWorker(thread *phpThread, bgWorkerName string, timeout time.Duration) error {
+	if bgWorkerName == "" {
+		return fmt.Errorf("background worker name must not be empty")
+	}
+	lookup := getLookup(thread)
+	if lookup == nil {
+		return fmt.Errorf("no background worker configured")
+	}
+
+	// byName is keyed by the user-facing (m#-stripped) name.
+	if w, ok := lookup.byName[bgWorkerName]; ok {
+		r, err := lazyStartNamedWorker(w)
+		if err != nil {
+			return err
+		}
+		return waitForBackgroundWorkerReady(bgWorkerName, r, timeout)
+	}
+
+	catchAll := lookup.catchAll
+	if catchAll == nil {
+		return fmt.Errorf("no background worker configured for name %q", bgWorkerName)
+	}
+
+	// Reject so behavior doesn't silently split-brain across the eager
+	// pool and a lazy-spawned instance. m#-strip matches
+	// buildBackgroundWorkerLookups: module catch-alls carry the prefix,
+	// bgWorkerName from PHP never does.
+	if bgWorkerName == strings.TrimPrefix(catchAll.name, "m#") {
+		return fmt.Errorf("cannot ensure() against %q: it matches the catch-all's own name; use a distinct user-facing name", bgWorkerName)
+	}
+
+	// Hold catchAllMu across thread reservation + entry publication so a
+	// failed allocation can't leave a phantom registration visible to
+	// concurrent callers.
+	bg := catchAll.bg
+	bg.catchAllMu.Lock()
+
+	if r, ok := bg.catchAllNames[bgWorkerName]; ok {
+		bg.catchAllMu.Unlock()
+		return waitForBackgroundWorkerReady(bgWorkerName, r, timeout)
+	}
+
+	if bg.catchAllCap > 0 && len(bg.catchAllNames) >= bg.catchAllCap {
+		bg.catchAllMu.Unlock()
+		return fmt.Errorf("cannot start background worker %q: limit of %d reached (increase max threads or declare it as a named worker)", bgWorkerName, bg.catchAllCap)
+	}
+
+	r := newBackgroundWorkerState()
+	bg.catchAllNames[bgWorkerName] = r
+	bg.catchAllMu.Unlock()
+
+	if _, err := addBackgroundWorkerThread(catchAll, bgWorkerName, r); err != nil {
+		// Wake any concurrent waiter that picked up r from catchAllNames
+		// between our publish and this rollback so they see the start
+		// failure instead of timing out.
+		r.abort(err)
+		bg.catchAllMu.Lock()
+		delete(bg.catchAllNames, bgWorkerName)
+		bg.catchAllMu.Unlock()
+		return fmt.Errorf("cannot start background worker %q: %w (increase max threads)", bgWorkerName, err)
+	}
+
+	if globalLogger.Enabled(globalCtx, slog.LevelInfo) {
+		globalLogger.LogAttrs(globalCtx, slog.LevelInfo, "background worker started",
+			slog.String("name", bgWorkerName))
+	}
+
+	return waitForBackgroundWorkerReady(bgWorkerName, r, timeout)
+}
+
+// lazyStartNamedWorker returns the readiness slot the caller should
+// wait on. For num=0 workers it spawns the first thread under
+// bg.lazyMu (idempotent); the snapshot captured under the lock stays
+// consistent with any concurrent invalidateBackgroundEntry.
+func lazyStartNamedWorker(w *worker) (*backgroundWorkerState, error) {
+	if w.num > 0 {
+		return w.bg.ready, nil
+	}
+	w.bg.lazyMu.Lock()
+	defer w.bg.lazyMu.Unlock()
+	if w.bg.lazyStarted {
+		return w.bg.ready, nil
+	}
+	r := w.bg.ready
+	if _, err := addBackgroundWorkerThread(w, w.name, r); err != nil {
+		return nil, fmt.Errorf("cannot start background worker %q: %w (increase max threads)", w.name, err)
+	}
+	w.bg.lazyStarted = true
+	return r, nil
+}
+
+// waitForBackgroundWorkerReady blocks until the worker reaches readiness,
+// aborts, or the timeout elapses. A nil state degrades to ready-immediately
+// to avoid a deadlock for workers declared without an allocated slot.
+func waitForBackgroundWorkerReady(name string, r *backgroundWorkerState, timeout time.Duration) error {
+	if r == nil {
+		return nil
+	}
+	if timeout <= 0 {
+		timeout = defaultEnsureTimeout
+	}
+	timer := time.NewTimer(timeout)
+	defer timer.Stop()
+	select {
+	case <-r.ready:
+		return nil
+	case <-r.aborted:
+		return fmt.Errorf("background worker %q failed to start: %w", name, r.abortErr)
+	case <-timer.C:
+		return formatEnsureTimeoutError(name, r, timeout)
+	}
+}
+
+func formatEnsureTimeoutError(name string, r *backgroundWorkerState, timeout time.Duration) error {
+	if bf := r.bootFailure.Load(); bf != nil {
+		msg := fmt.Sprintf("background worker %q did not become ready within %s; last attempt %d failed (exit status %d, entrypoint %s)",
+			name, timeout, bf.failureCount, bf.exitStatus, bf.entrypoint)
+		if bf.phpError != "" {
+			msg += ": " + bf.phpError
+		}
+		return errors.New(msg)
+	}
+	return fmt.Errorf("background worker %q did not call frankenphp_get_worker_handle() within %s", name, timeout)
+}
+
+// go_frankenphp_ensure_background_worker lazy-starts each named bg worker
+// (the C side has validated names are non-empty and unique) and blocks
+// until each signals readiness, aborts, or timeoutMs (ms; <=0 = default)
+// elapses.
+//
+//export go_frankenphp_ensure_background_worker
+func go_frankenphp_ensure_background_worker(threadIndex C.uintptr_t, names **C.char, nameLens *C.size_t, nameCount C.int, timeoutMs C.int64_t) *C.char {
+	thread := phpThreads[threadIndex]
+	n := int(nameCount)
+	if n <= 0 {
+		return nil
+	}
+	timeout := time.Duration(int64(timeoutMs)) * time.Millisecond
+	nameSlice := unsafe.Slice(names, n)
+	nameLenSlice := unsafe.Slice(nameLens, n)
+	for i := 0; i < n; i++ {
+		goName := C.GoStringN(nameSlice[i], C.int(nameLenSlice[i]))
+		if err := ensureBackgroundWorker(thread, goName, timeout); err != nil {
+			return C.CString(err.Error())
+		}
+	}
+	return nil
+}
+
+// go_frankenphp_worker_ready closes the per-thread readiness channel on
+// the first frankenphp_get_worker_handle() call. Idempotent.
+//
+//export go_frankenphp_worker_ready
+func go_frankenphp_worker_ready(threadIndex C.uintptr_t) {
+	thread := phpThreads[threadIndex]
+	if thread == nil {
+		return
+	}
+	handler, ok := thread.handler.(*backgroundWorkerThread)
+	if !ok || handler == nil {
+		return
+	}
+	if r := handler.backgroundReady; r != nil {
+		r.markReady()
+	}
+}
diff --git a/bgworker_test.go b/bgworker_test.go
new file mode 100644
index 0000000000..5ef6ec6e42
--- /dev/null
+++ b/bgworker_test.go
@@ -0,0 +1,86 @@
+package frankenphp_test
+
+import (
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/dunglas/frankenphp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestBackgroundWorkerLifecycle boots a background worker that touches a
+// sentinel file then parks on the stop pipe. It proves the bg worker runs
+// (sentinel appears) and that Shutdown returns within a reasonable time.
+func TestBackgroundWorkerLifecycle(t *testing.T) {
+	tmp := t.TempDir()
+	sentinel := filepath.Join(tmp, "bg-lifecycle.sentinel")
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("bg-lifecycle", "testdata/bgworker/basic.php", 1,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL": sentinel}),
+		),
+		frankenphp.WithNumThreads(2),
+	))
+	// Note: this test asserts on Shutdown timing, so it manages Shutdown
+	// itself instead of using setupFrankenPHP's t.Cleanup hook.
+
+	requireFileEventually(t, sentinel, "background worker did not touch sentinel")
+
+	done := make(chan struct{})
+	go func() {
+		frankenphp.Shutdown()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+	case <-time.After(10 * time.Second):
+		t.Fatalf("Shutdown did not return within 10s")
+	}
+}
+
+// TestBackgroundWorkerCrashRestarts boots a worker that exit(1)s on its
+// first run and touches a "restarted" sentinel on its second run. The
+// sentinel proves the crash-restart loop fired.
+func TestBackgroundWorkerCrashRestarts(t *testing.T) {
+	tmp := t.TempDir()
+	crashMarker := filepath.Join(tmp, "bg-crash.marker")
+	restarted := filepath.Join(tmp, "bg-crash.restarted")
+
+	setupFrankenPHP(t,
+		frankenphp.WithWorkers("bg-crash", "testdata/bgworker/crash.php", 1,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerEnv(map[string]string{
+				"BG_CRASH_MARKER":       crashMarker,
+				"BG_RESTARTED_SENTINEL": restarted,
+			}),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	requireFileEventually(t, restarted, "background worker did not restart after crash")
+}
+
+// TestBackgroundWorkerWithoutHTTP confirms that a request to a script
+// unrelated to the bg worker still works: the bg worker doesn't intercept
+// HTTP traffic.
+func TestBackgroundWorkerWithoutHTTP(t *testing.T) {
+	tmp := t.TempDir()
+	sentinel := filepath.Join(tmp, "bg-nohttp.sentinel")
+
+	testDataDir := setupFrankenPHP(t,
+		frankenphp.WithWorkers("bg-nohttp", "testdata/bgworker/basic.php", 1,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL": sentinel}),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	requireFileEventually(t, sentinel, "background worker did not touch sentinel")
+
+	body := serveBody(t, testDataDir, "index.php")
+	assert.NotEmpty(t, body, "expected non-empty body from index.php")
+}
diff --git a/bgworkerbatch_test.go b/bgworkerbatch_test.go
new file mode 100644
index 0000000000..12c5b734cd
--- /dev/null
+++ b/bgworkerbatch_test.go
@@ -0,0 +1,107 @@
+package frankenphp_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/dunglas/frankenphp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestEnsureBackgroundWorkerBatch declares a single catch-all bg worker
+// and ensures three distinct names from a single ensure() call. Each
+// catch-all instance touches a per-name sentinel; the test asserts that
+// all three appear, proving the array form started one worker per name.
+func TestEnsureBackgroundWorkerBatch(t *testing.T) {
+	tmp := t.TempDir()
+	testDataDir := setupFrankenPHP(t,
+		frankenphp.WithWorkers("", "testdata/bgworker/named.php", 0,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerMaxThreads(8),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		frankenphp.WithNumThreads(8),
+	)
+
+	body := serveBody(t, testDataDir, "bgworker/batch-ensure.php")
+	assert.Contains(t, body, "ok", "batch ensure script should echo ok, got: %q", body)
+
+	for _, name := range []string{"batch-a", "batch-b", "batch-c"} {
+		requireFileEventually(t, filepath.Join(tmp, name),
+			"catch-all instance %q should have written its sentinel", name)
+	}
+}
+
+// TestEnsureBackgroundWorkerBatchEmpty exercises the C-side validation
+// that an empty array raises a ValueError before any worker is started.
+// The fixture catches the throwable and echoes its class.
+func TestEnsureBackgroundWorkerBatchEmpty(t *testing.T) {
+	testDataDir := setupFrankenPHP(t,
+		frankenphp.WithWorkers("", "testdata/bgworker/named.php", 0,
+			frankenphp.WithWorkerBackground(),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	body := serveBody(t, testDataDir, "bgworker/batch-errors.php?mode=empty")
+	assert.Contains(t, body, "ValueError", "empty array should raise ValueError, got: %q", body)
+	assert.Contains(t, body, "must not be empty")
+}
+
+// TestEnsureBackgroundWorkerBatchNonString verifies a non-string element
+// raises a TypeError (PHP's standard for argument-type mismatches inside
+// our parsed array).
+func TestEnsureBackgroundWorkerBatchNonString(t *testing.T) {
+	testDataDir := setupFrankenPHP(t,
+		frankenphp.WithWorkers("", "testdata/bgworker/named.php", 0,
+			frankenphp.WithWorkerBackground(),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	body := serveBody(t, testDataDir, "bgworker/batch-errors.php?mode=nonstring")
+	assert.Contains(t, body, "TypeError", "non-string element should raise TypeError, got: %q", body)
+}
+
+// TestEnsureBackgroundWorkerBatchDuplicate verifies that duplicate names
+// in the same batch are rejected as a ValueError, matching the e17577e
+// reference behavior (no silent dedup).
+func TestEnsureBackgroundWorkerBatchDuplicate(t *testing.T) {
+	testDataDir := setupFrankenPHP(t,
+		frankenphp.WithWorkers("", "testdata/bgworker/named.php", 0,
+			frankenphp.WithWorkerBackground(),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	body := serveBody(t, testDataDir, "bgworker/batch-errors.php?mode=duplicate")
+	assert.Contains(t, body, "ValueError", "duplicate name should raise ValueError, got: %q", body)
+	assert.Contains(t, body, "duplicate")
+}
+
+// TestBackgroundWorkerBgFlag asserts that a bg worker script sees
+// $_SERVER['FRANKENPHP_WORKER_BACKGROUND'] === true. The fixture writes
+// var_export() of the value to a sentinel so the test can read the exact
+// PHP-level representation.
+func TestBackgroundWorkerBgFlag(t *testing.T) {
+	tmp := t.TempDir()
+	sentinel := filepath.Join(tmp, "bg-flag.sentinel")
+
+	setupFrankenPHP(t,
+		frankenphp.WithWorkers("bg-flag", "testdata/bgworker/bg-flag.php", 1,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL": sentinel}),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	requireFileEventually(t, sentinel,
+		"bg worker should have written the FRANKENPHP_WORKER_BACKGROUND sentinel")
+
+	contents, err := os.ReadFile(sentinel)
+	require.NoError(t, err)
+	assert.Equal(t, "true", string(contents),
+		"$_SERVER['FRANKENPHP_WORKER_BACKGROUND'] should be the bool true")
+}
diff --git a/bgworkerensure_test.go b/bgworkerensure_test.go
new file mode 100644
index 0000000000..478e219c9f
--- /dev/null
+++ b/bgworkerensure_test.go
@@ -0,0 +1,224 @@
+package frankenphp
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestEnsureBackgroundWorkerNamedLazy declares a num=0 named worker, then
+// calls ensure() to lazy-start it. The fixture writes a sentinel named
+// after FRANKENPHP_WORKER so we can confirm the right instance ran.
+func TestEnsureBackgroundWorkerNamedLazy(t *testing.T) {
+	tmp := t.TempDir()
+	setupBgWorker(t,
+		WithWorkers("bg-lazy", "testdata/bgworker/named.php", 0,
+			WithWorkerBackground(),
+			WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		WithNumThreads(2),
+	)
+
+	// num=0 means no eager start: the sentinel should not exist yet.
+	require.NoFileExists(t, filepath.Join(tmp, "bg-lazy"), "lazy worker should not have started yet")
+
+	require.NoError(t, ensureBackgroundWorker(nil, "bg-lazy", 5*time.Second))
+	requireSentinelEventually(t, filepath.Join(tmp, "bg-lazy"),
+		"ensure() should have lazy-started the named bg worker")
+}
+
+// TestEnsureBackgroundWorkerCatchAll declares a single catch-all (no name)
+// and invokes ensure() with two distinct names. Each name should spawn an
+// independent instance from the same entrypoint and write its own sentinel.
+func TestEnsureBackgroundWorkerCatchAll(t *testing.T) {
+	tmp := t.TempDir()
+	setupBgWorker(t,
+		// Name-less bg worker = catch-all.
+		WithWorkers("", "testdata/bgworker/named.php", 0,
+			WithWorkerBackground(),
+			WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		WithNumThreads(4),
+	)
+
+	for _, name := range []string{"job-a", "job-b"} {
+		require.NoError(t, ensureBackgroundWorker(nil, name, 5*time.Second), "ensure(%s)", name)
+	}
+
+	for _, name := range []string{"job-a", "job-b"} {
+		requireSentinelEventually(t, filepath.Join(tmp, name),
+			"catch-all instance %q should have written its sentinel", name)
+	}
+}
+
+// TestEnsureBackgroundWorkerCatchAllCap exercises max_threads on the
+// catch-all: third distinct name beyond the cap should error.
+func TestEnsureBackgroundWorkerCatchAllCap(t *testing.T) {
+	tmp := t.TempDir()
+	setupBgWorker(t,
+		WithWorkers("", "testdata/bgworker/named.php", 0,
+			WithWorkerBackground(),
+			WithWorkerMaxThreads(2),
+			WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		WithNumThreads(4),
+	)
+
+	require.NoError(t, ensureBackgroundWorker(nil, "cap-a", 5*time.Second))
+	require.NoError(t, ensureBackgroundWorker(nil, "cap-b", 5*time.Second))
+
+	require.ErrorContains(t,
+		ensureBackgroundWorker(nil, "cap-c", 5*time.Second),
+		"limit of 2 reached",
+		"third ensure must hit the catch-all cap")
+}
+
+// TestEnsureBackgroundWorkerUndeclared confirms ensure() on an undeclared
+// name with no catch-all returns the configuration error.
+func TestEnsureBackgroundWorkerUndeclared(t *testing.T) {
+	setupBgWorker(t,
+		WithWorkers("bg-known", "testdata/bgworker/named.php", 0,
+			WithWorkerBackground(),
+		),
+		WithNumThreads(2),
+	)
+
+	require.ErrorContains(t,
+		ensureBackgroundWorker(nil, "other-name", 5*time.Second),
+		"no background worker configured for name")
+}
+
+// TestEnsureBackgroundWorkerCatchAllSelfIdentityRejected verifies
+// ensure() rejects the catch-all's own filepath uniformly across
+// num=0 and num=1.
+func TestEnsureBackgroundWorkerCatchAllSelfIdentityRejected(t *testing.T) {
+	cwd, err := os.Getwd()
+	require.NoError(t, err)
+	// The catch-all's user-facing name is its absolute file path
+	// (set by newWorker when the declaration leaves name empty).
+	absPath := filepath.Join(cwd, "testdata/bgworker/named.php")
+
+	for _, tc := range []struct {
+		label string
+		num   int
+	}{
+		{"lazy num=0", 0},
+		{"eager num=1", 1},
+	} {
+		t.Run(tc.label, func(t *testing.T) {
+			setupBgWorker(t,
+				WithWorkers("", "testdata/bgworker/named.php", tc.num,
+					WithWorkerBackground(),
+				),
+				WithNumThreads(2),
+			)
+
+			err := ensureBackgroundWorker(nil, absPath, 1*time.Second)
+			require.Error(t, err, "ensure() with the catch-all's file path must be rejected")
+			// Echoes the rejected input so a PHP caller can see what
+			// they passed; "catch-all's own name" surfaces the cause.
+			assert.Contains(t, err.Error(), absPath, "error must echo the rejected input")
+			assert.Contains(t, err.Error(), "catch-all's own name", "error must explain why the input was rejected")
+		})
+	}
+}
+
+// TestEnsureBackgroundWorkerConcurrent confirms the doc claim that ensure()
+// is safe to call concurrently: 16 goroutines hitting the same lazy-named
+// declaration produce exactly one spawned thread. Without serialising the
+// lazy-start gate (bgLazyStartMu), the second caller could observe the
+// flag before the first caller has completed thread reservation, leaving
+// the worker in an inconsistent state.
+func TestEnsureBackgroundWorkerConcurrent(t *testing.T) {
+	setupBgWorker(t,
+		WithWorkers("bg-concurrent", "testdata/bgworker/named.php", 0,
+			WithWorkerBackground(),
+		),
+		WithNumThreads(8),
+	)
+
+	const goroutines = 16
+	var wg sync.WaitGroup
+	wg.Add(goroutines)
+	errs := make([]error, goroutines)
+	start := make(chan struct{})
+	for i := 0; i < goroutines; i++ {
+		go func(idx int) {
+			defer wg.Done()
+			<-start
+			errs[idx] = ensureBackgroundWorker(nil, "bg-concurrent", 5*time.Second)
+		}(i)
+	}
+	close(start)
+	wg.Wait()
+
+	for i, err := range errs {
+		require.NoError(t, err, "goroutine %d", i)
+	}
+
+	// The lazy-named declaration should resolve to its single *worker,
+	// and exactly one thread should have been spawned by the lazy-start
+	// path despite the 16 concurrent ensure() callers.
+	lookup := backgroundLookups[0]
+	require.NotNil(t, lookup)
+	w := lookup.byName["bg-concurrent"]
+	require.NotNil(t, w)
+	assert.Equal(t, 1, w.countThreads(), "exactly one worker thread expected")
+}
+
+// TestEnsureBackgroundWorkerTimeout proves ensure() blocks until either
+// the worker hits its readiness boundary (frankenphp_get_worker_handle())
+// or the timeout expires. The fixture sleep()s without ever calling the
+// readiness function, so the second branch must fire.
+func TestEnsureBackgroundWorkerTimeout(t *testing.T) {
+	setupBgWorker(t,
+		WithWorkers("bg-no-handle", "testdata/bgworker/no-handle.php", 0,
+			WithWorkerBackground(),
+		),
+		WithNumThreads(2),
+	)
+
+	start := time.Now()
+	err := ensureBackgroundWorker(nil, "bg-no-handle", 1*time.Second)
+	deadline := start.Add(1 * time.Second)
+
+	require.ErrorContains(t, err,
+		"did not call frankenphp_get_worker_handle()",
+		"ensure() must time out at the readiness boundary")
+	// Lower bound: timer must actually have run; allow a little slop for
+	// timer scheduling.
+	assert.GreaterOrEqual(t, time.Since(start), 900*time.Millisecond, "ensure() must wait the full timeout")
+	// Upper bound: ensure() returned close to the deadline (didn't hang).
+	assert.WithinDuration(t, deadline, time.Now(), 4*time.Second, "ensure() must return within a small slack window after the timeout")
+}
+
+// TestEnsureBackgroundWorkerBootFailure declares a worker whose entrypoint
+// throws on its very first line. ensure() should surface the boot crash
+// metadata (entrypoint, exit status, attempt count) instead of just
+// reporting a generic timeout. We use a max_consecutive_failures cap so
+// the worker stops respawning and the abort path fires deterministically.
+func TestEnsureBackgroundWorkerBootFailure(t *testing.T) {
+	setupBgWorker(t,
+		WithWorkers("bg-boot-fail", "testdata/bgworker/boot-fail.php", 0,
+			WithWorkerBackground(),
+			WithWorkerMaxFailures(2),
+		),
+		WithNumThreads(2),
+	)
+
+	err := ensureBackgroundWorker(nil, "bg-boot-fail", 5*time.Second)
+	require.Error(t, err, "ensure() must surface the boot failure")
+	msg := err.Error()
+	// One of two paths: either the abort fired (cap reached) and the error
+	// mentions max_consecutive_failures, or the timeout fired with the
+	// bootFailureInfo attached so the message mentions exit status.
+	assert.True(t,
+		strings.Contains(msg, "exit status") || strings.Contains(msg, "max_consecutive_failures") || strings.Contains(msg, "failed to start"),
+		"ensure() error must reflect the boot crash, got: %s", msg)
+}
diff --git a/bgworkerhelpers_test.go b/bgworkerhelpers_test.go
new file mode 100644
index 0000000000..a51a0042f8
--- /dev/null
+++ b/bgworkerhelpers_test.go
@@ -0,0 +1,57 @@
+package frankenphp_test
+
+import (
+	"io"
+	"net/http/httptest"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/dunglas/frankenphp"
+	"github.com/stretchr/testify/require"
+)
+
+// requireFileEventually asserts that `path` appears on disk before the
+// deadline. Wraps require.Eventually so call sites stay short.
+func requireFileEventually(t testing.TB, path string, msgAndArgs ...any) {
+	t.Helper()
+	require.Eventually(t, func() bool {
+		_, err := os.Stat(path)
+		return err == nil
+	}, 5*time.Second, 25*time.Millisecond, msgAndArgs...)
+}
+
+// setupFrankenPHP boots FrankenPHP with the given options, registers
+// Shutdown as a t.Cleanup, and returns the absolute path to the testdata
+// directory. Saves the boilerplate every bg-worker test repeats.
+func setupFrankenPHP(t *testing.T, opts ...frankenphp.Option) (testDataDir string) {
+	t.Helper()
+	cwd, err := os.Getwd()
+	require.NoError(t, err)
+	testDataDir = cwd + "/testdata/"
+	require.NoError(t, frankenphp.Init(opts...))
+	t.Cleanup(frankenphp.Shutdown)
+	return
+}
+
+// serveBody runs `script` (relative to testDataDir, may include a query
+// string) through FrankenPHP and returns the response body. ErrRejected is
+// treated as a non-fatal outcome so worker-mode quirks don't fail tests
+// that only care about the script's stdout.
+func serveBody(t *testing.T, testDataDir, scriptAndQuery string, opts ...frankenphp.RequestOption) string {
+	t.Helper()
+	req := httptest.NewRequest("GET", "http://example.com/"+scriptAndQuery, nil)
+	reqOpts := append([]frankenphp.RequestOption{
+		frankenphp.WithRequestDocumentRoot(testDataDir, false),
+	}, opts...)
+	fr, err := frankenphp.NewRequestWithContext(req, reqOpts...)
+	require.NoError(t, err)
+
+	w := httptest.NewRecorder()
+	if err := frankenphp.ServeHTTP(w, fr); err != nil {
+		require.ErrorAs(t, err, &frankenphp.ErrRejected{})
+	}
+	body, err := io.ReadAll(w.Result().Body)
+	require.NoError(t, err)
+	return string(body)
+}
diff --git a/bgworkerinternal_test.go b/bgworkerinternal_test.go
new file mode 100644
index 0000000000..83cfdffd49
--- /dev/null
+++ b/bgworkerinternal_test.go
@@ -0,0 +1,149 @@
+package frankenphp
+
+import (
+	"path/filepath"
+	"runtime"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestBackgroundWorkerRestartForceKillsStuckThread exercises the force-kill
+// path: the fixture sleep()s without watching the stop pipe, so
+// handler.drain() cannot wake it. RestartWorkers must go through the
+// grace-period timeout and the force-kill primitive (pthread_kill on
+// Linux/FreeBSD) to finish within the budget. Skips platforms where
+// force-kill cannot interrupt a blocking syscall.
+func TestBackgroundWorkerRestartForceKillsStuckThread(t *testing.T) {
+	if runtime.GOOS != "linux" && runtime.GOOS != "freebsd" {
+		t.Skipf("force-kill cannot interrupt blocking syscalls on %s", runtime.GOOS)
+	}
+
+	prev := drainGracePeriod
+	drainGracePeriod = 2 * time.Second
+	t.Cleanup(func() { drainGracePeriod = prev })
+
+	tmp := t.TempDir()
+	sentinel := filepath.Join(tmp, "bg-stuck.sentinel")
+
+	setupBgWorker(t,
+		WithWorkers("bg-stuck", "testdata/bgworker/stuck.php", 1,
+			WithWorkerBackground(),
+			WithWorkerEnv(map[string]string{"BG_SENTINEL": sentinel}),
+		),
+		WithNumThreads(2),
+	)
+
+	// Wait until the bg worker touched the sentinel (the line right
+	// before sleep(60)) so we know it is parked in the blocking syscall
+	// when the drain fires - that's the only way to prove the
+	// force-kill code path was exercised, not the stop-pipe EOF path
+	// (the fixture doesn't open the stop pipe at all).
+	requireSentinelEventually(t, sentinel, "bg worker never entered sleep()")
+
+	start := time.Now()
+	RestartWorkers()
+	// Drain budget = grace period (2s) + slack for signal dispatch and
+	// drain completion.
+	assert.WithinDuration(t, start, time.Now(), 5*time.Second,
+		"drain must force-kill the stuck bg worker within the grace period")
+}
+
+// TestEnsureBackgroundWorkerCatchAllNumPlusLazy exercises a catch-all
+// with both an eager pool (num=1) and lazy ensures: every ensure() must
+// succeed alongside the eager thread, since num and the catch-all cap
+// reserve independent thread budgets.
+func TestEnsureBackgroundWorkerCatchAllNumPlusLazy(t *testing.T) {
+	tmp := t.TempDir()
+	setupBgWorker(t,
+		WithWorkers("", "testdata/bgworker/named.php", 1,
+			WithWorkerBackground(),
+			WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		WithNumThreads(2),
+	)
+
+	for _, name := range []string{"a", "b", "c", "d"} {
+		require.NoError(t, ensureBackgroundWorker(nil, name, 5*time.Second), "ensure(%s)", name)
+	}
+	for _, name := range []string{"a", "b", "c", "d"} {
+		requireSentinelEventually(t, filepath.Join(tmp, name),
+			"lazy catch-all instance %q should have written its sentinel", name)
+	}
+}
+
+// TestBackgroundWorkerCatchAllEagerInstance verifies that a catch-all
+// declared with num>0 actually boots and runs the script — the
+// catch-all flag must not silently disable the eager pool.
+func TestBackgroundWorkerCatchAllEagerInstance(t *testing.T) {
+	tmp := t.TempDir()
+	sentinel := filepath.Join(tmp, "eager")
+	setupBgWorker(t,
+		WithWorkers("", "testdata/bgworker/eager-catchall.php", 1,
+			WithWorkerBackground(),
+			WithWorkerEnv(map[string]string{"BG_EAGER_SENTINEL": sentinel}),
+		),
+		WithNumThreads(2),
+	)
+	requireSentinelEventually(t, sentinel,
+		"eager catch-all instance must reach readiness")
+}
+
+// TestEnsureBackgroundWorkerPostBootCrashLoopAborts verifies that a
+// worker which reaches readiness once and then keeps crashing aborts
+// ensure() callers, instead of leaving them stuck on the stale "ready"
+// signal.
+func TestEnsureBackgroundWorkerPostBootCrashLoopAborts(t *testing.T) {
+	setupBgWorker(t,
+		WithWorkers("flapper", "testdata/bgworker/readiness-then-crash.php", 0,
+			WithWorkerBackground(),
+			WithWorkerMaxFailures(2),
+		),
+		WithNumThreads(2),
+	)
+
+	// Returns once the fixture signals readiness via frankenphp_get_worker_handle().
+	require.NoError(t, ensureBackgroundWorker(nil, "flapper", 5*time.Second))
+
+	// Subsequent ensure()s must surface the failure: prior abort or a
+	// fresh thread that crashes again. Never nil.
+	require.Eventually(t, func() bool {
+		return ensureBackgroundWorker(nil, "flapper", 1*time.Second) != nil
+	}, 10*time.Second, 100*time.Millisecond,
+		"ensure() must surface post-boot crash-loop")
+}
+
+// TestEnsureBackgroundWorkerCatchAllRespawnAfterCap verifies that once
+// a catch-all instance trips the failure cap, the slot is released so
+// a retried ensure() can lazy-spawn a fresh thread under the same name.
+func TestEnsureBackgroundWorkerCatchAllRespawnAfterCap(t *testing.T) {
+	tmp := t.TempDir()
+	setupBgWorker(t,
+		WithWorkers("", "testdata/bgworker/fail-then-succeed.php", 0,
+			WithWorkerBackground(),
+			WithWorkerMaxThreads(2),
+			WithWorkerMaxFailures(2),
+			WithWorkerEnv(map[string]string{
+				"BG_MARKER_DIR": tmp,
+				// Crash boots 1..3, succeed on boot 4. The cap fires on
+				// the 3rd crash because failureCount is checked before
+				// the increment in afterScriptExecution.
+				"BG_FAIL_UNTIL": "3",
+			}),
+		),
+		WithNumThreads(3),
+	)
+
+	err := ensureBackgroundWorker(nil, "respawn", 5*time.Second)
+	require.Error(t, err, "first ensure() must hit the cap")
+
+	require.Eventually(t, func() bool {
+		return ensureBackgroundWorker(nil, "respawn", 5*time.Second) == nil
+	}, 15*time.Second, 100*time.Millisecond,
+		"retry must lazy-spawn a fresh thread after the cap")
+
+	requireSentinelEventually(t, filepath.Join(tmp, "ready"),
+		"recovered worker must reach readiness")
+}
diff --git a/bgworkerinternalhelpers_test.go b/bgworkerinternalhelpers_test.go
new file mode 100644
index 0000000000..cd028a84ba
--- /dev/null
+++ b/bgworkerinternalhelpers_test.go
@@ -0,0 +1,32 @@
+package frankenphp
+
+import (
+	"os"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// setupBgWorker boots FrankenPHP with the given options (internal-package
+// variant), registers Shutdown as a t.Cleanup, and returns the absolute
+// path to the testdata directory.
+func setupBgWorker(t *testing.T, opts ...Option) (testDataDir string) {
+	t.Helper()
+	cwd, err := os.Getwd()
+	require.NoError(t, err)
+	testDataDir = cwd + "/testdata/"
+	require.NoError(t, Init(opts...))
+	t.Cleanup(Shutdown)
+	return
+}
+
+// requireSentinelEventually asserts that `path` appears on disk before the
+// deadline. Wraps require.Eventually so call sites stay short.
+func requireSentinelEventually(t testing.TB, path string, msgAndArgs ...any) {
+	t.Helper()
+	require.Eventually(t, func() bool {
+		_, err := os.Stat(path)
+		return err == nil
+	}, 5*time.Second, 10*time.Millisecond, msgAndArgs...)
+}
diff --git a/bgworkerpool_test.go b/bgworkerpool_test.go
new file mode 100644
index 0000000000..e82127aa97
--- /dev/null
+++ b/bgworkerpool_test.go
@@ -0,0 +1,58 @@
+package frankenphp_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/dunglas/frankenphp"
+	"github.com/stretchr/testify/require"
+)
+
+// TestBackgroundWorkerPool declares a named bg worker with num=3 (pool of
+// three threads). Each thread touches a unique sentinel under
+// BG_SENTINEL_DIR via tempnam(), so the test can assert that all three
+// pool threads booted independently. Covers the lifted num>1 +
+// max_threads>1 constraints and the per-thread stop pipe.
+func TestBackgroundWorkerPool(t *testing.T) {
+	tmp := t.TempDir()
+	setupFrankenPHP(t,
+		frankenphp.WithWorkers("pool-worker", "testdata/bgworker/pool.php", 3,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerMaxThreads(3),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		frankenphp.WithNumThreads(6),
+	)
+
+	require.Eventually(t, func() bool {
+		entries, err := os.ReadDir(tmp)
+		return err == nil && len(entries) == 3
+	}, 5*time.Second, 25*time.Millisecond,
+		"expected 3 distinct pool sentinels under %s", tmp)
+}
+
+// TestBackgroundWorkerMultiEntrypoint declares two named bg workers that
+// share the same entrypoint file. Each gets its own *worker, so both Init
+// successfully (no filename-collision rejection) and both produce
+// sentinels.
+func TestBackgroundWorkerMultiEntrypoint(t *testing.T) {
+	tmp := t.TempDir()
+	setupFrankenPHP(t,
+		frankenphp.WithWorkers("shared-a", "testdata/bgworker/named.php", 1,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		frankenphp.WithWorkers("shared-b", "testdata/bgworker/named.php", 1,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		frankenphp.WithNumThreads(5),
+	)
+
+	for _, name := range []string{"shared-a", "shared-b"} {
+		requireFileEventually(t, filepath.Join(tmp, name),
+			"shared bg worker %q did not touch its sentinel", name)
+	}
+}
diff --git a/bgworkerscope_test.go b/bgworkerscope_test.go
new file mode 100644
index 0000000000..8f23822233
--- /dev/null
+++ b/bgworkerscope_test.go
@@ -0,0 +1,133 @@
+package frankenphp
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestNextScopeIsDistinct verifies the scope counter
+// hands out unique values on consecutive calls.
+func TestNextScopeIsDistinct(t *testing.T) {
+	a := NextScope()
+	b := NextScope()
+	assert.NotEqual(t, a, b, "consecutive scopes must differ")
+	assert.NotZero(t, a, "scopes must be non-zero (zero is the global scope)")
+	assert.NotZero(t, b, "scopes must be non-zero (zero is the global scope)")
+}
+
+// TestBackgroundWorkerSameNameDifferentScope declares two named bg
+// workers with the same user-facing name in distinct scopes. Both must
+// Init successfully (the global workersByName collision check must
+// recognize bg workers as scope-isolated).
+func TestBackgroundWorkerSameNameDifferentScope(t *testing.T) {
+	scopeA := NextScope()
+	scopeB := NextScope()
+
+	tmp := t.TempDir()
+
+	setupBgWorker(t,
+		WithWorkers("shared", "testdata/bgworker/named.php", 1,
+			WithWorkerBackground(),
+			WithWorkerScope(scopeA),
+			WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp + "/a"}),
+		),
+		WithWorkers("shared", "testdata/bgworker/named.php", 1,
+			WithWorkerBackground(),
+			WithWorkerScope(scopeB),
+			WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp + "/b"}),
+		),
+		WithNumThreads(4),
+	)
+
+	// Both lookups must exist and resolve "shared" to a *worker.
+	require.NotNil(t, backgroundLookups[scopeA], "scope A lookup missing")
+	require.NotNil(t, backgroundLookups[scopeB], "scope B lookup missing")
+	assert.NotNil(t, backgroundLookups[scopeA].byName["shared"], "scope A must resolve 'shared'")
+	assert.NotNil(t, backgroundLookups[scopeB].byName["shared"], "scope B must resolve 'shared'")
+	// And they must be distinct *worker instances (not the same pointer).
+	assert.NotSame(t,
+		backgroundLookups[scopeA].byName["shared"],
+		backgroundLookups[scopeB].byName["shared"],
+		"each scope must own a distinct *worker for the same name")
+}
+
+// TestBackgroundWorkerCatchAllPerScope declares a catch-all in two
+// distinct scopes and verifies that ensure() in scope A consumes a slot
+// from scope A's catch-all only, leaving scope B's catch-all untouched.
+func TestBackgroundWorkerCatchAllPerScope(t *testing.T) {
+	scopeA := NextScope()
+	scopeB := NextScope()
+
+	tmp := t.TempDir()
+	dirA := filepath.Join(tmp, "a")
+	dirB := filepath.Join(tmp, "b")
+	require.NoError(t, os.MkdirAll(dirA, 0o755))
+	require.NoError(t, os.MkdirAll(dirB, 0o755))
+
+	setupBgWorker(t,
+		WithWorkers("", "testdata/bgworker/named.php", 0,
+			WithWorkerBackground(),
+			WithWorkerScope(scopeA),
+			WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": dirA}),
+		),
+		WithWorkers("", "testdata/bgworker/named.php", 0,
+			WithWorkerBackground(),
+			WithWorkerScope(scopeB),
+			WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": dirB}),
+		),
+		WithNumThreads(4),
+	)
+
+	// Pre-conditions: each scope's catch-all is empty.
+	require.Empty(t, backgroundLookups[scopeA].catchAll.bg.catchAllNames, "scope A catch-all must start empty")
+	require.Empty(t, backgroundLookups[scopeB].catchAll.bg.catchAllNames, "scope B catch-all must start empty")
+
+	// Drive ensure() through a fake "request" context tagged to scope A.
+	// We use a request-scope tag (rather than a worker handler) because
+	// no scope-specific handler is running in the test.
+	fc := newFrankenPHPContext()
+	fc.scope = scopeA
+	ctx := context.WithValue(context.Background(), contextKey, fc)
+	thread := &phpThread{}
+	thread.handler = &fakeContextThread{ctx: ctx}
+	require.NoError(t, ensureBackgroundWorker(thread, "job-a", 5*time.Second))
+
+	// The lazy-started instance must land in scope A's catch-all only.
+	require.Eventually(t, func() bool {
+		_, ok := backgroundLookups[scopeA].catchAll.bg.catchAllNames["job-a"]
+		return ok
+	}, 2*time.Second, 10*time.Millisecond, "ensure() must populate scope A's catch-all")
+	assert.Empty(t, backgroundLookups[scopeB].catchAll.bg.catchAllNames, "scope B catch-all must remain untouched")
+
+	// All catch-all threads attach to the scope's catch-all *worker, so
+	// scope A's catch-all should have one thread (for "job-a") while
+	// scope B's catch-all should have none.
+	assert.Equal(t, 1, backgroundLookups[scopeA].catchAll.countThreads(), "scope A catch-all must host exactly one thread")
+	assert.Equal(t, 0, backgroundLookups[scopeB].catchAll.countThreads(), "scope B catch-all must host zero threads")
+
+	// Wait for the worker to write its sentinel so we know the right
+	// fixture ran (sanity check that env was inherited from scope A).
+	requireSentinelEventually(t, filepath.Join(dirA, "job-a"),
+		"scope A catch-all instance must write its sentinel under scope A's BG_SENTINEL_DIR")
+}
+
+// fakeContextThread is a threadHandler stub that lets a test drive
+// ensureBackgroundWorker via the request-context fallback path in
+// getLookup, without spinning up a real PHP thread.
+type fakeContextThread struct {
+	ctx context.Context
+}
+
+func (h *fakeContextThread) name() string                          { return "fake" }
+func (h *fakeContextThread) beforeScriptExecution() string         { return "" }
+func (h *fakeContextThread) afterScriptExecution(int)              {}
+func (h *fakeContextThread) frankenPHPContext() *frankenPHPContext { return nil }
+func (h *fakeContextThread) drain()                                {}
+func (h *fakeContextThread) context() context.Context              { return h.ctx }
+func (h *fakeContextThread) scopedWorker() *worker                 { return nil }
diff --git a/caddy/app.go b/caddy/app.go
index fbe72eb620..8283718f94 100644
--- a/caddy/app.go
+++ b/caddy/app.go
@@ -1,7 +1,6 @@
 package caddy
 
 import (
-	"context"
 	"errors"
 	"fmt"
 	"log/slog"
@@ -62,8 +61,15 @@ type FrankenPHPApp struct {
 
 	opts    []frankenphp.Option
 	metrics frankenphp.Metrics
-	ctx     context.Context
+	ctx     caddy.Context
 	logger  *slog.Logger
+
+	// scopeOwners is the per-php_server module registry used by Start
+	// to resolve a human-readable scope label (via the cascade in
+	// scopelabel.go) before frankenphp.Init starts any bg worker, so
+	// the very first metric call already carries the right prefix.
+	scopeOwnersMu sync.Mutex
+	scopeOwners   map[frankenphp.Scope]*FrankenPHPModule
 }
 
 var iniError = errors.New(`"php_ini" must be in the format: php_ini "<key>" "<value>"`)
@@ -139,6 +145,41 @@ func (f *FrankenPHPApp) addModuleWorkers(workers ...workerConfig) ([]workerConfi
 	return workers, nil
 }
 
+// registerScopeOwner records the FrankenPHPModule that allocated the
+// given scope so Start() can resolve its label before frankenphp.Init.
+func (f *FrankenPHPApp) registerScopeOwner(scope frankenphp.Scope, mod *FrankenPHPModule) {
+	f.scopeOwnersMu.Lock()
+	defer f.scopeOwnersMu.Unlock()
+	if f.scopeOwners == nil {
+		f.scopeOwners = make(map[frankenphp.Scope]*FrankenPHPModule)
+	}
+	f.scopeOwners[scope] = mod
+}
+
+// resolveScopeLabels walks the http app's servers once per registered
+// module, picks the one whose route tree contains the module, runs the
+// scopelabel.go cascade, and stores the result via SetScopeLabel. Runs
+// before frankenphp.Init so the first metric emit on every bg worker
+// already carries the right "m#<label>:<name>" prefix.
+func (f *FrankenPHPApp) resolveScopeLabels() {
+	if len(f.scopeOwners) == 0 {
+		return
+	}
+	httpApp, err := f.ctx.AppIfConfigured("http")
+	if err != nil || httpApp == nil {
+		return
+	}
+	servers := httpApp.(*caddyhttp.App).Servers
+	for scope, mod := range f.scopeOwners {
+		for _, srv := range servers {
+			if label := mod.resolveScopeLabel(srv); label != "" {
+				frankenphp.SetScopeLabel(scope, label)
+				break
+			}
+		}
+	}
+}
+
 func (f *FrankenPHPApp) Start() error {
 	repl := caddy.NewReplacer()
 
@@ -146,6 +187,8 @@ func (f *FrankenPHPApp) Start() error {
 	f.opts = append(f.opts, options...)
 	optionsMU.RUnlock()
 
+	f.resolveScopeLabels()
+
 	f.opts = append(f.opts,
 		frankenphp.WithContext(f.ctx),
 		frankenphp.WithLogger(f.logger),
@@ -167,6 +210,10 @@ func (f *FrankenPHPApp) Start() error {
 			frankenphp.WithWorkerRequestOptions(w.requestOptions...),
 		)
 
+		if w.Background {
+			w.options = append(w.options, frankenphp.WithWorkerBackground())
+		}
+
 		f.opts = append(f.opts, frankenphp.WithWorkers(w.Name, repl.ReplaceKnown(w.FileName, ""), w.Num, w.options...))
 	}
 
diff --git a/caddy/module.go b/caddy/module.go
index fe14818105..842c84d74a 100644
--- a/caddy/module.go
+++ b/caddy/module.go
@@ -51,6 +51,7 @@ type FrankenPHPModule struct {
 	preparedEnvNeedsReplacement bool
 	logger                      *slog.Logger
 	requestOptions              []frankenphp.RequestOption
+	scope                       frankenphp.Scope
 }
 
 // CaddyModule returns the Caddy module information.
@@ -78,6 +79,14 @@ func (f *FrankenPHPModule) Provision(ctx caddy.Context) error {
 
 	f.assignMercureHub(ctx)
 
+	// Each php_server block gets its own scope so workers declared with
+	// the same name in different blocks don't collide. Provision can be
+	// called more than once for the same module; only assign once.
+	if f.scope == 0 {
+		f.scope = frankenphp.NextScope()
+	}
+	fapp.registerScopeOwner(f.scope, f)
+
 	loggerOpt := frankenphp.WithRequestLogger(f.logger)
 	for i, wc := range f.Workers {
 		// make the file path absolute from the public directory
@@ -92,6 +101,7 @@ func (f *FrankenPHPModule) Provision(ctx caddy.Context) error {
 		}
 
 		wc.requestOptions = append(wc.requestOptions, loggerOpt)
+		wc.options = append(wc.options, frankenphp.WithWorkerScope(f.scope))
 		f.Workers[i] = wc
 	}
 
@@ -241,6 +251,7 @@ func (f *FrankenPHPModule) ServeHTTP(w http.ResponseWriter, r *http.Request, _ c
 			opts,
 			frankenphp.WithOriginalRequest(new(ctx.Value(caddyhttp.OriginalRequestCtxKey).(http.Request))),
 			frankenphp.WithWorkerName(workerName),
+			frankenphp.WithRequestScope(f.scope),
 		)...,
 	)
 
diff --git a/caddy/scopelabel.go b/caddy/scopelabel.go
new file mode 100644
index 0000000000..e668404782
--- /dev/null
+++ b/caddy/scopelabel.go
@@ -0,0 +1,59 @@
+package caddy
+
+import (
+	"github.com/caddyserver/caddy/v2/modules/caddyhttp"
+)
+
+// resolveScopeLabel picks a stable, human-friendly identifier for this
+// module's background-worker scope so metric/log emitters can render it
+// (e.g. server="api.example.com") instead of the opaque numeric id.
+// Cascade:
+//  1. First host of the route's host matcher.
+//  2. First listener address of the server.
+func (f *FrankenPHPModule) resolveScopeLabel(srv *caddyhttp.Server) string {
+	if h := findHostInRoutes(srv.Routes, f); h != "" {
+		return h
+	}
+	if len(srv.Listen) > 0 {
+		return srv.Listen[0]
+	}
+	return ""
+}
+
+// findHostInRoutes walks routes (recursing into Subroute handlers) to
+// locate the route that contains target, then returns the first host of
+// that route's host matcher. Returns "" if no enclosing route or no host
+// matcher is found.
+func findHostInRoutes(routes caddyhttp.RouteList, target caddyhttp.MiddlewareHandler) string {
+	for _, route := range routes {
+		if !routeContainsHandler(route, target) {
+			continue
+		}
+		for _, mset := range route.MatcherSets {
+			for _, m := range mset {
+				hp, ok := m.(*caddyhttp.MatchHost)
+				if !ok || hp == nil || len(*hp) == 0 {
+					continue
+				}
+				return (*hp)[0]
+			}
+		}
+	}
+	return ""
+}
+
+func routeContainsHandler(route caddyhttp.Route, target caddyhttp.MiddlewareHandler) bool {
+	for _, h := range route.Handlers {
+		if h == target {
+			return true
+		}
+		if sub, ok := h.(*caddyhttp.Subroute); ok {
+			for _, r := range sub.Routes {
+				if routeContainsHandler(r, target) {
+					return true
+				}
+			}
+		}
+	}
+	return false
+}
diff --git a/caddy/workerconfig.go b/caddy/workerconfig.go
index c50f0d0688..2f51618d29 100644
--- a/caddy/workerconfig.go
+++ b/caddy/workerconfig.go
@@ -41,6 +41,8 @@ type workerConfig struct {
 	MatchPath []string `json:"match_path,omitempty"`
 	// MaxConsecutiveFailures sets the maximum number of consecutive failures before panicking (defaults to 6, set to -1 to never panick)
 	MaxConsecutiveFailures int `json:"max_consecutive_failures,omitempty"`
+	// Background marks this worker as a background (non-HTTP) worker.
+	Background bool `json:"background,omitempty"`
 
 	options        []frankenphp.WorkerOption
 	requestOptions []frankenphp.RequestOption
@@ -145,8 +147,10 @@ func unmarshalWorker(d *caddyfile.Dispenser) (workerConfig, error) {
 			}
 
 			wc.MaxConsecutiveFailures = v
+		case "background":
+			wc.Background = true
 		default:
-			return wc, wrongSubDirectiveError("worker", "name, file, num, env, watch, match, max_consecutive_failures, max_threads", v)
+			return wc, wrongSubDirectiveError("worker", "name, file, num, env, watch, match, max_consecutive_failures, max_threads, background", v)
 		}
 	}
 
@@ -154,6 +158,16 @@ func unmarshalWorker(d *caddyfile.Dispenser) (workerConfig, error) {
 		return wc, d.Err(`the "file" argument must be specified`)
 	}
 
+	if wc.Background {
+		// Named bg workers: num is the pool size; max_threads currently has
+		// no effect (no auto-scaling for bg workers in this build). Catch-all
+		// bg workers: num is unused at the declaration level, max_threads
+		// caps how many distinct names can be lazy-started via ensure().
+		if len(wc.MatchPath) != 0 {
+			return wc, d.Err(`"match" is not supported for background workers`)
+		}
+	}
+
 	if frankenphp.EmbeddedAppPath != "" && filepath.IsLocal(wc.FileName) {
 		wc.FileName = filepath.Join(frankenphp.EmbeddedAppPath, wc.FileName)
 	}
diff --git a/cgi.go b/cgi.go
index d4d6a32d37..4e2542d66f 100644
--- a/cgi.go
+++ b/cgi.go
@@ -44,7 +44,7 @@ var cStringHTTPMethods = map[string]*C.char{
 //
 // TODO: handle this case https://github.com/caddyserver/caddy/issues/3718
 // Inspired by https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/reverseproxy/fastcgi/fastcgi.go
-func addKnownVariablesToServer(fc *frankenPHPContext, trackVarsArray *C.zval) {
+func addKnownVariablesToServer(thread *phpThread, fc *frankenPHPContext, trackVarsArray *C.zval) {
 	request := fc.request
 	// Separate remote IP and port; more lenient than net.SplitHostPort
 	var ip, port string
@@ -113,6 +113,21 @@ func addKnownVariablesToServer(fc *frankenPHPContext, trackVarsArray *C.zval) {
 
 	phpSelf := fc.scriptName + fc.pathInfo
 
+	// Worker identity for $_SERVER. Bg-worker threads override fc.worker
+	// because catch-all threads share the catch-all template *worker
+	// (whose name is the entrypoint path); the per-thread runtimeName is
+	// the actual ensure() argument. m# is stripped so PHP sees the user-
+	// facing name regardless of how the worker was registered.
+	var workerName string
+	var isBackgroundWorker bool
+	if bgHandler, ok := thread.handler.(*backgroundWorkerThread); ok {
+		workerName = strings.TrimPrefix(bgHandler.runtimeName, "m#")
+		isBackgroundWorker = true
+	} else if fc.worker != nil {
+		workerName = strings.TrimPrefix(fc.worker.name, "m#")
+		isBackgroundWorker = fc.worker.bg != nil
+	}
+
 	C.frankenphp_register_server_vars(trackVarsArray, C.frankenphp_server_vars{
 		// approximate total length to avoid array re-hashing:
 		// 28 CGI vars + headers + environment
@@ -156,6 +171,11 @@ func addKnownVariablesToServer(fc *frankenPHPContext, trackVarsArray *C.zval) {
 		request_scheme: rs,          // "http" or "https"
 		ssl_protocol:   sslProtocol, // values from tlsProtocol
 		https:          https,       // "on" or empty
+
+		// Worker identity (empty for non-worker requests)
+		worker_name:          toUnsafeChar(workerName),
+		worker_name_len:      C.size_t(len(workerName)),
+		is_background_worker: C._Bool(isBackgroundWorker),
 	})
 }
 
@@ -188,7 +208,7 @@ func go_register_server_variables(threadIndex C.uintptr_t, trackVarsArray *C.zva
 	fc := thread.frankenPHPContext()
 
 	if fc.request != nil {
-		addKnownVariablesToServer(fc, trackVarsArray)
+		addKnownVariablesToServer(thread, fc, trackVarsArray)
 		addHeadersToServer(thread.context(), fc.request, trackVarsArray)
 	}
 
diff --git a/context.go b/context.go
index add8eff7bd..11f7d3d2bb 100644
--- a/context.go
+++ b/context.go
@@ -38,6 +38,10 @@ type frankenPHPContext struct {
 	handlerParameters  any
 	handlerReturn      any
 
+	// scope selects the per-php_server isolation boundary used by ensure()
+	// calls made from this request. Zero is the global scope.
+	scope Scope
+
 	done      chan any
 	startedAt time.Time
 }
diff --git a/frankenphp.c b/frankenphp.c
index 5e6ecb0f37..d7fc4de0d5 100644
--- a/frankenphp.c
+++ b/frankenphp.c
@@ -16,6 +16,7 @@
 #else
 #include <php_config.h>
 #endif
+#include <main/php_streams.h>
 #include <php_ini.h>
 #include <php_main.h>
 #include <php_output.h>
@@ -91,6 +92,9 @@ HashTable *main_thread_env = NULL;
 
 __thread uintptr_t thread_index;
 __thread bool is_worker_thread = false;
+__thread bool is_background_worker = false;
+__thread int worker_stop_fds[2] = {-1, -1};
+__thread php_stream *worker_signaling_stream = NULL;
 __thread HashTable *sandboxed_env = NULL;
 
 #ifndef PHP_WIN32
@@ -203,13 +207,98 @@ void frankenphp_release_thread_for_kill(force_kill_slot slot) {
 #endif
 }
 
+static void frankenphp_worker_close_stop_fds(void);
+
 void frankenphp_update_local_thread_context(bool is_worker) {
+  /* A thread that previously ran as a bg worker can be recycled into an
+   * HTTP worker or a regular request thread; reset the bg-worker TLS so
+   * frankenphp_handle_request() and friends don't reject the caller. The
+   * cached worker_signaling_stream is already dangling here (its
+   * zend_resource was freed by php_request_shutdown's EG(regular_list)
+   * teardown), so just NULL it without dereferencing. */
+  bool was_background_worker = is_background_worker;
+
   is_worker_thread = is_worker;
+  is_background_worker = false;
+
+  if (was_background_worker) {
+    frankenphp_worker_close_stop_fds();
+    worker_signaling_stream = NULL;
+  }
 
   /* workers should keep running if the user aborts the connection */
   PG(ignore_user_abort) = is_worker ? 1 : original_user_abort_setting;
 }
 
+/* Background worker stop-pipe: anonymous pipe whose read end is exposed to
+ * the PHP script via frankenphp_get_worker_handle. When the Go side closes
+ * the write end (on drain), the read end reaches EOF so the script can
+ * return from stream_select and exit its loop. */
+static int frankenphp_worker_open_stop_pipe(void) {
+#ifdef PHP_WIN32
+  return _pipe(worker_stop_fds, 4096, _O_BINARY);
+#else
+  return pipe(worker_stop_fds);
+#endif
+}
+
+static void frankenphp_worker_close_stop_fds(void) {
+  for (int i = 0; i < 2; i++) {
+    if (worker_stop_fds[i] >= 0) {
+#ifdef PHP_WIN32
+      _close(worker_stop_fds[i]);
+#else
+      close(worker_stop_fds[i]);
+#endif
+      worker_stop_fds[i] = -1;
+    }
+  }
+}
+
+/* Marks the calling thread as a background worker, opens its stop pipe,
+ * transfers the write fd to the caller (clearing the TLS slot so later
+ * recycle won't double-close), and disarms max_execution_time. Returns
+ * -1 if the pipe could not be opened. */
+int frankenphp_set_background_worker_and_get_stop_fd_write(void) {
+  is_background_worker = true;
+  /* Drop the dangling stream pointer (see
+   * frankenphp_update_local_thread_context for why). */
+  worker_signaling_stream = NULL;
+  /* Bg workers don't enforce max_execution_time; disarm any lingering timer. */
+  zend_unset_timeout();
+
+  frankenphp_worker_close_stop_fds();
+  if (frankenphp_worker_open_stop_pipe() != 0) {
+    worker_stop_fds[0] = -1;
+    worker_stop_fds[1] = -1;
+    return -1;
+  }
+  int fd = worker_stop_fds[1];
+  worker_stop_fds[1] = -1;
+  return fd;
+}
+
+void frankenphp_worker_close_fd(int fd) {
+  if (fd < 0) {
+    return;
+  }
+  /* Closing the write end of the stop pipe lands as EOF on the read end,
+   * so the PHP side's stream_select returns promptly. */
+#ifdef PHP_WIN32
+  _close(fd);
+#else
+  close(fd);
+#endif
+}
+
+static int frankenphp_worker_dup_fd(int fd) {
+#ifdef PHP_WIN32
+  return _dup(fd);
+#else
+  return dup(fd);
+#endif
+}
+
 static void frankenphp_update_request_context() {
   /* the server context is stored on the go side, still SG(server_context) needs
    * to not be NULL */
@@ -823,6 +912,191 @@ PHP_FUNCTION(frankenphp_log) {
   }
 }
 
+PHP_FUNCTION(frankenphp_ensure_background_worker) {
+  zval *names_zv;
+  double timeout = 0.0;
+  bool timeout_is_null = true;
+
+  ZEND_PARSE_PARAMETERS_START(1, 2);
+  Z_PARAM_ZVAL(names_zv);
+  Z_PARAM_OPTIONAL
+  Z_PARAM_DOUBLE_OR_NULL(timeout, timeout_is_null);
+  ZEND_PARSE_PARAMETERS_END();
+
+  if (!timeout_is_null && timeout <= 0.0) {
+    zend_value_error("frankenphp_ensure_background_worker(): timeout must "
+                     "be > 0 (pass null to use the default)");
+    RETURN_THROWS();
+  }
+
+  /* Accept either a single string or an array of strings. For a single
+   * string we avoid the heap allocation by pointing at ZSTR fields
+   * directly via the on-stack one-element arrays. */
+  char *single_name_ptr = NULL;
+  size_t single_name_len = 0;
+  char **name_ptrs = NULL;
+  size_t *name_lens = NULL;
+  int name_count = 0;
+  bool heap_allocated = false;
+
+  if (Z_TYPE_P(names_zv) == IS_STRING) {
+    if (Z_STRLEN_P(names_zv) == 0) {
+      zend_value_error("frankenphp_ensure_background_worker(): name "
+                       "must not be empty");
+      RETURN_THROWS();
+    }
+    /* Reject embedded NUL bytes: PHP's zend_string is length-tagged so
+     * arbitrary bytes are technically legal, but the bg-worker name flows
+     * through C-string-aware paths (logging, $_SERVER export) where an
+     * embedded NUL would silently truncate. Fail loudly instead. */
+    if (memchr(Z_STRVAL_P(names_zv), '\0', Z_STRLEN_P(names_zv)) != NULL) {
+      zend_value_error("frankenphp_ensure_background_worker(): name "
+                       "must not contain null bytes");
+      RETURN_THROWS();
+    }
+    single_name_ptr = Z_STRVAL_P(names_zv);
+    single_name_len = Z_STRLEN_P(names_zv);
+    name_ptrs = &single_name_ptr;
+    name_lens = &single_name_len;
+    name_count = 1;
+  } else if (Z_TYPE_P(names_zv) == IS_ARRAY) {
+    HashTable *ht = Z_ARRVAL_P(names_zv);
+    name_count = zend_hash_num_elements(ht);
+    if (name_count == 0) {
+      zend_value_error("frankenphp_ensure_background_worker(): names array "
+                       "must not be empty");
+      RETURN_THROWS();
+    }
+    name_ptrs = emalloc(name_count * sizeof(*name_ptrs));
+    name_lens = emalloc(name_count * sizeof(*name_lens));
+    heap_allocated = true;
+    int idx = 0;
+    zval *v;
+    ZEND_HASH_FOREACH_VAL(ht, v) {
+      if (Z_TYPE_P(v) != IS_STRING) {
+        efree(name_ptrs);
+        efree(name_lens);
+        zend_type_error("frankenphp_ensure_background_worker(): names array "
+                        "must contain only strings");
+        RETURN_THROWS();
+      }
+      if (Z_STRLEN_P(v) == 0) {
+        efree(name_ptrs);
+        efree(name_lens);
+        zend_value_error("frankenphp_ensure_background_worker(): names array "
+                         "must not contain empty strings");
+        RETURN_THROWS();
+      }
+      /* Reject embedded NUL bytes: see single-string form above for the
+       * reasoning. Apply per-element so a mixed array is fully validated
+       * before any worker is started. */
+      if (memchr(Z_STRVAL_P(v), '\0', Z_STRLEN_P(v)) != NULL) {
+        efree(name_ptrs);
+        efree(name_lens);
+        zend_value_error("frankenphp_ensure_background_worker(): names array "
+                         "must not contain names with null bytes");
+        RETURN_THROWS();
+      }
+      /* Reject duplicates: O(n^2) is fine for the small batch sizes we
+       * expect here. */
+      for (int j = 0; j < idx; j++) {
+        if (name_lens[j] == (size_t)Z_STRLEN_P(v) &&
+            memcmp(name_ptrs[j], Z_STRVAL_P(v), name_lens[j]) == 0) {
+          efree(name_ptrs);
+          efree(name_lens);
+          zend_value_error(
+              "frankenphp_ensure_background_worker(): duplicate name %s",
+              Z_STRVAL_P(v));
+          RETURN_THROWS();
+        }
+      }
+      name_ptrs[idx] = Z_STRVAL_P(v);
+      name_lens[idx] = Z_STRLEN_P(v);
+      idx++;
+    }
+    ZEND_HASH_FOREACH_END();
+  } else {
+    zend_type_error("frankenphp_ensure_background_worker(): name must be a "
+                    "string or an array of strings");
+    RETURN_THROWS();
+  }
+
+  /* Seconds (PHP) -> ms (Go time.Duration). null = use the Go-side
+   * default; <=0 was rejected upfront. */
+  int64_t timeout_ms = 0;
+  if (!timeout_is_null) {
+    timeout_ms = (int64_t)(timeout * 1000.0);
+  }
+  char *error = go_frankenphp_ensure_background_worker(
+      thread_index, name_ptrs, name_lens, name_count, timeout_ms);
+  if (heap_allocated) {
+    efree(name_ptrs);
+    efree(name_lens);
+  }
+
+  if (error) {
+    zend_throw_exception(spl_ce_RuntimeException, error, 0);
+    free(error);
+    RETURN_THROWS();
+  }
+}
+
+PHP_FUNCTION(frankenphp_get_worker_handle) {
+  ZEND_PARSE_PARAMETERS_NONE();
+
+  if (!is_background_worker) {
+    zend_throw_exception(spl_ce_RuntimeException,
+                         "frankenphp_get_worker_handle() can only be called "
+                         "from a background worker",
+                         0);
+    RETURN_THROWS();
+  }
+
+  /* Return the cached stream on repeat calls. The first call (below) is
+   * the readiness boundary that ensure() blocks on; subsequent calls just
+   * hand back the same stream. */
+  if (worker_signaling_stream != NULL) {
+    php_stream_to_zval(worker_signaling_stream, return_value);
+    GC_ADDREF(Z_COUNTED_P(return_value));
+    return;
+  }
+
+  if (worker_stop_fds[0] < 0) {
+    zend_throw_exception(spl_ce_RuntimeException,
+                         "failed to create background worker stop pipe", 0);
+    RETURN_THROWS();
+  }
+
+  /* DUP so closing the PHP stream doesn't affect worker_stop_fds[0]; the
+   * original stays owned by the C side for cleanup at worker restart. */
+  int fd = frankenphp_worker_dup_fd(worker_stop_fds[0]);
+  if (fd < 0) {
+    zend_throw_exception(spl_ce_RuntimeException,
+                         "failed to dup background worker stop fd", 0);
+    RETURN_THROWS();
+  }
+
+  php_stream *stream = php_stream_fopen_from_fd(fd, "rb", NULL);
+  if (!stream) {
+    frankenphp_worker_close_fd(fd);
+    zend_throw_exception(spl_ce_RuntimeException,
+                         "failed to create stream from stop fd", 0);
+    RETURN_THROWS();
+  }
+
+  worker_signaling_stream = stream;
+  php_stream_to_zval(stream, return_value);
+
+  /* Extra ref so PHP can't destroy the stream while TLS caches the pointer. */
+  GC_ADDREF(Z_COUNTED_P(return_value));
+
+  /* Signal that this worker has reached its main loop. ensure() callers
+   * waiting on this worker unblock here. Idempotent on the Go side
+   * (sync.Once-guarded), so a worker that crashed and respawned signals
+   * again on each fresh boot without harm. */
+  go_frankenphp_worker_ready(thread_index);
+}
+
 #ifdef FRANKENPHP_TEST
 /* Test-only entry point that exercises zval.h end-to-end:
  * validate -> persist (request -> persistent memory) ->
@@ -1035,6 +1309,22 @@ void frankenphp_register_server_vars(zval *track_vars_array,
   ZVAL_EMPTY_STRING(&zv);
   zend_hash_update_ind(ht, frankenphp_strings.auth_type, &zv);
   zend_hash_update_ind(ht, frankenphp_strings.remote_ident, &zv);
+
+  /* Worker identity in $_SERVER (HTTP and bg workers alike). The value is
+   * the user-facing worker name; pre-existing user code that only checks
+   * isset($_SERVER['FRANKENPHP_WORKER']) keeps working. */
+  if (vars.worker_name && vars.worker_name_len > 0) {
+    zval name_zv;
+    ZVAL_STRINGL(&name_zv, vars.worker_name, vars.worker_name_len);
+    zend_hash_str_update(ht, "FRANKENPHP_WORKER",
+                         sizeof("FRANKENPHP_WORKER") - 1, &name_zv);
+  }
+  if (vars.is_background_worker) {
+    zval bg_zv;
+    ZVAL_TRUE(&bg_zv);
+    zend_hash_str_update(ht, "FRANKENPHP_WORKER_BACKGROUND",
+                         sizeof("FRANKENPHP_WORKER_BACKGROUND") - 1, &bg_zv);
+  }
 }
 
 /** Create an immutable zend_string that lasts for the whole process **/
@@ -1264,6 +1554,12 @@ static void *php_thread(void *arg) {
         zend_bailout();
       }
 
+      /* php_request_startup re-arms max_execution_time; bg workers
+       * never enforce it, disarm again. */
+      if (is_background_worker) {
+        zend_unset_timeout();
+      }
+
       zend_file_handle file_handle;
       zend_stream_init_filename(&file_handle, scriptName);
 
diff --git a/frankenphp.go b/frankenphp.go
index 52246d01c7..4eb948b0d6 100644
--- a/frankenphp.go
+++ b/frankenphp.go
@@ -154,11 +154,27 @@ func Config() PHPConfig {
 	}
 }
 
-func calculateMaxThreads(opt *opt) (numWorkers int, _ error) {
+func calculateMaxThreads(opt *opt) (numWorkers int, err error) {
 	maxProcs := runtime.GOMAXPROCS(0) * 2
 	maxThreadsFromWorkers := 0
+	// Bg workers reserve their thread budget separately from HTTP
+	// workers so they don't double-count against the HTTP-worker
+	// admission check below; the bump is applied at the end.
+	reservedThreads := reserveBackgroundWorkerThreads(opt)
+	defer func() {
+		if err != nil {
+			return
+		}
+		opt.numThreads += reservedThreads
+		opt.maxThreads += reservedThreads
+		numWorkers += reservedThreads
+	}()
 
 	for i, w := range opt.workers {
+		if w.isBackgroundWorker {
+			continue
+		}
+
 		if w.num <= 0 {
 			// https://github.com/php/frankenphp/issues/126
 			opt.workers[i].num = maxProcs
@@ -786,6 +802,7 @@ func resetGlobals() {
 	workers = nil
 	workersByName = nil
 	workersByPath = nil
+	backgroundLookups = nil
 	watcherIsEnabled = false
 	maxIdleTime = defaultMaxIdleTime
 	maxRequestsPerThread = 0
diff --git a/frankenphp.h b/frankenphp.h
index 31df007f18..8cfd175df8 100644
--- a/frankenphp.h
+++ b/frankenphp.h
@@ -116,6 +116,12 @@ typedef struct frankenphp_server_vars {
   zend_string *request_scheme;
   zend_string *ssl_protocol;
   zend_string *https;
+
+  /* Worker identity for $_SERVER. worker_name is m#-stripped Go-side,
+   * empty for non-worker requests. */
+  char *worker_name;
+  size_t worker_name_len;
+  bool is_background_worker;
 } frankenphp_server_vars;
 
 /**
@@ -226,6 +232,10 @@ size_t frankenphp_get_thread_memory_usage(uintptr_t thread_index);
 void frankenphp_force_kill_thread(force_kill_slot slot);
 void frankenphp_release_thread_for_kill(force_kill_slot slot);
 
+/* Background worker primitives. */
+int frankenphp_set_background_worker_and_get_stop_fd_write(void);
+void frankenphp_worker_close_fd(int fd);
+
 void register_extensions(zend_module_entry **m, int len);
 
 #endif
diff --git a/frankenphp.stub.php b/frankenphp.stub.php
index d6c85aa05f..9a963ccb49 100644
--- a/frankenphp.stub.php
+++ b/frankenphp.stub.php
@@ -54,3 +54,33 @@ function mercure_publish(string|array $topics, string $data = '', bool $private
  * array<string, any> $context Values of the array will be converted to the corresponding Go type (if supported by FrankenPHP) and added to the context of the structured logs using https://pkg.go.dev/log/slog#Attr
  */
 function frankenphp_log(string $message, int $level = 0, array $context = []): void {}
+
+/**
+ * Declares a dependency on one or more background workers. Lazy-starts each
+ * worker that isn't already running, then blocks until every named worker
+ * has reached its main loop (signalled by its first call to
+ * frankenphp_get_worker_handle()), aborts after exhausting its
+ * max_consecutive_failures cap, or the timeout expires. Throws
+ * RuntimeException if no background worker is configured for any given
+ * name, if a worker fails to reach readiness within the timeout, or if a
+ * worker aborts during boot.
+ *
+ * The array form rejects empty arrays (ValueError), non-string elements
+ * (TypeError), empty strings, and duplicate names (ValueError) before
+ * any worker is started.
+ *
+ * @param string|string[] $name
+ * @param float|null $timeout deadline in seconds. null (the default) falls
+ *                            back to FrankenPHP's internal default
+ *                            timeout. A value <= 0 raises ValueError.
+ */
+function frankenphp_ensure_background_worker(string|array $name, ?float $timeout = null): void {}
+
+/**
+ * Returns the stop-signal stream for the current background worker. The
+ * stream closes when FrankenPHP is draining the worker so the script can
+ * exit its loop gracefully. Only callable from inside a background worker.
+ *
+ * @return resource
+ */
+function frankenphp_get_worker_handle(): mixed {}
diff --git a/frankenphp_arginfo.h b/frankenphp_arginfo.h
index 4f2707cbca..b55e0dc92a 100644
--- a/frankenphp_arginfo.h
+++ b/frankenphp_arginfo.h
@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 60f0d27c04f94d7b24c052e91ef294595a2bc421 */
+ * Stub hash: f90cea54c6a7c2b8559afa42abfd33066e764fd9 */
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_handle_request, 0, 1, _IS_BOOL, 0)
 	ZEND_ARG_TYPE_INFO(0, callback, IS_CALLABLE, 0)
@@ -41,6 +41,13 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_log, 0, 1, IS_VOID, 0
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, context, IS_ARRAY, 0, "[]")
 ZEND_END_ARG_INFO()
 
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_ensure_background_worker, 0, 1, IS_VOID, 0)
+	ZEND_ARG_TYPE_MASK(0, name, MAY_BE_STRING|MAY_BE_ARRAY, NULL)
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, timeout, IS_DOUBLE, 1, "null")
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_get_worker_handle, 0, 0, IS_MIXED, 0)
+ZEND_END_ARG_INFO()
 
 ZEND_FUNCTION(frankenphp_handle_request);
 ZEND_FUNCTION(headers_send);
@@ -49,7 +56,8 @@ ZEND_FUNCTION(frankenphp_request_headers);
 ZEND_FUNCTION(frankenphp_response_headers);
 ZEND_FUNCTION(mercure_publish);
 ZEND_FUNCTION(frankenphp_log);
-
+ZEND_FUNCTION(frankenphp_ensure_background_worker);
+ZEND_FUNCTION(frankenphp_get_worker_handle);
 
 static const zend_function_entry ext_functions[] = {
 	ZEND_FE(frankenphp_handle_request, arginfo_frankenphp_handle_request)
@@ -63,6 +71,8 @@ static const zend_function_entry ext_functions[] = {
 	ZEND_FALIAS(apache_response_headers, frankenphp_response_headers, arginfo_apache_response_headers)
 	ZEND_FE(mercure_publish, arginfo_mercure_publish)
 	ZEND_FE(frankenphp_log, arginfo_frankenphp_log)
+	ZEND_FE(frankenphp_ensure_background_worker, arginfo_frankenphp_ensure_background_worker)
+	ZEND_FE(frankenphp_get_worker_handle, arginfo_frankenphp_get_worker_handle)
 	ZEND_FE_END
 };
 
diff --git a/options.go b/options.go
index a9cd2a2630..a4843d30de 100644
--- a/options.go
+++ b/options.go
@@ -50,6 +50,8 @@ type workerOpt struct {
 	onThreadShutdown       func(int)
 	onServerStartup        func()
 	onServerShutdown       func()
+	isBackgroundWorker     bool
+	scope                  Scope
 }
 
 // WithContext sets the main context to use.
@@ -258,6 +260,32 @@ func WithWorkerOnServerShutdown(f func()) WorkerOption {
 	}
 }
 
+// EXPERIMENTAL: WithWorkerBackground marks this worker as a background
+// (non-HTTP) worker. Background workers run outside the request cycle and
+// share the PHP runtime with HTTP threads but don't serve HTTP requests.
+// They expose a stop pipe via frankenphp_get_worker_handle() so PHP scripts
+// can park on stream_select and exit gracefully when FrankenPHP drains.
+func WithWorkerBackground() WorkerOption {
+	return func(w *workerOpt) error {
+		w.isBackgroundWorker = true
+
+		return nil
+	}
+}
+
+// EXPERIMENTAL: WithWorkerScope assigns this worker to a given scope.
+// Workers in the same scope share a background lookup; each php_server
+// block gets its own scope so workers with the same name in different
+// blocks don't collide. The zero value is the global/embed scope and is
+// the default.
+func WithWorkerScope(scope Scope) WorkerOption {
+	return func(w *workerOpt) error {
+		w.scope = scope
+
+		return nil
+	}
+}
+
 func withExtensionWorkers(w *extensionWorkers) WorkerOption {
 	return func(wo *workerOpt) error {
 		wo.extensionWorkers = w
diff --git a/phpthread.go b/phpthread.go
index 5d94bd62f6..90eda0e9bf 100644
--- a/phpthread.go
+++ b/phpthread.go
@@ -47,6 +47,9 @@ type threadHandler interface {
 	// current handlers are no-ops; this is the seam later handler types use
 	// without having to modify drainWorkerThreads.
 	drain()
+	// scopedWorker returns the *worker this handler runs (HTTP / bg
+	// workers), or nil for non-worker handlers.
+	scopedWorker() *worker
 }
 
 func newPHPThread(threadIndex int) *phpThread {
@@ -105,6 +108,9 @@ func (thread *phpThread) shutdown() {
 		return
 	}
 
+	// Wake up handlers parked in a blocking C call (background workers'
+	// stream_select on the stop pipe). No-op for regular/worker handlers.
+	thread.handler.drain()
 	close(thread.drainChan)
 
 	// Arm force-kill after the grace period to wake any thread stuck in
diff --git a/requestoptions.go b/requestoptions.go
index 42cc3cf7c0..37e78072f5 100644
--- a/requestoptions.go
+++ b/requestoptions.go
@@ -154,6 +154,18 @@ func WithRequestLogger(logger *slog.Logger) RequestOption {
 	}
 }
 
+// WithRequestScope selects the scope for ensure() calls made from this
+// request. Web-server integrations (such as the Caddy module) can call
+// NextScope per independently-configured block to isolate its set of
+// background workers.
+func WithRequestScope(scope Scope) RequestOption {
+	return func(o *frankenPHPContext) error {
+		o.scope = scope
+
+		return nil
+	}
+}
+
 // WithWorkerName sets the worker that should handle the request
 func WithWorkerName(name string) RequestOption {
 	return func(o *frankenPHPContext) error {
diff --git a/scaling.go b/scaling.go
index c606925fdf..03f1f3953e 100644
--- a/scaling.go
+++ b/scaling.go
@@ -83,6 +83,19 @@ func addWorkerThread(worker *worker) (*phpThread, error) {
 	return thread, nil
 }
 
+// addBackgroundWorkerThread reserves an inactive thread and converts it
+// to a background worker thread bound to (worker, runtimeName, ready).
+// runtimeName is the worker's m#-prefixed identity for named workers and
+// pool members, or the user-facing name for catch-all instances.
+func addBackgroundWorkerThread(worker *worker, runtimeName string, ready *backgroundWorkerState) (*phpThread, error) {
+	thread := getInactivePHPThread()
+	if thread == nil {
+		return nil, ErrMaxThreadsReached
+	}
+	convertToBackgroundWorkerThread(thread, worker, runtimeName, ready)
+	return thread, nil
+}
+
 // scaleWorkerThread adds a worker PHP thread automatically
 func scaleWorkerThread(worker *worker, done chan struct{}, mstate *state.ThreadState) {
 	// probe CPU usage before acquiring the lock (avoids holding lock during 120ms sleep)
diff --git a/testdata/_executor.php b/testdata/_executor.php
index 61a5319f11..31b87c79cb 100644
--- a/testdata/_executor.php
+++ b/testdata/_executor.php
@@ -1,7 +1,7 @@
 <?php
 
 $fn = require $_SERVER['SCRIPT_FILENAME'];
-if ('1' !== ($_SERVER['FRANKENPHP_WORKER'] ?? null)) {
+if (!isset($_SERVER['FRANKENPHP_WORKER'])) {
     $fn();
     exit(0);
 }
diff --git a/testdata/bgworker/basic.php b/testdata/bgworker/basic.php
new file mode 100644
index 0000000000..48a2305be8
--- /dev/null
+++ b/testdata/bgworker/basic.php
@@ -0,0 +1,20 @@
+<?php
+
+// Long-lived background worker: disable PHP max_execution_time so the
+// 30s default cannot interrupt the stream_select park. The C side calls
+// zend_unset_timeout() too, but the belt-and-suspenders here covers PHP
+// builds where that path does not fully disarm the timer.
+set_time_limit(0);
+
+// Touch the sentinel so the test can confirm the worker actually ran.
+if (!empty($_SERVER['BG_SENTINEL'])) {
+    @touch($_SERVER['BG_SENTINEL']);
+}
+
+// Park on the stop pipe until FrankenPHP drains us (drain closes the
+// write end, which lands as EOF on the read end).
+$stream = frankenphp_get_worker_handle();
+$read = [$stream];
+$write = null;
+$except = null;
+stream_select($read, $write, $except, null);
diff --git a/testdata/bgworker/batch-ensure.php b/testdata/bgworker/batch-ensure.php
new file mode 100644
index 0000000000..446f80dbe4
--- /dev/null
+++ b/testdata/bgworker/batch-ensure.php
@@ -0,0 +1,8 @@
+<?php
+
+// HTTP fixture: ensure three workers in a single batch call. Each
+// catch-all instance writes its own per-name sentinel under
+// $_SERVER['BG_SENTINEL_DIR'] (set via WithWorkerEnv at the bg worker
+// declaration). The HTTP response just confirms the call did not throw.
+frankenphp_ensure_background_worker(['batch-a', 'batch-b', 'batch-c']);
+echo "ok\n";
diff --git a/testdata/bgworker/batch-errors.php b/testdata/bgworker/batch-errors.php
new file mode 100644
index 0000000000..f6bbd170b4
--- /dev/null
+++ b/testdata/bgworker/batch-errors.php
@@ -0,0 +1,30 @@
+<?php
+
+// HTTP fixture exercising input validation paths of the batch ensure().
+// The query string selects which scenario to trigger; the script catches
+// the resulting throwable and echoes its class so the test can assert the
+// expected error type without parsing PHP's error log.
+$mode = $_GET['mode'] ?? '';
+
+try {
+    switch ($mode) {
+        case 'empty':
+            frankenphp_ensure_background_worker([]);
+            break;
+        case 'nonstring':
+            frankenphp_ensure_background_worker(['ok-name', 42]);
+            break;
+        case 'duplicate':
+            frankenphp_ensure_background_worker(['dup', 'dup']);
+            break;
+        case 'empty-string':
+            frankenphp_ensure_background_worker(['', 'other']);
+            break;
+        default:
+            echo "no-mode\n";
+            return;
+    }
+    echo "no-throw\n";
+} catch (\Throwable $e) {
+    echo get_class($e), ': ', $e->getMessage(), "\n";
+}
diff --git a/testdata/bgworker/bg-flag.php b/testdata/bgworker/bg-flag.php
new file mode 100644
index 0000000000..6059316ae3
--- /dev/null
+++ b/testdata/bgworker/bg-flag.php
@@ -0,0 +1,20 @@
+<?php
+
+// Long-lived bg worker: disable PHP max_execution_time so the 30s default
+// cannot interrupt the stream_select park. The C side calls
+// zend_unset_timeout() too, but the belt-and-suspenders here covers PHP
+// builds where that path does not fully disarm the timer.
+set_time_limit(0);
+
+// Write a sentinel containing var_export() of FRANKENPHP_WORKER_BACKGROUND
+// so the test can assert the exact value injected by C ($_SERVER flag).
+if (!empty($_SERVER['BG_SENTINEL'])) {
+    $value = $_SERVER['FRANKENPHP_WORKER_BACKGROUND'] ?? 'MISSING';
+    @file_put_contents($_SERVER['BG_SENTINEL'], var_export($value, true));
+}
+
+$stream = frankenphp_get_worker_handle();
+$read = [$stream];
+$write = null;
+$except = null;
+stream_select($read, $write, $except, null);
diff --git a/testdata/bgworker/boot-fail.php b/testdata/bgworker/boot-fail.php
new file mode 100644
index 0000000000..ee97b2a0c4
--- /dev/null
+++ b/testdata/bgworker/boot-fail.php
@@ -0,0 +1,7 @@
+<?php
+
+// Bg worker fixture that throws on its very first line. Used by
+// TestEnsureBackgroundWorkerBootFailure to prove ensure() surfaces the
+// crash metadata (entrypoint, exit status, attempt count) when a worker
+// keeps crashing during boot before reaching the readiness boundary.
+throw new RuntimeException('intentional boot failure for test');
diff --git a/testdata/bgworker/crash.php b/testdata/bgworker/crash.php
new file mode 100644
index 0000000000..385df0d8ae
--- /dev/null
+++ b/testdata/bgworker/crash.php
@@ -0,0 +1,29 @@
+<?php
+
+// Crash-and-recover fixture. On the first boot (no marker), creates the
+// marker and exit(1) so the bg worker thread observes a non-zero exit
+// status. On the second boot (marker present), touches a "restarted"
+// sentinel and parks on the stop pipe. The test asserts the restarted
+// sentinel appears, proving the crash-restart loop ran.
+set_time_limit(0);
+
+$marker = $_SERVER['BG_CRASH_MARKER'] ?? '';
+$restarted = $_SERVER['BG_RESTARTED_SENTINEL'] ?? '';
+
+if ($marker === '' || $restarted === '') {
+    // Misconfigured: don't loop forever on a missing env.
+    exit(2);
+}
+
+if (!file_exists($marker)) {
+    file_put_contents($marker, '1');
+    exit(1);
+}
+
+@touch($restarted);
+
+$stream = frankenphp_get_worker_handle();
+$read = [$stream];
+$write = null;
+$except = null;
+stream_select($read, $write, $except, null);
diff --git a/testdata/bgworker/eager-catchall.php b/testdata/bgworker/eager-catchall.php
new file mode 100644
index 0000000000..4a32c942ec
--- /dev/null
+++ b/testdata/bgworker/eager-catchall.php
@@ -0,0 +1,16 @@
+<?php
+
+// Touches BG_EAGER_SENTINEL once readiness is reached, then parks.
+// Drives the eager catch-all readiness test.
+set_time_limit(0);
+
+$sentinel = $_SERVER['BG_EAGER_SENTINEL'] ?? '';
+if ($sentinel !== '') {
+    @touch($sentinel);
+}
+
+$stream = frankenphp_get_worker_handle();
+$read = [$stream];
+$write = null;
+$except = null;
+stream_select($read, $write, $except, null);
diff --git a/testdata/bgworker/fail-then-succeed.php b/testdata/bgworker/fail-then-succeed.php
new file mode 100644
index 0000000000..d5d061d38b
--- /dev/null
+++ b/testdata/bgworker/fail-then-succeed.php
@@ -0,0 +1,29 @@
+<?php
+
+// Crashes on boots 1..BG_FAIL_UNTIL, then succeeds. Each boot writes a
+// boot<N> marker so the script counts attempts; success path writes a
+// "ready" sentinel.
+set_time_limit(0);
+
+$markerDir = $_SERVER['BG_MARKER_DIR'] ?? '';
+if ($markerDir === '') {
+    exit(2);
+}
+
+$attempt = 1;
+while (file_exists($markerDir . '/boot' . $attempt)) {
+    $attempt++;
+}
+@touch($markerDir . '/boot' . $attempt);
+
+$failUntil = (int)($_SERVER['BG_FAIL_UNTIL'] ?? '2');
+if ($attempt <= $failUntil) {
+    exit(1);
+}
+
+@touch($markerDir . '/ready');
+$stream = frankenphp_get_worker_handle();
+$read = [$stream];
+$write = null;
+$except = null;
+stream_select($read, $write, $except, null);
diff --git a/testdata/bgworker/named.php b/testdata/bgworker/named.php
new file mode 100644
index 0000000000..ebf8bb5103
--- /dev/null
+++ b/testdata/bgworker/named.php
@@ -0,0 +1,19 @@
+<?php
+
+// Long-lived bg worker: disable PHP max_execution_time so the 30s default
+// cannot interrupt the stream_select park.
+set_time_limit(0);
+
+// Lazy-start fixture for ensure() tests. Touches a per-name sentinel under
+// $_SERVER['BG_SENTINEL_DIR'] so tests can confirm the right instance ran.
+// Catch-all instances see their declared name through FRANKENPHP_WORKER.
+$name = $_SERVER['FRANKENPHP_WORKER'] ?? 'unknown';
+if (!empty($_SERVER['BG_SENTINEL_DIR'])) {
+    @touch($_SERVER['BG_SENTINEL_DIR'] . DIRECTORY_SEPARATOR . $name);
+}
+
+$stream = frankenphp_get_worker_handle();
+$read = [$stream];
+$write = null;
+$except = null;
+stream_select($read, $write, $except, null);
diff --git a/testdata/bgworker/no-handle.php b/testdata/bgworker/no-handle.php
new file mode 100644
index 0000000000..a21029a1bc
--- /dev/null
+++ b/testdata/bgworker/no-handle.php
@@ -0,0 +1,9 @@
+<?php
+
+// Long-lived bg worker fixture that intentionally does NOT call
+// frankenphp_get_worker_handle(). Used by TestEnsureBackgroundWorkerTimeout
+// to prove ensure() times out when the readiness boundary is never crossed.
+// The 0 limit lets sleep() run as long as the test's drain takes.
+set_time_limit(0);
+
+sleep(60);
diff --git a/testdata/bgworker/pool.php b/testdata/bgworker/pool.php
new file mode 100644
index 0000000000..f23e0a0059
--- /dev/null
+++ b/testdata/bgworker/pool.php
@@ -0,0 +1,22 @@
+<?php
+
+// Long-lived bg worker: disable PHP max_execution_time so the 30s default
+// cannot interrupt the stream_select park. The C side calls
+// zend_unset_timeout() too, but the belt-and-suspenders here covers PHP
+// builds where that path does not fully disarm the timer.
+set_time_limit(0);
+
+// Pool worker: num > 1 means multiple threads share this worker name.
+// Each thread runs in its own ZTS context, but getmypid() returns the
+// shared process pid. random_bytes() gives us a unique-per-thread
+// suffix so the test can count N distinct booted threads.
+if (!empty($_SERVER['BG_SENTINEL_DIR'])) {
+    $path = $_SERVER['BG_SENTINEL_DIR'] . '/pool-' . bin2hex(random_bytes(8));
+    @touch($path);
+}
+
+$stream = frankenphp_get_worker_handle();
+$read = [$stream];
+$write = null;
+$except = null;
+stream_select($read, $write, $except, null);
diff --git a/testdata/bgworker/readiness-then-crash.php b/testdata/bgworker/readiness-then-crash.php
new file mode 100644
index 0000000000..c012d51ffe
--- /dev/null
+++ b/testdata/bgworker/readiness-then-crash.php
@@ -0,0 +1,8 @@
+<?php
+
+// Signals readiness via frankenphp_get_worker_handle(), then exits
+// non-zero. Drives the post-readiness crash-loop abort test.
+set_time_limit(0);
+
+frankenphp_get_worker_handle();
+exit(1);
diff --git a/testdata/bgworker/stuck.php b/testdata/bgworker/stuck.php
new file mode 100644
index 0000000000..2266406d52
--- /dev/null
+++ b/testdata/bgworker/stuck.php
@@ -0,0 +1,17 @@
+<?php
+
+// Intentionally stuck bg worker fixture: does NOT watch the stop pipe,
+// so handler.drain() closing the write end has no effect. The only way
+// to make RestartWorkers finish within the grace period is the
+// force-kill primitive (pthread_kill on Linux/FreeBSD). Used by
+// TestBackgroundWorkerRestartForceKillsStuckThread to prove the
+// force-kill path (not just the stop-pipe wake-up) is actually wired.
+set_time_limit(0);
+
+if (!empty($_SERVER['BG_SENTINEL'])) {
+    @touch($_SERVER['BG_SENTINEL']);
+}
+
+// sleep() is interruptible by SIGRTMIN+3 on Linux/FreeBSD; the test
+// skips platforms where neither mechanism can interrupt it.
+sleep(60);
diff --git a/threadbackgroundworker.go b/threadbackgroundworker.go
new file mode 100644
index 0000000000..dbfa51ff39
--- /dev/null
+++ b/threadbackgroundworker.go
@@ -0,0 +1,250 @@
+package frankenphp
+
+// #include "frankenphp.h"
+import "C"
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"path/filepath"
+	"sync/atomic"
+	"time"
+
+	"github.com/dunglas/frankenphp/internal/state"
+)
+
+// backgroundWorkerThread handles background worker scripts. Owns its own
+// lifecycle: boot, loop, optionally crash-restart with exponential backoff.
+// Background workers share the PHP runtime with HTTP threads but don't
+// serve HTTP requests. They expose a stop pipe (via
+// frankenphp_get_worker_handle) so PHP scripts can park on stream_select
+// and exit gracefully when FrankenPHP drains them.
+type backgroundWorkerThread struct {
+	state                  *state.ThreadState
+	thread                 *phpThread
+	worker                 *worker
+	dummyFrankenPHPContext *frankenPHPContext
+	dummyContext           context.Context
+	failureCount           int
+
+	// runtimeName is the worker identity (kept m#-prefixed for metric
+	// label consistency); setupScript trims it at the PHP boundary.
+	runtimeName string
+	// backgroundReady is this thread's readiness slot: worker.backgroundReady
+	// for named workers, worker.catchAllNames[runtimeName] for catch-all
+	// threads (so boot-failure / abort / markReady stay per-name).
+	backgroundReady *backgroundWorkerState
+
+	// stopFdWrite is this thread's stop-pipe write end (per-thread so pool
+	// workers drain independently); read end is exposed to PHP via
+	// frankenphp_get_worker_handle().
+	stopFdWrite atomic.Int32
+}
+
+func convertToBackgroundWorkerThread(thread *phpThread, worker *worker, runtimeName string, ready *backgroundWorkerState) {
+	handler := &backgroundWorkerThread{
+		state:           thread.state,
+		thread:          thread,
+		worker:          worker,
+		runtimeName:     runtimeName,
+		backgroundReady: ready,
+	}
+	handler.stopFdWrite.Store(-1)
+	thread.setHandler(handler)
+	worker.attachThread(thread)
+}
+
+func (handler *backgroundWorkerThread) scopedWorker() *worker { return handler.worker }
+
+func (handler *backgroundWorkerThread) name() string {
+	if handler.runtimeName != "" && handler.runtimeName != handler.worker.name {
+		return "Background Worker PHP Thread - " + handler.worker.fileName + " (" + handler.runtimeName + ")"
+	}
+	return "Background Worker PHP Thread - " + handler.worker.fileName
+}
+
+// isPostBoot samples the readiness channel non-blockingly so
+// afterScriptExecution can tell a boot crash (record bootFailureInfo) from
+// a post-boot crash (ensure() callers already saw success).
+func (handler *backgroundWorkerThread) isPostBoot() bool {
+	if handler.backgroundReady == nil {
+		return false
+	}
+	select {
+	case <-handler.backgroundReady.ready:
+		return true
+	default:
+		return false
+	}
+}
+
+func (handler *backgroundWorkerThread) frankenPHPContext() *frankenPHPContext {
+	return handler.dummyFrankenPHPContext
+}
+
+func (handler *backgroundWorkerThread) context() context.Context {
+	if handler.dummyContext != nil {
+		return handler.dummyContext
+	}
+	return globalCtx
+}
+
+// drain is called by drainWorkerThreads (and thread.shutdown) right before
+// drainChan is closed. We close the stop-pipe's write end so the PHP worker
+// script, which is typically parked in stream_select on the read end, wakes
+// up and can finish its loop gracefully. Per-thread fd so pool workers
+// drain their threads independently.
+func (handler *backgroundWorkerThread) drain() {
+	if fd := handler.stopFdWrite.Swap(-1); fd >= 0 {
+		C.frankenphp_worker_close_fd(C.int(fd))
+	}
+}
+
+func (handler *backgroundWorkerThread) beforeScriptExecution() string {
+	switch handler.state.Get() {
+	case state.TransitionRequested:
+		if handler.worker.onThreadShutdown != nil {
+			handler.worker.onThreadShutdown(handler.thread.threadIndex)
+		}
+		handler.worker.detachThread(handler.thread)
+		return handler.thread.transitionToNewHandler()
+	case state.Restarting:
+		if handler.worker.onThreadShutdown != nil {
+			handler.worker.onThreadShutdown(handler.thread.threadIndex)
+		}
+		handler.state.Set(state.Yielding)
+		handler.state.WaitFor(state.Ready, state.ShuttingDown)
+		return handler.beforeScriptExecution()
+	case state.Ready, state.TransitionComplete:
+		handler.thread.updateContext(true)
+		if handler.worker.onThreadReady != nil {
+			handler.worker.onThreadReady(handler.thread.threadIndex)
+		}
+
+		handler.setupScript()
+
+		return handler.worker.fileName
+	case state.ShuttingDown:
+		if handler.worker.onThreadShutdown != nil {
+			handler.worker.onThreadShutdown(handler.thread.threadIndex)
+		}
+		handler.worker.detachThread(handler.thread)
+		return ""
+	}
+
+	panic("unexpected state: " + handler.state.Name())
+}
+
+func (handler *backgroundWorkerThread) setupScript() {
+	if handler.runtimeName == "" {
+		handler.runtimeName = handler.worker.name
+	}
+	metrics.StartWorker(bgWorkerMetricName(handler.worker.scope, handler.runtimeName))
+
+	opts := append([]RequestOption(nil), handler.worker.requestOptions...)
+	handler.stopFdWrite.Store(int32(C.frankenphp_set_background_worker_and_get_stop_fd_write()))
+
+	fc, err := newDummyContext(
+		filepath.Base(handler.worker.fileName),
+		opts...,
+	)
+	if err != nil {
+		panic(err)
+	}
+
+	ctx := context.WithValue(globalCtx, contextKey, fc)
+
+	fc.worker = handler.worker
+	handler.dummyFrankenPHPContext = fc
+	handler.dummyContext = ctx
+
+	if globalLogger.Enabled(ctx, slog.LevelDebug) {
+		globalLogger.LogAttrs(ctx, slog.LevelDebug, "starting background worker", slog.String("worker", handler.runtimeName), slog.Int("thread", handler.thread.threadIndex))
+	}
+
+	handler.thread.state.Set(state.Ready)
+	fc.scriptFilename = handler.worker.fileName
+}
+
+func (handler *backgroundWorkerThread) afterScriptExecution(exitStatus int) {
+	// frankenphp_worker_get_stop_fd_write transferred fd ownership to Go,
+	// so we must close on every exit path to avoid a leak.
+	if fd := handler.stopFdWrite.Swap(-1); fd >= 0 {
+		C.frankenphp_worker_close_fd(C.int(fd))
+	}
+	worker := handler.worker
+	runtimeName := handler.runtimeName
+	if runtimeName == "" {
+		runtimeName = worker.name
+	}
+	handler.dummyFrankenPHPContext = nil
+	handler.dummyContext = nil
+
+	// During Shutdown the drain's force-kill is armed against one slot; a
+	// freshly spawned pthread would re-enter the script and never exit.
+	if mainThread != nil && mainThread.state.Is(state.ShuttingDown) {
+		handler.thread.state.Set(state.ShuttingDown)
+		return
+	}
+
+	metricName := bgWorkerMetricName(worker.scope, runtimeName)
+
+	// Cooperative exit: re-run, reset backoff.
+	if exitStatus == 0 {
+		metrics.StopWorker(metricName, StopReasonRestart)
+
+		if globalLogger.Enabled(globalCtx, slog.LevelDebug) {
+			globalLogger.LogAttrs(globalCtx, slog.LevelDebug, "restarting background worker", slog.String("worker", runtimeName), slog.Int("thread", handler.thread.threadIndex), slog.Int("exit_status", exitStatus))
+		}
+
+		handler.failureCount = 0
+		return
+	}
+
+	metrics.StopWorker(metricName, StopReasonCrash)
+
+	// Pre-readiness crash: stash metadata for a timing-out ensure(). Post-
+	// readiness crashes don't update this (the worker already signalled OK).
+	if !handler.isPostBoot() && handler.backgroundReady != nil {
+		handler.backgroundReady.bootFailure.Store(&bootFailureInfo{
+			entrypoint:   worker.fileName,
+			exitStatus:   exitStatus,
+			failureCount: handler.failureCount + 1,
+			// TODO(sidekicks): capture PG(last_error_message) here once
+			// the C-side helper lands in the set_vars/get_vars step.
+		})
+	}
+
+	// max_consecutive_failures cap. For single-instance bg workers,
+	// abort and release the slot so a future ensure() can lazy-spawn a
+	// fresh thread. Eager pools skip this: other pool threads may still
+	// be alive.
+	if worker.maxConsecutiveFailures >= 0 && handler.failureCount >= worker.maxConsecutiveFailures {
+		isSingleInstance := worker.bg.catchAllNames != nil || worker.num == 0
+		if isSingleInstance && handler.backgroundReady != nil {
+			handler.backgroundReady.abort(fmt.Errorf("background worker %s exceeded max_consecutive_failures (%d, last exit status %d)", worker.fileName, worker.maxConsecutiveFailures, exitStatus))
+			worker.invalidateBackgroundEntry(runtimeName)
+		}
+		if startupFailChan != nil && !watcherIsEnabled {
+			startupFailChan <- fmt.Errorf("too many consecutive failures: background worker %s keeps crashing", worker.fileName)
+			handler.thread.state.Set(state.ShuttingDown)
+			return
+		}
+		if globalLogger.Enabled(globalCtx, slog.LevelWarn) {
+			globalLogger.LogAttrs(globalCtx, slog.LevelWarn, "background worker exceeded max_consecutive_failures, stopping respawn", slog.String("worker", runtimeName), slog.Int("thread", handler.thread.threadIndex), slog.Int("failures", handler.failureCount))
+		}
+		handler.thread.state.Set(state.ShuttingDown)
+		return
+	}
+
+	if globalLogger.Enabled(globalCtx, slog.LevelWarn) {
+		globalLogger.LogAttrs(globalCtx, slog.LevelWarn, "background worker crashed, restarting", slog.String("worker", runtimeName), slog.Int("thread", handler.thread.threadIndex), slog.Int("failures", handler.failureCount), slog.Int("exit_status", exitStatus))
+	}
+
+	backoffDuration := time.Duration(handler.failureCount*handler.failureCount*100) * time.Millisecond
+	if backoffDuration > time.Second {
+		backoffDuration = time.Second
+	}
+	handler.failureCount++
+	time.Sleep(backoffDuration)
+}
diff --git a/threadinactive.go b/threadinactive.go
index e6de0b4be5..bef5192bd3 100644
--- a/threadinactive.go
+++ b/threadinactive.go
@@ -60,3 +60,5 @@ func (handler *inactiveThread) name() string {
 }
 
 func (handler *inactiveThread) drain() {}
+
+func (handler *inactiveThread) scopedWorker() *worker { return nil }
diff --git a/threadregular.go b/threadregular.go
index 2f52963726..bb9c305a00 100644
--- a/threadregular.go
+++ b/threadregular.go
@@ -85,6 +85,8 @@ func (handler *regularThread) name() string {
 
 func (handler *regularThread) drain() {}
 
+func (handler *regularThread) scopedWorker() *worker { return nil }
+
 func (handler *regularThread) waitForRequest() string {
 	// max_requests reached: restart the thread to clean up all ZTS state
 	if maxRequestsPerThread > 0 && handler.requestCount >= maxRequestsPerThread {
diff --git a/threadtasks_test.go b/threadtasks_test.go
index d6954d161c..3ecf12f391 100644
--- a/threadtasks_test.go
+++ b/threadtasks_test.go
@@ -81,6 +81,8 @@ func (handler *taskThread) name() string {
 
 func (handler *taskThread) drain() {}
 
+func (handler *taskThread) scopedWorker() *worker { return nil }
+
 func (handler *taskThread) waitForTasks() {
 	for {
 		select {
diff --git a/threadworker.go b/threadworker.go
index 21e1034805..f35a952d3d 100644
--- a/threadworker.go
+++ b/threadworker.go
@@ -105,6 +105,8 @@ func (handler *workerThread) name() string {
 	return "Worker PHP Thread - " + handler.worker.fileName
 }
 
+func (handler *workerThread) scopedWorker() *worker { return handler.worker }
+
 func (handler *workerThread) drain() {}
 
 func setupWorkerScript(handler *workerThread, worker *worker) {
diff --git a/worker.go b/worker.go
index fdc3098da6..9b748c93a0 100644
--- a/worker.go
+++ b/worker.go
@@ -33,6 +33,10 @@ type worker struct {
 	onThreadReady          func(int)
 	onThreadShutdown       func(int)
 	queuedRequests         atomic.Int32
+	scope                  Scope
+	// bg, if non-nil, marks this as a background (non-HTTP) worker and
+	// holds its bg-specific lifecycle state.
+	bg *backgroundWorkerExtras
 }
 
 var (
@@ -57,26 +61,47 @@ func initWorkers(opt []workerOpt) error {
 	workersByName = make(map[string]*worker, len(opt))
 	workersByPath = make(map[string]*worker, len(opt))
 
-	for _, o := range opt {
+	declared := make([]*worker, len(opt))
+	for i, o := range opt {
 		w, err := newWorker(o)
 		if err != nil {
 			return err
 		}
 
 		totalThreadsToStart += w.num
+		declared[i] = w
 		workers = append(workers, w)
-		workersByName[w.name] = w
+		// Background workers are resolved per-scope via backgroundLookups
+		// so the same user-facing name can appear in multiple scopes
+		// without colliding in the global workersByName map.
+		if w.bg == nil {
+			workersByName[w.name] = w
+		}
 		if w.allowPathMatching {
 			workersByPath[w.fileName] = w
 		}
 	}
 
+	// Build the per-scope lookups (named + catch-all per scope). Each
+	// php_server block gets its own scope; the global/embed scope is 0.
+	// Each declaration registers in its scope's lookup so lazy-start
+	// siblings inherit the template options.
+	var err error
+	backgroundLookups, err = buildBackgroundWorkerLookups(declared, opt)
+	if err != nil {
+		return err
+	}
+
 	startupFailChan = make(chan error, totalThreadsToStart)
 
 	for _, w := range workers {
 		for i := 0; i < w.num; i++ {
 			thread := getInactivePHPThread()
-			convertToWorkerThread(thread, w)
+			if w.bg != nil {
+				convertToBackgroundWorkerThread(thread, w, w.name, w.bg.ready)
+			} else {
+				convertToWorkerThread(thread, w)
+			}
 
 			workersReady.Go(func() {
 				thread.state.WaitFor(state.Ready, state.ShuttingDown, state.Done)
@@ -121,21 +146,32 @@ func newWorker(o workerOpt) (*worker, error) {
 	}
 
 	// workers that have a name starting with "m#" are module workers
-	// they can only be matched by their name, not by their path
-	allowPathMatching := !strings.HasPrefix(o.name, "m#")
-
-	if w := workersByPath[absFileName]; w != nil && allowPathMatching {
-		return w, fmt.Errorf("two workers cannot have the same filename: %q", absFileName)
-	}
-	if w := workersByName[o.name]; w != nil {
-		return w, fmt.Errorf("two workers cannot have the same name: %q", o.name)
+	// they can only be matched by their name, not by their path.
+	// Background workers are matched only by name, never by path, since
+	// they don't handle HTTP requests.
+	allowPathMatching := !strings.HasPrefix(o.name, "m#") && !o.isBackgroundWorker
+
+	// Background workers are matched only by name, never by path. Multiple
+	// named bg workers can share an entrypoint file; uniqueness is enforced
+	// per-scope via backgroundLookups, not at the global path level.
+	if !o.isBackgroundWorker {
+		if w := workersByPath[absFileName]; w != nil && allowPathMatching {
+			return w, fmt.Errorf("two workers cannot have the same filename: %q", absFileName)
+		}
+		// Background workers are resolved through per-scope lookups, not the
+		// global workersByName map; the same user-facing name can appear in
+		// multiple php_server scopes without collision.
+		if w := workersByName[o.name]; w != nil {
+			return w, fmt.Errorf("two workers cannot have the same name: %q", o.name)
+		}
 	}
 
 	if o.env == nil {
-		o.env = make(PreparedEnv, 1)
+		o.env = make(PreparedEnv)
 	}
 
-	o.env["FRANKENPHP_WORKER\x00"] = "1"
+	// $_SERVER['FRANKENPHP_WORKER'] is populated downstream from
+	// fc.worker.name via frankenphp_register_server_vars.
 	w := &worker{
 		name:                   o.name,
 		fileName:               absFileName,
@@ -148,10 +184,17 @@ func newWorker(o workerOpt) (*worker, error) {
 		maxConsecutiveFailures: o.maxConsecutiveFailures,
 		onThreadReady:          o.onThreadReady,
 		onThreadShutdown:       o.onThreadShutdown,
+		scope:                  o.scope,
+	}
+	if o.isBackgroundWorker {
+		w.bg = &backgroundWorkerExtras{ready: newBackgroundWorkerState()}
 	}
 
 	w.configureMercure(&o)
 
+	// o.env is shared by reference across instances; treat it as
+	// read-only after init. Deep-clone if per-instance env is ever
+	// needed.
 	w.requestOptions = append(
 		w.requestOptions,
 		WithRequestDocumentRoot(filepath.Dir(o.fileName), false),
@@ -172,9 +215,16 @@ var drainGracePeriod = 30 * time.Second
 // Blocks until every drained thread yields. Force-kill is armed after a
 // grace period to wake threads parked in blocking syscalls (sleep, I/O).
 func DrainWorkers() {
+	// Defensive RLock paired with RestartWorkers' scalingMu.Lock to
+	// guard against future runtime mutators of the workers slice.
+	scalingMu.RLock()
+	defer scalingMu.RUnlock()
 	_ = drainWorkerThreads()
 }
 
+// drainWorkerThreads walks the global workers slice. The caller must
+// ensure no concurrent mutation of the slice (either hold scalingMu or
+// be called from a context where scaling is paused).
 func drainWorkerThreads() (drainedThreads []*phpThread) {
 	var ready sync.WaitGroup
 
@@ -255,6 +305,27 @@ func (worker *worker) attachThread(thread *phpThread) {
 	worker.threadMutex.Unlock()
 }
 
+// invalidateBackgroundEntry releases the registry slot held by a bg
+// worker exiting on max_consecutive_failures so a future ensure() can
+// lazy-spawn a fresh thread. Single-instance only (catch-all instances,
+// lazy named).
+func (worker *worker) invalidateBackgroundEntry(name string) {
+	bg := worker.bg
+	if bg.catchAllNames != nil {
+		bg.catchAllMu.Lock()
+		delete(bg.catchAllNames, name)
+		bg.catchAllMu.Unlock()
+		return
+	}
+	if worker.num == 0 {
+		// Fresh slot so the retry isn't poisoned by the prior abort.
+		bg.lazyMu.Lock()
+		bg.ready = newBackgroundWorkerState()
+		bg.lazyStarted = false
+		bg.lazyMu.Unlock()
+	}
+}
+
 func (worker *worker) detachThread(thread *phpThread) {
 	worker.threadMutex.Lock()
 	for i, t := range worker.threads {