From 82f181338f011f18b032edebf3b58336ffb6adca Mon Sep 17 00:00:00 2001
From: Aric Camarata <aric.camarata@gmail.com>
Date: Sun, 25 Oct 2026 13:47:38 -0400
Subject: [PATCH 1/4] fix(compose): feed the cache password to the server on
 stdin so it never sits on argv (D-0587)

---
 internal/build/secrets_template_test.go       |  2 +-
 internal/compose/cache_service.go             | 27 ++++--
 internal/compose/cache_service_test.go        |  2 +-
 internal/compose/compose_extra_test.go        |  2 +-
 internal/compose/secret_argv_expanded_test.go | 97 +++++++++++++++++++
 internal/compose/secret_argv_test.go          |  4 +-
 internal/compose/secret_literal_test.go       |  4 +-
 7 files changed, 122 insertions(+), 16 deletions(-)
 create mode 100644 internal/compose/secret_argv_expanded_test.go

diff --git a/internal/build/secrets_template_test.go b/internal/build/secrets_template_test.go
index f80e320ca..d548d11b1 100644
--- a/internal/build/secrets_template_test.go
+++ b/internal/build/secrets_template_test.go
@@ -154,7 +154,7 @@ func TestTemplateSecrets_CommandAndHealthcheckLiteralsRewritten(t *testing.T) {
 	}
 	for _, ref := range []string{
 		"REDISCLI_AUTH: ${REDIS_PASSWORD}",
-		`--requirepass "$$REDISCLI_AUTH"`,
+		`requirepass "$$esc"`,
 		"TYPESENSE_API_KEY: ${TYPESENSE_API_KEY}",
 	} {
 		if !strings.Contains(doc, ref) {
diff --git a/internal/compose/cache_service.go b/internal/compose/cache_service.go
index a14e63a8a..9f5b6054f 100644
--- a/internal/compose/cache_service.go
+++ b/internal/compose/cache_service.go
@@ -141,6 +141,17 @@ func (g *Generator) cacheImage(engine string) string {
 	return ResolveImage("redis", ImageRef("redis", version))
 }
 
+// redisPasswordScript is the `sh -c` body that starts the cache server with the
+// password from $REDISCLI_AUTH on stdin as a `requirepass` config line. The
+// value is escaped for the config parser (backslash and double quote), so any
+// password round-trips. exec keeps the server as PID 1 for signal handling;
+// $$ survives compose interpolation as $.
+func redisPasswordScript(server string, poolSize int) string {
+	return fmt.Sprintf(`esc=$$(printf '%%s' "$$REDISCLI_AUTH" | sed 's/[\\"]/\\&/g'); `+
+		"exec %s --appendonly yes --protected-mode yes --maxclients %d - <<EOT\nrequirepass \"$$esc\"\nEOT\n",
+		server, poolSize)
+}
+
 // buildRedisService returns the cache/queue service configuration for the
 // engine. Command and health check depend on whether a password is set; the
 // valkey-* binaries are used by name (no reliance on redis-* symlinks).
@@ -173,16 +184,14 @@ func (g *Generator) buildRedisService() ServiceConfig {
 	var env map[string]string
 
 	if rc.Password != "" {
-		// D-0282: no argv carries the password. It reaches the container as
-		// REDISCLI_AUTH (Env, like every other secret), which the engine's CLI
-		// reads on its own (the health check needs no -a), and a shell expands it
-		// for the server ($$ survives compose interpolation as $). Valkey's CLI
-		// reads REDISCLI_AUTH too.
+		// D-0282, D-0587: no argv carries the password, not even the expanded
+		// one a host `ps` shows. It reaches the container as REDISCLI_AUTH (Env,
+		// like every other secret), which the engine's CLI reads on its own (the
+		// health check needs no -a). The server gets it as a config line on stdin
+		// (`-`), so it is never a process argument and never written to disk.
+		// Valkey's CLI and server behave the same.
 		env = map[string]string{"REDISCLI_AUTH": secretRef("REDIS_PASSWORD", rc.Password)}
-		command = []string{"sh", "-c", fmt.Sprintf(
-			`exec %s --appendonly yes --protected-mode yes --requirepass "$$REDISCLI_AUTH" --maxclients %d`,
-			server, poolSize,
-		)}
+		command = []string{"sh", "-c", redisPasswordScript(server, poolSize)}
 	} else {
 		command = fmt.Sprintf(
 			"%s --appendonly yes --protected-mode no --maxclients %d",
diff --git a/internal/compose/cache_service_test.go b/internal/compose/cache_service_test.go
index 540300475..a3f1f4e03 100644
--- a/internal/compose/cache_service_test.go
+++ b/internal/compose/cache_service_test.go
@@ -142,7 +142,7 @@ func TestCacheEngineExistingProjectNeverMoves(t *testing.T) {
 		if svc.Image != pin {
 			t.Errorf("image = %q, want the lock pin %q", svc.Image, pin)
 		}
-		wantCmd := []string{"sh", "-c", `exec redis-server --appendonly yes --protected-mode yes --requirepass "$$REDISCLI_AUTH" --maxclients 20`}
+		wantCmd := []string{"sh", "-c", redisPasswordScript("redis-server", 20)}
 		if got, _ := svc.Command.([]string); strings.Join(got, "\x00") != strings.Join(wantCmd, "\x00") {
 			t.Errorf("command = %q, want %q", svc.Command, wantCmd)
 		}
diff --git a/internal/compose/compose_extra_test.go b/internal/compose/compose_extra_test.go
index 2b35fda17..d6d18fd79 100644
--- a/internal/compose/compose_extra_test.go
+++ b/internal/compose/compose_extra_test.go
@@ -248,7 +248,7 @@ func TestBuildRedisService_WithPassword(t *testing.T) {
 	svc := g.buildRedisService()
 
 	cmd, ok := svc.Command.([]string)
-	if !ok || len(cmd) != 3 || cmd[0] != "sh" || !strings.Contains(cmd[2], `--requirepass "$$REDISCLI_AUTH"`) {
+	if !ok || len(cmd) != 3 || cmd[0] != "sh" || !strings.Contains(cmd[2], `requirepass "$$esc"`) || strings.Contains(cmd[2], "--requirepass") {
 		t.Errorf("Redis with password: command = %#v, want sh -c with requirepass from REDISCLI_AUTH", svc.Command)
 	}
 	if strings.Contains(strings.Join(cmd, " "), cfg.Redis.Password) {
diff --git a/internal/compose/secret_argv_expanded_test.go b/internal/compose/secret_argv_expanded_test.go
new file mode 100644
index 000000000..cdfe56b9f
--- /dev/null
+++ b/internal/compose/secret_argv_expanded_test.go
@@ -0,0 +1,97 @@
+package compose_test
+
+// secret_argv_expanded_test.go — D-0587 guard: the command a shell EXPANDS
+// inside the cache container carries no secret on its argv. secret_argv_test
+// checks the compose text; a `$$REDISCLI_AUTH` there is fine, yet `sh -c` turns
+// it into `--requirepass <value>` and host `ps` or /proc/<pid>/cmdline shows
+// it. This test runs the generated command with a stub server and reads the
+// argv the server really receives.
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/cli/internal/build"
+	"github.com/nself-org/cli/internal/compat/compattest"
+	"github.com/nself-org/cli/internal/compose"
+)
+
+// awkwardPassword holds every character the config line has to escape or the
+// shell could mangle.
+const awkwardPassword = "p\"a\\ss w$o`rd'x;#9"
+
+// runCacheCommand runs the sh -c script with a stub engine binary on PATH and
+// returns what the stub saw: its argv (one argument per line) and its stdin.
+func runCacheCommand(t *testing.T, server, script string) (argv, stdin string) {
+	t.Helper()
+	dir := t.TempDir()
+	stub := "#!/bin/sh\nprintf '%s\\n' \"$@\" > \"" + dir + "/argv\"\ncat > \"" + dir + "/stdin\"\n"
+	if err := os.WriteFile(filepath.Join(dir, server), []byte(stub), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	// compose turns $$ into $ before the container shell sees the script.
+	cmd := exec.Command("sh", "-c", strings.ReplaceAll(script, "$$", "$"))
+	cmd.Env = append(os.Environ(), "PATH="+dir+string(os.PathListSeparator)+os.Getenv("PATH"), "REDISCLI_AUTH="+awkwardPassword)
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("run %q: %v\n%s", script, err, out)
+	}
+	a, err := os.ReadFile(filepath.Join(dir, "argv"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	s, err := os.ReadFile(filepath.Join(dir, "stdin"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(a), string(s)
+}
+
+// TestExpandedCacheCommandNoSecretOnArgv: the expanded server argv carries no
+// part of the password and the server still receives it as a config line.
+func TestExpandedCacheCommandNoSecretOnArgv(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("needs a POSIX sh")
+	}
+	compattest.Set(t, false)
+	for _, cache := range []string{"redis", "valkey"} {
+		cfg := optionalSecretsConfig("meilisearch", setSecrets)
+		cfg.Redis.Engine = cache
+		cfg.Redis.Password = awkwardPassword
+		out, err := compose.NewGenerator(cfg).Generate()
+		if err != nil {
+			t.Fatalf("%s: Generate() error: %v", cache, err)
+		}
+		cmd := argvStrings(t, build.TemplateSecrets(out, build.SecretEnvMap(cfg)))["redis command"]
+		if len(cmd) != 3 || cmd[0] != "sh" || cmd[1] != "-c" {
+			t.Fatalf("%s: redis command = %q, want sh -c <script>", cache, cmd)
+		}
+		argv, stdin := runCacheCommand(t, cache+"-server", cmd[2])
+		if strings.Contains(argv, "pass") || strings.Contains(argv, "rd'x") || strings.Contains(argv, "requirepass") {
+			t.Errorf("%s: server argv carries the password:\n%s", cache, argv)
+		}
+		for _, want := range []string{"--appendonly", "--protected-mode", "--maxclients"} {
+			if !strings.Contains(argv, want) {
+				t.Errorf("%s: server argv lost %s:\n%s", cache, want, argv)
+			}
+		}
+		if want := "requirepass \"p\\\"a\\\\ss w$o`rd'x;#9\"\n"; stdin != want {
+			t.Errorf("%s: server stdin = %q, want the escaped config line %q", cache, stdin, want)
+		}
+	}
+}
+
+// TestExpandedCacheCommandControl proves the check can fail: the pre-D-0587
+// command puts the password on the server's argv.
+func TestExpandedCacheCommandControl(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("needs a POSIX sh")
+	}
+	argv, _ := runCacheCommand(t, "redis-server", `exec redis-server --appendonly yes --requirepass "$$REDISCLI_AUTH" --maxclients 50`)
+	if !strings.Contains(argv, awkwardPassword) {
+		t.Fatalf("control: the legacy command should expose the password on argv, got:\n%s", argv)
+	}
+}
diff --git a/internal/compose/secret_argv_test.go b/internal/compose/secret_argv_test.go
index 504a0daea..052aed8da 100644
--- a/internal/compose/secret_argv_test.go
+++ b/internal/compose/secret_argv_test.go
@@ -161,8 +161,8 @@ func TestNoSecretOnGeneratedArgv(t *testing.T) {
 			if got := argv["redis healthcheck.test"]; strings.Join(got, " ") != "CMD "+cache+"-cli ping" {
 				t.Errorf("%s/%s: redis healthcheck = %q, want %s-cli reading REDISCLI_AUTH", engine, cache, got, cache)
 			}
-			if got := strings.Join(argv["redis command"], " "); !strings.Contains(got, `exec `+cache+`-server `) || !strings.Contains(got, `--requirepass "$$REDISCLI_AUTH"`) {
-				t.Errorf("%s/%s: redis command = %q, want %s-server reading $$REDISCLI_AUTH", engine, cache, got, cache)
+			if got := strings.Join(argv["redis command"], " "); !strings.Contains(got, `exec `+cache+`-server `) || !strings.Contains(got, `requirepass "$$esc"`) || strings.Contains(got, "--requirepass") {
+				t.Errorf("%s/%s: redis command = %q, want %s-server reading the password from stdin", engine, cache, got, cache)
 			}
 		}
 	}
diff --git a/internal/compose/secret_literal_test.go b/internal/compose/secret_literal_test.go
index 6754b245e..76df78736 100644
--- a/internal/compose/secret_literal_test.go
+++ b/internal/compose/secret_literal_test.go
@@ -184,10 +184,10 @@ func TestOptionalServicesSecretRefsPerService(t *testing.T) {
 			"- http://localhost:8108/health",
 		}},
 		// Redis gets the password as REDISCLI_AUTH: redis-cli reads it itself
-		// and the shell expands $$REDISCLI_AUTH for redis-server (D-0282).
+		// and the shell feeds $$REDISCLI_AUTH to redis-server on stdin (D-0282, D-0587).
 		{"meilisearch", "redis", true, []string{
 			"REDISCLI_AUTH: ${REDIS_PASSWORD}",
-			`--requirepass "$$REDISCLI_AUTH"`,
+			`requirepass "$$esc"`,
 		}},
 		{"meilisearch", "minio", true, []string{"MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}"}},
 		{"meilisearch", "minio", false, []string{"MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:-}"}},

From d82c9cecd40784042b26366cf57ac04a3271fdcc Mon Sep 17 00:00:00 2001
From: Aric Camarata <aric.camarata@gmail.com>
Date: Sun, 25 Oct 2026 13:48:03 -0400
Subject: [PATCH 2/4] test(templates): make the entitlement no-write assertion
 observe cwd, HOME and TMPDIR (D-1171)

---
 internal/templates/clone/entitlement_test.go | 40 ++++++++++++++++++--
 1 file changed, 36 insertions(+), 4 deletions(-)

diff --git a/internal/templates/clone/entitlement_test.go b/internal/templates/clone/entitlement_test.go
index 4a95d221b..660722638 100644
--- a/internal/templates/clone/entitlement_test.go
+++ b/internal/templates/clone/entitlement_test.go
@@ -54,7 +54,40 @@ func required(t *testing.T, template string) []string {
 	return m.RequiredPlugins
 }
 
+// sandboxEntries points the working directory, HOME and TMPDIR at one fresh
+// directory and returns a function that lists what was created in it since.
+// Check takes no target path, so "writes nothing" can only be observed in the
+// places a stray write would land.
+func sandboxEntries(t *testing.T) func() []os.DirEntry {
+	t.Helper()
+	dir := t.TempDir()
+	t.Chdir(dir)
+	t.Setenv("HOME", dir)
+	t.Setenv("TMPDIR", dir)
+	return func() []os.DirEntry {
+		entries, err := os.ReadDir(dir)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return entries
+	}
+}
+
+// TestTemplateEntitlementNoWriteControl proves the sandbox sees a write made
+// from the licence callback, so the assertion in the E110 test can fail.
+func TestTemplateEntitlementNoWriteControl(t *testing.T) {
+	entries := sandboxEntries(t)
+	writer := func(_ context.Context, _ string) (bool, error) {
+		return false, os.WriteFile("stray", []byte("x"), 0o600)
+	}
+	Check(context.Background(), "discord-clone", required(t, "discord-clone"), fixtureCatalog(), writer)
+	if len(entries()) == 0 {
+		t.Fatal("sandbox missed a file written into the working directory")
+	}
+}
+
 func TestTemplateEntitlementE110NoWrite(t *testing.T) {
+	entries := sandboxEntries(t)
 	s := &spy{err: errors.New("no license key configured")}
 	rep := Check(context.Background(), "discord-clone", required(t, "discord-clone"), fixtureCatalog(), s.lic)
 	if len(rep.MissingLicence) != 4 || len(rep.Unknown) != 0 || len(rep.Unchecked) != 0 {
@@ -77,10 +110,9 @@ func TestTemplateEntitlementE110NoWrite(t *testing.T) {
 	if got := strings.Join(s.asked, ","); got != "family,clawde,claw" {
 		t.Errorf("bundles asked = %s, want family, clawde and claw once each", got)
 	}
-	// Check does no I/O: the scaffold target stays untouched.
-	dir := t.TempDir()
-	if entries, _ := os.ReadDir(dir); len(entries) != 0 {
-		t.Errorf("target not empty: %v", entries)
+	// Check does no I/O: nothing lands in the working directory, HOME or TMPDIR.
+	if got := entries(); len(got) != 0 {
+		t.Errorf("Check wrote %v", got)
 	}
 }
 

From 7b084eb1e77388c3e3a01be921b0b99e0372c0a9 Mon Sep 17 00:00:00 2001
From: Aric Camarata <aric.camarata@gmail.com>
Date: Sun, 25 Oct 2026 13:49:17 -0400
Subject: [PATCH 3/4] ci(json): add an error-json=<code> tag so rows that fail
 by design are envelope-checked (D-0864)

---
 cmd/commands/testdata/json/argv/README.md     |  1 +
 cmd/commands/testdata/json/argv/lifecycle.txt | 11 ++++++-----
 scripts/ci/json-conversion-check.sh           | 19 ++++++++++++++++++-
 3 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/cmd/commands/testdata/json/argv/README.md b/cmd/commands/testdata/json/argv/README.md
index 174dcfa43..3530b2670 100644
--- a/cmd/commands/testdata/json/argv/README.md
+++ b/cmd/commands/testdata/json/argv/README.md
@@ -5,6 +5,7 @@ Each `<fragment>.txt` file contains one command argv per line, without the leadi
 - `legacy-json` compares v1.4 `--json` stdout and exit status byte for byte against merge-base.
 - `volatile-json=timestamp` replaces only the top-level `timestamp` value in the raw legacy JSON bytes before comparison. The `health` row applies this automatically. Every other byte and the exit status must match.
 - `no-json=<reason>` skips the v1.5 envelope check for a command assigned to a later conversion ticket.
+- `error-json=<code>` marks a row that fails by design on the fixture (for example `start` without a compose file). Besides the human comparison, the head binary runs with `--json` in v1.5 mode and must exit non-zero, print exactly one error envelope that validates against `envelope.v1.schema.json`, and carry the named code (`E004`). It replaces `no-json` for such rows.
 - `human-skip=<reason>` skips the base versus head human stdout, stderr and exit comparison when a documented difference is expected.
 
 The harness checks human stdout, stderr and exit status in v1.4 and v1.5 modes, then requires a successful exit and exactly one valid v1 data envelope with the registered data shape for every row without `no-json`.
diff --git a/cmd/commands/testdata/json/argv/lifecycle.txt b/cmd/commands/testdata/json/argv/lifecycle.txt
index 467ddef31..ed7fd59b5 100644
--- a/cmd/commands/testdata/json/argv/lifecycle.txt
+++ b/cmd/commands/testdata/json/argv/lifecycle.txt
@@ -3,10 +3,11 @@
 # row goes first and writes AGENTS.md without a word, so the second row prints the
 # same stderr on every one of its runs. start, stop and restart cannot finish on
 # the fixture (no docker-compose.yml; --skip-build keeps start from generating
-# one), so each exits 1 the same way in base and head and is tagged no-json; their
-# success documents and their failures are covered by TestLifecycleJSON.
+# one), so each fails the same way in base and head and is tagged error-json with its
+# code, which the script checks as one valid error envelope; their success documents
+# and other failures are covered by TestLifecycleJSON.
 init --quiet --force --non-interactive --name smoke --domain example.test
 init --force --non-interactive --name smoke --domain example.test
-start --skip-build #| no-json=fixture-has-no-docker-compose-yml-see-json_lifecycle_test.go
-stop #| no-json=fixture-has-no-docker-compose-yml-see-json_lifecycle_test.go
-restart #| no-json=fixture-has-no-docker-compose-yml-see-json_lifecycle_test.go
+start --skip-build #| error-json=E004
+stop #| error-json=E400
+restart #| error-json=E400
diff --git a/scripts/ci/json-conversion-check.sh b/scripts/ci/json-conversion-check.sh
index 7cb4e4e97..11990a364 100644
--- a/scripts/ci/json-conversion-check.sh
+++ b/scripts/ci/json-conversion-check.sh
@@ -116,7 +116,24 @@ while IFS= read -r raw || [ -n "$raw" ]; do
       diff -u "$left" "$right" >&2 || true
     fi
   fi
-  if [[ "$tags" != *no-json=* ]]; then
+  if [[ "$tags" == *error-json=* ]]; then
+    # The row fails by design on the fixture: v1.5 --json must exit non-zero
+    # and print exactly one error envelope carrying the tagged code.
+    want_code="${tags#*error-json=}"; want_code="${want_code%%[[:space:]]*}"
+    run_one "$head_bin" 1 "--json" "$tmp/head-error" "${argv[@]}"
+    if ! [[ "$want_code" =~ ^E[0-9]{3}$ ]]; then
+      echo "FAIL $label: error-json tag needs a code like E004, got '$want_code'"; bad=1
+    elif [ "$(cat "$tmp/head-error.rc")" -eq 0 ]; then
+      echo "FAIL $label: v1.5 --json exited zero, want a failure with code $want_code"; bad=1
+    elif ! jq -e -s 'length == 1 and (.[0] | type == "object" and has("error") and (has("data") | not))' "$tmp/head-error.out" >/dev/null 2>&1; then
+      echo "FAIL $label: stdout is not exactly one error envelope"; bad=1
+    elif ! (cd "$repo_root" && "$tmp/jsonvalidate" -schema envelope.v1.schema.json "$tmp/head-error.out") >"$tmp/validator.out" 2>&1; then
+      echo "FAIL $label: error envelope invalid"; bad=1
+      cat "$tmp/validator.out" >&2
+    elif [ "$(jq -r '.error.code' "$tmp/head-error.out")" != "$want_code" ]; then
+      echo "FAIL $label: error code is $(jq -r '.error.code' "$tmp/head-error.out"), want $want_code"; bad=1
+    fi
+  elif [[ "$tags" != *no-json=* ]]; then
     run_one "$head_bin" 1 "--json" "$tmp/head-json" "${argv[@]}"
     if [ "$(cat "$tmp/head-json.rc")" -ne 0 ]; then
       echo "FAIL $label: v1.5 --json exited non-zero"; bad=1

From 4ab7a8709bc9485312e1af5e2b2bb49fc157095c Mon Sep 17 00:00:00 2001
From: Aric Camarata <aric.camarata@gmail.com>
Date: Sun, 25 Oct 2026 13:51:51 -0400
Subject: [PATCH 4/4] refactor(compose): build every container name with
 Config.ServiceContainerName and guard against hand-rolled copies (D-0130)

---
 cmd/commands/functions_deploy.go              |  2 +-
 cmd/commands/functions_logs.go                |  2 +-
 cmd/commands/start_containers.go              |  2 +-
 internal/build/orchestrator_build_compose.go  |  2 +-
 internal/builtin/admin/cmd_root.go            |  2 +-
 internal/compose/cache_service.go             |  2 +-
 internal/compose/container_name_guard_test.go | 55 +++++++++++++++++++
 internal/compose/core_services.go             |  4 +-
 internal/compose/core_services_auth_nginx.go  |  4 +-
 internal/compose/custom_services.go           |  2 +-
 internal/compose/object_storage.go            |  4 +-
 internal/compose/optional_services.go         |  4 +-
 internal/compose/optional_services_apps.go    |  4 +-
 internal/compose/optional_services_search.go  |  6 +-
 internal/exporter/dump.go                     |  2 +-
 15 files changed, 76 insertions(+), 21 deletions(-)
 create mode 100644 internal/compose/container_name_guard_test.go

diff --git a/cmd/commands/functions_deploy.go b/cmd/commands/functions_deploy.go
index 5b4507d16..b2b59e944 100644
--- a/cmd/commands/functions_deploy.go
+++ b/cmd/commands/functions_deploy.go
@@ -114,7 +114,7 @@ func runFunctionsDeploy(cmd *cobra.Command, args []string) error {
 	// Signal container reload.
 	cfg, _, loadErr := loadHealthConfig()
 	if loadErr == nil {
-		containerID := fmt.Sprintf("%s_functions", cfg.ProjectName)
+		containerID := cfg.ServiceContainerName("functions")
 		reloadCtx, cancel := context.WithTimeout(cmd.Context(), 10*time.Second)
 		defer cancel()
 		// nhost/functions watches for a .reload file touch.
diff --git a/cmd/commands/functions_logs.go b/cmd/commands/functions_logs.go
index 6565c5bba..c5bdb30b9 100644
--- a/cmd/commands/functions_logs.go
+++ b/cmd/commands/functions_logs.go
@@ -55,7 +55,7 @@ func runFunctionsLogs(cmd *cobra.Command, args []string) error {
 	cfg, _, cfgErr := loadHealthConfig()
 	containerID := "functions"
 	if cfgErr == nil {
-		containerID = fmt.Sprintf("%s_functions", cfg.ProjectName)
+		containerID = cfg.ServiceContainerName("functions")
 	}
 
 	dockerArgs := []string{"logs"}
diff --git a/cmd/commands/start_containers.go b/cmd/commands/start_containers.go
index 039faedd9..f2b30619b 100644
--- a/cmd/commands/start_containers.go
+++ b/cmd/commands/start_containers.go
@@ -182,7 +182,7 @@ func startPostgresPhase(ctx context.Context, opts startOpts, cfg *config.Config,
 	// Skip ComposeUp for an already healthy postgres unless a clean/fresh
 	// start cleared it. Compose may otherwise recreate it after config drift.
 	if !opts.cleanStart && !opts.fresh {
-		containerName := fmt.Sprintf("%s_postgres", cfg.ProjectName)
+		containerName := cfg.ServiceContainerName("postgres")
 		health, healthErr := docker.GetHealthStatus(ctx, containerName)
 		if healthErr == nil && postgresAlreadyRunning(health) {
 			sp.Success("PostgreSQL container already running and healthy")
diff --git a/internal/build/orchestrator_build_compose.go b/internal/build/orchestrator_build_compose.go
index 9076bd44d..dd0c52de7 100644
--- a/internal/build/orchestrator_build_compose.go
+++ b/internal/build/orchestrator_build_compose.go
@@ -54,7 +54,7 @@ func (st *buildState) generateCompose() error {
 	// ── Step 8.1: Warn if this regen would swap a running postgres image ──
 	// (cli#384 — advisory only, never blocks the build; see
 	// PostgresImageChangeWarning for the data-loss scenario this guards.)
-	postgresContainer := fmt.Sprintf("%s_postgres", st.cfg.ProjectName)
+	postgresContainer := st.cfg.ServiceContainerName("postgres")
 	generatedPostgresImage := compose.ResolveImage("postgres", compose.ResolvePostgresImage(st.cfg.Postgres))
 	// Plan mode skips it: the check runs `docker inspect`, a host effect.
 	if !st.planning() {
diff --git a/internal/builtin/admin/cmd_root.go b/internal/builtin/admin/cmd_root.go
index 7188b1ddb..21a1d1c78 100644
--- a/internal/builtin/admin/cmd_root.go
+++ b/internal/builtin/admin/cmd_root.go
@@ -34,7 +34,7 @@ func (r runner) adminContainerID() string {
 	if err != nil || cfg.ProjectName == "" {
 		return "nself_admin"
 	}
-	return fmt.Sprintf("%s_admin", cfg.ProjectName)
+	return cfg.ServiceContainerName("admin")
 }
 
 func rootCommand(r runner) *cobra.Command {
diff --git a/internal/compose/cache_service.go b/internal/compose/cache_service.go
index 9f5b6054f..e9f97482f 100644
--- a/internal/compose/cache_service.go
+++ b/internal/compose/cache_service.go
@@ -201,7 +201,7 @@ func (g *Generator) buildRedisService() ServiceConfig {
 
 	return ServiceConfig{
 		Image:         g.cacheImage(engine),
-		ContainerName: fmt.Sprintf("%s_redis", g.cfg.ProjectName),
+		ContainerName: g.cfg.ServiceContainerName("redis"),
 		Restart:       "unless-stopped",
 		User:          "999:999",
 		Networks:      []string{g.cfg.DockerNetwork},
diff --git a/internal/compose/container_name_guard_test.go b/internal/compose/container_name_guard_test.go
new file mode 100644
index 000000000..a354c2f3b
--- /dev/null
+++ b/internal/compose/container_name_guard_test.go
@@ -0,0 +1,55 @@
+package compose
+
+// container_name_guard_test.go — D-0130 guard: a service's container name is
+// built by config.Config.ServiceContainerName alone. A builder that formats
+// `<PROJECT_NAME>_<svc>` itself makes a naming change a dozen edits again.
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+// handRolledName matches a ContainerName field set from Sprintf("%s_<svc>", ...
+// ProjectName) or ProjectName + "_<svc>". Network and volume names share the
+// prefix but are not container names, so only ContainerName lines count.
+var handRolledName = regexp.MustCompile(`ContainerName\b.*("%s_[^"]*"\s*,[^)]*ProjectName|ProjectName\s*\+\s*"_)`)
+
+func TestContainerNamesComeFromOneHelper(t *testing.T) {
+	files, err := filepath.Glob("*.go")
+	if err != nil || len(files) == 0 {
+		t.Fatalf("no compose sources found: %v", err)
+	}
+	for _, f := range files {
+		if strings.HasSuffix(f, "_test.go") {
+			continue
+		}
+		src, err := os.ReadFile(f)
+		if err != nil {
+			t.Fatal(err)
+		}
+		for i, line := range strings.Split(string(src), "\n") {
+			if handRolledName.MatchString(line) {
+				t.Errorf("%s:%d builds a container name by hand, use cfg.ServiceContainerName: %s", f, i+1, strings.TrimSpace(line))
+			}
+		}
+	}
+}
+
+// TestHandRolledNamePatternControl proves the guard matches both shapes it
+// exists to stop.
+func TestHandRolledNamePatternControl(t *testing.T) {
+	for _, bad := range []string{
+		`ContainerName: fmt.Sprintf("%s_redis", g.cfg.ProjectName),`,
+		`ContainerName: cfg.ProjectName + "_postgres",`,
+	} {
+		if !handRolledName.MatchString(bad) {
+			t.Errorf("pattern misses %q", bad)
+		}
+	}
+	if handRolledName.MatchString(`ContainerName: g.cfg.ServiceContainerName("redis"),`) {
+		t.Error("pattern flags the helper call")
+	}
+}
diff --git a/internal/compose/core_services.go b/internal/compose/core_services.go
index 4d1b8f624..68a307d62 100644
--- a/internal/compose/core_services.go
+++ b/internal/compose/core_services.go
@@ -59,7 +59,7 @@ func (g *Generator) buildPostgresService() ServiceConfig {
 	}
 	return ServiceConfig{
 		Image:         image,
-		ContainerName: fmt.Sprintf("%s_postgres", cfg.ProjectName),
+		ContainerName: cfg.ServiceContainerName("postgres"),
 		Restart:       "unless-stopped",
 		Networks:      []string{cfg.DockerNetwork},
 		User:          user,
@@ -171,7 +171,7 @@ func (g *Generator) buildHasuraService() (ServiceConfig, error) {
 
 	return ServiceConfig{
 		Image:         hasuraImage(cfg.Hasura.Version),
-		ContainerName: fmt.Sprintf("%s_hasura", cfg.ProjectName),
+		ContainerName: cfg.ServiceContainerName("hasura"),
 		Restart:       "unless-stopped",
 		User:          "1001:1001",
 		Networks:      []string{cfg.DockerNetwork},
diff --git a/internal/compose/core_services_auth_nginx.go b/internal/compose/core_services_auth_nginx.go
index 500f55a23..30a3a0500 100644
--- a/internal/compose/core_services_auth_nginx.go
+++ b/internal/compose/core_services_auth_nginx.go
@@ -98,7 +98,7 @@ func (g *Generator) buildAuthService() (ServiceConfig, error) {
 	}
 	return ServiceConfig{
 		Image:         image,
-		ContainerName: fmt.Sprintf("%s_auth", cfg.ProjectName),
+		ContainerName: cfg.ServiceContainerName("auth"),
 		Restart:       "unless-stopped",
 		Networks:      []string{cfg.DockerNetwork},
 		DependsOn: map[string]DepOn{
@@ -146,7 +146,7 @@ func (g *Generator) buildNginxService(dc *DockerCompose) ServiceConfig {
 
 	return ServiceConfig{
 		Image:         ResolveImage("nginx", ImageRef("nginx", "")),
-		ContainerName: fmt.Sprintf("%s_nginx", cfg.ProjectName),
+		ContainerName: cfg.ServiceContainerName("nginx"),
 		Restart:       "unless-stopped",
 		// No User override on purpose. The nginx.conf this same tool generates
 		// declares `user nginx;` on line 4, which requires the MASTER process to
diff --git a/internal/compose/custom_services.go b/internal/compose/custom_services.go
index 98517888c..c8ff0218c 100644
--- a/internal/compose/custom_services.go
+++ b/internal/compose/custom_services.go
@@ -207,7 +207,7 @@ func (g *Generator) buildCustomService(cs config.CustomService) (ServiceConfig,
 	}
 
 	svc := ServiceConfig{
-		ContainerName: fmt.Sprintf("%s_%s", cfg.ProjectName, cs.Name),
+		ContainerName: cfg.ServiceContainerName(cs.Name),
 		Restart:       "unless-stopped",
 		Networks:      []string{cfg.DockerNetwork},
 		DependsOn: map[string]DepOn{
diff --git a/internal/compose/object_storage.go b/internal/compose/object_storage.go
index 8309ac353..67ad4d6e5 100644
--- a/internal/compose/object_storage.go
+++ b/internal/compose/object_storage.go
@@ -184,7 +184,7 @@ func (g *Generator) buildSeaweedService() (ServiceConfig, error) {
 	}
 	return ServiceConfig{
 		Image:         ResolveImage("seaweedfs", ImageRef("seaweedfs", os.Getenv("SEAWEEDFS_VERSION"))),
-		ContainerName: g.cfg.ProjectName + "_seaweedfs", Restart: "unless-stopped",
+		ContainerName: g.cfg.ServiceContainerName("seaweedfs"), Restart: "unless-stopped",
 		Networks: []string{g.cfg.DockerNetwork},
 		// The image's seaweed user (uid 1000) owns /data. CapDrop ALL removes root's
 		// DAC_OVERRIDE, so root could not write a fresh volume; run as that user.
@@ -224,7 +224,7 @@ func objectStorageKeyProblem(value string) string {
 func (g *Generator) buildSeaweedInit() ServiceConfig {
 	return ServiceConfig{
 		Image:         ResolveImage("seaweedfs", ImageRef("seaweedfs", os.Getenv("SEAWEEDFS_VERSION"))),
-		ContainerName: g.cfg.ProjectName + "_seaweedfs_init", Restart: "no",
+		ContainerName: g.cfg.ServiceContainerName("seaweedfs_init"), Restart: "no",
 		// Shares the server's network namespace: it reaches the master on 127.0.0.1 and
 		// needs no network or port of its own (the master and filer stay closed to the network).
 		NetworkMode: "service:seaweedfs",
diff --git a/internal/compose/optional_services.go b/internal/compose/optional_services.go
index bcaf3390c..cf6d2b0c2 100644
--- a/internal/compose/optional_services.go
+++ b/internal/compose/optional_services.go
@@ -25,7 +25,7 @@ func (g *Generator) buildMinioService() ServiceConfig {
 		// The minio entry in images.yaml is registry-qualified (docker.io/pgsty/minio);
 		// the Docker Hub minio/minio repository no longer exists (ADR 0028).
 		Image:         ResolveImage("minio", ImageRef("minio", version)),
-		ContainerName: fmt.Sprintf("%s_minio", g.cfg.ProjectName),
+		ContainerName: g.cfg.ServiceContainerName("minio"),
 		Restart:       "unless-stopped",
 		Networks:      []string{g.cfg.DockerNetwork},
 		Environment: map[string]string{
@@ -90,7 +90,7 @@ func (g *Generator) buildMailpitService() ServiceConfig {
 
 	return ServiceConfig{
 		Image:         ResolveImage("mailpit", ImageRef("mailpit", version)),
-		ContainerName: fmt.Sprintf("%s_mailpit", g.cfg.ProjectName),
+		ContainerName: g.cfg.ServiceContainerName("mailpit"),
 		Restart:       "unless-stopped",
 		User:          "1000:1000",
 		Networks:      []string{g.cfg.DockerNetwork},
diff --git a/internal/compose/optional_services_apps.go b/internal/compose/optional_services_apps.go
index 40c14ad64..c09967b43 100644
--- a/internal/compose/optional_services_apps.go
+++ b/internal/compose/optional_services_apps.go
@@ -57,7 +57,7 @@ func (g *Generator) buildAdminService() ServiceConfig {
 
 	return ServiceConfig{
 		Image:         ResolveImage("admin", ImageRef("admin", version)),
-		ContainerName: fmt.Sprintf("%s_admin", g.cfg.ProjectName),
+		ContainerName: g.cfg.ServiceContainerName("admin"),
 		Restart:       "unless-stopped",
 		User:          adminUser,
 		GroupAdd:      groupAdd,
@@ -145,7 +145,7 @@ func (g *Generator) buildFunctionsService() ServiceConfig {
 
 	svc := ServiceConfig{
 		Image:         image,
-		ContainerName: fmt.Sprintf("%s_functions", g.cfg.ProjectName),
+		ContainerName: g.cfg.ServiceContainerName("functions"),
 		Restart:       "unless-stopped",
 		Networks:      []string{g.cfg.DockerNetwork},
 		DependsOn: map[string]DepOn{
diff --git a/internal/compose/optional_services_search.go b/internal/compose/optional_services_search.go
index e7ea6191a..bd28e9b9b 100644
--- a/internal/compose/optional_services_search.go
+++ b/internal/compose/optional_services_search.go
@@ -16,7 +16,7 @@ import (
 func (g *Generator) buildMeiliInitService() ServiceConfig {
 	return ServiceConfig{
 		Image:         ResolveImage("meilisearch-init", ImageRef("meilisearch-init", "")),
-		ContainerName: fmt.Sprintf("%s_meilisearch_init", g.cfg.ProjectName),
+		ContainerName: g.cfg.ServiceContainerName("meilisearch_init"),
 		Restart:       "no",
 		User:          "root",
 		Networks:      []string{g.cfg.DockerNetwork},
@@ -51,7 +51,7 @@ func (g *Generator) buildMeiliService() ServiceConfig {
 
 	return ServiceConfig{
 		Image:         ResolveImage("meilisearch", ImageRef("meilisearch", version)),
-		ContainerName: fmt.Sprintf("%s_meilisearch", g.cfg.ProjectName),
+		ContainerName: g.cfg.ServiceContainerName("meilisearch"),
 		Restart:       "unless-stopped",
 		User:          "1000:1000",
 		Networks:      []string{g.cfg.DockerNetwork},
@@ -101,7 +101,7 @@ func (g *Generator) buildTypesenseService() ServiceConfig {
 
 	return ServiceConfig{
 		Image:         ResolveImage("typesense", ImageRef("typesense", version)),
-		ContainerName: fmt.Sprintf("%s_typesense", g.cfg.ProjectName),
+		ContainerName: g.cfg.ServiceContainerName("typesense"),
 		Restart:       "unless-stopped",
 		Networks:      []string{g.cfg.DockerNetwork},
 		Environment: map[string]string{
diff --git a/internal/exporter/dump.go b/internal/exporter/dump.go
index 58ca1824d..c495a56a4 100644
--- a/internal/exporter/dump.go
+++ b/internal/exporter/dump.go
@@ -21,7 +21,7 @@ var inspectContainer = docker.InspectContainer
 // Purpose: run project-major Postgres tools without password argv.
 // Inputs: private stage, args, snapshot. Outputs: tool files. Constraints: uid:gid.
 func tool(ctx context.Context, cfg *config.Config, stage string, args []string) error {
-	container, err := inspectContainer(ctx, cfg.ProjectName+"_postgres")
+	container, err := inspectContainer(ctx, cfg.ServiceContainerName("postgres"))
 	if err != nil {
 		return safeFailure("resolve postgres image")
 	}