From 2ec8d7201eda2b6b148fcb7b71abbbe775ce384d Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Wed, 2 Sep 2026 21:29:50 -0400
Subject: [PATCH 1/2] feat(compass-app): revive embedded dual-mode + supervisor
 pipeline (RIG-3197, RIG-3198)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reverse the RIG-2554 client-only retirement: embedded app mode returns alongside the surviving client mode, per the frozen embedded-revival design (docs/designs/ui/compass-native-embedded-revival/design.md, §A1/§A2/§A3/§A6 shell half). T-1 and T-2 land together because T-1 alone would flip the absent-app.toml default to a ModeEmbedded whose launch arm is only a transient error, and T-2 alone would not compile (embedded.go consumes T-1's appconfig API).

T-1 (RIG-3197) revives dual-mode in go/internal/appconfig: ModeEmbedded is added after ModeClient so ModeClient keeps the zero value; Parse resolves absent/empty/embedded mode to ModeEmbedded (the zero-config onboarding default) and rejects the client-only server_url/ca_cert fields under embedded mode legibly; Load gains the override parameter and resolves absent-file to the embedded default rather than a first-run error; the --mode/$COMPASS_APP_MODE override returns with flag>env>file>default precedence. The RIG-2554 retirement-error copy is deleted, not kept beside a working arm.

T-2 (RIG-3198) revives the in-process supervisor pipeline in go/cmd/compass-app (embedded.go, lifecycle.go, preflight_adapters.go) and the go/internal/preflight package, reconciled against current main rather than restored verbatim. The app supervises the stack through the compass-stack binary (fire-and-return): preflight then compass-stack up then a WhoAmI dial over the stack's Unix socket. Reconciliations: the app-side DSN duplicate and the DB preflight probe are dropped (postgres is now a DL-260 container the stack starts; up-Ready is the DB verification); stackUpArgs passes only up --state-dir --image --socket and none of the CLI-defaulted postgres/collector/listen flags; the revived files carry the current (linux && gtk4) || darwin build tags; the launch dispatch regains the two-arm switch handing bridge.NewUnixTarget(socket) plus the WhoAmI account id to the bridge service. Preflight v2 widens the OS check to linux|darwin, adds a darwin-only machine-ready seam (its adapter is a later task), drops the DB and uid checks (main's runner is uid-agnostic via the userns keep-id remap), and adds a fatal podman-version floor check that surfaces the podman 4.3+ requirement at the front door instead of deep inside a fire-and-return stack whose exit 0 hides the runner's own refusal. The bring-up timeout is raised to cover a three-image cold pull. shellStartupJS re-parameterizes on the resolved mode.

Ledger-impact: none
Refs RIG-1662
Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 go/cmd/compass-app/client_test.go        |  12 +-
 go/cmd/compass-app/embedded.go           | 423 ++++++++++++++
 go/cmd/compass-app/embedded_path_test.go |  64 +++
 go/cmd/compass-app/embedded_test.go      | 679 +++++++++++++++++++++++
 go/cmd/compass-app/lifecycle.go          |  74 +++
 go/cmd/compass-app/lifecycle_test.go     | 109 ++++
 go/cmd/compass-app/main.go               | 183 ++++--
 go/cmd/compass-app/preflight_adapters.go |  61 ++
 go/internal/appconfig/appconfig.go       | 133 +++--
 go/internal/appconfig/appconfig_test.go  | 274 ++++++---
 go/internal/appconfig/doc.go             |  29 +-
 go/internal/bridge/pump.go               |  11 +-
 go/internal/preflight/doc.go             |  19 +
 go/internal/preflight/preflight.go       | 164 ++++++
 go/internal/preflight/preflight_test.go  | 281 ++++++++++
 15 files changed, 2329 insertions(+), 187 deletions(-)
 create mode 100644 go/cmd/compass-app/embedded.go
 create mode 100644 go/cmd/compass-app/embedded_path_test.go
 create mode 100644 go/cmd/compass-app/embedded_test.go
 create mode 100644 go/cmd/compass-app/lifecycle.go
 create mode 100644 go/cmd/compass-app/lifecycle_test.go
 create mode 100644 go/cmd/compass-app/preflight_adapters.go
 create mode 100644 go/internal/preflight/doc.go
 create mode 100644 go/internal/preflight/preflight.go
 create mode 100644 go/internal/preflight/preflight_test.go

diff --git a/go/cmd/compass-app/client_test.go b/go/cmd/compass-app/client_test.go
index 82f1f8b63..6bc68eabf 100644
--- a/go/cmd/compass-app/client_test.go
+++ b/go/cmd/compass-app/client_test.go
@@ -166,13 +166,13 @@ func pemEncodeCert(t *testing.T, cert *x509.Certificate) []byte {
 	return pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: cert.Raw})
 }
 
-// TestShellStartupJS covers the OQ-8 startup-global injection: the client mode
-// token, __COMPASS_SERVER_URL__ present in client mode, and JSON-escaping of a
-// hostile server URL so it cannot break out of the script. Client is now the
-// only mode (embedded was retired in RIG-2554).
+// TestShellStartupJS covers the OQ-8 startup-global injection for CLIENT mode:
+// the client mode token, __COMPASS_SERVER_URL__ present in client mode, and
+// JSON-escaping of a hostile server URL so it cannot break out of the script.
+// (The embedded-mode arm of shellStartupJS is covered in embedded_test.go.)
 func TestShellStartupJS(t *testing.T) {
 	t.Run("client injects mode and server url", func(t *testing.T) {
-		js, err := shellStartupJS("https://remote.example:8443")
+		js, err := shellStartupJS(appconfig.ModeClient.String(), "https://remote.example:8443")
 		if err != nil {
 			t.Fatalf("shellStartupJS err = %v, want nil", err)
 		}
@@ -186,7 +186,7 @@ func TestShellStartupJS(t *testing.T) {
 
 	t.Run("hostile server url is JSON-escaped, not a breakout", func(t *testing.T) {
 		hostile := `https://x/"+alert(1)+"</script><script>`
-		js, err := shellStartupJS(hostile)
+		js, err := shellStartupJS(appconfig.ModeClient.String(), hostile)
 		if err != nil {
 			t.Fatalf("shellStartupJS err = %v, want nil", err)
 		}
diff --git a/go/cmd/compass-app/embedded.go b/go/cmd/compass-app/embedded.go
new file mode 100644
index 000000000..8b8e8830d
--- /dev/null
+++ b/go/cmd/compass-app/embedded.go
@@ -0,0 +1,423 @@
+//go:build (linux && gtk4) || darwin
+
+// The embedded-mode launch pipeline. Embedded mode wires the native shell
+// end-to-end before the window opens: host preflight → spawn and supervise the
+// private stack (via the compass-stack CLI) → learn the caller account id
+// (WhoAmI, DL-111) → hand the resolved socket + account id to the bridge/UI. It
+// is the composition root that supplies the real external effects (podman
+// probes, the compass-stack exec, the h2c-UDS WhoAmI dial) behind small injected
+// seams, so the orchestration is unit-testable without a real stack.
+//
+// This file supervises the stack through the compass-stack BINARY, not by
+// importing go/internal/stack: `compass-stack up` brings the stack to Ready and
+// exits 0 while the children keep running (fire-and-return), so the pipeline
+// runs it, waits for exit 0, and then dials the same socket it passed as
+// --socket.
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+
+	"connectrpc.com/connect"
+
+	compassv1 "github.com/RigelBuild/compass/go/gen/compass/v1"
+	"github.com/RigelBuild/compass/go/gen/compass/v1/compassv1connect"
+	"github.com/RigelBuild/compass/go/internal/preflight"
+)
+
+// defaultAgentImage is the canonical agent image ref the embedded stack runs
+// when no --image/$COMPASS_AGENT_IMAGE is supplied. The ref is locked
+// (docs/designs/platform/compass-agent-image-publish.md §Ref); the native app
+// does not bundle the image (DL-112) — compass-stack podman-pulls it from GHCR
+// at first run.
+const defaultAgentImage = "ghcr.io/rigelbuild/compass-agent:latest"
+
+// The compass-stack CLI flag names the embedded pipeline drives. Shared by
+// stackUpArgs and stackDownArgs so the two argv builders cannot drift on a flag
+// spelling (and so the strings are named once rather than repeated inline).
+const (
+	flagStateDir = "--state-dir"
+	flagImage    = "--image"
+	flagSocket   = "--socket"
+)
+
+// embeddedPipeline is the embedded-mode launch pipeline over its injected
+// external effects. Each field is one genuine effect the real launch supplies
+// (preflight run, the compass-stack up exec, the WhoAmI dial); a test supplies
+// deterministic stubs, so the orchestration — order, short-circuit, and the
+// argv it builds — is verified with no real podman/stack/exec.
+type embeddedPipeline struct {
+	// preflight runs the host precondition checks and folds any failures into a
+	// single legible error (the real seam wraps preflight.Deps.Run(...).Err()).
+	preflight func(ctx context.Context) error
+	// stackUp runs `compass-stack up` with the given argv and waits for it to
+	// exit 0 (fire-and-return); a non-zero exit is returned as an error carrying
+	// the captured stderr.
+	stackUp func(ctx context.Context, args []string) error
+	// whoAmI dials the stack socket over h2c-UDS and returns the caller account
+	// id (WhoAmI, DL-111 — server-derived, never supplied).
+	whoAmI func(ctx context.Context, socket string) (string, error)
+}
+
+// embeddedParams is the resolved input to one embedded launch: the single socket
+// path the stack serves and the pipeline then dials, plus the stack argv inputs.
+// The argv omits --database so compass-stack recomputes the default DSN from
+// --state-dir (the app carries no second DSN copy — §A2 reconciliation 1).
+type embeddedParams struct {
+	// socket is resolveSocket()'s result — the SAME value passed to
+	// `--socket` and dialed for WhoAmI (and, upstream, the bridge pump).
+	socket string
+	// stateDir is the app state directory passed to `--state-dir`.
+	stateDir string
+	// image is the agent image ref passed to `--image`.
+	image string
+}
+
+// runEmbedded runs the embedded-mode launch and builds the embedded-only quit
+// controller. It runs the pipeline (preflight → stack up → WhoAmI) and, on
+// success, returns the resolved caller account id together with a *quitController
+// wired to the injected stackDown seam (its quit func is wired to app.Quit by
+// run() once the app exists). resolveStackBin and this controller are embedded
+// concerns only: a client-only install has no compass-stack binary and no stack
+// to stop, so neither may gate a client launch (design §T5.6).
+func runEmbedded(
+	ctx context.Context,
+	pipeline embeddedPipeline,
+	params embeddedParams,
+	stackDown func(ctx context.Context, args []string) error,
+) (string, *quitController, error) {
+	accountID, err := pipeline.run(ctx, params)
+	if err != nil {
+		return "", nil, err
+	}
+	quitter := &quitController{
+		stackDown: stackDown,
+		params:    params,
+		timeout:   stackDownTimeout,
+	}
+	return accountID, quitter, nil
+}
+
+// run executes the embedded launch in order: preflight → stack up → WhoAmI. A
+// preflight failure short-circuits (the stack is never spawned) and returns the
+// aggregated legible error verbatim. On success it returns the resolved caller
+// account id.
+func (p embeddedPipeline) run(ctx context.Context, params embeddedParams) (string, error) {
+	if err := p.preflight(ctx); err != nil {
+		return "", err
+	}
+
+	args := stackUpArgs(params)
+	if err := p.stackUp(ctx, args); err != nil {
+		return "", err
+	}
+	slog.Info("stack ready", "socket", params.socket)
+
+	accountID, err := p.whoAmI(ctx, params.socket)
+	if err != nil {
+		return "", fmt.Errorf("resolving caller identity over %s: %w", params.socket, err)
+	}
+	slog.Info("caller identity resolved", "account", accountID)
+	return accountID, nil
+}
+
+// stackUpArgs builds the `compass-stack up` argv from the resolved params. It is
+// pure (no I/O, no exec) so the exact invocation is unit-testable without
+// running anything — mirroring cmd/compass-stack's pure resolveConfig. It passes
+// ONLY --state-dir/--image/--socket: --database is omitted (compass-stack
+// computes the identical default DSN from --state-dir, so passing it would
+// duplicate that logic), and --postgres-image/--collector-image/--listen are
+// omitted so the CLI's defaults are the contract (the app re-learns nothing the
+// stack already owns — §A2 reconciliation 2).
+func stackUpArgs(p embeddedParams) []string {
+	args := []string{
+		"up",
+		flagStateDir, p.stateDir,
+		flagImage, p.image,
+		flagSocket, p.socket,
+	}
+	return args
+}
+
+// captureStderr wires cmd.Stderr to a temp *os.File and returns a reader for the
+// bytes captured so far plus a cleanup that closes and removes the file.
+// Capturing to an *os.File — not a bytes.Buffer — is load-bearing for the
+// fire-and-return stack commands: `compass-stack up` exits 0 once the stack is
+// Ready while its postgres/server/runner children keep running. os/exec backs a
+// non-*os.File stderr writer with an OS pipe whose copy goroutine Cmd.Wait
+// blocks on until EOF, and those lingering children inherit the pipe's
+// write-end, so EOF never arrives and Wait hangs forever. An *os.File is dup'd
+// straight into the child (no pipe, no goroutine), so Wait returns the instant
+// compass-stack itself exits; and the children write to a plain file that never
+// EPIPEs, so capturing this way never signals the very stack the app must keep
+// alive.
+func captureStderr(cmd *exec.Cmd) (read func() string, cleanup func(), err error) {
+	f, err := os.CreateTemp("", "compass-stack-stderr-*")
+	if err != nil {
+		return nil, nil, fmt.Errorf("creating stderr capture file: %w", err)
+	}
+	cmd.Stderr = f
+	read = func() string {
+		// Best-effort: an unreadable capture degrades to the generic
+		// "compass-stack ... failed" error, and never blocks surfacing.
+		b, _ := os.ReadFile(f.Name())
+		return strings.TrimSpace(string(b))
+	}
+	cleanup = func() {
+		// Deferred cleanup of a temp capture file: a Close/Remove error here is
+		// not actionable (the process is past the point the stderr mattered), so
+		// it is discarded.
+		_ = f.Close()
+		_ = os.Remove(f.Name())
+	}
+	return read, cleanup, nil
+}
+
+// runStackUp is the real stackUp seam: it execs the compass-stack binary at bin
+// with the given argv and waits for it to exit 0 (up is fire-and-return, so
+// Run returning nil means the stack reached Ready and its children keep
+// running). A non-zero exit is surfaced with the captured stderr so the failure
+// copy is legible.
+func runStackUp(bin string) func(ctx context.Context, args []string) error {
+	return func(ctx context.Context, args []string) error {
+		//nolint:gosec // G204: bin is operator/PATH-resolved (resolveStackBin) and
+		// the argv is pipeline-assembled (stackUpArgs), not user input.
+		cmd := exec.CommandContext(ctx, bin, args...)
+		cmd.Env = prependExecDirToPath(os.Environ(), filepath.Dir(bin))
+		stderr, cleanup, capErr := captureStderr(cmd)
+		if capErr != nil {
+			return capErr
+		}
+		defer cleanup()
+		if err := cmd.Run(); err != nil {
+			if ctx.Err() == context.DeadlineExceeded || errors.Is(err, context.DeadlineExceeded) {
+				return fmt.Errorf("compass-stack up exceeded the %s bring-up window "+
+					"(a cold first run pulls three images from their registries — the agent "+
+					"image from GHCR, the postgres and collector images from their stock "+
+					"registries — which can take longer): %w", bringUpTimeout, err)
+			}
+			if msg := stderr(); msg != "" {
+				return fmt.Errorf("compass-stack up failed: %w: %s", err, msg)
+			}
+			return fmt.Errorf("compass-stack up failed: %w", err)
+		}
+		return nil
+	}
+}
+
+// stackDownArgs builds the `compass-stack down` argv from the resolved params.
+// It mirrors stackUpArgs (pure, no I/O, no exec) so the exact teardown
+// invocation is unit-testable without running anything. down parses the SAME
+// config flags as up, and its resolveConfig REQUIRES a non-empty --state-dir AND
+// --image (both rejected if empty), so --image is carried even though teardown
+// does not pull an image — it is the config key compass-stack keys the stack's
+// identity off. --database is omitted for the same reason as up (compass-stack
+// recomputes the identical default DSN from --state-dir), and --linger is
+// omitted because down is not lingerable (down's whole job is to tear the stack
+// down, so a linger flag would be nonsense — compass-stack rejects it).
+func stackDownArgs(p embeddedParams) []string {
+	args := []string{
+		"down",
+		flagStateDir, p.stateDir,
+		flagImage, p.image,
+		flagSocket, p.socket,
+	}
+	return args
+}
+
+// runStackDown is the real stackDown seam: it execs the compass-stack binary at
+// bin with the given argv and waits for it to exit 0 (down attaches to the live
+// stack, SIGTERMs the child tree, waits the server drain, and releases the
+// lock). A non-zero exit is surfaced with the captured stderr so the failure
+// copy is legible — mirroring runStackUp's shape exactly.
+func runStackDown(bin string) func(ctx context.Context, args []string) error {
+	return func(ctx context.Context, args []string) error {
+		//nolint:gosec // G204: bin is operator/PATH-resolved (resolveStackBin) and
+		// the argv is pipeline-assembled (stackDownArgs), not user input.
+		cmd := exec.CommandContext(ctx, bin, args...)
+		cmd.Env = prependExecDirToPath(os.Environ(), filepath.Dir(bin))
+		stderr, cleanup, capErr := captureStderr(cmd)
+		if capErr != nil {
+			return capErr
+		}
+		defer cleanup()
+		if err := cmd.Run(); err != nil {
+			if ctx.Err() == context.DeadlineExceeded || errors.Is(err, context.DeadlineExceeded) {
+				return fmt.Errorf("compass-stack down exceeded the %s teardown window "+
+					"(attach, SIGTERM the child tree, wait the server drain): %w", stackDownTimeout, err)
+			}
+			if msg := stderr(); msg != "" {
+				return fmt.Errorf("compass-stack down failed: %w: %s", err, msg)
+			}
+			return fmt.Errorf("compass-stack down failed: %w", err)
+		}
+		return nil
+	}
+}
+
+// whoAmIOverUDS is the real whoAmI seam: it dials the stack socket over
+// prior-knowledge cleartext HTTP/2 (the same door compass-server serves) and
+// calls WhoAmI, returning the server-derived caller account id. The transport
+// shape mirrors internal/stack/adapters/health.go (the established h2c-UDS
+// connect dial).
+func whoAmIOverUDS(ctx context.Context, socket string) (string, error) {
+	protocols := new(http.Protocols)
+	protocols.SetUnencryptedHTTP2(true)
+	transport := &http.Transport{
+		Protocols: protocols,
+		DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
+			var d net.Dialer
+			return d.DialContext(ctx, "unix", socket)
+		},
+	}
+	defer transport.CloseIdleConnections()
+
+	client := compassv1connect.NewCompassServiceClient(&http.Client{Transport: transport}, "http://unix")
+	resp, err := client.WhoAmI(ctx, connect.NewRequest(&compassv1.WhoAmIRequest{}))
+	if err != nil {
+		return "", err
+	}
+	id := resp.Msg.GetAccountId()
+	if id == "" {
+		return "", errors.New("WhoAmI returned an empty account id")
+	}
+	return id, nil
+}
+
+// resolveStackBin picks the compass-stack binary to supervise the stack with:
+// the --compass-stack flag, else $COMPASS_STACK_BIN, else a compass-stack
+// sibling of the running executable (where a packaged build stages it, mirroring
+// resolveAssetsDir's beside-the-executable pattern), else compass-stack on
+// $PATH. The sibling is preferred over $PATH so a packaged build's staged
+// sidecar wins over any ambient compass-stack, while a dev-box build (no
+// sibling) still falls through to $PATH. A legible error names every place it
+// looked when none resolves.
+func resolveStackBin(flagValue string) (string, error) {
+	if flagValue != "" {
+		return flagValue, nil
+	}
+	if env := os.Getenv("COMPASS_STACK_BIN"); env != "" {
+		return env, nil
+	}
+	if exe, err := os.Executable(); err == nil {
+		sibling := filepath.Join(filepath.Dir(exe), "compass-stack")
+		if info, statErr := os.Stat(sibling); statErr == nil && !info.IsDir() {
+			return sibling, nil
+		}
+	}
+	if p, err := exec.LookPath("compass-stack"); err == nil {
+		return p, nil
+	}
+	return "", errors.New("compass-stack binary not found: pass --compass-stack, set $COMPASS_STACK_BIN, " +
+		"put compass-stack on $PATH, or stage it beside the compass-app executable")
+}
+
+// prependExecDirToPath returns env with execDir prepended to its PATH entry so a
+// bundle's sidecar binaries (compass-server/compass-runner) win exec.LookPath
+// inside the supervised stack, while an ambient dev-box PATH keeps working
+// unchanged (prepend, never replace). postgres is NOT a PATH sidecar — it is a
+// DL-260 container the stack runs, not a process the stack LookPaths. env is the
+// process environment (os.Environ() shape: "KEY=VALUE"); a missing PATH entry is
+// created.
+//
+// execDir must be an absolute path — a relative or empty execDir is a no-op, so
+// a bare-name compass-stack (filepath.Dir "." from a $PATH/flag bin) never
+// prepends the current directory onto the child's PATH.
+func prependExecDirToPath(env []string, execDir string) []string {
+	if !filepath.IsAbs(execDir) {
+		return env
+	}
+	out := make([]string, len(env), len(env)+1)
+	copy(out, env)
+	for i, e := range out {
+		if value, ok := strings.CutPrefix(e, "PATH="); ok {
+			// A present-but-empty PATH takes execDir alone: appending the
+			// separator would leave a trailing empty element, which exec
+			// loaders read as the current directory.
+			if value == "" {
+				out[i] = "PATH=" + execDir
+			} else {
+				out[i] = "PATH=" + execDir + string(os.PathListSeparator) + value
+			}
+			return out
+		}
+	}
+	return append(out, "PATH="+execDir)
+}
+
+// resolveImage picks the agent image ref: the --image flag, else
+// $COMPASS_AGENT_IMAGE (the same env compass-runner honors), else the locked
+// GHCR default.
+func resolveImage(flagValue string) string {
+	if flagValue != "" {
+		return flagValue
+	}
+	if env := os.Getenv("COMPASS_AGENT_IMAGE"); env != "" {
+		return env
+	}
+	return defaultAgentImage
+}
+
+// realPreflight builds the preflight seam over the real host-probe adapters,
+// classified at this wiring boundary (see classifyPreflight). The DB probe and
+// the app-side DSN duplicate are gone (§A2 reconciliation 1): under DL-260
+// postgres is a container the stack itself starts, so a pre-`up` reachability
+// probe has no signal on the cold-start path — `up`-Ready is the DB
+// verification. On darwin the machine adapter is wired by T-6; a nil
+// MachineReady here leaves that check absent until then (design §A5).
+func realPreflight(image string) func(ctx context.Context) error {
+	deps := preflight.Deps{
+		GOOS:           runtime.GOOS,
+		PodmanRootless: podmanRootless,
+		PodmanVersion:  podmanVersionAtLeastFloor,
+		ImagePresent:   imagePresent,
+	}
+	params := preflight.Params{AgentImage: image}
+	return func(ctx context.Context) error {
+		return classifyPreflight(deps.Run(ctx, params))
+	}
+}
+
+// classifyPreflight splits the preflight results by severity at the wiring
+// boundary and returns only the FATAL failures folded into one legible error
+// (nil when none are fatal).
+//
+// The split is load-bearing for embedded mode's zero-config cold start. `up`
+// (compass-stack) is what STARTS postgres and PULLS the agent image
+// (internal/stack/adapters/image.go EnsureImage), so on a fresh state dir the
+// image check NECESSARILY fails before `up` has run — gating on it would make the
+// app unable to cold-start, breaking the zero-config charter. And it needs no
+// post-up re-check: `up`-Ready is GetServerInfo answering, which requires
+// migrations against a live postgres AND the runner booting on the pulled image,
+// so reaching Ready transitively verifies both.
+//
+//   - FATAL (host capabilities `up` cannot create): OS, rootless podman, the
+//     podman version floor (delta 4), and — on darwin — the podman machine.
+//   - ADVISORY (`up` ensures it, `up`-Ready verifies it): image — logged at
+//     Warn, never fatal.
+func classifyPreflight(results preflight.Results) error {
+	var fatal preflight.Results
+	for _, r := range results {
+		if r.OK {
+			continue
+		}
+		switch r.Name {
+		case preflight.CheckImage:
+			slog.Warn("preflight: precondition unmet; compass-stack up will ensure it",
+				"check", r.Name, "detail", r.Detail)
+		default:
+			fatal = append(fatal, r)
+		}
+	}
+	return fatal.Err()
+}
diff --git a/go/cmd/compass-app/embedded_path_test.go b/go/cmd/compass-app/embedded_path_test.go
new file mode 100644
index 000000000..003569d0a
--- /dev/null
+++ b/go/cmd/compass-app/embedded_path_test.go
@@ -0,0 +1,64 @@
+//go:build (linux && gtk4) || darwin
+
+package main
+
+// Sidecar PATH threading: prependExecDirToPath prepends the resolved
+// compass-stack's bundle dir to the child PATH so staged sidecars win
+// exec.LookPath, without mutating the caller's env slice.
+
+import (
+	"os"
+	"slices"
+	"testing"
+)
+
+func TestPrependExecDirToPath(t *testing.T) {
+	sep := string(os.PathListSeparator)
+	t.Run("prepends to an existing PATH", func(t *testing.T) {
+		in := []string{"PATH=/usr/bin" + sep + "/bin", "HOME=/h"}
+		got := prependExecDirToPath(in, "/opt/x")
+		want := []string{"PATH=/opt/x" + sep + "/usr/bin" + sep + "/bin", "HOME=/h"}
+		if !slices.Equal(got, want) {
+			t.Fatalf("got %v, want %v", got, want)
+		}
+	})
+	t.Run("appends PATH when none present", func(t *testing.T) {
+		in := []string{"HOME=/h"}
+		got := prependExecDirToPath(in, "/opt/x")
+		want := []string{"HOME=/h", "PATH=/opt/x"}
+		if !slices.Equal(got, want) {
+			t.Fatalf("got %v, want %v", got, want)
+		}
+	})
+	t.Run("empty execDir returns input unchanged", func(t *testing.T) {
+		in := []string{"PATH=/usr/bin", "HOME=/h"}
+		got := prependExecDirToPath(in, "")
+		want := []string{"PATH=/usr/bin", "HOME=/h"}
+		if !slices.Equal(got, want) {
+			t.Fatalf("got %v, want %v", got, want)
+		}
+	})
+	t.Run("relative execDir is a no-op (no cwd on PATH)", func(t *testing.T) {
+		in := []string{"PATH=/usr/bin", "HOME=/h"}
+		got := prependExecDirToPath(in, ".")
+		want := []string{"PATH=/usr/bin", "HOME=/h"}
+		if !slices.Equal(got, want) {
+			t.Fatalf("got %v, want %v", got, want)
+		}
+	})
+	t.Run("present-but-empty PATH takes execDir alone", func(t *testing.T) {
+		in := []string{"PATH=", "HOME=/h"}
+		got := prependExecDirToPath(in, "/opt/x")
+		want := []string{"PATH=/opt/x", "HOME=/h"}
+		if !slices.Equal(got, want) {
+			t.Fatalf("got %v, want %v (a trailing separator would put cwd on PATH)", got, want)
+		}
+	})
+	t.Run("does not mutate the input slice", func(t *testing.T) {
+		in := []string{"PATH=/usr/bin" + sep + "/bin", "HOME=/h"}
+		_ = prependExecDirToPath(in, "/opt/x")
+		if in[0] != "PATH=/usr/bin"+sep+"/bin" {
+			t.Fatalf("input mutated: in[0] = %q", in[0])
+		}
+	})
+}
diff --git a/go/cmd/compass-app/embedded_test.go b/go/cmd/compass-app/embedded_test.go
new file mode 100644
index 000000000..9eb033b09
--- /dev/null
+++ b/go/cmd/compass-app/embedded_test.go
@@ -0,0 +1,679 @@
+//go:build (linux && gtk4) || darwin
+
+package main
+
+// Embedded launch-pipeline gate. The pipeline is exercised through its Go
+// entrypoints with INJECTED effects — no real podman/compass-stack/exec — so
+// mode-select, preflight short-circuit, the exact compass-stack argv, the WhoAmI
+// hop, and the two error paths are all verified deterministically. The one seam
+// wired to a real transport is whoAmIOverUDS, driven against a REAL in-process
+// compass.v1 WhoAmI server over h2c on a Unix socket (mirroring the
+// bridge-service gate's stubServer and internal/runner/e2e_transport_test.go's
+// UDS/connect pattern), so the h2c-UDS dial is proven on the wire it ships on.
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/http"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"connectrpc.com/connect"
+
+	compassv1 "github.com/RigelBuild/compass/go/gen/compass/v1"
+	"github.com/RigelBuild/compass/go/gen/compass/v1/compassv1connect"
+	"github.com/RigelBuild/compass/go/internal/preflight"
+)
+
+const embeddedTestTimeout = 5 * time.Second
+
+// baseParams is a representative resolved launch input the argv/dial assertions
+// key off. The socket is a fixed path (the tests never dial it except in the
+// WhoAmI-server case, which overrides it).
+var baseParams = embeddedParams{
+	socket:   "/run/compass/server.sock",
+	stateDir: "/state/compass",
+	image:    "ghcr.io/rigelbuild/compass-agent:latest",
+}
+
+// stubPipeline builds an embeddedPipeline whose three seams are deterministic
+// stubs, recording what the orchestration invoked. Each seam defaults to a
+// success no-op; a test overrides the ones it drives.
+type recorder struct {
+	preflightCalled bool
+	stackUpCalled   bool
+	stackUpArgs     []string
+	whoAmICalled    bool
+	whoAmISocket    string
+}
+
+func stubPipeline(rec *recorder, preflightErr, stackUpErr, whoAmIErr error, accountID string) embeddedPipeline {
+	return embeddedPipeline{
+		preflight: func(_ context.Context) error {
+			rec.preflightCalled = true
+			return preflightErr
+		},
+		stackUp: func(_ context.Context, args []string) error {
+			rec.stackUpCalled = true
+			rec.stackUpArgs = args
+			return stackUpErr
+		},
+		whoAmI: func(_ context.Context, socket string) (string, error) {
+			rec.whoAmICalled = true
+			rec.whoAmISocket = socket
+			return accountID, whoAmIErr
+		},
+	}
+}
+
+// runEmbeddedStub runs runEmbedded with a recording stackDown seam so the quit
+// controller wiring is observable without a real exec.
+func runEmbeddedStub(
+	t *testing.T, pipeline embeddedPipeline,
+) (string, *quitController, error) {
+	t.Helper()
+	stackDown := func(_ context.Context, _ []string) error { return nil }
+	return runEmbedded(context.Background(), pipeline, baseParams, stackDown)
+}
+
+// TestRunEmbeddedHappyPath: embedded mode runs preflight → stack up → WhoAmI in
+// order, passes the SAME socket to the dial that the argv carries, returns the
+// resolved account id, and builds a quit controller wired to the params. Asserting
+// the argv (up, --socket, --state-dir, --image) is the stack-invocation contract;
+// asserting whoAmISocket == socket is the single-socket invariant (the value
+// passed to --socket IS the value dialed).
+func TestRunEmbeddedHappyPath(t *testing.T) {
+	rec := &recorder{}
+	pipeline := stubPipeline(rec, nil, nil, nil, "acc-42")
+
+	id, quitter, err := runEmbeddedStub(t, pipeline)
+	if err != nil {
+		t.Fatalf("embedded happy path err = %v, want nil", err)
+	}
+	if id != "acc-42" {
+		t.Errorf("account id = %q, want acc-42", id)
+	}
+	if quitter == nil {
+		t.Fatal("embedded mode returned a nil quit controller, want one wired to the stack teardown")
+	}
+	if quitter.params != baseParams {
+		t.Errorf("quit controller params = %+v, want %+v", quitter.params, baseParams)
+	}
+	if !rec.preflightCalled || !rec.stackUpCalled || !rec.whoAmICalled {
+		t.Fatalf("not every stage ran: %+v", rec)
+	}
+	assertArg(t, rec.stackUpArgs, "up")
+	assertArgPair(t, rec.stackUpArgs, "--socket", baseParams.socket)
+	assertArgPair(t, rec.stackUpArgs, "--state-dir", baseParams.stateDir)
+	assertArgPair(t, rec.stackUpArgs, "--image", baseParams.image)
+	if rec.whoAmISocket != baseParams.socket {
+		t.Errorf("WhoAmI dialed %q, want the SAME socket passed to --socket %q",
+			rec.whoAmISocket, baseParams.socket)
+	}
+}
+
+// TestRunEmbeddedPreflightShortCircuits: a preflight failure returns the
+// aggregated legible error VERBATIM, never proceeds to stack-up or WhoAmI, and
+// builds no quit controller. Mutation that reddens it: running the checks after a
+// failure, or reformatting Results.Err's copy.
+func TestRunEmbeddedPreflightShortCircuits(t *testing.T) {
+	rec := &recorder{}
+	preflightErr := errors.New("embedded-mode preflight failed:\n  - windows is not supported")
+	pipeline := stubPipeline(rec, preflightErr, nil, nil, "acc-x")
+
+	id, quitter, err := runEmbeddedStub(t, pipeline)
+	if !errors.Is(err, preflightErr) {
+		t.Fatalf("preflight-fail err = %v, want the preflight error verbatim", err)
+	}
+	if id != "" {
+		t.Errorf("account id = %q, want empty on preflight failure", id)
+	}
+	if quitter != nil {
+		t.Error("preflight failure returned a quit controller, want nil")
+	}
+	if !rec.preflightCalled {
+		t.Error("preflight did not run")
+	}
+	if rec.stackUpCalled || rec.whoAmICalled {
+		t.Errorf("pipeline proceeded past a failed preflight: %+v", rec)
+	}
+}
+
+// TestRunEmbeddedStackUpFails: a non-zero compass-stack up exit is surfaced and
+// the pipeline stops before WhoAmI. The stackUp seam already folds stderr into
+// its error (see TestRunStackUpNonZeroExitSurfacesStderr); here the contract is
+// that runEmbedded propagates it and does not dial.
+func TestRunEmbeddedStackUpFails(t *testing.T) {
+	rec := &recorder{}
+	stackErr := errors.New("compass-stack up failed: exit status 1: postgres refused")
+	pipeline := stubPipeline(rec, nil, stackErr, nil, "acc-x")
+
+	id, quitter, err := runEmbeddedStub(t, pipeline)
+	if !errors.Is(err, stackErr) {
+		t.Fatalf("stack-up-fail err = %v, want the stack-up error", err)
+	}
+	if id != "" {
+		t.Errorf("account id = %q, want empty on stack-up failure", id)
+	}
+	if quitter != nil {
+		t.Error("stack-up failure returned a quit controller, want nil")
+	}
+	if rec.whoAmICalled {
+		t.Error("pipeline dialed WhoAmI after a failed stack-up")
+	}
+}
+
+// TestRunEmbeddedWhoAmIFails: a WhoAmI error is surfaced (wrapped with the socket
+// for context) and no account id is returned. Mutation that reddens it:
+// swallowing the WhoAmI error and returning an empty id as success.
+func TestRunEmbeddedWhoAmIFails(t *testing.T) {
+	rec := &recorder{}
+	whoErr := errors.New("connect: connection refused")
+	pipeline := stubPipeline(rec, nil, nil, whoErr, "")
+
+	id, quitter, err := runEmbeddedStub(t, pipeline)
+	if !errors.Is(err, whoErr) {
+		t.Fatalf("whoami-fail err = %v, want the WhoAmI error wrapped", err)
+	}
+	if id != "" {
+		t.Errorf("account id = %q, want empty on WhoAmI failure", id)
+	}
+	if quitter != nil {
+		t.Error("WhoAmI failure returned a quit controller, want nil")
+	}
+	if !strings.Contains(err.Error(), baseParams.socket) {
+		t.Errorf("WhoAmI error %q does not name the socket for context", err.Error())
+	}
+}
+
+// TestStackUpArgsOmitsCLIDefaultedFlags: the pure argv builder passes ONLY
+// --state-dir/--image/--socket. It omits --database (compass-stack recomputes the
+// identical default DSN from --state-dir) AND the flags the CLI defaults on its
+// own — --postgres-image, --collector-image, --listen — so the CLI's defaults are
+// the contract and the app re-learns nothing the stack already owns (§A2
+// reconciliation 2).
+func TestStackUpArgsOmitsCLIDefaultedFlags(t *testing.T) {
+	args := stackUpArgs(baseParams)
+	for _, flag := range []string{
+		"--database", "--postgres-image", "--collector-image", "--listen",
+	} {
+		if slices.Contains(args, flag) {
+			t.Errorf("argv carries %s, want it omitted so compass-stack owns the default: %v", flag, args)
+		}
+	}
+}
+
+// stubWhoAmIServer implements just the WhoAmI RPC over the generated
+// CompassService handler; every other method returns Unimplemented. accountID is
+// what WhoAmI reports; whoErr, when non-nil, is returned instead.
+type stubWhoAmIServer struct {
+	compassv1connect.UnimplementedCompassServiceHandler
+	accountID string
+	whoErr    error
+}
+
+func (s *stubWhoAmIServer) WhoAmI(
+	_ context.Context, _ *connect.Request[compassv1.WhoAmIRequest],
+) (*connect.Response[compassv1.WhoAmIResponse], error) {
+	if s.whoErr != nil {
+		return nil, s.whoErr
+	}
+	return connect.NewResponse(&compassv1.WhoAmIResponse{AccountId: s.accountID}), nil
+}
+
+// serveWhoAmI stands up a real h2c compass.v1 server on a UDS listener, torn
+// down via t.Cleanup, and returns the socket path whoAmIOverUDS dials.
+func serveWhoAmI(t *testing.T, srv *stubWhoAmIServer) string {
+	t.Helper()
+	socket := filepath.Join(t.TempDir(), "server.sock")
+	ln, err := net.Listen("unix", socket)
+	if err != nil {
+		t.Fatalf("listen unix: %v", err)
+	}
+	_, handler := compassv1connect.NewCompassServiceHandler(srv)
+	p := new(http.Protocols)
+	p.SetUnencryptedHTTP2(true)
+	httpSrv := &http.Server{Handler: handler, Protocols: p}
+	go func() { _ = httpSrv.Serve(ln) }()
+	t.Cleanup(func() {
+		ctx, cancel := context.WithTimeout(context.Background(), embeddedTestTimeout)
+		defer cancel()
+		_ = httpSrv.Shutdown(ctx)
+	})
+	return socket
+}
+
+// TestWhoAmIOverUDSReturnsAccountID: the real h2c-UDS WhoAmI dial returns the
+// server-derived account id. This proves the transport shape (borrowed from
+// health.go) actually speaks to a compass.v1 server over the socket.
+func TestWhoAmIOverUDSReturnsAccountID(t *testing.T) {
+	socket := serveWhoAmI(t, &stubWhoAmIServer{accountID: "acc-served"})
+	ctx, cancel := context.WithTimeout(context.Background(), embeddedTestTimeout)
+	defer cancel()
+
+	id, err := whoAmIOverUDS(ctx, socket)
+	if err != nil {
+		t.Fatalf("whoAmIOverUDS err = %v, want nil", err)
+	}
+	if id != "acc-served" {
+		t.Errorf("account id = %q, want acc-served", id)
+	}
+}
+
+// TestWhoAmIOverUDSSurfacesError: an RPC error from the server surfaces as a
+// non-nil error and an empty id (the dial does not fabricate an identity).
+func TestWhoAmIOverUDSSurfacesError(t *testing.T) {
+	srv := &stubWhoAmIServer{whoErr: connect.NewError(connect.CodeUnavailable, errors.New("starting"))}
+	socket := serveWhoAmI(t, srv)
+	ctx, cancel := context.WithTimeout(context.Background(), embeddedTestTimeout)
+	defer cancel()
+
+	id, err := whoAmIOverUDS(ctx, socket)
+	if err == nil {
+		t.Fatal("whoAmIOverUDS err = nil, want the server's error surfaced")
+	}
+	if id != "" {
+		t.Errorf("account id = %q, want empty on a WhoAmI error", id)
+	}
+}
+
+// TestRunStackUpNonZeroExitSurfacesStderr: the real stackUp seam surfaces a
+// non-zero exit as an error carrying the child's stderr, so the failure copy is
+// legible. Driven with /bin/sh printing to stderr and exiting 1 — no real
+// compass-stack (the argv is not compass-stack's; only the exec+stderr contract
+// is under test here).
+func TestRunStackUpNonZeroExitSurfacesStderr(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), embeddedTestTimeout)
+	defer cancel()
+
+	stackUp := runStackUp("/bin/sh")
+	err := stackUp(ctx, []string{"-c", "echo 'boom on stderr' >&2; exit 1"})
+	if err == nil {
+		t.Fatal("stackUp err = nil, want a non-zero-exit error")
+	}
+	if !strings.Contains(err.Error(), "boom on stderr") {
+		t.Errorf("stackUp error %q does not carry the child stderr", err.Error())
+	}
+}
+
+// TestRunStackUpZeroExitSucceeds: a zero-exit child (fire-and-return) returns
+// nil — the Ready postcondition compass-stack up encodes.
+func TestRunStackUpZeroExitSucceeds(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), embeddedTestTimeout)
+	defer cancel()
+
+	stackUp := runStackUp("/bin/sh")
+	if err := stackUp(ctx, []string{"-c", "exit 0"}); err != nil {
+		t.Fatalf("stackUp on a zero exit err = %v, want nil", err)
+	}
+}
+
+// TestRunStackUpReturnsWhileChildrenLinger is the regression guard for the
+// fire-and-return hang: `compass-stack up` exits 0 once the stack is Ready while
+// its postgres/server/runner children keep running, and those children inherit
+// the exec'd command's stderr. If runStackUp captured stderr into a bytes.Buffer
+// (os/exec's pipe + copy-goroutine path), cmd.Wait would block until the pipe
+// hit EOF — which the lingering children hold open — so Run would hang for the
+// children's whole lifetime. Capturing to a temp *os.File (captureStderr) makes
+// Run return the instant the top-level child exits, regardless of survivors.
+//
+// Driven with /bin/sh that backgrounds a long sleep (a stand-in for the
+// reparented stack children) holding stderr, then exits 0. Pre-fix this blocks
+// for the sleep's lifetime; the fix returns immediately. The assertion is that
+// Run completes well under the sleep — a plain wall-clock bound, but the pre-fix
+// gap is enormous, so it is not flaky. The backgrounded sleep is cleaned up via
+// its own short lifetime; the test spawns nothing it must kill
+// (rule://process-safety — never pkill).
+func TestRunStackUpReturnsWhileChildrenLinger(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), embeddedTestTimeout)
+	defer cancel()
+
+	// A short-lived grandchild that outlives its parent and inherits stderr: the
+	// exact fire-and-return shape of `compass-stack up`. sleep 5 is far longer
+	// than any correct runStackUp (which returns at the parent's exit, ~ms) and
+	// well past the 1s assertion below, yet short enough that a regressed run's
+	// leaked grandchild self-reaps in seconds rather than a minute.
+	stackUp := runStackUp("/bin/sh")
+	start := time.Now()
+	err := stackUp(ctx, []string{"-c", "sleep 5 & exit 0"})
+	elapsed := time.Since(start)
+
+	if err != nil {
+		t.Fatalf("stackUp with a lingering child err = %v, want nil", err)
+	}
+	// Generous bound: the fix returns in single-digit ms, while a regressed Run
+	// blocks until the grandchild exits (~5s) — far past 1s. Anything under a
+	// second proves Run did not wait on the grandchild.
+	if elapsed > time.Second {
+		t.Fatalf("stackUp took %s with a lingering child — Run waited on the inherited stderr pipe (the fire-and-return hang regressed)", elapsed)
+	}
+}
+
+// TestRunStackDownNonZeroExitSurfacesStderr: the real stackDown seam surfaces a
+// non-zero exit as an error carrying the child's stderr, mirroring runStackUp.
+// Driven with /bin/sh printing to stderr and exiting 1 — no real compass-stack
+// (the argv is not compass-stack's; only the exec+stderr contract is tested).
+func TestRunStackDownNonZeroExitSurfacesStderr(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), embeddedTestTimeout)
+	defer cancel()
+
+	stackDown := runStackDown("/bin/sh")
+	err := stackDown(ctx, []string{"-c", "echo 'down boom on stderr' >&2; exit 1"})
+	if err == nil {
+		t.Fatal("stackDown err = nil, want a non-zero-exit error")
+	}
+	if !strings.Contains(err.Error(), "down boom on stderr") {
+		t.Errorf("stackDown error %q does not carry the child stderr", err.Error())
+	}
+}
+
+// TestRunStackDownZeroExitSucceeds: a zero-exit child (a clean teardown) returns
+// nil — the postcondition compass-stack down encodes.
+func TestRunStackDownZeroExitSucceeds(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), embeddedTestTimeout)
+	defer cancel()
+
+	stackDown := runStackDown("/bin/sh")
+	if err := stackDown(ctx, []string{"-c", "exit 0"}); err != nil {
+		t.Fatalf("stackDown on a zero exit err = %v, want nil", err)
+	}
+}
+
+// classifyDeps returns a preflight.Deps whose every injected effect passes (host
+// GOOS linux) — mirroring preflight_test.go's okDeps. Tests override individual
+// fields to drive one failing check at a time through classifyPreflight.
+func classifyDeps() preflight.Deps {
+	return preflight.Deps{
+		GOOS:           "linux",
+		PodmanRootless: func(context.Context) error { return nil },
+		PodmanVersion:  func(context.Context) error { return nil },
+		ImagePresent:   func(context.Context, string) error { return nil },
+	}
+}
+
+var classifyParams = preflight.Params{
+	AgentImage: "ghcr.io/rigelbuild/compass-agent:latest",
+}
+
+// classify runs deps and folds through the boundary classifier, the exact path
+// realPreflight uses.
+func classify(t *testing.T, deps preflight.Deps) error {
+	t.Helper()
+	return classifyPreflight(deps.Run(context.Background(), classifyParams))
+}
+
+// TestClassifyPreflightAllPass: no failing check → nil.
+func TestClassifyPreflightAllPass(t *testing.T) {
+	if err := classify(t, classifyDeps()); err != nil {
+		t.Fatalf("all-pass classify err = %v, want nil", err)
+	}
+}
+
+// TestClassifyPreflightHostCapUnmetIsFatal: each host-capability check (OS,
+// podman, podman-version) that `up` CANNOT create is fatal — classifyPreflight
+// returns non-nil, naming the failed check's copy.
+func TestClassifyPreflightHostCapUnmetIsFatal(t *testing.T) {
+	podmanErr := errors.New("no rootless podman here")
+	versionErr := errors.New("podman 4.3 or newer is required")
+	cases := map[string]struct {
+		mutate func(*preflight.Deps)
+		want   string
+	}{
+		"os": {
+			mutate: func(d *preflight.Deps) { d.GOOS = "windows" },
+			want:   "windows",
+		},
+		"podman": {
+			mutate: func(d *preflight.Deps) {
+				d.PodmanRootless = func(context.Context) error { return podmanErr }
+			},
+			want: podmanErr.Error(),
+		},
+		"podman-version": {
+			mutate: func(d *preflight.Deps) {
+				d.PodmanVersion = func(context.Context) error { return versionErr }
+			},
+			want: versionErr.Error(),
+		},
+	}
+	for name, tc := range cases {
+		t.Run(name, func(t *testing.T) {
+			deps := classifyDeps()
+			tc.mutate(&deps)
+			err := classify(t, deps)
+			if err == nil {
+				t.Fatalf("%s unmet: classify err = nil, want a fatal error", name)
+			}
+			if !strings.Contains(err.Error(), tc.want) {
+				t.Errorf("%s fatal error %q does not carry %q", name, err.Error(), tc.want)
+			}
+		})
+	}
+}
+
+// TestClassifyPreflightImageUnmetIsAdvisory: the load-bearing cold-start case.
+// When only the image is unmet (every host capability OK), classifyPreflight
+// returns NIL — `up` will pull the image and `up`-Ready verifies it. Gating on it
+// here would make the app unable to cold-start on a fresh state dir.
+func TestClassifyPreflightImageUnmetIsAdvisory(t *testing.T) {
+	deps := classifyDeps()
+	deps.ImagePresent = func(context.Context, string) error {
+		return errors.New("agent image absent locally")
+	}
+	if err := classify(t, deps); err != nil {
+		t.Fatalf("image-only unmet: classify err = %v, want nil (advisory, not fatal)", err)
+	}
+}
+
+// TestClassifyPreflightHostCapFatalEvenWithAdvisoryUnmet: a fatal host-cap
+// failure is still fatal when the image is ALSO unmet — the advisory check never
+// masks a genuine host-capability gap, and no advisory copy leaks into the fatal
+// fold.
+func TestClassifyPreflightHostCapFatalEvenWithAdvisoryUnmet(t *testing.T) {
+	deps := classifyDeps()
+	deps.PodmanRootless = func(context.Context) error { return errors.New("no podman") }
+	deps.ImagePresent = func(context.Context, string) error { return errors.New("no image") }
+	err := classify(t, deps)
+	if err == nil {
+		t.Fatal("classify err = nil, want fatal (podman unmet) despite an advisory image failure")
+	}
+	if !strings.Contains(err.Error(), "no podman") {
+		t.Errorf("fatal error %q does not carry the podman failure", err.Error())
+	}
+	if strings.Contains(err.Error(), "no image") {
+		t.Errorf("fatal error %q leaked an advisory failure into the fatal fold", err.Error())
+	}
+}
+
+// TestRunStackUpDeadlineExceededNamesBringUpWindow: when the child fails because
+// the context deadline was exceeded, the error names the bring-up window (the
+// likely cause) rather than surfacing a bare deadline error. Driven with an
+// already-past deadline against a real binary so the classification is
+// deterministic (no wall-clock wait).
+func TestRunStackUpDeadlineExceededNamesBringUpWindow(t *testing.T) {
+	ctx, cancel := context.WithDeadline(context.Background(), time.Now().Add(-time.Second))
+	defer cancel()
+
+	stackUp := runStackUp("/bin/sh")
+	err := stackUp(ctx, []string{"-c", "exit 0"})
+	if err == nil {
+		t.Fatal("stackUp err = nil, want a deadline-exceeded error")
+	}
+	if !strings.Contains(err.Error(), "bring-up window") {
+		t.Errorf("stackUp error %q does not name the bring-up window", err.Error())
+	}
+}
+
+// TestWhoAmIOverUDSRejectsEmptyAccountID: a SUCCESSFUL WhoAmI that reports an
+// empty account id is rejected (non-nil error, empty id) rather than resolving
+// an empty identity downstream.
+func TestWhoAmIOverUDSRejectsEmptyAccountID(t *testing.T) {
+	socket := serveWhoAmI(t, &stubWhoAmIServer{accountID: ""})
+	ctx, cancel := context.WithTimeout(context.Background(), embeddedTestTimeout)
+	defer cancel()
+
+	id, err := whoAmIOverUDS(ctx, socket)
+	if err == nil {
+		t.Fatal("whoAmIOverUDS err = nil, want an error on an empty account id")
+	}
+	if id != "" {
+		t.Errorf("account id = %q, want empty when WhoAmI returns an empty id", id)
+	}
+}
+
+// TestResolveStackBin: flag wins, then $COMPASS_STACK_BIN, then a not-found error
+// that names every place it looked. The executable-sibling branch is not covered
+// because os.Executable can't be overridden without mocking; the other three
+// legs are deterministic.
+func TestResolveStackBin(t *testing.T) {
+	t.Run("flag wins", func(t *testing.T) {
+		t.Setenv("COMPASS_STACK_BIN", "/env/compass-stack")
+		got, err := resolveStackBin("/flag/compass-stack")
+		if err != nil {
+			t.Fatalf("err = %v, want nil", err)
+		}
+		if got != "/flag/compass-stack" {
+			t.Errorf("got %q, want the flag value", got)
+		}
+	})
+	t.Run("env wins over PATH", func(t *testing.T) {
+		t.Setenv("COMPASS_STACK_BIN", "/env/compass-stack")
+		got, err := resolveStackBin("")
+		if err != nil {
+			t.Fatalf("err = %v, want nil", err)
+		}
+		if got != "/env/compass-stack" {
+			t.Errorf("got %q, want the env value", got)
+		}
+	})
+	t.Run("not found names all four locations", func(t *testing.T) {
+		t.Setenv("COMPASS_STACK_BIN", "")
+		t.Setenv("PATH", "")
+		_, err := resolveStackBin("")
+		if err == nil {
+			t.Fatal("err = nil, want a not-found error")
+		}
+		for _, want := range []string{"--compass-stack", "$COMPASS_STACK_BIN", "$PATH", "beside"} {
+			if !strings.Contains(err.Error(), want) {
+				t.Errorf("not-found error %q does not name %q", err.Error(), want)
+			}
+		}
+	})
+}
+
+// TestResolveSocket: flag wins, then $COMPASS_SOCKET, then an ABSOLUTE
+// $XDG_RUNTIME_DIR/compass/server.sock. A RELATIVE $XDG_RUNTIME_DIR is treated as
+// unset and falls through to $HOME/.compass/server.sock — the determinism guard.
+func TestResolveSocket(t *testing.T) {
+	t.Run("flag wins", func(t *testing.T) {
+		t.Setenv("COMPASS_SOCKET", "/env/server.sock")
+		if got := resolveSocket("/flag/server.sock"); got != "/flag/server.sock" {
+			t.Errorf("got %q, want the flag value", got)
+		}
+	})
+	t.Run("env wins", func(t *testing.T) {
+		t.Setenv("COMPASS_SOCKET", "/env/server.sock")
+		t.Setenv("XDG_RUNTIME_DIR", "/xdg/run")
+		if got := resolveSocket(""); got != "/env/server.sock" {
+			t.Errorf("got %q, want the env value", got)
+		}
+	})
+	t.Run("absolute XDG_RUNTIME_DIR", func(t *testing.T) {
+		t.Setenv("COMPASS_SOCKET", "")
+		xdg := t.TempDir()
+		t.Setenv("XDG_RUNTIME_DIR", xdg)
+		if got := resolveSocket(""); got != filepath.Join(xdg, "compass", "server.sock") {
+			t.Errorf("got %q, want %q", got, filepath.Join(xdg, "compass", "server.sock"))
+		}
+	})
+	t.Run("relative XDG_RUNTIME_DIR falls through to HOME/.compass", func(t *testing.T) {
+		t.Setenv("COMPASS_SOCKET", "")
+		t.Setenv("XDG_RUNTIME_DIR", "rel/run")
+		home := t.TempDir()
+		t.Setenv("HOME", home)
+		if got := resolveSocket(""); got != filepath.Join(home, ".compass", "server.sock") {
+			t.Errorf("got %q, want %q (relative XDG_RUNTIME_DIR must fall through)", got, filepath.Join(home, ".compass", "server.sock"))
+		}
+	})
+}
+
+// TestResolveImage: flag wins, then $COMPASS_AGENT_IMAGE, then the locked GHCR
+// default.
+func TestResolveImage(t *testing.T) {
+	t.Run("flag wins", func(t *testing.T) {
+		t.Setenv("COMPASS_AGENT_IMAGE", "env/image:tag")
+		if got := resolveImage("flag/image:tag"); got != "flag/image:tag" {
+			t.Errorf("got %q, want the flag value", got)
+		}
+	})
+	t.Run("env wins", func(t *testing.T) {
+		t.Setenv("COMPASS_AGENT_IMAGE", "env/image:tag")
+		if got := resolveImage(""); got != "env/image:tag" {
+			t.Errorf("got %q, want the env value", got)
+		}
+	})
+	t.Run("default", func(t *testing.T) {
+		t.Setenv("COMPASS_AGENT_IMAGE", "")
+		if got := resolveImage(""); got != defaultAgentImage {
+			t.Errorf("got %q, want defaultAgentImage %q", got, defaultAgentImage)
+		}
+	})
+	// Pin the default to the canonical live GHCR owner. This guards the value
+	// itself (not just that resolveImage returns it): the old
+	// ghcr.io/rigelbuild/compass-agent owner 403s post org-rename, so a
+	// shipped app that fell back to it could not pull its agent image (RIG-1967).
+	t.Run("default is the canonical rigelbuild ref", func(t *testing.T) {
+		if defaultAgentImage != "ghcr.io/rigelbuild/compass-agent:latest" {
+			t.Errorf("defaultAgentImage = %q, want the canonical rigelbuild ref", defaultAgentImage)
+		}
+	})
+}
+
+// TestResolveMode: flag wins, then $COMPASS_APP_MODE, then "" (no override).
+func TestResolveMode(t *testing.T) {
+	t.Run("flag wins", func(t *testing.T) {
+		t.Setenv("COMPASS_APP_MODE", "client")
+		if got := resolveMode("embedded"); got != "embedded" {
+			t.Errorf("got %q, want the flag value", got)
+		}
+	})
+	t.Run("env wins", func(t *testing.T) {
+		t.Setenv("COMPASS_APP_MODE", "client")
+		if got := resolveMode(""); got != "client" {
+			t.Errorf("got %q, want the env value", got)
+		}
+	})
+	t.Run("both empty", func(t *testing.T) {
+		t.Setenv("COMPASS_APP_MODE", "")
+		if got := resolveMode(""); got != "" {
+			t.Errorf("got %q, want empty (no override)", got)
+		}
+	})
+}
+
+// assertArg fails unless want appears as a token in args.
+func assertArg(t *testing.T, args []string, want string) {
+	t.Helper()
+	if !slices.Contains(args, want) {
+		t.Errorf("argv %v missing token %q", args, want)
+	}
+}
+
+// assertArgPair fails unless flag is immediately followed by value in args.
+func assertArgPair(t *testing.T, args []string, flag, value string) {
+	t.Helper()
+	for i, a := range args {
+		if a == flag {
+			if i+1 < len(args) && args[i+1] == value {
+				return
+			}
+			t.Errorf("argv %v: flag %q not followed by %q", args, flag, value)
+			return
+		}
+	}
+	t.Errorf("argv %v missing flag %q", args, flag)
+}
diff --git a/go/cmd/compass-app/lifecycle.go b/go/cmd/compass-app/lifecycle.go
new file mode 100644
index 000000000..32af11468
--- /dev/null
+++ b/go/cmd/compass-app/lifecycle.go
@@ -0,0 +1,74 @@
+//go:build (linux && gtk4) || darwin
+
+// The embedded-mode app QUIT lifecycle. Two behaviors sit on the frozen DL-108
+// contract:
+//
+//   - Linger (the DEFAULT, and PASSIVE): on a plain app quit (window close, OS
+//     quit) the app process exits while the already-detached stack children
+//     (postgres + server + runner, spawned by `compass-stack up` in their OWN
+//     processes) KEEP running. The app does nothing to the stack on a plain
+//     quit — relaunch re-attaches (compass-stack up attaches when a live server
+//     answers). So linger needs NO code here; it is the absence of a teardown on
+//     plain quit.
+//   - Explicit "Quit and stop stack": a distinct user action that runs
+//     `compass-stack down` (attach → SIGTERM the child tree → wait the server
+//     drain → release the lock) and THEN quits the app. That action is this
+//     file's quitController. The container-aware teardown (DL-262 pgid v2
+//     DownDetached) is the compass-stack CLI's; the app only execs the binary.
+//
+// The orchestration is decoupled from Wails and from exec behind small injected
+// seams (stackDown, quit), so the quit sequence — build the argv, run down under
+// a bounded context, quit regardless of the down outcome — is unit-testable
+// without a real stack or a display.
+package main
+
+import (
+	"context"
+	"log/slog"
+	"time"
+)
+
+// stackDownTimeout bounds the explicit teardown (compass-stack down: attach,
+// SIGTERM the child tree, wait the server drain, release the lock). The bring-up
+// context is already cancelled by the time the window is open, so
+// stopStackAndQuit roots a FRESH bounded context off the caller's rather than
+// reusing it.
+const stackDownTimeout = 60 * time.Second
+
+// quitController is the explicit "Quit and stop stack" orchestration over its
+// injected effects. It holds the teardown seam (stackDown), the argv inputs
+// (params, resolved once in run()), the app-quit indirection (quit, wired to
+// app.Quit), the teardown deadline (timeout), and a logger. A test supplies a
+// recording stackDown stub and a counting quit, so the quit sequence is
+// verified with no real exec and no display.
+type quitController struct {
+	stackDown func(ctx context.Context, args []string) error
+	params    embeddedParams
+	quit      func()
+	timeout   time.Duration
+	logger    *slog.Logger
+}
+
+// stopStackAndQuit runs the explicit teardown and then quits the app. It derives
+// a FRESH bounded context off the caller's (the bring-up context is already
+// cancelled by the time the window is open), builds the `compass-stack down`
+// argv, and runs the injected stackDown seam under that deadline.
+//
+// Quit-anyway on a failed down (OQ-6): if `compass-stack down` fails, the app
+// STILL quits. Rationale: the user's explicit intent is to quit, trapping them
+// in a live window because teardown hiccuped is worse, and a lingering stack is
+// the SAFE failure (it is the plain-quit default anyway).
+func (c quitController) stopStackAndQuit(ctx context.Context) {
+	logger := c.logger
+	if logger == nil {
+		logger = slog.Default()
+	}
+	downCtx, cancel := context.WithTimeout(ctx, c.timeout)
+	defer cancel()
+	if err := c.stackDown(downCtx, stackDownArgs(c.params)); err != nil {
+		// Quit-anyway (OQ-6): log and fall through to quit.
+		logger.Error("stopping the embedded stack failed; quitting anyway "+
+			"(the stack lingers, which is the safe plain-quit default)", "error", err)
+	}
+	c.quit()
+}
diff --git a/go/cmd/compass-app/lifecycle_test.go b/go/cmd/compass-app/lifecycle_test.go
new file mode 100644
index 000000000..6ca66671c
--- /dev/null
+++ b/go/cmd/compass-app/lifecycle_test.go
@@ -0,0 +1,109 @@
+//go:build (linux && gtk4) || darwin
+
+package main
+
+// Quit-lifecycle gate. The explicit "Quit and stop stack" orchestration is
+// exercised through quitController with INJECTED seams — a recording stackDown
+// stub and a counting quit — so the down argv, the happy-path quit, and the
+// quit-anyway-on-failure default (OQ-6) are all verified deterministically, with
+// no real compass-stack exec and no display.
+
+import (
+	"context"
+	"errors"
+	"slices"
+	"testing"
+	"time"
+)
+
+// TestStackDownArgs: the pure argv builder emits the exact `compass-stack down`
+// invocation (down + --state-dir + --image + --socket) and OMITS both --database
+// (compass-stack recomputes the default DSN from --state-dir) and --linger (down
+// is not lingerable).
+func TestStackDownArgs(t *testing.T) {
+	args := stackDownArgs(baseParams)
+
+	want := []string{
+		"down",
+		"--state-dir", baseParams.stateDir,
+		"--image", baseParams.image,
+		"--socket", baseParams.socket,
+	}
+	if !slices.Equal(args, want) {
+		t.Errorf("stackDownArgs = %v, want %v", args, want)
+	}
+	if slices.Contains(args, "--database") {
+		t.Errorf("argv carries --database, want it omitted (compass-stack defaults the DSN): %v", args)
+	}
+	if slices.Contains(args, "--linger") {
+		t.Errorf("argv carries --linger, want it omitted (down is not lingerable): %v", args)
+	}
+}
+
+// TestStopStackAndQuitHappyPath: a successful teardown runs down with EXACTLY
+// the stackDownArgs(params) argv and then quits the app exactly once.
+func TestStopStackAndQuitHappyPath(t *testing.T) {
+	var gotArgs []string
+	quitCount := 0
+	c := quitController{
+		stackDown: func(_ context.Context, args []string) error {
+			gotArgs = args
+			return nil
+		},
+		params:  baseParams,
+		quit:    func() { quitCount++ },
+		timeout: stackDownTimeout,
+	}
+
+	c.stopStackAndQuit(context.Background())
+
+	if want := stackDownArgs(baseParams); !slices.Equal(gotArgs, want) {
+		t.Errorf("stackDown argv = %v, want %v", gotArgs, want)
+	}
+	if quitCount != 1 {
+		t.Errorf("quit called %d times, want exactly 1", quitCount)
+	}
+}
+
+// TestStopStackAndQuitQuitsAnywayOnDownFailure: the OQ-6 default. When
+// compass-stack down FAILS, the app STILL quits exactly once (a lingering stack
+// is the safe failure; trapping the user in a live window is worse).
+func TestStopStackAndQuitQuitsAnywayOnDownFailure(t *testing.T) {
+	quitCount := 0
+	c := quitController{
+		stackDown: func(_ context.Context, _ []string) error {
+			return errors.New("down boom")
+		},
+		params:  baseParams,
+		quit:    func() { quitCount++ },
+		timeout: stackDownTimeout,
+	}
+
+	c.stopStackAndQuit(context.Background())
+
+	if quitCount != 1 {
+		t.Errorf("quit called %d times on a down failure, want exactly 1 (quit-anyway default)", quitCount)
+	}
+}
+
+// TestStopStackAndQuitBoundsTheDownContext: stopStackAndQuit derives a bounded
+// context off the caller's, so the injected down seam sees a deadline rather
+// than an unbounded context.
+func TestStopStackAndQuitBoundsTheDownContext(t *testing.T) {
+	hadDeadline := false
+	c := quitController{
+		stackDown: func(ctx context.Context, _ []string) error {
+			_, hadDeadline = ctx.Deadline()
+			return nil
+		},
+		params:  baseParams,
+		quit:    func() {},
+		timeout: 30 * time.Second,
+	}
+
+	c.stopStackAndQuit(context.Background())
+
+	if !hadDeadline {
+		t.Error("down context had no deadline, want it bounded by timeout")
+	}
+}
diff --git a/go/cmd/compass-app/main.go b/go/cmd/compass-app/main.go
index 9a0fb6f47..55abb513d 100644
--- a/go/cmd/compass-app/main.go
+++ b/go/cmd/compass-app/main.go
@@ -3,14 +3,15 @@
 // Command compass-app is the Compass native desktop shell: a Wails v3
 // application that opens one window loading the prebuilt SolidJS UI (apps/ui
 // dist) and exposes the compass_rpc / compass_rpc_cancel IPC bridge to it,
-// backed by the bridge pump over the client's TLS connection to a headless
-// Compass stack.
+// backed by the bridge pump.
 //
-// The app is a native CLIENT only (RIG-2554): it dials a headless Compass stack
-// over the authenticated TLS door (client.go, runClient). Embedded mode — an
-// in-process stack supervisor — was retired; the app no longer spawns, monitors,
-// or tears down a stack. The headless stack is brought up out of band on a
-// dedicated machine, and app.toml's server_url points the app at it.
+// The app runs in one of two modes (appconfig, resolved at launch):
+//   - EMBEDDED: it supervises a private stack in-process via the compass-stack
+//     CLI (embedded.go: preflight → compass-stack up → WhoAmI), then dials the
+//     stack's Unix socket over h2c. This is the zero-config self-host path.
+//   - CLIENT: it dials a headless Compass stack over the authenticated TLS door
+//     (client.go, runClient); the stack is brought up out of band on a dedicated
+//     machine, and app.toml's server_url points the app at it.
 //
 // Assets: the dist lives at repo apps/ui/dist, OUTSIDE this Go package's
 // directory subtree, so //go:embed cannot reach it (embed forbids ".." patterns
@@ -21,18 +22,30 @@
 package main
 
 import (
+	"context"
 	"encoding/json"
 	"flag"
 	"fmt"
 	"log/slog"
 	"os"
 	"path/filepath"
+	"time"
 
 	"github.com/RigelBuild/compass/go/internal/appconfig"
+	"github.com/RigelBuild/compass/go/internal/bridge"
 	"github.com/wailsapp/wails/v3/pkg/application"
 	"github.com/wailsapp/wails/v3/pkg/events"
 )
 
+// bringUpTimeout bounds the whole embedded bring-up (preflight + compass-stack
+// up + WhoAmI) as a backstop against a wedged launch; app.Run() itself is not
+// context-bound. It is generous because a cold first run pulls THREE images —
+// the agent image from GHCR plus the stock postgres and collector images
+// (DL-260) — before the stack reaches Ready, so the window covers three
+// sequential registry pulls, not one. (darwin machine-init time is A5/T-6's
+// concern and not folded in here.)
+const bringUpTimeout = 180 * time.Second
+
 func main() {
 	if err := run(); err != nil {
 		slog.Error("compass-app exited with an error", "error", err)
@@ -45,24 +58,41 @@ func run() error {
 		return err
 	}
 
+	socketFlag := flag.String("socket", "",
+		"Unix socket the Compass stack serves compass.v1 on. Defaults to "+
+			"$COMPASS_SOCKET, then $XDG_RUNTIME_DIR/compass/server.sock. In "+
+			"embedded mode the supervised stack serves it; in client mode the "+
+			"remote is dialed over TLS instead.")
 	assetsFlag := flag.String("assets", "",
 		"Directory of the prebuilt apps/ui dist to serve. Defaults to "+
 			"$COMPASS_ASSETS_DIR, then the dist for the executable's layout: "+
 			"a .app's Contents/Resources/dist, else a 'dist' beside the executable.")
 	stateDirFlag := flag.String("state-dir", "",
-		"App state directory (the client tokenstore lives here). Defaults to "+
-			"$COMPASS_STATE_DIR, then $XDG_STATE_HOME/compass, then $HOME/.compass.")
+		"App state directory (the embedded stack + client tokenstore live here). "+
+			"Defaults to $COMPASS_STATE_DIR, then $XDG_STATE_HOME/compass, then "+
+			"$HOME/.compass.")
+	modeFlag := flag.String("mode", "",
+		"Operating mode override (embedded|client). Defaults to $COMPASS_APP_MODE, "+
+			"then app.toml, then embedded.")
+	stackBinFlag := flag.String("compass-stack", "",
+		"Path to the compass-stack binary the embedded stack is supervised with. "+
+			"Defaults to $COMPASS_STACK_BIN, then a compass-stack sibling of this "+
+			"executable, then compass-stack on $PATH.")
+	imageFlag := flag.String("image", "",
+		"Agent container image ref for the embedded stack. Defaults to "+
+			"$COMPASS_AGENT_IMAGE, then "+defaultAgentImage+".")
 	flag.Parse()
 
+	socket := resolveSocket(*socketFlag)
 	assetsDir := resolveAssetsDir(*assetsFlag)
 
-	cfg, err := appconfig.Load(os.Getenv("XDG_CONFIG_HOME"), os.Getenv("HOME"))
+	cfg, err := appconfig.Load(os.Getenv("XDG_CONFIG_HOME"), os.Getenv("HOME"), resolveMode(*modeFlag))
 	if err != nil {
 		return err
 	}
 
 	stateDir := resolveStateDir(*stateDirFlag)
-	svc, err := launch(cfg, stateDir)
+	svc, quitter, err := launch(cfg, socket, stateDir, resolveImage(*imageFlag), stackBinFlag)
 	if err != nil {
 		return err
 	}
@@ -95,16 +125,30 @@ func run() error {
 		}
 	})
 
-	startupJS, err := shellStartupJS(cfg.ServerURL)
+	startupJS, err := shellStartupJS(cfg.Mode.String(), cfg.ServerURL)
 	if err != nil {
 		return err
 	}
 
-	// The "Window"/"New Window" item opens an additional Bridge window and is
-	// always available. Plain quit (window close, OS quit) has no stack teardown:
-	// the app is a client and owns no stack. (The window-set persist hook above
-	// touches only the state-dir window list.)
+	// The menu is installed in both modes. The "Window"/"New Window" item opens
+	// an additional Bridge window and is always available. The embedded-only
+	// "File"/"Quit and stop stack" item (DL-108) is gated on quitter: client
+	// mode has no stack to stop. Plain quit (window close, OS quit) LINGERS by
+	// default — the stack children stay running and the app does nothing to them
+	// (relaunch re-attaches), so there is deliberately no OnShutdown *stack*
+	// teardown here. (The window-set persist hook above is unrelated: it touches
+	// only the state-dir window list, never the stack.)
 	menu := application.NewMenu()
+	if quitter != nil {
+		quitter.quit = app.Quit
+		fileMenu := menu.AddSubmenu("File")
+		fileMenu.Add("Quit and stop stack").OnClick(func(_ *application.Context) {
+			// A UI-event callback has no inherited context.Context, so this is
+			// the legitimate main-entrypoint root; stopStackAndQuit derives its
+			// bounded teardown deadline from it.
+			quitter.stopStackAndQuit(context.Background())
+		})
+	}
 	windowMenu := menu.AddSubmenu("Window")
 	windowMenu.Add("New Window").OnClick(func(_ *application.Context) {
 		name := nextWindowName(app)
@@ -121,7 +165,7 @@ func run() error {
 		newAppWindow(app, svc, name, "Compass", startupJS)
 	}
 
-	slog.Info("compass-app starting", "mode", cfg.Mode, "assets", assetsDir, "version", version)
+	slog.Info("compass-app starting", "mode", cfg.Mode, "socket", socket, "assets", assetsDir, "version", version)
 	return app.Run()
 }
 
@@ -187,36 +231,73 @@ func firstFreeName(base string, exists func(string) bool) string {
 	}
 }
 
-// launch wires the native-client bridge service (design §T5.6). Embedded mode —
-// the in-process stack supervisor — was retired in RIG-2554, so launch is a thin
-// wrapper over runClient: there is no stack to spawn, monitor, or tear down, and
-// no quit controller. The Mode was validated to client by appconfig.Load; the
-// default arm rejects any other resolved Mode legibly rather than dialing a
-// half-configured target.
-func launch(cfg appconfig.Config, stateDir string) (*bridgeService, error) {
+// launch dispatches the resolved mode into the embedded or client launch arm and
+// returns the wired bridge service plus (embedded only) the quit controller.
+// Only the embedded arm resolves the compass-stack binary and builds the quit
+// controller; a client-only install has neither a compass-stack binary nor a
+// stack to stop, so those effects must not gate a client launch (design §T5.6).
+func launch(
+	cfg appconfig.Config, socket, stateDir, image string, stackBinFlag *string,
+) (*bridgeService, *quitController, error) {
 	switch cfg.Mode {
+	case appconfig.ModeEmbedded:
+		stackBin, err := resolveStackBin(*stackBinFlag)
+		if err != nil {
+			return nil, nil, err
+		}
+		pipeline := embeddedPipeline{
+			preflight: realPreflight(image),
+			stackUp:   runStackUp(stackBin),
+			whoAmI:    whoAmIOverUDS,
+		}
+		params := embeddedParams{socket: socket, stateDir: stateDir, image: image}
+
+		// The embedded bring-up (preflight → stack up → WhoAmI) runs BEFORE the
+		// window opens, under a bounded bring-up context. run() is the process
+		// root (called directly by main), so context.Background() here is the
+		// sanctioned process-root context, not a mid-tree re-root; the bring-up
+		// window is derived from it.
+		bringUpCtx, cancel := context.WithTimeout(context.Background(), bringUpTimeout)
+		accountID, quitter, err := runEmbedded(bringUpCtx, pipeline, params, runStackDown(stackBin))
+		cancel()
+		if err != nil {
+			return nil, nil, err
+		}
+
+		svc := newBridgeService(bridge.NewPump(bridge.NewUnixTarget(socket)), nil, nil, nil)
+		svc.accountID = accountID
+		return svc, quitter, nil
 	case appconfig.ModeClient:
 		// Client mode opens the window immediately: no pre-window probe (the
 		// single auto-connect is the UI's boot-time shellConnect(""), T5.5).
-		return runClient(cfg, stateDir)
+		svc, err := runClient(cfg, stateDir)
+		if err != nil {
+			return nil, nil, err
+		}
+		return svc, nil, nil
 	default:
-		return nil, fmt.Errorf("unknown app mode %v", cfg.Mode)
+		return nil, nil, fmt.Errorf("unknown app mode %v", cfg.Mode)
 	}
 }
 
 // shellStartupJS builds the OQ-8 startup script the webview loads before the app
-// bundle. It assigns window.__COMPASS_MODE__ ("client" — the app is a native
-// client only, RIG-2554) and window.__COMPASS_SERVER_URL__. The server URL is
-// JSON-encoded (encoding/json) so a hostile URL containing quotes/backslashes/
-// </script> cannot break out of the script or inject — the encoded form is
-// always a valid JS string literal.
-func shellStartupJS(serverURL string) (string, error) {
-	urlJSON, err := json.Marshal(serverURL)
+// bundle. It assigns window.__COMPASS_MODE__ in both modes and, in client mode,
+// window.__COMPASS_SERVER_URL__. Each value is JSON-encoded (encoding/json) so a
+// hostile server URL containing quotes/backslashes/</script> cannot break out of
+// the script or inject — the encoded form is always a valid JS string literal.
+func shellStartupJS(mode, serverURL string) (string, error) {
+	modeJSON, err := json.Marshal(mode)
 	if err != nil {
-		return "", fmt.Errorf("encoding startup server-url global: %w", err)
+		return "", fmt.Errorf("encoding startup mode global: %w", err)
+	}
+	js := "window.__COMPASS_MODE__=" + string(modeJSON) + ";"
+	if mode == appconfig.ModeClient.String() {
+		urlJSON, err := json.Marshal(serverURL)
+		if err != nil {
+			return "", fmt.Errorf("encoding startup server-url global: %w", err)
+		}
+		js += "window.__COMPASS_SERVER_URL__=" + string(urlJSON) + ";"
 	}
-	js := `window.__COMPASS_MODE__="client";` +
-		"window.__COMPASS_SERVER_URL__=" + string(urlJSON) + ";"
 	return js, nil
 }
 
@@ -238,6 +319,36 @@ func resolveAssetsDir(flagValue string) string {
 	return "dist"
 }
 
+// resolveMode resolves the --mode/$COMPASS_APP_MODE override to feed
+// appconfig.Load. An empty flag falls back to the env; both empty is "no
+// override" (Load then uses app.toml, else the embedded default).
+func resolveMode(flagValue string) string {
+	if flagValue != "" {
+		return flagValue
+	}
+	return os.Getenv("COMPASS_APP_MODE")
+}
+
+// resolveSocket picks the stack socket to serve/dial: the --socket flag, else
+// $COMPASS_SOCKET, else $XDG_RUNTIME_DIR/compass/server.sock (the server
+// default, go/server/socket.go DefaultSocketPath). A relative XDG_RUNTIME_DIR is
+// treated as unset, matching the server, so the fallback is deterministic. In
+// embedded mode the supervised stack serves this socket (passed as --socket and
+// dialed for WhoAmI); the client arm dials the remote over TLS instead and never
+// touches it.
+func resolveSocket(flagValue string) string {
+	if flagValue != "" {
+		return flagValue
+	}
+	if env := os.Getenv("COMPASS_SOCKET"); env != "" {
+		return env
+	}
+	if runtimeDir := os.Getenv("XDG_RUNTIME_DIR"); filepath.IsAbs(runtimeDir) {
+		return filepath.Join(runtimeDir, "compass", "server.sock")
+	}
+	return filepath.Join(os.Getenv("HOME"), ".compass", "server.sock")
+}
+
 // distDirForExecutable resolves the dist directory for a given executable path.
 // A macOS .app stages the binary at Contents/MacOS/compass-app and the UI dist
 // at Contents/Resources/dist (the macos-bundle tool, compass-distribution T3),
diff --git a/go/cmd/compass-app/preflight_adapters.go b/go/cmd/compass-app/preflight_adapters.go
new file mode 100644
index 000000000..dd1bff595
--- /dev/null
+++ b/go/cmd/compass-app/preflight_adapters.go
@@ -0,0 +1,61 @@
+//go:build (linux && gtk4) || darwin
+
+// The real host-preflight adapters for embedded mode: each is one genuine
+// external effect the preflight core (go/internal/preflight) is inverted over —
+// a rootless-podman probe, a podman-version floor probe, and an agent-image
+// presence check. They are thin shells around os/exec and the runtime package,
+// mirroring how go/internal/stack/adapters wires real effects behind the stack
+// core seams; the pipeline's composition root (realPreflight in embedded.go)
+// supplies them.
+package main
+
+import (
+	"context"
+	"fmt"
+	"os/exec"
+	"strings"
+
+	"github.com/RigelBuild/compass/go/internal/runtime"
+)
+
+// podmanRootless probes that rootless podman is present and usable by running
+// `podman info`. A nil error means it answered; a non-nil error wraps the
+// captured stderr so the preflight failure copy names why podman is unusable.
+func podmanRootless(ctx context.Context) error {
+	cmd := exec.CommandContext(ctx, "podman", "info")
+	if out, err := cmd.CombinedOutput(); err != nil {
+		if msg := strings.TrimSpace(string(out)); msg != "" {
+			return fmt.Errorf("podman info: %w: %s", err, msg)
+		}
+		return fmt.Errorf("podman info: %w", err)
+	}
+	return nil
+}
+
+// podmanVersionAtLeastFloor probes that the host podman is new enough for the
+// userns remap the runner depends on (podman >= 4.3). It reuses
+// runtime.(*PodmanCLI).VerifyUsernsRemapSupport so the app's front-door gate and
+// the runner's startup gate share one floor and one error copy ("podman N.N or
+// newer is required …"). A nil error means the floor is met; a non-nil error
+// carries that copy verbatim so preflight surfaces it before `compass-stack up`
+// (design §A3 delta 4).
+func podmanVersionAtLeastFloor(ctx context.Context) error {
+	return runtime.NewPodmanCLI().VerifyUsernsRemapSupport(ctx)
+}
+
+// imagePresent probes that the agent image ref is present in the local store via
+// `podman image exists <image>` (exit 0 = present, non-zero = absent). A
+// non-nil error means the image is not available locally (the preflight core
+// reports it is pulled from GHCR at first run); it wraps the captured stderr for
+// context.
+func imagePresent(ctx context.Context, image string) error {
+	//nolint:gosec // G204: image is an operator/env-resolved ref, argv is fixed.
+	cmd := exec.CommandContext(ctx, "podman", "image", "exists", image)
+	if out, err := cmd.CombinedOutput(); err != nil {
+		if msg := strings.TrimSpace(string(out)); msg != "" {
+			return fmt.Errorf("podman image exists %s: %w: %s", image, err, msg)
+		}
+		return fmt.Errorf("podman image exists %s: %w", image, err)
+	}
+	return nil
+}
diff --git a/go/internal/appconfig/appconfig.go b/go/internal/appconfig/appconfig.go
index 4412642ee..1ff2c240d 100644
--- a/go/internal/appconfig/appconfig.go
+++ b/go/internal/appconfig/appconfig.go
@@ -11,31 +11,39 @@ import (
 	"github.com/BurntSushi/toml"
 )
 
-// Mode is the native app's operating mode. Client is the only mode — embedded
-// mode was retired in RIG-2554 (the app no longer supervises a stack). Mode is
-// kept as a validation-only concept: Load/Parse only ever yield ModeClient or a
-// legible error, and the shell's launch dispatch keeps a default rejection arm.
+// Mode is the native app's operating mode, selected by app.toml and an optional
+// --mode/$COMPASS_APP_MODE override (design §A1). The app is dual-mode: it
+// either supervises a local stack (embedded) or dials a remote one (client).
 type Mode int
 
 const (
 	// ModeClient connects to a remote compass-server over its authenticated
 	// loopback/network door; it requires a ServerURL and may carry a CACert.
+	// It KEEPS the zero value so a client Config need not be spelled out.
 	ModeClient Mode = iota
+	// ModeEmbedded is the local-supervisor onboarding mode: the app brings up
+	// and supervises a private stack in-process. It is the zero-config default
+	// an absent app.toml (and an empty/absent mode) resolves to, so a first
+	// launch of the installed app just works without any server_url. It is
+	// declared AFTER ModeClient so ModeClient retains the zero value.
+	ModeEmbedded
 )
 
-// modeStrClient is the canonical client mode string as written in app.toml — the
-// single source of truth shared by String and Parse.
+// modeStrClient is the canonical client mode string as written in app.toml and
+// the --mode/$COMPASS_APP_MODE override — the single source of truth shared by
+// String, Parse, and applyOverride.
 const modeStrClient = "client"
 
-// modeStrEmbedded is the retired mode value. It is NOT a supported mode: it
-// parses to a legible rejection (see Parse) naming the retirement, not a
-// compatibility arm.
+// modeStrEmbedded is the canonical embedded mode string, shared by String,
+// Parse, and applyOverride.
 const modeStrEmbedded = "embedded"
 
 // String renders the mode as it is written in app.toml (the TOML mode value),
 // for logs and round-tripping.
 func (m Mode) String() string {
 	switch m {
+	case ModeEmbedded:
+		return modeStrEmbedded
 	case ModeClient:
 		return modeStrClient
 	default:
@@ -47,19 +55,20 @@ func (m Mode) String() string {
 // (OS keychain, DL-109) nor the caller account id (WhoAmI RPC, DL-111); neither
 // lives in the config file.
 type Config struct {
-	// Mode is the resolved operating mode. Client is the only mode.
+	// Mode is the resolved operating mode (embedded or client).
 	Mode Mode
 	// ServerURL is the native-client base URL (an absolute https URL). It is
-	// always required (client is the only mode).
+	// required in client mode and empty in embedded mode.
 	ServerURL string
 	// CACert is an optional path to a private trust anchor (PEM) for a
 	// native-client connection whose server presents a private-CA certificate.
-	// Empty means use the system roots.
+	// Empty means use the system roots. Client-only; empty in embedded mode.
 	CACert string
 }
 
 // fileConfig is the on-disk TOML shape. It is decoded and then validated into a
-// Config.
+// Config; keeping it separate lets Parse distinguish an absent mode key from an
+// explicit empty string only where that matters (both resolve to embedded).
 type fileConfig struct {
 	Mode      string `toml:"mode"`
 	ServerURL string `toml:"server_url"`
@@ -67,15 +76,13 @@ type fileConfig struct {
 }
 
 // Parse decodes and validates an app.toml byte slice into a Config. It performs
-// no I/O. The rules (design §A3, client-only):
-//   - absent/empty mode or mode="client" → client mode, which REQUIRES a
-//     non-empty server_url that parses as an absolute https URL (ca_cert is
-//     optional);
-//   - mode="embedded" → a legible rejection naming the retirement (embedded mode
-//     was retired; run a headless stack with `compass-stack up` and point the
-//     app at it in client mode). This is an error string, NOT a compatibility
-//     arm (Global Constraint 5's sanctioned residue).
-//   - any other mode value is an error naming the one valid mode.
+// no I/O. The rules (design §A1):
+//   - absent/empty mode or mode="embedded" → ModeEmbedded (the zero-config
+//     onboarding default). server_url and ca_cert are client-only fields, so a
+//     non-empty value under embedded mode is a legible error;
+//   - mode="client" requires a non-empty server_url that parses as an absolute
+//     https URL (ca_cert is optional);
+//   - any other mode value is an error naming the two valid modes.
 func Parse(data []byte) (Config, error) {
 	var fc fileConfig
 	md, err := toml.Decode(string(data), &fc)
@@ -91,25 +98,40 @@ func Parse(data []byte) (Config, error) {
 	}
 
 	switch strings.TrimSpace(fc.Mode) {
-	case "", modeStrClient:
+	case "", modeStrEmbedded:
+		return parseEmbedded(fc)
+	case modeStrClient:
 		return parseClient(fc)
-	case modeStrEmbedded:
-		return Config{}, errors.New(
-			`appconfig: mode="embedded" is no longer supported: embedded mode was retired (RIG-2554). ` +
-				"Run a headless Compass stack with `compass-stack up` on a dedicated machine and " +
-				`point the app at it in client mode (mode="client" with server_url = "https://host:8443")`)
 	default:
 		return Config{}, fmt.Errorf(
-			"appconfig: unknown mode %q in app.toml: the only valid mode is %q",
-			fc.Mode, modeStrClient)
+			"appconfig: unknown mode %q in app.toml: valid modes are %q and %q",
+			fc.Mode, modeStrEmbedded, modeStrClient)
 	}
 }
 
+// parseEmbedded validates the embedded-mode fields. Embedded supervises a local
+// stack, so server_url and ca_cert are client-only and must be absent: a value
+// under embedded mode is almost certainly a misfiled client config, so it is
+// rejected legibly rather than silently ignored.
+func parseEmbedded(fc fileConfig) (Config, error) {
+	if strings.TrimSpace(fc.ServerURL) != "" {
+		return Config{}, errors.New(
+			`appconfig: server_url is a client-only field and must not be set in embedded mode ` +
+				`(embedded supervises a local stack); use mode="client" to dial a remote server_url`)
+	}
+	if strings.TrimSpace(fc.CACert) != "" {
+		return Config{}, errors.New(
+			`appconfig: ca_cert is a client-only field and must not be set in embedded mode ` +
+				`(embedded supervises a local stack); use mode="client" to dial a remote server with a private CA`)
+	}
+	return Config{Mode: ModeEmbedded}, nil
+}
+
 // parseClient validates the client-mode fields.
 func parseClient(fc fileConfig) (Config, error) {
 	if strings.TrimSpace(fc.ServerURL) == "" {
 		return Config{}, errors.New(
-			`appconfig: server_url is required in app.toml (e.g. server_url = "https://host:8443")`)
+			`appconfig: mode="client" requires server_url in app.toml (e.g. server_url = "https://host:8443")`)
 	}
 	if err := validateServerURL(fc.ServerURL); err != nil {
 		return Config{}, err
@@ -145,37 +167,64 @@ func validateServerURL(raw string) error {
 	return nil
 }
 
-// Load resolves the app configuration from disk.
+// Load resolves the app configuration from disk and applies an override.
 //
 // The config path is computed from the caller-provided paths (design §A4):
 // configHome/compass/app.toml when configHome is non-empty (the resolved
 // $XDG_CONFIG_HOME), else home/.config/compass/app.toml. The caller reads the
 // env; Load performs the resolution so it stays testable.
 //
-// An absent file is a legible first-run error: client mode requires a server_url
-// and there is no zero-config default any more (embedded mode was retired,
-// RIG-2554). A present file is read and Parsed.
-func Load(configHome, home string) (Config, error) {
+// An absent file is not an error — it resolves to the ModeEmbedded zero-config
+// onboarding default (first launch just works). A present file is read and
+// Parsed.
+//
+// override is the resolved --mode/$COMPASS_APP_MODE value (empty = none). It is
+// applied AFTER the file parse and wins: precedence is override (flag > env,
+// resolved by the caller) > file > embedded-default (OQ-3). An override with no
+// file present still works.
+func Load(configHome, home, override string) (Config, error) {
 	path, err := configPath(configHome, home)
 	if err != nil {
 		return Config{}, err
 	}
 
+	cfg := Config{Mode: ModeEmbedded}
 	// The path is the app's own config file, resolved from the caller's config
 	// home — not attacker-controlled input.
 	data, readErr := os.ReadFile(path) //nolint:gosec // G304: caller-resolved app config path, not user input
 	switch {
 	case readErr == nil:
-		return Parse(data)
+		cfg, err = Parse(data)
+		if err != nil {
+			return Config{}, err
+		}
 	case errors.Is(readErr, os.ErrNotExist):
-		return Config{}, fmt.Errorf(
-			"appconfig: no app config found at %s: the Compass app is a client and needs a "+
-				`server_url to connect to. Create it with mode="client" and `+
-				`server_url = "https://host:8443" (the address of a headless stack started with `+
-				"`compass-stack up`)", path)
+		// Absent file → embedded zero-config onboarding default; not an error.
 	default:
 		return Config{}, fmt.Errorf("appconfig: reading %s: %w", path, readErr)
 	}
+
+	return applyOverride(cfg, override)
+}
+
+// applyOverride applies the resolved --mode/$COMPASS_APP_MODE override on top of
+// the file-derived config. An empty override is a no-op. An override to embedded
+// clears the client-only fields; an override to client keeps whatever server_url
+// and ca_cert the file supplied, then re-validates them so an override into
+// client mode without a usable server_url fails legibly.
+func applyOverride(cfg Config, override string) (Config, error) {
+	switch strings.TrimSpace(override) {
+	case "":
+		return cfg, nil
+	case modeStrEmbedded:
+		return Config{Mode: ModeEmbedded}, nil
+	case modeStrClient:
+		return parseClient(fileConfig{ServerURL: cfg.ServerURL, CACert: cfg.CACert})
+	default:
+		return Config{}, fmt.Errorf(
+			"appconfig: unknown mode override %q: valid modes are %q and %q",
+			override, modeStrEmbedded, modeStrClient)
+	}
 }
 
 // configPath computes the app.toml path from the caller-resolved config home and
diff --git a/go/internal/appconfig/appconfig_test.go b/go/internal/appconfig/appconfig_test.go
index eb75846cf..bbcfeb73e 100644
--- a/go/internal/appconfig/appconfig_test.go
+++ b/go/internal/appconfig/appconfig_test.go
@@ -7,30 +7,83 @@ import (
 	"testing"
 )
 
-func TestParse(t *testing.T) {
-	tests := []struct {
-		name       string
-		data       string
-		want       Config
-		wantErr    bool
-		errSubstrs []string
-	}{
-		{
-			name: "empty file → client (server_url required)",
+type parseCase struct {
+	name       string
+	data       string
+	want       Config
+	wantErr    bool
+	errSubstrs []string
+}
+
+func runParseCases(t *testing.T, tests []parseCase) {
+	t.Helper()
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := Parse([]byte(tc.data))
+			if tc.wantErr {
+				if err == nil {
+					t.Fatalf("want error, got config %+v", got)
+				}
+				for _, sub := range tc.errSubstrs {
+					if !strings.Contains(err.Error(), sub) {
+						t.Errorf("error %q missing substring %q", err, sub)
+					}
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if got != tc.want {
+				t.Errorf("got %+v, want %+v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestParseEmbedded(t *testing.T) {
+	runParseCases(t, []parseCase{
+		{
+			name: "empty file → embedded (zero-config default)",
 			data: "",
-			// Absent mode defaults to client, which requires server_url; an
-			// empty file therefore fails legibly rather than resolving.
+			want: Config{Mode: ModeEmbedded},
+		},
+		{
+			name: "explicit embedded mode",
+			data: `mode = "embedded"`,
+			want: Config{Mode: ModeEmbedded},
+		},
+		{
+			name: "whitespace-only mode → embedded",
+			data: `mode = "  "`,
+			want: Config{Mode: ModeEmbedded},
+		},
+		{
+			name:       "embedded with server_url → legible reject",
+			data:       "mode = \"embedded\"\nserver_url = \"https://host:8443\"\n",
 			wantErr:    true,
-			errSubstrs: []string{"server_url"},
+			errSubstrs: []string{"server_url", "client-only", "embedded"},
 		},
 		{
-			name: "client with server_url",
-			data: "mode = \"client\"\nserver_url = \"https://host:8443\"\n",
-			want: Config{Mode: ModeClient, ServerURL: "https://host:8443"},
+			name:       "embedded with ca_cert → legible reject",
+			data:       "mode = \"embedded\"\nca_cert = \"/etc/anchor.pem\"\n",
+			wantErr:    true,
+			errSubstrs: []string{"ca_cert", "client-only", "embedded"},
 		},
 		{
-			name: "absent mode with server_url → client",
-			data: "server_url = \"https://host:8443\"\n",
+			name:       "absent mode with server_url → legible reject (embedded default is client-free)",
+			data:       "server_url = \"https://host:8443\"\n",
+			wantErr:    true,
+			errSubstrs: []string{"server_url", "client-only"},
+		},
+	})
+}
+
+func TestParseClient(t *testing.T) {
+	runParseCases(t, []parseCase{
+		{
+			name: "client with server_url",
+			data: "mode = \"client\"\nserver_url = \"https://host:8443\"\n",
 			want: Config{Mode: ModeClient, ServerURL: "https://host:8443"},
 		},
 		{
@@ -38,12 +91,6 @@ func TestParse(t *testing.T) {
 			data: "mode = \"client\"\nserver_url = \"https://host:8443\"\nca_cert = \"/etc/anchor.pem\"\n",
 			want: Config{Mode: ModeClient, ServerURL: "https://host:8443", CACert: "/etc/anchor.pem"},
 		},
-		{
-			name:       "embedded → legible retirement rejection",
-			data:       `mode = "embedded"`,
-			wantErr:    true,
-			errSubstrs: []string{"embedded", "retired", "compass-stack up", "client"},
-		},
 		{
 			name:       "client missing server_url → error",
 			data:       `mode = "client"`,
@@ -62,24 +109,6 @@ func TestParse(t *testing.T) {
 			wantErr:    true,
 			errSubstrs: []string{"server_url"},
 		},
-		{
-			name:       "unknown mode → error",
-			data:       `mode = "proxy"`,
-			wantErr:    true,
-			errSubstrs: []string{"proxy", "client"},
-		},
-		{
-			name:       "malformed toml → error",
-			data:       "mode = ",
-			wantErr:    true,
-			errSubstrs: []string{"app.toml"},
-		},
-		{
-			name:       "whitespace-only mode → client (server_url required)",
-			data:       `mode = "  "`,
-			wantErr:    true,
-			errSubstrs: []string{"server_url"},
-		},
 		{
 			name:       "client whitespace-only server_url → error",
 			data:       "mode = \"client\"\nserver_url = \"   \"\n",
@@ -92,57 +121,60 @@ func TestParse(t *testing.T) {
 			wantErr:    true,
 			errSubstrs: []string{"credentials", "keychain"},
 		},
+		{
+			name:       "unknown mode → error naming both modes",
+			data:       `mode = "proxy"`,
+			wantErr:    true,
+			errSubstrs: []string{"proxy", "embedded", "client"},
+		},
+		{
+			name:       "malformed toml → error",
+			data:       "mode = ",
+			wantErr:    true,
+			errSubstrs: []string{"app.toml"},
+		},
 		{
 			name:       "unknown key → error",
 			data:       "mode = \"client\"\nserver_url = \"https://host:8443\"\ncacert = \"/etc/anchor.pem\"\n",
 			wantErr:    true,
 			errSubstrs: []string{"unknown key", "cacert"},
 		},
-	}
+	})
+}
 
-	for _, tc := range tests {
-		t.Run(tc.name, func(t *testing.T) {
-			got, err := Parse([]byte(tc.data))
-			if tc.wantErr {
-				if err == nil {
-					t.Fatalf("want error, got config %+v", got)
-				}
-				for _, sub := range tc.errSubstrs {
-					if !strings.Contains(err.Error(), sub) {
-						t.Errorf("error %q missing substring %q", err, sub)
-					}
-				}
-				return
-			}
-			if err != nil {
-				t.Fatalf("unexpected error: %v", err)
-			}
-			if got != tc.want {
-				t.Errorf("got %+v, want %+v", got, tc.want)
-			}
-		})
+// TestModeClientIsZeroValue pins the zero-value contract: ModeClient MUST be the
+// zero value so an unspelled Config{} means client, never embedded. Inserting
+// ModeEmbedded before ModeClient in the const block would silently flip this and
+// route every zero-valued Config to embedded.
+func TestModeClientIsZeroValue(t *testing.T) {
+	var zero Mode
+	if zero != ModeClient {
+		t.Fatalf("zero-value Mode = %v (%d), want ModeClient (0)", zero, int(zero))
+	}
+	if int(ModeClient) != 0 {
+		t.Errorf("ModeClient = %d, want 0", int(ModeClient))
+	}
+	if int(ModeEmbedded) == 0 {
+		t.Errorf("ModeEmbedded = 0, must not share the zero value with ModeClient")
 	}
 }
 
-// TestLoadAbsentFileIsFirstRunError: an absent app.toml is a legible first-run
-// error (client mode needs a server_url; embedded's zero-config default was
-// retired in RIG-2554), naming the config path and pointing at the client setup.
-func TestLoadAbsentFileIsFirstRunError(t *testing.T) {
+// TestLoadAbsentFileIsEmbeddedDefault: an absent app.toml is NOT an error — it
+// resolves to the embedded zero-config onboarding default.
+func TestLoadAbsentFileIsEmbeddedDefault(t *testing.T) {
 	dir := t.TempDir()
-	got, err := Load(dir, "")
-	if err == nil {
-		t.Fatalf("absent file: want a first-run error, got config %+v", got)
+	got, err := Load(dir, "", "")
+	if err != nil {
+		t.Fatalf("absent file: unexpected error: %v", err)
 	}
-	for _, sub := range []string{"app.toml", "server_url", "client"} {
-		if !strings.Contains(err.Error(), sub) {
-			t.Errorf("first-run error %q missing substring %q", err, sub)
-		}
+	if want := (Config{Mode: ModeEmbedded}); got != want {
+		t.Errorf("got %+v, want %+v", got, want)
 	}
 }
 
 func TestLoadReadsPresentFile(t *testing.T) {
 	dir := writeConfig(t, "mode = \"client\"\nserver_url = \"https://host:8443\"\n")
-	got, err := Load(dir, "")
+	got, err := Load(dir, "", "")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -151,18 +183,14 @@ func TestLoadReadsPresentFile(t *testing.T) {
 	}
 }
 
-// TestLoadEmbeddedFileIsRejected: a present file selecting the retired embedded
-// mode is rejected through Load (not just Parse) with the retirement copy.
-func TestLoadEmbeddedFileIsRejected(t *testing.T) {
+func TestLoadEmbeddedFile(t *testing.T) {
 	dir := writeConfig(t, `mode = "embedded"`)
-	got, err := Load(dir, "")
-	if err == nil {
-		t.Fatalf("embedded file: want a rejection, got config %+v", got)
+	got, err := Load(dir, "", "")
+	if err != nil {
+		t.Fatalf("embedded file: unexpected error: %v", err)
 	}
-	for _, sub := range []string{"embedded", "retired", "compass-stack up"} {
-		if !strings.Contains(err.Error(), sub) {
-			t.Errorf("embedded rejection %q missing substring %q", err, sub)
-		}
+	if want := (Config{Mode: ModeEmbedded}); got != want {
+		t.Errorf("got %+v, want %+v", got, want)
 	}
 }
 
@@ -175,7 +203,7 @@ func TestLoadHomeFallbackPath(t *testing.T) {
 	if err := os.WriteFile(path, []byte("mode = \"client\"\nserver_url = \"https://host:8443\"\n"), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	got, err := Load("", home)
+	got, err := Load("", home, "")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -184,10 +212,82 @@ func TestLoadHomeFallbackPath(t *testing.T) {
 	}
 }
 
+// TestLoadOverridePrecedence pins the override > file > default precedence
+// (OQ-3). The override is the resolved --mode/$COMPASS_APP_MODE value; the
+// caller resolves flag > env into that single string.
+func TestLoadOverridePrecedence(t *testing.T) {
+	t.Run("override embedded wins over client file", func(t *testing.T) {
+		dir := writeConfig(t, "mode = \"client\"\nserver_url = \"https://host:8443\"\n")
+		got, err := Load(dir, "", modeStrEmbedded)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if want := (Config{Mode: ModeEmbedded}); got != want {
+			t.Errorf("got %+v, want %+v", got, want)
+		}
+	})
+
+	t.Run("override client with no file needs server_url", func(t *testing.T) {
+		dir := t.TempDir()
+		if _, err := Load(dir, "", modeStrClient); err == nil {
+			t.Fatal("override to client without a server_url: want error, got nil")
+		}
+	})
+
+	t.Run("override client keeps file server_url", func(t *testing.T) {
+		dir := writeConfig(t, "mode = \"client\"\nserver_url = \"https://host:8443\"\n")
+		got, err := Load(dir, "", modeStrClient)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if want := (Config{Mode: ModeClient, ServerURL: "https://host:8443"}); got != want {
+			t.Errorf("got %+v, want %+v", got, want)
+		}
+	})
+
+	t.Run("empty override falls through to file", func(t *testing.T) {
+		dir := writeConfig(t, "mode = \"client\"\nserver_url = \"https://host:8443\"\n")
+		got, err := Load(dir, "", "")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if want := (Config{Mode: ModeClient, ServerURL: "https://host:8443"}); got != want {
+			t.Errorf("got %+v, want %+v", got, want)
+		}
+	})
+
+	t.Run("empty override with absent file → embedded default", func(t *testing.T) {
+		dir := t.TempDir()
+		got, err := Load(dir, "", "")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if want := (Config{Mode: ModeEmbedded}); got != want {
+			t.Errorf("got %+v, want %+v", got, want)
+		}
+	})
+
+	t.Run("unknown override → error naming both modes", func(t *testing.T) {
+		dir := t.TempDir()
+		_, err := Load(dir, "", "proxy")
+		if err == nil {
+			t.Fatal("unknown override: want error, got nil")
+		}
+		for _, sub := range []string{"proxy", "embedded", "client"} {
+			if !strings.Contains(err.Error(), sub) {
+				t.Errorf("override error %q missing substring %q", err, sub)
+			}
+		}
+	})
+}
+
 func TestModeString(t *testing.T) {
 	if got := ModeClient.String(); got != "client" {
 		t.Errorf("ModeClient.String() = %q, want client", got)
 	}
+	if got := ModeEmbedded.String(); got != "embedded" {
+		t.Errorf("ModeEmbedded.String() = %q, want embedded", got)
+	}
 }
 
 // writeConfig writes app.toml under a fresh temp configHome and returns that
diff --git a/go/internal/appconfig/doc.go b/go/internal/appconfig/doc.go
index 1363acaac..7d45356c8 100644
--- a/go/internal/appconfig/doc.go
+++ b/go/internal/appconfig/doc.go
@@ -1,15 +1,24 @@
-// Package appconfig is the native app's client config parser (design §A3). One
-// file — $XDG_CONFIG_HOME/compass/app.toml (fallback ~/.config/compass/app.toml)
-// — configures the native-client connection: a base URL plus an optional
-// private-anchor CA cert. Embedded mode was retired in RIG-2554, so client is
-// the only mode; a mode="embedded" value parses to a legible rejection, not a
-// compatibility arm.
+// Package appconfig is the native app's config parser (design §A1). One file —
+// $XDG_CONFIG_HOME/compass/app.toml (fallback ~/.config/compass/app.toml) —
+// selects the app's operating mode and, in client mode, its connection.
+//
+// The app is dual-mode:
+//   - embedded (the zero-config onboarding default): the app supervises a
+//     private local stack in-process. An absent file, an empty mode, or
+//     mode="embedded" resolves here, so a first launch just works. server_url
+//     and ca_cert are client-only fields and must be absent in embedded mode.
+//   - client: the app dials a remote compass-server. It requires a server_url
+//     that is an absolute https URL (cleartext is refused) and may carry an
+//     optional ca_cert private trust anchor.
+//
+// A --mode/$COMPASS_APP_MODE override, resolved by the caller and passed to
+// Load, wins over the file: precedence is override > file > embedded-default.
 //
 // The core is pure: Parse decodes and validates a TOML byte slice with no I/O,
-// and Load layers path resolution on top. Mirroring the stack package idiom, the
-// caller resolves every path — Load takes configHome and home as parameters (the
-// caller reads the env), so the resolution is fully unit-testable without
-// touching real $HOME/$XDG_CONFIG_HOME.
+// and Load layers path resolution and the override on top. Mirroring the stack
+// package idiom, the caller resolves every path — Load takes configHome and home
+// as parameters (the caller reads the env), so the resolution is fully
+// unit-testable without touching real $HOME/$XDG_CONFIG_HOME.
 //
 // The config file carries neither the bearer token (entered once and stored in
 // the OS keychain, DL-109) nor the caller account id (resolved by the WhoAmI
diff --git a/go/internal/bridge/pump.go b/go/internal/bridge/pump.go
index c7242f5b1..0c0060e09 100644
--- a/go/internal/bridge/pump.go
+++ b/go/internal/bridge/pump.go
@@ -74,12 +74,11 @@ type Call struct {
 // Target is a resolved daemon endpoint the pump forwards against. It holds the
 // HTTP client wired to reach the daemon and the base URL to build requests from.
 //
-// Production wires a TLS/network-door target (native-client mode): a constructor
-// supplies a client with a TLS-dialing transport and an https base URL, and the
-// pump forwarding logic is unchanged. [NewUnixTarget] remains only as a
-// test-harness h2c-over-UDS stub — its production caller was removed in T-1
-// (RIG-2554); its sole users are the pump test suite (pump_test.go) and two
-// compass-app tests.
+// Two production wirings build a Target. Embedded mode wires a
+// cleartext-HTTP/2-over-UDS target ([NewUnixTarget]) at the private stack's Unix
+// socket; native-client mode wires a TLS/network-door target
+// ([NewTLSTarget]) at an https base URL. The pump forwarding logic is identical
+// for both.
 type Target struct {
 	client  *http.Client
 	baseURL string
diff --git a/go/internal/preflight/doc.go b/go/internal/preflight/doc.go
new file mode 100644
index 000000000..44a9eff5f
--- /dev/null
+++ b/go/internal/preflight/doc.go
@@ -0,0 +1,19 @@
+// Package preflight is the native app's embedded-mode host preflight: the set of
+// checks that must pass BEFORE spawning the embedded stack (compass-stack up)
+// per the compass-native-embedded-revival design (§A3). Each check produces
+// actionable failure copy so an operator on an unsupported host sees the precise
+// precondition to fix, rather than a deep failure inside the stack.
+//
+// The checker core is inverted over injected effect functions (see Deps),
+// mirroring the go/internal/stack idiom: every genuine external effect —
+// probing rootless podman, the podman version floor, the darwin podman machine,
+// and the local image store — is a func the caller supplies. The core imports
+// none of those subsystems, so unit tests supply stubs and no test shells out.
+//
+// The checks are cross-OS: the OS check accepts linux or darwin, and a
+// darwin-only machine check joins the set when its adapter is wired. The host
+// uid is deliberately NOT checked — the runner is uid-agnostic now via the
+// --userns=keep-id:uid= remap, so a uid gate would break launch on every host
+// with uid != 1000; the importable single source of truth for the agent uid is
+// go/internal/agentuid.AgentUID.
+package preflight
diff --git a/go/internal/preflight/preflight.go b/go/internal/preflight/preflight.go
new file mode 100644
index 000000000..aec124e14
--- /dev/null
+++ b/go/internal/preflight/preflight.go
@@ -0,0 +1,164 @@
+package preflight
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+)
+
+// Deps is the set of external effects the preflight core is inverted over. Each
+// func field is one genuine external effect; the real adapters (which shell out
+// to podman and inspect the local image store) are supplied at the wiring
+// boundary, and unit tests supply stubs. The core imports none of those
+// subsystems itself.
+type Deps struct {
+	// GOOS is the host operating system (runtime.GOOS at the wiring boundary).
+	// Injected rather than read directly so the OS check is unit-testable.
+	GOOS string
+	// PodmanRootless probes that rootless podman is present and usable. A nil
+	// error means it is available; a non-nil error explains why not.
+	PodmanRootless func(ctx context.Context) error
+	// PodmanVersion probes that the host podman is new enough for the userns
+	// remap the runner depends on (podman >= 4.3, where --userns=keep-id:uid=
+	// is available). A nil error means the floor is met; a non-nil error carries
+	// the "podman N.N or newer is required" copy the runner would otherwise emit
+	// deep inside a fire-and-return stack whose exit 0 hides it. Surfaced at the
+	// front door instead (design §A3 delta 4).
+	PodmanVersion func(ctx context.Context) error
+	// MachineReady probes that the darwin podman machine (the Linux VM podman
+	// runs inside on macOS) is up. Consulted ONLY on darwin; nil on linux (there
+	// is no machine to check). A nil error means ready; a non-nil error explains
+	// why not. The darwin adapter that supplies it lands in T-6 (design §A5); a
+	// nil MachineReady on darwin leaves the check absent until then.
+	MachineReady func(ctx context.Context) error
+	// ImagePresent probes that the given agent image ref is present in the local
+	// container store. A nil error means present; a non-nil error means it is not
+	// available locally (it is pulled from GHCR at first run).
+	ImagePresent func(ctx context.Context, image string) error
+}
+
+// Params is what the checks need from the caller: the resolved agent image ref.
+type Params struct {
+	// AgentImage is the container image ref the embedded runner runs; its
+	// presence in the local store is checked.
+	AgentImage string
+}
+
+// Result is the outcome of one preflight check. Name identifies the check; OK
+// reports whether it passed; Detail carries the actionable failure copy when
+// !OK (and may be empty when OK).
+type Result struct {
+	Name   string
+	OK     bool
+	Detail string
+}
+
+// Check names, stable for logs and error copy.
+const (
+	checkOS            = "os"
+	checkPodman        = "podman"
+	checkPodmanVersion = "podman-version"
+	checkMachine       = "machine"
+	checkImage         = "image"
+)
+
+// Exported aliases of the check names, so callers can classify results by check
+// (e.g. the wiring boundary hard-gates host-capability checks and treats the
+// image check as advisory). These are additive: the unexported names above stay
+// the values written into Result.Name, and these consts alias them so a caller's
+// classification cannot drift from the Run implementation.
+const (
+	CheckOS            = checkOS
+	CheckPodman        = checkPodman
+	CheckPodmanVersion = checkPodmanVersion
+	CheckMachine       = checkMachine
+	CheckImage         = checkImage
+)
+
+// Run executes every host precondition in order and returns one Result per
+// check. It does NOT short-circuit: an operator should see every failing
+// precondition at once, so all checks run even after an earlier failure. Call
+// the returned Results' Err method to fold the failures into one legible error.
+func (d Deps) Run(ctx context.Context, p Params) Results {
+	results := make(Results, 0, 5)
+
+	// (1) OS is supported: linux or darwin (Windows/WSL is out of scope, OQ-4).
+	osRes := Result{Name: checkOS, OK: d.GOOS == "linux" || d.GOOS == "darwin"}
+	if !osRes.OK {
+		osRes.Detail = "embedded mode runs on linux or darwin, this host is " + d.GOOS
+	}
+	results = append(results, osRes)
+
+	// (2) Rootless podman present.
+	podmanRes := Result{Name: checkPodman, OK: true}
+	if err := d.PodmanRootless(ctx); err != nil {
+		podmanRes.OK = false
+		podmanRes.Detail = fmt.Sprintf("rootless podman is required: %v", err)
+	}
+	results = append(results, podmanRes)
+
+	// (3) Podman is new enough for the userns remap (>= 4.3). The runner
+	// enforces this at startup, but that refusal is swallowed on the embedded
+	// fire-and-return path (design §A3 delta 4), so it is surfaced here at the
+	// front door. The probe's error already carries the "podman N.N or newer is
+	// required" copy, so it is used verbatim.
+	pvRes := Result{Name: checkPodmanVersion, OK: true}
+	if err := d.PodmanVersion(ctx); err != nil {
+		pvRes.OK = false
+		pvRes.Detail = err.Error()
+	}
+	results = append(results, pvRes)
+
+	// (4) Darwin podman machine ready. macOS runs podman inside a Linux VM; the
+	// check is consulted ONLY on darwin, and only when an adapter is wired (the
+	// darwin adapter lands in T-6). On linux there is no machine, so the check
+	// is absent.
+	if d.GOOS == "darwin" && d.MachineReady != nil {
+		machineRes := Result{Name: checkMachine, OK: true}
+		if err := d.MachineReady(ctx); err != nil {
+			machineRes.OK = false
+			machineRes.Detail = fmt.Sprintf("the podman machine is not ready: %v", err)
+		}
+		results = append(results, machineRes)
+	}
+
+	// (5) Agent image present in the local store. Reporting "not available
+	// locally" is the correct behavior, not a stub: the image is pulled from
+	// GHCR at first run.
+	imageRes := Result{Name: checkImage, OK: true}
+	if err := d.ImagePresent(ctx, p.AgentImage); err != nil {
+		imageRes.OK = false
+		imageRes.Detail = fmt.Sprintf(
+			"agent image %s is not available locally; it is pulled from GHCR at "+
+				"first run: %v", p.AgentImage, err)
+	}
+	results = append(results, imageRes)
+
+	return results
+}
+
+// Results is a preflight run's set of check outcomes.
+type Results []Result
+
+// Err aggregates the failed checks into one legible multi-line error, or returns
+// nil when every check passed. Returning all failures at once lets the operator
+// fix every unmet precondition in a single pass.
+func (rs Results) Err() error {
+	var failed []Result
+	for _, r := range rs {
+		if !r.OK {
+			failed = append(failed, r)
+		}
+	}
+	if len(failed) == 0 {
+		return nil
+	}
+	var b strings.Builder
+	b.WriteString("embedded-mode preflight failed:")
+	for _, r := range failed {
+		b.WriteString("\n  - ")
+		b.WriteString(r.Detail)
+	}
+	return errors.New(b.String())
+}
diff --git a/go/internal/preflight/preflight_test.go b/go/internal/preflight/preflight_test.go
new file mode 100644
index 000000000..4c15aa1b9
--- /dev/null
+++ b/go/internal/preflight/preflight_test.go
@@ -0,0 +1,281 @@
+package preflight
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+)
+
+// okDeps returns a Deps whose every injected effect passes, for the given host
+// GOOS. Tests override individual fields to drive one failure at a time.
+func okDeps(goos string) Deps {
+	return Deps{
+		GOOS:           goos,
+		PodmanRootless: func(context.Context) error { return nil },
+		PodmanVersion:  func(context.Context) error { return nil },
+		ImagePresent:   func(context.Context, string) error { return nil },
+	}
+}
+
+var testParams = Params{
+	AgentImage: "ghcr.io/rigelbuild/compass-agent:latest",
+}
+
+// resultByName finds a check result by its Name.
+func resultByName(t *testing.T, rs []Result, name string) Result {
+	t.Helper()
+	for _, r := range rs {
+		if r.Name == name {
+			return r
+		}
+	}
+	t.Fatalf("no result named %q in %v", name, rs)
+	return Result{}
+}
+
+func TestRunAllPass(t *testing.T) {
+	ctx := context.Background()
+	rs := okDeps("linux").Run(ctx, testParams)
+
+	// linux: os, podman, podman-version, image (no machine check on linux).
+	if len(rs) != 4 {
+		t.Fatalf("want 4 results on linux, got %d: %v", len(rs), rs)
+	}
+	for _, r := range rs {
+		if !r.OK {
+			t.Errorf("check %q failed: %s", r.Name, r.Detail)
+		}
+	}
+	if err := rs.Err(); err != nil {
+		t.Errorf("want nil error when all pass, got %v", err)
+	}
+}
+
+func TestRunWrongGOOS(t *testing.T) {
+	ctx := context.Background()
+	rs := okDeps("windows").Run(ctx, testParams)
+
+	got := resultByName(t, rs, checkOS)
+	if got.OK {
+		t.Fatal("os check should fail on windows")
+	}
+	for _, tok := range []string{"linux", "darwin", "windows"} {
+		if !strings.Contains(got.Detail, tok) {
+			t.Errorf("os detail %q missing token %q", got.Detail, tok)
+		}
+	}
+	assertErrContains(t, rs.Err(), "windows")
+}
+
+// TestRunDarwinPasses: darwin is a supported OS. With a ready machine adapter
+// wired, all checks pass and the machine check appears in the results.
+func TestRunDarwinPasses(t *testing.T) {
+	ctx := context.Background()
+	d := okDeps("darwin")
+	d.MachineReady = func(context.Context) error { return nil }
+	rs := d.Run(ctx, testParams)
+
+	if resultByName(t, rs, checkOS).OK != true {
+		t.Error("os check should pass on darwin")
+	}
+	if got := resultByName(t, rs, checkMachine); !got.OK {
+		t.Errorf("machine check should pass with a ready adapter: %s", got.Detail)
+	}
+	if err := rs.Err(); err != nil {
+		t.Errorf("want nil error on darwin all-pass, got %v", err)
+	}
+}
+
+// TestRunMachineCheckAbsentOnLinux: linux has no podman machine, so the machine
+// check never appears even if a MachineReady adapter is somehow wired.
+func TestRunMachineCheckAbsentOnLinux(t *testing.T) {
+	ctx := context.Background()
+	d := okDeps("linux")
+	d.MachineReady = func(context.Context) error { return errors.New("should not be called on linux") }
+	rs := d.Run(ctx, testParams)
+
+	for _, r := range rs {
+		if r.Name == checkMachine {
+			t.Fatalf("machine check present on linux: %v", rs)
+		}
+	}
+}
+
+// TestRunMachineNotReadyOnDarwin: a darwin machine that is not ready fails the
+// machine check and folds into the aggregated error.
+func TestRunMachineNotReadyOnDarwin(t *testing.T) {
+	ctx := context.Background()
+	d := okDeps("darwin")
+	d.MachineReady = func(context.Context) error { return errors.New("machine stopped") }
+	rs := d.Run(ctx, testParams)
+
+	got := resultByName(t, rs, checkMachine)
+	if got.OK {
+		t.Fatal("machine check should fail when the machine is not ready")
+	}
+	if !strings.Contains(got.Detail, "machine stopped") {
+		t.Errorf("machine detail %q missing probe error", got.Detail)
+	}
+	assertErrContains(t, rs.Err(), "machine stopped")
+}
+
+// TestRunMachineAbsentOnDarwinWithoutAdapter: on darwin with no MachineReady
+// adapter wired (the pre-T-6 state), the machine check is absent rather than a
+// spurious failure — the seam is wired, the adapter lands in T-6.
+func TestRunMachineAbsentOnDarwinWithoutAdapter(t *testing.T) {
+	ctx := context.Background()
+	rs := okDeps("darwin").Run(ctx, testParams)
+
+	for _, r := range rs {
+		if r.Name == checkMachine {
+			t.Fatalf("machine check present on darwin without an adapter: %v", rs)
+		}
+	}
+	if err := rs.Err(); err != nil {
+		t.Errorf("want nil error on darwin with no machine adapter, got %v", err)
+	}
+}
+
+func TestRunPodmanProbeFails(t *testing.T) {
+	ctx := context.Background()
+	d := okDeps("linux")
+	d.PodmanRootless = func(context.Context) error {
+		return errors.New("podman socket not found")
+	}
+	rs := d.Run(ctx, testParams)
+
+	got := resultByName(t, rs, checkPodman)
+	if got.OK {
+		t.Fatal("podman check should fail when probe errors")
+	}
+	if !strings.Contains(got.Detail, "podman socket not found") {
+		t.Errorf("podman detail %q missing probe error", got.Detail)
+	}
+	assertErrContains(t, rs.Err(), "rootless podman")
+}
+
+// TestRunPodmanVersionGate is the delta-4 gate: a below-floor podman fails FATAL
+// carrying the "podman N.N or newer" copy verbatim; at/above the floor passes.
+// The version probe is injected, so the test is hermetic (no real podman). The
+// probe's error copy is what VerifyUsernsRemapSupport emits, reused verbatim by
+// the check.
+func TestRunPodmanVersionGate(t *testing.T) {
+	// The exact copy runtime.(*PodmanCLI).VerifyUsernsRemapSupport emits below
+	// the floor, which the injected probe surfaces and the check carries through.
+	const belowFloorCopy = "podman 4.3 or newer is required (the container userns " +
+		"remap --userns=keep-id:uid=,gid= is a 4.3+ option), but this host has podman 3.4.4"
+
+	tests := []struct {
+		name      string
+		probe     func(context.Context) error
+		wantOK    bool
+		wantToken string
+	}{
+		{
+			name:      "below floor is refused",
+			probe:     func(context.Context) error { return errors.New(belowFloorCopy) },
+			wantOK:    false,
+			wantToken: "podman 4.3 or newer is required",
+		},
+		{
+			name:   "at or above floor passes",
+			probe:  func(context.Context) error { return nil },
+			wantOK: true,
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			ctx := context.Background()
+			d := okDeps("linux")
+			d.PodmanVersion = tc.probe
+			rs := d.Run(ctx, testParams)
+
+			got := resultByName(t, rs, checkPodmanVersion)
+			if got.OK != tc.wantOK {
+				t.Fatalf("podman-version check OK = %v, want %v (detail %q)", got.OK, tc.wantOK, got.Detail)
+			}
+			if tc.wantOK {
+				if err := rs.Err(); err != nil {
+					t.Errorf("want nil error at/above floor, got %v", err)
+				}
+				return
+			}
+			if !strings.Contains(got.Detail, tc.wantToken) {
+				t.Errorf("podman-version detail %q missing token %q", got.Detail, tc.wantToken)
+			}
+			assertErrContains(t, rs.Err(), tc.wantToken)
+		})
+	}
+}
+
+func TestRunImageAbsent(t *testing.T) {
+	ctx := context.Background()
+	d := okDeps("linux")
+	d.ImagePresent = func(context.Context, string) error {
+		return errors.New("no such image")
+	}
+	rs := d.Run(ctx, testParams)
+
+	got := resultByName(t, rs, checkImage)
+	if got.OK {
+		t.Fatal("image check should fail when image absent")
+	}
+	if !strings.Contains(got.Detail, testParams.AgentImage) {
+		t.Errorf("image detail %q missing image ref %q", got.Detail, testParams.AgentImage)
+	}
+	assertErrContains(t, rs.Err(), testParams.AgentImage)
+}
+
+// TestRunMultipleFailures asserts Run does not short-circuit: every failing
+// precondition is reported and appears in the aggregated error.
+func TestRunMultipleFailures(t *testing.T) {
+	ctx := context.Background()
+	d := Deps{
+		GOOS:           "windows",
+		PodmanRootless: func(context.Context) error { return errors.New("no podman") },
+		PodmanVersion:  func(context.Context) error { return errors.New("podman too old") },
+		ImagePresent:   func(context.Context, string) error { return errors.New("no image") },
+	}
+	rs := d.Run(ctx, testParams)
+
+	for _, name := range []string{checkOS, checkPodman, checkPodmanVersion, checkImage} {
+		if resultByName(t, rs, name).OK {
+			t.Errorf("check %q should have failed", name)
+		}
+	}
+
+	err := rs.Err()
+	if err == nil {
+		t.Fatal("want aggregated error for multiple failures, got nil")
+	}
+	// Every failing check's load-bearing token must appear in one error.
+	for _, tok := range []string{
+		"windows", "no podman", "podman too old", testParams.AgentImage,
+	} {
+		if !strings.Contains(err.Error(), tok) {
+			t.Errorf("aggregated error %q missing token %q", err.Error(), tok)
+		}
+	}
+}
+
+// TestResultsErrMethod exercises the named-slice Err method directly.
+func TestResultsErrMethod(t *testing.T) {
+	if err := (Results{{Name: checkOS, OK: true}}).Err(); err != nil {
+		t.Errorf("want nil for all-OK, got %v", err)
+	}
+	err := (Results{{Name: checkImage, OK: false, Detail: "boom"}}).Err()
+	if err == nil || !strings.Contains(err.Error(), "boom") {
+		t.Errorf("want error containing detail, got %v", err)
+	}
+}
+
+func assertErrContains(t *testing.T, err error, tok string) {
+	t.Helper()
+	if err == nil {
+		t.Fatalf("want error containing %q, got nil", tok)
+	}
+	if !strings.Contains(err.Error(), tok) {
+		t.Errorf("error %q missing token %q", err.Error(), tok)
+	}
+}

From 3b93f1f8568f0a6ff0f1490237a05a59ab96a8c8 Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Wed, 2 Sep 2026 22:40:41 -0400
Subject: [PATCH 2/2] test(compass-app): cover embedded shellStartupJS arm;
 comment fixes (RIG-3197)

Review fixes on the embedded-revival T-1+T-2 slice. Add an embedded subtest to TestShellStartupJS asserting the embedded arm emits window.__COMPASS_MODE__="embedded" and omits __COMPASS_SERVER_URL__ (a non-empty server URL is ignored in embedded mode), pinning the OQ-8 startup-global contract the UI embedded boot arm reads; correct the client_test.go doc comment that falsely claimed this arm was already covered. Tighten the launch() bring-up context comment to name the actual call site.

Ledger-impact: none
Refs RIG-1662
Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 go/cmd/compass-app/client_test.go | 22 +++++++++++++++++++---
 go/cmd/compass-app/main.go        |  9 +++++----
 2 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/go/cmd/compass-app/client_test.go b/go/cmd/compass-app/client_test.go
index 6bc68eabf..dbc4848cf 100644
--- a/go/cmd/compass-app/client_test.go
+++ b/go/cmd/compass-app/client_test.go
@@ -166,10 +166,9 @@ func pemEncodeCert(t *testing.T, cert *x509.Certificate) []byte {
 	return pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: cert.Raw})
 }
 
-// TestShellStartupJS covers the OQ-8 startup-global injection for CLIENT mode:
-// the client mode token, __COMPASS_SERVER_URL__ present in client mode, and
+// TestShellStartupJS covers the OQ-8 startup-global injection in both modes: the
+// mode token, __COMPASS_SERVER_URL__ present only in client mode, and
 // JSON-escaping of a hostile server URL so it cannot break out of the script.
-// (The embedded-mode arm of shellStartupJS is covered in embedded_test.go.)
 func TestShellStartupJS(t *testing.T) {
 	t.Run("client injects mode and server url", func(t *testing.T) {
 		js, err := shellStartupJS(appconfig.ModeClient.String(), "https://remote.example:8443")
@@ -184,6 +183,23 @@ func TestShellStartupJS(t *testing.T) {
 		}
 	})
 
+	t.Run("embedded injects mode and omits the server-url global", func(t *testing.T) {
+		// In embedded mode the app supervises a local stack and has no
+		// server_url, so shellStartupJS must emit only the mode token and MUST
+		// NOT emit __COMPASS_SERVER_URL__ (the branch at shellStartupJS's
+		// `if mode == client` gate). A non-empty serverURL argument is ignored.
+		js, err := shellStartupJS(appconfig.ModeEmbedded.String(), "https://ignored.example:8443")
+		if err != nil {
+			t.Fatalf("shellStartupJS err = %v, want nil", err)
+		}
+		if !strings.Contains(js, `window.__COMPASS_MODE__="embedded";`) {
+			t.Errorf("embedded JS = %q, want the embedded mode global", js)
+		}
+		if strings.Contains(js, "__COMPASS_SERVER_URL__") {
+			t.Errorf("embedded JS = %q, must not emit the server-url global", js)
+		}
+	})
+
 	t.Run("hostile server url is JSON-escaped, not a breakout", func(t *testing.T) {
 		hostile := `https://x/"+alert(1)+"</script><script>`
 		js, err := shellStartupJS(appconfig.ModeClient.String(), hostile)
diff --git a/go/cmd/compass-app/main.go b/go/cmd/compass-app/main.go
index 55abb513d..75ba3daf7 100644
--- a/go/cmd/compass-app/main.go
+++ b/go/cmd/compass-app/main.go
@@ -253,10 +253,11 @@ func launch(
 		params := embeddedParams{socket: socket, stateDir: stateDir, image: image}
 
 		// The embedded bring-up (preflight → stack up → WhoAmI) runs BEFORE the
-		// window opens, under a bounded bring-up context. run() is the process
-		// root (called directly by main), so context.Background() here is the
-		// sanctioned process-root context, not a mid-tree re-root; the bring-up
-		// window is derived from it.
+		// window opens, under a bounded bring-up context. launch() is invoked
+		// once from run() (the process entrypoint) and no context is created
+		// upstream, so this context.Background() is the sanctioned root of the
+		// bring-up pipeline, not a mid-tree re-root; the bring-up window is
+		// derived from it.
 		bringUpCtx, cancel := context.WithTimeout(context.Background(), bringUpTimeout)
 		accountID, quitter, err := runEmbedded(bringUpCtx, pipeline, params, runStackDown(stackBin))
 		cancel()