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));
 
 // ---------------------------------------------------------------------------