feat(lab): multi-instance isolation for concurrent stacks

.xcli.example.yaml

@@ -1,5 +1,5 @@
-# lab-dev configuration example
-# This file is generated by 'lab-dev init' and can be customized for your environment
+# xcli lab configuration example
+# This file is generated by 'xcli lab init' and can be customized for your environment
 
 # Repository paths (auto-discovered or manually specified)
 repos:
@@ -9,6 +9,11 @@ repos:
   labBackend: ../lab-backend
   lab: ../lab
 
+# Optional stable instance id. If omitted, xcli derives one from the config
+# root and config path. With the wrapped config format this is lab.instance.id.
+instance:
+  id: ""
+
 # Operating mode: "local" or "hybrid"
 # - local: All services run locally including Xatu ClickHouse cluster
 # - hybrid: External Xatu data source, local transformations and APIs
@@ -67,7 +72,7 @@ infrastructure:
 
   volumes:
     persist: true  # Use named volumes (data survives down/up cycles)
-                  # Set to false for clean slate every restart
+                  # Use 'xcli lab destroy --instance <id>' for an intentional clean slate
 
   # Observability stack (Prometheus + Grafana)
   # When enabled, starts Prometheus to scrape all lab service metrics

README.md

@@ -61,6 +61,10 @@ xcli cc           # Launch web dashboard (Command Center)
 xcli lab status   # Check status (CLI)
 ```
 
+Each checkout is a distinct lab instance. A single instance uses the familiar
+default ports when they are free. Additional worktrees get isolated Docker
+resources, generated configs, state, and a non-overlapping port slot.
+
 Services:
 
 - Lab Frontend: <http://localhost:5173>
@@ -160,11 +164,31 @@ Keyboard shortcuts:
 xcli lab init                    # Initialize configuration
 xcli lab check                   # Verify environment (repos, Docker, config)
 xcli lab up                      # Start all services (always rebuilds)
-xcli lab down                    # Stop and remove containers/volumes
-xcli lab clean                   # Remove all containers, volumes, and build artifacts
+xcli lab down                    # Stop the selected instance, preserve data
+xcli lab stop                    # Same safe stop as down
+xcli lab clean                   # Safe alias for down
 xcli lab status                  # Show service status
+xcli lab status --all            # Show all known instances
+xcli lab list                    # List persisted instances
+xcli lab show <instance-id>      # Show one instance manifest and live state
+xcli lab destroy --instance <id> # Delete one instance's data and generated state
+xcli lab reset redis --instance <id> # Intentionally clear Redis for one instance
 ```
 
+`down`, `stop`, and `clean` preserve ClickHouse, Redis, Prometheus, and Grafana
+data. `destroy` and `reset redis` are the destructive paths.
+
+Use `--instance <id>` from any directory to target a specific persisted
+instance:
+
+```bash
+xcli lab --instance worktree-a stop
+xcli lab --instance worktree-a destroy --yes
+```
+
+By default, xcli derives the instance id from the config root and config path.
+You can set a stable id with `lab.instance.id` in `.xcli.yaml`.
+
 ### Build & Rebuild
 
 ```bash
@@ -197,6 +221,9 @@ xcli lab logs -f <service>       # Follow logs
 
 Services: `lab-backend`, `lab-frontend`, `cbt-mainnet`, `cbt-api-mainnet`, etc.
 
+Service commands target the selected instance. Use `xcli lab --instance <id>
+logs lab-backend` to inspect another worktree's stack.
+
 ### Configuration
 
 ```bash
@@ -243,8 +270,11 @@ xcli lab status
 # View logs
 xcli lab logs lab-backend -f
 
-# Complete cleanup (removes all containers, volumes, build artifacts)
-xcli lab clean
+# Diagnose instance paths, ports, traps, and latest rebuild failure
+xcli lab diagnose
+
+# Remove all generated state and data for one instance
+xcli lab destroy --instance <id>
 ```
 
 ### Getting Help
@@ -263,19 +293,23 @@ xcli lab mode --help         # Understand local vs hybrid modes
 `.xcli.yaml` is created by `xcli lab init`. Key settings:
 
 ```yaml
-mode: local  # "local" or "hybrid"
-
-networks:
-  - name: mainnet
-    enabled: true
-    portOffset: 0
-
-infrastructure:
-  clickhouse:
-    xatu:
-      mode: local  # "local" or "external"
-  volumes:
-    persist: true  # Keep data between restarts
+lab:
+  instance:
+    id: worktree-a  # Optional stable id; otherwise xcli derives one
+
+  mode: local  # "local" or "hybrid"
+
+  networks:
+    - name: mainnet
+      enabled: true
+      portOffset: 0
+
+  infrastructure:
+    clickhouse:
+      xatu:
+        mode: local  # "local" or "external"
+    volumes:
+      persist: true  # Keep data between restarts
 ```
 
 **Modes:**

cmd/xcli/main.go

@@ -88,6 +88,7 @@ func main() {
 		}
 
 		log.SetLevel(level)
+		config.SetRuntimeConfigPath(configPath)
 
 		// Enable log writer based on verbose flag
 		logWriter.SetEnabled(verbose)

go.mod

@@ -11,6 +11,7 @@ require (
 	github.com/aws/smithy-go v1.26.0
 	github.com/charmbracelet/bubbletea v1.3.10
 	github.com/charmbracelet/lipgloss v1.1.0
+	github.com/containerd/errdefs v1.0.0
 	github.com/docker/docker v28.5.2+incompatible
 	github.com/docker/go-connections v0.7.0
 	github.com/pterm/pterm v0.12.83
@@ -53,7 +54,6 @@ require (
 	github.com/clipperhouse/displaywidth v0.11.0 // indirect
 	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
 	github.com/containerd/console v1.0.5 // indirect
-	github.com/containerd/errdefs v1.0.0 // indirect
 	github.com/containerd/errdefs/pkg v0.3.0 // indirect
 	github.com/containerd/log v0.1.0 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect