feat(sandbox): readable container names + per-instance ownership

- containers are named superset-<workspace/branch-slug>-<short-id> so
  Docker Desktop shows which workspace each sandbox belongs to; the
  workspace-id label stays authoritative and destroy/cleanup resolve
  containers by label, healing renames and legacy names
- new com.superset.home ownership label; the startup reconcile only
  sweeps containers created by THIS host instance. Fixes integration
  test runs (own temp DB, same docker daemon) deleting the dev app's
  live workspace containers as orphans

Author: mikigraf

packages/host-service/src/runtime/sandbox/container-manager.ts

@@ -15,6 +15,7 @@ import {
 	createContainer,
 	imageExists,
 	inspectContainer,
+	listWorkspaceContainerNames,
 	pullImage,
 	removeContainer,
 	startContainer,
@@ -26,6 +27,7 @@ import {
 	CONTAINER_HOST_DIR,
 	CONTAINER_SUPERSET_DIR,
 	getSandboxContainerName,
+	getSupersetHomeDir,
 	getWorkspaceSandboxPaths,
 } from "./paths.ts";
 import { selectPublishablePorts } from "./port-probe.ts";
@@ -46,6 +48,8 @@ export interface EnsureContainerParams {
 	worktreePath: string;
 	repoPath: string;
 	branch: string;
+	/** Human-readable container-name slug (workspace name/branch). */
+	nameSlug: string;
 	settings: ResolvedSandboxSettings;
 }
 
@@ -176,7 +180,7 @@ async function doEnsureContainer(params: EnsureContainerParams): Promise<void> {
 	// Also re-registers the token in-memory after host-service restarts.
 	const cliToken = await ensureCliTokenFile(params.workspaceId);
 
-	const name = getSandboxContainerName(params.workspaceId);
+	const name = getSandboxContainerName(params.workspaceId, params.nameSlug);
 	const configHash = computeConfigHash(params.settings);
 	const inspection = await inspectContainer(name);
 
@@ -219,11 +223,21 @@ async function doEnsureContainer(params: EnsureContainerParams): Promise<void> {
 		}
 	}
 
+	// A rename (workspace or branch) changes the display name; the old-named
+	// container for this workspace would otherwise linger as a duplicate.
+	const staleNames = (
+		await listWorkspaceContainerNames(params.workspaceId)
+	).filter((existing) => existing !== name);
+	for (const stale of staleNames) {
+		await removeContainer(stale);
+	}
+
 	await createContainer(
 		buildContainerCreateArgs({
 			name,
 			workspaceId: params.workspaceId,
 			configHash,
+			ownerHome: getSupersetHomeDir(),
 			image: params.settings.image,
 			runtime: params.settings.runtime,
 			network: params.settings.network,
@@ -255,7 +269,11 @@ export async function destroyWorkspaceSandbox(
 	provisioningStates.delete(workspaceId);
 	const availability = await checkDockerAvailable();
 	if (availability.ok) {
-		await removeContainer(getSandboxContainerName(workspaceId));
+		// By label, not by name: display names drift (slug/rename) and legacy
+		// containers used the bare superset-ws-<id> form.
+		for (const name of await listWorkspaceContainerNames(workspaceId)) {
+			await removeContainer(name);
+		}
 	} else {
 		console.warn(
 			`[sandbox] docker unavailable during destroy of ${workspaceId}; ` +

packages/host-service/src/runtime/sandbox/docker-args.test.ts

@@ -14,6 +14,7 @@ describe("buildContainerCreateArgs", () => {
 			name: "superset-ws-abc",
 			workspaceId: "abc",
 			configHash: "deadbeef",
+			ownerHome: "/home/me/.superset",
 			image: "img:1",
 			runtime: "runsc",
 			network: "none",
@@ -36,6 +37,8 @@ describe("buildContainerCreateArgs", () => {
 			"com.superset.workspace-id=abc",
 			"--label",
 			"com.superset.config-hash=deadbeef",
+			"--label",
+			"com.superset.home=/home/me/.superset",
 			"--restart",
 			"unless-stopped",
 			"--init",
@@ -68,6 +71,7 @@ describe("buildContainerCreateArgs", () => {
 			name: "n",
 			workspaceId: "w",
 			configHash: "h",
+			ownerHome: "/home/me/.superset",
 			image: "img",
 			network: "bridge",
 			resources: { pidsLimit: 2048 },

packages/host-service/src/runtime/sandbox/docker-args.ts

@@ -19,11 +19,20 @@ export interface PublishedPort {
 export const MANAGED_LABEL = "com.superset.managed=true";
 export const WORKSPACE_ID_LABEL = "com.superset.workspace-id";
 export const CONFIG_HASH_LABEL = "com.superset.config-hash";
+/**
+ * Which host-service instance owns the container, keyed by its superset home
+ * dir. Reconcile only touches containers with ITS OWN home label — a test
+ * host or a second dev instance must never sweep another instance's
+ * containers as orphans.
+ */
+export const OWNER_HOME_LABEL = "com.superset.home";
 
 export interface ContainerCreateSpec {
 	name: string;
 	workspaceId: string;
 	configHash: string;
+	/** Superset home dir of the owning host-service (OWNER_HOME_LABEL). */
+	ownerHome: string;
 	image: string;
 	runtime?: string;
 	network: "bridge" | "none";
@@ -59,6 +68,8 @@ export function buildContainerCreateArgs(spec: ContainerCreateSpec): string[] {
 		`${WORKSPACE_ID_LABEL}=${spec.workspaceId}`,
 		"--label",
 		`${CONFIG_HASH_LABEL}=${spec.configHash}`,
+		"--label",
+		`${OWNER_HOME_LABEL}=${spec.ownerHome}`,
 		"--restart",
 		"unless-stopped",
 		"--init",

packages/host-service/src/runtime/sandbox/docker-cli.ts

@@ -178,10 +178,30 @@ export async function removeContainer(name: string): Promise<void> {
 export interface ManagedContainer {
 	name: string;
 	workspaceId: string | null;
+	/** OWNER_HOME_LABEL value; null on containers from before the label. */
+	ownerHome: string | null;
 	running: boolean;
 }
 
 /** All containers carrying the Superset managed label, running or not. */
+/**
+ * All container names labeled with this workspace id — authoritative lookup
+ * for destroy/cleanup, since display names can drift (rename, slug change).
+ */
+export async function listWorkspaceContainerNames(
+	workspaceId: string,
+): Promise<string[]> {
+	const out = await docker([
+		"ps",
+		"-a",
+		"--filter",
+		`label=com.superset.workspace-id=${workspaceId}`,
+		"--format",
+		"{{.Names}}",
+	]);
+	return out.split("\n").filter((name) => name.trim().length > 0);
+}
+
 export async function listManagedContainers(): Promise<ManagedContainer[]> {
 	const out = await docker([
 		"ps",
@@ -200,13 +220,15 @@ export async function listManagedContainers(): Promise<ManagedContainer[]> {
 				state: string;
 				labels: string;
 			};
-			const workspaceLabel = parsed.labels
+			const labelPairs = parsed.labels
 				.split(",")
-				.map((pair) => pair.split("="))
-				.find(([key]) => key === "com.superset.workspace-id");
+				.map((pair) => pair.split("="));
+			const labelValue = (key: string) =>
+				labelPairs.find(([k]) => k === key)?.[1] ?? null;
 			containers.push({
 				name: parsed.name,
-				workspaceId: workspaceLabel?.[1] ?? null,
+				workspaceId: labelValue("com.superset.workspace-id"),
+				ownerHome: labelValue("com.superset.home"),
 				running: parsed.state === "running",
 			});
 		} catch {

packages/host-service/src/runtime/sandbox/docker-runtime.ts

@@ -29,6 +29,8 @@ export interface DockerRuntimeParams {
 	worktreePath: string;
 	repoPath: string;
 	branch: string;
+	/** Human-readable container-name slug (workspace name/branch). */
+	nameSlug: string;
 	settings: ResolvedSandboxSettings;
 }
 
@@ -71,7 +73,10 @@ export class DockerRuntime implements WorkspaceRuntime {
 		return {
 			shell: "docker",
 			argv: buildExecArgs({
-				containerName: getSandboxContainerName(this.params.workspaceId),
+				containerName: getSandboxContainerName(
+					this.params.workspaceId,
+					this.params.nameSlug,
+				),
 				cwd: ctx.cwd,
 				env,
 				command: ["/bin/bash", "--rcfile", CONTAINER_BASH_RCFILE],

packages/host-service/src/runtime/sandbox/paths.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test";
+import { getSandboxContainerName, sandboxNameSlug } from "./paths.ts";
+
+describe("sandboxNameSlug", () => {
+	test("sanitizes to docker-safe lowercase and dedupes parts", () => {
+		expect(sandboxNameSlug("Add tests", "feat/add-tests")).toBe(
+			"add-tests-feat-add-tests",
+		);
+		expect(sandboxNameSlug("main", "main")).toBe("main");
+		expect(sandboxNameSlug(null, "Fix (WS) #12!")).toBe("fix-ws-12");
+	});
+
+	test("truncates long inputs without a trailing dash", () => {
+		const slug = sandboxNameSlug("a".repeat(28), "branch-name-that-is-long");
+		expect(slug.length).toBeLessThanOrEqual(30);
+		expect(slug.endsWith("-")).toBe(false);
+	});
+});
+
+describe("getSandboxContainerName", () => {
+	test("slugged name keeps a short unique id suffix", () => {
+		expect(
+			getSandboxContainerName(
+				"9431dce6-39c7-4fd9-b31c-4abc80b73170",
+				"add-tests",
+			),
+		).toBe("superset-add-tests-9431dce6");
+	});
+
+	test("falls back to the id-only form without a slug", () => {
+		expect(getSandboxContainerName("abc")).toBe("superset-ws-abc");
+	});
+});

packages/host-service/src/runtime/sandbox/paths.ts

@@ -56,6 +56,34 @@ export function getWorkspaceSandboxPaths(
 	};
 }
 
-export function getSandboxContainerName(workspaceId: string): string {
-	return `superset-ws-${workspaceId}`;
+const CONTAINER_SLUG_MAX = 30;
+
+/**
+ * Docker-safe, human-readable slug from workspace naming parts (name,
+ * branch). Duplicate/empty parts collapse; "" when nothing usable survives.
+ */
+export function sandboxNameSlug(
+	...parts: Array<string | null | undefined>
+): string {
+	const unique = [...new Set(parts.filter((p): p is string => !!p))];
+	return unique
+		.join("-")
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, CONTAINER_SLUG_MAX)
+		.replace(/-+$/, "");
+}
+
+/**
+ * Container name: readable slug (so Docker Desktop shows which workspace it
+ * is) + short workspace-id suffix for uniqueness. The workspace-id LABEL is
+ * authoritative for cleanup — names are display + exec targeting only.
+ */
+export function getSandboxContainerName(
+	workspaceId: string,
+	nameSlug?: string,
+): string {
+	if (!nameSlug) return `superset-ws-${workspaceId}`;
+	return `superset-${nameSlug}-${workspaceId.slice(0, 8)}`;
 }

packages/host-service/src/runtime/sandbox/registry.ts

@@ -6,14 +6,24 @@ import { computeConfigHash } from "./container-manager.ts";
 import { resolveSandboxSettings } from "./docker-args.ts";
 import { DockerRuntime } from "./docker-runtime.ts";
 import { HostRuntime } from "./host-runtime.ts";
+import { sandboxNameSlug } from "./paths.ts";
 import type { WorkspaceRuntime } from "./workspace-runtime.ts";
 
 const hostRuntime = new HostRuntime();
 const dockerRuntimes = new Map<
 	string,
-	{ configHash: string; runtime: DockerRuntime }
+	{ configHash: string; nameSlug: string; runtime: DockerRuntime }
 >();
 
+/** Container-name slug from a workspace row — shared with tests so name
+ * expectations can't drift from what the runtime actually creates. */
+export function computeWorkspaceNameSlug(row: {
+	name: string | null;
+	branch: string;
+}): string {
+	return sandboxNameSlug(row.name, row.branch);
+}
+
 /**
  * Resolve the execution runtime for a workspace.
  *
@@ -44,18 +54,25 @@ export function getWorkspaceRuntime(
 		})?.sandbox ?? {};
 	const settings = resolveSandboxSettings(sandboxConfig);
 	const configHash = computeConfigHash(settings);
+	const nameSlug = computeWorkspaceNameSlug(workspace);
 
 	const cached = dockerRuntimes.get(workspaceId);
-	if (cached && cached.configHash === configHash) return cached.runtime;
+	if (
+		cached &&
+		cached.configHash === configHash &&
+		cached.nameSlug === nameSlug
+	)
+		return cached.runtime;
 
 	const runtime = new DockerRuntime({
 		workspaceId,
 		worktreePath: workspace.worktreePath,
 		repoPath: project.repoPath,
 		branch: workspace.branch,
+		nameSlug,
 		settings,
 	});
-	dockerRuntimes.set(workspaceId, { configHash, runtime });
+	dockerRuntimes.set(workspaceId, { configHash, nameSlug, runtime });
 	return runtime;
 }
 

packages/host-service/src/runtime/sandbox/sandbox-docker.integration.test.ts

@@ -48,7 +48,10 @@ describe.skipIf(!DOCKER_TESTS)("sandbox docker integration", () => {
 	let repoPath: string;
 	let worktreePath: string;
 	let savedHomeDir: string | undefined;
-	const containerName = getSandboxContainerName(WORKSPACE_ID);
+	const containerName = getSandboxContainerName(
+		WORKSPACE_ID,
+		"inttest-feature",
+	);
 
 	beforeAll(async () => {
 		fixtureRoot = mkdtempSync(join(tmpdir(), "superset-sandbox-int-"));
@@ -133,6 +136,7 @@ describe.skipIf(!DOCKER_TESTS)("sandbox docker integration", () => {
 				worktreePath,
 				repoPath,
 				branch: "feature",
+				nameSlug: "inttest-feature",
 				settings,
 			});
 
@@ -150,6 +154,7 @@ describe.skipIf(!DOCKER_TESTS)("sandbox docker integration", () => {
 				worktreePath,
 				repoPath,
 				branch: "feature",
+				nameSlug: "inttest-feature",
 				settings,
 			});
 

packages/host-service/src/runtime/sandbox/sandbox-reconcile.ts

@@ -6,6 +6,7 @@ import {
 	listManagedContainers,
 	removeContainer,
 } from "./docker-cli.ts";
+import { getSupersetHomeDir } from "./paths.ts";
 
 /**
  * Startup sweep: remove Superset-managed containers whose workspace row is
@@ -20,7 +21,14 @@ export async function runSandboxReconcile(db: HostDb): Promise<void> {
 	const containers = await listManagedContainers();
 	if (containers.length === 0) return;
 
+	const ownerHome = getSupersetHomeDir();
 	for (const container of containers) {
+		// Only sweep containers THIS host instance created. Several instances
+		// share one docker daemon (dev app, integration tests, multiple orgs);
+		// another instance's live workspace looks like an orphan in our DB.
+		// Unlabeled containers (pre-ownership builds) are left alone too —
+		// never delete what we can't prove we own.
+		if (container.ownerHome !== ownerHome) continue;
 		const workspace = container.workspaceId
 			? db.query.workspaces
 					.findFirst({