refactor(stack): consolidate local lifecycle ownership

packages/stack/README.md

@@ -198,7 +198,7 @@ service and its projected status.
 ### Readiness
 
 ```typescript
-await stack.ready(); // Inherit the stack's finite two-minute default
+await stack.ready(); // Inherit the stack's finite three-minute default
 await stack.ready({ mode: "finite", timeoutMs: 30_000 });
 await stack.ready({ mode: "infinite" }); // Explicit debugging override
 await stack.serviceReady("postgres");
@@ -209,7 +209,10 @@ In eager mode, `start()` blocks until every enabled service is ready. In lazy mo
 for direct listeners and services activated so far. Unrequested lazy services report `Dormant`.
 Calling `serviceReady()` for a dormant lazy
 service fails immediately; activate it through the proxy or call `startService()` first. Foreground
-and detached stacks use the same readiness rules.
+and detached stacks use the same readiness rules. The configured policy also applies to service
+start, restart, activation, and reload operations; a call-specific option overrides it. A finite
+deadline fails with `STACK_READINESS_TIMEOUT` and disposes the local runtime, so the handle cannot
+be used to relaunch processes afterward.
 
 ### Status
 
@@ -308,15 +311,16 @@ try {
 }
 ```
 
-| Code                | Description                                  |
-| ------------------- | -------------------------------------------- |
-| `SERVICE_NOT_FOUND` | Referenced a service that doesn't exist      |
-| `SERVICE_NOT_READY` | Service failed to become healthy             |
-| `BUILD_ERROR`       | Failed to build the service dependency graph |
-| `BINARY_NOT_FOUND`  | No binary available for the current platform |
-| `DOWNLOAD_ERROR`    | Binary download failed                       |
-| `PORT_CONFLICT`     | Requested port is already in use             |
-| `PORT_ALLOCATION`   | Failed to allocate a free port               |
+| Code                      | Description                                  |
+| ------------------------- | -------------------------------------------- |
+| `SERVICE_NOT_FOUND`       | Referenced a service that doesn't exist      |
+| `SERVICE_NOT_READY`       | Service failed to become healthy             |
+| `STACK_READINESS_TIMEOUT` | Stack readiness exceeded its finite deadline |
+| `BUILD_ERROR`             | Failed to build the service dependency graph |
+| `BINARY_NOT_FOUND`        | No binary available for the current platform |
+| `DOWNLOAD_ERROR`          | Binary download failed                       |
+| `PORT_CONFLICT`           | Requested port is already in use             |
+| `PORT_ALLOCATION`         | Failed to allocate a free port               |
 
 ## Examples
 

packages/stack/docs/architecture.md

@@ -48,11 +48,13 @@ functions options, and per-service configuration. `false` disables an optional s
 4. applies per-service defaults and current `DEFAULT_VERSIONS`;
 5. records auto-managed paths for scoped cleanup.
 
-Readiness policy is part of the resolved configuration. The package default is a finite two-minute
+Readiness policy is part of the resolved configuration. The package default is a finite three-minute
 deadline; callers can choose a different finite deadline or explicit infinite waiting. Per-call
 `ReadyOptions` take precedence over the stack policy, while `inherit` delegates to the stack
-policy. The Promise `ready()` / `serviceReady()` Adapter applies that resolver today. The Effect
-lifecycle Interface remains unbounded until deadline enforcement is centralized there.
+policy. The local Implementation applies this resolver to startup, service activation, restart,
+reload, and explicit readiness waits. A finite deadline fails with `StackReadinessError` and runs
+the same scoped cleanup used by disposal. Promise and remote Adapters pass `ReadyOptions` through
+to that Implementation instead of layering a second timeout rule around it.
 
 The current zero-config stack enables PostgreSQL, PostgREST, Auth, and Edge Runtime. Realtime,
 Storage, imgproxy, Mailpit, Postgres Meta, Studio, Analytics, Vector, and Supavisor are enabled only
@@ -119,7 +121,7 @@ Vector without Analytics, and Studio without Postgres Meta.
 
 ## Lifecycle ownership
 
-The current local Implementation is `StackLifecycleCoordinator`. It owns one scoped lifecycle:
+The local Implementation is `LocalStack`. Its scoped layer owns one lifecycle:
 
 - preparation and its single-flight deferred;
 - graph construction and the process-compose runtime;
@@ -129,19 +131,21 @@ The current local Implementation is `StackLifecycleCoordinator`. It owns one sco
 - exact cleanup targets and metadata persistence;
 - disposal of processes, Docker resources, ports, and auto-managed paths.
 
-`Stack.ts` currently provides a thin public Effect Interface over that coordinator. `ApiProxy`
-uses the narrower `StackServiceActivator` Interface so an incoming request can activate a lazy
-backend without gaining unrelated lifecycle operations.
+`Stack.ts` contains only the public Effect Interface and transport schemas. `LocalStack` constructs
+the state once and publishes both `Stack` and the narrower `StackServiceActivator` Interface from
+the same scoped layer. `ApiProxy` therefore activates a lazy backend without gaining unrelated
+lifecycle operations or requiring a second pass-through lifecycle tag.
 
-Before the orchestrator exists, the coordinator publishes synthetic `Pending` and `Downloading`
+Before the orchestrator exists, `LocalStack` publishes synthetic `Pending` and `Downloading`
 states. After construction, it subscribes to raw process-compose state and publishes only public
 projected states. `StackServiceState` adds `Downloading`, `Initializing`, and `Dormant` to the raw
 process statuses.
 
 `start()` prepares artifacts, creates the runtime once, starts the appropriate services, and waits
 for their generic process-compose readiness. `stop()` preserves explicit per-service stop intent;
-`dispose()` additionally closes the scoped runtime and executes cleanup. Generic process-compose
-readiness remains intentionally policy-free and unbounded.
+`dispose()` additionally closes the scoped runtime and executes cleanup. Stack readiness policy is
+enforced around generic process-compose waits, which remain intentionally policy-free and
+unbounded. Structural `Equal.equals` comparison suppresses duplicate projected state emissions.
 
 ## Eager and lazy activation
 
@@ -237,8 +241,9 @@ Detached mode adds:
 - `StateManager`: atomically persists and discovers durable metadata and live state.
 
 The management transport includes health, status, status stream, start/stop, readiness,
-per-service lifecycle, logs/history, and Edge Runtime reload routes. It is local Unix-socket
-transport, not the public Supabase API proxy.
+per-service lifecycle, logs/history, and Edge Runtime reload routes. Readiness waits use validated
+`ReadyOptions` JSON bodies and preserve `StackReadinessError` across the transport. It is local
+Unix-socket transport, not the public Supabase API proxy.
 
 See [detach mode](./detach-mode.md) for paths, process startup, and compiled executable dispatch.
 

packages/stack/docs/detach-mode.md

@@ -114,14 +114,16 @@ metadata and service data remain.
 `DaemonServer` exposes the local `Stack` Interface on the Unix socket. Current routes include:
 
 - `/health`, `/status`, and `/status/stream`;
-- `/start`, `/stop`, and `/ready`;
+- `/start`, `/stop`, and `POST /ready`;
 - per-service start, stop, restart, and readiness;
 - merged and per-service live logs plus buffered history;
 - functions and Edge Runtime reload.
 
-State and log streams use SSE. Ordinary responses and typed failures use validated JSON shapes.
-`RemoteStack` decodes that transport back into the same Effect `Stack` Interface used in
-foreground mode, including `ServiceNotFoundError`, `ServiceReadyError`, and `StackBuildError`.
+State and log streams use SSE. Readiness routes use `POST` with a validated readiness-policy body;
+omitting an override sends the explicit `inherit` representation. Ordinary responses and typed
+failures use validated JSON shapes. `RemoteStack` decodes that transport back into the same Effect
+`Stack` Interface used in foreground mode, including `ServiceNotFoundError`, `ServiceReadyError`,
+`StackBuildError`, and `StackReadinessError`.
 
 The management socket is not the public local API endpoint. `ApiProxy` still owns the configured
 HTTP API port inside the daemon process.
@@ -141,6 +143,14 @@ package. In particular:
 On normal `/stop`, the daemon gracefully stops the stack, signals HTTP shutdown after the response
 has had time to flush, disposes both managed runtimes, and removes live state/runtime paths.
 
+A readiness deadline is terminal for that local runtime: the stack disposes its scoped resources,
+the daemon returns the typed timeout response, and then the daemon shuts down. This prevents later
+requests from relaunching processes after cleanup has already run. The boundary is deliberately
+fail-closed across the whole daemon, rather than isolated to the service that timed out: once
+processes and port leases are being released, the management and proxy servers cannot safely keep
+advertising a usable runtime. This terminal path does not drain unrelated in-flight requests to
+otherwise healthy services; callers must reconnect after starting a fresh daemon.
+
 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.

packages/stack/src/ApiProxy.ts

@@ -1,4 +1,4 @@
-import { Effect, Layer, Option, Context, Duration, Schedule, Result } from "effect";
+import { Deferred, Effect, Layer, Option, Context, Schedule, Result } from "effect";
 import {
   Headers,
   HttpBody,
@@ -9,12 +9,11 @@ import {
   HttpServerRequest,
   HttpServerResponse,
 } from "effect/unstable/http";
-import { activationTimeoutSecondsForService, StackServiceActivator } from "./ServiceActivation.ts";
-import type { ServiceName } from "./versions.ts";
+import { StackServiceActivator } from "./ServiceActivation.ts";
+import type { ServiceName } from "./ServiceName.ts";
 
 export interface ProxyConfig {
   readonly listenPort: number;
-  readonly activationTimeout?: Duration.Input;
   readonly gotruePort: number;
   readonly postgrestPort: number;
   readonly postgrestAdminPort: number;
@@ -132,19 +131,17 @@ function makeProxyHandler(
   client: HttpClient.HttpClient,
   config: ProxyConfig,
   activator: StackServiceActivator["Service"],
+  signalTerminalFailure: Effect.Effect<void>,
   opts: ProxyHandlerOptions,
 ) {
   return (req: HttpServerRequest.HttpServerRequest) =>
     Effect.gen(function* () {
-      const activation = yield* activator
-        .activate(opts.service)
-        .pipe(
-          Effect.timeout(
-            config.activationTimeout ??
-              Duration.seconds(activationTimeoutSecondsForService(opts.service)),
-          ),
-          Effect.result,
-        );
+      const activation = yield* activator.activate(opts.service).pipe(
+        Effect.tapError((error) =>
+          error._tag === "StackReadinessError" ? signalTerminalFailure : Effect.void,
+        ),
+        Effect.result,
+      );
       if (Result.isFailure(activation)) {
         return HttpServerResponse.text("Service unavailable", {
           status: 503,
@@ -225,6 +222,8 @@ export class ApiProxy extends Context.Service<
   ApiProxy,
   {
     readonly address: HttpServer.Address;
+    /** Completes when terminal lazy-activation failure requires daemon teardown. */
+    readonly awaitTerminalFailure: Effect.Effect<void>;
   }
 >()("local/ApiProxy") {
   static layer = (
@@ -239,13 +238,15 @@ export class ApiProxy extends Context.Service<
         const server = yield* HttpServer.HttpServer;
         const client = yield* HttpClient.HttpClient;
         const activator = yield* StackServiceActivator;
+        const terminalFailure = yield* Deferred.make<void>();
+        const signalTerminalFailure = Deferred.succeed(terminalFailure, void 0).pipe(Effect.asVoid);
 
         const routes = [
           HttpRouter.route("*", "/health", HttpServerResponse.text("OK", { status: 200 })),
           HttpRouter.route(
             "*",
             "/.well-known/oauth-authorization-server",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "auth",
               backendPort: config.gotruePort,
               backendPath: "/.well-known/oauth-authorization-server",
@@ -254,7 +255,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/auth/v1/verify",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "auth",
               backendPort: config.gotruePort,
               stripPrefix: "/auth/v1",
@@ -263,7 +264,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/auth/v1/callback",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "auth",
               backendPort: config.gotruePort,
               stripPrefix: "/auth/v1",
@@ -272,7 +273,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/auth/v1/authorize",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "auth",
               backendPort: config.gotruePort,
               stripPrefix: "/auth/v1",
@@ -281,7 +282,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/auth/v1/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "auth",
               backendPort: config.gotruePort,
               stripPrefix: "/auth/v1",
@@ -291,7 +292,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/rest/v1/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "postgrest",
               backendPort: config.postgrestPort,
               stripPrefix: "/rest/v1",
@@ -301,7 +302,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/rest-admin/v1/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "postgrest",
               backendPort: config.postgrestAdminPort,
               stripPrefix: "/rest-admin/v1",
@@ -310,7 +311,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/graphql/v1",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "postgrest",
               backendPort: config.postgrestPort,
               backendPath: "/rpc/graphql",
@@ -321,7 +322,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/functions/v1/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "edge-runtime",
               backendPort: config.edgeRuntimePort,
               stripPrefix: "/functions/v1",
@@ -333,7 +334,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/realtime/v1/api/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "realtime",
               backendPort: config.realtimePort,
               stripPrefix: "/realtime/v1",
@@ -343,7 +344,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/realtime/v1/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "realtime",
               backendPort: config.realtimePort,
               stripPrefix: "/realtime/v1",
@@ -352,7 +353,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/storage/v1/s3/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "storage",
               backendPort: config.storagePort,
               stripPrefix: "/storage/v1",
@@ -361,7 +362,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/storage/v1/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "storage",
               backendPort: config.storagePort,
               stripPrefix: "/storage/v1",
@@ -371,7 +372,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/pg/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "pgmeta",
               backendPort: config.pgmetaPort,
               stripPrefix: "/pg",
@@ -380,7 +381,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/analytics/v1/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "analytics",
               backendPort: config.analyticsPort,
               stripPrefix: "/analytics/v1",
@@ -389,7 +390,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/pooler/v2/*",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "pooler",
               backendPort: config.poolerPort,
               stripPrefix: "/pooler",
@@ -398,7 +399,7 @@ export class ApiProxy extends Context.Service<
           HttpRouter.route(
             "*",
             "/mcp",
-            makeProxyHandler(client, config, activator, {
+            makeProxyHandler(client, config, activator, signalTerminalFailure, {
               service: "studio",
               backendPort: config.studioPort,
               backendPath: "/api/mcp",
@@ -423,6 +424,7 @@ export class ApiProxy extends Context.Service<
 
         return {
           address: server.address,
+          awaitTerminalFailure: Deferred.await(terminalFailure),
         };
       }),
     );