Merge branch 'main' into fix/s8-bind-loopback-dev

Merge pull request 'fix(ci): lowercase 'molecule-ai/' in cross-repo workflow refs' (#17 ) from fix/lowercase-org-slug into main
fix(ci): lowercase 'molecule-ai/' in cross-repo workflow refs
2026-05-07 11:25:20 +00:00 · 2026-05-07 10:38:12 +00:00 · 2026-05-07 01:00:10 -07:00 · 2026-05-06 22:29:24 -07:00 · 2026-05-07 00:19:40 +00:00 · 2026-05-06 16:43:42 -07:00
19 changed files with 427 additions and 49 deletions
@@ -1,7 +1,7 @@
 name: Block internal-flavored paths

 # Hard CI gate. Internal content (positioning, competitive briefs, sales
-# playbooks, PMM/press drip, draft campaigns) lives in Molecule-AI/internal —
+# playbooks, PMM/press drip, draft campaigns) lives in molecule-ai/internal —
 # this public monorepo must never re-acquire those paths. CEO directive
 # 2026-04-23 after a fleet-wide audit found 79 internal files leaked here.
 #
@@ -135,7 +135,7 @@ jobs:
            echo "::error::Forbidden internal-flavored paths detected:"
            printf "$OFFENDING"
            echo ""
-            echo "These paths belong in Molecule-AI/internal, not this public repo."
+            echo "These paths belong in molecule-ai/internal, not this public repo."
            echo "See docs/internal-content-policy.md for canonical locations."
            echo ""
            echo "If your file is genuinely public-facing (e.g. a blog post"
@@ -108,7 +108,7 @@ jobs:
              echo
              echo "One or more canary secrets are unset (\`CANARY_TENANT_URLS\`, \`CANARY_ADMIN_TOKENS\`, \`CANARY_CP_SHARED_SECRET\`)."
              echo "Phase 2 canary fleet has not been stood up yet —"
-              echo "see [canary-tenants.md](https://github.com/Molecule-AI/molecule-controlplane/blob/main/docs/canary-tenants.md)."
+              echo "see [canary-tenants.md](https://github.com/molecule-ai/molecule-controlplane/blob/main/docs/canary-tenants.md)."
              echo
              echo "**Skipped — promote-to-latest will NOT auto-fire.** Dispatch \`promote-latest.yml\` manually when ready."
            } >> "$GITHUB_STEP_SUMMARY"
@@ -87,7 +87,7 @@ jobs:
        run: go mod download
      - if: needs.changes.outputs.platform == 'true'
        run: go build ./cmd/server
-      # CLI (molecli) moved to standalone repo: github.com/Molecule-AI/molecule-cli
+      # CLI (molecli) moved to standalone repo: github.com/molecule-ai/molecule-cli
      - if: needs.changes.outputs.platform == 'true'
        run: go vet ./... || true
      - if: needs.changes.outputs.platform == 'true'
@@ -165,7 +165,7 @@ jobs:
              # Strip the package-import prefix so we can match .coverage-allowlist.txt
              # entries written as paths relative to workspace-server/.
              # Handle both module paths: platform/workspace-server/... and platform/...
-              rel=$(echo "$file" | sed 's|^github.com/Molecule-AI/molecule-monorepo/platform/workspace-server/||; s|^github.com/Molecule-AI/molecule-monorepo/platform/||')
+              rel=$(echo "$file" | sed 's|^github.com/molecule-ai/molecule-monorepo/platform/workspace-server/||; s|^github.com/molecule-ai/molecule-monorepo/platform/||')

              if echo "$ALLOWLIST" | grep -qxF "$rel"; then
                echo "::warning file=workspace-server/$rel::Critical file at ${pct}% coverage (allowlisted, #1823) — fix before expiry."
@@ -243,8 +243,8 @@ jobs:
          if-no-files-found: warn

  # MCP Server + SDK removed from CI — now in standalone repos:
-  # - github.com/Molecule-AI/molecule-mcp-server (npm CI)
-  # - github.com/Molecule-AI/molecule-sdk-python (PyPI CI)
+  # - github.com/molecule-ai/molecule-mcp-server (npm CI)
+  # - github.com/molecule-ai/molecule-sdk-python (PyPI CI)

  # e2e-api job moved to .github/workflows/e2e-api.yml (issue #458).
  # It now has workflow-level concurrency (cancel-in-progress: false) so
@@ -434,5 +434,5 @@ jobs:
          fi

      # SDK + plugin validation moved to standalone repo:
-      # github.com/Molecule-AI/molecule-sdk-python
+      # github.com/molecule-ai/molecule-sdk-python

@@ -62,7 +62,7 @@ jobs:
        if: matrix.language == 'go'
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
-          repository: Molecule-AI/molecule-ai-plugin-github-app-auth
+          repository: molecule-ai/molecule-ai-plugin-github-app-auth
          path: molecule-ai-plugin-github-app-auth
          token: ${{ secrets.PLUGIN_REPO_PAT || secrets.GITHUB_TOKEN }}

@@ -102,7 +102,7 @@ jobs:
        if: needs.detect-changes.outputs.run == 'true'
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
-          repository: Molecule-AI/molecule-ai-plugin-github-app-auth
+          repository: molecule-ai/molecule-ai-plugin-github-app-auth
          path: molecule-ai-plugin-github-app-auth
          token: ${{ secrets.PLUGIN_REPO_PAT || secrets.GITHUB_TOKEN }}

@@ -19,4 +19,4 @@ permissions:

 jobs:
  disable-auto-merge-on-push:
-    uses: Molecule-AI/molecule-ci/.github/workflows/disable-auto-merge-on-push.yml@main
+    uses: molecule-ai/molecule-ci/.github/workflows/disable-auto-merge-on-push.yml@main
@@ -25,7 +25,7 @@ name: publish-runtime
 #   3. Publishes to PyPI via the PyPA Trusted Publisher action (OIDC).
 #      No static API token is stored — PyPI verifies the workflow's
 #      OIDC claim against the trusted-publisher config registered for
-#      molecule-ai-workspace-runtime (Molecule-AI/molecule-core,
+#      molecule-ai-workspace-runtime (molecule-ai/molecule-core,
 #      publish-runtime.yml, environment pypi-publish).
 #
 # After publish: the 8 template repos pick up the new version on their
@@ -166,7 +166,7 @@ jobs:

      - name: Publish to PyPI (Trusted Publisher / OIDC)
        # PyPI side is configured: project molecule-ai-workspace-runtime →
-        # publisher Molecule-AI/molecule-core, workflow publish-runtime.yml,
+        # publisher molecule-ai/molecule-core, workflow publish-runtime.yml,
        # environment pypi-publish. The action mints a short-lived OIDC
        # token and exchanges it for a PyPI upload credential — no static
        # API token in this repo's secrets.
@@ -342,7 +342,7 @@ jobs:
          TEMPLATES="claude-code hermes openclaw codex langgraph crewai autogen deepagents gemini-cli"
          FAILED=""
          for tpl in $TEMPLATES; do
-            REPO="Molecule-AI/molecule-ai-workspace-template-$tpl"
+            REPO="molecule-ai/molecule-ai-workspace-template-$tpl"
            STATUS=$(curl -sS -o /tmp/dispatch.out -w "%{http_code}" \
              -X POST "https://api.github.com/repos/$REPO/dispatches" \
              -H "Authorization: Bearer $DISPATCH_TOKEN" \
@@ -80,12 +80,12 @@ jobs:
        #
        # Uses a fine-grained PAT (PLUGIN_REPO_PAT) because the plugin repo
        # is private and the default GITHUB_TOKEN is scoped to THIS repo.
-        # The PAT needs Contents:Read on Molecule-AI/molecule-ai-plugin-
+        # The PAT needs Contents:Read on molecule-ai/molecule-ai-plugin-
        # github-app-auth. Falls back to the default token for the (rare)
        # case where an operator made the plugin repo public.
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
-          repository: Molecule-AI/molecule-ai-plugin-github-app-auth
+          repository: molecule-ai/molecule-ai-plugin-github-app-auth
          path: molecule-ai-plugin-github-app-auth
          token: ${{ secrets.PLUGIN_REPO_PAT || secrets.GITHUB_TOKEN }}

@@ -9,7 +9,7 @@ name: redeploy-tenants-on-main
 #
 # This workflow closes the gap by calling the control-plane admin
 # endpoint that performs a canary-first, batched, health-gated rolling
-# redeploy across every live tenant. Implemented in Molecule-AI/
+# redeploy across every live tenant. Implemented in molecule-ai/
 # molecule-controlplane as POST /cp/admin/tenants/redeploy-fleet
 # (feat/tenant-auto-redeploy, landing alongside this workflow).
 #
@@ -146,7 +146,7 @@ jobs:

      - name: Call CP redeploy-fleet
        # CP_ADMIN_API_TOKEN must be set as a repo/org secret on
-        # Molecule-AI/molecule-core, matching the staging/prod CP's
+        # molecule-ai/molecule-core, matching the staging/prod CP's
        # CP_ADMIN_API_TOKEN env. Stored in Railway, mirrored to this
        # repo's secrets for CI.
        env:
@@ -97,7 +97,7 @@ jobs:

      - name: Call staging-CP redeploy-fleet
        # CP_STAGING_ADMIN_API_TOKEN must be set as a repo/org secret
-        # on Molecule-AI/molecule-core, matching staging-CP's
+        # on molecule-ai/molecule-core, matching staging-CP's
        # CP_ADMIN_API_TOKEN env var (visible in Railway controlplane
        # / staging environment). Stored separately from the prod
        # CP_ADMIN_API_TOKEN so a leak of one doesn't auth the other.
@@ -96,7 +96,7 @@ jobs:
            --body "$(cat <<'BODY'
          [retarget-bot] This PR was opened against `main` and has been retargeted to `staging` automatically.

-          **Why:** per [SHARED_RULES rule 8](https://github.com/Molecule-AI/molecule-ai-org-template-molecule-dev/blob/main/SHARED_RULES.md), all feature work targets `staging` first; the CEO promotes `staging → main` separately.
+          **Why:** per [SHARED_RULES rule 8](https://github.com/molecule-ai/molecule-ai-org-template-molecule-dev/blob/main/SHARED_RULES.md), all feature work targets `staging` first; the CEO promotes `staging → main` separately.

          **What changed:** just the base branch — no code change. CI will re-run against `staging`. If you get merge conflicts, rebase on `staging`.

@@ -12,7 +12,7 @@ name: Secret scan
 #
 #   jobs:
 #     secret-scan:
-#       uses: Molecule-AI/molecule-core/.github/workflows/secret-scan.yml@staging
+#       uses: molecule-ai/molecule-core/.github/workflows/secret-scan.yml@staging
 #
 # Pin to @staging not @main — staging is the active default branch,
 # main lags via the staging-promotion workflow. Updates ride along
@@ -0,0 +1,89 @@
+package main
+
+import "testing"
+
+// TestResolveBindHost pins the precedence: BIND_ADDR explicit > dev-mode
+// fail-open default of 127.0.0.1 > production-shape empty (all interfaces).
+//
+// Mutation-test invariant: removing the IsDevModeFailOpen() branch makes
+// "no_bindaddr_devmode_unset_admin" fail (returns "" instead of "127.0.0.1").
+// Removing the BIND_ADDR branch makes "explicit_bindaddr_*" cases fail.
+func TestResolveBindHost(t *testing.T) {
+	cases := []struct {
+		name       string
+		bindAddr   string
+		adminToken string
+		molEnv     string
+		want       string
+	}{
+		{
+			name:       "no_bindaddr_devmode_unset_admin",
+			bindAddr:   "",
+			adminToken: "",
+			molEnv:     "dev",
+			want:       "127.0.0.1",
+		},
+		{
+			name:       "no_bindaddr_devmode_unset_admin_full_word",
+			bindAddr:   "",
+			adminToken: "",
+			molEnv:     "development",
+			want:       "127.0.0.1",
+		},
+		{
+			name:       "no_bindaddr_admin_set_in_dev_env",
+			bindAddr:   "",
+			adminToken: "secret",
+			molEnv:     "dev",
+			want:       "", // ADMIN_TOKEN flips IsDevModeFailOpen to false → all interfaces
+		},
+		{
+			name:       "no_bindaddr_production_env",
+			bindAddr:   "",
+			adminToken: "",
+			molEnv:     "production",
+			want:       "", // production is not a dev value → all interfaces
+		},
+		{
+			name:       "no_bindaddr_unset_env",
+			bindAddr:   "",
+			adminToken: "",
+			molEnv:     "",
+			want:       "", // unset MOLECULE_ENV → not dev → all interfaces
+		},
+		{
+			name:       "explicit_bindaddr_loopback_overrides_devmode",
+			bindAddr:   "127.0.0.1",
+			adminToken: "",
+			molEnv:     "dev",
+			want:       "127.0.0.1",
+		},
+		{
+			name:       "explicit_bindaddr_wildcard_overrides_devmode_default",
+			bindAddr:   "0.0.0.0",
+			adminToken: "",
+			molEnv:     "dev",
+			want:       "0.0.0.0",
+		},
+		{
+			name:       "explicit_bindaddr_in_production",
+			bindAddr:   "10.0.5.7",
+			adminToken: "secret",
+			molEnv:     "production",
+			want:       "10.0.5.7",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Setenv("BIND_ADDR", tc.bindAddr)
+			t.Setenv("ADMIN_TOKEN", tc.adminToken)
+			t.Setenv("MOLECULE_ENV", tc.molEnv)
+			got := resolveBindHost()
+			if got != tc.want {
+				t.Errorf("resolveBindHost() = %q, want %q (BIND_ADDR=%q ADMIN_TOKEN=%q MOLECULE_ENV=%q)",
+					got, tc.want, tc.bindAddr, tc.adminToken, tc.molEnv)
+			}
+		})
+	}
+}
@@ -19,6 +19,7 @@ import (
 	"github.com/Molecule-AI/molecule-monorepo/platform/internal/handlers"
 	"github.com/Molecule-AI/molecule-monorepo/platform/internal/imagewatch"
 	memwiring "github.com/Molecule-AI/molecule-monorepo/platform/internal/memory/wiring"
+	"github.com/Molecule-AI/molecule-monorepo/platform/internal/middleware"
 	"github.com/Molecule-AI/molecule-monorepo/platform/internal/pendinguploads"
 	"github.com/Molecule-AI/molecule-monorepo/platform/internal/provisioner"
 	"github.com/Molecule-AI/molecule-monorepo/platform/internal/registry"
@@ -337,15 +338,23 @@ func main() {
 	// Router
 	r := router.Setup(hub, broadcaster, prov, platformURL, configsDir, wh, channelMgr, memBundle)

-	// HTTP server with graceful shutdown
+	// HTTP server with graceful shutdown.
+	//
+	// Bind host: in dev-mode (no ADMIN_TOKEN, MOLECULE_ENV=dev|development)
+	// the AdminAuth chain fails open by design; pairing that with a wildcard
+	// bind would expose unauth /workspaces to any same-LAN peer. Default to
+	// loopback when fail-open is active. Operators who need LAN exposure set
+	// BIND_ADDR=0.0.0.0 explicitly. Production (ADMIN_TOKEN set) is unchanged.
+	// See molecule-core#7.
+	bindHost := resolveBindHost()
 	srv := &http.Server{
-		Addr:    fmt.Sprintf(":%s", port),
+		Addr:    fmt.Sprintf("%s:%s", bindHost, port),
 		Handler: r,
 	}

 	// Start server in goroutine
 	go func() {
-		log.Printf("Platform starting on :%s", port)
+		log.Printf("Platform starting on %s:%s (dev-mode-fail-open=%v)", bindHost, port, middleware.IsDevModeFailOpen())
 		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
 			log.Fatalf("Server failed: %v", err)
 		}
@@ -380,6 +389,29 @@ func envOr(key, fallback string) string {
 	return fallback
 }

+// resolveBindHost picks the listener interface for the HTTP server.
+//
+// Precedence:
+//  1. BIND_ADDR — explicit operator override (any value, including "0.0.0.0").
+//  2. dev-mode fail-open active → "127.0.0.1" (loopback only).
+//  3. otherwise → "" (Go binds every interface; existing prod/self-host shape).
+//
+// Coupling the loopback default to middleware.IsDevModeFailOpen() means the
+// two safety levers — bind narrowness and auth strength — move together. A
+// production deploy (ADMIN_TOKEN set) keeps binding to all interfaces because
+// the auth chain is doing its job; a dev Mac (no ADMIN_TOKEN, MOLECULE_ENV=dev)
+// is reachable only via loopback because the auth chain is fail-open. See
+// molecule-core#7 for the original LAN exposure finding.
+func resolveBindHost() string {
+	if v := os.Getenv("BIND_ADDR"); v != "" {
+		return v
+	}
+	if middleware.IsDevModeFailOpen() {
+		return "127.0.0.1"
+	}
+	return ""
+}
+
 func findConfigsDir() string {
 	candidates := []string{
 		"workspace-configs-templates",
@@ -56,10 +56,17 @@ type RefreshResult struct {
 	Recreated []string `json:"recreated"`
 }

-// TemplateImageRef returns the canonical GHCR ref for a runtime's template
-// image. Single source of truth shared with imagewatch.
+// TemplateImageRef returns the canonical image ref for a runtime's template,
+// using the configured registry (provisioner.RegistryPrefix()) and the
+// moving `:latest` tag. Single source of truth shared with imagewatch.
+//
+// Defaults to ghcr.io/molecule-ai/workspace-template-<runtime>:latest
+// (upstream OSS). When MOLECULE_IMAGE_REGISTRY is set in the environment
+// (typically the AWS ECR mirror in production), this returns the prefixed
+// equivalent so admin operations and image-watch checks hit the same
+// registry the provisioner pulls from.
 func TemplateImageRef(runtime string) string {
-	return fmt.Sprintf("ghcr.io/molecule-ai/workspace-template-%s:latest", runtime)
+	return fmt.Sprintf("%s/workspace-template-%s:latest", provisioner.RegistryPrefix(), runtime)
 }

 // ghcrAuthHeader returns the base64-encoded JSON auth payload Docker's
@@ -31,11 +31,25 @@ import (
 // tests pin the helper's three observable behaviors plus an AST gate
 // that catches future re-introductions of the un-checked INSERT.

+// lookupChildSQLRE anchors the sqlmock ExpectQuery on every load-bearing
+// token of lookupExistingChild's SELECT (org_import.go:639-645). A loose
+// substring match (the prior shape, just `SELECT id FROM workspaces`)
+// would silent-pass a regression that drops `IS NOT DISTINCT FROM`
+// (breaks NULL-parent matching), drops `parent_id` entirely (hijacks
+// siblings of the same name across different parents), or drops the
+// `status != 'removed'` filter (blocks re-import after Collapse).
+// RFC #2872 Important-2.
+//
+// The four anchored tokens are exactly the predicates the bug shapes
+// would tamper with. Whitespace is `\s+` so a future formatter pass
+// doesn't churn this string.
+const lookupChildSQLRE = `(?s)SELECT id FROM workspaces\s+WHERE name = \$1\s+AND parent_id IS NOT DISTINCT FROM \$2\s+AND status != 'removed'`
+
 func TestLookupExistingChild_NotFound_ReturnsFalseNoError(t *testing.T) {
 	mock := setupTestDB(t)
 	// 0-row result → driver returns sql.ErrNoRows on Scan.
 	parent := "parent-1"
-	mock.ExpectQuery(`SELECT id FROM workspaces`).
+	mock.ExpectQuery(lookupChildSQLRE).
 		WithArgs("Alpha", &parent).
 		WillReturnRows(sqlmock.NewRows([]string{"id"}))

@@ -56,7 +70,7 @@ func TestLookupExistingChild_NotFound_ReturnsFalseNoError(t *testing.T) {
 func TestLookupExistingChild_Found_ReturnsIDAndTrue(t *testing.T) {
 	mock := setupTestDB(t)
 	parent := "parent-1"
-	mock.ExpectQuery(`SELECT id FROM workspaces`).
+	mock.ExpectQuery(lookupChildSQLRE).
 		WithArgs("Alpha", &parent).
 		WillReturnRows(sqlmock.NewRows([]string{"id"}).AddRow("ws-existing-uuid"))

@@ -79,7 +93,7 @@ func TestLookupExistingChild_NilParent_MatchesRoot(t *testing.T) {
 	// a plain `=` would never match a NULL row. Pin that roots
 	// (parent_id=NULL) are still found by the lookup.
 	mock := setupTestDB(t)
-	mock.ExpectQuery(`SELECT id FROM workspaces`).
+	mock.ExpectQuery(lookupChildSQLRE).
 		WithArgs("RootAgent", (*string)(nil)).
 		WillReturnRows(sqlmock.NewRows([]string{"id"}).AddRow("ws-root-uuid"))

@@ -102,7 +116,7 @@ func TestLookupExistingChild_DBError_Propagates(t *testing.T) {
 	mock := setupTestDB(t)
 	parent := "parent-1"
 	connFail := errors.New("simulated postgres unavailable")
-	mock.ExpectQuery(`SELECT id FROM workspaces`).
+	mock.ExpectQuery(lookupChildSQLRE).
 		WithArgs("Alpha", &parent).
 		WillReturnError(connFail)

@@ -137,7 +151,7 @@ func TestLookupExistingChild_WrappedNoRows_TreatedAsNotFound(t *testing.T) {
 	mock := setupTestDB(t)
 	parent := "parent-1"
 	wrapped := fmt.Errorf("driver-wrapped: %w", sql.ErrNoRows)
-	mock.ExpectQuery(`SELECT id FROM workspaces`).
+	mock.ExpectQuery(lookupChildSQLRE).
 		WithArgs("Alpha", &parent).
 		WillReturnError(wrapped)

@@ -35,36 +35,37 @@ import (
 // drift-risk #6.
 var ErrNoBackend = errors.New("provisioner: no backend configured (zero-valued receiver)")

-// RuntimeImages maps runtime names to their Docker image refs on GHCR.
+// RuntimeImages maps runtime names to their Docker image refs.
 // Each standalone template repo publishes its image via the reusable
 // publish-template-image workflow in molecule-ci on every main merge.
 // The provisioner pulls these on demand (see ensureImageLocal) — no
 // pre-build step on the tenant host.
 //
+// The registry prefix is determined by RegistryPrefix() in registry.go;
+// defaults to ghcr.io/molecule-ai (upstream OSS) and is overridden via the
+// MOLECULE_IMAGE_REGISTRY env var in production tenants that mirror to
+// AWS ECR or another registry. The map is computed at package init and
+// captures whatever prefix was active then.
+//
 // Legacy local-build path (`docker build -t workspace-template:<runtime>`
 // via scripts/build-images.sh) is still supported for development:
 // when a bare `workspace-template:<runtime>` image is present locally,
 // Docker's image resolver matches it before any pull is attempted. Set
 // the env var WORKSPACE_IMAGE_LOCAL_OVERRIDE=1 (enforced by callers) to
 // short-circuit pulls entirely if needed.
-var RuntimeImages = map[string]string{
-	"langgraph":   "ghcr.io/molecule-ai/workspace-template-langgraph:latest",
-	"claude-code": "ghcr.io/molecule-ai/workspace-template-claude-code:latest",
-	"openclaw":    "ghcr.io/molecule-ai/workspace-template-openclaw:latest",
-	"deepagents":  "ghcr.io/molecule-ai/workspace-template-deepagents:latest",
-	"crewai":      "ghcr.io/molecule-ai/workspace-template-crewai:latest",
-	"autogen":     "ghcr.io/molecule-ai/workspace-template-autogen:latest",
-	"hermes":      "ghcr.io/molecule-ai/workspace-template-hermes:latest",     // Hermes (Nous Research) — real hermes-agent behind A2A bridge
-	"gemini-cli":  "ghcr.io/molecule-ai/workspace-template-gemini-cli:latest", // Google Gemini CLI
-}
+var RuntimeImages = computeRuntimeImages()
+
+// DefaultImage is the fallback workspace Docker image (langgraph is the
+// most common runtime). Computed via RegistryPrefix() so the prefix
+// override applies to the fallback path too.
+//
+// NOTE: Every runtime MUST have an entry in knownRuntimes (registry.go).
+// If a runtime is missing, it falls back to DefaultImage which may have
+// wrong deps. Add new runtimes to knownRuntimes AND create the standalone
+// template repo.
+var DefaultImage = RuntimeImage(defaultRuntime)

 const (
-	// DefaultImage is the fallback workspace Docker image (langgraph is the most common runtime).
-	DefaultImage = "ghcr.io/molecule-ai/workspace-template-langgraph:latest"
-	// NOTE: Every runtime MUST have an entry in RuntimeImages above. If a runtime is missing,
-	// it falls back to DefaultImage which may have wrong deps. Add new runtimes to both
-	// RuntimeImages AND create the standalone template repo.
-
 	// DefaultNetwork is the Docker network workspaces join.
 	DefaultNetwork = "molecule-monorepo-net"

@@ -0,0 +1,95 @@
+package provisioner
+
+import (
+	"fmt"
+	"os"
+)
+
+// defaultRegistryPrefix is the upstream OSS face for all workspace template
+// images. Self-hosted Molecule deployments without the MOLECULE_IMAGE_REGISTRY
+// override pull from here.
+const defaultRegistryPrefix = "ghcr.io/molecule-ai"
+
+// knownRuntimes is the canonical list of workspace template runtimes shipped
+// in main. Any runtime added here MUST also have a standalone template repo
+// (Molecule-AI/molecule-ai-workspace-template-<name>) and an entry in the
+// publish-template-image workflow that builds it.
+//
+// Order matters for deterministic test snapshots; keep alphabetical.
+var knownRuntimes = []string{
+	"autogen",
+	"claude-code",
+	"codex",
+	"crewai",
+	"deepagents",
+	"gemini-cli",
+	"hermes",
+	"langgraph",
+	"openclaw",
+}
+
+// defaultRuntime is the fallback when a workspace's config doesn't specify a
+// runtime. Picked because LangGraph is the most common in our org templates
+// and has the smallest "first impression" cold-start surface.
+const defaultRuntime = "langgraph"
+
+// RegistryPrefix returns the registry prefix all workspace-template image
+// references should use. Defaults to ghcr.io/molecule-ai (the upstream OSS
+// face) and is overridden by the MOLECULE_IMAGE_REGISTRY env var in
+// production tenants where we mirror images to a private registry.
+//
+// The override is set at deploy time (Railway env, EC2 user-data) — never
+// from user-supplied input — so the value is trusted by the time it reaches
+// this code. Validation is deliberately minimal: an operator-supplied
+// prefix that points at a registry the EC2 can't authenticate to will fail
+// loudly at docker-pull time, which is the right blast radius.
+//
+// Example values:
+//
+//	(unset)                                              → ghcr.io/molecule-ai (OSS default)
+//	"123456789012.dkr.ecr.us-east-2.amazonaws.com/molecule-ai"  → AWS ECR mirror
+//	"git.moleculesai.app/molecule-ai"                    → self-hosted Gitea Container Registry (future)
+//
+// Auth is registry-specific and configured outside this function:
+//   - GHCR: GHCR_USER/GHCR_TOKEN env vars consumed by ghcrAuthHeader()
+//   - ECR: docker credential helper (amazon-ecr-credential-helper) configured
+//     in EC2 user-data; ~/.docker/config.json has credHelpers entry; the
+//     daemon resolves auth automatically on every pull.
+func RegistryPrefix() string {
+	if v := os.Getenv("MOLECULE_IMAGE_REGISTRY"); v != "" {
+		return v
+	}
+	return defaultRegistryPrefix
+}
+
+// RuntimeImage returns the canonical image reference for the given runtime,
+// using the current RegistryPrefix() and the moving `:latest` tag.
+//
+// For SHA-pinned references (production thin-AMI launches), the
+// runtime_image_pins lookup in handlers/runtime_image_pin.go strips the
+// `:latest` suffix and appends an immutable `@sha256:<digest>` from the DB.
+// That code path naturally inherits any RegistryPrefix() change because it
+// reads from RuntimeImages[runtime] and only re-formats the tag suffix.
+//
+// Returns the empty string for unknown runtimes; callers should fall through
+// to DefaultImage in that case (matching legacy behavior).
+func RuntimeImage(runtime string) string {
+	for _, r := range knownRuntimes {
+		if r == runtime {
+			return fmt.Sprintf("%s/workspace-template-%s:latest", RegistryPrefix(), runtime)
+		}
+	}
+	return ""
+}
+
+// computeRuntimeImages returns the {runtime: image-ref} map evaluated against
+// the current RegistryPrefix(). Called at package init to populate the
+// exported RuntimeImages var. Tests that flip MOLECULE_IMAGE_REGISTRY between
+// expected values use this helper to rebuild the map mid-run.
+func computeRuntimeImages() map[string]string {
+	out := make(map[string]string, len(knownRuntimes))
+	for _, r := range knownRuntimes {
+		out[r] = RuntimeImage(r)
+	}
+	return out
+}
@@ -0,0 +1,140 @@
+package provisioner
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestRegistryPrefix_DefaultsToGHCR pins the OSS-default behavior. If a future
+// refactor accidentally drops the default, OSS users self-hosting Molecule
+// would silently lose image pulls — this test should fail loudly instead.
+func TestRegistryPrefix_DefaultsToGHCR(t *testing.T) {
+	t.Setenv("MOLECULE_IMAGE_REGISTRY", "")
+	got := RegistryPrefix()
+	want := "ghcr.io/molecule-ai"
+	if got != want {
+		t.Fatalf("RegistryPrefix() = %q, want %q (default must remain GHCR for OSS users)", got, want)
+	}
+}
+
+// TestRegistryPrefix_RespectsEnv verifies the override path used in
+// production tenants where MOLECULE_IMAGE_REGISTRY points at a private
+// mirror (AWS ECR, self-hosted Harbor, etc.).
+func TestRegistryPrefix_RespectsEnv(t *testing.T) {
+	t.Setenv("MOLECULE_IMAGE_REGISTRY", "123456789012.dkr.ecr.us-east-2.amazonaws.com/molecule-ai")
+	got := RegistryPrefix()
+	want := "123456789012.dkr.ecr.us-east-2.amazonaws.com/molecule-ai"
+	if got != want {
+		t.Fatalf("RegistryPrefix() = %q, want %q (env override path is the production cutover mechanism)", got, want)
+	}
+}
+
+// TestRegistryPrefix_EmptyEnvFallsBackToDefault — guard against an operator
+// setting MOLECULE_IMAGE_REGISTRY="" by mistake (e.g. unset deploy variable
+// becomes empty string, not literally absent). We treat "" as "use default"
+// so a misconfigured env doesn't mean an empty registry prefix.
+func TestRegistryPrefix_EmptyEnvFallsBackToDefault(t *testing.T) {
+	t.Setenv("MOLECULE_IMAGE_REGISTRY", "")
+	if RegistryPrefix() != defaultRegistryPrefix {
+		t.Fatalf("empty MOLECULE_IMAGE_REGISTRY should fall back to %q, got %q", defaultRegistryPrefix, RegistryPrefix())
+	}
+}
+
+// TestRuntimeImage_AllKnownRuntimes — every runtime in the canonical list
+// must produce a properly-formatted image ref. If a new runtime is added to
+// knownRuntimes but the format changes, this catches it.
+func TestRuntimeImage_AllKnownRuntimes(t *testing.T) {
+	t.Setenv("MOLECULE_IMAGE_REGISTRY", "")
+	for _, r := range knownRuntimes {
+		got := RuntimeImage(r)
+		want := "ghcr.io/molecule-ai/workspace-template-" + r + ":latest"
+		if got != want {
+			t.Errorf("RuntimeImage(%q) = %q, want %q", r, got, want)
+		}
+	}
+	// Pin the count so adding a runtime requires explicit test acknowledgement.
+	if len(knownRuntimes) != 9 {
+		t.Errorf("knownRuntimes length = %d, want 9 (autogen, claude-code, codex, crewai, deepagents, gemini-cli, hermes, langgraph, openclaw)", len(knownRuntimes))
+	}
+}
+
+// TestRuntimeImage_UnknownRuntime — defensive: callers must fall back to
+// DefaultImage when a runtime is unknown, never silently use the wrong
+// prefix. Returning "" enforces an explicit fallback at every call site.
+func TestRuntimeImage_UnknownRuntime(t *testing.T) {
+	for _, name := range []string{"", "nonexistent", "WORKSPACE-TEMPLATE-FAKE", "../../../etc/passwd"} {
+		if got := RuntimeImage(name); got != "" {
+			t.Errorf("RuntimeImage(%q) = %q, want empty string for unknown runtime", name, got)
+		}
+	}
+}
+
+// TestRuntimeImage_RegistryOverrideAppliesToAllRuntimes — the override
+// flips ALL runtimes consistently. If a refactor accidentally hardcoded
+// the prefix in some runtimes but not others (the failure mode that
+// triggered this whole rollout), this test catches it.
+func TestRuntimeImage_RegistryOverrideAppliesToAllRuntimes(t *testing.T) {
+	const ecr = "999999999999.dkr.ecr.us-east-2.amazonaws.com/molecule-ai"
+	t.Setenv("MOLECULE_IMAGE_REGISTRY", ecr)
+
+	for _, r := range knownRuntimes {
+		got := RuntimeImage(r)
+		if !strings.HasPrefix(got, ecr+"/workspace-template-") {
+			t.Errorf("RuntimeImage(%q) = %q, must start with override prefix %q", r, got, ecr)
+		}
+		if !strings.HasSuffix(got, ":latest") {
+			t.Errorf("RuntimeImage(%q) = %q, must keep :latest tag suffix", r, got)
+		}
+	}
+}
+
+// TestComputeRuntimeImages_AllRuntimesPresent — the map must contain every
+// known runtime. Drift between knownRuntimes and computeRuntimeImages would
+// silently break the runtime → image lookup that provisioner.Start uses.
+func TestComputeRuntimeImages_AllRuntimesPresent(t *testing.T) {
+	t.Setenv("MOLECULE_IMAGE_REGISTRY", "")
+	m := computeRuntimeImages()
+	if len(m) != len(knownRuntimes) {
+		t.Fatalf("computeRuntimeImages() has %d entries, want %d (one per knownRuntime)", len(m), len(knownRuntimes))
+	}
+	for _, r := range knownRuntimes {
+		img, ok := m[r]
+		if !ok {
+			t.Errorf("computeRuntimeImages() missing runtime %q", r)
+			continue
+		}
+		if img == "" {
+			t.Errorf("computeRuntimeImages()[%q] is empty", r)
+		}
+	}
+}
+
+// TestComputeRuntimeImages_ReflectsCurrentEnv — calling computeRuntimeImages
+// after env change rebuilds the map with new prefix. Tests + ops procedures
+// that flip the env in-process rely on this.
+func TestComputeRuntimeImages_ReflectsCurrentEnv(t *testing.T) {
+	t.Setenv("MOLECULE_IMAGE_REGISTRY", "")
+	defaultMap := computeRuntimeImages()
+	if !strings.HasPrefix(defaultMap["claude-code"], "ghcr.io/molecule-ai/") {
+		t.Fatalf("default map should be GHCR-prefixed, got %q", defaultMap["claude-code"])
+	}
+
+	const mirror = "registry.example.com/molecule-ai"
+	t.Setenv("MOLECULE_IMAGE_REGISTRY", mirror)
+	mirrorMap := computeRuntimeImages()
+	if !strings.HasPrefix(mirrorMap["claude-code"], mirror+"/") {
+		t.Fatalf("mirror-prefixed map should start with %q, got %q", mirror, mirrorMap["claude-code"])
+	}
+}
+
+// TestKnownRuntimes_AlphabeticalOrder — pin the order so test snapshots
+// (and human readers diffing the file) see deterministic output. Adding a
+// new runtime out of alphabetical order will fail this test, which is the
+// nudge to keep the file readable.
+func TestKnownRuntimes_AlphabeticalOrder(t *testing.T) {
+	for i := 1; i < len(knownRuntimes); i++ {
+		if knownRuntimes[i-1] >= knownRuntimes[i] {
+			t.Errorf("knownRuntimes not alphabetical: %q comes before %q", knownRuntimes[i-1], knownRuntimes[i])
+		}
+	}
+}