From 95db7ba527aa47a5e0131651abb63197e64b4bb2 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 14:32:51 +0200
Subject: [PATCH 01/44] docs(stack): align runtime architecture documentation

---
 docs/adr/0010-process-manager-architecture.md |   29 -
 .../adr/0012-compiled-bun-runtime-dispatch.md |   72 -
 .../0013-live-e2e-bypasses-replay-server.md   |    5 +-
 docs/adr/README.md                            |    2 -
 packages/process-compose/README.md            |   49 +-
 packages/process-compose/docs/architecture.md | 1088 +++----------
 packages/stack/README.md                      |   31 +-
 packages/stack/docs/architecture.md           | 1394 +++--------------
 packages/stack/docs/detach-mode.md            |  620 ++------
 packages/stack/src/daemon-node.ts             |    3 +
 packages/stack/src/node.ts                    |    8 +-
 11 files changed, 640 insertions(+), 2661 deletions(-)
 delete mode 100644 docs/adr/0010-process-manager-architecture.md
 delete mode 100644 docs/adr/0012-compiled-bun-runtime-dispatch.md

diff --git a/docs/adr/0010-process-manager-architecture.md b/docs/adr/0010-process-manager-architecture.md
deleted file mode 100644
index f988489d14..0000000000
--- a/docs/adr/0010-process-manager-architecture.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# 0010. Process Manager Architecture
-
-**Status**: proposed
-**Date**: 2026-02-10
-
-## Problem Statement
-
-ADR 0004 identifies the process manager as "significant infrastructure to build and maintain" for the local-first workflow. `PLAN_PROCESS_COMPOSE.md` exists as an implementation plan but isn't part of the ADR system.
-
-The plan ports a subset of process-compose (Go) to TypeScript. Scope includes: HTTP API server, log output, start/stop/status/shutdown. Explicitly excludes: TUI, WebSocket streaming, scaling, namespaces, scheduling, hot-reload.
-
-## Key Decisions to Cover
-
-- **Why port process-compose to TypeScript** instead of: (a) using the Go binary directly, (b) using Docker Compose, (c) building from scratch without process-compose's model
-- **Process lifecycle**: YAML config format, dependency resolution (`depends_on` with `process_healthy` / `process_completed_successfully`), readiness probes (exec, HTTP GET)
-- **Signal handling**: How SIGTERM/SIGINT propagate to child processes, graceful shutdown ordering
-- **HTTP API**: Endpoints, what `supabase dev` calls, how the TUI (React-Ink) connects to it
-- **Logging**: Per-process log files, log rotation, how logs surface in the TUI
-- **Health checks**: Probe types, intervals, failure thresholds, restart policies
-- **Embedded binaries vs Docker containers**: How native binaries and Docker containers coexist
-
-## Related Decisions
-
-- [ADR 0004](0004-cli-design-goals-and-workflows.md): CLI Design Goals — local-first workflow, `supabase dev` orchestrator
-- [ADR 0007](0007-realtime-progress-in-command-handlers.md): Real-time Progress — progress reporting from process manager phases
-
-## See Also
-
-- [PLAN_PROCESS_COMPOSE.md](../../PLAN_PROCESS_COMPOSE.md): Detailed implementation plan
diff --git a/docs/adr/0012-compiled-bun-runtime-dispatch.md b/docs/adr/0012-compiled-bun-runtime-dispatch.md
deleted file mode 100644
index 4795a1168a..0000000000
--- a/docs/adr/0012-compiled-bun-runtime-dispatch.md
+++ /dev/null
@@ -1,72 +0,0 @@
-# 0012. Compiled Bun Runtime Dispatch
-
-**Status**: proposed
-**Date**: 2026-05-13
-
-## Problem Statement
-
-ADR 0011 chooses Bun `--compile` single-file executables as the TypeScript CLI packaging format. That artifact shape matches the existing Go CLI distribution model, but compiled Bun does not behave exactly like `bun <script>` when a process tries to launch another TypeScript entrypoint.
-
-In Bun JIT mode, `process.execPath` is the Bun runtime, so `child_process.fork(entrypoint)` effectively runs `bun <entrypoint>`. In a compiled executable, `process.execPath` is the CLI binary itself. Passing a script path as argv re-enters the compiled binary's baked entrypoint instead of running that script. Detached daemon startup and process supervision therefore need an explicit dispatch contract.
-
-Compiled Bun also makes runtime source paths and dynamic native bindings different from a checkout. Source files can live in Bun's embedded filesystem, optional native packages are only included when they are statically referenced, and code that expects a stable filesystem path can fail at runtime.
-
-This surfaced in:
-
-- [CLI-1452](https://linear.app/supabase/issue/CLI-1452/compiled-bun-compile-next-binary-cant-run-supabase-functions-dev): the next binary could not run `supabase functions dev` because `@parcel/watcher` native bindings and the Edge Runtime bootstrap were not safe under the compiled binary.
-- [CLI-1453](https://linear.app/supabase/issue/CLI-1453/compiled-bun-compile-next-binary-start-detach-daemon-fork-ignores): `supabase start --detach` failed because the daemon fork re-entered the CLI entrypoint instead of the daemon entrypoint.
-
-## Decision
-
-Compiled-binary dispatch is explicit and owned by the layer that owns the process being launched:
-
-- The CLI/stack layer owns Supabase-specific daemon dispatch. `forkDaemon` marks daemon children with `SUPABASE_STACK_RUN_DAEMON=1`; the compiled next CLI entrypoint checks that marker and runs the Bun daemon entrypoint in-process.
-- `@supabase/process-compose` owns generic supervisor dispatch. Supervised services are launched through `process.execPath`; when the library is bundled into a compiled Bun binary, a small internal environment protocol asks the same binary to run the supervisor runtime path.
-- The supervisor runtime and protocol stay as native `.ts` source files. Bun and supported Node versions can run them directly, so process-compose does not need a JavaScript sidecar or Supabase-specific code.
-- Native watcher packages are referenced through static literal `require("@parcel/watcher-...")` calls so Bun can include the platform optional dependencies in compiled binaries.
-- The Edge Runtime bootstrap source is embedded with Bun's text import attribute and written to the runtime temp directory before launch, instead of being read from a source path that may live inside Bun's embedded filesystem.
-- The next CLI e2e harness runs against the compiled `supabase-next` binary so regressions are caught against the same artifact users run.
-
-## Rationale
-
-The compiled binary is the public artifact, so child-process behavior must be designed around that artifact rather than around development-mode script launching.
-
-Environment markers keep the contract small and side-effect free:
-
-- They do not depend on argv shape that compiled Bun ignores.
-- They let the compiled binary self-dispatch without extracting sidecar JavaScript files.
-- They keep Supabase-specific daemon knowledge out of the generic process-compose package.
-
-Using `process.execPath` in process-compose preserves runtime symmetry. If the library runs under Bun, it forks Bun; if it runs under Node, it forks Node. The only compiled-Bun-specific behavior is the self-dispatch marker, which is internal to the process-compose runtime contract.
-
-Static native imports and text-embedded bootstrap source avoid relying on filesystem paths that are not stable after `bun --compile`.
-
-## Consequences
-
-### Positive
-
-- Detached stack commands and supervised services work from the compiled next CLI binary.
-- Process-compose remains a generic Node/Bun supervision library, not a Supabase CLI adapter.
-- The e2e suite now exercises the distributed binary for next CLI workflows.
-
-### Negative
-
-- The environment variable names are internal contracts and must be changed carefully.
-- Native dependencies used by compiled binaries need static literal references; dynamic native resolution is unsafe.
-- Source files that must exist at runtime need explicit embedding or extraction.
-
-## Alternatives Considered
-
-1. **Keep relying on script-path argv**: rejected because compiled Bun ignores this shape and re-enters the baked entrypoint.
-2. **Ship sidecar JavaScript runtime files**: rejected for now because it adds release artifacts and path management that `process.execPath` self-dispatch avoids.
-3. **Move Supabase daemon knowledge into process-compose**: rejected because process-compose is a generic supervision library.
-4. **Use dynamic `@parcel/watcher` resolution**: rejected because Bun cannot reliably include platform optional native packages from dynamic require paths.
-
-## Related Decisions
-
-- [ADR 0011](0011-cli-release-and-distribution-strategy.md): CLI Release & Distribution Strategy
-- [ADR 0010](0010-process-manager-architecture.md): Process Manager Architecture
-
-## See Also
-
-- [Detached mode](../../packages/stack/docs/detach-mode.md)
diff --git a/docs/adr/0013-live-e2e-bypasses-replay-server.md b/docs/adr/0013-live-e2e-bypasses-replay-server.md
index 097bb467df..9b0c758818 100644
--- a/docs/adr/0013-live-e2e-bypasses-replay-server.md
+++ b/docs/adr/0013-live-e2e-bypasses-replay-server.md
@@ -123,8 +123,9 @@ independent green signals instead of one averaged result.
 
 ## Related Decisions
 
-- [ADR 0012](0012-compiled-bun-runtime-dispatch.md): Compiled Bun Runtime Dispatch
-  (the next CLI e2e harness runs against the compiled binary)
+- [Compiled Bun self-dispatch](../../packages/process-compose/docs/architecture.md#compiled-bun-self-dispatch):
+  the next CLI e2e harness runs against the compiled binary and therefore exercises its process
+  re-entry contract
 - [ADR 0011](0011-cli-release-and-distribution-strategy.md): CLI Release & Distribution Strategy
 
 ## See Also
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 91deb69cea..90f4694b45 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -53,9 +53,7 @@ When an ADR becomes outdated, mark it as `deprecated` or reference the supersedi
 | 0007 | [Real-time Progress in Command Handlers](0007-realtime-progress-in-command-handlers.md)  | proposed |
 | 0008 | [Authentication & Token Management](0008-authentication-and-token-management.md)        | proposed |
 | 0009 | [Configuration Schema & Validation](0009-configuration-schema-and-validation.md)         | proposed |
-| 0010 | [Process Manager Architecture](0010-process-manager-architecture.md)                     | proposed |
 | 0011 | [CLI Release & Distribution Strategy](0011-cli-release-and-distribution-strategy.md)     | proposed |
-| 0012 | [Compiled Bun Runtime Dispatch](0012-compiled-bun-runtime-dispatch.md)                   | proposed |
 | 0013 | [Live E2E Tests Bypass the Replay Server](0013-live-e2e-bypasses-replay-server.md)       | proposed |
 
 ## Template
diff --git a/packages/process-compose/README.md b/packages/process-compose/README.md
index 30a605d991..713ba10f12 100644
--- a/packages/process-compose/README.md
+++ b/packages/process-compose/README.md
@@ -1,32 +1,39 @@
-# @supabase/process-compose
+# `@supabase/process-compose`
 
-TypeScript port of [process-compose](https://github.com/F1bonacc1/process-compose) for Bun. Orchestrates multiple processes with health checks, an HTTP API, and structured logging. Zero runtime dependencies.
+An Effect-based TypeScript library for supervising dependency-ordered process graphs under Bun or
+Node.js.
 
-## Usage
-
-As a library:
+The package accepts in-memory `ServiceDef` values and provides lifecycle control, readiness,
+health probes, restart policies, state streams, log streams, and optional orphan supervision. It
+does not expose a CLI, parse YAML, or run an HTTP server.
 
 ```ts
-import { createProcessCompose } from "@supabase/process-compose";
-
-const pc = await createProcessCompose({
-  configPath: "process-compose.yaml",
-  apiPort: 8080,
-});
-
-await pc.start();
+import { buildGraph, Orchestrator } from "@supabase/process-compose";
+import { Effect } from "effect";
+
+const graph = await Effect.runPromise(
+  buildGraph([
+    { name: "database", command: "postgres" },
+    {
+      name: "api",
+      command: "api-server",
+      dependencies: [{ service: "database", condition: "healthy" }],
+    },
+  ]),
+);
+
+// Orchestrator.layer(graph) requires a LogBuffer layer and the caller's
+// ChildProcessSpawner Adapter.
+const orchestratorLayer = Orchestrator.layer(graph);
 ```
 
-As a CLI:
-
-```sh
-bun run packages/process-compose/src/cli.ts -f process-compose.yaml
-```
+See [the architecture guide](./docs/architecture.md) for the lifecycle, supervision, and compiled
+runtime contracts.
 
 ## Development
 
 ```sh
-pnpm run check:all   # Run all quality checks in parallel
-pnpm run fix:all     # Auto-fix lint, format, and unused exports in parallel
-pnpm run test        # Run tests
+pnpm check:all
+pnpm fix:all
+pnpm test:core
 ```
diff --git a/packages/process-compose/docs/architecture.md b/packages/process-compose/docs/architecture.md
index 309779363c..a7b97e0f5a 100644
--- a/packages/process-compose/docs/architecture.md
+++ b/packages/process-compose/docs/architecture.md
@@ -1,949 +1,267 @@
 # Architecture of `@supabase/process-compose`
 
-A service orchestrator that manages a dependency graph of long-running processes with health checks, log streaming, restart policies, and graceful shutdown. Built on [Effect V4](https://effect.website).
+`@supabase/process-compose` supervises an in-memory dependency graph of operating-system
+processes. It is a generic Effect Module: it has no Supabase service knowledge, project-file
+parser, CLI, or management HTTP server.
 
-## Table of contents
+## Why the process manager is TypeScript
 
-- [High-level overview](#high-level-overview)
-- [Effect primer for newcomers](#effect-primer-for-newcomers)
-- [Components](#components)
-  - [ServiceDef — configuration](#servicedef--configuration)
-  - [ServiceState — state machine](#servicestate--state-machine)
-  - [ServiceTransition — enforced state machine](#servicetransition--enforced-state-machine)
-  - [errors — typed error hierarchy](#errors--typed-error-hierarchy)
-  - [DependencyGraph — ordering engine](#dependencygraph--ordering-engine)
-  - [LogBuffer — log capture and streaming](#logbuffer--log-capture-and-streaming)
-  - [HealthProbe — health checking](#healthprobe--health-checking)
-  - [Orchestrator — the coordinator](#orchestrator--the-coordinator)
-- [Why Effect?](#why-effect)
-- [Data flow](#data-flow)
+The local stack needs one lifecycle model for native executables and Docker-backed processes, plus
+in-process access to typed state streams, log streams, lifecycle hooks, and scoped cleanup. Keeping
+that model in TypeScript lets `@supabase/stack` compose it directly with Effect resources without
+maintaining a second configuration and transport protocol to a Go process-manager binary. Docker
+Compose would make Docker the orchestration model and would prevent the native-first and
+sandbox-friendly runtime. The package borrows useful process-compose concepts—dependency
+conditions, health checks, and restart policies—but deliberately implements only the library
+capabilities needed by current callers.
 
----
-
-## High-level overview
-
-You give process-compose a list of service definitions ("run postgres on port 5432, then start the API once postgres is healthy"). It figures out the right startup order, spawns each process, monitors health, captures logs, and tears everything down cleanly when you ask it to stop.
+## Module map
 
 ```mermaid
-graph TB
-    subgraph Input
-        Config["ServiceDef[]<br/><i>what to run</i>"]
-    end
-
-    subgraph Core
-        DG["DependencyGraph<br/><i>start/stop ordering</i>"]
-        ORC["Orchestrator<br/><i>lifecycle coordinator</i>"]
-        FSM["ServiceTransition<br/><i>validated state machine</i>"]
-    end
-
-    subgraph Runtime
-        FM["FiberMap<br/><i>one fiber per service</i>"]
-        CPS["ChildProcessSpawner<br/><i>spawn OS processes</i>"]
-    end
-
-    subgraph Observation
-        SS["ServiceState<br/><i>per-service state</i>"]
-        LB["LogBuffer<br/><i>log capture + streaming</i>"]
-        HP["HealthProbe<br/><i>HTTP / exec / TCP checks</i>"]
-    end
-
-    Config --> DG
-    DG --> ORC
-    ORC --> FM
-    FM --> CPS
-    CPS --> LB
-    CPS --> HP
-    HP --> FSM
-    ORC --> FSM
-    FSM --> SS
-```
-
-The library has no CLI, no config file parser, and no HTTP server. It is a pure TypeScript library that exposes an `Orchestrator` service — consumers build their own interface on top.
-
----
-
-## Effect primer for newcomers
-
-process-compose uses several primitives from the Effect library. If you've never seen Effect before, here's a quick mental model for each one. You don't need to understand them deeply to read this document — just enough to follow the "why" behind each design choice.
-
-### Effect
-
-A lazy, composable description of work. Think of it as a `Promise` that hasn't started yet. You can chain operations, handle errors, and add timeouts — all before anything actually runs. Nothing happens until a "runner" executes the description.
-
-```
-Promise:  const result = await fetchUser(id);          // runs immediately
-Effect:   const program = fetchUser(id);                // just a description
-          const result = await Effect.runPromise(program); // runs here
-```
-
-### Fiber
-
-A lightweight green thread managed by the Effect runtime. While an OS thread costs ~1 MB of stack, a fiber costs a few hundred bytes. The runtime multiplexes thousands of fibers onto a small pool of OS threads.
-
-Why this matters for process-compose: we run one fiber per managed service. If you're orchestrating 50 services, that's 50 fibers — trivial for the runtime, but 50 OS threads would be wasteful. More importantly, fibers support **structured concurrency**: when a parent fiber is interrupted, all its children are interrupted too. This is how we guarantee no process is ever leaked.
-
-### Layer and Context.Service
-
-Effect's dependency injection system. A `Layer` is a recipe for building a service and its dependencies. `Context.Service` is the base class for declaring a service interface (what methods it provides) and its implementation (a `Layer` that creates those methods).
-
-In process-compose, `Orchestrator`, `LogBuffer`, and `Browser` are all services. Tests swap in mock implementations via `Layer.succeed(ServiceTag, mockImpl)` — no monkey-patching globals, no `jest.mock()`.
-
-### Deferred
-
-A one-shot async signal. Like a `Promise` you resolve manually: anyone can `await` it, and the first call to `succeed` or `fail` resolves all waiters.
-
-```
-const gate = Deferred.make<void>();
-
-// In fiber A (waiter):
-yield* Deferred.await(gate);   // blocks until resolved
-
-// In fiber B (signaler):
-yield* Deferred.succeed(gate, void 0);  // unblocks A
-```
-
-process-compose uses `Deferred` for local, one-shot coordination, such as racing a process exit against an unhealthy-restart request. Durable lifecycle coordination uses the service's state stream instead: a `Deferred` cannot represent repeated start/restart generations without replacing the object that existing waiters reference.
-
-### SubscriptionRef
-
-A mutable cell that broadcasts every update as a `Stream`. Readers can either snapshot the current value (`getUnsafe`) or subscribe to a stream of all future changes (`changes`).
-
-```
-const ref = yield* SubscriptionRef.make(0);
-
-// Writer:
-yield* SubscriptionRef.set(ref, 42);
-
-// Reader (snapshot):
-const value = SubscriptionRef.getUnsafe(ref);  // 42
-
-// Reader (live stream):
-const stream = SubscriptionRef.changes(ref);   // Stream of 0, 42, ...
-```
-
-Each service has one stable `SubscriptionRef<ServiceState>` for its entire lifetime. The Orchestrator updates it on state transitions; dependencies, readiness waiters, shutdown ordering, and consumers all subscribe to the same stream. `SubscriptionRef.changes` emits the current value first, so a waiter cannot miss a transition that happened just before it subscribed.
-
-### FiberMap
-
-A concurrent `Map<Key, Fiber>` with a crucial property: **removing a key interrupts its fiber**, which triggers all registered finalizers (cleanup logic). When the FiberMap's scope closes, _all_ entries are interrupted.
-
-This is the single most important data structure in process-compose. Each service gets one entry in the FiberMap:
-
-- **Start a service**: `FiberMap.run(fibers, "postgres", runService(pgDef))` — forks a fiber and stores it
-- **Stop a service**: `FiberMap.remove(fibers, "postgres")` — interrupts the fiber, which triggers `Effect.addFinalizer` to send SIGTERM/SIGKILL to the OS process
-- **Stop everything**: close the scope — FiberMap auto-interrupts all entries
-
-### Stream and PubSub
-
-`Stream` is a pull-based sequence of values, like an async iterator. `PubSub` is a bounded, backpressure-aware fan-out channel: one publisher, many subscribers, each getting their own queue.
-
-LogBuffer uses `PubSub` internally: when a service writes a log line, it's published once and delivered to every active subscriber (a TUI panel, a log file writer, etc.) independently.
-
-### Graph
-
-Effect's directed graph data structure with built-in topological sort. We build a graph where nodes are services and edges represent dependencies (edge from A to B means "A must start before B"). `Graph.topo()` gives us the correct startup order; reversing it gives shutdown order.
-
-### Data.Class and Data.TaggedError
-
-Immutable value types with built-in **structural equality**. Two `ServiceState` objects with the same fields are `===` equal, which is critical for `SubscriptionRef` — it only emits a change notification when the value actually differs.
-
-`Data.TaggedError` adds a `_tag` field for type-safe pattern matching:
-
-```ts
-class SpawnError extends Data.TaggedError("SpawnError")<{ service: string; cause: unknown }> {}
-class ServiceNotFoundError extends Data.TaggedError("ServiceNotFoundError")<{ name: string }> {}
-
-// Pattern matching:
-effect.pipe(
-  Effect.catch("SpawnError", (e) => ...),
-  Effect.catch("ServiceNotFoundError", (e) => ...),
-)
+flowchart LR
+    Def["ServiceDef values"] --> Graph["DependencyGraph"]
+    Graph --> Orch["Orchestrator"]
+    Orch --> Spawn["ChildProcessSpawner Adapter"]
+    Orch --> State["ServiceState streams"]
+    Orch --> Logs["LogBuffer"]
+    Orch --> Probe["HealthProbe"]
+    Orch --> Supervisor["Optional supervisor runtime"]
+    Probe --> Transition["ServiceTransition"]
+    Orch --> Transition
 ```
 
----
-
-## Components
+The public package export is `src/index.ts`. The principal Interface is `Orchestrator`; callers
+construct its layer from a validated `ResolvedGraph`, a `ChildProcessSpawner` Adapter, and a shared
+`LogBuffer`.
 
-### ServiceDef — configuration
+## Service definitions and dependency graph
 
-**File:** `src/ServiceDef.ts`
+`ServiceDef` describes one process:
 
-Pure TypeScript interfaces with no Effect imports (except for the `ChildProcess.Signal` type). This is the user-facing API for defining what to run.
+- executable, arguments, environment, and working directory;
+- dependencies and a dependency wait timeout;
+- optional HTTP, TCP, or exec health check;
+- shutdown signal and grace period;
+- restart policy and restart budget;
+- `started` and `healthy` lifecycle hooks;
+- in-process cleanup and optional external orphan supervision.
 
-```ts
-interface ServiceDef {
-  name: string; // unique identifier
-  command: string; // executable path
-  args?: string[]; // command arguments
-  env?: Record<string, string>;
-  cwd?: string;
-  dependencies?: Dependency[];
-  dependencyTimeoutSeconds?: number; // max wait for deps (default: 30)
-  healthCheck?: HealthCheckConfig;
-  shutdown?: ShutdownConfig;
-  restart?: RestartPolicy; // "no" | "on-failure" | "always" | "unless-stopped"
-  maxRestarts?: number;
-  enabled?: boolean;
-  hooks?: LifecycleHook[];
-}
-```
+`buildGraph()` removes definitions with `enabled: false`, validates every referenced dependency,
+rejects cycles, and returns topological start and reverse-topological stop orders. Dependencies use
+one of three conditions:
 
-**Dependency conditions** control when a dependent service is allowed to start:
+| Condition   | Satisfied when                                                                                     |
+| ----------- | -------------------------------------------------------------------------------------------------- |
+| `started`   | The dependency is desired to run and has spawned, is healthy/unhealthy, or completed successfully. |
+| `healthy`   | The dependency is desired to run and currently `Healthy`.                                          |
+| `completed` | The dependency reached `Stopped` with exit code `0`; a non-zero completion fails the dependent.    |
 
-| Condition   | Meaning                                   | Use case                                     |
-| ----------- | ----------------------------------------- | -------------------------------------------- |
-| `started`   | The dependency's process has been spawned | Services that just need the port to be bound |
-| `healthy`   | The dependency's health check is passing  | Services that need a fully-ready database    |
-| `completed` | The dependency has exited with code 0     | One-shot setup scripts (migrations, seeding) |
+`startService(name)` starts the requested definition and its transitive dependencies.
+`stopService(name)` and `restartService(name)` also include active dependents so a caller cannot
+leave an already-running dependent attached to a restarted dependency.
 
-**Health check probes** come in three flavors:
+`updateServiceDefinition(name, replacement)` validates a graph with the replacement and then swaps
+the graph used for subsequent starts and restarts. It does not mutate a process generation that is
+already running. The replacement name is normalized to the selected name.
 
-- **HTTP**: `fetch()` to a host:port/path — success if response is 2xx
-- **Exec**: runs the configured command with explicit args — success if exit code is 0
-- **TCP**: opens a TCP connection to a host:port — success if the connection is established
+## Desired state and observed state
 
-**Lifecycle hooks** run effects at specific service lifecycle points. The `HookTrigger` determines when a hook fires, and the `LifecycleHook` interface describes what runs:
+Each definition owns one stable `SubscriptionRef<ServiceState>` for the lifetime of the
+orchestrator. State contains both observed lifecycle status and caller-owned intent:
 
 ```ts
-type HookTrigger = "started" | "healthy";
-
-// Callback injected into each hook — writes a message to the service's log buffer
-type HookLog = (message: string) => Effect<void>;
-
-interface LifecycleHook {
-  on: HookTrigger;
-  run: (log: HookLog) => Effect<void, unknown>; // log writes to the service's log stream
-  timeoutSeconds?: number; // default: 30
-  failurePolicy?: "fail" | "ignore"; // default: "fail"
+type ServiceDesiredState = "inactive" | "running" | "stopped";
+
+interface ServiceState {
+  readonly name: string;
+  readonly status:
+    | "Pending"
+    | "Starting"
+    | "Running"
+    | "Healthy"
+    | "Unhealthy"
+    | "Stopping"
+    | "Stopped"
+    | "Failed"
+    | "Restarting";
+  readonly pid: number | null;
+  readonly exitCode: number | null;
+  readonly restartCount: number;
+  readonly startedAt: number | null;
+  readonly error: string | null;
+  readonly desired: ServiceDesiredState;
 }
 ```
 
-**Defaults** are defined as a const object and applied where config values are omitted:
-
-| Setting                        | Default                                 |
-| ------------------------------ | --------------------------------------- |
-| `restart`                      | `"unless-stopped"`                      |
-| `maxRestarts`                  | `0` (unlimited when restart is enabled) |
-| `dependencyTimeoutSeconds`     | `30`                                    |
-| `shutdown.signal`              | `SIGTERM`                               |
-| `shutdown.timeoutSeconds`      | `10`                                    |
-| `shutdownTimeoutSeconds`       | `60`                                    |
-| `healthCheck.periodSeconds`    | `10`                                    |
-| `healthCheck.timeoutSeconds`   | `2`                                     |
-| `healthCheck.successThreshold` | `1`                                     |
-| `healthCheck.failureThreshold` | `3`                                     |
-| `hookTimeoutSeconds`           | `30`                                    |
-
----
-
-### ServiceState — state machine
-
-**File:** `src/ServiceState.ts`
-
-Each service tracks its runtime state as an immutable `Data.Class`:
-
-```ts
-class ServiceState extends Data.Class<{
-  name: string;
-  status: ServiceStatus;
-  pid: number | null;
-  exitCode: number | null;
-  restartCount: number;
-  startedAt: number | null;
-  error: string | null;
-}> {}
-```
-
-The status field follows this state machine:
-
-```mermaid
-stateDiagram-v2
-    [*] --> Pending
-    Pending --> Starting : DependenciesSatisfied
-    Pending --> Failed : DependencyFailed
-    Pending --> Stopped : StopRequested
-    Starting --> Running : ProcessSpawned
-    Starting --> Stopping : StopRequested
-    Running --> Healthy : HealthCheckPassed<br/>(or no health check)
-    Running --> Stopped : ProcessExited (code 0)
-    Running --> Failed : ProcessExited (code ≠ 0)
-    Running --> Stopping : StopRequested
-    Healthy --> Unhealthy : HealthCheckFailed
-    Healthy --> Healthy : HealthCheckPassed (no-op)
-    Unhealthy --> Healthy : HealthCheckPassed
-    Healthy --> Stopped : ProcessExited (code 0)
-    Healthy --> Failed : ProcessExited (code ≠ 0)
-    Unhealthy --> Stopped : ProcessExited (code 0)
-    Unhealthy --> Failed : ProcessExited (code ≠ 0)
-    Healthy --> Stopping : StopRequested
-    Unhealthy --> Stopping : StopRequested
-    Stopping --> Stopped : ProcessExited
-    Stopped --> Restarting : RestartTriggered
-    Failed --> Restarting : RestartTriggered
-    Unhealthy --> Restarting : RestartTriggered
-    Restarting --> Starting : BackoffElapsed
-    Restarting --> Stopped : StopRequested
-```
-
-**Why `Data.Class`?** Two `ServiceState` instances with identical fields are structurally equal. This means `SubscriptionRef` can detect when a state update actually changes something — subscribers only receive notifications for real transitions, not redundant updates.
-
----
-
-### ServiceTransition — enforced state machine
-
-**File:** `src/ServiceTransition.ts`
-
-State transitions are **enforced at runtime**, not just documented. Every state change goes through a validated finite state machine (FSM) that rejects illegal transitions.
-
-#### Why an FSM?
-
-Without enforcement, any code with access to the `SubscriptionRef<ServiceState>` could set any status from any other status. In a concurrent system with multiple mutation sources (process exit handlers, health probe callbacks, manual stop/restart), this leads to subtle bugs:
-
-- A health probe callback firing `Healthy` after a stop has already begun
-- A stop setting `Stopped` before the OS process has actually exited
-- Concurrent stop and restart racing to update the same state
-
-The FSM eliminates these by making illegal transitions return `null` instead of corrupting state.
-
-#### Events
-
-Instead of directly setting status strings, the Orchestrator sends typed events:
-
-| Event                   | Payload            | Meaning                                |
-| ----------------------- | ------------------ | -------------------------------------- |
-| `DependenciesSatisfied` | —                  | All dependency conditions met          |
-| `DependencyFailed`      | `error: string`    | A dependency exited with non-zero code |
-| `ProcessSpawned`        | `pid`, `startedAt` | OS process successfully created        |
-| `HealthCheckPassed`     | —                  | Health probe reports success           |
-| `HealthCheckFailed`     | —                  | Health probe reports failure           |
-| `HookFailed`            | `error: string`    | Lifecycle hook failed                  |
-| `ProcessExited`         | `exitCode: number` | OS process exited                      |
-| `StopRequested`         | —                  | Manual stop or shutdown initiated      |
-| `RestartTriggered`      | `restartCount`     | Restart policy decided to restart      |
-| `BackoffElapsed`        | —                  | Restart backoff timer completed        |
-
-#### Transition table
-
-The set of legal `(fromStatus, event)` pairs is defined as data:
-
-```ts
-const allowed = new Set([
-  "Pending:DependenciesSatisfied", // → Starting
-  "Pending:DependencyFailed", // → Failed
-  "Pending:StopRequested", // → Stopped (no process to kill)
-  "Starting:ProcessSpawned", // → Running
-  "Starting:StopRequested", // → Stopping
-  "Running:HealthCheckPassed", // → Healthy
-  "Running:HookFailed", // → Failed
-  "Running:ProcessExited", // → Stopped or Failed
-  "Running:StopRequested", // → Stopping
-  "Healthy:HealthCheckPassed", // → Healthy (no-op, structural eq)
-  "Healthy:HealthCheckFailed", // → Unhealthy
-  "Healthy:HookFailed", // → Failed
-  "Healthy:ProcessExited", // → Stopped or Failed
-  "Healthy:StopRequested", // → Stopping
-  "Unhealthy:HealthCheckPassed", // → Healthy
-  "Unhealthy:ProcessExited", // → Stopped or Failed
-  "Unhealthy:StopRequested", // → Stopping
-  "Stopping:ProcessExited", // → Stopped (always, any exit code)
-  "Stopped:RestartTriggered", // → Restarting
-  "Failed:RestartTriggered", // → Restarting
-  "Unhealthy:RestartTriggered", // → Restarting (kill process, restart)
-  "Restarting:StopRequested", // → Stopped (no process to kill)
-  "Restarting:BackoffElapsed", // → Starting
-]);
-```
-
-Any `(status, event)` pair not in this set is silently rejected — `applyEvent()` returns `null`. This is intentional: in a concurrent system, a health probe callback racing a shutdown is expected, not an error.
-
-#### Core functions
-
-```ts
-// Pure — computes new state or null if the transition is illegal
-const applyEvent = (state: ServiceState, event: ServiceEvent): ServiceState | null
-
-// Effectful — atomic validate-and-apply via SubscriptionRef's internal Semaphore
-const transition = (
-  ref: SubscriptionRef<ServiceState>,
-  event: ServiceEvent,
-): Effect<ServiceState | null>
-```
-
-`transition()` uses `SubscriptionRef.modifyEffect`, which holds a `Semaphore(1)` permit during the entire read-validate-write cycle. This guarantees that concurrent callers (e.g., a health probe and a manual stop) are serialized — one completes before the other starts. No explicit Queue or actor needed.
+`inactive` means the definition has not been requested, `running` means the caller wants the
+service maintained, and `stopped` records an explicit stop. Desired state is independent of
+intermediate observed states and is what prevents an explicit stop from being undone by restart
+policy.
 
-#### How invalid transitions are handled
+`ServiceState` extends `Data.Class`, so Effect's `Equal.equals` can compare values structurally. It
+does not make two separately allocated objects equal under JavaScript `===`, and
+`SubscriptionRef.set` is not itself a distinct-update filter. Callers that want to suppress
+redundant publications must compare before writing.
 
-When a health probe fires `HealthCheckPassed` but the service is already in `Stopping`:
+`ServiceTransition` is the only normal path for observed-status changes. `applyEvent()` rejects
+illegal `(status, event)` pairs by returning `null`; `transition()` applies a legal event atomically
+through `SubscriptionRef.modifyEffect`. Races such as a late health callback during shutdown are
+therefore ignored without corrupting state.
 
-1. `transition()` acquires the semaphore
-2. `applyEvent(Stopping, HealthCheckPassed)` → `null` (not in the allowed set)
-3. State is unchanged, `null` returned to caller
-4. Semaphore released
+## Lifecycle of one process generation
 
-The health probe's callback gets `null` back and moves on. No error thrown, no state corrupted. The probe fiber will be interrupted shortly anyway when the service's scope closes.
+For each requested definition, `Orchestrator` runs this sequence:
+
+1. Set desired state to `running` and install one lifecycle fiber in a `FiberMap`.
+2. Call `beforeStart`, if supplied. It runs once for initial startup and again before each restart
+   backoff, allowing a caller to reserve external resources.
+3. Wait for dependencies, bounded by `dependencyTimeoutSeconds` (default: 120 seconds).
+4. Transition to `Starting`.
+5. Call `beforeSpawn` immediately before every spawn. The stack uses it to release a reserved port
+   as late as possible. For a supervised Docker command there is still a spawn-to-container-bind
+   window because no supervisor/container bind handshake exists.
+6. Spawn either the configured process or its optional supervisor.
+7. Register a scoped finalizer before exposing `Running`.
+8. Run `started` hooks sequentially. Only successful hooks allow `ProcessSpawned` to publish
+   `Running`.
+9. Stream stdout and stderr into `LogBuffer`.
+10. Run the health loop, or run `healthy` hooks immediately when no health check exists, then
+    publish `Healthy`.
+11. Race process exit against an unhealthy-restart request and apply restart policy.
 
----
+The service keeps the same state stream across restart generations. Restart backoff is
+`min(30 seconds, 2^(restartCount - 1))`.
+
+### Lifecycle hooks
 
-### errors — typed error hierarchy
+Hooks are caller-supplied Effects triggered on `started` or `healthy`. Hooks for one trigger run in
+declaration order. Each hook has a timeout (default: 30 seconds) and either:
 
-**File:** `src/errors.ts`
+- `fail`: publish `HookFailed` and stop running later hooks for that trigger;
+- `ignore`: append a diagnostic log and continue.
 
-All errors extend `Data.TaggedError`, giving each a unique `_tag` discriminator for pattern matching:
+The supplied logger writes tagged stdout/stderr lines into the service's normal log stream.
 
-| Error                    | Tag                        | When raised                                                  |
-| ------------------------ | -------------------------- | ------------------------------------------------------------ |
-| `CyclicDependencyError`  | `"CyclicDependencyError"`  | `buildGraph()` detects a cycle in service dependencies       |
-| `MissingDependencyError` | `"MissingDependencyError"` | A service references a dependency that doesn't exist         |
-| `ServiceNotFoundError`   | `"ServiceNotFoundError"`   | `getState()`, `stopService()`, etc. called with unknown name |
-| `SpawnError`             | `"SpawnError"`             | `ChildProcessSpawner` fails to spawn the process             |
-| `ShutdownTimeoutError`   | `"ShutdownTimeoutError"`   | Graceful shutdown exceeds the configured timeout             |
+## Health and readiness
 
-Because these are in the Effect type system, the compiler tracks which functions can fail with which errors. A function returning `Effect<void, ServiceNotFoundError>` guarantees it can only fail with that specific error — no surprise exceptions at runtime.
+`HealthProbe` supports:
 
----
+- HTTP: successful for a 2xx response;
+- TCP: successful when a connection opens;
+- exec: successful for exit code `0`.
 
-### DependencyGraph — ordering engine
+After `initialDelaySeconds`, probes repeat every `periodSeconds`. Each attempt is bounded by
+`timeoutSeconds`; consecutive success and failure counters reset each other. The current
+implementation calls `onHealthy` after `successThreshold`, and calls `onUnhealthy` after
+`failureThreshold` only after that same process generation has first become healthy. Consequently,
+initial probe failures leave a service in `Running` rather than publishing `Unhealthy`; callers
+must not treat the current generic `waitReady` Interface as a startup deadline.
 
-**File:** `src/DependencyGraph.ts`
+`waitReady(name)` is intentionally unbounded. For long-running definitions it succeeds at
+`Healthy` and fails at a non-restarting terminal state. For `restart: "no"` one-shot definitions,
+successful completion is readiness. `waitAllReady()` considers only definitions whose desired
+state is `running`, so intentionally inactive definitions do not block lazy callers. Higher-level
+Modules own any finite user-facing deadline.
 
-Turns a flat list of `ServiceDef[]` into a `ResolvedGraph` that answers ordering questions.
+## Restart policies
 
-```mermaid
-graph LR
-    subgraph "Input: ServiceDef[]"
-        DB["db"]
-        API["api<br/><i>depends on: db (healthy)</i>"]
-        WEB["web<br/><i>depends on: api (started)</i>"]
-        WORKER["worker<br/><i>depends on: db (started)</i>"]
-    end
-
-    subgraph "Graph edges (dep → dependent)"
-        DB2["db"] --> API2["api"]
-        DB2 --> WORKER2["worker"]
-        API2 --> WEB2["web"]
-    end
-
-    subgraph "Topological sort (start order)"
-        direction LR
-        S1["1. db"] ~~~ S2["2. api"] ~~~ S3["3. worker"] ~~~ S4["4. web"]
-    end
-```
-
-**How it works:**
+| Policy           | Exit behavior                                        | Unhealthy behavior                                |
+| ---------------- | ---------------------------------------------------- | ------------------------------------------------- |
+| `no`             | Never restart.                                       | Leave the live process observable as `Unhealthy`. |
+| `on-failure`     | Restart non-zero exits.                              | Restart.                                          |
+| `always`         | Restart every exit.                                  | Restart.                                          |
+| `unless-stopped` | Restart every exit while desired state is `running`. | Restart.                                          |
 
-1. **Filter** disabled services (`enabled: false`)
-2. **Build** a directed graph where edges point from dependency to dependent (`db → api`)
-3. **Validate** — throw `MissingDependencyError` if a dependency references a non-existent service
-4. **Cycle check** — `Graph.isAcyclic()` before sorting; throw `CyclicDependencyError` if cyclic
-5. **Topological sort** — `Graph.topo()` yields dependencies before their dependents
+`maxRestarts: 0` means unlimited restarts when the selected policy allows one. Manual stop first
+sets desired state to `stopped`, so it does not re-enter the restart loop.
 
-The `ResolvedGraph` interface exposes five operations:
+## Shutdown and cleanup ownership
 
-| Method                 | Purpose                                                    |
-| ---------------------- | ---------------------------------------------------------- |
-| `startOrder`           | All services in topological order (dependencies first)     |
-| `stopOrder`            | Reverse of startOrder (dependents stopped first)           |
-| `startOrderFor(name)`  | Only the transitive dependency chain for one service       |
-| `dependenciesOf(name)` | Direct dependencies with their conditions                  |
-| `dependentsOf(name)`   | Direct dependents of a service (reverse of dependenciesOf) |
+Removing a service from the `FiberMap`, clearing the map, or closing the orchestrator scope
+interrupts its lifecycle fiber. The generation finalizer:
 
-`startOrderFor("web")` does a DFS on reverse adjacency from the `web` node, collecting `db`, `api`, and `web` — but not `worker`. This powers selective startup: `orchestrator.startService("web")` only starts what `web` actually needs.
+1. sends the configured shutdown signal (default `SIGTERM`);
+2. waits for the configured per-process timeout (default 10 seconds);
+3. falls back to `SIGKILL`;
+4. runs the in-process `cleanup` Effect.
 
----
+Whole-graph stop sets desired state first and then stops dependents before dependencies. The global
+shutdown budget defaults to 60 seconds. If that budget expires, the orchestrator logs the timeout
+and clears all fibers; it does not fail with `ShutdownTimeoutError`.
 
-### LogBuffer — log capture and streaming
+In-process cleanup and orphan supervision solve different failure modes:
 
-**File:** `src/LogBuffer.ts`
+- `cleanup` runs while the owner Effect runtime is alive and can use its dependencies.
+- `supervision.orphanCleanup` is serializable work executed by a detached supervisor when the
+  owner's stdin closes, its PID disappears, the supervisor receives a termination signal, or the
+  managed child exits while cleanup is configured.
 
-Captures stdout/stderr from every managed process and makes it available for both historical queries and live streaming.
-
-```mermaid
-graph LR
-    subgraph Producers
-        P1["service 'db' stdout"]
-        P2["service 'api' stderr"]
-    end
-
-    subgraph LogBuffer
-        PS1["PubSub<br/><i>per-service (1024)</i>"]
-        PS2["PubSub<br/><i>global (4096)</i>"]
-        BUF["Ref&lt;LogEntry[]&gt;<br/><i>ring buffer (10k)</i>"]
-    end
-
-    subgraph Consumers
-        C1["TUI dashboard<br/><i>subscribe('db')</i>"]
-        C2["Log file writer<br/><i>subscribeAll()</i>"]
-        C3["API endpoint<br/><i>history('api', 50)</i>"]
-    end
-
-    P1 --> PS1
-    P2 --> PS1
-    P1 --> PS2
-    P2 --> PS2
-    P1 --> BUF
-    P2 --> BUF
-    PS1 --> C1
-    PS2 --> C2
-    BUF --> C3
-```
+`ExternalCleanupAction` currently supports removing a Docker container or a filesystem path. The
+supervisor validates the decoded configuration and ignores individual cleanup failures so cleanup
+remains best-effort and idempotent.
 
-**Internal data structures:**
+## Supervisor runtime
 
-- **Per-service `PubSub`** (bounded at 1024 entries): delivers log lines to subscribers watching a specific service. If a subscriber falls behind by 1024 lines, the oldest entries are dropped (backpressure).
-- **Global `PubSub`** (bounded at 4096): delivers all log lines across all services. Used by `subscribeAll()`.
-- **Per-service `Ref<Array<LogEntry>>`**: an in-memory ring buffer capped at 10,000 entries. Powers `history()` for historical queries — new subscribers can catch up on recent output without replaying the entire PubSub.
+A definition opts into supervision by setting `supervision`. Instead of spawning the configured
+command directly, `Supervisor.makeSupervisedCommand()` launches `supervisor-runtime.ts`. The
+supervisor:
 
-**Why PubSub instead of EventEmitter?**
+- starts the actual command in its own process group on Unix;
+- pipes child stdout/stderr back to the orchestrator;
+- watches both owner stdin and owner PID;
+- kills the entire child tree on owner loss or a shutdown signal;
+- applies graceful-then-forceful termination;
+- runs serializable orphan cleanup before it exits.
 
-- **Backpressure**: bounded buffers prevent a fast producer from overwhelming slow consumers
-- **Multiple subscribers**: each subscriber gets its own independent queue — one slow subscriber doesn't block others
-- **No callback hell**: consumers read from a `Stream`, which composes cleanly with the rest of the Effect pipeline
-- **No memory leaks**: subscribers are cleaned up when their fiber is interrupted (no forgotten `.removeListener()`)
+This extra process is required for abrupt owner death: an Effect finalizer cannot run after its
+own process has already disappeared. Ordinary definitions avoid the extra process.
 
----
+## Compiled Bun self-dispatch
 
-### HealthProbe — health checking
+Development runtimes can execute `supervisor-runtime.ts` by file path. A Bun single-file executable
+cannot: `process.execPath` points back to the compiled CLI, and source URLs may live under Bun's
+virtual filesystem. The package therefore uses three internal environment variables:
 
-**File:** `src/HealthProbe.ts`
+| Variable                                   | Role                                                                                                                                   |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `PROCESS_COMPOSE_SUPERVISOR_SELF_DISPATCH` | Enabled by the compiled parent when this package is loaded from `file:///$bunfs/`; tells later spawns to re-enter the same executable. |
+| `PROCESS_COMPOSE_RUN_SUPERVISOR`           | Selects the supervisor runtime when the executable re-enters its main entrypoint.                                                      |
+| `PROCESS_COMPOSE_SUPERVISOR_CONFIG`        | Carries the base64url-encoded supervisor configuration for that runtime.                                                               |
 
-Runs periodic health checks against a service and calls back when the service transitions between healthy and unhealthy states.
+The CLI entrypoint calls `enableSupervisorSelfDispatchForCompiledBun()` before normal command
+dispatch, checks `isSupervisorRuntimeRequested()`, and invokes `runSupervisorRuntimeFromEnv()`.
+The supervisor removes all three variables before starting the managed command, preventing the
+protocol from leaking recursively into a service.
 
-**Two probe types:**
+The stack daemon has a separate Supabase-owned marker, `SUPABASE_STACK_RUN_DAEMON`; it is documented
+in [the stack detach-mode guide](../../stack/docs/detach-mode.md#compiled-executable-re-entry).
 
-| Probe | How it works                                              | Success condition      |
-| ----- | --------------------------------------------------------- | ---------------------- |
-| HTTP  | `fetch(scheme://host:port/path)` with timeout             | Response status is 2xx |
-| Exec  | Spawns the configured command directly with explicit args | Exit code is 0         |
-| TCP   | `Net.createConnection(host, port)` with timeout           | Connection succeeds    |
+These contracts exist because compiled-child behavior caused two user-visible incidents:
 
-**Algorithm:**
+- [CLI-1452](https://linear.app/supabase/issue/CLI-1452/compiled-bun-compile-next-binary-cant-run-supabase-functions-dev): compiled runtime paths and native watcher bindings were unsafe for functions development.
+- [CLI-1453](https://linear.app/supabase/issue/CLI-1453/compiled-bun-compile-next-binary-start-detach-daemon-fork-ignores): detached startup re-entered the CLI instead of the daemon.
 
-1. Wait `initialDelaySeconds` (default: 0)
-2. Execute the probe every `periodSeconds` (default: 10)
-3. Track consecutive successes and failures in a `Ref<{ successes, failures }>` counter
-4. When consecutive successes reaches `successThreshold` (default: 1): call `onHealthy()`
-5. When consecutive failures reaches `failureThreshold` (default: 3): call `onUnhealthy()`
-6. A success resets the failure counter to 0, and vice versa
+## Logs
 
-The health probe runs as a forked child fiber inside the service's main fiber. When the service fiber is interrupted (e.g., on stop), the health probe fiber is automatically interrupted too — no manual cleanup needed.
+`LogBuffer` holds a bounded per-service history and a bounded merged history (10,000 entries each),
+plus live per-service and merged `PubSub` streams. `historyAll` can filter by service names.
+Streams contain new entries only; callers explicitly request history when they need replay.
 
----
+When a process exits unexpectedly or becomes unhealthy, the orchestrator appends recent buffered
+output to its diagnostics. `truncate` currently clears both a service's history and its entries in
+the merged history; it has no production caller.
 
-### Orchestrator — the coordinator
+## Error model
 
-**File:** `src/Orchestrator.ts`
+Graph construction can fail with `MissingDependencyError` or `CyclicDependencyError`. Lifecycle
+lookup uses `ServiceNotFoundError`; spawn preparation uses `SpawnError`; readiness uses
+`ServiceReadyError`. Global shutdown timeout is logged and force-cleared, so the exported
+`ShutdownTimeoutError` does not represent a current failure path.
 
-The Orchestrator is the heart of the library. It ties together every other component into a coherent service lifecycle manager.
+## Testing through Interfaces
 
-#### Service interface
-
-```ts
-class Orchestrator extends Context.Service<Orchestrator, {
-  start: ()           => Effect<void>;                              // start all services
-  startService: (name) => Effect<void, ServiceNotFoundError>;       // start one + its deps
-  stop: ()            => Effect<void>;                              // stop all services
-  stopService: (name) => Effect<void, ServiceNotFoundError>;        // stop service + active dependents
-  restartService: (name) => Effect<void, ServiceNotFoundError>;     // stop then start
-  updateServiceDefinition: (name, def) => Effect<void, ...>;       // replace definition
-  getState: (name)    => Effect<ServiceState, ServiceNotFoundError>;// snapshot
-  getAllStates: ()     => Effect<ReadonlyArray<ServiceState>>;      // snapshot of all
-  stateChanges: (name) => Effect<Stream<ServiceState>, ServiceNotFoundError>; // live
-  allStateChanges: ()  => Stream<ServiceState>;                     // live, all services
-  waitReady: (name)    => Effect<void, ServiceNotFoundError | ServiceReadyError>;
-  waitAllReady: ()     => Effect<void, ServiceReadyError>;
-}>()("process-compose/Orchestrator") { ... }
-```
-
-#### Initialization
-
-`Orchestrator.layer` accepts an optional `OrchestratorConfig` parameter (e.g. `shutdownTimeoutSeconds`) that applies global defaults over the per-service configuration.
-
-When the Orchestrator layer is constructed, it:
-
-1. Yields the `ChildProcessSpawner` and `LogBuffer` services from the environment
-2. Creates a `Map<string, ServiceRuntime>` where each entry holds one stable `SubscriptionRef<ServiceState>`. It is both the live state machine and the synchronization point for lifecycle waiters.
-3. Creates a `FiberMap<string>` to track one fiber per running service
-
-#### FiberMap — the central data structure
-
-FiberMap is the architectural linchpin. Here's why:
-
-```mermaid
-sequenceDiagram
-    participant Consumer as Consumer code
-    participant FM as FiberMap
-    participant Fiber as Service fiber
-    participant Finalizer as Effect.addFinalizer
-    participant OS as OS process
-
-    Consumer->>FM: FiberMap.run("db", runService(dbDef))
-    FM->>Fiber: fork new fiber
-    Fiber->>OS: spawner.spawn(cmd)
-    Note over Fiber,OS: process is running
-
-    Consumer->>FM: FiberMap.remove("db")
-    FM->>Fiber: interrupt
-    Fiber->>Finalizer: trigger registered finalizers
-    Finalizer->>OS: kill(SIGTERM)
-    OS-->>Finalizer: exit
-    Note over FM: entry removed, fiber done
-```
-
-The key insight: **stopping a service is just removing it from the map**. The interrupt cascades to the fiber, which triggers finalizers, which send SIGTERM to the OS process. There's no separate "process manager" or "cleanup registry" — the fiber's scope _is_ the lifecycle.
-
-When the Orchestrator's own scope closes (application shutdown), FiberMap interrupts _all_ entries automatically. Every process gets a graceful shutdown attempt, guaranteed, even if the application crashes.
-
-#### Service lifecycle (`runService`)
-
-Each service follows this lifecycle. All state mutations go through `sendEvent()` which validates transitions via the FSM before updating the `SubscriptionRef`:
-
-```mermaid
-sequenceDiagram
-    participant RUN as runService
-    participant DEP as Dependency state stream
-    participant FSM as sendEvent (FSM)
-    participant SPAWN as spawnOnce
-    participant CPS as ChildProcessSpawner
-    participant LOG as LogBuffer
-    participant HP as HealthProbe
-
-    RUN->>DEP: await dependency state predicates
-    Note over DEP: changes emits current state, then future transitions
-
-    RUN->>FSM: DependenciesSatisfied → Starting
-    RUN->>SPAWN: spawnOnce()
-    SPAWN->>CPS: spawner.spawn(cmd)
-    CPS-->>SPAWN: handle (pid, stdout, stderr, exitCode)
-
-    SPAWN->>SPAWN: register finalizer (SIGTERM → SIGKILL)
-    SPAWN->>SPAWN: run started hooks
-    SPAWN->>FSM: ProcessSpawned → Running
-
-    par Log streaming
-        SPAWN->>LOG: fork: stdout → decodeText → splitLines → append
-        SPAWN->>LOG: fork: stderr → decodeText → splitLines → append
-    and Health checking
-        SPAWN->>HP: fork: runHealthProbe(callbacks)
-        HP->>HP: run healthy hooks
-        HP->>FSM: HealthCheckPassed → Healthy
-    end
-
-    alt Process exits normally
-        SPAWN->>SPAWN: await handle.exitCode
-        SPAWN-->>RUN: SpawnResult::Exited(exitCode)
-        RUN->>FSM: ProcessExited → Stopped or Failed
-    else Health probe detects unhealthy (restart policy allows)
-        HP->>FSM: HealthCheckFailed → Unhealthy
-        HP->>SPAWN: resolve unhealthyRestart Deferred
-        SPAWN-->>RUN: SpawnResult::UnhealthyRestart
-        Note over SPAWN: scope closes → finalizer kills process
-    end
-
-    alt restart policy says yes
-        RUN->>FSM: RestartTriggered → Restarting
-        RUN->>RUN: exponential backoff
-        RUN->>FSM: BackoffElapsed → Starting
-        RUN->>RUN: loop back to spawnOnce
-    end
-```
-
-#### Dependency waiting
-
-When a service has dependencies, its fiber waits for predicates on the dependency's stable state stream before spawning:
-
-```ts
-// Service "api" depends on "db" being healthy
-const db = services.get("db");
-if (db) {
-  yield * waitForState(db, (state) => state.status === "Healthy");
-}
-// Execution only continues here once db is healthy
-```
-
-This is fundamentally different from polling or event-based approaches:
-
-- **No polling**: the fiber is parked with zero CPU cost until the deferred resolves
-- **Stable across restarts**: every waiter observes the same `SubscriptionRef`; no lifecycle-generation aliases need replacing
-- **No missed current state**: `SubscriptionRef.changes` emits the current value before future transitions
-
-The entire dependency-wait phase is wrapped in an `Effect.timeout` using `dependencyTimeoutSeconds` (default: 30s). If dependencies don't reach their conditions in time, the service receives a `DependencyFailed` event with a timeout error message and transitions to `Failed` without ever spawning. This prevents services from blocking indefinitely when a dependency is stuck.
-
-If a dependency exits with a non-zero code and the condition is `completed`, the dependent service also receives a `DependencyFailed` event and transitions to `Failed` without ever spawning.
-
-#### Graceful shutdown
-
-Every spawned process registers a finalizer via `Effect.addFinalizer`:
-
-```
-1. Send shutdown signal (default: SIGTERM)
-2. Wait for process to exit (up to timeoutSeconds, default: 10)
-3. If timeout: send SIGKILL (force kill)
-4. Log "Shutdown timed out, sent SIGKILL"
-```
-
-Finalizers run in three scenarios:
-
-- **Explicit stop**: `stopService("db")` → `StopRequested` event → `FiberMap.remove` → interrupt → finalizer → `ProcessExited` event
-- **Scope close**: application shutdown → FiberMap scope closes → all finalizers
-- **Fiber failure**: if `runService` throws, the scope closes → finalizer
-
-**Global shutdown timeout.** The entire `stop()` operation is wrapped in a `shutdownTimeoutSeconds` timeout (default: 60 seconds). If the global timeout expires before all services have stopped — for example because a service ignores SIGTERM and its per-service `shutdown.timeoutSeconds` has not yet elapsed — `FiberMap.clear` force-interrupts all remaining fibers and a `[shutdown-timeout]` warning is appended to every service's log buffer. This is a safety net layered on top of the per-service SIGTERM → wait → SIGKILL escalation controlled by `shutdown.timeoutSeconds`: the per-service timeout governs how long a single process gets to exit gracefully; the global timeout bounds the total wall-clock time the entire shutdown can take.
-
-**Shutdown is parallel, not sequential.** Services stop concurrently, but each service waits for its active dependents to reach `Stopped` before stopping itself. It observes the same stable state streams used during startup, but follows the graph in reverse. The `dependentsOf(name)` graph query provides the reverse dependency edges needed to identify which services must stop first.
-
-`stopService(name)` stops the named service and its active transitive dependents, in reverse dependency order. This preserves the graph invariant that no managed dependent keeps running after a dependency has been stopped. Never-started dependents are left dormant.
-
-The FSM guarantees correct state transitions during shutdown. For each affected service:
-
-1. `StopRequested` event transitions the service to `Stopping`
-2. `FiberMap.remove` interrupts the fiber, which triggers the finalizer (SIGTERM → wait → SIGKILL)
-3. After `remove` completes (the process is dead), a `ProcessExited` event transitions to `Stopped`; shutdown waiters observe that transition on the state stream
-
-This fixes a subtle bug in the pre-FSM design where `Stopped` was set immediately after `FiberMap.remove` returned, before the process had actually exited. The FSM enforces that `Stopping → Stopped` only happens via `ProcessExited`, which is only sent after the fiber (and its finalizer) has completed.
-
-If a health probe callback fires between steps 1 and 3 (the service is in `Stopping`), the FSM silently rejects the `HealthCheckPassed`/`HealthCheckFailed` event — no state corruption.
-
-This is the "Effect advantage" — you write cleanup logic once, attached to the resource, and it runs no matter how the fiber exits. With vanilla Node.js, you'd need try/finally blocks, `process.on('exit')` handlers, and careful bookkeeping to achieve the same guarantee.
-
-#### Log streaming pipeline
-
-Each spawned process has its stdout/stderr piped through a streaming pipeline:
-
-```
-handle.stdout (Stream<Uint8Array>)
-  → Stream.decodeText      (decode binary to UTF-8 strings)
-  → Stream.splitLines       (split on newlines)
-  → Stream.runForEach(...)  (send each line to LogBuffer.append)
-```
-
-This runs in a forked child fiber (`Effect.forkChild`), so it:
-
-- Runs concurrently with the main process lifecycle
-- Is automatically interrupted when the parent fiber (the service) is interrupted
-- Catches and ignores stream errors (a broken pipe shouldn't crash the service)
-
-#### Restart loop
-
-After a process exits **or becomes unhealthy**, the restart policy is evaluated:
-
-| Policy             | Restart on crash                | Restart on unhealthy |
-| ------------------ | ------------------------------- | -------------------- |
-| `"no"`             | Never                           | Never                |
-| `"on-failure"`     | Exit code != 0                  | Yes                  |
-| `"always"`         | Always (even on success)        | Yes                  |
-| `"unless-stopped"` | Always, unless manually stopped | Yes                  |
-
-**Unhealthy restart flow**: when the health probe transitions a service to `Unhealthy` and the restart policy allows it, the Orchestrator races an `unhealthyRestart` Deferred against `handle.exitCode` inside `spawnOnce()`. When the Deferred wins, the scope closes, triggering the kill finalizer (SIGTERM → timeout → SIGKILL). The service then enters the normal restart loop via `RestartTriggered`. Crash restarts and unhealthy restarts share the same `maxRestarts` counter.
-
-If restarting, exponential backoff is applied: `min(30s, 2^(n-1)s)` where n is the restart count. The state stream remains stable across the restart and publishes `Restarting → Starting → Running → Healthy`, so existing waiters stay attached to the new generation.
-
-#### Lifecycle hooks
-
-Services can define hooks that run at specific lifecycle points:
-
-- **`on: "started"`** — runs after the process is spawned but before `ProcessSpawned` transitions the service to `Running`
-- **`on: "healthy"`** — runs after the first successful health probe but before `HealthCheckPassed` transitions the service to `Healthy`
-
-The stable state is published only after its hooks complete. This means a service depending on `db` with condition `healthy` waits until db's `on:healthy` hooks have succeeded and db has entered `Healthy`.
-
-Each hook receives a `HookLog` callback scoped to the service name, allowing it to write directly to the service's log buffer. Hook output appears in the same log stream as the service's stdout/stderr, so callers subscribed to a service's logs see hook messages inline with process output.
-
-Each hook has:
-
-- `run: (log: HookLog) => Effect<void, unknown>` — the effect to execute; `log` writes to the service's log buffer
-- `timeoutSeconds` (default: 30) — maximum execution time
-- `failurePolicy: "fail" | "ignore"` (default: `"fail"`) — whether hook failure should fail the service
-
-If a hook with `failurePolicy: "fail"` fails or times out, the service receives a `HookFailed` event and transitions to `Failed`. Hooks with `failurePolicy: "ignore"` log a `[hook-ignored]` message and continue.
-
-Multiple hooks on the same trigger run in sequence.
-
-#### Failure diagnostics
-
-When a health probe transitions a service to `Unhealthy`, the Orchestrator emits diagnostic output to the service's stderr log:
-
-- A `[health-check-failed]` header line
-- The last 20 log entries from the service (timestamp, stream, content)
-- If no recent logs exist, a "no recent log output" message
-
-This mirrors how Docker streams container logs on health check failure, helping operators diagnose issues without manually querying logs.
-
----
-
-## Why Effect?
-
-The core question: is Effect justified for a process orchestrator?
-
-The answer comes down to three properties that are trivial in Effect but hard to implement correctly by hand: **structured concurrency**, **resource safety**, and **composable observation**.
-
-### Without Effect — what you'd build
-
-A vanilla Node.js orchestrator would need:
-
-```ts
-class Orchestrator {
-  private processes = new Map<string, ChildProcess>();
-  private states = new Map<string, ServiceState>();
-  private listeners = new Map<string, Set<(state: ServiceState) => void>>();
-  private cleanupHandlers: Array<() => Promise<void>> = [];
-
-  async start() {
-    // Sort services topologically (custom implementation)
-    const order = topoSort(this.config);
-
-    for (const def of order) {
-      // Wait for dependencies (EventEmitter + Promise)
-      await this.waitForDependencies(def);
-
-      // Spawn process
-      const proc = spawn(def.command, def.args);
-      this.processes.set(def.name, proc);
-
-      // Track cleanup
-      this.cleanupHandlers.push(async () => {
-        proc.kill("SIGTERM");
-        await new Promise((resolve) => setTimeout(resolve, 10000));
-        if (!proc.killed) proc.kill("SIGKILL");
-      });
-
-      // Log streaming
-      proc.stdout?.on("data", (chunk) => {
-        /* parse lines, notify subscribers */
-      });
-
-      // State tracking
-      proc.on("exit", (code) => {
-        this.states.set(def.name, { ...state, status: code === 0 ? "Stopped" : "Failed" });
-        this.listeners.get(def.name)?.forEach((fn) => fn(this.states.get(def.name)!));
-        // Handle restart policy...
-        // But what if stop() was called during restart backoff?
-        // What if the EventEmitter fires before the listener is registered?
-        // What if cleanup throws?
-      });
-    }
-  }
-
-  async stop() {
-    // Run all cleanup handlers... but what if one throws?
-    // What order? What about concurrent stop+restart?
-    for (const handler of this.cleanupHandlers.reverse()) {
-      try {
-        await handler();
-      } catch {
-        /* swallow? log? */
-      }
-    }
-  }
-}
-```
-
-This works for simple cases but accumulates edge cases fast:
-
-- **Leaked processes**: if `start()` throws after spawning 3 of 5 services, who cleans up the 3?
-- **Race conditions**: what if `stop()` is called while a restart backoff `setTimeout` is pending?
-- **Memory leaks**: forgetting to `removeListener()` on a destroyed process
-- **Error swallowing**: `try/catch` around cleanup often hides important errors
-- **Testing**: mocking `child_process.spawn` globally affects all tests
-
-### With Effect — what you actually write
-
-| Concern                        | Vanilla Node.js                                                      | Effect                                                                         |
-| ------------------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| **Fork a concurrent service**  | `spawn()` + manual tracking                                          | `FiberMap.run(fibers, name, effect)`                                           |
-| **Stop a service**             | `proc.kill()` + cleanup bookkeeping                                  | `FiberMap.remove(fibers, name)`                                                |
-| **Stop everything**            | Loop over processes + cleanup handlers                               | Close the scope (automatic)                                                    |
-| **Leaked process guarantee**   | Must manually handle every exit path                                 | Structured concurrency: parent interrupt = children interrupt = finalizers run |
-| **Wait for dependency**        | `EventEmitter` + `Promise` + race-condition handling                 | Predicate over `SubscriptionRef.changes(dep.state)`                            |
-| **Observe state changes**      | `EventEmitter` + manual subscriber tracking                          | `SubscriptionRef.changes(ref)` (Stream)                                        |
-| **Stream logs to N consumers** | Custom pub/sub or multiple `.on('data')`                             | `PubSub` with bounded backpressure                                             |
-| **Graceful shutdown**          | `process.on('exit')` + manual per-process cleanup                    | `Effect.addFinalizer(() => kill then wait then SIGKILL)`                       |
-| **Restart with backoff**       | `setTimeout` + state flags + "is this service being stopped?" checks | `Effect.sleep(backoff)` inside a loop — interruption cancels the sleep         |
-| **Test process spawning**      | `jest.mock('child_process')` globally                                | `Layer.succeed(ChildProcessSpawner, mockImpl)` per test                        |
-
-The key realization: **most of the vanilla code isn't business logic — it's concurrency plumbing**. EventEmitter subscription management, cleanup handler registries, race-condition guards, manual timeout cancellation. Effect's structured concurrency eliminates all of it, leaving just the business logic: "spawn process, stream logs, check health, restart on failure."
-
-### The fiber advantage, concretely
-
-Consider what happens when you call `orchestrator.stop()`:
-
-**Vanilla**: iterate processes in reverse order, kill each, await exit with timeout, SIGKILL on timeout, handle errors, remove event listeners, cancel pending restart timers, update state, notify subscribers, deallocate buffers...
-
-**Effect**: `FiberMap` scope closes. Each fiber is interrupted. Each fiber's `Effect.addFinalizer` sends SIGTERM, waits, escalates to SIGKILL. `SubscriptionRef` updates automatically. PubSub publishers complete. Child fibers (log streaming, health probes) are interrupted by structured concurrency. Done.
-
-The entire shutdown sequence is **implicit in the fiber tree structure**. There's no explicit "cleanup everything" code because there's nothing to clean up — the resources are tied to the fiber scopes that own them.
-
----
-
-## Data flow
-
-End-to-end flow from configuration to consumer:
-
-```mermaid
-graph TB
-    subgraph "1. Configuration"
-        DEFS["ServiceDef[]"]
-    end
-
-    subgraph "2. Graph resolution"
-        BG["buildGraph()"]
-        RG["ResolvedGraph<br/><i>startOrder, stopOrder,<br/>startOrderFor, dependenciesOf</i>"]
-    end
-
-    subgraph "3. Orchestrator construction"
-        OL["Orchestrator.layer(graph)"]
-        SIGS["ServiceRuntime map<br/><i>stable SubscriptionRef per service</i>"]
-        FBM["FiberMap&lt;string&gt;"]
-    end
-
-    subgraph "4. Per-service fiber"
-        DEP["Await dependency<br/>state predicates"]
-        SPAWN["spawner.spawn(cmd)"]
-        FIN["Effect.addFinalizer<br/><i>SIGTERM → SIGKILL</i>"]
-        STDOUT["stdout → decodeText<br/>→ splitLines"]
-        STDERR["stderr → decodeText<br/>→ splitLines"]
-        HEALTH["runHealthProbe<br/><i>periodic HTTP/exec</i>"]
-        EXIT["await exitCode"]
-        RESTART["restart loop<br/><i>backoff + policy</i>"]
-    end
-
-    subgraph "5. State management"
-        FSM["ServiceTransition<br/><i>validate + apply event</i>"]
-        SREF["SubscriptionRef&lt;ServiceState&gt;<br/><i>Semaphore(1) serialization</i>"]
-    end
-
-    subgraph "6. Shared services"
-        LB["LogBuffer<br/><i>PubSub + ring buffer</i>"]
-    end
-
-    subgraph "7. Consumers"
-        TUI["TUI dashboard<br/><i>stateChanges / allStateChanges</i>"]
-        LOGS["Log viewer<br/><i>subscribe / subscribeAll</i>"]
-        API["REST API<br/><i>getState / getAllStates / history</i>"]
-    end
-
-    DEFS --> BG --> RG
-    RG --> OL
-    OL --> SIGS
-    OL --> FBM
-
-    FBM -->|"FiberMap.run(name, ...)"| DEP
-    DEP --> SPAWN
-    SPAWN --> FIN
-    SPAWN --> STDOUT
-    SPAWN --> STDERR
-    SPAWN --> HEALTH
-    SPAWN --> EXIT
-    EXIT --> RESTART
-    RESTART -.->|"loop"| SPAWN
-
-    STDOUT --> LB
-    STDERR --> LB
-    HEALTH -->|"sendEvent"| FSM
-    EXIT -->|"sendEvent"| FSM
-    FSM -->|"modifyEffect"| SREF
-
-    SREF --> TUI
-    LB --> LOGS
-    SREF --> API
-    LB --> API
-```
+- Pure unit tests cover graph construction, state transitions, health counters, and log buffering.
+- Orchestrator integration tests provide a stateful `ChildProcessSpawner` Adapter and assert on
+  public states, desired state, logs, hooks, dependency ordering, restart, and cleanup.
+- Supervisor runtime tests use real subprocesses because owner-loss and process-tree behavior cross
+  the process Seam.
diff --git a/packages/stack/README.md b/packages/stack/README.md
index bf90e3ca9d..85d2db88e1 100644
--- a/packages/stack/README.md
+++ b/packages/stack/README.md
@@ -93,7 +93,7 @@ Optional. When omitted, uses all defaults (ephemeral temp data directory, auto-a
 | --------- | -------- | -------- | ------------------------------------------------------------------------------------------- |
 | `dataDir` | `string` | No       | Directory for Postgres data (PGDATA). Ephemeral temp dir if omitted (cleaned up on dispose) |
 | `port`    | `number` | No       | Postgres port (auto-allocated if omitted)                                                   |
-| `version` | `string` | No       | Postgres version (default: `17.6.1.081`)                                                    |
+| `version` | `string` | No       | Override the current pinned Postgres version                                                |
 
 ### `postgrest`
 
@@ -104,7 +104,7 @@ Optional. Omit to include with defaults, set to `false` to exclude.
 | `schemas`         | `string[]` | `["public"]`               | Database schemas to expose                |
 | `extraSearchPath` | `string[]` | `["public", "extensions"]` | Additional Postgres `search_path` entries |
 | `maxRows`         | `number`   | `1000`                     | Maximum rows returned per request         |
-| `version`         | `string`   | `14.5`                     | PostgREST version                         |
+| `version`         | `string`   | current pinned version     | PostgREST version override                |
 
 ### `auth`
 
@@ -116,7 +116,7 @@ Optional. Omit to include with defaults, set to `false` to exclude.
 | `siteUrl`     | `string` | `http://localhost:3000`    | Auth redirect URL (your app's URL) |
 | `jwtExpiry`   | `number` | `3600`                     | JWT expiry in seconds              |
 | `externalUrl` | `string` | `http://127.0.0.1:${port}` | Auth external URL                  |
-| `version`     | `string` | `2.188.0-rc.15`            | Auth version                       |
+| `version`     | `string` | current pinned version     | Auth version override              |
 
 ### Full config example
 
@@ -124,8 +124,8 @@ Optional. Omit to include with defaults, set to `false` to exclude.
 const stack = await createStack({
   jwtSecret: "super-secret-jwt-token-with-at-least-32-characters-long",
   port: 54321,
-  postgres: { port: 54322, dataDir: "/tmp/data", version: "17.6.1.081" },
-  postgrest: { schemas: ["public", "custom"], maxRows: 500, version: "14.5" },
+  postgres: { port: 54322, dataDir: "/tmp/data" },
+  postgrest: { schemas: ["public", "custom"], maxRows: 500 },
   auth: { port: 9999, siteUrl: "http://myapp.dev:3000", jwtExpiry: 7200 },
 });
 ```
@@ -187,8 +187,9 @@ Service activation is dependency-aware. Starting Storage also starts imgproxy wh
 starting Analytics also starts Vector when enabled, so a public service never comes up without the
 companion it calls or feeds.
 
-Common service names include `"postgres"`, `"postgrest"`, `"auth"`, `"realtime"`, `"storage"`,
-`"imgproxy"`, `"mailpit"`, `"pgmeta"`, `"studio"`, `"analytics"`, `"vector"`, and `"pooler"`.
+Service names are `"postgres"`, `"postgrest"`, `"auth"`, `"edge-runtime"`, `"realtime"`,
+`"storage"`, `"imgproxy"`, `"mailpit"`, `"pgmeta"`, `"studio"`, `"analytics"`, `"vector"`, and
+`"pooler"`.
 
 Internal helper processes are projected away from the public stack API. For example, `postgres-init`
 is treated as an implementation detail of `postgres`, so callers only see the public `postgres`
@@ -274,22 +275,18 @@ await prefetch({ versions: { postgres: "17.4.1.045" } });
 
 ## Service Versions
 
-Default versions are used when no `version` field is specified per service:
-
-| Service   | Default Version |
-| --------- | --------------- |
-| Postgres  | `17.6.1.081`    |
-| PostgREST | `14.5`          |
-| Auth      | `2.188.0-rc.15` |
+Default versions are used when no per-service `version` field is specified. The authoritative,
+exhaustive values are exported as `DEFAULT_VERSIONS` and live in
+[`src/versions.ts`](./src/versions.ts); they are intentionally not copied into this README.
 
 Override versions per service:
 
 ```typescript
 const stack = await createStack({
   jwtSecret: "...",
-  postgres: { dataDir: "/tmp/data", version: "17.4.1.045" },
-  postgrest: { version: "14.4" },
-  auth: { version: "2.180.0" },
+  postgres: { dataDir: "/tmp/data", version: "<postgres-version>" },
+  postgrest: { version: "<postgrest-version>" },
+  auth: { version: "<auth-version>" },
 });
 ```
 
diff --git a/packages/stack/docs/architecture.md b/packages/stack/docs/architecture.md
index 3e05be939f..042f24cf7f 100644
--- a/packages/stack/docs/architecture.md
+++ b/packages/stack/docs/architecture.md
@@ -1,1242 +1,280 @@
 # Architecture of `@supabase/stack`
 
-Manages a local Supabase development stack — resolving native binaries, wiring services into a dependency graph, and exposing a single async `createStack()` call that returns running connection details.
+`@supabase/stack` turns Supabase-local configuration into a supervised graph of native processes
+and Docker containers. It owns Supabase-specific configuration, artifact selection, topology,
+proxying, state projection, managed-daemon persistence, and cleanup. Generic process lifecycle is
+delegated to [`@supabase/process-compose`](../../process-compose/docs/architecture.md).
 
-## Table of contents
+## Public entrypoints
 
-- [High-level overview](#high-level-overview)
-- [Relationship to process-compose](#relationship-to-process-compose)
-- [Components](#components)
-  - [errors — typed error hierarchy](#errors--typed-error-hierarchy)
-  - [Platform — OS and architecture detection](#platform--os-and-architecture-detection)
-  - [BinaryResolver — download and cache binaries](#binaryresolver--download-and-cache-binaries)
-  - [resolveService — binary-first Docker fallback](#resolveservice--binary-first-docker-fallback)
-  - [JwtGenerator — JWT token generation and opaque keys](#jwtgenerator--jwt-token-generation-and-opaque-keys)
-  - [PortAllocator — dynamic port assignment](#portallocator--dynamic-port-assignment)
-  - [prefetch — pre-download binaries and images](#prefetch--pre-download-binaries-and-images)
-  - [ApiProxy — reverse proxy with key translation](#apiproxy--reverse-proxy-with-key-translation)
-  - [services — ServiceDef factories](#services--servicedef-factories)
-  - [StackBuilder — assemble the dependency graph](#stackbuilder--assemble-the-dependency-graph)
-  - [StackLifecycleCoordinator — lifecycle management](#stacklifecyclecoordinator--lifecycle-management)
-  - [createStack — platform-agnostic core](#createstack--platform-agnostic-core)
-  - [bun.ts / node.ts — runtime implementations behind the root export](#bunts--nodets--runtime-implementations-behind-the-root-export)
-- [Data flow](#data-flow)
-- [Testing](#testing)
+The package exposes two levels of Interface:
 
----
+- `@supabase/stack` selects `bun.ts` or `node.ts` through export conditions and exposes the
+  Promise-oriented `createStack()` / `StackHandle` Interface plus prefetch helpers.
+- `@supabase/stack/effect` exposes Effect Interfaces and layer factories used by the CLI and
+  advanced callers.
 
-## High-level overview
-
-`@supabase/stack` answers a single question: given a `StackConfig`, start a local Supabase stack and give me the URLs and keys I need to talk to it.
-
-Behind that simple surface, startup now has three explicit phases. `StackPreparation` resolves native-vs-Docker execution, downloads binaries, and pulls Docker images. `StackBuilder` turns the prepared artifacts into a process graph and service projection. `StackLifecycleCoordinator` then starts the orchestrator, merges pre-start and runtime state into one public stream, and exposes `Downloading`, `Starting`, `Initializing`, and `Healthy` as one continuous lifecycle to callers. An `ApiProxy` sits in front of GoTrue and PostgREST, translating opaque API keys into JWTs before forwarding requests.
-
-```mermaid
-graph TB
-    subgraph Input
-        SC["StackConfig<br/><i>ports, versions, secrets, keys</i>"]
-    end
-
-    subgraph "@supabase/stack"
-        PLT["Platform<br/><i>detect OS + arch</i>"]
-        BR["BinaryResolver<br/><i>download + cache</i>"]
-        PREP["StackPreparation<br/><i>resolve + fetch assets</i>"]
-        JG["JwtGenerator<br/><i>sign JWT tokens + opaque keys</i>"]
-        PA["PortAllocator<br/><i>allocate ports</i>"]
-        AP["ApiProxy<br/><i>reverse proxy + key translation</i>"]
-        SB["StackBuilder<br/><i>wire ServiceDefs</i>"]
-        LC["StackLifecycleCoordinator<br/><i>prepare + runtime lifecycle</i>"]
-        CS["createStack()<br/><i>resolveConfig + layer wiring</i>"]
-        BUN["bun.ts<br/><i>Bun entry point</i>"]
-        NODE["node.ts<br/><i>Node.js entry point</i>"]
-    end
-
-    subgraph "@supabase/process-compose"
-        BG["buildGraph()<br/><i>topological sort</i>"]
-        ORC["Orchestrator<br/><i>spawn + health + restart</i>"]
-    end
-
-    subgraph Output
-        SI["Stack<br/><i>url, publishableKey, secretKey, dbUrl<br/>start/stop, ready, logs, status, dispose</i>"]
-    end
-
-    SC --> CS
-    PLT --> BR
-    BR --> PREP
-    PREP --> SB
-    JG --> CS
-    PA --> CS
-    SB --> BG
-    BG --> ORC
-    ORC --> LC
-    LC --> CS
-    AP --> CS
-    BUN --> CS
-    NODE --> CS
-    CS --> SI
-```
-
-The package has no CLI. It is a library: callers supply a `StackConfig` object and get back a `Stack` with a rich interface including `dispose()`. When `projectDir` points at a Supabase project, the stack can use project config to serve local Edge Functions automatically. Bun and Node.js consumers import from the package root, and the export conditions select the appropriate runtime implementation from `bun.ts` or `node.ts`.
-
----
-
-## Relationship to process-compose
-
-`@supabase/stack` and `@supabase/process-compose` have a clean boundary: stack owns _what_ to run and _where_ to get it; process-compose owns _how_ to run it.
-
-```mermaid
-graph LR
-    subgraph "@supabase/stack"
-        direction TB
-        PLAT["Platform detection"]
-        BRES["Binary download + checksum"]
-        SDEFS["ServiceDef construction<br/><i>postgres / postgrest / auth</i>"]
-        JWTGEN["JwtGenerator<br/><i>HS256 JWT signing + opaque keys</i>"]
-        PALLOC["PortAllocator<br/><i>dynamic port assignment</i>"]
-        PROXY["ApiProxy<br/><i>reverse proxy + key translation</i>"]
-        PREP["StackPreparation"]
-        BUILD["StackBuilder"]
-        COORD["StackLifecycleCoordinator"]
-        CSTACK["createStack()<br/><i>resolveConfig + layer wiring</i>"]
-    end
-
-    subgraph "@supabase/process-compose"
-        direction TB
-        BGRAPH["buildGraph()<br/><i>validates + sorts deps</i>"]
-        ORCH["Orchestrator<br/><i>spawn, health, log, restart, shutdown</i>"]
-        LB["LogBuffer"]
-    end
-
-    SDEFS --> BGRAPH
-    PREP --> BUILD
-    BUILD --> BGRAPH
-    BGRAPH --> ORCH
-    JWTGEN --> CSTACK
-    PALLOC --> CSTACK
-    PROXY --> COORD
-    COORD --> ORCH
-```
-
-| Concern                          | Owner                       |
-| -------------------------------- | --------------------------- |
-| OS / arch detection              | `@supabase/stack`           |
-| Binary download, cache, verify   | `@supabase/stack`           |
-| ServiceDef construction          | `@supabase/stack`           |
-| JWT generation                   | `@supabase/stack`           |
-| Opaque API key translation       | `@supabase/stack`           |
-| Reverse proxy (GoTrue/PostgREST) | `@supabase/stack`           |
-| Dependency graph construction    | `@supabase/process-compose` |
-| Process spawning                 | `@supabase/process-compose` |
-| Health checks                    | `@supabase/process-compose` |
-| Log streaming                    | `@supabase/process-compose` |
-| Restart policies                 | `@supabase/process-compose` |
-| Graceful shutdown                | `@supabase/process-compose` |
-
----
-
-## Components
-
-### errors — typed error hierarchy
-
-**File:** `src/errors.ts`
-
-All Effect errors extend `Data.TaggedError`, which adds a `_tag` discriminator for type-safe pattern matching in Effect pipelines. The compiler tracks which errors each function can produce — callers know at compile time which failure modes they need to handle.
-
-`StackError` is a plain `Error` subclass (not a tagged Effect error) that non-Effect consumers receive from `Stack` method promises. `toStackError()` maps any tagged Effect error to a `StackError` with a string `code` field.
-
-| Error                   | Tag                       | When raised                                                |
-| ----------------------- | ------------------------- | ---------------------------------------------------------- |
-| `BinaryNotFoundError`   | `"BinaryNotFoundError"`   | No asset exists for the current OS/arch combination        |
-| `DownloadError`         | `"DownloadError"`         | Network request fails or `tar` extraction fails            |
-| `ChecksumMismatchError` | `"ChecksumMismatchError"` | Downloaded tarball does not match the published SHA-256    |
-| `DockerPullError`       | `"DockerPullError"`       | Docker image pull fails (exit code != 0 or platform error) |
-| `StackBuildError`       | `"StackBuildError"`       | Any failure during binary resolution or graph assembly     |
-| `PortConflictError`     | `"PortConflictError"`     | Configured port is already in use (reserved for future)    |
-| `PortAllocationError`   | `"PortAllocationError"`   | Failed to bind or allocate a network port                  |
-| `StackError`            | n/a (plain `Error`)       | Thrown from `Stack` promise methods for non-Effect callers |
-
-Each Effect error carries structured metadata:
-
-```ts
-class BinaryNotFoundError extends Data.TaggedError("BinaryNotFoundError")<{
-  readonly service: string; // "auth"
-  readonly platform: string; // "darwin-arm64"
-}> {}
-
-class ChecksumMismatchError extends Data.TaggedError("ChecksumMismatchError")<{
-  readonly url: string; // the .sha256 URL
-  readonly expected: string; // hex from the checksum file
-  readonly actual: string; // hex computed from the downloaded bytes
-}> {}
-```
-
-`StackBuildError` is the catch-all that `StackBuilder` uses to wrap errors from `BinaryResolver`. This means consumers of `StackBuilder.build()` only need to handle one error type — the root cause is attached in `cause` for debugging.
-
-`StackError` is the boundary type for Promise consumers:
-
-```ts
-class StackError extends Error {
-  readonly code: string; // e.g. "SERVICE_NOT_FOUND", "BUILD_ERROR", "DOWNLOAD_ERROR"
-}
-
-function toStackError(err: unknown): StackError;
-```
-
----
-
-### Platform — OS and architecture detection
-
-**File:** `src/Platform.ts`
-
-A thin module that reads `process.platform` and `process.arch` and maps them to the asset-name strings used in GitHub release URLs. Different services use different naming conventions in their releases, so each has its own mapping function.
-
-```ts
-interface PlatformInfo {
-  readonly os: string; // "darwin" | "linux"
-  readonly arch: string; // "arm64" | "x64"
-}
-
-// Reads process.platform and process.arch
-export const detectPlatform: Effect.Effect<PlatformInfo>;
-```
-
-The four mapping functions return `null` for unsupported platforms — `BinaryResolver` converts `null` into a `BinaryNotFoundError`. Returning `null` rather than throwing keeps the logic pure and easy to test without an Effect context.
-
-**Platform support matrix:**
-
-| Service      | darwin-arm64     | linux-x64             | linux-arm64      | win32-x64        |
-| ------------ | ---------------- | --------------------- | ---------------- | ---------------- |
-| postgres     | `darwin-arm64`   | `linux-x64`           | `linux-arm64`    | `null` (Docker)  |
-| postgrest    | `macos-aarch64`  | `linux-static-x86-64` | `ubuntu-aarch64` | `windows-x86-64` |
-| auth         | `darwin-arm64`   | `x86`                 | `arm64`          | `null` (Docker)  |
-| edge-runtime | `aarch64-darwin` | `x86_64-linux`        | `aarch64-linux`  | `null` (Docker)  |
-
-When a mapping function returns `null`, `BinaryResolver` fails with `BinaryNotFoundError` and the stack can fall back to Docker in `auto` mode. Postgres has no Windows binary. PostgREST has native binaries on all supported platforms including Windows (as a `.zip` archive instead of `.tar.xz`). Auth has native macOS arm64 and Linux binaries. Edge Runtime release assets exist for macOS arm64 and Linux, but the stack currently keeps Edge Runtime on Docker while the native path is not exposed.
+The root runtime Adapters provide Effect filesystem, path, child-process, HTTP-server, and Unix
+socket HTTP implementations. `createStack.ts` remains platform-agnostic and receives a
+`PlatformFactory`.
 
 ```mermaid
 flowchart LR
-    PLT["PlatformInfo\nos + arch"] --> PA["postgresAssetName()"]
-    PLT --> PRA["postgrestAssetName()"]
-    PLT --> AA["authAssetName()"]
-
-    PA -->|"darwin-arm64"| PAS["darwin-arm64"]
-    PA -->|"linux-x64"| PAL["linux-x64"]
-    PA -->|"win32/other"| PAX["null → Docker fallback"]
-
-    PRA -->|"darwin-arm64"| PRAS["macos-aarch64"]
-    PRA -->|"linux-x64"| PRAL["linux-static-x86-64"]
-    PRA -->|"win32-x64"| PRAW["windows-x86-64"]
-    PRA -->|"other"| PRAX["null → BinaryNotFoundError"]
-
-    AA -->|"linux-x64"| AAS["x86"]
-    AA -->|"linux-arm64"| AAL["arm64"]
-    AA -->|"darwin/win32"| AAX["null → Docker fallback"]
-```
-
----
-
-### BinaryResolver — download and cache binaries
-
-**File:** `src/BinaryResolver.ts`
-
-Given a service name and version, `BinaryResolver` asks the artifact catalog for a supported native release, reuses or downloads the corresponding binary for the current platform, verifies its integrity, and returns a path to the extracted directory.
-
-#### Service interface
-
-```ts
-class BinaryResolver extends Context.Service<
-  BinaryResolver,
-  {
-    readonly resolve: (
-      spec: BinarySpec,
-    ) => Effect.Effect<string, BinaryNotFoundError | DownloadError | ChecksumMismatchError>;
-  }
->()("local/BinaryResolver") {}
-
-interface BinarySpec {
-  readonly service: ServiceName;
-  readonly version: string;
-  readonly cacheDir?: string; // defaults to ~/.supabase/bin
-}
-```
-
-#### Binary resolution flow
-
-```mermaid
-flowchart TD
-    A["resolve(spec)"] --> B["detectPlatform"]
-    B --> C{"native release in artifact catalog?"}
-    C -->|"no"| D["BinaryNotFoundError"]
-    C -->|"yes"| E["construct provider-scoped cacheDir"]
-    E --> F["sweep stale .partial-* siblings (best-effort)"]
-    F --> G{"cacheDir has .complete marker and payload?"}
-    G -->|"yes"| H["return cacheDir"]
-    G -->|"no"| I{"compatible legacy cache has expected executable?"}
-    I -->|"yes"| J["return legacy cacheDir"]
-    I -->|"no"| M["HttpClient.get release archive"]
-    M -->|"network error"| N["DownloadError"]
-    M -->|"ok"| O{"checksum URL?"}
-    O -->|"no"| Q["skip verification"]
-    O -->|"yes"| P["download and verify SHA-256"]
-    P -->|"mismatch"| R["ChecksumMismatchError"]
-    P -->|"ok"| Q
-    Q --> S["extract into unique .partial-* staging directory"]
-    S -->|"exitCode != 0"| T["DownloadError"]
-    S -->|"ok"| U["chmod, macOS codesign, write .complete marker"]
-    U --> V{"atomically rename staging to cacheDir"}
-    V -->|"won publication"| H
-    V -->|"destination exists"| W{"destination complete?"}
-    W -->|"yes"| H
-    W -->|"no"| N
-```
-
-A markerless provider-scoped `cacheDir` is not removed on the initial miss. It is replaced only after a complete artifact has been staged, so a failed download does not destroy the previous files.
-
-#### Cache layout
-
-The cache identity is `<cacheDir>/<service>/<provider>/<version>/<assetName>/`. Including the provider prevents artifacts from different release sources from colliding when the catalog changes. A current cache entry is reusable only when it contains both the version-agnostic `.complete` marker and a payload file.
-
-The resolver also recognizes the previous `<cacheDir>/<service>/<version>/<assetName>/` layout for the four release providers supported by the old resolver. It reuses such an entry only when the service's expected executable exists. This keeps upgrades working offline without allowing a future provider change to inherit an artifact from an unrelated source.
-
-```
-~/.supabase/bin/
-  postgres/
-    github.com_supabase_postgres/
-      17.6.1.081/
-        darwin-arm64/       <- extracted binary tree
-          .complete
-          bin/
-            postgres
-  postgrest/
-    github.com_PostgREST_postgrest/
-      14.5/
-        macos-aarch64/
-          .complete
-          postgrest
-  auth/
-    github.com_supabase_auth/
-      2.187.0/
-        arm64/
-          .complete
-          auth
-```
-
-`BinaryResolver.cachePath` exposes this path calculation for focused unit tests. Release URLs, archive formats, checksums, and provider identities come from `ServiceArtifacts` rather than resolver-specific static helpers.
-
-#### Checksum verification
-
-Only postgres publishes SHA-256 checksums alongside its tarballs (as `<tarball-url>.sha256`). The verifier uses `node:crypto`'s `createHash("sha256")` to hash the downloaded bytes in memory before extraction, so a corrupted download is caught before any files are written to disk.
-
-#### Archive extraction
-
-Each resolver extracts into a per-invocation-unique sibling directory named `.<assetName>.partial-*`, never inside `cacheDir` itself. For tarballs (`.tar.gz`, `.tar.xz`), `tar` is used and catalog metadata decides whether to strip the top-level directory. For zip archives, `unzip` is used on Unix or `tar xf` on Windows. The subprocess is spawned through `ChildProcessSpawner`.
-
-After extraction, permissions are restored (`chmod`) and, on macOS, executables are ad-hoc code-signed. The `.complete` marker is written last and records the provider, service, version, asset, and source URL. Publication is a single atomic rename into `cacheDir`: one concurrent resolver wins, while losers reuse the winner's complete entry. Existing incomplete destinations are preserved rather than destructively replaced.
-
-An `Effect.ensuring` finalizer force-removes the staging directory on success, failure, or interruption. A best-effort sweep also reaps `.partial-*` siblings older than 24 hours. The sweep runs before the cache-hit check so abandoned staging directories are eventually removed even when the final cache is already complete.
-
-#### Layer wiring
-
-`BinaryResolver.make(cacheRoot)` requires `FileSystem | Path | HttpClient.HttpClient | ChildProcessSpawner.ChildProcessSpawner` from the environment. Entry-point layers provide those platform services and use `defaultCacheRoot()` when the caller does not configure a cache root.
-
----
-
-### resolveService — binary-first Docker fallback
-
-**File:** `src/resolve.ts`
-
-`resolveService` is a thin helper that wraps `BinaryResolver.resolve()` and implements the binary-first, Docker-fallback strategy used by `StackPreparation` and therefore shared by both `stack.start()` and `prefetch()`.
-
-#### ServiceResolution type
-
-```ts
-type ServiceResolution =
-  | { readonly type: "binary"; readonly path: string }
-  | { readonly type: "docker"; readonly image: string };
-```
-
-This discriminated union is the canonical output of resolution: downstream code switches on `type` to pick the right service factory.
-
-#### Resolution logic
-
-`resolveService(resolver, service, version)` calls `resolver.resolve({ service, version })` and maps the result:
-
-- **Success** (binary found and extracted) → `{ type: "binary", path }`.
-- **`BinaryNotFoundError`** (no native asset for this OS/arch) → `{ type: "docker", image }` using the default Docker image for the service and version.
-- **`DownloadError`** (network or extraction failure) → `{ type: "docker", image }` — falls back to Docker rather than hard-failing.
-- **`ChecksumMismatchError`** → propagates as a real error; a tampered or corrupted download is never silently replaced by Docker.
-
-```ts
-export const resolveService = (
-  resolver: BinaryResolver["Service"],
-  service: ServiceName,
-  version: string,
-): Effect.Effect<ServiceResolution, ChecksumMismatchError> =>
-  resolver.resolve({ service, version }).pipe(
-    Effect.map((path): ServiceResolution => ({ type: "binary", path })),
-    Effect.catchTag("BinaryNotFoundError", () =>
-      Effect.succeed<ServiceResolution>({
-        type: "docker",
-        image: dockerImageForService(service, version),
-      }),
-    ),
-    Effect.catchTag("DownloadError", () =>
-      Effect.succeed<ServiceResolution>({
-        type: "docker",
-        image: dockerImageForService(service, version),
-      }),
-    ),
-  );
-```
-
----
-
-### JwtGenerator — JWT token generation and opaque keys
-
-**File:** `src/JwtGenerator.ts`
-
-A focused service that encapsulates HS256 JWT signing. It also exports two hardcoded opaque API key constants that match the Go CLI defaults.
-
-#### Opaque key constants
-
-```ts
-// Hardcoded opaque key defaults matching Go CLI (pkg/config/apikeys.go:19-20).
-// These are client-facing keys for local dev — SDKs use these, not JWTs directly.
-export const defaultPublishableKey = "sb_publishable_ACJWlzQHlZjBrEguHvfOxg_3BJgxAaH";
-export const defaultSecretKey = "sb_secret_N7UND0UgjKTVK-Uodkm0Hg_xSvEMPvz";
-```
-
-These opaque keys (`publishableKey` / `secretKey`) are what callers and SDKs use. They are not JWTs. The `ApiProxy` translates them to the actual JWTs (`anonJwt` / `serviceRoleJwt`) before forwarding requests to GoTrue and PostgREST.
-
-#### Service interface
-
-```ts
-class JwtGenerator extends Context.Service<
-  JwtGenerator,
-  {
-    readonly generate: (secret: string, role: string) => Effect.Effect<string>;
-  }
->()("local/JwtGenerator") {}
-```
-
-`generate(secret, role)` produces a signed JWT with `{ role }` as the payload claim, using HMAC-SHA256 (`node:crypto`'s `createHmac("sha256", secret)`). Tokens are set to expire 10 years from issue time — appropriate for local development use.
-
-#### Layer
-
-`JwtGenerator.layer` is a `Layer.succeed` with no external dependencies — it has no I/O and requires no platform services.
-
----
-
-### PortAllocator — dynamic port assignment
-
-**File:** `src/PortAllocator.ts`
-
-`PortAllocator` resolves all port numbers before the stack starts. It supports explicit caller ports and random OS-assigned ports. `createStack()` uses leased allocation: each selected port remains bound until the API proxy or corresponding service dependency closure is ready to bind it.
-
-#### Interface
-
-```ts
-export const DEFAULT_API_PORT = 54321;
-export const DEFAULT_DB_PORT = 54322;
-
-export interface PortInput {
-  readonly apiPort?: number;
-  readonly dbPort?: number;
-  readonly authPort?: number;
-  readonly postgrestPort?: number;
-  readonly postgrestAdminPort?: number;
-}
-
-export interface AllocatedPorts {
-  readonly apiPort: number;
-  readonly dbPort: number;
-  readonly authPort: number;
-  readonly postgrestPort: number;
-  readonly postgrestAdminPort: number;
-}
-
-export const allocatePorts = (
-  input: PortInput,
-): Effect.Effect<AllocatedPorts, PortAllocationError>;
-
-export const reservePorts = (
-  input: PortInput,
-): Effect.Effect<PortLease, PortAllocationError>;
-```
-
-#### Two strategies
-
-- **Explicit port** (`input.apiPort !== undefined`) binds the specific port on `127.0.0.1` and fails with `PortAllocationError` if it is already in use.
-- **Omitted** binds port `0` on `127.0.0.1`, allowing the OS to assign a free port.
-
-#### Collision avoidance
-
-Allocated ports are tracked in a `Set<number>` and OS listeners prevent concurrent stacks from receiving the same assignment. The API lease is released immediately before the central proxy binds. Backend leases remain active in lazy mode and are released only for the graph dependency closure being started. Any remaining listeners are closed during stack disposal. `allocatePorts()` remains available as a probe-only low-level API; stack construction uses `reservePorts()`.
-
----
+    Input["StackConfig"] --> Resolve["resolveConfig"]
+    Resolve --> Layer["foregroundLayer"]
+    Layer --> Prepare["StackPreparation"]
+    Prepare --> Builder["StackBuilder"]
+    Builder --> Orch["process-compose Orchestrator"]
+    Layer --> Proxy["ApiProxy"]
+    Orch --> Stack["Stack Interface"]
+    Proxy --> Stack
+```
+
+`StackHandle` converts Effect calls and streams to Promises and `AsyncIterable`s and implements
+`AsyncDisposable`. The Effect `Stack` Interface is also implemented by `RemoteStack`, so CLI code
+can use the same lifecycle calls against an in-process stack or a detached daemon.
+
+## Configuration and roots
+
+`StackConfig` is an in-memory library input, not the project configuration-file schema. Its
+top-level fields choose runtime mode, startup mode, cache/runtime roots, API keys, JWT secret,
+functions options, and per-service configuration. `false` disables an optional service.
+
+`resolveConfig()`:
+
+1. chooses cache, durable stack, runtime, and project roots;
+2. allocates every required port through one port allocator;
+3. creates development JWTs and opaque publishable/secret keys;
+4. applies per-service defaults and current `DEFAULT_VERSIONS`;
+5. records auto-managed paths for scoped cleanup.
+
+The current zero-config stack enables PostgreSQL, PostgREST, Auth, and Edge Runtime. Realtime,
+Storage, imgproxy, Mailpit, Postgres Meta, Studio, Analytics, Vector, and Supavisor are enabled only
+when their corresponding configuration object is present. In `native` mode, Edge Runtime is also
+disabled by omission because the automatic artifact policy currently classifies it as Docker-only.
+
+`mode` has these meanings:
+
+- `native`: require native artifacts and reject enabled Docker-only services;
+- `auto`: prefer supported native artifacts, then fall back to Docker;
+- `docker`: resolve every enabled service to a Docker image.
+
+`startupMode` defaults to `eager`; `lazy` defers eligible proxied services until first use.
+
+## Preparation and artifact resolution
 
-### prefetch — pre-download binaries and images
+Preparation is separate from topology construction:
+
+- `ServiceArtifacts.ts` records native release providers and Docker image candidates.
+- `BinaryResolver` detects the platform, downloads and verifies archives, restores executable
+  permissions, and publishes complete cache entries atomically.
+- `StackPreparation` resolves all enabled public services, emits download/pull progress, and
+  returns `PreparedStackArtifacts`.
+- `StackBuilder` consumes only resolved artifacts; it does not perform network fetches.
 
-**File:** `src/prefetch.ts`
+Native cache identity includes service, provider, version, and asset name. `.complete` is written
+last, so an incomplete download is never treated as reusable. Supabase-owned Docker images are
+tried through ECR, Docker Hub, then GHCR; upstream images use their canonical repository.
+
+`prefetch()` uses the same `StackPreparation` Interface without constructing a lifecycle runtime.
 
-`prefetch` is now a thin wrapper over `StackPreparation`. It downloads all service binaries and pulls all Docker images concurrently, so the first `createStack()` or `stack.start()` call in a test run does not stall on slow downloads.
+## Service coverage and topology
+
+`StackBuilder.build(config, prepared)` is the explicit owner of cross-service topology. Individual
+factories under `src/services/` own executable arguments, environment, mounts, health checks, and
+per-process cleanup. The builder owns which definitions exist and how they depend on one another.
 
-#### Interface
+| Public service | Automatic runtime support               | Principal dependency or role                                                                                       |
+| -------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `postgres`     | Native preferred, Docker fallback       | Root database process. Native PostgreSQL also introduces the internal `postgres-init` one-shot definition.         |
+| `postgrest`    | Native preferred, Docker fallback       | Database initialization completed, or PostgreSQL healthy in all-Docker mode.                                       |
+| `auth`         | Native preferred, Docker fallback       | Database initialization completed/healthy; optionally sends mail through Mailpit.                                  |
+| `edge-runtime` | Docker-only under automatic preparation | Database initialization completed/healthy; reads a generated functions runtime file.                               |
+| `realtime`     | Docker                                  | Database initialization completed/healthy; started eagerly and routed by the API proxy for ordinary HTTP requests. |
+| `storage`      | Docker                                  | Database initialization completed/healthy; optionally calls imgproxy.                                              |
+| `imgproxy`     | Docker                                  | Storage healthy; owned and activated with Storage.                                                                 |
+| `mailpit`      | Docker                                  | Direct web, SMTP, and POP3 listeners.                                                                              |
+| `pgmeta`       | Docker                                  | Database initialization completed/healthy.                                                                         |
+| `analytics`    | Docker                                  | Database initialization completed/healthy.                                                                         |
+| `vector`       | Docker                                  | Analytics healthy; owned and activated with Analytics.                                                             |
+| `pooler`       | Docker                                  | Database initialization completed/healthy; direct database and admin listeners.                                    |
+| `studio`       | Docker                                  | Postgres Meta healthy and, when enabled, Analytics healthy.                                                        |
 
-```ts
-export interface PrefetchOptions {
-  readonly versions?: Partial<VersionManifest>;
-  /** Services to prefetch. Defaults to all. */
-  readonly services?: ReadonlyArray<ServiceName>;
-}
+`postgres-init` is an internal helper only for native PostgreSQL. It applies initial schema and
+privilege setup and completes before database consumers start. `StackStateProjection` hides it and
+projects active initialization as `postgres: Initializing`; helper failure is projected onto
+PostgreSQL.
 
-export type PrefetchResult = Record<string, ServiceResolution>;
+Configuration validation prevents unsupported combinations, including imgproxy without Storage,
+Vector without Analytics, and Studio without Postgres Meta.
 
-export const prefetch: (
-  options?: PrefetchOptions,
-) => Effect.Effect<
-  PrefetchResult,
-  DockerPullError | ChecksumMismatchError,
-  BinaryResolver | ChildProcessSpawner
->;
-```
-
-#### How it works
-
-For each requested service, `prefetch` delegates to `StackPreparation.prepare()`:
-
-- If the result is `{ type: "binary" }`, the binary is already cached — nothing more to do.
-- If the result is `{ type: "docker" }`, `prefetch` runs `docker pull <image>` via `ChildProcessSpawner`. A non-zero exit code or a `PlatformError` both map to `DockerPullError`.
-
-All services are resolved and pulled concurrently (`concurrency: "unbounded"`). The returned `PrefetchResult` maps each service name to its `ServiceResolution`.
-
-#### Typical usage — vitest globalSetup
-
-```ts
-// vitest.config.ts / globalSetup.ts
-import { prefetch } from "@supabase/stack";
-
-export async function setup() {
-  await prefetch(); // downloads auto-mode assets for all services before any test runs
-  await prefetch({ mode: "docker" }); // pulls Docker images for all services
-}
-```
-
-Pass `versions` to pin specific versions, or `services` to fetch a subset.
-
----
-
-### ApiProxy — reverse proxy with key translation
-
-**File:** `src/ApiProxy.ts`
-
-`ApiProxy` is a reverse proxy that sits in front of GoTrue (auth) and PostgREST (REST API). Its primary job is to translate opaque API keys (`publishableKey`, `secretKey`) into JWTs before forwarding requests to the backend services. It also handles CORS and standard proxy headers.
-
-#### Service interface
-
-```ts
-export interface ProxyConfig {
-  readonly listenPort: number;
-  readonly gotruePort: number;
-  readonly postgrestPort: number;
-  readonly postgrestAdminPort: number;
-  readonly publishableKey: string; // opaque — e.g. "sb_publishable_..."
-  readonly secretKey: string; // opaque — e.g. "sb_secret_..."
-  readonly anonJwt: string; // internal HS256 JWT passed to GoTrue/PostgREST
-  readonly serviceRoleJwt: string; // internal HS256 JWT passed to GoTrue/PostgREST
-}
-
-class ApiProxy extends Context.Service<
-  ApiProxy,
-  {
-    readonly address: HttpServer.Address;
-  }
->()("local/ApiProxy") {
-  static layer: (
-    config: ProxyConfig,
-  ) => Layer.Layer<ApiProxy, never, HttpServer.HttpServer | HttpClient.HttpClient>;
-}
-```
-
-#### Request routing
-
-| Route pattern        | Backend           | Auth transformation |
-| -------------------- | ----------------- | ------------------- |
-| `GET /health`        | (local, 200 OK)   | none                |
-| `/auth/v1/verify`    | GoTrue            | none (open)         |
-| `/auth/v1/callback`  | GoTrue            | none (open)         |
-| `/auth/v1/authorize` | GoTrue            | none (open)         |
-| `/auth/v1/*`         | GoTrue            | key translation     |
-| `/rest/v1/*`         | PostgREST         | key translation     |
-| `/rest-admin/v1/*`   | PostgREST (admin) | none                |
-
-#### Key translation logic
-
-`transformAuthorization` is called for routes marked with auth transformation:
-
-1. If `Authorization` is present and is NOT `Bearer sb_*`, pass it through (caller has a real JWT).
-2. If `apikey` matches `publishableKey` → set `Authorization: Bearer <anonJwt>`.
-3. If `apikey` matches `secretKey` → set `Authorization: Bearer <serviceRoleJwt>`.
-4. If `apikey` is present but unrecognized → pass it through as `Authorization`.
-
-```mermaid
-flowchart TD
-    REQ["Incoming request"] --> AUTH{"Authorization header<br/>not Bearer sb_*?"}
-    AUTH -->|"yes"| PASS["Pass through unchanged"]
-    AUTH -->|"no / missing"| KEY{"apikey header?"}
-    KEY -->|"= publishableKey"| ANON["Authorization: Bearer anonJwt"]
-    KEY -->|"= secretKey"| SVC["Authorization: Bearer serviceRoleJwt"]
-    KEY -->|"other"| FWD["Authorization: <apikey value>"]
-    KEY -->|"missing"| NONE["No Authorization header"]
-    PASS --> BACKEND["Forward to backend"]
-    ANON --> BACKEND
-    SVC --> BACKEND
-    FWD --> BACKEND
-    NONE --> BACKEND
-```
-
-#### CORS handling
-
-All responses receive standard CORS headers (`access-control-allow-origin: *`, etc.). `OPTIONS` preflight requests are intercepted globally and receive a `204 No Content` response before reaching the router — this matches the Go proxy behavior.
-
-#### Layer requirements
-
-`ApiProxy.layer(config)` requires `HttpServer.HttpServer | HttpClient.HttpClient`. The `HttpServer` instance is platform-provided (via `bun.ts` or `node.ts`); `HttpClient` is provided by `FetchHttpClient.layer` in `createStack.ts`.
-
----
-
-### services — ServiceDef factories
-
-**Files:** `src/services/postgres.ts`, `src/services/postgrest.ts`, `src/services/auth.ts`
-
-Pure factory functions that construct `ServiceDef` objects for `@supabase/process-compose`. No Effect, no async — just data construction. This separation means the shape of each service definition can be tested with plain `vitest` `it()` calls without any Effect infrastructure.
-
-#### postgres
-
-```ts
-interface PostgresServiceOptions {
-  readonly binPath: string; // path to extracted binary dir (contains start.sh)
-  readonly dataDir: string; // PGDATA directory
-  readonly port: number;
-}
-```
-
-Postgres is the foundation of the stack. It has no dependencies and uses a TCP health check (connecting to port 5432) rather than HTTP. The TCP probe is appropriate here because postgres doesn't expose an HTTP endpoint — a successful connection on the port indicates the server is accepting connections.
-
-The start command is `${binPath}/start.sh`, not the postgres binary directly, because the supabase-postgres release includes a wrapper script that sets the correct extension paths and configuration.
-
-Shutdown uses `SIGINT` (not the default `SIGTERM`) with a 15-second timeout. Postgres responds to `SIGINT` with a fast shutdown: it terminates connections and exits cleanly, whereas `SIGTERM` triggers a slower smart shutdown that waits for clients to disconnect.
-
-Postgres has two factories (like auth) because there is no Windows native binary:
-
-```ts
-// Native binary — macOS and Linux
-export const makePostgresService = (opts: NativePostgresOptions): ServiceDef
-
-// Docker — fallback for Windows
-export const makePostgresServiceDocker = (opts: DockerPostgresOptions): ServiceDef
-```
-
-Both share `postgresEnv()` and `postgresHealthCheck()` helpers. The Docker variant mounts the data directory as a volume (`-v dataDir:/var/lib/postgresql/data`) and publishes the configured host port to the container port.
-
-#### postgrest
-
-```ts
-interface PostgrestServiceOptions {
-  readonly binPath: string; // path to the postgrest binary
-  readonly dbPort: number;
-  readonly apiPort: number;
-  readonly schemas: ReadonlyArray<string>;
-  readonly extraSearchPath: ReadonlyArray<string>;
-  readonly maxRows: number;
-  readonly jwtSecret: string;
-}
-```
-
-PostgREST depends on postgres being `healthy` before it starts. It uses an HTTP health check on `GET /` which PostgREST serves once it has established a database connection. Key environment variables are translated directly from config options — schema lists are joined with commas because PostgREST's `PGRST_DB_SCHEMAS` expects a comma-separated string.
+## Lifecycle ownership
 
-The anonymous role is hardcoded to `anon`: this matches the Supabase database convention where the `anon` role has limited public permissions enforced by Row Level Security.
+The current local Implementation is `StackLifecycleCoordinator`. It owns one scoped lifecycle:
 
-#### auth (two factories)
+- preparation and its single-flight deferred;
+- graph construction and the process-compose runtime;
+- a shared `LogBuffer`;
+- public state projection;
+- activation and lifecycle locks;
+- exact cleanup targets and metadata persistence;
+- disposal of processes, Docker resources, ports, and auto-managed paths.
 
-Auth has two factories because the stack supports both native and Docker auth launches:
+`Stack.ts` currently provides a thin public Effect Interface over that coordinator. `ApiProxy`
+uses the narrower `StackServiceActivator` Interface so an incoming request can activate a lazy
+backend without gaining unrelated lifecycle operations.
 
-```ts
-// Native binary
-export const makeAuthServiceNative = (opts: NativeAuthOptions): ServiceDef
+Before the orchestrator exists, the coordinator publishes synthetic `Pending` and `Downloading`
+states. After construction, it subscribes to raw process-compose state and publishes only public
+projected states. `StackServiceState` adds `Downloading`, `Initializing`, and `Dormant` to the raw
+process statuses.
 
-// Docker fallback
-export const makeAuthServiceDocker = (opts: DockerAuthOptions): ServiceDef
-```
+`start()` prepares artifacts, creates the runtime once, starts the appropriate services, and waits
+for their generic process-compose readiness. `stop()` preserves explicit per-service stop intent;
+`dispose()` additionally closes the scoped runtime and executes cleanup. Current generic readiness
+has no built-in deadline.
 
-Both factories share the `authEnv()` helper which builds the `GOTRUE_*` environment variables from the same `AuthBaseOptions`. The native factory sets `command` to the binary path; the Docker factory sets `command: "docker"` and builds `args: ["run", "--rm", ...networkArgs, ...envArgs, image]`.
+## Eager and lazy activation
 
-Docker services reach host-native services through `host.docker.internal`. On Linux the stack adds Docker's `host-gateway` alias explicitly; Docker Desktop provides that host name on macOS and Windows. This keeps published-port behavior consistent across all supported operating systems.
+`ServiceActivation.ts` is the declarative startup and companion-ownership policy:
 
-Both variants use an HTTP health check on `GET /health` (the GoTrue health endpoint). Both depend on postgres being `healthy` before starting.
+- eager: PostgreSQL, Realtime, Mailpit, Studio, and Pooler;
+- lazy: PostgREST, Auth, Edge Runtime, Storage, imgproxy, Postgres Meta, Analytics, and Vector;
+- Storage activates and owns imgproxy;
+- Analytics activates and owns Vector;
+- Studio activates Analytics but does not own it.
 
----
+In eager startup mode, every enabled service is started. In lazy mode, the internal
+`postgres-init` service, enabled eager services, and any activation companions they require start
+initially. Proxy handlers activate their backend before forwarding, with single-flight lifecycle
+coordination and a 30-second proxy activation timeout. Unrequested lazy services project as
+`Dormant`; `waitAllReady()` considers only services desired to run.
 
-### StackBuilder — assemble the dependency graph
+Realtime stays eager because the HTTP proxy owns ordinary request forwarding, while WebSocket
+transport is not duplicated in a separate lazy-activation Adapter. Direct listeners must also
+exist before their endpoints are advertised.
 
-**File:** `src/StackBuilder.ts`
+## API proxy and connection information
 
-`StackBuilder` is now graph-only. Asset preparation moved out into `StackPreparation`, so
-`StackBuilder` receives a `ResolvedStackConfig` plus `PreparedStackArtifacts`, constructs the
-complete `ServiceDef[]` list, and passes it to `buildGraph()` from `@supabase/process-compose`.
+`ApiProxy` owns the public API port and routes Supabase paths to loopback service ports. It covers
+Auth, PostgREST, Edge Functions, Realtime, Storage, Postgres Meta, Analytics, Pooler administration,
+and Studio's MCP route. It adds forwarding/CORS headers and translates opaque `publishableKey` and
+`secretKey` values into the internal anon and service-role JWTs when appropriate.
 
-#### Service interface
+`StackInfo` contains user-facing connection data:
 
-```ts
-class StackBuilder extends Context.Service<
-  StackBuilder,
-  {
-    readonly build: (
-      config: ResolvedStackConfig,
-      prepared: PreparedStackArtifacts,
-    ) => Effect.Effect<BuildResult, StackBuildError>;
-  }
->()("local/StackBuilder") {}
-```
+- API URL and database URL;
+- opaque publishable and secret keys;
+- internal anon and service-role JWTs;
+- endpoints for enabled services.
 
-`build()` is the only method. It takes a fully resolved `ResolvedStackConfig` (all defaults applied,
-ports concrete, JWTs generated) plus prepared binary / Docker resolutions and returns the graph,
-public service projection metadata, and exact cleanup targets.
-
-#### ResolvedStackConfig
-
-`StackBuilder.build()` receives a `ResolvedStackConfig`, not the raw user-facing `StackConfig`. All resolution (port allocation, JWT generation, default application) happens in `createStack.ts` before `build()` is called:
-
-```ts
-interface ResolvedStackConfig {
-  readonly startupMode: "eager" | "lazy";
-  readonly jwtSecret: string;
-  readonly apiPort: number;
-  readonly dbPort: number;
-  readonly publishableKey: string;
-  readonly secretKey: string;
-  readonly autoManagedDataDir: boolean;
-  readonly anonJwt: string;
-  readonly serviceRoleJwt: string;
-  readonly postgres: ResolvedPostgresConfig;
-  readonly postgrest: ResolvedPostgrestConfig | false;
-  readonly auth: ResolvedAuthConfig | false;
-}
-```
+Cleanup targets do not belong to `StackInfo`; they are internal runtime metadata.
 
-Setting `postgrest` or `auth` to `false` excludes those services entirely. Postgres is always included.
+## Functions runtime configuration and reload
 
-#### Build flow
+The current `functions.ts` Implementation discovers project configuration and function manifests,
+resolves paths and environment values, combines them with stack URLs/keys, and writes
+`functions-runtime-config.json` under the Edge Runtime workspace. The Edge Runtime factory mounts
+or references that file.
 
-```mermaid
-flowchart TD
-    A["StackPreparation.prepare(config)"] --> B["PreparedStackArtifacts"]
-    B --> C["StackBuilder.build(config, prepared)"]
-    C --> D["BuildResult"]
-```
+`reloadFunctions()` rewrites the file and updates/restarts the Edge Runtime definition.
+`reloadEdgeRuntime()` can change runtime settings and optionally functions settings. In detached
+mode, `/functions/reload` currently carries `envFile` and `noVerifyJwt` as query parameters, while
+`/edge-runtime/reload` accepts a validated JSON body.
 
-Docker vs native selection, cache probing, binary downloads, and Docker pulls now happen entirely in
-`StackPreparation`. `StackBuilder` only consumes the prepared resolutions and turns them into graph
-definitions plus cleanup metadata.
-
----
-
-### StackLifecycleCoordinator — lifecycle management
-
-**File:** `src/StackLifecycleCoordinator.ts`
-
-`StackLifecycleCoordinator` is the top-level runtime coordinator. It owns the startup state machine,
-drives `StackPreparation`, builds the orchestrator from `StackBuilder`, persists cleanup targets,
-and exposes the unified public state stream used by both in-process and daemon-backed flows.
-
-#### Service interface
-
-```ts
-class StackLifecycleCoordinator extends Context.Service<
-  StackLifecycleCoordinator,
-  {
-    readonly getInfo: () => Effect.Effect<StackInfo>;
-    readonly start: () => Effect.Effect<void, ServiceReadyError | StackBuildError>;
-    readonly stop: () => Effect.Effect<void>;
-    readonly startService: (
-      name: string,
-    ) => Effect.Effect<void, ServiceNotFoundError | ServiceReadyError | StackBuildError>;
-    readonly stopService: (
-      name: string,
-    ) => Effect.Effect<void, ServiceNotFoundError | StackBuildError>;
-    readonly restartService: (
-      name: string,
-    ) => Effect.Effect<void, ServiceNotFoundError | StackBuildError>;
-    readonly getState: (name: string) => Effect.Effect<StackServiceState, ServiceNotFoundError>;
-    readonly getAllStates: () => Effect.Effect<ReadonlyArray<StackServiceState>>;
-    readonly stateChanges: (
-      name: string,
-    ) => Effect.Effect<Stream.Stream<StackServiceState>, ServiceNotFoundError>;
-    readonly allStateChanges: () => Stream.Stream<StackServiceState>;
-    readonly waitReady: (
-      name: string,
-    ) => Effect.Effect<void, ServiceNotFoundError | ServiceReadyError | StackBuildError>;
-    readonly waitAllReady: () => Effect.Effect<void, ServiceReadyError | StackBuildError>;
-    readonly subscribeLogs: (name: string) => Stream.Stream<LogEntry>;
-    readonly subscribeAllLogs: (services?: ReadonlyArray<string>) => Stream.Stream<LogEntry>;
-    readonly logHistory: (name: string, limit?: number) => Effect.Effect<ReadonlyArray<LogEntry>>;
-    readonly logHistoryAll: (
-      limit?: number,
-      services?: ReadonlyArray<string>,
-    ) => Effect.Effect<ReadonlyArray<LogEntry>>;
-  }
->()("stack/StackLifecycleCoordinator") {}
-```
+## Port leases
 
-Internally, the coordinator owns these lifecycle phases:
-
-- `idle`
-- `preparing`
-- `prepared`
-- `starting`
-- `running`
-- `stopping`
-- `stopped`
-
-Before the orchestrator exists, it publishes synthetic service states derived from config. That is
-why `getAllStates()` and `allStateChanges()` can surface `Downloading` during cold-cache startup
-even though no process has been spawned yet.
-
-`ServiceActivation.ts` is the declarative policy for startup and lifecycle ownership. It marks
-services as eager or lazy, declares activation companions, and declares owned companions. Storage
-activates and owns imgproxy; Analytics activates and owns Vector; Studio activates Analytics but
-does not own it. Process dependencies remain the responsibility of the process graph.
-
-The package defaults to `startupMode: "eager"`. In `"lazy"` mode, `start()` starts and waits only
-for direct listeners, Realtime, and Studio. Each HTTP proxy route activates its target service
-before it forwards the request, and concurrent activation remains single-flight in the
-orchestrator. Proxy
-requests made before startup or after shutdown receive `503 Service Unavailable`. `waitAllReady()`
-waits for services whose orchestrator desired state is `running`, rather than blocking on
-intentionally dormant ones. The public projection maps unrequested services to the explicit
-`Dormant` status. Readiness includes the process graph's dependency closure and fails immediately
-for dormant or explicitly stopped services. An explicit service stop remains `Stopped` across a
-whole-stack stop/start until that service is explicitly started again.
-
-Detached mode preserves these semantics instead of reconstructing readiness from status snapshots.
-The daemon exposes `/ready` and `/services/:name/ready`, both of which delegate to the lifecycle
-coordinator. Typed error discriminants preserve service-not-found, service-readiness, and stack-build
-failures across the HTTP boundary.
-
-Realtime starts eagerly because the HTTP proxy only owns ordinary request forwarding; WebSocket
-transport is not duplicated in platform-specific stack adapters.
-
-#### StackInfo
-
-```ts
-interface StackInfo {
-  readonly url: string; // "http://127.0.0.1:<apiPort>"
-  readonly dbUrl: string; // "postgresql://postgres:postgres@127.0.0.1:<dbPort>/postgres"
-  readonly publishableKey: string; // opaque key for SDK consumers
-  readonly secretKey: string; // opaque key for SDK consumers (privileged)
-  readonly anonJwt: string; // internal HS256 JWT (role: "anon")
-  readonly serviceRoleJwt: string; // internal HS256 JWT (role: "service_role")
-  readonly serviceEndpoints: Readonly<Record<string, string>>;
-}
-```
+Port allocation returns a `PortLease`, not just numbers. The stack reserves ports before cold asset
+preparation. The lifecycle Adapter passes:
 
-The `url` points to the `ApiProxy` listener, not to PostgREST directly. Callers use
-`publishableKey` / `secretKey` as their API keys; the proxy translates them to JWTs internally.
-`StackInfo` intentionally does not include runtime cleanup details such as Docker container names.
-Those are persisted separately as internal metadata after preparation/build.
+- `beforeStart` to reserve the service's fields again for a restart generation;
+- `beforeSpawn` to release those fields immediately before process creation;
+- a platform-factory release Effect for the public API server.
 
-#### Layer construction
+This narrows but cannot completely remove the race between releasing a reservation and the child
+binding. Supervised Docker services have a wider window because the supervisor starts before
+`docker run` binds published ports.
 
-```mermaid
-graph TB
-    subgraph "StackLifecycleCoordinator.layer(config)"
-        PREP["StackPreparation.prepareEvents()<br/><i>emits Downloading + prepared artifacts</i>"]
-        SB["StackBuilder.build(config, prepared)<br/><i>produces ResolvedGraph</i>"]
-        LB["LogBuffer.layer<br/><i>shared between Orchestrator + coordinator</i>"]
-        OL["Orchestrator.layer(graph)<br/><i>provided with shared LogBuffer</i>"]
-        EP["Layer.buildWithScope(orchLayer, scope)<br/><i>scoped to coordinator scope</i>"]
-        INFO["StackInfo object<br/><i>built from ResolvedStackConfig — no JWT generation needed</i>"]
-        STATE["SubscriptionRef<StackServiceState[]><br/><i>authoritative public state stream</i>"]
-    end
-
-    PREP --> SB
-    SB --> LB
-    LB --> OL
-    OL --> EP
-    EP --> STATE
-    STATE --> INFO
-```
-
-The `LogBuffer` is created at coordinator level and shared with the `Orchestrator`. This gives the
-coordinator direct access to `logBuffer.subscribe(name)`, `logBuffer.subscribeAll()`, and
-`logBuffer.history(name, limit)` — powering the `subscribeLogs`, `subscribeAllLogs`,
-`logHistory`, and `logHistoryAll` methods without going through the Orchestrator.
+## Cleanup and crash recovery
 
-Public status is projected in `@supabase/stack`, not exposed raw from `@supabase/process-compose`.
-Helper jobs like `postgres-init` remain part of the process graph, but the public stack API hides
-them and instead projects their lifecycle onto the owning service. While `postgres-init` is active,
-callers see `postgres: Initializing`.
+Every Docker definition has ordinary in-process cleanup and supervisor-owned orphan cleanup.
+`StackBuilder` also returns exact Docker container names for the definitions it constructed. The
+coordinator persists these targets for managed daemons and uses them as a force-removal safety net
+after graceful stop. Auto-created PostgreSQL, Storage, and runtime paths are also removed.
 
-The Orchestrator layer is constructed inside `StackLifecycleCoordinator.layer` using
-`Layer.buildWithScope`. This means the Orchestrator lives within the coordinator's scope: when the
-runtime is disposed, the Orchestrator's scope closes, which triggers `FiberMap` to interrupt all
-service fibers and run their shutdown finalizers.
+Cleanup is intentionally defensive:
 
-#### JWT fields and key naming
+1. process-compose finalizers stop individual process trees and run definition cleanup;
+2. supervisor runtimes survive abrupt owner loss long enough to kill child trees and clean
+   external resources;
+3. stack disposal force-removes exact known Docker containers;
+4. managed `stop` can use persisted cleanup metadata after daemon death;
+5. startup failure has candidate cleanup derived from the requested configuration.
 
-The public `Stack` service is now a thin facade over `StackLifecycleCoordinator`. `StackInfo`
-contains only stable user-facing connection info; exact cleanup targets are internal runtime
-metadata persisted separately for crash recovery.
+These paths overlap by design and must remain idempotent.
 
----
+## Foreground and daemon Adapters
 
-### createStack — platform-agnostic core
+`foregroundLayer()` builds the local stack and API proxy in the caller process.
 
-**File:** `src/createStack.ts`
+Detached mode adds:
 
-`createStack` is the platform-agnostic core. It wires all layers, delegates to a `ManagedRuntime`, and returns a rich `Stack` interface. It takes a `PlatformFactory` parameter — a function receiving `{ apiPort, releaseApiPort }` — so the platform-specific HTTP server (Bun or Node.js) can release the reserved API port immediately before binding it. Platform-specific HTTP layers (`BunHttpServer` and `NodeHttpServer`) are provided by the entry points (`bun.ts`, `node.ts`), not baked in.
+- `daemonLayer()`: forks a runtime-specific daemon entrypoint and returns a `RemoteStack` layer;
+- `daemon.ts`: receives the configuration over Node IPC, resolves ports, builds the foreground
+  daemon layer, claims live state, and waits for HTTP stop or a signal;
+- `DaemonServer`: exposes the `Stack` Interface over HTTP/SSE on a Unix-domain socket;
+- `RemoteStack`: maps that transport back to the same Effect `Stack` Interface;
+- `StateManager`: atomically persists and discovers durable metadata and live state.
 
-`createStack` also owns `resolveConfig()`, the internal async function that turns a raw
-`StackConfig` into a `ResolvedStackConfig`: it allocates ports via `PortAllocator`, generates JWTs
-via `generateJwt()` from `JwtGenerator.ts`, creates an ephemeral temp directory if no `dataDir`
-was specified, and applies all service config defaults.
+The management transport includes health, status, status stream, start/stop, readiness,
+per-service lifecycle, logs/history, and Edge Runtime reload routes. It is local Unix-socket
+transport, not the public Supabase API proxy.
 
-Once the runtime is built, `stack.start()` now means:
+See [detach mode](./detach-mode.md) for paths, process startup, and compiled executable dispatch.
 
-1. prepare assets via `StackPreparation`
-2. publish synthetic `Downloading` states on cache misses
-3. build the orchestrator through `StackBuilder`
-4. start services and wait for health through `StackLifecycleCoordinator`
+## Managed paths
 
-#### PlatformLayer type
-
-```ts
-/**
- * The minimum set of platform services required to run a local stack.
- * Platform entry points (bun.ts, node.ts) provide layers that satisfy this type.
- */
-export type PlatformServices =
-  | FileSystem.FileSystem
-  | Path.Path
-  | ChildProcessSpawner.ChildProcessSpawner
-  | HttpServer.HttpServer;
-
-export type PlatformLayer = Layer.Layer<PlatformServices>;
-```
+With the default cache root (`~/.supabase`), durable data is project-keyed:
 
-#### Stack interface
-
-```ts
-interface Stack extends AsyncDisposable {
-  // Connection info
-  readonly url: string; // proxy listener URL
-  readonly dbUrl: string;
-  readonly publishableKey: string; // opaque publishable API key for SDK consumers
-  readonly secretKey: string; // opaque secret API key for privileged SDK consumers
-
-  // Stack lifecycle
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  dispose(): Promise<void>;
-
-  // Per-service lifecycle
-  startService(name: string): Promise<void>;
-  stopService(name: string): Promise<void>;
-  restartService(name: string): Promise<void>;
-
-  // Status
-  getStatus(): Promise<ReadonlyArray<StackServiceState>>;
-  getServiceStatus(name: string): Promise<StackServiceState>;
-  statusChanges(): AsyncIterable<StackServiceState>;
-
-  // Logs
-  logs(): AsyncIterable<LogEntry>;
-  serviceLogs(name: string): AsyncIterable<LogEntry>;
-  logHistory(name: string, limit?: number): Promise<ReadonlyArray<LogEntry>>;
-
-  // Readiness
-  ready(opts?: ReadyOptions): Promise<void>;
-  serviceReady(name: string, opts?: ReadyOptions): Promise<void>;
-
-  // AsyncDisposable — supports `await using stack = await createStack(...)`
-  [Symbol.asyncDispose](): Promise<void>;
-}
-
-async function createStack(
-  config: StackConfig | undefined,
-  platformFactory: PlatformFactory,
-): Promise<Stack>;
+```text
+<cacheRoot>/projects/<sha256(projectDir)[0:16]>/stacks/<name>/
+  stack.json
+  state.json
+  data/
 ```
 
-`Stack` implements `AsyncDisposable`, so it works with the `await using` statement in environments that support it.
+The live runtime directory is short and outside the project tree:
 
-All `Stack` methods that can fail throw `StackError` (not Effect tagged errors), making them straightforward to catch in non-Effect code.
-
-#### Layer composition
-
-```mermaid
-graph BT
-    subgraph "Runtime layers (bottom to top)"
-        PL["PlatformLayer<br/><i>provided by bun.ts / node.ts<br/>— FileSystem, Path, ChildProcessSpawner, HttpServer</i>"]
-        FH["FetchHttpClient.layer<br/><i>for BinaryResolver + ApiProxy</i>"]
-        BRL["BinaryResolver.layer<br/><i>+ FetchHttpClient</i>"]
-        PREP["StackPreparation.layer<br/><i>+ BinaryResolver</i>"]
-        SBL["StackBuilder.layer"]
-        COORD["StackLifecycleCoordinator.layer(resolvedConfig)<br/><i>+ StackPreparation + StackBuilder</i>"]
-        STACK["Stack.layer(resolvedConfig)<br/><i>thin facade over coordinator</i>"]
-        APL["ApiProxy.layer(proxyConfig)<br/><i>+ FetchHttpClient</i>"]
-        FULL["Layer.mergeAll(Stack, ApiProxy)<br/><i>+ PlatformLayer</i>"]
-    end
-
-    PL --> FULL
-    FH --> BRL
-    BRL --> PREP
-    PREP --> COORD
-    SBL --> COORD
-    COORD --> STACK
-    STACK --> FULL
-    FH --> APL
-    APL --> FULL
+```text
+/tmp/supabase/s-<sha256(stackRoot)[0:12]>/
+  daemon-<generation>.sock
 ```
 
-The assembled layer is passed to `ManagedRuntime.make()`. A `ManagedRuntime` is an Effect runtime that holds an open scope — resources allocated inside the scope (like the Orchestrator's `FiberMap`) stay alive as long as the runtime is alive. Calling `runtime.dispose()` closes the scope, which triggers all finalizers and kills all spawned processes.
-
-Streams (`statusChanges`, `logs`, `serviceLogs`) are converted to `AsyncIterable` via `Stream.toAsyncIterableWith(stream, services)`, which requires the runtime's services map for correct resource management.
-
----
-
-### bun.ts / node.ts — runtime implementations behind the root export
+Windows substitutes its system temporary directory for `/tmp`. Socket names are generation-scoped
+so a delayed daemon shutdown cannot unlink a replacement daemon's socket.
 
-**Files:** `src/bun.ts`, `src/node.ts`
+Callers may explicitly supply `projectStateRoot`, in which case durable stacks live under
+`<projectStateRoot>/stacks/`; managed daemon callers may not directly override individual
+`stackRoot` or `runtimeRoot` values.
 
-These thin wrappers are the runtime-specific implementations selected by the package root export conditions. Each one constructs the platform-specific layer and delegates to `createStack` from `createStack.ts`.
+## Runtime entrypoints and exports
 
-```ts
-// bun.ts
-import * as BunHttpServer from "@effect/platform-bun/BunHttpServer";
-
-export async function createStack(config?: StackConfig): Promise<Stack> {
-  return createStackCore(
-    config,
-    (apiPort) => BunHttpServer.layer({ port: apiPort }) as unknown as PlatformLayer,
-  );
-}
-```
-
-```ts
-// node.ts
-import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer";
-
-export async function createStack(config?: StackConfig): Promise<Stack> {
-  return createStackCore(config, (apiPort) => {
-    const spawnerLayer = NodeChildProcessSpawnerLayer.pipe(
-      Layer.provide(Layer.mergeAll(NodeFileSystemLayer, NodePathLayer)),
-    );
-    const httpServerLayer = NodeHttpServer.layer(() => createServer(), { port: apiPort });
-    return Layer.mergeAll(httpServerLayer, spawnerLayer) as unknown as PlatformLayer;
-  });
-}
-```
-
-Callers import from the package root:
-
-```ts
-import { createStack } from "@supabase/stack";
-```
-
-The `HttpServer` instance is configured to listen on `apiPort` — this is the port that `ApiProxy` binds to, so the proxy's listener port matches the configured API port.
-
----
-
-## Data flow
-
-End-to-end from caller to running stack:
-
-```mermaid
-graph TB
-    subgraph "1. Entry"
-        CS["createStack(config, platformFactory)"]
-    end
-
-    subgraph "2. Layer assembly"
-        LA["ManagedRuntime.make(fullLayer)<br/><i>wires BinaryResolver → StackPreparation → StackBuilder → StackLifecycleCoordinator + ApiProxy</i>"]
-    end
-
-    subgraph "3. Asset preparation"
-        DP["detectPlatform()"]
-        CH["check ~/.supabase/bin cache"]
-        DL["HttpClient.get GitHub release tarball"]
-        PI["docker pull image when service resolves to Docker"]
-        VR["verify SHA-256 (node:crypto createHash)"]
-        EX["ChildProcessSpawner → tar extract to cache"]
-        DS["publish synthetic Downloading states"]
-    end
-
-    subgraph "4. Graph assembly"
-        SD["makePostgresService()<br/>makePostgrestService()<br/>makeAuthServiceNative/Docker()"]
-        BG["buildGraph(allDefs)<br/><i>topological sort + validation</i>"]
-    end
-
-    subgraph "5. Orchestrator startup"
-        OL["Orchestrator.layer(graph) + shared LogBuffer"]
-        FM["FiberMap — one fiber per service"]
-        DEP["Await dependency state streams<br/><i>postgres healthy before postgrest/auth</i>"]
-        SP["ChildProcessSpawner.spawn()"]
-        HC["HealthProbe running"]
-    end
-
-    subgraph "6. ApiProxy startup"
-        AP["ApiProxy.layer(proxyConfig)<br/><i>binds HttpServer on apiPort</i>"]
-        KT["Key translation: publishableKey → anonJwt<br/>secretKey → serviceRoleJwt"]
-    end
-
-    subgraph "7. Output"
-        SI["Stack { url, publishableKey, secretKey, dbUrl,<br/>start/stop, ready, per-service, status, logs, dispose }"]
-    end
-
-    CS --> LA
-    LA --> DP
-    DP --> CH
-    CH -->|"miss"| DL
-    DL --> VR
-    VR --> EX
-    CH -->|"docker"| PI
-    DL --> DS
-    PI --> DS
-    EX --> SD
-    PI --> SD
-    CH -->|"hit"| SD
-    SD --> BG
-    BG --> OL
-    OL --> FM
-    FM --> DEP
-    DEP --> SP
-    SP --> HC
-    HC -->|"healthy"| AP
-    AP --> KT
-    KT --> SI
-```
-
----
+- `bun.ts` and `node.ts` are root export-condition targets.
+- `daemon-bun.ts` is exported as `@supabase/stack/daemon-bun` so the compiled CLI can dispatch to
+  it in-process.
+- `daemon-node.ts` is intentionally not a package export. `node.ts` resolves it by file URL and
+  passes that filesystem path to `daemonLayer`; the package `knip.entry` list preserves this live
+  file-URL-only entrypoint.
+- `effect.ts` is the low-level Effect export used by the CLI. There is no `internals.ts` entrypoint.
 
 ## Testing
 
-### Test file table
-
-| File                                     | Type        | What it tests                                                                                                                |
-| ---------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `src/Platform.unit.test.ts`              | Unit        | `detectPlatform`, all three asset-name mapping functions                                                                     |
-| `src/BinaryResolver.unit.test.ts`        | Unit        | Native release descriptors and provider-scoped `cachePath`                                                                   |
-| `src/BinaryResolver.integration.test.ts` | Integration | Concurrent atomic cache publication, legacy-cache reuse, failed replacement preservation, and stale staging cleanup          |
-| `src/services/services.unit.test.ts`     | Unit        | `makePostgresService`, `makePostgresServiceDocker`, `makePostgrestService`, `makeAuthServiceNative`, `makeAuthServiceDocker` |
-| `src/ApiProxy.unit.test.ts`              | Unit        | `transformAuthorization` key translation logic, CORS headers, route routing                                                  |
-| `src/StackBuilder.unit.test.ts`          | Unit        | `StackBuilder.build()` with prepared artifacts and mocked platform services                                                  |
-| `src/prefetch.unit.test.ts`              | Unit        | `StackPreparation` / `prefetch` cache hits, Docker fallback order, and pull behavior                                         |
-| `src/Stack.unit.test.ts`                 | Integration | Public `Stack` facade over `StackLifecycleCoordinator`, including pre-start `Downloading` state publication                  |
-| `src/createStack.unit.test.ts`           | Unit        | Type shape assertions + missing `stackConfig` error                                                                          |
-| `tests/createStack.e2e.test.ts`          | E2e         | Full stack lifecycle: health checks, auth sign up/in/out, PostgREST CRUD                                                     |
-| `tests/parallelStacks.e2e.test.ts`       | E2e         | Concurrent stacks: port uniqueness, health check validation                                                                  |
-
-### Mock patterns
-
-The test helper in `tests/helpers/mocks.ts` follows the same factory pattern as `@supabase/process-compose`:
-
-```ts
-function mockBinaryResolver(
-  opts: {
-    binaries?: Record<string, string>;
-    failServices?: string[];
-  } = {},
-) {
-  const resolved: Array<{ service: string; version: string }> = [];
-  // ...
-  return {
-    layer: Layer.succeed(BinaryResolver, {
-      resolve: (spec) => {
-        /* ... */
-      },
-    }),
-    resolved, // observable state — assert after the effect runs
-  };
-}
-```
-
-No `vi.fn()` spies. The mock accumulates calls in a plain array; tests assert on `resolver.resolved` after the effect completes. This avoids the overhead of mock expectation setup and teardown, and makes the test read like a data transformation check rather than a spy assertion.
-
-**Integration test example — `StackBuilder` with mocked binaries:**
-
-```ts
-it.effect("uses docker fallback when auth binary not found", () => {
-  const prepared = {
-    resolutions: {
-      postgres: { type: "binary", path: "/tmp/postgres" },
-      postgrest: { type: "binary", path: "/tmp/postgrest" },
-      auth: { type: "docker", image: "public.ecr.aws/supabase/gotrue:v2.188.0-rc.15" },
-    },
-  };
-
-  return Effect.gen(function* () {
-    const builder = yield* StackBuilder;
-    const { graph } = yield* builder.build(baseConfig, prepared);
-
-    const authDef = graph.startOrder.find((s) => s.name === "auth");
-    expect(authDef?.command).toBe("docker");
-  }).pipe(Effect.provide(StackBuilder.layer));
-});
-```
-
-**Integration test example — public `Stack` key naming:**
-
-```ts
-it.effect("StackInfo uses publishableKey and secretKey", () => {
-  const { layer } = setupLayer(defaultConfig);
-
-  return Effect.gen(function* () {
-    const stack = yield* Stack;
-    const info = yield* stack.getInfo();
-
-    expect(info.publishableKey).toBe(defaultPublishableKey);
-    expect(info.secretKey).toBe(defaultSecretKey);
-    expect(info.anonJwt).toMatch(/^ey/); // base64url JWT
-    expect(info.serviceRoleJwt).toMatch(/^ey/);
-  }).pipe(Effect.provide(layer));
-});
-```
-
-`Stack` integration tests wire the coordinator and preparation layers together via `setupLayer()`.
-The exact helper in the repo also provides metadata persistence and the shared child-process
-spawner; the key idea is that tests compose `Stack.layer(config)` on top of a real
-`StackLifecycleCoordinator.layer(config)`.
-
-```ts
-function setupLayer(config: ResolvedStackConfig = defaultConfig) {
-  const resolver = mockBinaryResolver();
-  const spawner = mockChildProcessSpawner(); // from @supabase/process-compose mocks
-  const portLease: PortLease = {
-    ports: config.ports,
-    reserve: () => Effect.void,
-    release: () => Effect.void,
-    releaseAll: Effect.void,
-  };
-
-  const preparationLayer = StackPreparation.layer.pipe(
-    Layer.provide(resolver.layer),
-    Layer.provide(spawner.layer),
-  );
-  const coordinatorLayer = StackLifecycleCoordinator.layer(config, portLease).pipe(
-    Layer.provide(StackBuilder.layer),
-    Layer.provide(preparationLayer),
-    Layer.provide(StackMetadataPersistence.noop),
-  );
-  const layer = Stack.layer(config).pipe(Layer.provide(coordinatorLayer));
-
-  return { layer, resolver, spawner };
-}
-```
-
-Production setup passes the real reserved `PortLease`; tests use the no-op lease above because
-their mocked processes do not bind the configured ports.
+- Unit tests cover configuration resolution, ports, versions, artifact definitions, service
+  factories, topology, projection, cleanup metadata, and protocol schemas.
+- Integration tests exercise binary publication, lifecycle coordination, daemon HTTP/SSE, remote
+  stack behavior, state persistence, and Unix socket streaming with stateful Effect Adapters.
+- Targeted e2e tests own the expensive process/container Seam for full stack startup, parallel
+  stacks, daemon lifecycle, and cleanup behavior.
 
-The `mockChildProcessSpawner` is reused from `@supabase/process-compose`'s test helpers — it
-stubs process spawning without forking real OS processes, making `Stack` / coordinator tests fast
-and deterministic.
+The authoritative current service versions are `DEFAULT_VERSIONS` in `src/versions.ts`; package
+documentation should link to that source rather than copy its values.
diff --git a/packages/stack/docs/detach-mode.md b/packages/stack/docs/detach-mode.md
index 5ac622f0b6..812c8e861a 100644
--- a/packages/stack/docs/detach-mode.md
+++ b/packages/stack/docs/detach-mode.md
@@ -1,508 +1,220 @@
-# Detach Mode
-
-## Context
-
-The local stack currently runs in the foreground, blocking the terminal. Users (both humans and AI agents) need a way to start the stack in the background and manage it via CLI commands. This design combines insights from process-compose (Go) and Prisma CLI (Node.js) detach implementations, adapted for our Effect-based Bun monorepo.
+# Detached stack mode
+
+Detached mode runs the same local `Stack` Implementation in a background process and exposes its
+Effect Interface over HTTP and server-sent events on a Unix-domain socket. Foreground and detached
+callers share configuration resolution, preparation, topology, lifecycle, readiness, state
+projection, and cleanup behavior.
+
+## Process model
+
+```mermaid
+sequenceDiagram
+    participant CLI
+    participant Child as "Daemon process"
+    participant HTTP as "DaemonServer on Unix socket"
+    participant Stack as "Local Stack"
+
+    CLI->>Child: detached fork with IPC
+    CLI->>Child: DaemonStartMessage(config, socketPath)
+    Child->>Stack: resolve config and build foreground daemon layer
+    Child->>HTTP: bind generation-scoped Unix socket
+    Child->>Child: atomically claim state.json
+    Child-->>CLI: DaemonStartedMessage(state)
+    CLI->>HTTP: POST /start through RemoteStack
+    HTTP->>Stack: Stack.start()
+    CLI-->>CLI: parent command exits; daemon remains
+```
 
----
+`daemonLayer()` performs the parent side:
 
-## Design Decisions
+1. resolves stack identity and durable/runtime roots;
+2. rejects an already-live state claim and removes stale live state;
+3. creates a generation-specific socket path;
+4. forks the runtime-specific daemon entrypoint with an IPC channel;
+5. sends a schema-defined start message and waits up to 30 seconds for acknowledgement;
+6. unrefs the child only after the daemon has bound its server and atomically claimed live state;
+7. returns a `RemoteStack` layer connected to the reported socket.
 
-- **Approach**: Fork daemon process with Unix socket management API (Prisma-style fork + process-compose-style HTTP API)
-- **Stack identity**: Project-scoped stacks keyed by the discovered project root, with implicit stack name `default` and explicit selection via `--stack`
-- **Log access**: On-demand streaming via SSE from daemon process (LogBuffer already exists in process-compose)
-- **Current commands**: `stack start --detach`, `stack stop`, `stack status`, `stack list`, `stack update`, plus top-level aliases for `start`, `stop`, and `status`, and the top-level `logs` command
-- **Future commands**: `restart`, `attach` (reconnect interactive TUI), per-service control
-- **Package boundaries**: Daemon and stack state live in `@supabase/stack`, CLI commands in `supabase`, `@supabase/process-compose` untouched
-- **Cross-platform**: Works on macOS, Linux, and Windows 10+ (Unix sockets supported since Build 17063)
+Until acknowledgement, the parent owns the child and terminates it if setup fails or is
+interrupted. This avoids leaving an unregistered daemon behind.
 
----
+The daemon side in `daemon.ts`:
 
-## Architecture
+1. receives the start message over IPC;
+2. resolves the final configuration and port lease;
+3. releases unused port reservations;
+4. builds `foregroundDaemonLayer`, including `Stack`, `ApiProxy`, and `StateManager`;
+5. binds `DaemonServer` to the Unix socket;
+6. atomically creates `state.json` and acknowledges the parent;
+7. waits for `/stop`, `SIGINT`, or `SIGTERM`;
+8. disposes the management runtime and stack runtime.
 
-```
-User runs: supabase start --detach
-                │
-                ▼
-        ┌──────────────┐
-        │   CLI (cli/)  │  Forks daemon, waits for IPC "started" msg,
-        │  start -d     │  writes state file, prints connection info, exits
-        └───────┬───────┘
-                │ fork (detached, stdio: ignore)
-                ▼
-        ┌──────────────────┐
-        │  Daemon Process   │  Lives in @supabase/stack
-        │  (daemon.ts)      │
-        │                   │
-        │  ┌──────────────────────────────┐  │
-        │  │ StackLifecycleCoordinator    │  │  Prepares assets, publishes
-        │  │ + StackBuilder + ApiProxy    │  │  Downloading states, starts runtime
-        │  └─────────────┬────────────────┘  │
-        │         │          │
-        │  ┌──────▼──────┐  │
-        │  │ Mgmt HTTP    │  │  Unix socket: /tmp/supabase/s-<hash>/daemon.sock
-        │  │ Server       │  │  Endpoints: /health, /status, /stop, /logs
-        │  └─────────────┘  │
-        └──────────────────┘
-```
+The daemon is acknowledged before `POST /start` starts service processes. Startup and readiness
+errors therefore travel through the same `Stack` transport as later lifecycle calls.
 
-### State Directory
+## Stack identity and paths
 
-```
-<project-root>/
-  ├── supabase/
-  │   └── config.json
-  └── .supabase/
-      ├── project.json
-      ├── local-versions.json
-      └── stacks/
-          └── default/
-              ├── stack.json
-              ├── state.json
-              └── data/
-```
+A stack is identified by canonical project directory plus stack name (`default` when omitted).
+The package supports two durable layouts:
 
-The durable managed-stack record lives under
-`<project-root>/.supabase/stacks/<stack-name>/`.
+- Library default: `<cacheRoot>/projects/<project-hash>/stacks/<name>/`.
+- Explicit `projectStateRoot`: `<projectStateRoot>/stacks/<name>/`.
 
-The live daemon socket is runtime state and lives under the OS temp directory, not under `~/.supabase`:
+The current CLI passes its discovered project home (`<project-root>/.supabase`) as
+`projectStateRoot`, so CLI-managed stacks use:
 
 ```text
-/tmp/supabase/s-<hash>/daemon.sock
-```
-
-Project-scoped service version state such as `.supabase/project.json` and
-`.supabase/local-versions.json` is documented separately in
-[`service-versioning.md`](./service-versioning.md).
-
-### State File Formats
-
-`stack.json` is the durable per-stack metadata record:
-
-```json
-{
-  "schemaVersion": 1,
-  "updatedAt": "2026-03-25T10:00:00Z",
-  "ports": {
-    "apiPort": 54321,
-    "dbPort": 54322
-  },
-  "services": {
-    "postgres": "17.6.1.084",
-    "postgrest": "14.4",
-    "auth": "2.188.1",
-    "realtime": "2.34.47",
-    "storage": "1.43.3",
-    "imgproxy": "v3.8.0",
-    "mailpit": "v1.30.2",
-    "pgmeta": "0.95.2",
-    "studio": "2026.02.16-sha-26c615c",
-    "analytics": "1.33.3",
-    "vector": "0.28.1-alpine",
-    "pooler": "2.7.4"
-  }
-}
-```
-
-`state.json` is the live runtime record:
-
-```json
-{
-  "pid": 12345,
-  "name": "default",
-  "projectDir": "<project-root>",
-  "apiPort": 54321,
-  "dbPort": 54322,
-  "socketPath": "/tmp/supabase/s-123456789abc/daemon.sock",
-  "startedAt": "2026-03-03T10:00:00Z",
-  "url": "http://127.0.0.1:54321",
-  "dbUrl": "postgresql://postgres:postgres@127.0.0.1:54322/postgres",
-  "publishableKey": "eyJ...",
-  "secretKey": "eyJ...",
-  "anonJwt": "eyJ...",
-  "serviceRoleJwt": "eyJ...",
-  "services": {
-    "postgres": "17.6.1.084",
-    "postgrest": "14.4",
-    "auth": "2.188.1"
-  }
-}
+<project-root>/.supabase/
+  project.json
+  local-versions.json
+  stacks/
+    <name>/
+      stack.json
+      state.json
+      data/
 ```
 
-The `publishableKey`, `secretKey`, `anonJwt`, and `serviceRoleJwt` fields are needed so CLI
-commands like `status` can display connection info without querying the daemon. The
-exact Docker cleanup targets are now persisted in stack metadata after runtime preparation. That
-keeps `/status` focused on user-facing connection info while still allowing crash recovery and
-orphan cleanup when the daemon is gone.
-
----
-
-## Package Changes
-
-### `@supabase/process-compose` — No changes
-
-### `@supabase/stack` — New additions
-
-| File                               | Purpose                                                                                                       |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `src/daemon.ts`                    | Shared daemon logic: `runDaemon(platformFactory)`. IPC handling, lifecycle, signal management                 |
-| `src/daemon-bun.ts`                | Bun daemon entry point. Imports Bun platform factory, calls `runDaemon()`. Forked by CLI (Bun)                |
-| `src/daemon-node.ts`               | Node daemon entry point. Imports Node platform factory, calls `runDaemon()`. For Node consumers               |
-| `src/DaemonServer.ts`              | Management HTTP server (Effect-based, Unix socket). Exposes the in-process `Stack` over HTTP                  |
-| `src/RemoteStack.ts`               | Implements the `Stack` Effect Service interface over HTTP/SSE, connecting to a daemon's Unix socket           |
-| `src/StackPreparation.ts`          | Resolves native-vs-Docker assets, downloads binaries, and pulls Docker images                                 |
-| `src/StackLifecycleCoordinator.ts` | Owns preparation, unified state publication, runtime creation, and cleanup metadata                           |
-| `src/StackMetadataPersistence.ts`  | Persists exact cleanup targets for daemon crash recovery                                                      |
-| `src/StateManager.ts`              | Read/write/scan `stack.json` and `state.json` under `<project-root>/.supabase/stacks/`. Stale state detection |
-| `src/internals.ts`                 | Export new modules for CLI consumption                                                                        |
+Direct `@supabase/stack` daemon callers that do not supply `projectStateRoot` use the hashed
+cache-root layout instead. Documentation must not conflate these two valid modes.
 
-### Transparent Effect Service interface
+Runtime sockets use a short temporary path independent of either durable layout:
 
-The CLI uses Effect V4 and consumes `Stack` as an Effect Service (via `internals.ts`). Rather than
-using the Promise-based `createStack()` handle, the CLI and `RemoteStack` both operate at the
-Effect level.
-
-There are two layers of API:
-
-- **`Stack`** (Effect Service) — used by CLI and other Effect consumers.
-  Returns `Effect`s and `Stream`s. This is the internal API.
-- **`createStack()` handle** (Promise-based) — used by non-Effect library consumers.
-  Returns `Promise`s and `AsyncIterable`s. This public API is unchanged.
-
-`RemoteStack` implements the same `Stack` Effect Service interface, but backed
-by HTTP/SSE over a Unix socket instead of in-process orchestration. The CLI switches
-between them via **Layers** — no branching in CLI code:
-
-```
-// Foreground: provide the in-process layer
-const layer = Stack.layer(config).pipe(Layer.provide(...));
-
-// Detached: provide the remote layer
-const layer = RemoteStack.layer(socketPath);
-
-// CLI code is identical — just consumes the Stack tag
-Effect.gen(function* () {
-  const stack = yield* Stack;
-  yield* stack.start();
-  yield* stack.subscribeAllLogs().pipe(Stream.runForEach(renderLog));
-});
-```
-
-`stack.start()` now means `prepare assets -> publish Downloading when needed -> start services ->
-wait healthy`, so detached mode exposes the same pre-runtime status behavior as foreground mode.
-`RemoteStack` translates each Effect/Stream method to the corresponding HTTP call:
-
-| Stack method               | RemoteStack transport                                          |
-| -------------------------- | -------------------------------------------------------------- |
-| `start()`                  | `POST /start` → `Effect`                                       |
-| `stop()`                   | `POST /stop` → `Effect`                                        |
-| `getInfo()`                | `GET /status` → `Effect` (extract connection info)             |
-| `getAllStates()`           | `GET /status` → `Effect` (extract service states)              |
-| `getState(name)`           | `GET /status` → `Effect` (filter by name)                      |
-| `allStateChanges()`        | `GET /status/stream` (SSE → `Stream`, including `Downloading`) |
-| `stateChanges(name)`       | `GET /status/stream` (SSE → `Stream`, filter by name)          |
-| `waitReady(name)`          | `GET /services/:name/ready` → `Effect`                         |
-| `waitAllReady()`           | `GET /ready` → `Effect`                                        |
-| `subscribeAllLogs()`       | `GET /logs` (SSE → `Stream`)                                   |
-| `subscribeLogs(name)`      | `GET /logs/:name` (SSE → `Stream`)                             |
-| `logHistory(name, limit?)` | `GET /logs/:name/history?limit=N` → `Effect`                   |
-| `startService(name)`       | `POST /services/:name/start` → `Effect`                        |
-| `stopService(name)`        | `POST /services/:name/stop` → `Effect`                         |
-| `restartService(name)`     | `POST /services/:name/restart` → `Effect`                      |
-
-Note: `start()`, per-service control, and `logHistory` are included for completeness.
-In the MVP, the CLI only uses a subset (status, logs, stop). The full mapping ensures
-`RemoteStack` is a drop-in replacement for `Stack` in any Effect consumer.
-
-Benefits of using Effect throughout:
-
-- **`Stream`** instead of `AsyncIterable` — composable with `Stream.runForEach`, `Stream.take`, timeouts, etc.
-- **`Effect`** instead of `Promise` — typed errors, cancellation, retries
-- **Layer system** handles the wiring — the CLI never checks "am I foreground or detached?"
-- SSE response body maps naturally to `Stream` (via `Stream.fromReadableStream` or `Stream.async`)
-
-**Daemon entry points** follow the same split as `bun.ts`/`node.ts`:
-
-- `daemon.ts` exports `runDaemon(platformFactory)` — shared logic, not executable
-- `daemon-bun.ts` — Bun entry point, forked by CLI
-- `daemon-node.ts` — Node entry point, for Node consumers
-
-**Daemon lifecycle (`runDaemon`):**
-
-1. Receive serializable `StackConfig` via IPC message from parent
-2. Build the foreground daemon layer (`StackPreparation` + `StackBuilder` + `StackLifecycleCoordinator` + `ApiProxy`)
-3. Call `stack.start()` which prepares assets first, then starts services
-4. Start management HTTP server on Unix socket
-5. Atomically claim `state.json`, then send IPC `{ type: "started", info: { url, dbUrl, ... } }` to parent
-6. Parent disconnects — daemon keeps running
-7. On SIGTERM/SIGINT or POST `/stop`: call `stack.dispose()` and exit. The stopping client removes live state only after confirming process exit; later discovery removes crash-stale state.
-
-**IPC startup handshake:**
-
-IPC (Inter-Process Communication) is how the CLI and daemon exchange data during startup.
-`forkDaemon` uses `child_process.fork()` so Node/Bun establish a built-in IPC channel
-between parent and child. In Bun JIT mode, `fork()` starts the daemon entrypoint by
-running Bun with the daemon script path. In a compiled Bun binary, the child process
-re-enters the compiled CLI binary instead; the parent marks the child with
-`SUPABASE_STACK_RUN_DAEMON=1`, and the CLI entrypoint routes that process to the daemon
-runner. See [ADR 0012](../../../docs/adr/0012-compiled-bun-runtime-dispatch.md) for the
-runtime-dispatch rationale.
-
-Parent and child send JSON messages via `process.send()` / `process.on("message")`.
-
-This channel is only used for the initial startup handshake. The parent validates the response and
-applies a bounded startup timeout. Once the daemon confirms it's ready (or reports an error), the
-CLI disconnects the channel. All subsequent
-communication (stop, status, logs) happens over the Unix socket HTTP API instead.
-
-```
-CLI (parent)                          Daemon (child)
-     │                                      │
-     │── fork(daemon-bun.ts, {              │
-     │     env: {                           │
-     │       SUPABASE_STACK_RUN_DAEMON: "1" │
-     │     },                               │
-     │     detached: true,                  │
-     │     stdio: "ignore"                  │
-     │   }) ───────────────────────────────▶│
-     │                                      │── build foreground daemon layer
-     │                                      │── stack.start()
-     │                                      │── start mgmt HTTP server
-     │                                      │
-     │◀── { type: "started", info: ... } ───│  (IPC message: "I'm ready")
-     │                                      │
-     │── child.disconnect()  ──────────────▶│  (close IPC channel)
-     │── child.unref()  ───────────────────▶│  (allow parent to exit)
-     │                                      │
-     │  CLI prints connection info & exits  │  Daemon keeps running independently
-     │                                      │  Managed via Unix socket from now on
+```text
+/tmp/supabase/s-<stack-root-hash>/daemon-<generation>.sock
 ```
 
-If the daemon fails to start, it sends `{ type: "error", error: ... }` instead,
-and the CLI displays the error and exits with a non-zero code.
-
-**Management HTTP endpoints:**
-
-| Endpoint                 | Method | Description                                                                         |
-| ------------------------ | ------ | ----------------------------------------------------------------------------------- |
-| `/health`                | GET    | Liveness check (200 OK)                                                             |
-| `/ready`                 | GET    | Wait for all activated services using foreground lifecycle semantics                |
-| `/status`                | GET    | All service states + connection info (JSON)                                         |
-| `/status/stream`         | GET    | SSE stream of all service state changes, including `Downloading` during preparation |
-| `/stop`                  | POST   | Graceful shutdown → dispose + exit                                                  |
-| `/services/:name/ready`  | GET    | Wait for one activated service                                                      |
-| `/logs`                  | GET    | SSE stream of all logs                                                              |
-| `/logs/:service`         | GET    | SSE stream for one service                                                          |
-| `/logs/:service/history` | GET    | Recent log entries for one service (JSON, `?limit=N`)                               |
-
-Management errors include a stable discriminator. `RemoteStack` maps service-not-found,
-service-readiness, and stack-build responses back to the same typed failures exposed by a
-foreground stack.
-
-### `supabase` — New/modified commands
-
-**Modified: `src/commands/start/`**
+On Windows, the system temporary directory replaces `/tmp`. The generation suffix prevents an old
+daemon from unlinking a replacement daemon's socket during delayed shutdown.
 
-- New flags: `--detach`, `--stack`
-- When `--detach`: fork daemon with unresolved port preferences, wait for IPC "started", print connection info, exit. The daemon allocates ports and atomically claims the live state file before acknowledging startup.
-- When foreground (default): unchanged behavior
+## Durable metadata and live state
 
-**New: `src/commands/stop/`**
+`stack.json` is durable metadata. It records:
 
-- Flags: `--stack`
-- Reads state file, sends POST `/stop` to daemon socket, waits for process exit
-- `--no-backup` deletes only the selected stack directory under
-  `<project-root>/.supabase/stacks/<stack-name>/`
+- schema version and update time;
+- allocated ports;
+- the pinned complete service version manifest;
+- launch mode and excluded services;
+- exact cleanup targets once preparation/build has produced them;
+- the last version-update notification fingerprint, when present.
 
-**New: `src/commands/status/`**
+`state.json` is the live-daemon claim. It records:
 
-- Resolves the current project from `cwd`, then resolves the selected stack within that project
-- Shows a detailed running view when `state.json` exists
-- Shows a detailed stopped view when only `stack.json` exists
+- PID, project directory, stack name, and start time;
+- API/database ports and the full allocated port set;
+- generation socket path;
+- user-facing URLs, keys, JWTs, and service endpoints;
+- versions for services enabled in this run.
 
-**New: `src/commands/list/`**
+`StateManager.claim()` uses an exclusive hard-link operation so concurrent daemons cannot both own
+the same name. A stale PID causes live state and its runtime directory to be removed; durable
+metadata and service data remain.
 
-- Lists all known stacks for the current project from `.supabase/stacks/*/stack.json`
-- Overlays live runtime state when a daemon is running
+## The transport Adapter
 
-**New: `src/commands/update/`**
+`DaemonServer` exposes the local `Stack` Interface on the Unix socket. Current routes include:
 
-- Refreshes linked remote service versions when the project is linked
-- Rewrites the pinned baseline in `.supabase/stacks/<stack-name>/stack.json`
-- Does not start or restart the stack automatically
+- `/health`, `/status`, and `/status/stream`;
+- `/start`, `/stop`, and `/ready`;
+- per-service start, stop, restart, and readiness;
+- merged and per-service live logs plus buffered history;
+- functions and Edge Runtime reload.
 
-**New: `src/commands/logs/`**
+State and log streams use SSE. Ordinary responses and typed failures use validated JSON shapes.
+`RemoteStack` decodes that transport back into the same Effect `Stack` Interface used in
+foreground mode, including `ServiceNotFoundError`, `ServiceReadyError`, and `StackBuildError`.
 
-- Flags: `--stack`, `--service <name>`
-- Flags: `--service <name>` (optional, filter to one service)
-- Connects to daemon SSE endpoint, streams to stdout
+The management socket is not the public local API endpoint. `ApiProxy` still owns the configured
+HTTP API port inside the daemon process.
 
-### Stack resolution
+## Lifecycle and cleanup
 
-When a command like `supabase stop`, `supabase status`, or `supabase logs` is run,
-the CLI first resolves the canonical local project from `cwd`, then resolves the selected stack
-within that project. This works from any nested directory inside the project.
+Detached mode relies on changes in `@supabase/process-compose`; it is not isolated to the stack
+package. In particular:
 
-**Algorithm:**
+- desired state distinguishes inactive lazy definitions from explicitly stopped definitions;
+- stable state streams survive restart generations;
+- `updateServiceDefinition()` supports Edge Runtime reload;
+- supervisor runtimes watch owner loss and clean child trees/external resources;
+- definition cleanup, exact stack cleanup targets, and orphan cleanup form an idempotent defense in
+  depth.
 
-1. Discover the nearest local Supabase project root from `cwd`
-2. Prefer a config-discovered root from `supabase/config.json` or `supabase/config.toml`
-3. Otherwise prefer the nearest ancestor containing `.supabase/project.json`
-4. Otherwise treat `cwd` as the project root
-5. Select the named stack from `.supabase/stacks/<stack-name>/`
-6. If `--stack` is omitted, use `default`
+On normal `/stop`, the daemon gracefully stops the stack, signals HTTP shutdown after the response
+has had time to flush, disposes both managed runtimes, and removes live state/runtime paths.
 
-**Examples:**
+If the daemon has died, CLI stop/status detects a stale PID. Stop can use cleanup targets persisted
+in `stack.json` to force-remove known Docker containers before removing the stale state. This
+crash-recovery metadata is deliberately separate from user-facing `/status` connection data.
 
-- cwd = `<project-root>/src/components/`
-- discovered project root = `<project-root>`
-- resolved stack = `.supabase/stacks/default`
+## Package entrypoints
 
-**Edge cases:**
+| File                  | Reachability and role                                                                                         |
+| --------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `src/daemon.ts`       | Shared daemon protocol and lifecycle; receives runtime-specific HTTP-server factories.                        |
+| `src/daemon-bun.ts`   | Bun daemon Adapter. Exported as `@supabase/stack/daemon-bun` for compiled CLI dispatch.                       |
+| `src/daemon-node.ts`  | Node daemon Adapter. Intentionally file-URL-only: `node.ts` resolves its path and passes it to `daemonLayer`. |
+| `src/DaemonServer.ts` | Unix-socket HTTP/SSE Adapter over `Stack`.                                                                    |
+| `src/RemoteStack.ts`  | Remote Effect `Stack` Adapter over that transport.                                                            |
+| `src/layers.ts`       | Foreground, foreground-daemon, forked-daemon, and connect layer composition.                                  |
+| `src/StateManager.ts` | Durable metadata, live-state claims, scanning, stale-state removal, and deletion.                             |
+| `src/effect.ts`       | Effect-facing exports consumed by the CLI and advanced callers.                                               |
 
-- No config or `.supabase/project.json` discovered from `cwd` → treat the current working
-  directory as the project root
-- No persisted stack directory for the selected stack → no known local stack for this project
-- Explicit `--stack` always takes precedence over the implicit `default`
+There is no `internals.ts`. `daemon-node.ts` is not a package export because Node root consumers
+reach it by the file URL returned from `node.ts`; it is listed under `knip.entry` in `package.json`
+so static unused-code analysis preserves that live entrypoint.
 
----
+## Compiled executable re-entry
 
-## Error Handling
+In development, `child_process.fork(entrypoint)` can execute the selected `.ts` daemon file through
+Bun or Node. In a Bun single-file executable, `process.execPath` is the compiled CLI itself, and a
+script-path argument does not replace its baked entrypoint. The fork therefore sets:
 
-| Scenario                                | Behavior                                                                                                                                                                                                               |
-| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Port already in use                     | Daemon sends IPC error before parent exits; CLI shows error                                                                                                                                                            |
-| Name collision (already running)        | State file exists + daemon alive → error with connection info                                                                                                                                                          |
-| Daemon crashes                          | State becomes stale. `status` detects dead PID, shows "crashed". `stop` cleans up state + Docker containers                                                                                                            |
-| Orphaned Docker containers              | `stack.dispose()` calls `dockerForceRemove()`. On crash, `stop` reads persisted cleanup metadata, then force-removes the exact known containers                                                                        |
-| Ctrl+C during `start --detach`          | If daemon hasn't started: kill child. If started: daemon keeps running                                                                                                                                                 |
-| Foreground start while detached running | `supabase start` (foreground) checks StateManager first. If a daemon is running for the same project, error with "Stack already running in detached mode. Use `supabase stop` first or `supabase logs` to see output." |
-| Detached start while foreground running | The daemon owns port allocation and reports a conflict before acknowledging startup.                                                                                                                                   |
-
----
-
-## Testing Strategy
-
-1. **Unit tests** on `StateManager` — pure file operations, mock filesystem
-2. **Integration tests** on `RemoteStack`/`DaemonServer` — test HTTP API with real Unix socket, verify Effect/Stream round-trip
-3. **Integration tests** on CLI handlers — mock `Stack` via `Layer.succeed`, assert on output/state (same pattern as existing CLI tests)
-4. **E2e tests** — spawn real `supabase start --detach`, verify startup, `supabase status` shows it, `supabase stack list` finds it, `supabase stop` stops it
-
----
-
-## Verification
-
-1. `supabase start --detach` — daemon starts, connection info printed, terminal returns
-2. `supabase status` — shows running stack with name, ports, uptime
-3. `supabase logs` — streams real-time logs from daemon
-4. `supabase stop` — graceful shutdown, Docker containers removed, state cleaned up
-5. `supabase start --detach && supabase start --detach` — second invocation shows "already running"
-6. Kill daemon with `kill <pid>`, then `supabase status` — shows "crashed", `supabase stop` cleans up
-
----
-
-## Future Improvements
-
-### Reattach (`supabase attach [--stack <name>]`)
-
-Reconnects an interactive TUI to a running detached daemon. The HTTP daemon design
-makes this straightforward — the attach command is just an HTTP client rendering a TUI,
-connecting to the same endpoints that `supabase status` and `supabase logs` use.
-
-```
-supabase attach [name]
-     │
-     ▼
-  1. Read state file → find daemon socket
-  2. GET /status → render current service states
-  3. GET /logs → open SSE stream → render logs in real-time
-  4. Same interactive TUI as foreground mode, but fed by HTTP
-     instead of in-process Effect streams
-     │
-     ▼
-  On Ctrl+C → just disconnect (daemon keeps running)
+```text
+SUPABASE_STACK_RUN_DAEMON=1
 ```
 
-Key difference from foreground mode:
-
-- **Foreground**: TUI consumes in-process `Stack` Effect Service (Effect `Stream`s)
-- **Attached**: TUI consumes `RemoteStack` Effect Service (same `Stream` interface, backed by SSE over Unix socket)
-
-Ctrl+C when attached means **detach** (daemon keeps running), not stop. The user ran
-detached intentionally — if they want to stop, they use `supabase stop`. This matches
-`tmux`/`screen` behavior.
-
-No additional daemon-side work is required — the management API already exposes
-everything the TUI needs.
-
-### Restart (`supabase restart [name]`)
-
-Restart all services in a running detached stack without tearing down the daemon.
-Requires a new `POST /restart` endpoint on the management API that calls
-`stack.stop()` followed by `stack.start()`.
-
-### Per-service control
-
-Expose per-service start/stop/restart for detached stacks:
-
-- `supabase service start <service> [--stack <name>]`
-- `supabase service stop <service> [--stack <name>]`
-- `supabase service restart <service> [--stack <name>]`
-
-Requires new management API endpoints: `POST /services/:name/start`, `/stop`, `/restart`.
-The underlying `stack.startService()`, `stack.stopService()`, `stack.restartService()`
-methods already exist.
-
-### File-based log persistence
-
-Optionally write logs to disk in addition to in-memory buffering, for post-crash analysis.
-Could be enabled via a `--persist-logs` flag on `supabase start --detach`. Logs would go to
-`<project-root>/.supabase/stacks/<stack-name>/logs/`.
-
----
-
-## Research: Prior Art
-
-### Process-Compose (Go)
-
-Source: `.repos/process-compose/`
-
-**Detach mechanism**: Self re-exec with `Setsid: true` (`src/cmd/project_runner_unix.go:13-44`). Strips `--detached` flag, adds `-t=false`, redirects stdio to `/dev/null`.
-
-**Management**: Full HTTP API (28 REST endpoints) over Unix domain sockets (`/tmp/process-compose-<PID>.sock`). WebSocket log streaming. CLI acts as HTTP client (`src/client/client.go`).
+The compiled CLI entrypoint sees that marker and dynamically imports
+`@supabase/stack/daemon-bun`, which invokes `runDaemon()` in the re-entered process. Supabase daemon
+selection stays in the CLI/stack layer; generic process supervision uses its own protocol.
 
-**Key commands**: `attach` (reconnect TUI), `down` (stop), `process start/stop/restart`, `logs`, `list`.
+`@supabase/process-compose` uses three variables for its separate supervisor re-entry protocol:
 
-**Key patterns**:
+- `PROCESS_COMPOSE_SUPERVISOR_SELF_DISPATCH` enables compiled self-dispatch for supervisor spawns;
+- `PROCESS_COMPOSE_RUN_SUPERVISOR` selects the supervisor path in the re-entered executable;
+- `PROCESS_COMPOSE_SUPERVISOR_CONFIG` carries its encoded configuration.
 
-- Self-re-exec with session detach (not fork)
-- PID-based socket naming for unique identification
-- Full HTTP API enables rich remote management
-- No PID file — uses socket existence for discovery
+The exact protocol and cleanup behavior are documented in
+[process-compose architecture](../../process-compose/docs/architecture.md#compiled-bun-self-dispatch).
 
-### Prisma CLI (Node.js)
+These explicit dispatch contracts were introduced after:
 
-Source: `@prisma/cli-dev` npm package (v0.15.0), `@prisma/dev/internal/daemon`
+- [CLI-1452](https://linear.app/supabase/issue/CLI-1452/compiled-bun-compile-next-binary-cant-run-supabase-functions-dev), where compiled functions development depended on unsafe runtime paths/native binding discovery;
+- [CLI-1453](https://linear.app/supabase/issue/CLI-1453/compiled-bun-compile-next-binary-start-detach-daemon-fork-ignores), where detached startup re-entered the normal CLI instead of the daemon.
 
-**Detach mechanism**: `child_process.fork()` with `{detached: true, stdio: "ignore"}`. IPC for startup coordination (`"started"`/`"error"` messages), then `disconnect()`/`unref()`.
+Runtime sources or native dependencies needed by the single-file executable must therefore be
+statically reachable or explicitly embedded. Development-mode success alone does not verify this
+contract.
 
-**State management**: Filesystem-based `ServerState` (`@prisma/dev/internal/state`). Named instances with glob matching. `ServerState.scan()`, `isServerRunning()`, `killServer()`, `deleteServer()`.
+## CLI integration
 
-**Key commands**: `ls` (list), `start <glob>`, `stop <glob>`, `rm <glob>`.
+The CLI resolves the canonical project before selecting a stack, so management commands work from
+nested directories. Current detached workflows include:
 
-**Key patterns**:
+- `supabase start --detach`;
+- `supabase stop`;
+- `supabase status`;
+- `supabase stack list`;
+- `supabase stack update`;
+- `supabase logs`;
+- functions development reconnect/reload flows.
 
-- `fork()` + IPC for startup coordination, then disconnect/unref to release
-- Persistent state store for tracking instances across CLI invocations
-- Named instances with glob-based matching for multi-project support
-- No HTTP API — management through state files + process signals
+Version selection and durable metadata behavior are described in
+[service versioning](./service-versioning.md).
 
-### Comparison
+## Testing
 
-| Aspect          | process-compose    | Prisma                | Our approach               |
-| --------------- | ------------------ | --------------------- | -------------------------- |
-| Detach method   | Re-exec + Setsid   | fork + detached       | fork + detached            |
-| Management IPC  | HTTP + Unix socket | State files + signals | HTTP + Unix socket         |
-| Log streaming   | WebSocket          | None                  | SSE                        |
-| Named instances | Socket path        | `--stack` flag        | Project-scoped + `--stack` |
-| Windows support | No                 | Yes                   | Yes                        |
+- `StateManager` tests cover atomic claims, stale-state cleanup, metadata compatibility, and path
+  layouts.
+- `DaemonServer` and `RemoteStack` integration tests cover JSON/SSE translation and typed failures
+  on real Unix sockets.
+- Entry-point tests pin Bun/Node export selection and daemon paths.
+- Targeted CLI e2e tests cover detached start, status, logs, stop, and live compiled-binary behavior.
diff --git a/packages/stack/src/daemon-node.ts b/packages/stack/src/daemon-node.ts
index f85e6d7761..387b2dff11 100644
--- a/packages/stack/src/daemon-node.ts
+++ b/packages/stack/src/daemon-node.ts
@@ -4,6 +4,9 @@ import { createServer } from "node:http";
 import { Effect, Layer } from "effect";
 import { runDaemon } from "./daemon.ts";
 
+// Live child-process entrypoint for Node root consumers. `node.ts` resolves this module by file URL
+// and passes its filesystem path to daemonLayer, so it is deliberately not a package export. The
+// `knip.entry` declaration in package.json preserves this file-URL-only reachability.
 runDaemon(
   ({ apiPort, releaseApiPort }) =>
     Layer.mergeAll(
diff --git a/packages/stack/src/node.ts b/packages/stack/src/node.ts
index 712359833d..8feb036db6 100644
--- a/packages/stack/src/node.ts
+++ b/packages/stack/src/node.ts
@@ -128,7 +128,13 @@ export const platformFactory: PlatformFactory = ({ apiPort, releaseApiPort }) =>
     ),
   );
 
-/** Path to the Node daemon entry point for use with daemonLayer. */
+/**
+ * Path to the Node daemon entry point for use with daemonLayer.
+ *
+ * `daemon-node.ts` is intentionally reached by this file URL instead of a package export. Keep the
+ * matching `knip.entry` in package.json when changing this path; static import analysis cannot see
+ * the child-process entrypoint.
+ */
 export const daemonEntryPoint: string = fileURLToPath(new URL("./daemon-node.ts", import.meta.url));
 
 // ---------------------------------------------------------------------------

From b2943a01a4e28bbe3c82b44cd9d1ac1fcd16cd4d Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 14:55:08 +0200
Subject: [PATCH 02/44] fix(process-compose): make unhealthy lifecycle terminal

---
 .../start/ui/StartDashboardView.unit.test.ts  |  11 +-
 packages/process-compose/docs/architecture.md |  41 +++--
 packages/process-compose/src/HealthProbe.ts   |  16 +-
 .../src/HealthProbe.unit.test.ts              | 128 ++++++++++++++++
 packages/process-compose/src/Orchestrator.ts  | 142 +++++++++++-------
 .../src/Orchestrator.unit.test.ts             | 106 ++++++++++++-
 .../process-compose/src/RestartDecision.ts    |  49 ++++++
 .../src/RestartDecision.unit.test.ts          |  72 +++++++++
 packages/process-compose/src/ServiceDef.ts    |   2 +
 .../process-compose/src/ServiceTransition.ts  |  20 +++
 .../src/ServiceTransition.unit.test.ts        |  31 ++++
 .../src/DaemonServer.integration.test.ts      |  21 ++-
 .../stack/src/RemoteStack.integration.test.ts |  25 ++-
 .../stack/src/StackServiceState.unit.test.ts  |  27 ++++
 packages/stack/src/services/analytics.ts      |   5 +-
 packages/stack/src/services/auth.ts           |   4 +-
 packages/stack/src/services/edge-runtime.ts   |   5 +-
 packages/stack/src/services/health-budgets.ts |  94 ++++++++++++
 .../src/services/health-budgets.unit.test.ts  | 123 +++++++++++++++
 packages/stack/src/services/imgproxy.ts       |   5 +-
 packages/stack/src/services/mailpit.ts        |   5 +-
 packages/stack/src/services/pgmeta.ts         |   5 +-
 packages/stack/src/services/pooler.ts         |   5 +-
 packages/stack/src/services/postgres.ts       |   8 +-
 packages/stack/src/services/postgrest.ts      |   4 +-
 packages/stack/src/services/realtime.ts       |   5 +-
 packages/stack/src/services/storage.ts        |   5 +-
 packages/stack/src/services/studio.ts         |   5 +-
 packages/stack/src/services/vector.ts         |   5 +-
 .../tests/createStack-docker.e2e.test.ts      |  15 ++
 30 files changed, 865 insertions(+), 124 deletions(-)
 create mode 100644 packages/process-compose/src/RestartDecision.ts
 create mode 100644 packages/process-compose/src/RestartDecision.unit.test.ts
 create mode 100644 packages/stack/src/StackServiceState.unit.test.ts
 create mode 100644 packages/stack/src/services/health-budgets.ts
 create mode 100644 packages/stack/src/services/health-budgets.unit.test.ts

diff --git a/apps/cli/src/next/commands/start/ui/StartDashboardView.unit.test.ts b/apps/cli/src/next/commands/start/ui/StartDashboardView.unit.test.ts
index 57b1ad2fa7..331009b352 100644
--- a/apps/cli/src/next/commands/start/ui/StartDashboardView.unit.test.ts
+++ b/apps/cli/src/next/commands/start/ui/StartDashboardView.unit.test.ts
@@ -1,16 +1,17 @@
 import { describe, expect, test } from "vitest";
+import { StackServiceState, type StackServiceStatus } from "@supabase/stack/effect";
 import { ConnectionInfo } from "./ConnectionInfo.tsx";
 
-function state(name: string, status: string) {
-  return {
+function state(name: string, status: StackServiceStatus, error: string | null = null) {
+  return new StackServiceState({
     name,
     status,
     pid: null,
     exitCode: null,
     restartCount: 0,
     startedAt: null,
-    error: null,
-  } as any;
+    error,
+  });
 }
 
 function collectNodes(node: unknown): Array<unknown> {
@@ -60,7 +61,7 @@ describe("StartDashboardView", () => {
     if (!("StartDashboardView" in dashboardModule)) return;
 
     const element = dashboardModule.StartDashboardView({
-      states: [state("postgres", "Failed")],
+      states: [state("postgres", "Failed", "Health check failed and restart budget was exhausted")],
       info: {
         url: "http://127.0.0.1:54321",
         dbUrl: "postgresql://postgres:postgres@127.0.0.1:54322/postgres",
diff --git a/packages/process-compose/docs/architecture.md b/packages/process-compose/docs/architecture.md
index a7b97e0f5a..85e3f58841 100644
--- a/packages/process-compose/docs/architecture.md
+++ b/packages/process-compose/docs/architecture.md
@@ -40,7 +40,7 @@ construct its layer from a validated `ResolvedGraph`, a `ChildProcessSpawner` Ad
 
 - executable, arguments, environment, and working directory;
 - dependencies and a dependency wait timeout;
-- optional HTTP, TCP, or exec health check;
+- optional HTTP, TCP, or exec health check with separate startup and liveness failure thresholds;
 - shutdown signal and grace period;
 - restart policy and restart budget;
 - `started` and `healthy` lifecycle hooks;
@@ -98,6 +98,10 @@ service maintained, and `stopped` records an explicit stop. Desired state is ind
 intermediate observed states and is what prevents an explicit stop from being undone by restart
 policy.
 
+`pid` identifies only a currently live process. Process exit, supervisory termination, hook
+failure, restart, and forced shutdown clear it. A health-triggered termination does not fabricate
+an `exitCode`; the code remains `null` unless the process itself reports an exit.
+
 `ServiceState` extends `Data.Class`, so Effect's `Equal.equals` can compare values structurally. It
 does not make two separately allocated objects equal under JavaScript `===`, and
 `SubscriptionRef.set` is not itself a distinct-update filter. Callers that want to suppress
@@ -127,7 +131,8 @@ For each requested definition, `Orchestrator` runs this sequence:
 9. Stream stdout and stderr into `LogBuffer`.
 10. Run the health loop, or run `healthy` hooks immediately when no health check exists, then
     publish `Healthy`.
-11. Race process exit against an unhealthy-restart request and apply restart policy.
+11. Race process exit against unhealthy or hook failure, finalize the child, and apply restart
+    policy to process-exit and unhealthy causes.
 
 The service keeps the same state stream across restart generations. Restart backoff is
 `min(30 seconds, 2^(restartCount - 1))`.
@@ -140,7 +145,8 @@ declaration order. Each hook has a timeout (default: 30 seconds) and either:
 - `fail`: publish `HookFailed` and stop running later hooks for that trigger;
 - `ignore`: append a diagnostic log and continue.
 
-The supplied logger writes tagged stdout/stderr lines into the service's normal log stream.
+The supplied logger writes tagged stdout/stderr lines into the service's normal log stream. A
+failing hook finalizes its process generation before publishing terminal `Failed` state.
 
 ## Health and readiness
 
@@ -151,17 +157,25 @@ The supplied logger writes tagged stdout/stderr lines into the service's normal
 - exec: successful for exit code `0`.
 
 After `initialDelaySeconds`, probes repeat every `periodSeconds`. Each attempt is bounded by
-`timeoutSeconds`; consecutive success and failure counters reset each other. The current
-implementation calls `onHealthy` after `successThreshold`, and calls `onUnhealthy` after
-`failureThreshold` only after that same process generation has first become healthy. Consequently,
-initial probe failures leave a service in `Running` rather than publishing `Unhealthy`; callers
-must not treat the current generic `waitReady` Interface as a startup deadline.
+`timeoutSeconds`; consecutive success and failure counters reset each other. Before a process
+generation has ever become healthy, `startupFailureThreshold` controls when it becomes
+`Unhealthy`. It defaults to `failureThreshold` for compatibility. After the first healthy result,
+all later failures use `failureThreshold`, including after an unhealthy-to-healthy recovery.
+Initial probe failures are therefore observable rather than leaving the service indefinitely in
+`Running`.
+
+An unhealthy process uses the same pure restart-budget decision as a process exit. When restart is
+enabled and the budget is exhausted, the supervisor terminates the child and publishes `Failed`
+with `pid: null`, `exitCode: null`, and a stable health-exhaustion error. With restart policy `no`,
+the live process remains observable as `Unhealthy`.
 
 `waitReady(name)` is intentionally unbounded. For long-running definitions it succeeds at
-`Healthy` and fails at a non-restarting terminal state. For `restart: "no"` one-shot definitions,
-successful completion is readiness. `waitAllReady()` considers only definitions whose desired
-state is `running`, so intentionally inactive definitions do not block lazy callers. Higher-level
-Modules own any finite user-facing deadline.
+`Healthy` and fails at a non-restarting terminal state. A `restart: "no"` definition without a
+health check is treated as one-shot work, where successful completion is readiness; a
+health-checked definition remains subject to health readiness even when restart is disabled.
+`waitAllReady()` considers only definitions whose desired state is `running`, so intentionally
+inactive definitions do not block lazy callers. Higher-level Modules own any finite user-facing
+deadline.
 
 ## Restart policies
 
@@ -187,7 +201,8 @@ interrupts its lifecycle fiber. The generation finalizer:
 
 Whole-graph stop sets desired state first and then stops dependents before dependencies. The global
 shutdown budget defaults to 60 seconds. If that budget expires, the orchestrator logs the timeout
-and clears all fibers; it does not fail with `ShutdownTimeoutError`.
+and clears all fibers. Services that were running are forced to terminal `Stopped` state with
+`pid: null` and exit code `143`; stop does not fail with `ShutdownTimeoutError`.
 
 In-process cleanup and orphan supervision solve different failure modes:
 
diff --git a/packages/process-compose/src/HealthProbe.ts b/packages/process-compose/src/HealthProbe.ts
index 708a6b5b63..8664cc6100 100644
--- a/packages/process-compose/src/HealthProbe.ts
+++ b/packages/process-compose/src/HealthProbe.ts
@@ -69,13 +69,15 @@ export const runHealthProbe = (config: {
     const timeout = hc.timeoutSeconds ?? defaults.healthCheck.timeoutSeconds;
     const successThreshold = hc.successThreshold ?? defaults.healthCheck.successThreshold;
     const failureThreshold = hc.failureThreshold ?? defaults.healthCheck.failureThreshold;
+    const startupFailureThreshold = hc.startupFailureThreshold ?? failureThreshold;
 
     if (initialDelay > 0) {
       yield* Effect.sleep(Duration.seconds(initialDelay));
     }
 
     const counters = yield* Ref.make({ successes: 0, failures: 0 });
-    let isHealthy = false;
+    let phase: "Starting" | "Healthy" | "Unhealthy" = "Starting";
+    let hasEverBeenHealthy = false;
 
     yield* Effect.repeat(
       Effect.gen(function* () {
@@ -86,8 +88,9 @@ export const runHealthProbe = (config: {
             successes: c.successes + 1,
             failures: 0,
           }));
-          if (!isHealthy && successes + 1 >= successThreshold) {
-            isHealthy = true;
+          if (phase !== "Healthy" && successes + 1 >= successThreshold) {
+            phase = "Healthy";
+            hasEverBeenHealthy = true;
             yield* config.callbacks.onHealthy();
           }
         } else {
@@ -95,8 +98,11 @@ export const runHealthProbe = (config: {
             successes: 0,
             failures: c.failures + 1,
           }));
-          if (isHealthy && failures + 1 >= failureThreshold) {
-            isHealthy = false;
+          const activeFailureThreshold = hasEverBeenHealthy
+            ? failureThreshold
+            : startupFailureThreshold;
+          if (phase !== "Unhealthy" && failures + 1 >= activeFailureThreshold) {
+            phase = "Unhealthy";
             yield* config.callbacks.onUnhealthy();
           }
         }
diff --git a/packages/process-compose/src/HealthProbe.unit.test.ts b/packages/process-compose/src/HealthProbe.unit.test.ts
index c4bcf4f6cb..a2ac95c4e7 100644
--- a/packages/process-compose/src/HealthProbe.unit.test.ts
+++ b/packages/process-compose/src/HealthProbe.unit.test.ts
@@ -15,6 +15,37 @@ const platformLayer = BunChildProcessSpawnerLayer.pipe(
   Layer.provide(Layer.mergeAll(BunFileSystemLayer, BunPathLayer)),
 );
 
+const sequenceProbeLayer = (results: ReadonlyArray<boolean>) => {
+  let calls = 0;
+  return {
+    layer: Layer.succeed(
+      ChildProcessSpawner.ChildProcessSpawner,
+      ChildProcessSpawner.make(() =>
+        Effect.sync(() => {
+          const result = results[calls] ?? results.at(-1) ?? false;
+          calls++;
+          return ChildProcessSpawner.makeHandle({
+            pid: ChildProcessSpawner.ProcessId(2000 + calls),
+            stdout: Stream.empty,
+            stderr: Stream.empty,
+            all: Stream.empty,
+            exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(result ? 0 : 1)),
+            isRunning: Effect.succeed(false),
+            stdin: Sink.drain,
+            kill: () => Effect.void,
+            unref: Effect.succeed(Effect.void),
+            getInputFd: () => Sink.drain,
+            getOutputFd: () => Stream.empty,
+          });
+        }),
+      ),
+    ),
+    get calls() {
+      return calls;
+    },
+  };
+};
+
 const setupProbe = (probe: ProbeConfig, overrides?: Partial<HealthCheckConfig>) =>
   Effect.gen(function* () {
     let healthy = false;
@@ -190,6 +221,103 @@ describe("HealthProbe", () => {
     }).pipe(Effect.provide(platformLayer)),
   );
 
+  it.live("uses failureThreshold for startup when no startup threshold is configured", () => {
+    const probe = sequenceProbeLayer([false]);
+    return Effect.gen(function* () {
+      const { unhealthySignal, config } = yield* setupProbe(
+        { _tag: "Exec", command: "check", args: [] },
+        { failureThreshold: 2 },
+      );
+      const fiber = yield* Effect.forkChild(runHealthProbe(config));
+      yield* Deferred.await(unhealthySignal).pipe(Effect.timeout(Duration.seconds(1)));
+      expect(probe.calls).toBe(2);
+      yield* Fiber.interrupt(fiber);
+    }).pipe(Effect.provide(probe.layer));
+  });
+
+  it.live("allows a larger startup threshold than the liveness threshold", () => {
+    const probe = sequenceProbeLayer([false]);
+    return Effect.gen(function* () {
+      const { unhealthySignal, config } = yield* setupProbe(
+        { _tag: "Exec", command: "check", args: [] },
+        { startupFailureThreshold: 4, failureThreshold: 2 },
+      );
+      const fiber = yield* Effect.forkChild(runHealthProbe(config));
+      yield* Deferred.await(unhealthySignal).pipe(Effect.timeout(Duration.seconds(1)));
+      expect(probe.calls).toBe(4);
+      yield* Fiber.interrupt(fiber);
+    }).pipe(Effect.provide(probe.layer));
+  });
+
+  it.live("recovers on the final startup probe without becoming unhealthy", () => {
+    const probe = sequenceProbeLayer([false, false, true]);
+    return Effect.gen(function* () {
+      const { healthySignal, unhealthySignal, config } = yield* setupProbe(
+        { _tag: "Exec", command: "check", args: [] },
+        { startupFailureThreshold: 3, failureThreshold: 1 },
+      );
+      const fiber = yield* Effect.forkChild(runHealthProbe(config));
+      yield* Deferred.await(healthySignal).pipe(Effect.timeout(Duration.seconds(1)));
+      expect(probe.calls).toBe(3);
+      expect(yield* Deferred.isDone(unhealthySignal)).toBe(false);
+      yield* Fiber.interrupt(fiber);
+    }).pipe(Effect.provide(probe.layer));
+  });
+
+  it.live("uses the liveness threshold after the first healthy transition", () => {
+    const probe = sequenceProbeLayer([true, false, false]);
+    return Effect.gen(function* () {
+      const { healthySignal, unhealthySignal, config } = yield* setupProbe(
+        { _tag: "Exec", command: "check", args: [] },
+        { startupFailureThreshold: 5, failureThreshold: 2 },
+      );
+      const fiber = yield* Effect.forkChild(runHealthProbe(config));
+      yield* Deferred.await(healthySignal).pipe(Effect.timeout(Duration.seconds(1)));
+      yield* Deferred.await(unhealthySignal).pipe(Effect.timeout(Duration.seconds(1)));
+      expect(probe.calls).toBe(3);
+      yield* Fiber.interrupt(fiber);
+    }).pipe(Effect.provide(probe.layer));
+  });
+
+  it.live("does not re-enable startup tolerance after an unhealthy recovery", () => {
+    const probe = sequenceProbeLayer([true, false, false, true, false, false]);
+    return Effect.gen(function* () {
+      let healthyTransitions = 0;
+      let unhealthyTransitions = 0;
+      const secondUnhealthy = yield* Deferred.make<void>();
+      const fiber = yield* Effect.forkChild(
+        runHealthProbe({
+          name: "test",
+          healthCheck: {
+            probe: { _tag: "Exec", command: "check", args: [] },
+            periodSeconds: 0.01,
+            startupFailureThreshold: 5,
+            failureThreshold: 2,
+          },
+          callbacks: {
+            onHealthy: () =>
+              Effect.sync(() => {
+                healthyTransitions++;
+              }),
+            onUnhealthy: () =>
+              Effect.gen(function* () {
+                unhealthyTransitions++;
+                if (unhealthyTransitions === 2) {
+                  yield* Deferred.succeed(secondUnhealthy, void 0);
+                }
+              }),
+          },
+        }),
+      );
+
+      yield* Deferred.await(secondUnhealthy).pipe(Effect.timeout(Duration.seconds(1)));
+      expect(probe.calls).toBe(6);
+      expect(healthyTransitions).toBe(2);
+      expect(unhealthyTransitions).toBe(2);
+      yield* Fiber.interrupt(fiber);
+    }).pipe(Effect.provide(probe.layer));
+  });
+
   it.live("respects initialDelaySeconds before first probe", () =>
     Effect.gen(function* () {
       const { healthySignal, config } = yield* setupProbe(
diff --git a/packages/process-compose/src/Orchestrator.ts b/packages/process-compose/src/Orchestrator.ts
index 06bbaee504..23c33ed6fd 100644
--- a/packages/process-compose/src/Orchestrator.ts
+++ b/packages/process-compose/src/Orchestrator.ts
@@ -16,10 +16,14 @@ import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import { buildGraph, type ResolvedGraph } from "./DependencyGraph.ts";
 import { type HealthProbeCallbacks, runHealthProbe } from "./HealthProbe.ts";
 import { LogBuffer } from "./LogBuffer.ts";
+import {
+  decideRestart,
+  type LifecycleCause,
+  UNHEALTHY_RESTART_EXHAUSTED_ERROR,
+} from "./RestartDecision.ts";
 import type {
   HookTrigger,
   OrchestratorConfig,
-  RestartPolicy,
   ServiceDef,
   ServiceStartOptions,
 } from "./ServiceDef.ts";
@@ -154,7 +158,7 @@ export class Orchestrator extends Context.Service<
           );
 
         // Helper: run all hooks for a given trigger in sequence
-        const runHooks = (def: ServiceDef, trigger: HookTrigger): Effect.Effect<void> =>
+        const runHooks = (def: ServiceDef, trigger: HookTrigger): Effect.Effect<string | null> =>
           Effect.gen(function* () {
             const hooks = (def.hooks ?? []).filter((h) => h.on === trigger);
             for (const hook of hooks) {
@@ -165,11 +169,7 @@ export class Orchestrator extends Context.Service<
                 .run(log)
                 .pipe(Effect.timeout(Duration.seconds(timeout)), Effect.exit);
               if (Exit.isFailure(result) && (hook.failurePolicy ?? "fail") === "fail") {
-                yield* sendEvent(def.name, {
-                  _tag: "HookFailed",
-                  error: `Hook (on:${trigger}) failed: ${Cause.pretty(result.cause)}`,
-                });
-                return;
+                return `Hook (on:${trigger}) failed: ${Cause.pretty(result.cause)}`;
               }
               if (Exit.isFailure(result)) {
                 yield* logBuffer.append(
@@ -179,13 +179,13 @@ export class Orchestrator extends Context.Service<
                 );
               }
             }
+            return null;
           });
 
         type SpawnResult =
-          | { readonly _tag: "Exited"; readonly exitCode: number }
-          | { readonly _tag: "UnhealthyRestart" };
-
-        const shouldRestartOnUnhealthy = (policy: RestartPolicy): boolean => policy !== "no";
+          | { readonly _tag: "ProcessExit"; readonly exitCode: number }
+          | { readonly _tag: "Unhealthy" }
+          | { readonly _tag: "HookFailed"; readonly error: string };
 
         // The full lifecycle loop for a single service
         const runService = (
@@ -260,7 +260,7 @@ export class Orchestrator extends Context.Service<
             const spawnOnce = (): Effect.Effect<SpawnResult, SpawnError> =>
               Effect.scoped(
                 Effect.gen(function* () {
-                  const unhealthyRestart = Deferred.makeUnsafe<void>();
+                  const generationResult = Deferred.makeUnsafe<SpawnResult>();
                   const supervised = usesSupervisor(def);
 
                   // Build command
@@ -338,12 +338,9 @@ export class Orchestrator extends Context.Service<
 
                   // Keep the service in Starting until its started hooks pass,
                   // so Running is the stable dependency signal.
-                  yield* runHooks(def, "started");
-                  const stateAfterStartedHooks = SubscriptionRef.getUnsafe(
-                    services.get(def.name)!.state,
-                  );
-                  if (stateAfterStartedHooks.status === "Failed") {
-                    return { _tag: "Exited", exitCode: 1 } as SpawnResult;
+                  const startedHookError = yield* runHooks(def, "started");
+                  if (startedHookError !== null) {
+                    return { _tag: "HookFailed", error: startedHookError };
                   }
                   yield* sendEvent(def.name, {
                     _tag: "ProcessSpawned",
@@ -383,8 +380,12 @@ export class Orchestrator extends Context.Service<
                           if (service === undefined) return;
                           const current = SubscriptionRef.getUnsafe(service.state);
                           if (current.status === "Running") {
-                            yield* runHooks(def, "healthy");
-                            if (SubscriptionRef.getUnsafe(service.state).status === "Failed") {
+                            const healthyHookError = yield* runHooks(def, "healthy");
+                            if (healthyHookError !== null) {
+                              yield* Deferred.succeed(generationResult, {
+                                _tag: "HookFailed",
+                                error: healthyHookError,
+                              });
                               return;
                             }
                           }
@@ -398,8 +399,8 @@ export class Orchestrator extends Context.Service<
                             `[health-check-failed] Service "${def.name}" became unhealthy. Recent output:`,
                             `[health-check-failed] Service "${def.name}" became unhealthy (no recent log output).`,
                           );
-                          if (shouldRestartOnUnhealthy(restartPolicy)) {
-                            yield* Deferred.succeed(unhealthyRestart, void 0);
+                          if (restartPolicy !== "no") {
+                            yield* Deferred.succeed(generationResult, { _tag: "Unhealthy" });
                           }
                         }),
                     };
@@ -412,14 +413,11 @@ export class Orchestrator extends Context.Service<
                       Effect.forkChild,
                     );
                   } else {
-                    yield* runHooks(def, "healthy");
-                    const service = services.get(def.name);
-                    if (
-                      service !== undefined &&
-                      SubscriptionRef.getUnsafe(service.state).status !== "Failed"
-                    ) {
-                      yield* sendEvent(def.name, { _tag: "HealthCheckPassed" });
+                    const healthyHookError = yield* runHooks(def, "healthy");
+                    if (healthyHookError !== null) {
+                      return { _tag: "HookFailed", error: healthyHookError };
                     }
+                    yield* sendEvent(def.name, { _tag: "HealthCheckPassed" });
                   }
 
                   // Race process exit against unhealthy restart signal.
@@ -428,11 +426,11 @@ export class Orchestrator extends Context.Service<
                   // as exit code 143 (128 + SIGTERM).
                   const waitForExit = handle.exitCode.pipe(
                     Effect.map(
-                      (code): SpawnResult => ({ _tag: "Exited", exitCode: code as number }),
+                      (code): SpawnResult => ({ _tag: "ProcessExit", exitCode: Number(code) }),
                     ),
                     Effect.catch(
                       (): Effect.Effect<SpawnResult> =>
-                        Effect.succeed({ _tag: "Exited", exitCode: 143 }),
+                        Effect.succeed({ _tag: "ProcessExit", exitCode: 143 }),
                     ),
                   );
                   const waitForObservedOneShotExit =
@@ -443,7 +441,7 @@ export class Orchestrator extends Context.Service<
                               Effect.timeout(Duration.millis(100)),
                               Effect.catch(
                                 (): Effect.Effect<SpawnResult> =>
-                                  Effect.succeed({ _tag: "Exited", exitCode: 0 }),
+                                  Effect.succeed({ _tag: "ProcessExit", exitCode: 0 }),
                               ),
                             ),
                           ),
@@ -453,9 +451,7 @@ export class Orchestrator extends Context.Service<
                   return yield* Effect.raceAll([
                     waitForExit,
                     waitForObservedOneShotExit,
-                    Deferred.await(unhealthyRestart).pipe(
-                      Effect.map((): SpawnResult => ({ _tag: "UnhealthyRestart" })),
-                    ),
+                    Deferred.await(generationResult),
                   ]);
                 }),
               );
@@ -475,7 +471,7 @@ export class Orchestrator extends Context.Service<
             // Handle spawn result
             const handleResult = (r: SpawnResult) =>
               Effect.gen(function* () {
-                if (r._tag === "Exited") {
+                if (r._tag === "ProcessExit") {
                   if (r.exitCode !== 0 && r.exitCode !== 143) {
                     yield* appendRecentServiceLogs(
                       def.name,
@@ -484,27 +480,39 @@ export class Orchestrator extends Context.Service<
                     );
                   }
                   yield* sendEvent(def.name, { _tag: "ProcessExited", exitCode: r.exitCode });
+                } else if (r._tag === "HookFailed") {
+                  yield* sendEvent(def.name, { _tag: "HookFailed", error: r.error });
+                } else {
+                  yield* sendEvent(def.name, { _tag: "ProcessTerminated" });
                 }
-                // UnhealthyRestart: process killed by scope closure, skip ProcessExited
+                // Unhealthy is already recorded by the probe. Scope finalization
+                // terminates its process without inventing a process exit code.
               });
             yield* handleResult(result);
 
-            // Restart loop
-            const shouldRestart = (r: SpawnResult): boolean => {
+            const restartDecision = (r: SpawnResult) => {
               const svc = services.get(def.name);
-              if (svc === undefined || SubscriptionRef.getUnsafe(svc.state).desired !== "running") {
-                return false;
+              const desired =
+                svc === undefined ? "inactive" : SubscriptionRef.getUnsafe(svc.state).desired;
+              if (r._tag === "HookFailed") {
+                return { _tag: "Terminate", reason: "PolicyDisabled" } as const;
               }
-              if (r._tag === "UnhealthyRestart") return true;
-              if (restartPolicy === "no") return false;
-              if (restartPolicy === "always") return true;
-              if (restartPolicy === "unless-stopped") return true;
-              if (restartPolicy === "on-failure") return r.exitCode !== 0;
-              return false;
+              const cause: LifecycleCause =
+                r._tag === "ProcessExit"
+                  ? { _tag: "ProcessExit", exitCode: r.exitCode }
+                  : { _tag: "Unhealthy" };
+              return decideRestart({
+                cause,
+                policy: restartPolicy,
+                restartCount,
+                maxRestarts,
+                desired,
+              });
             };
 
-            while (shouldRestart(result) && (maxRestarts === 0 || restartCount < maxRestarts)) {
-              restartCount++;
+            let decision = restartDecision(result);
+            while (decision._tag === "Restart") {
+              restartCount = decision.restartCount;
 
               yield* sendEvent(def.name, { _tag: "RestartTriggered", restartCount });
 
@@ -512,7 +520,7 @@ export class Orchestrator extends Context.Service<
               // be reserved safely for the duration of this restart's backoff.
               yield* prepareStart();
 
-              if (result._tag === "UnhealthyRestart") {
+              if (result._tag === "Unhealthy") {
                 yield* appendRecentServiceLogs(
                   def.name,
                   `[restart] Service "${def.name}" is restarting after an unhealthy health check. Recent output:`,
@@ -530,6 +538,18 @@ export class Orchestrator extends Context.Service<
 
               result = yield* spawnOnce();
               yield* handleResult(result);
+              decision = restartDecision(result);
+            }
+
+            if (
+              result._tag === "Unhealthy" &&
+              decision._tag === "Terminate" &&
+              decision.reason === "BudgetExhausted"
+            ) {
+              yield* sendEvent(def.name, {
+                _tag: "UnhealthyRestartExhausted",
+                error: UNHEALTHY_RESTART_EXHAUSTED_ERROR,
+              });
             }
           });
 
@@ -591,13 +611,17 @@ export class Orchestrator extends Context.Service<
           Effect.suspend(() => {
             const svc = services.get(def.name);
             if (!svc) return Effect.void;
-            const restartPolicy = def.restart ?? defaults.restart;
-            const maxRestarts = def.maxRestarts ?? defaults.maxRestarts;
             const willRestartAfterExit = (state: ServiceState): boolean => {
-              if (state.desired !== "running" || state.exitCode === null) return false;
-              if (maxRestarts !== 0 && state.restartCount >= maxRestarts) return false;
-              if (restartPolicy === "always" || restartPolicy === "unless-stopped") return true;
-              return restartPolicy === "on-failure" && state.exitCode !== 0;
+              if (state.exitCode === null) return false;
+              return (
+                decideRestart({
+                  cause: { _tag: "ProcessExit", exitCode: state.exitCode },
+                  policy: def.restart ?? defaults.restart,
+                  restartCount: state.restartCount,
+                  maxRestarts: def.maxRestarts ?? defaults.maxRestarts,
+                  desired: state.desired,
+                })._tag === "Restart"
+              );
             };
 
             const current = SubscriptionRef.getUnsafe(svc.state);
@@ -621,7 +645,7 @@ export class Orchestrator extends Context.Service<
               );
             }
 
-            if (restartPolicy === "no") {
+            if ((def.restart ?? defaults.restart) === "no" && def.healthCheck == null) {
               return waitForState(
                 svc,
                 (state) => state.status === "Failed" || state.status === "Stopped",
@@ -783,6 +807,10 @@ export class Orchestrator extends Context.Service<
                       );
                     }
                     yield* FiberMap.clear(fibers);
+                    for (const def of graph.startOrder) {
+                      yield* sendEvent(def.name, { _tag: "StopRequested" });
+                      yield* sendEvent(def.name, { _tag: "ProcessExited", exitCode: 143 });
+                    }
                   }),
                 ),
               );
diff --git a/packages/process-compose/src/Orchestrator.unit.test.ts b/packages/process-compose/src/Orchestrator.unit.test.ts
index 81c83634a3..515d6658cf 100644
--- a/packages/process-compose/src/Orchestrator.unit.test.ts
+++ b/packages/process-compose/src/Orchestrator.unit.test.ts
@@ -1072,6 +1072,7 @@ describe("Orchestrator", () => {
       const state = yield* orc.getState("a");
       expect(state.status).toBe("Stopped");
       expect(state.exitCode).toBe(0);
+      expect(state.pid).toBeNull();
     }).pipe(Effect.provide(layer), Effect.scoped);
   });
 
@@ -1088,6 +1089,7 @@ describe("Orchestrator", () => {
       const state = yield* orc.getState("a");
       expect(state.status).toBe("Failed");
       expect(state.exitCode).toBe(1);
+      expect(state.pid).toBeNull();
       expect(log.entries.some((e) => e.line.includes("[process-exited]"))).toBe(true);
       expect(log.entries.some((e) => e.line.includes("about to fail"))).toBe(true);
     }).pipe(Effect.provide(layer), Effect.scoped);
@@ -1656,6 +1658,10 @@ describe("Orchestrator", () => {
         yield* orc.stop();
         const elapsed = Date.now() - before;
         expect(elapsed).toBeLessThan(3000);
+        const state = yield* orc.getState("stuck");
+        expect(state.status).toBe("Stopped");
+        expect(state.pid).toBeNull();
+        expect(state.exitCode).toBe(143);
       }).pipe(Effect.provide(layer), Effect.scoped);
     });
 
@@ -1856,12 +1862,110 @@ describe("Orchestrator", () => {
         const orc = yield* Orchestrator;
         yield* orc.start();
         yield* proc.waitForSpawn("a", 2);
-        yield* waitForState(orc, "a", (state) => state.status === "Unhealthy", "Unhealthy");
+        const state = yield* waitForState(
+          orc,
+          "a",
+          (candidate) => candidate.status === "Failed",
+          "Failed",
+        );
         // maxRestarts=1 means original spawn + 1 restart = 2 total
         const mainSpawns = proc.spawned.filter((s) => s.command === "a");
         expect(mainSpawns.length).toBe(2);
+        expect(state.pid).toBeNull();
+        expect(state.exitCode).toBeNull();
+        expect(state.error).toBe("Health check failed and restart budget was exhausted");
+
+        const readyError = yield* orc.waitReady("a").pipe(Effect.flip);
+        expect(readyError._tag).toBe("ServiceReadyError");
+        if (readyError._tag === "ServiceReadyError") {
+          expect(readyError.reason).toBe("Health check failed and restart budget was exhausted");
+        }
       }).pipe(Effect.provide(layer), Effect.scoped);
     });
+
+    it.live("applies startup failures before a service has ever been healthy", () => {
+      const { layer, proc } = setupOrchestrator(
+        [
+          svc("a", {
+            restart: "always",
+            maxRestarts: 1,
+            healthCheck: {
+              probe: { _tag: "Exec", command: "check", args: [] },
+              periodSeconds: 0.01,
+              startupFailureThreshold: 2,
+              failureThreshold: 1,
+            },
+          }),
+        ],
+        {
+          exitDelay: "5 seconds",
+          perService: { check: { exitCode: 1, exitDelay: "1 millis" } },
+        },
+      );
+
+      return Effect.gen(function* () {
+        const orc = yield* Orchestrator;
+        yield* orc.start();
+        const state = yield* waitForFailed(orc, "a");
+        expect(proc.spawned.filter((spawn) => spawn.command === "a")).toHaveLength(2);
+        expect(state.pid).toBeNull();
+        expect(state.exitCode).toBeNull();
+      }).pipe(Effect.provide(layer), Effect.scoped);
+    });
+
+    it.live("keeps an initially unhealthy no-restart service alive", () => {
+      const { layer, proc } = setupOrchestrator(
+        [
+          svc("a", {
+            restart: "no",
+            healthCheck: {
+              probe: { _tag: "Exec", command: "check", args: [] },
+              periodSeconds: 0.01,
+              failureThreshold: 1,
+            },
+          }),
+        ],
+        {
+          exitDelay: "5 seconds",
+          perService: { check: { exitCode: 1, exitDelay: "1 millis" } },
+        },
+      );
+
+      return Effect.gen(function* () {
+        const orc = yield* Orchestrator;
+        yield* orc.start();
+        const state = yield* waitForState(
+          orc,
+          "a",
+          (candidate) => candidate.status === "Unhealthy",
+          "Unhealthy",
+        );
+        expect(state.pid).not.toBeNull();
+        expect(state.exitCode).toBeNull();
+        expect(proc.spawned.filter((spawn) => spawn.command === "a")).toHaveLength(1);
+      }).pipe(Effect.provide(layer), Effect.scoped);
+    });
+  });
+
+  it.live("finalizes the child before publishing a healthy-hook failure", () => {
+    const { layer, proc } = setupOrchestrator(
+      [
+        svc("a", {
+          hooks: [{ on: "healthy", run: () => Effect.fail(new Error("warmup failed")) }],
+        }),
+      ],
+      { exitDelay: "5 seconds" },
+    );
+
+    return Effect.gen(function* () {
+      const orc = yield* Orchestrator;
+      yield* orc.start();
+      const state = yield* waitForFailed(orc, "a");
+      expect(proc.killed.some((record) => record.command === "a")).toBe(true);
+      expect(state.pid).toBeNull();
+      expect(state.exitCode).toBeNull();
+      expect(state.error).toContain("on:healthy");
+    }).pipe(Effect.provide(layer), Effect.scoped);
   });
 
   describe("readiness", () => {
diff --git a/packages/process-compose/src/RestartDecision.ts b/packages/process-compose/src/RestartDecision.ts
new file mode 100644
index 0000000000..dc1d2fc5ae
--- /dev/null
+++ b/packages/process-compose/src/RestartDecision.ts
@@ -0,0 +1,49 @@
+import type { RestartPolicy } from "./ServiceDef.ts";
+import type { ServiceDesiredState } from "./ServiceState.ts";
+
+export type LifecycleCause =
+  | { readonly _tag: "ProcessExit"; readonly exitCode: number }
+  | { readonly _tag: "Unhealthy" };
+
+export type RestartDecision =
+  | { readonly _tag: "Restart"; readonly restartCount: number }
+  | {
+      readonly _tag: "Terminate";
+      readonly reason: "NotDesired" | "PolicyDisabled" | "BudgetExhausted";
+    }
+  | { readonly _tag: "KeepRunningUnhealthy" };
+
+export const UNHEALTHY_RESTART_EXHAUSTED_ERROR =
+  "Health check failed and restart budget was exhausted";
+
+export function decideRestart(options: {
+  readonly cause: LifecycleCause;
+  readonly policy: RestartPolicy;
+  readonly restartCount: number;
+  readonly maxRestarts: number;
+  readonly desired: ServiceDesiredState;
+}): RestartDecision {
+  if (options.desired !== "running") {
+    return { _tag: "Terminate", reason: "NotDesired" };
+  }
+
+  if (options.cause._tag === "Unhealthy" && options.policy === "no") {
+    return { _tag: "KeepRunningUnhealthy" };
+  }
+
+  const policyAllowsRestart =
+    options.policy === "always" ||
+    options.policy === "unless-stopped" ||
+    (options.policy === "on-failure" &&
+      (options.cause._tag === "Unhealthy" || options.cause.exitCode !== 0));
+
+  if (!policyAllowsRestart) {
+    return { _tag: "Terminate", reason: "PolicyDisabled" };
+  }
+
+  if (options.maxRestarts !== 0 && options.restartCount >= options.maxRestarts) {
+    return { _tag: "Terminate", reason: "BudgetExhausted" };
+  }
+
+  return { _tag: "Restart", restartCount: options.restartCount + 1 };
+}
diff --git a/packages/process-compose/src/RestartDecision.unit.test.ts b/packages/process-compose/src/RestartDecision.unit.test.ts
new file mode 100644
index 0000000000..f8d751daa5
--- /dev/null
+++ b/packages/process-compose/src/RestartDecision.unit.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import { decideRestart, type LifecycleCause } from "./RestartDecision.ts";
+import type { RestartPolicy } from "./ServiceDef.ts";
+
+const exit = (exitCode: number): LifecycleCause => ({ _tag: "ProcessExit", exitCode });
+const unhealthy: LifecycleCause = { _tag: "Unhealthy" };
+
+describe("decideRestart", () => {
+  it.each([
+    ["no", exit(0), "Terminate"],
+    ["no", exit(1), "Terminate"],
+    ["no", unhealthy, "KeepRunningUnhealthy"],
+    ["on-failure", exit(0), "Terminate"],
+    ["on-failure", exit(1), "Restart"],
+    ["on-failure", unhealthy, "Restart"],
+    ["always", exit(0), "Restart"],
+    ["always", exit(1), "Restart"],
+    ["always", unhealthy, "Restart"],
+    ["unless-stopped", exit(0), "Restart"],
+    ["unless-stopped", exit(1), "Restart"],
+    ["unless-stopped", unhealthy, "Restart"],
+  ] as const)("applies %s to %o", (policy, cause, expected) => {
+    expect(
+      decideRestart({
+        policy,
+        cause,
+        restartCount: 0,
+        maxRestarts: 1,
+        desired: "running",
+      })._tag,
+    ).toBe(expected);
+  });
+
+  it.each(["no", "on-failure", "always", "unless-stopped"] as const)(
+    "never restarts %s after stop was requested",
+    (policy: RestartPolicy) => {
+      expect(
+        decideRestart({
+          policy,
+          cause: exit(1),
+          restartCount: 0,
+          maxRestarts: 0,
+          desired: "stopped",
+        }),
+      ).toEqual({ _tag: "Terminate", reason: "NotDesired" });
+    },
+  );
+
+  it("treats zero maxRestarts as unlimited", () => {
+    expect(
+      decideRestart({
+        policy: "always",
+        cause: unhealthy,
+        restartCount: 1_000,
+        maxRestarts: 0,
+        desired: "running",
+      }),
+    ).toEqual({ _tag: "Restart", restartCount: 1_001 });
+  });
+
+  it("terminates when the restart budget is exhausted", () => {
+    expect(
+      decideRestart({
+        policy: "always",
+        cause: unhealthy,
+        restartCount: 2,
+        maxRestarts: 2,
+        desired: "running",
+      }),
+    ).toEqual({ _tag: "Terminate", reason: "BudgetExhausted" });
+  });
+});
diff --git a/packages/process-compose/src/ServiceDef.ts b/packages/process-compose/src/ServiceDef.ts
index 3f9f857139..d015fcdae1 100644
--- a/packages/process-compose/src/ServiceDef.ts
+++ b/packages/process-compose/src/ServiceDef.ts
@@ -30,6 +30,8 @@ export interface HealthCheckConfig {
   readonly periodSeconds?: number;
   readonly timeoutSeconds?: number;
   readonly successThreshold?: number;
+  /** Consecutive failures allowed before the process has ever become healthy. */
+  readonly startupFailureThreshold?: number;
   readonly failureThreshold?: number;
 }
 
diff --git a/packages/process-compose/src/ServiceTransition.ts b/packages/process-compose/src/ServiceTransition.ts
index 662022ba57..228ca5e1ce 100644
--- a/packages/process-compose/src/ServiceTransition.ts
+++ b/packages/process-compose/src/ServiceTransition.ts
@@ -16,6 +16,8 @@ export type ServiceEvent =
     }
   | { readonly _tag: "HealthCheckPassed" }
   | { readonly _tag: "HealthCheckFailed" }
+  | { readonly _tag: "ProcessTerminated" }
+  | { readonly _tag: "UnhealthyRestartExhausted"; readonly error: string }
   | { readonly _tag: "ProcessExited"; readonly exitCode: number }
   | { readonly _tag: "StopRequested" }
   | {
@@ -39,6 +41,7 @@ const allowed = new Set<`${ServiceStatus}:${ServiceEvent["_tag"]}`>([
   "Starting:StopRequested",
   "Starting:HookFailed",
   "Running:HealthCheckPassed",
+  "Running:HealthCheckFailed",
   "Running:ProcessExited",
   "Running:StopRequested",
   "Healthy:HealthCheckPassed",
@@ -47,6 +50,7 @@ const allowed = new Set<`${ServiceStatus}:${ServiceEvent["_tag"]}`>([
   "Healthy:StopRequested",
   "Unhealthy:HealthCheckPassed",
   "Unhealthy:ProcessExited",
+  "Unhealthy:ProcessTerminated",
   "Unhealthy:StopRequested",
   "Stopping:ProcessExited",
   "Stopped:RestartTriggered",
@@ -54,6 +58,7 @@ const allowed = new Set<`${ServiceStatus}:${ServiceEvent["_tag"]}`>([
   "Failed:ProcessExited",
   "Failed:StopRequested",
   "Unhealthy:RestartTriggered",
+  "Unhealthy:UnhealthyRestartExhausted",
   "Restarting:StopRequested",
   "Restarting:SpawnFailed",
   "Restarting:BackoffElapsed",
@@ -95,12 +100,25 @@ export const applyEvent = (state: ServiceState, event: ServiceEvent): ServiceSta
     case "HealthCheckFailed":
       return new ServiceState({ ...state, status: "Unhealthy" });
 
+    case "UnhealthyRestartExhausted":
+      return new ServiceState({
+        ...state,
+        status: "Failed",
+        pid: null,
+        exitCode: null,
+        error: event.error,
+      });
+
+    case "ProcessTerminated":
+      return new ServiceState({ ...state, pid: null });
+
     case "ProcessExited": {
       const status: ServiceStatus =
         state.status === "Stopping" ? "Stopped" : event.exitCode === 0 ? "Stopped" : "Failed";
       return new ServiceState({
         ...state,
         status,
+        pid: null,
         exitCode: event.exitCode,
       });
     }
@@ -116,6 +134,7 @@ export const applyEvent = (state: ServiceState, event: ServiceEvent): ServiceSta
       return new ServiceState({
         ...state,
         status: "Restarting",
+        pid: null,
         restartCount: event.restartCount,
       });
 
@@ -133,6 +152,7 @@ export const applyEvent = (state: ServiceState, event: ServiceEvent): ServiceSta
       return new ServiceState({
         ...state,
         status: "Failed",
+        pid: null,
         error: event.error,
       });
   }
diff --git a/packages/process-compose/src/ServiceTransition.unit.test.ts b/packages/process-compose/src/ServiceTransition.unit.test.ts
index 08a295e6f7..6de22894a4 100644
--- a/packages/process-compose/src/ServiceTransition.unit.test.ts
+++ b/packages/process-compose/src/ServiceTransition.unit.test.ts
@@ -91,6 +91,7 @@ describe("ServiceTransition", () => {
       expect(next).not.toBeNull();
       expect(next!.status).toBe("Stopped");
       expect(next!.exitCode).toBe(0);
+      expect(next!.pid).toBeNull();
     });
 
     it("Running + ProcessExited(1) → Failed", () => {
@@ -99,6 +100,7 @@ describe("ServiceTransition", () => {
       expect(next).not.toBeNull();
       expect(next!.status).toBe("Failed");
       expect(next!.exitCode).toBe(1);
+      expect(next!.pid).toBeNull();
     });
 
     it("Running + StopRequested → Stopping", () => {
@@ -108,6 +110,13 @@ describe("ServiceTransition", () => {
       expect(next!.status).toBe("Stopping");
     });
 
+    it("Running + HealthCheckFailed → Unhealthy", () => {
+      const state = make("db", { status: "Running", pid: 1234 });
+      const next = applyEvent(state, { _tag: "HealthCheckFailed" });
+      expect(next?.status).toBe("Unhealthy");
+      expect(next?.pid).toBe(1234);
+    });
+
     it("Healthy + HealthCheckFailed → Unhealthy", () => {
       const state = make("db", { status: "Healthy", pid: 1234 });
       const next = applyEvent(state, { _tag: "HealthCheckFailed" });
@@ -219,6 +228,27 @@ describe("ServiceTransition", () => {
       expect(next).not.toBeNull();
       expect(next!.status).toBe("Restarting");
       expect(next!.restartCount).toBe(1);
+      expect(next!.pid).toBeNull();
+    });
+
+    it("Unhealthy + UnhealthyRestartExhausted → terminal Failed", () => {
+      const state = make("db", { status: "Unhealthy", pid: 1234, exitCode: null });
+      const next = applyEvent(state, {
+        _tag: "UnhealthyRestartExhausted",
+        error: "Health check failed and restart budget was exhausted",
+      });
+      expect(next?.status).toBe("Failed");
+      expect(next?.pid).toBeNull();
+      expect(next?.exitCode).toBeNull();
+      expect(next?.error).toBe("Health check failed and restart budget was exhausted");
+    });
+
+    it("Unhealthy + ProcessTerminated clears its no-longer-live pid", () => {
+      const state = make("db", { status: "Unhealthy", pid: 1234 });
+      const next = applyEvent(state, { _tag: "ProcessTerminated" });
+      expect(next?.status).toBe("Unhealthy");
+      expect(next?.pid).toBeNull();
+      expect(next?.exitCode).toBeNull();
     });
 
     it("Pending + StopRequested → Stopped (no process to kill)", () => {
@@ -324,6 +354,7 @@ describe("ServiceTransition", () => {
       expect(next).not.toBeNull();
       expect(next!.status).toBe("Failed");
       expect(next!.error).toBe("migration failed");
+      expect(next!.pid).toBeNull();
     });
 
     it("Healthy + HookFailed → Failed with error", () => {
diff --git a/packages/stack/src/DaemonServer.integration.test.ts b/packages/stack/src/DaemonServer.integration.test.ts
index 3b5c25cd15..e16ec4ac7f 100644
--- a/packages/stack/src/DaemonServer.integration.test.ts
+++ b/packages/stack/src/DaemonServer.integration.test.ts
@@ -31,7 +31,17 @@ const POSTGRES_STATE = new StackServiceState({
   error: null,
 });
 
-const MOCK_STATES: ReadonlyArray<StackServiceState> = [POSTGRES_STATE];
+const HEALTH_FAILED_STATE = new StackServiceState({
+  name: "edge-runtime",
+  status: "Failed",
+  pid: null,
+  exitCode: null,
+  restartCount: 2,
+  startedAt: Date.now(),
+  error: "Health check failed and restart budget was exhausted",
+});
+
+const MOCK_STATES: ReadonlyArray<StackServiceState> = [POSTGRES_STATE, HEALTH_FAILED_STATE];
 
 const MOCK_LOGS: ReadonlyArray<LogEntry> = [
   { timestamp: 1000, service: "postgres", stream: "stdout", line: "starting" },
@@ -190,9 +200,16 @@ describe("DaemonServer", () => {
     expect(res.status).toBe(200);
     const body = (await res.json()) as { info: StackInfo; services: StackServiceState[] };
     expect(body.info).toEqual(MOCK_INFO);
-    expect(body.services).toHaveLength(1);
+    expect(body.services).toHaveLength(2);
     expect(body.services.at(0)?.name).toBe("postgres");
     expect(body.services.at(0)?.status).toBe("Running");
+    expect(body.services.at(1)).toMatchObject({
+      name: "edge-runtime",
+      status: "Failed",
+      pid: null,
+      exitCode: null,
+      error: "Health check failed and restart budget was exhausted",
+    });
   });
 
   // -------------------------------------------------------------------------
diff --git a/packages/stack/src/RemoteStack.integration.test.ts b/packages/stack/src/RemoteStack.integration.test.ts
index 19e16a9c79..dc520bab1e 100644
--- a/packages/stack/src/RemoteStack.integration.test.ts
+++ b/packages/stack/src/RemoteStack.integration.test.ts
@@ -44,7 +44,21 @@ const AUTH_STATE = new StackServiceState({
   error: null,
 });
 
-const MOCK_STATES: ReadonlyArray<StackServiceState> = [POSTGRES_STATE, AUTH_STATE];
+const HEALTH_FAILED_STATE = new StackServiceState({
+  name: "edge-runtime",
+  status: "Failed",
+  pid: null,
+  exitCode: null,
+  restartCount: 2,
+  startedAt: Date.now(),
+  error: "Health check failed and restart budget was exhausted",
+});
+
+const MOCK_STATES: ReadonlyArray<StackServiceState> = [
+  POSTGRES_STATE,
+  AUTH_STATE,
+  HEALTH_FAILED_STATE,
+];
 
 const MOCK_LOGS: ReadonlyArray<LogEntry> = [
   { timestamp: 1000, service: "postgres", stream: "stdout", line: "starting" },
@@ -233,9 +247,16 @@ describe("RemoteStack integration", () => {
     const states = await clientRuntime.runPromise(
       Effect.flatMap(Stack, (stack) => stack.getAllStates()),
     );
-    expect(states).toHaveLength(2);
+    expect(states).toHaveLength(3);
     expect(states.at(0)?.name).toBe("postgres");
     expect(states.at(1)?.name).toBe("auth");
+    expect(states.at(2)).toMatchObject({
+      name: "edge-runtime",
+      status: "Failed",
+      pid: null,
+      exitCode: null,
+      error: "Health check failed and restart budget was exhausted",
+    });
   });
 
   test("getState returns a single service state", async () => {
diff --git a/packages/stack/src/StackServiceState.unit.test.ts b/packages/stack/src/StackServiceState.unit.test.ts
new file mode 100644
index 0000000000..20f3b99b81
--- /dev/null
+++ b/packages/stack/src/StackServiceState.unit.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { ServiceState } from "@supabase/process-compose";
+import { fromRawServiceState } from "./StackServiceState.ts";
+
+describe("fromRawServiceState", () => {
+  it("preserves terminal health-failure state semantics", () => {
+    const projected = fromRawServiceState(
+      new ServiceState({
+        name: "edge-runtime",
+        status: "Failed",
+        pid: null,
+        exitCode: null,
+        restartCount: 2,
+        startedAt: 1_000,
+        error: "Health check failed and restart budget was exhausted",
+        desired: "running",
+      }),
+    );
+
+    expect(projected).toMatchObject({
+      status: "Failed",
+      pid: null,
+      exitCode: null,
+      error: "Health check failed and restart budget was exhausted",
+    });
+  });
+});
diff --git a/packages/stack/src/services/analytics.ts b/packages/stack/src/services/analytics.ts
index 78c62f895e..9f2f742438 100644
--- a/packages/stack/src/services/analytics.ts
+++ b/packages/stack/src/services/analytics.ts
@@ -1,5 +1,6 @@
 import type { ServiceDef } from "@supabase/process-compose";
 import { dockerRunService, type ServiceDependency } from "./service-utils.ts";
+import { stackHealthBudgets } from "./health-budgets.ts";
 
 interface DockerAnalyticsOptions {
   readonly image: string;
@@ -34,9 +35,7 @@ const analyticsHealthCheck = (port: number): ServiceDef["healthCheck"] => ({
     path: "/health",
     scheme: "http",
   },
-  initialDelaySeconds: 10,
-  periodSeconds: 1,
-  failureThreshold: 60,
+  ...stackHealthBudgets.analytics,
 });
 
 export const makeAnalyticsServiceDocker = (opts: DockerAnalyticsOptions): ServiceDef => {
diff --git a/packages/stack/src/services/auth.ts b/packages/stack/src/services/auth.ts
index b3e0360c83..355b8265c6 100644
--- a/packages/stack/src/services/auth.ts
+++ b/packages/stack/src/services/auth.ts
@@ -1,5 +1,6 @@
 import type { ServiceDef } from "@supabase/process-compose";
 import { dockerServiceCleanup, dockerServiceOrphanCleanup } from "./docker-cleanup.ts";
+import { stackHealthBudgets } from "./health-budgets.ts";
 
 interface AuthServiceOptions {
   readonly dbPort: number;
@@ -66,8 +67,7 @@ const authHealthCheck = (port: number) => ({
     path: "/health",
     scheme: "http" as const,
   },
-  periodSeconds: 0.5,
-  failureThreshold: 20,
+  ...stackHealthBudgets.auth,
 });
 
 export const makeAuthServiceNative = (opts: NativeAuthOptions): ServiceDef => ({
diff --git a/packages/stack/src/services/edge-runtime.ts b/packages/stack/src/services/edge-runtime.ts
index 4132cf4787..66f6d52b9d 100644
--- a/packages/stack/src/services/edge-runtime.ts
+++ b/packages/stack/src/services/edge-runtime.ts
@@ -3,6 +3,7 @@ import { join } from "node:path";
 import type { ServiceDef } from "@supabase/process-compose";
 import { dockerRunService, hostHttpHealthCheck, type ServiceDependency } from "./service-utils.ts";
 import bootstrapSource from "./edge-runtime-main.ts" with { type: "text" };
+import { stackHealthBudgets } from "./health-budgets.ts";
 
 interface EdgeRuntimeOptions {
   readonly runtimeRoot: string;
@@ -61,9 +62,7 @@ const edgeRuntimeArgs = (
 
 const edgeRuntimeHealthCheck = (port: number): ServiceDef["healthCheck"] =>
   hostHttpHealthCheck(port, "/_internal/health", {
-    initialDelaySeconds: 1,
-    periodSeconds: 0.5,
-    failureThreshold: 30,
+    ...stackHealthBudgets.edgeRuntime,
   });
 
 export const makeEdgeRuntimeServiceNative = (opts: NativeEdgeRuntimeOptions): ServiceDef => {
diff --git a/packages/stack/src/services/health-budgets.ts b/packages/stack/src/services/health-budgets.ts
new file mode 100644
index 0000000000..ea478b5ad7
--- /dev/null
+++ b/packages/stack/src/services/health-budgets.ts
@@ -0,0 +1,94 @@
+import type { HealthCheckConfig } from "@supabase/process-compose";
+
+type HealthBudget = Pick<
+  HealthCheckConfig,
+  "initialDelaySeconds" | "periodSeconds" | "startupFailureThreshold" | "failureThreshold"
+>;
+
+/** Cold-start tolerance and tighter post-start liveness thresholds. */
+export const stackHealthBudgets = {
+  postgresNative: {
+    initialDelaySeconds: 0,
+    periodSeconds: 0.5,
+    startupFailureThreshold: 120,
+    failureThreshold: 30,
+  },
+  postgresDocker: {
+    initialDelaySeconds: 1,
+    periodSeconds: 0.5,
+    startupFailureThreshold: 120,
+    failureThreshold: 30,
+  },
+  auth: {
+    initialDelaySeconds: 0,
+    periodSeconds: 0.5,
+    startupFailureThreshold: 60,
+    failureThreshold: 20,
+  },
+  postgrest: {
+    initialDelaySeconds: 0,
+    periodSeconds: 0.5,
+    startupFailureThreshold: 60,
+    failureThreshold: 20,
+  },
+  edgeRuntime: {
+    initialDelaySeconds: 1,
+    periodSeconds: 0.5,
+    startupFailureThreshold: 60,
+    failureThreshold: 30,
+  },
+  mailpit: {
+    initialDelaySeconds: 1,
+    periodSeconds: 0.5,
+    startupFailureThreshold: 60,
+    failureThreshold: 30,
+  },
+  realtime: {
+    initialDelaySeconds: 1,
+    periodSeconds: 0.5,
+    startupFailureThreshold: 60,
+    failureThreshold: 30,
+  },
+  storage: {
+    initialDelaySeconds: 1,
+    periodSeconds: 0.5,
+    startupFailureThreshold: 60,
+    failureThreshold: 30,
+  },
+  imgproxy: {
+    initialDelaySeconds: 1,
+    periodSeconds: 0.5,
+    startupFailureThreshold: 60,
+    failureThreshold: 30,
+  },
+  pgmeta: {
+    initialDelaySeconds: 1,
+    periodSeconds: 0.5,
+    startupFailureThreshold: 60,
+    failureThreshold: 30,
+  },
+  analytics: {
+    initialDelaySeconds: 10,
+    periodSeconds: 1,
+    startupFailureThreshold: 120,
+    failureThreshold: 60,
+  },
+  vector: {
+    initialDelaySeconds: 1,
+    periodSeconds: 1,
+    startupFailureThreshold: 60,
+    failureThreshold: 30,
+  },
+  pooler: {
+    initialDelaySeconds: 2,
+    periodSeconds: 1,
+    startupFailureThreshold: 90,
+    failureThreshold: 60,
+  },
+  studio: {
+    initialDelaySeconds: 2,
+    periodSeconds: 1,
+    startupFailureThreshold: 90,
+    failureThreshold: 60,
+  },
+} as const satisfies Record<string, HealthBudget>;
diff --git a/packages/stack/src/services/health-budgets.unit.test.ts b/packages/stack/src/services/health-budgets.unit.test.ts
new file mode 100644
index 0000000000..9dced20c60
--- /dev/null
+++ b/packages/stack/src/services/health-budgets.unit.test.ts
@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import { stackHealthBudgets } from "./health-budgets.ts";
+
+describe("stack health budgets", () => {
+  it("records startup and liveness policy for every health-checked service", () => {
+    const summarized = Object.fromEntries(
+      Object.entries(stackHealthBudgets).map(([name, budget]) => [
+        name,
+        {
+          initialDelay: budget.initialDelaySeconds,
+          period: budget.periodSeconds,
+          startupThreshold: budget.startupFailureThreshold,
+          startupBudget:
+            budget.initialDelaySeconds + budget.periodSeconds * budget.startupFailureThreshold,
+          livenessThreshold: budget.failureThreshold,
+        },
+      ]),
+    );
+
+    expect(summarized).toMatchInlineSnapshot(`
+      {
+        "analytics": {
+          "initialDelay": 10,
+          "livenessThreshold": 60,
+          "period": 1,
+          "startupBudget": 130,
+          "startupThreshold": 120,
+        },
+        "auth": {
+          "initialDelay": 0,
+          "livenessThreshold": 20,
+          "period": 0.5,
+          "startupBudget": 30,
+          "startupThreshold": 60,
+        },
+        "edgeRuntime": {
+          "initialDelay": 1,
+          "livenessThreshold": 30,
+          "period": 0.5,
+          "startupBudget": 31,
+          "startupThreshold": 60,
+        },
+        "imgproxy": {
+          "initialDelay": 1,
+          "livenessThreshold": 30,
+          "period": 0.5,
+          "startupBudget": 31,
+          "startupThreshold": 60,
+        },
+        "mailpit": {
+          "initialDelay": 1,
+          "livenessThreshold": 30,
+          "period": 0.5,
+          "startupBudget": 31,
+          "startupThreshold": 60,
+        },
+        "pgmeta": {
+          "initialDelay": 1,
+          "livenessThreshold": 30,
+          "period": 0.5,
+          "startupBudget": 31,
+          "startupThreshold": 60,
+        },
+        "pooler": {
+          "initialDelay": 2,
+          "livenessThreshold": 60,
+          "period": 1,
+          "startupBudget": 92,
+          "startupThreshold": 90,
+        },
+        "postgresDocker": {
+          "initialDelay": 1,
+          "livenessThreshold": 30,
+          "period": 0.5,
+          "startupBudget": 61,
+          "startupThreshold": 120,
+        },
+        "postgresNative": {
+          "initialDelay": 0,
+          "livenessThreshold": 30,
+          "period": 0.5,
+          "startupBudget": 60,
+          "startupThreshold": 120,
+        },
+        "postgrest": {
+          "initialDelay": 0,
+          "livenessThreshold": 20,
+          "period": 0.5,
+          "startupBudget": 30,
+          "startupThreshold": 60,
+        },
+        "realtime": {
+          "initialDelay": 1,
+          "livenessThreshold": 30,
+          "period": 0.5,
+          "startupBudget": 31,
+          "startupThreshold": 60,
+        },
+        "storage": {
+          "initialDelay": 1,
+          "livenessThreshold": 30,
+          "period": 0.5,
+          "startupBudget": 31,
+          "startupThreshold": 60,
+        },
+        "studio": {
+          "initialDelay": 2,
+          "livenessThreshold": 60,
+          "period": 1,
+          "startupBudget": 92,
+          "startupThreshold": 90,
+        },
+        "vector": {
+          "initialDelay": 1,
+          "livenessThreshold": 30,
+          "period": 1,
+          "startupBudget": 61,
+          "startupThreshold": 60,
+        },
+      }
+    `);
+  });
+});
diff --git a/packages/stack/src/services/imgproxy.ts b/packages/stack/src/services/imgproxy.ts
index a943dad356..f38699f88e 100644
--- a/packages/stack/src/services/imgproxy.ts
+++ b/packages/stack/src/services/imgproxy.ts
@@ -1,5 +1,6 @@
 import type { ServiceDef } from "@supabase/process-compose";
 import { dockerRunService, hostHttpHealthCheck, type ServiceDependency } from "./service-utils.ts";
+import { stackHealthBudgets } from "./health-budgets.ts";
 
 interface DockerImgproxyOptions {
   readonly image: string;
@@ -14,9 +15,7 @@ const IMGPROXY_STORAGE_DIR = "/var/lib/storage";
 
 const imgproxyHealthCheck = (port: number): ServiceDef["healthCheck"] =>
   hostHttpHealthCheck(port, "/health", {
-    initialDelaySeconds: 1,
-    periodSeconds: 0.5,
-    failureThreshold: 30,
+    ...stackHealthBudgets.imgproxy,
   });
 
 export const makeImgproxyServiceDocker = (opts: DockerImgproxyOptions): ServiceDef =>
diff --git a/packages/stack/src/services/mailpit.ts b/packages/stack/src/services/mailpit.ts
index 70e0176de6..e60f41a14e 100644
--- a/packages/stack/src/services/mailpit.ts
+++ b/packages/stack/src/services/mailpit.ts
@@ -1,5 +1,6 @@
 import type { ServiceDef } from "@supabase/process-compose";
 import { dockerRunService, hostHttpHealthCheck } from "./service-utils.ts";
+import { stackHealthBudgets } from "./health-budgets.ts";
 
 interface DockerMailpitOptions {
   readonly image: string;
@@ -12,9 +13,7 @@ interface DockerMailpitOptions {
 
 const mailpitHealthCheck = (port: number): ServiceDef["healthCheck"] =>
   hostHttpHealthCheck(port, "/readyz", {
-    initialDelaySeconds: 1,
-    periodSeconds: 0.5,
-    failureThreshold: 30,
+    ...stackHealthBudgets.mailpit,
   });
 
 export const makeMailpitServiceDocker = (opts: DockerMailpitOptions): ServiceDef =>
diff --git a/packages/stack/src/services/pgmeta.ts b/packages/stack/src/services/pgmeta.ts
index 38c4fd282e..67a258c6f2 100644
--- a/packages/stack/src/services/pgmeta.ts
+++ b/packages/stack/src/services/pgmeta.ts
@@ -1,5 +1,6 @@
 import type { ServiceDef } from "@supabase/process-compose";
 import { dockerRunService, type ServiceDependency } from "./service-utils.ts";
+import { stackHealthBudgets } from "./health-budgets.ts";
 
 interface DockerPgmetaOptions {
   readonly image: string;
@@ -19,9 +20,7 @@ const pgmetaHealthCheck = (port: number): ServiceDef["healthCheck"] => ({
     path: "/health",
     scheme: "http",
   },
-  initialDelaySeconds: 1,
-  periodSeconds: 0.5,
-  failureThreshold: 30,
+  ...stackHealthBudgets.pgmeta,
 });
 
 export const makePgmetaServiceDocker = (opts: DockerPgmetaOptions): ServiceDef =>
diff --git a/packages/stack/src/services/pooler.ts b/packages/stack/src/services/pooler.ts
index be75a7397b..7d81e3edda 100644
--- a/packages/stack/src/services/pooler.ts
+++ b/packages/stack/src/services/pooler.ts
@@ -1,5 +1,6 @@
 import type { ServiceDef } from "@supabase/process-compose";
 import { dockerRunService, type ServiceDependency } from "./service-utils.ts";
+import { stackHealthBudgets } from "./health-budgets.ts";
 
 type PoolMode = "transaction" | "session";
 
@@ -28,9 +29,7 @@ const poolerHealthCheck = (port: number): ServiceDef["healthCheck"] => ({
     path: "/api/health",
     scheme: "http",
   },
-  initialDelaySeconds: 2,
-  periodSeconds: 1,
-  failureThreshold: 60,
+  ...stackHealthBudgets.pooler,
 });
 
 const tenantScript = (
diff --git a/packages/stack/src/services/postgres.ts b/packages/stack/src/services/postgres.ts
index bb3b5953f7..6968f989f8 100644
--- a/packages/stack/src/services/postgres.ts
+++ b/packages/stack/src/services/postgres.ts
@@ -5,6 +5,7 @@ import {
   dockerServiceOrphanCleanup,
   removePathOnOrphanCleanup,
 } from "./docker-cleanup.ts";
+import { stackHealthBudgets } from "./health-budgets.ts";
 
 interface PostgresServiceOptions {
   readonly dataDir: string;
@@ -89,8 +90,7 @@ const postgresHealthCheck = (binPath: string, port: number) => ({
       LD_LIBRARY_PATH: `${binPath}/lib`,
     },
   },
-  periodSeconds: 0.5,
-  failureThreshold: 30,
+  ...stackHealthBudgets.postgresNative,
 });
 
 /**
@@ -107,9 +107,7 @@ const postgresDockerHealthCheck = (containerName: string, port: number) => ({
     command: "docker",
     args: ["exec", containerName, "pg_isready", "-p", String(port), "-U", "postgres"],
   },
-  initialDelaySeconds: 1,
-  periodSeconds: 0.5,
-  failureThreshold: 30,
+  ...stackHealthBudgets.postgresDocker,
 });
 
 export const makePostgresService = (opts: NativePostgresOptions): ServiceDef => {
diff --git a/packages/stack/src/services/postgrest.ts b/packages/stack/src/services/postgrest.ts
index fffd349457..0562277927 100644
--- a/packages/stack/src/services/postgrest.ts
+++ b/packages/stack/src/services/postgrest.ts
@@ -1,5 +1,6 @@
 import type { ServiceDef } from "@supabase/process-compose";
 import { dockerServiceCleanup, dockerServiceOrphanCleanup } from "./docker-cleanup.ts";
+import { stackHealthBudgets } from "./health-budgets.ts";
 
 interface PostgrestServiceOptions {
   readonly dbPort: number;
@@ -43,8 +44,7 @@ const postgrestHealthCheck = (port: number) => ({
     path: "/",
     scheme: "http" as const,
   },
-  periodSeconds: 0.5,
-  failureThreshold: 20,
+  ...stackHealthBudgets.postgrest,
 });
 
 const postgrestDependencies = [{ service: "postgres-init", condition: "completed" as const }];
diff --git a/packages/stack/src/services/realtime.ts b/packages/stack/src/services/realtime.ts
index 4f4c209777..a8bd42eacd 100644
--- a/packages/stack/src/services/realtime.ts
+++ b/packages/stack/src/services/realtime.ts
@@ -1,5 +1,6 @@
 import type { ServiceDef } from "@supabase/process-compose";
 import { dockerRunService, type ServiceDependency } from "./service-utils.ts";
+import { stackHealthBudgets } from "./health-budgets.ts";
 
 interface DockerRealtimeOptions {
   readonly image: string;
@@ -31,9 +32,7 @@ const realtimeHealthCheck = (port: number, tenantId: string): ServiceDef["health
       `http://127.0.0.1:${port}/api/ping`,
     ],
   },
-  initialDelaySeconds: 1,
-  periodSeconds: 0.5,
-  failureThreshold: 30,
+  ...stackHealthBudgets.realtime,
 });
 
 export const makeRealtimeServiceDocker = (opts: DockerRealtimeOptions): ServiceDef =>
diff --git a/packages/stack/src/services/storage.ts b/packages/stack/src/services/storage.ts
index 056a27605e..87e21a6ab9 100644
--- a/packages/stack/src/services/storage.ts
+++ b/packages/stack/src/services/storage.ts
@@ -1,6 +1,7 @@
 import type { ServiceDef } from "@supabase/process-compose";
 import { removePathOnOrphanCleanup } from "./docker-cleanup.ts";
 import { dockerRunService, type ServiceDependency } from "./service-utils.ts";
+import { stackHealthBudgets } from "./health-budgets.ts";
 
 interface DockerStorageOptions {
   readonly image: string;
@@ -38,9 +39,7 @@ const storageHealthCheck = (port: number): ServiceDef["healthCheck"] => ({
     path: "/status",
     scheme: "http",
   },
-  initialDelaySeconds: 1,
-  periodSeconds: 0.5,
-  failureThreshold: 30,
+  ...stackHealthBudgets.storage,
 });
 
 export const makeStorageServiceDocker = (opts: DockerStorageOptions): ServiceDef =>
diff --git a/packages/stack/src/services/studio.ts b/packages/stack/src/services/studio.ts
index 7521fce3c7..4b139abc96 100644
--- a/packages/stack/src/services/studio.ts
+++ b/packages/stack/src/services/studio.ts
@@ -1,5 +1,6 @@
 import type { ServiceDef } from "@supabase/process-compose";
 import { dockerRunService, type ServiceDependency } from "./service-utils.ts";
+import { stackHealthBudgets } from "./health-budgets.ts";
 
 interface DockerStudioOptions {
   readonly image: string;
@@ -29,9 +30,7 @@ const studioHealthCheck = (port: number): ServiceDef["healthCheck"] => ({
     path: "/api/platform/profile",
     scheme: "http",
   },
-  initialDelaySeconds: 2,
-  periodSeconds: 1,
-  failureThreshold: 60,
+  ...stackHealthBudgets.studio,
 });
 
 export const makeStudioServiceDocker = (opts: DockerStudioOptions): ServiceDef =>
diff --git a/packages/stack/src/services/vector.ts b/packages/stack/src/services/vector.ts
index a66bf5f88a..90aa557f04 100644
--- a/packages/stack/src/services/vector.ts
+++ b/packages/stack/src/services/vector.ts
@@ -4,6 +4,7 @@ import {
   dockerRunService,
   type ServiceDependency,
 } from "./service-utils.ts";
+import { stackHealthBudgets } from "./health-budgets.ts";
 
 interface DockerVectorOptions {
   readonly image: string;
@@ -67,9 +68,7 @@ ${VECTOR_CONFIG(opts.serviceHost, opts.analyticsPort, opts.analyticsApiKey)}EOF
       "sh",
       ["-ec", "wget -q -O /dev/null http://127.0.0.1:9001/health"],
       {
-        initialDelaySeconds: 1,
-        periodSeconds: 1,
-        failureThreshold: 30,
+        ...stackHealthBudgets.vector,
       },
     ),
   });
diff --git a/packages/stack/tests/createStack-docker.e2e.test.ts b/packages/stack/tests/createStack-docker.e2e.test.ts
index 41eacc6e2b..0cba048b0b 100644
--- a/packages/stack/tests/createStack-docker.e2e.test.ts
+++ b/packages/stack/tests/createStack-docker.e2e.test.ts
@@ -34,6 +34,7 @@ dockerDescribe("createStack e2e (docker mode)", () => {
       mode: "docker",
       jwtSecret: "super-secret-jwt-token-with-at-least-32-characters-long",
       postgres: { dataDir },
+      analytics: {},
     });
 
     try {
@@ -110,6 +111,20 @@ dockerDescribe("createStack e2e (docker mode)", () => {
     },
   );
 
+  test("cold-starts analytics through lazy service activation", { timeout: 60_000 }, async () => {
+    await stack.startService("analytics");
+
+    const [runningImages, states] = await Promise.all([
+      Promise.resolve(execSync("docker ps --format '{{.Image}}'").toString()),
+      stack.getStatus(),
+    ]);
+
+    expect(runningImages).toContain("supabase/logflare");
+    expect(states).toEqual(
+      expect.arrayContaining([expect.objectContaining({ name: "analytics", status: "Healthy" })]),
+    );
+  });
+
   test(
     "supports the docker auth signup and session golden path",
     { timeout: STACK_DOCKER_E2E_TEST_TIMEOUT_MS },

From 7d19e70de09f8d9786f966c832c3e63dda5eddf4 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 15:02:03 +0200
Subject: [PATCH 03/44] refactor(stack): establish explicit domain model

---
 packages/stack/README.md                      |  13 +-
 packages/stack/docs/architecture.md           |  27 +-
 packages/stack/docs/service-versioning.md     |  12 +-
 .../scripts/sync-versions-from-dockerfile.ts  |  55 +-
 .../src/BinaryResolver.integration.test.ts    |   2 +-
 packages/stack/src/BinaryResolver.ts          |   4 +-
 .../stack/src/BinaryResolver.unit.test.ts     |   2 +-
 packages/stack/src/ServiceActivation.ts       |  39 +-
 .../stack/src/ServiceActivation.unit.test.ts  |   5 +-
 packages/stack/src/ServiceArtifacts.ts        | 213 ------
 packages/stack/src/ServiceCatalog.ts          | 337 +++++++++
 .../stack/src/ServiceCatalog.unit.test.ts     |  22 +
 packages/stack/src/ServiceName.ts             |  15 +
 packages/stack/src/ServicePorts.ts            |  25 +-
 packages/stack/src/Stack.ts                   |   2 +-
 packages/stack/src/Stack.unit.test.ts         |   3 +-
 packages/stack/src/StackBuilder.ts            | 361 +---------
 packages/stack/src/StackBuilder.unit.test.ts  |   3 +-
 packages/stack/src/StackConfig.ts             | 295 ++++++++
 packages/stack/src/StackConfig.unit.test.ts   |  59 ++
 packages/stack/src/StackConfigResolver.ts     | 613 +++++++++++++++++
 .../stack/src/StackLifecycleCoordinator.ts    |   2 +-
 packages/stack/src/StackMetadata.ts           |  12 +-
 packages/stack/src/StackPreparation.ts        |  15 +-
 packages/stack/src/bun.ts                     |   2 +-
 packages/stack/src/cleanup.ts                 |   2 +-
 packages/stack/src/createStack.ts             | 645 +-----------------
 packages/stack/src/createStack.unit.test.ts   |  24 +-
 packages/stack/src/daemon.ts                  |   7 +-
 packages/stack/src/discovery.ts               |   2 +-
 packages/stack/src/effect.ts                  |  16 +-
 packages/stack/src/functions.ts               |   2 +-
 packages/stack/src/functions.unit.test.ts     |   2 +-
 packages/stack/src/index.ts                   |   8 +-
 packages/stack/src/layers.ts                  |  13 +-
 packages/stack/src/node.ts                    |   2 +-
 packages/stack/src/prefetch.ts                |  12 +-
 packages/stack/src/resolve.ts                 |  35 -
 packages/stack/src/versions.ts                |  69 +-
 packages/stack/src/versions.unit.test.ts      |  77 +--
 40 files changed, 1569 insertions(+), 1485 deletions(-)
 delete mode 100644 packages/stack/src/ServiceArtifacts.ts
 create mode 100644 packages/stack/src/ServiceCatalog.ts
 create mode 100644 packages/stack/src/ServiceCatalog.unit.test.ts
 create mode 100644 packages/stack/src/ServiceName.ts
 create mode 100644 packages/stack/src/StackConfig.ts
 create mode 100644 packages/stack/src/StackConfig.unit.test.ts
 create mode 100644 packages/stack/src/StackConfigResolver.ts
 delete mode 100644 packages/stack/src/resolve.ts

diff --git a/packages/stack/README.md b/packages/stack/README.md
index 85d2db88e1..50dd10f464 100644
--- a/packages/stack/README.md
+++ b/packages/stack/README.md
@@ -198,10 +198,11 @@ service and its projected status.
 ### Readiness
 
 ```typescript
-await stack.ready(); // Wait for all services
-await stack.ready({ timeout: 30_000 }); // With timeout (ms)
-await stack.serviceReady("postgres"); // Wait for one service
-await stack.serviceReady("auth", { timeout: 10_000 });
+await stack.ready(); // Inherit the stack's finite two-minute default
+await stack.ready({ mode: "finite", timeoutMs: 30_000 });
+await stack.ready({ mode: "infinite" }); // Explicit debugging override
+await stack.serviceReady("postgres");
+await stack.serviceReady("auth", { mode: "finite", timeoutMs: 10_000 });
 ```
 
 In eager mode, `start()` blocks until every enabled service is ready. In lazy mode it waits only
@@ -276,8 +277,8 @@ await prefetch({ versions: { postgres: "17.4.1.045" } });
 ## Service Versions
 
 Default versions are used when no per-service `version` field is specified. The authoritative,
-exhaustive values are exported as `DEFAULT_VERSIONS` and live in
-[`src/versions.ts`](./src/versions.ts); they are intentionally not copied into this README.
+exhaustive values live in [`src/ServiceCatalog.ts`](./src/ServiceCatalog.ts) and are exported as
+the derived `DEFAULT_VERSIONS` manifest; they are intentionally not copied into this README.
 
 Override versions per service:
 
diff --git a/packages/stack/docs/architecture.md b/packages/stack/docs/architecture.md
index 042f24cf7f..336964d1d2 100644
--- a/packages/stack/docs/architecture.md
+++ b/packages/stack/docs/architecture.md
@@ -20,7 +20,7 @@ socket HTTP implementations. `createStack.ts` remains platform-agnostic and rece
 
 ```mermaid
 flowchart LR
-    Input["StackConfig"] --> Resolve["resolveConfig"]
+    Input["StackConfig"] --> Resolve["StackConfigResolver"]
     Resolve --> Layer["foregroundLayer"]
     Layer --> Prepare["StackPreparation"]
     Prepare --> Builder["StackBuilder"]
@@ -40,7 +40,7 @@ can use the same lifecycle calls against an in-process stack or a detached daemo
 top-level fields choose runtime mode, startup mode, cache/runtime roots, API keys, JWT secret,
 functions options, and per-service configuration. `false` disables an optional service.
 
-`resolveConfig()`:
+`StackConfigResolver.resolveConfig()`:
 
 1. chooses cache, durable stack, runtime, and project roots;
 2. allocates every required port through one port allocator;
@@ -48,6 +48,12 @@ functions options, and per-service configuration. `false` disables an optional s
 4. applies per-service defaults and current `DEFAULT_VERSIONS`;
 5. records auto-managed paths for scoped cleanup.
 
+Readiness policy is part of the resolved configuration. The package default is a finite two-minute
+deadline; callers can choose a different finite deadline or explicit infinite waiting. Per-call
+`ReadyOptions` take precedence over the stack policy, while `inherit` delegates to the stack
+policy. The Promise `ready()` / `serviceReady()` Adapter applies that resolver today. The Effect
+lifecycle Interface remains unbounded until deadline enforcement is centralized there.
+
 The current zero-config stack enables PostgreSQL, PostgREST, Auth, and Edge Runtime. Realtime,
 Storage, imgproxy, Mailpit, Postgres Meta, Studio, Analytics, Vector, and Supavisor are enabled only
 when their corresponding configuration object is present. In `native` mode, Edge Runtime is also
@@ -65,7 +71,8 @@ disabled by omission because the automatic artifact policy currently classifies
 
 Preparation is separate from topology construction:
 
-- `ServiceArtifacts.ts` records native release providers and Docker image candidates.
+- `ServiceCatalog.ts` is the exhaustive source for service identity, default version, runtime
+  support, artifact providers, activation policy, and allocated port fields.
 - `BinaryResolver` detects the platform, downloads and verifies archives, restores executable
   permissions, and publishes complete cache entries atomically.
 - `StackPreparation` resolves all enabled public services, emits download/pull progress, and
@@ -76,7 +83,9 @@ Native cache identity includes service, provider, version, and asset name. `.com
 last, so an incomplete download is never treated as reusable. Supabase-owned Docker images are
 tried through ECR, Docker Hub, then GHCR; upstream images use their canonical repository.
 
-`prefetch()` uses the same `StackPreparation` Interface without constructing a lifecycle runtime.
+`ServiceResolution` belongs to this preparation domain. `prefetch()` uses the same
+`StackPreparation` Interface and its binary-to-Docker fallback without constructing a lifecycle
+runtime.
 
 ## Service coverage and topology
 
@@ -131,12 +140,13 @@ process statuses.
 
 `start()` prepares artifacts, creates the runtime once, starts the appropriate services, and waits
 for their generic process-compose readiness. `stop()` preserves explicit per-service stop intent;
-`dispose()` additionally closes the scoped runtime and executes cleanup. Current generic readiness
-has no built-in deadline.
+`dispose()` additionally closes the scoped runtime and executes cleanup. Generic process-compose
+readiness remains intentionally policy-free and unbounded.
 
 ## Eager and lazy activation
 
-`ServiceActivation.ts` is the declarative startup and companion-ownership policy:
+`ServiceActivation.ts` evaluates the startup and companion-ownership metadata in
+`ServiceCatalog.ts`:
 
 - eager: PostgreSQL, Realtime, Mailpit, Studio, and Pooler;
 - lazy: PostgREST, Auth, Edge Runtime, Storage, imgproxy, Postgres Meta, Analytics, and Vector;
@@ -276,5 +286,6 @@ Callers may explicitly supply `projectStateRoot`, in which case durable stacks l
 - Targeted e2e tests own the expensive process/container Seam for full stack startup, parallel
   stacks, daemon lifecycle, and cleanup behavior.
 
-The authoritative current service versions are `DEFAULT_VERSIONS` in `src/versions.ts`; package
+The authoritative current service versions are the `defaultVersion` fields in
+`src/ServiceCatalog.ts`; `DEFAULT_VERSIONS` is derived from that catalog, and package
 documentation should link to that source rather than copy its values.
diff --git a/packages/stack/docs/service-versioning.md b/packages/stack/docs/service-versioning.md
index d4c12efdfa..f8a3dd819c 100644
--- a/packages/stack/docs/service-versioning.md
+++ b/packages/stack/docs/service-versioning.md
@@ -38,10 +38,10 @@ The important separation is:
 
 ## Artifact Providers and Runtime Support
 
-Every service in the Stack has one artifact definition, regardless of who maintains it. The
-definition records its Docker image provider, tag convention, and whether a supported native
-release is available. Runtime code consumes the resulting service resolution and does not need to
-know which registry or release repository supplied it.
+Every service in the Stack has one entry in `ServiceCatalog.ts`, regardless of who maintains it.
+The entry records its default version, Docker image provider, tag convention, runtime support, and
+any native release source. Runtime code consumes the resulting service resolution and does not
+need to know which registry or release repository supplied it.
 
 Supabase-managed images currently retain their ECR, Docker Hub, and GHCR candidates. External
 services such as imgproxy, Mailpit, and Vector retain their upstream Docker images and are marked
@@ -63,8 +63,8 @@ service definitions.
 The old Go CLI used `pkg/config/templates/Dockerfile` as a version manifest so Dependabot could
 bump image tags automatically.
 
-The TypeScript stack exports a typed `DEFAULT_VERSIONS` manifest instead. That constant is the
-built-in default version set for a given CLI release.
+The TypeScript stack derives its typed `DEFAULT_VERSIONS` manifest from `ServiceCatalog.ts`. The
+catalog values are the built-in default version set for a given CLI release.
 
 These defaults are the fallback for:
 
diff --git a/packages/stack/scripts/sync-versions-from-dockerfile.ts b/packages/stack/scripts/sync-versions-from-dockerfile.ts
index 39e4592ea2..a35e4db24d 100644
--- a/packages/stack/scripts/sync-versions-from-dockerfile.ts
+++ b/packages/stack/scripts/sync-versions-from-dockerfile.ts
@@ -11,7 +11,7 @@ import {
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(scriptDir, "../../..");
 const dockerfilePath = path.join(repoRoot, "apps/cli-go/pkg/config/templates/Dockerfile");
-const versionsPath = path.join(repoRoot, "packages/stack/src/versions.ts");
+const catalogPath = path.join(repoRoot, "packages/stack/src/ServiceCatalog.ts");
 
 const fromLinePattern = /^FROM\s+(.+):([^:\s]+)\s+AS\s+([^\s#]+)/i;
 
@@ -76,43 +76,40 @@ export function readVersionManifestFromDockerfile(dockerfile: string): VersionMa
   return versions;
 }
 
-function renderManifestKey(service: ServiceName): string {
-  return /^[a-zA-Z_$][\w$]*$/.test(service) ? service : JSON.stringify(service);
-}
-
-export function renderDefaultVersions(versions: VersionManifest): string {
-  const lines = SERVICE_NAMES.map(
-    (service) => `  ${renderManifestKey(service)}: ${JSON.stringify(versions[service])},`,
-  );
-  return ["export const DEFAULT_VERSIONS: VersionManifest = {", ...lines, "} as const;"].join("\n");
-}
-
 export function syncDefaultVersionsSource(source: string, versions: VersionManifest): string {
-  const startMarker = "export const DEFAULT_VERSIONS: VersionManifest = {";
-  const endMarker = "\n} as const;";
-  const start = source.indexOf(startMarker);
-  if (start === -1) {
-    throw new Error("Could not find DEFAULT_VERSIONS declaration.");
-  }
+  let updated = source;
+  for (const service of SERVICE_NAMES) {
+    const nameMarker = `    name: ${JSON.stringify(service)},`;
+    const entryStart = updated.indexOf(nameMarker);
+    if (entryStart === -1) {
+      throw new Error(`Could not find catalog entry for '${service}'.`);
+    }
 
-  const end = source.indexOf(endMarker, start);
-  if (end === -1) {
-    throw new Error("Could not find DEFAULT_VERSIONS declaration end.");
-  }
+    const versionMarker = "    defaultVersion: ";
+    const versionStart = updated.indexOf(versionMarker, entryStart + nameMarker.length);
+    if (versionStart === -1 || versionStart - entryStart > 300) {
+      throw new Error(`Could not find defaultVersion for '${service}'.`);
+    }
+    const versionEnd = updated.indexOf("\n", versionStart);
+    if (versionEnd === -1) {
+      throw new Error(`Could not find defaultVersion line end for '${service}'.`);
+    }
 
-  return `${source.slice(0, start)}${renderDefaultVersions(versions)}${source.slice(
-    end + endMarker.length,
-  )}`;
+    updated = `${updated.slice(0, versionStart)}${versionMarker}${JSON.stringify(
+      versions[service],
+    )},${updated.slice(versionEnd)}`;
+  }
+  return updated;
 }
 
 async function main() {
   const checkOnly = process.argv.includes("--check");
   const dockerfile = await readFile(dockerfilePath, "utf8");
-  const versionsSource = await readFile(versionsPath, "utf8");
+  const catalogSource = await readFile(catalogPath, "utf8");
   const versions = readVersionManifestFromDockerfile(dockerfile);
-  const syncedSource = syncDefaultVersionsSource(versionsSource, versions);
+  const syncedSource = syncDefaultVersionsSource(catalogSource, versions);
 
-  if (syncedSource === versionsSource) {
+  if (syncedSource === catalogSource) {
     console.log("DEFAULT_VERSIONS is already synced with the Dockerfile manifest.");
     return;
   }
@@ -123,7 +120,7 @@ async function main() {
     return;
   }
 
-  await Bun.write(versionsPath, syncedSource);
+  await Bun.write(catalogPath, syncedSource);
   console.log("Synced DEFAULT_VERSIONS with the Dockerfile manifest.");
 }
 
diff --git a/packages/stack/src/BinaryResolver.integration.test.ts b/packages/stack/src/BinaryResolver.integration.test.ts
index b7ff757b7d..5dc58fe38d 100644
--- a/packages/stack/src/BinaryResolver.integration.test.ts
+++ b/packages/stack/src/BinaryResolver.integration.test.ts
@@ -18,7 +18,7 @@ import { afterEach } from "vitest";
 import { BinaryResolver } from "./BinaryResolver.ts";
 import { DownloadError } from "./errors.ts";
 import { detectPlatform } from "./Platform.ts";
-import { nativeReleaseForService } from "./ServiceArtifacts.ts";
+import { nativeReleaseForService } from "./ServiceCatalog.ts";
 import { DEFAULT_VERSIONS } from "./versions.ts";
 
 const tempRoots: string[] = [];
diff --git a/packages/stack/src/BinaryResolver.ts b/packages/stack/src/BinaryResolver.ts
index dbd68113b7..f6ee4070d4 100644
--- a/packages/stack/src/BinaryResolver.ts
+++ b/packages/stack/src/BinaryResolver.ts
@@ -8,8 +8,8 @@ import {
   nativeReleaseForService,
   type ArchiveFormat,
   type NativeReleaseArtifact,
-} from "./ServiceArtifacts.ts";
-import type { ServiceName } from "./versions.ts";
+} from "./ServiceCatalog.ts";
+import type { ServiceName } from "./ServiceName.ts";
 
 export interface BinarySpec {
   readonly service: ServiceName;
diff --git a/packages/stack/src/BinaryResolver.unit.test.ts b/packages/stack/src/BinaryResolver.unit.test.ts
index 3aabc93834..d0576010bd 100644
--- a/packages/stack/src/BinaryResolver.unit.test.ts
+++ b/packages/stack/src/BinaryResolver.unit.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "@effect/vitest";
 import { BinaryResolver } from "./BinaryResolver.ts";
-import { nativeReleaseForService } from "./ServiceArtifacts.ts";
+import { nativeReleaseForService } from "./ServiceCatalog.ts";
 import { DEFAULT_VERSIONS } from "./versions.ts";
 
 const postgresVersion = DEFAULT_VERSIONS.postgres;
diff --git a/packages/stack/src/ServiceActivation.ts b/packages/stack/src/ServiceActivation.ts
index a97d147489..e66f9fd8e2 100644
--- a/packages/stack/src/ServiceActivation.ts
+++ b/packages/stack/src/ServiceActivation.ts
@@ -2,40 +2,11 @@ import { ServiceNotFoundError } from "@supabase/process-compose";
 import type { ServiceReadyError } from "@supabase/process-compose";
 import { Context, Effect, Layer } from "effect";
 import { StackBuildError, StackNotRunningError } from "./errors.ts";
-import type { ServiceName } from "./versions.ts";
-
-export interface ServiceActivationPolicy {
-  /** Whether the public service must already be running when lazy startup completes. */
-  readonly startup: "eager" | "lazy";
-  /** Other public services required when this service is activated. */
-  readonly activates?: ReadonlyArray<ServiceName>;
-  /** Private companions whose lifecycle is exclusively owned by this service. */
-  readonly owns?: ReadonlyArray<ServiceName>;
-}
-
-/**
- * Central ownership map for lazy startup. Services with a direct TCP or HTTP
- * endpoint must be running before that endpoint is published. Companion
- * services are activated with the public service that consumes them.
- */
-export const SERVICE_ACTIVATION_POLICY: Readonly<Record<ServiceName, ServiceActivationPolicy>> = {
-  postgres: { startup: "eager" },
-  postgrest: { startup: "lazy" },
-  auth: { startup: "lazy" },
-  "edge-runtime": { startup: "lazy" },
-  realtime: { startup: "eager" },
-  storage: { startup: "lazy", activates: ["imgproxy"], owns: ["imgproxy"] },
-  imgproxy: { startup: "lazy" },
-  mailpit: { startup: "eager" },
-  pgmeta: { startup: "lazy" },
-  studio: { startup: "eager", activates: ["analytics"] },
-  analytics: { startup: "lazy", activates: ["vector"], owns: ["vector"] },
-  vector: { startup: "lazy" },
-  pooler: { startup: "eager" },
-};
+import { serviceMetadata } from "./ServiceCatalog.ts";
+import type { ServiceName } from "./ServiceName.ts";
 
 export const eagerServices = (enabled: ReadonlyArray<ServiceName>): ReadonlyArray<ServiceName> =>
-  enabled.filter((service) => SERVICE_ACTIVATION_POLICY[service].startup === "eager");
+  enabled.filter((service) => serviceMetadata(service).activation.startup === "eager");
 
 export const activationTargetsForService = (
   enabledServices: ReadonlyArray<ServiceName>,
@@ -45,7 +16,7 @@ export const activationTargetsForService = (
   const targets = new Set<ServiceName>();
   const addWithCompanions = (target: ServiceName): void => {
     if (!enabled.has(target) || targets.has(target)) return;
-    for (const activated of SERVICE_ACTIVATION_POLICY[target].activates ?? []) {
+    for (const activated of serviceMetadata(target).activation.activates) {
       addWithCompanions(activated);
     }
     targets.add(target);
@@ -68,7 +39,7 @@ export const lifecycleTargetsForService = (
 
   const addWithOwnedCompanions = (target: ServiceName): void => {
     add(target);
-    for (const owned of SERVICE_ACTIVATION_POLICY[target].owns ?? []) {
+    for (const owned of serviceMetadata(target).activation.owns) {
       addWithOwnedCompanions(owned);
     }
   };
diff --git a/packages/stack/src/ServiceActivation.unit.test.ts b/packages/stack/src/ServiceActivation.unit.test.ts
index cc41dd31b7..ed0ad8a851 100644
--- a/packages/stack/src/ServiceActivation.unit.test.ts
+++ b/packages/stack/src/ServiceActivation.unit.test.ts
@@ -3,13 +3,12 @@ import {
   activationTargetsForService,
   eagerServices,
   lifecycleTargetsForService,
-  SERVICE_ACTIVATION_POLICY,
 } from "./ServiceActivation.ts";
-import { SERVICE_NAMES } from "./versions.ts";
+import { SERVICE_CATALOG, SERVICE_NAMES } from "./ServiceCatalog.ts";
 
 describe("service activation", () => {
   it("defines an access policy for every stack service", () => {
-    expect(Object.keys(SERVICE_ACTIVATION_POLICY).sort()).toEqual([...SERVICE_NAMES].sort());
+    expect(Object.keys(SERVICE_CATALOG).sort()).toEqual([...SERVICE_NAMES].sort());
   });
 
   it("starts direct endpoints eagerly", () => {
diff --git a/packages/stack/src/ServiceArtifacts.ts b/packages/stack/src/ServiceArtifacts.ts
deleted file mode 100644
index 65921365c7..0000000000
--- a/packages/stack/src/ServiceArtifacts.ts
+++ /dev/null
@@ -1,213 +0,0 @@
-import {
-  authAssetName,
-  edgeRuntimeAssetName,
-  postgresAssetName,
-  postgrestAssetName,
-  type PlatformInfo,
-} from "./Platform.ts";
-import type { ServiceName } from "./versions.ts";
-
-type ArtifactOwnership = "supabase" | "upstream";
-type ServiceRuntimeSupport = "native-preferred" | "docker-only";
-export type ArchiveFormat = "tar.gz" | "tar.xz" | "zip";
-
-export interface NativeReleaseArtifact {
-  readonly provider: string;
-  readonly assetName: string;
-  readonly archive: ArchiveFormat;
-  readonly downloadUrl: string;
-  readonly checksumUrl: string | null;
-  readonly stripComponents: boolean;
-}
-
-interface NativeReleaseSource {
-  readonly provider: string;
-  readonly resolve: (version: string, platform: PlatformInfo) => NativeReleaseArtifact | undefined;
-}
-
-interface DockerImageSource {
-  readonly ownership: ArtifactOwnership;
-  readonly repository: string;
-  readonly tagPrefix?: string;
-}
-
-export interface ServiceArtifactDefinition {
-  readonly runtimeSupport: ServiceRuntimeSupport;
-  readonly docker: DockerImageSource;
-  readonly native?: NativeReleaseSource;
-}
-
-const SUPABASE_ECR_REGISTRY = "public.ecr.aws/supabase";
-const SUPABASE_DOCKER_HUB_REGISTRY = "supabase";
-const SUPABASE_GHCR_REGISTRY = "ghcr.io/supabase";
-
-const nativeRelease = (
-  provider: string,
-  assetName: string | null,
-  archive: ArchiveFormat,
-  downloadUrl: string,
-  options?: {
-    readonly checksumUrl?: string;
-    readonly stripComponents?: boolean;
-  },
-): NativeReleaseArtifact | undefined =>
-  assetName === null
-    ? undefined
-    : {
-        provider,
-        assetName,
-        archive,
-        downloadUrl,
-        checksumUrl: options?.checksumUrl ?? null,
-        stripComponents: options?.stripComponents ?? false,
-      };
-
-const authReleaseTag = (version: string): string =>
-  version.includes("-rc.") ? `rc${version}` : `v${version}`;
-
-export const SERVICE_ARTIFACTS: Record<ServiceName, ServiceArtifactDefinition> = {
-  postgres: {
-    runtimeSupport: "native-preferred",
-    docker: { ownership: "supabase", repository: "postgres" },
-    native: {
-      provider: "github.com/supabase/postgres",
-      resolve: (version, platform) => {
-        const assetName = postgresAssetName(platform);
-        const cliVersion = `${version}-cli`;
-        const url = `https://github.com/supabase/postgres/releases/download/v${cliVersion}/supabase-postgres-v${cliVersion}-${assetName}.tar.gz`;
-        return nativeRelease("github.com/supabase/postgres", assetName, "tar.gz", url, {
-          checksumUrl: `${url}.sha256`,
-          stripComponents: true,
-        });
-      },
-    },
-  },
-  postgrest: {
-    runtimeSupport: "native-preferred",
-    docker: { ownership: "supabase", repository: "postgrest", tagPrefix: "v" },
-    native: {
-      provider: "github.com/PostgREST/postgrest",
-      resolve: (version, platform) => {
-        const assetName = postgrestAssetName(platform);
-        const archive = assetName?.startsWith("windows") === true ? "zip" : "tar.xz";
-        return nativeRelease(
-          "github.com/PostgREST/postgrest",
-          assetName,
-          archive,
-          `https://github.com/PostgREST/postgrest/releases/download/v${version}/postgrest-v${version}-${assetName}.${archive}`,
-        );
-      },
-    },
-  },
-  auth: {
-    runtimeSupport: "native-preferred",
-    docker: { ownership: "supabase", repository: "gotrue", tagPrefix: "v" },
-    native: {
-      provider: "github.com/supabase/auth",
-      resolve: (version, platform) => {
-        const assetName = authAssetName(platform);
-        return nativeRelease(
-          "github.com/supabase/auth",
-          assetName,
-          "tar.gz",
-          `https://github.com/supabase/auth/releases/download/${authReleaseTag(version)}/auth-v${version}-${assetName}.tar.gz`,
-        );
-      },
-    },
-  },
-  "edge-runtime": {
-    runtimeSupport: "docker-only",
-    docker: { ownership: "supabase", repository: "edge-runtime", tagPrefix: "v" },
-    native: {
-      provider: "github.com/supabase/edge-runtime",
-      resolve: (version, platform) => {
-        const assetName = edgeRuntimeAssetName(platform);
-        return nativeRelease(
-          "github.com/supabase/edge-runtime",
-          assetName,
-          "tar.gz",
-          `https://github.com/supabase/edge-runtime/releases/download/v${version}/edge-runtime-v${version}-${assetName}.tar.gz`,
-        );
-      },
-    },
-  },
-  realtime: {
-    runtimeSupport: "docker-only",
-    docker: { ownership: "supabase", repository: "realtime", tagPrefix: "v" },
-  },
-  storage: {
-    runtimeSupport: "docker-only",
-    docker: { ownership: "supabase", repository: "storage-api", tagPrefix: "v" },
-  },
-  imgproxy: {
-    runtimeSupport: "docker-only",
-    docker: { ownership: "upstream", repository: "darthsim/imgproxy" },
-  },
-  mailpit: {
-    runtimeSupport: "docker-only",
-    docker: { ownership: "upstream", repository: "axllent/mailpit" },
-  },
-  pgmeta: {
-    runtimeSupport: "docker-only",
-    docker: { ownership: "supabase", repository: "postgres-meta", tagPrefix: "v" },
-  },
-  studio: {
-    runtimeSupport: "docker-only",
-    docker: { ownership: "supabase", repository: "studio" },
-  },
-  analytics: {
-    runtimeSupport: "docker-only",
-    docker: { ownership: "supabase", repository: "logflare" },
-  },
-  vector: {
-    runtimeSupport: "docker-only",
-    docker: { ownership: "upstream", repository: "timberio/vector" },
-  },
-  pooler: {
-    runtimeSupport: "docker-only",
-    docker: { ownership: "supabase", repository: "supavisor" },
-  },
-};
-
-export const nativeReleaseForService = (
-  service: ServiceName,
-  version: string,
-  platform: PlatformInfo,
-): NativeReleaseArtifact | undefined =>
-  SERVICE_ARTIFACTS[service].native?.resolve(version, platform);
-
-export const isDockerOnlyService = (service: ServiceName): boolean =>
-  SERVICE_ARTIFACTS[service].runtimeSupport === "docker-only";
-
-const dockerTag = (service: ServiceName, version: string): string => {
-  const source = SERVICE_ARTIFACTS[service].docker;
-  return `${source.tagPrefix ?? ""}${version}`;
-};
-
-export const dockerImageForArtifact = (service: ServiceName, version: string): string => {
-  const source = SERVICE_ARTIFACTS[service].docker;
-  const repository =
-    source.ownership === "supabase"
-      ? `${SUPABASE_ECR_REGISTRY}/${source.repository}`
-      : source.repository;
-  return `${repository}:${dockerTag(service, version)}`;
-};
-
-export const dockerImageCandidatesForArtifact = (
-  service: ServiceName,
-  version: string,
-): ReadonlyArray<string> => {
-  const source = SERVICE_ARTIFACTS[service].docker;
-  const tag = dockerTag(service, version);
-  if (source.ownership === "upstream") {
-    return [`${source.repository}:${tag}`];
-  }
-  return [
-    `${SUPABASE_ECR_REGISTRY}/${source.repository}:${tag}`,
-    `${SUPABASE_DOCKER_HUB_REGISTRY}/${source.repository}:${tag}`,
-    `${SUPABASE_GHCR_REGISTRY}/${source.repository}:${tag}`,
-  ];
-};
-
-export const imageTagPrefixForService = (service: ServiceName): string | undefined =>
-  SERVICE_ARTIFACTS[service].docker.tagPrefix;
diff --git a/packages/stack/src/ServiceCatalog.ts b/packages/stack/src/ServiceCatalog.ts
new file mode 100644
index 0000000000..4a90c65822
--- /dev/null
+++ b/packages/stack/src/ServiceCatalog.ts
@@ -0,0 +1,337 @@
+import { Record } from "effect";
+import {
+  authAssetName,
+  edgeRuntimeAssetName,
+  postgresAssetName,
+  postgrestAssetName,
+  type PlatformInfo,
+} from "./Platform.ts";
+import type { PortField } from "./PortAllocator.ts";
+import type { ServiceName } from "./ServiceName.ts";
+
+type ArtifactOwnership = "supabase" | "upstream";
+type ServiceRuntimeSupport = "native-preferred" | "docker-only";
+export type ArchiveFormat = "tar.gz" | "tar.xz" | "zip";
+
+export interface NativeReleaseArtifact {
+  readonly provider: string;
+  readonly assetName: string;
+  readonly archive: ArchiveFormat;
+  readonly downloadUrl: string;
+  readonly checksumUrl: string | null;
+  readonly stripComponents: boolean;
+}
+
+interface NativeReleaseSource {
+  readonly provider: string;
+  readonly resolve: (version: string, platform: PlatformInfo) => NativeReleaseArtifact | undefined;
+}
+
+interface DockerImageSource {
+  readonly ownership: ArtifactOwnership;
+  readonly repository: string;
+  readonly tagPrefix?: string;
+}
+
+interface ServiceArtifactDefinition {
+  readonly docker: DockerImageSource;
+  readonly native?: NativeReleaseSource;
+}
+
+interface ServiceActivationPolicy {
+  /** Whether the public service must already be running when lazy startup completes. */
+  readonly startup: "eager" | "lazy";
+  /** Other public services required when this service is activated. */
+  readonly activates: ReadonlyArray<ServiceName>;
+  /** Private companions whose lifecycle is exclusively owned by this service. */
+  readonly owns: ReadonlyArray<ServiceName>;
+}
+
+type ServiceConfigKey =
+  | "postgres"
+  | "postgrest"
+  | "auth"
+  | "edgeRuntime"
+  | "realtime"
+  | "storage"
+  | "imgproxy"
+  | "mailpit"
+  | "pgmeta"
+  | "studio"
+  | "analytics"
+  | "vector"
+  | "pooler";
+
+export interface ServiceCatalogEntry<Name extends ServiceName> {
+  readonly name: Name;
+  readonly configKey: ServiceConfigKey;
+  readonly defaultVersion: string;
+  readonly runtimeSupport: ServiceRuntimeSupport;
+  readonly artifact: ServiceArtifactDefinition;
+  readonly activation: ServiceActivationPolicy;
+  readonly portFields: ReadonlyArray<PortField>;
+}
+
+const SUPABASE_ECR_REGISTRY = "public.ecr.aws/supabase";
+const SUPABASE_DOCKER_HUB_REGISTRY = "supabase";
+const SUPABASE_GHCR_REGISTRY = "ghcr.io/supabase";
+
+const nativeRelease = (
+  provider: string,
+  assetName: string | null,
+  archive: ArchiveFormat,
+  downloadUrl: string,
+  options?: {
+    readonly checksumUrl?: string;
+    readonly stripComponents?: boolean;
+  },
+): NativeReleaseArtifact | undefined =>
+  assetName === null
+    ? undefined
+    : {
+        provider,
+        assetName,
+        archive,
+        downloadUrl,
+        checksumUrl: options?.checksumUrl ?? null,
+        stripComponents: options?.stripComponents ?? false,
+      };
+
+const authReleaseTag = (version: string): string =>
+  version.includes("-rc.") ? `rc${version}` : `v${version}`;
+
+/**
+ * Exhaustive static identity and capability metadata for public stack services.
+ * Cross-service topology and process definitions deliberately remain in StackBuilder.
+ */
+export const SERVICE_CATALOG = {
+  postgres: {
+    name: "postgres",
+    configKey: "postgres",
+    defaultVersion: "17.6.1.158",
+    runtimeSupport: "native-preferred",
+    artifact: {
+      docker: { ownership: "supabase", repository: "postgres" },
+      native: {
+        provider: "github.com/supabase/postgres",
+        resolve: (version, platform) => {
+          const assetName = postgresAssetName(platform);
+          const cliVersion = `${version}-cli`;
+          const url = `https://github.com/supabase/postgres/releases/download/v${cliVersion}/supabase-postgres-v${cliVersion}-${assetName}.tar.gz`;
+          return nativeRelease("github.com/supabase/postgres", assetName, "tar.gz", url, {
+            checksumUrl: `${url}.sha256`,
+            stripComponents: true,
+          });
+        },
+      },
+    },
+    activation: { startup: "eager", activates: [], owns: [] },
+    portFields: ["dbPort"],
+  },
+  postgrest: {
+    name: "postgrest",
+    configKey: "postgrest",
+    defaultVersion: "14.15",
+    runtimeSupport: "native-preferred",
+    artifact: {
+      docker: { ownership: "supabase", repository: "postgrest", tagPrefix: "v" },
+      native: {
+        provider: "github.com/PostgREST/postgrest",
+        resolve: (version, platform) => {
+          const assetName = postgrestAssetName(platform);
+          const archive = assetName?.startsWith("windows") === true ? "zip" : "tar.xz";
+          return nativeRelease(
+            "github.com/PostgREST/postgrest",
+            assetName,
+            archive,
+            `https://github.com/PostgREST/postgrest/releases/download/v${version}/postgrest-v${version}-${assetName}.${archive}`,
+          );
+        },
+      },
+    },
+    activation: { startup: "lazy", activates: [], owns: [] },
+    portFields: ["postgrestPort", "postgrestAdminPort"],
+  },
+  auth: {
+    name: "auth",
+    configKey: "auth",
+    defaultVersion: "2.194.0",
+    runtimeSupport: "native-preferred",
+    artifact: {
+      docker: { ownership: "supabase", repository: "gotrue", tagPrefix: "v" },
+      native: {
+        provider: "github.com/supabase/auth",
+        resolve: (version, platform) => {
+          const assetName = authAssetName(platform);
+          return nativeRelease(
+            "github.com/supabase/auth",
+            assetName,
+            "tar.gz",
+            `https://github.com/supabase/auth/releases/download/${authReleaseTag(version)}/auth-v${version}-${assetName}.tar.gz`,
+          );
+        },
+      },
+    },
+    activation: { startup: "lazy", activates: [], owns: [] },
+    portFields: ["authPort"],
+  },
+  "edge-runtime": {
+    name: "edge-runtime",
+    configKey: "edgeRuntime",
+    defaultVersion: "1.74.2",
+    runtimeSupport: "docker-only",
+    artifact: {
+      docker: { ownership: "supabase", repository: "edge-runtime", tagPrefix: "v" },
+      native: {
+        provider: "github.com/supabase/edge-runtime",
+        resolve: (version, platform) => {
+          const assetName = edgeRuntimeAssetName(platform);
+          return nativeRelease(
+            "github.com/supabase/edge-runtime",
+            assetName,
+            "tar.gz",
+            `https://github.com/supabase/edge-runtime/releases/download/v${version}/edge-runtime-v${version}-${assetName}.tar.gz`,
+          );
+        },
+      },
+    },
+    activation: { startup: "lazy", activates: [], owns: [] },
+    portFields: ["edgeRuntimePort", "edgeRuntimeInspectorPort"],
+  },
+  realtime: {
+    name: "realtime",
+    configKey: "realtime",
+    defaultVersion: "2.120.3",
+    runtimeSupport: "docker-only",
+    artifact: { docker: { ownership: "supabase", repository: "realtime", tagPrefix: "v" } },
+    activation: { startup: "eager", activates: [], owns: [] },
+    portFields: ["realtimePort"],
+  },
+  storage: {
+    name: "storage",
+    configKey: "storage",
+    defaultVersion: "1.67.20",
+    runtimeSupport: "docker-only",
+    artifact: { docker: { ownership: "supabase", repository: "storage-api", tagPrefix: "v" } },
+    activation: { startup: "lazy", activates: ["imgproxy"], owns: ["imgproxy"] },
+    portFields: ["storagePort"],
+  },
+  imgproxy: {
+    name: "imgproxy",
+    configKey: "imgproxy",
+    defaultVersion: "v3.8.0",
+    runtimeSupport: "docker-only",
+    artifact: { docker: { ownership: "upstream", repository: "darthsim/imgproxy" } },
+    activation: { startup: "lazy", activates: [], owns: [] },
+    portFields: ["imgproxyPort"],
+  },
+  mailpit: {
+    name: "mailpit",
+    configKey: "mailpit",
+    defaultVersion: "v1.30.2",
+    runtimeSupport: "docker-only",
+    artifact: { docker: { ownership: "upstream", repository: "axllent/mailpit" } },
+    activation: { startup: "eager", activates: [], owns: [] },
+    portFields: ["mailpitPort", "mailpitSmtpPort", "mailpitPop3Port"],
+  },
+  pgmeta: {
+    name: "pgmeta",
+    configKey: "pgmeta",
+    defaultVersion: "0.96.6",
+    runtimeSupport: "docker-only",
+    artifact: {
+      docker: { ownership: "supabase", repository: "postgres-meta", tagPrefix: "v" },
+    },
+    activation: { startup: "lazy", activates: [], owns: [] },
+    portFields: ["pgmetaPort"],
+  },
+  studio: {
+    name: "studio",
+    configKey: "studio",
+    defaultVersion: "2026.07.27-sha-cbb076d",
+    runtimeSupport: "docker-only",
+    artifact: { docker: { ownership: "supabase", repository: "studio" } },
+    activation: { startup: "eager", activates: ["analytics"], owns: [] },
+    portFields: ["studioPort"],
+  },
+  analytics: {
+    name: "analytics",
+    configKey: "analytics",
+    defaultVersion: "1.47.1",
+    runtimeSupport: "docker-only",
+    artifact: { docker: { ownership: "supabase", repository: "logflare" } },
+    activation: { startup: "lazy", activates: ["vector"], owns: ["vector"] },
+    portFields: ["analyticsPort"],
+  },
+  vector: {
+    name: "vector",
+    configKey: "vector",
+    defaultVersion: "0.53.0-alpine",
+    runtimeSupport: "docker-only",
+    artifact: { docker: { ownership: "upstream", repository: "timberio/vector" } },
+    activation: { startup: "lazy", activates: [], owns: [] },
+    portFields: [],
+  },
+  pooler: {
+    name: "pooler",
+    configKey: "pooler",
+    defaultVersion: "2.9.7",
+    runtimeSupport: "docker-only",
+    artifact: { docker: { ownership: "supabase", repository: "supavisor" } },
+    activation: { startup: "eager", activates: [], owns: [] },
+    portFields: ["poolerPort", "poolerApiPort"],
+  },
+} satisfies { readonly [Name in ServiceName]: ServiceCatalogEntry<Name> };
+
+export const SERVICE_NAMES: ReadonlyArray<ServiceName> = Record.keys(SERVICE_CATALOG);
+
+export const DEFAULT_VERSIONS: Readonly<Record<ServiceName, string>> = Record.map(
+  SERVICE_CATALOG,
+  (metadata) => metadata.defaultVersion,
+);
+
+export const serviceMetadata = (service: ServiceName): ServiceCatalogEntry<ServiceName> =>
+  SERVICE_CATALOG[service];
+
+export const nativeReleaseForService = (
+  service: ServiceName,
+  version: string,
+  platform: PlatformInfo,
+): NativeReleaseArtifact | undefined =>
+  serviceMetadata(service).artifact.native?.resolve(version, platform);
+
+export const isDockerOnlyService = (service: ServiceName): boolean =>
+  SERVICE_CATALOG[service].runtimeSupport === "docker-only";
+
+const dockerTag = (service: ServiceName, version: string): string => {
+  const source = serviceMetadata(service).artifact.docker;
+  return `${source.tagPrefix ?? ""}${version}`;
+};
+
+export const dockerImageForArtifact = (service: ServiceName, version: string): string => {
+  const source = SERVICE_CATALOG[service].artifact.docker;
+  const repository =
+    source.ownership === "supabase"
+      ? `${SUPABASE_ECR_REGISTRY}/${source.repository}`
+      : source.repository;
+  return `${repository}:${dockerTag(service, version)}`;
+};
+
+export const dockerImageCandidatesForArtifact = (
+  service: ServiceName,
+  version: string,
+): ReadonlyArray<string> => {
+  const source = SERVICE_CATALOG[service].artifact.docker;
+  const tag = dockerTag(service, version);
+  if (source.ownership === "upstream") {
+    return [`${source.repository}:${tag}`];
+  }
+  return [
+    `${SUPABASE_ECR_REGISTRY}/${source.repository}:${tag}`,
+    `${SUPABASE_DOCKER_HUB_REGISTRY}/${source.repository}:${tag}`,
+    `${SUPABASE_GHCR_REGISTRY}/${source.repository}:${tag}`,
+  ];
+};
+
+export const imageTagPrefixForService = (service: ServiceName): string | undefined =>
+  serviceMetadata(service).artifact.docker.tagPrefix;
diff --git a/packages/stack/src/ServiceCatalog.unit.test.ts b/packages/stack/src/ServiceCatalog.unit.test.ts
new file mode 100644
index 0000000000..d00f5a177b
--- /dev/null
+++ b/packages/stack/src/ServiceCatalog.unit.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_VERSIONS, SERVICE_CATALOG, SERVICE_NAMES } from "./ServiceCatalog.ts";
+
+describe("ServiceCatalog", () => {
+  it("derives exhaustive iteration and defaults from catalog entries", () => {
+    expect(SERVICE_NAMES).toEqual(Object.keys(SERVICE_CATALOG));
+    expect(Object.keys(DEFAULT_VERSIONS)).toEqual(SERVICE_NAMES);
+
+    for (const service of SERVICE_NAMES) {
+      expect(SERVICE_CATALOG[service].name).toBe(service);
+      expect(DEFAULT_VERSIONS[service]).toBe(SERVICE_CATALOG[service].defaultVersion);
+    }
+  });
+
+  it("references only catalog services in activation relationships", () => {
+    const knownServices = new Set(SERVICE_NAMES);
+    for (const service of SERVICE_NAMES) {
+      const { activates, owns } = SERVICE_CATALOG[service].activation;
+      expect([...activates, ...owns].every((related) => knownServices.has(related))).toBe(true);
+    }
+  });
+});
diff --git a/packages/stack/src/ServiceName.ts b/packages/stack/src/ServiceName.ts
new file mode 100644
index 0000000000..f9524cacd2
--- /dev/null
+++ b/packages/stack/src/ServiceName.ts
@@ -0,0 +1,15 @@
+/** Public Supabase services represented in a local stack. */
+export type ServiceName =
+  | "postgres"
+  | "postgrest"
+  | "auth"
+  | "edge-runtime"
+  | "realtime"
+  | "storage"
+  | "imgproxy"
+  | "mailpit"
+  | "pgmeta"
+  | "studio"
+  | "analytics"
+  | "vector"
+  | "pooler";
diff --git a/packages/stack/src/ServicePorts.ts b/packages/stack/src/ServicePorts.ts
index 27a0b125c0..cb61925149 100644
--- a/packages/stack/src/ServicePorts.ts
+++ b/packages/stack/src/ServicePorts.ts
@@ -1,31 +1,16 @@
 import type { PortField } from "./PortAllocator.ts";
-import { enabledServicesForConfig, type ResolvedStackConfig } from "./StackBuilder.ts";
-import { SERVICE_NAMES, type ServiceName } from "./versions.ts";
+import { enabledServicesForConfig } from "./StackBuilder.ts";
+import { SERVICE_CATALOG, SERVICE_NAMES } from "./ServiceCatalog.ts";
+import type { ResolvedStackConfig } from "./StackConfig.ts";
 
 export const allocatedPortFieldsForConfig = (
   config: ResolvedStackConfig,
 ): ReadonlyArray<PortField> => [
   "apiPort",
-  ...enabledServicesForConfig(config).flatMap((service) => SERVICE_PORT_FIELDS[service]),
+  ...enabledServicesForConfig(config).flatMap((service) => SERVICE_CATALOG[service].portFields),
 ];
 
-const SERVICE_PORT_FIELDS = {
-  postgres: ["dbPort"],
-  postgrest: ["postgrestPort", "postgrestAdminPort"],
-  auth: ["authPort"],
-  "edge-runtime": ["edgeRuntimePort", "edgeRuntimeInspectorPort"],
-  realtime: ["realtimePort"],
-  storage: ["storagePort"],
-  imgproxy: ["imgproxyPort"],
-  mailpit: ["mailpitPort", "mailpitSmtpPort", "mailpitPop3Port"],
-  pgmeta: ["pgmetaPort"],
-  studio: ["studioPort"],
-  analytics: ["analyticsPort"],
-  vector: [],
-  pooler: ["poolerPort", "poolerApiPort"],
-} as const satisfies Readonly<Record<ServiceName, ReadonlyArray<PortField>>>;
-
 export const portFieldsForService = (name: string): ReadonlyArray<PortField> => {
   const service = SERVICE_NAMES.find((candidate) => candidate === name);
-  return service === undefined ? [] : SERVICE_PORT_FIELDS[service];
+  return service === undefined ? [] : SERVICE_CATALOG[service].portFields;
 };
diff --git a/packages/stack/src/Stack.ts b/packages/stack/src/Stack.ts
index 06ab6abd44..dbe2ce70e0 100644
--- a/packages/stack/src/Stack.ts
+++ b/packages/stack/src/Stack.ts
@@ -4,7 +4,7 @@ import { Effect, Layer, Schema, Context, Stream } from "effect";
 import { StackBuildError } from "./errors.ts";
 import type { FunctionsConfig } from "./functions.ts";
 import { StackLifecycleCoordinator } from "./StackLifecycleCoordinator.ts";
-import type { EdgeRuntimeConfig, ResolvedStackConfig } from "./StackBuilder.ts";
+import type { EdgeRuntimeConfig, ResolvedStackConfig } from "./StackConfig.ts";
 import { StackServiceState } from "./StackServiceState.ts";
 
 export interface StackInfo {
diff --git a/packages/stack/src/Stack.unit.test.ts b/packages/stack/src/Stack.unit.test.ts
index 5f40c98cee..1ee19f6389 100644
--- a/packages/stack/src/Stack.unit.test.ts
+++ b/packages/stack/src/Stack.unit.test.ts
@@ -11,7 +11,7 @@ import { StackLifecycleCoordinator } from "./StackLifecycleCoordinator.ts";
 import { StackMetadataPersistence } from "./StackMetadataPersistence.ts";
 import { StackPreparation } from "./StackPreparation.ts";
 import { StackBuilder } from "./StackBuilder.ts";
-import type { ResolvedStackConfig } from "./StackBuilder.ts";
+import { DEFAULT_STACK_READINESS_POLICY, type ResolvedStackConfig } from "./StackConfig.ts";
 import { DEFAULT_VERSIONS } from "./versions.ts";
 
 const testJwtSecret = "super-secret-jwt-token-with-at-least-32-characters-long";
@@ -44,6 +44,7 @@ const defaultConfig: ResolvedStackConfig = {
   projectDir: "/tmp/supabase-project",
   mode: "native",
   startupMode: "eager",
+  readiness: DEFAULT_STACK_READINESS_POLICY,
   jwtSecret: testJwtSecret,
   ports: defaultPorts,
   apiPort: 54321,
diff --git a/packages/stack/src/StackBuilder.ts b/packages/stack/src/StackBuilder.ts
index 31ebab0db5..318ad63989 100644
--- a/packages/stack/src/StackBuilder.ts
+++ b/packages/stack/src/StackBuilder.ts
@@ -3,7 +3,6 @@ import type { ResolvedGraph, ServiceDef } from "@supabase/process-compose";
 import { Effect, Layer, Context } from "effect";
 import type { CleanupTargets } from "./CleanupTargets.ts";
 import { StackBuildError } from "./errors.ts";
-import type { FunctionsConfig, ResolvedFunctionsConfig } from "./functions.ts";
 import { generateJwks } from "./JwtGenerator.ts";
 import {
   detectPlatform,
@@ -11,7 +10,6 @@ import {
   dockerNetworkArgs,
   dockerPortMapArgs,
 } from "./Platform.ts";
-import type { ServiceResolution } from "./resolve.ts";
 import { analyticsDockerRuntimeNetwork, makeAnalyticsServiceDocker } from "./services/analytics.ts";
 import { makeAuthServiceDocker, makeAuthServiceNative } from "./services/auth.ts";
 import {
@@ -34,271 +32,12 @@ import {
 } from "./services/storage.ts";
 import { makeStudioServiceDocker } from "./services/studio.ts";
 import { makeVectorServiceDocker } from "./services/vector.ts";
-import type { PreparedStackArtifacts } from "./StackPreparation.ts";
+import type { PreparedStackArtifacts, ServiceResolution } from "./StackPreparation.ts";
 import type { StackServiceProjectionCatalog } from "./StackStateProjection.ts";
-import type { AllocatedPorts } from "./PortAllocator.ts";
-import type { ServiceName, VersionManifest } from "./versions.ts";
-
-export interface PostgresConfig {
-  readonly port?: number;
-  readonly dataDir?: string;
-  readonly version?: string;
-  /**
-   * When true (default), the bundled initial schema GRANTs that expose new tables, views,
-   * sequences, and functions in `public` to the Data API roles (`anon`, `authenticated`,
-   * `service_role`) are kept in place. When false, those default privileges are revoked so the
-   * local stack matches the new cloud default and requires explicit GRANTs to surface entities
-   * through the Data API.
-   */
-  readonly autoExposeNewTables?: boolean;
-}
-
-export interface PostgrestConfig {
-  readonly schemas?: ReadonlyArray<string>;
-  readonly extraSearchPath?: ReadonlyArray<string>;
-  readonly maxRows?: number;
-  readonly version?: string;
-}
-
-export interface AuthConfig {
-  readonly port?: number;
-  readonly siteUrl?: string;
-  readonly jwtExpiry?: number;
-  readonly externalUrl?: string;
-  readonly version?: string;
-}
-
-export interface RealtimeConfig {
-  readonly port?: number;
-  readonly version?: string;
-  readonly tenantId?: string;
-  readonly encryptionKey?: string;
-  readonly secretKeyBase?: string;
-  readonly maxHeaderLength?: number;
-}
-
-export interface EdgeRuntimeConfig {
-  readonly enabled?: boolean;
-  readonly port?: number;
-  readonly inspectorPort?: number;
-  readonly policy?: "oneshot" | "per_worker";
-  readonly version?: string;
-  readonly env?: Readonly<Record<string, string>>;
-}
-
-export interface StorageConfig {
-  readonly port?: number;
-  readonly dataDir?: string;
-  readonly fileSizeLimit?: string;
-  readonly s3ProtocolEnabled?: boolean;
-  readonly version?: string;
-}
-
-export interface ImgproxyConfig {
-  readonly port?: number;
-  readonly version?: string;
-}
-
-export interface MailpitConfig {
-  readonly port?: number;
-  readonly smtpPort?: number;
-  readonly pop3Port?: number;
-  readonly version?: string;
-  readonly adminEmail?: string;
-  readonly senderName?: string;
-}
-
-export interface PgmetaConfig {
-  readonly port?: number;
-  readonly version?: string;
-}
-
-export interface StudioConfig {
-  readonly port?: number;
-  readonly apiUrl?: string;
-  readonly version?: string;
-}
-
-export interface AnalyticsConfig {
-  readonly port?: number;
-  readonly version?: string;
-  readonly backend?: "postgres" | "bigquery";
-  readonly apiKey?: string;
-}
-
-export interface VectorConfig {
-  readonly version?: string;
-}
-
-export interface PoolerConfig {
-  readonly port?: number;
-  readonly apiPort?: number;
-  readonly mode?: "transaction" | "session";
-  readonly version?: string;
-  readonly tenantId?: string;
-  readonly encryptionKey?: string;
-  readonly secretKeyBase?: string;
-  readonly defaultPoolSize?: number;
-  readonly maxClientConn?: number;
-}
-
-export interface StackConfig {
-  readonly cacheRoot?: string;
-  readonly stackRoot?: string;
-  readonly runtimeRoot?: string;
-  readonly projectDir?: string;
-  readonly mode?: "native" | "auto" | "docker";
-  /** Start all services immediately, or defer proxied services until first use. */
-  readonly startupMode?: "eager" | "lazy";
-  readonly jwtSecret?: string;
-  readonly port?: number;
-  readonly publishableKey?: string;
-  readonly secretKey?: string;
-  readonly functions?: FunctionsConfig | false;
-  readonly postgres?: PostgresConfig;
-  readonly postgrest?: PostgrestConfig | false;
-  readonly auth?: AuthConfig | false;
-  readonly edgeRuntime?: EdgeRuntimeConfig | false;
-  readonly realtime?: RealtimeConfig | false;
-  readonly storage?: StorageConfig | false;
-  readonly imgproxy?: ImgproxyConfig | false;
-  readonly mailpit?: MailpitConfig | false;
-  readonly pgmeta?: PgmetaConfig | false;
-  readonly studio?: StudioConfig | false;
-  readonly analytics?: AnalyticsConfig | false;
-  readonly vector?: VectorConfig | false;
-  readonly pooler?: PoolerConfig | false;
-}
-
-export interface ResolvedPostgresConfig {
-  readonly port: number;
-  readonly dataDir: string;
-  readonly version: string;
-  readonly autoExposeNewTables: boolean;
-}
-
-export interface ResolvedPostgrestConfig {
-  readonly port: number;
-  readonly adminPort: number;
-  readonly schemas: ReadonlyArray<string>;
-  readonly extraSearchPath: ReadonlyArray<string>;
-  readonly maxRows: number;
-  readonly version: string;
-}
-
-export interface ResolvedAuthConfig {
-  readonly port: number;
-  readonly siteUrl: string;
-  readonly jwtExpiry: number;
-  readonly externalUrl: string;
-  readonly version: string;
-}
-
-export interface ResolvedRealtimeConfig {
-  readonly port: number;
-  readonly version: string;
-  readonly tenantId: string;
-  readonly encryptionKey: string;
-  readonly secretKeyBase: string;
-  readonly maxHeaderLength: number;
-}
-
-export interface ResolvedEdgeRuntimeConfig {
-  readonly enabled: boolean;
-  readonly port: number;
-  readonly inspectorPort: number;
-  readonly policy: "oneshot" | "per_worker";
-  readonly version: string;
-  readonly env: Readonly<Record<string, string>>;
-}
-
-export interface ResolvedStorageConfig {
-  readonly port: number;
-  readonly version: string;
-  readonly dataDir: string;
-  readonly fileSizeLimit: string;
-  readonly s3ProtocolEnabled: boolean;
-}
-
-export interface ResolvedImgproxyConfig {
-  readonly port: number;
-  readonly version: string;
-}
-
-export interface ResolvedMailpitConfig {
-  readonly port: number;
-  readonly smtpPort: number;
-  readonly pop3Port: number;
-  readonly version: string;
-  readonly adminEmail: string;
-  readonly senderName: string;
-}
-
-export interface ResolvedPgmetaConfig {
-  readonly port: number;
-  readonly version: string;
-}
-
-export interface ResolvedStudioConfig {
-  readonly port: number;
-  readonly version: string;
-  readonly apiUrl: string;
-}
-
-export interface ResolvedAnalyticsConfig {
-  readonly port: number;
-  readonly version: string;
-  readonly backend: "postgres" | "bigquery";
-  readonly apiKey: string;
-}
-
-export interface ResolvedVectorConfig {
-  readonly version: string;
-}
-
-export interface ResolvedPoolerConfig {
-  readonly port: number;
-  readonly apiPort: number;
-  readonly mode: "transaction" | "session";
-  readonly version: string;
-  readonly tenantId: string;
-  readonly encryptionKey: string;
-  readonly secretKeyBase: string;
-  readonly defaultPoolSize: number;
-  readonly maxClientConn: number;
-}
-
-export interface ResolvedStackConfig {
-  readonly cacheRoot: string;
-  readonly stackRoot: string;
-  readonly runtimeRoot: string;
-  readonly projectDir: string;
-  readonly mode: "native" | "auto" | "docker";
-  readonly startupMode: "eager" | "lazy";
-  readonly jwtSecret: string;
-  readonly ports: AllocatedPorts;
-  readonly apiPort: number;
-  readonly dbPort: number;
-  readonly publishableKey: string;
-  readonly secretKey: string;
-  readonly functions: ResolvedFunctionsConfig | false;
-  readonly autoManagedPaths: ReadonlyArray<string>;
-  readonly anonJwt: string;
-  readonly serviceRoleJwt: string;
-  readonly postgres: ResolvedPostgresConfig;
-  readonly postgrest: ResolvedPostgrestConfig | false;
-  readonly auth: ResolvedAuthConfig | false;
-  readonly edgeRuntime: ResolvedEdgeRuntimeConfig | false;
-  readonly realtime: ResolvedRealtimeConfig | false;
-  readonly storage: ResolvedStorageConfig | false;
-  readonly imgproxy: ResolvedImgproxyConfig | false;
-  readonly mailpit: ResolvedMailpitConfig | false;
-  readonly pgmeta: ResolvedPgmetaConfig | false;
-  readonly studio: ResolvedStudioConfig | false;
-  readonly analytics: ResolvedAnalyticsConfig | false;
-  readonly vector: ResolvedVectorConfig | false;
-  readonly pooler: ResolvedPoolerConfig | false;
-}
+import { SERVICE_NAMES, serviceMetadata } from "./ServiceCatalog.ts";
+import type { ServiceName } from "./ServiceName.ts";
+import type { ResolvedStackConfig } from "./StackConfig.ts";
+import type { VersionManifest } from "./versions.ts";
 
 export interface BuildResult {
   readonly graph: ResolvedGraph;
@@ -306,18 +45,9 @@ export interface BuildResult {
   readonly serviceProjection: StackServiceProjectionCatalog;
 }
 
-const dockerOnlyServices = [
-  "edge-runtime",
-  "realtime",
-  "storage",
-  "imgproxy",
-  "mailpit",
-  "pgmeta",
-  "studio",
-  "analytics",
-  "vector",
-  "pooler",
-] as const;
+const dockerOnlyServices = SERVICE_NAMES.filter(
+  (service) => serviceMetadata(service).runtimeSupport === "docker-only",
+);
 
 const dependsOnPostgres = (hasPostgresInit: boolean): ReadonlyArray<ServiceDependency> =>
   hasPostgresInit
@@ -358,10 +88,8 @@ const hasAutoManagedPath = (config: ResolvedStackConfig, path: string) =>
       path.startsWith(`${managedPath}\\`),
   );
 
-const resolvedConfigForService = (
-  config: ResolvedStackConfig,
-  service: Exclude<ServiceName, "postgres">,
-) => (service === "edge-runtime" ? config.edgeRuntime : config[service]);
+const resolvedConfigForService = (config: ResolvedStackConfig, service: ServiceName) =>
+  config[serviceMetadata(service).configKey];
 
 export const validateResolvedConfig = (
   config: ResolvedStackConfig,
@@ -405,67 +133,22 @@ export const validateResolvedConfig = (
     }
   });
 
-export const enabledServicesForConfig = (
-  config: ResolvedStackConfig,
-): ReadonlyArray<ServiceName> => {
-  const services: ServiceName[] = ["postgres"];
+export const enabledServicesForConfig = (config: ResolvedStackConfig): ReadonlyArray<ServiceName> =>
+  SERVICE_NAMES.filter(
+    (service) => service === "postgres" || resolvedConfigForService(config, service) !== false,
+  );
 
-  if (config.postgrest !== false) {
-    services.push("postgrest");
-  }
-  if (config.auth !== false) {
-    services.push("auth");
-  }
-  if (config.edgeRuntime !== false) {
-    services.push("edge-runtime");
-  }
-  if (config.realtime !== false) {
-    services.push("realtime");
-  }
-  if (config.storage !== false) {
-    services.push("storage");
-  }
-  if (config.imgproxy !== false) {
-    services.push("imgproxy");
-  }
-  if (config.mailpit !== false) {
-    services.push("mailpit");
-  }
-  if (config.pgmeta !== false) {
-    services.push("pgmeta");
-  }
-  if (config.studio !== false) {
-    services.push("studio");
-  }
-  if (config.analytics !== false) {
-    services.push("analytics");
-  }
-  if (config.vector !== false) {
-    services.push("vector");
-  }
-  if (config.pooler !== false) {
-    services.push("pooler");
+export const versionsForConfig = (config: ResolvedStackConfig): Partial<VersionManifest> => {
+  const versions: Partial<Record<ServiceName, string>> = {};
+  for (const service of enabledServicesForConfig(config)) {
+    const serviceConfig = resolvedConfigForService(config, service);
+    if (serviceConfig !== false) {
+      versions[service] = serviceConfig.version;
+    }
   }
-
-  return services;
+  return versions;
 };
 
-export const versionsForConfig = (config: ResolvedStackConfig): Partial<VersionManifest> => ({
-  postgres: config.postgres.version,
-  ...(config.postgrest === false ? {} : { postgrest: config.postgrest.version }),
-  ...(config.auth === false ? {} : { auth: config.auth.version }),
-  ...(config.edgeRuntime === false ? {} : { "edge-runtime": config.edgeRuntime.version }),
-  ...(config.realtime === false ? {} : { realtime: config.realtime.version }),
-  ...(config.storage === false ? {} : { storage: config.storage.version }),
-  ...(config.imgproxy === false ? {} : { imgproxy: config.imgproxy.version }),
-  ...(config.mailpit === false ? {} : { mailpit: config.mailpit.version }),
-  ...(config.pgmeta === false ? {} : { pgmeta: config.pgmeta.version }),
-  ...(config.studio === false ? {} : { studio: config.studio.version }),
-  ...(config.analytics === false ? {} : { analytics: config.analytics.version }),
-  ...(config.vector === false ? {} : { vector: config.vector.version }),
-  ...(config.pooler === false ? {} : { pooler: config.pooler.version }),
-});
-
 const requirePreparedResolution = (
   prepared: PreparedStackArtifacts,
   service: ServiceName,
diff --git a/packages/stack/src/StackBuilder.unit.test.ts b/packages/stack/src/StackBuilder.unit.test.ts
index f8c7f40765..2fb442725c 100644
--- a/packages/stack/src/StackBuilder.unit.test.ts
+++ b/packages/stack/src/StackBuilder.unit.test.ts
@@ -5,7 +5,7 @@ import { mockBinaryResolver } from "../tests/helpers/mocks.ts";
 import { defaultPublishableKey, defaultSecretKey, generateJwt } from "./JwtGenerator.ts";
 import { StackBuilder } from "./StackBuilder.ts";
 import type { BuildResult } from "./StackBuilder.ts";
-import type { ResolvedStackConfig } from "./StackBuilder.ts";
+import { DEFAULT_STACK_READINESS_POLICY, type ResolvedStackConfig } from "./StackConfig.ts";
 import { enabledServicesForConfig, versionsForConfig } from "./StackBuilder.ts";
 import { nativePostgresNeedsDockerAccess } from "./StackBuilder.ts";
 import type { AllocatedPorts } from "./PortAllocator.ts";
@@ -43,6 +43,7 @@ const baseConfig: ResolvedStackConfig = {
   projectDir: "/tmp/supabase-project",
   mode: "auto",
   startupMode: "eager",
+  readiness: DEFAULT_STACK_READINESS_POLICY,
   jwtSecret: testJwtSecret,
   ports: basePorts,
   apiPort: 3000,
diff --git a/packages/stack/src/StackConfig.ts b/packages/stack/src/StackConfig.ts
new file mode 100644
index 0000000000..cbf6552fc8
--- /dev/null
+++ b/packages/stack/src/StackConfig.ts
@@ -0,0 +1,295 @@
+import type { FunctionsConfig, ResolvedFunctionsConfig } from "./functions.ts";
+import type { AllocatedPorts } from "./PortAllocator.ts";
+
+type StackMode = "native" | "auto" | "docker";
+type StackStartupMode = "eager" | "lazy";
+
+export type ReadinessPolicy =
+  | { readonly mode: "finite"; readonly timeoutMs: number }
+  | { readonly mode: "infinite" };
+
+export type ReadyOptions = { readonly mode: "inherit" } | ReadinessPolicy;
+
+/** Standalone stacks wait at most two minutes unless a caller or launch Adapter chooses otherwise. */
+export const DEFAULT_STACK_READINESS_POLICY: ReadinessPolicy = {
+  mode: "finite",
+  timeoutMs: 120_000,
+};
+
+/** Resolve readiness with per-call policy taking precedence over stack policy and package default. */
+export const resolveReadinessPolicy = (input: {
+  readonly readyOptions?: ReadyOptions;
+  readonly stackPolicy?: ReadinessPolicy;
+}): ReadinessPolicy =>
+  input.readyOptions === undefined || input.readyOptions.mode === "inherit"
+    ? (input.stackPolicy ?? DEFAULT_STACK_READINESS_POLICY)
+    : input.readyOptions;
+
+export interface PostgresConfig {
+  readonly port?: number;
+  readonly dataDir?: string;
+  readonly version?: string;
+  /**
+   * When true (default), the bundled initial schema GRANTs that expose new tables, views,
+   * sequences, and functions in `public` to the Data API roles (`anon`, `authenticated`,
+   * `service_role`) are kept in place. When false, those default privileges are revoked so the
+   * local stack matches the new cloud default and requires explicit GRANTs to surface entities
+   * through the Data API.
+   */
+  readonly autoExposeNewTables?: boolean;
+}
+
+export interface PostgrestConfig {
+  readonly schemas?: ReadonlyArray<string>;
+  readonly extraSearchPath?: ReadonlyArray<string>;
+  readonly maxRows?: number;
+  readonly version?: string;
+}
+
+export interface AuthConfig {
+  readonly port?: number;
+  readonly siteUrl?: string;
+  readonly jwtExpiry?: number;
+  readonly externalUrl?: string;
+  readonly version?: string;
+}
+
+export interface RealtimeConfig {
+  readonly port?: number;
+  readonly version?: string;
+  readonly tenantId?: string;
+  readonly encryptionKey?: string;
+  readonly secretKeyBase?: string;
+  readonly maxHeaderLength?: number;
+}
+
+export interface EdgeRuntimeConfig {
+  readonly enabled?: boolean;
+  readonly port?: number;
+  readonly inspectorPort?: number;
+  readonly policy?: "oneshot" | "per_worker";
+  readonly version?: string;
+  readonly env?: Readonly<Record<string, string>>;
+}
+
+export interface StorageConfig {
+  readonly port?: number;
+  readonly dataDir?: string;
+  readonly fileSizeLimit?: string;
+  readonly s3ProtocolEnabled?: boolean;
+  readonly version?: string;
+}
+
+export interface ImgproxyConfig {
+  readonly port?: number;
+  readonly version?: string;
+}
+
+export interface MailpitConfig {
+  readonly port?: number;
+  readonly smtpPort?: number;
+  readonly pop3Port?: number;
+  readonly version?: string;
+  readonly adminEmail?: string;
+  readonly senderName?: string;
+}
+
+export interface PgmetaConfig {
+  readonly port?: number;
+  readonly version?: string;
+}
+
+export interface StudioConfig {
+  readonly port?: number;
+  readonly apiUrl?: string;
+  readonly version?: string;
+}
+
+export interface AnalyticsConfig {
+  readonly port?: number;
+  readonly version?: string;
+  readonly backend?: "postgres" | "bigquery";
+  readonly apiKey?: string;
+}
+
+export interface VectorConfig {
+  readonly version?: string;
+}
+
+export interface PoolerConfig {
+  readonly port?: number;
+  readonly apiPort?: number;
+  readonly mode?: "transaction" | "session";
+  readonly version?: string;
+  readonly tenantId?: string;
+  readonly encryptionKey?: string;
+  readonly secretKeyBase?: string;
+  readonly defaultPoolSize?: number;
+  readonly maxClientConn?: number;
+}
+
+export interface StackConfig {
+  readonly cacheRoot?: string;
+  readonly stackRoot?: string;
+  readonly runtimeRoot?: string;
+  readonly projectDir?: string;
+  readonly mode?: StackMode;
+  /** Start all services immediately, or defer proxied services until first use. */
+  readonly startupMode?: StackStartupMode;
+  /** Stack-wide readiness policy. Per-call ReadyOptions take precedence. */
+  readonly readiness?: ReadinessPolicy;
+  readonly jwtSecret?: string;
+  readonly port?: number;
+  readonly publishableKey?: string;
+  readonly secretKey?: string;
+  readonly functions?: FunctionsConfig | false;
+  readonly postgres?: PostgresConfig;
+  readonly postgrest?: PostgrestConfig | false;
+  readonly auth?: AuthConfig | false;
+  readonly edgeRuntime?: EdgeRuntimeConfig | false;
+  readonly realtime?: RealtimeConfig | false;
+  readonly storage?: StorageConfig | false;
+  readonly imgproxy?: ImgproxyConfig | false;
+  readonly mailpit?: MailpitConfig | false;
+  readonly pgmeta?: PgmetaConfig | false;
+  readonly studio?: StudioConfig | false;
+  readonly analytics?: AnalyticsConfig | false;
+  readonly vector?: VectorConfig | false;
+  readonly pooler?: PoolerConfig | false;
+}
+
+export interface ResolvedPostgresConfig {
+  readonly port: number;
+  readonly dataDir: string;
+  readonly version: string;
+  readonly autoExposeNewTables: boolean;
+}
+
+export interface ResolvedPostgrestConfig {
+  readonly port: number;
+  readonly adminPort: number;
+  readonly schemas: ReadonlyArray<string>;
+  readonly extraSearchPath: ReadonlyArray<string>;
+  readonly maxRows: number;
+  readonly version: string;
+}
+
+export interface ResolvedAuthConfig {
+  readonly port: number;
+  readonly siteUrl: string;
+  readonly jwtExpiry: number;
+  readonly externalUrl: string;
+  readonly version: string;
+}
+
+export interface ResolvedRealtimeConfig {
+  readonly port: number;
+  readonly version: string;
+  readonly tenantId: string;
+  readonly encryptionKey: string;
+  readonly secretKeyBase: string;
+  readonly maxHeaderLength: number;
+}
+
+export interface ResolvedEdgeRuntimeConfig {
+  readonly enabled: boolean;
+  readonly port: number;
+  readonly inspectorPort: number;
+  readonly policy: "oneshot" | "per_worker";
+  readonly version: string;
+  readonly env: Readonly<Record<string, string>>;
+}
+
+export interface ResolvedStorageConfig {
+  readonly port: number;
+  readonly version: string;
+  readonly dataDir: string;
+  readonly fileSizeLimit: string;
+  readonly s3ProtocolEnabled: boolean;
+}
+
+export interface ResolvedImgproxyConfig {
+  readonly port: number;
+  readonly version: string;
+}
+
+export interface ResolvedMailpitConfig {
+  readonly port: number;
+  readonly smtpPort: number;
+  readonly pop3Port: number;
+  readonly version: string;
+  readonly adminEmail: string;
+  readonly senderName: string;
+}
+
+export interface ResolvedPgmetaConfig {
+  readonly port: number;
+  readonly version: string;
+}
+
+export interface ResolvedStudioConfig {
+  readonly port: number;
+  readonly version: string;
+  readonly apiUrl: string;
+}
+
+export interface ResolvedAnalyticsConfig {
+  readonly port: number;
+  readonly version: string;
+  readonly backend: "postgres" | "bigquery";
+  readonly apiKey: string;
+}
+
+export interface ResolvedVectorConfig {
+  readonly version: string;
+}
+
+export interface ResolvedPoolerConfig {
+  readonly port: number;
+  readonly apiPort: number;
+  readonly mode: "transaction" | "session";
+  readonly version: string;
+  readonly tenantId: string;
+  readonly encryptionKey: string;
+  readonly secretKeyBase: string;
+  readonly defaultPoolSize: number;
+  readonly maxClientConn: number;
+}
+
+export interface ResolvedStackConfig {
+  readonly cacheRoot: string;
+  readonly stackRoot: string;
+  readonly runtimeRoot: string;
+  readonly projectDir: string;
+  readonly mode: StackMode;
+  readonly startupMode: StackStartupMode;
+  readonly readiness: ReadinessPolicy;
+  readonly jwtSecret: string;
+  readonly ports: AllocatedPorts;
+  readonly apiPort: number;
+  readonly dbPort: number;
+  readonly publishableKey: string;
+  readonly secretKey: string;
+  readonly functions: ResolvedFunctionsConfig | false;
+  readonly autoManagedPaths: ReadonlyArray<string>;
+  readonly anonJwt: string;
+  readonly serviceRoleJwt: string;
+  readonly postgres: ResolvedPostgresConfig;
+  readonly postgrest: ResolvedPostgrestConfig | false;
+  readonly auth: ResolvedAuthConfig | false;
+  readonly edgeRuntime: ResolvedEdgeRuntimeConfig | false;
+  readonly realtime: ResolvedRealtimeConfig | false;
+  readonly storage: ResolvedStorageConfig | false;
+  readonly imgproxy: ResolvedImgproxyConfig | false;
+  readonly mailpit: ResolvedMailpitConfig | false;
+  readonly pgmeta: ResolvedPgmetaConfig | false;
+  readonly studio: ResolvedStudioConfig | false;
+  readonly analytics: ResolvedAnalyticsConfig | false;
+  readonly vector: ResolvedVectorConfig | false;
+  readonly pooler: ResolvedPoolerConfig | false;
+}
+
+export interface ResolvedDaemonConfig extends ResolvedStackConfig {
+  readonly name: string;
+  readonly projectDir: string;
+}
diff --git a/packages/stack/src/StackConfig.unit.test.ts b/packages/stack/src/StackConfig.unit.test.ts
new file mode 100644
index 0000000000..9c3d3b0a84
--- /dev/null
+++ b/packages/stack/src/StackConfig.unit.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_STACK_READINESS_POLICY,
+  resolveReadinessPolicy,
+  type ReadinessPolicy,
+} from "./StackConfig.ts";
+
+const finite = (timeoutMs: number): ReadinessPolicy => ({ mode: "finite", timeoutMs });
+
+describe("resolveReadinessPolicy", () => {
+  it("uses the finite package default when neither level chooses a policy", () => {
+    expect(resolveReadinessPolicy({})).toEqual(DEFAULT_STACK_READINESS_POLICY);
+  });
+
+  it("inherits finite and infinite stack policies", () => {
+    expect(
+      resolveReadinessPolicy({
+        readyOptions: { mode: "inherit" },
+        stackPolicy: finite(120_000),
+      }),
+    ).toEqual(finite(120_000));
+    expect(
+      resolveReadinessPolicy({
+        readyOptions: { mode: "inherit" },
+        stackPolicy: { mode: "infinite" },
+      }),
+    ).toEqual({ mode: "infinite" });
+  });
+
+  it("allows shorter and longer per-call finite policies", () => {
+    expect(
+      resolveReadinessPolicy({
+        readyOptions: finite(5_000),
+        stackPolicy: finite(120_000),
+      }),
+    ).toEqual(finite(5_000));
+    expect(
+      resolveReadinessPolicy({
+        readyOptions: finite(300_000),
+        stackPolicy: finite(120_000),
+      }),
+    ).toEqual(finite(300_000));
+  });
+
+  it("allows either level to opt into or override infinite waiting", () => {
+    expect(
+      resolveReadinessPolicy({
+        readyOptions: { mode: "infinite" },
+        stackPolicy: finite(120_000),
+      }),
+    ).toEqual({ mode: "infinite" });
+    expect(
+      resolveReadinessPolicy({
+        readyOptions: finite(30_000),
+        stackPolicy: { mode: "infinite" },
+      }),
+    ).toEqual(finite(30_000));
+  });
+});
diff --git a/packages/stack/src/StackConfigResolver.ts b/packages/stack/src/StackConfigResolver.ts
new file mode 100644
index 0000000000..88cd888abf
--- /dev/null
+++ b/packages/stack/src/StackConfigResolver.ts
@@ -0,0 +1,613 @@
+import { mkdtempSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Effect, Schema } from "effect";
+import { toStackError } from "./errors.ts";
+import {
+  defaultJwtSecret,
+  defaultPublishableKey,
+  defaultSecretKey,
+  generateJwt,
+} from "./JwtGenerator.ts";
+import {
+  DEFAULT_MANAGED_STACK_NAME,
+  defaultCacheRoot,
+  defaultManagedProjectsRoot,
+  defaultManagedRuntimeRoot,
+  defaultManagedStackRoot,
+  shortTempPrefixRoot,
+} from "./paths.ts";
+import {
+  allocatePorts,
+  DEFAULT_PORTS,
+  PORT_FIELDS,
+  type AllocatedPorts,
+  type PortAllocationError,
+  type PortInput,
+  type PortSelectionOptions,
+} from "./PortAllocator.ts";
+import { StackMetadataSchema } from "./StackMetadata.ts";
+import { resolveReadinessPolicy } from "./StackConfig.ts";
+import type {
+  AnalyticsConfig,
+  AuthConfig,
+  EdgeRuntimeConfig,
+  ImgproxyConfig,
+  MailpitConfig,
+  PgmetaConfig,
+  PoolerConfig,
+  PostgrestConfig,
+  RealtimeConfig,
+  ResolvedAnalyticsConfig,
+  ResolvedAuthConfig,
+  ResolvedDaemonConfig,
+  ResolvedEdgeRuntimeConfig,
+  ResolvedImgproxyConfig,
+  ResolvedMailpitConfig,
+  ResolvedPgmetaConfig,
+  ResolvedPoolerConfig,
+  ResolvedPostgrestConfig,
+  ResolvedRealtimeConfig,
+  ResolvedStackConfig,
+  ResolvedStorageConfig,
+  ResolvedStudioConfig,
+  ResolvedVectorConfig,
+  StackConfig,
+  StorageConfig,
+  StudioConfig,
+  VectorConfig,
+} from "./StackConfig.ts";
+import { DEFAULT_VERSIONS } from "./ServiceCatalog.ts";
+
+const StackMetadataFileSchema = Schema.fromJsonString(StackMetadataSchema);
+const decodeStackMetadataFile = Schema.decodeUnknownSync(StackMetadataFileSchema);
+
+export function defaultManagedStackName(_cwd: string): string {
+  return DEFAULT_MANAGED_STACK_NAME;
+}
+
+export interface ResolveConfigOptions {
+  readonly stackRoot?: string;
+  readonly runtimeRoot?: string;
+  readonly preferredPorts?: Partial<AllocatedPorts>;
+  readonly reservedPorts?: ReadonlySet<number>;
+  readonly portAllocator?: (
+    input: PortInput,
+    options: PortSelectionOptions,
+  ) => Effect.Effect<AllocatedPorts, PortAllocationError>;
+}
+
+interface ResolvedRoots {
+  readonly cacheRoot: string;
+  readonly stackRoot: string;
+  readonly runtimeRoot: string;
+  readonly autoManagedPaths: ReadonlyArray<string>;
+}
+
+const makeTempRoot = (prefix: string) => mkdtempSync(join(shortTempPrefixRoot(), prefix));
+
+const resolveRoots = (config: StackConfig, opts: ResolveConfigOptions): ResolvedRoots => {
+  const cacheRoot = config.cacheRoot ?? defaultCacheRoot();
+  const autoManagedPaths: string[] = [];
+
+  const stackRoot =
+    opts.stackRoot ??
+    config.stackRoot ??
+    (() => {
+      const dir = makeTempRoot("sb-stack-");
+      autoManagedPaths.push(dir);
+      return dir;
+    })();
+
+  const runtimeRoot =
+    opts.runtimeRoot ??
+    config.runtimeRoot ??
+    (() => {
+      const dir = makeTempRoot("sb-run-");
+      autoManagedPaths.push(dir);
+      return dir;
+    })();
+
+  return {
+    cacheRoot,
+    stackRoot,
+    runtimeRoot,
+    autoManagedPaths,
+  };
+};
+
+const resolveDataDir = (
+  explicitDir: string | undefined,
+  stackRoot: string,
+  suffix: string,
+): string => explicitDir ?? join(stackRoot, "data", suffix);
+
+async function readStackMetadataFile(filePath: string) {
+  try {
+    const content = await readFile(filePath, "utf8");
+    return decodeStackMetadataFile(content);
+  } catch {
+    return undefined;
+  }
+}
+
+async function readOwnedPorts(stackRoot: string): Promise<AllocatedPorts | undefined> {
+  const metadata = await readStackMetadataFile(join(stackRoot, "stack.json"));
+  return metadata?.ports;
+}
+
+async function readReservedPorts(
+  projectsRoot: string,
+  currentStackRoot: string,
+): Promise<ReadonlySet<number>> {
+  const reserved = new Set<number>();
+
+  let projectEntries: Array<{ isDirectory(): boolean; name: string }>;
+  try {
+    projectEntries = await readdir(projectsRoot, { withFileTypes: true });
+  } catch {
+    return reserved;
+  }
+
+  await Promise.all(
+    projectEntries.map(async (projectEntry) => {
+      if (!projectEntry.isDirectory()) {
+        return;
+      }
+
+      const stacksRoot = join(projectsRoot, projectEntry.name, "stacks");
+      let stackEntries: Array<{ isDirectory(): boolean; name: string }>;
+      try {
+        stackEntries = await readdir(stacksRoot, { withFileTypes: true });
+      } catch {
+        return;
+      }
+
+      await Promise.all(
+        stackEntries.map(async (stackEntry) => {
+          if (!stackEntry.isDirectory()) {
+            return;
+          }
+
+          const stackRoot = join(stacksRoot, stackEntry.name);
+          if (stackRoot === currentStackRoot) {
+            return;
+          }
+
+          const ports = (await readStackMetadataFile(join(stackRoot, "stack.json")))?.ports;
+          if (ports === undefined) {
+            return;
+          }
+
+          for (const field of PORT_FIELDS) {
+            reserved.add(ports[field]);
+          }
+        }),
+      );
+    }),
+  );
+
+  return reserved;
+}
+
+async function readReservedPortsInStacksRoot(
+  stacksRoot: string,
+  currentStackRoot: string,
+): Promise<ReadonlySet<number>> {
+  const reserved = new Set<number>();
+
+  let stackEntries: Array<{ isDirectory(): boolean; name: string }>;
+  try {
+    stackEntries = await readdir(stacksRoot, { withFileTypes: true });
+  } catch {
+    return reserved;
+  }
+
+  await Promise.all(
+    stackEntries.map(async (stackEntry) => {
+      if (!stackEntry.isDirectory()) {
+        return;
+      }
+
+      const stackRoot = join(stacksRoot, stackEntry.name);
+      if (stackRoot === currentStackRoot) {
+        return;
+      }
+
+      const ports = (await readStackMetadataFile(join(stackRoot, "stack.json")))?.ports;
+      if (ports === undefined) {
+        return;
+      }
+
+      for (const field of PORT_FIELDS) {
+        reserved.add(ports[field]);
+      }
+    }),
+  );
+
+  return reserved;
+}
+
+function resolvePostgrestConfig(
+  input: PostgrestConfig | undefined,
+  raw: PostgrestConfig | false | undefined,
+  ports: AllocatedPorts,
+): ResolvedPostgrestConfig | false {
+  if (raw === false) return false;
+  const cfg = input ?? {};
+  return {
+    port: ports.postgrestPort,
+    adminPort: ports.postgrestAdminPort,
+    schemas: cfg.schemas ?? ["public", "graphql_public"],
+    extraSearchPath: cfg.extraSearchPath ?? ["public", "extensions"],
+    maxRows: cfg.maxRows ?? 1000,
+    version: cfg.version ?? DEFAULT_VERSIONS.postgrest,
+  };
+}
+
+function resolveAuthConfig(
+  input: AuthConfig | undefined,
+  raw: AuthConfig | false | undefined,
+  ports: AllocatedPorts,
+  apiPort: number,
+): ResolvedAuthConfig | false {
+  if (raw === false) return false;
+  const cfg = input ?? {};
+  return {
+    port: ports.authPort,
+    siteUrl: cfg.siteUrl ?? "http://localhost:3000",
+    jwtExpiry: cfg.jwtExpiry ?? 3600,
+    externalUrl: cfg.externalUrl ?? `http://127.0.0.1:${apiPort}`,
+    version: cfg.version ?? DEFAULT_VERSIONS.auth,
+  };
+}
+
+function resolveRealtimeConfig(
+  input: RealtimeConfig | undefined,
+  raw: RealtimeConfig | false | undefined,
+  ports: AllocatedPorts,
+): ResolvedRealtimeConfig | false {
+  if (raw === false) return false;
+  const cfg = input ?? {};
+  return {
+    port: ports.realtimePort,
+    version: cfg.version ?? DEFAULT_VERSIONS.realtime,
+    tenantId: cfg.tenantId ?? "realtime-dev",
+    encryptionKey: cfg.encryptionKey ?? "supabaserealtime",
+    secretKeyBase:
+      cfg.secretKeyBase ?? "EAx3IQ/wRG1v47ZD4NE4/9RzBI8Jmil3x0yhcW4V2NHBP6c2iPIzwjofi2Ep4HIG",
+    maxHeaderLength: cfg.maxHeaderLength ?? 4096,
+  };
+}
+
+function resolveEdgeRuntimeConfig(
+  input: EdgeRuntimeConfig | undefined,
+  raw: EdgeRuntimeConfig | false | undefined,
+  ports: AllocatedPorts,
+): ResolvedEdgeRuntimeConfig | false {
+  if (raw === false || raw?.enabled === false) return false;
+  const cfg = input ?? {};
+  return {
+    enabled: cfg.enabled ?? true,
+    port: ports.edgeRuntimePort,
+    inspectorPort: ports.edgeRuntimeInspectorPort,
+    policy: cfg.policy ?? "per_worker",
+    version: cfg.version ?? DEFAULT_VERSIONS["edge-runtime"],
+    env: cfg.env ?? {},
+  };
+}
+
+function resolveFunctionsConfig(config: StackConfig) {
+  if (config.functions === false) return false;
+  return {
+    envFile: config.functions?.envFile,
+    noVerifyJwt: config.functions?.noVerifyJwt ?? false,
+  };
+}
+
+function resolveStorageConfig(
+  input: StorageConfig | undefined,
+  raw: StorageConfig | false | undefined,
+  ports: AllocatedPorts,
+  opts: ResolveConfigOptions,
+): ResolvedStorageConfig | false {
+  if (raw === false) return false;
+  const cfg = input ?? {};
+  return {
+    port: ports.storagePort,
+    version: cfg.version ?? DEFAULT_VERSIONS.storage,
+    dataDir: resolveDataDir(cfg.dataDir, opts.stackRoot!, "storage"),
+    fileSizeLimit: cfg.fileSizeLimit ?? "50MiB",
+    s3ProtocolEnabled: cfg.s3ProtocolEnabled ?? true,
+  };
+}
+
+function resolveImgproxyConfig(
+  input: ImgproxyConfig | undefined,
+  raw: ImgproxyConfig | false | undefined,
+  ports: AllocatedPorts,
+): ResolvedImgproxyConfig | false {
+  if (raw === false) return false;
+  const cfg = input ?? {};
+  return {
+    port: ports.imgproxyPort,
+    version: cfg.version ?? DEFAULT_VERSIONS.imgproxy,
+  };
+}
+
+function resolveMailpitConfig(
+  input: MailpitConfig | undefined,
+  raw: MailpitConfig | false | undefined,
+  ports: AllocatedPorts,
+): ResolvedMailpitConfig | false {
+  if (raw === false) return false;
+  const cfg = input ?? {};
+  return {
+    port: ports.mailpitPort,
+    smtpPort: ports.mailpitSmtpPort,
+    pop3Port: ports.mailpitPop3Port,
+    version: cfg.version ?? DEFAULT_VERSIONS.mailpit,
+    adminEmail: cfg.adminEmail ?? "admin@email.com",
+    senderName: cfg.senderName ?? "Admin",
+  };
+}
+
+function resolvePgmetaConfig(
+  input: PgmetaConfig | undefined,
+  raw: PgmetaConfig | false | undefined,
+  ports: AllocatedPorts,
+): ResolvedPgmetaConfig | false {
+  if (raw === false) return false;
+  const cfg = input ?? {};
+  return {
+    port: ports.pgmetaPort,
+    version: cfg.version ?? DEFAULT_VERSIONS.pgmeta,
+  };
+}
+
+function resolveStudioConfig(
+  input: StudioConfig | undefined,
+  raw: StudioConfig | false | undefined,
+  ports: AllocatedPorts,
+  apiPort: number,
+): ResolvedStudioConfig | false {
+  if (raw === false) return false;
+  const cfg = input ?? {};
+  return {
+    port: ports.studioPort,
+    version: cfg.version ?? DEFAULT_VERSIONS.studio,
+    apiUrl: cfg.apiUrl ?? `http://127.0.0.1:${apiPort}`,
+  };
+}
+
+function resolveAnalyticsConfig(
+  input: AnalyticsConfig | undefined,
+  raw: AnalyticsConfig | false | undefined,
+  ports: AllocatedPorts,
+): ResolvedAnalyticsConfig | false {
+  if (raw === false) return false;
+  const cfg = input ?? {};
+  return {
+    port: ports.analyticsPort,
+    version: cfg.version ?? DEFAULT_VERSIONS.analytics,
+    backend: cfg.backend ?? "postgres",
+    apiKey: cfg.apiKey ?? "api-key",
+  };
+}
+
+function resolveVectorConfig(
+  input: VectorConfig | undefined,
+  raw: VectorConfig | false | undefined,
+): ResolvedVectorConfig | false {
+  if (raw === false) return false;
+  const cfg = input ?? {};
+  return {
+    version: cfg.version ?? DEFAULT_VERSIONS.vector,
+  };
+}
+
+function resolvePoolerConfig(
+  input: PoolerConfig | undefined,
+  raw: PoolerConfig | false | undefined,
+  ports: AllocatedPorts,
+): ResolvedPoolerConfig | false {
+  if (raw === false) return false;
+  const cfg = input ?? {};
+  return {
+    port: ports.poolerPort,
+    apiPort: ports.poolerApiPort,
+    mode: cfg.mode ?? "transaction",
+    version: cfg.version ?? DEFAULT_VERSIONS.pooler,
+    tenantId: cfg.tenantId ?? "pooler-dev",
+    encryptionKey: cfg.encryptionKey ?? "12345678901234567890123456789032",
+    secretKeyBase:
+      cfg.secretKeyBase ?? "EAx3IQ/wRG1v47ZD4NE4/9RzBI8Jmil3x0yhcW4V2NHBP6c2iPIzwjofi2Ep4HIG",
+    defaultPoolSize: cfg.defaultPoolSize ?? 20,
+    maxClientConn: cfg.maxClientConn ?? 100,
+  };
+}
+
+export async function resolveConfig(
+  input?: StackConfig,
+  opts: ResolveConfigOptions = {},
+): Promise<ResolvedStackConfig> {
+  const config = input ?? {};
+  const projectDir = config.projectDir ?? process.cwd();
+  const resolvedMode = config.mode ?? "auto";
+  const roots = resolveRoots(config, opts);
+  const postgresInput = config.postgres ?? {};
+  const postgrestInput = config.postgrest !== false ? (config.postgrest ?? undefined) : undefined;
+  const authInput = config.auth !== false ? (config.auth ?? undefined) : undefined;
+  const edgeRuntimeEnabled =
+    !(resolvedMode === "native" && config.edgeRuntime === undefined) &&
+    config.edgeRuntime !== false &&
+    (config.edgeRuntime?.enabled ?? true) !== false;
+  const realtimeEnabled = config.realtime !== undefined && config.realtime !== false;
+  const storageEnabled = config.storage !== undefined && config.storage !== false;
+  const imgproxyEnabled = config.imgproxy !== undefined && config.imgproxy !== false;
+  const mailpitEnabled = config.mailpit !== undefined && config.mailpit !== false;
+  const pgmetaEnabled = config.pgmeta !== undefined && config.pgmeta !== false;
+  const studioEnabled = config.studio !== undefined && config.studio !== false;
+  const analyticsEnabled = config.analytics !== undefined && config.analytics !== false;
+  const vectorEnabled = config.vector !== undefined && config.vector !== false;
+  const poolerEnabled = config.pooler !== undefined && config.pooler !== false;
+  const edgeRuntimeInput = edgeRuntimeEnabled ? (config.edgeRuntime ?? undefined) : undefined;
+  const realtimeInput = realtimeEnabled ? (config.realtime ?? undefined) : undefined;
+  const storageInput = storageEnabled ? (config.storage ?? undefined) : undefined;
+  const imgproxyInput = imgproxyEnabled ? (config.imgproxy ?? undefined) : undefined;
+  const mailpitInput = mailpitEnabled ? (config.mailpit ?? undefined) : undefined;
+  const pgmetaInput = pgmetaEnabled ? (config.pgmeta ?? undefined) : undefined;
+  const studioInput = studioEnabled ? (config.studio ?? undefined) : undefined;
+  const analyticsInput = analyticsEnabled ? (config.analytics ?? undefined) : undefined;
+  const vectorInput = vectorEnabled ? (config.vector ?? undefined) : undefined;
+  const poolerInput = poolerEnabled ? (config.pooler ?? undefined) : undefined;
+
+  const postgresDataDir = resolveDataDir(postgresInput.dataDir, roots.stackRoot, "postgres");
+
+  const ports = await Effect.runPromise(
+    (opts.portAllocator ?? allocatePorts)(
+      {
+        apiPort: config.port,
+        dbPort: postgresInput.port,
+        authPort: authInput?.port,
+        postgrestPort: undefined,
+        postgrestAdminPort: undefined,
+        edgeRuntimePort: edgeRuntimeInput?.port,
+        edgeRuntimeInspectorPort: edgeRuntimeInput?.inspectorPort,
+        realtimePort: realtimeInput?.port,
+        storagePort: storageInput?.port,
+        imgproxyPort: imgproxyInput?.port,
+        mailpitPort: mailpitInput?.port,
+        mailpitSmtpPort: mailpitInput?.smtpPort,
+        mailpitPop3Port: mailpitInput?.pop3Port,
+        pgmetaPort: pgmetaInput?.port,
+        studioPort: studioInput?.port,
+        analyticsPort: analyticsInput?.port,
+        poolerPort: poolerInput?.port,
+        poolerApiPort: poolerInput?.apiPort,
+      },
+      {
+        preferred: opts.preferredPorts,
+        reserved: opts.reservedPorts,
+      },
+    ),
+  ).catch((error: unknown) => {
+    throw toStackError(error);
+  });
+
+  const jwtSecret = config.jwtSecret ?? defaultJwtSecret;
+  const anonJwt = generateJwt(jwtSecret, "anon");
+  const serviceRoleJwt = generateJwt(jwtSecret, "service_role");
+
+  return {
+    cacheRoot: roots.cacheRoot,
+    stackRoot: roots.stackRoot,
+    runtimeRoot: roots.runtimeRoot,
+    projectDir,
+    mode: resolvedMode,
+    startupMode: config.startupMode ?? "eager",
+    readiness: resolveReadinessPolicy({ stackPolicy: config.readiness }),
+    jwtSecret,
+    ports,
+    apiPort: ports.apiPort,
+    dbPort: ports.dbPort,
+    publishableKey: config.publishableKey ?? defaultPublishableKey,
+    secretKey: config.secretKey ?? defaultSecretKey,
+    functions: resolveFunctionsConfig(config),
+    autoManagedPaths: roots.autoManagedPaths,
+    anonJwt,
+    serviceRoleJwt,
+    postgres: {
+      port: ports.dbPort,
+      dataDir: postgresDataDir,
+      version: postgresInput.version ?? DEFAULT_VERSIONS.postgres,
+      autoExposeNewTables: postgresInput.autoExposeNewTables ?? true,
+    },
+    postgrest: resolvePostgrestConfig(postgrestInput, config.postgrest, ports),
+    auth: resolveAuthConfig(authInput, config.auth, ports, ports.apiPort),
+    edgeRuntime: edgeRuntimeEnabled
+      ? resolveEdgeRuntimeConfig(edgeRuntimeInput, config.edgeRuntime, ports)
+      : false,
+    realtime: realtimeEnabled
+      ? resolveRealtimeConfig(realtimeInput, config.realtime, ports)
+      : false,
+    storage: storageEnabled
+      ? resolveStorageConfig(storageInput, config.storage, ports, {
+          ...opts,
+          stackRoot: roots.stackRoot,
+        })
+      : false,
+    imgproxy: imgproxyEnabled
+      ? resolveImgproxyConfig(imgproxyInput, config.imgproxy, ports)
+      : false,
+    mailpit: mailpitEnabled ? resolveMailpitConfig(mailpitInput, config.mailpit, ports) : false,
+    pgmeta: pgmetaEnabled ? resolvePgmetaConfig(pgmetaInput, config.pgmeta, ports) : false,
+    studio: studioEnabled
+      ? resolveStudioConfig(studioInput, config.studio, ports, ports.apiPort)
+      : false,
+    analytics: analyticsEnabled
+      ? resolveAnalyticsConfig(analyticsInput, config.analytics, ports)
+      : false,
+    vector: vectorEnabled ? resolveVectorConfig(vectorInput, config.vector) : false,
+    pooler: poolerEnabled ? resolvePoolerConfig(poolerInput, config.pooler, ports) : false,
+  };
+}
+
+export type DaemonConfigInput = StackConfig & {
+  readonly cwd: string;
+  readonly name?: string;
+  readonly projectDir?: string;
+  readonly projectStateRoot?: string;
+};
+
+export async function resolveDaemonConfig(
+  input: DaemonConfigInput,
+  opts: Pick<ResolveConfigOptions, "portAllocator"> = {},
+): Promise<ResolvedDaemonConfig> {
+  const { cwd, name, projectDir, projectStateRoot, ...stackConfig } = input;
+  if (stackConfig.stackRoot !== undefined || stackConfig.runtimeRoot !== undefined) {
+    throw new Error("Managed daemon stacks derive stackRoot and runtimeRoot automatically");
+  }
+  const effectiveProjectDir = projectDir ?? cwd;
+  const resolvedName = name ?? defaultManagedStackName(effectiveProjectDir);
+  const cacheRoot = stackConfig.cacheRoot ?? defaultCacheRoot();
+  const stackRoot =
+    projectStateRoot !== undefined
+      ? join(projectStateRoot, "stacks", resolvedName)
+      : defaultManagedStackRoot(cacheRoot, effectiveProjectDir, resolvedName);
+  const runtimeRoot = defaultManagedRuntimeRoot(stackRoot);
+  const savedPorts = await readOwnedPorts(stackRoot);
+  const reservedPortSets = await Promise.all([
+    readReservedPorts(defaultManagedProjectsRoot(cacheRoot), stackRoot),
+    projectStateRoot === undefined
+      ? Promise.resolve<ReadonlySet<number>>(new Set())
+      : readReservedPortsInStacksRoot(join(projectStateRoot, "stacks"), stackRoot),
+  ]);
+  const reservedPorts = new Set<number>();
+  for (const ports of reservedPortSets) {
+    for (const port of ports) {
+      reservedPorts.add(port);
+    }
+  }
+  const resolved = await resolveConfig(
+    {
+      ...stackConfig,
+      cacheRoot,
+      stackRoot,
+      runtimeRoot,
+      projectDir: effectiveProjectDir,
+    },
+    {
+      stackRoot,
+      runtimeRoot,
+      preferredPorts: savedPorts ?? DEFAULT_PORTS,
+      reservedPorts,
+      portAllocator: opts.portAllocator,
+    },
+  );
+  return {
+    ...resolved,
+    name: resolvedName,
+    projectDir: effectiveProjectDir,
+  };
+}
diff --git a/packages/stack/src/StackLifecycleCoordinator.ts b/packages/stack/src/StackLifecycleCoordinator.ts
index a9eeb0196d..fe5f82bc42 100644
--- a/packages/stack/src/StackLifecycleCoordinator.ts
+++ b/packages/stack/src/StackLifecycleCoordinator.ts
@@ -34,8 +34,8 @@ import {
   StackBuilder,
   validateResolvedConfig,
   versionsForConfig,
-  type ResolvedStackConfig,
 } from "./StackBuilder.ts";
+import type { ResolvedStackConfig } from "./StackConfig.ts";
 import { changedProjectedStates, projectStackStates } from "./StackStateProjection.ts";
 import { StackServiceState } from "./StackServiceState.ts";
 import type { EdgeRuntimeReloadConfig, StackInfo } from "./Stack.ts";
diff --git a/packages/stack/src/StackMetadata.ts b/packages/stack/src/StackMetadata.ts
index 1704993751..aa4a3fb0d9 100644
--- a/packages/stack/src/StackMetadata.ts
+++ b/packages/stack/src/StackMetadata.ts
@@ -1,7 +1,8 @@
 import { Schema } from "effect";
 import { CleanupTargetsSchema, type CleanupTargets } from "./CleanupTargets.ts";
 import { AllocatedPortsSchema, type AllocatedPorts } from "./PortAllocator.ts";
-import type { ResolvedStackConfig } from "./StackBuilder.ts";
+import { serviceMetadata } from "./ServiceCatalog.ts";
+import type { ResolvedStackConfig } from "./StackConfig.ts";
 import { SERVICE_NAMES, type ServiceName, type VersionManifest } from "./versions.ts";
 
 const VersionManifestSchema = Schema.Struct({
@@ -76,15 +77,10 @@ export const STACK_METADATA_SCHEMA_VERSION = 1;
 export function runningServiceVersionsForConfig(
   config: ResolvedStackConfig,
 ): PartialVersionManifest {
-  const versions: Partial<Record<ServiceName, string>> = {
-    postgres: config.postgres.version,
-  };
+  const versions: Partial<Record<ServiceName, string>> = {};
 
   for (const service of SERVICE_NAMES) {
-    if (service === "postgres") {
-      continue;
-    }
-    const serviceConfig = service === "edge-runtime" ? config.edgeRuntime : config[service];
+    const serviceConfig = config[serviceMetadata(service).configKey];
     if (serviceConfig !== false) {
       versions[service] = serviceConfig.version;
     }
diff --git a/packages/stack/src/StackPreparation.ts b/packages/stack/src/StackPreparation.ts
index a363d40a78..c0feb4924d 100644
--- a/packages/stack/src/StackPreparation.ts
+++ b/packages/stack/src/StackPreparation.ts
@@ -3,8 +3,7 @@ import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import { BinaryResolver } from "./BinaryResolver.ts";
 import type { ChecksumMismatchError } from "./errors.ts";
 import { DockerPullError } from "./errors.ts";
-import type { ServiceResolution } from "./resolve.ts";
-import { isDockerOnlyService } from "./ServiceArtifacts.ts";
+import { isDockerOnlyService } from "./ServiceCatalog.ts";
 import {
   DEFAULT_VERSIONS,
   SERVICE_NAMES,
@@ -17,6 +16,10 @@ export interface PreparedStackArtifacts {
   readonly resolutions: Partial<Record<ServiceName, ServiceResolution>>;
 }
 
+export type ServiceResolution =
+  | { readonly type: "binary"; readonly path: string }
+  | { readonly type: "docker"; readonly image: string };
+
 export interface StackPreparationInput {
   readonly versions?: Partial<VersionManifest>;
   readonly services?: ReadonlyArray<ServiceName>;
@@ -133,9 +136,11 @@ export const prepareAssetsWithDependencies = (
       concurrency: "unbounded",
     });
 
-    const artifacts = {
-      resolutions: Object.fromEntries(results) as PreparedStackArtifacts["resolutions"],
-    } satisfies PreparedStackArtifacts;
+    const resolutions: Partial<Record<ServiceName, ServiceResolution>> = {};
+    for (const [service, resolution] of results) {
+      resolutions[service] = resolution;
+    }
+    const artifacts = { resolutions } satisfies PreparedStackArtifacts;
     yield* publishEvent?.(new PreparationCompleted({ artifacts })) ?? Effect.void;
     return artifacts;
   });
diff --git a/packages/stack/src/bun.ts b/packages/stack/src/bun.ts
index 2642e1b6c6..ebc92eb69c 100644
--- a/packages/stack/src/bun.ts
+++ b/packages/stack/src/bun.ts
@@ -16,7 +16,7 @@ import {
 } from "./prefetch.ts";
 import { defaultCacheRoot } from "./paths.ts";
 import { StackPreparation } from "./StackPreparation.ts";
-import type { StackConfig } from "./StackBuilder.ts";
+import type { StackConfig } from "./StackConfig.ts";
 import { UnixHttpClient, UnixHttpClientError } from "./UnixHttpClient.ts";
 
 interface BunUnixRequestInit extends RequestInit {
diff --git a/packages/stack/src/cleanup.ts b/packages/stack/src/cleanup.ts
index 59ee0d2cae..7e43ecb6c6 100644
--- a/packages/stack/src/cleanup.ts
+++ b/packages/stack/src/cleanup.ts
@@ -2,7 +2,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, rmSync } from "node:fs";
 import { Duration, Effect } from "effect";
 import type { CleanupTargets } from "./CleanupTargets.ts";
-import type { ResolvedStackConfig } from "./StackBuilder.ts";
+import type { ResolvedStackConfig } from "./StackConfig.ts";
 
 /**
  * Force-remove Docker containers by name. Best-effort safety net —
diff --git a/packages/stack/src/createStack.ts b/packages/stack/src/createStack.ts
index f0b22c2f6d..9f0559a4fc 100644
--- a/packages/stack/src/createStack.ts
+++ b/packages/stack/src/createStack.ts
@@ -1,8 +1,5 @@
 import type { LogEntry } from "@supabase/process-compose";
-import { readdir, readFile } from "node:fs/promises";
-import { mkdtempSync } from "node:fs";
-import { join } from "node:path";
-import { Duration, Effect, type Layer, ManagedRuntime, Schema, Stream } from "effect";
+import { Duration, Effect, type Layer, ManagedRuntime, Stream } from "effect";
 import { FileSystem, Path } from "effect";
 import { HttpServer } from "effect/unstable/http";
 import { ChildProcessSpawner } from "effect/unstable/process";
@@ -10,76 +7,17 @@ import { cleanupAutoManagedPaths, dockerForceRemove } from "./cleanup.ts";
 import type { CleanupTargets } from "./CleanupTargets.ts";
 import { toStackError } from "./errors.ts";
 import type { FunctionsConfig } from "./functions.ts";
-import {
-  defaultJwtSecret,
-  defaultPublishableKey,
-  defaultSecretKey,
-  generateJwt,
-} from "./JwtGenerator.ts";
-import {
-  daemonLayer,
-  foregroundLayer,
-  type DaemonConfig,
-  type DaemonStartError,
-} from "./layers.ts";
-import {
-  DEFAULT_MANAGED_STACK_NAME,
-  defaultCacheRoot,
-  defaultManagedProjectsRoot,
-  defaultManagedRuntimeRoot,
-  defaultManagedStackRoot,
-  shortTempPrefixRoot,
-} from "./paths.ts";
-import {
-  allocatePorts,
-  DEFAULT_PORTS,
-  PORT_FIELDS,
-  reservePorts,
-  type AllocatedPorts,
-  type PortInput,
-  type PortAllocationError,
-  type PortLease,
-  type PortSelectionOptions,
-} from "./PortAllocator.ts";
+import { daemonLayer, foregroundLayer, type DaemonStartError } from "./layers.ts";
+import { PORT_FIELDS, reservePorts, type PortLease } from "./PortAllocator.ts";
 import { allocatedPortFieldsForConfig } from "./ServicePorts.ts";
-import { StackMetadataSchema } from "./StackMetadata.ts";
-import { InvalidStackStateError, StackAlreadyRunningError } from "./StateManager.ts";
 import { Stack } from "./Stack.ts";
 import type { EdgeRuntimeReloadConfig } from "./Stack.ts";
+import type { ReadyOptions, ResolvedStackConfig, StackConfig } from "./StackConfig.ts";
+import { resolveReadinessPolicy } from "./StackConfig.ts";
+import { resolveConfig } from "./StackConfigResolver.ts";
 import type { StackServiceState } from "./StackServiceState.ts";
+import { InvalidStackStateError, StackAlreadyRunningError } from "./StateManager.ts";
 import { UnixHttpClient } from "./UnixHttpClient.ts";
-import type {
-  AnalyticsConfig,
-  AuthConfig,
-  EdgeRuntimeConfig,
-  ImgproxyConfig,
-  MailpitConfig,
-  PgmetaConfig,
-  PoolerConfig,
-  PostgrestConfig,
-  RealtimeConfig,
-  ResolvedAnalyticsConfig,
-  ResolvedAuthConfig,
-  ResolvedEdgeRuntimeConfig,
-  ResolvedImgproxyConfig,
-  ResolvedMailpitConfig,
-  ResolvedPgmetaConfig,
-  ResolvedPoolerConfig,
-  ResolvedPostgrestConfig,
-  ResolvedRealtimeConfig,
-  ResolvedStackConfig,
-  ResolvedStorageConfig,
-  ResolvedStudioConfig,
-  ResolvedVectorConfig,
-  StackConfig,
-  StorageConfig,
-  StudioConfig,
-  VectorConfig,
-} from "./StackBuilder.ts";
-import { DEFAULT_VERSIONS } from "./versions.ts";
-
-const StackMetadataFileSchema = Schema.fromJsonString(StackMetadataSchema);
-const decodeStackMetadataFile = Schema.decodeUnknownSync(StackMetadataFileSchema);
 
 export type PlatformServices =
   | FileSystem.FileSystem
@@ -96,14 +34,6 @@ export interface PlatformFactoryOptions {
 
 export type PlatformFactory = (options: PlatformFactoryOptions) => PlatformLayer;
 
-export interface ReadyOptions {
-  readonly timeout?: number;
-}
-
-export function defaultManagedStackName(_cwd: string): string {
-  return DEFAULT_MANAGED_STACK_NAME;
-}
-
 export interface StackHandle extends AsyncDisposable {
   readonly url: string;
   readonly dbUrl: string;
@@ -127,551 +57,6 @@ export interface StackHandle extends AsyncDisposable {
   logHistory(name: string, limit?: number): Promise<ReadonlyArray<LogEntry>>;
 }
 
-interface ResolveConfigOptions {
-  readonly stackRoot?: string;
-  readonly runtimeRoot?: string;
-  readonly preferredPorts?: Partial<AllocatedPorts>;
-  readonly reservedPorts?: ReadonlySet<number>;
-  readonly portAllocator?: (
-    input: PortInput,
-    options: PortSelectionOptions,
-  ) => Effect.Effect<AllocatedPorts, PortAllocationError>;
-}
-
-interface ResolvedRoots {
-  readonly cacheRoot: string;
-  readonly stackRoot: string;
-  readonly runtimeRoot: string;
-  readonly autoManagedPaths: ReadonlyArray<string>;
-}
-
-const makeTempRoot = (prefix: string) => mkdtempSync(join(shortTempPrefixRoot(), prefix));
-
-const resolveRoots = (config: StackConfig, opts: ResolveConfigOptions): ResolvedRoots => {
-  const cacheRoot = config.cacheRoot ?? defaultCacheRoot();
-  const autoManagedPaths: string[] = [];
-
-  const stackRoot =
-    opts.stackRoot ??
-    config.stackRoot ??
-    (() => {
-      const dir = makeTempRoot("sb-stack-");
-      autoManagedPaths.push(dir);
-      return dir;
-    })();
-
-  const runtimeRoot =
-    opts.runtimeRoot ??
-    config.runtimeRoot ??
-    (() => {
-      const dir = makeTempRoot("sb-run-");
-      autoManagedPaths.push(dir);
-      return dir;
-    })();
-
-  return {
-    cacheRoot,
-    stackRoot,
-    runtimeRoot,
-    autoManagedPaths,
-  };
-};
-
-const resolveDataDir = (
-  explicitDir: string | undefined,
-  stackRoot: string,
-  suffix: string,
-): string => explicitDir ?? join(stackRoot, "data", suffix);
-
-async function readStackMetadataFile(filePath: string) {
-  try {
-    const content = await readFile(filePath, "utf8");
-    return decodeStackMetadataFile(content);
-  } catch {
-    return undefined;
-  }
-}
-
-async function readOwnedPorts(stackRoot: string): Promise<AllocatedPorts | undefined> {
-  const metadata = await readStackMetadataFile(join(stackRoot, "stack.json"));
-  return metadata?.ports;
-}
-
-async function readReservedPorts(
-  projectsRoot: string,
-  currentStackRoot: string,
-): Promise<ReadonlySet<number>> {
-  const reserved = new Set<number>();
-
-  let projectEntries: Array<{ isDirectory(): boolean; name: string }>;
-  try {
-    projectEntries = await readdir(projectsRoot, { withFileTypes: true });
-  } catch {
-    return reserved;
-  }
-
-  await Promise.all(
-    projectEntries.map(async (projectEntry) => {
-      if (!projectEntry.isDirectory()) {
-        return;
-      }
-
-      const stacksRoot = join(projectsRoot, projectEntry.name, "stacks");
-      let stackEntries: Array<{ isDirectory(): boolean; name: string }>;
-      try {
-        stackEntries = await readdir(stacksRoot, { withFileTypes: true });
-      } catch {
-        return;
-      }
-
-      await Promise.all(
-        stackEntries.map(async (stackEntry) => {
-          if (!stackEntry.isDirectory()) {
-            return;
-          }
-
-          const stackRoot = join(stacksRoot, stackEntry.name);
-          if (stackRoot === currentStackRoot) {
-            return;
-          }
-
-          const ports = (await readStackMetadataFile(join(stackRoot, "stack.json")))?.ports;
-          if (ports === undefined) {
-            return;
-          }
-
-          for (const field of PORT_FIELDS) {
-            reserved.add(ports[field]);
-          }
-        }),
-      );
-    }),
-  );
-
-  return reserved;
-}
-
-async function readReservedPortsInStacksRoot(
-  stacksRoot: string,
-  currentStackRoot: string,
-): Promise<ReadonlySet<number>> {
-  const reserved = new Set<number>();
-
-  let stackEntries: Array<{ isDirectory(): boolean; name: string }>;
-  try {
-    stackEntries = await readdir(stacksRoot, { withFileTypes: true });
-  } catch {
-    return reserved;
-  }
-
-  await Promise.all(
-    stackEntries.map(async (stackEntry) => {
-      if (!stackEntry.isDirectory()) {
-        return;
-      }
-
-      const stackRoot = join(stacksRoot, stackEntry.name);
-      if (stackRoot === currentStackRoot) {
-        return;
-      }
-
-      const ports = (await readStackMetadataFile(join(stackRoot, "stack.json")))?.ports;
-      if (ports === undefined) {
-        return;
-      }
-
-      for (const field of PORT_FIELDS) {
-        reserved.add(ports[field]);
-      }
-    }),
-  );
-
-  return reserved;
-}
-
-function resolvePostgrestConfig(
-  input: PostgrestConfig | undefined,
-  raw: PostgrestConfig | false | undefined,
-  ports: AllocatedPorts,
-): ResolvedPostgrestConfig | false {
-  if (raw === false) return false;
-  const cfg = input ?? {};
-  return {
-    port: ports.postgrestPort,
-    adminPort: ports.postgrestAdminPort,
-    schemas: cfg.schemas ?? ["public", "graphql_public"],
-    extraSearchPath: cfg.extraSearchPath ?? ["public", "extensions"],
-    maxRows: cfg.maxRows ?? 1000,
-    version: cfg.version ?? DEFAULT_VERSIONS.postgrest,
-  };
-}
-
-function resolveAuthConfig(
-  input: AuthConfig | undefined,
-  raw: AuthConfig | false | undefined,
-  ports: AllocatedPorts,
-  apiPort: number,
-): ResolvedAuthConfig | false {
-  if (raw === false) return false;
-  const cfg = input ?? {};
-  return {
-    port: ports.authPort,
-    siteUrl: cfg.siteUrl ?? "http://localhost:3000",
-    jwtExpiry: cfg.jwtExpiry ?? 3600,
-    externalUrl: cfg.externalUrl ?? `http://127.0.0.1:${apiPort}`,
-    version: cfg.version ?? DEFAULT_VERSIONS.auth,
-  };
-}
-
-function resolveRealtimeConfig(
-  input: RealtimeConfig | undefined,
-  raw: RealtimeConfig | false | undefined,
-  ports: AllocatedPorts,
-): ResolvedRealtimeConfig | false {
-  if (raw === false) return false;
-  const cfg = input ?? {};
-  return {
-    port: ports.realtimePort,
-    version: cfg.version ?? DEFAULT_VERSIONS.realtime,
-    tenantId: cfg.tenantId ?? "realtime-dev",
-    encryptionKey: cfg.encryptionKey ?? "supabaserealtime",
-    secretKeyBase:
-      cfg.secretKeyBase ?? "EAx3IQ/wRG1v47ZD4NE4/9RzBI8Jmil3x0yhcW4V2NHBP6c2iPIzwjofi2Ep4HIG",
-    maxHeaderLength: cfg.maxHeaderLength ?? 4096,
-  };
-}
-
-function resolveEdgeRuntimeConfig(
-  input: EdgeRuntimeConfig | undefined,
-  raw: EdgeRuntimeConfig | false | undefined,
-  ports: AllocatedPorts,
-): ResolvedEdgeRuntimeConfig | false {
-  if (raw === false || raw?.enabled === false) return false;
-  const cfg = input ?? {};
-  return {
-    enabled: cfg.enabled ?? true,
-    port: ports.edgeRuntimePort,
-    inspectorPort: ports.edgeRuntimeInspectorPort,
-    policy: cfg.policy ?? "per_worker",
-    version: cfg.version ?? DEFAULT_VERSIONS["edge-runtime"],
-    env: cfg.env ?? {},
-  };
-}
-
-function resolveFunctionsConfig(config: StackConfig) {
-  if (config.functions === false) return false;
-  return {
-    envFile: config.functions?.envFile,
-    noVerifyJwt: config.functions?.noVerifyJwt ?? false,
-  };
-}
-
-function resolveStorageConfig(
-  input: StorageConfig | undefined,
-  raw: StorageConfig | false | undefined,
-  ports: AllocatedPorts,
-  opts: ResolveConfigOptions,
-): ResolvedStorageConfig | false {
-  if (raw === false) return false;
-  const cfg = input ?? {};
-  return {
-    port: ports.storagePort,
-    version: cfg.version ?? DEFAULT_VERSIONS.storage,
-    dataDir: resolveDataDir(cfg.dataDir, opts.stackRoot!, "storage"),
-    fileSizeLimit: cfg.fileSizeLimit ?? "50MiB",
-    s3ProtocolEnabled: cfg.s3ProtocolEnabled ?? true,
-  };
-}
-
-function resolveImgproxyConfig(
-  input: ImgproxyConfig | undefined,
-  raw: ImgproxyConfig | false | undefined,
-  ports: AllocatedPorts,
-): ResolvedImgproxyConfig | false {
-  if (raw === false) return false;
-  const cfg = input ?? {};
-  return {
-    port: ports.imgproxyPort,
-    version: cfg.version ?? DEFAULT_VERSIONS.imgproxy,
-  };
-}
-
-function resolveMailpitConfig(
-  input: MailpitConfig | undefined,
-  raw: MailpitConfig | false | undefined,
-  ports: AllocatedPorts,
-): ResolvedMailpitConfig | false {
-  if (raw === false) return false;
-  const cfg = input ?? {};
-  return {
-    port: ports.mailpitPort,
-    smtpPort: ports.mailpitSmtpPort,
-    pop3Port: ports.mailpitPop3Port,
-    version: cfg.version ?? DEFAULT_VERSIONS.mailpit,
-    adminEmail: cfg.adminEmail ?? "admin@email.com",
-    senderName: cfg.senderName ?? "Admin",
-  };
-}
-
-function resolvePgmetaConfig(
-  input: PgmetaConfig | undefined,
-  raw: PgmetaConfig | false | undefined,
-  ports: AllocatedPorts,
-): ResolvedPgmetaConfig | false {
-  if (raw === false) return false;
-  const cfg = input ?? {};
-  return {
-    port: ports.pgmetaPort,
-    version: cfg.version ?? DEFAULT_VERSIONS.pgmeta,
-  };
-}
-
-function resolveStudioConfig(
-  input: StudioConfig | undefined,
-  raw: StudioConfig | false | undefined,
-  ports: AllocatedPorts,
-  apiPort: number,
-): ResolvedStudioConfig | false {
-  if (raw === false) return false;
-  const cfg = input ?? {};
-  return {
-    port: ports.studioPort,
-    version: cfg.version ?? DEFAULT_VERSIONS.studio,
-    apiUrl: cfg.apiUrl ?? `http://127.0.0.1:${apiPort}`,
-  };
-}
-
-function resolveAnalyticsConfig(
-  input: AnalyticsConfig | undefined,
-  raw: AnalyticsConfig | false | undefined,
-  ports: AllocatedPorts,
-): ResolvedAnalyticsConfig | false {
-  if (raw === false) return false;
-  const cfg = input ?? {};
-  return {
-    port: ports.analyticsPort,
-    version: cfg.version ?? DEFAULT_VERSIONS.analytics,
-    backend: cfg.backend ?? "postgres",
-    apiKey: cfg.apiKey ?? "api-key",
-  };
-}
-
-function resolveVectorConfig(
-  input: VectorConfig | undefined,
-  raw: VectorConfig | false | undefined,
-): ResolvedVectorConfig | false {
-  if (raw === false) return false;
-  const cfg = input ?? {};
-  return {
-    version: cfg.version ?? DEFAULT_VERSIONS.vector,
-  };
-}
-
-function resolvePoolerConfig(
-  input: PoolerConfig | undefined,
-  raw: PoolerConfig | false | undefined,
-  ports: AllocatedPorts,
-): ResolvedPoolerConfig | false {
-  if (raw === false) return false;
-  const cfg = input ?? {};
-  return {
-    port: ports.poolerPort,
-    apiPort: ports.poolerApiPort,
-    mode: cfg.mode ?? "transaction",
-    version: cfg.version ?? DEFAULT_VERSIONS.pooler,
-    tenantId: cfg.tenantId ?? "pooler-dev",
-    encryptionKey: cfg.encryptionKey ?? "12345678901234567890123456789032",
-    secretKeyBase:
-      cfg.secretKeyBase ?? "EAx3IQ/wRG1v47ZD4NE4/9RzBI8Jmil3x0yhcW4V2NHBP6c2iPIzwjofi2Ep4HIG",
-    defaultPoolSize: cfg.defaultPoolSize ?? 20,
-    maxClientConn: cfg.maxClientConn ?? 100,
-  };
-}
-
-export async function resolveConfig(
-  input?: StackConfig,
-  opts: ResolveConfigOptions = {},
-): Promise<ResolvedStackConfig> {
-  const config = input ?? {};
-  const projectDir = config.projectDir ?? process.cwd();
-  const resolvedMode = config.mode ?? "auto";
-  const roots = resolveRoots(config, opts);
-  const postgresInput = config.postgres ?? {};
-  const postgrestInput = config.postgrest !== false ? (config.postgrest ?? undefined) : undefined;
-  const authInput = config.auth !== false ? (config.auth ?? undefined) : undefined;
-  const edgeRuntimeEnabled =
-    !(resolvedMode === "native" && config.edgeRuntime === undefined) &&
-    config.edgeRuntime !== false &&
-    (config.edgeRuntime?.enabled ?? true) !== false;
-  const realtimeEnabled = config.realtime !== undefined && config.realtime !== false;
-  const storageEnabled = config.storage !== undefined && config.storage !== false;
-  const imgproxyEnabled = config.imgproxy !== undefined && config.imgproxy !== false;
-  const mailpitEnabled = config.mailpit !== undefined && config.mailpit !== false;
-  const pgmetaEnabled = config.pgmeta !== undefined && config.pgmeta !== false;
-  const studioEnabled = config.studio !== undefined && config.studio !== false;
-  const analyticsEnabled = config.analytics !== undefined && config.analytics !== false;
-  const vectorEnabled = config.vector !== undefined && config.vector !== false;
-  const poolerEnabled = config.pooler !== undefined && config.pooler !== false;
-  const edgeRuntimeInput = edgeRuntimeEnabled ? (config.edgeRuntime ?? undefined) : undefined;
-  const realtimeInput = realtimeEnabled ? (config.realtime ?? undefined) : undefined;
-  const storageInput = storageEnabled ? (config.storage ?? undefined) : undefined;
-  const imgproxyInput = imgproxyEnabled ? (config.imgproxy ?? undefined) : undefined;
-  const mailpitInput = mailpitEnabled ? (config.mailpit ?? undefined) : undefined;
-  const pgmetaInput = pgmetaEnabled ? (config.pgmeta ?? undefined) : undefined;
-  const studioInput = studioEnabled ? (config.studio ?? undefined) : undefined;
-  const analyticsInput = analyticsEnabled ? (config.analytics ?? undefined) : undefined;
-  const vectorInput = vectorEnabled ? (config.vector ?? undefined) : undefined;
-  const poolerInput = poolerEnabled ? (config.pooler ?? undefined) : undefined;
-
-  const postgresDataDir = resolveDataDir(postgresInput.dataDir, roots.stackRoot, "postgres");
-
-  const ports = await Effect.runPromise(
-    (opts.portAllocator ?? allocatePorts)(
-      {
-        apiPort: config.port,
-        dbPort: postgresInput.port,
-        authPort: authInput?.port,
-        postgrestPort: undefined,
-        postgrestAdminPort: undefined,
-        edgeRuntimePort: edgeRuntimeInput?.port,
-        edgeRuntimeInspectorPort: edgeRuntimeInput?.inspectorPort,
-        realtimePort: realtimeInput?.port,
-        storagePort: storageInput?.port,
-        imgproxyPort: imgproxyInput?.port,
-        mailpitPort: mailpitInput?.port,
-        mailpitSmtpPort: mailpitInput?.smtpPort,
-        mailpitPop3Port: mailpitInput?.pop3Port,
-        pgmetaPort: pgmetaInput?.port,
-        studioPort: studioInput?.port,
-        analyticsPort: analyticsInput?.port,
-        poolerPort: poolerInput?.port,
-        poolerApiPort: poolerInput?.apiPort,
-      },
-      {
-        preferred: opts.preferredPorts,
-        reserved: opts.reservedPorts,
-      },
-    ),
-  ).catch((error: unknown) => {
-    throw toStackError(error);
-  });
-
-  const jwtSecret = config.jwtSecret ?? defaultJwtSecret;
-  const anonJwt = generateJwt(jwtSecret, "anon");
-  const serviceRoleJwt = generateJwt(jwtSecret, "service_role");
-
-  return {
-    cacheRoot: roots.cacheRoot,
-    stackRoot: roots.stackRoot,
-    runtimeRoot: roots.runtimeRoot,
-    projectDir,
-    mode: resolvedMode,
-    startupMode: config.startupMode ?? "eager",
-    jwtSecret,
-    ports,
-    apiPort: ports.apiPort,
-    dbPort: ports.dbPort,
-    publishableKey: config.publishableKey ?? defaultPublishableKey,
-    secretKey: config.secretKey ?? defaultSecretKey,
-    functions: resolveFunctionsConfig(config),
-    autoManagedPaths: roots.autoManagedPaths,
-    anonJwt,
-    serviceRoleJwt,
-    postgres: {
-      port: ports.dbPort,
-      dataDir: postgresDataDir,
-      version: postgresInput.version ?? DEFAULT_VERSIONS.postgres,
-      autoExposeNewTables: postgresInput.autoExposeNewTables ?? true,
-    },
-    postgrest: resolvePostgrestConfig(postgrestInput, config.postgrest, ports),
-    auth: resolveAuthConfig(authInput, config.auth, ports, ports.apiPort),
-    edgeRuntime: edgeRuntimeEnabled
-      ? resolveEdgeRuntimeConfig(edgeRuntimeInput, config.edgeRuntime, ports)
-      : false,
-    realtime: realtimeEnabled
-      ? resolveRealtimeConfig(realtimeInput, config.realtime, ports)
-      : false,
-    storage: storageEnabled
-      ? resolveStorageConfig(storageInput, config.storage, ports, {
-          ...opts,
-          stackRoot: roots.stackRoot,
-        })
-      : false,
-    imgproxy: imgproxyEnabled
-      ? resolveImgproxyConfig(imgproxyInput, config.imgproxy, ports)
-      : false,
-    mailpit: mailpitEnabled ? resolveMailpitConfig(mailpitInput, config.mailpit, ports) : false,
-    pgmeta: pgmetaEnabled ? resolvePgmetaConfig(pgmetaInput, config.pgmeta, ports) : false,
-    studio: studioEnabled
-      ? resolveStudioConfig(studioInput, config.studio, ports, ports.apiPort)
-      : false,
-    analytics: analyticsEnabled
-      ? resolveAnalyticsConfig(analyticsInput, config.analytics, ports)
-      : false,
-    vector: vectorEnabled ? resolveVectorConfig(vectorInput, config.vector) : false,
-    pooler: poolerEnabled ? resolvePoolerConfig(poolerInput, config.pooler, ports) : false,
-  };
-}
-
-export type DaemonConfigInput = StackConfig & {
-  readonly cwd: string;
-  readonly name?: string;
-  readonly projectDir?: string;
-  readonly projectStateRoot?: string;
-};
-
-export async function resolveDaemonConfig(
-  input: DaemonConfigInput,
-  opts: Pick<ResolveConfigOptions, "portAllocator"> = {},
-): Promise<DaemonConfig> {
-  const { cwd, name, projectDir, projectStateRoot, ...stackConfig } = input;
-  if (stackConfig.stackRoot !== undefined || stackConfig.runtimeRoot !== undefined) {
-    throw new Error("Managed daemon stacks derive stackRoot and runtimeRoot automatically");
-  }
-  const effectiveProjectDir = projectDir ?? cwd;
-  const resolvedName = name ?? defaultManagedStackName(effectiveProjectDir);
-  const cacheRoot = stackConfig.cacheRoot ?? defaultCacheRoot();
-  const stackRoot =
-    projectStateRoot !== undefined
-      ? join(projectStateRoot, "stacks", resolvedName)
-      : defaultManagedStackRoot(cacheRoot, effectiveProjectDir, resolvedName);
-  const runtimeRoot = defaultManagedRuntimeRoot(stackRoot);
-  const savedPorts = await readOwnedPorts(stackRoot);
-  const reservedPortSets = await Promise.all([
-    readReservedPorts(defaultManagedProjectsRoot(cacheRoot), stackRoot),
-    projectStateRoot === undefined
-      ? Promise.resolve<ReadonlySet<number>>(new Set())
-      : readReservedPortsInStacksRoot(join(projectStateRoot, "stacks"), stackRoot),
-  ]);
-  const reservedPorts = new Set<number>();
-  for (const ports of reservedPortSets) {
-    for (const port of ports) {
-      reservedPorts.add(port);
-    }
-  }
-  const resolved = await resolveConfig(
-    {
-      ...stackConfig,
-      cacheRoot,
-      stackRoot,
-      runtimeRoot,
-      projectDir: effectiveProjectDir,
-    },
-    {
-      stackRoot,
-      runtimeRoot,
-      preferredPorts: savedPorts ?? DEFAULT_PORTS,
-      reservedPorts,
-      portAllocator: opts.portAllocator,
-    },
-  );
-  return {
-    ...resolved,
-    name: resolvedName,
-    projectDir: effectiveProjectDir,
-  };
-}
-
 export const projectDaemonLayer = (opts: {
   readonly cacheRoot: string;
   readonly cwd: string;
@@ -784,16 +169,24 @@ export async function createStack(
         reloadFunctions: (opts) => run(localStack.reloadFunctions(opts)),
         reloadEdgeRuntime: (opts) => run(localStack.reloadEdgeRuntime(opts)),
         ready: (opts) => {
+          const policy = resolveReadinessPolicy({
+            readyOptions: opts,
+            stackPolicy: resolved.readiness,
+          });
           const effect =
-            opts?.timeout != null
-              ? localStack.waitAllReady().pipe(Effect.timeout(Duration.millis(opts.timeout)))
+            policy.mode === "finite"
+              ? localStack.waitAllReady().pipe(Effect.timeout(Duration.millis(policy.timeoutMs)))
               : localStack.waitAllReady();
           return run(effect);
         },
         serviceReady: (name, opts) => {
+          const policy = resolveReadinessPolicy({
+            readyOptions: opts,
+            stackPolicy: resolved.readiness,
+          });
           const effect =
-            opts?.timeout != null
-              ? localStack.waitReady(name).pipe(Effect.timeout(Duration.millis(opts.timeout)))
+            policy.mode === "finite"
+              ? localStack.waitReady(name).pipe(Effect.timeout(Duration.millis(policy.timeoutMs)))
               : localStack.waitReady(name);
           return run(effect);
         },
diff --git a/packages/stack/src/createStack.unit.test.ts b/packages/stack/src/createStack.unit.test.ts
index 68caf179c1..747b16686b 100644
--- a/packages/stack/src/createStack.unit.test.ts
+++ b/packages/stack/src/createStack.unit.test.ts
@@ -2,12 +2,18 @@ import { describe, expect, it } from "vitest";
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import type { ReadyOptions, StackHandle } from "./createStack.ts";
-import { resolveConfig, resolveDaemonConfig } from "./createStack.ts";
+import type { StackHandle } from "./createStack.ts";
 import type { AllocatedPorts } from "./PortAllocator.ts";
 import { DEFAULT_MANAGED_STACK_NAME, projectKeyForProjectDir } from "./paths.ts";
 import { stackMetadata } from "./StackMetadata.ts";
-import type { AuthConfig, PostgresConfig, PostgrestConfig, StackConfig } from "./StackBuilder.ts";
+import type {
+  AuthConfig,
+  PostgresConfig,
+  PostgrestConfig,
+  ReadyOptions,
+  StackConfig,
+} from "./StackConfig.ts";
+import { resolveConfig, resolveDaemonConfig } from "./StackConfigResolver.ts";
 import { DEFAULT_VERSIONS } from "./versions.ts";
 
 const DEFAULT_PORTS: AllocatedPorts = {
@@ -251,3 +257,15 @@ describe("resolveConfig startup mode", () => {
     expect(config.startupMode).toBe("lazy");
   });
 });
+
+describe("resolveConfig readiness policy", () => {
+  it("uses a finite package default", async () => {
+    const config = await resolveConfig();
+    expect(config.readiness).toEqual({ mode: "finite", timeoutMs: 120_000 });
+  });
+
+  it("preserves an explicit infinite policy", async () => {
+    const config = await resolveConfig({ readiness: { mode: "infinite" } });
+    expect(config.readiness).toEqual({ mode: "infinite" });
+  });
+});
diff --git a/packages/stack/src/daemon.ts b/packages/stack/src/daemon.ts
index 1171d634c5..30361ecb92 100644
--- a/packages/stack/src/daemon.ts
+++ b/packages/stack/src/daemon.ts
@@ -1,16 +1,13 @@
 import { Effect, Layer, ManagedRuntime } from "effect";
 import { HttpServer } from "effect/unstable/http";
-import {
-  resolveDaemonConfig,
-  type DaemonConfigInput,
-  type PlatformFactory,
-} from "./createStack.ts";
+import type { PlatformFactory } from "./createStack.ts";
 import { DaemonServer } from "./DaemonServer.ts";
 import { PORT_FIELDS, reservePorts, type PortLease } from "./PortAllocator.ts";
 import { allocatedPortFieldsForConfig } from "./ServicePorts.ts";
 import { runningServiceVersionsForConfig } from "./StackMetadata.ts";
 import { foregroundDaemonLayer } from "./layers.ts";
 import { Stack } from "./Stack.ts";
+import { resolveDaemonConfig, type DaemonConfigInput } from "./StackConfigResolver.ts";
 import { StateManager, type StackState } from "./StateManager.ts";
 
 /** Factory for creating the daemon's Unix socket HTTP server (platform-specific). */
diff --git a/packages/stack/src/discovery.ts b/packages/stack/src/discovery.ts
index 18de19f60f..314ec2d5ba 100644
--- a/packages/stack/src/discovery.ts
+++ b/packages/stack/src/discovery.ts
@@ -1,7 +1,7 @@
 import { Data, Duration, Effect } from "effect";
 import { FileSystem, Path } from "effect";
 import { dockerForceRemove } from "./cleanup.ts";
-import { defaultManagedStackName } from "./createStack.ts";
+import { defaultManagedStackName } from "./StackConfigResolver.ts";
 import {
   InvalidStackMetadataError,
   InvalidStackStateError,
diff --git a/packages/stack/src/effect.ts b/packages/stack/src/effect.ts
index f3efd79c4e..215e6b6892 100644
--- a/packages/stack/src/effect.ts
+++ b/packages/stack/src/effect.ts
@@ -27,8 +27,7 @@ export {
 export type { BinarySpec } from "./BinaryResolver.ts";
 export { BinaryResolver } from "./BinaryResolver.ts";
 
-export type { ServiceResolution } from "./resolve.ts";
-export { resolveService } from "./resolve.ts";
+export type { ServiceResolution } from "./StackPreparation.ts";
 
 export type { PrefetchOptions, PrefetchResult } from "./prefetch.ts";
 export { prefetch } from "./prefetch.ts";
@@ -84,11 +83,14 @@ export type {
   ResolvedStorageConfig,
   ResolvedStudioConfig,
   ResolvedVectorConfig,
+  ReadinessPolicy,
+  ReadyOptions,
   StackConfig,
   StorageConfig,
   StudioConfig,
   VectorConfig,
-} from "./StackBuilder.ts";
+} from "./StackConfig.ts";
+export { DEFAULT_STACK_READINESS_POLICY, resolveReadinessPolicy } from "./StackConfig.ts";
 export { StackBuilder } from "./StackBuilder.ts";
 
 export type { EdgeRuntimeReloadConfig, StackInfo } from "./Stack.ts";
@@ -164,18 +166,16 @@ export type {
   PlatformFactoryOptions,
   PlatformLayer,
   PlatformServices,
-  ReadyOptions,
   StackHandle,
 } from "./createStack.ts";
+export { createStack, projectDaemonLayer } from "./createStack.ts";
+export type { ResolvedDaemonConfig } from "./StackConfig.ts";
 export {
-  createStack,
   defaultManagedStackName,
-  projectDaemonLayer,
   resolveConfig,
   resolveDaemonConfig,
-} from "./createStack.ts";
+} from "./StackConfigResolver.ts";
 
-export type { DaemonConfig } from "./layers.ts";
 export { connectLayer, DaemonStartError, daemonLayer, foregroundLayer } from "./layers.ts";
 export type { ManagedStack } from "./managed-stack.ts";
 export { resolveManagedStack } from "./managed-stack.ts";
diff --git a/packages/stack/src/functions.ts b/packages/stack/src/functions.ts
index 527a163b65..fd95607f93 100644
--- a/packages/stack/src/functions.ts
+++ b/packages/stack/src/functions.ts
@@ -8,7 +8,7 @@ import {
   type ResolvedFunctionConfig,
 } from "@supabase/config";
 import { Effect, FileSystem, Path, Redacted } from "effect";
-import type { ResolvedStackConfig } from "./StackBuilder.ts";
+import type { ResolvedStackConfig } from "./StackConfig.ts";
 
 export interface FunctionsConfig {
   readonly envFile?: string;
diff --git a/packages/stack/src/functions.unit.test.ts b/packages/stack/src/functions.unit.test.ts
index 56ead117fb..e537ea9a90 100644
--- a/packages/stack/src/functions.unit.test.ts
+++ b/packages/stack/src/functions.unit.test.ts
@@ -5,7 +5,7 @@ import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Effect } from "effect";
-import { resolveConfig } from "./createStack.ts";
+import { resolveConfig } from "./StackConfigResolver.ts";
 import { defaultJwtSecret, generateJwt } from "./JwtGenerator.ts";
 import {
   configureFunctionsRuntime,
diff --git a/packages/stack/src/index.ts b/packages/stack/src/index.ts
index 087b40503e..8e990d0640 100644
--- a/packages/stack/src/index.ts
+++ b/packages/stack/src/index.ts
@@ -14,15 +14,17 @@ export type {
   PostgresConfig,
   PostgrestConfig,
   RealtimeConfig,
+  ReadinessPolicy,
+  ReadyOptions,
   StackConfig,
   StorageConfig,
   StudioConfig,
   VectorConfig,
-} from "./StackBuilder.ts";
+} from "./StackConfig.ts";
 
 export type { ServiceName, VersionManifest } from "./versions.ts";
-export type { ServiceResolution } from "./resolve.ts";
+export type { ServiceResolution } from "./StackPreparation.ts";
 export type { PrefetchOptions, PrefetchResult } from "./prefetch.ts";
-export type { ReadyOptions, StackHandle } from "./createStack.ts";
+export type { StackHandle } from "./createStack.ts";
 export type { FunctionsConfig, FunctionsRuntimeConfig } from "./functions.ts";
 export { UnixHttpClient, UnixHttpClientError } from "./UnixHttpClient.ts";
diff --git a/packages/stack/src/layers.ts b/packages/stack/src/layers.ts
index 34f3ea0413..30fb1c3eb4 100644
--- a/packages/stack/src/layers.ts
+++ b/packages/stack/src/layers.ts
@@ -6,7 +6,7 @@ import { FileSystem, Path } from "effect";
 import { FetchHttpClient } from "effect/unstable/http";
 import { ApiProxy, type ProxyConfig } from "./ApiProxy.ts";
 import { BinaryResolver } from "./BinaryResolver.ts";
-import type { DaemonConfigInput, PlatformFactory } from "./createStack.ts";
+import type { PlatformFactory } from "./createStack.ts";
 import type { DaemonMessage, DaemonStartMessage } from "./daemon.ts";
 import { DaemonMessageSchema } from "./DaemonProtocol.ts";
 import type { PortLease } from "./PortAllocator.ts";
@@ -23,7 +23,9 @@ import {
   StateManager,
   singleStackStateManagerPaths,
 } from "./StateManager.ts";
-import { StackBuilder, type ResolvedStackConfig } from "./StackBuilder.ts";
+import { StackBuilder } from "./StackBuilder.ts";
+import type { ResolvedDaemonConfig, ResolvedStackConfig } from "./StackConfig.ts";
+import type { DaemonConfigInput } from "./StackConfigResolver.ts";
 import { UnixHttpClient } from "./UnixHttpClient.ts";
 import { resolveManagedStack } from "./managed-stack.ts";
 import {
@@ -108,13 +110,8 @@ export class DaemonStartError extends Data.TaggedError("DaemonStartError")<{
 // Daemon-backed mode
 // ---------------------------------------------------------------------------
 
-export interface DaemonConfig extends ResolvedStackConfig {
-  readonly name: string;
-  readonly projectDir: string;
-}
-
 export const foregroundDaemonLayer = (
-  config: DaemonConfig,
+  config: ResolvedDaemonConfig,
   platformFactory: PlatformFactory,
   portLease: PortLease,
 ): Layer.Layer<Stack | StateManager> => {
diff --git a/packages/stack/src/node.ts b/packages/stack/src/node.ts
index 8feb036db6..aedf7ab1f1 100644
--- a/packages/stack/src/node.ts
+++ b/packages/stack/src/node.ts
@@ -19,7 +19,7 @@ import {
 } from "./prefetch.ts";
 import { defaultCacheRoot } from "./paths.ts";
 import { StackPreparation } from "./StackPreparation.ts";
-import type { StackConfig } from "./StackBuilder.ts";
+import type { StackConfig } from "./StackConfig.ts";
 import { UnixHttpClient, UnixHttpClientError } from "./UnixHttpClient.ts";
 
 const mergeBodyHeaders = (
diff --git a/packages/stack/src/prefetch.ts b/packages/stack/src/prefetch.ts
index f086bd5102..b68d4b5f4d 100644
--- a/packages/stack/src/prefetch.ts
+++ b/packages/stack/src/prefetch.ts
@@ -1,16 +1,20 @@
 import { Effect } from "effect";
 import type { ChecksumMismatchError } from "./errors.ts";
 import type { DockerPullError } from "./errors.ts";
-import { type PreparedStackArtifacts, type StackPreparationInput } from "./StackPreparation.ts";
+import {
+  type PreparedStackArtifacts,
+  type ServiceResolution,
+  type StackPreparationInput,
+} from "./StackPreparation.ts";
 import { StackPreparation } from "./StackPreparation.ts";
-import type { ServiceResolution } from "./resolve.ts";
+import type { ServiceName } from "./ServiceName.ts";
 
 export interface PrefetchOptions extends StackPreparationInput {}
 
-export type PrefetchResult = Record<string, ServiceResolution>;
+export type PrefetchResult = Partial<Record<ServiceName, ServiceResolution>>;
 
 const toPrefetchResult = (artifacts: PreparedStackArtifacts): PrefetchResult =>
-  artifacts.resolutions as PrefetchResult;
+  artifacts.resolutions;
 
 export const prefetch = (
   options?: PrefetchOptions,
diff --git a/packages/stack/src/resolve.ts b/packages/stack/src/resolve.ts
deleted file mode 100644
index 813a7448f7..0000000000
--- a/packages/stack/src/resolve.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import { Effect } from "effect";
-import type { BinaryResolver } from "./BinaryResolver.ts";
-import type { ChecksumMismatchError } from "./errors.ts";
-import type { ServiceName } from "./versions.ts";
-import { dockerImageForService } from "./versions.ts";
-
-export type ServiceResolution =
-  | { readonly type: "binary"; readonly path: string }
-  | { readonly type: "docker"; readonly image: string };
-
-/**
- * Resolve a service to either a native binary path or a Docker image.
- * Tries BinaryResolver first; falls back to Docker on BinaryNotFoundError or DownloadError.
- * ChecksumMismatchError is a real error and propagates.
- */
-export const resolveService = (
-  resolver: BinaryResolver["Service"],
-  service: ServiceName,
-  version: string,
-): Effect.Effect<ServiceResolution, ChecksumMismatchError> =>
-  resolver.resolve({ service, version }).pipe(
-    Effect.map((path): ServiceResolution => ({ type: "binary", path })),
-    Effect.catchTag("BinaryNotFoundError", () =>
-      Effect.succeed<ServiceResolution>({
-        type: "docker",
-        image: dockerImageForService(service, version),
-      }),
-    ),
-    Effect.catchTag("DownloadError", () =>
-      Effect.succeed<ServiceResolution>({
-        type: "docker",
-        image: dockerImageForService(service, version),
-      }),
-    ),
-  );
diff --git a/packages/stack/src/versions.ts b/packages/stack/src/versions.ts
index f54f44c5db..9e6295fac0 100644
--- a/packages/stack/src/versions.ts
+++ b/packages/stack/src/versions.ts
@@ -1,71 +1,16 @@
 import {
+  DEFAULT_VERSIONS,
+  SERVICE_NAMES,
   dockerImageCandidatesForArtifact,
   dockerImageForArtifact,
   imageTagPrefixForService,
-} from "./ServiceArtifacts.ts";
+} from "./ServiceCatalog.ts";
+import type { ServiceName } from "./ServiceName.ts";
 
-export type ServiceName =
-  | "postgres"
-  | "postgrest"
-  | "auth"
-  | "edge-runtime"
-  | "realtime"
-  | "storage"
-  | "imgproxy"
-  | "mailpit"
-  | "pgmeta"
-  | "studio"
-  | "analytics"
-  | "vector"
-  | "pooler";
+export { DEFAULT_VERSIONS, SERVICE_NAMES } from "./ServiceCatalog.ts";
+export type { ServiceName } from "./ServiceName.ts";
 
-export const SERVICE_NAMES = [
-  "postgres",
-  "postgrest",
-  "auth",
-  "edge-runtime",
-  "realtime",
-  "storage",
-  "imgproxy",
-  "mailpit",
-  "pgmeta",
-  "studio",
-  "analytics",
-  "vector",
-  "pooler",
-] as const satisfies ReadonlyArray<ServiceName>;
-
-export interface VersionManifest {
-  readonly postgres: string;
-  readonly postgrest: string;
-  readonly auth: string;
-  readonly "edge-runtime": string;
-  readonly realtime: string;
-  readonly storage: string;
-  readonly imgproxy: string;
-  readonly mailpit: string;
-  readonly pgmeta: string;
-  readonly studio: string;
-  readonly analytics: string;
-  readonly vector: string;
-  readonly pooler: string;
-}
-
-export const DEFAULT_VERSIONS: VersionManifest = {
-  postgres: "17.6.1.158",
-  postgrest: "14.15",
-  auth: "2.194.0",
-  "edge-runtime": "1.74.2",
-  realtime: "2.120.3",
-  storage: "1.67.20",
-  imgproxy: "v3.8.0",
-  mailpit: "v1.30.2",
-  pgmeta: "0.96.6",
-  studio: "2026.07.27-sha-cbb076d",
-  analytics: "1.47.1",
-  vector: "0.53.0-alpine",
-  pooler: "2.9.7",
-} as const;
+export type VersionManifest = Readonly<Record<ServiceName, string>>;
 
 export const IMAGE_TAG_PREFIX: Partial<Record<ServiceName, string>> = Object.fromEntries(
   SERVICE_NAMES.flatMap((service) => {
diff --git a/packages/stack/src/versions.unit.test.ts b/packages/stack/src/versions.unit.test.ts
index 4b31249dbd..bd5e584c3f 100644
--- a/packages/stack/src/versions.unit.test.ts
+++ b/packages/stack/src/versions.unit.test.ts
@@ -13,7 +13,7 @@ import {
   SERVICE_NAMES,
   type VersionManifest,
 } from "./versions.ts";
-import { SERVICE_ARTIFACTS } from "./ServiceArtifacts.ts";
+import { SERVICE_CATALOG } from "./ServiceCatalog.ts";
 
 const sampleDockerfile = `
 FROM supabase/postgres:17.0.0.1 AS pg
@@ -35,44 +35,29 @@ FROM supabase/migra:3.0.1663481299 AS migra
 
 describe("syncDefaultVersionsSource", () => {
   it("rewrites the DEFAULT_VERSIONS block from Dockerfile versions", () => {
-    const source = `before
-export const DEFAULT_VERSIONS: VersionManifest = {
-  postgres: "old",
-  postgrest: "old",
-  auth: "old",
-  "edge-runtime": "old",
-  realtime: "old",
-  storage: "old",
-  imgproxy: "old",
-  mailpit: "old",
-  pgmeta: "old",
-  studio: "old",
-  analytics: "old",
-  vector: "old",
-  pooler: "old",
-} as const;
-after`;
-
-    expect(syncDefaultVersionsSource(source, readVersionManifestFromDockerfile(sampleDockerfile)))
-      .toMatchInlineSnapshot(`
-        "before
-        export const DEFAULT_VERSIONS: VersionManifest = {
-          postgres: "17.0.0.1",
-          postgrest: "14.0",
-          auth: "2.100.0",
-          "edge-runtime": "1.70.0",
-          realtime: "2.100.0",
-          storage: "1.50.0",
-          imgproxy: "v3.8.0",
-          mailpit: "v1.2.3",
-          pgmeta: "0.90.0",
-          studio: "2026.01.01-sha-abcdef0",
-          analytics: "1.40.0",
-          vector: "0.50.0-alpine",
-          pooler: "2.1.0",
-        } as const;
-        after"
-      `);
+    const source = SERVICE_NAMES.map(
+      (service) => `  ${JSON.stringify(service)}: {
+    name: ${JSON.stringify(service)},
+    configKey: "example",
+    defaultVersion: "old",
+  },`,
+    ).join("\n");
+
+    const updated = syncDefaultVersionsSource(
+      source,
+      readVersionManifestFromDockerfile(sampleDockerfile),
+    );
+
+    expect(updated).toContain(
+      'name: "postgres",\n    configKey: "example",\n    defaultVersion: "17.0.0.1"',
+    );
+    expect(updated).toContain(
+      'name: "edge-runtime",\n    configKey: "example",\n    defaultVersion: "1.70.0"',
+    );
+    expect(updated).toContain(
+      'name: "mailpit",\n    configKey: "example",\n    defaultVersion: "v1.2.3"',
+    );
+    expect(updated).not.toContain('defaultVersion: "old"');
   });
 
   it("fails when a required Dockerfile image alias is missing", () => {
@@ -92,7 +77,7 @@ after`;
 
 describe("dockerImageForService", () => {
   it("defines artifact capabilities for every stack service", () => {
-    expect(Object.keys(SERVICE_ARTIFACTS).sort()).toEqual([...SERVICE_NAMES].sort());
+    expect(Object.keys(SERVICE_CATALOG).sort()).toEqual([...SERVICE_NAMES].sort());
   });
 
   it("returns correct image for postgres", () => {
@@ -134,17 +119,17 @@ describe("dockerImageForService", () => {
   });
 
   it("keeps non-managed services Docker-only", () => {
-    expect(SERVICE_ARTIFACTS.imgproxy).toMatchObject({
+    expect(SERVICE_CATALOG.imgproxy).toMatchObject({
       runtimeSupport: "docker-only",
-      docker: { ownership: "upstream", repository: "darthsim/imgproxy" },
+      artifact: { docker: { ownership: "upstream", repository: "darthsim/imgproxy" } },
     });
-    expect(SERVICE_ARTIFACTS.mailpit).toMatchObject({
+    expect(SERVICE_CATALOG.mailpit).toMatchObject({
       runtimeSupport: "docker-only",
-      docker: { ownership: "upstream", repository: "axllent/mailpit" },
+      artifact: { docker: { ownership: "upstream", repository: "axllent/mailpit" } },
     });
-    expect(SERVICE_ARTIFACTS.vector).toMatchObject({
+    expect(SERVICE_CATALOG.vector).toMatchObject({
       runtimeSupport: "docker-only",
-      docker: { ownership: "upstream", repository: "timberio/vector" },
+      artifact: { docker: { ownership: "upstream", repository: "timberio/vector" } },
     });
   });
 });

From 442698f79aaf6d52764ecc156b90bcbe899d7cd2 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 15:14:37 +0200
Subject: [PATCH 04/44] refactor(process-compose): isolate supervisor policies

---
 packages/process-compose/docs/architecture.md |  35 +++--
 packages/process-compose/src/LogBuffer.ts     |  10 --
 .../src/LogBuffer.unit.test.ts                |  11 --
 packages/process-compose/src/Orchestrator.ts  |  62 ++++----
 .../src/Orchestrator.unit.test.ts             |  33 +++--
 .../process-compose/src/RestartClosure.ts     |  37 +++++
 .../src/RestartClosure.unit.test.ts           |  72 ++++++++++
 packages/process-compose/src/ServiceDef.ts    |   6 +-
 .../process-compose/src/ServiceTransition.ts  |  66 ++++-----
 .../src/ServiceTransition.unit.test.ts        |  71 ++++++++-
 .../src/SupervisorRuntime.unit.test.ts        | 136 ++++++++++++++++--
 packages/process-compose/src/errors.ts        |   4 -
 .../process-compose/src/errors.unit.test.ts   |   7 -
 packages/process-compose/src/index.ts         |   1 -
 .../process-compose/src/supervisor-runtime.ts |  40 ++++--
 packages/stack/src/services/docker-cleanup.ts |   9 +-
 packages/stack/src/services/service-utils.ts  |   4 +-
 .../stack/src/services/services.unit.test.ts  |  18 ++-
 18 files changed, 472 insertions(+), 150 deletions(-)
 create mode 100644 packages/process-compose/src/RestartClosure.ts
 create mode 100644 packages/process-compose/src/RestartClosure.unit.test.ts

diff --git a/packages/process-compose/docs/architecture.md b/packages/process-compose/docs/architecture.md
index 85e3f58841..b8f7675640 100644
--- a/packages/process-compose/docs/architecture.md
+++ b/packages/process-compose/docs/architecture.md
@@ -58,7 +58,9 @@ one of three conditions:
 
 `startService(name)` starts the requested definition and its transitive dependencies.
 `stopService(name)` and `restartService(name)` also include active dependents so a caller cannot
-leave an already-running dependent attached to a restarted dependency.
+leave an already-running dependent attached to a restarted dependency. The pure restart-closure
+calculation preserves inactive connector services on a dependency path to an active descendant;
+otherwise restarting the descendant without its connector would violate graph order.
 
 `updateServiceDefinition(name, replacement)` validates a graph with the replacement and then swaps
 the graph used for subsequent starts and restarts. It does not mutate a process generation that is
@@ -110,7 +112,8 @@ redundant publications must compare before writing.
 `ServiceTransition` is the only normal path for observed-status changes. `applyEvent()` rejects
 illegal `(status, event)` pairs by returning `null`; `transition()` applies a legal event atomically
 through `SubscriptionRef.modifyEffect`. Races such as a late health callback during shutdown are
-therefore ignored without corrupting state.
+therefore ignored without corrupting state. The transition classification is keyed by every event
+tag, so adding an event fails type checking until its legal source statuses are defined.
 
 ## Lifecycle of one process generation
 
@@ -121,9 +124,9 @@ For each requested definition, `Orchestrator` runs this sequence:
    backoff, allowing a caller to reserve external resources.
 3. Wait for dependencies, bounded by `dependencyTimeoutSeconds` (default: 120 seconds).
 4. Transition to `Starting`.
-5. Call `beforeSpawn` immediately before every spawn. The stack uses it to release a reserved port
-   as late as possible. For a supervised Docker command there is still a spawn-to-container-bind
-   window because no supervisor/container bind handshake exists.
+5. Call `beforeSpawn` immediately before every spawn. A caller can use it to release a reserved port
+   as late as possible. For a supervised child there is still a spawn-to-bind window because no
+   supervisor/child bind handshake exists.
 6. Spawn either the configured process or its optional supervisor.
 7. Register a scoped finalizer before exposing `Running`.
 8. Run `started` hooks sequentially. Only successful hooks allow `ProcessSpawned` to publish
@@ -137,6 +140,10 @@ For each requested definition, `Orchestrator` runs this sequence:
 The service keeps the same state stream across restart generations. Restart backoff is
 `min(30 seconds, 2^(restartCount - 1))`.
 
+A no-health-check, `restart: "no"` process is treated as one-shot work. A small isolated poll of
+`ChildProcessHandle.isRunning` compensates for adapters that can report process completion before
+their `exitCode` Effect becomes observable; it is not part of the general lifecycle loop.
+
 ### Lifecycle hooks
 
 Hooks are caller-supplied Effects triggered on `started` or `healthy`. Hooks for one trigger run in
@@ -202,7 +209,7 @@ interrupts its lifecycle fiber. The generation finalizer:
 Whole-graph stop sets desired state first and then stops dependents before dependencies. The global
 shutdown budget defaults to 60 seconds. If that budget expires, the orchestrator logs the timeout
 and clears all fibers. Services that were running are forced to terminal `Stopped` state with
-`pid: null` and exit code `143`; stop does not fail with `ShutdownTimeoutError`.
+`pid: null` and exit code `143`.
 
 In-process cleanup and orphan supervision solve different failure modes:
 
@@ -211,9 +218,10 @@ In-process cleanup and orphan supervision solve different failure modes:
   owner's stdin closes, its PID disappears, the supervisor receives a termination signal, or the
   managed child exits while cleanup is configured.
 
-`ExternalCleanupAction` currently supports removing a Docker container or a filesystem path. The
-supervisor validates the decoded configuration and ignores individual cleanup failures so cleanup
-remains best-effort and idempotent.
+`ExternalCleanupAction` supports a shell-free `RunCommand` with an executable, argument array, and
+optional timeout, plus `RemovePath` for filesystem cleanup. The supervisor rejects a malformed
+decoded cleanup contract before spawning the child, while individual execution failures remain
+best-effort. Callers must choose idempotent commands because owner-loss signals can race.
 
 ## Supervisor runtime
 
@@ -246,7 +254,8 @@ virtual filesystem. The package therefore uses three internal environment variab
 The CLI entrypoint calls `enableSupervisorSelfDispatchForCompiledBun()` before normal command
 dispatch, checks `isSupervisorRuntimeRequested()`, and invokes `runSupervisorRuntimeFromEnv()`.
 The supervisor removes all three variables before starting the managed command, preventing the
-protocol from leaking recursively into a service.
+protocol from leaking recursively into a service. Contract tests run the same encoded supervisor
+configuration through both the source-file argument path and environment-based self-dispatch path.
 
 The stack daemon has a separate Supabase-owned marker, `SUPABASE_STACK_RUN_DAEMON`; it is documented
 in [the stack detach-mode guide](../../stack/docs/detach-mode.md#compiled-executable-re-entry).
@@ -263,15 +272,13 @@ plus live per-service and merged `PubSub` streams. `historyAll` can filter by se
 Streams contain new entries only; callers explicitly request history when they need replay.
 
 When a process exits unexpectedly or becomes unhealthy, the orchestrator appends recent buffered
-output to its diagnostics. `truncate` currently clears both a service's history and its entries in
-the merged history; it has no production caller.
+output to its diagnostics.
 
 ## Error model
 
 Graph construction can fail with `MissingDependencyError` or `CyclicDependencyError`. Lifecycle
 lookup uses `ServiceNotFoundError`; spawn preparation uses `SpawnError`; readiness uses
-`ServiceReadyError`. Global shutdown timeout is logged and force-cleared, so the exported
-`ShutdownTimeoutError` does not represent a current failure path.
+`ServiceReadyError`. Global shutdown timeout is logged and force-cleared.
 
 ## Testing through Interfaces
 
diff --git a/packages/process-compose/src/LogBuffer.ts b/packages/process-compose/src/LogBuffer.ts
index 53a247098c..b561d7e6fe 100644
--- a/packages/process-compose/src/LogBuffer.ts
+++ b/packages/process-compose/src/LogBuffer.ts
@@ -24,7 +24,6 @@ export class LogBuffer extends Context.Service<
       limit?: number,
       services?: ReadonlyArray<string>,
     ) => Effect.Effect<ReadonlyArray<LogEntry>>;
-    readonly truncate: (service: string) => Effect.Effect<void>;
   }
 >()("process-compose/LogBuffer") {
   static layer = Layer.effect(
@@ -97,15 +96,6 @@ export class LogBuffer extends Context.Service<
 
             return filtered.slice(-limit);
           }),
-
-        truncate: (service) =>
-          Effect.gen(function* () {
-            const { buffer } = yield* getOrCreate(service);
-            yield* Ref.set(buffer, []);
-            yield* Ref.update(globalBuffer, (entries) =>
-              entries.filter((entry) => entry.service !== service),
-            );
-          }),
       };
     }),
   );
diff --git a/packages/process-compose/src/LogBuffer.unit.test.ts b/packages/process-compose/src/LogBuffer.unit.test.ts
index b4e26774a8..c758785707 100644
--- a/packages/process-compose/src/LogBuffer.unit.test.ts
+++ b/packages/process-compose/src/LogBuffer.unit.test.ts
@@ -69,17 +69,6 @@ describe("LogBuffer", () => {
     }).pipe(Effect.provide(layer));
   });
 
-  it.live("truncate clears buffer", () =>
-    Effect.gen(function* () {
-      const log = yield* LogBuffer;
-      yield* log.append("svc", "stdout", "line1");
-      yield* log.append("svc", "stdout", "line2");
-      yield* log.truncate("svc");
-      const entries = yield* log.history("svc");
-      expect(entries).toHaveLength(0);
-    }).pipe(Effect.provide(layer)),
-  );
-
   it.live("subscribeAll receives entries from all services", () =>
     Effect.gen(function* () {
       const log = yield* LogBuffer;
diff --git a/packages/process-compose/src/Orchestrator.ts b/packages/process-compose/src/Orchestrator.ts
index 23c33ed6fd..6152a774bf 100644
--- a/packages/process-compose/src/Orchestrator.ts
+++ b/packages/process-compose/src/Orchestrator.ts
@@ -16,6 +16,7 @@ import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import { buildGraph, type ResolvedGraph } from "./DependencyGraph.ts";
 import { type HealthProbeCallbacks, runHealthProbe } from "./HealthProbe.ts";
 import { LogBuffer } from "./LogBuffer.ts";
+import { restartClosureFor } from "./RestartClosure.ts";
 import {
   decideRestart,
   type LifecycleCause,
@@ -41,6 +42,8 @@ import { type ServiceEvent, transition } from "./ServiceTransition.ts";
 
 const DIAGNOSTIC_LOG_LINES = 20;
 
+// Some one-shot adapters report `isRunning: false` before their exit-code Effect is observable.
+// Keep the compensating poll isolated here so the ordinary process-exit path remains event-driven.
 const waitForProcessToStop = (handle: {
   readonly isRunning: Effect.Effect<boolean, unknown, never>;
 }): Effect.Effect<void> =>
@@ -275,10 +278,10 @@ export class Orchestrator extends Context.Service<
 
                   // Release external resources such as port reservations only
                   // once dependencies are satisfied and spawning is imminent.
-                  // For supervised Docker services, this still leaves a wider
-                  // spawn-to-bind window because the supervisor starts before
-                  // the container binds its published ports. Closing that gap
-                  // would require an explicit supervisor/container handshake.
+                  // For supervised external processes, this can still leave a wider
+                  // spawn-to-bind window because the supervisor starts before its
+                  // child binds published ports. Closing that gap would require an
+                  // explicit supervisor/child handshake.
                   yield* options?.beforeSpawn?.(def.name) ?? Effect.void;
 
                   // Spawn the process
@@ -582,29 +585,30 @@ export class Orchestrator extends Context.Service<
             yield* sendEvent(name, { _tag: "ProcessExited", exitCode: 143 });
           });
 
-        const restartClosureFor = (name: string): ReadonlyArray<ServiceDef> => {
-          const names = new Set<string>([name]);
-          const visited = new Set<string>();
-          const collectDependents = (current: string): boolean => {
-            if (visited.has(current)) return names.has(current);
-            visited.add(current);
-            let hasActiveDependent = false;
-            for (const dependent of graph.dependentsOf(current)) {
-              const dependentService = services.get(dependent.name);
-              const dependentIsActive =
-                FiberMap.hasUnsafe(fibers, dependent.name) ||
-                (dependentService !== undefined &&
-                  SubscriptionRef.getUnsafe(dependentService.state).desired === "running");
-              const descendantIsActive = collectDependents(dependent.name);
-              if (dependentIsActive || descendantIsActive) {
-                names.add(dependent.name);
-                hasActiveDependent = true;
-              }
-            }
-            return hasActiveDependent;
-          };
-          collectDependents(name);
-          return graph.startOrder.filter((def) => names.has(def.name));
+        const restartClosure = (name: string): ReadonlyArray<ServiceDef> => {
+          const activeServices = new Set(
+            graph.startOrder
+              .filter((def) => {
+                const service = services.get(def.name);
+                return (
+                  FiberMap.hasUnsafe(fibers, def.name) ||
+                  (service !== undefined &&
+                    SubscriptionRef.getUnsafe(service.state).desired === "running")
+                );
+              })
+              .map((def) => def.name),
+          );
+          const closure = new Set(
+            restartClosureFor(
+              {
+                order: graph.startOrder.map((def) => def.name),
+                dependentsOf: (service) => graph.dependentsOf(service).map((def) => def.name),
+              },
+              name,
+              activeServices,
+            ),
+          );
+          return graph.startOrder.filter((def) => closure.has(def.name));
         };
 
         const waitReadySingle = (def: ServiceDef): Effect.Effect<void, ServiceReadyError> =>
@@ -821,7 +825,7 @@ export class Orchestrator extends Context.Service<
               if (lookupDef(name) === undefined) {
                 return yield* Effect.fail(new ServiceNotFoundError({ name }));
               }
-              const affected = restartClosureFor(name);
+              const affected = restartClosure(name);
               for (const affectedDef of [...affected].reverse()) {
                 yield* setDesired(affectedDef.name, "stopped");
                 yield* sendEvent(affectedDef.name, { _tag: "StopRequested" });
@@ -836,7 +840,7 @@ export class Orchestrator extends Context.Service<
               if (def === undefined) {
                 return yield* Effect.fail(new ServiceNotFoundError({ name }));
               }
-              const affected = restartClosureFor(name);
+              const affected = restartClosure(name);
 
               for (const affectedDef of [...affected].reverse()) {
                 yield* stopForRestart(affectedDef.name);
diff --git a/packages/process-compose/src/Orchestrator.unit.test.ts b/packages/process-compose/src/Orchestrator.unit.test.ts
index 515d6658cf..f2f272cd33 100644
--- a/packages/process-compose/src/Orchestrator.unit.test.ts
+++ b/packages/process-compose/src/Orchestrator.unit.test.ts
@@ -48,7 +48,6 @@ function mockLogBuffer() {
             line: entry.line,
           }));
         }),
-      truncate: () => Effect.void,
     }),
     get entries() {
       return entries;
@@ -455,11 +454,17 @@ describe("Orchestrator", () => {
 
   it.live("supervised services spawn the supervisor runtime", () => {
     const { layer, proc } = setupOrchestrator([
-      svc("postgres", {
-        command: "docker",
-        args: ["run", "--rm", "postgres"],
+      svc("database", {
+        command: "container-runtime",
+        args: ["run", "database"],
         supervision: {
-          orphanCleanup: [{ _tag: "DockerRemove", containerName: "supabase-postgres-test" }],
+          orphanCleanup: [
+            {
+              _tag: "RunCommand",
+              executable: "container-runtime",
+              args: ["remove", "database-test"],
+            },
+          ],
         },
       }),
     ]);
@@ -476,11 +481,17 @@ describe("Orchestrator", () => {
   it.live("stopping a supervisor during its spawn handshake cleans it up", () => {
     const { layer, proc } = setupOrchestrator(
       [
-        svc("postgres", {
-          command: "docker",
-          args: ["run", "--rm", "postgres"],
+        svc("database", {
+          command: "container-runtime",
+          args: ["run", "database"],
           supervision: {
-            orphanCleanup: [{ _tag: "DockerRemove", containerName: "supabase-postgres-test" }],
+            orphanCleanup: [
+              {
+                _tag: "RunCommand",
+                executable: "container-runtime",
+                args: ["remove", "database-test"],
+              },
+            ],
           },
         }),
       ],
@@ -488,10 +499,10 @@ describe("Orchestrator", () => {
     );
     return Effect.gen(function* () {
       const orc = yield* Orchestrator;
-      yield* orc.startService("postgres", { beforeSpawn: () => Effect.void });
+      yield* orc.startService("database", { beforeSpawn: () => Effect.void });
       yield* proc.waitForSpawnCount(1);
 
-      yield* orc.stopService("postgres");
+      yield* orc.stopService("database");
       yield* proc.waitForKillCount(1);
 
       expect(proc.killed[0]?.command).toBe(process.execPath);
diff --git a/packages/process-compose/src/RestartClosure.ts b/packages/process-compose/src/RestartClosure.ts
new file mode 100644
index 0000000000..2871e38fed
--- /dev/null
+++ b/packages/process-compose/src/RestartClosure.ts
@@ -0,0 +1,37 @@
+export interface RestartClosureGraph {
+  readonly order: ReadonlyArray<string>;
+  readonly dependentsOf: (name: string) => ReadonlyArray<string>;
+}
+
+/**
+ * Returns the requested service and every connector on a path to an active dependent.
+ * The result preserves dependency start order so callers can stop it in reverse safely.
+ */
+export const restartClosureFor = (
+  graph: RestartClosureGraph,
+  name: string,
+  activeServices: ReadonlySet<string>,
+): ReadonlyArray<string> => {
+  const closure = new Set<string>([name]);
+  const visited = new Set<string>();
+
+  const collectDependents = (current: string): boolean => {
+    if (visited.has(current)) {
+      return closure.has(current);
+    }
+    visited.add(current);
+
+    let connectsToActiveDependent = false;
+    for (const dependent of graph.dependentsOf(current)) {
+      const descendantConnectsToActive = collectDependents(dependent);
+      if (activeServices.has(dependent) || descendantConnectsToActive) {
+        closure.add(dependent);
+        connectsToActiveDependent = true;
+      }
+    }
+    return connectsToActiveDependent;
+  };
+
+  collectDependents(name);
+  return graph.order.filter((service) => closure.has(service));
+};
diff --git a/packages/process-compose/src/RestartClosure.unit.test.ts b/packages/process-compose/src/RestartClosure.unit.test.ts
new file mode 100644
index 0000000000..306d926c9b
--- /dev/null
+++ b/packages/process-compose/src/RestartClosure.unit.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import { restartClosureFor, type RestartClosureGraph } from "./RestartClosure.ts";
+
+const graph = (
+  order: ReadonlyArray<string>,
+  dependents: Readonly<Record<string, ReadonlyArray<string>>>,
+): RestartClosureGraph => ({
+  order,
+  dependentsOf: (name) => dependents[name] ?? [],
+});
+
+describe("restartClosureFor", () => {
+  const cases: ReadonlyArray<{
+    readonly name: string;
+    readonly graph: RestartClosureGraph;
+    readonly root: string;
+    readonly active: ReadonlyArray<string>;
+    readonly expected: ReadonlyArray<string>;
+  }> = [
+    {
+      name: "keeps only the requested service when no dependent is active",
+      graph: graph(["db", "api", "web"], { db: ["api"], api: ["web"] }),
+      root: "db",
+      active: [],
+      expected: ["db"],
+    },
+    {
+      name: "includes active direct dependents in dependency order",
+      graph: graph(["db", "api", "worker"], { db: ["api", "worker"] }),
+      root: "db",
+      active: ["worker", "api"],
+      expected: ["db", "api", "worker"],
+    },
+    {
+      name: "preserves inactive connectors leading to an active descendant",
+      graph: graph(["db", "gateway", "api", "web"], {
+        db: ["gateway"],
+        gateway: ["api"],
+        api: ["web"],
+      }),
+      root: "db",
+      active: ["web"],
+      expected: ["db", "gateway", "api", "web"],
+    },
+    {
+      name: "continues through active dependents to include active descendants",
+      graph: graph(["db", "api", "web"], { db: ["api"], api: ["web"] }),
+      root: "db",
+      active: ["api", "web"],
+      expected: ["db", "api", "web"],
+    },
+    {
+      name: "handles shared connectors without duplicating diamond nodes",
+      graph: graph(["db", "api", "worker", "web"], {
+        db: ["api", "worker"],
+        api: ["web"],
+        worker: ["web"],
+      }),
+      root: "db",
+      active: ["web"],
+      expected: ["db", "api", "worker", "web"],
+    },
+  ];
+
+  for (const testCase of cases) {
+    it(testCase.name, () => {
+      expect(restartClosureFor(testCase.graph, testCase.root, new Set(testCase.active))).toEqual(
+        testCase.expected,
+      );
+    });
+  }
+});
diff --git a/packages/process-compose/src/ServiceDef.ts b/packages/process-compose/src/ServiceDef.ts
index d015fcdae1..6cdc03150b 100644
--- a/packages/process-compose/src/ServiceDef.ts
+++ b/packages/process-compose/src/ServiceDef.ts
@@ -55,8 +55,10 @@ export interface LifecycleHook {
 
 export type ExternalCleanupAction =
   | {
-      readonly _tag: "DockerRemove";
-      readonly containerName: string;
+      readonly _tag: "RunCommand";
+      readonly executable: string;
+      readonly args: ReadonlyArray<string>;
+      readonly timeoutMs?: number;
     }
   | {
       readonly _tag: "RemovePath";
diff --git a/packages/process-compose/src/ServiceTransition.ts b/packages/process-compose/src/ServiceTransition.ts
index 228ca5e1ce..07135b5893 100644
--- a/packages/process-compose/src/ServiceTransition.ts
+++ b/packages/process-compose/src/ServiceTransition.ts
@@ -28,51 +28,43 @@ export type ServiceEvent =
   | { readonly _tag: "HookFailed"; readonly error: string };
 
 // ---------------------------------------------------------------------------
-// Transition table — set of (fromStatus, eventTag) pairs that are legal
+// Transition table — every event must classify its legal source statuses
 // ---------------------------------------------------------------------------
 
-const allowed = new Set<`${ServiceStatus}:${ServiceEvent["_tag"]}`>([
-  "Pending:DependenciesSatisfied",
-  "Pending:DependencyFailed",
-  "Pending:SpawnFailed",
-  "Pending:StopRequested",
-  "Starting:ProcessSpawned",
-  "Starting:SpawnFailed",
-  "Starting:StopRequested",
-  "Starting:HookFailed",
-  "Running:HealthCheckPassed",
-  "Running:HealthCheckFailed",
-  "Running:ProcessExited",
-  "Running:StopRequested",
-  "Healthy:HealthCheckPassed",
-  "Healthy:HealthCheckFailed",
-  "Healthy:ProcessExited",
-  "Healthy:StopRequested",
-  "Unhealthy:HealthCheckPassed",
-  "Unhealthy:ProcessExited",
-  "Unhealthy:ProcessTerminated",
-  "Unhealthy:StopRequested",
-  "Stopping:ProcessExited",
-  "Stopped:RestartTriggered",
-  "Failed:RestartTriggered",
-  "Failed:ProcessExited",
-  "Failed:StopRequested",
-  "Unhealthy:RestartTriggered",
-  "Unhealthy:UnhealthyRestartExhausted",
-  "Restarting:StopRequested",
-  "Restarting:SpawnFailed",
-  "Restarting:BackoffElapsed",
-  "Running:HookFailed",
-  "Healthy:HookFailed",
-]);
+type TransitionTable = {
+  readonly [Tag in ServiceEvent["_tag"]]: ReadonlySet<ServiceStatus>;
+};
+
+const transitions: TransitionTable = {
+  DependenciesSatisfied: new Set(["Pending"]),
+  DependencyFailed: new Set(["Pending"]),
+  SpawnFailed: new Set(["Pending", "Starting", "Restarting"]),
+  ProcessSpawned: new Set(["Starting"]),
+  HealthCheckPassed: new Set(["Running", "Healthy", "Unhealthy"]),
+  HealthCheckFailed: new Set(["Running", "Healthy"]),
+  ProcessTerminated: new Set(["Unhealthy"]),
+  UnhealthyRestartExhausted: new Set(["Unhealthy"]),
+  ProcessExited: new Set(["Running", "Healthy", "Unhealthy", "Stopping", "Failed"]),
+  StopRequested: new Set([
+    "Pending",
+    "Starting",
+    "Running",
+    "Healthy",
+    "Unhealthy",
+    "Restarting",
+    "Failed",
+  ]),
+  RestartTriggered: new Set(["Stopped", "Failed", "Unhealthy"]),
+  BackoffElapsed: new Set(["Restarting"]),
+  HookFailed: new Set(["Starting", "Running", "Healthy"]),
+};
 
 // ---------------------------------------------------------------------------
 // applyEvent — pure function, returns new ServiceState or null if invalid
 // ---------------------------------------------------------------------------
 
 export const applyEvent = (state: ServiceState, event: ServiceEvent): ServiceState | null => {
-  const key = `${state.status}:${event._tag}` as const;
-  if (!allowed.has(key)) return null;
+  if (!transitions[event._tag].has(state.status)) return null;
 
   switch (event._tag) {
     case "DependenciesSatisfied":
diff --git a/packages/process-compose/src/ServiceTransition.unit.test.ts b/packages/process-compose/src/ServiceTransition.unit.test.ts
index 6de22894a4..455c84887a 100644
--- a/packages/process-compose/src/ServiceTransition.unit.test.ts
+++ b/packages/process-compose/src/ServiceTransition.unit.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
-import { applyEvent } from "./ServiceTransition.ts";
-import { ServiceState, initial } from "./ServiceState.ts";
+import { applyEvent, type ServiceEvent } from "./ServiceTransition.ts";
+import { ServiceState, initial, type ServiceStatus } from "./ServiceState.ts";
 
 const make = (
   name: string,
@@ -19,6 +19,73 @@ const make = (
   });
 
 describe("ServiceTransition", () => {
+  it("classifies every event against every service status", () => {
+    const statuses: ReadonlyArray<ServiceStatus> = [
+      "Pending",
+      "Starting",
+      "Running",
+      "Healthy",
+      "Unhealthy",
+      "Stopping",
+      "Stopped",
+      "Failed",
+      "Restarting",
+    ];
+    const events: { readonly [Tag in ServiceEvent["_tag"]]: Extract<ServiceEvent, { _tag: Tag }> } =
+      {
+        DependenciesSatisfied: { _tag: "DependenciesSatisfied" },
+        DependencyFailed: { _tag: "DependencyFailed", error: "dependency failed" },
+        SpawnFailed: { _tag: "SpawnFailed", error: "spawn failed" },
+        ProcessSpawned: { _tag: "ProcessSpawned", pid: 1234, startedAt: 1000 },
+        HealthCheckPassed: { _tag: "HealthCheckPassed" },
+        HealthCheckFailed: { _tag: "HealthCheckFailed" },
+        ProcessTerminated: { _tag: "ProcessTerminated" },
+        UnhealthyRestartExhausted: {
+          _tag: "UnhealthyRestartExhausted",
+          error: "restart exhausted",
+        },
+        ProcessExited: { _tag: "ProcessExited", exitCode: 1 },
+        StopRequested: { _tag: "StopRequested" },
+        RestartTriggered: { _tag: "RestartTriggered", restartCount: 1 },
+        BackoffElapsed: { _tag: "BackoffElapsed" },
+        HookFailed: { _tag: "HookFailed", error: "hook failed" },
+      };
+    const legalStatuses: {
+      readonly [Tag in ServiceEvent["_tag"]]: ReadonlyArray<ServiceStatus>;
+    } = {
+      DependenciesSatisfied: ["Pending"],
+      DependencyFailed: ["Pending"],
+      SpawnFailed: ["Pending", "Starting", "Restarting"],
+      ProcessSpawned: ["Starting"],
+      HealthCheckPassed: ["Running", "Healthy", "Unhealthy"],
+      HealthCheckFailed: ["Running", "Healthy"],
+      ProcessTerminated: ["Unhealthy"],
+      UnhealthyRestartExhausted: ["Unhealthy"],
+      ProcessExited: ["Running", "Healthy", "Unhealthy", "Stopping", "Failed"],
+      StopRequested: [
+        "Pending",
+        "Starting",
+        "Running",
+        "Healthy",
+        "Unhealthy",
+        "Failed",
+        "Restarting",
+      ],
+      RestartTriggered: ["Unhealthy", "Stopped", "Failed"],
+      BackoffElapsed: ["Restarting"],
+      HookFailed: ["Starting", "Running", "Healthy"],
+    };
+
+    for (const event of Object.values(events)) {
+      for (const status of statuses) {
+        const state = make("service", { status, pid: 1234 });
+        expect(applyEvent(state, event) !== null, `${status} + ${event._tag}`).toBe(
+          legalStatuses[event._tag].includes(status),
+        );
+      }
+    }
+  });
+
   describe("valid transitions", () => {
     it("Pending + DependenciesSatisfied → Starting", () => {
       const state = make("db");
diff --git a/packages/process-compose/src/SupervisorRuntime.unit.test.ts b/packages/process-compose/src/SupervisorRuntime.unit.test.ts
index 77b7b61b5d..ce4fee52d5 100644
--- a/packages/process-compose/src/SupervisorRuntime.unit.test.ts
+++ b/packages/process-compose/src/SupervisorRuntime.unit.test.ts
@@ -2,10 +2,38 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { describe, test } from "vitest";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { describe, expect, test } from "vitest";
+import { makeSupervisorRuntimeEnv, withoutSupervisorRuntimeEnv } from "./supervisor-protocol.ts";
 
 const supervisorRuntimePath = fileURLToPath(new URL("./supervisor-runtime.ts", import.meta.url));
+const supervisorProtocolPath = fileURLToPath(new URL("./supervisor-protocol.ts", import.meta.url));
+
+type SupervisorEntry = "source path" | "compiled self-dispatch";
+
+const spawnSupervisor = (entry: SupervisorEntry, encodedConfig: string) => {
+  if (entry === "source path") {
+    return spawn(process.execPath, [supervisorRuntimePath, encodedConfig], {
+      stdio: ["pipe", "ignore", "ignore"],
+    });
+  }
+
+  const runtimeUrl = pathToFileURL(supervisorRuntimePath).href;
+  const protocolUrl = pathToFileURL(supervisorProtocolPath).href;
+  const dispatch = [
+    `import { runSupervisorRuntimeFromEnv } from ${JSON.stringify(runtimeUrl)};`,
+    `import { isSupervisorRuntimeRequested } from ${JSON.stringify(protocolUrl)};`,
+    `if (!isSupervisorRuntimeRequested()) throw new Error("supervisor dispatch not requested");`,
+    `runSupervisorRuntimeFromEnv();`,
+  ].join("\n");
+  return spawn(process.execPath, ["--eval", dispatch], {
+    env: makeSupervisorRuntimeEnv(encodedConfig, {
+      ...process.env,
+      PROCESS_COMPOSE_SUPERVISOR_SELF_DISPATCH: "1",
+    }),
+    stdio: ["pipe", "ignore", "ignore"],
+  });
+};
 
 const waitFor = async (
   predicate: () => boolean,
@@ -39,12 +67,13 @@ const isPidAlive = (pid: number): boolean => {
 };
 
 describe("supervisor-runtime", () => {
-  test(
-    "kills the child tree and runs orphan cleanup when parent stdin closes",
+  test.each<SupervisorEntry>(["source path", "compiled self-dispatch"])(
+    "%s kills the child tree and runs validated orphan cleanup when parent stdin closes",
     { timeout: 15_000 },
-    async () => {
+    async (entry) => {
       const tempDir = mkdtempSync(path.join(tmpdir(), "process-compose-supervisor-"));
       const cleanupDir = path.join(tempDir, "cleanup-dir");
+      const cleanupMarker = path.join(tempDir, "cleanup-command-ran");
       const childPidFile = path.join(tempDir, "child.pid");
       const grandchildPidFile = path.join(tempDir, "grandchild.pid");
       const readyFile = path.join(tempDir, "ready");
@@ -72,13 +101,23 @@ describe("supervisor-runtime", () => {
           args: [childScriptPath],
           shutdownSignal: "SIGTERM",
           shutdownTimeoutMs: 100,
-          cleanup: [{ _tag: "RemovePath", path: cleanupDir, recursive: true }],
+          cleanup: [
+            { _tag: "RemovePath", path: cleanupDir, recursive: true },
+            {
+              _tag: "RunCommand",
+              executable: process.execPath,
+              args: [
+                "-e",
+                `require("node:fs").writeFileSync(process.argv[1], process.argv[2])`,
+                cleanupMarker,
+                "literal; $(not-run) & value",
+              ],
+            },
+          ],
         }),
       ).toString("base64url");
 
-      const supervisor = spawn(process.execPath, [supervisorRuntimePath, encodedConfig], {
-        stdio: ["pipe", "ignore", "ignore"],
-      });
+      const supervisor = spawnSupervisor(entry, encodedConfig);
 
       try {
         await waitFor(() => existsSync(readyFile));
@@ -90,6 +129,8 @@ describe("supervisor-runtime", () => {
 
         await waitFor(() => supervisor.exitCode != null, { timeoutMs: 10_000 });
         await waitFor(() => !existsSync(cleanupDir), { timeoutMs: 10_000 });
+        await waitFor(() => existsSync(cleanupMarker), { timeoutMs: 10_000 });
+        expect(readFileSync(cleanupMarker, "utf8")).toBe("literal; $(not-run) & value");
         await waitFor(() => !isPidAlive(childPid), { timeoutMs: 10_000 });
         await waitFor(() => !isPidAlive(grandchildPid), { timeoutMs: 10_000 });
       } finally {
@@ -99,6 +140,83 @@ describe("supervisor-runtime", () => {
     },
   );
 
+  test.each([
+    [
+      "non-string command argument",
+      { _tag: "RunCommand", executable: process.execPath, args: [42] },
+    ],
+    ["empty executable", { _tag: "RunCommand", executable: "", args: [] }],
+    [
+      "non-positive timeout",
+      { _tag: "RunCommand", executable: process.execPath, args: [], timeoutMs: 0 },
+    ],
+    ["invalid path option", { _tag: "RemovePath", path: "/tmp/example", recursive: "yes" }],
+  ])("rejects a malformed cleanup contract with %s before spawning", async (_name, cleanup) => {
+    const tempDir = mkdtempSync(path.join(tmpdir(), "process-compose-supervisor-invalid-"));
+    const childMarker = path.join(tempDir, "child-started");
+    const encodedConfig = Buffer.from(
+      JSON.stringify({
+        command: process.execPath,
+        args: ["-e", `require("node:fs").writeFileSync(${JSON.stringify(childMarker)}, "started")`],
+        cleanup: [cleanup],
+      }),
+    ).toString("base64url");
+    const supervisor = spawnSupervisor("source path", encodedConfig);
+
+    try {
+      await waitFor(() => supervisor.exitCode != null);
+      expect(supervisor.exitCode).not.toBe(0);
+      expect(existsSync(childMarker)).toBe(false);
+    } finally {
+      supervisor.kill("SIGKILL");
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  test("removes supervisor protocol variables from the managed child environment", () => {
+    const childEnv = withoutSupervisorRuntimeEnv({
+      KEEP_ME: "value",
+      PROCESS_COMPOSE_SUPERVISOR_SELF_DISPATCH: "1",
+      PROCESS_COMPOSE_RUN_SUPERVISOR: "1",
+      PROCESS_COMPOSE_SUPERVISOR_CONFIG: "encoded",
+    });
+
+    expect(childEnv).toEqual({ KEEP_ME: "value" });
+  });
+
+  test("bounds a cleanup command by its timeout and continues remaining cleanup", async () => {
+    const tempDir = mkdtempSync(path.join(tmpdir(), "process-compose-supervisor-timeout-"));
+    const cleanupDir = path.join(tempDir, "cleanup-dir");
+    const childScriptPath = path.join(tempDir, "child.mjs");
+    mkdirSync(cleanupDir);
+    writeFileSync(childScriptPath, "process.exit(0);\n");
+    const encodedConfig = Buffer.from(
+      JSON.stringify({
+        command: process.execPath,
+        args: [childScriptPath],
+        cleanup: [
+          {
+            _tag: "RunCommand",
+            executable: process.execPath,
+            args: ["-e", "setInterval(() => {}, 1000)"],
+            timeoutMs: 100,
+          },
+          { _tag: "RemovePath", path: cleanupDir, recursive: true },
+        ],
+      }),
+    ).toString("base64url");
+    const supervisor = spawnSupervisor("source path", encodedConfig);
+
+    try {
+      await waitFor(() => supervisor.exitCode != null);
+      expect(supervisor.exitCode).toBe(0);
+      expect(existsSync(cleanupDir)).toBe(false);
+    } finally {
+      supervisor.kill("SIGKILL");
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
   test(
     "runs orphan cleanup when the configured owner pid is already gone",
     { timeout: 15_000 },
diff --git a/packages/process-compose/src/errors.ts b/packages/process-compose/src/errors.ts
index 44bde7ff2b..65dc4ea66f 100644
--- a/packages/process-compose/src/errors.ts
+++ b/packages/process-compose/src/errors.ts
@@ -18,10 +18,6 @@ export class SpawnError extends Data.TaggedError("SpawnError")<{
   readonly cause: unknown;
 }> {}
 
-export class ShutdownTimeoutError extends Data.TaggedError("ShutdownTimeoutError")<{
-  readonly service: string;
-}> {}
-
 export class ServiceReadyError extends Data.TaggedError("ServiceReadyError")<{
   readonly name: string;
   readonly reason: string;
diff --git a/packages/process-compose/src/errors.unit.test.ts b/packages/process-compose/src/errors.unit.test.ts
index b2c2920595..073e5279f0 100644
--- a/packages/process-compose/src/errors.unit.test.ts
+++ b/packages/process-compose/src/errors.unit.test.ts
@@ -4,7 +4,6 @@ import {
   MissingDependencyError,
   ServiceNotFoundError,
   SpawnError,
-  ShutdownTimeoutError,
 } from "./errors.ts";
 
 describe("errors", () => {
@@ -34,10 +33,4 @@ describe("errors", () => {
     expect(err.service).toBe("postgres");
     expect(err.cause).toBe(cause);
   });
-
-  it("ShutdownTimeoutError has correct tag and data", () => {
-    const err = new ShutdownTimeoutError({ service: "postgres" });
-    expect(err._tag).toBe("ShutdownTimeoutError");
-    expect(err.service).toBe("postgres");
-  });
 });
diff --git a/packages/process-compose/src/index.ts b/packages/process-compose/src/index.ts
index 609f5db891..421763613f 100644
--- a/packages/process-compose/src/index.ts
+++ b/packages/process-compose/src/index.ts
@@ -25,7 +25,6 @@ export {
   ServiceNotFoundError,
   ServiceReadyError,
   SpawnError,
-  ShutdownTimeoutError,
 } from "./errors.ts";
 
 export type { LogEntry } from "./LogBuffer.ts";
diff --git a/packages/process-compose/src/supervisor-runtime.ts b/packages/process-compose/src/supervisor-runtime.ts
index 302961ffdf..3069796d54 100644
--- a/packages/process-compose/src/supervisor-runtime.ts
+++ b/packages/process-compose/src/supervisor-runtime.ts
@@ -104,16 +104,35 @@ const cleanupActionFrom = (value: unknown): ExternalCleanupAction | undefined =>
   }
 
   const tag = getField(value, "_tag");
-  if (tag === "DockerRemove") {
-    const containerName = getField(value, "containerName");
-    return typeof containerName === "string" ? { _tag: tag, containerName } : undefined;
+  if (tag === "RunCommand") {
+    const executable = getField(value, "executable");
+    const args = stringArrayFrom(getField(value, "args"));
+    const timeoutMs = getField(value, "timeoutMs");
+    if (
+      typeof executable !== "string" ||
+      executable.length === 0 ||
+      args === undefined ||
+      (timeoutMs !== undefined &&
+        (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0))
+    ) {
+      return undefined;
+    }
+    return {
+      _tag: tag,
+      executable,
+      args,
+      timeoutMs: typeof timeoutMs === "number" ? timeoutMs : undefined,
+    };
   }
 
   if (tag === "RemovePath") {
     const path = getField(value, "path");
     const recursive = getField(value, "recursive");
     const force = getField(value, "force");
-    return typeof path === "string"
+    return typeof path === "string" &&
+      path.length > 0 &&
+      (recursive === undefined || typeof recursive === "boolean") &&
+      (force === undefined || typeof force === "boolean")
       ? {
           _tag: tag,
           path,
@@ -148,6 +167,11 @@ const parseSupervisorRuntimeConfig = (encodedConfig: string): SupervisorRuntimeC
 
   const ownerPid = getField(value, "ownerPid");
   const shutdownTimeoutMs = getField(value, "shutdownTimeoutMs");
+  const cleanupValue = getField(value, "cleanup");
+  const cleanup = cleanupValue === undefined ? undefined : cleanupActionsFrom(cleanupValue);
+  if (cleanupValue !== undefined && cleanup === undefined) {
+    throw new Error("Invalid supervisor cleanup");
+  }
 
   return {
     command,
@@ -155,7 +179,7 @@ const parseSupervisorRuntimeConfig = (encodedConfig: string): SupervisorRuntimeC
     ownerPid: typeof ownerPid === "number" ? ownerPid : undefined,
     shutdownSignal: signalFrom(getField(value, "shutdownSignal")),
     shutdownTimeoutMs: typeof shutdownTimeoutMs === "number" ? shutdownTimeoutMs : undefined,
-    cleanup: cleanupActionsFrom(getField(value, "cleanup")),
+    cleanup,
   };
 };
 
@@ -252,10 +276,10 @@ export function runSupervisorRuntime(encodedConfig = process.argv[2]): void {
     return Promise.all(
       (config.cleanup ?? []).map(async (action) => {
         try {
-          if (action._tag === "DockerRemove") {
-            execFileSync("docker", ["rm", "-f", action.containerName], {
+          if (action._tag === "RunCommand") {
+            execFileSync(action.executable, action.args, {
               stdio: "ignore",
-              timeout: 5_000,
+              timeout: action.timeoutMs,
             });
           } else if (action._tag === "RemovePath") {
             await removePathWithRetry(action);
diff --git a/packages/stack/src/services/docker-cleanup.ts b/packages/stack/src/services/docker-cleanup.ts
index b3673a1b61..c96c7af6b9 100644
--- a/packages/stack/src/services/docker-cleanup.ts
+++ b/packages/stack/src/services/docker-cleanup.ts
@@ -14,7 +14,14 @@ export const dockerServiceCleanup = (containerName: string): Effect.Effect<void>
 
 export const dockerServiceOrphanCleanup = (
   containerName: string,
-): ReadonlyArray<ExternalCleanupAction> => [{ _tag: "DockerRemove", containerName }];
+): ReadonlyArray<ExternalCleanupAction> => [
+  {
+    _tag: "RunCommand",
+    executable: "docker",
+    args: ["rm", "-f", containerName],
+    timeoutMs: 5_000,
+  },
+];
 
 export const removePathOnOrphanCleanup = (
   path: string,
diff --git a/packages/stack/src/services/service-utils.ts b/packages/stack/src/services/service-utils.ts
index eabb31cd5e..4259ed02f7 100644
--- a/packages/stack/src/services/service-utils.ts
+++ b/packages/stack/src/services/service-utils.ts
@@ -1,4 +1,4 @@
-import type { ServiceDef } from "@supabase/process-compose";
+import type { ExternalCleanupAction, ServiceDef } from "@supabase/process-compose";
 import { dockerServiceCleanup, dockerServiceOrphanCleanup } from "./docker-cleanup.ts";
 
 export interface ServiceDependency {
@@ -20,7 +20,7 @@ interface DockerRunServiceOptions {
   readonly healthCheck?: ServiceDef["healthCheck"];
   readonly restart?: ServiceDef["restart"];
   readonly shutdown?: ServiceDef["shutdown"];
-  readonly orphanCleanup?: ReadonlyArray<any>;
+  readonly orphanCleanup?: ReadonlyArray<ExternalCleanupAction>;
 }
 
 const envArgs = (env: Record<string, string>): ReadonlyArray<string> =>
diff --git a/packages/stack/src/services/services.unit.test.ts b/packages/stack/src/services/services.unit.test.ts
index 2db96bb9af..2c5b887999 100644
--- a/packages/stack/src/services/services.unit.test.ts
+++ b/packages/stack/src/services/services.unit.test.ts
@@ -200,7 +200,14 @@ describe("makePostgresServiceDocker", () => {
     expect(def.dependencies).toBeUndefined();
     expect(def.restart).toBe("unless-stopped");
     expect(def.supervision).toEqual({
-      orphanCleanup: [{ _tag: "DockerRemove", containerName: `supabase-postgres-${API_PORT}` }],
+      orphanCleanup: [
+        {
+          _tag: "RunCommand",
+          executable: "docker",
+          args: ["rm", "-f", `supabase-postgres-${API_PORT}`],
+          timeoutMs: 5_000,
+        },
+      ],
     });
   });
 
@@ -313,7 +320,14 @@ describe("makeAuthServiceDocker", () => {
     expect(def.args).toContain("9999:9999");
     expect(def.dependencies).toEqual([{ service: "postgres", condition: "healthy" }]);
     expect(def.supervision).toEqual({
-      orphanCleanup: [{ _tag: "DockerRemove", containerName: `supabase-auth-${API_PORT}` }],
+      orphanCleanup: [
+        {
+          _tag: "RunCommand",
+          executable: "docker",
+          args: ["rm", "-f", `supabase-auth-${API_PORT}`],
+          timeoutMs: 5_000,
+        },
+      ],
     });
   });
 });

From 3e5662291a7110de86173d7669fda51e4412146d Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 15:32:48 +0200
Subject: [PATCH 05/44] refactor(stack): consolidate local lifecycle ownership

---
 packages/stack/README.md                      |  24 +-
 packages/stack/docs/architecture.md           |  27 +-
 packages/stack/docs/detach-mode.md            |  14 +-
 packages/stack/src/DaemonProtocol.ts          |   2 +
 .../src/DaemonServer.integration.test.ts      |  57 +-
 packages/stack/src/DaemonServer.ts            |  72 +-
 packages/stack/src/LocalStack.ts              | 897 ++++++++++++++++++
 .../stack/src/RemoteStack.integration.test.ts |  62 +-
 packages/stack/src/RemoteStack.ts             |  38 +-
 packages/stack/src/ServiceActivation.ts       |   8 +-
 packages/stack/src/Stack.ts                   |  77 +-
 packages/stack/src/Stack.unit.test.ts         | 290 ++++--
 packages/stack/src/StackConfig.ts             |  17 +
 packages/stack/src/StackConfig.unit.test.ts   |  21 +
 .../stack/src/StackLifecycleCoordinator.ts    | 880 -----------------
 packages/stack/src/createStack.ts             |  27 +-
 packages/stack/src/effect.ts                  |   1 +
 packages/stack/src/errors.ts                  |  12 +
 packages/stack/src/layers.ts                  |  38 +-
 19 files changed, 1433 insertions(+), 1131 deletions(-)
 create mode 100644 packages/stack/src/LocalStack.ts
 delete mode 100644 packages/stack/src/StackLifecycleCoordinator.ts

diff --git a/packages/stack/README.md b/packages/stack/README.md
index 50dd10f464..321d60d988 100644
--- a/packages/stack/README.md
+++ b/packages/stack/README.md
@@ -209,7 +209,10 @@ In eager mode, `start()` blocks until every enabled service is ready. In lazy mo
 for direct listeners and services activated so far. Unrequested lazy services report `Dormant`.
 Calling `serviceReady()` for a dormant lazy
 service fails immediately; activate it through the proxy or call `startService()` first. Foreground
-and detached stacks use the same readiness rules.
+and detached stacks use the same readiness rules. The configured policy also applies to service
+start, restart, activation, and reload operations; a call-specific option overrides it. A finite
+deadline fails with `STACK_READINESS_TIMEOUT` and disposes the local runtime, so the handle cannot
+be used to relaunch processes afterward.
 
 ### Status
 
@@ -308,15 +311,16 @@ try {
 }
 ```
 
-| Code                | Description                                  |
-| ------------------- | -------------------------------------------- |
-| `SERVICE_NOT_FOUND` | Referenced a service that doesn't exist      |
-| `SERVICE_NOT_READY` | Service failed to become healthy             |
-| `BUILD_ERROR`       | Failed to build the service dependency graph |
-| `BINARY_NOT_FOUND`  | No binary available for the current platform |
-| `DOWNLOAD_ERROR`    | Binary download failed                       |
-| `PORT_CONFLICT`     | Requested port is already in use             |
-| `PORT_ALLOCATION`   | Failed to allocate a free port               |
+| Code                      | Description                                  |
+| ------------------------- | -------------------------------------------- |
+| `SERVICE_NOT_FOUND`       | Referenced a service that doesn't exist      |
+| `SERVICE_NOT_READY`       | Service failed to become healthy             |
+| `STACK_READINESS_TIMEOUT` | Stack readiness exceeded its finite deadline |
+| `BUILD_ERROR`             | Failed to build the service dependency graph |
+| `BINARY_NOT_FOUND`        | No binary available for the current platform |
+| `DOWNLOAD_ERROR`          | Binary download failed                       |
+| `PORT_CONFLICT`           | Requested port is already in use             |
+| `PORT_ALLOCATION`         | Failed to allocate a free port               |
 
 ## Examples
 
diff --git a/packages/stack/docs/architecture.md b/packages/stack/docs/architecture.md
index 336964d1d2..4ce734db24 100644
--- a/packages/stack/docs/architecture.md
+++ b/packages/stack/docs/architecture.md
@@ -51,8 +51,10 @@ functions options, and per-service configuration. `false` disables an optional s
 Readiness policy is part of the resolved configuration. The package default is a finite two-minute
 deadline; callers can choose a different finite deadline or explicit infinite waiting. Per-call
 `ReadyOptions` take precedence over the stack policy, while `inherit` delegates to the stack
-policy. The Promise `ready()` / `serviceReady()` Adapter applies that resolver today. The Effect
-lifecycle Interface remains unbounded until deadline enforcement is centralized there.
+policy. The local Implementation applies this resolver to startup, service activation, restart,
+reload, and explicit readiness waits. A finite deadline fails with `StackReadinessError` and runs
+the same scoped cleanup used by disposal. Promise and remote Adapters pass `ReadyOptions` through
+to that Implementation instead of layering a second timeout rule around it.
 
 The current zero-config stack enables PostgreSQL, PostgREST, Auth, and Edge Runtime. Realtime,
 Storage, imgproxy, Mailpit, Postgres Meta, Studio, Analytics, Vector, and Supavisor are enabled only
@@ -119,7 +121,7 @@ Vector without Analytics, and Studio without Postgres Meta.
 
 ## Lifecycle ownership
 
-The current local Implementation is `StackLifecycleCoordinator`. It owns one scoped lifecycle:
+The local Implementation is `LocalStack`. Its scoped layer owns one lifecycle:
 
 - preparation and its single-flight deferred;
 - graph construction and the process-compose runtime;
@@ -129,19 +131,21 @@ The current local Implementation is `StackLifecycleCoordinator`. It owns one sco
 - exact cleanup targets and metadata persistence;
 - disposal of processes, Docker resources, ports, and auto-managed paths.
 
-`Stack.ts` currently provides a thin public Effect Interface over that coordinator. `ApiProxy`
-uses the narrower `StackServiceActivator` Interface so an incoming request can activate a lazy
-backend without gaining unrelated lifecycle operations.
+`Stack.ts` contains only the public Effect Interface and transport schemas. `LocalStack` constructs
+the state once and publishes both `Stack` and the narrower `StackServiceActivator` Interface from
+the same scoped layer. `ApiProxy` therefore activates a lazy backend without gaining unrelated
+lifecycle operations or requiring a second pass-through lifecycle tag.
 
-Before the orchestrator exists, the coordinator publishes synthetic `Pending` and `Downloading`
+Before the orchestrator exists, `LocalStack` publishes synthetic `Pending` and `Downloading`
 states. After construction, it subscribes to raw process-compose state and publishes only public
 projected states. `StackServiceState` adds `Downloading`, `Initializing`, and `Dormant` to the raw
 process statuses.
 
 `start()` prepares artifacts, creates the runtime once, starts the appropriate services, and waits
 for their generic process-compose readiness. `stop()` preserves explicit per-service stop intent;
-`dispose()` additionally closes the scoped runtime and executes cleanup. Generic process-compose
-readiness remains intentionally policy-free and unbounded.
+`dispose()` additionally closes the scoped runtime and executes cleanup. Stack readiness policy is
+enforced around generic process-compose waits, which remain intentionally policy-free and
+unbounded. Structural `Equal.equals` comparison suppresses duplicate projected state emissions.
 
 ## Eager and lazy activation
 
@@ -237,8 +241,9 @@ Detached mode adds:
 - `StateManager`: atomically persists and discovers durable metadata and live state.
 
 The management transport includes health, status, status stream, start/stop, readiness,
-per-service lifecycle, logs/history, and Edge Runtime reload routes. It is local Unix-socket
-transport, not the public Supabase API proxy.
+per-service lifecycle, logs/history, and Edge Runtime reload routes. Readiness waits use validated
+`ReadyOptions` JSON bodies and preserve `StackReadinessError` across the transport. It is local
+Unix-socket transport, not the public Supabase API proxy.
 
 See [detach mode](./detach-mode.md) for paths, process startup, and compiled executable dispatch.
 
diff --git a/packages/stack/docs/detach-mode.md b/packages/stack/docs/detach-mode.md
index 812c8e861a..e288a7e5a1 100644
--- a/packages/stack/docs/detach-mode.md
+++ b/packages/stack/docs/detach-mode.md
@@ -114,14 +114,16 @@ metadata and service data remain.
 `DaemonServer` exposes the local `Stack` Interface on the Unix socket. Current routes include:
 
 - `/health`, `/status`, and `/status/stream`;
-- `/start`, `/stop`, and `/ready`;
+- `/start`, `/stop`, and `POST /ready`;
 - per-service start, stop, restart, and readiness;
 - merged and per-service live logs plus buffered history;
 - functions and Edge Runtime reload.
 
-State and log streams use SSE. Ordinary responses and typed failures use validated JSON shapes.
-`RemoteStack` decodes that transport back into the same Effect `Stack` Interface used in
-foreground mode, including `ServiceNotFoundError`, `ServiceReadyError`, and `StackBuildError`.
+State and log streams use SSE. Readiness routes use `POST` with a validated readiness-policy body;
+omitting an override sends the explicit `inherit` representation. Ordinary responses and typed
+failures use validated JSON shapes. `RemoteStack` decodes that transport back into the same Effect
+`Stack` Interface used in foreground mode, including `ServiceNotFoundError`, `ServiceReadyError`,
+`StackBuildError`, and `StackReadinessError`.
 
 The management socket is not the public local API endpoint. `ApiProxy` still owns the configured
 HTTP API port inside the daemon process.
@@ -141,6 +143,10 @@ package. In particular:
 On normal `/stop`, the daemon gracefully stops the stack, signals HTTP shutdown after the response
 has had time to flush, disposes both managed runtimes, and removes live state/runtime paths.
 
+A readiness deadline is terminal for that local runtime: the stack disposes its scoped resources,
+the daemon returns the typed timeout response, and then the daemon shuts down. This prevents later
+requests from relaunching processes after cleanup has already run.
+
 If the daemon has died, CLI stop/status detects a stale PID. Stop can use cleanup targets persisted
 in `stack.json` to force-remove known Docker containers before removing the stale state. This
 crash-recovery metadata is deliberately separate from user-facing `/status` connection data.
diff --git a/packages/stack/src/DaemonProtocol.ts b/packages/stack/src/DaemonProtocol.ts
index 7bfdf9fb94..88262482cb 100644
--- a/packages/stack/src/DaemonProtocol.ts
+++ b/packages/stack/src/DaemonProtocol.ts
@@ -4,6 +4,7 @@ import { StackStateSchema } from "./StateManager.ts";
 const DaemonErrorCodeSchema = Schema.Literals([
   "SERVICE_NOT_FOUND",
   "SERVICE_NOT_READY",
+  "STACK_READINESS_TIMEOUT",
   "STACK_BUILD_ERROR",
 ]);
 
@@ -12,6 +13,7 @@ export const DaemonErrorResponseSchema = Schema.Struct({
   error: Schema.String,
   service: Schema.optionalKey(Schema.String),
   exitCode: Schema.optionalKey(Schema.Number),
+  timeoutMs: Schema.optionalKey(Schema.Number),
 });
 
 export type DaemonErrorResponse = typeof DaemonErrorResponseSchema.Type;
diff --git a/packages/stack/src/DaemonServer.integration.test.ts b/packages/stack/src/DaemonServer.integration.test.ts
index e16ec4ac7f..1cb2227f68 100644
--- a/packages/stack/src/DaemonServer.integration.test.ts
+++ b/packages/stack/src/DaemonServer.integration.test.ts
@@ -4,6 +4,7 @@ import { Effect, Layer, ManagedRuntime, Stream } from "effect";
 import * as http from "node:http";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { DaemonServer } from "./DaemonServer.ts";
+import { StackReadinessError } from "./errors.ts";
 import { Stack, type StackInfo } from "./Stack.ts";
 import { StackServiceState } from "./StackServiceState.ts";
 
@@ -53,13 +54,22 @@ const MOCK_LOGS: ReadonlyArray<LogEntry> = [
 // Mock Stack
 // ---------------------------------------------------------------------------
 
-function mockStack() {
+function mockStack(options: { readonly startTimeoutMs?: number } = {}) {
   let stopped = false;
   const serviceCalls: string[] = [];
 
   const layer = Layer.succeed(Stack, {
     getInfo: () => Effect.succeed(MOCK_INFO),
-    start: () => Effect.void,
+    start: () =>
+      options.startTimeoutMs === undefined
+        ? Effect.void
+        : Effect.fail(
+            new StackReadinessError({
+              target: "stack",
+              timeoutMs: options.startTimeoutMs,
+              detail: `Timed out waiting for stack readiness after ${options.startTimeoutMs}ms`,
+            }),
+          ),
     stop: () =>
       Effect.sync(() => {
         stopped = true;
@@ -321,6 +331,29 @@ describe("DaemonServer", () => {
     expect(mock.serviceCalls).toContain("restart:postgres");
   });
 
+  test("POST readiness routes validate the shared override representation", async () => {
+    const stackReady = await fetch(`${url}/ready`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ mode: "inherit" }),
+    });
+    expect(stackReady.status).toBe(200);
+
+    const serviceReady = await fetch(`${url}/services/postgres/ready`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ mode: "finite", timeoutMs: 100 }),
+    });
+    expect(serviceReady.status).toBe(200);
+
+    const malformed = await fetch(`${url}/ready`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ mode: "finite", timeoutMs: 0 }),
+    });
+    expect(malformed.status).not.toBe(200);
+  });
+
   test("POST /edge-runtime/reload returns 200", async () => {
     const res = await fetch(`${url}/edge-runtime/reload`, {
       method: "POST",
@@ -358,6 +391,26 @@ describe("DaemonServer", () => {
     expect(body.error).toContain("unknown");
   });
 
+  test("a startup readiness timeout returns the typed failure and shuts down the daemon", async () => {
+    const freshRuntime = ManagedRuntime.make(buildDaemonLayer(mockStack({ startTimeoutMs: 75 })));
+    try {
+      const daemon = await freshRuntime.runPromise(DaemonServer);
+      const shutdownPromise = freshRuntime.runPromise(daemon.awaitShutdown);
+      const response = await fetch(`${getUrl(daemon.address)}/start`, { method: "POST" });
+
+      expect(response.status).toBe(500);
+      expect(await response.json()).toEqual({
+        code: "STACK_READINESS_TIMEOUT",
+        error: "Timed out waiting for stack readiness after 75ms",
+        service: "stack",
+        timeoutMs: 75,
+      });
+      await shutdownPromise;
+    } finally {
+      await freshRuntime.dispose();
+    }
+  });
+
   // -------------------------------------------------------------------------
   // Stop (tested last since it modifies daemon state)
   // -------------------------------------------------------------------------
diff --git a/packages/stack/src/DaemonServer.ts b/packages/stack/src/DaemonServer.ts
index 638029c885..4900fcba8c 100644
--- a/packages/stack/src/DaemonServer.ts
+++ b/packages/stack/src/DaemonServer.ts
@@ -9,6 +9,7 @@ import {
 import * as Sse from "effect/unstable/encoding/Sse";
 import type { DaemonErrorResponse } from "./DaemonProtocol.ts";
 import { EdgeRuntimeReloadConfigSchema, Stack } from "./Stack.ts";
+import { ReadyOptionsSchema } from "./StackConfig.ts";
 
 // ---------------------------------------------------------------------------
 // Service
@@ -50,6 +51,29 @@ export class DaemonServer extends Context.Service<
           );
         const buildErrorResponse = (detail: string) =>
           errorResponse({ code: "STACK_BUILD_ERROR", error: detail }, 500);
+        const readinessTimeoutResponse = (target: string, timeoutMs: number, detail: string) =>
+          errorResponse(
+            {
+              code: "STACK_READINESS_TIMEOUT",
+              error: detail,
+              service: target,
+              timeoutMs,
+            },
+            500,
+          );
+        const beginShutdown = beforeShutdown.pipe(
+          Effect.ensuring(
+            // The HTTP module has no response-flushed hook. Delay the process
+            // shutdown signal long enough for the final JSON response to leave
+            // the socket.
+            Deferred.succeed(shutdownDeferred, void 0).pipe(
+              Effect.delay("25 millis"),
+              Effect.forkDetach,
+            ),
+          ),
+        );
+        const terminalReadinessResponse = (target: string, timeoutMs: number, detail: string) =>
+          beginShutdown.pipe(Effect.as(readinessTimeoutResponse(target, timeoutMs, detail)));
 
         // Helper: wrap an Effect Stream as a text/event-stream response
         const sseResponse = <A>(
@@ -113,20 +137,29 @@ export class DaemonServer extends Context.Service<
               Effect.catchTag("StackBuildError", (e) =>
                 Effect.succeed(buildErrorResponse(e.detail)),
               ),
+              Effect.catchTag("StackReadinessError", (e) =>
+                terminalReadinessResponse(e.target, e.timeoutMs, e.detail),
+              ),
             ),
           ),
 
           HttpRouter.route(
-            "GET",
+            "POST",
             "/ready",
-            stack.waitAllReady().pipe(
-              Effect.as(HttpServerResponse.jsonUnsafe({ ok: true })),
+            Effect.gen(function* () {
+              const opts = yield* HttpServerRequest.schemaBodyJson(ReadyOptionsSchema);
+              yield* stack.waitAllReady(opts);
+              return HttpServerResponse.jsonUnsafe({ ok: true });
+            }).pipe(
               Effect.catchTag("ServiceReadyError", (e) =>
                 Effect.succeed(notReadyResponse(e.name, e.reason, e.exitCode)),
               ),
               Effect.catchTag("StackBuildError", (e) =>
                 Effect.succeed(buildErrorResponse(e.detail)),
               ),
+              Effect.catchTag("StackReadinessError", (e) =>
+                terminalReadinessResponse(e.target, e.timeoutMs, e.detail),
+              ),
             ),
           ),
 
@@ -136,18 +169,7 @@ export class DaemonServer extends Context.Service<
             "/stop",
             Effect.gen(function* () {
               yield* stack.stop();
-              yield* beforeShutdown.pipe(
-                Effect.ensuring(
-                  // The HTTP module has no response-flushed hook. Delay the
-                  // process shutdown signal long enough for this small JSON
-                  // response to leave the socket; stopDaemon also tolerates a
-                  // dropped response and confirms termination by polling PID.
-                  Deferred.succeed(shutdownDeferred, void 0).pipe(
-                    Effect.delay("25 millis"),
-                    Effect.forkDetach,
-                  ),
-                ),
-              );
+              yield* beginShutdown;
               return HttpServerResponse.jsonUnsafe({ ok: true });
             }),
           ),
@@ -219,15 +241,19 @@ export class DaemonServer extends Context.Service<
               Effect.catchTag("StackBuildError", (e) =>
                 Effect.succeed(buildErrorResponse(e.detail)),
               ),
+              Effect.catchTag("StackReadinessError", (e) =>
+                terminalReadinessResponse(e.target, e.timeoutMs, e.detail),
+              ),
             ),
           ),
 
           HttpRouter.route(
-            "GET",
+            "POST",
             "/services/:name/ready",
             Effect.gen(function* () {
               const routeParams = yield* HttpRouter.params;
-              yield* stack.waitReady(routeParams.name!);
+              const opts = yield* HttpServerRequest.schemaBodyJson(ReadyOptionsSchema);
+              yield* stack.waitReady(routeParams.name!, opts);
               return HttpServerResponse.jsonUnsafe({ ok: true });
             }).pipe(
               Effect.catchTag("ServiceNotFoundError", (e) =>
@@ -239,6 +265,9 @@ export class DaemonServer extends Context.Service<
               Effect.catchTag("StackBuildError", (e) =>
                 Effect.succeed(buildErrorResponse(e.detail)),
               ),
+              Effect.catchTag("StackReadinessError", (e) =>
+                terminalReadinessResponse(e.target, e.timeoutMs, e.detail),
+              ),
             ),
           ),
 
@@ -276,6 +305,9 @@ export class DaemonServer extends Context.Service<
               Effect.catchTag("StackBuildError", (e) =>
                 Effect.succeed(buildErrorResponse(e.detail)),
               ),
+              Effect.catchTag("StackReadinessError", (e) =>
+                terminalReadinessResponse(e.target, e.timeoutMs, e.detail),
+              ),
             ),
           ),
 
@@ -299,6 +331,9 @@ export class DaemonServer extends Context.Service<
               Effect.catchTag("StackBuildError", (e) =>
                 Effect.succeed(buildErrorResponse(e.detail)),
               ),
+              Effect.catchTag("StackReadinessError", (e) =>
+                terminalReadinessResponse(e.target, e.timeoutMs, e.detail),
+              ),
             ),
           ),
 
@@ -319,6 +354,9 @@ export class DaemonServer extends Context.Service<
               Effect.catchTag("StackBuildError", (e) =>
                 Effect.succeed(buildErrorResponse(e.detail)),
               ),
+              Effect.catchTag("StackReadinessError", (e) =>
+                terminalReadinessResponse(e.target, e.timeoutMs, e.detail),
+              ),
             ),
           ),
         ];
diff --git a/packages/stack/src/LocalStack.ts b/packages/stack/src/LocalStack.ts
new file mode 100644
index 0000000000..23602329cf
--- /dev/null
+++ b/packages/stack/src/LocalStack.ts
@@ -0,0 +1,897 @@
+import { LogBuffer, Orchestrator } from "@supabase/process-compose";
+import { ServiceNotFoundError } from "@supabase/process-compose";
+import type { ResolvedGraph, ServiceReadyError } from "@supabase/process-compose";
+import {
+  Context,
+  Deferred,
+  Duration,
+  Effect,
+  Equal,
+  FileSystem,
+  Layer,
+  Path,
+  Ref,
+  Semaphore,
+  Stream,
+  SubscriptionRef,
+} from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import type { CleanupTargets } from "./CleanupTargets.ts";
+import { cleanupLocalStackResources } from "./cleanup.ts";
+import { StackBuildError, StackNotRunningError, StackReadinessError } from "./errors.ts";
+import { configureFunctionsRuntime, type FunctionsConfig } from "./functions.ts";
+import { detectPlatform, dockerHostAddress } from "./Platform.ts";
+import type { PortLease } from "./PortAllocator.ts";
+import {
+  activationTargetsForService,
+  eagerServices,
+  lifecycleTargetsForService,
+  StackServiceActivator,
+} from "./ServiceActivation.ts";
+import { portFieldsForService } from "./ServicePorts.ts";
+import { StackMetadataPersistence } from "./StackMetadataPersistence.ts";
+import { StackPreparation } from "./StackPreparation.ts";
+import type { PreparedStackArtifacts } from "./StackPreparation.ts";
+import {
+  enabledServicesForConfig,
+  StackBuilder,
+  validateResolvedConfig,
+  versionsForConfig,
+} from "./StackBuilder.ts";
+import { resolveReadinessPolicy } from "./StackConfig.ts";
+import type { ReadinessPolicy, ReadyOptions, ResolvedStackConfig } from "./StackConfig.ts";
+import { changedProjectedStates, projectStackStates } from "./StackStateProjection.ts";
+import { StackServiceState } from "./StackServiceState.ts";
+import { Stack } from "./Stack.ts";
+import type { EdgeRuntimeReloadConfig, StackInfo } from "./Stack.ts";
+import { SERVICE_NAMES, type ServiceName } from "./versions.ts";
+
+type LifecyclePhase =
+  | "idle"
+  | "preparing"
+  | "prepared"
+  | "starting"
+  | "running"
+  | "stopping"
+  | "stopped"
+  | "disposed";
+
+type StackService = typeof Stack.Service;
+
+interface RuntimeState {
+  readonly orchestrator: Orchestrator["Service"];
+  readonly graph: ResolvedGraph;
+  readonly cleanupTargets: CleanupTargets;
+}
+
+const initialPublicStates = (config: ResolvedStackConfig): ReadonlyArray<StackServiceState> =>
+  enabledServicesForConfig(config).map(
+    (name) =>
+      new StackServiceState({
+        name,
+        status: "Pending",
+        pid: null,
+        exitCode: null,
+        restartCount: 0,
+        startedAt: null,
+        error: null,
+      }),
+  );
+
+const stackInfoFor = (config: ResolvedStackConfig): StackInfo => {
+  const apiUrl = `http://127.0.0.1:${config.apiPort}`;
+  return {
+    url: apiUrl,
+    dbUrl: `postgresql://postgres:postgres@127.0.0.1:${config.dbPort}/postgres`,
+    publishableKey: config.publishableKey,
+    secretKey: config.secretKey,
+    anonJwt: config.anonJwt,
+    serviceRoleJwt: config.serviceRoleJwt,
+    serviceEndpoints: {
+      ...(config.auth === false ? {} : { auth: `${apiUrl}/auth/v1` }),
+      ...(config.postgrest === false ? {} : { postgrest: `${apiUrl}/rest/v1` }),
+      ...(config.edgeRuntime === false
+        ? {}
+        : {
+            functions: `${apiUrl}/functions/v1`,
+            edge_runtime: `${apiUrl}/functions/v1`,
+          }),
+      ...(config.realtime === false ? {} : { realtime: `${apiUrl}/realtime/v1` }),
+      ...(config.storage === false
+        ? {}
+        : {
+            storage: `${apiUrl}/storage/v1`,
+            storage_s3: `${apiUrl}/storage/v1/s3`,
+          }),
+      ...(config.imgproxy === false || config.startupMode === "lazy"
+        ? {}
+        : { imgproxy: `http://127.0.0.1:${config.imgproxy.port}` }),
+      ...(config.mailpit === false
+        ? {}
+        : {
+            mailpit: `http://127.0.0.1:${config.mailpit.port}`,
+            mailpit_smtp: `smtp://127.0.0.1:${config.mailpit.smtpPort}`,
+            mailpit_pop3: `pop3://127.0.0.1:${config.mailpit.pop3Port}`,
+          }),
+      ...(config.pgmeta === false ? {} : { pgmeta: `${apiUrl}/pg` }),
+      ...(config.studio === false ? {} : { studio: `http://127.0.0.1:${config.studio.port}` }),
+      ...(config.analytics === false ? {} : { analytics: `${apiUrl}/analytics/v1` }),
+      ...(config.pooler === false
+        ? {}
+        : {
+            pooler: `postgresql://postgres:postgres@127.0.0.1:${config.pooler.port}/postgres`,
+            pooler_admin: `http://127.0.0.1:${config.pooler.apiPort}`,
+          }),
+    },
+  };
+};
+
+const changedStatesBetween = (
+  previous: ReadonlyArray<StackServiceState> | undefined,
+  current: ReadonlyArray<StackServiceState>,
+): ReadonlyArray<StackServiceState> => {
+  if (previous === undefined) {
+    return current;
+  }
+
+  const previousByName = new Map(previous.map((state) => [state.name, state] as const));
+  return current.filter((state) => !Equal.equals(previousByName.get(state.name), state));
+};
+
+/**
+ * The private in-process Stack implementation. Its scoped construction owns
+ * lifecycle state once and publishes both public seams from that same state.
+ */
+export const localStackLayer = (
+  config: ResolvedStackConfig,
+  portLease: PortLease,
+): Layer.Layer<
+  Stack | StackServiceActivator,
+  StackBuildError,
+  | StackBuilder
+  | StackPreparation
+  | ChildProcessSpawner.ChildProcessSpawner
+  | StackMetadataPersistence
+  | FileSystem.FileSystem
+  | Path.Path
+> =>
+  Layer.effectContext(
+    Effect.gen(function* () {
+      const builder = yield* StackBuilder;
+      const preparation = yield* StackPreparation;
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const metadataPersistence = yield* StackMetadataPersistence;
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const scope = yield* Effect.scope;
+
+      const info = stackInfoFor(config);
+      const enabledServices = enabledServicesForConfig(config);
+      const stateRef = yield* SubscriptionRef.make(initialPublicStates(config));
+      const phaseRef = yield* Ref.make<LifecyclePhase>("idle");
+      const lifecycleLock = Semaphore.makeUnsafe(1);
+
+      const logBufferServices = yield* Layer.buildWithScope(LogBuffer.layer, scope);
+      const logBuffer = Context.get(logBufferServices, LogBuffer);
+
+      const updateState = (nextState: StackServiceState) =>
+        SubscriptionRef.update(stateRef, (current) => {
+          const previous = current.find((entry) => entry.name === nextState.name);
+          if (Equal.equals(previous, nextState)) {
+            return current;
+          }
+          return current.some((entry) => entry.name === nextState.name)
+            ? current.map((entry) => (entry.name === nextState.name ? nextState : entry))
+            : [...current, nextState];
+        });
+
+      const requireKnownService = (name: string) =>
+        Effect.gen(function* () {
+          const currentStates = SubscriptionRef.getUnsafe(stateRef);
+          const match = currentStates.find((state) => state.name === name);
+          if (match === undefined) {
+            return yield* Effect.fail(new ServiceNotFoundError({ name }));
+          }
+          return match;
+        });
+      const requireKnownServiceName = (
+        name: string,
+      ): Effect.Effect<ServiceName, ServiceNotFoundError> =>
+        Effect.gen(function* () {
+          yield* requireKnownService(name);
+          const service = SERVICE_NAMES.find((candidate) => candidate === name);
+          if (service === undefined) {
+            return yield* Effect.fail(new ServiceNotFoundError({ name }));
+          }
+          return service;
+        });
+
+      let preparedArtifacts: PreparedStackArtifacts | undefined;
+      let prepareDeferred: Deferred.Deferred<PreparedStackArtifacts, StackBuildError> | undefined;
+      let runtimeState: RuntimeState | undefined;
+      let runtimeDeferred: Deferred.Deferred<RuntimeState, StackBuildError> | undefined;
+
+      const ensurePrepared = Effect.suspend(() => {
+        if (preparedArtifacts !== undefined) {
+          return Effect.succeed(preparedArtifacts);
+        }
+        if (prepareDeferred !== undefined) {
+          return Deferred.await(prepareDeferred);
+        }
+
+        const deferred = Deferred.makeUnsafe<PreparedStackArtifacts, StackBuildError>();
+        prepareDeferred = deferred;
+
+        const effect = Effect.gen(function* () {
+          yield* validateResolvedConfig(config);
+          yield* Ref.set(phaseRef, "preparing");
+
+          let prepared: PreparedStackArtifacts | undefined;
+          yield* preparation
+            .prepareEvents({
+              mode: config.mode,
+              services: enabledServicesForConfig(config),
+              versions: versionsForConfig(config),
+            })
+            .pipe(
+              Stream.mapError(
+                (cause) =>
+                  new StackBuildError({
+                    detail: "Failed to prepare stack assets",
+                    cause,
+                  }),
+              ),
+            )
+            .pipe(
+              Stream.runForEach((event) => {
+                switch (event._tag) {
+                  case "ServiceDownloadStarted":
+                    return updateState(
+                      new StackServiceState({
+                        name: event.service,
+                        status: "Downloading",
+                        pid: null,
+                        exitCode: null,
+                        restartCount: 0,
+                        startedAt: null,
+                        error: null,
+                      }),
+                    );
+                  case "ServiceDownloadFinished":
+                    return updateState(
+                      new StackServiceState({
+                        name: event.service,
+                        status: "Pending",
+                        pid: null,
+                        exitCode: null,
+                        restartCount: 0,
+                        startedAt: null,
+                        error: null,
+                      }),
+                    );
+                  case "PreparationCompleted":
+                    return Effect.sync(() => {
+                      prepared = event.artifacts;
+                    });
+                }
+              }),
+            );
+
+          if (prepared === undefined) {
+            return yield* Effect.fail(
+              new StackBuildError({
+                detail: "Stack preparation completed without prepared artifacts",
+              }),
+            );
+          }
+
+          yield* Ref.set(phaseRef, "prepared");
+          return prepared;
+        }).pipe(
+          Effect.tap((value) =>
+            Effect.sync(() => {
+              preparedArtifacts = value;
+            }),
+          ),
+          Effect.onError(() => Ref.set(phaseRef, "idle")),
+          Effect.ensuring(
+            Effect.sync(() => {
+              prepareDeferred = undefined;
+            }),
+          ),
+        );
+
+        return Effect.gen(function* () {
+          yield* Effect.forkIn(effect.pipe(Deferred.into(deferred)), scope);
+          return yield* Deferred.await(deferred);
+        });
+      });
+
+      const ensureRuntime = Effect.suspend(() => {
+        if (runtimeState !== undefined) {
+          return Effect.succeed(runtimeState);
+        }
+        if (runtimeDeferred !== undefined) {
+          return Deferred.await(runtimeDeferred);
+        }
+
+        const deferred = Deferred.makeUnsafe<RuntimeState, StackBuildError>();
+        runtimeDeferred = deferred;
+
+        const effect = Effect.gen(function* () {
+          const prepared = yield* ensurePrepared;
+          const { graph, serviceProjection, cleanupTargets } = yield* builder.build(
+            config,
+            prepared,
+          );
+
+          yield* metadataPersistence.persistCleanupTargets(cleanupTargets).pipe(
+            Effect.mapError(
+              (cause) =>
+                new StackBuildError({
+                  detail: "Failed to persist stack cleanup metadata",
+                  cause,
+                }),
+            ),
+          );
+
+          const orchLayer = Orchestrator.layer(graph).pipe(
+            Layer.provide(Layer.succeed(LogBuffer, logBuffer)),
+            Layer.provide(Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner)),
+          );
+          const orchServices = yield* Layer.buildWithScope(orchLayer, scope);
+          const orchestrator = Context.get(orchServices, Orchestrator);
+
+          const projectedStates = Stream.unwrap(
+            Effect.gen(function* () {
+              const rawInitialStates = yield* orchestrator.getAllStates();
+              const initialProjected = projectStackStates(rawInitialStates, serviceProjection);
+              let rawStates = new Map(
+                rawInitialStates.map((state) => [state.name, state] as const),
+              );
+              let projectedByName = new Map(
+                initialProjected.map((state) => [state.name, state] as const),
+              );
+
+              return Stream.concat(
+                Stream.fromIterable(initialProjected),
+                orchestrator.allStateChanges().pipe(
+                  Stream.map((rawState) => {
+                    rawStates.set(rawState.name, rawState);
+                    const nextProjected = projectStackStates(
+                      [...rawStates.values()],
+                      serviceProjection,
+                    );
+                    const changed = changedProjectedStates(projectedByName, nextProjected);
+                    projectedByName = new Map(
+                      nextProjected.map((state) => [state.name, state] as const),
+                    );
+                    return changed;
+                  }),
+                  Stream.flatMap((states) => Stream.fromIterable(states)),
+                ),
+              );
+            }),
+          );
+
+          yield* projectedStates.pipe(
+            Stream.runForEach((state) => updateState(state)),
+            Effect.ignore,
+            Effect.forkIn(scope),
+          );
+
+          return {
+            orchestrator,
+            graph,
+            cleanupTargets,
+          } satisfies RuntimeState;
+        }).pipe(
+          Effect.tap((value) =>
+            Effect.sync(() => {
+              runtimeState = value;
+            }),
+          ),
+          Effect.ensuring(
+            Effect.sync(() => {
+              runtimeDeferred = undefined;
+            }),
+          ),
+        );
+
+        return Effect.gen(function* () {
+          yield* Effect.forkIn(effect.pipe(Deferred.into(deferred)), scope);
+          return yield* Deferred.await(deferred);
+        });
+      });
+
+      let disposed = false;
+      const runtimeHost = Effect.gen(function* () {
+        const prepared = yield* ensurePrepared;
+        const platform = yield* detectPlatform;
+        const edgeRuntimeResolution = prepared.resolutions["edge-runtime"];
+        return {
+          hostname:
+            edgeRuntimeResolution?.type === "docker" ? dockerHostAddress(platform.os) : "127.0.0.1",
+        };
+      });
+      const providePlatform = <A, E>(
+        effect: Effect.Effect<A, E, FileSystem.FileSystem | Path.Path>,
+      ): Effect.Effect<A, E> =>
+        effect.pipe(
+          Effect.provideService(FileSystem.FileSystem, fs),
+          Effect.provideService(Path.Path, path),
+        );
+      const configureFunctions = (
+        nextConfig: ResolvedStackConfig,
+      ): Effect.Effect<void, StackBuildError> =>
+        Effect.gen(function* () {
+          yield* providePlatform(configureFunctionsRuntime(nextConfig, yield* runtimeHost));
+        }).pipe(
+          Effect.mapError(
+            (cause) =>
+              new StackBuildError({
+                detail: "Failed to configure Edge Functions",
+                cause,
+              }),
+          ),
+        );
+      const configWithFunctionOptions = (opts?: FunctionsConfig): ResolvedStackConfig => {
+        if (opts === undefined) {
+          return config;
+        }
+        const base = config.functions === false ? { noVerifyJwt: false } : config.functions;
+        return {
+          ...config,
+          functions: {
+            envFile: opts.envFile ?? base.envFile,
+            noVerifyJwt: opts.noVerifyJwt ?? base.noVerifyJwt,
+          },
+        };
+      };
+      const configWithEdgeRuntimeOptions = (
+        opts: EdgeRuntimeReloadConfig,
+      ): Effect.Effect<ResolvedStackConfig, ServiceNotFoundError> =>
+        Effect.gen(function* () {
+          if (config.edgeRuntime === false || opts.edgeRuntime.enabled === false) {
+            return yield* Effect.fail(new ServiceNotFoundError({ name: "edge-runtime" }));
+          }
+
+          const base = configWithFunctionOptions(opts.functions);
+          return {
+            ...base,
+            edgeRuntime: {
+              ...config.edgeRuntime,
+              enabled: opts.edgeRuntime.enabled ?? config.edgeRuntime.enabled,
+              inspectorPort: opts.edgeRuntime.inspectorPort ?? config.edgeRuntime.inspectorPort,
+              policy: opts.edgeRuntime.policy ?? config.edgeRuntime.policy,
+              env: opts.edgeRuntime.env ?? config.edgeRuntime.env,
+            },
+          };
+        });
+      const publicAllStateChanges = () =>
+        SubscriptionRef.changes(stateRef).pipe(
+          Stream.mapAccum<
+            ReadonlyArray<StackServiceState> | undefined,
+            ReadonlyArray<StackServiceState>,
+            StackServiceState
+          >(
+            () => undefined,
+            (previous, current) => [current, changedStatesBetween(previous, current)],
+          ),
+        );
+      const withLifecycleLock = lifecycleLock.withPermit;
+      const serviceStartOptions = {
+        beforeStart: (name: string) => portLease.reserve(portFieldsForService(name)),
+        beforeSpawn: (name: string) => portLease.release(portFieldsForService(name)),
+      };
+      const knownServiceError = (service: string, cause: ServiceNotFoundError) =>
+        new StackBuildError({
+          detail: `Prepared graph does not contain enabled service ${service}`,
+          cause,
+        });
+      const beginStartTargets = (
+        root: ServiceName,
+        allowExplicitlyStopped: ReadonlySet<ServiceName>,
+      ) =>
+        Effect.gen(function* () {
+          const runtime = yield* ensureRuntime;
+          const targets = activationTargetsForService(enabledServices, root);
+          const targetClosure = new Set(
+            targets.flatMap((target) =>
+              runtime.graph.startOrderFor(target).map((definition) => definition.name),
+            ),
+          );
+
+          for (const dependency of targetClosure) {
+            const state = yield* runtime.orchestrator
+              .getState(dependency)
+              .pipe(
+                Effect.catchTag("ServiceNotFoundError", (cause) =>
+                  Effect.fail(knownServiceError(dependency, cause)),
+                ),
+              );
+            const publicDependency = SERVICE_NAMES.find((candidate) => candidate === dependency);
+            if (
+              state.desired === "stopped" &&
+              publicDependency !== undefined &&
+              !allowExplicitlyStopped.has(publicDependency)
+            ) {
+              return yield* Effect.fail(
+                new StackBuildError({
+                  detail: `Cannot activate ${root} because dependency ${dependency} was explicitly stopped`,
+                }),
+              );
+            }
+          }
+
+          for (const target of targets) {
+            yield* runtime.orchestrator
+              .startService(target, serviceStartOptions)
+              .pipe(
+                Effect.catchTag("ServiceNotFoundError", (cause) =>
+                  Effect.fail(knownServiceError(target, cause)),
+                ),
+              );
+          }
+          return { runtime, targets };
+        });
+      const waitForTargets = ({
+        runtime,
+        targets,
+      }: {
+        readonly runtime: RuntimeState;
+        readonly targets: ReadonlyArray<ServiceName>;
+      }) =>
+        Effect.forEach(
+          targets,
+          (target) =>
+            runtime.orchestrator
+              .waitReady(target)
+              .pipe(
+                Effect.catchTag("ServiceNotFoundError", (cause) =>
+                  Effect.fail(knownServiceError(target, cause)),
+                ),
+              ),
+          { concurrency: "unbounded", discard: true },
+        );
+      const inspectStartedTargets = (root: ServiceName) =>
+        Effect.gen(function* () {
+          const runtime = yield* ensureRuntime;
+          const targets = activationTargetsForService(enabledServices, root);
+          const states = yield* Effect.forEach(targets, (target) =>
+            runtime.orchestrator
+              .getState(target)
+              .pipe(
+                Effect.catchTag("ServiceNotFoundError", (cause) =>
+                  Effect.fail(knownServiceError(target, cause)),
+                ),
+              ),
+          );
+          if (states.some((state) => state.desired !== "running")) {
+            return undefined;
+          }
+          return {
+            runtime,
+            targets,
+            ready: states.every(
+              (state) =>
+                state.status === "Healthy" || (state.status === "Stopped" && state.exitCode === 0),
+            ),
+          };
+        });
+      const requireRunningPhase = Effect.gen(function* () {
+        const phase = yield* Ref.get(phaseRef);
+        if (phase !== "running") {
+          return yield* Effect.fail(new StackNotRunningError({ phase }));
+        }
+      });
+      const requireMutable = (operation: string) =>
+        Effect.suspend(() =>
+          disposed
+            ? Effect.fail(
+                new StackBuildError({
+                  detail: `Cannot ${operation} after the stack has been disposed`,
+                }),
+              )
+            : Effect.void,
+        );
+      const disposeOnce = () =>
+        Effect.gen(function* () {
+          if (disposed) {
+            return;
+          }
+          disposed = true;
+          yield* Ref.set(phaseRef, "stopping");
+          yield* cleanupLocalStackResources({
+            stop: () =>
+              runtimeState === undefined ? Effect.void : runtimeState.orchestrator.stop(),
+            cleanupTargets: runtimeState?.cleanupTargets ?? { dockerContainerNames: [] },
+            config,
+          }).pipe(
+            Effect.ensuring(portLease.releaseAll),
+            Effect.ensuring(Ref.set(phaseRef, "disposed")),
+          );
+        }).pipe(withLifecycleLock);
+
+      const withReadinessPolicy = <A, E, R>(
+        effect: Effect.Effect<A, E, R>,
+        target: string,
+        readyOptions?: ReadyOptions,
+      ): Effect.Effect<A, E | StackReadinessError, R> => {
+        const policy: ReadinessPolicy = resolveReadinessPolicy({
+          readyOptions,
+          stackPolicy: config.readiness,
+        });
+        if (policy.mode === "infinite") {
+          return effect;
+        }
+        return effect.pipe(
+          Effect.timeoutOrElse({
+            duration: Duration.millis(policy.timeoutMs),
+            orElse: () =>
+              Effect.fail(
+                new StackReadinessError({
+                  target,
+                  timeoutMs: policy.timeoutMs,
+                  detail: `Timed out waiting for ${target} readiness after ${policy.timeoutMs}ms`,
+                }),
+              ),
+          }),
+        );
+      };
+      const cleanupOnReadinessFailure = <A, E, R>(
+        effect: Effect.Effect<A, E | StackReadinessError, R>,
+      ): Effect.Effect<A, E | StackReadinessError, R> =>
+        effect.pipe(
+          Effect.catchTag("StackReadinessError", (error) =>
+            disposeOnce().pipe(Effect.andThen(Effect.fail(error))),
+          ),
+        );
+
+      yield* Effect.addFinalizer(disposeOnce);
+
+      const activateService = (name: ServiceName) =>
+        Effect.gen(function* () {
+          yield* requireRunningPhase;
+          const service = yield* requireKnownServiceName(name);
+          const existing = yield* inspectStartedTargets(service);
+          if (existing?.ready === true) {
+            // Close the race with a concurrent stack stop before taking
+            // the lock-free healthy-request fast path.
+            yield* requireRunningPhase;
+            return;
+          }
+          if (existing !== undefined) {
+            yield* waitForTargets(existing);
+            return;
+          }
+          const started = yield* Effect.gen(function* () {
+            yield* requireRunningPhase;
+            const concurrentlyStarted = yield* inspectStartedTargets(service);
+            if (concurrentlyStarted !== undefined) return concurrentlyStarted;
+            return yield* beginStartTargets(service, new Set());
+          }).pipe(withLifecycleLock);
+          yield* waitForTargets(started);
+        }).pipe((effect) => withReadinessPolicy(effect, name), cleanupOnReadinessFailure);
+
+      const stack = {
+        getInfo: () => Effect.succeed(info),
+        start: () =>
+          Effect.gen(function* () {
+            yield* requireMutable("start");
+            yield* Ref.set(phaseRef, "starting");
+            const runtime = yield* ensureRuntime;
+            yield* configureFunctions(config);
+
+            if (config.startupMode === "lazy") {
+              const readiness: Array<Effect.Effect<void, ServiceReadyError | StackBuildError>> = [];
+              if (
+                runtime.graph.startOrder.some((definition) => definition.name === "postgres-init")
+              ) {
+                yield* runtime.orchestrator
+                  .startService("postgres-init", serviceStartOptions)
+                  .pipe(
+                    Effect.catchTag("ServiceNotFoundError", (cause) =>
+                      Effect.fail(knownServiceError("postgres-init", cause)),
+                    ),
+                  );
+                readiness.push(
+                  runtime.orchestrator
+                    .waitReady("postgres-init")
+                    .pipe(
+                      Effect.catchTag("ServiceNotFoundError", (cause) =>
+                        Effect.fail(knownServiceError("postgres-init", cause)),
+                      ),
+                    ),
+                );
+              }
+              for (const service of eagerServices(enabledServices)) {
+                const started = yield* beginStartTargets(
+                  service,
+                  new Set(lifecycleTargetsForService(enabledServices, service)),
+                );
+                readiness.push(waitForTargets(started));
+              }
+              yield* Effect.all(readiness, { concurrency: "unbounded", discard: true });
+            } else {
+              yield* runtime.orchestrator.start(serviceStartOptions);
+              yield* runtime.orchestrator.waitAllReady();
+            }
+            yield* Ref.set(phaseRef, "running");
+          }).pipe(
+            Effect.onError(() => Ref.set(phaseRef, "stopped")),
+            withLifecycleLock,
+            (effect) => withReadinessPolicy(effect, "stack"),
+            cleanupOnReadinessFailure,
+          ),
+        stop: () =>
+          Effect.gen(function* () {
+            if (disposed) {
+              return;
+            }
+            if (runtimeState === undefined) {
+              yield* Ref.set(phaseRef, "stopped");
+              return;
+            }
+            yield* Ref.set(phaseRef, "stopping");
+            yield* runtimeState.orchestrator.stop();
+            yield* Ref.set(phaseRef, "stopped");
+          }).pipe(withLifecycleLock),
+        dispose: disposeOnce,
+        startService: (name) =>
+          Effect.gen(function* () {
+            const started = yield* Effect.gen(function* () {
+              yield* requireMutable(`start service ${name}`);
+              const service = yield* requireKnownServiceName(name);
+              return yield* beginStartTargets(
+                service,
+                new Set(lifecycleTargetsForService(enabledServices, service)),
+              );
+            }).pipe(withLifecycleLock);
+            yield* waitForTargets(started);
+          }).pipe((effect) => withReadinessPolicy(effect, name), cleanupOnReadinessFailure),
+        stopService: (name) =>
+          Effect.gen(function* () {
+            yield* requireMutable(`stop service ${name}`);
+            const service = yield* requireKnownServiceName(name);
+            const runtime = yield* ensureRuntime;
+            for (const target of lifecycleTargetsForService(
+              enabledServices,
+              service,
+            ).toReversed()) {
+              yield* runtime.orchestrator.stopService(target);
+            }
+          }).pipe(withLifecycleLock),
+        restartService: (name) =>
+          Effect.gen(function* () {
+            const started = yield* Effect.gen(function* () {
+              yield* requireMutable(`restart service ${name}`);
+              const service = yield* requireKnownServiceName(name);
+              const runtime = yield* ensureRuntime;
+              yield* runtime.orchestrator.restartService(service, serviceStartOptions);
+              return { runtime, targets: [service] };
+            }).pipe(withLifecycleLock);
+            yield* waitForTargets(started);
+          }).pipe((effect) => withReadinessPolicy(effect, name), cleanupOnReadinessFailure),
+        reloadFunctions: (opts) =>
+          Effect.gen(function* () {
+            const started = yield* Effect.gen(function* () {
+              yield* requireMutable("reload functions");
+              yield* requireKnownService("edge-runtime");
+              yield* configureFunctions(configWithFunctionOptions(opts));
+              const runtime = yield* ensureRuntime;
+              const state = yield* runtime.orchestrator.getState("edge-runtime");
+              if (state.desired !== "running") {
+                return yield* beginStartTargets("edge-runtime", new Set(["edge-runtime"]));
+              }
+              yield* runtime.orchestrator.restartService("edge-runtime", serviceStartOptions);
+              return { runtime, targets: ["edge-runtime"] as const };
+            }).pipe(withLifecycleLock);
+            yield* waitForTargets(started);
+          }).pipe(
+            (effect) => withReadinessPolicy(effect, "edge-runtime"),
+            cleanupOnReadinessFailure,
+          ),
+        reloadEdgeRuntime: (opts) =>
+          Effect.gen(function* () {
+            const started = yield* Effect.gen(function* () {
+              yield* requireMutable("reload Edge Runtime");
+              yield* requireKnownService("edge-runtime");
+              const nextConfig = yield* configWithEdgeRuntimeOptions(opts);
+              const prepared = yield* ensurePrepared;
+              const runtime = yield* ensureRuntime;
+              const buildResult = yield* builder.build(nextConfig, prepared);
+              const edgeRuntimeDef = buildResult.graph.startOrder.find(
+                (def) => def.name === "edge-runtime",
+              );
+
+              if (edgeRuntimeDef === undefined) {
+                return yield* Effect.fail(new ServiceNotFoundError({ name: "edge-runtime" }));
+              }
+
+              yield* configureFunctions(nextConfig);
+              yield* runtime.orchestrator
+                .updateServiceDefinition("edge-runtime", edgeRuntimeDef)
+                .pipe(
+                  Effect.mapError(
+                    (cause) =>
+                      new StackBuildError({
+                        detail: "Failed to update edge-runtime service definition",
+                        cause,
+                      }),
+                  ),
+                );
+              const state = yield* runtime.orchestrator.getState("edge-runtime");
+              if (state.desired !== "running") {
+                return yield* beginStartTargets("edge-runtime", new Set(["edge-runtime"]));
+              }
+              yield* runtime.orchestrator.restartService("edge-runtime", serviceStartOptions);
+              return { runtime, targets: ["edge-runtime"] as const };
+            }).pipe(withLifecycleLock);
+            yield* waitForTargets(started);
+          }).pipe(
+            (effect) => withReadinessPolicy(effect, "edge-runtime"),
+            cleanupOnReadinessFailure,
+          ),
+        getState: (name) =>
+          Effect.gen(function* () {
+            const currentStates = SubscriptionRef.getUnsafe(stateRef);
+            const match = currentStates.find((state) => state.name === name);
+            if (match === undefined) {
+              return yield* Effect.fail(new ServiceNotFoundError({ name }));
+            }
+            return match;
+          }),
+        getAllStates: () => Effect.sync(() => SubscriptionRef.getUnsafe(stateRef)),
+        stateChanges: (name) =>
+          Effect.gen(function* () {
+            yield* requireKnownService(name);
+            return Stream.filter(publicAllStateChanges(), (state) => state.name === name);
+          }),
+        allStateChanges: publicAllStateChanges,
+        waitReady: (name, opts) =>
+          Effect.gen(function* () {
+            const phase = yield* Ref.get(phaseRef);
+            if (phase !== "running") {
+              return yield* Effect.fail(
+                new StackBuildError({
+                  detail: `Cannot wait for service ${name} while the stack is ${phase}`,
+                }),
+              );
+            }
+            yield* requireKnownServiceName(name);
+            const runtime = yield* ensureRuntime;
+            yield* runtime.orchestrator.waitReady(name);
+          }).pipe((effect) => withReadinessPolicy(effect, name, opts), cleanupOnReadinessFailure),
+        waitAllReady: (opts) =>
+          Effect.gen(function* () {
+            const phase = yield* Ref.get(phaseRef);
+            if (phase !== "running") {
+              return yield* Effect.fail(
+                new StackBuildError({
+                  detail: `Cannot wait for stack readiness while the stack is ${phase}`,
+                }),
+              );
+            }
+            const runtime = yield* ensureRuntime;
+            yield* runtime.orchestrator.waitAllReady();
+          }).pipe(
+            (effect) => withReadinessPolicy(effect, "stack", opts),
+            cleanupOnReadinessFailure,
+          ),
+        subscribeLogs: (name) => logBuffer.subscribe(name),
+        subscribeAllLogs: (services) =>
+          services === undefined || services.length === 0
+            ? logBuffer.subscribeAll()
+            : logBuffer
+                .subscribeAll()
+                .pipe(Stream.filter((entry) => services.includes(entry.service))),
+        logHistory: (name, limit) => logBuffer.history(name, limit),
+        logHistoryAll: (limit, services) => logBuffer.historyAll(limit, services),
+      } satisfies StackService;
+
+      return Context.make(Stack, stack).pipe(
+        Context.add(StackServiceActivator, { activate: activateService }),
+      );
+    }),
+  );
diff --git a/packages/stack/src/RemoteStack.integration.test.ts b/packages/stack/src/RemoteStack.integration.test.ts
index dc520bab1e..43930a1a2a 100644
--- a/packages/stack/src/RemoteStack.integration.test.ts
+++ b/packages/stack/src/RemoteStack.integration.test.ts
@@ -4,9 +4,10 @@ import { Effect, Fiber, Layer, ManagedRuntime, Stream } from "effect";
 import * as http from "node:http";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { DaemonServer } from "./DaemonServer.ts";
-import { StackBuildError } from "./errors.ts";
+import { StackBuildError, StackReadinessError } from "./errors.ts";
 import { RemoteStack } from "./RemoteStack.ts";
 import { Stack, type StackInfo } from "./Stack.ts";
+import type { ReadyOptions } from "./StackConfig.ts";
 import { StackServiceState } from "./StackServiceState.ts";
 import { UnixHttpClient, UnixHttpClientError } from "./UnixHttpClient.ts";
 
@@ -75,11 +76,13 @@ function mockStack(
     readonly startServiceBuildError?: string;
     readonly startServiceReadyError?: string;
     readonly waitReadyBuildError?: string;
+    readonly waitReadyTimeoutMs?: number;
     readonly restartServiceReadyError?: string;
   } = {},
 ) {
   let stopped = false;
   const serviceCalls: string[] = [];
+  const readinessCalls: Array<{ readonly target: string; readonly options?: ReadyOptions }> = [];
 
   const layer = Layer.succeed(Stack, {
     getInfo: () => Effect.succeed(MOCK_INFO),
@@ -146,18 +149,29 @@ function mockStack(
         : Effect.fail(new ServiceNotFoundError({ name }));
     },
     allStateChanges: () => Stream.fromIterable(MOCK_STATES),
-    waitReady: (name: string) => {
+    waitReady: (name: string, readyOptions?: ReadyOptions) => {
       const match = MOCK_STATES.find((s) => s.name === name);
       if (match === undefined) return Effect.fail(new ServiceNotFoundError({ name }));
       if (options.waitReadyBuildError !== undefined) {
         return Effect.fail(new StackBuildError({ detail: options.waitReadyBuildError }));
       }
+      if (options.waitReadyTimeoutMs !== undefined) {
+        return Effect.fail(
+          new StackReadinessError({
+            target: name,
+            timeoutMs: options.waitReadyTimeoutMs,
+            detail: `Timed out waiting for ${name}`,
+          }),
+        );
+      }
       return Effect.sync(() => {
+        readinessCalls.push({ target: name, options: readyOptions });
         serviceCalls.push(`ready:${name}`);
       });
     },
-    waitAllReady: () =>
+    waitAllReady: (readyOptions?: ReadyOptions) =>
       Effect.sync(() => {
+        readinessCalls.push({ target: "stack", options: readyOptions });
         serviceCalls.push("ready:all");
       }),
     subscribeLogs: (name: string) =>
@@ -185,6 +199,7 @@ function mockStack(
       return stopped;
     },
     serviceCalls,
+    readinessCalls,
   };
 }
 
@@ -288,9 +303,15 @@ describe("RemoteStack integration", () => {
     expect(exit._tag).toBe("Failure");
   });
 
-  test("waitReady delegates to the daemon coordinator", async () => {
-    await clientRuntime.runPromise(Effect.flatMap(Stack, (stack) => stack.waitReady("auth")));
+  test("waitReady passes one validated finite override through the daemon", async () => {
+    await clientRuntime.runPromise(
+      Effect.flatMap(Stack, (stack) => stack.waitReady("auth", { mode: "finite", timeoutMs: 250 })),
+    );
     expect(mock.serviceCalls).toContain("ready:auth");
+    expect(mock.readinessCalls).toContainEqual({
+      target: "auth",
+      options: { mode: "finite", timeoutMs: 250 },
+    });
   });
 
   test("waitReady rejects dot path segments locally", async () => {
@@ -301,9 +322,38 @@ describe("RemoteStack integration", () => {
     expect(mock.serviceCalls).not.toContain("ready:all");
   });
 
-  test("waitAllReady delegates to the daemon coordinator", async () => {
+  test("waitAllReady sends explicit inherit semantics to the daemon", async () => {
     await clientRuntime.runPromise(Effect.flatMap(Stack, (stack) => stack.waitAllReady()));
     expect(mock.serviceCalls).toContain("ready:all");
+    expect(mock.readinessCalls).toContainEqual({
+      target: "stack",
+      options: { mode: "inherit" },
+    });
+  });
+
+  test("preserves StackReadinessError across the daemon transport", async () => {
+    const failingMock = mockStack({ waitReadyTimeoutMs: 75 });
+    const failingServer = ManagedRuntime.make(buildServerLayer(failingMock));
+    let failingClient: ManagedRuntime.ManagedRuntime<Stack, never> | undefined;
+    try {
+      const daemon = await failingServer.runPromise(DaemonServer);
+      const addr = daemon.address;
+      if (addr._tag !== "TcpAddress") throw new Error("Expected TcpAddress");
+      const host = addr.hostname === "0.0.0.0" ? "127.0.0.1" : addr.hostname;
+      failingClient = ManagedRuntime.make(buildClientLayer(`http://${host}:${addr.port}`));
+
+      const error = await failingClient.runPromise(
+        Effect.flatMap(Stack, (stack) => stack.waitReady("auth")).pipe(Effect.flip),
+      );
+      expect(error._tag).toBe("StackReadinessError");
+      if (error._tag === "StackReadinessError") {
+        expect(error.target).toBe("auth");
+        expect(error.timeoutMs).toBe(75);
+      }
+    } finally {
+      await failingClient?.dispose();
+      await failingServer.dispose();
+    }
   });
 
   test("interrupting waitReady aborts the daemon request", async () => {
diff --git a/packages/stack/src/RemoteStack.ts b/packages/stack/src/RemoteStack.ts
index df7388559f..dd0f8ca6a4 100644
--- a/packages/stack/src/RemoteStack.ts
+++ b/packages/stack/src/RemoteStack.ts
@@ -3,8 +3,9 @@ import { Effect, Layer, Schema, Stream } from "effect";
 import * as Sse from "effect/unstable/encoding/Sse";
 import { HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
 import { DaemonErrorResponseSchema } from "./DaemonProtocol.ts";
-import { StackBuildError } from "./errors.ts";
+import { StackBuildError, StackReadinessError } from "./errors.ts";
 import { Stack, StackInfoSchema } from "./Stack.ts";
+import { inheritReadyOptions } from "./StackConfig.ts";
 import { StackServiceState, StackServiceStatusSchema } from "./StackServiceState.ts";
 import { UnixHttpClient, UnixHttpClientError } from "./UnixHttpClient.ts";
 import { SERVICE_NAMES } from "./versions.ts";
@@ -105,7 +106,10 @@ function withAbortSignal<A, E, R>(
 const failDaemonResponse = (
   response: HttpClientResponse.HttpClientResponse,
   fallbackName: string,
-): Effect.Effect<never, ServiceNotFoundError | ServiceReadyError | StackBuildError> =>
+): Effect.Effect<
+  never,
+  ServiceNotFoundError | ServiceReadyError | StackBuildError | StackReadinessError
+> =>
   Effect.gen(function* () {
     const body = yield* HttpClientResponse.schemaBodyJson(DaemonErrorResponseSchema)(response).pipe(
       Effect.orDie,
@@ -121,13 +125,22 @@ const failDaemonResponse = (
         });
       case "STACK_BUILD_ERROR":
         return yield* new StackBuildError({ detail: body.error });
+      case "STACK_READINESS_TIMEOUT":
+        return yield* new StackReadinessError({
+          target: body.service ?? fallbackName,
+          timeoutMs: body.timeoutMs ?? 0,
+          detail: body.error,
+        });
     }
   });
 
 const expectDaemonOk = (
   response: HttpClientResponse.HttpClientResponse,
   fallbackName: string,
-): Effect.Effect<void, ServiceNotFoundError | ServiceReadyError | StackBuildError> =>
+): Effect.Effect<
+  void,
+  ServiceNotFoundError | ServiceReadyError | StackBuildError | StackReadinessError
+> =>
   response.status >= 200 && response.status < 300
     ? Effect.void
     : failDaemonResponse(response, fallbackName);
@@ -301,6 +314,7 @@ export const RemoteStack = {
                 });
                 yield* expectDaemonOk(response, name).pipe(
                   Effect.catchTag("ServiceReadyError", (error) => Effect.die(error)),
+                  Effect.catchTag("StackReadinessError", (error) => Effect.die(error)),
                 );
               }),
             ),
@@ -392,7 +406,7 @@ export const RemoteStack = {
               }),
             ),
 
-          waitReady: (name: string) =>
+          waitReady: (name, opts) =>
             withUnixHttpClient(
               withAbortSignal((signal) =>
                 Effect.gen(function* () {
@@ -400,18 +414,28 @@ export const RemoteStack = {
                   const response = yield* unixResponse(
                     socketPath,
                     `/services/${servicePath}/ready`,
-                    { signal },
+                    {
+                      method: "POST",
+                      signal,
+                      headers: { "content-type": "application/json" },
+                      body: JSON.stringify(opts ?? inheritReadyOptions),
+                    },
                   );
                   yield* expectDaemonOk(response, name);
                 }),
               ),
             ),
 
-          waitAllReady: () =>
+          waitAllReady: (opts) =>
             withUnixHttpClient(
               withAbortSignal((signal) =>
                 Effect.gen(function* () {
-                  const response = yield* unixResponse(socketPath, "/ready", { signal });
+                  const response = yield* unixResponse(socketPath, "/ready", {
+                    method: "POST",
+                    signal,
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify(opts ?? inheritReadyOptions),
+                  });
                   yield* expectDaemonOk(response, "stack").pipe(
                     Effect.catchTag("ServiceNotFoundError", (error) => Effect.die(error)),
                   );
diff --git a/packages/stack/src/ServiceActivation.ts b/packages/stack/src/ServiceActivation.ts
index e66f9fd8e2..4238dc323f 100644
--- a/packages/stack/src/ServiceActivation.ts
+++ b/packages/stack/src/ServiceActivation.ts
@@ -1,7 +1,7 @@
 import { ServiceNotFoundError } from "@supabase/process-compose";
 import type { ServiceReadyError } from "@supabase/process-compose";
 import { Context, Effect, Layer } from "effect";
-import { StackBuildError, StackNotRunningError } from "./errors.ts";
+import { StackBuildError, StackNotRunningError, StackReadinessError } from "./errors.ts";
 import { serviceMetadata } from "./ServiceCatalog.ts";
 import type { ServiceName } from "./ServiceName.ts";
 
@@ -54,7 +54,11 @@ export class StackServiceActivator extends Context.Service<
       service: ServiceName,
     ) => Effect.Effect<
       void,
-      ServiceNotFoundError | ServiceReadyError | StackBuildError | StackNotRunningError
+      | ServiceNotFoundError
+      | ServiceReadyError
+      | StackBuildError
+      | StackNotRunningError
+      | StackReadinessError
     >;
   }
 >()("stack/StackServiceActivator") {
diff --git a/packages/stack/src/Stack.ts b/packages/stack/src/Stack.ts
index dbe2ce70e0..6d07355597 100644
--- a/packages/stack/src/Stack.ts
+++ b/packages/stack/src/Stack.ts
@@ -1,10 +1,9 @@
 import { ServiceNotFoundError } from "@supabase/process-compose";
 import type { LogEntry, ServiceReadyError } from "@supabase/process-compose";
-import { Effect, Layer, Schema, Context, Stream } from "effect";
-import { StackBuildError } from "./errors.ts";
+import { Context, Effect, Schema, Stream } from "effect";
+import { StackBuildError, StackReadinessError } from "./errors.ts";
 import type { FunctionsConfig } from "./functions.ts";
-import { StackLifecycleCoordinator } from "./StackLifecycleCoordinator.ts";
-import type { EdgeRuntimeConfig, ResolvedStackConfig } from "./StackConfig.ts";
+import type { EdgeRuntimeConfig, ReadyOptions } from "./StackConfig.ts";
 import { StackServiceState } from "./StackServiceState.ts";
 
 export interface StackInfo {
@@ -49,30 +48,43 @@ export interface EdgeRuntimeReloadConfig {
   readonly functions?: FunctionsConfig;
 }
 
-type StackService = typeof Stack.Service;
-
 export class Stack extends Context.Service<
   Stack,
   {
     readonly getInfo: () => Effect.Effect<StackInfo>;
-    readonly start: () => Effect.Effect<void, ServiceReadyError | StackBuildError>;
+    readonly start: () => Effect.Effect<
+      void,
+      ServiceReadyError | StackBuildError | StackReadinessError
+    >;
     readonly stop: () => Effect.Effect<void>;
     readonly dispose: () => Effect.Effect<void>;
     readonly startService: (
       name: string,
-    ) => Effect.Effect<void, ServiceNotFoundError | ServiceReadyError | StackBuildError>;
+    ) => Effect.Effect<
+      void,
+      ServiceNotFoundError | ServiceReadyError | StackBuildError | StackReadinessError
+    >;
     readonly stopService: (
       name: string,
     ) => Effect.Effect<void, ServiceNotFoundError | StackBuildError>;
     readonly restartService: (
       name: string,
-    ) => Effect.Effect<void, ServiceNotFoundError | ServiceReadyError | StackBuildError>;
+    ) => Effect.Effect<
+      void,
+      ServiceNotFoundError | ServiceReadyError | StackBuildError | StackReadinessError
+    >;
     readonly reloadFunctions: (
       opts?: FunctionsConfig,
-    ) => Effect.Effect<void, ServiceNotFoundError | ServiceReadyError | StackBuildError>;
+    ) => Effect.Effect<
+      void,
+      ServiceNotFoundError | ServiceReadyError | StackBuildError | StackReadinessError
+    >;
     readonly reloadEdgeRuntime: (
       opts: EdgeRuntimeReloadConfig,
-    ) => Effect.Effect<void, ServiceNotFoundError | ServiceReadyError | StackBuildError>;
+    ) => Effect.Effect<
+      void,
+      ServiceNotFoundError | ServiceReadyError | StackBuildError | StackReadinessError
+    >;
     readonly getState: (name: string) => Effect.Effect<StackServiceState, ServiceNotFoundError>;
     readonly getAllStates: () => Effect.Effect<ReadonlyArray<StackServiceState>>;
     readonly stateChanges: (
@@ -81,8 +93,14 @@ export class Stack extends Context.Service<
     readonly allStateChanges: () => Stream.Stream<StackServiceState>;
     readonly waitReady: (
       name: string,
-    ) => Effect.Effect<void, ServiceNotFoundError | ServiceReadyError | StackBuildError>;
-    readonly waitAllReady: () => Effect.Effect<void, ServiceReadyError | StackBuildError>;
+      opts?: ReadyOptions,
+    ) => Effect.Effect<
+      void,
+      ServiceNotFoundError | ServiceReadyError | StackBuildError | StackReadinessError
+    >;
+    readonly waitAllReady: (
+      opts?: ReadyOptions,
+    ) => Effect.Effect<void, ServiceReadyError | StackBuildError | StackReadinessError>;
     readonly subscribeLogs: (name: string) => Stream.Stream<LogEntry>;
     readonly subscribeAllLogs: (services?: ReadonlyArray<string>) => Stream.Stream<LogEntry>;
     readonly logHistory: (name: string, limit?: number) => Effect.Effect<ReadonlyArray<LogEntry>>;
@@ -91,35 +109,4 @@ export class Stack extends Context.Service<
       services?: ReadonlyArray<string>,
     ) => Effect.Effect<ReadonlyArray<LogEntry>>;
   }
->()("stack/Stack") {
-  static layer = (
-    _config: ResolvedStackConfig,
-  ): Layer.Layer<Stack, StackBuildError, StackLifecycleCoordinator> =>
-    Layer.effect(
-      this,
-      Effect.gen(function* () {
-        const coordinator = yield* StackLifecycleCoordinator;
-        return {
-          getInfo: coordinator.getInfo,
-          start: coordinator.start,
-          stop: coordinator.stop,
-          dispose: coordinator.dispose,
-          startService: coordinator.startService,
-          stopService: coordinator.stopService,
-          restartService: coordinator.restartService,
-          reloadFunctions: coordinator.reloadFunctions,
-          reloadEdgeRuntime: coordinator.reloadEdgeRuntime,
-          getState: coordinator.getState,
-          getAllStates: coordinator.getAllStates,
-          stateChanges: coordinator.stateChanges,
-          allStateChanges: coordinator.allStateChanges,
-          waitReady: coordinator.waitReady,
-          waitAllReady: coordinator.waitAllReady,
-          subscribeLogs: coordinator.subscribeLogs,
-          subscribeAllLogs: coordinator.subscribeAllLogs,
-          logHistory: coordinator.logHistory,
-          logHistoryAll: coordinator.logHistoryAll,
-        } satisfies StackService;
-      }),
-    );
-}
+>()("stack/Stack") {}
diff --git a/packages/stack/src/Stack.unit.test.ts b/packages/stack/src/Stack.unit.test.ts
index 1ee19f6389..f3286e0a53 100644
--- a/packages/stack/src/Stack.unit.test.ts
+++ b/packages/stack/src/Stack.unit.test.ts
@@ -6,8 +6,9 @@ import { mockChildProcessSpawner } from "../../process-compose/tests/helpers/moc
 import { mockBinaryResolver } from "../tests/helpers/mocks.ts";
 import { defaultPublishableKey, defaultSecretKey, generateJwt } from "./JwtGenerator.ts";
 import type { AllocatedPorts, PortField, PortLease } from "./PortAllocator.ts";
+import { StackServiceActivator } from "./ServiceActivation.ts";
 import { Stack } from "./Stack.ts";
-import { StackLifecycleCoordinator } from "./StackLifecycleCoordinator.ts";
+import { localStackLayer } from "./LocalStack.ts";
 import { StackMetadataPersistence } from "./StackMetadataPersistence.ts";
 import { StackPreparation } from "./StackPreparation.ts";
 import { StackBuilder } from "./StackBuilder.ts";
@@ -115,7 +116,7 @@ function setupLayer(
 ) {
   const resolver = mockBinaryResolver();
   const stackPreparationLayer = StackPreparation.layer.pipe(Layer.provide(resolver.layer));
-  const coordinatorLayer = StackLifecycleCoordinator.layer(config, portLease).pipe(
+  const layer = localStackLayer(config, portLease).pipe(
     Layer.provide(StackBuilder.layer),
     Layer.provide(stackPreparationLayer),
     Layer.provide(StackMetadataPersistence.noop),
@@ -123,9 +124,7 @@ function setupLayer(
     Layer.provide(BunServices.layer),
   );
 
-  const layer = Stack.layer(config).pipe(Layer.provide(coordinatorLayer));
-
-  return { coordinatorLayer, layer, resolver, spawner };
+  return { layer, resolver, spawner };
 }
 
 describe("Stack", () => {
@@ -306,16 +305,12 @@ describe("Stack", () => {
     });
     const spawner = mockChildProcessSpawner();
     const stackPreparationLayer = StackPreparation.layer.pipe(Layer.provide(resolver.layer));
-    const coordinatorLayer = StackLifecycleCoordinator.layer(
-      defaultConfig,
-      noopPortLease(defaultConfig.ports),
-    ).pipe(
+    const layer = localStackLayer(defaultConfig, noopPortLease(defaultConfig.ports)).pipe(
       Layer.provide(StackBuilder.layer),
       Layer.provide(stackPreparationLayer),
       Layer.provide(StackMetadataPersistence.noop),
     );
-    const layer = Stack.layer(defaultConfig).pipe(
-      Layer.provide(coordinatorLayer),
+    const providedLayer = layer.pipe(
       Layer.provide(spawner.layer),
       Layer.provide(BunServices.layer),
     );
@@ -334,7 +329,7 @@ describe("Stack", () => {
       yield* Fiber.interrupt(startFiber);
 
       expect(states.map((state) => state.status)).toContain("Downloading");
-    }).pipe(Effect.provide(layer));
+    }).pipe(Effect.provide(providedLayer));
   });
 
   it.effect("getState fails for internal helper services", () => {
@@ -391,16 +386,12 @@ describe("Stack", () => {
     const resolver = mockBinaryResolver({ failServices: ["postgres", "postgrest", "auth"] });
     const spawner = mockChildProcessSpawner({ exitCode: 1 });
     const stackPreparationLayer = StackPreparation.layer.pipe(Layer.provide(resolver.layer));
-    const coordinatorLayer = StackLifecycleCoordinator.layer(
-      defaultConfig,
-      noopPortLease(defaultConfig.ports),
-    ).pipe(
+    const layer = localStackLayer(defaultConfig, noopPortLease(defaultConfig.ports)).pipe(
       Layer.provide(StackBuilder.layer),
       Layer.provide(stackPreparationLayer),
       Layer.provide(StackMetadataPersistence.noop),
     );
-    const layer = Stack.layer(defaultConfig).pipe(
-      Layer.provide(coordinatorLayer),
+    const providedLayer = layer.pipe(
       Layer.provide(spawner.layer),
       Layer.provide(BunServices.layer),
     );
@@ -413,7 +404,7 @@ describe("Stack", () => {
       // No container was ever started: only prepare-phase docker commands ran.
       const startedContainers = spawner.spawned.filter((record) => record.args[0] === "run");
       expect(startedContainers).toEqual([]);
-    }).pipe(Effect.provide(layer));
+    }).pipe(Effect.provide(providedLayer));
   });
 
   it.live("lazy startup starts direct services without starting HTTP backends", () => {
@@ -455,21 +446,22 @@ describe("Stack", () => {
         version: DEFAULT_VERSIONS.imgproxy,
       },
     };
-    const { coordinatorLayer } = setupLayer(config);
+    const { layer } = setupLayer(config);
 
     return Effect.gen(function* () {
-      const coordinator = yield* StackLifecycleCoordinator;
-      yield* coordinator.start();
-      yield* coordinator.stopService("imgproxy");
+      const stack = yield* Stack;
+      const activator = yield* StackServiceActivator;
+      yield* stack.start();
+      yield* stack.stopService("imgproxy");
 
-      const error = yield* coordinator.activateService("storage").pipe(Effect.flip);
+      const error = yield* activator.activate("storage").pipe(Effect.flip);
 
       expect(error._tag).toBe("StackBuildError");
       if (error._tag === "StackBuildError") {
         expect(error.detail).toContain("imgproxy was explicitly stopped");
       }
-      yield* coordinator.stop();
-    }).pipe(Effect.provide(coordinatorLayer), Effect.timeout("5 seconds"));
+      yield* stack.stop();
+    }).pipe(Effect.provide(layer), Effect.timeout("5 seconds"));
   });
 
   it.live("lazy readiness includes an activation that is still starting", () =>
@@ -484,34 +476,35 @@ describe("Stack", () => {
             : Effect.void,
       });
       const config = { ...defaultConfig, startupMode: "lazy" } satisfies ResolvedStackConfig;
-      const { coordinatorLayer } = setupLayer(config, noopPortLease(config.ports), spawner);
+      const { layer } = setupLayer(config, noopPortLease(config.ports), spawner);
 
       yield* Effect.gen(function* () {
-        const coordinator = yield* StackLifecycleCoordinator;
-        yield* coordinator.start();
-        expect((yield* coordinator.getState("auth")).status).toBe("Dormant");
-        const activeStateFiber = yield* coordinator.allStateChanges().pipe(
+        const stack = yield* Stack;
+        const activator = yield* StackServiceActivator;
+        yield* stack.start();
+        expect((yield* stack.getState("auth")).status).toBe("Dormant");
+        const activeStateFiber = yield* stack.allStateChanges().pipe(
           Stream.filter((state) => state.name === "auth" && state.status !== "Dormant"),
           Stream.runHead,
           Effect.forkChild({ startImmediately: true }),
         );
-        const activationFiber = yield* coordinator
-          .activateService("auth")
+        const activationFiber = yield* activator
+          .activate("auth")
           .pipe(Effect.forkChild({ startImmediately: true }));
         yield* Deferred.await(spawnStarted);
         expect((yield* Fiber.join(activeStateFiber))._tag).toBe("Some");
-        expect((yield* coordinator.getState("auth")).status).not.toBe("Dormant");
+        expect((yield* stack.getState("auth")).status).not.toBe("Dormant");
 
-        const readyFiber = yield* coordinator
+        const readyFiber = yield* stack
           .waitAllReady()
           .pipe(Effect.forkChild({ startImmediately: true }));
         yield* Effect.yieldNow;
         expect(readyFiber.pollUnsafe()).toBeUndefined();
 
-        yield* coordinator.stop().pipe(Effect.timeout("1 second"));
+        yield* stack.stop().pipe(Effect.timeout("1 second"));
         yield* Fiber.interrupt(readyFiber);
         yield* Fiber.interrupt(activationFiber);
-      }).pipe(Effect.provide(coordinatorLayer));
+      }).pipe(Effect.provide(layer));
     }).pipe(Effect.scoped, Effect.timeout("5 seconds")),
   );
 
@@ -529,25 +522,26 @@ describe("Stack", () => {
               : Effect.void,
         });
         const config = { ...defaultConfig, startupMode: "lazy" } satisfies ResolvedStackConfig;
-        const { coordinatorLayer } = setupLayer(config, noopPortLease(config.ports), spawner);
+        const { layer } = setupLayer(config, noopPortLease(config.ports), spawner);
 
         yield* Effect.gen(function* () {
-          const coordinator = yield* StackLifecycleCoordinator;
-          yield* coordinator.start();
-          const manualStart = yield* coordinator
+          const stack = yield* Stack;
+          const activator = yield* StackServiceActivator;
+          yield* stack.start();
+          const manualStart = yield* stack
             .startService("auth")
             .pipe(Effect.forkChild({ startImmediately: true }));
           yield* Deferred.await(authSpawnStarted);
 
           const activationCompleted = yield* Effect.race(
-            coordinator.activateService("postgres").pipe(Effect.as(true)),
+            activator.activate("postgres").pipe(Effect.as(true)),
             Effect.sleep("200 millis").pipe(Effect.as(false)),
           );
 
           yield* Fiber.interrupt(manualStart);
           expect(activationCompleted).toBe(true);
-          yield* coordinator.stop();
-        }).pipe(Effect.provide(coordinatorLayer));
+          yield* stack.stop();
+        }).pipe(Effect.provide(layer));
       }).pipe(Effect.scoped, Effect.timeout("5 seconds")),
   );
 
@@ -582,13 +576,11 @@ describe("Stack", () => {
               : Effect.void,
         releaseAll: Effect.void,
       };
-      const { coordinatorLayer } = setupLayer(config, lease);
+      const { layer } = setupLayer(config, lease);
 
       yield* Effect.gen(function* () {
-        const coordinator = yield* StackLifecycleCoordinator;
-        const starting = yield* coordinator
-          .start()
-          .pipe(Effect.forkChild({ startImmediately: true }));
+        const stack = yield* Stack;
+        const starting = yield* stack.start().pipe(Effect.forkChild({ startImmediately: true }));
         yield* Deferred.await(postgresReleaseStarted);
 
         const mailpitBeganConcurrently = yield* Effect.race(
@@ -599,8 +591,8 @@ describe("Stack", () => {
         yield* Fiber.interrupt(starting);
 
         expect(mailpitBeganConcurrently).toBe(true);
-        yield* coordinator.stop();
-      }).pipe(Effect.provide(coordinatorLayer));
+        yield* stack.stop();
+      }).pipe(Effect.provide(layer));
     }).pipe(Effect.scoped, Effect.timeout("5 seconds")),
   );
 
@@ -619,17 +611,18 @@ describe("Stack", () => {
             : Effect.void,
       });
       const config = { ...defaultConfig, startupMode: "lazy" } satisfies ResolvedStackConfig;
-      const { coordinatorLayer } = setupLayer(config, noopPortLease(config.ports), spawner);
+      const { layer } = setupLayer(config, noopPortLease(config.ports), spawner);
 
       yield* Effect.gen(function* () {
-        const coordinator = yield* StackLifecycleCoordinator;
-        yield* coordinator.start();
-        const activationFiber = yield* coordinator
-          .activateService("auth")
+        const stack = yield* Stack;
+        const activator = yield* StackServiceActivator;
+        yield* stack.start();
+        const activationFiber = yield* activator
+          .activate("auth")
           .pipe(Effect.forkChild({ startImmediately: true }));
         yield* Deferred.await(spawnStarted);
 
-        const disposeFiber = yield* coordinator
+        const disposeFiber = yield* stack
           .dispose()
           .pipe(Effect.forkChild({ startImmediately: true }));
         yield* Fiber.join(disposeFiber);
@@ -639,9 +632,116 @@ describe("Stack", () => {
 
         expect(spawner.spawned.some((record) => record.command.endsWith("/auth"))).toBe(false);
 
-        const error = yield* coordinator.activateService("auth").pipe(Effect.flip);
+        const error = yield* activator.activate("auth").pipe(Effect.flip);
         expect(error._tag).toBe("StackNotRunningError");
-      }).pipe(Effect.provide(coordinatorLayer));
+      }).pipe(Effect.provide(layer));
+    }).pipe(Effect.scoped, Effect.timeout("5 seconds")),
+  );
+
+  it.live("uses the stack readiness deadline for explicit lazy activation and cleans up", () =>
+    Effect.gen(function* () {
+      const spawnStarted = yield* Deferred.make<void>();
+      const spawner = mockChildProcessSpawner({
+        beforeSpawn: (record) =>
+          record.args.some((arg) =>
+            Buffer.from(arg, "base64url").toString().includes('"command":"/cache/auth/'),
+          )
+            ? Deferred.succeed(spawnStarted, undefined).pipe(Effect.andThen(Effect.never))
+            : Effect.void,
+      });
+      let releasedAll = false;
+      const config = {
+        ...defaultConfig,
+        startupMode: "lazy",
+        readiness: { mode: "finite", timeoutMs: 250 },
+      } satisfies ResolvedStackConfig;
+      const lease: PortLease = {
+        ...noopPortLease(config.ports),
+        releaseAll: Effect.sync(() => {
+          releasedAll = true;
+        }),
+      };
+      const { layer } = setupLayer(config, lease, spawner);
+
+      yield* Effect.gen(function* () {
+        const stack = yield* Stack;
+        const activator = yield* StackServiceActivator;
+        yield* stack.start();
+
+        const error = yield* activator.activate("auth").pipe(Effect.flip);
+
+        expect(error._tag).toBe("StackReadinessError");
+        if (error._tag === "StackReadinessError") {
+          expect(error.target).toBe("auth");
+          expect(error.timeoutMs).toBe(250);
+        }
+        expect(releasedAll).toBe(true);
+        const spawnCountAfterDisposal = spawner.spawned.length;
+        expect((yield* activator.activate("postgres").pipe(Effect.flip))._tag).toBe(
+          "StackNotRunningError",
+        );
+        for (const operation of [
+          stack.start(),
+          stack.startService("postgres"),
+          stack.stopService("postgres"),
+          stack.restartService("postgres"),
+          stack.reloadFunctions(),
+          stack.reloadEdgeRuntime({ edgeRuntime: {} }),
+        ]) {
+          expect((yield* operation.pipe(Effect.flip))._tag).toBe("StackBuildError");
+        }
+        yield* stack.stop();
+        expect(spawner.spawned).toHaveLength(spawnCountAfterDisposal);
+      }).pipe(Effect.provide(layer));
+    }).pipe(Effect.scoped, Effect.timeout("5 seconds")),
+  );
+
+  it.live("allows a finite wait override against an infinite stack policy", () =>
+    Effect.gen(function* () {
+      const spawnStarted = yield* Deferred.make<void>();
+      const spawner = mockChildProcessSpawner({
+        beforeSpawn: (record) =>
+          record.args.some((arg) =>
+            Buffer.from(arg, "base64url").toString().includes('"command":"/cache/auth/'),
+          )
+            ? Deferred.succeed(spawnStarted, undefined).pipe(Effect.andThen(Effect.never))
+            : Effect.void,
+      });
+      let releasedAll = false;
+      const config = {
+        ...defaultConfig,
+        startupMode: "lazy",
+        readiness: { mode: "infinite" },
+      } satisfies ResolvedStackConfig;
+      const lease: PortLease = {
+        ...noopPortLease(config.ports),
+        releaseAll: Effect.sync(() => {
+          releasedAll = true;
+        }),
+      };
+      const { layer } = setupLayer(config, lease, spawner);
+
+      yield* Effect.gen(function* () {
+        const stack = yield* Stack;
+        const activator = yield* StackServiceActivator;
+        yield* stack.start();
+        const activation = yield* activator
+          .activate("auth")
+          .pipe(Effect.forkChild({ startImmediately: true }));
+        yield* Deferred.await(spawnStarted);
+
+        const error = yield* stack
+          .waitAllReady({ mode: "finite", timeoutMs: 25 })
+          .pipe(Effect.flip);
+
+        expect(error._tag).toBe("StackReadinessError");
+        if (error._tag === "StackReadinessError") {
+          expect(error.target).toBe("stack");
+          expect(error.timeoutMs).toBe(25);
+        }
+        expect(releasedAll).toBe(true);
+        yield* Fiber.interrupt(activation);
+      }).pipe(Effect.provide(layer));
     }).pipe(Effect.scoped, Effect.timeout("5 seconds")),
   );
 
@@ -664,31 +764,32 @@ describe("Stack", () => {
       if (authConfig === false) {
         throw new Error("Expected auth to be enabled in the default test config");
       }
-      const { coordinatorLayer, spawner } = setupLayer({
+      const { layer, spawner } = setupLayer({
         ...defaultConfig,
         startupMode: "lazy",
         ports: { ...defaultPorts, authPort },
         auth: { ...authConfig, port: authPort },
       });
       yield* Effect.gen(function* () {
-        const coordinator = yield* StackLifecycleCoordinator;
+        const stack = yield* Stack;
+        const activator = yield* StackServiceActivator;
         const isAuthStart = (record: { readonly args: ReadonlyArray<string> }) =>
           record.args.some((arg) =>
             Buffer.from(arg, "base64url").toString().includes('"command":"/cache/auth/'),
           );
-        yield* coordinator.start();
-        yield* coordinator.activateService("auth");
+        yield* stack.start();
+        yield* activator.activate("auth");
         const initialAuthStarts = spawner.spawned.filter(isAuthStart).length;
         expect(initialAuthStarts).toBeGreaterThan(0);
 
-        yield* coordinator.stopService("postgres");
-        yield* coordinator.restartService("postgres");
-        yield* coordinator.waitAllReady();
+        yield* stack.stopService("postgres");
+        yield* stack.restartService("postgres");
+        yield* stack.waitAllReady();
 
         expect(spawner.spawned.filter(isAuthStart)).toHaveLength(initialAuthStarts);
-        expect((yield* coordinator.getState("auth")).status).toBe("Stopped");
-        yield* coordinator.stop();
-      }).pipe(Effect.provide(coordinatorLayer));
+        expect((yield* stack.getState("auth")).status).toBe("Stopped");
+        yield* stack.stop();
+      }).pipe(Effect.provide(layer));
     }).pipe(Effect.scoped, Effect.timeout("5 seconds"));
   });
 
@@ -710,52 +811,53 @@ describe("Stack", () => {
 
   it.live("keeps unactivated services dormant after a stop and start cycle", () => {
     const config = { ...defaultConfig, startupMode: "lazy" } satisfies ResolvedStackConfig;
-    const { coordinatorLayer } = setupLayer(config);
+    const { layer } = setupLayer(config);
 
     return Effect.gen(function* () {
-      const coordinator = yield* StackLifecycleCoordinator;
-      yield* coordinator.start();
-      expect((yield* coordinator.getState("auth")).status).toBe("Dormant");
+      const stack = yield* Stack;
+      yield* stack.start();
+      expect((yield* stack.getState("auth")).status).toBe("Dormant");
 
-      yield* coordinator.stop();
-      yield* coordinator.start();
+      yield* stack.stop();
+      yield* stack.start();
 
-      expect((yield* coordinator.getState("auth")).status).toBe("Dormant");
-      yield* coordinator.stop();
-    }).pipe(Effect.provide(coordinatorLayer), Effect.timeout("5 seconds"));
+      expect((yield* stack.getState("auth")).status).toBe("Dormant");
+      yield* stack.stop();
+    }).pipe(Effect.provide(layer), Effect.timeout("5 seconds"));
   });
 
   it.live("rejects a cached activation after the stack has stopped", () => {
     const config = { ...defaultConfig, startupMode: "lazy" } satisfies ResolvedStackConfig;
-    const { coordinatorLayer } = setupLayer(config);
+    const { layer } = setupLayer(config);
 
     return Effect.gen(function* () {
-      const coordinator = yield* StackLifecycleCoordinator;
-      yield* coordinator.start();
-      yield* coordinator.stop();
+      const stack = yield* Stack;
+      const activator = yield* StackServiceActivator;
+      yield* stack.start();
+      yield* stack.stop();
 
-      const error = yield* coordinator.activateService("postgres").pipe(Effect.flip);
+      const error = yield* activator.activate("postgres").pipe(Effect.flip);
       expect(error._tag).toBe("StackNotRunningError");
-    }).pipe(Effect.provide(coordinatorLayer), Effect.timeout("5 seconds"));
+    }).pipe(Effect.provide(layer), Effect.timeout("5 seconds"));
   });
 
   it.live("preserves an explicitly stopped service across a stack restart", () => {
     const config = { ...defaultConfig, startupMode: "lazy" } satisfies ResolvedStackConfig;
-    const { coordinatorLayer } = setupLayer(config);
+    const { layer } = setupLayer(config);
 
     return Effect.gen(function* () {
-      const coordinator = yield* StackLifecycleCoordinator;
-      yield* coordinator.start();
-      yield* coordinator.stopService("auth");
+      const stack = yield* Stack;
+      yield* stack.start();
+      yield* stack.stopService("auth");
       yield* Effect.sleep("20 millis");
-      expect((yield* coordinator.getState("auth")).status).toBe("Stopped");
+      expect((yield* stack.getState("auth")).status).toBe("Stopped");
 
-      yield* coordinator.stop();
-      yield* coordinator.start();
+      yield* stack.stop();
+      yield* stack.start();
 
-      expect((yield* coordinator.getState("auth")).status).toBe("Stopped");
-      yield* coordinator.stop();
-    }).pipe(Effect.provide(coordinatorLayer), Effect.timeout("5 seconds"));
+      expect((yield* stack.getState("auth")).status).toBe("Stopped");
+      yield* stack.stop();
+    }).pipe(Effect.provide(layer), Effect.timeout("5 seconds"));
   });
 
   it.live("releases only the ports in a lazy service dependency closure", () => {
diff --git a/packages/stack/src/StackConfig.ts b/packages/stack/src/StackConfig.ts
index cbf6552fc8..32d1251225 100644
--- a/packages/stack/src/StackConfig.ts
+++ b/packages/stack/src/StackConfig.ts
@@ -1,3 +1,4 @@
+import { Schema } from "effect";
 import type { FunctionsConfig, ResolvedFunctionsConfig } from "./functions.ts";
 import type { AllocatedPorts } from "./PortAllocator.ts";
 
@@ -10,6 +11,22 @@ export type ReadinessPolicy =
 
 export type ReadyOptions = { readonly mode: "inherit" } | ReadinessPolicy;
 
+const ReadinessPolicySchema = Schema.Union([
+  Schema.Struct({
+    mode: Schema.Literal("finite"),
+    timeoutMs: Schema.Int.check(Schema.isGreaterThan(0)),
+  }),
+  Schema.Struct({ mode: Schema.Literal("infinite") }),
+]);
+
+/** The single wire representation accepted by Effect, Promise, and daemon Adapters. */
+export const ReadyOptionsSchema = Schema.Union([
+  Schema.Struct({ mode: Schema.Literal("inherit") }),
+  ReadinessPolicySchema,
+]);
+
+export const inheritReadyOptions: ReadyOptions = { mode: "inherit" };
+
 /** Standalone stacks wait at most two minutes unless a caller or launch Adapter chooses otherwise. */
 export const DEFAULT_STACK_READINESS_POLICY: ReadinessPolicy = {
   mode: "finite",
diff --git a/packages/stack/src/StackConfig.unit.test.ts b/packages/stack/src/StackConfig.unit.test.ts
index 9c3d3b0a84..2c160900f5 100644
--- a/packages/stack/src/StackConfig.unit.test.ts
+++ b/packages/stack/src/StackConfig.unit.test.ts
@@ -1,6 +1,8 @@
 import { describe, expect, it } from "vitest";
+import { Schema } from "effect";
 import {
   DEFAULT_STACK_READINESS_POLICY,
+  ReadyOptionsSchema,
   resolveReadinessPolicy,
   type ReadinessPolicy,
 } from "./StackConfig.ts";
@@ -57,3 +59,22 @@ describe("resolveReadinessPolicy", () => {
     ).toEqual(finite(30_000));
   });
 });
+
+describe("ReadyOptionsSchema", () => {
+  const decode = Schema.decodeUnknownSync(ReadyOptionsSchema);
+
+  it("accepts the three readiness override modes", () => {
+    expect(decode({ mode: "inherit" })).toEqual({ mode: "inherit" });
+    expect(decode({ mode: "infinite" })).toEqual({ mode: "infinite" });
+    expect(decode({ mode: "finite", timeoutMs: 25 })).toEqual({
+      mode: "finite",
+      timeoutMs: 25,
+    });
+  });
+
+  it("rejects malformed and non-positive finite deadlines", () => {
+    expect(() => decode({ mode: "finite", timeoutMs: 0 })).toThrow();
+    expect(() => decode({ mode: "finite", timeoutMs: -1 })).toThrow();
+    expect(() => decode({ mode: "forever" })).toThrow();
+  });
+});
diff --git a/packages/stack/src/StackLifecycleCoordinator.ts b/packages/stack/src/StackLifecycleCoordinator.ts
deleted file mode 100644
index fe5f82bc42..0000000000
--- a/packages/stack/src/StackLifecycleCoordinator.ts
+++ /dev/null
@@ -1,880 +0,0 @@
-import { LogBuffer, Orchestrator } from "@supabase/process-compose";
-import { ServiceNotFoundError } from "@supabase/process-compose";
-import type { LogEntry, ResolvedGraph, ServiceReadyError } from "@supabase/process-compose";
-import {
-  Deferred,
-  Effect,
-  FileSystem,
-  Layer,
-  Path,
-  Ref,
-  Semaphore,
-  Context,
-  Stream,
-  SubscriptionRef,
-} from "effect";
-import { ChildProcessSpawner } from "effect/unstable/process";
-import type { CleanupTargets } from "./CleanupTargets.ts";
-import { cleanupLocalStackResources } from "./cleanup.ts";
-import { StackBuildError, StackNotRunningError } from "./errors.ts";
-import { configureFunctionsRuntime, type FunctionsConfig } from "./functions.ts";
-import { detectPlatform, dockerHostAddress } from "./Platform.ts";
-import type { PortLease } from "./PortAllocator.ts";
-import {
-  activationTargetsForService,
-  eagerServices,
-  lifecycleTargetsForService,
-} from "./ServiceActivation.ts";
-import { portFieldsForService } from "./ServicePorts.ts";
-import { StackMetadataPersistence } from "./StackMetadataPersistence.ts";
-import { StackPreparation } from "./StackPreparation.ts";
-import type { PreparedStackArtifacts } from "./StackPreparation.ts";
-import {
-  enabledServicesForConfig,
-  StackBuilder,
-  validateResolvedConfig,
-  versionsForConfig,
-} from "./StackBuilder.ts";
-import type { ResolvedStackConfig } from "./StackConfig.ts";
-import { changedProjectedStates, projectStackStates } from "./StackStateProjection.ts";
-import { StackServiceState } from "./StackServiceState.ts";
-import type { EdgeRuntimeReloadConfig, StackInfo } from "./Stack.ts";
-import { SERVICE_NAMES, type ServiceName } from "./versions.ts";
-
-type LifecyclePhase =
-  | "idle"
-  | "preparing"
-  | "prepared"
-  | "starting"
-  | "running"
-  | "stopping"
-  | "stopped";
-
-interface RuntimeState {
-  readonly orchestrator: Orchestrator["Service"];
-  readonly graph: ResolvedGraph;
-  readonly cleanupTargets: CleanupTargets;
-}
-
-const sameState = (a: StackServiceState | undefined, b: StackServiceState): boolean =>
-  a?.name === b.name &&
-  a.status === b.status &&
-  a.pid === b.pid &&
-  a.exitCode === b.exitCode &&
-  a.restartCount === b.restartCount &&
-  a.startedAt === b.startedAt &&
-  a.error === b.error;
-
-const initialPublicStates = (config: ResolvedStackConfig): ReadonlyArray<StackServiceState> =>
-  enabledServicesForConfig(config).map(
-    (name) =>
-      new StackServiceState({
-        name,
-        status: "Pending",
-        pid: null,
-        exitCode: null,
-        restartCount: 0,
-        startedAt: null,
-        error: null,
-      }),
-  );
-
-const stackInfoFor = (config: ResolvedStackConfig): StackInfo => {
-  const apiUrl = `http://127.0.0.1:${config.apiPort}`;
-  return {
-    url: apiUrl,
-    dbUrl: `postgresql://postgres:postgres@127.0.0.1:${config.dbPort}/postgres`,
-    publishableKey: config.publishableKey,
-    secretKey: config.secretKey,
-    anonJwt: config.anonJwt,
-    serviceRoleJwt: config.serviceRoleJwt,
-    serviceEndpoints: {
-      ...(config.auth === false ? {} : { auth: `${apiUrl}/auth/v1` }),
-      ...(config.postgrest === false ? {} : { postgrest: `${apiUrl}/rest/v1` }),
-      ...(config.edgeRuntime === false
-        ? {}
-        : {
-            functions: `${apiUrl}/functions/v1`,
-            edge_runtime: `${apiUrl}/functions/v1`,
-          }),
-      ...(config.realtime === false ? {} : { realtime: `${apiUrl}/realtime/v1` }),
-      ...(config.storage === false
-        ? {}
-        : {
-            storage: `${apiUrl}/storage/v1`,
-            storage_s3: `${apiUrl}/storage/v1/s3`,
-          }),
-      ...(config.imgproxy === false || config.startupMode === "lazy"
-        ? {}
-        : { imgproxy: `http://127.0.0.1:${config.imgproxy.port}` }),
-      ...(config.mailpit === false
-        ? {}
-        : {
-            mailpit: `http://127.0.0.1:${config.mailpit.port}`,
-            mailpit_smtp: `smtp://127.0.0.1:${config.mailpit.smtpPort}`,
-            mailpit_pop3: `pop3://127.0.0.1:${config.mailpit.pop3Port}`,
-          }),
-      ...(config.pgmeta === false ? {} : { pgmeta: `${apiUrl}/pg` }),
-      ...(config.studio === false ? {} : { studio: `http://127.0.0.1:${config.studio.port}` }),
-      ...(config.analytics === false ? {} : { analytics: `${apiUrl}/analytics/v1` }),
-      ...(config.pooler === false
-        ? {}
-        : {
-            pooler: `postgresql://postgres:postgres@127.0.0.1:${config.pooler.port}/postgres`,
-            pooler_admin: `http://127.0.0.1:${config.pooler.apiPort}`,
-          }),
-    },
-  };
-};
-
-const changedStatesBetween = (
-  previous: ReadonlyArray<StackServiceState> | undefined,
-  current: ReadonlyArray<StackServiceState>,
-): ReadonlyArray<StackServiceState> => {
-  if (previous === undefined) {
-    return current;
-  }
-
-  const previousByName = new Map(previous.map((state) => [state.name, state] as const));
-  return current.filter((state) => !sameState(previousByName.get(state.name), state));
-};
-
-export class StackLifecycleCoordinator extends Context.Service<
-  StackLifecycleCoordinator,
-  {
-    readonly getInfo: () => Effect.Effect<StackInfo>;
-    readonly getCleanupTargets: () => Effect.Effect<CleanupTargets>;
-    readonly start: () => Effect.Effect<void, ServiceReadyError | StackBuildError>;
-    readonly stop: () => Effect.Effect<void>;
-    readonly dispose: () => Effect.Effect<void>;
-    readonly startService: (
-      name: string,
-    ) => Effect.Effect<void, ServiceNotFoundError | ServiceReadyError | StackBuildError>;
-    readonly activateService: (
-      name: ServiceName,
-    ) => Effect.Effect<
-      void,
-      ServiceNotFoundError | ServiceReadyError | StackBuildError | StackNotRunningError
-    >;
-    readonly stopService: (
-      name: string,
-    ) => Effect.Effect<void, ServiceNotFoundError | StackBuildError>;
-    readonly restartService: (
-      name: string,
-    ) => Effect.Effect<void, ServiceNotFoundError | ServiceReadyError | StackBuildError>;
-    readonly reloadFunctions: (
-      opts?: FunctionsConfig,
-    ) => Effect.Effect<void, ServiceNotFoundError | ServiceReadyError | StackBuildError>;
-    readonly reloadEdgeRuntime: (
-      opts: EdgeRuntimeReloadConfig,
-    ) => Effect.Effect<void, ServiceNotFoundError | ServiceReadyError | StackBuildError>;
-    readonly getState: (name: string) => Effect.Effect<StackServiceState, ServiceNotFoundError>;
-    readonly getAllStates: () => Effect.Effect<ReadonlyArray<StackServiceState>>;
-    readonly stateChanges: (
-      name: string,
-    ) => Effect.Effect<Stream.Stream<StackServiceState>, ServiceNotFoundError>;
-    readonly allStateChanges: () => Stream.Stream<StackServiceState>;
-    readonly waitReady: (
-      name: string,
-    ) => Effect.Effect<void, ServiceNotFoundError | ServiceReadyError | StackBuildError>;
-    readonly waitAllReady: () => Effect.Effect<void, ServiceReadyError | StackBuildError>;
-    readonly subscribeLogs: (name: string) => Stream.Stream<LogEntry>;
-    readonly subscribeAllLogs: (services?: ReadonlyArray<string>) => Stream.Stream<LogEntry>;
-    readonly logHistory: (name: string, limit?: number) => Effect.Effect<ReadonlyArray<LogEntry>>;
-    readonly logHistoryAll: (
-      limit?: number,
-      services?: ReadonlyArray<string>,
-    ) => Effect.Effect<ReadonlyArray<LogEntry>>;
-  }
->()("stack/StackLifecycleCoordinator") {
-  static layer = (
-    config: ResolvedStackConfig,
-    portLease: PortLease,
-  ): Layer.Layer<
-    StackLifecycleCoordinator,
-    StackBuildError,
-    | StackBuilder
-    | StackPreparation
-    | ChildProcessSpawner.ChildProcessSpawner
-    | StackMetadataPersistence
-    | FileSystem.FileSystem
-    | Path.Path
-  > =>
-    Layer.effect(
-      this,
-      Effect.gen(function* () {
-        const builder = yield* StackBuilder;
-        const preparation = yield* StackPreparation;
-        const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-        const metadataPersistence = yield* StackMetadataPersistence;
-        const fs = yield* FileSystem.FileSystem;
-        const path = yield* Path.Path;
-        const scope = yield* Effect.scope;
-
-        const info = stackInfoFor(config);
-        const enabledServices = enabledServicesForConfig(config);
-        const stateRef = yield* SubscriptionRef.make(initialPublicStates(config));
-        const phaseRef = yield* Ref.make<LifecyclePhase>("idle");
-        const lifecycleLock = Semaphore.makeUnsafe(1);
-
-        const logBufferServices = yield* Layer.buildWithScope(LogBuffer.layer, scope);
-        const logBuffer = Context.get(logBufferServices, LogBuffer);
-
-        const updateState = (nextState: StackServiceState) =>
-          SubscriptionRef.update(stateRef, (current) => {
-            const previous = current.find((entry) => entry.name === nextState.name);
-            if (sameState(previous, nextState)) {
-              return current;
-            }
-            return current.some((entry) => entry.name === nextState.name)
-              ? current.map((entry) => (entry.name === nextState.name ? nextState : entry))
-              : [...current, nextState];
-          });
-
-        const requireKnownService = (name: string) =>
-          Effect.gen(function* () {
-            const currentStates = SubscriptionRef.getUnsafe(stateRef);
-            const match = currentStates.find((state) => state.name === name);
-            if (match === undefined) {
-              return yield* Effect.fail(new ServiceNotFoundError({ name }));
-            }
-            return match;
-          });
-        const requireKnownServiceName = (
-          name: string,
-        ): Effect.Effect<ServiceName, ServiceNotFoundError> =>
-          Effect.gen(function* () {
-            yield* requireKnownService(name);
-            const service = SERVICE_NAMES.find((candidate) => candidate === name);
-            if (service === undefined) {
-              return yield* Effect.fail(new ServiceNotFoundError({ name }));
-            }
-            return service;
-          });
-
-        let preparedArtifacts: PreparedStackArtifacts | undefined;
-        let prepareDeferred: Deferred.Deferred<PreparedStackArtifacts, StackBuildError> | undefined;
-        let runtimeState: RuntimeState | undefined;
-        let runtimeDeferred: Deferred.Deferred<RuntimeState, StackBuildError> | undefined;
-
-        const ensurePrepared = Effect.suspend(() => {
-          if (preparedArtifacts !== undefined) {
-            return Effect.succeed(preparedArtifacts);
-          }
-          if (prepareDeferred !== undefined) {
-            return Deferred.await(prepareDeferred);
-          }
-
-          const deferred = Deferred.makeUnsafe<PreparedStackArtifacts, StackBuildError>();
-          prepareDeferred = deferred;
-
-          const effect = Effect.gen(function* () {
-            yield* validateResolvedConfig(config);
-            yield* Ref.set(phaseRef, "preparing");
-
-            let prepared: PreparedStackArtifacts | undefined;
-            yield* preparation
-              .prepareEvents({
-                mode: config.mode,
-                services: enabledServicesForConfig(config),
-                versions: versionsForConfig(config),
-              })
-              .pipe(
-                Stream.mapError(
-                  (cause) =>
-                    new StackBuildError({
-                      detail: "Failed to prepare stack assets",
-                      cause,
-                    }),
-                ),
-              )
-              .pipe(
-                Stream.runForEach((event) => {
-                  switch (event._tag) {
-                    case "ServiceDownloadStarted":
-                      return updateState(
-                        new StackServiceState({
-                          name: event.service,
-                          status: "Downloading",
-                          pid: null,
-                          exitCode: null,
-                          restartCount: 0,
-                          startedAt: null,
-                          error: null,
-                        }),
-                      );
-                    case "ServiceDownloadFinished":
-                      return updateState(
-                        new StackServiceState({
-                          name: event.service,
-                          status: "Pending",
-                          pid: null,
-                          exitCode: null,
-                          restartCount: 0,
-                          startedAt: null,
-                          error: null,
-                        }),
-                      );
-                    case "PreparationCompleted":
-                      return Effect.sync(() => {
-                        prepared = event.artifacts;
-                      });
-                  }
-                }),
-              );
-
-            if (prepared === undefined) {
-              return yield* Effect.fail(
-                new StackBuildError({
-                  detail: "Stack preparation completed without prepared artifacts",
-                }),
-              );
-            }
-
-            yield* Ref.set(phaseRef, "prepared");
-            return prepared;
-          }).pipe(
-            Effect.tap((value) =>
-              Effect.sync(() => {
-                preparedArtifacts = value;
-              }),
-            ),
-            Effect.onError(() => Ref.set(phaseRef, "idle")),
-            Effect.ensuring(
-              Effect.sync(() => {
-                prepareDeferred = undefined;
-              }),
-            ),
-          );
-
-          return Effect.gen(function* () {
-            yield* Effect.forkIn(effect.pipe(Deferred.into(deferred)), scope);
-            return yield* Deferred.await(deferred);
-          });
-        });
-
-        const ensureRuntime = Effect.suspend(() => {
-          if (runtimeState !== undefined) {
-            return Effect.succeed(runtimeState);
-          }
-          if (runtimeDeferred !== undefined) {
-            return Deferred.await(runtimeDeferred);
-          }
-
-          const deferred = Deferred.makeUnsafe<RuntimeState, StackBuildError>();
-          runtimeDeferred = deferred;
-
-          const effect = Effect.gen(function* () {
-            const prepared = yield* ensurePrepared;
-            const { graph, serviceProjection, cleanupTargets } = yield* builder.build(
-              config,
-              prepared,
-            );
-
-            yield* metadataPersistence.persistCleanupTargets(cleanupTargets).pipe(
-              Effect.mapError(
-                (cause) =>
-                  new StackBuildError({
-                    detail: "Failed to persist stack cleanup metadata",
-                    cause,
-                  }),
-              ),
-            );
-
-            const orchLayer = Orchestrator.layer(graph).pipe(
-              Layer.provide(Layer.succeed(LogBuffer, logBuffer)),
-              Layer.provide(Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner)),
-            );
-            const orchServices = yield* Layer.buildWithScope(orchLayer, scope);
-            const orchestrator = Context.get(orchServices, Orchestrator);
-
-            const projectedStates = Stream.unwrap(
-              Effect.gen(function* () {
-                const rawInitialStates = yield* orchestrator.getAllStates();
-                const initialProjected = projectStackStates(rawInitialStates, serviceProjection);
-                let rawStates = new Map(
-                  rawInitialStates.map((state) => [state.name, state] as const),
-                );
-                let projectedByName = new Map(
-                  initialProjected.map((state) => [state.name, state] as const),
-                );
-
-                return Stream.concat(
-                  Stream.fromIterable(initialProjected),
-                  orchestrator.allStateChanges().pipe(
-                    Stream.map((rawState) => {
-                      rawStates.set(rawState.name, rawState);
-                      const nextProjected = projectStackStates(
-                        [...rawStates.values()],
-                        serviceProjection,
-                      );
-                      const changed = changedProjectedStates(projectedByName, nextProjected);
-                      projectedByName = new Map(
-                        nextProjected.map((state) => [state.name, state] as const),
-                      );
-                      return changed;
-                    }),
-                    Stream.flatMap((states) => Stream.fromIterable(states)),
-                  ),
-                );
-              }),
-            );
-
-            yield* projectedStates.pipe(
-              Stream.runForEach((state) => updateState(state)),
-              Effect.ignore,
-              Effect.forkIn(scope),
-            );
-
-            return {
-              orchestrator,
-              graph,
-              cleanupTargets,
-            } satisfies RuntimeState;
-          }).pipe(
-            Effect.tap((value) =>
-              Effect.sync(() => {
-                runtimeState = value;
-              }),
-            ),
-            Effect.ensuring(
-              Effect.sync(() => {
-                runtimeDeferred = undefined;
-              }),
-            ),
-          );
-
-          return Effect.gen(function* () {
-            yield* Effect.forkIn(effect.pipe(Deferred.into(deferred)), scope);
-            return yield* Deferred.await(deferred);
-          });
-        });
-
-        let disposed = false;
-        const runtimeHost = Effect.gen(function* () {
-          const prepared = yield* ensurePrepared;
-          const platform = yield* detectPlatform;
-          const edgeRuntimeResolution = prepared.resolutions["edge-runtime"];
-          return {
-            hostname:
-              edgeRuntimeResolution?.type === "docker"
-                ? dockerHostAddress(platform.os)
-                : "127.0.0.1",
-          };
-        });
-        const providePlatform = <A, E>(
-          effect: Effect.Effect<A, E, FileSystem.FileSystem | Path.Path>,
-        ): Effect.Effect<A, E> =>
-          effect.pipe(
-            Effect.provideService(FileSystem.FileSystem, fs),
-            Effect.provideService(Path.Path, path),
-          );
-        const configureFunctions = (
-          nextConfig: ResolvedStackConfig,
-        ): Effect.Effect<void, StackBuildError> =>
-          Effect.gen(function* () {
-            yield* providePlatform(configureFunctionsRuntime(nextConfig, yield* runtimeHost));
-          }).pipe(
-            Effect.mapError(
-              (cause) =>
-                new StackBuildError({
-                  detail: "Failed to configure Edge Functions",
-                  cause,
-                }),
-            ),
-          );
-        const configWithFunctionOptions = (opts?: FunctionsConfig): ResolvedStackConfig => {
-          if (opts === undefined) {
-            return config;
-          }
-          const base = config.functions === false ? { noVerifyJwt: false } : config.functions;
-          return {
-            ...config,
-            functions: {
-              envFile: opts.envFile ?? base.envFile,
-              noVerifyJwt: opts.noVerifyJwt ?? base.noVerifyJwt,
-            },
-          };
-        };
-        const configWithEdgeRuntimeOptions = (
-          opts: EdgeRuntimeReloadConfig,
-        ): Effect.Effect<ResolvedStackConfig, ServiceNotFoundError> =>
-          Effect.gen(function* () {
-            if (config.edgeRuntime === false || opts.edgeRuntime.enabled === false) {
-              return yield* Effect.fail(new ServiceNotFoundError({ name: "edge-runtime" }));
-            }
-
-            const base = configWithFunctionOptions(opts.functions);
-            return {
-              ...base,
-              edgeRuntime: {
-                ...config.edgeRuntime,
-                enabled: opts.edgeRuntime.enabled ?? config.edgeRuntime.enabled,
-                inspectorPort: opts.edgeRuntime.inspectorPort ?? config.edgeRuntime.inspectorPort,
-                policy: opts.edgeRuntime.policy ?? config.edgeRuntime.policy,
-                env: opts.edgeRuntime.env ?? config.edgeRuntime.env,
-              },
-            };
-          });
-        const publicAllStateChanges = () =>
-          SubscriptionRef.changes(stateRef).pipe(
-            Stream.mapAccum<
-              ReadonlyArray<StackServiceState> | undefined,
-              ReadonlyArray<StackServiceState>,
-              StackServiceState
-            >(
-              () => undefined,
-              (previous, current) => [current, changedStatesBetween(previous, current)],
-            ),
-          );
-        const withLifecycleLock = lifecycleLock.withPermit;
-        const serviceStartOptions = {
-          beforeStart: (name: string) => portLease.reserve(portFieldsForService(name)),
-          beforeSpawn: (name: string) => portLease.release(portFieldsForService(name)),
-        };
-        const knownServiceError = (service: string, cause: ServiceNotFoundError) =>
-          new StackBuildError({
-            detail: `Prepared graph does not contain enabled service ${service}`,
-            cause,
-          });
-        const beginStartTargets = (
-          root: ServiceName,
-          allowExplicitlyStopped: ReadonlySet<ServiceName>,
-        ) =>
-          Effect.gen(function* () {
-            const runtime = yield* ensureRuntime;
-            const targets = activationTargetsForService(enabledServices, root);
-            const targetClosure = new Set(
-              targets.flatMap((target) =>
-                runtime.graph.startOrderFor(target).map((definition) => definition.name),
-              ),
-            );
-
-            for (const dependency of targetClosure) {
-              const state = yield* runtime.orchestrator
-                .getState(dependency)
-                .pipe(
-                  Effect.catchTag("ServiceNotFoundError", (cause) =>
-                    Effect.fail(knownServiceError(dependency, cause)),
-                  ),
-                );
-              const publicDependency = SERVICE_NAMES.find((candidate) => candidate === dependency);
-              if (
-                state.desired === "stopped" &&
-                publicDependency !== undefined &&
-                !allowExplicitlyStopped.has(publicDependency)
-              ) {
-                return yield* Effect.fail(
-                  new StackBuildError({
-                    detail: `Cannot activate ${root} because dependency ${dependency} was explicitly stopped`,
-                  }),
-                );
-              }
-            }
-
-            for (const target of targets) {
-              yield* runtime.orchestrator
-                .startService(target, serviceStartOptions)
-                .pipe(
-                  Effect.catchTag("ServiceNotFoundError", (cause) =>
-                    Effect.fail(knownServiceError(target, cause)),
-                  ),
-                );
-            }
-            return { runtime, targets };
-          });
-        const waitForTargets = ({
-          runtime,
-          targets,
-        }: {
-          readonly runtime: RuntimeState;
-          readonly targets: ReadonlyArray<ServiceName>;
-        }) =>
-          Effect.forEach(
-            targets,
-            (target) =>
-              runtime.orchestrator
-                .waitReady(target)
-                .pipe(
-                  Effect.catchTag("ServiceNotFoundError", (cause) =>
-                    Effect.fail(knownServiceError(target, cause)),
-                  ),
-                ),
-            { concurrency: "unbounded", discard: true },
-          );
-        const inspectStartedTargets = (root: ServiceName) =>
-          Effect.gen(function* () {
-            const runtime = yield* ensureRuntime;
-            const targets = activationTargetsForService(enabledServices, root);
-            const states = yield* Effect.forEach(targets, (target) =>
-              runtime.orchestrator
-                .getState(target)
-                .pipe(
-                  Effect.catchTag("ServiceNotFoundError", (cause) =>
-                    Effect.fail(knownServiceError(target, cause)),
-                  ),
-                ),
-            );
-            if (states.some((state) => state.desired !== "running")) {
-              return undefined;
-            }
-            return {
-              runtime,
-              targets,
-              ready: states.every(
-                (state) =>
-                  state.status === "Healthy" ||
-                  (state.status === "Stopped" && state.exitCode === 0),
-              ),
-            };
-          });
-        const requireRunningPhase = Effect.gen(function* () {
-          const phase = yield* Ref.get(phaseRef);
-          if (phase !== "running") {
-            return yield* Effect.fail(new StackNotRunningError({ phase }));
-          }
-        });
-        const disposeOnce = () =>
-          Effect.gen(function* () {
-            if (disposed) {
-              return;
-            }
-            disposed = true;
-            yield* Ref.set(phaseRef, "stopping");
-            yield* cleanupLocalStackResources({
-              stop: () =>
-                runtimeState === undefined ? Effect.void : runtimeState.orchestrator.stop(),
-              cleanupTargets: runtimeState?.cleanupTargets ?? { dockerContainerNames: [] },
-              config,
-            }).pipe(
-              Effect.ensuring(portLease.releaseAll),
-              Effect.ensuring(Ref.set(phaseRef, "stopped")),
-            );
-          }).pipe(withLifecycleLock);
-
-        yield* Effect.addFinalizer(disposeOnce);
-
-        return {
-          getInfo: () => Effect.succeed(info),
-          getCleanupTargets: () =>
-            Effect.succeed(runtimeState?.cleanupTargets ?? { dockerContainerNames: [] }),
-          start: () =>
-            Effect.gen(function* () {
-              yield* Ref.set(phaseRef, "starting");
-              const runtime = yield* ensureRuntime;
-              yield* configureFunctions(config);
-
-              if (config.startupMode === "lazy") {
-                const readiness: Array<Effect.Effect<void, ServiceReadyError | StackBuildError>> =
-                  [];
-                if (
-                  runtime.graph.startOrder.some((definition) => definition.name === "postgres-init")
-                ) {
-                  yield* runtime.orchestrator
-                    .startService("postgres-init", serviceStartOptions)
-                    .pipe(
-                      Effect.catchTag("ServiceNotFoundError", (cause) =>
-                        Effect.fail(knownServiceError("postgres-init", cause)),
-                      ),
-                    );
-                  readiness.push(
-                    runtime.orchestrator
-                      .waitReady("postgres-init")
-                      .pipe(
-                        Effect.catchTag("ServiceNotFoundError", (cause) =>
-                          Effect.fail(knownServiceError("postgres-init", cause)),
-                        ),
-                      ),
-                  );
-                }
-                for (const service of eagerServices(enabledServices)) {
-                  const started = yield* beginStartTargets(
-                    service,
-                    new Set(lifecycleTargetsForService(enabledServices, service)),
-                  );
-                  readiness.push(waitForTargets(started));
-                }
-                yield* Effect.all(readiness, { concurrency: "unbounded", discard: true });
-              } else {
-                yield* runtime.orchestrator.start(serviceStartOptions);
-                yield* runtime.orchestrator.waitAllReady();
-              }
-              yield* Ref.set(phaseRef, "running");
-            }).pipe(
-              Effect.onError(() => Ref.set(phaseRef, "stopped")),
-              withLifecycleLock,
-            ),
-          stop: () =>
-            Effect.gen(function* () {
-              if (runtimeState === undefined) {
-                yield* Ref.set(phaseRef, "stopped");
-                return;
-              }
-              yield* Ref.set(phaseRef, "stopping");
-              yield* runtimeState.orchestrator.stop();
-              yield* Ref.set(phaseRef, "stopped");
-            }).pipe(withLifecycleLock),
-          dispose: disposeOnce,
-          startService: (name) =>
-            Effect.gen(function* () {
-              const started = yield* Effect.gen(function* () {
-                const service = yield* requireKnownServiceName(name);
-                return yield* beginStartTargets(
-                  service,
-                  new Set(lifecycleTargetsForService(enabledServices, service)),
-                );
-              }).pipe(withLifecycleLock);
-              yield* waitForTargets(started);
-            }),
-          activateService: (name) =>
-            Effect.gen(function* () {
-              yield* requireRunningPhase;
-              const service = yield* requireKnownServiceName(name);
-              const existing = yield* inspectStartedTargets(service);
-              if (existing?.ready === true) {
-                // Close the race with a concurrent stack stop before taking
-                // the lock-free healthy-request fast path.
-                yield* requireRunningPhase;
-                return;
-              }
-              if (existing !== undefined) {
-                yield* waitForTargets(existing);
-                return;
-              }
-              const started = yield* Effect.gen(function* () {
-                yield* requireRunningPhase;
-                const concurrentlyStarted = yield* inspectStartedTargets(service);
-                if (concurrentlyStarted !== undefined) return concurrentlyStarted;
-                return yield* beginStartTargets(service, new Set());
-              }).pipe(withLifecycleLock);
-              yield* waitForTargets(started);
-            }),
-          stopService: (name) =>
-            Effect.gen(function* () {
-              const service = yield* requireKnownServiceName(name);
-              const runtime = yield* ensureRuntime;
-              for (const target of lifecycleTargetsForService(
-                enabledServices,
-                service,
-              ).toReversed()) {
-                yield* runtime.orchestrator.stopService(target);
-              }
-            }).pipe(withLifecycleLock),
-          restartService: (name) =>
-            Effect.gen(function* () {
-              const started = yield* Effect.gen(function* () {
-                const service = yield* requireKnownServiceName(name);
-                const runtime = yield* ensureRuntime;
-                yield* runtime.orchestrator.restartService(service, serviceStartOptions);
-                return { runtime, targets: [service] };
-              }).pipe(withLifecycleLock);
-              yield* waitForTargets(started);
-            }),
-          reloadFunctions: (opts) =>
-            Effect.gen(function* () {
-              const started = yield* Effect.gen(function* () {
-                yield* requireKnownService("edge-runtime");
-                yield* configureFunctions(configWithFunctionOptions(opts));
-                const runtime = yield* ensureRuntime;
-                const state = yield* runtime.orchestrator.getState("edge-runtime");
-                if (state.desired !== "running") {
-                  return yield* beginStartTargets("edge-runtime", new Set(["edge-runtime"]));
-                }
-                yield* runtime.orchestrator.restartService("edge-runtime", serviceStartOptions);
-                return { runtime, targets: ["edge-runtime"] as const };
-              }).pipe(withLifecycleLock);
-              yield* waitForTargets(started);
-            }),
-          reloadEdgeRuntime: (opts) =>
-            Effect.gen(function* () {
-              const started = yield* Effect.gen(function* () {
-                yield* requireKnownService("edge-runtime");
-                const nextConfig = yield* configWithEdgeRuntimeOptions(opts);
-                const prepared = yield* ensurePrepared;
-                const runtime = yield* ensureRuntime;
-                const buildResult = yield* builder.build(nextConfig, prepared);
-                const edgeRuntimeDef = buildResult.graph.startOrder.find(
-                  (def) => def.name === "edge-runtime",
-                );
-
-                if (edgeRuntimeDef === undefined) {
-                  return yield* Effect.fail(new ServiceNotFoundError({ name: "edge-runtime" }));
-                }
-
-                yield* configureFunctions(nextConfig);
-                yield* runtime.orchestrator
-                  .updateServiceDefinition("edge-runtime", edgeRuntimeDef)
-                  .pipe(
-                    Effect.mapError(
-                      (cause) =>
-                        new StackBuildError({
-                          detail: "Failed to update edge-runtime service definition",
-                          cause,
-                        }),
-                    ),
-                  );
-                const state = yield* runtime.orchestrator.getState("edge-runtime");
-                if (state.desired !== "running") {
-                  return yield* beginStartTargets("edge-runtime", new Set(["edge-runtime"]));
-                }
-                yield* runtime.orchestrator.restartService("edge-runtime", serviceStartOptions);
-                return { runtime, targets: ["edge-runtime"] as const };
-              }).pipe(withLifecycleLock);
-              yield* waitForTargets(started);
-            }),
-          getState: (name) =>
-            Effect.gen(function* () {
-              const currentStates = SubscriptionRef.getUnsafe(stateRef);
-              const match = currentStates.find((state) => state.name === name);
-              if (match === undefined) {
-                return yield* Effect.fail(new ServiceNotFoundError({ name }));
-              }
-              return match;
-            }),
-          getAllStates: () => Effect.sync(() => SubscriptionRef.getUnsafe(stateRef)),
-          stateChanges: (name) =>
-            Effect.gen(function* () {
-              yield* requireKnownService(name);
-              return Stream.filter(publicAllStateChanges(), (state) => state.name === name);
-            }),
-          allStateChanges: publicAllStateChanges,
-          waitReady: (name) =>
-            Effect.gen(function* () {
-              const phase = yield* Ref.get(phaseRef);
-              if (phase !== "running") {
-                return yield* Effect.fail(
-                  new StackBuildError({
-                    detail: `Cannot wait for service ${name} while the stack is ${phase}`,
-                  }),
-                );
-              }
-              yield* requireKnownServiceName(name);
-              const runtime = yield* ensureRuntime;
-              yield* runtime.orchestrator.waitReady(name);
-            }),
-          waitAllReady: () =>
-            Effect.gen(function* () {
-              const phase = yield* Ref.get(phaseRef);
-              if (phase !== "running") {
-                return yield* Effect.fail(
-                  new StackBuildError({
-                    detail: `Cannot wait for stack readiness while the stack is ${phase}`,
-                  }),
-                );
-              }
-              const runtime = yield* ensureRuntime;
-              yield* runtime.orchestrator.waitAllReady();
-            }),
-          subscribeLogs: (name) => logBuffer.subscribe(name),
-          subscribeAllLogs: (services) =>
-            services === undefined || services.length === 0
-              ? logBuffer.subscribeAll()
-              : logBuffer
-                  .subscribeAll()
-                  .pipe(Stream.filter((entry) => services.includes(entry.service))),
-          logHistory: (name, limit) => logBuffer.history(name, limit),
-          logHistoryAll: (limit, services) => logBuffer.historyAll(limit, services),
-        };
-      }),
-    );
-}
diff --git a/packages/stack/src/createStack.ts b/packages/stack/src/createStack.ts
index 9f0559a4fc..3aaeb48a7d 100644
--- a/packages/stack/src/createStack.ts
+++ b/packages/stack/src/createStack.ts
@@ -1,5 +1,5 @@
 import type { LogEntry } from "@supabase/process-compose";
-import { Duration, Effect, type Layer, ManagedRuntime, Stream } from "effect";
+import { Effect, type Layer, ManagedRuntime, Stream } from "effect";
 import { FileSystem, Path } from "effect";
 import { HttpServer } from "effect/unstable/http";
 import { ChildProcessSpawner } from "effect/unstable/process";
@@ -13,7 +13,6 @@ import { allocatedPortFieldsForConfig } from "./ServicePorts.ts";
 import { Stack } from "./Stack.ts";
 import type { EdgeRuntimeReloadConfig } from "./Stack.ts";
 import type { ReadyOptions, ResolvedStackConfig, StackConfig } from "./StackConfig.ts";
-import { resolveReadinessPolicy } from "./StackConfig.ts";
 import { resolveConfig } from "./StackConfigResolver.ts";
 import type { StackServiceState } from "./StackServiceState.ts";
 import { InvalidStackStateError, StackAlreadyRunningError } from "./StateManager.ts";
@@ -168,28 +167,8 @@ export async function createStack(
         restartService: (name) => run(localStack.restartService(name)),
         reloadFunctions: (opts) => run(localStack.reloadFunctions(opts)),
         reloadEdgeRuntime: (opts) => run(localStack.reloadEdgeRuntime(opts)),
-        ready: (opts) => {
-          const policy = resolveReadinessPolicy({
-            readyOptions: opts,
-            stackPolicy: resolved.readiness,
-          });
-          const effect =
-            policy.mode === "finite"
-              ? localStack.waitAllReady().pipe(Effect.timeout(Duration.millis(policy.timeoutMs)))
-              : localStack.waitAllReady();
-          return run(effect);
-        },
-        serviceReady: (name, opts) => {
-          const policy = resolveReadinessPolicy({
-            readyOptions: opts,
-            stackPolicy: resolved.readiness,
-          });
-          const effect =
-            policy.mode === "finite"
-              ? localStack.waitReady(name).pipe(Effect.timeout(Duration.millis(policy.timeoutMs)))
-              : localStack.waitReady(name);
-          return run(effect);
-        },
+        ready: (opts) => run(localStack.waitAllReady(opts)),
+        serviceReady: (name, opts) => run(localStack.waitReady(name, opts)),
         getStatus: () => run(localStack.getAllStates()),
         getServiceStatus: (name) => run(localStack.getState(name)),
         statusChanges: () => Stream.toAsyncIterableWith(localStack.allStateChanges(), services),
diff --git a/packages/stack/src/effect.ts b/packages/stack/src/effect.ts
index 215e6b6892..e757aaeb58 100644
--- a/packages/stack/src/effect.ts
+++ b/packages/stack/src/effect.ts
@@ -13,6 +13,7 @@ export {
   PortConflictError,
   StackBuildError,
   StackError,
+  StackReadinessError,
   toStackError,
 } from "./errors.ts";
 
diff --git a/packages/stack/src/errors.ts b/packages/stack/src/errors.ts
index 1da68cdd63..937d3330db 100644
--- a/packages/stack/src/errors.ts
+++ b/packages/stack/src/errors.ts
@@ -31,6 +31,12 @@ export class StackNotRunningError extends Data.TaggedError("StackNotRunningError
   readonly phase: string;
 }> {}
 
+export class StackReadinessError extends Data.TaggedError("StackReadinessError")<{
+  readonly target: string;
+  readonly timeoutMs: number;
+  readonly detail: string;
+}> {}
+
 export class PortConflictError extends Data.TaggedError("PortConflictError")<{
   readonly port: number;
   readonly service: string;
@@ -71,6 +77,12 @@ export function toStackError(err: unknown): StackError {
           message: taggedMessage,
           cause: err,
         });
+      case "StackReadinessError":
+        return new StackError({
+          code: "STACK_READINESS_TIMEOUT",
+          message: taggedMessage,
+          cause: err,
+        });
       case "BinaryNotFoundError":
         return new StackError({
           code: "BINARY_NOT_FOUND",
diff --git a/packages/stack/src/layers.ts b/packages/stack/src/layers.ts
index 30fb1c3eb4..ade58438a9 100644
--- a/packages/stack/src/layers.ts
+++ b/packages/stack/src/layers.ts
@@ -11,9 +11,8 @@ import type { DaemonMessage, DaemonStartMessage } from "./daemon.ts";
 import { DaemonMessageSchema } from "./DaemonProtocol.ts";
 import type { PortLease } from "./PortAllocator.ts";
 import { RemoteStack } from "./RemoteStack.ts";
-import { StackServiceActivator } from "./ServiceActivation.ts";
 import { Stack } from "./Stack.ts";
-import { StackLifecycleCoordinator } from "./StackLifecycleCoordinator.ts";
+import { localStackLayer } from "./LocalStack.ts";
 import { StackMetadataPersistence } from "./StackMetadataPersistence.ts";
 import { StackPreparation } from "./StackPreparation.ts";
 import {
@@ -56,18 +55,11 @@ export const foregroundLayer = (
     Layer.provide(FetchHttpClient.layer),
   );
   const stackPreparationLayer = StackPreparation.layer.pipe(Layer.provide(binaryResolverLayer));
-  const coordinatorLayer = StackLifecycleCoordinator.layer(config, portLease).pipe(
+  const stackLayer = localStackLayer(config, portLease).pipe(
     Layer.provide(StackBuilder.layer),
     Layer.provide(stackPreparationLayer),
     Layer.provide(StackMetadataPersistence.noop),
   );
-  const stackLayer = Stack.layer(config);
-  const serviceActivatorLayer = Layer.effect(
-    StackServiceActivator,
-    Effect.map(StackLifecycleCoordinator, (coordinator) => ({
-      activate: coordinator.activateService,
-    })),
-  );
 
   const proxyConfig: ProxyConfig = {
     listenPort: config.apiPort,
@@ -88,14 +80,10 @@ export const foregroundLayer = (
   };
   const apiProxyLayer = ApiProxy.layer(proxyConfig).pipe(
     Layer.provide(FetchHttpClient.layer),
-    Layer.provide(serviceActivatorLayer),
+    Layer.provide(stackLayer),
   );
 
-  return Layer.mergeAll(stackLayer, apiProxyLayer).pipe(
-    Layer.provide(coordinatorLayer),
-    Layer.provide(platform),
-    Layer.orDie,
-  );
+  return Layer.mergeAll(stackLayer, apiProxyLayer).pipe(Layer.provide(platform), Layer.orDie);
 };
 
 // ---------------------------------------------------------------------------
@@ -140,16 +128,6 @@ export const foregroundDaemonLayer = (
     anonJwt: config.anonJwt,
     serviceRoleJwt: config.serviceRoleJwt,
   };
-  const serviceActivatorLayer = Layer.effect(
-    StackServiceActivator,
-    Effect.map(StackLifecycleCoordinator, (coordinator) => ({
-      activate: coordinator.activateService,
-    })),
-  );
-  const apiProxyLayer = ApiProxy.layer(proxyConfig).pipe(
-    Layer.provide(FetchHttpClient.layer),
-    Layer.provide(serviceActivatorLayer),
-  );
   const stateManagerLayer = StateManager.make(
     singleStackStateManagerPaths(config.stackRoot, config.runtimeRoot, config.name),
   );
@@ -157,15 +135,17 @@ export const foregroundDaemonLayer = (
   const metadataPersistenceLayer = StackMetadataPersistence.fromStateManager(config.name).pipe(
     Layer.provide(stateManagerLayer),
   );
-  const coordinatorLayer = StackLifecycleCoordinator.layer(config, portLease).pipe(
+  const stackLayer = localStackLayer(config, portLease).pipe(
     Layer.provide(StackBuilder.layer),
     Layer.provide(stackPreparationLayer),
     Layer.provide(metadataPersistenceLayer),
   );
-  const stackLayer = Stack.layer(config);
+  const apiProxyLayer = ApiProxy.layer(proxyConfig).pipe(
+    Layer.provide(FetchHttpClient.layer),
+    Layer.provide(stackLayer),
+  );
 
   return Layer.mergeAll(stackLayer, apiProxyLayer, stateManagerLayer).pipe(
-    Layer.provide(coordinatorLayer),
     Layer.provide(platform),
     Layer.orDie,
   );

From 6c577a4c807414e4bb94dda3c2e2b2e20516050b Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 15:56:50 +0200
Subject: [PATCH 06/44] refactor(stack): restore service factory locality

---
 packages/stack/docs/architecture.md           |  13 +-
 packages/stack/src/CleanupTargets.ts          |   4 +
 packages/stack/src/LocalStack.ts              |  11 +-
 packages/stack/src/Stack.unit.test.ts         |  62 ++++++
 packages/stack/src/StackBuilder.ts            |  87 +++-----
 packages/stack/src/StackBuilder.unit.test.ts  |   6 +
 packages/stack/src/cleanup.ts                 |  10 +-
 packages/stack/src/createStack.ts             |  23 +--
 packages/stack/src/createStack.unit.test.ts   |  28 +++
 packages/stack/src/services/analytics.ts      |  20 +-
 packages/stack/src/services/auth.ts           |  26 +--
 packages/stack/src/services/edge-runtime.ts   |   9 +-
 packages/stack/src/services/imgproxy.ts       |   9 +-
 packages/stack/src/services/mailpit.ts        |  11 +-
 packages/stack/src/services/pgmeta.ts         |   9 +-
 packages/stack/src/services/pooler.ts         |  19 +-
 packages/stack/src/services/postgres-init.ts  |   4 +-
 packages/stack/src/services/postgres.ts       |  68 +++----
 packages/stack/src/services/postgrest.ts      |  28 ++-
 packages/stack/src/services/realtime.ts       |   9 +-
 packages/stack/src/services/service-utils.ts  |  20 +-
 .../stack/src/services/services.unit.test.ts  | 185 ++++++++++++++----
 packages/stack/src/services/storage.ts        |   9 +-
 packages/stack/src/services/studio.ts         |   9 +-
 packages/stack/src/services/vector.ts         |  12 +-
 25 files changed, 438 insertions(+), 253 deletions(-)

diff --git a/packages/stack/docs/architecture.md b/packages/stack/docs/architecture.md
index 4ce734db24..af52c3d3d7 100644
--- a/packages/stack/docs/architecture.md
+++ b/packages/stack/docs/architecture.md
@@ -93,7 +93,9 @@ runtime.
 
 `StackBuilder.build(config, prepared)` is the explicit owner of cross-service topology. Individual
 factories under `src/services/` own executable arguments, environment, mounts, health checks, and
-per-process cleanup. The builder owns which definitions exist and how they depend on one another.
+per-process cleanup. Docker factories also own their host-network and port-mapping arguments. The
+builder owns which definitions exist and how they depend on one another, including the choice
+between `postgres-init (completed)` and `postgres (healthy)` for every database consumer.
 
 | Public service | Automatic runtime support               | Principal dependency or role                                                                                       |
 | -------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
@@ -213,8 +215,10 @@ binding. Supervised Docker services have a wider window because the supervisor s
 
 Every Docker definition has ordinary in-process cleanup and supervisor-owned orphan cleanup.
 `StackBuilder` also returns exact Docker container names for the definitions it constructed. The
-coordinator persists these targets for managed daemons and uses them as a force-removal safety net
-after graceful stop. Auto-created PostgreSQL, Storage, and runtime paths are also removed.
+local Implementation captures these targets before persistence or orchestrator setup, persists
+them for managed daemons, and uses them as a force-removal safety net after graceful stop. Launch,
+exact cleanup, and candidate cleanup all derive container identity through the same naming
+function. Auto-created PostgreSQL, Storage, and runtime paths are also removed.
 
 Cleanup is intentionally defensive:
 
@@ -223,7 +227,8 @@ Cleanup is intentionally defensive:
    external resources;
 3. stack disposal force-removes exact known Docker containers;
 4. managed `stop` can use persisted cleanup metadata after daemon death;
-5. startup failure has candidate cleanup derived from the requested configuration.
+5. a failure before the exact build plan exists has candidate cleanup derived from enabled catalog
+   services; a partial startup failure disposes the exact build-produced plan.
 
 These paths overlap by design and must remain idempotent.
 
diff --git a/packages/stack/src/CleanupTargets.ts b/packages/stack/src/CleanupTargets.ts
index 47cb77a788..6de3b51cd9 100644
--- a/packages/stack/src/CleanupTargets.ts
+++ b/packages/stack/src/CleanupTargets.ts
@@ -1,4 +1,5 @@
 import { Schema } from "effect";
+import type { ServiceName } from "./ServiceName.ts";
 
 export interface CleanupTargets {
   readonly dockerContainerNames: ReadonlyArray<string>;
@@ -7,3 +8,6 @@ export interface CleanupTargets {
 export const CleanupTargetsSchema = Schema.Struct({
   dockerContainerNames: Schema.Array(Schema.String),
 });
+
+export const dockerContainerName = (service: ServiceName, apiPort: number): string =>
+  `supabase-${service}-${apiPort}`;
diff --git a/packages/stack/src/LocalStack.ts b/packages/stack/src/LocalStack.ts
index 23602329cf..39d33b0ad7 100644
--- a/packages/stack/src/LocalStack.ts
+++ b/packages/stack/src/LocalStack.ts
@@ -61,7 +61,6 @@ type StackService = typeof Stack.Service;
 interface RuntimeState {
   readonly orchestrator: Orchestrator["Service"];
   readonly graph: ResolvedGraph;
-  readonly cleanupTargets: CleanupTargets;
 }
 
 const initialPublicStates = (config: ResolvedStackConfig): ReadonlyArray<StackServiceState> =>
@@ -210,6 +209,7 @@ export const localStackLayer = (
       let prepareDeferred: Deferred.Deferred<PreparedStackArtifacts, StackBuildError> | undefined;
       let runtimeState: RuntimeState | undefined;
       let runtimeDeferred: Deferred.Deferred<RuntimeState, StackBuildError> | undefined;
+      let exactCleanupTargets: CleanupTargets | undefined;
 
       const ensurePrepared = Effect.suspend(() => {
         if (preparedArtifacts !== undefined) {
@@ -324,6 +324,7 @@ export const localStackLayer = (
             config,
             prepared,
           );
+          exactCleanupTargets = cleanupTargets;
 
           yield* metadataPersistence.persistCleanupTargets(cleanupTargets).pipe(
             Effect.mapError(
@@ -383,7 +384,6 @@ export const localStackLayer = (
           return {
             orchestrator,
             graph,
-            cleanupTargets,
           } satisfies RuntimeState;
         }).pipe(
           Effect.tap((value) =>
@@ -605,7 +605,7 @@ export const localStackLayer = (
           yield* cleanupLocalStackResources({
             stop: () =>
               runtimeState === undefined ? Effect.void : runtimeState.orchestrator.stop(),
-            cleanupTargets: runtimeState?.cleanupTargets ?? { dockerContainerNames: [] },
+            cleanupTargets: exactCleanupTargets ?? { dockerContainerNames: [] },
             config,
           }).pipe(
             Effect.ensuring(portLease.releaseAll),
@@ -647,6 +647,9 @@ export const localStackLayer = (
             disposeOnce().pipe(Effect.andThen(Effect.fail(error))),
           ),
         );
+      const cleanupOnStartupFailure = <A, E, R>(
+        effect: Effect.Effect<A, E, R>,
+      ): Effect.Effect<A, E, R> => effect.pipe(Effect.onError(() => disposeOnce()));
 
       yield* Effect.addFinalizer(disposeOnce);
 
@@ -722,7 +725,7 @@ export const localStackLayer = (
             Effect.onError(() => Ref.set(phaseRef, "stopped")),
             withLifecycleLock,
             (effect) => withReadinessPolicy(effect, "stack"),
-            cleanupOnReadinessFailure,
+            cleanupOnStartupFailure,
           ),
         stop: () =>
           Effect.gen(function* () {
diff --git a/packages/stack/src/Stack.unit.test.ts b/packages/stack/src/Stack.unit.test.ts
index f3286e0a53..c77a5fc9cf 100644
--- a/packages/stack/src/Stack.unit.test.ts
+++ b/packages/stack/src/Stack.unit.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "@effect/vitest";
 import { BunServices } from "@effect/platform-bun";
+import { buildGraph } from "@supabase/process-compose";
 import { createHmac } from "node:crypto";
 import { Deferred, Effect, Exit, Fiber, Layer, Stream } from "effect";
 import { mockChildProcessSpawner } from "../../process-compose/tests/helpers/mocks.ts";
@@ -407,6 +408,67 @@ describe("Stack", () => {
     }).pipe(Effect.provide(providedLayer));
   });
 
+  it.live("a partial startup failure disposes resources from services already started", () => {
+    let cleaned = false;
+    const spawner = mockChildProcessSpawner({
+      beforeSpawn: (record) =>
+        record.command === "fail" ? Effect.die("simulated spawn failure") : Effect.void,
+    });
+    const graph = Effect.runSync(
+      buildGraph([
+        {
+          name: "postgres",
+          command: process.execPath,
+          restart: "no",
+          cleanup: Effect.sync(() => {
+            cleaned = true;
+          }),
+        },
+        {
+          name: "postgrest",
+          command: "fail",
+          dependencies: [{ service: "postgres", condition: "healthy" }],
+          restart: "no",
+        },
+      ]),
+    );
+    const builderLayer = Layer.succeed(StackBuilder, {
+      build: () =>
+        Effect.succeed({
+          graph,
+          cleanupTargets: { dockerContainerNames: [] },
+          serviceProjection: new Map([
+            ["postgres", { visibility: "public" }],
+            ["postgrest", { visibility: "public" }],
+          ]),
+        }),
+    });
+    const resolver = mockBinaryResolver();
+    const stackPreparationLayer = StackPreparation.layer.pipe(Layer.provide(resolver.layer));
+    const layer = localStackLayer(
+      {
+        ...defaultConfig,
+        readiness: { mode: "finite", timeoutMs: 100 },
+      },
+      noopPortLease(defaultConfig.ports),
+    ).pipe(
+      Layer.provide(builderLayer),
+      Layer.provide(stackPreparationLayer),
+      Layer.provide(StackMetadataPersistence.noop),
+      Layer.provide(spawner.layer),
+      Layer.provide(BunServices.layer),
+    );
+
+    return Effect.gen(function* () {
+      const stack = yield* Stack;
+      const exit = yield* stack.start().pipe(Effect.exit);
+
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(cleaned).toBe(true);
+      expect(spawner.killed).toContain("SIGTERM");
+    }).pipe(Effect.provide(layer), Effect.timeout("2 seconds"));
+  });
+
   it.live("lazy startup starts direct services without starting HTTP backends", () => {
     const { layer, spawner } = setupLayer({ ...defaultConfig, startupMode: "lazy" });
 
diff --git a/packages/stack/src/StackBuilder.ts b/packages/stack/src/StackBuilder.ts
index 318ad63989..16ac7a272a 100644
--- a/packages/stack/src/StackBuilder.ts
+++ b/packages/stack/src/StackBuilder.ts
@@ -1,16 +1,11 @@
 import { buildGraph } from "@supabase/process-compose";
 import type { ResolvedGraph, ServiceDef } from "@supabase/process-compose";
 import { Effect, Layer, Context } from "effect";
-import type { CleanupTargets } from "./CleanupTargets.ts";
+import { dockerContainerName, type CleanupTargets } from "./CleanupTargets.ts";
 import { StackBuildError } from "./errors.ts";
 import { generateJwks } from "./JwtGenerator.ts";
-import {
-  detectPlatform,
-  dockerHostAddress,
-  dockerNetworkArgs,
-  dockerPortMapArgs,
-} from "./Platform.ts";
-import { analyticsDockerRuntimeNetwork, makeAnalyticsServiceDocker } from "./services/analytics.ts";
+import { detectPlatform, dockerHostAddress } from "./Platform.ts";
+import { makeAnalyticsServiceDocker } from "./services/analytics.ts";
 import { makeAuthServiceDocker, makeAuthServiceNative } from "./services/auth.ts";
 import {
   makeEdgeRuntimeServiceDocker,
@@ -19,7 +14,7 @@ import {
 import { makeImgproxyServiceDocker } from "./services/imgproxy.ts";
 import { makeMailpitServiceDocker } from "./services/mailpit.ts";
 import { makePgmetaServiceDocker } from "./services/pgmeta.ts";
-import { makePoolerServiceDocker, poolerContainerPorts } from "./services/pooler.ts";
+import { makePoolerServiceDocker } from "./services/pooler.ts";
 import { makePostgresInitService } from "./services/postgres-init.ts";
 import { makePostgresService, makePostgresServiceDocker } from "./services/postgres.ts";
 import { makePostgrestService, makePostgrestServiceDocker } from "./services/postgrest.ts";
@@ -78,8 +73,6 @@ const publicServiceProjection = (
   return serviceProjection;
 };
 
-const dockerContainerName = (service: string, apiPort: number) => `supabase-${service}-${apiPort}`;
-
 const hasAutoManagedPath = (config: ResolvedStackConfig, path: string) =>
   config.autoManagedPaths.some(
     (managedPath) =>
@@ -248,16 +241,18 @@ export class StackBuilder extends Context.Service<
                   port: config.dbPort,
                   dockerAccessible: needsDockerAccess,
                   cleanupDataDirOnExit: hasAutoManagedPath(config, config.postgres.dataDir),
+                  dependencies: [],
                 })
               : makePostgresServiceDocker({
                   image: postgresResolution.image,
                   dataDir: config.postgres.dataDir,
                   port: config.dbPort,
-                  networkArgs: dockerNetworkArgs(platform.os, [config.dbPort]),
+                  platformOs: platform.os,
                   jwtSecret: config.jwtSecret,
                   jwtExpiry: config.auth !== false ? config.auth.jwtExpiry : 3600,
                   apiPort: config.apiPort,
                   cleanupDataDirOnExit: hasAutoManagedPath(config, config.postgres.dataDir),
+                  dependencies: [],
                 })),
             enabled: true,
           },
@@ -269,6 +264,7 @@ export class StackBuilder extends Context.Service<
               postgresDir: postgresResolution.path,
               dbPort: config.dbPort,
               autoExposeNewTables: config.postgres.autoExposeNewTables,
+              dependencies: [{ service: "postgres", condition: "healthy" }],
             }),
             enabled: true,
           });
@@ -285,6 +281,7 @@ export class StackBuilder extends Context.Service<
                   extraSearchPath: config.postgrest.extraSearchPath,
                   maxRows: config.postgrest.maxRows,
                   jwtSecret: config.jwtSecret,
+                  dependencies: postgresDeps,
                 })
               : makePostgrestServiceDocker({
                   image: postgrestResolution.image,
@@ -296,17 +293,10 @@ export class StackBuilder extends Context.Service<
                   extraSearchPath: config.postgrest.extraSearchPath,
                   maxRows: config.postgrest.maxRows,
                   jwtSecret: config.jwtSecret,
-                  networkArgs: dockerNetworkArgs(platform.os, [
-                    config.postgrest.port,
-                    config.postgrest.adminPort,
-                  ]),
+                  platformOs: platform.os,
                   apiPort: config.apiPort,
+                  dependencies: postgresDeps,
                 })),
-            ...(hasPostgresInit
-              ? {}
-              : {
-                  dependencies: [{ service: "postgres", condition: "healthy" as const }],
-                }),
             enabled: true,
           });
         }
@@ -341,7 +331,7 @@ export class StackBuilder extends Context.Service<
                   smtpPort: config.mailpit !== false ? config.mailpit.smtpPort : undefined,
                   smtpAdminEmail: config.mailpit !== false ? config.mailpit.adminEmail : undefined,
                   smtpSenderName: config.mailpit !== false ? config.mailpit.senderName : undefined,
-                  networkArgs: dockerNetworkArgs(platform.os, [config.auth.port]),
+                  platformOs: platform.os,
                   apiPort: config.apiPort,
                   dependencies: postgresDeps,
                 })),
@@ -370,7 +360,7 @@ export class StackBuilder extends Context.Service<
                   inspectorPort: config.edgeRuntime.inspectorPort,
                   policy: config.edgeRuntime.policy,
                   env: config.edgeRuntime.env,
-                  networkArgs: dockerNetworkArgs(platform.os, [config.edgeRuntime.port]),
+                  platformOs: platform.os,
                   dependencies: postgresDeps,
                 })),
             enabled: true,
@@ -386,11 +376,8 @@ export class StackBuilder extends Context.Service<
               webPort: config.mailpit.port,
               smtpPort: config.mailpit.smtpPort,
               pop3Port: config.mailpit.pop3Port,
-              networkArgs: dockerNetworkArgs(platform.os, [
-                config.mailpit.port,
-                config.mailpit.smtpPort,
-                config.mailpit.pop3Port,
-              ]),
+              platformOs: platform.os,
+              dependencies: [],
             }),
             enabled: true,
           });
@@ -411,7 +398,7 @@ export class StackBuilder extends Context.Service<
               encryptionKey: config.realtime.encryptionKey,
               secretKeyBase: config.realtime.secretKeyBase,
               maxHeaderLength: config.realtime.maxHeaderLength,
-              networkArgs: dockerNetworkArgs(platform.os, [config.realtime.port]),
+              platformOs: platform.os,
               dependencies: postgresDeps,
             }),
             enabled: true,
@@ -437,7 +424,7 @@ export class StackBuilder extends Context.Service<
               imgproxyUrl:
                 config.imgproxy !== false ? `http://${serviceHost}:${config.imgproxy.port}` : "",
               s3ProtocolEnabled: config.storage.s3ProtocolEnabled,
-              networkArgs: dockerNetworkArgs(platform.os, [config.storage.port]),
+              platformOs: platform.os,
               dependencies: postgresDeps,
               cleanupDataDirOnExit: hasAutoManagedPath(config, config.storage.dataDir),
             }),
@@ -454,7 +441,7 @@ export class StackBuilder extends Context.Service<
               port: config.imgproxy.port,
               apiPort: config.apiPort,
               dataDir: storageConfig === false ? "" : storageConfig.dataDir,
-              networkArgs: dockerNetworkArgs(platform.os, [config.imgproxy.port]),
+              platformOs: platform.os,
               dependencies: [{ service: "storage", condition: "healthy" }],
             }),
             enabled: true,
@@ -470,7 +457,7 @@ export class StackBuilder extends Context.Service<
               port: config.pgmeta.port,
               dbHost: serviceHost,
               dbPort: config.dbPort,
-              networkArgs: dockerNetworkArgs(platform.os, [config.pgmeta.port]),
+              platformOs: platform.os,
               dependencies: postgresDeps,
             }),
             enabled: true,
@@ -479,25 +466,16 @@ export class StackBuilder extends Context.Service<
 
         if (config.analytics !== false) {
           const analyticsImage = yield* requirePreparedDockerImage(prepared, "analytics");
-          const analyticsRuntimeNetwork = analyticsDockerRuntimeNetwork(
-            platform.os,
-            config.analytics.port,
-            serviceHost,
-          );
           defs.push({
             ...makeAnalyticsServiceDocker({
               image: analyticsImage,
               apiPort: config.apiPort,
               hostPort: config.analytics.port,
-              listenPort: analyticsRuntimeNetwork.listenPort,
-              nodeHost: analyticsRuntimeNetwork.nodeHost,
+              platformOs: platform.os,
               dbHost: serviceHost,
               dbPort: config.dbPort,
               apiKey: config.analytics.apiKey,
               backend: config.analytics.backend,
-              networkArgs: dockerPortMapArgs(platform.os, [
-                { host: config.analytics.port, container: 4000 },
-              ]),
               dependencies: postgresDeps,
             }),
             enabled: true,
@@ -514,7 +492,7 @@ export class StackBuilder extends Context.Service<
               serviceHost,
               analyticsPort: analyticsConfig === false ? 0 : analyticsConfig.port,
               analyticsApiKey: analyticsConfig === false ? "api-key" : analyticsConfig.apiKey,
-              networkArgs: dockerNetworkArgs(platform.os, []),
+              platformOs: platform.os,
               dependencies: [{ service: "analytics", condition: "healthy" }],
             }),
             enabled: true,
@@ -528,6 +506,8 @@ export class StackBuilder extends Context.Service<
               image: poolerImage,
               apiPort: config.apiPort,
               hostAdminPort: config.pooler.apiPort,
+              hostPort: config.pooler.port,
+              platformOs: platform.os,
               dbHost: serviceHost,
               dbPort: config.dbPort,
               poolMode: config.pooler.mode,
@@ -537,19 +517,6 @@ export class StackBuilder extends Context.Service<
               tenantId: config.pooler.tenantId,
               encryptionKey: config.pooler.encryptionKey,
               secretKeyBase: config.pooler.secretKeyBase,
-              networkArgs: dockerPortMapArgs(platform.os, [
-                {
-                  host: config.pooler.apiPort,
-                  container: poolerContainerPorts.admin,
-                },
-                {
-                  host: config.pooler.port,
-                  container:
-                    config.pooler.mode === "session"
-                      ? poolerContainerPorts.session
-                      : poolerContainerPorts.transaction,
-                },
-              ]),
               dependencies: postgresDeps,
             }),
             enabled: true,
@@ -577,7 +544,7 @@ export class StackBuilder extends Context.Service<
               analyticsUrl:
                 config.analytics !== false ? `http://${serviceHost}:${config.analytics.port}` : "",
               analyticsApiKey: config.analytics !== false ? config.analytics.apiKey : "api-key",
-              networkArgs: dockerNetworkArgs(platform.os, [config.studio.port]),
+              platformOs: platform.os,
               dependencies:
                 config.analytics === false
                   ? [{ service: "pgmeta", condition: "healthy" }]
@@ -590,9 +557,9 @@ export class StackBuilder extends Context.Service<
           });
         }
 
-        const dockerContainerNames = defs
-          .filter((def) => def.command === "docker")
-          .map((def) => dockerContainerName(def.name, config.apiPort));
+        const dockerContainerNames = SERVICE_NAMES.filter((service) =>
+          defs.some((def) => def.name === service && def.command === "docker"),
+        ).map((service) => dockerContainerName(service, config.apiPort));
 
         const graph = yield* buildGraph(defs).pipe(
           Effect.mapError(
diff --git a/packages/stack/src/StackBuilder.unit.test.ts b/packages/stack/src/StackBuilder.unit.test.ts
index 2fb442725c..a11a0ce5c2 100644
--- a/packages/stack/src/StackBuilder.unit.test.ts
+++ b/packages/stack/src/StackBuilder.unit.test.ts
@@ -3,6 +3,7 @@ import { Deferred, Effect, Layer, Sink, Stream } from "effect";
 import { ChildProcessSpawner } from "effect/unstable/process";
 import { mockBinaryResolver } from "../tests/helpers/mocks.ts";
 import { defaultPublishableKey, defaultSecretKey, generateJwt } from "./JwtGenerator.ts";
+import { candidateCleanupTargets } from "./cleanup.ts";
 import { StackBuilder } from "./StackBuilder.ts";
 import type { BuildResult } from "./StackBuilder.ts";
 import { DEFAULT_STACK_READINESS_POLICY, type ResolvedStackConfig } from "./StackConfig.ts";
@@ -193,6 +194,11 @@ describe("StackBuilder", () => {
 
       expect(graph.startOrder.length).toBe(4);
       expect(cleanupTargets.dockerContainerNames).toEqual([]);
+      expect(candidateCleanupTargets(baseConfig).dockerContainerNames).toEqual([
+        `supabase-postgres-${baseConfig.apiPort}`,
+        `supabase-postgrest-${baseConfig.apiPort}`,
+        `supabase-auth-${baseConfig.apiPort}`,
+      ]);
 
       const names = graph.startOrder.map((s) => s.name);
       expect(names).toContain("postgres");
diff --git a/packages/stack/src/cleanup.ts b/packages/stack/src/cleanup.ts
index 7e43ecb6c6..419c405384 100644
--- a/packages/stack/src/cleanup.ts
+++ b/packages/stack/src/cleanup.ts
@@ -1,9 +1,17 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, rmSync } from "node:fs";
 import { Duration, Effect } from "effect";
-import type { CleanupTargets } from "./CleanupTargets.ts";
+import { dockerContainerName, type CleanupTargets } from "./CleanupTargets.ts";
+import { SERVICE_NAMES, serviceMetadata } from "./ServiceCatalog.ts";
 import type { ResolvedStackConfig } from "./StackConfig.ts";
 
+export const candidateCleanupTargets = (config: ResolvedStackConfig): CleanupTargets => ({
+  dockerContainerNames: SERVICE_NAMES.filter((service) => {
+    const serviceConfig = config[serviceMetadata(service).configKey];
+    return service === "postgres" || serviceConfig !== false;
+  }).map((service) => dockerContainerName(service, config.apiPort)),
+});
+
 /**
  * Force-remove Docker containers by name. Best-effort safety net —
  * silently ignores containers that don't exist or are already removed.
diff --git a/packages/stack/src/createStack.ts b/packages/stack/src/createStack.ts
index 3aaeb48a7d..f75f6bf66d 100644
--- a/packages/stack/src/createStack.ts
+++ b/packages/stack/src/createStack.ts
@@ -3,8 +3,7 @@ import { Effect, type Layer, ManagedRuntime, Stream } from "effect";
 import { FileSystem, Path } from "effect";
 import { HttpServer } from "effect/unstable/http";
 import { ChildProcessSpawner } from "effect/unstable/process";
-import { cleanupAutoManagedPaths, dockerForceRemove } from "./cleanup.ts";
-import type { CleanupTargets } from "./CleanupTargets.ts";
+import { candidateCleanupTargets, cleanupAutoManagedPaths, dockerForceRemove } from "./cleanup.ts";
 import { toStackError } from "./errors.ts";
 import type { FunctionsConfig } from "./functions.ts";
 import { daemonLayer, foregroundLayer, type DaemonStartError } from "./layers.ts";
@@ -81,24 +80,6 @@ export const projectDaemonLayer = (opts: {
     opts.daemonEntryPoint,
   );
 
-function possibleCleanupTargetsForConfig(config: ResolvedStackConfig): CleanupTargets {
-  const dockerContainerNames = [`supabase-postgres-${config.apiPort}`];
-  if (config.postgrest !== false) dockerContainerNames.push(`supabase-postgrest-${config.apiPort}`);
-  if (config.auth !== false) dockerContainerNames.push(`supabase-auth-${config.apiPort}`);
-  if (config.edgeRuntime !== false)
-    dockerContainerNames.push(`supabase-edge-runtime-${config.apiPort}`);
-  if (config.realtime !== false) dockerContainerNames.push(`supabase-realtime-${config.apiPort}`);
-  if (config.storage !== false) dockerContainerNames.push(`supabase-storage-${config.apiPort}`);
-  if (config.imgproxy !== false) dockerContainerNames.push(`supabase-imgproxy-${config.apiPort}`);
-  if (config.mailpit !== false) dockerContainerNames.push(`supabase-mailpit-${config.apiPort}`);
-  if (config.pgmeta !== false) dockerContainerNames.push(`supabase-pgmeta-${config.apiPort}`);
-  if (config.studio !== false) dockerContainerNames.push(`supabase-studio-${config.apiPort}`);
-  if (config.analytics !== false) dockerContainerNames.push(`supabase-analytics-${config.apiPort}`);
-  if (config.vector !== false) dockerContainerNames.push(`supabase-vector-${config.apiPort}`);
-  if (config.pooler !== false) dockerContainerNames.push(`supabase-pooler-${config.apiPort}`);
-  return { dockerContainerNames };
-}
-
 export async function createStack(
   config: StackConfig | undefined,
   platformFactory: PlatformFactory,
@@ -185,7 +166,7 @@ export async function createStack(
     }
   } catch (error: unknown) {
     await Effect.runPromise(portLease.releaseAll);
-    dockerForceRemove(possibleCleanupTargetsForConfig(resolved).dockerContainerNames);
+    dockerForceRemove(candidateCleanupTargets(resolved).dockerContainerNames);
     cleanupAutoManagedPaths(resolved);
     throw toStackError(error);
   }
diff --git a/packages/stack/src/createStack.unit.test.ts b/packages/stack/src/createStack.unit.test.ts
index 747b16686b..609b336093 100644
--- a/packages/stack/src/createStack.unit.test.ts
+++ b/packages/stack/src/createStack.unit.test.ts
@@ -3,6 +3,8 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { StackHandle } from "./createStack.ts";
+import { candidateCleanupTargets } from "./cleanup.ts";
+import { dockerContainerName } from "./CleanupTargets.ts";
 import type { AllocatedPorts } from "./PortAllocator.ts";
 import { DEFAULT_MANAGED_STACK_NAME, projectKeyForProjectDir } from "./paths.ts";
 import { stackMetadata } from "./StackMetadata.ts";
@@ -246,6 +248,32 @@ describe("resolveConfig edge runtime defaults", () => {
   });
 });
 
+describe("candidateCleanupTargets", () => {
+  it("derives fallback Docker identities from enabled catalog services", async () => {
+    const config = await resolveConfig({
+      mode: "docker",
+      auth: false,
+      edgeRuntime: false,
+      realtime: false,
+      storage: false,
+      imgproxy: false,
+      mailpit: false,
+      pgmeta: false,
+      studio: false,
+      analytics: false,
+      vector: false,
+      pooler: false,
+    });
+
+    expect(candidateCleanupTargets(config)).toEqual({
+      dockerContainerNames: [
+        dockerContainerName("postgres", config.apiPort),
+        dockerContainerName("postgrest", config.apiPort),
+      ],
+    });
+  });
+});
+
 describe("resolveConfig startup mode", () => {
   it("keeps eager startup as the package default", async () => {
     const config = await resolveConfig();
diff --git a/packages/stack/src/services/analytics.ts b/packages/stack/src/services/analytics.ts
index 9f2f742438..10d26d28d0 100644
--- a/packages/stack/src/services/analytics.ts
+++ b/packages/stack/src/services/analytics.ts
@@ -1,4 +1,5 @@
 import type { ServiceDef } from "@supabase/process-compose";
+import { dockerPortMapArgs } from "../Platform.ts";
 import { dockerRunService, type ServiceDependency } from "./service-utils.ts";
 import { stackHealthBudgets } from "./health-budgets.ts";
 
@@ -6,13 +7,11 @@ interface DockerAnalyticsOptions {
   readonly image: string;
   readonly apiPort: number;
   readonly hostPort: number;
-  readonly listenPort: number;
-  readonly nodeHost: string;
+  readonly platformOs: string;
   readonly dbHost: string;
   readonly dbPort: number;
   readonly apiKey: string;
   readonly backend: "postgres" | "bigquery";
-  readonly networkArgs: ReadonlyArray<string>;
   readonly dependencies: ReadonlyArray<ServiceDependency>;
 }
 
@@ -39,9 +38,10 @@ const analyticsHealthCheck = (port: number): ServiceDef["healthCheck"] => ({
 });
 
 export const makeAnalyticsServiceDocker = (opts: DockerAnalyticsOptions): ServiceDef => {
+  const runtimeNetwork = analyticsDockerRuntimeNetwork(opts.platformOs, opts.hostPort, opts.dbHost);
   const env: Record<string, string> = {
-    PORT: String(opts.listenPort),
-    PHX_HTTP_PORT: String(opts.listenPort),
+    PORT: String(runtimeNetwork.listenPort),
+    PHX_HTTP_PORT: String(runtimeNetwork.listenPort),
     DB_DATABASE: "_supabase",
     DB_HOSTNAME: opts.dbHost,
     DB_PORT: String(opts.dbPort),
@@ -53,7 +53,7 @@ export const makeAnalyticsServiceDocker = (opts: DockerAnalyticsOptions): Servic
     LOGFLARE_SUPABASE_MODE: "true",
     LOGFLARE_PRIVATE_ACCESS_TOKEN: opts.apiKey,
     LOGFLARE_LOG_LEVEL: "warn",
-    LOGFLARE_NODE_HOST: opts.nodeHost,
+    LOGFLARE_NODE_HOST: runtimeNetwork.nodeHost,
     LOGFLARE_FEATURE_FLAG_OVERRIDE: "'multibackend=true'",
     RELEASE_COOKIE: "cookie",
   };
@@ -69,9 +69,11 @@ export const makeAnalyticsServiceDocker = (opts: DockerAnalyticsOptions): Servic
 
   return dockerRunService({
     name: "analytics",
-    containerName: `supabase-analytics-${opts.apiPort}`,
+    apiPort: opts.apiPort,
     image: opts.image,
-    networkArgs: opts.networkArgs,
+    networkArgs: dockerPortMapArgs(opts.platformOs, [
+      { host: opts.hostPort, container: ANALYTICS_CONTAINER_PORT },
+    ]),
     entrypoint: "sh",
     cmd: [
       "-c",
@@ -82,7 +84,7 @@ EOF
 `,
     ],
     env,
-    dependsOn: opts.dependencies,
+    dependencies: opts.dependencies,
     healthCheck: analyticsHealthCheck(opts.hostPort),
   });
 };
diff --git a/packages/stack/src/services/auth.ts b/packages/stack/src/services/auth.ts
index 355b8265c6..6e604695b6 100644
--- a/packages/stack/src/services/auth.ts
+++ b/packages/stack/src/services/auth.ts
@@ -1,6 +1,7 @@
 import type { ServiceDef } from "@supabase/process-compose";
-import { dockerServiceCleanup, dockerServiceOrphanCleanup } from "./docker-cleanup.ts";
+import { dockerNetworkArgs } from "../Platform.ts";
 import { stackHealthBudgets } from "./health-budgets.ts";
+import { dockerRunService, type ServiceDependency } from "./service-utils.ts";
 
 interface AuthServiceOptions {
   readonly dbPort: number;
@@ -13,10 +14,7 @@ interface AuthServiceOptions {
   readonly smtpPort?: number;
   readonly smtpAdminEmail?: string;
   readonly smtpSenderName?: string;
-  readonly dependencies: ReadonlyArray<{
-    readonly service: string;
-    readonly condition: "healthy" | "completed";
-  }>;
+  readonly dependencies: ReadonlyArray<ServiceDependency>;
 }
 
 interface NativeAuthOptions extends AuthServiceOptions {
@@ -26,7 +24,7 @@ interface NativeAuthOptions extends AuthServiceOptions {
 interface DockerAuthOptions extends AuthServiceOptions {
   readonly image: string;
   readonly dbHost: string;
-  readonly networkArgs: readonly string[];
+  readonly platformOs: string;
   readonly apiPort: number;
 }
 
@@ -82,17 +80,13 @@ export const makeAuthServiceNative = (opts: NativeAuthOptions): ServiceDef => ({
 
 export const makeAuthServiceDocker = (opts: DockerAuthOptions): ServiceDef => {
   const env = authEnv(opts, opts.dbHost);
-  const envArgs = Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
-  const containerName = `supabase-auth-${opts.apiPort}`;
-
-  return {
+  return dockerRunService({
     name: "auth",
-    command: "docker",
-    args: ["run", "--rm", "--name", containerName, ...opts.networkArgs, ...envArgs, opts.image],
+    apiPort: opts.apiPort,
+    image: opts.image,
+    networkArgs: dockerNetworkArgs(opts.platformOs, [opts.authPort]),
+    env,
     dependencies: opts.dependencies,
     healthCheck: authHealthCheck(opts.authPort),
-    cleanup: dockerServiceCleanup(containerName),
-    supervision: { orphanCleanup: dockerServiceOrphanCleanup(containerName) },
-    restart: "unless-stopped",
-  };
+  });
 };
diff --git a/packages/stack/src/services/edge-runtime.ts b/packages/stack/src/services/edge-runtime.ts
index 66f6d52b9d..bd3a35c66d 100644
--- a/packages/stack/src/services/edge-runtime.ts
+++ b/packages/stack/src/services/edge-runtime.ts
@@ -1,6 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { ServiceDef } from "@supabase/process-compose";
+import { dockerNetworkArgs } from "../Platform.ts";
 import { dockerRunService, hostHttpHealthCheck, type ServiceDependency } from "./service-utils.ts";
 import bootstrapSource from "./edge-runtime-main.ts" with { type: "text" };
 import { stackHealthBudgets } from "./health-budgets.ts";
@@ -22,7 +23,7 @@ interface NativeEdgeRuntimeOptions extends EdgeRuntimeOptions {
 interface DockerEdgeRuntimeOptions extends EdgeRuntimeOptions {
   readonly image: string;
   readonly apiPort: number;
-  readonly networkArgs: ReadonlyArray<string>;
+  readonly platformOs: string;
 }
 
 const bootstrapFileName = "index.ts";
@@ -85,9 +86,9 @@ export const makeEdgeRuntimeServiceDocker = (opts: DockerEdgeRuntimeOptions): Se
 
   return dockerRunService({
     name: "edge-runtime",
-    containerName: `supabase-edge-runtime-${opts.apiPort}`,
+    apiPort: opts.apiPort,
     image: opts.image,
-    networkArgs: opts.networkArgs,
+    networkArgs: dockerNetworkArgs(opts.platformOs, [opts.port]),
     volumes: [
       `${bootstrapDir}:${bootstrapMountDir}:ro`,
       ...(opts.projectDir === undefined ? [] : [`${opts.projectDir}:${opts.projectDir}:ro`]),
@@ -98,7 +99,7 @@ export const makeEdgeRuntimeServiceDocker = (opts: DockerEdgeRuntimeOptions): Se
       FUNCTIONS_RUNTIME_CONFIG_PATH: `${bootstrapMountDir}/functions-runtime-config.json`,
     },
     cmd: [...edgeRuntimeArgs(opts, bootstrapMountDir)],
-    dependsOn: opts.dependencies,
+    dependencies: opts.dependencies,
     healthCheck: edgeRuntimeHealthCheck(opts.port),
   });
 };
diff --git a/packages/stack/src/services/imgproxy.ts b/packages/stack/src/services/imgproxy.ts
index f38699f88e..a1526da08e 100644
--- a/packages/stack/src/services/imgproxy.ts
+++ b/packages/stack/src/services/imgproxy.ts
@@ -1,4 +1,5 @@
 import type { ServiceDef } from "@supabase/process-compose";
+import { dockerNetworkArgs } from "../Platform.ts";
 import { dockerRunService, hostHttpHealthCheck, type ServiceDependency } from "./service-utils.ts";
 import { stackHealthBudgets } from "./health-budgets.ts";
 
@@ -7,7 +8,7 @@ interface DockerImgproxyOptions {
   readonly port: number;
   readonly apiPort: number;
   readonly dataDir: string;
-  readonly networkArgs: ReadonlyArray<string>;
+  readonly platformOs: string;
   readonly dependencies: ReadonlyArray<ServiceDependency>;
 }
 
@@ -21,9 +22,9 @@ const imgproxyHealthCheck = (port: number): ServiceDef["healthCheck"] =>
 export const makeImgproxyServiceDocker = (opts: DockerImgproxyOptions): ServiceDef =>
   dockerRunService({
     name: "imgproxy",
-    containerName: `supabase-imgproxy-${opts.apiPort}`,
+    apiPort: opts.apiPort,
     image: opts.image,
-    networkArgs: opts.networkArgs,
+    networkArgs: dockerNetworkArgs(opts.platformOs, [opts.port]),
     volumes: [`${opts.dataDir}:${IMGPROXY_STORAGE_DIR}`],
     env: {
       IMGPROXY_BIND: `:${opts.port}`,
@@ -36,6 +37,6 @@ export const makeImgproxyServiceDocker = (opts: DockerImgproxyOptions): ServiceD
       IMGPROXY_PRESETS: "default=width:3000/height:8192",
       IMGPROXY_FORMAT_QUALITY: "jpeg=80,avif=62,webp=80",
     },
-    dependsOn: opts.dependencies,
+    dependencies: opts.dependencies,
     healthCheck: imgproxyHealthCheck(opts.port),
   });
diff --git a/packages/stack/src/services/mailpit.ts b/packages/stack/src/services/mailpit.ts
index e60f41a14e..edc8673e6a 100644
--- a/packages/stack/src/services/mailpit.ts
+++ b/packages/stack/src/services/mailpit.ts
@@ -1,5 +1,6 @@
 import type { ServiceDef } from "@supabase/process-compose";
-import { dockerRunService, hostHttpHealthCheck } from "./service-utils.ts";
+import { dockerNetworkArgs } from "../Platform.ts";
+import { dockerRunService, hostHttpHealthCheck, type ServiceDependency } from "./service-utils.ts";
 import { stackHealthBudgets } from "./health-budgets.ts";
 
 interface DockerMailpitOptions {
@@ -8,7 +9,8 @@ interface DockerMailpitOptions {
   readonly webPort: number;
   readonly smtpPort: number;
   readonly pop3Port: number;
-  readonly networkArgs: ReadonlyArray<string>;
+  readonly platformOs: string;
+  readonly dependencies: ReadonlyArray<ServiceDependency>;
 }
 
 const mailpitHealthCheck = (port: number): ServiceDef["healthCheck"] =>
@@ -19,9 +21,10 @@ const mailpitHealthCheck = (port: number): ServiceDef["healthCheck"] =>
 export const makeMailpitServiceDocker = (opts: DockerMailpitOptions): ServiceDef =>
   dockerRunService({
     name: "mailpit",
-    containerName: `supabase-mailpit-${opts.apiPort}`,
+    apiPort: opts.apiPort,
     image: opts.image,
-    networkArgs: opts.networkArgs,
+    networkArgs: dockerNetworkArgs(opts.platformOs, [opts.webPort, opts.smtpPort, opts.pop3Port]),
+    dependencies: opts.dependencies,
     env: {
       MP_UI_BIND_ADDR: `0.0.0.0:${opts.webPort}`,
       MP_SMTP_BIND_ADDR: `0.0.0.0:${opts.smtpPort}`,
diff --git a/packages/stack/src/services/pgmeta.ts b/packages/stack/src/services/pgmeta.ts
index 67a258c6f2..26a9e26d7a 100644
--- a/packages/stack/src/services/pgmeta.ts
+++ b/packages/stack/src/services/pgmeta.ts
@@ -1,4 +1,5 @@
 import type { ServiceDef } from "@supabase/process-compose";
+import { dockerNetworkArgs } from "../Platform.ts";
 import { dockerRunService, type ServiceDependency } from "./service-utils.ts";
 import { stackHealthBudgets } from "./health-budgets.ts";
 
@@ -8,7 +9,7 @@ interface DockerPgmetaOptions {
   readonly port: number;
   readonly dbHost: string;
   readonly dbPort: number;
-  readonly networkArgs: ReadonlyArray<string>;
+  readonly platformOs: string;
   readonly dependencies: ReadonlyArray<ServiceDependency>;
 }
 
@@ -26,9 +27,9 @@ const pgmetaHealthCheck = (port: number): ServiceDef["healthCheck"] => ({
 export const makePgmetaServiceDocker = (opts: DockerPgmetaOptions): ServiceDef =>
   dockerRunService({
     name: "pgmeta",
-    containerName: `supabase-pgmeta-${opts.apiPort}`,
+    apiPort: opts.apiPort,
     image: opts.image,
-    networkArgs: opts.networkArgs,
+    networkArgs: dockerNetworkArgs(opts.platformOs, [opts.port]),
     env: {
       PG_META_PORT: String(opts.port),
       PG_META_DB_HOST: opts.dbHost,
@@ -37,6 +38,6 @@ export const makePgmetaServiceDocker = (opts: DockerPgmetaOptions): ServiceDef =
       PG_META_DB_PORT: String(opts.dbPort),
       PG_META_DB_PASSWORD: "postgres",
     },
-    dependsOn: opts.dependencies,
+    dependencies: opts.dependencies,
     healthCheck: pgmetaHealthCheck(opts.port),
   });
diff --git a/packages/stack/src/services/pooler.ts b/packages/stack/src/services/pooler.ts
index 7d81e3edda..0091689aa5 100644
--- a/packages/stack/src/services/pooler.ts
+++ b/packages/stack/src/services/pooler.ts
@@ -1,4 +1,5 @@
 import type { ServiceDef } from "@supabase/process-compose";
+import { dockerPortMapArgs } from "../Platform.ts";
 import { dockerRunService, type ServiceDependency } from "./service-utils.ts";
 import { stackHealthBudgets } from "./health-budgets.ts";
 
@@ -8,6 +9,7 @@ interface DockerPoolerOptions {
   readonly image: string;
   readonly apiPort: number;
   readonly hostAdminPort: number;
+  readonly hostPort: number;
   readonly dbHost: string;
   readonly dbPort: number;
   readonly poolMode: PoolMode;
@@ -17,7 +19,7 @@ interface DockerPoolerOptions {
   readonly tenantId: string;
   readonly encryptionKey: string;
   readonly secretKeyBase: string;
-  readonly networkArgs: ReadonlyArray<string>;
+  readonly platformOs: string;
   readonly dependencies: ReadonlyArray<ServiceDependency>;
 }
 
@@ -68,9 +70,18 @@ export const makePoolerServiceDocker = (opts: DockerPoolerOptions): ServiceDef =
   (() => {
     return dockerRunService({
       name: "pooler",
-      containerName: `supabase-pooler-${opts.apiPort}`,
+      apiPort: opts.apiPort,
       image: opts.image,
-      networkArgs: opts.networkArgs,
+      networkArgs: dockerPortMapArgs(opts.platformOs, [
+        { host: opts.hostAdminPort, container: poolerContainerPorts.admin },
+        {
+          host: opts.hostPort,
+          container:
+            opts.poolMode === "session"
+              ? poolerContainerPorts.session
+              : poolerContainerPorts.transaction,
+        },
+      ]),
       env: {
         PORT: String(poolerContainerPorts.admin),
         PROXY_PORT_SESSION: String(poolerContainerPorts.session),
@@ -91,7 +102,7 @@ export const makePoolerServiceDocker = (opts: DockerPoolerOptions): ServiceDef =
         "-c",
         `/app/bin/migrate && /app/bin/supavisor eval '${tenantScript(opts)}' && /app/bin/server`,
       ],
-      dependsOn: opts.dependencies,
+      dependencies: opts.dependencies,
       healthCheck: poolerHealthCheck(opts.hostAdminPort),
     });
   })();
diff --git a/packages/stack/src/services/postgres-init.ts b/packages/stack/src/services/postgres-init.ts
index 694951230d..63917352b1 100644
--- a/packages/stack/src/services/postgres-init.ts
+++ b/packages/stack/src/services/postgres-init.ts
@@ -1,4 +1,5 @@
 import type { ServiceDef } from "@supabase/process-compose";
+import type { ServiceDependency } from "./service-utils.ts";
 
 interface PostgresInitOptions {
   readonly postgresDir: string;
@@ -8,6 +9,7 @@ interface PostgresInitOptions {
    * Data API privileges on the `public` schema so newly-created entities require explicit GRANTs.
    */
   readonly autoExposeNewTables: boolean;
+  readonly dependencies: ReadonlyArray<ServiceDependency>;
 }
 
 /**
@@ -136,7 +138,7 @@ END
       LD_LIBRARY_PATH: pgLibDir,
       PGPASSWORD: "postgres",
     },
-    dependencies: [{ service: "postgres", condition: "healthy" }],
+    dependencies: opts.dependencies,
     supervision: {},
     restart: "no",
   };
diff --git a/packages/stack/src/services/postgres.ts b/packages/stack/src/services/postgres.ts
index 6968f989f8..296cc5d5bb 100644
--- a/packages/stack/src/services/postgres.ts
+++ b/packages/stack/src/services/postgres.ts
@@ -1,16 +1,20 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import type { ServiceDef } from "@supabase/process-compose";
-import {
-  dockerServiceCleanup,
-  dockerServiceOrphanCleanup,
-  removePathOnOrphanCleanup,
-} from "./docker-cleanup.ts";
+import { dockerContainerName } from "../CleanupTargets.ts";
+import { dockerNetworkArgs } from "../Platform.ts";
+import { removePathOnOrphanCleanup } from "./docker-cleanup.ts";
 import { stackHealthBudgets } from "./health-budgets.ts";
+import {
+  dockerExecHealthCheck,
+  dockerRunService,
+  type ServiceDependency,
+} from "./service-utils.ts";
 
 interface PostgresServiceOptions {
   readonly dataDir: string;
   readonly port: number;
   readonly cleanupDataDirOnExit?: boolean;
+  readonly dependencies: ReadonlyArray<ServiceDependency>;
 }
 
 interface NativePostgresOptions extends PostgresServiceOptions {
@@ -21,7 +25,7 @@ interface NativePostgresOptions extends PostgresServiceOptions {
 
 interface DockerPostgresOptions extends PostgresServiceOptions {
   readonly image: string;
-  readonly networkArgs: readonly string[];
+  readonly platformOs: string;
   readonly jwtSecret: string;
   readonly jwtExpiry: number;
   readonly apiPort: number;
@@ -101,14 +105,10 @@ const postgresHealthCheck = (binPath: string, port: number) => ({
  * queries with "unexpected EOF". We use `docker exec` to run pg_isready
  * inside the container, which verifies postgres is accepting commands.
  */
-const postgresDockerHealthCheck = (containerName: string, port: number) => ({
-  probe: {
-    _tag: "Exec" as const,
-    command: "docker",
-    args: ["exec", containerName, "pg_isready", "-p", String(port), "-U", "postgres"],
-  },
-  ...stackHealthBudgets.postgresDocker,
-});
+const postgresDockerHealthCheck = (containerName: string, port: number) =>
+  dockerExecHealthCheck(containerName, "pg_isready", ["-p", String(port), "-U", "postgres"], {
+    ...stackHealthBudgets.postgresDocker,
+  });
 
 export const makePostgresService = (opts: NativePostgresOptions): ServiceDef => {
   const initScript = `${opts.binPath}/share/supabase-cli/bin/supabase-postgres-init.sh`;
@@ -146,6 +146,7 @@ export const makePostgresService = (opts: NativePostgresOptions): ServiceDef =>
         `hba_file=${customHbaPath}`,
       ],
       env: postgresEnv(opts),
+      dependencies: opts.dependencies,
       healthCheck: postgresHealthCheck(opts.binPath, opts.port),
       shutdown: { signal: "SIGTERM", timeoutSeconds: 10 },
       supervision: {
@@ -163,6 +164,7 @@ export const makePostgresService = (opts: NativePostgresOptions): ServiceDef =>
     command: "bash",
     args: [initScript, "-p", String(opts.port), ...NATIVE_POSTGRES_RUNTIME_ARGS],
     env: postgresEnv(opts),
+    dependencies: opts.dependencies,
     healthCheck: postgresHealthCheck(opts.binPath, opts.port),
     shutdown: { signal: "SIGTERM", timeoutSeconds: 10 },
     supervision: { orphanCleanup: orphanCleanup(opts) },
@@ -172,33 +174,19 @@ export const makePostgresService = (opts: NativePostgresOptions): ServiceDef =>
 
 export const makePostgresServiceDocker = (opts: DockerPostgresOptions): ServiceDef => {
   const env = postgresDockerEnv(opts);
-  const envArgs = Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
-  const containerName = `supabase-postgres-${opts.apiPort}`;
-  const dockerArgs = [
-    "run",
-    "--rm",
-    "--name",
-    containerName,
-    ...opts.networkArgs,
-    "-v",
-    `${opts.dataDir}:/var/lib/postgresql/data`,
-    ...envArgs,
-    "--entrypoint",
-    "sh",
-    opts.image,
-    "-c",
-    dockerPostgresEntrypoint(opts.port),
-  ];
-  return {
+  const containerName = dockerContainerName("postgres", opts.apiPort);
+  return dockerRunService({
     name: "postgres",
-    command: "docker",
-    args: dockerArgs,
+    apiPort: opts.apiPort,
+    image: opts.image,
+    networkArgs: dockerNetworkArgs(opts.platformOs, [opts.port]),
+    volumes: [`${opts.dataDir}:/var/lib/postgresql/data`],
+    env,
+    entrypoint: "sh",
+    cmd: ["-c", dockerPostgresEntrypoint(opts.port)],
+    dependencies: opts.dependencies,
     healthCheck: postgresDockerHealthCheck(containerName, opts.port),
     shutdown: { signal: "SIGTERM", timeoutSeconds: 10 },
-    cleanup: dockerServiceCleanup(containerName),
-    supervision: {
-      orphanCleanup: [...dockerServiceOrphanCleanup(containerName), ...orphanCleanup(opts)],
-    },
-    restart: "unless-stopped",
-  };
+    orphanCleanup: orphanCleanup(opts),
+  });
 };
diff --git a/packages/stack/src/services/postgrest.ts b/packages/stack/src/services/postgrest.ts
index 0562277927..c8c7959de3 100644
--- a/packages/stack/src/services/postgrest.ts
+++ b/packages/stack/src/services/postgrest.ts
@@ -1,6 +1,7 @@
 import type { ServiceDef } from "@supabase/process-compose";
-import { dockerServiceCleanup, dockerServiceOrphanCleanup } from "./docker-cleanup.ts";
+import { dockerNetworkArgs } from "../Platform.ts";
 import { stackHealthBudgets } from "./health-budgets.ts";
+import { dockerRunService, type ServiceDependency } from "./service-utils.ts";
 
 interface PostgrestServiceOptions {
   readonly dbPort: number;
@@ -9,6 +10,7 @@ interface PostgrestServiceOptions {
   readonly extraSearchPath: ReadonlyArray<string>;
   readonly maxRows: number;
   readonly jwtSecret: string;
+  readonly dependencies: ReadonlyArray<ServiceDependency>;
 }
 
 interface NativePostgrestOptions extends PostgrestServiceOptions {
@@ -18,7 +20,7 @@ interface NativePostgrestOptions extends PostgrestServiceOptions {
 interface DockerPostgrestOptions extends PostgrestServiceOptions {
   readonly image: string;
   readonly dbHost: string;
-  readonly networkArgs: readonly string[];
+  readonly platformOs: string;
   readonly adminPort: number;
   readonly apiPort: number;
 }
@@ -47,13 +49,11 @@ const postgrestHealthCheck = (port: number) => ({
   ...stackHealthBudgets.postgrest,
 });
 
-const postgrestDependencies = [{ service: "postgres-init", condition: "completed" as const }];
-
 export const makePostgrestService = (opts: NativePostgrestOptions): ServiceDef => ({
   name: "postgrest",
   command: `${opts.binPath}/postgrest`,
   env: postgrestEnv(opts),
-  dependencies: postgrestDependencies,
+  dependencies: opts.dependencies,
   healthCheck: postgrestHealthCheck(opts.port),
   supervision: {},
   restart: "unless-stopped",
@@ -64,17 +64,13 @@ export const makePostgrestServiceDocker = (opts: DockerPostgrestOptions): Servic
     ...postgrestEnv(opts, opts.dbHost),
     PGRST_ADMIN_SERVER_PORT: String(opts.adminPort),
   };
-  const envArgs = Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
-  const containerName = `supabase-postgrest-${opts.apiPort}`;
-
-  return {
+  return dockerRunService({
     name: "postgrest",
-    command: "docker",
-    args: ["run", "--rm", "--name", containerName, ...opts.networkArgs, ...envArgs, opts.image],
-    dependencies: postgrestDependencies,
+    apiPort: opts.apiPort,
+    image: opts.image,
+    networkArgs: dockerNetworkArgs(opts.platformOs, [opts.port, opts.adminPort]),
+    env,
+    dependencies: opts.dependencies,
     healthCheck: postgrestHealthCheck(opts.port),
-    cleanup: dockerServiceCleanup(containerName),
-    supervision: { orphanCleanup: dockerServiceOrphanCleanup(containerName) },
-    restart: "unless-stopped",
-  };
+  });
 };
diff --git a/packages/stack/src/services/realtime.ts b/packages/stack/src/services/realtime.ts
index a8bd42eacd..68910a19e4 100644
--- a/packages/stack/src/services/realtime.ts
+++ b/packages/stack/src/services/realtime.ts
@@ -1,4 +1,5 @@
 import type { ServiceDef } from "@supabase/process-compose";
+import { dockerNetworkArgs } from "../Platform.ts";
 import { dockerRunService, type ServiceDependency } from "./service-utils.ts";
 import { stackHealthBudgets } from "./health-budgets.ts";
 
@@ -14,7 +15,7 @@ interface DockerRealtimeOptions {
   readonly encryptionKey: string;
   readonly secretKeyBase: string;
   readonly maxHeaderLength: number;
-  readonly networkArgs: ReadonlyArray<string>;
+  readonly platformOs: string;
   readonly dependencies: ReadonlyArray<ServiceDependency>;
 }
 
@@ -38,9 +39,9 @@ const realtimeHealthCheck = (port: number, tenantId: string): ServiceDef["health
 export const makeRealtimeServiceDocker = (opts: DockerRealtimeOptions): ServiceDef =>
   dockerRunService({
     name: "realtime",
-    containerName: `supabase-realtime-${opts.apiPort}`,
+    apiPort: opts.apiPort,
     image: opts.image,
-    networkArgs: opts.networkArgs,
+    networkArgs: dockerNetworkArgs(opts.platformOs, [opts.port]),
     env: {
       PORT: String(opts.port),
       DB_HOST: opts.dbHost,
@@ -62,6 +63,6 @@ export const makeRealtimeServiceDocker = (opts: DockerRealtimeOptions): ServiceD
       RUN_JANITOR: "true",
       MAX_HEADER_LENGTH: String(opts.maxHeaderLength),
     },
-    dependsOn: opts.dependencies,
+    dependencies: opts.dependencies,
     healthCheck: realtimeHealthCheck(opts.port, opts.tenantId),
   });
diff --git a/packages/stack/src/services/service-utils.ts b/packages/stack/src/services/service-utils.ts
index 4259ed02f7..91a326eaea 100644
--- a/packages/stack/src/services/service-utils.ts
+++ b/packages/stack/src/services/service-utils.ts
@@ -1,4 +1,6 @@
 import type { ExternalCleanupAction, ServiceDef } from "@supabase/process-compose";
+import { dockerContainerName } from "../CleanupTargets.ts";
+import type { ServiceName } from "../ServiceName.ts";
 import { dockerServiceCleanup, dockerServiceOrphanCleanup } from "./docker-cleanup.ts";
 
 export interface ServiceDependency {
@@ -7,8 +9,8 @@ export interface ServiceDependency {
 }
 
 interface DockerRunServiceOptions {
-  readonly name: string;
-  readonly containerName: string;
+  readonly name: ServiceName;
+  readonly apiPort: number;
   readonly image: string;
   readonly networkArgs?: ReadonlyArray<string>;
   readonly env?: Record<string, string>;
@@ -16,7 +18,7 @@ interface DockerRunServiceOptions {
   readonly cmd?: ReadonlyArray<string>;
   readonly entrypoint?: string;
   readonly volumes?: ReadonlyArray<string>;
-  readonly dependsOn?: ReadonlyArray<ServiceDependency>;
+  readonly dependencies: ReadonlyArray<ServiceDependency>;
   readonly healthCheck?: ServiceDef["healthCheck"];
   readonly restart?: ServiceDef["restart"];
   readonly shutdown?: ServiceDef["shutdown"];
@@ -56,11 +58,12 @@ export const dockerExecHealthCheck = (
 });
 
 export const dockerRunService = (opts: DockerRunServiceOptions): ServiceDef => {
+  const containerName = dockerContainerName(opts.name, opts.apiPort);
   const dockerArgs = [
     "run",
     "--rm",
     "--name",
-    opts.containerName,
+    containerName,
     ...(opts.networkArgs ?? []),
     ...(opts.volumes ?? []).flatMap((volume) => ["-v", volume]),
     ...(opts.entrypoint === undefined ? [] : ["--entrypoint", opts.entrypoint]),
@@ -74,15 +77,12 @@ export const dockerRunService = (opts: DockerRunServiceOptions): ServiceDef => {
     name: opts.name,
     command: "docker",
     args: dockerArgs,
-    dependencies: opts.dependsOn,
+    dependencies: opts.dependencies,
     healthCheck: opts.healthCheck,
     shutdown: opts.shutdown,
-    cleanup: dockerServiceCleanup(opts.containerName),
+    cleanup: dockerServiceCleanup(containerName),
     supervision: {
-      orphanCleanup: [
-        ...dockerServiceOrphanCleanup(opts.containerName),
-        ...(opts.orphanCleanup ?? []),
-      ],
+      orphanCleanup: [...dockerServiceOrphanCleanup(containerName), ...(opts.orphanCleanup ?? [])],
     },
     restart: opts.restart ?? "unless-stopped",
   };
diff --git a/packages/stack/src/services/services.unit.test.ts b/packages/stack/src/services/services.unit.test.ts
index 2c5b887999..119db96f54 100644
--- a/packages/stack/src/services/services.unit.test.ts
+++ b/packages/stack/src/services/services.unit.test.ts
@@ -7,14 +7,20 @@ import { makeAuthServiceNative, makeAuthServiceDocker } from "./auth.ts";
 import { makeEdgeRuntimeServiceDocker, makeEdgeRuntimeServiceNative } from "./edge-runtime.ts";
 import { makeImgproxyServiceDocker } from "./imgproxy.ts";
 import { makeMailpitServiceDocker } from "./mailpit.ts";
+import { makePgmetaServiceDocker } from "./pgmeta.ts";
 import {
   makePostgresInitService,
   REVOKE_DEFAULT_DATA_API_PRIVILEGES_SQL,
 } from "./postgres-init.ts";
 import { makePostgresService, makePostgresServiceDocker } from "./postgres.ts";
-import { makePostgrestService } from "./postgrest.ts";
+import { makePostgrestService, makePostgrestServiceDocker } from "./postgrest.ts";
+import { makeRealtimeServiceDocker } from "./realtime.ts";
 import { makePoolerServiceDocker, poolerContainerPorts } from "./pooler.ts";
-import { LOCAL_S3_PROTOCOL_ACCESS_KEY_ID, LOCAL_S3_PROTOCOL_ACCESS_KEY_SECRET } from "./storage.ts";
+import {
+  LOCAL_S3_PROTOCOL_ACCESS_KEY_ID,
+  LOCAL_S3_PROTOCOL_ACCESS_KEY_SECRET,
+  makeStorageServiceDocker,
+} from "./storage.ts";
 import { makeStudioServiceDocker } from "./studio.ts";
 import { makeVectorServiceDocker } from "./vector.ts";
 import { DEFAULT_VERSIONS, dockerImageForService } from "../versions.ts";
@@ -26,14 +32,13 @@ const POSTGRES_BIN_PATH = `/cache/postgres/${DEFAULT_VERSIONS.postgres}/darwin-a
 const POSTGREST_BIN_PATH = `/cache/postgrest/${DEFAULT_VERSIONS.postgrest}/macos-aarch64`;
 const AUTH_BIN_PATH = `/cache/auth/${DEFAULT_VERSIONS.auth}/arm64`;
 const EDGE_RUNTIME_BIN_PATH = `/cache/edge-runtime/${DEFAULT_VERSIONS["edge-runtime"]}/aarch64-darwin`;
-const LINUX_HOST_GATEWAY_ARGS = ["--add-host", "host.docker.internal:host-gateway"];
-
 describe("makePostgresService", () => {
   it("creates a postgres ServiceDef with correct defaults", () => {
     const def = makePostgresService({
       binPath: POSTGRES_BIN_PATH,
       dataDir: "/tmp/supabase/data",
       port: DB_PORT,
+      dependencies: [],
     });
 
     expect(def.name).toBe("postgres");
@@ -61,7 +66,7 @@ describe("makePostgresService", () => {
         LD_LIBRARY_PATH: `${POSTGRES_BIN_PATH}/lib`,
       },
     });
-    expect(def.dependencies).toBeUndefined();
+    expect(def.dependencies).toEqual([]);
     expect(def.restart).toBe("unless-stopped");
     expect(def.supervision).toBeDefined();
   });
@@ -101,7 +106,7 @@ describe("makeStudioServiceDocker", () => {
       analyticsBackend: "postgres",
       analyticsUrl: "http://host.docker.internal:54327",
       analyticsApiKey: "test-api-key",
-      networkArgs: ["-p", "54323:54323"],
+      platformOs: "darwin",
       dependencies: [{ service: "pgmeta", condition: "healthy" }],
     });
 
@@ -125,6 +130,7 @@ describe("makePostgresService (dockerAccessible)", () => {
       port: DB_PORT,
       dockerAccessible: true,
       cleanupDataDirOnExit: true,
+      dependencies: [],
     });
     const customHbaPath = `${path.join(tempDir, "data")}_pg_hba_docker.conf`;
 
@@ -166,10 +172,11 @@ describe("makePostgresServiceDocker", () => {
       image: dockerImageForService("postgres", DEFAULT_VERSIONS.postgres),
       dataDir: "/tmp/supabase/data",
       port: DB_PORT,
-      networkArgs: [...LINUX_HOST_GATEWAY_ARGS, "-p", `${DB_PORT}:${DB_PORT}`],
+      platformOs: "linux",
       jwtSecret: "test-jwt-secret-with-at-least-32-characters",
       jwtExpiry: 3600,
       apiPort: API_PORT,
+      dependencies: [],
     });
 
     expect(def.name).toBe("postgres");
@@ -197,7 +204,7 @@ describe("makePostgresServiceDocker", () => {
         "postgres",
       ],
     });
-    expect(def.dependencies).toBeUndefined();
+    expect(def.dependencies).toEqual([]);
     expect(def.restart).toBe("unless-stopped");
     expect(def.supervision).toEqual({
       orphanCleanup: [
@@ -216,10 +223,11 @@ describe("makePostgresServiceDocker", () => {
       image: dockerImageForService("postgres", DEFAULT_VERSIONS.postgres),
       dataDir: "/tmp/supabase/data",
       port: DB_PORT,
-      networkArgs: [...LINUX_HOST_GATEWAY_ARGS, "-p", `${DB_PORT}:${DB_PORT}`],
+      platformOs: "linux",
       jwtSecret: "test-jwt-secret-with-at-least-32-characters",
       jwtExpiry: 3600,
       apiPort: API_PORT,
+      dependencies: [],
     });
 
     const script = def.args?.[def.args.length - 1] as string;
@@ -243,6 +251,7 @@ describe("makePostgrestService", () => {
       extraSearchPath: ["public", "extensions"],
       maxRows: 1000,
       jwtSecret: JWT_SECRET,
+      dependencies: [{ service: "postgres-init", condition: "completed" }],
     });
 
     expect(def.name).toBe("postgrest");
@@ -263,6 +272,38 @@ describe("makePostgrestService", () => {
     });
     expect(def.supervision).toBeDefined();
   });
+
+  it("creates a docker definition with caller-supplied topology and derived identity", () => {
+    const dependencies = [{ service: "postgres", condition: "healthy" }] as const;
+    const def = makePostgrestServiceDocker({
+      image: dockerImageForService("postgrest", DEFAULT_VERSIONS.postgrest),
+      apiPort: API_PORT,
+      dbHost: "host.docker.internal",
+      dbPort: DB_PORT,
+      port: 54323,
+      adminPort: 54324,
+      schemas: ["public", "storage"],
+      extraSearchPath: ["public", "extensions"],
+      maxRows: 1000,
+      jwtSecret: JWT_SECRET,
+      platformOs: "linux",
+      dependencies,
+    });
+
+    expect(def.command).toBe("docker");
+    expect(def.args).toContain(`supabase-postgrest-${API_PORT}`);
+    expect(def.args).toContain("host.docker.internal:host-gateway");
+    expect(def.args).toContain("54323:54323");
+    expect(def.args).toContain("54324:54324");
+    expect(def.args).toContain("PGRST_ADMIN_SERVER_PORT=54324");
+    expect(def.dependencies).toEqual(dependencies);
+    expect(def.supervision?.orphanCleanup).toContainEqual({
+      _tag: "RunCommand",
+      executable: "docker",
+      args: ["rm", "-f", `supabase-postgrest-${API_PORT}`],
+      timeoutMs: 5_000,
+    });
+  });
 });
 
 describe("makeAuthServiceNative", () => {
@@ -306,7 +347,7 @@ describe("makeAuthServiceDocker", () => {
       jwtExpiry: 3600,
       externalUrl: `http://127.0.0.1:${API_PORT}`,
       dbHost: "127.0.0.1",
-      networkArgs: [...LINUX_HOST_GATEWAY_ARGS, "-p", "9999:9999"],
+      platformOs: "linux",
       apiPort: API_PORT,
       dependencies: [{ service: "postgres", condition: "healthy" }],
     });
@@ -345,7 +386,7 @@ describe("makeEdgeRuntimeServiceDocker", () => {
         inspectorPort: 54341,
         policy: "per_worker",
         env: { SUPABASE_INTERNAL_DEBUG: "true" },
-        networkArgs: [...LINUX_HOST_GATEWAY_ARGS, "-p", "54340:54340", "-p", "54341:54341"],
+        platformOs: "linux",
         dependencies: [{ service: "postgres", condition: "healthy" }],
       });
 
@@ -423,6 +464,7 @@ describe("makePostgresInitService", () => {
       postgresDir: POSTGRES_BIN_PATH,
       dbPort: DB_PORT,
       autoExposeNewTables: true,
+      dependencies: [{ service: "postgres", condition: "healthy" }],
     });
 
     expect(def.name).toBe("postgres-init");
@@ -441,6 +483,7 @@ describe("makePostgresInitService", () => {
       postgresDir: POSTGRES_BIN_PATH,
       dbPort: DB_PORT,
       autoExposeNewTables: true,
+      dependencies: [{ service: "postgres", condition: "healthy" }],
     });
     const script = def.args?.[1] as string;
     expect(script).not.toContain("set -e");
@@ -451,6 +494,7 @@ describe("makePostgresInitService", () => {
       postgresDir: "/cache/postgres/17/darwin-arm64",
       dbPort: DB_PORT,
       autoExposeNewTables: true,
+      dependencies: [{ service: "postgres", condition: "healthy" }],
     });
     const script = def.args?.[1] as string;
     expect(script).toContain("authenticator");
@@ -462,6 +506,7 @@ describe("makePostgresInitService", () => {
       postgresDir: "/cache/postgres/17/darwin-arm64",
       dbPort: DB_PORT,
       autoExposeNewTables: true,
+      dependencies: [{ service: "postgres", condition: "healthy" }],
     });
     const script = def.args?.[1] as string;
 
@@ -477,6 +522,7 @@ describe("makePostgresInitService", () => {
       postgresDir: "/cache/postgres/17/darwin-arm64",
       dbPort: DB_PORT,
       autoExposeNewTables: true,
+      dependencies: [{ service: "postgres", condition: "healthy" }],
     });
     const script = def.args?.[1] as string;
     expect(script).not.toMatch(/sh .+migrate\.sh/);
@@ -490,6 +536,7 @@ describe("makePostgresInitService", () => {
       postgresDir: POSTGRES_BIN_PATH,
       dbPort: DB_PORT,
       autoExposeNewTables: true,
+      dependencies: [{ service: "postgres", condition: "healthy" }],
     });
     const script = def.args?.[1] as string;
     expect(script).not.toContain("alter default privileges");
@@ -501,6 +548,7 @@ describe("makePostgresInitService", () => {
       postgresDir: POSTGRES_BIN_PATH,
       dbPort: DB_PORT,
       autoExposeNewTables: false,
+      dependencies: [{ service: "postgres", condition: "healthy" }],
     });
     const script = def.args?.[1] as string;
     expect(script).toContain(REVOKE_DEFAULT_DATA_API_PRIVILEGES_SQL);
@@ -515,6 +563,90 @@ describe("makePostgresInitService", () => {
 });
 
 describe("docker-backed auxiliary services", () => {
+  it("defines realtime command, topology, environment, and readiness locally", () => {
+    const dependencies = [{ service: "postgres", condition: "healthy" }] as const;
+    const def = makeRealtimeServiceDocker({
+      image: dockerImageForService("realtime", DEFAULT_VERSIONS.realtime),
+      apiPort: API_PORT,
+      port: 54330,
+      dbHost: "host.docker.internal",
+      dbPort: DB_PORT,
+      jwtSecret: JWT_SECRET,
+      jwtJwks: "test-jwks",
+      tenantId: "realtime-dev",
+      encryptionKey: "supabaserealtime",
+      secretKeyBase: "test-secret-key-base",
+      maxHeaderLength: 4096,
+      platformOs: "linux",
+      dependencies,
+    });
+
+    expect(def.args).toContain(`supabase-realtime-${API_PORT}`);
+    expect(def.args).toContain("54330:54330");
+    expect(def.args).toContain("DB_HOST=host.docker.internal");
+    expect(def.dependencies).toEqual(dependencies);
+    expect(def.healthCheck?.probe).toEqual(
+      expect.objectContaining({ _tag: "Exec", command: "curl" }),
+    );
+  });
+
+  it("defines storage mounts, cleanup, topology, and readiness locally", () => {
+    const dependencies = [{ service: "postgres-init", condition: "completed" }] as const;
+    const def = makeStorageServiceDocker({
+      image: dockerImageForService("storage", DEFAULT_VERSIONS.storage),
+      apiPort: API_PORT,
+      port: 54331,
+      dbHost: "host.docker.internal",
+      dbPort: DB_PORT,
+      dataDir: "/tmp/supabase/storage",
+      anonKey: "anon-key",
+      serviceKey: "service-key",
+      jwtSecret: JWT_SECRET,
+      jwtJwks: "test-jwks",
+      fileSizeLimit: "50MiB",
+      enableImageTransformation: true,
+      imgproxyUrl: "http://host.docker.internal:54332",
+      s3ProtocolEnabled: true,
+      cleanupDataDirOnExit: true,
+      platformOs: "linux",
+      dependencies,
+    });
+
+    expect(def.args).toContain(`supabase-storage-${API_PORT}`);
+    expect(def.args).toContain("/tmp/supabase/storage:/var/lib/storage");
+    expect(def.args).toContain("54331:54331");
+    expect(def.dependencies).toEqual(dependencies);
+    expect(def.healthCheck?.probe).toEqual(
+      expect.objectContaining({ _tag: "Http", port: 54331, path: "/status" }),
+    );
+    expect(def.supervision?.orphanCleanup).toContainEqual({
+      _tag: "RemovePath",
+      path: "/tmp/supabase/storage",
+      recursive: true,
+    });
+  });
+
+  it("defines postgres metadata command, topology, environment, and readiness locally", () => {
+    const dependencies = [{ service: "postgres", condition: "healthy" }] as const;
+    const def = makePgmetaServiceDocker({
+      image: dockerImageForService("pgmeta", DEFAULT_VERSIONS.pgmeta),
+      apiPort: API_PORT,
+      port: 54336,
+      dbHost: "host.docker.internal",
+      dbPort: DB_PORT,
+      platformOs: "linux",
+      dependencies,
+    });
+
+    expect(def.args).toContain(`supabase-pgmeta-${API_PORT}`);
+    expect(def.args).toContain("54336:54336");
+    expect(def.args).toContain("PG_META_DB_HOST=host.docker.internal");
+    expect(def.dependencies).toEqual(dependencies);
+    expect(def.healthCheck?.probe).toEqual(
+      expect.objectContaining({ _tag: "Http", port: 54336, path: "/health" }),
+    );
+  });
+
   it("uses a host HTTP readiness probe for mailpit", () => {
     const def = makeMailpitServiceDocker({
       image: dockerImageForService("mailpit", DEFAULT_VERSIONS.mailpit),
@@ -522,15 +654,8 @@ describe("docker-backed auxiliary services", () => {
       webPort: 54323,
       smtpPort: 54324,
       pop3Port: 54325,
-      networkArgs: [
-        ...LINUX_HOST_GATEWAY_ARGS,
-        "-p",
-        "54323:54323",
-        "-p",
-        "54324:54324",
-        "-p",
-        "54325:54325",
-      ],
+      platformOs: "linux",
+      dependencies: [],
     });
 
     expect(def.healthCheck?.probe).toEqual({
@@ -548,7 +673,7 @@ describe("docker-backed auxiliary services", () => {
       apiPort: API_PORT,
       port: 54326,
       dataDir: "/tmp/supabase/storage",
-      networkArgs: [...LINUX_HOST_GATEWAY_ARGS, "-p", "54326:54326"],
+      platformOs: "linux",
       dependencies: [{ service: "storage", condition: "healthy" }],
     });
 
@@ -569,7 +694,7 @@ describe("docker-backed auxiliary services", () => {
       serviceHost: "127.0.0.1",
       analyticsPort: 54327,
       analyticsApiKey: "test-api-key",
-      networkArgs: [],
+      platformOs: "darwin",
       dependencies: [{ service: "analytics", condition: "healthy" }],
     });
 
@@ -591,13 +716,11 @@ describe("docker-backed auxiliary services", () => {
       image: dockerImageForService("analytics", DEFAULT_VERSIONS.analytics),
       apiPort: API_PORT,
       hostPort: 54328,
-      listenPort: 4000,
-      nodeHost: "0.0.0.0",
+      platformOs: "darwin",
       dbHost: "127.0.0.1",
       dbPort: DB_PORT,
       apiKey: "test-api-key",
       backend: "postgres",
-      networkArgs: ["-p", "54328:4000"],
       dependencies: [{ service: "postgres", condition: "healthy" }],
     });
 
@@ -621,13 +744,11 @@ describe("docker-backed auxiliary services", () => {
       image: dockerImageForService("analytics", DEFAULT_VERSIONS.analytics),
       apiPort: API_PORT,
       hostPort: 54328,
-      listenPort: 4000,
-      nodeHost: "0.0.0.0",
+      platformOs: "linux",
       dbHost: "host.docker.internal",
       dbPort: DB_PORT,
       apiKey: "test-api-key",
       backend: "postgres",
-      networkArgs: [...LINUX_HOST_GATEWAY_ARGS, "-p", "54328:4000"],
       dependencies: [{ service: "postgres", condition: "healthy" }],
     });
 
@@ -643,6 +764,8 @@ describe("docker-backed auxiliary services", () => {
       image: dockerImageForService("pooler", DEFAULT_VERSIONS.pooler),
       apiPort: API_PORT,
       hostAdminPort: 54329,
+      hostPort: 54330,
+      platformOs: "linux",
       dbHost: "127.0.0.1",
       dbPort: DB_PORT,
       poolMode: "transaction",
@@ -652,12 +775,6 @@ describe("docker-backed auxiliary services", () => {
       tenantId: "pooler-dev",
       encryptionKey: "12345678901234567890123456789012",
       secretKeyBase: "1234567890123456789012345678901234567890123456789012345678901234",
-      networkArgs: [
-        "-p",
-        `54329:${poolerContainerPorts.admin}`,
-        "-p",
-        `54330:${poolerContainerPorts.transaction}`,
-      ],
       dependencies: [{ service: "postgres", condition: "healthy" }],
     });
 
diff --git a/packages/stack/src/services/storage.ts b/packages/stack/src/services/storage.ts
index 87e21a6ab9..cf6f88e33a 100644
--- a/packages/stack/src/services/storage.ts
+++ b/packages/stack/src/services/storage.ts
@@ -1,4 +1,5 @@
 import type { ServiceDef } from "@supabase/process-compose";
+import { dockerNetworkArgs } from "../Platform.ts";
 import { removePathOnOrphanCleanup } from "./docker-cleanup.ts";
 import { dockerRunService, type ServiceDependency } from "./service-utils.ts";
 import { stackHealthBudgets } from "./health-budgets.ts";
@@ -18,7 +19,7 @@ interface DockerStorageOptions {
   readonly enableImageTransformation: boolean;
   readonly imgproxyUrl: string;
   readonly s3ProtocolEnabled: boolean;
-  readonly networkArgs: ReadonlyArray<string>;
+  readonly platformOs: string;
   readonly dependencies: ReadonlyArray<ServiceDependency>;
   readonly cleanupDataDirOnExit?: boolean;
 }
@@ -45,9 +46,9 @@ const storageHealthCheck = (port: number): ServiceDef["healthCheck"] => ({
 export const makeStorageServiceDocker = (opts: DockerStorageOptions): ServiceDef =>
   dockerRunService({
     name: "storage",
-    containerName: `supabase-storage-${opts.apiPort}`,
+    apiPort: opts.apiPort,
     image: opts.image,
-    networkArgs: opts.networkArgs,
+    networkArgs: dockerNetworkArgs(opts.platformOs, [opts.port]),
     volumes: [`${opts.dataDir}:${STORAGE_DATA_DIR}`],
     env: {
       PORT: String(opts.port),
@@ -75,7 +76,7 @@ export const makeStorageServiceDocker = (opts: DockerStorageOptions): ServiceDef
       UPLOAD_FILE_SIZE_LIMIT_STANDARD: "5242880000",
       SIGNED_UPLOAD_URL_EXPIRATION_TIME: "7200",
     },
-    dependsOn: opts.dependencies,
+    dependencies: opts.dependencies,
     healthCheck: storageHealthCheck(opts.port),
     orphanCleanup: orphanCleanup(opts),
   });
diff --git a/packages/stack/src/services/studio.ts b/packages/stack/src/services/studio.ts
index 4b139abc96..f84c24c6a8 100644
--- a/packages/stack/src/services/studio.ts
+++ b/packages/stack/src/services/studio.ts
@@ -1,4 +1,5 @@
 import type { ServiceDef } from "@supabase/process-compose";
+import { dockerNetworkArgs } from "../Platform.ts";
 import { dockerRunService, type ServiceDependency } from "./service-utils.ts";
 import { stackHealthBudgets } from "./health-budgets.ts";
 
@@ -18,7 +19,7 @@ interface DockerStudioOptions {
   readonly analyticsBackend: "postgres" | "bigquery";
   readonly analyticsUrl: string;
   readonly analyticsApiKey: string;
-  readonly networkArgs: ReadonlyArray<string>;
+  readonly platformOs: string;
   readonly dependencies: ReadonlyArray<ServiceDependency>;
 }
 
@@ -36,9 +37,9 @@ const studioHealthCheck = (port: number): ServiceDef["healthCheck"] => ({
 export const makeStudioServiceDocker = (opts: DockerStudioOptions): ServiceDef =>
   dockerRunService({
     name: "studio",
-    containerName: `supabase-studio-${opts.apiPort}`,
+    apiPort: opts.apiPort,
     image: opts.image,
-    networkArgs: opts.networkArgs,
+    networkArgs: dockerNetworkArgs(opts.platformOs, [opts.port]),
     env: {
       PORT: String(opts.port),
       CURRENT_CLI_VERSION: "local",
@@ -64,6 +65,6 @@ export const makeStudioServiceDocker = (opts: DockerStudioOptions): ServiceDef =
       PGRST_DB_EXTRA_SEARCH_PATH: "public,extensions",
       PGRST_DB_MAX_ROWS: "1000",
     },
-    dependsOn: opts.dependencies,
+    dependencies: opts.dependencies,
     healthCheck: studioHealthCheck(opts.port),
   });
diff --git a/packages/stack/src/services/vector.ts b/packages/stack/src/services/vector.ts
index 90aa557f04..c7b41c700a 100644
--- a/packages/stack/src/services/vector.ts
+++ b/packages/stack/src/services/vector.ts
@@ -1,4 +1,6 @@
 import { existsSync } from "node:fs";
+import { dockerContainerName } from "../CleanupTargets.ts";
+import { dockerNetworkArgs } from "../Platform.ts";
 import {
   dockerExecHealthCheck,
   dockerRunService,
@@ -12,7 +14,7 @@ interface DockerVectorOptions {
   readonly serviceHost: string;
   readonly analyticsPort: number;
   readonly analyticsApiKey: string;
-  readonly networkArgs: ReadonlyArray<string>;
+  readonly platformOs: string;
   readonly dependencies: ReadonlyArray<ServiceDependency>;
 }
 
@@ -40,7 +42,7 @@ sinks:
 `;
 
 export const makeVectorServiceDocker = (opts: DockerVectorOptions) => {
-  const containerName = `supabase-vector-${opts.apiPort}`;
+  const containerName = dockerContainerName("vector", opts.apiPort);
   const dockerSocket = process.env.DOCKER_HOST?.startsWith("unix://")
     ? process.env.DOCKER_HOST.slice("unix://".length)
     : "/var/run/docker.sock";
@@ -48,9 +50,9 @@ export const makeVectorServiceDocker = (opts: DockerVectorOptions) => {
 
   return dockerRunService({
     name: "vector",
-    containerName,
+    apiPort: opts.apiPort,
     image: opts.image,
-    networkArgs: opts.networkArgs,
+    networkArgs: dockerNetworkArgs(opts.platformOs, []),
     volumes,
     env: {
       DOCKER_HOST: "unix:///var/run/docker.sock",
@@ -62,7 +64,7 @@ export const makeVectorServiceDocker = (opts: DockerVectorOptions) => {
 ${VECTOR_CONFIG(opts.serviceHost, opts.analyticsPort, opts.analyticsApiKey)}EOF
 `,
     ],
-    dependsOn: opts.dependencies,
+    dependencies: opts.dependencies,
     healthCheck: dockerExecHealthCheck(
       containerName,
       "sh",

From b7a45d1d46a0915f8dad8d872ec3087d8d730abc Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 16:39:23 +0200
Subject: [PATCH 07/44] refactor(stack): make functions configuration explicit

---
 .../functions/dev/functions-dev-config.ts     |  93 +++++-
 .../dev/functions-dev-config.unit.test.ts     |  68 ++++-
 .../functions/dev/functions-dev-runtime.ts    |  19 +-
 packages/config/src/index.ts                  |   1 +
 packages/config/src/project.ts                |   9 +
 packages/stack/README.md                      |  29 ++
 packages/stack/docs/architecture.md           |  33 ++-
 packages/stack/docs/detach-mode.md            |   6 +
 packages/stack/package.json                   |   1 -
 .../src/DaemonServer.integration.test.ts      |  56 +++-
 packages/stack/src/DaemonServer.ts            |  27 +-
 packages/stack/src/LocalStack.ts              |  37 +--
 .../stack/src/RemoteStack.integration.test.ts |  43 ++-
 packages/stack/src/RemoteStack.ts             |  14 +-
 packages/stack/src/Stack.ts                   |  17 +-
 packages/stack/src/Stack.unit.test.ts         |  92 +++++-
 packages/stack/src/StackConfig.ts             |   6 +-
 packages/stack/src/StackConfigResolver.ts     |   8 +-
 packages/stack/src/createStack.ts             |   6 +-
 packages/stack/src/effect.ts                  |   9 +-
 packages/stack/src/functions.ts               | 266 +++++++-----------
 packages/stack/src/functions.unit.test.ts     | 199 ++++++-------
 packages/stack/src/index.ts                   |   7 +-
 .../stack/src/services/edge-runtime-main.ts   |   3 +-
 packages/stack/tests/createStack.e2e.test.ts  |  23 +-
 pnpm-lock.yaml                                |   3 -
 26 files changed, 680 insertions(+), 395 deletions(-)

diff --git a/apps/cli/src/next/commands/functions/dev/functions-dev-config.ts b/apps/cli/src/next/commands/functions/dev/functions-dev-config.ts
index 8cd70eb28f..144c71c390 100644
--- a/apps/cli/src/next/commands/functions/dev/functions-dev-config.ts
+++ b/apps/cli/src/next/commands/functions/dev/functions-dev-config.ts
@@ -1,6 +1,13 @@
-import { basename, dirname, resolve } from "node:path";
-import type { FunctionsConfig } from "@supabase/stack/effect";
-import { Effect, Option } from "effect";
+import {
+  inferFunctionsManifest,
+  loadDotEnvFile,
+  loadProjectConfig,
+  loadProjectEnvironment,
+  resolveProjectSubtree,
+} from "@supabase/config";
+import type { ResolvedFunctionsBundle } from "@supabase/stack/effect";
+import { Effect, Option, Redacted } from "effect";
+import { basename, dirname, join, resolve } from "node:path";
 import { ProjectHome } from "../../../config/project-home.service.ts";
 import { RuntimeInfo } from "../../../../shared/runtime/runtime-info.service.ts";
 
@@ -14,16 +21,80 @@ export interface FunctionsDevWatchPath {
   readonly names?: ReadonlyArray<string>;
 }
 
-export function toStackFunctionsConfig(opts: FunctionsDevConfigOptions): FunctionsConfig {
-  return {
-    envFile: Option.match(opts.envFile, {
-      onNone: () => undefined,
-      onSome: (path) => path,
-    }),
-    noVerifyJwt: opts.noVerifyJwt,
-  };
+function reveal(value: string | Redacted.Redacted<string>): string {
+  return Redacted.isRedacted(value) ? Redacted.value(value) : value;
+}
+
+function absoluteProjectPath(supabaseDir: string, path: string): string {
+  const withoutDotSlash = path.startsWith("./") ? path.slice(2) : path;
+  return resolve(supabaseDir, withoutDotSlash);
 }
 
+export const resolveFunctionsBundle = Effect.fnUntraced(function* (
+  opts: FunctionsDevConfigOptions,
+) {
+  const projectHome = yield* ProjectHome;
+  const runtimeInfo = yield* RuntimeInfo;
+  const projectEnvironment = yield* loadProjectEnvironment({
+    cwd: projectHome.projectRoot,
+    baseEnv: process.env,
+  });
+  const loadedConfig = yield* loadProjectConfig(projectHome.projectRoot);
+  const projectConfig =
+    projectEnvironment === null || loadedConfig === null
+      ? undefined
+      : {
+          ...loadedConfig.config,
+          functions: Object.fromEntries(
+            Object.entries(
+              yield* resolveProjectSubtree(
+                loadedConfig.config.functions,
+                projectEnvironment,
+                "functions",
+              ),
+            ).map(([name, config]) => [
+              name,
+              {
+                ...config,
+                entrypoint: reveal(config.entrypoint),
+                import_map: reveal(config.import_map),
+                static_files: config.static_files.map(reveal),
+                env: Object.fromEntries(
+                  Object.entries(config.env).map(([key, value]) => [key, reveal(value)]),
+                ),
+              },
+            ]),
+          ),
+        };
+  const manifest = yield* inferFunctionsManifest({
+    cwd: projectHome.projectRoot,
+    ...(projectConfig === undefined ? {} : { config: projectConfig }),
+  });
+  const envFilePath = Option.match(opts.envFile, {
+    onNone: () => join(projectHome.supabaseDir, "functions", ".env"),
+    onSome: (path) => resolve(runtimeInfo.cwd, path),
+  });
+
+  return {
+    env: yield* loadDotEnvFile(envFilePath),
+    functions: Object.entries(manifest)
+      .filter(([, config]) => config.enabled)
+      .map(([name, config]) => ({
+        name,
+        verifyJWT: opts.noVerifyJwt ? false : config.verify_jwt,
+        entrypointPath: absoluteProjectPath(projectHome.supabaseDir, config.entrypoint),
+        importMapPath:
+          config.import_map === ""
+            ? null
+            : absoluteProjectPath(projectHome.supabaseDir, config.import_map),
+        staticFiles: config.static_files.map((path) =>
+          absoluteProjectPath(projectHome.supabaseDir, path),
+        ),
+        env: config.env,
+      })),
+  } satisfies ResolvedFunctionsBundle;
+});
+
 export const functionsDevWatchPaths = Effect.fnUntraced(function* (envFile: Option.Option<string>) {
   const projectHome = yield* ProjectHome;
   const runtimeInfo = yield* RuntimeInfo;
diff --git a/apps/cli/src/next/commands/functions/dev/functions-dev-config.unit.test.ts b/apps/cli/src/next/commands/functions/dev/functions-dev-config.unit.test.ts
index 983a7a6a5e..6467afdc29 100644
--- a/apps/cli/src/next/commands/functions/dev/functions-dev-config.unit.test.ts
+++ b/apps/cli/src/next/commands/functions/dev/functions-dev-config.unit.test.ts
@@ -7,11 +7,7 @@ import { join } from "node:path";
 import { Effect, Exit, Layer, Option } from "effect";
 import { ProjectHome } from "../../../config/project-home.service.ts";
 import { RuntimeInfo } from "../../../../shared/runtime/runtime-info.service.ts";
-import {
-  functionsDevWatchPaths,
-  toStackFunctionsConfig,
-  type FunctionsDevConfigOptions,
-} from "./functions-dev-config.ts";
+import { functionsDevWatchPaths, resolveFunctionsBundle } from "./functions-dev-config.ts";
 import {
   FunctionsDevEdgeRuntimeDisabledError,
   resolveFunctionsDevEdgeRuntimeConfig,
@@ -61,16 +57,60 @@ describe("functions dev config", () => {
     expect(connectOrStartFunctionsDevStack).toBeTypeOf("function");
   });
 
-  it("converts CLI options to stack Functions config", () => {
-    const opts: FunctionsDevConfigOptions = {
-      envFile: Option.some("./custom.env"),
-      noVerifyJwt: true,
-    };
+  it.live("resolves project functions, environment and absolute paths before stack handoff", () => {
+    const cwd = makeTempProject();
+
+    return Effect.gen(function* () {
+      yield* Effect.tryPromise(() =>
+        mkdir(join(cwd, "supabase", "functions", "hello", "assets"), { recursive: true }),
+      );
+      yield* Effect.tryPromise(() =>
+        writeFile(join(cwd, "supabase", "functions", "hello", "index.ts"), "export {};\n"),
+      );
+      yield* Effect.tryPromise(() =>
+        writeFile(join(cwd, "supabase", "functions", "hello", "deno.json"), "{}\n"),
+      );
+      yield* Effect.tryPromise(() =>
+        writeFile(join(cwd, "supabase", ".env"), "FUNCTION_VALUE=resolved-secret\n"),
+      );
+      yield* Effect.tryPromise(() => writeFile(join(cwd, "custom.env"), "SHARED=custom\n"));
+      yield* Effect.tryPromise(() =>
+        writeFile(
+          join(cwd, "supabase", "config.toml"),
+          `[functions.hello]
+verify_jwt = true
+entrypoint = "./functions/hello/index.ts"
+import_map = "./functions/hello/deno.json"
+static_files = ["./functions/hello/assets/*"]
+
+[functions.hello.env]
+FUNCTION_VALUE = "env(FUNCTION_VALUE)"
+`,
+        ),
+      );
 
-    expect(toStackFunctionsConfig(opts)).toEqual({
-      envFile: "./custom.env",
-      noVerifyJwt: true,
-    });
+      const bundle = yield* resolveFunctionsBundle({
+        envFile: Option.some("./custom.env"),
+        noVerifyJwt: true,
+      });
+
+      expect(bundle).toEqual({
+        env: { SHARED: "custom" },
+        functions: [
+          {
+            name: "hello",
+            verifyJWT: false,
+            entrypointPath: join(cwd, "supabase", "functions", "hello", "index.ts"),
+            importMapPath: join(cwd, "supabase", "functions", "hello", "deno.json"),
+            staticFiles: [join(cwd, "supabase", "functions", "hello", "assets", "*")],
+            env: { FUNCTION_VALUE: "resolved-secret" },
+          },
+        ],
+      });
+    }).pipe(
+      Effect.ensuring(Effect.tryPromise(() => rm(cwd, { recursive: true, force: true }))),
+      Effect.provide(projectLayer(cwd)),
+    );
   });
 
   it.live("selects supabase and explicit env directory watch paths", () => {
diff --git a/apps/cli/src/next/commands/functions/dev/functions-dev-runtime.ts b/apps/cli/src/next/commands/functions/dev/functions-dev-runtime.ts
index c3a1e69722..0f73099841 100644
--- a/apps/cli/src/next/commands/functions/dev/functions-dev-runtime.ts
+++ b/apps/cli/src/next/commands/functions/dev/functions-dev-runtime.ts
@@ -30,7 +30,7 @@ import { RuntimeInfo } from "../../../../shared/runtime/runtime-info.service.ts"
 import { startStackWithProgress } from "../../../stack/stack.shared.ts";
 import {
   functionsDevWatchPaths,
-  toStackFunctionsConfig,
+  resolveFunctionsBundle,
   type FunctionsDevConfigOptions,
   type FunctionsDevWatchPath,
 } from "./functions-dev-config.ts";
@@ -76,7 +76,6 @@ const startFullStack = Effect.fnUntraced(function* (opts: FunctionsDevStackOptio
       projectStateRoot: projectHome.projectHomeDir,
       name: opts.stack,
       edgeRuntime: opts.edgeRuntime,
-      functions: toStackFunctionsConfig(opts),
       ...versionsFromContext(serviceVersionContext),
     },
     daemonEntryPoint,
@@ -180,9 +179,9 @@ function reloadEdgeRuntime(
   opts: FunctionsDevRuntimeOptions,
   edgeRuntime: EdgeRuntimeConfig,
 ) {
-  return stack.reloadEdgeRuntime({
-    edgeRuntime,
-    functions: toStackFunctionsConfig(opts),
+  return Effect.gen(function* () {
+    const functions = yield* resolveFunctionsBundle(opts);
+    yield* stack.reloadEdgeRuntime({ edgeRuntime, functions });
   });
 }
 
@@ -248,7 +247,7 @@ export const runFunctionsDevRuntime = Effect.fnUntraced(function* (
         }
         edgeRuntimeState = result.state;
         yield* output.info("Function files changed. Restarting edge-runtime...");
-        yield* stack.reloadFunctions(toStackFunctionsConfig(opts));
+        yield* stack.reloadFunctions({ functions: yield* resolveFunctionsBundle(opts) });
       }).pipe(
         Effect.catch((error) =>
           output.error(error instanceof Error ? error.message : String(error)),
@@ -266,9 +265,13 @@ export const runFunctionsDevRuntime = Effect.fnUntraced(function* (
         if (startedByCommand) {
           yield* stack.dispose().pipe(Effect.ignore);
         } else {
-          yield* stack.reloadFunctions({}).pipe(Effect.ignore);
+          const functions = yield* resolveFunctionsBundle({
+            envFile: Option.none(),
+            noVerifyJwt: false,
+          });
+          yield* stack.reloadFunctions({ functions }).pipe(Effect.ignore);
         }
-      }),
+      }).pipe(Effect.ignore),
     ),
   );
 });
diff --git a/packages/config/src/index.ts b/packages/config/src/index.ts
index 77af2064ae..61ee04dbdc 100644
--- a/packages/config/src/index.ts
+++ b/packages/config/src/index.ts
@@ -32,6 +32,7 @@ export {
   type ProjectEnvironment,
   type ResolvedProjectValue,
   type ResolveProjectOptions,
+  loadDotEnvFile,
   loadProjectEnvironment,
   resolveProjectSubtree,
   resolveProjectValue,
diff --git a/packages/config/src/project.ts b/packages/config/src/project.ts
index eb1def2642..28f4c5cd3a 100644
--- a/packages/config/src/project.ts
+++ b/packages/config/src/project.ts
@@ -166,6 +166,15 @@ function parseDotEnv(
   });
 }
 
+/** Parse one explicit dotenv file without applying ambient or project-local precedence. */
+export const loadDotEnvFile = Effect.fnUntraced(function* (path: string) {
+  const fs = yield* FileSystem.FileSystem;
+  if (!(yield* fs.exists(path))) {
+    return {};
+  }
+  return yield* parseDotEnv(path, yield* fs.readFileString(path));
+});
+
 function applySource(
   target: Record<string, string>,
   sources: Record<string, "ambient" | ".env" | ".env.local">,
diff --git a/packages/stack/README.md b/packages/stack/README.md
index 321d60d988..54140e751d 100644
--- a/packages/stack/README.md
+++ b/packages/stack/README.md
@@ -130,6 +130,35 @@ const stack = await createStack({
 });
 ```
 
+### Edge Functions
+
+The stack accepts an explicit, fully resolved Functions bundle. Paths must be absolute and the
+caller owns project-file discovery, environment-file parsing, and manifest interpretation:
+
+```typescript
+const stack = await createStack({
+  functions: {
+    env: { SHARED_VALUE: "available to every function" },
+    functions: [
+      {
+        name: "hello",
+        verifyJWT: true,
+        entrypointPath: "/absolute/project/supabase/functions/hello/index.ts",
+        importMapPath: null,
+        staticFiles: [],
+        env: { FUNCTION_VALUE: "available only to hello" },
+      },
+    ],
+  },
+});
+```
+
+Per-function environment values override shared values. Stack-owned runtime URLs and credentials
+take final precedence. To update the active bundle, call
+`reloadFunctions({ functions: nextBundle })`; `reloadFunctions()` preserves and reapplies the most
+recent bundle. `reloadEdgeRuntime()` follows the same preservation rule when its optional
+`functions` field is omitted.
+
 ## Docker Mode
 
 Set `mode: "docker"` to force all services to run in Docker containers, bypassing native binary resolution:
diff --git a/packages/stack/docs/architecture.md b/packages/stack/docs/architecture.md
index af52c3d3d7..7faf85e5e7 100644
--- a/packages/stack/docs/architecture.md
+++ b/packages/stack/docs/architecture.md
@@ -37,8 +37,9 @@ can use the same lifecycle calls against an in-process stack or a detached daemo
 ## Configuration and roots
 
 `StackConfig` is an in-memory library input, not the project configuration-file schema. Its
-top-level fields choose runtime mode, startup mode, cache/runtime roots, API keys, JWT secret,
-functions options, and per-service configuration. `false` disables an optional service.
+top-level fields choose runtime mode, startup mode, cache/runtime roots, API keys, JWT secret, a
+resolved Edge Functions bundle, and per-service configuration. `false` disables an optional
+service.
 
 `StackConfigResolver.resolveConfig()`:
 
@@ -188,15 +189,22 @@ Cleanup targets do not belong to `StackInfo`; they are internal runtime metadata
 
 ## Functions runtime configuration and reload
 
-The current `functions.ts` Implementation discovers project configuration and function manifests,
-resolves paths and environment values, combines them with stack URLs/keys, and writes
-`functions-runtime-config.json` under the Edge Runtime workspace. The Edge Runtime factory mounts
-or references that file.
+Project discovery is outside the stack boundary. A caller supplies a serializable
+`ResolvedFunctionsBundle` containing absolute entrypoint, optional import-map, and static-file
+paths plus already-resolved shared and per-function environment values. The import-map path is
+explicitly nullable. Per-function environment values override shared values; stack-owned runtime
+URLs and credentials take final precedence when the worker is created.
 
-`reloadFunctions()` rewrites the file and updates/restarts the Edge Runtime definition.
-`reloadEdgeRuntime()` can change runtime settings and optionally functions settings. In detached
-mode, `/functions/reload` currently carries `envFile` and `noVerifyJwt` as query parameters, while
-`/edge-runtime/reload` accepts a validated JSON body.
+`LocalStack` keeps the current bundle in runtime-local memory. `reloadFunctions({ functions })`
+replaces it, while a reload without `functions` preserves the latest bundle. An Edge Runtime reload
+uses that same current bundle unless its body supplies a replacement. The stack combines the
+bundle with runtime URLs and credentials, atomically publishes `functions-runtime-config.json`
+with owner-only permissions under the Edge Runtime workspace, and removes it on disposal.
+
+Detached stacks deliberately exclude resolved bundles from daemon startup IPC, durable metadata,
+live state, logs, URLs, and rendered validation errors. Both `/functions/reload` and
+`/edge-runtime/reload` accept validated JSON bodies over the local Unix socket. This keeps resolved
+environment values confined to an explicit request body and the ephemeral runtime file.
 
 ## Port leases
 
@@ -239,8 +247,9 @@ These paths overlap by design and must remain idempotent.
 Detached mode adds:
 
 - `daemonLayer()`: forks a runtime-specific daemon entrypoint and returns a `RemoteStack` layer;
-- `daemon.ts`: receives the configuration over Node IPC, resolves ports, builds the foreground
-  daemon layer, claims live state, and waits for HTTP stop or a signal;
+- `daemon.ts`: receives configuration excluding the resolved Functions bundle over Node IPC,
+  resolves ports, builds the foreground daemon layer, claims live state, and waits for HTTP stop or
+  a signal;
 - `DaemonServer`: exposes the `Stack` Interface over HTTP/SSE on a Unix-domain socket;
 - `RemoteStack`: maps that transport back to the same Effect `Stack` Interface;
 - `StateManager`: atomically persists and discovers durable metadata and live state.
diff --git a/packages/stack/docs/detach-mode.md b/packages/stack/docs/detach-mode.md
index e288a7e5a1..f1a1b6ecbd 100644
--- a/packages/stack/docs/detach-mode.md
+++ b/packages/stack/docs/detach-mode.md
@@ -125,6 +125,12 @@ failures use validated JSON shapes. `RemoteStack` decodes that transport back in
 `Stack` Interface used in foreground mode, including `ServiceNotFoundError`, `ServiceReadyError`,
 `StackBuildError`, and `StackReadinessError`.
 
+Functions and Edge Runtime reload routes also use validated JSON bodies. Resolved Functions
+bundles may contain environment values, so they are deliberately excluded from daemon startup IPC,
+query parameters, durable metadata, live state, logs, and rendered validation errors. The daemon
+keeps only the active bundle in memory and writes the derived Edge Runtime file ephemerally with
+owner-only permissions.
+
 The management socket is not the public local API endpoint. `ApiProxy` still owns the configured
 HTTP API port inside the daemon process.
 
diff --git a/packages/stack/package.json b/packages/stack/package.json
index 3582370c56..80161f67b9 100644
--- a/packages/stack/package.json
+++ b/packages/stack/package.json
@@ -22,7 +22,6 @@
   "dependencies": {
     "@effect/platform-bun": "catalog:",
     "@effect/platform-node": "catalog:",
-    "@supabase/config": "workspace:*",
     "@supabase/process-compose": "workspace:*",
     "effect": "catalog:"
   },
diff --git a/packages/stack/src/DaemonServer.integration.test.ts b/packages/stack/src/DaemonServer.integration.test.ts
index 1cb2227f68..d7d8664210 100644
--- a/packages/stack/src/DaemonServer.integration.test.ts
+++ b/packages/stack/src/DaemonServer.integration.test.ts
@@ -5,6 +5,7 @@ import * as http from "node:http";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { DaemonServer } from "./DaemonServer.ts";
 import { StackReadinessError } from "./errors.ts";
+import type { FunctionsReloadConfig, ResolvedFunctionsBundle } from "./functions.ts";
 import { Stack, type StackInfo } from "./Stack.ts";
 import { StackServiceState } from "./StackServiceState.ts";
 
@@ -57,6 +58,7 @@ const MOCK_LOGS: ReadonlyArray<LogEntry> = [
 function mockStack(options: { readonly startTimeoutMs?: number } = {}) {
   let stopped = false;
   const serviceCalls: string[] = [];
+  const functionReloads: FunctionsReloadConfig[] = [];
 
   const layer = Layer.succeed(Stack, {
     getInfo: () => Effect.succeed(MOCK_INFO),
@@ -96,8 +98,9 @@ function mockStack(options: { readonly startTimeoutMs?: number } = {}) {
         : Effect.sync(() => {
             serviceCalls.push(`restart:${name}`);
           }),
-    reloadFunctions: () =>
+    reloadFunctions: (config) =>
       Effect.sync(() => {
+        functionReloads.push(config ?? {});
         serviceCalls.push("reload-functions");
       }),
     reloadEdgeRuntime: () =>
@@ -142,9 +145,24 @@ function mockStack(options: { readonly startTimeoutMs?: number } = {}) {
       return stopped;
     },
     serviceCalls,
+    functionReloads,
   };
 }
 
+const functionsBundle: ResolvedFunctionsBundle = {
+  env: { SHARED_SECRET: "shared-secret-value" },
+  functions: [
+    {
+      name: "hello",
+      verifyJWT: false,
+      entrypointPath: "/project/supabase/functions/hello/index.ts",
+      importMapPath: null,
+      staticFiles: [],
+      env: { FUNCTION_SECRET: "function-secret-value" },
+    },
+  ],
+};
+
 // ---------------------------------------------------------------------------
 // Layer builder
 // ---------------------------------------------------------------------------
@@ -366,6 +384,42 @@ describe("DaemonServer", () => {
     expect(mock.serviceCalls).toContain("reload-edge-runtime");
   });
 
+  test("POST /functions/reload validates and forwards its JSON body", async () => {
+    const res = await fetch(`${url}/functions/reload`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ functions: functionsBundle }),
+    });
+
+    expect(res.status).toBe(200);
+    expect(mock.functionReloads).toContainEqual({ functions: functionsBundle });
+  });
+
+  test("reload validation never renders resolved environment values", async () => {
+    const secret = "must-not-appear-in-errors";
+    const res = await fetch(`${url}/functions/reload`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        functions: {
+          env: { SECRET: secret },
+          functions: [
+            {
+              ...functionsBundle.functions[0],
+              entrypointPath: "relative/index.ts",
+            },
+          ],
+        },
+      }),
+    });
+    const responseText = await res.text();
+
+    expect(res.status).toBe(400);
+    expect(responseText).toContain("Invalid Edge Functions reload payload");
+    expect(responseText).not.toContain(secret);
+    expect(responseText).not.toContain("relative/index.ts");
+  });
+
   // -------------------------------------------------------------------------
   // Error cases — service not found
   // -------------------------------------------------------------------------
diff --git a/packages/stack/src/DaemonServer.ts b/packages/stack/src/DaemonServer.ts
index 4900fcba8c..4fb874f8a5 100644
--- a/packages/stack/src/DaemonServer.ts
+++ b/packages/stack/src/DaemonServer.ts
@@ -8,6 +8,7 @@ import {
 } from "effect/unstable/http";
 import * as Sse from "effect/unstable/encoding/Sse";
 import type { DaemonErrorResponse } from "./DaemonProtocol.ts";
+import { FunctionsReloadConfigSchema } from "./functions.ts";
 import { EdgeRuntimeReloadConfigSchema, Stack } from "./Stack.ts";
 import { ReadyOptionsSchema } from "./StackConfig.ts";
 
@@ -51,6 +52,11 @@ export class DaemonServer extends Context.Service<
           );
         const buildErrorResponse = (detail: string) =>
           errorResponse({ code: "STACK_BUILD_ERROR", error: detail }, 500);
+        const invalidReloadPayloadResponse = () =>
+          HttpServerResponse.jsonUnsafe(
+            { error: "Invalid Edge Functions reload payload" },
+            { status: 400 },
+          );
         const readinessTimeoutResponse = (target: string, timeoutMs: number, detail: string) =>
           errorResponse(
             {
@@ -315,13 +321,14 @@ export class DaemonServer extends Context.Service<
             "POST",
             "/functions/reload",
             Effect.gen(function* () {
-              const searchParams = yield* HttpServerRequest.ParsedSearchParams;
-              yield* stack.reloadFunctions({
-                envFile: parseSingleParam(searchParams.envFile),
-                noVerifyJwt: parseBoolean(searchParams.noVerifyJwt),
-              });
+              const body = yield* HttpServerRequest.schemaBodyJson(FunctionsReloadConfigSchema);
+              yield* stack.reloadFunctions(body);
               return HttpServerResponse.jsonUnsafe({ ok: true });
             }).pipe(
+              Effect.catchTags({
+                SchemaError: () => Effect.succeed(invalidReloadPayloadResponse()),
+                HttpServerError: () => Effect.succeed(invalidReloadPayloadResponse()),
+              }),
               Effect.catchTag("ServiceNotFoundError", (e) =>
                 Effect.succeed(notFoundResponse(e.name)),
               ),
@@ -345,6 +352,10 @@ export class DaemonServer extends Context.Service<
               yield* stack.reloadEdgeRuntime(body);
               return HttpServerResponse.jsonUnsafe({ ok: true });
             }).pipe(
+              Effect.catchTags({
+                SchemaError: () => Effect.succeed(invalidReloadPayloadResponse()),
+                HttpServerError: () => Effect.succeed(invalidReloadPayloadResponse()),
+              }),
               Effect.catchTag("ServiceNotFoundError", (e) =>
                 Effect.succeed(notFoundResponse(e.name)),
               ),
@@ -393,9 +404,3 @@ function parseSingleParam(value: string | ReadonlyArray<string> | undefined): st
   if (value === undefined) return undefined;
   return typeof value === "string" ? value : value[0];
 }
-
-function parseBoolean(value: string | ReadonlyArray<string> | undefined): boolean | undefined {
-  const raw = parseSingleParam(value);
-  if (raw === undefined) return undefined;
-  return raw === "true";
-}
diff --git a/packages/stack/src/LocalStack.ts b/packages/stack/src/LocalStack.ts
index 39d33b0ad7..901ec079d2 100644
--- a/packages/stack/src/LocalStack.ts
+++ b/packages/stack/src/LocalStack.ts
@@ -19,7 +19,11 @@ import { ChildProcessSpawner } from "effect/unstable/process";
 import type { CleanupTargets } from "./CleanupTargets.ts";
 import { cleanupLocalStackResources } from "./cleanup.ts";
 import { StackBuildError, StackNotRunningError, StackReadinessError } from "./errors.ts";
-import { configureFunctionsRuntime, type FunctionsConfig } from "./functions.ts";
+import {
+  clearFunctionsRuntimeConfig,
+  configureFunctionsRuntime,
+  type ResolvedFunctionsBundle,
+} from "./functions.ts";
 import { detectPlatform, dockerHostAddress } from "./Platform.ts";
 import type { PortLease } from "./PortAllocator.ts";
 import {
@@ -168,6 +172,9 @@ export const localStackLayer = (
       const enabledServices = enabledServicesForConfig(config);
       const stateRef = yield* SubscriptionRef.make(initialPublicStates(config));
       const phaseRef = yield* Ref.make<LifecyclePhase>("idle");
+      const functionsBundleRef = yield* Ref.make<ResolvedFunctionsBundle | undefined>(
+        config.functions === false ? undefined : config.functions,
+      );
       const lifecycleLock = Semaphore.makeUnsafe(1);
 
       const logBufferServices = yield* Layer.buildWithScope(LogBuffer.layer, scope);
@@ -425,7 +432,8 @@ export const localStackLayer = (
         nextConfig: ResolvedStackConfig,
       ): Effect.Effect<void, StackBuildError> =>
         Effect.gen(function* () {
-          yield* providePlatform(configureFunctionsRuntime(nextConfig, yield* runtimeHost));
+          const bundle = yield* Ref.get(functionsBundleRef);
+          yield* providePlatform(configureFunctionsRuntime(nextConfig, yield* runtimeHost, bundle));
         }).pipe(
           Effect.mapError(
             (cause) =>
@@ -435,19 +443,6 @@ export const localStackLayer = (
               }),
           ),
         );
-      const configWithFunctionOptions = (opts?: FunctionsConfig): ResolvedStackConfig => {
-        if (opts === undefined) {
-          return config;
-        }
-        const base = config.functions === false ? { noVerifyJwt: false } : config.functions;
-        return {
-          ...config,
-          functions: {
-            envFile: opts.envFile ?? base.envFile,
-            noVerifyJwt: opts.noVerifyJwt ?? base.noVerifyJwt,
-          },
-        };
-      };
       const configWithEdgeRuntimeOptions = (
         opts: EdgeRuntimeReloadConfig,
       ): Effect.Effect<ResolvedStackConfig, ServiceNotFoundError> =>
@@ -456,9 +451,8 @@ export const localStackLayer = (
             return yield* Effect.fail(new ServiceNotFoundError({ name: "edge-runtime" }));
           }
 
-          const base = configWithFunctionOptions(opts.functions);
           return {
-            ...base,
+            ...config,
             edgeRuntime: {
               ...config.edgeRuntime,
               enabled: opts.edgeRuntime.enabled ?? config.edgeRuntime.enabled,
@@ -608,6 +602,7 @@ export const localStackLayer = (
             cleanupTargets: exactCleanupTargets ?? { dockerContainerNames: [] },
             config,
           }).pipe(
+            Effect.ensuring(providePlatform(clearFunctionsRuntimeConfig(config.runtimeRoot))),
             Effect.ensuring(portLease.releaseAll),
             Effect.ensuring(Ref.set(phaseRef, "disposed")),
           );
@@ -781,7 +776,10 @@ export const localStackLayer = (
             const started = yield* Effect.gen(function* () {
               yield* requireMutable("reload functions");
               yield* requireKnownService("edge-runtime");
-              yield* configureFunctions(configWithFunctionOptions(opts));
+              if (opts?.functions !== undefined) {
+                yield* Ref.set(functionsBundleRef, opts.functions);
+              }
+              yield* configureFunctions(config);
               const runtime = yield* ensureRuntime;
               const state = yield* runtime.orchestrator.getState("edge-runtime");
               if (state.desired !== "running") {
@@ -801,6 +799,9 @@ export const localStackLayer = (
               yield* requireMutable("reload Edge Runtime");
               yield* requireKnownService("edge-runtime");
               const nextConfig = yield* configWithEdgeRuntimeOptions(opts);
+              if (opts.functions !== undefined) {
+                yield* Ref.set(functionsBundleRef, opts.functions);
+              }
               const prepared = yield* ensurePrepared;
               const runtime = yield* ensureRuntime;
               const buildResult = yield* builder.build(nextConfig, prepared);
diff --git a/packages/stack/src/RemoteStack.integration.test.ts b/packages/stack/src/RemoteStack.integration.test.ts
index 43930a1a2a..289d3cf64e 100644
--- a/packages/stack/src/RemoteStack.integration.test.ts
+++ b/packages/stack/src/RemoteStack.integration.test.ts
@@ -5,8 +5,9 @@ import * as http from "node:http";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { DaemonServer } from "./DaemonServer.ts";
 import { StackBuildError, StackReadinessError } from "./errors.ts";
+import type { FunctionsReloadConfig, ResolvedFunctionsBundle } from "./functions.ts";
 import { RemoteStack } from "./RemoteStack.ts";
-import { Stack, type StackInfo } from "./Stack.ts";
+import { Stack, type EdgeRuntimeReloadConfig, type StackInfo } from "./Stack.ts";
 import type { ReadyOptions } from "./StackConfig.ts";
 import { StackServiceState } from "./StackServiceState.ts";
 import { UnixHttpClient, UnixHttpClientError } from "./UnixHttpClient.ts";
@@ -82,6 +83,8 @@ function mockStack(
 ) {
   let stopped = false;
   const serviceCalls: string[] = [];
+  const functionReloads: FunctionsReloadConfig[] = [];
+  const edgeRuntimeReloads: EdgeRuntimeReloadConfig[] = [];
   const readinessCalls: Array<{ readonly target: string; readonly options?: ReadyOptions }> = [];
 
   const layer = Layer.succeed(Stack, {
@@ -129,12 +132,14 @@ function mockStack(
           : Effect.sync(() => {
               serviceCalls.push(`restart:${name}`);
             }),
-    reloadFunctions: () =>
+    reloadFunctions: (config) =>
       Effect.sync(() => {
+        functionReloads.push(config ?? {});
         serviceCalls.push("reload-functions");
       }),
-    reloadEdgeRuntime: () =>
+    reloadEdgeRuntime: (config) =>
       Effect.sync(() => {
+        edgeRuntimeReloads.push(config);
         serviceCalls.push("reload-edge-runtime");
       }),
     getState: (name: string) => {
@@ -200,9 +205,25 @@ function mockStack(
     },
     serviceCalls,
     readinessCalls,
+    functionReloads,
+    edgeRuntimeReloads,
   };
 }
 
+const functionsBundle: ResolvedFunctionsBundle = {
+  env: { SHARED_SECRET: "shared-secret-value" },
+  functions: [
+    {
+      name: "hello",
+      verifyJWT: false,
+      entrypointPath: "/project/supabase/functions/hello/index.ts",
+      importMapPath: null,
+      staticFiles: [],
+      env: { FUNCTION_SECRET: "function-secret-value" },
+    },
+  ],
+};
+
 // ---------------------------------------------------------------------------
 // Layer builder — DaemonServer backed by mock Stack on TCP port
 // ---------------------------------------------------------------------------
@@ -467,13 +488,27 @@ describe("RemoteStack integration", () => {
     expect(mock.serviceCalls).toContain("restart:postgres");
   });
 
+  test("reloadFunctions transports the validated bundle in a JSON body", async () => {
+    await clientRuntime.runPromise(
+      Effect.flatMap(Stack, (stack) => stack.reloadFunctions({ functions: functionsBundle })),
+    );
+
+    expect(mock.functionReloads).toEqual([{ functions: functionsBundle }]);
+  });
+
   test("reloadEdgeRuntime records the call", async () => {
     await clientRuntime.runPromise(
       Effect.flatMap(Stack, (stack) =>
-        stack.reloadEdgeRuntime({ edgeRuntime: { policy: "oneshot" } }),
+        stack.reloadEdgeRuntime({
+          edgeRuntime: { policy: "oneshot" },
+          functions: functionsBundle,
+        }),
       ),
     );
     expect(mock.serviceCalls).toContain("reload-edge-runtime");
+    expect(mock.edgeRuntimeReloads).toEqual([
+      { edgeRuntime: { policy: "oneshot" }, functions: functionsBundle },
+    ]);
   });
 
   test("logHistory returns entries", async () => {
diff --git a/packages/stack/src/RemoteStack.ts b/packages/stack/src/RemoteStack.ts
index dd0f8ca6a4..7bbd6fb72a 100644
--- a/packages/stack/src/RemoteStack.ts
+++ b/packages/stack/src/RemoteStack.ts
@@ -337,15 +337,11 @@ export const RemoteStack = {
           reloadFunctions: (opts) =>
             withUnixHttpClient(
               Effect.gen(function* () {
-                const response = yield* unixResponse(
-                  socketPath,
-                  `/functions/reload${encodeSearchParams({
-                    envFile: opts?.envFile,
-                    noVerifyJwt:
-                      opts?.noVerifyJwt === undefined ? undefined : String(opts.noVerifyJwt),
-                  })}`,
-                  { method: "POST" },
-                );
+                const response = yield* unixResponse(socketPath, "/functions/reload", {
+                  method: "POST",
+                  headers: { "content-type": "application/json" },
+                  body: JSON.stringify(opts ?? {}),
+                });
                 yield* expectDaemonOk(response, "edge-runtime");
               }),
             ),
diff --git a/packages/stack/src/Stack.ts b/packages/stack/src/Stack.ts
index 6d07355597..9693b08d02 100644
--- a/packages/stack/src/Stack.ts
+++ b/packages/stack/src/Stack.ts
@@ -2,7 +2,11 @@ import { ServiceNotFoundError } from "@supabase/process-compose";
 import type { LogEntry, ServiceReadyError } from "@supabase/process-compose";
 import { Context, Effect, Schema, Stream } from "effect";
 import { StackBuildError, StackReadinessError } from "./errors.ts";
-import type { FunctionsConfig } from "./functions.ts";
+import {
+  ResolvedFunctionsBundleSchema,
+  type FunctionsReloadConfig,
+  type ResolvedFunctionsBundle,
+} from "./functions.ts";
 import type { EdgeRuntimeConfig, ReadyOptions } from "./StackConfig.ts";
 import { StackServiceState } from "./StackServiceState.ts";
 
@@ -33,19 +37,14 @@ const EdgeRuntimeConfigSchema = Schema.Struct({
   env: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
 });
 
-const FunctionsConfigSchema = Schema.Struct({
-  envFile: Schema.optionalKey(Schema.String),
-  noVerifyJwt: Schema.optionalKey(Schema.Boolean),
-});
-
 export const EdgeRuntimeReloadConfigSchema = Schema.Struct({
   edgeRuntime: EdgeRuntimeConfigSchema,
-  functions: Schema.optionalKey(FunctionsConfigSchema),
+  functions: Schema.optionalKey(ResolvedFunctionsBundleSchema),
 });
 
 export interface EdgeRuntimeReloadConfig {
   readonly edgeRuntime: EdgeRuntimeConfig;
-  readonly functions?: FunctionsConfig;
+  readonly functions?: ResolvedFunctionsBundle;
 }
 
 export class Stack extends Context.Service<
@@ -74,7 +73,7 @@ export class Stack extends Context.Service<
       ServiceNotFoundError | ServiceReadyError | StackBuildError | StackReadinessError
     >;
     readonly reloadFunctions: (
-      opts?: FunctionsConfig,
+      opts?: FunctionsReloadConfig,
     ) => Effect.Effect<
       void,
       ServiceNotFoundError | ServiceReadyError | StackBuildError | StackReadinessError
diff --git a/packages/stack/src/Stack.unit.test.ts b/packages/stack/src/Stack.unit.test.ts
index c77a5fc9cf..afbfff3c05 100644
--- a/packages/stack/src/Stack.unit.test.ts
+++ b/packages/stack/src/Stack.unit.test.ts
@@ -2,10 +2,15 @@ import { describe, expect, it } from "@effect/vitest";
 import { BunServices } from "@effect/platform-bun";
 import { buildGraph } from "@supabase/process-compose";
 import { createHmac } from "node:crypto";
+import { mkdtempSync } from "node:fs";
+import { readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { Deferred, Effect, Exit, Fiber, Layer, Stream } from "effect";
 import { mockChildProcessSpawner } from "../../process-compose/tests/helpers/mocks.ts";
 import { mockBinaryResolver } from "../tests/helpers/mocks.ts";
 import { defaultPublishableKey, defaultSecretKey, generateJwt } from "./JwtGenerator.ts";
+import { functionsRuntimeConfigPath, type ResolvedFunctionsBundle } from "./functions.ts";
 import type { AllocatedPorts, PortField, PortLease } from "./PortAllocator.ts";
 import { StackServiceActivator } from "./ServiceActivation.ts";
 import { Stack } from "./Stack.ts";
@@ -103,6 +108,20 @@ const edgeRuntimeConfig: ResolvedStackConfig = {
   },
 };
 
+const functionsBundle = (root: string, value: string): ResolvedFunctionsBundle => ({
+  env: { SHARED: value },
+  functions: [
+    {
+      name: "hello",
+      verifyJWT: false,
+      entrypointPath: join(root, "hello", "index.ts"),
+      importMapPath: null,
+      staticFiles: [],
+      env: { FUNCTION_VALUE: value },
+    },
+  ],
+});
+
 const noopPortLease = (ports: AllocatedPorts): PortLease => ({
   ports,
   reserve: () => Effect.void,
@@ -155,6 +174,75 @@ describe("Stack", () => {
     }).pipe(Effect.provide(layer));
   });
 
+  it.live("preserves the current functions bundle across repeated runtime reloads", () => {
+    const runtimeRoot = mkdtempSync(join(tmpdir(), "supabase-functions-reload-"));
+    const initialBundle = functionsBundle(runtimeRoot, "initial-secret");
+    const replacementBundle = functionsBundle(runtimeRoot, "replacement-secret");
+    const config = {
+      ...edgeRuntimeConfig,
+      runtimeRoot,
+      functions: initialBundle,
+    } satisfies ResolvedStackConfig;
+    const graph = Effect.runSync(
+      buildGraph([
+        {
+          name: "edge-runtime",
+          command: process.execPath,
+          restart: "unless-stopped",
+        },
+      ]),
+    );
+    const builderLayer = Layer.succeed(StackBuilder, {
+      build: () =>
+        Effect.succeed({
+          graph,
+          cleanupTargets: { dockerContainerNames: [] },
+          serviceProjection: new Map([["edge-runtime", { visibility: "public" as const }]]),
+        }),
+    });
+    const resolver = mockBinaryResolver();
+    const layer = localStackLayer(config, noopPortLease(config.ports)).pipe(
+      Layer.provide(builderLayer),
+      Layer.provide(StackPreparation.layer.pipe(Layer.provide(resolver.layer))),
+      Layer.provide(StackMetadataPersistence.noop),
+      Layer.provide(mockChildProcessSpawner().layer),
+      Layer.provide(BunServices.layer),
+    );
+    const readRuntimeConfig = Effect.promise(() =>
+      readFile(functionsRuntimeConfigPath(runtimeRoot), "utf8").then((contents) =>
+        JSON.parse(contents),
+      ),
+    );
+
+    return Effect.gen(function* () {
+      const stack = yield* Stack;
+      yield* stack.start();
+
+      yield* stack.reloadFunctions({ functions: replacementBundle });
+      expect((yield* readRuntimeConfig).env.SHARED).toBe("replacement-secret");
+
+      yield* stack.reloadEdgeRuntime({ edgeRuntime: { policy: "oneshot" } });
+      expect((yield* readRuntimeConfig).env.SHARED).toBe("replacement-secret");
+
+      yield* stack.reloadFunctions();
+      expect((yield* readRuntimeConfig).env.SHARED).toBe("replacement-secret");
+
+      yield* stack.dispose();
+      expect(
+        yield* Effect.promise(() =>
+          readFile(functionsRuntimeConfigPath(runtimeRoot), "utf8").then(
+            () => true,
+            () => false,
+          ),
+        ),
+      ).toBe(false);
+    }).pipe(
+      Effect.provide(layer),
+      Effect.ensuring(Effect.promise(() => rm(runtimeRoot, { recursive: true, force: true }))),
+      Effect.timeout("5 seconds"),
+    );
+  });
+
   it.effect("getInfo returns valid JWT tokens", () => {
     const { layer } = setupLayer();
 
@@ -715,7 +803,7 @@ describe("Stack", () => {
       const config = {
         ...defaultConfig,
         startupMode: "lazy",
-        readiness: { mode: "finite", timeoutMs: 250 },
+        readiness: { mode: "finite", timeoutMs: 1_000 },
       } satisfies ResolvedStackConfig;
       const lease: PortLease = {
         ...noopPortLease(config.ports),
@@ -735,7 +823,7 @@ describe("Stack", () => {
         expect(error._tag).toBe("StackReadinessError");
         if (error._tag === "StackReadinessError") {
           expect(error.target).toBe("auth");
-          expect(error.timeoutMs).toBe(250);
+          expect(error.timeoutMs).toBe(1_000);
         }
         expect(releasedAll).toBe(true);
         const spawnCountAfterDisposal = spawner.spawned.length;
diff --git a/packages/stack/src/StackConfig.ts b/packages/stack/src/StackConfig.ts
index 32d1251225..a4ca22de89 100644
--- a/packages/stack/src/StackConfig.ts
+++ b/packages/stack/src/StackConfig.ts
@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-import type { FunctionsConfig, ResolvedFunctionsConfig } from "./functions.ts";
+import type { ResolvedFunctionsBundle } from "./functions.ts";
 import type { AllocatedPorts } from "./PortAllocator.ts";
 
 type StackMode = "native" | "auto" | "docker";
@@ -159,7 +159,7 @@ export interface StackConfig {
   readonly port?: number;
   readonly publishableKey?: string;
   readonly secretKey?: string;
-  readonly functions?: FunctionsConfig | false;
+  readonly functions?: ResolvedFunctionsBundle | false;
   readonly postgres?: PostgresConfig;
   readonly postgrest?: PostgrestConfig | false;
   readonly auth?: AuthConfig | false;
@@ -287,7 +287,7 @@ export interface ResolvedStackConfig {
   readonly dbPort: number;
   readonly publishableKey: string;
   readonly secretKey: string;
-  readonly functions: ResolvedFunctionsConfig | false;
+  readonly functions: ResolvedFunctionsBundle | false;
   readonly autoManagedPaths: ReadonlyArray<string>;
   readonly anonJwt: string;
   readonly serviceRoleJwt: string;
diff --git a/packages/stack/src/StackConfigResolver.ts b/packages/stack/src/StackConfigResolver.ts
index 88cd888abf..84bc42bc79 100644
--- a/packages/stack/src/StackConfigResolver.ts
+++ b/packages/stack/src/StackConfigResolver.ts
@@ -298,11 +298,7 @@ function resolveEdgeRuntimeConfig(
 }
 
 function resolveFunctionsConfig(config: StackConfig) {
-  if (config.functions === false) return false;
-  return {
-    envFile: config.functions?.envFile,
-    noVerifyJwt: config.functions?.noVerifyJwt ?? false,
-  };
+  return config.functions ?? false;
 }
 
 function resolveStorageConfig(
@@ -553,7 +549,7 @@ export async function resolveConfig(
   };
 }
 
-export type DaemonConfigInput = StackConfig & {
+export type DaemonConfigInput = Omit<StackConfig, "functions"> & {
   readonly cwd: string;
   readonly name?: string;
   readonly projectDir?: string;
diff --git a/packages/stack/src/createStack.ts b/packages/stack/src/createStack.ts
index f75f6bf66d..fc89fb2edb 100644
--- a/packages/stack/src/createStack.ts
+++ b/packages/stack/src/createStack.ts
@@ -5,7 +5,7 @@ import { HttpServer } from "effect/unstable/http";
 import { ChildProcessSpawner } from "effect/unstable/process";
 import { candidateCleanupTargets, cleanupAutoManagedPaths, dockerForceRemove } from "./cleanup.ts";
 import { toStackError } from "./errors.ts";
-import type { FunctionsConfig } from "./functions.ts";
+import type { FunctionsReloadConfig } from "./functions.ts";
 import { daemonLayer, foregroundLayer, type DaemonStartError } from "./layers.ts";
 import { PORT_FIELDS, reservePorts, type PortLease } from "./PortAllocator.ts";
 import { allocatedPortFieldsForConfig } from "./ServicePorts.ts";
@@ -43,7 +43,7 @@ export interface StackHandle extends AsyncDisposable {
   startService(name: string): Promise<void>;
   stopService(name: string): Promise<void>;
   restartService(name: string): Promise<void>;
-  reloadFunctions(opts?: FunctionsConfig): Promise<void>;
+  reloadFunctions(opts?: FunctionsReloadConfig): Promise<void>;
   reloadEdgeRuntime(opts: EdgeRuntimeReloadConfig): Promise<void>;
   ready(opts?: ReadyOptions): Promise<void>;
   serviceReady(name: string, opts?: ReadyOptions): Promise<void>;
@@ -62,7 +62,7 @@ export const projectDaemonLayer = (opts: {
   readonly projectStateRoot?: string;
   readonly name?: string;
   readonly daemonEntryPoint: string;
-  readonly stackConfig?: Omit<StackConfig, "cacheRoot" | "stackRoot" | "runtimeRoot">;
+  readonly stackConfig?: Omit<StackConfig, "cacheRoot" | "stackRoot" | "runtimeRoot" | "functions">;
 }): Effect.Effect<
   Layer.Layer<Stack>,
   DaemonStartError | InvalidStackStateError | StackAlreadyRunningError,
diff --git a/packages/stack/src/effect.ts b/packages/stack/src/effect.ts
index e757aaeb58..6a15a5c76d 100644
--- a/packages/stack/src/effect.ts
+++ b/packages/stack/src/effect.ts
@@ -97,14 +97,19 @@ export { StackBuilder } from "./StackBuilder.ts";
 export type { EdgeRuntimeReloadConfig, StackInfo } from "./Stack.ts";
 export { EdgeRuntimeReloadConfigSchema, Stack } from "./Stack.ts";
 export type {
-  FunctionsConfig,
+  FunctionsReloadConfig,
   FunctionsRuntimeConfig,
-  ResolvedFunctionsConfig,
+  ResolvedFunction,
+  ResolvedFunctionsBundle,
 } from "./functions.ts";
 export {
+  clearFunctionsRuntimeConfig,
   configureFunctionsRuntime,
+  FunctionsReloadConfigSchema,
   functionsRuntimeConfigFileName,
   functionsRuntimeConfigPath,
+  ResolvedFunctionSchema,
+  ResolvedFunctionsBundleSchema,
   resolveFunctionsRuntimeConfig,
 } from "./functions.ts";
 
diff --git a/packages/stack/src/functions.ts b/packages/stack/src/functions.ts
index fd95607f93..bcf5c1648e 100644
--- a/packages/stack/src/functions.ts
+++ b/packages/stack/src/functions.ts
@@ -1,24 +1,66 @@
-import { readFileSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
-import {
-  inferFunctionsManifest,
-  loadProjectConfig,
-  loadProjectEnvironment,
-  resolveProjectSubtree,
-  type ResolvedFunctionConfig,
-} from "@supabase/config";
-import { Effect, FileSystem, Path, Redacted } from "effect";
+import { isAbsolute, join } from "node:path";
+import { Effect, FileSystem, Path, Schema } from "effect";
 import type { ResolvedStackConfig } from "./StackConfig.ts";
 
-export interface FunctionsConfig {
-  readonly envFile?: string;
-  readonly noVerifyJwt?: boolean;
-}
+const absolutePath = Schema.String.check(
+  Schema.makeFilter((value) =>
+    isAbsolute(value) ? undefined : { path: [], issue: "Expected an absolute path" },
+  ),
+);
+
+const environment = Schema.Record(Schema.String, Schema.String);
+
+export const ResolvedFunctionSchema = Schema.Struct({
+  name: Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_-]+$/)),
+  verifyJWT: Schema.Boolean,
+  entrypointPath: absolutePath,
+  importMapPath: Schema.NullOr(absolutePath),
+  staticFiles: Schema.Array(absolutePath),
+  env: environment,
+});
 
-export interface ResolvedFunctionsConfig {
-  readonly envFile?: string;
-  readonly noVerifyJwt: boolean;
-}
+export interface ResolvedFunction extends Schema.Schema.Type<typeof ResolvedFunctionSchema> {}
+
+/**
+ * Project-owned Edge Functions input. Every path and environment reference is
+ * resolved before the bundle crosses into the stack package.
+ *
+ * `env` contains values shared by every function. A function's own `env`
+ * overrides matching shared values when its worker is created.
+ */
+export const ResolvedFunctionsBundleSchema = Schema.Struct({
+  env: environment,
+  functions: Schema.Array(ResolvedFunctionSchema),
+}).check(
+  Schema.makeFilter((bundle) => {
+    const names = new Set<string>();
+    for (let index = 0; index < bundle.functions.length; index += 1) {
+      const name = bundle.functions[index]?.name;
+      if (name !== undefined && names.has(name)) {
+        return {
+          path: ["functions", index, "name"],
+          issue: `Duplicate function name: ${name}`,
+        };
+      }
+      if (name !== undefined) {
+        names.add(name);
+      }
+    }
+    return undefined;
+  }),
+);
+
+export interface ResolvedFunctionsBundle extends Schema.Schema.Type<
+  typeof ResolvedFunctionsBundleSchema
+> {}
+
+export const FunctionsReloadConfigSchema = Schema.Struct({
+  functions: Schema.optionalKey(ResolvedFunctionsBundleSchema),
+});
+
+export interface FunctionsReloadConfig extends Schema.Schema.Type<
+  typeof FunctionsReloadConfigSchema
+> {}
 
 export interface FunctionsRuntimeConfig {
   readonly functionsUrl: string;
@@ -34,8 +76,9 @@ export interface FunctionsRuntimeConfig {
       {
         readonly verifyJWT: boolean;
         readonly entrypointPath: string;
-        readonly importMapPath: string;
+        readonly importMapPath: string | null;
         readonly staticFiles: ReadonlyArray<string>;
+        readonly env: Readonly<Record<string, string>>;
       }
     >
   >;
@@ -55,142 +98,15 @@ export function functionsRuntimeConfigPath(runtimeRoot: string): string {
   return join(edgeRuntimeWorkspaceDir(runtimeRoot), functionsRuntimeConfigFileName);
 }
 
-function reveal(value: string | Redacted.Redacted<string>): string {
-  return Redacted.isRedacted(value) ? Redacted.value(value) : value;
-}
-
-function absolutizeProjectPath(projectDir: string, relativePath: string): string {
-  if (relativePath.length === 0) {
-    return "";
-  }
-
-  const withoutDotSlash = relativePath.startsWith("./") ? relativePath.slice(2) : relativePath;
-  return isAbsolute(withoutDotSlash)
-    ? withoutDotSlash
-    : join(projectDir, "supabase", withoutDotSlash);
-}
-
-function parseDotEnv(contents: string): Record<string, string> {
-  const env: Record<string, string> = {};
-  const lines = contents.replace(/\r\n?/g, "\n").split("\n");
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (trimmed === "" || trimmed.startsWith("#")) {
-      continue;
-    }
-
-    const equals = line.indexOf("=");
-    if (equals === -1) {
-      continue;
-    }
-
-    const key = line
-      .slice(0, equals)
-      .trim()
-      .replace(/^export\s+/, "");
-    let value = line.slice(equals + 1).trim();
-    const quote = value[0];
-    if (
-      (quote === '"' || quote === "'" || quote === "`") &&
-      value.endsWith(quote) &&
-      value.length >= 2
-    ) {
-      value = value.slice(1, -1);
-    }
-    if (quote === '"') {
-      value = value.replace(/\\n/g, "\n").replace(/\\r/g, "\r");
-    }
-    env[key] = value;
-  }
-
-  return env;
-}
-
-function loadEnvFile(path: string): Record<string, string> {
-  try {
-    return parseDotEnv(readFileSync(path, "utf8"));
-  } catch {
-    return {};
-  }
-}
-
-const resolveFunctionsProjectConfig = Effect.fnUntraced(function* (projectDir: string) {
-  const projectEnv = yield* loadProjectEnvironment({ cwd: projectDir, baseEnv: process.env });
-  const loadedConfig = yield* loadProjectConfig(projectDir);
-  if (projectEnv === null || loadedConfig === null) {
-    return undefined;
-  }
-
-  const resolvedFunctions = yield* resolveProjectSubtree(
-    loadedConfig.config.functions,
-    projectEnv,
-    "functions",
-  );
-
-  return {
-    ...loadedConfig.config,
-    functions: Object.fromEntries(
-      Object.entries(resolvedFunctions).map(([slug, config]) => [
-        slug,
-        {
-          ...config,
-          entrypoint: reveal(config.entrypoint),
-          import_map: reveal(config.import_map),
-          static_files: config.static_files.map((path) => reveal(path)),
-          env: Object.fromEntries(
-            Object.entries(config.env).map(([name, value]) => [name, reveal(value)]),
-          ),
-        },
-      ]),
-    ),
-  };
-});
-
-function functionToRuntimeConfig(
-  projectDir: string,
-  noVerifyJwt: boolean,
-  config: ResolvedFunctionConfig,
-) {
-  return {
-    verifyJWT: noVerifyJwt ? false : config.verify_jwt,
-    entrypointPath: absolutizeProjectPath(projectDir, config.entrypoint),
-    importMapPath: absolutizeProjectPath(projectDir, config.import_map),
-    staticFiles: config.static_files.map((path) => absolutizeProjectPath(projectDir, path)),
-  };
-}
-
-export const resolveFunctionsRuntimeConfig = Effect.fnUntraced(function* (
+export function resolveFunctionsRuntimeConfig(
   stackConfig: ResolvedStackConfig,
   runtimeHost: FunctionsRuntimeHost,
-) {
-  const functionsConfig = stackConfig.functions;
-  if (functionsConfig === false || stackConfig.edgeRuntime === false) {
-    return undefined;
-  }
-
-  const projectConfig = yield* resolveFunctionsProjectConfig(stackConfig.projectDir);
-  const manifest = yield* inferFunctionsManifest({
-    cwd: stackConfig.projectDir,
-    ...(projectConfig === undefined ? {} : { config: projectConfig }),
-  });
-  const enabledManifest = Object.entries(manifest).filter(([, config]) => config.enabled);
-  if (enabledManifest.length === 0) {
+  bundle: ResolvedFunctionsBundle | undefined,
+): FunctionsRuntimeConfig | undefined {
+  if (bundle === undefined || bundle.functions.length === 0 || stackConfig.edgeRuntime === false) {
     return undefined;
   }
 
-  const functionEnv = Object.fromEntries(
-    enabledManifest.flatMap(([, config]) => Object.entries(config.env)),
-  );
-  const envFilePath =
-    functionsConfig.envFile === undefined
-      ? join(stackConfig.projectDir, "supabase", "functions", ".env")
-      : resolve(stackConfig.projectDir, functionsConfig.envFile);
-  const env = {
-    ...loadEnvFile(envFilePath),
-    ...functionEnv,
-  };
-
   return {
     functionsUrl: `http://127.0.0.1:${stackConfig.apiPort}/functions/v1`,
     supabaseUrl: `http://${runtimeHost.hostname}:${stackConfig.apiPort}`,
@@ -198,15 +114,21 @@ export const resolveFunctionsRuntimeConfig = Effect.fnUntraced(function* (
     publishableKey: stackConfig.publishableKey,
     secretKey: stackConfig.secretKey,
     jwtSecret: stackConfig.jwtSecret,
-    env,
+    env: bundle.env,
     functions: Object.fromEntries(
-      enabledManifest.map(([slug, config]) => [
-        slug,
-        functionToRuntimeConfig(stackConfig.projectDir, functionsConfig.noVerifyJwt, config),
+      bundle.functions.map((fn) => [
+        fn.name,
+        {
+          verifyJWT: fn.verifyJWT,
+          entrypointPath: fn.entrypointPath,
+          importMapPath: fn.importMapPath,
+          staticFiles: fn.staticFiles,
+          env: fn.env,
+        },
       ]),
     ),
-  } satisfies FunctionsRuntimeConfig;
-});
+  };
+}
 
 const writeFunctionsRuntimeConfig = Effect.fnUntraced(function* (
   runtimeRoot: string,
@@ -215,20 +137,42 @@ const writeFunctionsRuntimeConfig = Effect.fnUntraced(function* (
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const filePath = functionsRuntimeConfigPath(runtimeRoot);
-  yield* fs.makeDirectory(path.dirname(filePath), { recursive: true });
-  yield* fs.writeFileString(filePath, `${JSON.stringify(config, null, 2)}\n`);
+  const directory = path.dirname(filePath);
+  const temporaryPath = `${filePath}.tmp-${crypto.randomUUID()}`;
+
+  yield* fs.makeDirectory(directory, { recursive: true, mode: 0o700 });
+  yield* Effect.gen(function* () {
+    yield* fs.writeFileString(temporaryPath, `${JSON.stringify(config, null, 2)}\n`, {
+      flag: "wx",
+      mode: 0o600,
+    });
+    yield* fs.chmod(temporaryPath, 0o600);
+    yield* fs.rename(temporaryPath, filePath);
+    yield* fs.chmod(filePath, 0o600);
+  }).pipe(Effect.ensuring(fs.remove(temporaryPath).pipe(Effect.ignore)));
 });
 
-const clearFunctionsRuntimeConfig = Effect.fnUntraced(function* (runtimeRoot: string) {
+export const clearFunctionsRuntimeConfig = Effect.fnUntraced(function* (runtimeRoot: string) {
   const fs = yield* FileSystem.FileSystem;
-  yield* fs.remove(functionsRuntimeConfigPath(runtimeRoot)).pipe(Effect.ignore);
+  const filePath = functionsRuntimeConfigPath(runtimeRoot);
+  const directory = yield* Path.Path.pipe(Effect.map((path) => path.dirname(filePath)));
+
+  yield* fs.remove(filePath).pipe(Effect.ignore);
+
+  const entries = yield* fs.readDirectory(directory).pipe(Effect.orElseSucceed(() => []));
+  yield* Effect.forEach(
+    entries.filter((entry) => entry.startsWith(`${functionsRuntimeConfigFileName}.tmp-`)),
+    (entry) => fs.remove(join(directory, entry)).pipe(Effect.ignore),
+    { discard: true },
+  );
 });
 
 export const configureFunctionsRuntime = Effect.fnUntraced(function* (
   stackConfig: ResolvedStackConfig,
   runtimeHost: FunctionsRuntimeHost,
+  bundle: ResolvedFunctionsBundle | undefined,
 ) {
-  const runtimeConfig = yield* resolveFunctionsRuntimeConfig(stackConfig, runtimeHost);
+  const runtimeConfig = resolveFunctionsRuntimeConfig(stackConfig, runtimeHost, bundle);
   if (runtimeConfig === undefined) {
     yield* clearFunctionsRuntimeConfig(stackConfig.runtimeRoot);
   } else {
diff --git a/packages/stack/src/functions.unit.test.ts b/packages/stack/src/functions.unit.test.ts
index e537ea9a90..2c046a2d28 100644
--- a/packages/stack/src/functions.unit.test.ts
+++ b/packages/stack/src/functions.unit.test.ts
@@ -1,16 +1,19 @@
 import { describe, expect, it } from "@effect/vitest";
 import { BunServices } from "@effect/platform-bun";
 import { mkdtempSync } from "node:fs";
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { readFile, readdir, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { Effect } from "effect";
+import { Effect, Schema } from "effect";
 import { resolveConfig } from "./StackConfigResolver.ts";
 import { defaultJwtSecret, generateJwt } from "./JwtGenerator.ts";
 import {
+  clearFunctionsRuntimeConfig,
   configureFunctionsRuntime,
   functionsRuntimeConfigPath,
+  ResolvedFunctionsBundleSchema,
   resolveFunctionsRuntimeConfig,
+  type ResolvedFunctionsBundle,
 } from "./functions.ts";
 import { verifyRequest } from "./services/edge-runtime-main.ts";
 
@@ -18,42 +21,20 @@ function makeTempProject(): string {
   return mkdtempSync(join(tmpdir(), "supabase-stack-functions-"));
 }
 
-async function writeProject(cwd: string) {
-  await mkdir(join(cwd, "supabase", "functions", "hello-world"), { recursive: true });
-  await mkdir(join(cwd, "supabase", "functions", "disabled-function"), { recursive: true });
-  await writeFile(
-    join(cwd, "supabase", "functions", "hello-world", "index.ts"),
-    "Deno.serve(() => Response.json({ ok: true }));\n",
-  );
-  await writeFile(
-    join(cwd, "supabase", "functions", "disabled-function", "index.ts"),
-    "Deno.serve(() => Response.json({ disabled: true }));\n",
-  );
-  await writeFile(
-    join(cwd, "supabase", ".env"),
-    "CONFIG_ONLY=from-project-env\nSHARED=from-project-env\n",
-  );
-  await writeFile(
-    join(cwd, "supabase", "functions", ".env"),
-    "FILE_ONLY=from-functions-env\nSHARED=from-functions-env\n",
-  );
-  await writeFile(
-    join(cwd, "supabase", "config.json"),
-    JSON.stringify({
-      functions: {
-        "hello-world": {
-          verify_jwt: true,
-          env: {
-            CONFIG_ONLY: "env(CONFIG_ONLY)",
-            SHARED: "env(SHARED)",
-          },
-        },
-        "disabled-function": {
-          enabled: false,
-        },
+function makeBundle(root: string): ResolvedFunctionsBundle {
+  return {
+    env: { SHARED: "shared-value", BUNDLE_ONLY: "bundle-value" },
+    functions: [
+      {
+        name: "hello-world",
+        verifyJWT: true,
+        entrypointPath: join(root, "functions", "hello-world", "index.ts"),
+        importMapPath: null,
+        staticFiles: [join(root, "functions", "hello-world", "assets", "*")],
+        env: { SHARED: "function-value", FUNCTION_ONLY: "function-value" },
       },
-    }),
-  );
+    ],
+  };
 }
 
 function jwtWithInvalidSignature(algorithm?: string): string {
@@ -101,95 +82,89 @@ const authFailureCases = [
 ];
 
 describe("stack Functions runtime config", () => {
-  it.live("auto-detects enabled functions from projectDir", () => {
-    const cwd = makeTempProject();
-
-    return Effect.gen(function* () {
-      yield* Effect.promise(() => writeProject(cwd));
-      const stackConfig = yield* Effect.promise(() => resolveConfig({ projectDir: cwd }));
-      const config = yield* resolveFunctionsRuntimeConfig(stackConfig, {
-        hostname: "127.0.0.1",
-      });
-
-      expect(config).toBeDefined();
-      expect(Object.keys(config!.functions)).toEqual(["hello-world"]);
-      expect(config!.functions["hello-world"]).toEqual({
-        verifyJWT: true,
-        entrypointPath: join(cwd, "supabase", "functions", "hello-world", "index.ts"),
-        importMapPath: "",
-        staticFiles: [],
-      });
-      expect(config!.env).toMatchObject({
-        FILE_ONLY: "from-functions-env",
-        CONFIG_ONLY: "from-project-env",
-        SHARED: "from-project-env",
-      });
-    }).pipe(
-      Effect.provide(BunServices.layer),
-      Effect.ensuring(Effect.promise(() => rm(cwd, { recursive: true, force: true }))),
+  it("projects an explicit bundle without project discovery", async () => {
+    const root = makeTempProject();
+    const stackConfig = await resolveConfig({ functions: makeBundle(root) });
+    const config = resolveFunctionsRuntimeConfig(
+      stackConfig,
+      { hostname: "127.0.0.1" },
+      makeBundle(root),
     );
-  });
-
-  it.live("supports explicit env files and disabling JWT verification", () => {
-    const cwd = makeTempProject();
 
-    return Effect.gen(function* () {
-      yield* Effect.promise(() => writeProject(cwd));
-      yield* Effect.promise(() => writeFile(join(cwd, "custom.env"), "FILE_ONLY=custom\n"));
-      const stackConfig = yield* Effect.promise(() =>
-        resolveConfig({
-          projectDir: cwd,
-          functions: {
-            envFile: "custom.env",
-            noVerifyJwt: true,
-          },
-        }),
-      );
-      const config = yield* resolveFunctionsRuntimeConfig(stackConfig, {
-        hostname: "127.0.0.1",
-      });
+    expect(config?.env).toEqual({ SHARED: "shared-value", BUNDLE_ONLY: "bundle-value" });
+    expect(config?.functions["hello-world"]).toEqual({
+      verifyJWT: true,
+      entrypointPath: join(root, "functions", "hello-world", "index.ts"),
+      importMapPath: null,
+      staticFiles: [join(root, "functions", "hello-world", "assets", "*")],
+      env: { SHARED: "function-value", FUNCTION_ONLY: "function-value" },
+    });
 
-      expect(config!.env.FILE_ONLY).toBe("custom");
-      expect(config!.functions["hello-world"]?.verifyJWT).toBe(false);
-    }).pipe(
-      Effect.provide(BunServices.layer),
-      Effect.ensuring(Effect.promise(() => rm(cwd, { recursive: true, force: true }))),
-    );
+    await rm(root, { recursive: true, force: true });
   });
 
-  it.live("keeps placeholder mode when Functions are disabled", () => {
-    const cwd = makeTempProject();
+  it("validates paths, import maps, and unique function names", async () => {
+    const decode = Schema.decodeUnknownSync(ResolvedFunctionsBundleSchema);
+    const root = makeTempProject();
+    const bundle = makeBundle(root);
 
-    return Effect.gen(function* () {
-      yield* Effect.promise(() => writeProject(cwd));
-      const stackConfig = yield* Effect.promise(() =>
-        resolveConfig({ projectDir: cwd, functions: false }),
-      );
-      const config = yield* resolveFunctionsRuntimeConfig(stackConfig, {
-        hostname: "127.0.0.1",
-      });
+    expect(decode(bundle).functions[0]?.importMapPath).toBeNull();
+    expect(() =>
+      decode({
+        ...bundle,
+        functions: [{ ...bundle.functions[0], entrypointPath: "./index.ts" }],
+      }),
+    ).toThrow("Expected an absolute path");
+    expect(() =>
+      decode({
+        ...bundle,
+        functions: [bundle.functions[0], bundle.functions[0]],
+      }),
+    ).toThrow("Duplicate function name: hello-world");
 
-      expect(config).toBeUndefined();
-    }).pipe(
-      Effect.provide(BunServices.layer),
-      Effect.ensuring(Effect.promise(() => rm(cwd, { recursive: true, force: true }))),
-    );
+    await rm(root, { recursive: true, force: true });
   });
 
-  it.live("writes generated runtime config into the stack runtime directory", () => {
+  it("keeps placeholder mode when no functions are supplied", async () => {
+    const stackConfig = await resolveConfig({ functions: false });
+
+    expect(
+      resolveFunctionsRuntimeConfig(stackConfig, { hostname: "127.0.0.1" }, undefined),
+    ).toBeUndefined();
+    expect(
+      resolveFunctionsRuntimeConfig(
+        stackConfig,
+        { hostname: "127.0.0.1" },
+        {
+          env: {},
+          functions: [],
+        },
+      ),
+    ).toBeUndefined();
+  });
+
+  it.live("atomically writes restrictive ephemeral config and removes it", () => {
     const cwd = makeTempProject();
 
     return Effect.gen(function* () {
-      yield* Effect.promise(() => writeProject(cwd));
-      const stackConfig = yield* Effect.promise(() => resolveConfig({ projectDir: cwd }));
-      yield* configureFunctionsRuntime(stackConfig, { hostname: "127.0.0.1" });
-      const written = JSON.parse(
-        yield* Effect.promise(() =>
-          readFile(functionsRuntimeConfigPath(stackConfig.runtimeRoot), "utf8"),
-        ),
-      ) as { functions: Record<string, unknown> };
+      const bundle = makeBundle(cwd);
+      const stackConfig = yield* Effect.promise(() =>
+        resolveConfig({ runtimeRoot: cwd, functions: bundle }),
+      );
+      yield* configureFunctionsRuntime(stackConfig, { hostname: "127.0.0.1" }, bundle);
+      const filePath = functionsRuntimeConfigPath(stackConfig.runtimeRoot);
+      const written = JSON.parse(yield* Effect.promise(() => readFile(filePath, "utf8"))) as {
+        functions: Record<string, unknown>;
+      };
 
       expect(Object.keys(written.functions)).toEqual(["hello-world"]);
+      expect((yield* Effect.promise(() => stat(filePath))).mode & 0o777).toBe(0o600);
+      expect(yield* Effect.promise(() => readdir(join(cwd, "edge-runtime")))).toEqual([
+        "functions-runtime-config.json",
+      ]);
+
+      yield* clearFunctionsRuntimeConfig(stackConfig.runtimeRoot);
+      expect(yield* Effect.promise(() => readdir(join(cwd, "edge-runtime")))).toEqual([]);
     }).pipe(
       Effect.provide(BunServices.layer),
       Effect.ensuring(Effect.promise(() => rm(cwd, { recursive: true, force: true }))),
diff --git a/packages/stack/src/index.ts b/packages/stack/src/index.ts
index 8e990d0640..4b238c07b8 100644
--- a/packages/stack/src/index.ts
+++ b/packages/stack/src/index.ts
@@ -26,5 +26,10 @@ export type { ServiceName, VersionManifest } from "./versions.ts";
 export type { ServiceResolution } from "./StackPreparation.ts";
 export type { PrefetchOptions, PrefetchResult } from "./prefetch.ts";
 export type { StackHandle } from "./createStack.ts";
-export type { FunctionsConfig, FunctionsRuntimeConfig } from "./functions.ts";
+export type {
+  FunctionsReloadConfig,
+  FunctionsRuntimeConfig,
+  ResolvedFunction,
+  ResolvedFunctionsBundle,
+} from "./functions.ts";
 export { UnixHttpClient, UnixHttpClientError } from "./UnixHttpClient.ts";
diff --git a/packages/stack/src/services/edge-runtime-main.ts b/packages/stack/src/services/edge-runtime-main.ts
index cda66721c5..7bdd1cd266 100644
--- a/packages/stack/src/services/edge-runtime-main.ts
+++ b/packages/stack/src/services/edge-runtime-main.ts
@@ -177,6 +177,7 @@ async function serveFunction(req: Request, config: any, functionName: string, fu
 
   const envVars = Object.entries({
     ...config.env,
+    ...functionConfig.env,
     SUPABASE_URL: config.supabaseUrl,
     SUPABASE_ANON_KEY: config.publishableKey,
     SUPABASE_SERVICE_ROLE_KEY: config.secretKey,
@@ -192,7 +193,7 @@ async function serveFunction(req: Request, config: any, functionName: string, fu
       workerTimeoutMs: 400000,
       noModuleCache: false,
       noNpm: false,
-      importMapPath: functionConfig.importMapPath,
+      importMapPath: functionConfig.importMapPath ?? undefined,
       envVars,
       forceCreate: false,
       customModuleRoot: "",
diff --git a/packages/stack/tests/createStack.e2e.test.ts b/packages/stack/tests/createStack.e2e.test.ts
index 9b734fa450..6511c750ad 100644
--- a/packages/stack/tests/createStack.e2e.test.ts
+++ b/packages/stack/tests/createStack.e2e.test.ts
@@ -3,7 +3,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
-import { createStack, type StackHandle } from "../src/node.ts";
+import { createStack, type ResolvedFunctionsBundle, type StackHandle } from "../src/node.ts";
 import { fetchFunctionWhenReady, setupTestTable } from "./helpers/e2e.ts";
 
 const STACK_E2E_TEST_TIMEOUT_MS = 5_000;
@@ -21,7 +21,7 @@ describe("createStack e2e", () => {
 
     stack = await createStack({
       projectDir,
-      functions: { noVerifyJwt: true },
+      functions: functionsBundle(projectDir, ["hello"]),
       jwtSecret: "super-secret-jwt-token-with-at-least-32-characters-long",
       postgres: { dataDir },
     });
@@ -89,7 +89,7 @@ describe("createStack e2e", () => {
 
   test("reloadFunctions picks up newly added Edge Functions", { timeout: 30_000 }, async () => {
     writeFunction(projectDir, "later", "later");
-    await stack.reloadFunctions({ noVerifyJwt: true });
+    await stack.reloadFunctions({ functions: functionsBundle(projectDir, ["hello", "later"]) });
 
     const res = await fetchFunctionWhenReady(`${stack.url}/functions/v1/later`);
 
@@ -168,3 +168,20 @@ function writeFunction(projectDir: string, slug: string, body: string) {
     `Deno.serve(() => new Response(${JSON.stringify(body)}));\n`,
   );
 }
+
+function functionsBundle(
+  projectDir: string,
+  names: ReadonlyArray<string>,
+): ResolvedFunctionsBundle {
+  return {
+    env: {},
+    functions: names.map((name) => ({
+      name,
+      verifyJWT: false,
+      entrypointPath: join(projectDir, "supabase", "functions", name, "index.ts"),
+      importMapPath: null,
+      staticFiles: [],
+      env: {},
+    })),
+  };
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index b6e5837da1..0e20dd2890 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -517,9 +517,6 @@ importers:
       '@effect/platform-node':
         specifier: 'catalog:'
         version: 4.0.0-beta.97(effect@4.0.0-beta.97)(ioredis@5.11.1)
-      '@supabase/config':
-        specifier: workspace:*
-        version: link:../config
       '@supabase/process-compose':
         specifier: workspace:*
         version: link:../process-compose

From e845aee4cbd42725a94442cc48d3406e1a4a4265 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 17:25:16 +0200
Subject: [PATCH 08/44] refactor(stack): narrow package entrypoints

---
 .../branches/switch/switch.handler.ts         |  20 ++-
 .../commands/functions/dev/dev.command.ts     |   3 +-
 .../functions/dev/functions-dev-runtime.ts    |  22 ++-
 .../functions/list/list.integration.test.ts   |   2 +-
 .../functions/new/new.integration.test.ts     |   2 +-
 .../commands/logs/logs.integration.test.ts    |   2 +-
 .../src/next/commands/start/start.command.ts  |  20 ++-
 .../status/status.integration.test.ts         |   2 +-
 .../commands/stop/stop.integration.test.ts    |   2 +-
 apps/cli/src/shared/cli/run.ts                |   2 +-
 apps/cli/tests/helpers/mocks.ts               |   2 +-
 apps/cli/tests/helpers/running-stack.ts       |   4 +-
 packages/stack/docs/architecture.md           |  23 +--
 packages/stack/docs/detach-mode.md            |  29 ++--
 packages/stack/package.json                   |   6 +-
 packages/stack/src/JwtGenerator.ts            |  17 +--
 .../src/UnixSocketSse.integration.test.ts     |   2 +-
 packages/stack/src/bun.ts                     |  46 +-----
 packages/stack/src/createStack.ts             |  38 +----
 packages/stack/src/daemon-node.ts             |   7 +-
 packages/stack/src/daemon.ts                  |   4 +-
 packages/stack/src/effect-bun.ts              |  20 +++
 packages/stack/src/effect-node.ts             |  20 +++
 packages/stack/src/effect.ts                  |  32 +----
 packages/stack/src/entrypoints.unit.test.ts   |  64 +++++++--
 packages/stack/src/index.ts                   |   1 -
 packages/stack/src/node.ts                    | 132 +-----------------
 packages/stack/src/platform-bun.ts            |  30 ++++
 packages/stack/src/platform-node.ts           | 109 +++++++++++++++
 packages/stack/src/testing.ts                 |   3 +
 30 files changed, 329 insertions(+), 337 deletions(-)
 create mode 100644 packages/stack/src/effect-bun.ts
 create mode 100644 packages/stack/src/effect-node.ts
 create mode 100644 packages/stack/src/platform-bun.ts
 create mode 100644 packages/stack/src/platform-node.ts
 create mode 100644 packages/stack/src/testing.ts

diff --git a/apps/cli/src/next/commands/branches/switch/switch.handler.ts b/apps/cli/src/next/commands/branches/switch/switch.handler.ts
index 86cbdb35a3..24d76bbc96 100644
--- a/apps/cli/src/next/commands/branches/switch/switch.handler.ts
+++ b/apps/cli/src/next/commands/branches/switch/switch.handler.ts
@@ -1,5 +1,4 @@
 import { StateManager, daemonLayer, resolveManagedStack, stopDaemon } from "@supabase/stack/effect";
-import { daemonEntryPoint } from "@supabase/stack";
 import { Effect, Option } from "effect";
 import { PlatformApi } from "../../../auth/platform-api.service.ts";
 import { CliConfig } from "../../../config/cli-config.service.ts";
@@ -154,17 +153,14 @@ export const switchBranch = Effect.fn("branches.switch")(function* (opts: {
       },
     });
 
-    const stackLayer = yield* daemonLayer(
-      {
-        cacheRoot: cliConfig.supabaseHome,
-        cwd: runtimeInfo.cwd,
-        projectDir: projectHome.projectRoot,
-        projectStateRoot: projectHome.projectHomeDir,
-        name: stackState.name,
-        ...launchConfig,
-      },
-      daemonEntryPoint,
-    );
+    const stackLayer = yield* daemonLayer({
+      cacheRoot: cliConfig.supabaseHome,
+      cwd: runtimeInfo.cwd,
+      projectDir: projectHome.projectRoot,
+      projectStateRoot: projectHome.projectHomeDir,
+      name: stackState.name,
+      ...launchConfig,
+    });
 
     yield* Effect.scoped(
       Effect.gen(function* () {
diff --git a/apps/cli/src/next/commands/functions/dev/dev.command.ts b/apps/cli/src/next/commands/functions/dev/dev.command.ts
index 3e84cba86e..04d932246b 100644
--- a/apps/cli/src/next/commands/functions/dev/dev.command.ts
+++ b/apps/cli/src/next/commands/functions/dev/dev.command.ts
@@ -1,5 +1,4 @@
-import { unixHttpClientLayer } from "@supabase/stack";
-import { DEFAULT_MANAGED_STACK_NAME } from "@supabase/stack/effect";
+import { DEFAULT_MANAGED_STACK_NAME, unixHttpClientLayer } from "@supabase/stack/effect";
 import { Layer } from "effect";
 import { Command, Flag } from "effect/unstable/cli";
 import type * as CliCommand from "effect/unstable/cli/Command";
diff --git a/apps/cli/src/next/commands/functions/dev/functions-dev-runtime.ts b/apps/cli/src/next/commands/functions/dev/functions-dev-runtime.ts
index 0f73099841..0b5fe7d749 100644
--- a/apps/cli/src/next/commands/functions/dev/functions-dev-runtime.ts
+++ b/apps/cli/src/next/commands/functions/dev/functions-dev-runtime.ts
@@ -1,4 +1,3 @@
-import { daemonEntryPoint } from "@supabase/stack";
 import {
   connectLayer,
   daemonLayer,
@@ -68,18 +67,15 @@ const startFullStack = Effect.fnUntraced(function* (opts: FunctionsDevStackOptio
   yield* ensureProjectStateIgnored(projectHome.projectRoot);
 
   const serviceVersionContext = yield* resolveServiceVersionContext([], undefined);
-  const stackLayer = yield* daemonLayer(
-    {
-      cacheRoot: cliConfig.supabaseHome,
-      cwd: runtimeInfo.cwd,
-      projectDir: projectHome.projectRoot,
-      projectStateRoot: projectHome.projectHomeDir,
-      name: opts.stack,
-      edgeRuntime: opts.edgeRuntime,
-      ...versionsFromContext(serviceVersionContext),
-    },
-    daemonEntryPoint,
-  );
+  const stackLayer = yield* daemonLayer({
+    cacheRoot: cliConfig.supabaseHome,
+    cwd: runtimeInfo.cwd,
+    projectDir: projectHome.projectRoot,
+    projectStateRoot: projectHome.projectHomeDir,
+    name: opts.stack,
+    edgeRuntime: opts.edgeRuntime,
+    ...versionsFromContext(serviceVersionContext),
+  });
   const state = yield* stateManager.read(opts.stack);
 
   yield* stateManager.writeMetadata(
diff --git a/apps/cli/src/next/commands/functions/list/list.integration.test.ts b/apps/cli/src/next/commands/functions/list/list.integration.test.ts
index 68ee7c2c3d..c7e5e99e41 100644
--- a/apps/cli/src/next/commands/functions/list/list.integration.test.ts
+++ b/apps/cli/src/next/commands/functions/list/list.integration.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from "@effect/vitest";
 import { FunctionResponse } from "@supabase/api/effect";
 import { BunServices } from "@effect/platform-bun";
-import { unixHttpClientLayer } from "@supabase/stack";
+import { unixHttpClientLayer } from "@supabase/stack/effect";
 import { mkdtempSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
diff --git a/apps/cli/src/next/commands/functions/new/new.integration.test.ts b/apps/cli/src/next/commands/functions/new/new.integration.test.ts
index 7396813785..a545d8104b 100644
--- a/apps/cli/src/next/commands/functions/new/new.integration.test.ts
+++ b/apps/cli/src/next/commands/functions/new/new.integration.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "@effect/vitest";
 import { BunServices } from "@effect/platform-bun";
-import { unixHttpClientLayer } from "@supabase/stack";
+import { unixHttpClientLayer } from "@supabase/stack/effect";
 import { existsSync, mkdtempSync } from "node:fs";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
diff --git a/apps/cli/src/next/commands/logs/logs.integration.test.ts b/apps/cli/src/next/commands/logs/logs.integration.test.ts
index f9e554e959..95c1eb6e36 100644
--- a/apps/cli/src/next/commands/logs/logs.integration.test.ts
+++ b/apps/cli/src/next/commands/logs/logs.integration.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "@effect/vitest";
 import { BunServices } from "@effect/platform-bun";
-import { unixHttpClientLayer } from "@supabase/stack";
+import { unixHttpClientLayer } from "@supabase/stack/effect";
 import { Effect, Exit, Fiber, Layer } from "effect";
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
diff --git a/apps/cli/src/next/commands/start/start.command.ts b/apps/cli/src/next/commands/start/start.command.ts
index 4db1fc276d..4b675d13e9 100644
--- a/apps/cli/src/next/commands/start/start.command.ts
+++ b/apps/cli/src/next/commands/start/start.command.ts
@@ -7,7 +7,6 @@ import {
   stackMetadata,
   type StackMetadata,
 } from "@supabase/stack/effect";
-import { daemonEntryPoint } from "@supabase/stack";
 import { Command, Flag } from "effect/unstable/cli";
 import type * as CliCommand from "effect/unstable/cli/Command";
 import { projectLocalServiceVersionsLayer } from "../../config/project-local-service-versions.layer.ts";
@@ -197,17 +196,14 @@ export const startCommand = Command.make("start", flags).pipe(
       yield* output.intro("Start local Supabase stack");
       yield* ensureProjectStateIgnored(projectHome.projectRoot);
 
-      const stackLayer = yield* daemonLayer(
-        {
-          cacheRoot: cliConfig.supabaseHome,
-          cwd: runtimeInfo.cwd,
-          projectDir: projectHome.projectRoot,
-          projectStateRoot: projectHome.projectHomeDir,
-          name: flags.stack,
-          ...stackConfig,
-        },
-        daemonEntryPoint,
-      );
+      const stackLayer = yield* daemonLayer({
+        cacheRoot: cliConfig.supabaseHome,
+        cwd: runtimeInfo.cwd,
+        projectDir: projectHome.projectRoot,
+        projectStateRoot: projectHome.projectHomeDir,
+        name: flags.stack,
+        ...stackConfig,
+      });
       const daemonState = yield* stateManager.read(flags.stack);
 
       const metadata = stackMetadata({
diff --git a/apps/cli/src/next/commands/status/status.integration.test.ts b/apps/cli/src/next/commands/status/status.integration.test.ts
index 95ac5bc27a..f12be0f0ee 100644
--- a/apps/cli/src/next/commands/status/status.integration.test.ts
+++ b/apps/cli/src/next/commands/status/status.integration.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "@effect/vitest";
 import { BunServices } from "@effect/platform-bun";
-import { unixHttpClientLayer } from "@supabase/stack";
+import { unixHttpClientLayer } from "@supabase/stack/effect";
 import { StackServiceState } from "@supabase/stack/effect";
 import { Effect, Layer } from "effect";
 import { status } from "./status.handler.ts";
diff --git a/apps/cli/src/next/commands/stop/stop.integration.test.ts b/apps/cli/src/next/commands/stop/stop.integration.test.ts
index bcf7a8d46f..1f8167e436 100644
--- a/apps/cli/src/next/commands/stop/stop.integration.test.ts
+++ b/apps/cli/src/next/commands/stop/stop.integration.test.ts
@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Effect, Exit, Layer } from "effect";
 import { BunServices } from "@effect/platform-bun";
-import { unixHttpClientLayer } from "@supabase/stack";
+import { unixHttpClientLayer } from "@supabase/stack/effect";
 import { stop } from "./stop.handler.ts";
 import { mockOutput, withEnv } from "../../../../tests/helpers/mocks.ts";
 import {
diff --git a/apps/cli/src/shared/cli/run.ts b/apps/cli/src/shared/cli/run.ts
index 0ee530f2d3..0175631686 100644
--- a/apps/cli/src/shared/cli/run.ts
+++ b/apps/cli/src/shared/cli/run.ts
@@ -1,6 +1,6 @@
 import { BunServices } from "@effect/platform-bun";
 import { ProjectConfigStore } from "@supabase/config";
-import { unixHttpClientLayer } from "@supabase/stack";
+import { unixHttpClientLayer } from "@supabase/stack/effect";
 import { Cause, Console, Effect, Exit, Fiber, Layer, Runtime, Stdio } from "effect";
 import { CliError, CliOutput, Command } from "effect/unstable/cli";
 import { CLI_VERSION } from "./version.ts";
diff --git a/apps/cli/tests/helpers/mocks.ts b/apps/cli/tests/helpers/mocks.ts
index 885009f822..792c27fbb8 100644
--- a/apps/cli/tests/helpers/mocks.ts
+++ b/apps/cli/tests/helpers/mocks.ts
@@ -14,7 +14,7 @@ import {
   type StackMetadata,
   type StackState,
 } from "@supabase/stack/effect";
-import { UnixHttpClient } from "@supabase/stack";
+import { UnixHttpClient } from "@supabase/stack/testing";
 import { Api } from "../../src/next/auth/api.service.ts";
 import type { LoginSessionResponse, ProfileResponse } from "../../src/next/auth/api.service.ts";
 import { Credentials } from "../../src/next/auth/credentials.service.ts";
diff --git a/apps/cli/tests/helpers/running-stack.ts b/apps/cli/tests/helpers/running-stack.ts
index 50283f76fa..9e7ed2e106 100644
--- a/apps/cli/tests/helpers/running-stack.ts
+++ b/apps/cli/tests/helpers/running-stack.ts
@@ -1,8 +1,6 @@
 import { BunServices } from "@effect/platform-bun";
 import * as BunHttpServer from "@effect/platform-bun/BunHttpServer";
-import { unixHttpClientLayer } from "@supabase/stack";
 import {
-  DaemonServer,
   DEFAULT_VERSIONS,
   fullVersionManifest,
   type PartialVersionManifest,
@@ -14,7 +12,9 @@ import {
   type StackInfo,
   type StackMetadata,
   type StackState,
+  unixHttpClientLayer,
 } from "@supabase/stack/effect";
+import { DaemonServer } from "@supabase/stack/testing";
 import { Effect, Layer, ManagedRuntime, Option, Stream } from "effect";
 import { spawn, type ChildProcess } from "node:child_process";
 import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
diff --git a/packages/stack/docs/architecture.md b/packages/stack/docs/architecture.md
index 7faf85e5e7..7120a7cbe9 100644
--- a/packages/stack/docs/architecture.md
+++ b/packages/stack/docs/architecture.md
@@ -11,12 +11,14 @@ The package exposes two levels of Interface:
 
 - `@supabase/stack` selects `bun.ts` or `node.ts` through export conditions and exposes the
   Promise-oriented `createStack()` / `StackHandle` Interface plus prefetch helpers.
-- `@supabase/stack/effect` exposes Effect Interfaces and layer factories used by the CLI and
-  advanced callers.
+- `@supabase/stack/effect` selects a runtime Adapter through the same export conditions and exposes
+  Effect Interfaces plus platform-bound layer factories used by the CLI and advanced callers.
+- `@supabase/stack/testing` exposes only the service tags needed to replace daemon transport in
+  consumer tests. Runtime implementation tags do not leak through the root or Effect barrels.
 
-The root runtime Adapters provide Effect filesystem, path, child-process, HTTP-server, and Unix
-socket HTTP implementations. `createStack.ts` remains platform-agnostic and receives a
-`PlatformFactory`.
+Internal runtime Adapters provide Effect filesystem, path, child-process, HTTP-server, and Unix
+socket HTTP implementations. `createStack.ts` and the layer factories remain platform-agnostic;
+the conditional root and Effect entries bind them to their selected runtime.
 
 ```mermaid
 flowchart LR
@@ -289,12 +291,15 @@ Callers may explicitly supply `projectStateRoot`, in which case durable stacks l
 ## Runtime entrypoints and exports
 
 - `bun.ts` and `node.ts` are root export-condition targets.
+- `effect-bun.ts` and `effect-node.ts` are Effect export-condition targets. They bind foreground,
+  daemon, and Unix-socket layers without exposing raw platform factories or bootstrap paths.
 - `daemon-bun.ts` is exported as `@supabase/stack/daemon-bun` so the compiled CLI can dispatch to
   it in-process.
-- `daemon-node.ts` is intentionally not a package export. `node.ts` resolves it by file URL and
-  passes that filesystem path to `daemonLayer`; the package `knip.entry` list preserves this live
-  file-URL-only entrypoint.
-- `effect.ts` is the low-level Effect export used by the CLI. There is no `internals.ts` entrypoint.
+- `daemon-node.ts` is intentionally not a package export. The internal Node platform Adapter
+  resolves it by file URL and passes that filesystem path to `daemonLayer`; the package
+  `knip.entry` list preserves this live file-URL-only entrypoint.
+- `effect.ts` is the platform-agnostic consumer contract re-exported by the conditional Effect
+  entries. There is no general-purpose `internals.ts` entrypoint.
 
 ## Testing
 
diff --git a/packages/stack/docs/detach-mode.md b/packages/stack/docs/detach-mode.md
index f1a1b6ecbd..14f715631b 100644
--- a/packages/stack/docs/detach-mode.md
+++ b/packages/stack/docs/detach-mode.md
@@ -159,20 +159,21 @@ crash-recovery metadata is deliberately separate from user-facing `/status` conn
 
 ## Package entrypoints
 
-| File                  | Reachability and role                                                                                         |
-| --------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `src/daemon.ts`       | Shared daemon protocol and lifecycle; receives runtime-specific HTTP-server factories.                        |
-| `src/daemon-bun.ts`   | Bun daemon Adapter. Exported as `@supabase/stack/daemon-bun` for compiled CLI dispatch.                       |
-| `src/daemon-node.ts`  | Node daemon Adapter. Intentionally file-URL-only: `node.ts` resolves its path and passes it to `daemonLayer`. |
-| `src/DaemonServer.ts` | Unix-socket HTTP/SSE Adapter over `Stack`.                                                                    |
-| `src/RemoteStack.ts`  | Remote Effect `Stack` Adapter over that transport.                                                            |
-| `src/layers.ts`       | Foreground, foreground-daemon, forked-daemon, and connect layer composition.                                  |
-| `src/StateManager.ts` | Durable metadata, live-state claims, scanning, stale-state removal, and deletion.                             |
-| `src/effect.ts`       | Effect-facing exports consumed by the CLI and advanced callers.                                               |
-
-There is no `internals.ts`. `daemon-node.ts` is not a package export because Node root consumers
-reach it by the file URL returned from `node.ts`; it is listed under `knip.entry` in `package.json`
-so static unused-code analysis preserves that live entrypoint.
+| File                  | Reachability and role                                                                                   |
+| --------------------- | ------------------------------------------------------------------------------------------------------- |
+| `src/daemon.ts`       | Shared daemon protocol and lifecycle; receives runtime-specific HTTP-server factories.                  |
+| `src/daemon-bun.ts`   | Bun daemon Adapter. Exported as `@supabase/stack/daemon-bun` for compiled CLI dispatch.                 |
+| `src/daemon-node.ts`  | Node daemon Adapter. Intentionally file-URL-only: the internal Node platform Adapter resolves its path. |
+| `src/DaemonServer.ts` | Unix-socket HTTP/SSE Adapter over `Stack`.                                                              |
+| `src/RemoteStack.ts`  | Remote Effect `Stack` Adapter over that transport.                                                      |
+| `src/layers.ts`       | Foreground, foreground-daemon, forked-daemon, and connect layer composition.                            |
+| `src/StateManager.ts` | Durable metadata, live-state claims, scanning, stale-state removal, and deletion.                       |
+| `src/effect-*.ts`     | Conditional Effect entries that bind consumer layers to Bun or Node.                                    |
+| `src/effect.ts`       | Platform-agnostic Effect contracts re-exported by the conditional entries.                              |
+
+There is no `internals.ts`. `daemon-node.ts` is not a package export because the Node Effect
+Adapter reaches it through the file URL returned by the internal platform module; it is listed
+under `knip.entry` in `package.json` so static unused-code analysis preserves that live entrypoint.
 
 ## Compiled executable re-entry
 
diff --git a/packages/stack/package.json b/packages/stack/package.json
index 80161f67b9..a25e82d9bf 100644
--- a/packages/stack/package.json
+++ b/packages/stack/package.json
@@ -8,7 +8,11 @@
       "bun": "./src/bun.ts",
       "default": "./src/node.ts"
     },
-    "./effect": "./src/effect.ts",
+    "./effect": {
+      "bun": "./src/effect-bun.ts",
+      "default": "./src/effect-node.ts"
+    },
+    "./testing": "./src/testing.ts",
     "./daemon-bun": "./src/daemon-bun.ts"
   },
   "scripts": {
diff --git a/packages/stack/src/JwtGenerator.ts b/packages/stack/src/JwtGenerator.ts
index 83ac2115d6..ae4566cfd3 100644
--- a/packages/stack/src/JwtGenerator.ts
+++ b/packages/stack/src/JwtGenerator.ts
@@ -1,5 +1,4 @@
 import { createHmac } from "node:crypto";
-import { Effect, Layer, Context } from "effect";
 
 // Hardcoded opaque key defaults matching Go CLI (pkg/config/apikeys.go:19-20).
 // These are client-facing keys for local dev — SDKs use these, not JWTs directly.
@@ -10,8 +9,7 @@ export const defaultSecretKey = "sb_secret_N7UND0UgjKTVK-Uodkm0Hg_xSvEMPvz";
 export const defaultJwtSecret = "super-secret-jwt-token-with-at-least-32-characters-long";
 
 /**
- * Pure synchronous JWT generation. Used both by the JwtGenerator service
- * and directly in createStack() where JWTs are needed before layers run.
+ * Pure synchronous JWT generation used while resolving stack configuration.
  */
 export function generateJwt(secret: string, role: string): string {
   const header = Buffer.from(JSON.stringify({ alg: "HS256", typ: "JWT" })).toString("base64url");
@@ -38,16 +36,3 @@ export function generateJwks(secret: string): string {
     ],
   });
 }
-
-export class JwtGenerator extends Context.Service<
-  JwtGenerator,
-  {
-    readonly generate: (secret: string, role: string) => Effect.Effect<string>;
-    readonly generateJwks: (secret: string) => Effect.Effect<string>;
-  }
->()("local/JwtGenerator") {
-  static layer: Layer.Layer<JwtGenerator> = Layer.succeed(this, {
-    generate: (secret: string, role: string) => Effect.sync(() => generateJwt(secret, role)),
-    generateJwks: (secret: string) => Effect.sync(() => generateJwks(secret)),
-  });
-}
diff --git a/packages/stack/src/UnixSocketSse.integration.test.ts b/packages/stack/src/UnixSocketSse.integration.test.ts
index e6694814da..c7de5133b0 100644
--- a/packages/stack/src/UnixSocketSse.integration.test.ts
+++ b/packages/stack/src/UnixSocketSse.integration.test.ts
@@ -10,7 +10,7 @@ import { DaemonServer } from "./DaemonServer.ts";
 import { RemoteStack } from "./RemoteStack.ts";
 import { Stack, type StackInfo } from "./Stack.ts";
 import { StackServiceState } from "./StackServiceState.ts";
-import { unixHttpClientLayer } from "./bun.ts";
+import { unixHttpClientLayer } from "./platform-bun.ts";
 
 const REFERENCE_IDLE_TIMEOUT_SECONDS = 1;
 // Keep the idle gap just past a short reference timeout so the suite stays fast.
diff --git a/packages/stack/src/bun.ts b/packages/stack/src/bun.ts
index ebc92eb69c..2d05640881 100644
--- a/packages/stack/src/bun.ts
+++ b/packages/stack/src/bun.ts
@@ -1,59 +1,17 @@
 import { BunServices } from "@effect/platform-bun";
-import * as BunHttpServer from "@effect/platform-bun/BunHttpServer";
-import { fileURLToPath } from "node:url";
 import { Effect, Layer } from "effect";
 import { FetchHttpClient } from "effect/unstable/http";
 import { BinaryResolver } from "./BinaryResolver.ts";
-import {
-  createStack as createStackCore,
-  type PlatformFactory,
-  type StackHandle,
-} from "./createStack.ts";
+import { createStack as createStackCore, type StackHandle } from "./createStack.ts";
 import {
   prefetch as prefetchEffect,
   type PrefetchOptions,
   type PrefetchResult,
 } from "./prefetch.ts";
 import { defaultCacheRoot } from "./paths.ts";
+import { platformFactory } from "./platform-bun.ts";
 import { StackPreparation } from "./StackPreparation.ts";
 import type { StackConfig } from "./StackConfig.ts";
-import { UnixHttpClient, UnixHttpClientError } from "./UnixHttpClient.ts";
-
-interface BunUnixRequestInit extends RequestInit {
-  readonly unix: string;
-}
-
-export const unixHttpClientLayer = Layer.succeed(UnixHttpClient, {
-  request: (socketPath, path, init) =>
-    Effect.tryPromise({
-      try: () => {
-        const requestInit: BunUnixRequestInit = {
-          ...init,
-          unix: socketPath,
-        };
-        return fetch(`http://localhost${path}`, requestInit);
-      },
-      catch: (cause) => new UnixHttpClientError({ socketPath, path, cause }),
-    }),
-});
-
-// ---------------------------------------------------------------------------
-// Platform values — for use with Effect layer factories
-// ---------------------------------------------------------------------------
-
-/** Bun platform factory for use with foregroundLayer / daemonLayer. */
-export const platformFactory: PlatformFactory = ({ apiPort, releaseApiPort }) =>
-  Layer.mergeAll(
-    BunServices.layer,
-    Layer.unwrap(releaseApiPort.pipe(Effect.as(BunHttpServer.layer({ port: apiPort })))),
-  );
-
-/** Path to the Bun daemon entry point for use with daemonLayer. */
-export const daemonEntryPoint: string = fileURLToPath(new URL("./daemon-bun.ts", import.meta.url));
-
-// ---------------------------------------------------------------------------
-// Promise API — convenience wrappers for non-Effect consumers
-// ---------------------------------------------------------------------------
 
 export async function createStack(config?: StackConfig): Promise<StackHandle> {
   return createStackCore(config, platformFactory);
diff --git a/packages/stack/src/createStack.ts b/packages/stack/src/createStack.ts
index fc89fb2edb..4864d0223b 100644
--- a/packages/stack/src/createStack.ts
+++ b/packages/stack/src/createStack.ts
@@ -1,12 +1,11 @@
 import type { LogEntry } from "@supabase/process-compose";
-import { Effect, type Layer, ManagedRuntime, Stream } from "effect";
-import { FileSystem, Path } from "effect";
+import { Effect, FileSystem, type Layer, ManagedRuntime, Path, Stream } from "effect";
 import { HttpServer } from "effect/unstable/http";
 import { ChildProcessSpawner } from "effect/unstable/process";
 import { candidateCleanupTargets, cleanupAutoManagedPaths, dockerForceRemove } from "./cleanup.ts";
 import { toStackError } from "./errors.ts";
 import type { FunctionsReloadConfig } from "./functions.ts";
-import { daemonLayer, foregroundLayer, type DaemonStartError } from "./layers.ts";
+import { foregroundLayer } from "./layers.ts";
 import { PORT_FIELDS, reservePorts, type PortLease } from "./PortAllocator.ts";
 import { allocatedPortFieldsForConfig } from "./ServicePorts.ts";
 import { Stack } from "./Stack.ts";
@@ -14,18 +13,16 @@ import type { EdgeRuntimeReloadConfig } from "./Stack.ts";
 import type { ReadyOptions, ResolvedStackConfig, StackConfig } from "./StackConfig.ts";
 import { resolveConfig } from "./StackConfigResolver.ts";
 import type { StackServiceState } from "./StackServiceState.ts";
-import { InvalidStackStateError, StackAlreadyRunningError } from "./StateManager.ts";
-import { UnixHttpClient } from "./UnixHttpClient.ts";
 
-export type PlatformServices =
+type PlatformServices =
   | FileSystem.FileSystem
   | Path.Path
   | ChildProcessSpawner.ChildProcessSpawner
   | HttpServer.HttpServer;
 
-export type PlatformLayer = Layer.Layer<PlatformServices>;
+type PlatformLayer = Layer.Layer<PlatformServices>;
 /** Supplies the platform HTTP server used by the stack and HTTP proxy. */
-export interface PlatformFactoryOptions {
+interface PlatformFactoryOptions {
   readonly apiPort: number;
   readonly releaseApiPort: Effect.Effect<void>;
 }
@@ -55,31 +52,6 @@ export interface StackHandle extends AsyncDisposable {
   logHistory(name: string, limit?: number): Promise<ReadonlyArray<LogEntry>>;
 }
 
-export const projectDaemonLayer = (opts: {
-  readonly cacheRoot: string;
-  readonly cwd: string;
-  readonly projectDir?: string;
-  readonly projectStateRoot?: string;
-  readonly name?: string;
-  readonly daemonEntryPoint: string;
-  readonly stackConfig?: Omit<StackConfig, "cacheRoot" | "stackRoot" | "runtimeRoot" | "functions">;
-}): Effect.Effect<
-  Layer.Layer<Stack>,
-  DaemonStartError | InvalidStackStateError | StackAlreadyRunningError,
-  FileSystem.FileSystem | Path.Path | UnixHttpClient
-> =>
-  daemonLayer(
-    {
-      cacheRoot: opts.cacheRoot,
-      cwd: opts.cwd,
-      projectDir: opts.projectDir,
-      projectStateRoot: opts.projectStateRoot,
-      name: opts.name,
-      ...opts.stackConfig,
-    },
-    opts.daemonEntryPoint,
-  );
-
 export async function createStack(
   config: StackConfig | undefined,
   platformFactory: PlatformFactory,
diff --git a/packages/stack/src/daemon-node.ts b/packages/stack/src/daemon-node.ts
index 387b2dff11..7c34ac6c70 100644
--- a/packages/stack/src/daemon-node.ts
+++ b/packages/stack/src/daemon-node.ts
@@ -4,9 +4,10 @@ import { createServer } from "node:http";
 import { Effect, Layer } from "effect";
 import { runDaemon } from "./daemon.ts";
 
-// Live child-process entrypoint for Node root consumers. `node.ts` resolves this module by file URL
-// and passes its filesystem path to daemonLayer, so it is deliberately not a package export. The
-// `knip.entry` declaration in package.json preserves this file-URL-only reachability.
+// Live child-process entrypoint for Node Effect consumers. The internal Node platform adapter
+// resolves this module by file URL and passes its filesystem path to daemonLayer, so it is
+// deliberately not a package export. The `knip.entry` declaration in package.json preserves this
+// file-URL-only reachability; see the matching note in node.ts.
 runDaemon(
   ({ apiPort, releaseApiPort }) =>
     Layer.mergeAll(
diff --git a/packages/stack/src/daemon.ts b/packages/stack/src/daemon.ts
index 30361ecb92..0c64553060 100644
--- a/packages/stack/src/daemon.ts
+++ b/packages/stack/src/daemon.ts
@@ -23,12 +23,12 @@ export interface DaemonStartMessage {
   readonly socketPath: string;
 }
 
-export interface DaemonStartedMessage {
+interface DaemonStartedMessage {
   readonly type: "started";
   readonly state: StackState;
 }
 
-export interface DaemonErrorMessage {
+interface DaemonErrorMessage {
   readonly type: "error";
   readonly message: string;
 }
diff --git a/packages/stack/src/effect-bun.ts b/packages/stack/src/effect-bun.ts
new file mode 100644
index 0000000000..e4ef00edf9
--- /dev/null
+++ b/packages/stack/src/effect-bun.ts
@@ -0,0 +1,20 @@
+// @supabase/stack/effect — Bun-bound Effect interfaces and consumer layers.
+
+export * from "./effect.ts";
+
+import type { PortLease } from "./PortAllocator.ts";
+import type { ResolvedStackConfig } from "./StackConfig.ts";
+import type { DaemonConfigInput } from "./StackConfigResolver.ts";
+import {
+  daemonLayer as daemonLayerForPlatform,
+  foregroundLayer as foregroundLayerForPlatform,
+} from "./layers.ts";
+import { daemonEntryPoint, platformFactory, unixHttpClientLayer } from "./platform-bun.ts";
+
+export { unixHttpClientLayer };
+
+export const foregroundLayer = (config: ResolvedStackConfig, portLease: PortLease) =>
+  foregroundLayerForPlatform(config, platformFactory, portLease);
+
+export const daemonLayer = (input: DaemonConfigInput) =>
+  daemonLayerForPlatform(input, daemonEntryPoint);
diff --git a/packages/stack/src/effect-node.ts b/packages/stack/src/effect-node.ts
new file mode 100644
index 0000000000..fb60982fae
--- /dev/null
+++ b/packages/stack/src/effect-node.ts
@@ -0,0 +1,20 @@
+// @supabase/stack/effect — Node-bound Effect interfaces and consumer layers.
+
+export * from "./effect.ts";
+
+import type { PortLease } from "./PortAllocator.ts";
+import type { ResolvedStackConfig } from "./StackConfig.ts";
+import type { DaemonConfigInput } from "./StackConfigResolver.ts";
+import {
+  daemonLayer as daemonLayerForPlatform,
+  foregroundLayer as foregroundLayerForPlatform,
+} from "./layers.ts";
+import { daemonEntryPoint, platformFactory, unixHttpClientLayer } from "./platform-node.ts";
+
+export { unixHttpClientLayer };
+
+export const foregroundLayer = (config: ResolvedStackConfig, portLease: PortLease) =>
+  foregroundLayerForPlatform(config, platformFactory, portLease);
+
+export const daemonLayer = (input: DaemonConfigInput) =>
+  daemonLayerForPlatform(input, daemonEntryPoint);
diff --git a/packages/stack/src/effect.ts b/packages/stack/src/effect.ts
index 6a15a5c76d..f1ea9b8407 100644
--- a/packages/stack/src/effect.ts
+++ b/packages/stack/src/effect.ts
@@ -1,5 +1,4 @@
-// @supabase/stack/effect — advanced Effect and low-level APIs.
-// Platform-agnostic: pass platformFactory/daemonEntryPoint from @supabase/stack.
+// Platform-agnostic Effect contracts re-exported by the conditional @supabase/stack/effect entry.
 
 export type { LogEntry } from "@supabase/process-compose";
 export type { StackServiceStatus } from "./StackServiceState.ts";
@@ -25,9 +24,6 @@ export {
   postgrestAssetName,
 } from "./Platform.ts";
 
-export type { BinarySpec } from "./BinaryResolver.ts";
-export { BinaryResolver } from "./BinaryResolver.ts";
-
 export type { ServiceResolution } from "./StackPreparation.ts";
 
 export type { PrefetchOptions, PrefetchResult } from "./prefetch.ts";
@@ -38,7 +34,6 @@ export {
   defaultPublishableKey,
   defaultSecretKey,
   generateJwt,
-  JwtGenerator,
 } from "./JwtGenerator.ts";
 
 export type {
@@ -57,8 +52,6 @@ export {
   reservePorts,
 } from "./PortAllocator.ts";
 
-export type { ProxyConfig } from "./ApiProxy.ts";
-export { ApiProxy } from "./ApiProxy.ts";
 export type {
   AnalyticsConfig,
   AuthConfig,
@@ -92,7 +85,6 @@ export type {
   VectorConfig,
 } from "./StackConfig.ts";
 export { DEFAULT_STACK_READINESS_POLICY, resolveReadinessPolicy } from "./StackConfig.ts";
-export { StackBuilder } from "./StackBuilder.ts";
 
 export type { EdgeRuntimeReloadConfig, StackInfo } from "./Stack.ts";
 export { EdgeRuntimeReloadConfigSchema, Stack } from "./Stack.ts";
@@ -163,18 +155,6 @@ export {
   stackMetadata,
 } from "./StackMetadata.ts";
 
-export { DaemonServer } from "./DaemonServer.ts";
-export { RemoteStack } from "./RemoteStack.ts";
-export { UnixHttpClient, UnixHttpClientError } from "./UnixHttpClient.ts";
-
-export type {
-  PlatformFactory,
-  PlatformFactoryOptions,
-  PlatformLayer,
-  PlatformServices,
-  StackHandle,
-} from "./createStack.ts";
-export { createStack, projectDaemonLayer } from "./createStack.ts";
 export type { ResolvedDaemonConfig } from "./StackConfig.ts";
 export {
   defaultManagedStackName,
@@ -182,7 +162,7 @@ export {
   resolveDaemonConfig,
 } from "./StackConfigResolver.ts";
 
-export { connectLayer, DaemonStartError, daemonLayer, foregroundLayer } from "./layers.ts";
+export { connectLayer, DaemonStartError } from "./layers.ts";
 export type { ManagedStack } from "./managed-stack.ts";
 export { resolveManagedStack } from "./managed-stack.ts";
 
@@ -194,11 +174,3 @@ export {
   resolveStackSummary,
   stopDaemon,
 } from "./discovery.ts";
-
-export type {
-  DaemonErrorMessage,
-  DaemonHttpServerFactory,
-  DaemonMessage,
-  DaemonStartedMessage,
-  DaemonStartMessage,
-} from "./daemon.ts";
diff --git a/packages/stack/src/entrypoints.unit.test.ts b/packages/stack/src/entrypoints.unit.test.ts
index 61d8f0f41b..59f1aa4044 100644
--- a/packages/stack/src/entrypoints.unit.test.ts
+++ b/packages/stack/src/entrypoints.unit.test.ts
@@ -1,23 +1,71 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { describe, expect, expectTypeOf, it } from "vitest";
+import * as bunRoot from "./bun.ts";
+import * as bunEffect from "./effect-bun.ts";
+import * as nodeEffect from "./effect-node.ts";
+import * as nodeRoot from "./node.ts";
+import type { StackHandle } from "./createStack.ts";
+import * as testing from "./testing.ts";
 
-import { describe, expect, it } from "vitest";
+const INTERNAL_EFFECT_EXPORTS = [
+  "ApiProxy",
+  "BinaryResolver",
+  "DaemonServer",
+  "JwtGenerator",
+  "RemoteStack",
+  "StackBuilder",
+  "UnixHttpClient",
+  "createStack",
+  "projectDaemonLayer",
+] as const;
 
 describe("@supabase/stack entrypoints", () => {
-  it("ships conditional root exports and keeps only the effect subpath", () => {
+  it("declares only intentional package entrypoints", () => {
     const srcDir = dirname(fileURLToPath(import.meta.url));
     const packageJson = JSON.parse(readFileSync(join(srcDir, "../package.json"), "utf8")) as {
       readonly exports: Record<string, string | Record<string, string>>;
+      readonly knip: { readonly entry: ReadonlyArray<string> };
     };
 
-    expect(packageJson.exports["."]).toEqual({
-      bun: "./src/bun.ts",
-      default: "./src/node.ts",
+    expect(packageJson.exports).toEqual({
+      ".": {
+        bun: "./src/bun.ts",
+        default: "./src/node.ts",
+      },
+      "./effect": {
+        bun: "./src/effect-bun.ts",
+        default: "./src/effect-node.ts",
+      },
+      "./testing": "./src/testing.ts",
+      "./daemon-bun": "./src/daemon-bun.ts",
     });
-    expect(packageJson.exports["./effect"]).toBe("./src/effect.ts");
-    expect(packageJson.exports["./bun"]).toBeUndefined();
-    expect(packageJson.exports["./node"]).toBeUndefined();
+    expect(packageJson.exports["./daemon-node"]).toBeUndefined();
     expect(packageJson.exports["./internals"]).toBeUndefined();
+    expect(packageJson.knip.entry).toContain("src/daemon-node.ts");
+  });
+
+  it("keeps the root runtime surface Promise-only", () => {
+    expect(Object.keys(nodeRoot).sort()).toEqual(["createStack", "prefetch"]);
+    expect(Object.keys(bunRoot).sort()).toEqual(["createStack", "prefetch"]);
+    expectTypeOf(nodeRoot.createStack).returns.toEqualTypeOf<Promise<StackHandle>>();
+    expectTypeOf(bunRoot.createStack).returns.toEqualTypeOf<Promise<StackHandle>>();
+  });
+
+  it("binds consumer Effect layers without exposing implementation tags", () => {
+    for (const entrypoint of [nodeEffect, bunEffect]) {
+      expect(entrypoint).toHaveProperty("connectLayer");
+      expect(entrypoint).toHaveProperty("daemonLayer");
+      expect(entrypoint).toHaveProperty("foregroundLayer");
+      expect(entrypoint).toHaveProperty("unixHttpClientLayer");
+      for (const name of INTERNAL_EFFECT_EXPORTS) {
+        expect(entrypoint).not.toHaveProperty(name);
+      }
+    }
+  });
+
+  it("isolates consumer test seams in the testing entry", () => {
+    expect(Object.keys(testing).sort()).toEqual(["DaemonServer", "UnixHttpClient"]);
   });
 });
diff --git a/packages/stack/src/index.ts b/packages/stack/src/index.ts
index 4b238c07b8..3969233f6f 100644
--- a/packages/stack/src/index.ts
+++ b/packages/stack/src/index.ts
@@ -32,4 +32,3 @@ export type {
   ResolvedFunction,
   ResolvedFunctionsBundle,
 } from "./functions.ts";
-export { UnixHttpClient, UnixHttpClientError } from "./UnixHttpClient.ts";
diff --git a/packages/stack/src/node.ts b/packages/stack/src/node.ts
index aedf7ab1f1..8be38e7ce1 100644
--- a/packages/stack/src/node.ts
+++ b/packages/stack/src/node.ts
@@ -1,145 +1,23 @@
 import { NodeServices } from "@effect/platform-node";
-import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer";
-import { createServer } from "node:http";
-import * as Http from "node:http";
-import { Readable } from "node:stream";
-import { fileURLToPath } from "node:url";
 import { Effect, Layer } from "effect";
 import { FetchHttpClient } from "effect/unstable/http";
 import { BinaryResolver } from "./BinaryResolver.ts";
-import {
-  createStack as createStackCore,
-  type PlatformFactory,
-  type StackHandle,
-} from "./createStack.ts";
+import { createStack as createStackCore, type StackHandle } from "./createStack.ts";
 import {
   prefetch as prefetchEffect,
   type PrefetchOptions,
   type PrefetchResult,
 } from "./prefetch.ts";
 import { defaultCacheRoot } from "./paths.ts";
+import { platformFactory } from "./platform-node.ts";
 import { StackPreparation } from "./StackPreparation.ts";
 import type { StackConfig } from "./StackConfig.ts";
-import { UnixHttpClient, UnixHttpClientError } from "./UnixHttpClient.ts";
-
-const mergeBodyHeaders = (
-  headersInit: RequestInit["headers"] | undefined,
-  bodyHeaders: Headers,
-): Headers => {
-  const headers = new Headers(headersInit);
-  for (const [key, value] of bodyHeaders.entries()) {
-    if (!headers.has(key)) {
-      headers.set(key, value);
-    }
-  }
-  return headers;
-};
-
-const toOutgoingHeaders = (headers: Headers): Http.OutgoingHttpHeaders =>
-  Object.fromEntries(headers.entries());
-
-const toResponseHeaders = (headers: Http.IncomingHttpHeaders): Headers => {
-  const responseHeaders = new Headers();
-  for (const [key, value] of Object.entries(headers)) {
-    if (value === undefined) {
-      continue;
-    }
-    if (Array.isArray(value)) {
-      for (const item of value) {
-        responseHeaders.append(key, item);
-      }
-      continue;
-    }
-    responseHeaders.set(key, value);
-  }
-  return responseHeaders;
-};
-
-const encodeRequest = async (
-  init: RequestInit | undefined,
-): Promise<{
-  readonly body: Uint8Array | undefined;
-  readonly headers: Http.OutgoingHttpHeaders;
-}> => {
-  if (init?.body == null) {
-    return {
-      body: undefined,
-      headers: toOutgoingHeaders(new Headers(init?.headers)),
-    };
-  }
-
-  const bodyResponse = new Response(init.body);
-  const headers = mergeBodyHeaders(init.headers, bodyResponse.headers);
-  return {
-    body: new Uint8Array(await bodyResponse.arrayBuffer()),
-    headers: toOutgoingHeaders(headers),
-  };
-};
-
-const toWebResponse = (response: Http.IncomingMessage): Response =>
-  new Response(
-    response.statusCode === 204 || response.statusCode === 304 ? null : Readable.toWeb(response),
-    {
-      status: response.statusCode ?? 200,
-      statusText: response.statusMessage ?? "",
-      headers: toResponseHeaders(response.headers),
-    },
-  );
-
-export const unixHttpClientLayer = Layer.succeed(UnixHttpClient, {
-  request: (socketPath, path, init) =>
-    Effect.tryPromise({
-      try: async () => {
-        const { body, headers } = await encodeRequest(init);
-        return await new Promise<Response>((resolve, reject) => {
-          const request = Http.request(
-            {
-              socketPath,
-              path,
-              method: init?.method ?? "GET",
-              headers,
-              signal: init?.signal ?? undefined,
-            },
-            (response) => {
-              resolve(toWebResponse(response));
-            },
-          );
-
-          request.on("error", reject);
-          request.end(body);
-        });
-      },
-      catch: (cause) => new UnixHttpClientError({ socketPath, path, cause }),
-    }),
-});
-
-// ---------------------------------------------------------------------------
-// Platform values — for use with Effect layer factories
-// ---------------------------------------------------------------------------
-
-/** Node platform factory for use with foregroundLayer / daemonLayer. */
-export const platformFactory: PlatformFactory = ({ apiPort, releaseApiPort }) =>
-  Layer.mergeAll(
-    NodeServices.layer,
-    Layer.unwrap(
-      releaseApiPort.pipe(
-        Effect.as(NodeHttpServer.layer(() => createServer(), { port: apiPort }).pipe(Layer.orDie)),
-      ),
-    ),
-  );
 
 /**
- * Path to the Node daemon entry point for use with daemonLayer.
- *
- * `daemon-node.ts` is intentionally reached by this file URL instead of a package export. Keep the
- * matching `knip.entry` in package.json when changing this path; static import analysis cannot see
- * the child-process entrypoint.
+ * The Node daemon bootstrap is deliberately not exported from the package. The conditional Effect
+ * entry resolves `daemon-node.ts` by file URL through the internal platform adapter. Keep
+ * `src/daemon-node.ts` in package.json's `knip.entry` list: static imports cannot see that fork target.
  */
-export const daemonEntryPoint: string = fileURLToPath(new URL("./daemon-node.ts", import.meta.url));
-
-// ---------------------------------------------------------------------------
-// Promise API — convenience wrappers for non-Effect consumers
-// ---------------------------------------------------------------------------
 
 export async function createStack(config?: StackConfig): Promise<StackHandle> {
   return createStackCore(config, platformFactory);
diff --git a/packages/stack/src/platform-bun.ts b/packages/stack/src/platform-bun.ts
new file mode 100644
index 0000000000..96d6252165
--- /dev/null
+++ b/packages/stack/src/platform-bun.ts
@@ -0,0 +1,30 @@
+import { BunServices } from "@effect/platform-bun";
+import * as BunHttpServer from "@effect/platform-bun/BunHttpServer";
+import { fileURLToPath } from "node:url";
+import { Effect, Layer } from "effect";
+import type { PlatformFactory } from "./createStack.ts";
+import { UnixHttpClient, UnixHttpClientError } from "./UnixHttpClient.ts";
+
+interface BunUnixRequestInit extends RequestInit {
+  readonly unix: string;
+}
+
+export const unixHttpClientLayer = Layer.succeed(UnixHttpClient, {
+  request: (socketPath, path, init) =>
+    Effect.tryPromise({
+      try: () => {
+        const requestInit: BunUnixRequestInit = { ...init, unix: socketPath };
+        return fetch(`http://localhost${path}`, requestInit);
+      },
+      catch: (cause) => new UnixHttpClientError({ socketPath, path, cause }),
+    }),
+});
+
+export const platformFactory: PlatformFactory = ({ apiPort, releaseApiPort }) =>
+  Layer.mergeAll(
+    BunServices.layer,
+    Layer.unwrap(releaseApiPort.pipe(Effect.as(BunHttpServer.layer({ port: apiPort })))),
+  );
+
+/** Internal source-mode child target. Compiled CLI dispatch still uses the daemon-bun export. */
+export const daemonEntryPoint = fileURLToPath(new URL("./daemon-bun.ts", import.meta.url));
diff --git a/packages/stack/src/platform-node.ts b/packages/stack/src/platform-node.ts
new file mode 100644
index 0000000000..bdcc9c85b3
--- /dev/null
+++ b/packages/stack/src/platform-node.ts
@@ -0,0 +1,109 @@
+import { NodeServices } from "@effect/platform-node";
+import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer";
+import { createServer } from "node:http";
+import * as Http from "node:http";
+import { Readable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { Effect, Layer } from "effect";
+import type { PlatformFactory } from "./createStack.ts";
+import { UnixHttpClient, UnixHttpClientError } from "./UnixHttpClient.ts";
+
+const mergeBodyHeaders = (
+  headersInit: RequestInit["headers"] | undefined,
+  bodyHeaders: Headers,
+): Headers => {
+  const headers = new Headers(headersInit);
+  for (const [key, value] of bodyHeaders.entries()) {
+    if (!headers.has(key)) {
+      headers.set(key, value);
+    }
+  }
+  return headers;
+};
+
+const toOutgoingHeaders = (headers: Headers): Http.OutgoingHttpHeaders =>
+  Object.fromEntries(headers.entries());
+
+const toResponseHeaders = (headers: Http.IncomingHttpHeaders): Headers => {
+  const responseHeaders = new Headers();
+  for (const [key, value] of Object.entries(headers)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) responseHeaders.append(key, item);
+      continue;
+    }
+    responseHeaders.set(key, value);
+  }
+  return responseHeaders;
+};
+
+const encodeRequest = async (
+  init: RequestInit | undefined,
+): Promise<{
+  readonly body: Uint8Array | undefined;
+  readonly headers: Http.OutgoingHttpHeaders;
+}> => {
+  if (init?.body == null) {
+    return {
+      body: undefined,
+      headers: toOutgoingHeaders(new Headers(init?.headers)),
+    };
+  }
+
+  const bodyResponse = new Response(init.body);
+  const headers = mergeBodyHeaders(init.headers, bodyResponse.headers);
+  return {
+    body: new Uint8Array(await bodyResponse.arrayBuffer()),
+    headers: toOutgoingHeaders(headers),
+  };
+};
+
+const toWebResponse = (response: Http.IncomingMessage): Response =>
+  new Response(
+    response.statusCode === 204 || response.statusCode === 304 ? null : Readable.toWeb(response),
+    {
+      status: response.statusCode ?? 200,
+      statusText: response.statusMessage ?? "",
+      headers: toResponseHeaders(response.headers),
+    },
+  );
+
+export const unixHttpClientLayer = Layer.succeed(UnixHttpClient, {
+  request: (socketPath, path, init) =>
+    Effect.tryPromise({
+      try: async () => {
+        const { body, headers } = await encodeRequest(init);
+        return await new Promise<Response>((resolve, reject) => {
+          const request = Http.request(
+            {
+              socketPath,
+              path,
+              method: init?.method ?? "GET",
+              headers,
+              signal: init?.signal ?? undefined,
+            },
+            (response) => {
+              resolve(toWebResponse(response));
+            },
+          );
+
+          request.on("error", reject);
+          request.end(body);
+        });
+      },
+      catch: (cause) => new UnixHttpClientError({ socketPath, path, cause }),
+    }),
+});
+
+export const platformFactory: PlatformFactory = ({ apiPort, releaseApiPort }) =>
+  Layer.mergeAll(
+    NodeServices.layer,
+    Layer.unwrap(
+      releaseApiPort.pipe(
+        Effect.as(NodeHttpServer.layer(() => createServer(), { port: apiPort }).pipe(Layer.orDie)),
+      ),
+    ),
+  );
+
+/** Internal child-process target. It is intentionally absent from package exports. */
+export const daemonEntryPoint = fileURLToPath(new URL("./daemon-node.ts", import.meta.url));
diff --git a/packages/stack/src/testing.ts b/packages/stack/src/testing.ts
new file mode 100644
index 0000000000..206459eeeb
--- /dev/null
+++ b/packages/stack/src/testing.ts
@@ -0,0 +1,3 @@
+/** Test-only service tags for building deterministic consumer layers. */
+export { DaemonServer } from "./DaemonServer.ts";
+export { UnixHttpClient } from "./UnixHttpClient.ts";

From 5ca2c1b4002ee1919c1e974afed0fbc8eb0902f7 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 18:45:18 +0200
Subject: [PATCH 09/44] chore(process-compose): reconcile updated lifecycle
 imports

---
 packages/process-compose/src/Orchestrator.ts | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/packages/process-compose/src/Orchestrator.ts b/packages/process-compose/src/Orchestrator.ts
index 36da54a34e..f23de210b9 100644
--- a/packages/process-compose/src/Orchestrator.ts
+++ b/packages/process-compose/src/Orchestrator.ts
@@ -18,11 +18,6 @@ import { buildGraph, type ResolvedGraph } from "./DependencyGraph.ts";
 import { type HealthProbeCallbacks, runHealthProbe } from "./HealthProbe.ts";
 import { LogBuffer } from "./LogBuffer.ts";
 import { restartClosureFor } from "./RestartClosure.ts";
-import {
-  decideRestart,
-  type LifecycleCause,
-  UNHEALTHY_RESTART_EXHAUSTED_ERROR,
-} from "./RestartDecision.ts";
 import type {
   HookTrigger,
   OrchestratorConfig,

From 55f8013a7a7c16cc3020a1d58dc4da027127334e Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 18:52:52 +0200
Subject: [PATCH 10/44] test(stack): make partial startup cleanup deterministic

---
 packages/stack/src/Stack.unit.test.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/stack/src/Stack.unit.test.ts b/packages/stack/src/Stack.unit.test.ts
index c77a5fc9cf..49612b42b1 100644
--- a/packages/stack/src/Stack.unit.test.ts
+++ b/packages/stack/src/Stack.unit.test.ts
@@ -427,7 +427,7 @@ describe("Stack", () => {
         {
           name: "postgrest",
           command: "fail",
-          dependencies: [{ service: "postgres", condition: "healthy" }],
+          dependencies: [{ service: "postgres", condition: "started" }],
           restart: "no",
         },
       ]),
@@ -448,7 +448,7 @@ describe("Stack", () => {
     const layer = localStackLayer(
       {
         ...defaultConfig,
-        readiness: { mode: "finite", timeoutMs: 100 },
+        readiness: { mode: "finite", timeoutMs: 1_000 },
       },
       noopPortLease(defaultConfig.ports),
     ).pipe(
@@ -466,7 +466,7 @@ describe("Stack", () => {
       expect(Exit.isFailure(exit)).toBe(true);
       expect(cleaned).toBe(true);
       expect(spawner.killed).toContain("SIGTERM");
-    }).pipe(Effect.provide(layer), Effect.timeout("2 seconds"));
+    }).pipe(Effect.provide(layer), Effect.timeout("5 seconds"));
   });
 
   it.live("lazy startup starts direct services without starting HTTP backends", () => {

From 8e2ed7639a478129ec35313f636bcc4a0aa16204 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 19:57:35 +0200
Subject: [PATCH 11/44] fix(process-compose): handle terminal health failures

---
 packages/process-compose/src/Orchestrator.ts  | 13 +++-
 .../src/Orchestrator.unit.test.ts             | 77 +++++++++++++++++++
 .../tests/createStack-docker.e2e.test.ts      |  7 +-
 3 files changed, 93 insertions(+), 4 deletions(-)

diff --git a/packages/process-compose/src/Orchestrator.ts b/packages/process-compose/src/Orchestrator.ts
index dac79485c7..782fbd169b 100644
--- a/packages/process-compose/src/Orchestrator.ts
+++ b/packages/process-compose/src/Orchestrator.ts
@@ -234,9 +234,16 @@ export class Orchestrator extends Context.Service<
                   const completed = yield* waitForState(
                     dependency,
                     (state) =>
-                      state.exitCode !== null &&
-                      (state.status === "Stopped" || state.status === "Failed"),
+                      state.status === "Failed" ||
+                      (state.status === "Stopped" && state.exitCode !== null),
                   );
+                  if (completed.status === "Failed") {
+                    yield* sendEvent(def.name, {
+                      _tag: "DependencyFailed",
+                      error: `Dependency ${depDef.name} failed: ${completed.error ?? "unknown failure"}`,
+                    });
+                    return;
+                  }
                   if (completed.exitCode !== 0) {
                     yield* sendEvent(def.name, {
                       _tag: "DependencyFailed",
@@ -384,7 +391,7 @@ export class Orchestrator extends Context.Service<
                           const service = services.get(def.name);
                           if (service === undefined) return;
                           const current = SubscriptionRef.getUnsafe(service.state);
-                          if (current.status === "Running") {
+                          if (current.status === "Running" || current.status === "Unhealthy") {
                             const healthyHookError = yield* runHooks(def, "healthy");
                             if (healthyHookError !== null) {
                               yield* Deferred.succeed(generationResult, {
diff --git a/packages/process-compose/src/Orchestrator.unit.test.ts b/packages/process-compose/src/Orchestrator.unit.test.ts
index f2a5f98eb4..5bf69eb3df 100644
--- a/packages/process-compose/src/Orchestrator.unit.test.ts
+++ b/packages/process-compose/src/Orchestrator.unit.test.ts
@@ -1172,6 +1172,39 @@ describe("Orchestrator", () => {
         expect(state.error).toContain("Timed out");
       }).pipe(Effect.provide(layer), Effect.scoped);
     });
+
+    it.live("completed dependency fails immediately when health restarts are exhausted", () => {
+      const { layer } = setupOrchestrator(
+        [
+          svc("setup", {
+            restart: "always",
+            maxRestarts: 1,
+            healthCheck: {
+              probe: { _tag: "Exec", command: "check", args: [] },
+              periodSeconds: 0.01,
+              startupFailureThreshold: 1,
+              failureThreshold: 1,
+            },
+          }),
+          svc("app", {
+            restart: "no",
+            dependencies: [{ service: "setup", condition: "completed" }],
+            dependencyTimeoutSeconds: 5,
+          }),
+        ],
+        {
+          exitDelay: "5 seconds",
+          perService: { check: { exitCode: 1, exitDelay: "1 millis" } },
+        },
+      );
+      return Effect.gen(function* () {
+        const orc = yield* Orchestrator;
+        yield* orc.start();
+        const state = yield* waitForFailed(orc, "app");
+        expect(state.error).toContain("Dependency setup failed");
+        expect(state.error).not.toContain("Timed out");
+      }).pipe(Effect.provide(layer), Effect.scoped);
+    });
   });
 
   describe("failure diagnostics", () => {
@@ -1271,6 +1304,50 @@ describe("Orchestrator", () => {
       }).pipe(Effect.provide(layer), Effect.scoped);
     });
 
+    it.live("runs on:healthy hook when an unhealthy service recovers", () => {
+      let checkCalls = 0;
+      let healthyHookRuns = 0;
+      const { layer } = setupOrchestrator(
+        [
+          svc("a", {
+            restart: "no",
+            healthCheck: {
+              probe: { _tag: "Exec", command: "check", args: [] },
+              periodSeconds: 0.01,
+              startupFailureThreshold: 1,
+              successThreshold: 1,
+              failureThreshold: 1,
+            },
+            hooks: [
+              {
+                on: "healthy",
+                run: () =>
+                  Effect.sync(() => {
+                    healthyHookRuns++;
+                  }),
+              },
+            ],
+          }),
+        ],
+        {
+          exitDelay: "5 seconds",
+          perService: {
+            check: {
+              exitDelay: "1 millis",
+              getExitCode: () => (++checkCalls === 1 ? 1 : 0),
+            },
+          },
+        },
+      );
+      return Effect.gen(function* () {
+        const orc = yield* Orchestrator;
+        yield* orc.start();
+        yield* waitForState(orc, "a", (state) => state.status === "Unhealthy", "Unhealthy");
+        yield* waitForHealthy(orc, "a");
+        expect(healthyHookRuns).toBe(1);
+      }).pipe(Effect.provide(layer), Effect.scoped);
+    });
+
     it.live("dependent waits for on:started hook to complete before starting", () => {
       const order: string[] = [];
       const { layer } = setupOrchestrator(
diff --git a/packages/stack/tests/createStack-docker.e2e.test.ts b/packages/stack/tests/createStack-docker.e2e.test.ts
index 0cba048b0b..1ab035c20b 100644
--- a/packages/stack/tests/createStack-docker.e2e.test.ts
+++ b/packages/stack/tests/createStack-docker.e2e.test.ts
@@ -32,6 +32,7 @@ dockerDescribe("createStack e2e (docker mode)", () => {
 
     stack = await createStack({
       mode: "docker",
+      startupMode: "lazy",
       jwtSecret: "super-secret-jwt-token-with-at-least-32-characters-long",
       postgres: { dataDir },
       analytics: {},
@@ -111,7 +112,11 @@ dockerDescribe("createStack e2e (docker mode)", () => {
     },
   );
 
-  test("cold-starts analytics through lazy service activation", { timeout: 60_000 }, async () => {
+  test("cold-starts analytics through lazy service activation", { timeout: 180_000 }, async () => {
+    expect(await stack.getServiceStatus("analytics")).toEqual(
+      expect.objectContaining({ status: "Dormant" }),
+    );
+
     await stack.startService("analytics");
 
     const [runningImages, states] = await Promise.all([

From 57979d5cdb09bb062a180b4caf1e2e80a42e4632 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 20:01:16 +0200
Subject: [PATCH 12/44] fix(process-compose): bound supervisor cleanup commands

---
 packages/process-compose/docs/architecture.md |  8 +--
 .../src/SupervisorRuntime.unit.test.ts        | 54 ++++++++++++++++++-
 .../process-compose/src/supervisor-runtime.ts |  5 +-
 3 files changed, 62 insertions(+), 5 deletions(-)

diff --git a/packages/process-compose/docs/architecture.md b/packages/process-compose/docs/architecture.md
index b9845b8300..4cb0c4ae17 100644
--- a/packages/process-compose/docs/architecture.md
+++ b/packages/process-compose/docs/architecture.md
@@ -219,9 +219,11 @@ In-process cleanup and orphan supervision solve different failure modes:
   managed child exits while cleanup is configured.
 
 `ExternalCleanupAction` supports a shell-free `RunCommand` with an executable, argument array, and
-optional timeout, plus `RemovePath` for filesystem cleanup. The supervisor rejects a malformed
-decoded cleanup contract before spawning the child, while individual execution failures remain
-best-effort. Callers must choose idempotent commands because owner-loss signals can race.
+optional timeout (default 5 seconds), plus `RemovePath` for filesystem cleanup. Cleanup commands
+receive the managed child's sanitized environment, without the supervisor self-dispatch protocol
+variables. The supervisor rejects a malformed decoded cleanup contract before spawning the child,
+while individual execution failures remain best-effort. Callers must choose idempotent commands
+because owner-loss signals can race.
 
 ## Supervisor runtime
 
diff --git a/packages/process-compose/src/SupervisorRuntime.unit.test.ts b/packages/process-compose/src/SupervisorRuntime.unit.test.ts
index ce4fee52d5..7e3e780a05 100644
--- a/packages/process-compose/src/SupervisorRuntime.unit.test.ts
+++ b/packages/process-compose/src/SupervisorRuntime.unit.test.ts
@@ -74,6 +74,7 @@ describe("supervisor-runtime", () => {
       const tempDir = mkdtempSync(path.join(tmpdir(), "process-compose-supervisor-"));
       const cleanupDir = path.join(tempDir, "cleanup-dir");
       const cleanupMarker = path.join(tempDir, "cleanup-command-ran");
+      const cleanupEnvironmentMarker = path.join(tempDir, "cleanup-environment.json");
       const childPidFile = path.join(tempDir, "child.pid");
       const grandchildPidFile = path.join(tempDir, "grandchild.pid");
       const readyFile = path.join(tempDir, "ready");
@@ -108,9 +109,18 @@ describe("supervisor-runtime", () => {
               executable: process.execPath,
               args: [
                 "-e",
-                `require("node:fs").writeFileSync(process.argv[1], process.argv[2])`,
+                [
+                  `const { writeFileSync } = require("node:fs");`,
+                  `writeFileSync(process.argv[1], process.argv[2]);`,
+                  `writeFileSync(process.argv[3], JSON.stringify({`,
+                  `  run: process.env.PROCESS_COMPOSE_RUN_SUPERVISOR,`,
+                  `  config: process.env.PROCESS_COMPOSE_SUPERVISOR_CONFIG,`,
+                  `  dispatch: process.env.PROCESS_COMPOSE_SUPERVISOR_SELF_DISPATCH,`,
+                  `}));`,
+                ].join("\n"),
                 cleanupMarker,
                 "literal; $(not-run) & value",
+                cleanupEnvironmentMarker,
               ],
             },
           ],
@@ -131,6 +141,7 @@ describe("supervisor-runtime", () => {
         await waitFor(() => !existsSync(cleanupDir), { timeoutMs: 10_000 });
         await waitFor(() => existsSync(cleanupMarker), { timeoutMs: 10_000 });
         expect(readFileSync(cleanupMarker, "utf8")).toBe("literal; $(not-run) & value");
+        expect(JSON.parse(readFileSync(cleanupEnvironmentMarker, "utf8"))).toEqual({});
         await waitFor(() => !isPidAlive(childPid), { timeoutMs: 10_000 });
         await waitFor(() => !isPidAlive(grandchildPid), { timeoutMs: 10_000 });
       } finally {
@@ -217,6 +228,47 @@ describe("supervisor-runtime", () => {
     }
   });
 
+  test("bounds a cleanup command when no timeout is configured", { timeout: 12_000 }, async () => {
+    const tempDir = mkdtempSync(path.join(tmpdir(), "process-compose-supervisor-timeout-"));
+    const cleanupDir = path.join(tempDir, "cleanup-dir");
+    const cleanupPidFile = path.join(tempDir, "cleanup.pid");
+    const childScriptPath = path.join(tempDir, "child.mjs");
+    mkdirSync(cleanupDir);
+    writeFileSync(childScriptPath, "process.exit(0);\n");
+    const encodedConfig = Buffer.from(
+      JSON.stringify({
+        command: process.execPath,
+        args: [childScriptPath],
+        cleanup: [
+          {
+            _tag: "RunCommand",
+            executable: process.execPath,
+            args: [
+              "-e",
+              `require("node:fs").writeFileSync(${JSON.stringify(cleanupPidFile)}, String(process.pid)); setInterval(() => {}, 1000)`,
+            ],
+          },
+          { _tag: "RemovePath", path: cleanupDir, recursive: true },
+        ],
+      }),
+    ).toString("base64url");
+    const supervisor = spawnSupervisor("source path", encodedConfig);
+
+    try {
+      await waitFor(() => supervisor.exitCode != null, { timeoutMs: 8_000 });
+      expect(supervisor.exitCode).toBe(0);
+      expect(existsSync(cleanupDir)).toBe(false);
+    } finally {
+      supervisor.kill("SIGKILL");
+      if (existsSync(cleanupPidFile)) {
+        try {
+          process.kill(Number.parseInt(readFileSync(cleanupPidFile, "utf8"), 10), "SIGKILL");
+        } catch {}
+      }
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
   test(
     "runs orphan cleanup when the configured owner pid is already gone",
     { timeout: 15_000 },
diff --git a/packages/process-compose/src/supervisor-runtime.ts b/packages/process-compose/src/supervisor-runtime.ts
index 3069796d54..5dc2af51ae 100644
--- a/packages/process-compose/src/supervisor-runtime.ts
+++ b/packages/process-compose/src/supervisor-runtime.ts
@@ -24,6 +24,8 @@ interface ChildExit {
   readonly signal: NodeJS.Signals | null;
 }
 
+const DEFAULT_CLEANUP_COMMAND_TIMEOUT_MS = 5_000;
+
 const isMain = (() => {
   if (process.argv[1] == null) {
     return false;
@@ -278,8 +280,9 @@ export function runSupervisorRuntime(encodedConfig = process.argv[2]): void {
         try {
           if (action._tag === "RunCommand") {
             execFileSync(action.executable, action.args, {
+              env: childEnv,
               stdio: "ignore",
-              timeout: action.timeoutMs,
+              timeout: action.timeoutMs ?? DEFAULT_CLEANUP_COMMAND_TIMEOUT_MS,
             });
           } else if (action._tag === "RemovePath") {
             await removePathWithRetry(action);

From 3817fcdc7ed4292a182fbe76cc4e9f42e7232a29 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 20:19:50 +0200
Subject: [PATCH 13/44] fix(stack): scope readiness deadlines to health waits

---
 packages/process-compose/src/Orchestrator.ts  | 130 ++++++++++--------
 .../src/Orchestrator.unit.test.ts             | 102 +++++++++++++-
 packages/stack/README.md                      |   2 +-
 packages/stack/docs/architecture.md           |   2 +-
 packages/stack/src/LocalStack.ts              |  56 ++++----
 packages/stack/src/Stack.unit.test.ts         |  45 ++++--
 packages/stack/src/StackConfig.ts             |   4 +-
 packages/stack/src/StackConfig.unit.test.ts   |  10 +-
 packages/stack/src/StackStateProjection.ts    |  15 +-
 .../src/StackStateProjection.unit.test.ts     |  19 +++
 packages/stack/src/createStack.unit.test.ts   |   2 +-
 11 files changed, 270 insertions(+), 117 deletions(-)

diff --git a/packages/process-compose/src/Orchestrator.ts b/packages/process-compose/src/Orchestrator.ts
index b183acdec6..782fbd169b 100644
--- a/packages/process-compose/src/Orchestrator.ts
+++ b/packages/process-compose/src/Orchestrator.ts
@@ -17,10 +17,14 @@ import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import { buildGraph, type ResolvedGraph } from "./DependencyGraph.ts";
 import { type HealthProbeCallbacks, runHealthProbe } from "./HealthProbe.ts";
 import { LogBuffer } from "./LogBuffer.ts";
+import {
+  decideRestart,
+  type LifecycleCause,
+  UNHEALTHY_RESTART_EXHAUSTED_ERROR,
+} from "./RestartDecision.ts";
 import type {
   HookTrigger,
   OrchestratorConfig,
-  RestartPolicy,
   ServiceDef,
   ServiceStartOptions,
 } from "./ServiceDef.ts";
@@ -156,7 +160,7 @@ export class Orchestrator extends Context.Service<
           );
 
         // Helper: run all hooks for a given trigger in sequence
-        const runHooks = (def: ServiceDef, trigger: HookTrigger): Effect.Effect<void> =>
+        const runHooks = (def: ServiceDef, trigger: HookTrigger): Effect.Effect<string | null> =>
           Effect.gen(function* () {
             const hooks = (def.hooks ?? []).filter((h) => h.on === trigger);
             for (const hook of hooks) {
@@ -167,11 +171,7 @@ export class Orchestrator extends Context.Service<
                 .run(log)
                 .pipe(Effect.timeout(Duration.seconds(timeout)), Effect.exit);
               if (Exit.isFailure(result) && (hook.failurePolicy ?? "fail") === "fail") {
-                yield* sendEvent(def.name, {
-                  _tag: "HookFailed",
-                  error: `Hook (on:${trigger}) failed: ${Cause.pretty(result.cause)}`,
-                });
-                return;
+                return `Hook (on:${trigger}) failed: ${Cause.pretty(result.cause)}`;
               }
               if (Exit.isFailure(result)) {
                 yield* logBuffer.append(
@@ -181,13 +181,13 @@ export class Orchestrator extends Context.Service<
                 );
               }
             }
+            return null;
           });
 
         type SpawnResult =
-          | { readonly _tag: "Exited"; readonly exitCode: number }
-          | { readonly _tag: "UnhealthyRestart" };
-
-        const shouldRestartOnUnhealthy = (policy: RestartPolicy): boolean => policy !== "no";
+          | { readonly _tag: "ProcessExit"; readonly exitCode: number }
+          | { readonly _tag: "Unhealthy" }
+          | { readonly _tag: "HookFailed"; readonly error: string };
 
         // The full lifecycle loop for a single service
         const runService = (
@@ -269,7 +269,7 @@ export class Orchestrator extends Context.Service<
             const spawnOnce = (): Effect.Effect<SpawnResult, SpawnError> =>
               Effect.scoped(
                 Effect.gen(function* () {
-                  const unhealthyRestart = Deferred.makeUnsafe<void>();
+                  const generationResult = Deferred.makeUnsafe<SpawnResult>();
                   const supervised = usesSupervisor(def);
 
                   // Build command
@@ -350,12 +350,9 @@ export class Orchestrator extends Context.Service<
 
                   // Keep the service in Starting until its started hooks pass,
                   // so Running is the stable dependency signal.
-                  yield* runHooks(def, "started");
-                  const stateAfterStartedHooks = SubscriptionRef.getUnsafe(
-                    services.get(def.name)!.state,
-                  );
-                  if (stateAfterStartedHooks.status === "Failed") {
-                    return { _tag: "Exited", exitCode: 1 } as SpawnResult;
+                  const startedHookError = yield* runHooks(def, "started");
+                  if (startedHookError !== null) {
+                    return { _tag: "HookFailed", error: startedHookError };
                   }
                   yield* sendEvent(def.name, {
                     _tag: "ProcessSpawned",
@@ -414,8 +411,8 @@ export class Orchestrator extends Context.Service<
                             `[health-check-failed] Service "${def.name}" became unhealthy. Recent output:`,
                             `[health-check-failed] Service "${def.name}" became unhealthy (no recent log output).`,
                           );
-                          if (shouldRestartOnUnhealthy(restartPolicy)) {
-                            yield* Deferred.succeed(unhealthyRestart, void 0);
+                          if (restartPolicy !== "no") {
+                            yield* Deferred.succeed(generationResult, { _tag: "Unhealthy" });
                           }
                         }),
                     };
@@ -428,14 +425,11 @@ export class Orchestrator extends Context.Service<
                       Effect.forkChild,
                     );
                   } else {
-                    yield* runHooks(def, "healthy");
-                    const service = services.get(def.name);
-                    if (
-                      service !== undefined &&
-                      SubscriptionRef.getUnsafe(service.state).status !== "Failed"
-                    ) {
-                      yield* sendEvent(def.name, { _tag: "HealthCheckPassed" });
+                    const healthyHookError = yield* runHooks(def, "healthy");
+                    if (healthyHookError !== null) {
+                      return { _tag: "HookFailed", error: healthyHookError };
                     }
+                    yield* sendEvent(def.name, { _tag: "HealthCheckPassed" });
                   }
 
                   // Race process exit against unhealthy restart signal.
@@ -444,11 +438,11 @@ export class Orchestrator extends Context.Service<
                   // as exit code 143 (128 + SIGTERM).
                   const waitForExit = handle.exitCode.pipe(
                     Effect.map(
-                      (code): SpawnResult => ({ _tag: "Exited", exitCode: code as number }),
+                      (code): SpawnResult => ({ _tag: "ProcessExit", exitCode: Number(code) }),
                     ),
                     Effect.catch(
                       (): Effect.Effect<SpawnResult> =>
-                        Effect.succeed({ _tag: "Exited", exitCode: 143 }),
+                        Effect.succeed({ _tag: "ProcessExit", exitCode: 143 }),
                     ),
                   );
                   const waitForObservedOneShotExit =
@@ -459,7 +453,7 @@ export class Orchestrator extends Context.Service<
                               Effect.timeout(Duration.millis(100)),
                               Effect.catch(
                                 (): Effect.Effect<SpawnResult> =>
-                                  Effect.succeed({ _tag: "Exited", exitCode: 0 }),
+                                  Effect.succeed({ _tag: "ProcessExit", exitCode: 0 }),
                               ),
                             ),
                           ),
@@ -469,9 +463,7 @@ export class Orchestrator extends Context.Service<
                   return yield* Effect.raceAll([
                     waitForExit,
                     waitForObservedOneShotExit,
-                    Deferred.await(unhealthyRestart).pipe(
-                      Effect.map((): SpawnResult => ({ _tag: "UnhealthyRestart" })),
-                    ),
+                    Deferred.await(generationResult),
                   ]);
                 }),
               );
@@ -491,7 +483,7 @@ export class Orchestrator extends Context.Service<
             // Handle spawn result
             const handleResult = (r: SpawnResult) =>
               Effect.gen(function* () {
-                if (r._tag === "Exited") {
+                if (r._tag === "ProcessExit") {
                   if (r.exitCode !== 0 && r.exitCode !== 143) {
                     yield* appendRecentServiceLogs(
                       def.name,
@@ -500,27 +492,39 @@ export class Orchestrator extends Context.Service<
                     );
                   }
                   yield* sendEvent(def.name, { _tag: "ProcessExited", exitCode: r.exitCode });
+                } else if (r._tag === "HookFailed") {
+                  yield* sendEvent(def.name, { _tag: "HookFailed", error: r.error });
+                } else {
+                  yield* sendEvent(def.name, { _tag: "ProcessTerminated" });
                 }
-                // UnhealthyRestart: process killed by scope closure, skip ProcessExited
+                // Unhealthy is already recorded by the probe. Scope finalization
+                // terminates its process without inventing a process exit code.
               });
             yield* handleResult(result);
 
-            // Restart loop
-            const shouldRestart = (r: SpawnResult): boolean => {
+            const restartDecision = (r: SpawnResult) => {
               const svc = services.get(def.name);
-              if (svc === undefined || SubscriptionRef.getUnsafe(svc.state).desired !== "running") {
-                return false;
+              const desired =
+                svc === undefined ? "inactive" : SubscriptionRef.getUnsafe(svc.state).desired;
+              if (r._tag === "HookFailed") {
+                return { _tag: "Terminate", reason: "PolicyDisabled" } as const;
               }
-              if (r._tag === "UnhealthyRestart") return true;
-              if (restartPolicy === "no") return false;
-              if (restartPolicy === "always") return true;
-              if (restartPolicy === "unless-stopped") return true;
-              if (restartPolicy === "on-failure") return r.exitCode !== 0;
-              return false;
+              const cause: LifecycleCause =
+                r._tag === "ProcessExit"
+                  ? { _tag: "ProcessExit", exitCode: r.exitCode }
+                  : { _tag: "Unhealthy" };
+              return decideRestart({
+                cause,
+                policy: restartPolicy,
+                restartCount,
+                maxRestarts,
+                desired,
+              });
             };
 
-            while (shouldRestart(result) && (maxRestarts === 0 || restartCount < maxRestarts)) {
-              restartCount++;
+            let decision = restartDecision(result);
+            while (decision._tag === "Restart") {
+              restartCount = decision.restartCount;
 
               yield* sendEvent(def.name, { _tag: "RestartTriggered", restartCount });
 
@@ -528,7 +532,7 @@ export class Orchestrator extends Context.Service<
               // be reserved safely for the duration of this restart's backoff.
               yield* prepareStart();
 
-              if (result._tag === "UnhealthyRestart") {
+              if (result._tag === "Unhealthy") {
                 yield* appendRecentServiceLogs(
                   def.name,
                   `[restart] Service "${def.name}" is restarting after an unhealthy health check. Recent output:`,
@@ -546,6 +550,18 @@ export class Orchestrator extends Context.Service<
 
               result = yield* spawnOnce();
               yield* handleResult(result);
+              decision = restartDecision(result);
+            }
+
+            if (
+              result._tag === "Unhealthy" &&
+              decision._tag === "Terminate" &&
+              decision.reason === "BudgetExhausted"
+            ) {
+              yield* sendEvent(def.name, {
+                _tag: "UnhealthyRestartExhausted",
+                error: UNHEALTHY_RESTART_EXHAUSTED_ERROR,
+              });
             }
           });
 
@@ -607,13 +623,17 @@ export class Orchestrator extends Context.Service<
           Effect.suspend(() => {
             const svc = services.get(def.name);
             if (!svc) return Effect.void;
-            const restartPolicy = def.restart ?? defaults.restart;
-            const maxRestarts = def.maxRestarts ?? defaults.maxRestarts;
             const willRestartAfterExit = (state: ServiceState): boolean => {
-              if (state.desired !== "running" || state.exitCode === null) return false;
-              if (maxRestarts !== 0 && state.restartCount >= maxRestarts) return false;
-              if (restartPolicy === "always" || restartPolicy === "unless-stopped") return true;
-              return restartPolicy === "on-failure" && state.exitCode !== 0;
+              if (state.exitCode === null) return false;
+              return (
+                decideRestart({
+                  cause: { _tag: "ProcessExit", exitCode: state.exitCode },
+                  policy: def.restart ?? defaults.restart,
+                  restartCount: state.restartCount,
+                  maxRestarts: def.maxRestarts ?? defaults.maxRestarts,
+                  desired: state.desired,
+                })._tag === "Restart"
+              );
             };
 
             const current = SubscriptionRef.getUnsafe(svc.state);
@@ -637,7 +657,7 @@ export class Orchestrator extends Context.Service<
               );
             }
 
-            if (restartPolicy === "no") {
+            if ((def.restart ?? defaults.restart) === "no" && def.healthCheck == null) {
               return waitForState(
                 svc,
                 (state) => state.status === "Failed" || state.status === "Stopped",
diff --git a/packages/process-compose/src/Orchestrator.unit.test.ts b/packages/process-compose/src/Orchestrator.unit.test.ts
index f0a897bb8a..5bf69eb3df 100644
--- a/packages/process-compose/src/Orchestrator.unit.test.ts
+++ b/packages/process-compose/src/Orchestrator.unit.test.ts
@@ -1072,6 +1072,7 @@ describe("Orchestrator", () => {
       const state = yield* orc.getState("a");
       expect(state.status).toBe("Stopped");
       expect(state.exitCode).toBe(0);
+      expect(state.pid).toBeNull();
     }).pipe(Effect.provide(layer), Effect.scoped);
   });
 
@@ -1088,6 +1089,7 @@ describe("Orchestrator", () => {
       const state = yield* orc.getState("a");
       expect(state.status).toBe("Failed");
       expect(state.exitCode).toBe(1);
+      expect(state.pid).toBeNull();
       expect(log.entries.some((e) => e.line.includes("[process-exited]"))).toBe(true);
       expect(log.entries.some((e) => e.line.includes("about to fail"))).toBe(true);
     }).pipe(Effect.provide(layer), Effect.scoped);
@@ -1938,14 +1940,112 @@ describe("Orchestrator", () => {
         const orc = yield* Orchestrator;
         yield* orc.start();
         yield* proc.waitForSpawn("a", 2);
-        yield* waitForState(orc, "a", (state) => state.status === "Unhealthy", "Unhealthy");
+        const state = yield* waitForState(
+          orc,
+          "a",
+          (candidate) => candidate.status === "Failed",
+          "Failed",
+        );
         // maxRestarts=1 means original spawn + 1 restart = 2 total
         const mainSpawns = proc.spawned.filter((s) => s.command === "a");
         expect(mainSpawns.length).toBe(2);
+        expect(state.pid).toBeNull();
+        expect(state.exitCode).toBeNull();
+        expect(state.error).toBe("Health check failed and restart budget was exhausted");
+
+        const readyError = yield* orc.waitReady("a").pipe(Effect.flip);
+        expect(readyError._tag).toBe("ServiceReadyError");
+        if (readyError._tag === "ServiceReadyError") {
+          expect(readyError.reason).toBe("Health check failed and restart budget was exhausted");
+        }
+      }).pipe(Effect.provide(layer), Effect.scoped);
+    });
+
+    it.live("applies startup failures before a service has ever been healthy", () => {
+      const { layer, proc } = setupOrchestrator(
+        [
+          svc("a", {
+            restart: "always",
+            maxRestarts: 1,
+            healthCheck: {
+              probe: { _tag: "Exec", command: "check", args: [] },
+              periodSeconds: 0.01,
+              startupFailureThreshold: 2,
+              failureThreshold: 1,
+            },
+          }),
+        ],
+        {
+          exitDelay: "5 seconds",
+          perService: { check: { exitCode: 1, exitDelay: "1 millis" } },
+        },
+      );
+
+      return Effect.gen(function* () {
+        const orc = yield* Orchestrator;
+        yield* orc.start();
+        const state = yield* waitForFailed(orc, "a");
+        expect(proc.spawned.filter((spawn) => spawn.command === "a")).toHaveLength(2);
+        expect(state.pid).toBeNull();
+        expect(state.exitCode).toBeNull();
+      }).pipe(Effect.provide(layer), Effect.scoped);
+    });
+
+    it.live("keeps an initially unhealthy no-restart service alive", () => {
+      const { layer, proc } = setupOrchestrator(
+        [
+          svc("a", {
+            restart: "no",
+            healthCheck: {
+              probe: { _tag: "Exec", command: "check", args: [] },
+              periodSeconds: 0.01,
+              failureThreshold: 1,
+            },
+          }),
+        ],
+        {
+          exitDelay: "5 seconds",
+          perService: { check: { exitCode: 1, exitDelay: "1 millis" } },
+        },
+      );
+
+      return Effect.gen(function* () {
+        const orc = yield* Orchestrator;
+        yield* orc.start();
+        const state = yield* waitForState(
+          orc,
+          "a",
+          (candidate) => candidate.status === "Unhealthy",
+          "Unhealthy",
+        );
+        expect(state.pid).not.toBeNull();
+        expect(state.exitCode).toBeNull();
+        expect(proc.spawned.filter((spawn) => spawn.command === "a")).toHaveLength(1);
       }).pipe(Effect.provide(layer), Effect.scoped);
     });
   });
 
+  it.live("finalizes the child before publishing a healthy-hook failure", () => {
+    const { layer, proc } = setupOrchestrator(
+      [
+        svc("a", {
+          hooks: [{ on: "healthy", run: () => Effect.fail(new Error("warmup failed")) }],
+        }),
+      ],
+      { exitDelay: "5 seconds" },
+    );
+
+    return Effect.gen(function* () {
+      const orc = yield* Orchestrator;
+      yield* orc.start();
+      const state = yield* waitForFailed(orc, "a");
+      expect(proc.killed.some((record) => record.command === "a")).toBe(true);
+      expect(state.pid).toBeNull();
+      expect(state.exitCode).toBeNull();
+      expect(state.error).toContain("on:healthy");
+    }).pipe(Effect.provide(layer), Effect.scoped);
+  });
+
   describe("readiness", () => {
     it.live("waitReady resolves when long-running service becomes healthy", () => {
       const { layer } = setupOrchestrator([svc("a")], {
diff --git a/packages/stack/README.md b/packages/stack/README.md
index 321d60d988..6f412c8944 100644
--- a/packages/stack/README.md
+++ b/packages/stack/README.md
@@ -198,7 +198,7 @@ service and its projected status.
 ### Readiness
 
 ```typescript
-await stack.ready(); // Inherit the stack's finite two-minute default
+await stack.ready(); // Inherit the stack's finite three-minute default
 await stack.ready({ mode: "finite", timeoutMs: 30_000 });
 await stack.ready({ mode: "infinite" }); // Explicit debugging override
 await stack.serviceReady("postgres");
diff --git a/packages/stack/docs/architecture.md b/packages/stack/docs/architecture.md
index 4ce734db24..a6ba09c9d2 100644
--- a/packages/stack/docs/architecture.md
+++ b/packages/stack/docs/architecture.md
@@ -48,7 +48,7 @@ functions options, and per-service configuration. `false` disables an optional s
 4. applies per-service defaults and current `DEFAULT_VERSIONS`;
 5. records auto-managed paths for scoped cleanup.
 
-Readiness policy is part of the resolved configuration. The package default is a finite two-minute
+Readiness policy is part of the resolved configuration. The package default is a finite three-minute
 deadline; callers can choose a different finite deadline or explicit infinite waiting. Per-call
 `ReadyOptions` take precedence over the stack policy, while `inherit` delegates to the stack
 policy. The local Implementation applies this resolver to startup, service activation, restart,
diff --git a/packages/stack/src/LocalStack.ts b/packages/stack/src/LocalStack.ts
index 23602329cf..620eb548f3 100644
--- a/packages/stack/src/LocalStack.ts
+++ b/packages/stack/src/LocalStack.ts
@@ -662,7 +662,7 @@ export const localStackLayer = (
             return;
           }
           if (existing !== undefined) {
-            yield* waitForTargets(existing);
+            yield* waitForTargets(existing).pipe((effect) => withReadinessPolicy(effect, name));
             return;
           }
           const started = yield* Effect.gen(function* () {
@@ -671,8 +671,8 @@ export const localStackLayer = (
             if (concurrentlyStarted !== undefined) return concurrentlyStarted;
             return yield* beginStartTargets(service, new Set());
           }).pipe(withLifecycleLock);
-          yield* waitForTargets(started);
-        }).pipe((effect) => withReadinessPolicy(effect, name), cleanupOnReadinessFailure);
+          yield* waitForTargets(started).pipe((effect) => withReadinessPolicy(effect, name));
+        }).pipe(cleanupOnReadinessFailure);
 
       const stack = {
         getInfo: () => Effect.succeed(info),
@@ -712,16 +712,19 @@ export const localStackLayer = (
                 );
                 readiness.push(waitForTargets(started));
               }
-              yield* Effect.all(readiness, { concurrency: "unbounded", discard: true });
+              yield* Effect.all(readiness, { concurrency: "unbounded", discard: true }).pipe(
+                (effect) => withReadinessPolicy(effect, "stack"),
+              );
             } else {
               yield* runtime.orchestrator.start(serviceStartOptions);
-              yield* runtime.orchestrator.waitAllReady();
+              yield* runtime.orchestrator
+                .waitAllReady()
+                .pipe((effect) => withReadinessPolicy(effect, "stack"));
             }
             yield* Ref.set(phaseRef, "running");
           }).pipe(
             Effect.onError(() => Ref.set(phaseRef, "stopped")),
             withLifecycleLock,
-            (effect) => withReadinessPolicy(effect, "stack"),
             cleanupOnReadinessFailure,
           ),
         stop: () =>
@@ -748,8 +751,8 @@ export const localStackLayer = (
                 new Set(lifecycleTargetsForService(enabledServices, service)),
               );
             }).pipe(withLifecycleLock);
-            yield* waitForTargets(started);
-          }).pipe((effect) => withReadinessPolicy(effect, name), cleanupOnReadinessFailure),
+            yield* waitForTargets(started).pipe((effect) => withReadinessPolicy(effect, name));
+          }).pipe(cleanupOnReadinessFailure),
         stopService: (name) =>
           Effect.gen(function* () {
             yield* requireMutable(`stop service ${name}`);
@@ -771,8 +774,8 @@ export const localStackLayer = (
               yield* runtime.orchestrator.restartService(service, serviceStartOptions);
               return { runtime, targets: [service] };
             }).pipe(withLifecycleLock);
-            yield* waitForTargets(started);
-          }).pipe((effect) => withReadinessPolicy(effect, name), cleanupOnReadinessFailure),
+            yield* waitForTargets(started).pipe((effect) => withReadinessPolicy(effect, name));
+          }).pipe(cleanupOnReadinessFailure),
         reloadFunctions: (opts) =>
           Effect.gen(function* () {
             const started = yield* Effect.gen(function* () {
@@ -787,11 +790,10 @@ export const localStackLayer = (
               yield* runtime.orchestrator.restartService("edge-runtime", serviceStartOptions);
               return { runtime, targets: ["edge-runtime"] as const };
             }).pipe(withLifecycleLock);
-            yield* waitForTargets(started);
-          }).pipe(
-            (effect) => withReadinessPolicy(effect, "edge-runtime"),
-            cleanupOnReadinessFailure,
-          ),
+            yield* waitForTargets(started).pipe((effect) =>
+              withReadinessPolicy(effect, "edge-runtime"),
+            );
+          }).pipe(cleanupOnReadinessFailure),
         reloadEdgeRuntime: (opts) =>
           Effect.gen(function* () {
             const started = yield* Effect.gen(function* () {
@@ -828,11 +830,10 @@ export const localStackLayer = (
               yield* runtime.orchestrator.restartService("edge-runtime", serviceStartOptions);
               return { runtime, targets: ["edge-runtime"] as const };
             }).pipe(withLifecycleLock);
-            yield* waitForTargets(started);
-          }).pipe(
-            (effect) => withReadinessPolicy(effect, "edge-runtime"),
-            cleanupOnReadinessFailure,
-          ),
+            yield* waitForTargets(started).pipe((effect) =>
+              withReadinessPolicy(effect, "edge-runtime"),
+            );
+          }).pipe(cleanupOnReadinessFailure),
         getState: (name) =>
           Effect.gen(function* () {
             const currentStates = SubscriptionRef.getUnsafe(stateRef);
@@ -861,8 +862,10 @@ export const localStackLayer = (
             }
             yield* requireKnownServiceName(name);
             const runtime = yield* ensureRuntime;
-            yield* runtime.orchestrator.waitReady(name);
-          }).pipe((effect) => withReadinessPolicy(effect, name, opts), cleanupOnReadinessFailure),
+            yield* runtime.orchestrator
+              .waitReady(name)
+              .pipe((effect) => withReadinessPolicy(effect, name, opts));
+          }).pipe(cleanupOnReadinessFailure),
         waitAllReady: (opts) =>
           Effect.gen(function* () {
             const phase = yield* Ref.get(phaseRef);
@@ -874,11 +877,10 @@ export const localStackLayer = (
               );
             }
             const runtime = yield* ensureRuntime;
-            yield* runtime.orchestrator.waitAllReady();
-          }).pipe(
-            (effect) => withReadinessPolicy(effect, "stack", opts),
-            cleanupOnReadinessFailure,
-          ),
+            yield* runtime.orchestrator
+              .waitAllReady()
+              .pipe((effect) => withReadinessPolicy(effect, "stack", opts));
+          }).pipe(cleanupOnReadinessFailure),
         subscribeLogs: (name) => logBuffer.subscribe(name),
         subscribeAllLogs: (services) =>
           services === undefined || services.length === 0
diff --git a/packages/stack/src/Stack.unit.test.ts b/packages/stack/src/Stack.unit.test.ts
index f3286e0a53..c52918dedb 100644
--- a/packages/stack/src/Stack.unit.test.ts
+++ b/packages/stack/src/Stack.unit.test.ts
@@ -332,6 +332,37 @@ describe("Stack", () => {
     }).pipe(Effect.provide(providedLayer));
   });
 
+  it.live("starts the readiness deadline after artifact preparation", () => {
+    const resolver = mockBinaryResolver({
+      downloadedServices: ["postgres"],
+      downloadDelayMs: 1_000,
+    });
+    const spawner = mockChildProcessSpawner();
+    const config = {
+      ...defaultConfig,
+      postgrest: false,
+      auth: false,
+      readiness: { mode: "finite", timeoutMs: 250 },
+    } satisfies ResolvedStackConfig;
+    const stackPreparationLayer = StackPreparation.layer.pipe(Layer.provide(resolver.layer));
+    const layer = localStackLayer(config, noopPortLease(config.ports)).pipe(
+      Layer.provide(StackBuilder.layer),
+      Layer.provide(stackPreparationLayer),
+      Layer.provide(StackMetadataPersistence.noop),
+      Layer.provide(spawner.layer),
+      Layer.provide(BunServices.layer),
+    );
+
+    return Effect.gen(function* () {
+      const stack = yield* Stack;
+      const startedAt = Date.now();
+      const exit = yield* stack.start().pipe(Effect.exit);
+
+      expect(Date.now() - startedAt).toBeGreaterThanOrEqual(900);
+      expect(Exit.isSuccess(exit)).toBe(true);
+    }).pipe(Effect.provide(layer), Effect.scoped, Effect.timeout("5 seconds"));
+  });
+
   it.effect("getState fails for internal helper services", () => {
     const { layer } = setupLayer();
 
@@ -640,20 +671,12 @@ describe("Stack", () => {
 
   it.live("uses the stack readiness deadline for explicit lazy activation and cleans up", () =>
     Effect.gen(function* () {
-      const spawnStarted = yield* Deferred.make<void>();
-      const spawner = mockChildProcessSpawner({
-        beforeSpawn: (record) =>
-          record.args.some((arg) =>
-            Buffer.from(arg, "base64url").toString().includes('"command":"/cache/auth/'),
-          )
-            ? Deferred.succeed(spawnStarted, undefined).pipe(Effect.andThen(Effect.never))
-            : Effect.void,
-      });
+      const spawner = mockChildProcessSpawner();
       let releasedAll = false;
       const config = {
         ...defaultConfig,
         startupMode: "lazy",
-        readiness: { mode: "finite", timeoutMs: 250 },
+        readiness: { mode: "finite", timeoutMs: 500 },
       } satisfies ResolvedStackConfig;
       const lease: PortLease = {
         ...noopPortLease(config.ports),
@@ -673,7 +696,7 @@ describe("Stack", () => {
         expect(error._tag).toBe("StackReadinessError");
         if (error._tag === "StackReadinessError") {
           expect(error.target).toBe("auth");
-          expect(error.timeoutMs).toBe(250);
+          expect(error.timeoutMs).toBe(500);
         }
         expect(releasedAll).toBe(true);
         const spawnCountAfterDisposal = spawner.spawned.length;
diff --git a/packages/stack/src/StackConfig.ts b/packages/stack/src/StackConfig.ts
index 32d1251225..77b23e0bec 100644
--- a/packages/stack/src/StackConfig.ts
+++ b/packages/stack/src/StackConfig.ts
@@ -27,10 +27,10 @@ export const ReadyOptionsSchema = Schema.Union([
 
 export const inheritReadyOptions: ReadyOptions = { mode: "inherit" };
 
-/** Standalone stacks wait at most two minutes unless a caller or launch Adapter chooses otherwise. */
+/** Standalone stacks wait at most three minutes unless a caller or launch Adapter chooses otherwise. */
 export const DEFAULT_STACK_READINESS_POLICY: ReadinessPolicy = {
   mode: "finite",
-  timeoutMs: 120_000,
+  timeoutMs: 180_000,
 };
 
 /** Resolve readiness with per-call policy taking precedence over stack policy and package default. */
diff --git a/packages/stack/src/StackConfig.unit.test.ts b/packages/stack/src/StackConfig.unit.test.ts
index 2c160900f5..21978dcd9e 100644
--- a/packages/stack/src/StackConfig.unit.test.ts
+++ b/packages/stack/src/StackConfig.unit.test.ts
@@ -18,9 +18,9 @@ describe("resolveReadinessPolicy", () => {
     expect(
       resolveReadinessPolicy({
         readyOptions: { mode: "inherit" },
-        stackPolicy: finite(120_000),
+        stackPolicy: finite(180_000),
       }),
-    ).toEqual(finite(120_000));
+    ).toEqual(finite(180_000));
     expect(
       resolveReadinessPolicy({
         readyOptions: { mode: "inherit" },
@@ -33,13 +33,13 @@ describe("resolveReadinessPolicy", () => {
     expect(
       resolveReadinessPolicy({
         readyOptions: finite(5_000),
-        stackPolicy: finite(120_000),
+        stackPolicy: finite(180_000),
       }),
     ).toEqual(finite(5_000));
     expect(
       resolveReadinessPolicy({
         readyOptions: finite(300_000),
-        stackPolicy: finite(120_000),
+        stackPolicy: finite(180_000),
       }),
     ).toEqual(finite(300_000));
   });
@@ -48,7 +48,7 @@ describe("resolveReadinessPolicy", () => {
     expect(
       resolveReadinessPolicy({
         readyOptions: { mode: "infinite" },
-        stackPolicy: finite(120_000),
+        stackPolicy: finite(180_000),
       }),
     ).toEqual({ mode: "infinite" });
     expect(
diff --git a/packages/stack/src/StackStateProjection.ts b/packages/stack/src/StackStateProjection.ts
index 1d878a5a49..9d741215b8 100644
--- a/packages/stack/src/StackStateProjection.ts
+++ b/packages/stack/src/StackStateProjection.ts
@@ -1,4 +1,5 @@
 import type { ServiceState as RawServiceState } from "@supabase/process-compose";
+import { Equal } from "effect";
 import {
   StackServiceState,
   type StackServiceStatus,
@@ -17,18 +18,6 @@ function isHelperActive(state: RawServiceState): boolean {
   return state.status !== "Stopped" && state.status !== "Failed";
 }
 
-function sameState(a: StackServiceState | undefined, b: StackServiceState): boolean {
-  return (
-    a?.name === b.name &&
-    a.status === b.status &&
-    a.pid === b.pid &&
-    a.exitCode === b.exitCode &&
-    a.restartCount === b.restartCount &&
-    a.startedAt === b.startedAt &&
-    a.error === b.error
-  );
-}
-
 function projectPublicState(
   raw: RawServiceState,
   rawByName: ReadonlyMap<string, RawServiceState>,
@@ -100,5 +89,5 @@ export function changedProjectedStates(
   previous: ReadonlyMap<string, StackServiceState>,
   next: ReadonlyArray<StackServiceState>,
 ): ReadonlyArray<StackServiceState> {
-  return next.filter((state) => !sameState(previous.get(state.name), state));
+  return next.filter((state) => !Equal.equals(previous.get(state.name), state));
 }
diff --git a/packages/stack/src/StackStateProjection.unit.test.ts b/packages/stack/src/StackStateProjection.unit.test.ts
index 7275ba764e..8148da6fb0 100644
--- a/packages/stack/src/StackStateProjection.unit.test.ts
+++ b/packages/stack/src/StackStateProjection.unit.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, test } from "vitest";
 import { ServiceState } from "@supabase/process-compose";
 import {
+  changedProjectedStates,
   projectStackState,
   projectStackStates,
   type StackServiceProjectionCatalog,
@@ -83,4 +84,22 @@ describe("projectStackStates", () => {
 
     expect(projected?.status).toBe("Healthy");
   });
+
+  test("suppresses structurally equal projected states", () => {
+    const previousStates = projectStackStates(
+      [rawState("postgres", "Healthy"), rawState("auth", "Running")],
+      projectionCatalog,
+    );
+    const nextStates = projectStackStates(
+      [rawState("postgres", "Healthy"), rawState("auth", "Running")],
+      projectionCatalog,
+    );
+
+    expect(
+      changedProjectedStates(
+        new Map(previousStates.map((state) => [state.name, state])),
+        nextStates,
+      ),
+    ).toEqual([]);
+  });
 });
diff --git a/packages/stack/src/createStack.unit.test.ts b/packages/stack/src/createStack.unit.test.ts
index 747b16686b..abc8499e4d 100644
--- a/packages/stack/src/createStack.unit.test.ts
+++ b/packages/stack/src/createStack.unit.test.ts
@@ -261,7 +261,7 @@ describe("resolveConfig startup mode", () => {
 describe("resolveConfig readiness policy", () => {
   it("uses a finite package default", async () => {
     const config = await resolveConfig();
-    expect(config.readiness).toEqual({ mode: "finite", timeoutMs: 120_000 });
+    expect(config.readiness).toEqual({ mode: "finite", timeoutMs: 180_000 });
   });
 
   it("preserves an explicit infinite policy", async () => {

From 77782dfe2f5d3fe30ba154f0544aeabc57ab12bf Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 20:30:21 +0200
Subject: [PATCH 14/44] test(stack): await lazy Docker service readiness

---
 .../tests/createStack-docker.e2e.test.ts      | 23 +++++++++----------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/packages/stack/tests/createStack-docker.e2e.test.ts b/packages/stack/tests/createStack-docker.e2e.test.ts
index 1ab035c20b..2e49595930 100644
--- a/packages/stack/tests/createStack-docker.e2e.test.ts
+++ b/packages/stack/tests/createStack-docker.e2e.test.ts
@@ -70,6 +70,8 @@ dockerDescribe("createStack e2e (docker mode)", () => {
     "runs the core services in Docker containers and serves health endpoints",
     { timeout: STACK_DOCKER_E2E_TEST_TIMEOUT_MS },
     async () => {
+      await Promise.all([stack.startService("postgrest"), stack.startService("auth")]);
+
       const runningImages = execSync("docker ps --format '{{.Image}}'").toString();
       expect(runningImages).toContain("supabase/postgrest");
       expect(runningImages).toContain("supabase/postgres");
@@ -92,11 +94,10 @@ dockerDescribe("createStack e2e (docker mode)", () => {
     "runs the edge runtime in Docker and serves the functions placeholder through the local gateway",
     { timeout: STACK_DOCKER_E2E_TEST_TIMEOUT_MS },
     async () => {
-      const [runningImages, states, functionsRes] = await Promise.all([
-        Promise.resolve(execSync("docker ps --format '{{.Image}}'").toString()),
-        stack.getStatus(),
-        fetch(`${stack.url}/functions/v1/test`),
-      ]);
+      const functionsRes = await fetch(`${stack.url}/functions/v1/test`);
+      await stack.serviceReady("edge-runtime");
+      const runningImages = execSync("docker ps --format '{{.Image}}'").toString();
+      const states = await stack.getStatus();
 
       expect(runningImages).toContain("supabase/edge-runtime");
       expect(states).toEqual(
@@ -118,16 +119,14 @@ dockerDescribe("createStack e2e (docker mode)", () => {
     );
 
     await stack.startService("analytics");
+    await stack.serviceReady("analytics");
+    await expect
+      .poll(() => stack.getServiceStatus("analytics"), { timeout: 5_000 })
+      .toEqual(expect.objectContaining({ name: "analytics", status: "Healthy" }));
 
-    const [runningImages, states] = await Promise.all([
-      Promise.resolve(execSync("docker ps --format '{{.Image}}'").toString()),
-      stack.getStatus(),
-    ]);
+    const runningImages = execSync("docker ps --format '{{.Image}}'").toString();
 
     expect(runningImages).toContain("supabase/logflare");
-    expect(states).toEqual(
-      expect.arrayContaining([expect.objectContaining({ name: "analytics", status: "Healthy" })]),
-    );
   });
 
   test(

From a570b9e9c4b38eee8129c5039c6a2e922d472446 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 20:36:20 +0200
Subject: [PATCH 15/44] chore(stack): format merged readiness test

---
 packages/stack/src/Stack.unit.test.ts | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/stack/src/Stack.unit.test.ts b/packages/stack/src/Stack.unit.test.ts
index 259c8c8464..f471a80955 100644
--- a/packages/stack/src/Stack.unit.test.ts
+++ b/packages/stack/src/Stack.unit.test.ts
@@ -843,10 +843,10 @@ describe("Stack", () => {
 
         const error = yield* activator.activate("auth").pipe(Effect.flip);
 
-          expect(error._tag).toBe("StackReadinessError");
-          if (error._tag === "StackReadinessError") {
-            expect(error.target).toBe("auth");
-            expect(error.timeoutMs).toBe(1_000);
+        expect(error._tag).toBe("StackReadinessError");
+        if (error._tag === "StackReadinessError") {
+          expect(error.target).toBe("auth");
+          expect(error.timeoutMs).toBe(1_000);
         }
         expect(releasedAll).toBe(true);
         const spawnCountAfterDisposal = spawner.spawned.length;

From b7e84b697d2a25b41ec9c186d9568674d291d737 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 20:57:55 +0200
Subject: [PATCH 16/44] fix(stack): terminate daemon after lazy timeout

---
 packages/stack/src/ApiProxy.ts                | 63 +++++++++++--------
 packages/stack/src/ApiProxy.unit.test.ts      | 35 ++++++++++-
 packages/stack/src/daemon.ts                  | 21 ++++---
 packages/stack/src/layers.ts                  |  6 +-
 .../tests/createStack-docker.e2e.test.ts      |  2 +-
 5 files changed, 90 insertions(+), 37 deletions(-)

diff --git a/packages/stack/src/ApiProxy.ts b/packages/stack/src/ApiProxy.ts
index c3ecf5e01a..1f3fa5daae 100644
--- a/packages/stack/src/ApiProxy.ts
+++ b/packages/stack/src/ApiProxy.ts
@@ -1,4 +1,4 @@
-import { Effect, Layer, Option, Context, Duration, Schedule, Result } from "effect";
+import { Deferred, Effect, Layer, Option, Context, Duration, Schedule, Result } from "effect";
 import {
   Headers,
   HttpBody,
@@ -14,7 +14,7 @@ import type { ServiceName } from "./versions.ts";
 
 export interface ProxyConfig {
   readonly listenPort: number;
-  readonly activationTimeout?: Duration.Input;
+  readonly activationTimeout?: Duration.Input | "infinite";
   readonly gotruePort: number;
   readonly postgrestPort: number;
   readonly postgrestAdminPort: number;
@@ -134,16 +134,24 @@ function makeProxyHandler(
   client: HttpClient.HttpClient,
   config: ProxyConfig,
   activator: StackServiceActivator["Service"],
+  signalTerminalFailure: Effect.Effect<void>,
   opts: ProxyHandlerOptions,
 ) {
   return (req: HttpServerRequest.HttpServerRequest) =>
     Effect.gen(function* () {
-      const activation = yield* activator
-        .activate(opts.service)
-        .pipe(
-          Effect.timeout(config.activationTimeout ?? DEFAULT_SERVICE_ACTIVATION_TIMEOUT),
-          Effect.result,
-        );
+      const activationEffect = activator.activate(opts.service);
+      const activation = yield* (
+        config.activationTimeout === "infinite"
+          ? activationEffect
+          : activationEffect.pipe(
+              Effect.timeout(config.activationTimeout ?? DEFAULT_SERVICE_ACTIVATION_TIMEOUT),
+            )
+      ).pipe(
+        Effect.tapError((error) =>
+          error._tag === "StackReadinessError" ? signalTerminalFailure : Effect.void,
+        ),
+        Effect.result,
+      );
       if (Result.isFailure(activation)) {
         return HttpServerResponse.text("Service unavailable", {
           status: 503,
@@ -224,6 +232,8 @@ export class ApiProxy extends Context.Service<
   ApiProxy,
   {
     readonly address: HttpServer.Address;
+    /** Completes when terminal lazy-activation failure requires daemon teardown. */
+    readonly awaitTerminalFailure: Effect.Effect<void>;
   }
 >()("local/ApiProxy") {
   static layer = (
@@ -238,13 +248,15 @@ export class ApiProxy extends Context.Service<
         const server = yield* HttpServer.HttpServer;
         const client = yield* HttpClient.HttpClient;
         const activator = yield* StackServiceActivator;
+        const terminalFailure = yield* Deferred.make<void>();
+        const signalTerminalFailure = Deferred.succeed(terminalFailure, void 0).pipe(Effect.asVoid);
 
         const routes = [
           HttpRouter.route("*", "/health", HttpServerResponse.text("OK", { status: 200 })),
           HttpRouter.route(
             "*",
             "/.well-known/oauth-authorization-server",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "auth",
               backendPort: config.gotruePort,
               backendPath: "/.well-known/oauth-authorization-server",
@@ -253,7 +265,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/auth/v1/verify",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "auth",
               backendPort: config.gotruePort,
               stripPrefix: "/auth/v1",
@@ -262,7 +274,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/auth/v1/callback",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "auth",
               backendPort: config.gotruePort,
               stripPrefix: "/auth/v1",
@@ -271,7 +283,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/auth/v1/authorize",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "auth",
               backendPort: config.gotruePort,
               stripPrefix: "/auth/v1",
@@ -280,7 +292,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/auth/v1/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "auth",
               backendPort: config.gotruePort,
               stripPrefix: "/auth/v1",
@@ -290,7 +302,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/rest/v1/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "postgrest",
               backendPort: config.postgrestPort,
               stripPrefix: "/rest/v1",
@@ -300,7 +312,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/rest-admin/v1/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "postgrest",
               backendPort: config.postgrestAdminPort,
               stripPrefix: "/rest-admin/v1",
@@ -309,7 +321,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/graphql/v1",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "postgrest",
               backendPort: config.postgrestPort,
               backendPath: "/rpc/graphql",
@@ -320,7 +332,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/functions/v1/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "edge-runtime",
               backendPort: config.edgeRuntimePort,
               stripPrefix: "/functions/v1",
@@ -332,7 +344,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/realtime/v1/api/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "realtime",
               backendPort: config.realtimePort,
               stripPrefix: "/realtime/v1",
@@ -342,7 +354,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/realtime/v1/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "realtime",
               backendPort: config.realtimePort,
               stripPrefix: "/realtime/v1",
@@ -351,7 +363,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/storage/v1/s3/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "storage",
               backendPort: config.storagePort,
               stripPrefix: "/storage/v1",
@@ -360,7 +372,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/storage/v1/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "storage",
               backendPort: config.storagePort,
               stripPrefix: "/storage/v1",
@@ -370,7 +382,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/pg/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "pgmeta",
               backendPort: config.pgmetaPort,
               stripPrefix: "/pg",
@@ -379,7 +391,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/analytics/v1/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "analytics",
               backendPort: config.analyticsPort,
               stripPrefix: "/analytics/v1",
@@ -388,7 +400,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/pooler/v2/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "pooler",
               backendPort: config.poolerPort,
               stripPrefix: "/pooler",
@@ -397,7 +409,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/mcp",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "studio",
               backendPort: config.studioPort,
               backendPath: "/api/mcp",
@@ -422,6 +434,7 @@ export class ApiProxy extends Context.Service<
 
         return {
           address: server.address,
+          awaitTerminalFailure: Deferred.await(terminalFailure),
         };
       }),
     );
diff --git a/packages/stack/src/ApiProxy.unit.test.ts b/packages/stack/src/ApiProxy.unit.test.ts
index 6e97bd0a6c..ceea7eb174 100644
--- a/packages/stack/src/ApiProxy.unit.test.ts
+++ b/packages/stack/src/ApiProxy.unit.test.ts
@@ -5,7 +5,7 @@ import { Effect, Layer, ManagedRuntime } from "effect";
 import { FetchHttpClient } from "effect/unstable/http";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { ApiProxy, type ProxyConfig } from "./ApiProxy.ts";
-import { StackNotRunningError } from "./errors.ts";
+import { StackNotRunningError, StackReadinessError } from "./errors.ts";
 import { StackServiceActivator } from "./ServiceActivation.ts";
 import type { ServiceName } from "./versions.ts";
 
@@ -120,7 +120,11 @@ function buildProxyLayer(
 async function startProxy(
   config: ProxyConfig,
   activatorLayer?: Layer.Layer<StackServiceActivator>,
-): Promise<{ url: string; dispose: () => Promise<void> }> {
+): Promise<{
+  url: string;
+  dispose: () => Promise<void>;
+  awaitTerminalFailure: () => Promise<void>;
+}> {
   const proxyRuntime = ManagedRuntime.make(buildProxyLayer(config, activatorLayer));
   const proxy = await proxyRuntime.runPromise(ApiProxy);
   const addr = proxy.address;
@@ -129,7 +133,11 @@ async function startProxy(
     const host = addr.hostname === "0.0.0.0" ? "127.0.0.1" : addr.hostname;
     url = `http://${host}:${addr.port}`;
   }
-  return { url, dispose: () => proxyRuntime.dispose() };
+  return {
+    url,
+    dispose: () => proxyRuntime.dispose(),
+    awaitTerminalFailure: () => proxyRuntime.runPromise(proxy.awaitTerminalFailure),
+  };
 }
 
 describe("ApiProxy", () => {
@@ -246,6 +254,27 @@ describe("ApiProxy", () => {
     }
   });
 
+  test("signals daemon teardown after a terminal activation failure", async () => {
+    const activatorLayer = Layer.succeed(StackServiceActivator, {
+      activate: () =>
+        Effect.fail(
+          new StackReadinessError({
+            target: "postgrest",
+            timeoutMs: 30_000,
+            detail: "PostgREST did not become ready",
+          }),
+        ),
+    });
+    const proxy = await startProxy(configForPort(echoServer.port), activatorLayer);
+    try {
+      const res = await fetch(`${proxy.url}/rest/v1/users`);
+      expect(res.status).toBe(503);
+      await expect(proxy.awaitTerminalFailure()).resolves.toBeUndefined();
+    } finally {
+      await proxy.dispose();
+    }
+  });
+
   test("returns 503 when service activation does not complete before the request deadline", async () => {
     const activatorLayer = Layer.succeed(StackServiceActivator, {
       activate: () => Effect.never,
diff --git a/packages/stack/src/daemon.ts b/packages/stack/src/daemon.ts
index 30361ecb92..a7896aabeb 100644
--- a/packages/stack/src/daemon.ts
+++ b/packages/stack/src/daemon.ts
@@ -1,5 +1,6 @@
 import { Effect, Layer, ManagedRuntime } from "effect";
 import { HttpServer } from "effect/unstable/http";
+import { ApiProxy } from "./ApiProxy.ts";
 import type { PlatformFactory } from "./createStack.ts";
 import { DaemonServer } from "./DaemonServer.ts";
 import { PORT_FIELDS, reservePorts, type PortLease } from "./PortAllocator.ts";
@@ -46,7 +47,7 @@ export async function runDaemon(
   const msg = await waitForMessage<DaemonStartMessage>();
   const { socketPath } = msg;
 
-  let appRuntime: ManagedRuntime.ManagedRuntime<Stack | StateManager, never> | undefined;
+  let appRuntime: ManagedRuntime.ManagedRuntime<Stack | StateManager | ApiProxy, never> | undefined;
   let daemonRuntime: ManagedRuntime.ManagedRuntime<DaemonServer, never> | undefined;
   let portLease: PortLease | undefined;
 
@@ -73,12 +74,14 @@ export async function runDaemon(
     // Build the app layer (Stack + ApiProxy)
     const appLayer = foregroundDaemonLayer(config, platformFactory, portLease);
 
-    appRuntime = ManagedRuntime.make(appLayer);
+    const localAppRuntime = ManagedRuntime.make(appLayer);
+    appRuntime = localAppRuntime;
 
     // Build the stack (services are started later via POST /start)
-    const localStack = await appRuntime.runPromise(Stack);
-    const info = await appRuntime.runPromise(localStack.getInfo());
-    const localStateManager = await appRuntime.runPromise(StateManager);
+    const localStack = await localAppRuntime.runPromise(Stack);
+    const apiProxy = await localAppRuntime.runPromise(ApiProxy);
+    const info = await localAppRuntime.runPromise(localStack.getInfo());
+    const localStateManager = await localAppRuntime.runPromise(StateManager);
 
     // Build daemon management server on Unix socket
     const daemonLayer = DaemonServer.layer.pipe(
@@ -115,7 +118,11 @@ export async function runDaemon(
     process.disconnect?.();
 
     const daemon = await daemonRuntime.runPromise(DaemonServer);
-    await Promise.race([daemonRuntime.runPromise(daemon.awaitShutdown), waitForSignal()]);
+    await Promise.race([
+      daemonRuntime.runPromise(daemon.awaitShutdown),
+      localAppRuntime.runPromise(apiProxy.awaitTerminalFailure),
+      waitForSignal(),
+    ]);
     await shutdownDaemon({ appRuntime, daemonRuntime });
     process.exit(0);
   } catch (err) {
@@ -159,7 +166,7 @@ function waitForSignal(): Promise<"SIGINT" | "SIGTERM"> {
 }
 
 async function shutdownDaemon(opts: {
-  readonly appRuntime?: ManagedRuntime.ManagedRuntime<Stack, never>;
+  readonly appRuntime?: ManagedRuntime.ManagedRuntime<Stack | StateManager | ApiProxy, never>;
   readonly daemonRuntime?: ManagedRuntime.ManagedRuntime<DaemonServer, never>;
 }): Promise<void> {
   await opts.daemonRuntime?.dispose().catch(() => {});
diff --git a/packages/stack/src/layers.ts b/packages/stack/src/layers.ts
index ade58438a9..00d44270e5 100644
--- a/packages/stack/src/layers.ts
+++ b/packages/stack/src/layers.ts
@@ -63,6 +63,8 @@ export const foregroundLayer = (
 
   const proxyConfig: ProxyConfig = {
     listenPort: config.apiPort,
+    activationTimeout:
+      config.readiness.mode === "infinite" ? "infinite" : config.readiness.timeoutMs,
     gotruePort: config.auth !== false ? config.auth.port : 0,
     postgrestPort: config.postgrest !== false ? config.postgrest.port : 0,
     postgrestAdminPort: config.postgrest !== false ? config.postgrest.adminPort : 0,
@@ -102,7 +104,7 @@ export const foregroundDaemonLayer = (
   config: ResolvedDaemonConfig,
   platformFactory: PlatformFactory,
   portLease: PortLease,
-): Layer.Layer<Stack | StateManager> => {
+): Layer.Layer<Stack | StateManager | ApiProxy> => {
   const platform = platformFactory({
     apiPort: config.apiPort,
     releaseApiPort: portLease.release(["apiPort"]),
@@ -113,6 +115,8 @@ export const foregroundDaemonLayer = (
   );
   const proxyConfig: ProxyConfig = {
     listenPort: config.apiPort,
+    activationTimeout:
+      config.readiness.mode === "infinite" ? "infinite" : config.readiness.timeoutMs,
     gotruePort: config.auth !== false ? config.auth.port : 0,
     postgrestPort: config.postgrest !== false ? config.postgrest.port : 0,
     postgrestAdminPort: config.postgrest !== false ? config.postgrest.adminPort : 0,
diff --git a/packages/stack/tests/createStack-docker.e2e.test.ts b/packages/stack/tests/createStack-docker.e2e.test.ts
index 2e49595930..17e155291a 100644
--- a/packages/stack/tests/createStack-docker.e2e.test.ts
+++ b/packages/stack/tests/createStack-docker.e2e.test.ts
@@ -7,7 +7,7 @@ import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { createStack, type StackHandle } from "../src/node.ts";
 import { setupTestTable } from "./helpers/e2e.ts";
 
-const STACK_DOCKER_E2E_TEST_TIMEOUT_MS = 5_000;
+const STACK_DOCKER_E2E_TEST_TIMEOUT_MS = 180_000;
 const STACK_DOCKER_E2E_SETUP_TIMEOUT_MS = 90_000;
 
 function hasDockerDaemon(): boolean {

From d24cdb90dc9a7a203d4019474bb25a757a8c85e7 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 21:02:54 +0200
Subject: [PATCH 17/44] fix(process-compose): surface recovery hook failures

---
 .../src/Orchestrator.unit.test.ts             | 38 +++++++++++++++++++
 .../process-compose/src/ServiceTransition.ts  |  1 +
 .../src/ServiceTransition.unit.test.ts        |  9 +++++
 .../tests/createStack-docker.e2e.test.ts      | 10 +++--
 4 files changed, 55 insertions(+), 3 deletions(-)

diff --git a/packages/process-compose/src/Orchestrator.unit.test.ts b/packages/process-compose/src/Orchestrator.unit.test.ts
index 5bf69eb3df..802d6461a5 100644
--- a/packages/process-compose/src/Orchestrator.unit.test.ts
+++ b/packages/process-compose/src/Orchestrator.unit.test.ts
@@ -1348,6 +1348,44 @@ describe("Orchestrator", () => {
       }).pipe(Effect.provide(layer), Effect.scoped);
     });
 
+    it.live("publishes a failed recovery hook as a terminal failure", () => {
+      let checkCalls = 0;
+      const { layer, proc } = setupOrchestrator(
+        [
+          svc("a", {
+            restart: "no",
+            healthCheck: {
+              probe: { _tag: "Exec", command: "check", args: [] },
+              periodSeconds: 0.01,
+              startupFailureThreshold: 1,
+              successThreshold: 1,
+              failureThreshold: 1,
+            },
+            hooks: [{ on: "healthy", run: () => Effect.fail(new Error("recovery failed")) }],
+          }),
+        ],
+        {
+          exitDelay: "5 seconds",
+          perService: {
+            check: {
+              exitDelay: "1 millis",
+              getExitCode: () => (++checkCalls === 1 ? 1 : 0),
+            },
+          },
+        },
+      );
+      return Effect.gen(function* () {
+        const orc = yield* Orchestrator;
+        yield* orc.start();
+        yield* waitForState(orc, "a", (state) => state.status === "Unhealthy", "Unhealthy");
+        const state = yield* waitForFailed(orc, "a");
+        expect(proc.killed.some((record) => record.command === "a")).toBe(true);
+        expect(state.pid).toBeNull();
+        expect(state.error).toContain("on:healthy");
+        expect(state.error).toContain("recovery failed");
+      }).pipe(Effect.provide(layer), Effect.scoped);
+    });
+
     it.live("dependent waits for on:started hook to complete before starting", () => {
       const order: string[] = [];
       const { layer } = setupOrchestrator(
diff --git a/packages/process-compose/src/ServiceTransition.ts b/packages/process-compose/src/ServiceTransition.ts
index 228ca5e1ce..e7a20a8a8b 100644
--- a/packages/process-compose/src/ServiceTransition.ts
+++ b/packages/process-compose/src/ServiceTransition.ts
@@ -64,6 +64,7 @@ const allowed = new Set<`${ServiceStatus}:${ServiceEvent["_tag"]}`>([
   "Restarting:BackoffElapsed",
   "Running:HookFailed",
   "Healthy:HookFailed",
+  "Unhealthy:HookFailed",
 ]);
 
 // ---------------------------------------------------------------------------
diff --git a/packages/process-compose/src/ServiceTransition.unit.test.ts b/packages/process-compose/src/ServiceTransition.unit.test.ts
index 6de22894a4..5db75df898 100644
--- a/packages/process-compose/src/ServiceTransition.unit.test.ts
+++ b/packages/process-compose/src/ServiceTransition.unit.test.ts
@@ -365,6 +365,15 @@ describe("ServiceTransition", () => {
       expect(next!.error).toBe("seed failed");
     });
 
+    it("Unhealthy + HookFailed → Failed with error", () => {
+      const state = make("db", { status: "Unhealthy", pid: 1234, startedAt: 1000 });
+      const next = applyEvent(state, { _tag: "HookFailed", error: "recovery failed" });
+      expect(next).not.toBeNull();
+      expect(next!.status).toBe("Failed");
+      expect(next!.error).toBe("recovery failed");
+      expect(next!.pid).toBeNull();
+    });
+
     it("Starting + HookFailed → Failed with error", () => {
       const state = make("db", { status: "Starting" });
       const next = applyEvent(state, { _tag: "HookFailed", error: "startup failed" });
diff --git a/packages/stack/tests/createStack-docker.e2e.test.ts b/packages/stack/tests/createStack-docker.e2e.test.ts
index 1ab035c20b..47264b7187 100644
--- a/packages/stack/tests/createStack-docker.e2e.test.ts
+++ b/packages/stack/tests/createStack-docker.e2e.test.ts
@@ -7,7 +7,7 @@ import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { createStack, type StackHandle } from "../src/node.ts";
 import { setupTestTable } from "./helpers/e2e.ts";
 
-const STACK_DOCKER_E2E_TEST_TIMEOUT_MS = 5_000;
+const STACK_DOCKER_E2E_TEST_TIMEOUT_MS = 180_000;
 const STACK_DOCKER_E2E_SETUP_TIMEOUT_MS = 90_000;
 
 function hasDockerDaemon(): boolean {
@@ -70,6 +70,8 @@ dockerDescribe("createStack e2e (docker mode)", () => {
     "runs the core services in Docker containers and serves health endpoints",
     { timeout: STACK_DOCKER_E2E_TEST_TIMEOUT_MS },
     async () => {
+      await Promise.all([stack.startService("postgrest"), stack.startService("auth")]);
+
       const runningImages = execSync("docker ps --format '{{.Image}}'").toString();
       expect(runningImages).toContain("supabase/postgrest");
       expect(runningImages).toContain("supabase/postgres");
@@ -92,10 +94,12 @@ dockerDescribe("createStack e2e (docker mode)", () => {
     "runs the edge runtime in Docker and serves the functions placeholder through the local gateway",
     { timeout: STACK_DOCKER_E2E_TEST_TIMEOUT_MS },
     async () => {
-      const [runningImages, states, functionsRes] = await Promise.all([
+      const functionsRes = await fetch(`${stack.url}/functions/v1/test`);
+      await stack.serviceReady("edge-runtime");
+
+      const [runningImages, states] = await Promise.all([
         Promise.resolve(execSync("docker ps --format '{{.Image}}'").toString()),
         stack.getStatus(),
-        fetch(`${stack.url}/functions/v1/test`),
       ]);
 
       expect(runningImages).toContain("supabase/edge-runtime");

From 6017cc321d13191785a5c8c6db313ccea7dd25dc Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 21:06:39 +0200
Subject: [PATCH 18/44] test(process-compose): cover recovery hook transition

---
 packages/process-compose/src/ServiceTransition.unit.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/process-compose/src/ServiceTransition.unit.test.ts b/packages/process-compose/src/ServiceTransition.unit.test.ts
index 4f3a2defda..802f1d766a 100644
--- a/packages/process-compose/src/ServiceTransition.unit.test.ts
+++ b/packages/process-compose/src/ServiceTransition.unit.test.ts
@@ -73,7 +73,7 @@ describe("ServiceTransition", () => {
       ],
       RestartTriggered: ["Unhealthy", "Stopped", "Failed"],
       BackoffElapsed: ["Restarting"],
-      HookFailed: ["Starting", "Running", "Healthy"],
+      HookFailed: ["Starting", "Running", "Healthy", "Unhealthy"],
     };
 
     for (const event of Object.values(events)) {

From f1ade49a28cd816280aa60fa3f542387e1d37a1f Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 21:15:31 +0200
Subject: [PATCH 19/44] fix(process-compose): fail blocked healthy dependents

---
 packages/process-compose/src/Orchestrator.ts  | 13 ++++++--
 .../src/Orchestrator.unit.test.ts             | 33 +++++++++++++++++++
 2 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/packages/process-compose/src/Orchestrator.ts b/packages/process-compose/src/Orchestrator.ts
index 782fbd169b..4cc40594c6 100644
--- a/packages/process-compose/src/Orchestrator.ts
+++ b/packages/process-compose/src/Orchestrator.ts
@@ -226,10 +226,19 @@ export class Orchestrator extends Context.Service<
                         (state.status === "Stopped" && state.exitCode === 0)),
                   );
                 } else if (condition === "healthy") {
-                  yield* waitForState(
+                  const ready = yield* waitForState(
                     dependency,
-                    (state) => state.desired === "running" && state.status === "Healthy",
+                    (state) =>
+                      state.desired === "running" &&
+                      (state.status === "Healthy" || state.status === "Failed"),
                   );
+                  if (ready.status === "Failed") {
+                    yield* sendEvent(def.name, {
+                      _tag: "DependencyFailed",
+                      error: `Dependency ${depDef.name} failed: ${ready.error ?? "unknown failure"}`,
+                    });
+                    return;
+                  }
                 } else if (condition === "completed") {
                   const completed = yield* waitForState(
                     dependency,
diff --git a/packages/process-compose/src/Orchestrator.unit.test.ts b/packages/process-compose/src/Orchestrator.unit.test.ts
index 802d6461a5..9c0dce71d8 100644
--- a/packages/process-compose/src/Orchestrator.unit.test.ts
+++ b/packages/process-compose/src/Orchestrator.unit.test.ts
@@ -1124,6 +1124,39 @@ describe("Orchestrator", () => {
       }).pipe(Effect.provide(layer), Effect.scoped);
     });
 
+    it.live("healthy dependency fails immediately when health restarts are exhausted", () => {
+      const { layer } = setupOrchestrator(
+        [
+          svc("db", {
+            restart: "always",
+            maxRestarts: 1,
+            healthCheck: {
+              probe: { _tag: "Exec", command: "check", args: [] },
+              periodSeconds: 0.01,
+              startupFailureThreshold: 1,
+              failureThreshold: 1,
+            },
+          }),
+          svc("api", {
+            restart: "no",
+            dependencies: [{ service: "db", condition: "healthy" }],
+            dependencyTimeoutSeconds: 5,
+          }),
+        ],
+        {
+          exitDelay: "5 seconds",
+          perService: { check: { exitCode: 1, exitDelay: "1 millis" } },
+        },
+      );
+      return Effect.gen(function* () {
+        const orc = yield* Orchestrator;
+        yield* orc.start();
+        const state = yield* waitForFailed(orc, "api");
+        expect(state.error).toContain("Dependency db failed");
+        expect(state.error).not.toContain("Timed out");
+      }).pipe(Effect.provide(layer), Effect.scoped);
+    });
+
     it.live("no timeout when dependency resolves before deadline", () => {
       const { layer } = setupOrchestrator(
         [

From 27e8561f9a44e459b95699a975e65661c8d53fc6 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 21:21:49 +0200
Subject: [PATCH 20/44] fix(process-compose): hard-kill timed-out cleanup

---
 packages/process-compose/src/SupervisorRuntime.unit.test.ts | 2 +-
 packages/process-compose/src/supervisor-runtime.ts          | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/process-compose/src/SupervisorRuntime.unit.test.ts b/packages/process-compose/src/SupervisorRuntime.unit.test.ts
index 7e3e780a05..de8fa96894 100644
--- a/packages/process-compose/src/SupervisorRuntime.unit.test.ts
+++ b/packages/process-compose/src/SupervisorRuntime.unit.test.ts
@@ -209,7 +209,7 @@ describe("supervisor-runtime", () => {
           {
             _tag: "RunCommand",
             executable: process.execPath,
-            args: ["-e", "setInterval(() => {}, 1000)"],
+            args: ["-e", 'process.on("SIGTERM", () => {}); setInterval(() => {}, 1000)'],
             timeoutMs: 100,
           },
           { _tag: "RemovePath", path: cleanupDir, recursive: true },
diff --git a/packages/process-compose/src/supervisor-runtime.ts b/packages/process-compose/src/supervisor-runtime.ts
index 5dc2af51ae..3633a50d97 100644
--- a/packages/process-compose/src/supervisor-runtime.ts
+++ b/packages/process-compose/src/supervisor-runtime.ts
@@ -283,6 +283,7 @@ export function runSupervisorRuntime(encodedConfig = process.argv[2]): void {
               env: childEnv,
               stdio: "ignore",
               timeout: action.timeoutMs ?? DEFAULT_CLEANUP_COMMAND_TIMEOUT_MS,
+              killSignal: "SIGKILL",
             });
           } else if (action._tag === "RemovePath") {
             await removePathWithRetry(action);

From a1f7a1129001cf57e6400948f6043229160a69f4 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 21:25:36 +0200
Subject: [PATCH 21/44] fix(stack): make readiness teardown terminal

---
 packages/stack/src/ApiProxy.ts           | 27 +++++++++++-----
 packages/stack/src/ApiProxy.unit.test.ts |  1 +
 packages/stack/src/LocalStack.ts         | 40 +++++++++++++-----------
 3 files changed, 43 insertions(+), 25 deletions(-)

diff --git a/packages/stack/src/ApiProxy.ts b/packages/stack/src/ApiProxy.ts
index 1f3fa5daae..88c9a3d9d0 100644
--- a/packages/stack/src/ApiProxy.ts
+++ b/packages/stack/src/ApiProxy.ts
@@ -10,6 +10,7 @@ import {
   HttpServerResponse,
 } from "effect/unstable/http";
 import { StackServiceActivator } from "./ServiceActivation.ts";
+import { StackReadinessError } from "./errors.ts";
 import type { ServiceName } from "./versions.ts";
 
 export interface ProxyConfig {
@@ -140,13 +141,25 @@ function makeProxyHandler(
   return (req: HttpServerRequest.HttpServerRequest) =>
     Effect.gen(function* () {
       const activationEffect = activator.activate(opts.service);
-      const activation = yield* (
-        config.activationTimeout === "infinite"
-          ? activationEffect
-          : activationEffect.pipe(
-              Effect.timeout(config.activationTimeout ?? DEFAULT_SERVICE_ACTIVATION_TIMEOUT),
-            )
-      ).pipe(
+      const activation = yield* (() => {
+        if (config.activationTimeout === "infinite") {
+          return activationEffect;
+        }
+        const activationTimeout = config.activationTimeout ?? DEFAULT_SERVICE_ACTIVATION_TIMEOUT;
+        return activationEffect.pipe(
+          Effect.timeoutOrElse({
+            duration: activationTimeout,
+            orElse: () =>
+              Effect.fail(
+                new StackReadinessError({
+                  target: opts.service,
+                  timeoutMs: Duration.toMillis(activationTimeout),
+                  detail: `Timed out waiting for ${opts.service} activation`,
+                }),
+              ),
+          }),
+        );
+      })().pipe(
         Effect.tapError((error) =>
           error._tag === "StackReadinessError" ? signalTerminalFailure : Effect.void,
         ),
diff --git a/packages/stack/src/ApiProxy.unit.test.ts b/packages/stack/src/ApiProxy.unit.test.ts
index ceea7eb174..3d29dc85d5 100644
--- a/packages/stack/src/ApiProxy.unit.test.ts
+++ b/packages/stack/src/ApiProxy.unit.test.ts
@@ -289,6 +289,7 @@ describe("ApiProxy", () => {
       });
       expect(res.status).toBe(503);
       expect(res.headers.get("retry-after")).toBe("1");
+      await expect(proxy.awaitTerminalFailure()).resolves.toBeUndefined();
     } finally {
       await proxy.dispose();
     }
diff --git a/packages/stack/src/LocalStack.ts b/packages/stack/src/LocalStack.ts
index 620eb548f3..588257b9e8 100644
--- a/packages/stack/src/LocalStack.ts
+++ b/packages/stack/src/LocalStack.ts
@@ -405,6 +405,7 @@ export const localStackLayer = (
       });
 
       let disposed = false;
+      let disposing = false;
       const runtimeHost = Effect.gen(function* () {
         const prepared = yield* ensurePrepared;
         const platform = yield* detectPlatform;
@@ -587,31 +588,34 @@ export const localStackLayer = (
       });
       const requireMutable = (operation: string) =>
         Effect.suspend(() =>
-          disposed
+          disposed || disposing
             ? Effect.fail(
                 new StackBuildError({
-                  detail: `Cannot ${operation} after the stack has been disposed`,
+                  detail: `Cannot ${operation} after stack disposal has begun`,
                 }),
               )
             : Effect.void,
         );
       const disposeOnce = () =>
-        Effect.gen(function* () {
-          if (disposed) {
-            return;
-          }
-          disposed = true;
-          yield* Ref.set(phaseRef, "stopping");
-          yield* cleanupLocalStackResources({
-            stop: () =>
-              runtimeState === undefined ? Effect.void : runtimeState.orchestrator.stop(),
-            cleanupTargets: runtimeState?.cleanupTargets ?? { dockerContainerNames: [] },
-            config,
-          }).pipe(
-            Effect.ensuring(portLease.releaseAll),
-            Effect.ensuring(Ref.set(phaseRef, "disposed")),
-          );
-        }).pipe(withLifecycleLock);
+        Effect.suspend(() => {
+          disposing = true;
+          return Effect.gen(function* () {
+            if (disposed) {
+              return;
+            }
+            disposed = true;
+            yield* Ref.set(phaseRef, "stopping");
+            yield* cleanupLocalStackResources({
+              stop: () =>
+                runtimeState === undefined ? Effect.void : runtimeState.orchestrator.stop(),
+              cleanupTargets: runtimeState?.cleanupTargets ?? { dockerContainerNames: [] },
+              config,
+            }).pipe(
+              Effect.ensuring(portLease.releaseAll),
+              Effect.ensuring(Ref.set(phaseRef, "disposed")),
+            );
+          }).pipe(withLifecycleLock);
+        }).pipe(Effect.uninterruptible);
 
       const withReadinessPolicy = <A, E, R>(
         effect: Effect.Effect<A, E, R>,

From 42c775cdb3283ae2606de4071afd306bcdfec6b4 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 21:31:50 +0200
Subject: [PATCH 22/44] fix(process-compose): await restartable dependencies

---
 packages/process-compose/src/Orchestrator.ts  | 15 ++++++-
 .../src/Orchestrator.unit.test.ts             | 40 +++++++++++++++++++
 packages/stack/src/ApiProxy.ts                |  2 +-
 3 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/packages/process-compose/src/Orchestrator.ts b/packages/process-compose/src/Orchestrator.ts
index 4cc40594c6..86b7f52b28 100644
--- a/packages/process-compose/src/Orchestrator.ts
+++ b/packages/process-compose/src/Orchestrator.ts
@@ -226,11 +226,24 @@ export class Orchestrator extends Context.Service<
                         (state.status === "Stopped" && state.exitCode === 0)),
                   );
                 } else if (condition === "healthy") {
+                  const willRestartAfterExit = (state: ServiceState): boolean => {
+                    if (state.exitCode === null) return false;
+                    return (
+                      decideRestart({
+                        cause: { _tag: "ProcessExit", exitCode: state.exitCode },
+                        policy: depDef.restart ?? defaults.restart,
+                        restartCount: state.restartCount,
+                        maxRestarts: depDef.maxRestarts ?? defaults.maxRestarts,
+                        desired: state.desired,
+                      })._tag === "Restart"
+                    );
+                  };
                   const ready = yield* waitForState(
                     dependency,
                     (state) =>
                       state.desired === "running" &&
-                      (state.status === "Healthy" || state.status === "Failed"),
+                      (state.status === "Healthy" ||
+                        (state.status === "Failed" && !willRestartAfterExit(state))),
                   );
                   if (ready.status === "Failed") {
                     yield* sendEvent(def.name, {
diff --git a/packages/process-compose/src/Orchestrator.unit.test.ts b/packages/process-compose/src/Orchestrator.unit.test.ts
index 9c0dce71d8..8431d3ec88 100644
--- a/packages/process-compose/src/Orchestrator.unit.test.ts
+++ b/packages/process-compose/src/Orchestrator.unit.test.ts
@@ -1157,6 +1157,46 @@ describe("Orchestrator", () => {
       }).pipe(Effect.provide(layer), Effect.scoped);
     });
 
+    it.live("healthy dependency waits through a transient failed restart", () => {
+      let databaseSpawns = 0;
+      const { layer, proc } = setupOrchestrator(
+        [
+          svc("db", {
+            restart: "always",
+            maxRestarts: 1,
+            healthCheck: {
+              probe: { _tag: "Exec", command: "check", args: [] },
+              initialDelaySeconds: 0.05,
+              periodSeconds: 0.05,
+            },
+          }),
+          svc("api", {
+            restart: "no",
+            dependencies: [{ service: "db", condition: "healthy" }],
+            dependencyTimeoutSeconds: 5,
+          }),
+        ],
+        {
+          perService: {
+            db: {
+              exitCode: 1,
+              getExitDelay: () => (++databaseSpawns === 1 ? "10 millis" : "5 seconds"),
+            },
+            check: { exitCode: 0, exitDelay: "1 millis" },
+          },
+        },
+      );
+
+      return Effect.gen(function* () {
+        const orc = yield* Orchestrator;
+        yield* orc.start();
+        yield* proc.waitForSpawn("api");
+
+        expect(proc.spawned.filter((spawn) => spawn.command === "db")).toHaveLength(2);
+        expect((yield* orc.getState("api")).status).not.toBe("Failed");
+      }).pipe(Effect.provide(layer), Effect.scoped);
+    });
+
     it.live("no timeout when dependency resolves before deadline", () => {
       const { layer } = setupOrchestrator(
         [
diff --git a/packages/stack/src/ApiProxy.ts b/packages/stack/src/ApiProxy.ts
index c3ecf5e01a..628d7f4f3e 100644
--- a/packages/stack/src/ApiProxy.ts
+++ b/packages/stack/src/ApiProxy.ts
@@ -114,7 +114,7 @@ function addCorsHeaders(
 // status does not mean a function is servable yet. Briefly retry transport
 // failures on that route so a user's first call doesn't surface as a 502.
 const COLD_START_RETRY_SCHEDULE = Schedule.spaced("250 millis").pipe(Schedule.upTo({ times: 8 }));
-const DEFAULT_SERVICE_ACTIVATION_TIMEOUT = Duration.seconds(30);
+const DEFAULT_SERVICE_ACTIVATION_TIMEOUT = Duration.seconds(180);
 
 interface ProxyHandlerOptions {
   readonly service: ServiceName;

From 48a60578502fd6461208f4eb270c39924513a08d Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 21:45:28 +0200
Subject: [PATCH 23/44] fix(stack): synchronize status after readiness

---
 .../stack/src/StackLifecycleCoordinator.ts    | 45 ++++++++++++++-----
 .../tests/createStack-docker.e2e.test.ts      |  1 +
 2 files changed, 34 insertions(+), 12 deletions(-)

diff --git a/packages/stack/src/StackLifecycleCoordinator.ts b/packages/stack/src/StackLifecycleCoordinator.ts
index a9eeb0196d..27e5b2839a 100644
--- a/packages/stack/src/StackLifecycleCoordinator.ts
+++ b/packages/stack/src/StackLifecycleCoordinator.ts
@@ -36,7 +36,11 @@ import {
   versionsForConfig,
   type ResolvedStackConfig,
 } from "./StackBuilder.ts";
-import { changedProjectedStates, projectStackStates } from "./StackStateProjection.ts";
+import {
+  changedProjectedStates,
+  projectStackStates,
+  type StackServiceProjectionCatalog,
+} from "./StackStateProjection.ts";
 import { StackServiceState } from "./StackServiceState.ts";
 import type { EdgeRuntimeReloadConfig, StackInfo } from "./Stack.ts";
 import { SERVICE_NAMES, type ServiceName } from "./versions.ts";
@@ -53,6 +57,7 @@ type LifecyclePhase =
 interface RuntimeState {
   readonly orchestrator: Orchestrator["Service"];
   readonly graph: ResolvedGraph;
+  readonly serviceProjection: StackServiceProjectionCatalog;
   readonly cleanupTargets: CleanupTargets;
 }
 
@@ -429,6 +434,7 @@ export class StackLifecycleCoordinator extends Context.Service<
             return {
               orchestrator,
               graph,
+              serviceProjection,
               cleanupTargets,
             } satisfies RuntimeState;
           }).pipe(
@@ -528,6 +534,15 @@ export class StackLifecycleCoordinator extends Context.Service<
             ),
           );
         const withLifecycleLock = lifecycleLock.withPermit;
+        const syncProjectedStates = (runtime: RuntimeState) =>
+          Effect.gen(function* () {
+            const rawStates = yield* runtime.orchestrator.getAllStates();
+            yield* Effect.forEach(
+              projectStackStates(rawStates, runtime.serviceProjection),
+              updateState,
+              { discard: true },
+            );
+          });
         const serviceStartOptions = {
           beforeStart: (name: string) => portLease.reserve(portFieldsForService(name)),
           beforeSpawn: (name: string) => portLease.release(portFieldsForService(name)),
@@ -590,18 +605,21 @@ export class StackLifecycleCoordinator extends Context.Service<
           readonly runtime: RuntimeState;
           readonly targets: ReadonlyArray<ServiceName>;
         }) =>
-          Effect.forEach(
-            targets,
-            (target) =>
-              runtime.orchestrator
-                .waitReady(target)
-                .pipe(
-                  Effect.catchTag("ServiceNotFoundError", (cause) =>
-                    Effect.fail(knownServiceError(target, cause)),
+          Effect.gen(function* () {
+            yield* Effect.forEach(
+              targets,
+              (target) =>
+                runtime.orchestrator
+                  .waitReady(target)
+                  .pipe(
+                    Effect.catchTag("ServiceNotFoundError", (cause) =>
+                      Effect.fail(knownServiceError(target, cause)),
+                    ),
                   ),
-                ),
-            { concurrency: "unbounded", discard: true },
-          );
+              { concurrency: "unbounded", discard: true },
+            );
+            yield* syncProjectedStates(runtime);
+          });
         const inspectStartedTargets = (root: ServiceName) =>
           Effect.gen(function* () {
             const runtime = yield* ensureRuntime;
@@ -698,6 +716,7 @@ export class StackLifecycleCoordinator extends Context.Service<
               } else {
                 yield* runtime.orchestrator.start(serviceStartOptions);
                 yield* runtime.orchestrator.waitAllReady();
+                yield* syncProjectedStates(runtime);
               }
               yield* Ref.set(phaseRef, "running");
             }).pipe(
@@ -851,6 +870,7 @@ export class StackLifecycleCoordinator extends Context.Service<
               yield* requireKnownServiceName(name);
               const runtime = yield* ensureRuntime;
               yield* runtime.orchestrator.waitReady(name);
+              yield* syncProjectedStates(runtime);
             }),
           waitAllReady: () =>
             Effect.gen(function* () {
@@ -864,6 +884,7 @@ export class StackLifecycleCoordinator extends Context.Service<
               }
               const runtime = yield* ensureRuntime;
               yield* runtime.orchestrator.waitAllReady();
+              yield* syncProjectedStates(runtime);
             }),
           subscribeLogs: (name) => logBuffer.subscribe(name),
           subscribeAllLogs: (services) =>
diff --git a/packages/stack/tests/createStack-docker.e2e.test.ts b/packages/stack/tests/createStack-docker.e2e.test.ts
index 47264b7187..dfb3d913a0 100644
--- a/packages/stack/tests/createStack-docker.e2e.test.ts
+++ b/packages/stack/tests/createStack-docker.e2e.test.ts
@@ -122,6 +122,7 @@ dockerDescribe("createStack e2e (docker mode)", () => {
     );
 
     await stack.startService("analytics");
+    await stack.serviceReady("analytics");
 
     const [runningImages, states] = await Promise.all([
       Promise.resolve(execSync("docker ps --format '{{.Image}}'").toString()),

From c9de546136a75d566b85d0271cfaaf5ebd9735f3 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Wed, 5 Aug 2026 22:00:15 +0200
Subject: [PATCH 24/44] fix(stack): derive startup coordination timeouts

---
 packages/stack/src/ApiProxy.ts                |  9 +++--
 packages/stack/src/ServiceActivation.ts       | 22 ++++++++++-
 .../stack/src/ServiceActivation.unit.test.ts  |  7 ++++
 packages/stack/src/StackBuilder.ts            |  3 ++
 packages/stack/src/services/health-budgets.ts | 37 +++++++++++++++++--
 .../src/services/health-budgets.unit.test.ts  | 16 ++++++--
 6 files changed, 83 insertions(+), 11 deletions(-)

diff --git a/packages/stack/src/ApiProxy.ts b/packages/stack/src/ApiProxy.ts
index 628d7f4f3e..632e467b09 100644
--- a/packages/stack/src/ApiProxy.ts
+++ b/packages/stack/src/ApiProxy.ts
@@ -9,7 +9,7 @@ import {
   HttpServerRequest,
   HttpServerResponse,
 } from "effect/unstable/http";
-import { StackServiceActivator } from "./ServiceActivation.ts";
+import { activationTimeoutSecondsForService, StackServiceActivator } from "./ServiceActivation.ts";
 import type { ServiceName } from "./versions.ts";
 
 export interface ProxyConfig {
@@ -114,8 +114,6 @@ function addCorsHeaders(
 // status does not mean a function is servable yet. Briefly retry transport
 // failures on that route so a user's first call doesn't surface as a 502.
 const COLD_START_RETRY_SCHEDULE = Schedule.spaced("250 millis").pipe(Schedule.upTo({ times: 8 }));
-const DEFAULT_SERVICE_ACTIVATION_TIMEOUT = Duration.seconds(180);
-
 interface ProxyHandlerOptions {
   readonly service: ServiceName;
   readonly backendPort: number;
@@ -141,7 +139,10 @@ function makeProxyHandler(
       const activation = yield* activator
         .activate(opts.service)
         .pipe(
-          Effect.timeout(config.activationTimeout ?? DEFAULT_SERVICE_ACTIVATION_TIMEOUT),
+          Effect.timeout(
+            config.activationTimeout ??
+              Duration.seconds(activationTimeoutSecondsForService(opts.service)),
+          ),
           Effect.result,
         );
       if (Result.isFailure(activation)) {
diff --git a/packages/stack/src/ServiceActivation.ts b/packages/stack/src/ServiceActivation.ts
index a97d147489..0edb4dafb9 100644
--- a/packages/stack/src/ServiceActivation.ts
+++ b/packages/stack/src/ServiceActivation.ts
@@ -2,7 +2,8 @@ import { ServiceNotFoundError } from "@supabase/process-compose";
 import type { ServiceReadyError } from "@supabase/process-compose";
 import { Context, Effect, Layer } from "effect";
 import { StackBuildError, StackNotRunningError } from "./errors.ts";
-import type { ServiceName } from "./versions.ts";
+import { stackServiceStartupBudgetSeconds } from "./services/health-budgets.ts";
+import { SERVICE_NAMES, type ServiceName } from "./versions.ts";
 
 export interface ServiceActivationPolicy {
   /** Whether the public service must already be running when lazy startup completes. */
@@ -55,6 +56,25 @@ export const activationTargetsForService = (
   return [...targets];
 };
 
+const DEFAULT_ACTIVATION_TIMEOUT_FLOOR_SECONDS = 180;
+const ACTIVATION_COORDINATION_MARGIN_SECONDS = 5;
+
+/**
+ * Bounds request-triggered lazy activation by the complete companion closure.
+ * The floor preserves the existing tolerance for services with shorter probe
+ * budgets, while longer transitive closures expand the timeout automatically.
+ */
+export const activationTimeoutSecondsForService = (service: ServiceName): number => {
+  const startupBudget = activationTargetsForService(SERVICE_NAMES, service).reduce(
+    (total, target) => total + stackServiceStartupBudgetSeconds[target],
+    0,
+  );
+  return Math.max(
+    DEFAULT_ACTIVATION_TIMEOUT_FLOOR_SECONDS,
+    startupBudget + ACTIVATION_COORDINATION_MARGIN_SECONDS,
+  );
+};
+
 /** Services exclusively owned by a public service for stop/restart operations. */
 export const lifecycleTargetsForService = (
   enabledServices: ReadonlyArray<ServiceName>,
diff --git a/packages/stack/src/ServiceActivation.unit.test.ts b/packages/stack/src/ServiceActivation.unit.test.ts
index cc41dd31b7..42aed05d23 100644
--- a/packages/stack/src/ServiceActivation.unit.test.ts
+++ b/packages/stack/src/ServiceActivation.unit.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import {
+  activationTimeoutSecondsForService,
   activationTargetsForService,
   eagerServices,
   lifecycleTargetsForService,
@@ -44,6 +45,12 @@ describe("service activation", () => {
     expect(activationTargetsForService(enabled, "studio")).toEqual(["analytics", "studio"]);
   });
 
+  it("derives request activation timeouts from the transitive companion closure", () => {
+    expect(activationTimeoutSecondsForService("auth")).toBe(180);
+    expect(activationTimeoutSecondsForService("analytics")).toBe(196);
+    expect(activationTimeoutSecondsForService("studio")).toBe(288);
+  });
+
   it("does not assign shared public dependencies to their consumers", () => {
     expect(lifecycleTargetsForService(SERVICE_NAMES, "storage")).toEqual(["storage", "imgproxy"]);
     expect(lifecycleTargetsForService(SERVICE_NAMES, "analytics")).toEqual(["analytics", "vector"]);
diff --git a/packages/stack/src/StackBuilder.ts b/packages/stack/src/StackBuilder.ts
index 31ebab0db5..8bc5b75351 100644
--- a/packages/stack/src/StackBuilder.ts
+++ b/packages/stack/src/StackBuilder.ts
@@ -34,6 +34,7 @@ import {
 } from "./services/storage.ts";
 import { makeStudioServiceDocker } from "./services/studio.ts";
 import { makeVectorServiceDocker } from "./services/vector.ts";
+import { dependencyTimeoutSecondsForService } from "./services/health-budgets.ts";
 import type { PreparedStackArtifacts } from "./StackPreparation.ts";
 import type { StackServiceProjectionCatalog } from "./StackStateProjection.ts";
 import type { AllocatedPorts } from "./PortAllocator.ts";
@@ -834,6 +835,7 @@ export class StackBuilder extends Context.Service<
               networkArgs: dockerNetworkArgs(platform.os, []),
               dependencies: [{ service: "analytics", condition: "healthy" }],
             }),
+            dependencyTimeoutSeconds: dependencyTimeoutSecondsForService("analytics"),
             enabled: true,
           });
         }
@@ -903,6 +905,7 @@ export class StackBuilder extends Context.Service<
                       { service: "analytics", condition: "healthy" },
                     ],
             }),
+            dependencyTimeoutSeconds: dependencyTimeoutSecondsForService("analytics"),
             enabled: true,
           });
         }
diff --git a/packages/stack/src/services/health-budgets.ts b/packages/stack/src/services/health-budgets.ts
index ea478b5ad7..f1b794c418 100644
--- a/packages/stack/src/services/health-budgets.ts
+++ b/packages/stack/src/services/health-budgets.ts
@@ -1,8 +1,11 @@
 import type { HealthCheckConfig } from "@supabase/process-compose";
+import type { ServiceName } from "../versions.ts";
 
-type HealthBudget = Pick<
-  HealthCheckConfig,
-  "initialDelaySeconds" | "periodSeconds" | "startupFailureThreshold" | "failureThreshold"
+type HealthBudget = Required<
+  Pick<
+    HealthCheckConfig,
+    "initialDelaySeconds" | "periodSeconds" | "startupFailureThreshold" | "failureThreshold"
+  >
 >;
 
 /** Cold-start tolerance and tighter post-start liveness thresholds. */
@@ -92,3 +95,31 @@ export const stackHealthBudgets = {
     failureThreshold: 60,
   },
 } as const satisfies Record<string, HealthBudget>;
+
+export const healthStartupBudgetSeconds = (budget: HealthBudget): number =>
+  budget.initialDelaySeconds + budget.periodSeconds * budget.startupFailureThreshold;
+
+/** Worst-case initial health budget for each public service. */
+export const stackServiceStartupBudgetSeconds = {
+  postgres: Math.max(
+    healthStartupBudgetSeconds(stackHealthBudgets.postgresNative),
+    healthStartupBudgetSeconds(stackHealthBudgets.postgresDocker),
+  ),
+  postgrest: healthStartupBudgetSeconds(stackHealthBudgets.postgrest),
+  auth: healthStartupBudgetSeconds(stackHealthBudgets.auth),
+  "edge-runtime": healthStartupBudgetSeconds(stackHealthBudgets.edgeRuntime),
+  realtime: healthStartupBudgetSeconds(stackHealthBudgets.realtime),
+  storage: healthStartupBudgetSeconds(stackHealthBudgets.storage),
+  imgproxy: healthStartupBudgetSeconds(stackHealthBudgets.imgproxy),
+  mailpit: healthStartupBudgetSeconds(stackHealthBudgets.mailpit),
+  pgmeta: healthStartupBudgetSeconds(stackHealthBudgets.pgmeta),
+  studio: healthStartupBudgetSeconds(stackHealthBudgets.studio),
+  analytics: healthStartupBudgetSeconds(stackHealthBudgets.analytics),
+  vector: healthStartupBudgetSeconds(stackHealthBudgets.vector),
+  pooler: healthStartupBudgetSeconds(stackHealthBudgets.pooler),
+} as const satisfies Readonly<Record<ServiceName, number>>;
+
+const STARTUP_COORDINATION_MARGIN_SECONDS = 5;
+
+export const dependencyTimeoutSecondsForService = (service: ServiceName): number =>
+  stackServiceStartupBudgetSeconds[service] + STARTUP_COORDINATION_MARGIN_SECONDS;
diff --git a/packages/stack/src/services/health-budgets.unit.test.ts b/packages/stack/src/services/health-budgets.unit.test.ts
index 9dced20c60..12c7f54428 100644
--- a/packages/stack/src/services/health-budgets.unit.test.ts
+++ b/packages/stack/src/services/health-budgets.unit.test.ts
@@ -1,5 +1,10 @@
 import { describe, expect, it } from "vitest";
-import { stackHealthBudgets } from "./health-budgets.ts";
+import {
+  dependencyTimeoutSecondsForService,
+  healthStartupBudgetSeconds,
+  stackHealthBudgets,
+  stackServiceStartupBudgetSeconds,
+} from "./health-budgets.ts";
 
 describe("stack health budgets", () => {
   it("records startup and liveness policy for every health-checked service", () => {
@@ -10,8 +15,7 @@ describe("stack health budgets", () => {
           initialDelay: budget.initialDelaySeconds,
           period: budget.periodSeconds,
           startupThreshold: budget.startupFailureThreshold,
-          startupBudget:
-            budget.initialDelaySeconds + budget.periodSeconds * budget.startupFailureThreshold,
+          startupBudget: healthStartupBudgetSeconds(budget),
           livenessThreshold: budget.failureThreshold,
         },
       ]),
@@ -120,4 +124,10 @@ describe("stack health budgets", () => {
       }
     `);
   });
+
+  it("keeps dependency timeouts beyond the dependency startup budget", () => {
+    expect(dependencyTimeoutSecondsForService("analytics")).toBeGreaterThan(
+      stackServiceStartupBudgetSeconds.analytics,
+    );
+  });
 });

From a14d408ac8e21e2703d9b0b5679aac57a9116fd2 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 10:37:15 +0200
Subject: [PATCH 25/44] fix(stack): align startup budget deadlines

---
 .../stack/src/ServiceActivation.unit.test.ts  |  4 +--
 packages/stack/src/StackBuilder.ts            | 12 +++++--
 packages/stack/src/services/health-budgets.ts | 21 +++++++----
 .../src/services/health-budgets.unit.test.ts  | 34 +++++++++---------
 .../tests/createStack-docker.e2e.test.ts      | 35 +++++++++++--------
 5 files changed, 63 insertions(+), 43 deletions(-)

diff --git a/packages/stack/src/ServiceActivation.unit.test.ts b/packages/stack/src/ServiceActivation.unit.test.ts
index 42aed05d23..83336d573d 100644
--- a/packages/stack/src/ServiceActivation.unit.test.ts
+++ b/packages/stack/src/ServiceActivation.unit.test.ts
@@ -47,8 +47,8 @@ describe("service activation", () => {
 
   it("derives request activation timeouts from the transitive companion closure", () => {
     expect(activationTimeoutSecondsForService("auth")).toBe(180);
-    expect(activationTimeoutSecondsForService("analytics")).toBe(196);
-    expect(activationTimeoutSecondsForService("studio")).toBe(288);
+    expect(activationTimeoutSecondsForService("analytics")).toBe(554);
+    expect(activationTimeoutSecondsForService("studio")).toBe(825);
   });
 
   it("does not assign shared public dependencies to their consumers", () => {
diff --git a/packages/stack/src/StackBuilder.ts b/packages/stack/src/StackBuilder.ts
index 8bc5b75351..9d7b8109f8 100644
--- a/packages/stack/src/StackBuilder.ts
+++ b/packages/stack/src/StackBuilder.ts
@@ -34,7 +34,7 @@ import {
 } from "./services/storage.ts";
 import { makeStudioServiceDocker } from "./services/studio.ts";
 import { makeVectorServiceDocker } from "./services/vector.ts";
-import { dependencyTimeoutSecondsForService } from "./services/health-budgets.ts";
+import { dependencyTimeoutSecondsForServices } from "./services/health-budgets.ts";
 import type { PreparedStackArtifacts } from "./StackPreparation.ts";
 import type { StackServiceProjectionCatalog } from "./StackStateProjection.ts";
 import type { AllocatedPorts } from "./PortAllocator.ts";
@@ -835,7 +835,10 @@ export class StackBuilder extends Context.Service<
               networkArgs: dockerNetworkArgs(platform.os, []),
               dependencies: [{ service: "analytics", condition: "healthy" }],
             }),
-            dependencyTimeoutSeconds: dependencyTimeoutSecondsForService("analytics"),
+            dependencyTimeoutSeconds: dependencyTimeoutSecondsForServices([
+              "postgres",
+              "analytics",
+            ]),
             enabled: true,
           });
         }
@@ -905,7 +908,10 @@ export class StackBuilder extends Context.Service<
                       { service: "analytics", condition: "healthy" },
                     ],
             }),
-            dependencyTimeoutSeconds: dependencyTimeoutSecondsForService("analytics"),
+            dependencyTimeoutSeconds: dependencyTimeoutSecondsForServices([
+              "postgres",
+              "analytics",
+            ]),
             enabled: true,
           });
         }
diff --git a/packages/stack/src/services/health-budgets.ts b/packages/stack/src/services/health-budgets.ts
index f1b794c418..70c20a0770 100644
--- a/packages/stack/src/services/health-budgets.ts
+++ b/packages/stack/src/services/health-budgets.ts
@@ -1,4 +1,4 @@
-import type { HealthCheckConfig } from "@supabase/process-compose";
+import { defaults, type HealthCheckConfig } from "@supabase/process-compose";
 import type { ServiceName } from "../versions.ts";
 
 type HealthBudget = Required<
@@ -6,7 +6,8 @@ type HealthBudget = Required<
     HealthCheckConfig,
     "initialDelaySeconds" | "periodSeconds" | "startupFailureThreshold" | "failureThreshold"
   >
->;
+> &
+  Pick<HealthCheckConfig, "timeoutSeconds">;
 
 /** Cold-start tolerance and tighter post-start liveness thresholds. */
 export const stackHealthBudgets = {
@@ -96,8 +97,15 @@ export const stackHealthBudgets = {
   },
 } as const satisfies Record<string, HealthBudget>;
 
-export const healthStartupBudgetSeconds = (budget: HealthBudget): number =>
-  budget.initialDelaySeconds + budget.periodSeconds * budget.startupFailureThreshold;
+export const healthStartupBudgetSeconds = (budget: HealthBudget): number => {
+  const attempts = budget.startupFailureThreshold;
+  const probeTimeoutSeconds = budget.timeoutSeconds ?? defaults.healthCheck.timeoutSeconds;
+  return (
+    budget.initialDelaySeconds +
+    attempts * probeTimeoutSeconds +
+    (attempts - 1) * budget.periodSeconds
+  );
+};
 
 /** Worst-case initial health budget for each public service. */
 export const stackServiceStartupBudgetSeconds = {
@@ -121,5 +129,6 @@ export const stackServiceStartupBudgetSeconds = {
 
 const STARTUP_COORDINATION_MARGIN_SECONDS = 5;
 
-export const dependencyTimeoutSecondsForService = (service: ServiceName): number =>
-  stackServiceStartupBudgetSeconds[service] + STARTUP_COORDINATION_MARGIN_SECONDS;
+export const dependencyTimeoutSecondsForServices = (services: ReadonlyArray<ServiceName>): number =>
+  services.reduce((total, service) => total + stackServiceStartupBudgetSeconds[service], 0) +
+  STARTUP_COORDINATION_MARGIN_SECONDS;
diff --git a/packages/stack/src/services/health-budgets.unit.test.ts b/packages/stack/src/services/health-budgets.unit.test.ts
index 12c7f54428..557b9cdf38 100644
--- a/packages/stack/src/services/health-budgets.unit.test.ts
+++ b/packages/stack/src/services/health-budgets.unit.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import {
-  dependencyTimeoutSecondsForService,
+  dependencyTimeoutSecondsForServices,
   healthStartupBudgetSeconds,
   stackHealthBudgets,
   stackServiceStartupBudgetSeconds,
@@ -27,98 +27,98 @@ describe("stack health budgets", () => {
           "initialDelay": 10,
           "livenessThreshold": 60,
           "period": 1,
-          "startupBudget": 130,
+          "startupBudget": 369,
           "startupThreshold": 120,
         },
         "auth": {
           "initialDelay": 0,
           "livenessThreshold": 20,
           "period": 0.5,
-          "startupBudget": 30,
+          "startupBudget": 149.5,
           "startupThreshold": 60,
         },
         "edgeRuntime": {
           "initialDelay": 1,
           "livenessThreshold": 30,
           "period": 0.5,
-          "startupBudget": 31,
+          "startupBudget": 150.5,
           "startupThreshold": 60,
         },
         "imgproxy": {
           "initialDelay": 1,
           "livenessThreshold": 30,
           "period": 0.5,
-          "startupBudget": 31,
+          "startupBudget": 150.5,
           "startupThreshold": 60,
         },
         "mailpit": {
           "initialDelay": 1,
           "livenessThreshold": 30,
           "period": 0.5,
-          "startupBudget": 31,
+          "startupBudget": 150.5,
           "startupThreshold": 60,
         },
         "pgmeta": {
           "initialDelay": 1,
           "livenessThreshold": 30,
           "period": 0.5,
-          "startupBudget": 31,
+          "startupBudget": 150.5,
           "startupThreshold": 60,
         },
         "pooler": {
           "initialDelay": 2,
           "livenessThreshold": 60,
           "period": 1,
-          "startupBudget": 92,
+          "startupBudget": 271,
           "startupThreshold": 90,
         },
         "postgresDocker": {
           "initialDelay": 1,
           "livenessThreshold": 30,
           "period": 0.5,
-          "startupBudget": 61,
+          "startupBudget": 300.5,
           "startupThreshold": 120,
         },
         "postgresNative": {
           "initialDelay": 0,
           "livenessThreshold": 30,
           "period": 0.5,
-          "startupBudget": 60,
+          "startupBudget": 299.5,
           "startupThreshold": 120,
         },
         "postgrest": {
           "initialDelay": 0,
           "livenessThreshold": 20,
           "period": 0.5,
-          "startupBudget": 30,
+          "startupBudget": 149.5,
           "startupThreshold": 60,
         },
         "realtime": {
           "initialDelay": 1,
           "livenessThreshold": 30,
           "period": 0.5,
-          "startupBudget": 31,
+          "startupBudget": 150.5,
           "startupThreshold": 60,
         },
         "storage": {
           "initialDelay": 1,
           "livenessThreshold": 30,
           "period": 0.5,
-          "startupBudget": 31,
+          "startupBudget": 150.5,
           "startupThreshold": 60,
         },
         "studio": {
           "initialDelay": 2,
           "livenessThreshold": 60,
           "period": 1,
-          "startupBudget": 92,
+          "startupBudget": 271,
           "startupThreshold": 90,
         },
         "vector": {
           "initialDelay": 1,
           "livenessThreshold": 30,
           "period": 1,
-          "startupBudget": 61,
+          "startupBudget": 180,
           "startupThreshold": 60,
         },
       }
@@ -126,8 +126,8 @@ describe("stack health budgets", () => {
   });
 
   it("keeps dependency timeouts beyond the dependency startup budget", () => {
-    expect(dependencyTimeoutSecondsForService("analytics")).toBeGreaterThan(
-      stackServiceStartupBudgetSeconds.analytics,
+    expect(dependencyTimeoutSecondsForServices(["postgres", "analytics"])).toBeGreaterThan(
+      stackServiceStartupBudgetSeconds.postgres + stackServiceStartupBudgetSeconds.analytics,
     );
   });
 });
diff --git a/packages/stack/tests/createStack-docker.e2e.test.ts b/packages/stack/tests/createStack-docker.e2e.test.ts
index dfb3d913a0..1016af64b2 100644
--- a/packages/stack/tests/createStack-docker.e2e.test.ts
+++ b/packages/stack/tests/createStack-docker.e2e.test.ts
@@ -4,11 +4,13 @@ import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { activationTimeoutSecondsForService } from "../src/ServiceActivation.ts";
 import { createStack, type StackHandle } from "../src/node.ts";
 import { setupTestTable } from "./helpers/e2e.ts";
 
 const STACK_DOCKER_E2E_TEST_TIMEOUT_MS = 180_000;
 const STACK_DOCKER_E2E_SETUP_TIMEOUT_MS = 90_000;
+const ANALYTICS_COLD_START_TEST_TIMEOUT_MS = activationTimeoutSecondsForService("analytics") * 1000;
 
 function hasDockerDaemon(): boolean {
   try {
@@ -116,24 +118,27 @@ dockerDescribe("createStack e2e (docker mode)", () => {
     },
   );
 
-  test("cold-starts analytics through lazy service activation", { timeout: 180_000 }, async () => {
-    expect(await stack.getServiceStatus("analytics")).toEqual(
-      expect.objectContaining({ status: "Dormant" }),
-    );
+  test(
+    "cold-starts analytics through lazy service activation",
+    { timeout: ANALYTICS_COLD_START_TEST_TIMEOUT_MS },
+    async () => {
+      expect(await stack.getServiceStatus("analytics")).toEqual(
+        expect.objectContaining({ status: "Dormant" }),
+      );
 
-    await stack.startService("analytics");
-    await stack.serviceReady("analytics");
+      await stack.startService("analytics");
 
-    const [runningImages, states] = await Promise.all([
-      Promise.resolve(execSync("docker ps --format '{{.Image}}'").toString()),
-      stack.getStatus(),
-    ]);
+      const [runningImages, states] = await Promise.all([
+        Promise.resolve(execSync("docker ps --format '{{.Image}}'").toString()),
+        stack.getStatus(),
+      ]);
 
-    expect(runningImages).toContain("supabase/logflare");
-    expect(states).toEqual(
-      expect.arrayContaining([expect.objectContaining({ name: "analytics", status: "Healthy" })]),
-    );
-  });
+      expect(runningImages).toContain("supabase/logflare");
+      expect(states).toEqual(
+        expect.arrayContaining([expect.objectContaining({ name: "analytics", status: "Healthy" })]),
+      );
+    },
+  );
 
   test(
     "supports the docker auth signup and session golden path",

From db7d0157fd5c5dddbbcc9dacafe29d26b4391b3c Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 10:37:13 +0200
Subject: [PATCH 26/44] fix(process-compose): await restarting completed
 dependencies

---
 packages/process-compose/src/Orchestrator.ts  | 49 +++++++------------
 .../src/Orchestrator.unit.test.ts             | 35 +++++++++++++
 .../process-compose/src/ServiceTransition.ts  |  2 +
 .../src/ServiceTransition.unit.test.ts        |  8 ++-
 4 files changed, 62 insertions(+), 32 deletions(-)

diff --git a/packages/process-compose/src/Orchestrator.ts b/packages/process-compose/src/Orchestrator.ts
index 86b7f52b28..d884c5c693 100644
--- a/packages/process-compose/src/Orchestrator.ts
+++ b/packages/process-compose/src/Orchestrator.ts
@@ -42,6 +42,19 @@ import { type ServiceEvent, transition } from "./ServiceTransition.ts";
 
 const DIAGNOSTIC_LOG_LINES = 20;
 
+const willRestartAfterExit = (def: ServiceDef, state: ServiceState): boolean => {
+  if (state.exitCode === null) return false;
+  return (
+    decideRestart({
+      cause: { _tag: "ProcessExit", exitCode: state.exitCode },
+      policy: def.restart ?? defaults.restart,
+      restartCount: state.restartCount,
+      maxRestarts: def.maxRestarts ?? defaults.maxRestarts,
+      desired: state.desired,
+    })._tag === "Restart"
+  );
+};
+
 const waitForProcessToStop = (handle: {
   readonly isRunning: Effect.Effect<boolean, unknown, never>;
 }): Effect.Effect<void> =>
@@ -226,24 +239,12 @@ export class Orchestrator extends Context.Service<
                         (state.status === "Stopped" && state.exitCode === 0)),
                   );
                 } else if (condition === "healthy") {
-                  const willRestartAfterExit = (state: ServiceState): boolean => {
-                    if (state.exitCode === null) return false;
-                    return (
-                      decideRestart({
-                        cause: { _tag: "ProcessExit", exitCode: state.exitCode },
-                        policy: depDef.restart ?? defaults.restart,
-                        restartCount: state.restartCount,
-                        maxRestarts: depDef.maxRestarts ?? defaults.maxRestarts,
-                        desired: state.desired,
-                      })._tag === "Restart"
-                    );
-                  };
                   const ready = yield* waitForState(
                     dependency,
                     (state) =>
                       state.desired === "running" &&
                       (state.status === "Healthy" ||
-                        (state.status === "Failed" && !willRestartAfterExit(state))),
+                        (state.status === "Failed" && !willRestartAfterExit(depDef, state))),
                   );
                   if (ready.status === "Failed") {
                     yield* sendEvent(def.name, {
@@ -256,8 +257,9 @@ export class Orchestrator extends Context.Service<
                   const completed = yield* waitForState(
                     dependency,
                     (state) =>
-                      state.status === "Failed" ||
-                      (state.status === "Stopped" && state.exitCode !== null),
+                      (state.status === "Failed" ||
+                        (state.status === "Stopped" && state.exitCode !== null)) &&
+                      !willRestartAfterExit(depDef, state),
                   );
                   if (completed.status === "Failed") {
                     yield* sendEvent(def.name, {
@@ -645,19 +647,6 @@ export class Orchestrator extends Context.Service<
           Effect.suspend(() => {
             const svc = services.get(def.name);
             if (!svc) return Effect.void;
-            const willRestartAfterExit = (state: ServiceState): boolean => {
-              if (state.exitCode === null) return false;
-              return (
-                decideRestart({
-                  cause: { _tag: "ProcessExit", exitCode: state.exitCode },
-                  policy: def.restart ?? defaults.restart,
-                  restartCount: state.restartCount,
-                  maxRestarts: def.maxRestarts ?? defaults.maxRestarts,
-                  desired: state.desired,
-                })._tag === "Restart"
-              );
-            };
-
             const current = SubscriptionRef.getUnsafe(svc.state);
             if (current.desired !== "running") {
               return Effect.fail(
@@ -670,7 +659,7 @@ export class Orchestrator extends Context.Service<
                 }),
               );
             }
-            if (current.status === "Failed" && !willRestartAfterExit(current)) {
+            if (current.status === "Failed" && !willRestartAfterExit(def, current)) {
               return Effect.fail(
                 new ServiceReadyError({
                   name: def.name,
@@ -706,7 +695,7 @@ export class Orchestrator extends Context.Service<
               (state) =>
                 state.status === "Healthy" ||
                 ((state.status === "Failed" || state.status === "Stopped") &&
-                  !willRestartAfterExit(state)),
+                  !willRestartAfterExit(def, state)),
             ).pipe(
               Effect.flatMap((ready) => {
                 if (ready.status === "Healthy") return Effect.void;
diff --git a/packages/process-compose/src/Orchestrator.unit.test.ts b/packages/process-compose/src/Orchestrator.unit.test.ts
index 8431d3ec88..e58d7eb70f 100644
--- a/packages/process-compose/src/Orchestrator.unit.test.ts
+++ b/packages/process-compose/src/Orchestrator.unit.test.ts
@@ -1197,6 +1197,41 @@ describe("Orchestrator", () => {
       }).pipe(Effect.provide(layer), Effect.scoped);
     });
 
+    it.live("completed dependency waits through a transient failed restart", () => {
+      let setupSpawns = 0;
+      const { layer, proc } = setupOrchestrator(
+        [
+          svc("setup", {
+            restart: "on-failure",
+            maxRestarts: 1,
+          }),
+          svc("app", {
+            restart: "no",
+            dependencies: [{ service: "setup", condition: "completed" }],
+            dependencyTimeoutSeconds: 5,
+          }),
+        ],
+        {
+          perService: {
+            setup: {
+              getExitCode: () => (++setupSpawns === 1 ? 1 : 0),
+              exitDelay: "10 millis",
+            },
+            app: { exitDelay: "5 seconds" },
+          },
+        },
+      );
+
+      return Effect.gen(function* () {
+        const orc = yield* Orchestrator;
+        yield* orc.start();
+        yield* proc.waitForSpawn("app");
+
+        expect(proc.spawned.filter((spawn) => spawn.command === "setup")).toHaveLength(2);
+        expect((yield* orc.getState("app")).status).not.toBe("Failed");
+      }).pipe(Effect.provide(layer), Effect.scoped);
+    });
+
     it.live("no timeout when dependency resolves before deadline", () => {
       const { layer } = setupOrchestrator(
         [
diff --git a/packages/process-compose/src/ServiceTransition.ts b/packages/process-compose/src/ServiceTransition.ts
index e7a20a8a8b..94c28528ed 100644
--- a/packages/process-compose/src/ServiceTransition.ts
+++ b/packages/process-compose/src/ServiceTransition.ts
@@ -84,6 +84,8 @@ export const applyEvent = (state: ServiceState, event: ServiceEvent): ServiceSta
       return new ServiceState({
         ...state,
         status: "Failed",
+        pid: null,
+        exitCode: null,
         error: event.error,
       });
 
diff --git a/packages/process-compose/src/ServiceTransition.unit.test.ts b/packages/process-compose/src/ServiceTransition.unit.test.ts
index 5db75df898..58b41524f6 100644
--- a/packages/process-compose/src/ServiceTransition.unit.test.ts
+++ b/packages/process-compose/src/ServiceTransition.unit.test.ts
@@ -28,13 +28,15 @@ describe("ServiceTransition", () => {
     });
 
     it("Pending + DependencyFailed → Failed with error", () => {
-      const state = make("api");
+      const state = make("api", { pid: 1234, exitCode: 1 });
       const next = applyEvent(state, {
         _tag: "DependencyFailed",
         error: "db exited with code 1",
       });
       expect(next).not.toBeNull();
       expect(next!.status).toBe("Failed");
+      expect(next!.pid).toBeNull();
+      expect(next!.exitCode).toBeNull();
       expect(next!.error).toBe("db exited with code 1");
     });
 
@@ -52,11 +54,13 @@ describe("ServiceTransition", () => {
     });
 
     it("Starting + SpawnFailed → Failed with error", () => {
-      const result = applyEvent(make("db", { status: "Starting" }), {
+      const result = applyEvent(make("db", { status: "Starting", pid: 1234, exitCode: 1 }), {
         _tag: "SpawnFailed",
         error: "spawn gate failed",
       });
       expect(result?.status).toBe("Failed");
+      expect(result?.pid).toBeNull();
+      expect(result?.exitCode).toBeNull();
       expect(result?.error).toBe("spawn gate failed");
     });
 

From af6c0275a4301e946353140e2c9951315cb7a411 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 11:03:08 +0200
Subject: [PATCH 27/44] fix(stack): align dependent startup deadlines

---
 packages/stack/src/StackBuilder.ts            | 30 ++++++++++++++-----
 packages/stack/src/StackBuilder.unit.test.ts  |  8 +++++
 .../src/services/health-budgets.unit.test.ts  |  8 ++++-
 3 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/packages/stack/src/StackBuilder.ts b/packages/stack/src/StackBuilder.ts
index 9d7b8109f8..51cc3d6e9b 100644
--- a/packages/stack/src/StackBuilder.ts
+++ b/packages/stack/src/StackBuilder.ts
@@ -325,6 +325,16 @@ const dependsOnPostgres = (hasPostgresInit: boolean): ReadonlyArray<ServiceDepen
     ? [{ service: "postgres-init", condition: "completed" }]
     : [{ service: "postgres", condition: "healthy" }];
 
+const POSTGRES_DEPENDENCY_TIMEOUT_SECONDS = dependencyTimeoutSecondsForServices(["postgres"]);
+const STORAGE_DEPENDENCY_TIMEOUT_SECONDS = dependencyTimeoutSecondsForServices([
+  "postgres",
+  "storage",
+]);
+const ANALYTICS_DEPENDENCY_TIMEOUT_SECONDS = dependencyTimeoutSecondsForServices([
+  "postgres",
+  "analytics",
+]);
+
 const publicServiceProjection = (
   defs: ReadonlyArray<ServiceDef>,
   hasPostgresInit: boolean,
@@ -588,6 +598,7 @@ export class StackBuilder extends Context.Service<
               dbPort: config.dbPort,
               autoExposeNewTables: config.postgres.autoExposeNewTables,
             }),
+            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
             enabled: true,
           });
         }
@@ -625,6 +636,7 @@ export class StackBuilder extends Context.Service<
               : {
                   dependencies: [{ service: "postgres", condition: "healthy" as const }],
                 }),
+            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
             enabled: true,
           });
         }
@@ -663,6 +675,7 @@ export class StackBuilder extends Context.Service<
                   apiPort: config.apiPort,
                   dependencies: postgresDeps,
                 })),
+            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
             enabled: true,
           });
         }
@@ -691,6 +704,7 @@ export class StackBuilder extends Context.Service<
                   networkArgs: dockerNetworkArgs(platform.os, [config.edgeRuntime.port]),
                   dependencies: postgresDeps,
                 })),
+            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
             enabled: true,
           });
         }
@@ -732,6 +746,7 @@ export class StackBuilder extends Context.Service<
               networkArgs: dockerNetworkArgs(platform.os, [config.realtime.port]),
               dependencies: postgresDeps,
             }),
+            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
             enabled: true,
           });
         }
@@ -759,6 +774,7 @@ export class StackBuilder extends Context.Service<
               dependencies: postgresDeps,
               cleanupDataDirOnExit: hasAutoManagedPath(config, config.storage.dataDir),
             }),
+            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
             enabled: true,
           });
         }
@@ -775,6 +791,7 @@ export class StackBuilder extends Context.Service<
               networkArgs: dockerNetworkArgs(platform.os, [config.imgproxy.port]),
               dependencies: [{ service: "storage", condition: "healthy" }],
             }),
+            dependencyTimeoutSeconds: STORAGE_DEPENDENCY_TIMEOUT_SECONDS,
             enabled: true,
           });
         }
@@ -791,6 +808,7 @@ export class StackBuilder extends Context.Service<
               networkArgs: dockerNetworkArgs(platform.os, [config.pgmeta.port]),
               dependencies: postgresDeps,
             }),
+            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
             enabled: true,
           });
         }
@@ -818,6 +836,7 @@ export class StackBuilder extends Context.Service<
               ]),
               dependencies: postgresDeps,
             }),
+            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
             enabled: true,
           });
         }
@@ -835,10 +854,7 @@ export class StackBuilder extends Context.Service<
               networkArgs: dockerNetworkArgs(platform.os, []),
               dependencies: [{ service: "analytics", condition: "healthy" }],
             }),
-            dependencyTimeoutSeconds: dependencyTimeoutSecondsForServices([
-              "postgres",
-              "analytics",
-            ]),
+            dependencyTimeoutSeconds: ANALYTICS_DEPENDENCY_TIMEOUT_SECONDS,
             enabled: true,
           });
         }
@@ -874,6 +890,7 @@ export class StackBuilder extends Context.Service<
               ]),
               dependencies: postgresDeps,
             }),
+            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
             enabled: true,
           });
         }
@@ -908,10 +925,7 @@ export class StackBuilder extends Context.Service<
                       { service: "analytics", condition: "healthy" },
                     ],
             }),
-            dependencyTimeoutSeconds: dependencyTimeoutSecondsForServices([
-              "postgres",
-              "analytics",
-            ]),
+            dependencyTimeoutSeconds: ANALYTICS_DEPENDENCY_TIMEOUT_SECONDS,
             enabled: true,
           });
         }
diff --git a/packages/stack/src/StackBuilder.unit.test.ts b/packages/stack/src/StackBuilder.unit.test.ts
index f8c7f40765..81f98dc56e 100644
--- a/packages/stack/src/StackBuilder.unit.test.ts
+++ b/packages/stack/src/StackBuilder.unit.test.ts
@@ -11,6 +11,7 @@ import { nativePostgresNeedsDockerAccess } from "./StackBuilder.ts";
 import type { AllocatedPorts } from "./PortAllocator.ts";
 import { StackPreparation } from "./StackPreparation.ts";
 import type { StackPreparationInput } from "./StackPreparation.ts";
+import { dependencyTimeoutSecondsForServices } from "./services/health-budgets.ts";
 import { DEFAULT_VERSIONS } from "./versions.ts";
 
 const testJwtSecret = "super-secret-jwt-token-with-at-least-32-characters";
@@ -204,6 +205,13 @@ describe("StackBuilder", () => {
       expect(names.indexOf("postgres-init")).toBeLessThan(names.indexOf("postgrest"));
       expect(names.indexOf("postgres-init")).toBeLessThan(names.indexOf("auth"));
 
+      const postgresDependencyTimeout = dependencyTimeoutSecondsForServices(["postgres"]);
+      for (const name of ["postgres-init", "postgrest", "auth"]) {
+        expect(
+          graph.startOrder.find((service) => service.name === name)?.dependencyTimeoutSeconds,
+        ).toBe(postgresDependencyTimeout);
+      }
+
       expect(serviceProjection.get("postgres")).toEqual({ visibility: "public" });
       expect(serviceProjection.get("postgres-init")).toEqual({
         visibility: "internal",
diff --git a/packages/stack/src/services/health-budgets.unit.test.ts b/packages/stack/src/services/health-budgets.unit.test.ts
index 557b9cdf38..e9840ea45e 100644
--- a/packages/stack/src/services/health-budgets.unit.test.ts
+++ b/packages/stack/src/services/health-budgets.unit.test.ts
@@ -125,7 +125,13 @@ describe("stack health budgets", () => {
     `);
   });
 
-  it("keeps dependency timeouts beyond the dependency startup budget", () => {
+  it("keeps dependency timeouts beyond each dependency startup path", () => {
+    expect(dependencyTimeoutSecondsForServices(["postgres"])).toBeGreaterThan(
+      stackServiceStartupBudgetSeconds.postgres,
+    );
+    expect(dependencyTimeoutSecondsForServices(["postgres", "storage"])).toBeGreaterThan(
+      stackServiceStartupBudgetSeconds.postgres + stackServiceStartupBudgetSeconds.storage,
+    );
     expect(dependencyTimeoutSecondsForServices(["postgres", "analytics"])).toBeGreaterThan(
       stackServiceStartupBudgetSeconds.postgres + stackServiceStartupBudgetSeconds.analytics,
     );

From 908ed4df9831106b4e645fa00b13f95d1dc53772 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 13:54:52 +0200
Subject: [PATCH 28/44] chore(stack): document dependency startup path

---
 packages/stack/src/StackBuilder.ts | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/packages/stack/src/StackBuilder.ts b/packages/stack/src/StackBuilder.ts
index 85586950c2..cfc963268b 100644
--- a/packages/stack/src/StackBuilder.ts
+++ b/packages/stack/src/StackBuilder.ts
@@ -50,6 +50,9 @@ const dockerOnlyServices = SERVICE_NAMES.filter(
   (service) => serviceMetadata(service).runtimeSupport === "docker-only",
 );
 
+// Longest serial health-check path to analytics; keep aligned with its transitive dependencies.
+const analyticsStartupPath: ReadonlyArray<ServiceName> = ["postgres", "analytics"];
+
 const dependsOnPostgres = (hasPostgresInit: boolean): ReadonlyArray<ServiceDependency> =>
   hasPostgresInit
     ? [{ service: "postgres-init", condition: "completed" }]
@@ -518,10 +521,7 @@ export class StackBuilder extends Context.Service<
               networkArgs: dockerNetworkArgs(platform.os, []),
               dependencies: [{ service: "analytics", condition: "healthy" }],
             }),
-            dependencyTimeoutSeconds: dependencyTimeoutSecondsForServices([
-              "postgres",
-              "analytics",
-            ]),
+            dependencyTimeoutSeconds: dependencyTimeoutSecondsForServices(analyticsStartupPath),
             enabled: true,
           });
         }
@@ -591,10 +591,7 @@ export class StackBuilder extends Context.Service<
                       { service: "analytics", condition: "healthy" },
                     ],
             }),
-            dependencyTimeoutSeconds: dependencyTimeoutSecondsForServices([
-              "postgres",
-              "analytics",
-            ]),
+            dependencyTimeoutSeconds: dependencyTimeoutSecondsForServices(analyticsStartupPath),
             enabled: true,
           });
         }

From 5a298f1834ed36d2f36bf614f74f4e06e27067e8 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 13:59:42 +0200
Subject: [PATCH 29/44] test(stack): align Docker setup timeout

---
 packages/stack/tests/createStack-docker.e2e.test.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/stack/tests/createStack-docker.e2e.test.ts b/packages/stack/tests/createStack-docker.e2e.test.ts
index 1016af64b2..f957492e72 100644
--- a/packages/stack/tests/createStack-docker.e2e.test.ts
+++ b/packages/stack/tests/createStack-docker.e2e.test.ts
@@ -6,10 +6,13 @@ import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { activationTimeoutSecondsForService } from "../src/ServiceActivation.ts";
 import { createStack, type StackHandle } from "../src/node.ts";
+import { dependencyTimeoutSecondsForServices } from "../src/services/health-budgets.ts";
 import { setupTestTable } from "./helpers/e2e.ts";
 
 const STACK_DOCKER_E2E_TEST_TIMEOUT_MS = 180_000;
-const STACK_DOCKER_E2E_SETUP_TIMEOUT_MS = 90_000;
+const STACK_DOCKER_E2E_SETUP_OVERHEAD_MS = 90_000;
+const STACK_DOCKER_E2E_SETUP_TIMEOUT_MS =
+  dependencyTimeoutSecondsForServices(["postgres"]) * 1000 + STACK_DOCKER_E2E_SETUP_OVERHEAD_MS;
 const ANALYTICS_COLD_START_TEST_TIMEOUT_MS = activationTimeoutSecondsForService("analytics") * 1000;
 
 function hasDockerDaemon(): boolean {

From 1184ec5170b04cd73d2d67dd3755f3a0dbe84050 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 14:07:38 +0200
Subject: [PATCH 30/44] fix(process-compose): terminate timed-out cleanup trees

---
 packages/process-compose/docs/architecture.md |  7 +-
 .../src/SupervisorRuntime.unit.test.ts        | 22 ++++-
 .../process-compose/src/supervisor-runtime.ts | 82 +++++++++++++------
 3 files changed, 80 insertions(+), 31 deletions(-)

diff --git a/packages/process-compose/docs/architecture.md b/packages/process-compose/docs/architecture.md
index 03622f17ff..1afc47e127 100644
--- a/packages/process-compose/docs/architecture.md
+++ b/packages/process-compose/docs/architecture.md
@@ -223,9 +223,10 @@ optional timeout (default 5 seconds), plus `RemovePath` for filesystem cleanup.
 receive the managed child's sanitized environment, without the supervisor self-dispatch protocol
 variables. The supervisor rejects a malformed decoded cleanup contract before spawning the child,
 while individual execution failures remain best-effort. Callers must choose idempotent commands
-because owner-loss signals can race. `RunCommand` actions execute synchronously and therefore
-serialize; callers that configure several commands must budget for an aggregate duration up to the
-sum of their individual timeouts. Filesystem retry delays may overlap command execution.
+because owner-loss signals can race. `RunCommand` actions execute serially, so their aggregate
+duration can approach the sum of their individual timeouts. Each command runs in its own process
+group on Unix, while Windows uses `taskkill /T`; a timeout therefore terminates the command tree
+rather than only its root. Filesystem retry delays may overlap command execution.
 
 ## Supervisor runtime
 
diff --git a/packages/process-compose/src/SupervisorRuntime.unit.test.ts b/packages/process-compose/src/SupervisorRuntime.unit.test.ts
index de8fa96894..4cdd6321eb 100644
--- a/packages/process-compose/src/SupervisorRuntime.unit.test.ts
+++ b/packages/process-compose/src/SupervisorRuntime.unit.test.ts
@@ -195,9 +195,10 @@ describe("supervisor-runtime", () => {
     expect(childEnv).toEqual({ KEEP_ME: "value" });
   });
 
-  test("bounds a cleanup command by its timeout and continues remaining cleanup", async () => {
+  test("bounds a cleanup command tree by its timeout and continues remaining cleanup", async () => {
     const tempDir = mkdtempSync(path.join(tmpdir(), "process-compose-supervisor-timeout-"));
     const cleanupDir = path.join(tempDir, "cleanup-dir");
+    const cleanupWorkerPidFile = path.join(tempDir, "cleanup-worker.pid");
     const childScriptPath = path.join(tempDir, "child.mjs");
     mkdirSync(cleanupDir);
     writeFileSync(childScriptPath, "process.exit(0);\n");
@@ -209,7 +210,16 @@ describe("supervisor-runtime", () => {
           {
             _tag: "RunCommand",
             executable: process.execPath,
-            args: ["-e", 'process.on("SIGTERM", () => {}); setInterval(() => {}, 1000)'],
+            args: [
+              "-e",
+              [
+                `const { spawn } = require("node:child_process");`,
+                `const { writeFileSync } = require("node:fs");`,
+                `const worker = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], { stdio: "ignore" });`,
+                `writeFileSync(${JSON.stringify(cleanupWorkerPidFile)}, String(worker.pid));`,
+                `setInterval(() => {}, 1000);`,
+              ].join("\n"),
+            ],
             timeoutMs: 100,
           },
           { _tag: "RemovePath", path: cleanupDir, recursive: true },
@@ -222,8 +232,16 @@ describe("supervisor-runtime", () => {
       await waitFor(() => supervisor.exitCode != null);
       expect(supervisor.exitCode).toBe(0);
       expect(existsSync(cleanupDir)).toBe(false);
+      const cleanupWorkerPid = Number.parseInt(readFileSync(cleanupWorkerPidFile, "utf8"), 10);
+      expect(Number.isSafeInteger(cleanupWorkerPid)).toBe(true);
+      await waitFor(() => !isPidAlive(cleanupWorkerPid));
     } finally {
       supervisor.kill("SIGKILL");
+      if (existsSync(cleanupWorkerPidFile)) {
+        try {
+          process.kill(Number.parseInt(readFileSync(cleanupWorkerPidFile, "utf8"), 10), "SIGKILL");
+        } catch {}
+      }
       rmSync(tempDir, { recursive: true, force: true });
     }
   });
diff --git a/packages/process-compose/src/supervisor-runtime.ts b/packages/process-compose/src/supervisor-runtime.ts
index df87862cca..f3114183f5 100644
--- a/packages/process-compose/src/supervisor-runtime.ts
+++ b/packages/process-compose/src/supervisor-runtime.ts
@@ -9,6 +9,7 @@ import {
 } from "./supervisor-protocol.ts";
 
 type RemovePathAction = Extract<ExternalCleanupAction, { readonly _tag: "RemovePath" }>;
+type RunCommandAction = Extract<ExternalCleanupAction, { readonly _tag: "RunCommand" }>;
 
 interface SupervisorRuntimeConfig {
   readonly command: string;
@@ -233,14 +234,10 @@ export function runSupervisorRuntime(encodedConfig = process.argv[2]): void {
     }
   };
 
-  const killChildTree = (signal: ChildProcess.Signal): void => {
-    if (child.pid == null) {
-      return;
-    }
-
+  const killProcessTree = (pid: number, signal: ChildProcess.Signal): void => {
     if (isWindows) {
       try {
-        execFileSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], {
+        execFileSync("taskkill", ["/PID", String(pid), "/T", "/F"], {
           stdio: "ignore",
           timeout: 5_000,
         });
@@ -250,16 +247,48 @@ export function runSupervisorRuntime(encodedConfig = process.argv[2]): void {
     }
 
     try {
-      process.kill(-child.pid, signal);
+      process.kill(-pid, signal);
       return;
     } catch {}
 
     try {
-      process.kill(child.pid, signal);
+      process.kill(pid, signal);
     } catch {}
   };
 
-  const runCleanup = () => {
+  const killChildTree = (signal: ChildProcess.Signal): void => {
+    if (child.pid != null) {
+      killProcessTree(child.pid, signal);
+    }
+  };
+
+  const runCleanupCommand = (action: RunCommandAction): Promise<void> =>
+    new Promise((resolve) => {
+      const cleanupChild = spawn(action.executable, action.args, {
+        detached: !isWindows,
+        env: childEnv,
+        stdio: "ignore",
+      });
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+      const finish = () => {
+        if (timeoutId != null) {
+          clearTimeout(timeoutId);
+        }
+        resolve();
+      };
+
+      cleanupChild.once("error", finish);
+      cleanupChild.once("exit", finish);
+      timeoutId = setTimeout(() => {
+        if (cleanupChild.pid != null) {
+          killProcessTree(cleanupChild.pid, "SIGKILL");
+        }
+        finish();
+      }, action.timeoutMs ?? DEFAULT_CLEANUP_COMMAND_TIMEOUT_MS);
+    });
+
+  const runCleanup = async (): Promise<void> => {
     const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
     const removePathWithRetry = async (action: RemovePathAction): Promise<void> => {
       for (let attempt = 0; attempt < 20; attempt++) {
@@ -275,25 +304,26 @@ export function runSupervisorRuntime(encodedConfig = process.argv[2]): void {
       }
     };
 
-    // `RunCommand` uses the synchronous child-process API, so command actions execute serially
-    // while `RemovePath` retry delays may overlap. Each command has its own timeout; the aggregate
-    // cleanup duration can therefore approach the sum of all command timeouts.
-    return Promise.all(
-      (config.cleanup ?? []).map(async (action) => {
+    const runCommands = async () => {
+      for (const action of config.cleanup ?? []) {
+        if (action._tag !== "RunCommand") {
+          continue;
+        }
+
         try {
-          if (action._tag === "RunCommand") {
-            execFileSync(action.executable, action.args, {
-              env: childEnv,
-              stdio: "ignore",
-              timeout: action.timeoutMs ?? DEFAULT_CLEANUP_COMMAND_TIMEOUT_MS,
-              killSignal: "SIGKILL",
-            });
-          } else if (action._tag === "RemovePath") {
-            await removePathWithRetry(action);
-          }
+          await runCleanupCommand(action);
         } catch {}
-      }),
-    ).then(() => undefined);
+      }
+    };
+
+    // Commands serialize so their worst-case timeouts add together. Each runs in its own Unix
+    // process group (or uses taskkill on Windows), allowing a timeout to terminate its whole tree.
+    await Promise.all([
+      runCommands(),
+      ...(config.cleanup ?? []).map((action) =>
+        action._tag === "RemovePath" ? removePathWithRetry(action) : Promise.resolve(),
+      ),
+    ]);
   };
 
   const shutdown = async (signal: ChildProcess.Signal): Promise<void> => {

From 1abd493ea4d0df1f1f3cfa06b007dcb57d17b76e Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 14:07:59 +0200
Subject: [PATCH 31/44] fix(stack): keep pre-start failures retryable

---
 packages/stack/src/LocalStack.ts      | 15 +++++-----
 packages/stack/src/Stack.unit.test.ts | 42 +++++++++++++++++++++++++++
 2 files changed, 49 insertions(+), 8 deletions(-)

diff --git a/packages/stack/src/LocalStack.ts b/packages/stack/src/LocalStack.ts
index 77f2e901a3..bf34b6393d 100644
--- a/packages/stack/src/LocalStack.ts
+++ b/packages/stack/src/LocalStack.ts
@@ -669,10 +669,6 @@ export const localStackLayer = (
             disposeOnce().pipe(Effect.andThen(Effect.fail(error))),
           ),
         );
-      const cleanupOnStartupFailure = <A, E, R>(
-        effect: Effect.Effect<A, E, R>,
-      ): Effect.Effect<A, E, R> => effect.pipe(Effect.onError(() => disposeOnce()));
-
       yield* Effect.addFinalizer(disposeOnce);
 
       const activateService = (name: ServiceName) =>
@@ -701,12 +697,14 @@ export const localStackLayer = (
 
       const stack = {
         getInfo: () => Effect.succeed(info),
-        start: () =>
-          Effect.gen(function* () {
+        start: () => {
+          let serviceStartupBegan = false;
+          return Effect.gen(function* () {
             yield* requireMutable("start");
             yield* Ref.set(phaseRef, "starting");
             const runtime = yield* ensureRuntime;
             yield* configureFunctions(config);
+            serviceStartupBegan = true;
 
             if (config.startupMode === "lazy") {
               const readiness: Array<Effect.Effect<void, ServiceReadyError | StackBuildError>> = [];
@@ -751,8 +749,9 @@ export const localStackLayer = (
           }).pipe(
             Effect.onError(() => Ref.set(phaseRef, "stopped")),
             withLifecycleLock,
-            cleanupOnStartupFailure,
-          ),
+            Effect.onError(() => (serviceStartupBegan ? disposeOnce() : Effect.void)),
+          );
+        },
         stop: () =>
           Effect.gen(function* () {
             if (disposed) {
diff --git a/packages/stack/src/Stack.unit.test.ts b/packages/stack/src/Stack.unit.test.ts
index 1a75250667..ee030350f1 100644
--- a/packages/stack/src/Stack.unit.test.ts
+++ b/packages/stack/src/Stack.unit.test.ts
@@ -5,6 +5,7 @@ import { createHmac } from "node:crypto";
 import { Deferred, Effect, Exit, Fiber, Layer, Stream } from "effect";
 import { mockChildProcessSpawner } from "../../process-compose/tests/helpers/mocks.ts";
 import { mockBinaryResolver } from "../tests/helpers/mocks.ts";
+import { StackBuildError } from "./errors.ts";
 import { defaultPublishableKey, defaultSecretKey, generateJwt } from "./JwtGenerator.ts";
 import type { AllocatedPorts, PortField, PortLease } from "./PortAllocator.ts";
 import { StackServiceActivator } from "./ServiceActivation.ts";
@@ -439,6 +440,47 @@ describe("Stack", () => {
     }).pipe(Effect.provide(providedLayer));
   });
 
+  it.live("can retry start after a build failure before services start", () => {
+    let buildAttempts = 0;
+    const graph = Effect.runSync(
+      buildGraph([{ name: "postgres", command: "true", restart: "no" }]),
+    );
+    const builderLayer = Layer.succeed(StackBuilder, {
+      build: () =>
+        Effect.suspend(() => {
+          buildAttempts += 1;
+          return buildAttempts === 1
+            ? Effect.fail(new StackBuildError({ detail: "transient build failure" }))
+            : Effect.succeed({
+                graph,
+                cleanupTargets: { dockerContainerNames: [] },
+                serviceProjection: new Map<string, { readonly visibility: "public" }>([
+                  ["postgres", { visibility: "public" }],
+                ]),
+              });
+        }),
+    });
+    const resolver = mockBinaryResolver();
+    const spawner = mockChildProcessSpawner();
+    const stackPreparationLayer = StackPreparation.layer.pipe(Layer.provide(resolver.layer));
+    const layer = localStackLayer(defaultConfig, noopPortLease(defaultConfig.ports)).pipe(
+      Layer.provide(builderLayer),
+      Layer.provide(stackPreparationLayer),
+      Layer.provide(StackMetadataPersistence.noop),
+      Layer.provide(spawner.layer),
+      Layer.provide(BunServices.layer),
+    );
+
+    return Effect.gen(function* () {
+      const stack = yield* Stack;
+
+      expect(Exit.isFailure(yield* stack.start().pipe(Effect.exit))).toBe(true);
+      yield* stack.start();
+
+      expect(buildAttempts).toBe(2);
+    }).pipe(Effect.provide(layer), Effect.timeout("5 seconds"));
+  });
+
   it.live("a partial startup failure disposes resources from services already started", () => {
     let cleaned = false;
     const spawner = mockChildProcessSpawner({

From e01aaf746de49ed113155272196465807d937687 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 14:11:23 +0200
Subject: [PATCH 32/44] fix(stack): align activation lifecycle ownership

---
 packages/stack/src/ApiProxy.ts                | 29 +-------
 packages/stack/src/ApiProxy.unit.test.ts      | 20 -----
 packages/stack/src/LocalStack.ts              | 74 ++++++-------------
 packages/stack/src/StackBuilder.ts            | 17 ++++-
 packages/stack/src/StackBuilder.unit.test.ts  |  7 ++
 packages/stack/src/StackStateProjection.ts    |  8 --
 .../src/StackStateProjection.unit.test.ts     | 19 -----
 packages/stack/src/createStack.ts             | 23 ++++--
 packages/stack/src/layers.ts                  |  6 +-
 9 files changed, 64 insertions(+), 139 deletions(-)

diff --git a/packages/stack/src/ApiProxy.ts b/packages/stack/src/ApiProxy.ts
index 51ac4e75ee..9a3f98041c 100644
--- a/packages/stack/src/ApiProxy.ts
+++ b/packages/stack/src/ApiProxy.ts
@@ -1,4 +1,4 @@
-import { Deferred, Effect, Layer, Option, Context, Duration, Schedule, Result } from "effect";
+import { Deferred, Effect, Layer, Option, Context, Schedule, Result } from "effect";
 import {
   Headers,
   HttpBody,
@@ -9,13 +9,11 @@ import {
   HttpServerRequest,
   HttpServerResponse,
 } from "effect/unstable/http";
-import { activationTimeoutSecondsForService, StackServiceActivator } from "./ServiceActivation.ts";
-import { StackReadinessError } from "./errors.ts";
+import { StackServiceActivator } from "./ServiceActivation.ts";
 import type { ServiceName } from "./ServiceName.ts";
 
 export interface ProxyConfig {
   readonly listenPort: number;
-  readonly activationTimeout?: Duration.Input | "infinite";
   readonly gotruePort: number;
   readonly postgrestPort: number;
   readonly postgrestAdminPort: number;
@@ -138,28 +136,7 @@ function makeProxyHandler(
 ) {
   return (req: HttpServerRequest.HttpServerRequest) =>
     Effect.gen(function* () {
-      const activationEffect = activator.activate(opts.service);
-      const activation = yield* (() => {
-        if (config.activationTimeout === "infinite") {
-          return activationEffect;
-        }
-        const activationTimeout =
-          config.activationTimeout ??
-          Duration.seconds(activationTimeoutSecondsForService(opts.service));
-        return activationEffect.pipe(
-          Effect.timeoutOrElse({
-            duration: activationTimeout,
-            orElse: () =>
-              Effect.fail(
-                new StackReadinessError({
-                  target: opts.service,
-                  timeoutMs: Duration.toMillis(activationTimeout),
-                  detail: `Timed out waiting for ${opts.service} activation`,
-                }),
-              ),
-          }),
-        );
-      })().pipe(
+      const activation = yield* activator.activate(opts.service).pipe(
         Effect.tapError((error) =>
           error._tag === "StackReadinessError" ? signalTerminalFailure : Effect.void,
         ),
diff --git a/packages/stack/src/ApiProxy.unit.test.ts b/packages/stack/src/ApiProxy.unit.test.ts
index 3d29dc85d5..2d13427352 100644
--- a/packages/stack/src/ApiProxy.unit.test.ts
+++ b/packages/stack/src/ApiProxy.unit.test.ts
@@ -275,26 +275,6 @@ describe("ApiProxy", () => {
     }
   });
 
-  test("returns 503 when service activation does not complete before the request deadline", async () => {
-    const activatorLayer = Layer.succeed(StackServiceActivator, {
-      activate: () => Effect.never,
-    });
-    const proxy = await startProxy(
-      { ...configForPort(echoServer.port), activationTimeout: "10 millis" },
-      activatorLayer,
-    );
-    try {
-      const res = await fetch(`${proxy.url}/rest/v1/users`, {
-        signal: AbortSignal.timeout(1_000),
-      });
-      expect(res.status).toBe(503);
-      expect(res.headers.get("retry-after")).toBe("1");
-      await expect(proxy.awaitTerminalFailure()).resolves.toBeUndefined();
-    } finally {
-      await proxy.dispose();
-    }
-  });
-
   // ---------------------------------------------------------------------------
   // Auth transformation — publishableKey → anonJwt
   // ---------------------------------------------------------------------------
diff --git a/packages/stack/src/LocalStack.ts b/packages/stack/src/LocalStack.ts
index 13edf5186c..363a7ac48a 100644
--- a/packages/stack/src/LocalStack.ts
+++ b/packages/stack/src/LocalStack.ts
@@ -40,11 +40,7 @@ import {
 } from "./StackBuilder.ts";
 import { resolveReadinessPolicy } from "./StackConfig.ts";
 import type { ReadinessPolicy, ReadyOptions, ResolvedStackConfig } from "./StackConfig.ts";
-import {
-  changedProjectedStates,
-  projectStackStates,
-  type StackServiceProjectionCatalog,
-} from "./StackStateProjection.ts";
+import { projectStackStates, type StackServiceProjectionCatalog } from "./StackStateProjection.ts";
 import { StackServiceState } from "./StackServiceState.ts";
 import { Stack } from "./Stack.ts";
 import type { EdgeRuntimeReloadConfig, StackInfo } from "./Stack.ts";
@@ -175,6 +171,7 @@ export const localStackLayer = (
       const stateRef = yield* SubscriptionRef.make(initialPublicStates(config));
       const phaseRef = yield* Ref.make<LifecyclePhase>("idle");
       const lifecycleLock = Semaphore.makeUnsafe(1);
+      const projectionLock = Semaphore.makeUnsafe(1);
 
       const logBufferServices = yield* Layer.buildWithScope(LogBuffer.layer, scope);
       const logBuffer = Context.get(logBufferServices, LogBuffer);
@@ -190,6 +187,17 @@ export const localStackLayer = (
             : [...current, nextState];
         });
 
+      const syncProjectedStates = (
+        orchestrator: Orchestrator["Service"],
+        serviceProjection: StackServiceProjectionCatalog,
+      ) =>
+        Effect.gen(function* () {
+          const rawStates = yield* orchestrator.getAllStates();
+          yield* Effect.forEach(projectStackStates(rawStates, serviceProjection), updateState, {
+            discard: true,
+          });
+        }).pipe(projectionLock.withPermit);
+
       const requireKnownService = (name: string) =>
         Effect.gen(function* () {
           const currentStates = SubscriptionRef.getUnsafe(stateRef);
@@ -347,40 +355,9 @@ export const localStackLayer = (
           const orchServices = yield* Layer.buildWithScope(orchLayer, scope);
           const orchestrator = Context.get(orchServices, Orchestrator);
 
-          const projectedStates = Stream.unwrap(
-            Effect.gen(function* () {
-              const rawInitialStates = yield* orchestrator.getAllStates();
-              const initialProjected = projectStackStates(rawInitialStates, serviceProjection);
-              let rawStates = new Map(
-                rawInitialStates.map((state) => [state.name, state] as const),
-              );
-              let projectedByName = new Map(
-                initialProjected.map((state) => [state.name, state] as const),
-              );
-
-              return Stream.concat(
-                Stream.fromIterable(initialProjected),
-                orchestrator.allStateChanges().pipe(
-                  Stream.map((rawState) => {
-                    rawStates.set(rawState.name, rawState);
-                    const nextProjected = projectStackStates(
-                      [...rawStates.values()],
-                      serviceProjection,
-                    );
-                    const changed = changedProjectedStates(projectedByName, nextProjected);
-                    projectedByName = new Map(
-                      nextProjected.map((state) => [state.name, state] as const),
-                    );
-                    return changed;
-                  }),
-                  Stream.flatMap((states) => Stream.fromIterable(states)),
-                ),
-              );
-            }),
-          );
-
-          yield* projectedStates.pipe(
-            Stream.runForEach((state) => updateState(state)),
+          yield* syncProjectedStates(orchestrator, serviceProjection);
+          yield* orchestrator.allStateChanges().pipe(
+            Stream.runForEach(() => syncProjectedStates(orchestrator, serviceProjection)),
             Effect.ignore,
             Effect.forkIn(scope),
           );
@@ -487,15 +464,8 @@ export const localStackLayer = (
           ),
         );
       const withLifecycleLock = lifecycleLock.withPermit;
-      const syncProjectedStates = (runtime: RuntimeState) =>
-        Effect.gen(function* () {
-          const rawStates = yield* runtime.orchestrator.getAllStates();
-          yield* Effect.forEach(
-            projectStackStates(rawStates, runtime.serviceProjection),
-            updateState,
-            { discard: true },
-          );
-        });
+      const syncRuntimeProjectedStates = (runtime: RuntimeState) =>
+        syncProjectedStates(runtime.orchestrator, runtime.serviceProjection);
       const serviceStartOptions = {
         beforeStart: (name: string) => portLease.reserve(portFieldsForService(name)),
         beforeSpawn: (name: string) => portLease.release(portFieldsForService(name)),
@@ -571,7 +541,7 @@ export const localStackLayer = (
                 ),
             { concurrency: "unbounded", discard: true },
           );
-          yield* syncProjectedStates(runtime);
+          yield* syncRuntimeProjectedStates(runtime);
         });
       const inspectStartedTargets = (root: ServiceName) =>
         Effect.gen(function* () {
@@ -742,7 +712,7 @@ export const localStackLayer = (
               yield* runtime.orchestrator
                 .waitAllReady()
                 .pipe((effect) => withReadinessPolicy(effect, "stack"));
-              yield* syncProjectedStates(runtime);
+              yield* syncRuntimeProjectedStates(runtime);
             }
             yield* Ref.set(phaseRef, "running");
           }).pipe(
@@ -888,7 +858,7 @@ export const localStackLayer = (
             yield* runtime.orchestrator
               .waitReady(name)
               .pipe((effect) => withReadinessPolicy(effect, name, opts));
-            yield* syncProjectedStates(runtime);
+            yield* syncRuntimeProjectedStates(runtime);
           }).pipe(cleanupOnReadinessFailure),
         waitAllReady: (opts) =>
           Effect.gen(function* () {
@@ -904,7 +874,7 @@ export const localStackLayer = (
             yield* runtime.orchestrator
               .waitAllReady()
               .pipe((effect) => withReadinessPolicy(effect, "stack", opts));
-            yield* syncProjectedStates(runtime);
+            yield* syncRuntimeProjectedStates(runtime);
           }).pipe(cleanupOnReadinessFailure),
         subscribeLogs: (name) => logBuffer.subscribe(name),
         subscribeAllLogs: (services) =>
diff --git a/packages/stack/src/StackBuilder.ts b/packages/stack/src/StackBuilder.ts
index cfc963268b..9913406157 100644
--- a/packages/stack/src/StackBuilder.ts
+++ b/packages/stack/src/StackBuilder.ts
@@ -50,9 +50,14 @@ const dockerOnlyServices = SERVICE_NAMES.filter(
   (service) => serviceMetadata(service).runtimeSupport === "docker-only",
 );
 
-// Longest serial health-check path to analytics; keep aligned with its transitive dependencies.
+// Serial health-check paths used by dependency waits; keep each path aligned
+// with the corresponding service's transitive dependencies.
+const postgresStartupPath: ReadonlyArray<ServiceName> = ["postgres"];
+const storageStartupPath: ReadonlyArray<ServiceName> = ["postgres", "storage"];
 const analyticsStartupPath: ReadonlyArray<ServiceName> = ["postgres", "analytics"];
 
+const postgresDependencyTimeoutSeconds = dependencyTimeoutSecondsForServices(postgresStartupPath);
+
 const dependsOnPostgres = (hasPostgresInit: boolean): ReadonlyArray<ServiceDependency> =>
   hasPostgresInit
     ? [{ service: "postgres-init", condition: "completed" }]
@@ -274,6 +279,7 @@ export class StackBuilder extends Context.Service<
               dbPort: config.dbPort,
               autoExposeNewTables: config.postgres.autoExposeNewTables,
             }),
+            dependencyTimeoutSeconds: postgresDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -311,6 +317,7 @@ export class StackBuilder extends Context.Service<
               : {
                   dependencies: [{ service: "postgres", condition: "healthy" as const }],
                 }),
+            dependencyTimeoutSeconds: postgresDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -349,6 +356,7 @@ export class StackBuilder extends Context.Service<
                   apiPort: config.apiPort,
                   dependencies: postgresDeps,
                 })),
+            dependencyTimeoutSeconds: postgresDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -377,6 +385,7 @@ export class StackBuilder extends Context.Service<
                   networkArgs: dockerNetworkArgs(platform.os, [config.edgeRuntime.port]),
                   dependencies: postgresDeps,
                 })),
+            dependencyTimeoutSeconds: postgresDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -418,6 +427,7 @@ export class StackBuilder extends Context.Service<
               networkArgs: dockerNetworkArgs(platform.os, [config.realtime.port]),
               dependencies: postgresDeps,
             }),
+            dependencyTimeoutSeconds: postgresDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -445,6 +455,7 @@ export class StackBuilder extends Context.Service<
               dependencies: postgresDeps,
               cleanupDataDirOnExit: hasAutoManagedPath(config, config.storage.dataDir),
             }),
+            dependencyTimeoutSeconds: postgresDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -461,6 +472,7 @@ export class StackBuilder extends Context.Service<
               networkArgs: dockerNetworkArgs(platform.os, [config.imgproxy.port]),
               dependencies: [{ service: "storage", condition: "healthy" }],
             }),
+            dependencyTimeoutSeconds: dependencyTimeoutSecondsForServices(storageStartupPath),
             enabled: true,
           });
         }
@@ -477,6 +489,7 @@ export class StackBuilder extends Context.Service<
               networkArgs: dockerNetworkArgs(platform.os, [config.pgmeta.port]),
               dependencies: postgresDeps,
             }),
+            dependencyTimeoutSeconds: postgresDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -504,6 +517,7 @@ export class StackBuilder extends Context.Service<
               ]),
               dependencies: postgresDeps,
             }),
+            dependencyTimeoutSeconds: postgresDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -557,6 +571,7 @@ export class StackBuilder extends Context.Service<
               ]),
               dependencies: postgresDeps,
             }),
+            dependencyTimeoutSeconds: postgresDependencyTimeoutSeconds,
             enabled: true,
           });
         }
diff --git a/packages/stack/src/StackBuilder.unit.test.ts b/packages/stack/src/StackBuilder.unit.test.ts
index 2fb442725c..2125107e89 100644
--- a/packages/stack/src/StackBuilder.unit.test.ts
+++ b/packages/stack/src/StackBuilder.unit.test.ts
@@ -205,6 +205,12 @@ describe("StackBuilder", () => {
       expect(names.indexOf("postgres-init")).toBeLessThan(names.indexOf("postgrest"));
       expect(names.indexOf("postgres-init")).toBeLessThan(names.indexOf("auth"));
 
+      for (const name of ["postgres-init", "postgrest", "auth"]) {
+        expect(
+          graph.startOrder.find((service) => service.name === name)?.dependencyTimeoutSeconds,
+        ).toBeGreaterThan(120);
+      }
+
       expect(serviceProjection.get("postgres")).toEqual({ visibility: "public" });
       expect(serviceProjection.get("postgres-init")).toEqual({
         visibility: "internal",
@@ -346,6 +352,7 @@ describe("StackBuilder", () => {
 
       const authDef = graph.startOrder.find((s) => s.name === "auth");
       expect(authDef?.dependencies).toEqual([{ service: "postgres", condition: "healthy" }]);
+      expect(authDef?.dependencyTimeoutSeconds).toBeGreaterThan(120);
     }).pipe(Effect.provide(layer));
   });
 
diff --git a/packages/stack/src/StackStateProjection.ts b/packages/stack/src/StackStateProjection.ts
index 9d741215b8..51b25512e8 100644
--- a/packages/stack/src/StackStateProjection.ts
+++ b/packages/stack/src/StackStateProjection.ts
@@ -1,5 +1,4 @@
 import type { ServiceState as RawServiceState } from "@supabase/process-compose";
-import { Equal } from "effect";
 import {
   StackServiceState,
   type StackServiceStatus,
@@ -84,10 +83,3 @@ export function projectStackState(
 ): StackServiceState | undefined {
   return projectStackStates(rawStates, catalog).find((state) => state.name === name);
 }
-
-export function changedProjectedStates(
-  previous: ReadonlyMap<string, StackServiceState>,
-  next: ReadonlyArray<StackServiceState>,
-): ReadonlyArray<StackServiceState> {
-  return next.filter((state) => !Equal.equals(previous.get(state.name), state));
-}
diff --git a/packages/stack/src/StackStateProjection.unit.test.ts b/packages/stack/src/StackStateProjection.unit.test.ts
index 8148da6fb0..7275ba764e 100644
--- a/packages/stack/src/StackStateProjection.unit.test.ts
+++ b/packages/stack/src/StackStateProjection.unit.test.ts
@@ -1,7 +1,6 @@
 import { describe, expect, test } from "vitest";
 import { ServiceState } from "@supabase/process-compose";
 import {
-  changedProjectedStates,
   projectStackState,
   projectStackStates,
   type StackServiceProjectionCatalog,
@@ -84,22 +83,4 @@ describe("projectStackStates", () => {
 
     expect(projected?.status).toBe("Healthy");
   });
-
-  test("suppresses structurally equal projected states", () => {
-    const previousStates = projectStackStates(
-      [rawState("postgres", "Healthy"), rawState("auth", "Running")],
-      projectionCatalog,
-    );
-    const nextStates = projectStackStates(
-      [rawState("postgres", "Healthy"), rawState("auth", "Running")],
-      projectionCatalog,
-    );
-
-    expect(
-      changedProjectedStates(
-        new Map(previousStates.map((state) => [state.name, state])),
-        nextStates,
-      ),
-    ).toEqual([]);
-  });
 });
diff --git a/packages/stack/src/createStack.ts b/packages/stack/src/createStack.ts
index 3aaeb48a7d..24752da00c 100644
--- a/packages/stack/src/createStack.ts
+++ b/packages/stack/src/createStack.ts
@@ -1,10 +1,11 @@
 import type { LogEntry } from "@supabase/process-compose";
-import { Effect, type Layer, ManagedRuntime, Stream } from "effect";
+import { Context, Effect, type Layer, ManagedRuntime, Stream } from "effect";
 import { FileSystem, Path } from "effect";
 import { HttpServer } from "effect/unstable/http";
 import { ChildProcessSpawner } from "effect/unstable/process";
 import { cleanupAutoManagedPaths, dockerForceRemove } from "./cleanup.ts";
 import type { CleanupTargets } from "./CleanupTargets.ts";
+import { ApiProxy } from "./ApiProxy.ts";
 import { toStackError } from "./errors.ts";
 import type { FunctionsConfig } from "./functions.ts";
 import { daemonLayer, foregroundLayer, type DaemonStartError } from "./layers.ts";
@@ -138,11 +139,8 @@ export async function createStack(
 
     try {
       const services = await runtime.context();
-      const localStack = await runtime.runPromise(
-        Effect.gen(function* () {
-          return yield* Stack;
-        }),
-      );
+      const localStack = Context.get(services, Stack);
+      const apiProxy = Context.get(services, ApiProxy);
       const info = await runtime.runPromise(localStack.getInfo());
 
       const run = <A>(effect: Effect.Effect<A, unknown>) =>
@@ -150,10 +148,19 @@ export async function createStack(
           throw toStackError(error);
         });
 
-      const gracefulDispose = async () => {
-        await runtime.dispose().catch(() => {});
+      let disposal: Promise<void> | undefined;
+      const gracefulDispose = () => {
+        disposal ??= runtime.dispose().catch(() => {});
+        return disposal;
       };
 
+      // A terminal lazy-activation timeout disposes LocalStack. Close the
+      // foreground runtime as well so the public API port cannot outlive it.
+      void runtime
+        .runPromise(apiProxy.awaitTerminalFailure)
+        .then(gracefulDispose)
+        .catch(() => {});
+
       const stack: StackHandle = {
         url: info.url,
         dbUrl: info.dbUrl,
diff --git a/packages/stack/src/layers.ts b/packages/stack/src/layers.ts
index 00d44270e5..c0afe22dcb 100644
--- a/packages/stack/src/layers.ts
+++ b/packages/stack/src/layers.ts
@@ -45,7 +45,7 @@ export const foregroundLayer = (
   config: ResolvedStackConfig,
   platformFactory: PlatformFactory,
   portLease: PortLease,
-): Layer.Layer<Stack> => {
+): Layer.Layer<Stack | ApiProxy> => {
   const platform = platformFactory({
     apiPort: config.apiPort,
     releaseApiPort: portLease.release(["apiPort"]),
@@ -63,8 +63,6 @@ export const foregroundLayer = (
 
   const proxyConfig: ProxyConfig = {
     listenPort: config.apiPort,
-    activationTimeout:
-      config.readiness.mode === "infinite" ? "infinite" : config.readiness.timeoutMs,
     gotruePort: config.auth !== false ? config.auth.port : 0,
     postgrestPort: config.postgrest !== false ? config.postgrest.port : 0,
     postgrestAdminPort: config.postgrest !== false ? config.postgrest.adminPort : 0,
@@ -115,8 +113,6 @@ export const foregroundDaemonLayer = (
   );
   const proxyConfig: ProxyConfig = {
     listenPort: config.apiPort,
-    activationTimeout:
-      config.readiness.mode === "infinite" ? "infinite" : config.readiness.timeoutMs,
     gotruePort: config.auth !== false ? config.auth.port : 0,
     postgrestPort: config.postgrest !== false ? config.postgrest.port : 0,
     postgrestAdminPort: config.postgrest !== false ? config.postgrest.adminPort : 0,

From d5ae5820899d5c8658097d14ba7f5363b9e799b8 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 14:13:02 +0200
Subject: [PATCH 33/44] fix(stack): harden functions bundle reloads

---
 .../functions/dev/functions-dev-runtime.ts    | 80 +++++++++----------
 packages/stack/README.md                      |  5 ++
 .../src/DaemonServer.integration.test.ts      |  1 +
 packages/stack/src/DaemonServer.ts            |  8 +-
 packages/stack/src/LocalStack.ts              | 40 +++++++---
 .../stack/src/RemoteStack.integration.test.ts | 19 +++++
 packages/stack/src/Stack.unit.test.ts         | 29 ++++++-
 packages/stack/src/StackConfigResolver.ts     | 19 ++++-
 packages/stack/src/functions.ts               | 45 ++++++++++-
 packages/stack/src/functions.unit.test.ts     | 33 +++++++-
 10 files changed, 214 insertions(+), 65 deletions(-)

diff --git a/apps/cli/src/next/commands/functions/dev/functions-dev-runtime.ts b/apps/cli/src/next/commands/functions/dev/functions-dev-runtime.ts
index 0f73099841..ba348f6aa6 100644
--- a/apps/cli/src/next/commands/functions/dev/functions-dev-runtime.ts
+++ b/apps/cli/src/next/commands/functions/dev/functions-dev-runtime.ts
@@ -225,53 +225,51 @@ export const runFunctionsDevRuntime = Effect.fnUntraced(function* (
     ...opts,
     edgeRuntime: edgeRuntimeState.config,
   });
-  yield* ensureFunctionsDirectory();
-  yield* reloadEdgeRuntime(stack, opts, edgeRuntimeState.config);
-  const info = yield* stack.getInfo();
-  const watchPathList = yield* functionsDevWatchPaths(opts.envFile);
-
-  yield* output.success("Edge Functions dev server is running.", {
-    functions_url: `${info.url}/functions/v1`,
-  });
-  yield* output.info(`Functions URL: ${info.url}/functions/v1/<function-name>`);
-
-  const restartOnChange = watchPaths(watchPathList).pipe(
-    Stream.runForEach((change) =>
-      Effect.gen(function* () {
-        const result = yield* applyWatchedChange(edgeRuntimeState, change);
-        if (result.action === "edge-runtime") {
-          yield* output.info("Edge runtime config changed. Restarting edge-runtime...");
-          yield* reloadEdgeRuntime(stack, opts, result.state.config);
+  const restoreFunctions = startedByCommand
+    ? undefined
+    : yield* resolveFunctionsBundle({ envFile: Option.none(), noVerifyJwt: false });
+
+  yield* Effect.gen(function* () {
+    yield* ensureFunctionsDirectory();
+    yield* reloadEdgeRuntime(stack, opts, edgeRuntimeState.config);
+    const info = yield* stack.getInfo();
+    const watchPathList = yield* functionsDevWatchPaths(opts.envFile);
+
+    yield* output.success("Edge Functions dev server is running.", {
+      functions_url: `${info.url}/functions/v1`,
+    });
+    yield* output.info(`Functions URL: ${info.url}/functions/v1/<function-name>`);
+
+    const restartOnChange = watchPaths(watchPathList).pipe(
+      Stream.runForEach((change) =>
+        Effect.gen(function* () {
+          const result = yield* applyWatchedChange(edgeRuntimeState, change);
+          if (result.action === "edge-runtime") {
+            yield* output.info("Edge runtime config changed. Restarting edge-runtime...");
+            yield* reloadEdgeRuntime(stack, opts, result.state.config);
+            edgeRuntimeState = result.state;
+            return;
+          }
           edgeRuntimeState = result.state;
-          return;
-        }
-        edgeRuntimeState = result.state;
-        yield* output.info("Function files changed. Restarting edge-runtime...");
-        yield* stack.reloadFunctions({ functions: yield* resolveFunctionsBundle(opts) });
-      }).pipe(
-        Effect.catch((error) =>
-          output.error(error instanceof Error ? error.message : String(error)),
+          yield* output.info("Function files changed. Restarting edge-runtime...");
+          yield* stack.reloadFunctions({ functions: yield* resolveFunctionsBundle(opts) });
+        }).pipe(
+          Effect.catch((error) =>
+            output.error(error instanceof Error ? error.message : String(error)),
+          ),
         ),
       ),
-    ),
-  );
+    );
 
-  const logs = logEntryStream(stack).pipe(Stream.runForEach((event) => output.event(event)));
-  const shutdown = processControl.awaitShutdown;
+    const logs = logEntryStream(stack).pipe(Stream.runForEach((event) => output.event(event)));
+    const shutdown = processControl.awaitShutdown;
 
-  yield* Effect.raceFirst(Effect.raceFirst(restartOnChange, logs), shutdown).pipe(
+    yield* Effect.raceFirst(Effect.raceFirst(restartOnChange, logs), shutdown);
+  }).pipe(
     Effect.ensuring(
-      Effect.gen(function* () {
-        if (startedByCommand) {
-          yield* stack.dispose().pipe(Effect.ignore);
-        } else {
-          const functions = yield* resolveFunctionsBundle({
-            envFile: Option.none(),
-            noVerifyJwt: false,
-          });
-          yield* stack.reloadFunctions({ functions }).pipe(Effect.ignore);
-        }
-      }).pipe(Effect.ignore),
+      startedByCommand
+        ? stack.dispose().pipe(Effect.ignore)
+        : stack.reloadFunctions({ functions: restoreFunctions }).pipe(Effect.ignore),
     ),
   );
 });
diff --git a/packages/stack/README.md b/packages/stack/README.md
index ee5285f8c2..0294bc01e8 100644
--- a/packages/stack/README.md
+++ b/packages/stack/README.md
@@ -136,7 +136,9 @@ The stack accepts an explicit, fully resolved Functions bundle. Paths must be ab
 caller owns project-file discovery, environment-file parsing, and manifest interpretation:
 
 ```typescript
+const projectDir = "/absolute/project";
 const stack = await createStack({
+  projectDir,
   functions: {
     env: { SHARED_VALUE: "available to every function" },
     functions: [
@@ -153,6 +155,9 @@ const stack = await createStack({
 });
 ```
 
+Every referenced path must be contained by `projectDir` so the same bundle works when Edge Runtime
+runs in Docker and the project directory is bind-mounted into the container.
+
 Per-function environment values override shared values. Stack-owned runtime URLs and credentials
 take final precedence. To update the active bundle, call
 `reloadFunctions({ functions: nextBundle })`; `reloadFunctions()` preserves and reapplies the most
diff --git a/packages/stack/src/DaemonServer.integration.test.ts b/packages/stack/src/DaemonServer.integration.test.ts
index d7d8664210..7bd0988a41 100644
--- a/packages/stack/src/DaemonServer.integration.test.ts
+++ b/packages/stack/src/DaemonServer.integration.test.ts
@@ -416,6 +416,7 @@ describe("DaemonServer", () => {
 
     expect(res.status).toBe(400);
     expect(responseText).toContain("Invalid Edge Functions reload payload");
+    expect(JSON.parse(responseText)).toMatchObject({ code: "STACK_BUILD_ERROR" });
     expect(responseText).not.toContain(secret);
     expect(responseText).not.toContain("relative/index.ts");
   });
diff --git a/packages/stack/src/DaemonServer.ts b/packages/stack/src/DaemonServer.ts
index 4fb874f8a5..09f205e794 100644
--- a/packages/stack/src/DaemonServer.ts
+++ b/packages/stack/src/DaemonServer.ts
@@ -33,7 +33,7 @@ export class DaemonServer extends Context.Service<
         const server = yield* HttpServer.HttpServer;
         const shutdownDeferred = yield* Deferred.make<void>();
         const textEncoder = new TextEncoder();
-        const errorResponse = (body: DaemonErrorResponse, status: 404 | 500) =>
+        const errorResponse = (body: DaemonErrorResponse, status: 400 | 404 | 500) =>
           HttpServerResponse.jsonUnsafe(body, { status });
         const notFoundResponse = (name: string) =>
           errorResponse(
@@ -53,9 +53,9 @@ export class DaemonServer extends Context.Service<
         const buildErrorResponse = (detail: string) =>
           errorResponse({ code: "STACK_BUILD_ERROR", error: detail }, 500);
         const invalidReloadPayloadResponse = () =>
-          HttpServerResponse.jsonUnsafe(
-            { error: "Invalid Edge Functions reload payload" },
-            { status: 400 },
+          errorResponse(
+            { code: "STACK_BUILD_ERROR", error: "Invalid Edge Functions reload payload" },
+            400,
           );
         const readinessTimeoutResponse = (target: string, timeoutMs: number, detail: string) =>
           errorResponse(
diff --git a/packages/stack/src/LocalStack.ts b/packages/stack/src/LocalStack.ts
index 35ffba9fdf..5462763751 100644
--- a/packages/stack/src/LocalStack.ts
+++ b/packages/stack/src/LocalStack.ts
@@ -11,6 +11,7 @@ import {
   Layer,
   Path,
   Ref,
+  Schema,
   Semaphore,
   Stream,
   SubscriptionRef,
@@ -22,6 +23,7 @@ import { StackBuildError, StackNotRunningError, StackReadinessError } from "./er
 import {
   clearFunctionsRuntimeConfig,
   configureFunctionsRuntime,
+  resolvedFunctionsBundleSchemaForProject,
   type ResolvedFunctionsBundle,
 } from "./functions.ts";
 import { detectPlatform, dockerHostAddress } from "./Platform.ts";
@@ -435,11 +437,23 @@ export const localStackLayer = (
           Effect.provideService(FileSystem.FileSystem, fs),
           Effect.provideService(Path.Path, path),
         );
+      const decodeFunctionsBundle = (bundle: unknown) =>
+        Schema.decodeUnknownEffect(resolvedFunctionsBundleSchemaForProject(config.projectDir))(
+          bundle,
+        ).pipe(
+          Effect.mapError(
+            (cause) =>
+              new StackBuildError({
+                detail: "Invalid Edge Functions bundle",
+                cause,
+              }),
+          ),
+        );
       const configureFunctions = (
         nextConfig: ResolvedStackConfig,
+        bundle: ResolvedFunctionsBundle | undefined,
       ): Effect.Effect<void, StackBuildError> =>
         Effect.gen(function* () {
-          const bundle = yield* Ref.get(functionsBundleRef);
           yield* providePlatform(configureFunctionsRuntime(nextConfig, yield* runtimeHost, bundle));
         }).pipe(
           Effect.mapError(
@@ -701,7 +715,7 @@ export const localStackLayer = (
             yield* requireMutable("start");
             yield* Ref.set(phaseRef, "starting");
             const runtime = yield* ensureRuntime;
-            yield* configureFunctions(config);
+            yield* configureFunctions(config, yield* Ref.get(functionsBundleRef));
 
             if (config.startupMode === "lazy") {
               const readiness: Array<Effect.Effect<void, ServiceReadyError | StackBuildError>> = [];
@@ -802,10 +816,13 @@ export const localStackLayer = (
             const started = yield* Effect.gen(function* () {
               yield* requireMutable("reload functions");
               yield* requireKnownService("edge-runtime");
-              if (opts?.functions !== undefined) {
-                yield* Ref.set(functionsBundleRef, opts.functions);
-              }
-              yield* configureFunctions(config);
+              const currentBundle = yield* Ref.get(functionsBundleRef);
+              const nextBundle =
+                opts?.functions === undefined
+                  ? currentBundle
+                  : yield* decodeFunctionsBundle(opts.functions);
+              yield* configureFunctions(config, nextBundle);
+              yield* Ref.set(functionsBundleRef, nextBundle);
               const runtime = yield* ensureRuntime;
               const state = yield* runtime.orchestrator.getState("edge-runtime");
               if (state.desired !== "running") {
@@ -824,9 +841,11 @@ export const localStackLayer = (
               yield* requireMutable("reload Edge Runtime");
               yield* requireKnownService("edge-runtime");
               const nextConfig = yield* configWithEdgeRuntimeOptions(opts);
-              if (opts.functions !== undefined) {
-                yield* Ref.set(functionsBundleRef, opts.functions);
-              }
+              const currentBundle = yield* Ref.get(functionsBundleRef);
+              const nextBundle =
+                opts.functions === undefined
+                  ? currentBundle
+                  : yield* decodeFunctionsBundle(opts.functions);
               const prepared = yield* ensurePrepared;
               const runtime = yield* ensureRuntime;
               const buildResult = yield* builder.build(nextConfig, prepared);
@@ -838,7 +857,8 @@ export const localStackLayer = (
                 return yield* Effect.fail(new ServiceNotFoundError({ name: "edge-runtime" }));
               }
 
-              yield* configureFunctions(nextConfig);
+              yield* configureFunctions(nextConfig, nextBundle);
+              yield* Ref.set(functionsBundleRef, nextBundle);
               yield* runtime.orchestrator
                 .updateServiceDefinition("edge-runtime", edgeRuntimeDef)
                 .pipe(
diff --git a/packages/stack/src/RemoteStack.integration.test.ts b/packages/stack/src/RemoteStack.integration.test.ts
index 289d3cf64e..7d2fc3f781 100644
--- a/packages/stack/src/RemoteStack.integration.test.ts
+++ b/packages/stack/src/RemoteStack.integration.test.ts
@@ -496,6 +496,25 @@ describe("RemoteStack integration", () => {
     expect(mock.functionReloads).toEqual([{ functions: functionsBundle }]);
   });
 
+  test("reloadFunctions returns a typed build error for an invalid bundle", async () => {
+    const invalidBundle = {
+      ...functionsBundle,
+      functions: [{ ...functionsBundle.functions[0]!, entrypointPath: "relative/index.ts" }],
+    };
+
+    const error = await clientRuntime.runPromise(
+      Effect.flatMap(Stack, (stack) =>
+        stack.reloadFunctions({ functions: invalidBundle }).pipe(Effect.flip),
+      ),
+    );
+
+    expect(error).toBeInstanceOf(StackBuildError);
+    expect(error._tag).toBe("StackBuildError");
+    if (error._tag === "StackBuildError") {
+      expect(error.detail).toBe("Invalid Edge Functions reload payload");
+    }
+  });
+
   test("reloadEdgeRuntime records the call", async () => {
     await clientRuntime.runPromise(
       Effect.flatMap(Stack, (stack) =>
diff --git a/packages/stack/src/Stack.unit.test.ts b/packages/stack/src/Stack.unit.test.ts
index f471a80955..8ed99c3e61 100644
--- a/packages/stack/src/Stack.unit.test.ts
+++ b/packages/stack/src/Stack.unit.test.ts
@@ -3,7 +3,7 @@ import { BunServices } from "@effect/platform-bun";
 import { buildGraph } from "@supabase/process-compose";
 import { createHmac } from "node:crypto";
 import { mkdtempSync } from "node:fs";
-import { readFile, rm } from "node:fs/promises";
+import { chmod, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Deferred, Effect, Exit, Fiber, Layer, Stream } from "effect";
@@ -180,6 +180,7 @@ describe("Stack", () => {
     const replacementBundle = functionsBundle(runtimeRoot, "replacement-secret");
     const config = {
       ...edgeRuntimeConfig,
+      projectDir: runtimeRoot,
       runtimeRoot,
       functions: initialBundle,
     } satisfies ResolvedStackConfig;
@@ -227,6 +228,25 @@ describe("Stack", () => {
       yield* stack.reloadFunctions();
       expect((yield* readRuntimeConfig).env.SHARED).toBe("replacement-secret");
 
+      const duplicateBundle = {
+        ...replacementBundle,
+        functions: [replacementBundle.functions[0]!, replacementBundle.functions[0]!],
+      };
+      expect(
+        (yield* stack.reloadFunctions({ functions: duplicateBundle }).pipe(Effect.flip))._tag,
+      ).toBe("StackBuildError");
+      expect((yield* readRuntimeConfig).env.SHARED).toBe("replacement-secret");
+
+      const runtimeDirectory = join(runtimeRoot, "edge-runtime");
+      yield* Effect.promise(() => chmod(runtimeDirectory, 0o500));
+      const failedBundle = functionsBundle(runtimeRoot, "failed-secret");
+      const error = yield* stack.reloadFunctions({ functions: failedBundle }).pipe(Effect.flip);
+      expect(error._tag).toBe("StackBuildError");
+
+      yield* Effect.promise(() => chmod(runtimeDirectory, 0o700));
+      yield* stack.reloadFunctions();
+      expect((yield* readRuntimeConfig).env.SHARED).toBe("replacement-secret");
+
       yield* stack.dispose();
       expect(
         yield* Effect.promise(() =>
@@ -238,7 +258,12 @@ describe("Stack", () => {
       ).toBe(false);
     }).pipe(
       Effect.provide(layer),
-      Effect.ensuring(Effect.promise(() => rm(runtimeRoot, { recursive: true, force: true }))),
+      Effect.ensuring(
+        Effect.promise(async () => {
+          await chmod(join(runtimeRoot, "edge-runtime"), 0o700).catch(() => {});
+          await rm(runtimeRoot, { recursive: true, force: true });
+        }),
+      ),
       Effect.timeout("5 seconds"),
     );
   });
diff --git a/packages/stack/src/StackConfigResolver.ts b/packages/stack/src/StackConfigResolver.ts
index 84bc42bc79..6a847c47e5 100644
--- a/packages/stack/src/StackConfigResolver.ts
+++ b/packages/stack/src/StackConfigResolver.ts
@@ -2,7 +2,8 @@ import { mkdtempSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { Effect, Schema } from "effect";
-import { toStackError } from "./errors.ts";
+import { StackBuildError, toStackError } from "./errors.ts";
+import { resolvedFunctionsBundleSchemaForProject } from "./functions.ts";
 import {
   defaultJwtSecret,
   defaultPublishableKey,
@@ -297,8 +298,17 @@ function resolveEdgeRuntimeConfig(
   };
 }
 
-function resolveFunctionsConfig(config: StackConfig) {
-  return config.functions ?? false;
+async function resolveFunctionsConfig(config: StackConfig, projectDir: string) {
+  if (config.functions === undefined || config.functions === false) {
+    return false;
+  }
+  try {
+    return await Schema.decodeUnknownPromise(resolvedFunctionsBundleSchemaForProject(projectDir))(
+      config.functions,
+    );
+  } catch (cause) {
+    throw new StackBuildError({ detail: "Invalid Edge Functions bundle", cause });
+  }
 }
 
 function resolveStorageConfig(
@@ -429,6 +439,7 @@ export async function resolveConfig(
 ): Promise<ResolvedStackConfig> {
   const config = input ?? {};
   const projectDir = config.projectDir ?? process.cwd();
+  const functions = await resolveFunctionsConfig(config, projectDir);
   const resolvedMode = config.mode ?? "auto";
   const roots = resolveRoots(config, opts);
   const postgresInput = config.postgres ?? {};
@@ -509,7 +520,7 @@ export async function resolveConfig(
     dbPort: ports.dbPort,
     publishableKey: config.publishableKey ?? defaultPublishableKey,
     secretKey: config.secretKey ?? defaultSecretKey,
-    functions: resolveFunctionsConfig(config),
+    functions,
     autoManagedPaths: roots.autoManagedPaths,
     anonJwt,
     serviceRoleJwt,
diff --git a/packages/stack/src/functions.ts b/packages/stack/src/functions.ts
index bcf5c1648e..4a321b8695 100644
--- a/packages/stack/src/functions.ts
+++ b/packages/stack/src/functions.ts
@@ -1,4 +1,4 @@
-import { isAbsolute, join } from "node:path";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { Effect, FileSystem, Path, Schema } from "effect";
 import type { ResolvedStackConfig } from "./StackConfig.ts";
 
@@ -54,6 +54,48 @@ export interface ResolvedFunctionsBundle extends Schema.Schema.Type<
   typeof ResolvedFunctionsBundleSchema
 > {}
 
+function isWithinProjectDir(projectDir: string, candidate: string): boolean {
+  const relativePath = relative(resolve(projectDir), candidate);
+  return (
+    relativePath === "" ||
+    (relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath))
+  );
+}
+
+/**
+ * Docker mounts `projectDir` at the same absolute path as the host. Keeping all
+ * referenced files below that root gives native and Docker runtimes the same
+ * bundle contract, including after a reload.
+ */
+export const resolvedFunctionsBundleSchemaForProject = (projectDir: string) =>
+  ResolvedFunctionsBundleSchema.check(
+    Schema.makeFilter((bundle) => {
+      for (let index = 0; index < bundle.functions.length; index += 1) {
+        const fn = bundle.functions[index];
+        if (fn === undefined) continue;
+
+        const paths = [
+          { field: "entrypointPath", value: fn.entrypointPath },
+          ...(fn.importMapPath === null
+            ? []
+            : [{ field: "importMapPath", value: fn.importMapPath }]),
+          ...fn.staticFiles.map((value, staticIndex) => ({
+            field: `staticFiles.${staticIndex}`,
+            value,
+          })),
+        ];
+        const outsideProject = paths.find(({ value }) => !isWithinProjectDir(projectDir, value));
+        if (outsideProject !== undefined) {
+          return {
+            path: ["functions", index, outsideProject.field],
+            issue: "Function paths must be within projectDir",
+          };
+        }
+      }
+      return undefined;
+    }),
+  );
+
 export const FunctionsReloadConfigSchema = Schema.Struct({
   functions: Schema.optionalKey(ResolvedFunctionsBundleSchema),
 });
@@ -148,7 +190,6 @@ const writeFunctionsRuntimeConfig = Effect.fnUntraced(function* (
     });
     yield* fs.chmod(temporaryPath, 0o600);
     yield* fs.rename(temporaryPath, filePath);
-    yield* fs.chmod(filePath, 0o600);
   }).pipe(Effect.ensuring(fs.remove(temporaryPath).pipe(Effect.ignore)));
 });
 
diff --git a/packages/stack/src/functions.unit.test.ts b/packages/stack/src/functions.unit.test.ts
index 2c046a2d28..39cd9d780e 100644
--- a/packages/stack/src/functions.unit.test.ts
+++ b/packages/stack/src/functions.unit.test.ts
@@ -84,7 +84,7 @@ const authFailureCases = [
 describe("stack Functions runtime config", () => {
   it("projects an explicit bundle without project discovery", async () => {
     const root = makeTempProject();
-    const stackConfig = await resolveConfig({ functions: makeBundle(root) });
+    const stackConfig = await resolveConfig({ projectDir: root, functions: makeBundle(root) });
     const config = resolveFunctionsRuntimeConfig(
       stackConfig,
       { hostname: "127.0.0.1" },
@@ -125,6 +125,35 @@ describe("stack Functions runtime config", () => {
     await rm(root, { recursive: true, force: true });
   });
 
+  it("validates explicit bundles at config resolution", async () => {
+    const root = makeTempProject();
+    const bundle = makeBundle(root);
+
+    await expect(
+      resolveConfig({
+        projectDir: root,
+        functions: {
+          ...bundle,
+          functions: [bundle.functions[0]!, bundle.functions[0]!],
+        },
+      }),
+    ).rejects.toMatchObject({
+      _tag: "StackBuildError",
+      detail: "Invalid Edge Functions bundle",
+    });
+    await expect(
+      resolveConfig({
+        projectDir: join(root, "project"),
+        functions: bundle,
+      }),
+    ).rejects.toMatchObject({
+      _tag: "StackBuildError",
+      detail: "Invalid Edge Functions bundle",
+    });
+
+    await rm(root, { recursive: true, force: true });
+  });
+
   it("keeps placeholder mode when no functions are supplied", async () => {
     const stackConfig = await resolveConfig({ functions: false });
 
@@ -149,7 +178,7 @@ describe("stack Functions runtime config", () => {
     return Effect.gen(function* () {
       const bundle = makeBundle(cwd);
       const stackConfig = yield* Effect.promise(() =>
-        resolveConfig({ runtimeRoot: cwd, functions: bundle }),
+        resolveConfig({ projectDir: cwd, runtimeRoot: cwd, functions: bundle }),
       );
       yield* configureFunctionsRuntime(stackConfig, { hostname: "127.0.0.1" }, bundle);
       const filePath = functionsRuntimeConfigPath(stackConfig.runtimeRoot);

From 75055374ac2748b5c9c048ae0592b550ddab9372 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 14:38:02 +0200
Subject: [PATCH 34/44] fix(stack): close foreground runtime on readiness
 timeout

---
 packages/stack/src/createStack.ts           | 23 +++++++++++---
 packages/stack/src/createStack.unit.test.ts | 34 ++++++++++++++++++++-
 2 files changed, 51 insertions(+), 6 deletions(-)

diff --git a/packages/stack/src/createStack.ts b/packages/stack/src/createStack.ts
index 24752da00c..6d06b9666f 100644
--- a/packages/stack/src/createStack.ts
+++ b/packages/stack/src/createStack.ts
@@ -34,6 +34,22 @@ export interface PlatformFactoryOptions {
 
 export type PlatformFactory = (options: PlatformFactoryOptions) => PlatformLayer;
 
+/** @internal Converts foreground operation failures and closes the runtime after terminal timeouts. */
+export async function runForegroundOperation<A>(
+  operation: Promise<A>,
+  dispose: () => Promise<void>,
+): Promise<A> {
+  try {
+    return await operation;
+  } catch (error: unknown) {
+    const stackError = toStackError(error);
+    if (stackError.code === "STACK_READINESS_TIMEOUT") {
+      await dispose();
+    }
+    throw stackError;
+  }
+}
+
 export interface StackHandle extends AsyncDisposable {
   readonly url: string;
   readonly dbUrl: string;
@@ -143,16 +159,13 @@ export async function createStack(
       const apiProxy = Context.get(services, ApiProxy);
       const info = await runtime.runPromise(localStack.getInfo());
 
-      const run = <A>(effect: Effect.Effect<A, unknown>) =>
-        runtime.runPromise(effect).catch((error: unknown) => {
-          throw toStackError(error);
-        });
-
       let disposal: Promise<void> | undefined;
       const gracefulDispose = () => {
         disposal ??= runtime.dispose().catch(() => {});
         return disposal;
       };
+      const run = <A>(effect: Effect.Effect<A, unknown>) =>
+        runForegroundOperation(runtime.runPromise(effect), gracefulDispose);
 
       // A terminal lazy-activation timeout disposes LocalStack. Close the
       // foreground runtime as well so the public API port cannot outlive it.
diff --git a/packages/stack/src/createStack.unit.test.ts b/packages/stack/src/createStack.unit.test.ts
index abc8499e4d..90516c1884 100644
--- a/packages/stack/src/createStack.unit.test.ts
+++ b/packages/stack/src/createStack.unit.test.ts
@@ -2,7 +2,8 @@ import { describe, expect, it } from "vitest";
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import type { StackHandle } from "./createStack.ts";
+import { runForegroundOperation, type StackHandle } from "./createStack.ts";
+import { StackReadinessError } from "./errors.ts";
 import type { AllocatedPorts } from "./PortAllocator.ts";
 import { DEFAULT_MANAGED_STACK_NAME, projectKeyForProjectDir } from "./paths.ts";
 import { stackMetadata } from "./StackMetadata.ts";
@@ -66,6 +67,37 @@ function writeStackMetadata(
   );
 }
 
+describe("foreground operation lifecycle", () => {
+  it("disposes the foreground runtime after a direct readiness timeout", async () => {
+    let disposeCount = 0;
+    const operation = Promise.reject(
+      new StackReadinessError({
+        target: "stack",
+        timeoutMs: 10,
+        detail: "Timed out waiting for stack readiness",
+      }),
+    );
+
+    await expect(
+      runForegroundOperation(operation, async () => {
+        disposeCount += 1;
+      }),
+    ).rejects.toMatchObject({ code: "STACK_READINESS_TIMEOUT" });
+    expect(disposeCount).toBe(1);
+  });
+
+  it("keeps the foreground runtime open after a non-terminal operation failure", async () => {
+    let disposeCount = 0;
+
+    await expect(
+      runForegroundOperation(Promise.reject(new Error("failed")), async () => {
+        disposeCount += 1;
+      }),
+    ).rejects.toMatchObject({ code: "UNKNOWN" });
+    expect(disposeCount).toBe(0);
+  });
+});
+
 describe("createStack types", () => {
   it("StackHandle interface has expected shape", () => {
     const check = (_stack: StackHandle) => {

From e089d7d32d9b4224f12fae4cc7ee33a213a42305 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 14:48:05 +0200
Subject: [PATCH 35/44] fix(process-compose): preserve active restart policy

---
 packages/process-compose/src/Orchestrator.ts  | 15 +++++++--
 .../src/Orchestrator.unit.test.ts             | 33 +++++++++++++++++++
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/packages/process-compose/src/Orchestrator.ts b/packages/process-compose/src/Orchestrator.ts
index d884c5c693..166dab8389 100644
--- a/packages/process-compose/src/Orchestrator.ts
+++ b/packages/process-compose/src/Orchestrator.ts
@@ -127,6 +127,7 @@ export class Orchestrator extends Context.Service<
 
         interface ServiceRuntime {
           readonly state: SubscriptionRef.SubscriptionRef<ServiceState>;
+          effectiveDef: ServiceDef;
         }
         const services = new Map<string, ServiceRuntime>();
 
@@ -135,6 +136,7 @@ export class Orchestrator extends Context.Service<
           const stateRef = yield* SubscriptionRef.make(initial(def.name));
           services.set(def.name, {
             state: stateRef,
+            effectiveDef: def,
           });
         }
 
@@ -244,7 +246,8 @@ export class Orchestrator extends Context.Service<
                     (state) =>
                       state.desired === "running" &&
                       (state.status === "Healthy" ||
-                        (state.status === "Failed" && !willRestartAfterExit(depDef, state))),
+                        (state.status === "Failed" &&
+                          !willRestartAfterExit(dependency.effectiveDef, state))),
                   );
                   if (ready.status === "Failed") {
                     yield* sendEvent(def.name, {
@@ -259,7 +262,7 @@ export class Orchestrator extends Context.Service<
                     (state) =>
                       (state.status === "Failed" ||
                         (state.status === "Stopped" && state.exitCode !== null)) &&
-                      !willRestartAfterExit(depDef, state),
+                      !willRestartAfterExit(dependency.effectiveDef, state),
                   );
                   if (completed.status === "Failed") {
                     yield* sendEvent(def.name, {
@@ -590,7 +593,13 @@ export class Orchestrator extends Context.Service<
           });
 
         const runServiceSafe = (def: ServiceDef, options?: ServiceStartOptions) =>
-          runService(def, options).pipe(
+          Effect.sync(() => {
+            const service = services.get(def.name);
+            if (service !== undefined) {
+              service.effectiveDef = def;
+            }
+          }).pipe(
+            Effect.andThen(runService(def, options)),
             Effect.catch((error) =>
               sendEvent(def.name, {
                 _tag: "SpawnFailed",
diff --git a/packages/process-compose/src/Orchestrator.unit.test.ts b/packages/process-compose/src/Orchestrator.unit.test.ts
index e58d7eb70f..47a5861ffc 100644
--- a/packages/process-compose/src/Orchestrator.unit.test.ts
+++ b/packages/process-compose/src/Orchestrator.unit.test.ts
@@ -1232,6 +1232,39 @@ describe("Orchestrator", () => {
       }).pipe(Effect.provide(layer), Effect.scoped);
     });
 
+    it.live("dependency waits use the running generation restart policy", () => {
+      const { layer, proc } = setupOrchestrator(
+        [
+          svc("setup", { restart: "no" }),
+          svc("app", {
+            restart: "no",
+            dependencies: [{ service: "setup", condition: "completed" }],
+            dependencyTimeoutSeconds: 1,
+          }),
+        ],
+        {
+          perService: {
+            setup: { exitCode: 1, exitDelay: "200 millis" },
+            app: { exitDelay: "5 seconds" },
+          },
+        },
+      );
+
+      return Effect.gen(function* () {
+        const orc = yield* Orchestrator;
+        yield* orc.start();
+        yield* proc.waitForSpawn("setup");
+
+        // The replacement applies on the next explicit restart. The running
+        // generation still uses restart:no and must remain authoritative.
+        yield* orc.updateServiceDefinition("setup", svc("setup", { restart: "always" }));
+
+        const state = yield* waitForFailed(orc, "app");
+        expect(state.error).toContain("Dependency setup failed");
+        expect(state.error).not.toContain("Timed out");
+      }).pipe(Effect.provide(layer), Effect.scoped);
+    });
+
     it.live("no timeout when dependency resolves before deadline", () => {
       const { layer } = setupOrchestrator(
         [

From f2758593e87281aea1a7e5841aa798180764857e Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 14:48:05 +0200
Subject: [PATCH 36/44] fix(stack): serialize projected state snapshots

---
 .../stack/src/StackLifecycleCoordinator.ts    | 74 ++++++-------------
 1 file changed, 22 insertions(+), 52 deletions(-)

diff --git a/packages/stack/src/StackLifecycleCoordinator.ts b/packages/stack/src/StackLifecycleCoordinator.ts
index 27e5b2839a..86b4097bae 100644
--- a/packages/stack/src/StackLifecycleCoordinator.ts
+++ b/packages/stack/src/StackLifecycleCoordinator.ts
@@ -36,11 +36,7 @@ import {
   versionsForConfig,
   type ResolvedStackConfig,
 } from "./StackBuilder.ts";
-import {
-  changedProjectedStates,
-  projectStackStates,
-  type StackServiceProjectionCatalog,
-} from "./StackStateProjection.ts";
+import { projectStackStates, type StackServiceProjectionCatalog } from "./StackStateProjection.ts";
 import { StackServiceState } from "./StackServiceState.ts";
 import type { EdgeRuntimeReloadConfig, StackInfo } from "./Stack.ts";
 import { SERVICE_NAMES, type ServiceName } from "./versions.ts";
@@ -221,6 +217,7 @@ export class StackLifecycleCoordinator extends Context.Service<
         const stateRef = yield* SubscriptionRef.make(initialPublicStates(config));
         const phaseRef = yield* Ref.make<LifecyclePhase>("idle");
         const lifecycleLock = Semaphore.makeUnsafe(1);
+        const projectionLock = Semaphore.makeUnsafe(1);
 
         const logBufferServices = yield* Layer.buildWithScope(LogBuffer.layer, scope);
         const logBuffer = Context.get(logBufferServices, LogBuffer);
@@ -236,6 +233,17 @@ export class StackLifecycleCoordinator extends Context.Service<
               : [...current, nextState];
           });
 
+        const syncProjectedStates = (
+          orchestrator: Orchestrator["Service"],
+          serviceProjection: StackServiceProjectionCatalog,
+        ) =>
+          Effect.gen(function* () {
+            const rawStates = yield* orchestrator.getAllStates();
+            yield* Effect.forEach(projectStackStates(rawStates, serviceProjection), updateState, {
+              discard: true,
+            });
+          }).pipe(projectionLock.withPermit);
+
         const requireKnownService = (name: string) =>
           Effect.gen(function* () {
             const currentStates = SubscriptionRef.getUnsafe(stateRef);
@@ -393,40 +401,9 @@ export class StackLifecycleCoordinator extends Context.Service<
             const orchServices = yield* Layer.buildWithScope(orchLayer, scope);
             const orchestrator = Context.get(orchServices, Orchestrator);
 
-            const projectedStates = Stream.unwrap(
-              Effect.gen(function* () {
-                const rawInitialStates = yield* orchestrator.getAllStates();
-                const initialProjected = projectStackStates(rawInitialStates, serviceProjection);
-                let rawStates = new Map(
-                  rawInitialStates.map((state) => [state.name, state] as const),
-                );
-                let projectedByName = new Map(
-                  initialProjected.map((state) => [state.name, state] as const),
-                );
-
-                return Stream.concat(
-                  Stream.fromIterable(initialProjected),
-                  orchestrator.allStateChanges().pipe(
-                    Stream.map((rawState) => {
-                      rawStates.set(rawState.name, rawState);
-                      const nextProjected = projectStackStates(
-                        [...rawStates.values()],
-                        serviceProjection,
-                      );
-                      const changed = changedProjectedStates(projectedByName, nextProjected);
-                      projectedByName = new Map(
-                        nextProjected.map((state) => [state.name, state] as const),
-                      );
-                      return changed;
-                    }),
-                    Stream.flatMap((states) => Stream.fromIterable(states)),
-                  ),
-                );
-              }),
-            );
-
-            yield* projectedStates.pipe(
-              Stream.runForEach((state) => updateState(state)),
+            yield* syncProjectedStates(orchestrator, serviceProjection);
+            yield* orchestrator.allStateChanges().pipe(
+              Stream.runForEach(() => syncProjectedStates(orchestrator, serviceProjection)),
               Effect.ignore,
               Effect.forkIn(scope),
             );
@@ -534,15 +511,8 @@ export class StackLifecycleCoordinator extends Context.Service<
             ),
           );
         const withLifecycleLock = lifecycleLock.withPermit;
-        const syncProjectedStates = (runtime: RuntimeState) =>
-          Effect.gen(function* () {
-            const rawStates = yield* runtime.orchestrator.getAllStates();
-            yield* Effect.forEach(
-              projectStackStates(rawStates, runtime.serviceProjection),
-              updateState,
-              { discard: true },
-            );
-          });
+        const syncRuntimeProjectedStates = (runtime: RuntimeState) =>
+          syncProjectedStates(runtime.orchestrator, runtime.serviceProjection);
         const serviceStartOptions = {
           beforeStart: (name: string) => portLease.reserve(portFieldsForService(name)),
           beforeSpawn: (name: string) => portLease.release(portFieldsForService(name)),
@@ -618,7 +588,7 @@ export class StackLifecycleCoordinator extends Context.Service<
                   ),
               { concurrency: "unbounded", discard: true },
             );
-            yield* syncProjectedStates(runtime);
+            yield* syncRuntimeProjectedStates(runtime);
           });
         const inspectStartedTargets = (root: ServiceName) =>
           Effect.gen(function* () {
@@ -716,7 +686,7 @@ export class StackLifecycleCoordinator extends Context.Service<
               } else {
                 yield* runtime.orchestrator.start(serviceStartOptions);
                 yield* runtime.orchestrator.waitAllReady();
-                yield* syncProjectedStates(runtime);
+                yield* syncRuntimeProjectedStates(runtime);
               }
               yield* Ref.set(phaseRef, "running");
             }).pipe(
@@ -870,7 +840,7 @@ export class StackLifecycleCoordinator extends Context.Service<
               yield* requireKnownServiceName(name);
               const runtime = yield* ensureRuntime;
               yield* runtime.orchestrator.waitReady(name);
-              yield* syncProjectedStates(runtime);
+              yield* syncRuntimeProjectedStates(runtime);
             }),
           waitAllReady: () =>
             Effect.gen(function* () {
@@ -884,7 +854,7 @@ export class StackLifecycleCoordinator extends Context.Service<
               }
               const runtime = yield* ensureRuntime;
               yield* runtime.orchestrator.waitAllReady();
-              yield* syncProjectedStates(runtime);
+              yield* syncRuntimeProjectedStates(runtime);
             }),
           subscribeLogs: (name) => logBuffer.subscribe(name),
           subscribeAllLogs: (services) =>

From 665f8cc9002d586174787de5dca0ee3fce223418 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 14:53:41 +0200
Subject: [PATCH 37/44] fix(stack): propagate terminal local disposal

---
 packages/stack/src/LocalStack.ts            | 21 +++++++++++--
 packages/stack/src/createStack.ts           | 21 ++++++++-----
 packages/stack/src/createStack.unit.test.ts | 35 +++++++++++++++++----
 packages/stack/src/layers.ts                |  4 +--
 4 files changed, 63 insertions(+), 18 deletions(-)

diff --git a/packages/stack/src/LocalStack.ts b/packages/stack/src/LocalStack.ts
index ad7bdb9913..1be254e8ac 100644
--- a/packages/stack/src/LocalStack.ts
+++ b/packages/stack/src/LocalStack.ts
@@ -58,6 +58,15 @@ type LifecyclePhase =
 
 type StackService = typeof Stack.Service;
 
+/** Private signal used by the Promise adapter to close its enclosing managed runtime. */
+export class LocalStackLifecycle extends Context.Service<
+  LocalStackLifecycle,
+  {
+    readonly awaitDisposed: Effect.Effect<void>;
+    readonly isDisposed: Effect.Effect<boolean>;
+  }
+>()("stack/LocalStackLifecycle") {}
+
 interface RuntimeState {
   readonly orchestrator: Orchestrator["Service"];
   readonly graph: ResolvedGraph;
@@ -146,7 +155,7 @@ export const localStackLayer = (
   config: ResolvedStackConfig,
   portLease: PortLease,
 ): Layer.Layer<
-  Stack | StackServiceActivator,
+  Stack | StackServiceActivator | LocalStackLifecycle,
   StackBuildError,
   | StackBuilder
   | StackPreparation
@@ -169,6 +178,7 @@ export const localStackLayer = (
       const enabledServices = enabledServicesForConfig(config);
       const stateRef = yield* SubscriptionRef.make(initialPublicStates(config));
       const phaseRef = yield* Ref.make<LifecyclePhase>("idle");
+      const disposedSignal = yield* Deferred.make<void>();
       const lifecycleLock = Semaphore.makeUnsafe(1);
       const projectionLock = Semaphore.makeUnsafe(1);
 
@@ -603,7 +613,10 @@ export const localStackLayer = (
               Effect.ensuring(Ref.set(phaseRef, "disposed")),
             );
           }).pipe(withLifecycleLock);
-        }).pipe(Effect.uninterruptible);
+        }).pipe(
+          Effect.ensuring(Deferred.succeed(disposedSignal, undefined).pipe(Effect.asVoid)),
+          Effect.uninterruptible,
+        );
 
       const withReadinessPolicy = <A, E, R>(
         effect: Effect.Effect<A, E, R>,
@@ -891,6 +904,10 @@ export const localStackLayer = (
 
       return Context.make(Stack, stack).pipe(
         Context.add(StackServiceActivator, { activate: activateService }),
+        Context.add(LocalStackLifecycle, {
+          awaitDisposed: Deferred.await(disposedSignal),
+          isDisposed: Effect.sync(() => disposed),
+        }),
       );
     }),
   );
diff --git a/packages/stack/src/createStack.ts b/packages/stack/src/createStack.ts
index ab8ba8ffe7..d8b2ee0c50 100644
--- a/packages/stack/src/createStack.ts
+++ b/packages/stack/src/createStack.ts
@@ -4,10 +4,10 @@ import { FileSystem, Path } from "effect";
 import { HttpServer } from "effect/unstable/http";
 import { ChildProcessSpawner } from "effect/unstable/process";
 import { candidateCleanupTargets, cleanupAutoManagedPaths, dockerForceRemove } from "./cleanup.ts";
-import { ApiProxy } from "./ApiProxy.ts";
 import { toStackError } from "./errors.ts";
 import type { FunctionsConfig } from "./functions.ts";
 import { daemonLayer, foregroundLayer, type DaemonStartError } from "./layers.ts";
+import { LocalStackLifecycle } from "./LocalStack.ts";
 import { PORT_FIELDS, reservePorts, type PortLease } from "./PortAllocator.ts";
 import { allocatedPortFieldsForConfig } from "./ServicePorts.ts";
 import { Stack } from "./Stack.ts";
@@ -33,16 +33,17 @@ export interface PlatformFactoryOptions {
 
 export type PlatformFactory = (options: PlatformFactoryOptions) => PlatformLayer;
 
-/** @internal Converts foreground operation failures and closes the runtime after terminal timeouts. */
+/** @internal Converts operation failures and closes a terminal foreground runtime. */
 export async function runForegroundOperation<A>(
   operation: Promise<A>,
+  isDisposed: () => Promise<boolean>,
   dispose: () => Promise<void>,
 ): Promise<A> {
   try {
     return await operation;
   } catch (error: unknown) {
     const stackError = toStackError(error);
-    if (stackError.code === "STACK_READINESS_TIMEOUT") {
+    if (await isDisposed()) {
       await dispose();
     }
     throw stackError;
@@ -137,7 +138,7 @@ export async function createStack(
     try {
       const services = await runtime.context();
       const localStack = Context.get(services, Stack);
-      const apiProxy = Context.get(services, ApiProxy);
+      const lifecycle = Context.get(services, LocalStackLifecycle);
       const info = await runtime.runPromise(localStack.getInfo());
 
       let disposal: Promise<void> | undefined;
@@ -146,12 +147,16 @@ export async function createStack(
         return disposal;
       };
       const run = <A>(effect: Effect.Effect<A, unknown>) =>
-        runForegroundOperation(runtime.runPromise(effect), gracefulDispose);
+        runForegroundOperation(
+          runtime.runPromise(effect),
+          () => runtime.runPromise(lifecycle.isDisposed),
+          gracefulDispose,
+        );
 
-      // A terminal lazy-activation timeout disposes LocalStack. Close the
-      // foreground runtime as well so the public API port cannot outlive it.
+      // LocalStack owns terminality. When it disposes, close the enclosing
+      // runtime as well so the public API port cannot outlive the stack.
       void runtime
-        .runPromise(apiProxy.awaitTerminalFailure)
+        .runPromise(lifecycle.awaitDisposed)
         .then(gracefulDispose)
         .catch(() => {});
 
diff --git a/packages/stack/src/createStack.unit.test.ts b/packages/stack/src/createStack.unit.test.ts
index 9736b7cc5f..2413e5a65a 100644
--- a/packages/stack/src/createStack.unit.test.ts
+++ b/packages/stack/src/createStack.unit.test.ts
@@ -81,20 +81,43 @@ describe("foreground operation lifecycle", () => {
     );
 
     await expect(
-      runForegroundOperation(operation, async () => {
-        disposeCount += 1;
-      }),
+      runForegroundOperation(
+        operation,
+        async () => true,
+        async () => {
+          disposeCount += 1;
+        },
+      ),
     ).rejects.toMatchObject({ code: "STACK_READINESS_TIMEOUT" });
     expect(disposeCount).toBe(1);
   });
 
+  it("disposes the foreground runtime after another terminal start failure", async () => {
+    let disposeCount = 0;
+
+    await expect(
+      runForegroundOperation(
+        Promise.reject(new Error("service startup failed")),
+        async () => true,
+        async () => {
+          disposeCount += 1;
+        },
+      ),
+    ).rejects.toMatchObject({ code: "UNKNOWN" });
+    expect(disposeCount).toBe(1);
+  });
+
   it("keeps the foreground runtime open after a non-terminal operation failure", async () => {
     let disposeCount = 0;
 
     await expect(
-      runForegroundOperation(Promise.reject(new Error("failed")), async () => {
-        disposeCount += 1;
-      }),
+      runForegroundOperation(
+        Promise.reject(new Error("failed")),
+        async () => false,
+        async () => {
+          disposeCount += 1;
+        },
+      ),
     ).rejects.toMatchObject({ code: "UNKNOWN" });
     expect(disposeCount).toBe(0);
   });
diff --git a/packages/stack/src/layers.ts b/packages/stack/src/layers.ts
index c0afe22dcb..8761d2b0c6 100644
--- a/packages/stack/src/layers.ts
+++ b/packages/stack/src/layers.ts
@@ -12,7 +12,7 @@ import { DaemonMessageSchema } from "./DaemonProtocol.ts";
 import type { PortLease } from "./PortAllocator.ts";
 import { RemoteStack } from "./RemoteStack.ts";
 import { Stack } from "./Stack.ts";
-import { localStackLayer } from "./LocalStack.ts";
+import { LocalStackLifecycle, localStackLayer } from "./LocalStack.ts";
 import { StackMetadataPersistence } from "./StackMetadataPersistence.ts";
 import { StackPreparation } from "./StackPreparation.ts";
 import {
@@ -45,7 +45,7 @@ export const foregroundLayer = (
   config: ResolvedStackConfig,
   platformFactory: PlatformFactory,
   portLease: PortLease,
-): Layer.Layer<Stack | ApiProxy> => {
+): Layer.Layer<Stack | ApiProxy | LocalStackLifecycle> => {
   const platform = platformFactory({
     apiPort: config.apiPort,
     releaseApiPort: portLease.release(["apiPort"]),

From ed31de0a773b07e8c3127d218ad3afec3345ccb0 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 15:05:19 +0200
Subject: [PATCH 38/44] fix(process-compose): use active policy for readiness

---
 packages/process-compose/src/Orchestrator.ts  | 10 +++++++---
 .../src/Orchestrator.unit.test.ts             | 20 +++++++++++++++++++
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/packages/process-compose/src/Orchestrator.ts b/packages/process-compose/src/Orchestrator.ts
index 166dab8389..64f508c535 100644
--- a/packages/process-compose/src/Orchestrator.ts
+++ b/packages/process-compose/src/Orchestrator.ts
@@ -657,6 +657,7 @@ export class Orchestrator extends Context.Service<
             const svc = services.get(def.name);
             if (!svc) return Effect.void;
             const current = SubscriptionRef.getUnsafe(svc.state);
+            const effectiveDef = svc.effectiveDef;
             if (current.desired !== "running") {
               return Effect.fail(
                 new ServiceReadyError({
@@ -668,7 +669,7 @@ export class Orchestrator extends Context.Service<
                 }),
               );
             }
-            if (current.status === "Failed" && !willRestartAfterExit(def, current)) {
+            if (current.status === "Failed" && !willRestartAfterExit(effectiveDef, current)) {
               return Effect.fail(
                 new ServiceReadyError({
                   name: def.name,
@@ -677,7 +678,10 @@ export class Orchestrator extends Context.Service<
               );
             }
 
-            if ((def.restart ?? defaults.restart) === "no" && def.healthCheck == null) {
+            if (
+              (effectiveDef.restart ?? defaults.restart) === "no" &&
+              effectiveDef.healthCheck == null
+            ) {
               return waitForState(
                 svc,
                 (state) => state.status === "Failed" || state.status === "Stopped",
@@ -704,7 +708,7 @@ export class Orchestrator extends Context.Service<
               (state) =>
                 state.status === "Healthy" ||
                 ((state.status === "Failed" || state.status === "Stopped") &&
-                  !willRestartAfterExit(def, state)),
+                  !willRestartAfterExit(effectiveDef, state)),
             ).pipe(
               Effect.flatMap((ready) => {
                 if (ready.status === "Healthy") return Effect.void;
diff --git a/packages/process-compose/src/Orchestrator.unit.test.ts b/packages/process-compose/src/Orchestrator.unit.test.ts
index 47a5861ffc..06b954acd8 100644
--- a/packages/process-compose/src/Orchestrator.unit.test.ts
+++ b/packages/process-compose/src/Orchestrator.unit.test.ts
@@ -2274,6 +2274,26 @@ describe("Orchestrator", () => {
       }).pipe(Effect.provide(layer), Effect.scoped);
     });
 
+    it.live("waitReady uses the running generation restart policy", () => {
+      const { layer, proc } = setupOrchestrator([svc("a", { restart: "no" })], {
+        exitCode: 1,
+        exitDelay: "200 millis",
+      });
+
+      return Effect.gen(function* () {
+        const orc = yield* Orchestrator;
+        yield* orc.start();
+        yield* proc.waitForSpawn("a");
+
+        // The replacement applies to the next generation; this one still
+        // terminates under restart:no and readiness must fail with it.
+        yield* orc.updateServiceDefinition("a", svc("a", { restart: "always" }));
+
+        const exit = yield* orc.waitReady("a").pipe(Effect.exit, Effect.timeout("1 second"));
+        expect(Exit.isFailure(exit)).toBe(true);
+      }).pipe(Effect.provide(layer), Effect.scoped);
+    });
+
     it.live("waitReady resolves when one-shot service completes successfully", () => {
       const { layer } = setupOrchestrator([svc("a", { restart: "no" })], {
         exitCode: 0,

From 267de27ae025d8877df1bfc841a136f93fc026e9 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 15:05:19 +0200
Subject: [PATCH 39/44] fix(stack): budget native database initialization

---
 packages/stack/src/StackBuilder.ts            | 36 ++++++++++++-------
 packages/stack/src/StackBuilder.unit.test.ts  | 16 +++++++--
 packages/stack/src/StackStateProjection.ts    | 19 ----------
 packages/stack/src/services/health-budgets.ts |  3 ++
 4 files changed, 40 insertions(+), 34 deletions(-)

diff --git a/packages/stack/src/StackBuilder.ts b/packages/stack/src/StackBuilder.ts
index 51cc3d6e9b..dc95e58583 100644
--- a/packages/stack/src/StackBuilder.ts
+++ b/packages/stack/src/StackBuilder.ts
@@ -34,7 +34,10 @@ import {
 } from "./services/storage.ts";
 import { makeStudioServiceDocker } from "./services/studio.ts";
 import { makeVectorServiceDocker } from "./services/vector.ts";
-import { dependencyTimeoutSecondsForServices } from "./services/health-budgets.ts";
+import {
+  dependencyTimeoutSecondsForServices,
+  POSTGRES_INIT_COMPLETION_BUDGET_SECONDS,
+} from "./services/health-budgets.ts";
 import type { PreparedStackArtifacts } from "./StackPreparation.ts";
 import type { StackServiceProjectionCatalog } from "./StackStateProjection.ts";
 import type { AllocatedPorts } from "./PortAllocator.ts";
@@ -565,6 +568,15 @@ export class StackBuilder extends Context.Service<
         );
         const hasPostgresInit = postgresResolution.type === "binary";
         const postgresDeps = dependsOnPostgres(hasPostgresInit);
+        const postgresConsumerDependencyTimeoutSeconds =
+          POSTGRES_DEPENDENCY_TIMEOUT_SECONDS +
+          (hasPostgresInit ? POSTGRES_INIT_COMPLETION_BUDGET_SECONDS : 0);
+        const storageDependencyTimeoutSeconds =
+          STORAGE_DEPENDENCY_TIMEOUT_SECONDS +
+          (hasPostgresInit ? POSTGRES_INIT_COMPLETION_BUDGET_SECONDS : 0);
+        const analyticsDependencyTimeoutSeconds =
+          ANALYTICS_DEPENDENCY_TIMEOUT_SECONDS +
+          (hasPostgresInit ? POSTGRES_INIT_COMPLETION_BUDGET_SECONDS : 0);
         const jwtJwks = generateJwks(config.jwtSecret);
 
         const defs: Array<ServiceDef & { enabled: boolean }> = [
@@ -636,7 +648,7 @@ export class StackBuilder extends Context.Service<
               : {
                   dependencies: [{ service: "postgres", condition: "healthy" as const }],
                 }),
-            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
+            dependencyTimeoutSeconds: postgresConsumerDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -675,7 +687,7 @@ export class StackBuilder extends Context.Service<
                   apiPort: config.apiPort,
                   dependencies: postgresDeps,
                 })),
-            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
+            dependencyTimeoutSeconds: postgresConsumerDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -704,7 +716,7 @@ export class StackBuilder extends Context.Service<
                   networkArgs: dockerNetworkArgs(platform.os, [config.edgeRuntime.port]),
                   dependencies: postgresDeps,
                 })),
-            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
+            dependencyTimeoutSeconds: postgresConsumerDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -746,7 +758,7 @@ export class StackBuilder extends Context.Service<
               networkArgs: dockerNetworkArgs(platform.os, [config.realtime.port]),
               dependencies: postgresDeps,
             }),
-            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
+            dependencyTimeoutSeconds: postgresConsumerDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -774,7 +786,7 @@ export class StackBuilder extends Context.Service<
               dependencies: postgresDeps,
               cleanupDataDirOnExit: hasAutoManagedPath(config, config.storage.dataDir),
             }),
-            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
+            dependencyTimeoutSeconds: postgresConsumerDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -791,7 +803,7 @@ export class StackBuilder extends Context.Service<
               networkArgs: dockerNetworkArgs(platform.os, [config.imgproxy.port]),
               dependencies: [{ service: "storage", condition: "healthy" }],
             }),
-            dependencyTimeoutSeconds: STORAGE_DEPENDENCY_TIMEOUT_SECONDS,
+            dependencyTimeoutSeconds: storageDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -808,7 +820,7 @@ export class StackBuilder extends Context.Service<
               networkArgs: dockerNetworkArgs(platform.os, [config.pgmeta.port]),
               dependencies: postgresDeps,
             }),
-            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
+            dependencyTimeoutSeconds: postgresConsumerDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -836,7 +848,7 @@ export class StackBuilder extends Context.Service<
               ]),
               dependencies: postgresDeps,
             }),
-            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
+            dependencyTimeoutSeconds: postgresConsumerDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -854,7 +866,7 @@ export class StackBuilder extends Context.Service<
               networkArgs: dockerNetworkArgs(platform.os, []),
               dependencies: [{ service: "analytics", condition: "healthy" }],
             }),
-            dependencyTimeoutSeconds: ANALYTICS_DEPENDENCY_TIMEOUT_SECONDS,
+            dependencyTimeoutSeconds: analyticsDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -890,7 +902,7 @@ export class StackBuilder extends Context.Service<
               ]),
               dependencies: postgresDeps,
             }),
-            dependencyTimeoutSeconds: POSTGRES_DEPENDENCY_TIMEOUT_SECONDS,
+            dependencyTimeoutSeconds: postgresConsumerDependencyTimeoutSeconds,
             enabled: true,
           });
         }
@@ -925,7 +937,7 @@ export class StackBuilder extends Context.Service<
                       { service: "analytics", condition: "healthy" },
                     ],
             }),
-            dependencyTimeoutSeconds: ANALYTICS_DEPENDENCY_TIMEOUT_SECONDS,
+            dependencyTimeoutSeconds: analyticsDependencyTimeoutSeconds,
             enabled: true,
           });
         }
diff --git a/packages/stack/src/StackBuilder.unit.test.ts b/packages/stack/src/StackBuilder.unit.test.ts
index 81f98dc56e..75935f65ac 100644
--- a/packages/stack/src/StackBuilder.unit.test.ts
+++ b/packages/stack/src/StackBuilder.unit.test.ts
@@ -11,7 +11,10 @@ import { nativePostgresNeedsDockerAccess } from "./StackBuilder.ts";
 import type { AllocatedPorts } from "./PortAllocator.ts";
 import { StackPreparation } from "./StackPreparation.ts";
 import type { StackPreparationInput } from "./StackPreparation.ts";
-import { dependencyTimeoutSecondsForServices } from "./services/health-budgets.ts";
+import {
+  dependencyTimeoutSecondsForServices,
+  POSTGRES_INIT_COMPLETION_BUDGET_SECONDS,
+} from "./services/health-budgets.ts";
 import { DEFAULT_VERSIONS } from "./versions.ts";
 
 const testJwtSecret = "super-secret-jwt-token-with-at-least-32-characters";
@@ -206,10 +209,14 @@ describe("StackBuilder", () => {
       expect(names.indexOf("postgres-init")).toBeLessThan(names.indexOf("auth"));
 
       const postgresDependencyTimeout = dependencyTimeoutSecondsForServices(["postgres"]);
-      for (const name of ["postgres-init", "postgrest", "auth"]) {
+      expect(
+        graph.startOrder.find((service) => service.name === "postgres-init")
+          ?.dependencyTimeoutSeconds,
+      ).toBe(postgresDependencyTimeout);
+      for (const name of ["postgrest", "auth"]) {
         expect(
           graph.startOrder.find((service) => service.name === name)?.dependencyTimeoutSeconds,
-        ).toBe(postgresDependencyTimeout);
+        ).toBe(postgresDependencyTimeout + POSTGRES_INIT_COMPLETION_BUDGET_SECONDS);
       }
 
       expect(serviceProjection.get("postgres")).toEqual({ visibility: "public" });
@@ -353,6 +360,9 @@ describe("StackBuilder", () => {
 
       const authDef = graph.startOrder.find((s) => s.name === "auth");
       expect(authDef?.dependencies).toEqual([{ service: "postgres", condition: "healthy" }]);
+      expect(authDef?.dependencyTimeoutSeconds).toBe(
+        dependencyTimeoutSecondsForServices(["postgres"]),
+      );
     }).pipe(Effect.provide(layer));
   });
 
diff --git a/packages/stack/src/StackStateProjection.ts b/packages/stack/src/StackStateProjection.ts
index 1d878a5a49..51b25512e8 100644
--- a/packages/stack/src/StackStateProjection.ts
+++ b/packages/stack/src/StackStateProjection.ts
@@ -17,18 +17,6 @@ function isHelperActive(state: RawServiceState): boolean {
   return state.status !== "Stopped" && state.status !== "Failed";
 }
 
-function sameState(a: StackServiceState | undefined, b: StackServiceState): boolean {
-  return (
-    a?.name === b.name &&
-    a.status === b.status &&
-    a.pid === b.pid &&
-    a.exitCode === b.exitCode &&
-    a.restartCount === b.restartCount &&
-    a.startedAt === b.startedAt &&
-    a.error === b.error
-  );
-}
-
 function projectPublicState(
   raw: RawServiceState,
   rawByName: ReadonlyMap<string, RawServiceState>,
@@ -95,10 +83,3 @@ export function projectStackState(
 ): StackServiceState | undefined {
   return projectStackStates(rawStates, catalog).find((state) => state.name === name);
 }
-
-export function changedProjectedStates(
-  previous: ReadonlyMap<string, StackServiceState>,
-  next: ReadonlyArray<StackServiceState>,
-): ReadonlyArray<StackServiceState> {
-  return next.filter((state) => !sameState(previous.get(state.name), state));
-}
diff --git a/packages/stack/src/services/health-budgets.ts b/packages/stack/src/services/health-budgets.ts
index 70c20a0770..7c623bfb6d 100644
--- a/packages/stack/src/services/health-budgets.ts
+++ b/packages/stack/src/services/health-budgets.ts
@@ -129,6 +129,9 @@ export const stackServiceStartupBudgetSeconds = {
 
 const STARTUP_COORDINATION_MARGIN_SECONDS = 5;
 
+/** Maximum coordination allowance for the native one-shot database initialization step. */
+export const POSTGRES_INIT_COMPLETION_BUDGET_SECONDS = 60;
+
 export const dependencyTimeoutSecondsForServices = (services: ReadonlyArray<ServiceName>): number =>
   services.reduce((total, service) => total + stackServiceStartupBudgetSeconds[service], 0) +
   STARTUP_COORDINATION_MARGIN_SECONDS;

From 858e882b0d17c931e1dab8c87ecc89492130237a Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 15:11:21 +0200
Subject: [PATCH 40/44] fix(stack): stop daemon after terminal disposal

---
 packages/stack/src/daemon.ts | 17 ++++++++++++-----
 packages/stack/src/layers.ts |  2 +-
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/packages/stack/src/daemon.ts b/packages/stack/src/daemon.ts
index de7671d72e..713916940f 100644
--- a/packages/stack/src/daemon.ts
+++ b/packages/stack/src/daemon.ts
@@ -7,6 +7,7 @@ import { PORT_FIELDS, reservePorts, type PortLease } from "./PortAllocator.ts";
 import { allocatedPortFieldsForConfig } from "./ServicePorts.ts";
 import { runningServiceVersionsForConfig } from "./StackMetadata.ts";
 import { foregroundDaemonLayer } from "./layers.ts";
+import { LocalStackLifecycle } from "./LocalStack.ts";
 import { Stack } from "./Stack.ts";
 import { resolveDaemonConfig, type DaemonConfigInput } from "./StackConfigResolver.ts";
 import { StateManager, type StackState } from "./StateManager.ts";
@@ -47,7 +48,9 @@ export async function runDaemon(
   const msg = await waitForMessage<DaemonStartMessage>();
   const { socketPath } = msg;
 
-  let appRuntime: ManagedRuntime.ManagedRuntime<Stack | StateManager | ApiProxy, never> | undefined;
+  let appRuntime:
+    | ManagedRuntime.ManagedRuntime<Stack | StateManager | ApiProxy | LocalStackLifecycle, never>
+    | undefined;
   let daemonRuntime: ManagedRuntime.ManagedRuntime<DaemonServer, never> | undefined;
   let portLease: PortLease | undefined;
 
@@ -80,6 +83,7 @@ export async function runDaemon(
     // Build the stack (services are started later via POST /start)
     const localStack = await localAppRuntime.runPromise(Stack);
     const apiProxy = await localAppRuntime.runPromise(ApiProxy);
+    const localStackLifecycle = await localAppRuntime.runPromise(LocalStackLifecycle);
     const info = await localAppRuntime.runPromise(localStack.getInfo());
     const localStateManager = await localAppRuntime.runPromise(StateManager);
 
@@ -118,13 +122,13 @@ export async function runDaemon(
     process.disconnect?.();
 
     const daemon = await daemonRuntime.runPromise(DaemonServer);
-    // A terminal activation deadline has already disposed the stack's scoped processes and port
-    // leases. Treat that as a whole-runtime failure: keeping the management or proxy servers alive
-    // would expose partially disposed state. This path deliberately does not drain unrelated
+    // Any terminal stack disposal is a whole-runtime failure: keeping the management or proxy
+    // servers alive would expose disposed state. This path deliberately does not drain unrelated
     // in-flight proxy requests; callers should reconnect after starting a fresh daemon.
     await Promise.race([
       daemonRuntime.runPromise(daemon.awaitShutdown),
       localAppRuntime.runPromise(apiProxy.awaitTerminalFailure),
+      localAppRuntime.runPromise(localStackLifecycle.awaitDisposed),
       waitForSignal(),
     ]);
     await shutdownDaemon({ appRuntime, daemonRuntime });
@@ -170,7 +174,10 @@ function waitForSignal(): Promise<"SIGINT" | "SIGTERM"> {
 }
 
 async function shutdownDaemon(opts: {
-  readonly appRuntime?: ManagedRuntime.ManagedRuntime<Stack | StateManager | ApiProxy, never>;
+  readonly appRuntime?: ManagedRuntime.ManagedRuntime<
+    Stack | StateManager | ApiProxy | LocalStackLifecycle,
+    never
+  >;
   readonly daemonRuntime?: ManagedRuntime.ManagedRuntime<DaemonServer, never>;
 }): Promise<void> {
   await opts.daemonRuntime?.dispose().catch(() => {});
diff --git a/packages/stack/src/layers.ts b/packages/stack/src/layers.ts
index 8761d2b0c6..be97567638 100644
--- a/packages/stack/src/layers.ts
+++ b/packages/stack/src/layers.ts
@@ -102,7 +102,7 @@ export const foregroundDaemonLayer = (
   config: ResolvedDaemonConfig,
   platformFactory: PlatformFactory,
   portLease: PortLease,
-): Layer.Layer<Stack | StateManager | ApiProxy> => {
+): Layer.Layer<Stack | StateManager | ApiProxy | LocalStackLifecycle> => {
   const platform = platformFactory({
     apiPort: config.apiPort,
     releaseApiPort: portLease.release(["apiPort"]),

From c860c9a487419a20e948bb3587ee7b68ad8965d9 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 15:13:13 +0200
Subject: [PATCH 41/44] fix(stack): strip functions from daemon startup

---
 packages/stack/src/StackConfigResolver.ts   | 10 +++++++++-
 packages/stack/src/createStack.unit.test.ts | 15 ++++++++++++++-
 packages/stack/src/layers.ts                | 17 +++++++++--------
 3 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/packages/stack/src/StackConfigResolver.ts b/packages/stack/src/StackConfigResolver.ts
index 6a847c47e5..38e33e5e79 100644
--- a/packages/stack/src/StackConfigResolver.ts
+++ b/packages/stack/src/StackConfigResolver.ts
@@ -567,11 +567,19 @@ export type DaemonConfigInput = Omit<StackConfig, "functions"> & {
   readonly projectStateRoot?: string;
 };
 
+export function sanitizeDaemonConfigInput(
+  input: DaemonConfigInput & { readonly functions?: unknown },
+): DaemonConfigInput {
+  const { functions: _functions, ...config } = input;
+  return config;
+}
+
 export async function resolveDaemonConfig(
   input: DaemonConfigInput,
   opts: Pick<ResolveConfigOptions, "portAllocator"> = {},
 ): Promise<ResolvedDaemonConfig> {
-  const { cwd, name, projectDir, projectStateRoot, ...stackConfig } = input;
+  const { cwd, name, projectDir, projectStateRoot, ...stackConfig } =
+    sanitizeDaemonConfigInput(input);
   if (stackConfig.stackRoot !== undefined || stackConfig.runtimeRoot !== undefined) {
     throw new Error("Managed daemon stacks derive stackRoot and runtimeRoot automatically");
   }
diff --git a/packages/stack/src/createStack.unit.test.ts b/packages/stack/src/createStack.unit.test.ts
index 2413e5a65a..da7f2f2c4e 100644
--- a/packages/stack/src/createStack.unit.test.ts
+++ b/packages/stack/src/createStack.unit.test.ts
@@ -16,7 +16,11 @@ import type {
   ReadyOptions,
   StackConfig,
 } from "./StackConfig.ts";
-import { resolveConfig, resolveDaemonConfig } from "./StackConfigResolver.ts";
+import {
+  resolveConfig,
+  resolveDaemonConfig,
+  sanitizeDaemonConfigInput,
+} from "./StackConfigResolver.ts";
 import { DEFAULT_VERSIONS } from "./versions.ts";
 
 const DEFAULT_PORTS: AllocatedPorts = {
@@ -192,6 +196,15 @@ describe("createStack types", () => {
     );
   });
 
+  it("strips function bundles from daemon configuration at runtime", () => {
+    const input = {
+      cwd: "/project",
+      functions: { environment: { SECRET: "must-not-cross-ipc" } },
+    };
+
+    expect(sanitizeDaemonConfigInput(input)).toEqual({ cwd: "/project" });
+  });
+
   it("resolveDaemonConfig prefers legacy defaults for a first named stack", async () => {
     await withTempCacheRoot(async (cacheRoot) => {
       const config = await resolveDaemonConfig({
diff --git a/packages/stack/src/layers.ts b/packages/stack/src/layers.ts
index 8761d2b0c6..fbd3b69d77 100644
--- a/packages/stack/src/layers.ts
+++ b/packages/stack/src/layers.ts
@@ -24,7 +24,7 @@ import {
 } from "./StateManager.ts";
 import { StackBuilder } from "./StackBuilder.ts";
 import type { ResolvedDaemonConfig, ResolvedStackConfig } from "./StackConfig.ts";
-import type { DaemonConfigInput } from "./StackConfigResolver.ts";
+import { sanitizeDaemonConfigInput, type DaemonConfigInput } from "./StackConfigResolver.ts";
 import { UnixHttpClient } from "./UnixHttpClient.ts";
 import { resolveManagedStack } from "./managed-stack.ts";
 import {
@@ -169,21 +169,22 @@ export const daemonLayer = (
   FileSystem.FileSystem | Path.Path | UnixHttpClient
 > =>
   Effect.gen(function* () {
-    if (input.stackRoot !== undefined || input.runtimeRoot !== undefined) {
+    const daemonInput = sanitizeDaemonConfigInput(input);
+    if (daemonInput.stackRoot !== undefined || daemonInput.runtimeRoot !== undefined) {
       return yield* new DaemonStartError({
         message: "Managed daemon stacks derive stackRoot and runtimeRoot automatically",
       });
     }
-    const projectDir = input.projectDir ?? input.cwd;
-    const name = input.name ?? DEFAULT_MANAGED_STACK_NAME;
-    const cacheRoot = input.cacheRoot ?? defaultCacheRoot();
+    const projectDir = daemonInput.projectDir ?? daemonInput.cwd;
+    const name = daemonInput.name ?? DEFAULT_MANAGED_STACK_NAME;
+    const cacheRoot = daemonInput.cacheRoot ?? defaultCacheRoot();
     const stackRoot =
-      input.projectStateRoot !== undefined
-        ? join(input.projectStateRoot, "stacks", name)
+      daemonInput.projectStateRoot !== undefined
+        ? join(daemonInput.projectStateRoot, "stacks", name)
         : defaultManagedStackRoot(cacheRoot, projectDir, name);
     const runtimeRoot = defaultManagedRuntimeRoot(stackRoot);
     const config: DaemonConfigInput = {
-      ...input,
+      ...daemonInput,
       cacheRoot,
       projectDir,
       name,

From eeac2a068c00cef31335b8f5976ee990bba1f39b Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 15:18:44 +0200
Subject: [PATCH 42/44] fix(process-compose): handle stopped dependencies

---
 packages/process-compose/src/Orchestrator.ts  | 14 +++-
 .../src/Orchestrator.unit.test.ts             | 78 +++++++++++++++++++
 2 files changed, 88 insertions(+), 4 deletions(-)

diff --git a/packages/process-compose/src/Orchestrator.ts b/packages/process-compose/src/Orchestrator.ts
index 64f508c535..dd1014cbd7 100644
--- a/packages/process-compose/src/Orchestrator.ts
+++ b/packages/process-compose/src/Orchestrator.ts
@@ -246,13 +246,18 @@ export class Orchestrator extends Context.Service<
                     (state) =>
                       state.desired === "running" &&
                       (state.status === "Healthy" ||
-                        (state.status === "Failed" &&
+                        ((state.status === "Failed" || state.status === "Stopped") &&
                           !willRestartAfterExit(dependency.effectiveDef, state))),
                   );
-                  if (ready.status === "Failed") {
+                  if (ready.status !== "Healthy") {
                     yield* sendEvent(def.name, {
                       _tag: "DependencyFailed",
-                      error: `Dependency ${depDef.name} failed: ${ready.error ?? "unknown failure"}`,
+                      error: `Dependency ${depDef.name} failed: ${
+                        ready.error ??
+                        (ready.exitCode === null
+                          ? "stopped before becoming healthy"
+                          : `exited with code ${ready.exitCode} before becoming healthy`)
+                      }`,
                     });
                     return;
                   }
@@ -756,7 +761,8 @@ export class Orchestrator extends Context.Service<
                   d.name !== name &&
                   service !== undefined &&
                   SubscriptionRef.getUnsafe(service.state).desired !== "stopped" &&
-                  restartPolicy === "no"
+                  restartPolicy === "no" &&
+                  d.healthCheck == null
                 ) {
                   continue;
                 }
diff --git a/packages/process-compose/src/Orchestrator.unit.test.ts b/packages/process-compose/src/Orchestrator.unit.test.ts
index 06b954acd8..954ce355b6 100644
--- a/packages/process-compose/src/Orchestrator.unit.test.ts
+++ b/packages/process-compose/src/Orchestrator.unit.test.ts
@@ -636,6 +636,48 @@ describe("Orchestrator", () => {
     }).pipe(Effect.provide(layer), Effect.scoped);
   });
 
+  it.live("startService restarts a stopped health-checked dependency", () => {
+    const { layer, proc } = setupOrchestrator(
+      [
+        svc("db", {
+          restart: "no",
+          healthCheck: {
+            probe: { _tag: "Exec", command: "check", args: [] },
+            periodSeconds: 0.01,
+          },
+        }),
+        svc("api", {
+          dependencies: [{ service: "db", condition: "healthy" }],
+        }),
+        svc("worker", {
+          dependencies: [{ service: "db", condition: "healthy" }],
+          dependencyTimeoutSeconds: 1,
+        }),
+      ],
+      {
+        exitDelay: "5 seconds",
+        perService: {
+          db: { exitCode: 0, exitDelay: "50 millis" },
+          check: { exitCode: 0, exitDelay: "1 millis" },
+        },
+      },
+    );
+
+    return Effect.gen(function* () {
+      const orc = yield* Orchestrator;
+      yield* orc.startService("api");
+      yield* proc.waitForSpawn("api");
+      yield* waitForStopped(orc, "db");
+
+      yield* orc.startService("worker");
+      yield* proc.waitForSpawn("db", 2);
+      yield* proc.waitForSpawn("worker");
+
+      expect(proc.spawned.filter((spawn) => spawn.command === "db")).toHaveLength(2);
+      expect((yield* orc.getState("worker")).status).not.toBe("Failed");
+    }).pipe(Effect.provide(layer), Effect.scoped);
+  });
+
   it.live("startService reruns a directly requested successful one-shot", () => {
     const { layer, proc } = setupOrchestrator([svc("setup", { restart: "no" })]);
     return Effect.gen(function* () {
@@ -1197,6 +1239,42 @@ describe("Orchestrator", () => {
       }).pipe(Effect.provide(layer), Effect.scoped);
     });
 
+    it.live("healthy dependency fails after clean-exit restarts are exhausted", () => {
+      const { layer, proc } = setupOrchestrator(
+        [
+          svc("db", {
+            restart: "always",
+            maxRestarts: 1,
+            healthCheck: {
+              probe: { _tag: "Exec", command: "check", args: [] },
+              initialDelaySeconds: 5,
+            },
+          }),
+          svc("api", {
+            restart: "no",
+            dependencies: [{ service: "db", condition: "healthy" }],
+            dependencyTimeoutSeconds: 3,
+          }),
+        ],
+        {
+          perService: {
+            db: { exitCode: 0, exitDelay: "10 millis" },
+            check: { exitCode: 0, exitDelay: "1 millis" },
+          },
+        },
+      );
+
+      return Effect.gen(function* () {
+        const orc = yield* Orchestrator;
+        yield* orc.start();
+
+        const state = yield* waitForFailed(orc, "api");
+        expect(state.error).toContain("Dependency db failed");
+        expect(state.error).not.toContain("Timed out");
+        expect(proc.spawned.filter((spawn) => spawn.command === "db")).toHaveLength(2);
+      }).pipe(Effect.provide(layer), Effect.scoped);
+    });
+
     it.live("completed dependency waits through a transient failed restart", () => {
       let setupSpawns = 0;
       const { layer, proc } = setupOrchestrator(

From 32bc3b6707b031ccfb235e8014920ace79d13bf0 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 15:22:09 +0200
Subject: [PATCH 43/44] fix(stack): flush terminal daemon responses

---
 packages/stack/src/DaemonServer.ts |  2 ++
 packages/stack/src/daemon.ts       | 23 ++++++++++++++---------
 2 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/packages/stack/src/DaemonServer.ts b/packages/stack/src/DaemonServer.ts
index 4900fcba8c..58bb409c78 100644
--- a/packages/stack/src/DaemonServer.ts
+++ b/packages/stack/src/DaemonServer.ts
@@ -19,6 +19,7 @@ export class DaemonServer extends Context.Service<
   DaemonServer,
   {
     readonly address: HttpServer.Address;
+    readonly beginShutdown: Effect.Effect<void>;
     readonly awaitShutdown: Effect.Effect<void>;
   }
 >()("stack/DaemonServer") {
@@ -366,6 +367,7 @@ export class DaemonServer extends Context.Service<
 
         return {
           address: server.address,
+          beginShutdown,
           awaitShutdown: Deferred.await(shutdownDeferred),
         };
       }),
diff --git a/packages/stack/src/daemon.ts b/packages/stack/src/daemon.ts
index 713916940f..a3e0c61464 100644
--- a/packages/stack/src/daemon.ts
+++ b/packages/stack/src/daemon.ts
@@ -82,7 +82,6 @@ export async function runDaemon(
 
     // Build the stack (services are started later via POST /start)
     const localStack = await localAppRuntime.runPromise(Stack);
-    const apiProxy = await localAppRuntime.runPromise(ApiProxy);
     const localStackLifecycle = await localAppRuntime.runPromise(LocalStackLifecycle);
     const info = await localAppRuntime.runPromise(localStack.getInfo());
     const localStateManager = await localAppRuntime.runPromise(StateManager);
@@ -93,8 +92,9 @@ export async function runDaemon(
       Layer.provide(daemonServerFactory(socketPath)),
     );
 
-    daemonRuntime = ManagedRuntime.make(daemonLayer);
-    await daemonRuntime.runPromise(DaemonServer);
+    const localDaemonRuntime = ManagedRuntime.make(daemonLayer);
+    daemonRuntime = localDaemonRuntime;
+    await localDaemonRuntime.runPromise(DaemonServer);
 
     // Claim live state before acknowledging startup to the parent.
     const state: StackState = {
@@ -121,14 +121,19 @@ export async function runDaemon(
     process.send!(response);
     process.disconnect?.();
 
-    const daemon = await daemonRuntime.runPromise(DaemonServer);
+    const daemon = await localDaemonRuntime.runPromise(DaemonServer);
     // Any terminal stack disposal is a whole-runtime failure: keeping the management or proxy
-    // servers alive would expose disposed state. This path deliberately does not drain unrelated
-    // in-flight proxy requests; callers should reconnect after starting a fresh daemon.
+    // servers alive would expose disposed state. Route it through the server's delayed shutdown
+    // signal so the request that caused disposal can flush its typed response first.
+    const shutdownAfterLocalStackDisposal = localAppRuntime
+      .runPromise(localStackLifecycle.awaitDisposed)
+      .then(async () => {
+        await localDaemonRuntime.runPromise(daemon.beginShutdown);
+        await localDaemonRuntime.runPromise(daemon.awaitShutdown);
+      });
     await Promise.race([
-      daemonRuntime.runPromise(daemon.awaitShutdown),
-      localAppRuntime.runPromise(apiProxy.awaitTerminalFailure),
-      localAppRuntime.runPromise(localStackLifecycle.awaitDisposed),
+      localDaemonRuntime.runPromise(daemon.awaitShutdown),
+      shutdownAfterLocalStackDisposal,
       waitForSignal(),
     ]);
     await shutdownDaemon({ appRuntime, daemonRuntime });

From 0369f52042e591cd19d215d766cc440732590f29 Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 6 Aug 2026 15:31:19 +0200
Subject: [PATCH 44/44] fix(stack): reject function path symlink escapes

---
 packages/stack/src/functions.ts           | 30 +++++++++++++++++--
 packages/stack/src/functions.unit.test.ts | 36 ++++++++++++++++++++++-
 2 files changed, 62 insertions(+), 4 deletions(-)

diff --git a/packages/stack/src/functions.ts b/packages/stack/src/functions.ts
index 4a321b8695..478790fe6e 100644
--- a/packages/stack/src/functions.ts
+++ b/packages/stack/src/functions.ts
@@ -1,4 +1,5 @@
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { Effect, FileSystem, Path, Schema } from "effect";
 import type { ResolvedStackConfig } from "./StackConfig.ts";
 
@@ -54,14 +55,37 @@ export interface ResolvedFunctionsBundle extends Schema.Schema.Type<
   typeof ResolvedFunctionsBundleSchema
 > {}
 
-function isWithinProjectDir(projectDir: string, candidate: string): boolean {
-  const relativePath = relative(resolve(projectDir), candidate);
+function isWithinPath(root: string, candidate: string): boolean {
+  const relativePath = relative(root, candidate);
   return (
     relativePath === "" ||
     (relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath))
   );
 }
 
+function nearestExistingAncestor(candidate: string): string | undefined {
+  let current = resolve(candidate);
+  while (!existsSync(current)) {
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+  return current;
+}
+
+function isWithinProjectDir(projectDir: string, candidate: string): boolean {
+  const resolvedProjectDir = resolve(projectDir);
+  if (!isWithinPath(resolvedProjectDir, candidate)) return false;
+
+  const existingCandidate = nearestExistingAncestor(candidate);
+  if (existingCandidate === undefined) return false;
+  try {
+    return isWithinPath(realpathSync(resolvedProjectDir), realpathSync(existingCandidate));
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Docker mounts `projectDir` at the same absolute path as the host. Keeping all
  * referenced files below that root gives native and Docker runtimes the same
diff --git a/packages/stack/src/functions.unit.test.ts b/packages/stack/src/functions.unit.test.ts
index 39cd9d780e..46f9298c83 100644
--- a/packages/stack/src/functions.unit.test.ts
+++ b/packages/stack/src/functions.unit.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "@effect/vitest";
 import { BunServices } from "@effect/platform-bun";
-import { mkdtempSync } from "node:fs";
+import { mkdtempSync, symlinkSync } from "node:fs";
 import { readFile, readdir, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -154,6 +154,40 @@ describe("stack Functions runtime config", () => {
     await rm(root, { recursive: true, force: true });
   });
 
+  it("rejects bundle paths that escape projectDir through a symlink", async () => {
+    const root = makeTempProject();
+    const outside = makeTempProject();
+    const bundle = makeBundle(root);
+    symlinkSync(
+      outside,
+      join(root, "linked-outside"),
+      process.platform === "win32" ? "junction" : "dir",
+    );
+
+    await expect(
+      resolveConfig({
+        projectDir: root,
+        functions: {
+          ...bundle,
+          functions: [
+            {
+              ...bundle.functions[0]!,
+              entrypointPath: join(root, "linked-outside", "index.ts"),
+            },
+          ],
+        },
+      }),
+    ).rejects.toMatchObject({
+      _tag: "StackBuildError",
+      detail: "Invalid Edge Functions bundle",
+    });
+
+    await Promise.all([
+      rm(root, { recursive: true, force: true }),
+      rm(outside, { recursive: true, force: true }),
+    ]);
+  });
+
   it("keeps placeholder mode when no functions are supplied", async () => {
     const stackConfig = await resolveConfig({ functions: false });