refactor(stack): simplify managed stack architecture

apps/cli/README.md

@@ -131,7 +131,6 @@ use. The package API itself keeps eager startup as its default.
 Useful companion docs:
 
 - [`../../packages/stack/docs/architecture.md`](../../packages/stack/docs/architecture.md)
-- [`../../packages/stack/docs/detach-mode.md`](../../packages/stack/docs/detach-mode.md)
 - [`docs/ui.md`](./docs/ui.md)
 
 ## Development

apps/cli/docs/supabase-home.md

@@ -1,7 +1,7 @@
 # Supabase CLI State Layout
 
-This document describes how CLI-owned state is split between the repo-local `.supabase/`
-directory and the global `SUPABASE_HOME`.
+The CLI keeps authored project configuration in `supabase/`, checkout-local link and version
+caches in `.supabase/`, and managed runtime state in the global `SUPABASE_HOME` directory.
 
 By default:
 
@@ -11,297 +11,110 @@ SUPABASE_HOME = ~/.supabase
 
 The path can be overridden with the `SUPABASE_HOME` environment variable.
 
-## Goals
+## State roots
 
-- keep committed project intent in `supabase/`
-- keep checkout-specific machine state explicit and discoverable in `.supabase/`
-- keep machine-global auth, telemetry, and binary caches in `SUPABASE_HOME`
-- keep live runtime socket state under the OS temp directory
+### Project files
 
-## Two State Roots
-
-### Repo-local project state
-
-Project-scoped local state lives next to the repo as a gitignored sibling of `supabase/`:
+User-authored configuration and migrations live in the repository:
 
 ```text
 <project-root>/
   supabase/
-    config.json
+    config.toml
     migrations/
     functions/
-  .supabase/
-    project.json
-    local-versions.json
-    stacks/
-      default/
-        stack.json
-        state.json
-        data/
-```
-
-This state is:
-
-- local to one checkout
-- readable by humans and agents directly from the repo root
-- intentionally not committed
-
-### Global CLI home
-
-Machine-global state remains under `SUPABASE_HOME`:
-
-```text
-~/.supabase/
-  access-token
-  telemetry.json
-  traces/
-    <date>.ndjson
-  bin/
-    <service>/
-      <version>/
-        <platform>/
-          ...
-```
-
-This state is shared across all local projects on the machine.
-
-## Project Root Resolution
-
-For project-local CLI state, the CLI resolves the active project root from `cwd` using this
-order:
-
-1. nearest ancestor containing `supabase/config.toml` or `supabase/config.json`
-2. otherwise nearest ancestor containing `.supabase/project.json`
-3. otherwise `cwd`
-
-That means:
-
-- `supabase link` and `supabase unlink` can work before `supabase init`
-- `supabase start`, `supabase stop`, `supabase status`, `supabase stack list`, and `supabase logs`
-  can be run from nested subdirectories inside a linked checkout
-- stack persistence is no longer keyed by a hashed global project directory
-
-`@supabase/config` still only discovers `supabase/config.*`. The broader `.supabase/project.json`
-fallback is CLI-specific runtime behavior.
-
-## Repo-local Files
-
-### `project.json`
-
-`.supabase/project.json` stores cached linked-remote metadata for the checkout.
-
-Shape:
-
-```json
-{
-  "ref": "abcdefghijklmnopqrst",
-  "name": "my-project",
-  "fetchedAt": "2026-03-25T12:34:56.000Z",
-  "versions": {
-    "postgres": "17.6.1.084",
-    "postgrest": "14.4",
-    "auth": "2.188.1",
-    "storage": "1.43.3"
-  }
-}
-```
-
-This file is written by `supabase link` and removed by `supabase unlink`.
-
-It is CLI runtime state, not committed project config. The linked project ref does not live in
-`supabase/config.json`.
-
-### `local-versions.json`
-
-`.supabase/local-versions.json` stores optional checkout-local service version overrides.
-
-Shape:
-
-```json
-{
-  "updatedAt": "2026-03-23T10:15:00.000Z",
-  "versions": {
-    "auth": "2.180.0",
-    "storage": "1.39.2"
-  }
-}
 ```
 
-This is a power-user escape hatch. There is no dedicated top-level command for it yet. Advanced
-users can edit it directly if they want persistent local overrides.
+The CLI discovers the active project from the nearest ancestor containing `supabase/config.toml`
+(or the legacy config filename where supported), then passes that canonical project root to the
+managed stack identity. Managed `workspaceId` is local repository/folder lineage and is unrelated
+to the remote Supabase project ID in `config.toml` or link state.
 
-### `stacks/<name>/stack.json`
+### Checkout-local caches
 
-Each project can own multiple named local stacks:
+Gitignored checkout metadata lives beside the project:
 
 ```text
-.supabase/stacks/
-  default/
-  preview/
-  ci/
+<project-root>/.supabase/
+  project.json
+  local-versions.json
 ```
 
-The implicit stack name is `default`.
-
-`stack.json` is the durable per-stack metadata record. It stores:
-
-- `schemaVersion`
-- `updatedAt`
-- `ports`
-- the pinned baseline `services` manifest for that stack
-- `lastNotifiedUpdateFingerprint` when the CLI has already warned about available updates
-
-### `stacks/<name>/state.json`
-
-`state.json` is the live runtime record for a running stack. It stores connection info,
-service endpoints, process identifiers, and the exact service versions currently running.
-
-It is written when the managed stack is running and removed on normal `supabase stop`.
-
-### `stacks/<name>/data/`
-
-`data/` stores persisted local service data for that stack.
-
-The CLI does not currently persist stack logs under `.supabase/`; logs are buffered in memory by
-the daemon and streamed on demand through `supabase logs`.
-
-## Service Version Resolution
-
-There are two separate concepts:
-
-- the **candidate baseline**, computed from cached linked-remote versions plus CLI defaults
-- the **pinned baseline**, stored in `.supabase/stacks/<name>/stack.json`
-
-The candidate baseline is:
+`project.json` is the linked remote version cache. `local-versions.json` contains optional
+checkout-local service-version overrides. Neither file records whether a local stack is running.
+For ordinary non-Git folders, `.supabase/identity.json` stores the managed workspace identity. Git
+checkouts keep checkout identity in Git metadata instead and do not use that marker.
 
-1. cached linked service versions from `.supabase/project.json`
-2. CLI `DEFAULT_VERSIONS` as fallback for everything else
+### Global managed runtime
 
-The pinned baseline is what a named stack actually uses by default on subsequent starts.
-
-Runtime precedence is:
-
-1. per-run `supabase start --service-version service=version`
-2. checkout-local overrides from `.supabase/local-versions.json`
-3. pinned stack versions from `.supabase/stacks/<name>/stack.json`
-
-If a stack has never been started before and `stack.json` does not exist yet, the CLI creates it
-from the current candidate baseline.
-
-This keeps linked remote parity, persistent local experimentation, and one-off overrides separate
-from committed project config.
-
-## Local and Remote Sync Workflow
-
-### `supabase init`
-
-`supabase init` creates a minimal repo-scoped config file:
+Managed stack documents and runtime artifacts are shared through the global CLI home:
 
 ```text
-supabase/config.json
-```
-
-with only a top-level `"$schema"` reference:
-
-```json
-{
-  "$schema": "https://supabase.com/docs/cli/config.schema.json"
-}
+<SUPABASE_HOME>/
+  access-token
+  telemetry.json
+  traces/
+  bin/
+  managed/
+    stacks/
+      <stack-id>/
+        stack.json
+        data/
+        logs/
+        runtime/
 ```
 
-It does not link a remote project and does not create `.supabase/project.json`.
-
-### `supabase link`
-
-`supabase link` binds the local project to a remote Supabase project and refreshes the cached
-linked metadata in `.supabase/project.json`.
-
-If the linked remote service versions differ from any existing pinned stack metadata, `link`
-warns and tells the user to run `supabase stack update`.
-
-### `supabase stack update`
-
-`supabase stack update` is the explicit adoption step for pinned local stack versions.
-
-When the project is linked, it first fetches the latest remote service versions and rewrites
-`.supabase/project.json`. It then recomputes the candidate baseline and writes the pinned stack
-versions into `.supabase/stacks/<name>/stack.json`.
-
-If the stack is currently running, `update` warns that the user must stop and start it again for
-the new pinned versions to take effect.
+`stack.json` is the single durable managed record. It contains stack identity, including the
+canonical local-project key relative to the enclosing Git checkout, and sticky port intents
+and assignments, lifecycle, runtime control endpoint, and launch metadata (mode, versions,
+exclusions, and update-notification fingerprint). Runtime-only service ports are allocated for the
+supervisor run and are not persisted as sticky intents. The deterministic loopback control endpoint
+and ownership protocol are the liveness authority; a stale document is reclaimed by a subsequent
+managed lifecycle operation.
 
-### `supabase stack status`
+There is no project-local `stacks/<name>` directory, `state.json`, daemon socket file, or second
+StateManager metadata format.
 
-`supabase stack status` is local-only. It does not make a network call.
+## Service-version inputs
 
-It shows:
+The candidate baseline is computed from linked versions in `.supabase/project.json` and the CLI's
+`DEFAULT_VERSIONS` catalog. Runtime precedence is:
 
-- a detailed running view when `state.json` exists and the daemon is alive
-- a detailed stopped view when only `stack.json` exists
-- whether pinned stack versions are up to date against the current candidate baseline
+1. `supabase start --service-version service=version` for one invocation;
+2. checkout-local values in `.supabase/local-versions.json`;
+3. the managed document's `launch.versions` baseline;
+4. catalog defaults for values not supplied by the preceding sources.
 
-### `supabase stack list`
+`supabase stack update` refreshes the linked cache when possible and updates `launch` through the
+managed lifecycle (directly when stopped, or through the owner control route when running). It does
+not write a second project-level pinned-version file.
 
-`supabase stack list` scans `.supabase/stacks/*/stack.json` for the current project and overlays
-live `state.json` data when a daemon is running.
+## Port intents
 
-## What Is Not Under `.supabase/`
+Raw `supabase/config.toml` values and their origins are loaded before defaults are applied. Explicit
+sticky values are persisted as `exact` intents in each managed document. Omitted values remain
+`automatic`; sibling worktrees have independent stack identities and allocations, while live exact
+port conflicts are rejected by the manager. Runtime-only service ports are selected by the managed
+supervisor and are not written to the document.
 
-Not all runtime files live in the repo.
-
-### Auth state
-
-Auth is still machine-global today:
-
-- keyring entry: `Supabase CLI/access-token`
-- filesystem fallback: `<SUPABASE_HOME or ~/.supabase>/access-token`
-
-### Telemetry and traces
-
-Telemetry state remains in `SUPABASE_HOME`:
-
-- `telemetry.json`
-- `traces/`
-
-### Shared binaries
-
-Downloaded binaries remain shared across projects in:
-
-```text
-<SUPABASE_HOME or ~/.supabase>/bin/
-```
-
-The legacy Go installer stores its Deno binary directly under the state root:
-
-```text
-<SUPABASE_HOME or ~/.supabase>/deno
-```
-
-### Live runtime sockets
-
-Managed daemon runtime directories, including the live Unix socket path, still use the OS temp
-directory:
-
-```text
-/tmp/supabase/
-```
-
-The durable stack record remains in the repo-local state directory:
-
-```text
-<project-root>/.supabase/stacks/<stack-name>/stack.json
-```
+## Command behavior
 
-## Ownership Rules
+- `supabase start` resolves launch metadata and port intents, acquires managed control, and records
+  the document before starting services.
+- `supabase status`, `logs`, and `services` attach through the deterministic control endpoint and
+  report only a live owner as running.
+- `supabase stop` asks the owner to stop, waits for `stopped` and control release, and keeps the
+  document by default. `--no-backup` removes it after deterministic cleanup.
+- `supabase stack list` enumerates healthy managed documents and checks control ownership for live
+  status; `--project-dir` scopes the result to one checkout.
 
-When deciding where something belongs, use this rule of thumb:
+## Auth, telemetry, and binaries
 
-- user-authored project config belongs in the repository under `supabase/`
-- checkout-specific machine state belongs in `.supabase/`
-- machine-global auth, telemetry, and caches belong in `SUPABASE_HOME`
-- live runtime temp/socket state belongs under the OS temp directory
+Auth, telemetry, traces, and downloaded binaries remain machine-global under `SUPABASE_HOME`.
+Legacy installer artifacts may coexist under that root, but they are not part of managed stack
+coordination.
 
-## Related Docs
+## Related docs
 
 - [CLI Code Structure](./code-structure.md)
 - [Service Versioning](../../../packages/stack/docs/service-versioning.md)

apps/cli/src/legacy/commands/start/start.command.ts

@@ -48,7 +48,7 @@ export type LegacyStartFlags = CliCommand.Command.Config.Infer<typeof config>;
 // are not listed here: they come from `BunServices`/`processControlLayer`/
 // `runtimeInfoLayer` in the root runtime (`shared/cli/run.ts`), the same way
 // `stop`/`status` rely on the former. `HttpClient.HttpClient` is NOT provided by the
-// root runtime — `BunServices.layer` never supplies it, and `unixHttpClientLayer` is a
+// root runtime — `BunServices.layer` never supplies it, and `httpTransportClientLayer` is a
 // different service tag entirely — so it's composed here via `legacyHttpClientLayer`,
 // the same `FetchHttpClient`-backed layer `db reset`/`seed buckets` use, needed for the
 // health-check probes (`legacyWaitForHealthyServices`) and `legacySeedBucketsRun`.