@go-to-k/cdkd 0.138.0 → 0.139.0

package/dist/cli.js

@@ -38097,6 +38097,8 @@ function parseContainerDefinition(raw, idx, taskLogicalId, resources, stack, con
 			protocol: pickString(p["Protocol"]) === "udp" ? "udp" : "tcp"
 		};
 		if (hostPort !== void 0) pm.hostPort = hostPort;
+		const portName = typeof p["Name"] === "string" ? p["Name"] : void 0;
+		if (portName !== void 0) pm.name = portName;
 		portMappings.push(pm);
 	}
 	const mountPoints = [];
@@ -38745,7 +38747,7 @@ function resolveRuntimeCodeMountPath(runtime) {
 
 //#endregion
 //#region src/local/docker-runner.ts
-const execFileAsync$3 = promisify(execFile);
+const execFileAsync$4 = promisify(execFile);
 /**
 * Wraps `docker pull` / `docker run` / `docker rm` for `cdkd local invoke`.
 *
@@ -38838,7 +38840,7 @@ async function runDetached(opts) {
 	args.push(opts.image, ...entryPointTail, ...opts.cmd);
 	getLogger().child("docker").debug(`${getDockerCmd()} ${redactAwsCredentialsInArgs(args).join(" ")}`);
 	try {
-		const { stdout } = await execFileAsync$3(getDockerCmd(), args, { maxBuffer: 10 * 1024 * 1024 });
+		const { stdout } = await execFileAsync$4(getDockerCmd(), args, { maxBuffer: 10 * 1024 * 1024 });
 		return stdout.trim();
 	} catch (error) {
 		const err = error;
@@ -38875,7 +38877,7 @@ async function removeContainer(containerId) {
 	if (!containerId) return;
 	const logger = getLogger().child("docker");
 	try {
-		await execFileAsync$3(getDockerCmd(), [
+		await execFileAsync$4(getDockerCmd(), [
 			"rm",
 			"-f",
 			containerId
@@ -38894,7 +38896,7 @@ async function removeContainer(containerId) {
 async function ensureDockerAvailable() {
 	const cmd = getDockerCmd();
 	try {
-		await execFileAsync$3(cmd, [
+		await execFileAsync$4(cmd, [
 			"version",
 			"--format",
 			"{{.Server.Version}}"
@@ -49340,7 +49342,7 @@ function createLocalStartApiCommand() {
 
 //#endregion
 //#region src/local/ecs-network.ts
-const execFileAsync$2 = promisify(execFile);
+const execFileAsync$3 = promisify(execFile);
 /**
 * Docker network + AWS-published metadata-endpoints sidecar lifecycle for
 * `cdkd local run-task`. The sidecar (a small Go binary maintained by
@@ -49358,8 +49360,10 @@ const METADATA_ENDPOINT_IMAGE = "amazon/amazon-ecs-local-container-endpoints:lat
 * matches the documented AWS task-metadata endpoint address. Containers
 * inject `ECS_CONTAINER_METADATA_URI_V4=http://169.254.170.2/v4/<id>`
 * to reach it. `cdkd local run-task` keeps this verbatim; `cdkd local
-* start-service` allocates a per-replica subnet (via `subnetOctet`) so
-* concurrent replicas don't collide on a single docker network range.
+* start-service` creates ONE shared network at CLI startup (design
+* § 5 Option A) — the shared sidecar lives at `169.254.171.2` (see
+* `SHARED_SVC_SUBNET_OCTET` below), one octet up so the two CLI
+* variants can run on the same host without bridge-pool collision.
 */
 const METADATA_ENDPOINT_IP = "169.254.170.2";
 /** Default subnet — used when no `subnetOctet` override is supplied. */
@@ -49387,23 +49391,58 @@ function buildEndpointSubnet(subnetOctet) {
 	};
 }
 /**
-* Create the per-task docker network + start the metadata-endpoints
-* sidecar. The sidecar must come up at the well-known address BEFORE any
-* user container starts so the `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`
-* lookup at container start doesn't race.
+* Subnet octet for the shared-service docker network used by
+* `cdkd local start-service`. One octet up from `cdkd local run-task`'s
+* default (170 → 171) so the two CLI variants can run on the same host
+* without docker rejecting the second `--subnet`. The shared-service
+* network reuses the same `createTaskNetwork` machinery; the sidecar at
+* `169.254.171.2` serves the same metadata-endpoint API to every
+* container that joins this one network.
 */
-async function createTaskNetwork(options = {}) {
+const SHARED_SVC_SUBNET_OCTET = 171;
+/**
+* Create the one shared docker network + metadata-endpoints sidecar
+* used by every service-replica boot in a single
+* `cdkd local start-service` invocation. This is design doc § 5
+* Option A — one network per CLI invocation instead of one network
+* per task — so peer services can reach each other by IP / network
+* alias without docker `--network connect` choreography (Option B,
+* rejected in design § 5 as "unwieldy and racy"). The returned
+* `TaskNetwork` carries `ownedByCaller: true` so `cleanupEcsRun()`
+* (called per replica by the service runner) does NOT teardown — the
+* CLI tears down ONCE at the end of the run.
+*/
+async function createSharedSvcNetwork(options = {}) {
+	const networkName = `${options.prefix ?? "cdkd-local"}-svc-${randomBytes(4).toString("hex")}`;
+	const { cidr, sidecarIp } = buildEndpointSubnet(171);
+	return {
+		networkName,
+		sidecarContainerId: await createNetworkAndSidecar({
+			networkName,
+			cidr,
+			sidecarIp,
+			skipPull: options.skipPull ?? false,
+			...options.credentials !== void 0 ? { credentials: options.credentials } : {},
+			...options.cluster !== void 0 ? { cluster: options.cluster } : {}
+		}),
+		sidecarIp,
+		ownedByCaller: true
+	};
+}
+/**
+* Internal helper shared by `createTaskNetwork` (per-task) and
+* `createSharedSvcNetwork` (per-CLI-run). Creates the docker network,
+* pulls the sidecar image, and starts the sidecar at the documented
+* IP. Throws `DockerRunnerError` with a hint when the network already
+* exists (the typical "leftover from previous run" path).
+*/
+async function createNetworkAndSidecar(args) {
 	const logger = getLogger().child("ecs-network");
-	const networkName = `${options.prefix ?? "cdkd-local"}-task-${randomBytes(4).toString("hex")}`;
-	const subnetOctet = options.subnetOctet ?? 170;
-	const { cidr, sidecarIp } = options.subnetOctet === void 0 ? {
-		cidr: DEFAULT_METADATA_ENDPOINT_SUBNET,
-		sidecarIp: METADATA_ENDPOINT_IP
-	} : buildEndpointSubnet(subnetOctet);
-	await pullImage(METADATA_ENDPOINT_IMAGE, options.skipPull ?? false);
+	const { networkName, cidr, sidecarIp, credentials, cluster, skipPull } = args;
+	await pullImage(METADATA_ENDPOINT_IMAGE, skipPull);
 	logger.info(`Creating docker network ${networkName} (subnet ${cidr})...`);
 	try {
-		await execFileAsync$2(getDockerCmd(), [
+		await execFileAsync$3(getDockerCmd(), [
 			"network",
 			"create",
 			"--driver",
@@ -49414,7 +49453,7 @@ async function createTaskNetwork(options = {}) {
 		]);
 	} catch (err) {
 		const e = err;
-		throw new DockerRunnerError(`docker network create failed: ${e.stderr?.trim() || e.message || String(err)}. Hint: another cdkd run-task on the same host may already own subnet ${cidr}; wait for it to finish, or remove the leftover network with \`docker network ls\` + \`docker network rm\`. \`cdkd local start-service\` walks subnetOctet per replica to avoid this; bare \`cdkd local run-task\` uses the default subnet so only one run can be active at a time.`);
+		throw new DockerRunnerError(`docker network create failed: ${e.stderr?.trim() || e.message || String(err)}. Hint: another cdkd run may already own subnet ${cidr}; wait for it to finish, or remove the leftover network with \`docker network ls\` + \`docker network rm\`. \`cdkd local start-service\` shares one network across every service in the run; bare \`cdkd local run-task\` uses a per-task network so only one run can be active at a time.`);
 	}
 	const sidecarArgs = [
 		"run",
@@ -49428,27 +49467,46 @@ async function createTaskNetwork(options = {}) {
 		sidecarIp
 	];
 	const sidecarEnv = {};
-	if (options.credentials) {
-		sidecarEnv["AWS_ACCESS_KEY_ID"] = options.credentials.accessKeyId;
-		sidecarEnv["AWS_SECRET_ACCESS_KEY"] = options.credentials.secretAccessKey;
-		if (options.credentials.sessionToken) sidecarEnv["AWS_SESSION_TOKEN"] = options.credentials.sessionToken;
+	if (credentials) {
+		sidecarEnv["AWS_ACCESS_KEY_ID"] = credentials.accessKeyId;
+		sidecarEnv["AWS_SECRET_ACCESS_KEY"] = credentials.secretAccessKey;
+		if (credentials.sessionToken) sidecarEnv["AWS_SESSION_TOKEN"] = credentials.sessionToken;
 	}
-	if (options.cluster) sidecarEnv["CLUSTER"] = options.cluster;
+	if (cluster) sidecarEnv["CLUSTER"] = cluster;
 	for (const [k, v] of Object.entries(sidecarEnv)) sidecarArgs.push("-e", `${k}=${v}`);
 	sidecarArgs.push(METADATA_ENDPOINT_IMAGE);
 	logger.info(`Starting ECS local-container-endpoints sidecar at ${sidecarIp}...`);
-	let sidecarContainerId;
 	try {
-		const { stdout } = await execFileAsync$2(getDockerCmd(), sidecarArgs, { maxBuffer: 10 * 1024 * 1024 });
-		sidecarContainerId = stdout.trim();
+		const { stdout } = await execFileAsync$3(getDockerCmd(), sidecarArgs, { maxBuffer: 10 * 1024 * 1024 });
+		return stdout.trim();
 	} catch (err) {
 		await destroyNetworkOnly(networkName);
 		const e = err;
 		throw new DockerRunnerError(`Failed to start metadata-endpoints sidecar: ${e.stderr?.trim() || e.message || String(err)}`);
 	}
+}
+/**
+* Create the per-task docker network + start the metadata-endpoints
+* sidecar. The sidecar must come up at the well-known address BEFORE any
+* user container starts so the `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`
+* lookup at container start doesn't race.
+*/
+async function createTaskNetwork(options = {}) {
+	const networkName = `${options.prefix ?? "cdkd-local"}-task-${randomBytes(4).toString("hex")}`;
+	const { cidr, sidecarIp } = options.subnetOctet === void 0 ? {
+		cidr: DEFAULT_METADATA_ENDPOINT_SUBNET,
+		sidecarIp: METADATA_ENDPOINT_IP
+	} : buildEndpointSubnet(options.subnetOctet);
 	return {
 		networkName,
-		sidecarContainerId,
+		sidecarContainerId: await createNetworkAndSidecar({
+			networkName,
+			cidr,
+			sidecarIp,
+			skipPull: options.skipPull ?? false,
+			...options.credentials !== void 0 ? { credentials: options.credentials } : {},
+			...options.cluster !== void 0 ? { cluster: options.cluster } : {}
+		}),
 		sidecarIp
 	};
 }
@@ -49487,7 +49545,7 @@ async function destroyNetworkOnly(networkName) {
 	if (!networkName) return;
 	const logger = getLogger().child("ecs-network");
 	try {
-		await execFileAsync$2(getDockerCmd(), [
+		await execFileAsync$3(getDockerCmd(), [
 			"network",
 			"rm",
 			networkName
@@ -49620,7 +49678,7 @@ async function resolveSsm(entry, shape, client) {
 
 //#endregion
 //#region src/local/ecs-task-runner.ts
-const execFileAsync$1 = promisify(execFile);
+const execFileAsync$2 = promisify(execFile);
 /**
 * Top-level orchestrator for `cdkd local run-task`. Coordinates image
 * preparation, secret resolution, docker-network bring-up, container
@@ -49677,10 +49735,10 @@ async function cleanupEcsRun(state, options) {
 		}
 		state.startedContainers = [];
 	}
-	await destroyTaskNetwork(state.network);
+	if (state.network && !state.network.ownedByCaller) await destroyTaskNetwork(state.network);
 	state.network = void 0;
 	for (const v of state.dockerVolumeNames) try {
-		await execFileAsync$1(getDockerCmd(), [
+		await execFileAsync$2(getDockerCmd(), [
 			"volume",
 			"rm",
 			v
@@ -49710,14 +49768,20 @@ async function runEcsTask(task, options, state) {
 		valueFrom: s.valueFrom
 	});
 	const secretsByContainer = groupSecretsByContainer(await resolveEcsSecrets(allSecrets, { ...options.region !== void 0 && { region: options.region } }));
-	const netCreateOpts = {
-		prefix: options.cluster,
-		skipPull: options.skipPull
-	};
-	if (options.taskCredentials) netCreateOpts.credentials = options.taskCredentials;
-	if (options.cluster) netCreateOpts.cluster = options.cluster;
-	if (options.subnetOctet !== void 0) netCreateOpts.subnetOctet = options.subnetOctet;
-	state.network = await createTaskNetwork(netCreateOpts);
+	if (options.existingNetwork) state.network = {
+		...options.existingNetwork,
+		ownedByCaller: true
+	};
+	else {
+		const netCreateOpts = {
+			prefix: options.cluster,
+			skipPull: options.skipPull
+		};
+		if (options.taskCredentials) netCreateOpts.credentials = options.taskCredentials;
+		if (options.cluster) netCreateOpts.cluster = options.cluster;
+		if (options.subnetOctet !== void 0) netCreateOpts.subnetOctet = options.subnetOctet;
+		state.network = await createTaskNetwork(netCreateOpts);
+	}
 	const volumeByName = await realizeDockerVolumes(task.volumes, state);
 	const dockerCmds = /* @__PURE__ */ new Map();
 	for (const container of task.containers) {
@@ -49735,7 +49799,9 @@ async function runEcsTask(task, options, state) {
 			roleArn: options.taskRoleArn,
 			platformOverride: options.platformOverride,
 			region: options.region,
-			sidecarIp: state.network.sidecarIp
+			sidecarIp: state.network.sidecarIp,
+			...options.addHostFlags && options.addHostFlags.length > 0 ? { addHostFlags: options.addHostFlags } : {},
+			...(options.networkAliasesByContainer?.get(container.name)?.length ?? 0) > 0 ? { networkAliases: options.networkAliasesByContainer.get(container.name) } : {}
 		}));
 	}
 	const startedByName = /* @__PURE__ */ new Map();
@@ -49746,7 +49812,7 @@ async function runEcsTask(task, options, state) {
 		logger.info(`Starting container '${container.name}' (image=${imagePlan.get(container.name)})`);
 		let id;
 		try {
-			const { stdout } = await execFileAsync$1(getDockerCmd(), args, { maxBuffer: 10 * 1024 * 1024 });
+			const { stdout } = await execFileAsync$2(getDockerCmd(), args, { maxBuffer: 10 * 1024 * 1024 });
 			id = stdout.trim();
 		} catch (err) {
 			const e = err;
@@ -49855,7 +49921,7 @@ async function waitForContainerHealthy(containerId, displayName) {
 	let lastStatus = "";
 	while (Date.now() < deadline) {
 		try {
-			const { stdout } = await execFileAsync$1(getDockerCmd(), [
+			const { stdout } = await execFileAsync$2(getDockerCmd(), [
 				"inspect",
 				"--format",
 				"{{.State.Health.Status}}",
@@ -49878,7 +49944,7 @@ async function waitForContainerHealthy(containerId, displayName) {
 }
 async function waitForContainerExit(containerId) {
 	try {
-		const { stdout } = await execFileAsync$1(getDockerCmd(), ["wait", containerId], { maxBuffer: 1024 * 1024 });
+		const { stdout } = await execFileAsync$2(getDockerCmd(), ["wait", containerId], { maxBuffer: 1024 * 1024 });
 		const code = Number.parseInt(stdout.trim(), 10);
 		return Number.isFinite(code) ? code : 1;
 	} catch (err) {
@@ -49888,7 +49954,7 @@ async function waitForContainerExit(containerId) {
 }
 async function stopContainer(containerId, graceSeconds) {
 	try {
-		await execFileAsync$1(getDockerCmd(), [
+		await execFileAsync$2(getDockerCmd(), [
 			"stop",
 			"-t",
 			String(graceSeconds),
@@ -50013,7 +50079,7 @@ async function realizeDockerVolumes(volumes, state) {
 		const dockerVolumeName = `cdkd-local-${v.name}-${randHex(4)}`;
 		args.push(dockerVolumeName);
 		try {
-			await execFileAsync$1(getDockerCmd(), args);
+			await execFileAsync$2(getDockerCmd(), args);
 			state.dockerVolumeNames.push(dockerVolumeName);
 			logger.debug(`Created docker volume ${dockerVolumeName} for task volume '${v.name}'`);
 		} catch (err) {
@@ -50053,6 +50119,14 @@ function buildDockerRunArgs(opts) {
 	args.push("--name", `cdkd-local-${task.family}-${container.name}-${randHex(3)}`);
 	args.push("--network", network);
 	args.push("--network-alias", container.name);
+	if (opts.networkAliases && opts.networkAliases.length > 0) {
+		const seen = new Set([container.name]);
+		for (const a of opts.networkAliases) if (!seen.has(a)) {
+			args.push("--network-alias", a);
+			seen.add(a);
+		}
+	}
+	if (opts.addHostFlags && opts.addHostFlags.length > 0) for (const f of opts.addHostFlags) args.push(f);
 	if (opts.platformOverride) args.push("--platform", opts.platformOverride);
 	else if (task.runtimePlatform) args.push("--platform", task.runtimePlatform.cpuArchitecture === "ARM64" ? "linux/arm64" : "linux/amd64");
 	for (const pm of container.portMappings) {
@@ -50459,8 +50533,8 @@ function extractServiceProperties(stack, serviceLogicalId, resource, stacks, con
 	const healthCheckGracePeriodSeconds = parseHealthCheckGrace(props["HealthCheckGracePeriodSeconds"], serviceLogicalId);
 	const serviceName = parseServiceName(props["ServiceName"], serviceLogicalId);
 	if (Array.isArray(props["LoadBalancers"]) && props["LoadBalancers"].length > 0) warnings.push(`ECS Service '${serviceLogicalId}' declares LoadBalancers, but local load-balancer emulation is deferred to a follow-up PR. Containers are NOT registered to a local listener; reach them via their published ports.`);
-	if (props["ServiceConnectConfiguration"]) warnings.push(`ECS Service '${serviceLogicalId}' declares ServiceConnectConfiguration, but Service Connect / Cloud Map emulation is deferred (tracked in #460). Cross-service discovery between locally-run services is not provided.`);
-	return {
+	const serviceConnect = extractServiceConnect(props["ServiceConnectConfiguration"], task);
+	const out = {
 		stack,
 		serviceLogicalId,
 		resource,
@@ -50468,8 +50542,103 @@ function extractServiceProperties(stack, serviceLogicalId, resource, stacks, con
 		desiredCount,
 		healthCheckGracePeriodSeconds,
 		task,
+		serviceRegistries: extractServiceRegistries(props["ServiceRegistries"]),
 		warnings
 	};
+	if (serviceConnect) out.serviceConnect = serviceConnect;
+	return out;
+}
+/**
+* Parse `ServiceConnectConfiguration` against the producer TaskDef.
+* Returns `undefined` when the block is missing OR `Enabled: false`.
+*
+* Reject conditions (surface as resolver-time errors so the user sees
+* them BEFORE the docker network is created):
+*   - `Namespace` is not a literal string. CDK 2.x always emits a
+*     literal string here (verified 2026-05-22); cross-stack /
+*     intrinsic shapes are out of scope.
+*   - `Services[].PortName` doesn't match any of the TaskDef's
+*     `ContainerDefinitions[].PortMappings[].Name` entries.
+*
+* Note on `clientAliases[]` shape: each ClientAlias can declare a
+* `DnsName` (the bare short-name peers connect to, e.g. `orders`) AND
+* a `Port` (the listening port the alias maps to inside the consumer).
+* cdkd surfaces both verbatim; the registry / `--add-host` overlay
+* publishes each `DnsName` as a bare alias pointing at the same IP as
+* the canonical fqdn.
+*/
+function extractServiceConnect(raw, task) {
+	if (!raw || typeof raw !== "object") return void 0;
+	const cfg = raw;
+	if (cfg["Enabled"] === false) return void 0;
+	const namespaceName = pickServiceConnectNamespace(cfg["Namespace"]);
+	if (!namespaceName) throw new EcsTaskResolutionError(`ServiceConnectConfiguration.Namespace must be a literal string (the Cloud Map namespace name like 'cdkd-local.local'); got ${JSON.stringify(cfg["Namespace"])}. Intrinsic / cross-stack namespace references are not supported in v1.`);
+	const rawServices = cfg["Services"];
+	if (!Array.isArray(rawServices) || rawServices.length === 0) return {
+		namespaceName,
+		services: []
+	};
+	const portByName = /* @__PURE__ */ new Map();
+	for (const c of task.containers) for (const pm of c.portMappings) if (pm.name) portByName.set(pm.name, pm.containerPort);
+	const services = [];
+	for (const entry of rawServices) {
+		if (!entry || typeof entry !== "object") continue;
+		const e = entry;
+		const portName = typeof e["PortName"] === "string" ? e["PortName"] : void 0;
+		if (!portName) throw new EcsTaskResolutionError(`ServiceConnectConfiguration.Services[] entry has no PortName: ${JSON.stringify(entry)}. Every Service entry must reference a producer-side PortMappings[].Name.`);
+		const containerPort = portByName.get(portName);
+		if (containerPort === void 0) throw new EcsTaskResolutionError(`ServiceConnectConfiguration.Services[].PortName='${portName}' does not match any PortMappings[].Name on the producer TaskDef (available: ${[...portByName.keys()].join(", ") || "(none)"}).`);
+		const clientAliases = [];
+		if (Array.isArray(e["ClientAliases"])) for (const ca of e["ClientAliases"]) {
+			if (!ca || typeof ca !== "object") continue;
+			const caObj = ca;
+			const dnsName = typeof caObj["DnsName"] === "string" ? caObj["DnsName"] : void 0;
+			const aliasEntry = { port: typeof caObj["Port"] === "number" ? caObj["Port"] : containerPort };
+			if (dnsName !== void 0) aliasEntry.dnsName = dnsName;
+			clientAliases.push(aliasEntry);
+		}
+		const discoveryName = clientAliases.find((c) => c.dnsName !== void 0)?.dnsName ?? portName;
+		services.push({
+			portName,
+			containerPort,
+			discoveryName,
+			clientAliases
+		});
+	}
+	return {
+		namespaceName,
+		services
+	};
+}
+/**
+* Parse `ServiceRegistries[]`. Each entry's `RegistryArn` is the
+* canonical `Fn::GetAtt: [<CloudMapServiceLogicalId>, 'Arn']` shape;
+* cdkd surfaces the logical id (the AWS-side ARN is irrelevant
+* locally — the registry is in-process).
+*/
+function extractServiceRegistries(raw) {
+	if (!Array.isArray(raw)) return [];
+	const out = [];
+	for (const entry of raw) {
+		if (!entry || typeof entry !== "object") continue;
+		const e = entry;
+		const registryArn = e["RegistryArn"];
+		let cloudMapServiceLogicalId;
+		if (typeof registryArn === "string") continue;
+		if (registryArn && typeof registryArn === "object" && !Array.isArray(registryArn)) {
+			const getAtt = registryArn["Fn::GetAtt"];
+			if (Array.isArray(getAtt) && typeof getAtt[0] === "string") cloudMapServiceLogicalId = getAtt[0];
+		}
+		if (!cloudMapServiceLogicalId) continue;
+		const reg = { cloudMapServiceLogicalId };
+		if (typeof e["ContainerName"] === "string") reg.containerName = e["ContainerName"];
+		if (typeof e["ContainerPort"] === "number") reg.containerPort = e["ContainerPort"];
+		out.push(reg);
+	}
+	return out;
+}
+function pickServiceConnectNamespace(raw) {
+	if (typeof raw === "string" && raw.length > 0) return raw;
 }
 /**
 * Resolve `Properties.TaskDefinition` to a logical id in the same stack.
@@ -50534,6 +50703,42 @@ function notFoundError(target, stack, resources) {
 	return new EcsTaskResolutionError(`Target '${target}' did not match any ECS Service in ${stack.stackName}. Available services: ${services.join(", ")}.`);
 }
 
+//#endregion
+//#region src/local/docker-inspect.ts
+const execFileAsync$1 = promisify(execFile);
+/**
+* Phase 3 of #262 (Issue #460) helper — query the docker network IP
+* assigned to a freshly-started container so the Cloud Map registry
+* can publish reachable endpoints for peer discovery.
+*
+* Returns `undefined` when:
+*   - The container is not found (docker rm raced us).
+*   - The container is not attached to the named network.
+*   - The IP is empty (docker hasn't fully wired the network yet —
+*     caller should retry-or-skip; the helper deliberately does NOT
+*     embed a retry loop to keep the caller in charge of timing).
+*
+* Errors propagate verbatim to the caller (`DockerRunnerError`-style
+* wrapping is the caller's concern; this helper is structurally a
+* simple inspect wrapper).
+*/
+async function getContainerNetworkIp(containerId, networkName) {
+	const format = `{{with index .NetworkSettings.Networks "${networkName}"}}{{.IPAddress}}{{end}}`;
+	try {
+		const { stdout } = await execFileAsync$1(getDockerCmd(), [
+			"inspect",
+			"--format",
+			format,
+			containerId
+		]);
+		const ip = stdout.trim();
+		if (!ip) return void 0;
+		return ip;
+	} catch {
+		return;
+	}
+}
+
 //#endregion
 //#region src/local/ecs-service-runner.ts
 /**
@@ -50551,10 +50756,20 @@ function notFoundError(target, stack, resources) {
 *     stops compounding cleanup work.
 *   - Long-running lifecycle (returns only on shutdown).
 *
+* Phase 3 of #262 (Issue #460) — Cloud Map / Service Connect peer
+* discovery is wired through `ServiceRunnerOptions.discovery`. When
+* supplied, every booted replica discovers its docker IP, registers
+* itself into the shared in-process `CloudMapRegistry`, and emits
+* `--add-host` flags so consumer containers reach peer services via
+* the canonical `<discoveryName>.<namespace>` fqdn. Envoy L7 sidecar
+* emulation (design Layer B) is deferred to a follow-up PR per the
+* design's §O5 "--no-envoy by default" recommendation.
+*
 * Deferred to follow-up PRs:
 *   - Local load-balancer emulation (LB listener + target-group health
 *     check + round-robin) — separate PR per the issue's PR-split.
-*   - Service Connect / Cloud Map (tracked in #460).
+*   - Envoy sidecar for Service Connect L7 routing / retries / circuit
+*     breaking (Cloud Map DNS-only mode ships now).
 *   - Rolling deployment (`--reload` / `--watch`).
 */
 var EcsServiceRunnerError = class EcsServiceRunnerError extends Error {
@@ -50620,7 +50835,8 @@ async function startEcsService(service, options, runState) {
 			state: createEcsRunState(),
 			restartCount: 0,
 			shuttingDown: false,
-			inFlightBoot: void 0
+			inFlightBoot: void 0,
+			cloudMapHandles: []
 		};
 		runState.replicas.push(instance);
 		const bootPromise = bootReplica(service, options, instance);
@@ -50702,6 +50918,12 @@ var ServiceController = class {
 			await Promise.allSettled(inFlightBoots);
 		}
 		await Promise.allSettled(this.runState.replicas.map(async (instance) => {
+			if (this.options.discovery) {
+				for (const handle of instance.cloudMapHandles) try {
+					this.options.discovery.registry.unregister(handle);
+				} catch {}
+				instance.cloudMapHandles = [];
+			}
 			try {
 				await cleanupEcsRun(instance.state, { keepRunning: this.options.taskOptions.keepRunning });
 			} catch (err) {
@@ -50712,6 +50934,39 @@ var ServiceController = class {
 	}
 };
 /**
+* Build the `--network-alias` map for one service's containers (design
+* doc § 5 Option A). For every Service Connect entry, attach the
+* fqdn (`<discoveryName>.<namespaceName>`), the bare discoveryName,
+* AND every ClientAlias DnsName to the container that owns the
+* matching PortName. Other containers in the task get NO extra
+* aliases (only their default `--name`-derived alias from
+* `buildDockerRunArgs`).
+*
+* Aliases per container are de-duplicated so docker doesn't reject
+* a `--network-alias X` repeated against the same container.
+*
+* Returns an empty map when the service has no Service Connect — the
+* runner's `... .size > 0 ? { networkAliasesByContainer } : {}` guard
+* short-circuits in that case so backward-compat callers pay no cost.
+*/
+function buildNetworkAliasesByContainer(service) {
+	const out = /* @__PURE__ */ new Map();
+	const sc = service.serviceConnect;
+	if (!sc) return out;
+	for (const entry of sc.services) {
+		const owner = service.task.containers.find((c) => c.portMappings.some((pm) => pm.name === entry.portName));
+		if (!owner) continue;
+		const aliases = [];
+		aliases.push(entry.discoveryName);
+		aliases.push(`${entry.discoveryName}.${sc.namespaceName}`);
+		for (const ca of entry.clientAliases) if (ca.dnsName) aliases.push(ca.dnsName);
+		const existing = out.get(owner.name) ?? [];
+		for (const a of aliases) if (!existing.includes(a)) existing.push(a);
+		out.set(owner.name, existing);
+	}
+	return out;
+}
+/**
 * Boot a single replica. Mutates the supplied `instance.state` so the
 * shutdown path's `cleanupEcsRun(instance.state)` covers every partial
 * side effect. Network names are suffixed with the replica index so
@@ -50720,15 +50975,99 @@ var ServiceController = class {
 async function bootReplica(service, options, instance) {
 	const logger = getLogger().child("ecs-service");
 	const perReplicaCluster = `${options.taskOptions.cluster}-svc-${service.serviceLogicalId.toLowerCase()}-r${instance.index}`;
-	const perReplicaSubnetOctet = 170 + instance.index % 84;
+	const ownerKeyPrefix = `${service.serviceLogicalId}:r${instance.index}`;
+	const addHostFlags = options.discovery?.registry ? options.discovery.registry.buildAddHostFlags(ownerKeyPrefix) : [];
+	const sharedNetwork = options.discovery?.sharedNetwork;
+	const networkAliasesByContainer = buildNetworkAliasesByContainer(service);
 	const perReplicaTaskOptions = {
 		...options.taskOptions,
 		cluster: perReplicaCluster,
-		subnetOctet: perReplicaSubnetOctet,
-		detach: true
+		detach: true,
+		...sharedNetwork ? { existingNetwork: sharedNetwork } : { subnetOctet: 170 + instance.index % 84 },
+		...addHostFlags.length > 0 ? { addHostFlags } : {},
+		...networkAliasesByContainer.size > 0 ? { networkAliasesByContainer } : {}
 	};
 	logger.info(`Booting replica ${instance.index} (${perReplicaCluster})`);
 	await runEcsTask(service.task, perReplicaTaskOptions, instance.state);
+	if (options.discovery) await publishReplicaToCloudMap(service, instance, options.discovery, ownerKeyPrefix);
+}
+/**
+* After the replica's main container is up, discover its docker
+* network IP and publish the configured Service Connect + Cloud Map
+* endpoints into the shared registry. The handles are tracked on the
+* instance so the shutdown / restart path can unregister symmetrically.
+*
+* Errors here are best-effort: docker inspect can fail right after run
+* (container vanished, network not fully wired), and the registry is
+* advisory — losing one replica's registration means peer services
+* can't reach it via the overlay, but it doesn't break that replica's
+* own work or AWS SDK calls.
+*/
+async function publishReplicaToCloudMap(service, instance, discovery, ownerKeyPrefix) {
+	const logger = getLogger().child("ecs-service");
+	const networkName = instance.state.network?.networkName;
+	if (!networkName) return;
+	const essential = service.task.containers.find((c) => c.essential) ?? service.task.containers[0];
+	if (!essential) return;
+	const started = instance.state.startedContainers.find((c) => c.name === essential.name);
+	if (!started) return;
+	let ip;
+	try {
+		ip = await getContainerNetworkIp(started.id, networkName);
+	} catch (err) {
+		logger.warn(`Replica ${instance.index}: docker inspect failed before Cloud Map publish: ${err instanceof Error ? err.message : String(err)}`);
+		return;
+	}
+	if (!ip) {
+		logger.warn(`Replica ${instance.index}: no docker IP discovered on network ${networkName}; skipping Cloud Map publish for this replica.`);
+		return;
+	}
+	if (service.serviceConnect) {
+		const ns = service.serviceConnect.namespaceName;
+		const index = discovery.cloudMapIndexByStack.get(service.stack.stackName);
+		if (index && !index.namespacesByName.has(ns)) logger.warn(`ECS Service '${service.serviceLogicalId}' ServiceConnectConfiguration.Namespace='${ns}' does not match any AWS::ServiceDiscovery::PrivateDnsNamespace declared in stack ${service.stack.stackName}. Publishing under the literal name anyway; peer services using the same literal will still discover this endpoint.`);
+		let i = 0;
+		for (const entry of service.serviceConnect.services) {
+			const ownerKey = `${ownerKeyPrefix}:sc:${i}`;
+			const handle = discovery.registry.register(ns, entry.discoveryName, {
+				ip,
+				port: entry.containerPort,
+				ownerKey
+			});
+			instance.cloudMapHandles.push(handle);
+			for (const alias of entry.clientAliases) if (alias.dnsName) discovery.registry.registerAlias(alias.dnsName, handle.fqdn);
+			i++;
+		}
+	}
+	if (service.serviceRegistries.length > 0) {
+		const index = discovery.cloudMapIndexByStack.get(service.stack.stackName);
+		if (!index) {
+			logger.warn(`ECS Service '${service.serviceLogicalId}' declares ServiceRegistries[] but cdkd has no Cloud Map index for stack ${service.stack.stackName}. Skipping registration.`);
+			return;
+		}
+		let j = 0;
+		for (const reg of service.serviceRegistries) {
+			const cm = index.servicesByLogicalId.get(reg.cloudMapServiceLogicalId);
+			if (!cm) {
+				logger.warn(`ECS Service '${service.serviceLogicalId}' ServiceRegistries[].cloudMapServiceLogicalId='${reg.cloudMapServiceLogicalId}' did not resolve to an AWS::ServiceDiscovery::Service in stack ${service.stack.stackName}. Skipping this registration.`);
+				continue;
+			}
+			let port = reg.containerPort;
+			if (port === void 0 && essential.portMappings.length > 0) port = essential.portMappings[0].containerPort;
+			if (port === void 0) {
+				logger.warn(`ECS Service '${service.serviceLogicalId}' ServiceRegistries[] entry for Cloud Map service '${cm.logicalId}' has no resolvable container port; skipping.`);
+				continue;
+			}
+			const ownerKey = `${ownerKeyPrefix}:sr:${j}`;
+			const handle = discovery.registry.register(cm.namespaceName, cm.name, {
+				ip,
+				port,
+				ownerKey
+			});
+			instance.cloudMapHandles.push(handle);
+			j++;
+		}
+	}
 }
 /**
 * Long-running watcher loop for one replica. Polls the essential
@@ -50762,6 +51101,12 @@ async function watchReplica(service, options, instance, runState) {
 		logger.info(`Restarting replica ${instance.index} in ${delay}ms...`);
 		await sleep(delay);
 		if (instance.shuttingDown || runState.shuttingDown) return;
+		if (options.discovery) {
+			for (const handle of instance.cloudMapHandles) try {
+				options.discovery.registry.unregister(handle);
+			} catch {}
+			instance.cloudMapHandles = [];
+		}
 		try {
 			await cleanupEcsRun(instance.state, { keepRunning: false });
 		} catch (err) {
@@ -50816,6 +51161,305 @@ function sleep(ms) {
 	return sleepImpl(ms);
 }
 
+//#endregion
+//#region src/local/cloud-map-registry.ts
+/**
+* In-process registry. `register()` is called by the service runner
+* after each replica's main container boot; `unregister()` is called by
+* the shutdown / restart paths. `lookupHosts()` produces the
+* `--add-host` flag list a consumer task's `docker run` injects so
+* `<discoveryName>.<namespace>` and (when registered as an alias)
+* bare `<discoveryName>` both resolve to a registered endpoint inside
+* the consumer container.
+*
+* Concurrency note: docker-run callers are not concurrent for the same
+* replica (the runner boots replicas sequentially), but `lookupHosts()`
+* MAY be called concurrently with `register()` / `unregister()` of an
+* unrelated service. The implementation uses synchronous Map mutations
+* so a stale read returns the previous snapshot — never a partially-
+* mutated one. No async / mutex needed.
+*/
+var CloudMapRegistry = class {
+	/** Map<fqdn, RegistryEntry[]> — one per replica registered under that fqdn. */
+	byFqdn = /* @__PURE__ */ new Map();
+	/**
+	* Map<alias, fqdn> — secondary index for ClientAlias short forms.
+	* Multiple aliases can point at the same fqdn; one alias only points
+	* at one fqdn (last write wins, with a warn surfaced by the resolver
+	* when a cross-namespace collision is detected — see design §O6).
+	*/
+	aliasIndex = /* @__PURE__ */ new Map();
+	/**
+	* Register a replica's endpoint under `{namespace}/{discoveryName}`.
+	*
+	* @param namespace Cloud Map namespace name, e.g. `cdkd-local.local`.
+	*                  An empty string is rejected — Cloud Map requires a
+	*                  named namespace.
+	* @param discoveryName Cloud Map service name, e.g. `orders`. Rejected
+	*                      when empty.
+	* @param endpoint Reachable endpoint + owner key for symmetric
+	*                 unregister.
+	* @returns A handle the caller stores for later `unregister(handle)`.
+	*/
+	register(namespace, discoveryName, endpoint) {
+		if (!namespace) throw new Error("CloudMapRegistry.register: namespace must be a non-empty string.");
+		if (!discoveryName) throw new Error("CloudMapRegistry.register: discoveryName must be a non-empty string.");
+		const fqdn = `${discoveryName}.${namespace}`;
+		const filtered = (this.byFqdn.get(fqdn) ?? []).filter((e) => e.endpoint.ownerKey !== endpoint.ownerKey);
+		filtered.push({
+			namespace,
+			discoveryName,
+			endpoint
+		});
+		this.byFqdn.set(fqdn, filtered);
+		return {
+			fqdn,
+			ownerKey: endpoint.ownerKey
+		};
+	}
+	/**
+	* Register a bare-name alias (`<discoveryName>` without the namespace
+	* suffix). Cloud Map / Service Connect does NOT auto-create such
+	* aliases — they're populated by `ClientAliases[].DnsName` entries in
+	* the consumer service's `ServiceConnectConfiguration`. Aliases are
+	* scoped per-CLI-invocation and last-write-wins on collision (the
+	* resolver surfaces a `warn` when this happens — see §O6).
+	*
+	* @param alias The bare discovery name (e.g. `orders` for an alias to
+	*              `orders.cdkd-local.local`).
+	* @param targetFqdn The full `{discoveryName}.{namespace}` the alias
+	*                   resolves to.
+	*/
+	registerAlias(alias, targetFqdn) {
+		if (!alias) throw new Error("CloudMapRegistry.registerAlias: alias must be a non-empty string.");
+		if (!targetFqdn) throw new Error("CloudMapRegistry.registerAlias: targetFqdn must be a non-empty string.");
+		this.aliasIndex.set(alias, targetFqdn);
+	}
+	/**
+	* Remove a single endpoint registered under the supplied handle.
+	* Idempotent — unknown handles return false without throwing.
+	*/
+	unregister(handle) {
+		const entries = this.byFqdn.get(handle.fqdn);
+		if (!entries) return false;
+		const filtered = entries.filter((e) => e.endpoint.ownerKey !== handle.ownerKey);
+		if (filtered.length === entries.length) return false;
+		if (filtered.length === 0) this.byFqdn.delete(handle.fqdn);
+		else this.byFqdn.set(handle.fqdn, filtered);
+		return true;
+	}
+	/**
+	* Drop every registration with the supplied owner key (e.g. teardown
+	* of every replica of a service). Used by the service controller's
+	* shutdown path; complementary to per-replica `unregister`.
+	*/
+	unregisterByOwner(ownerKeyPrefix) {
+		let removed = 0;
+		for (const [fqdn, entries] of [...this.byFqdn.entries()]) {
+			const filtered = entries.filter((e) => !e.endpoint.ownerKey.startsWith(ownerKeyPrefix));
+			removed += entries.length - filtered.length;
+			if (filtered.length === 0) this.byFqdn.delete(fqdn);
+			else this.byFqdn.set(fqdn, filtered);
+		}
+		return removed;
+	}
+	/**
+	* Look up every endpoint registered under `{discoveryName}.{namespace}`.
+	* Returns `undefined` when no endpoint exists (which is the consumer
+	* runner's signal to log a warn — the user likely forgot to start the
+	* producer). Returns the underlying array verbatim so callers cannot
+	* accidentally mutate registry state — call `.slice()` if you need a
+	* detachable copy.
+	*/
+	lookup(namespace, discoveryName) {
+		const fqdn = `${discoveryName}.${namespace}`;
+		const entries = this.byFqdn.get(fqdn);
+		if (!entries || entries.length === 0) return void 0;
+		return entries.map((e) => e.endpoint);
+	}
+	/**
+	* Resolve a bare alias to its target endpoints. Returns the same
+	* shape as `lookup` for the alias's target fqdn, or `undefined` when
+	* no such alias exists (which is distinct from "alias known but
+	* target has no live replica" — caller may want different warns).
+	*/
+	lookupAlias(alias) {
+		const fqdn = this.aliasIndex.get(alias);
+		if (!fqdn) return void 0;
+		const entries = this.byFqdn.get(fqdn);
+		if (!entries || entries.length === 0) return void 0;
+		return entries.map((e) => e.endpoint);
+	}
+	/**
+	* Build the `--add-host` flag list for a consumer container's
+	* `docker run`. Returns each unique `(hostname, ip)` pair as a flat
+	* `['--add-host', 'name:ip', ...]` array consumable verbatim by the
+	* docker-runner. Includes both the fqdn AND every alias mapped to it.
+	*
+	* Multiple replicas per fqdn cannot be expressed as multiple
+	* `--add-host` entries with the same name (docker's resolver takes
+	* the *last* entry on duplicate keys per `getent hosts` semantics),
+	* so this returns the **first** registered endpoint per fqdn /
+	* alias. Multi-instance round-robin via the static `--add-host`
+	* shape is structurally impossible; a true rotation requires the
+	* DNS-sidecar option (deferred). Documented as a v1 limitation.
+	*/
+	buildAddHostFlags(excludeOwnerKeyPrefix) {
+		const flags = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const [fqdn, entries] of this.byFqdn.entries()) {
+			const candidate = entries.find((e) => !excludeOwnerKeyPrefix || !e.endpoint.ownerKey.startsWith(excludeOwnerKeyPrefix));
+			if (!candidate) continue;
+			if (seen.has(fqdn)) continue;
+			flags.push("--add-host", `${fqdn}:${candidate.endpoint.ip}`);
+			seen.add(fqdn);
+		}
+		for (const [alias, targetFqdn] of this.aliasIndex.entries()) {
+			if (seen.has(alias)) continue;
+			const entries = this.byFqdn.get(targetFqdn);
+			if (!entries || entries.length === 0) continue;
+			const candidate = entries.find((e) => !excludeOwnerKeyPrefix || !e.endpoint.ownerKey.startsWith(excludeOwnerKeyPrefix));
+			if (!candidate) continue;
+			flags.push("--add-host", `${alias}:${candidate.endpoint.ip}`);
+			seen.add(alias);
+		}
+		return flags;
+	}
+	/**
+	* Diagnostic snapshot used by the boot banner / test assertions.
+	* Stable iteration order (insertion-order is preserved by JS Maps).
+	*/
+	list() {
+		const out = [];
+		for (const [, entries] of this.byFqdn.entries()) {
+			if (entries.length === 0) continue;
+			const first = entries[0];
+			out.push({
+				namespace: first.namespace,
+				discoveryName: first.discoveryName,
+				endpoints: entries.map((e) => e.endpoint),
+				isAlias: false
+			});
+		}
+		for (const [alias, fqdn] of this.aliasIndex.entries()) {
+			const entries = this.byFqdn.get(fqdn);
+			if (!entries || entries.length === 0) continue;
+			out.push({
+				namespace: "",
+				discoveryName: alias,
+				endpoints: entries.map((e) => e.endpoint),
+				isAlias: true
+			});
+		}
+		return out;
+	}
+	/** True when no endpoint is registered. Used by the runner to short-circuit. */
+	isEmpty() {
+		return this.byFqdn.size === 0;
+	}
+};
+
+//#endregion
+//#region src/local/cloud-map-resolver.ts
+/**
+* Build the `CloudMapIndex` for one stack's template. Empty index when
+* the stack declares no `AWS::ServiceDiscovery::*` resources.
+*
+* Hard-reject errors (throw `EcsTaskResolutionError`):
+*   - `AWS::ServiceDiscovery::PublicDnsNamespace` — defeats "local" semantics.
+*   - `AWS::ServiceDiscovery::HttpNamespace` — DiscoverInstances-only,
+*     no DNS, would require shimming the AWS SDK inside every container.
+*   - An `AWS::ServiceDiscovery::Service` with a `NamespaceId` that
+*     doesn't resolve to a same-stack `PrivateDnsNamespace`.
+*/
+function buildCloudMapIndex(stack) {
+	const namespacesByLogicalId = /* @__PURE__ */ new Map();
+	const namespacesByName = /* @__PURE__ */ new Map();
+	const servicesByLogicalId = /* @__PURE__ */ new Map();
+	const warnings = [];
+	const resources = stack.template.Resources ?? {};
+	for (const [logicalId, resource] of Object.entries(resources)) {
+		if (resource.Type === "AWS::ServiceDiscovery::PublicDnsNamespace") throw new EcsTaskResolutionError(`Stack ${stack.stackName}: AWS::ServiceDiscovery::PublicDnsNamespace '${logicalId}' is not supported by local emulation — public DNS defeats the "local" point. Use a PrivateDnsNamespace for cdkd local start-service.`);
+		if (resource.Type === "AWS::ServiceDiscovery::HttpNamespace") throw new EcsTaskResolutionError(`Stack ${stack.stackName}: AWS::ServiceDiscovery::HttpNamespace '${logicalId}' is not supported by local emulation — HttpNamespace uses the AWS Cloud Map DiscoverInstances API directly (no DNS), which would require shimming the AWS SDK inside every container. Use a PrivateDnsNamespace + DnsConfig instead.`);
+		if (resource.Type !== "AWS::ServiceDiscovery::PrivateDnsNamespace") continue;
+		const props = resource.Properties ?? {};
+		const name = typeof props["Name"] === "string" ? props["Name"] : void 0;
+		if (!name) throw new EcsTaskResolutionError(`Stack ${stack.stackName}: PrivateDnsNamespace '${logicalId}' has no literal Name property. Intrinsic-valued names are not supported (cross-stack / dynamic namespace names require deploy-state resolution which is out of scope for v1).`);
+		const entry = {
+			logicalId,
+			name
+		};
+		namespacesByLogicalId.set(logicalId, entry);
+		if (namespacesByName.has(name)) warnings.push(`Stack ${stack.stackName}: two PrivateDnsNamespace resources share Name='${name}' ('${namespacesByName.get(name).logicalId}' and '${logicalId}'). Local emulation routes registrations to the first; the second will silently shadow.`);
+		else namespacesByName.set(name, entry);
+	}
+	for (const [logicalId, resource] of Object.entries(resources)) {
+		if (resource.Type !== "AWS::ServiceDiscovery::Service") continue;
+		const props = resource.Properties ?? {};
+		const namespaceLogicalId = resolveNamespaceIdRef(props["NamespaceId"] ?? props["DnsConfig"]?.["NamespaceId"], stack.stackName, logicalId);
+		const ns = namespacesByLogicalId.get(namespaceLogicalId);
+		if (!ns) throw new EcsTaskResolutionError(`Stack ${stack.stackName}: AWS::ServiceDiscovery::Service '${logicalId}' references NamespaceId '${namespaceLogicalId}' but no PrivateDnsNamespace with that logical id exists in this stack. Cross-stack Cloud Map namespaces are not supported in v1.`);
+		const name = typeof props["Name"] === "string" ? props["Name"] : void 0;
+		if (!name) throw new EcsTaskResolutionError(`Stack ${stack.stackName}: AWS::ServiceDiscovery::Service '${logicalId}' has no literal Name property. Intrinsic-valued names are not supported in v1.`);
+		const dnsRecords = extractDnsRecords(props);
+		servicesByLogicalId.set(logicalId, {
+			logicalId,
+			namespaceLogicalId,
+			namespaceName: ns.name,
+			name,
+			dnsRecords
+		});
+	}
+	return {
+		namespacesByLogicalId,
+		namespacesByName,
+		servicesByLogicalId,
+		warnings
+	};
+}
+/**
+* Resolve `NamespaceId` to the parent's logical id. CDK 2.x synthesizes
+* this as `{Fn::GetAtt: ['<NsLogicalId>', 'Id']}` (verified via real
+* `cdk synth` on 2026-05-22). `Ref` is also accepted defensively
+* (returns the namespace's physical id, but inside one synth template
+* the Ref target IS the logical id we want).
+*
+* Cross-stack / intrinsic shapes that we cannot resolve at synth time
+* are hard-rejected — cdkd would otherwise silently route to no
+* namespace and the consumer would get an unhelpful "DNS lookup failed"
+* at runtime.
+*/
+function resolveNamespaceIdRef(raw, stackName, serviceLogicalId) {
+	if (typeof raw === "string") return raw;
+	if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+		const obj = raw;
+		if (typeof obj["Ref"] === "string") return obj["Ref"];
+		const getAtt = obj["Fn::GetAtt"];
+		if (Array.isArray(getAtt) && typeof getAtt[0] === "string") return getAtt[0];
+	}
+	throw new EcsTaskResolutionError(`Stack ${stackName}: AWS::ServiceDiscovery::Service '${serviceLogicalId}' has an unsupported NamespaceId reference shape: ${JSON.stringify(raw)}. Accepted shapes are {Fn::GetAtt: [<NsLogicalId>, 'Id']} or {Ref: <NsLogicalId>} pointing at a same-stack PrivateDnsNamespace.`);
+}
+function extractDnsRecords(serviceProps) {
+	const dnsConfig = serviceProps["DnsConfig"];
+	if (!dnsConfig || typeof dnsConfig !== "object") return [];
+	const records = dnsConfig["DnsRecords"];
+	if (!Array.isArray(records)) return [];
+	const out = [];
+	for (const r of records) {
+		if (!r || typeof r !== "object") continue;
+		const obj = r;
+		const type = obj["Type"];
+		if (type !== "A" && type !== "SRV") continue;
+		const ttl = obj["TTL"];
+		const ttlSeconds = typeof ttl === "number" && Number.isFinite(ttl) && ttl >= 0 ? Math.floor(ttl) : typeof ttl === "string" && /^\d+$/.test(ttl) ? parseInt(ttl, 10) : 60;
+		out.push({
+			type,
+			ttlSeconds
+		});
+	}
+	return out;
+}
+
 //#endregion
 //#region src/cli/commands/local-start-service.ts
 /**
@@ -50830,17 +51474,34 @@ function sleep(ms) {
 *   - Rolling deployment (`--watch` / `--reload`) — PR D of #466.
 *   - Service Connect / Cloud Map — tracked separately in #460.
 */
-async function localStartServiceCommand(target, options) {
+async function localStartServiceCommand(targets, options) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
 	warnIfDeprecatedRegion(options);
-	const runState = createServiceRunState();
+	if (!targets || targets.length === 0) throw new LocalStartServiceError("cdkd local start-service requires at least one <target>. Pass one or more service paths like 'Stack/Orders' 'Stack/Frontend'.");
+	const perTarget = targets.map((t) => ({
+		target: t,
+		runState: createServiceRunState()
+	}));
 	let sigintHandler;
 	let sigintCount = 0;
-	let controller;
+	let sharedNetwork;
 	const cleanup = singleFlight(async () => {
-		if (controller) await controller.shutdown();
-		else await Promise.allSettled(runState.replicas.map((r) => cleanupEcsRun(r.state, { keepRunning: false }).catch(() => void 0)));
+		await Promise.allSettled(perTarget.map(async (pt) => {
+			if (pt.controller) await pt.controller.shutdown();
+			else {
+				await Promise.allSettled(pt.runState.replicas.map((r) => r.inFlightBoot).filter((p) => p !== void 0));
+				await Promise.allSettled(pt.runState.replicas.map((r) => cleanupEcsRun(r.state, { keepRunning: false }).catch(() => void 0)));
+			}
+		}));
+		if (sharedNetwork) {
+			try {
+				await destroyTaskNetwork(sharedNetwork);
+			} catch (err) {
+				getLogger().warn(`shared service network teardown failed: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			sharedNetwork = void 0;
+		}
 	}, (err) => getLogger().warn(`service cleanup failed: ${err instanceof Error ? err.message : String(err)}`));
 	try {
 		await applyRoleArnIfSet({
@@ -50863,72 +51524,42 @@ async function localStartServiceCommand(target, options) {
 			...options.profile && { macroExpandS3ClientOpts: { profile: options.profile } }
 		};
 		const { stacks } = await synthesizer.synthesize(synthOpts);
-		const imageContext = await buildEcsImageResolutionContext(target, stacks, options);
-		const service = resolveEcsServiceTarget(target, stacks, imageContext);
-		logger.info(`Target: ${service.stack.stackName}/${service.serviceLogicalId} (service=${service.serviceName}, desiredCount=${service.desiredCount}, task=${service.task.taskDefinitionLogicalId})`);
-		const taskNeeds = detectEcsImageResolutionNeeds(stacks.find((s) => s.stackName === service.stack.stackName) ?? service.stack);
-		if (options.fromState && taskNeeds.needsCrossStackResolver) {
-			const consumerRegion = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? service.stack.region ?? "us-east-1";
-			const built = await buildCrossStackResolver(consumerRegion, {
-				...options.stateBucket !== void 0 && { stateBucket: options.stateBucket },
-				statePrefix: options.statePrefix,
-				...options.region !== void 0 && { region: options.region },
-				...options.profile !== void 0 && { profile: options.profile }
+		const cloudMapIndexByStack = /* @__PURE__ */ new Map();
+		for (const stack of stacks) {
+			const index = buildCloudMapIndex(stack);
+			cloudMapIndexByStack.set(stack.stackName, index);
+			for (const w of index.warnings) logger.warn(w);
+		}
+		const registry = new CloudMapRegistry();
+		try {
+			sharedNetwork = await createSharedSvcNetwork({
+				prefix: options.cluster,
+				skipPull: options.pull === false,
+				cluster: options.cluster
 			});
-			if (built) try {
-				const subContext = {
-					resources: imageContext?.stateResources ?? {},
-					...imageContext?.pseudoParameters && { pseudoParameters: imageContext.pseudoParameters },
-					consumerRegion,
-					crossStackResolver: built.resolver
-				};
-				await applyCrossStackResolverToTask(service.task, subContext);
-			} finally {
-				built.dispose();
-			}
-		} else if (!options.fromState && taskNeeds.needsCrossStackResolver) logger.warn("Container Environment / Secrets entries contain Fn::ImportValue / Fn::GetStackOutput intrinsics. Pass --from-state to substitute them against deployed cdkd state.");
+		} catch (err) {
+			throw new LocalStartServiceError(`Failed to create shared service network: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		const discovery = {
+			registry,
+			cloudMapIndexByStack,
+			sharedNetwork
+		};
 		sigintHandler = () => {
 			sigintCount += 1;
 			if (sigintCount >= 2) {
 				process.stderr.write("Force-exit on second ^C; container cleanup skipped.\n");
 				process.exit(130);
 			}
-			logger.info("Stopping service...");
+			logger.info("Stopping service(s)...");
 			cleanup().then(() => process.exit(130));
 		};
 		process.on("SIGINT", sigintHandler);
 		process.on("SIGTERM", sigintHandler);
-		let assumedCredentials;
-		let resolvedRoleArn;
-		if (options.assumeTaskRole === true) {
-			if (!service.task.taskRoleArn) throw new LocalStartServiceError("--assume-task-role passed without an ARN but the task definition has no resolvable TaskRoleArn. Pass the ARN explicitly: --assume-task-role <arn>");
-			resolvedRoleArn = await resolvePlaceholderAccount(service.task.taskRoleArn, options.region);
-			assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region);
-		} else if (typeof options.assumeTaskRole === "string") {
-			resolvedRoleArn = options.assumeTaskRole;
-			assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region);
-		}
-		const envOverrides = readEnvOverridesFile$1(options.envVars);
-		const taskOpts = {
-			cluster: options.cluster,
-			containerHost: options.containerHost,
-			skipPull: options.pull === false,
-			keepRunning: false,
-			detach: true
-		};
-		if (envOverrides) taskOpts.envOverrides = envOverrides;
-		if (assumedCredentials) taskOpts.taskCredentials = assumedCredentials;
-		if (resolvedRoleArn) taskOpts.taskRoleArn = resolvedRoleArn;
-		if (options.platform) taskOpts.platformOverride = options.platform;
-		if (options.region) taskOpts.region = options.region;
-		if (options.ecrRoleArn) taskOpts.ecrRoleArn = options.ecrRoleArn;
-		controller = await startEcsService(service, {
-			maxTasks: options.maxTasks,
-			restartPolicy: options.restartPolicy,
-			taskOptions: taskOpts
-		}, runState);
-		logger.info(`Service '${service.serviceName}' running with ${controller.activeReplicaCount()} active replica(s). Press ^C to shut down.`);
-		await controller.waitForShutdown();
+		for (const pt of perTarget) pt.controller = await bootOneTarget(pt.target, pt.runState, stacks, options, discovery);
+		const summary = perTarget.map((pt) => `${pt.controller.service.serviceName} (${pt.controller.activeReplicaCount()} replica(s))`).join(", ");
+		logger.info(`Service(s) running: ${summary}. Press ^C to shut down.`);
+		await Promise.all(perTarget.map((pt) => pt.controller.waitForShutdown()));
 	} finally {
 		if (sigintHandler) {
 			process.off("SIGINT", sigintHandler);
@@ -50937,6 +51568,72 @@ async function localStartServiceCommand(target, options) {
 		await cleanup();
 	}
 }
+/**
+* Boot one target. Extracted from the loop so each per-service block
+* (image context, cross-stack resolver, task-role credentials, runner
+* options) is scoped locally. Returns the started controller for the
+* outer code to wait + tear down.
+*/
+async function bootOneTarget(target, runState, stacks, options, discovery) {
+	const logger = getLogger();
+	const imageContext = await buildEcsImageResolutionContext(target, stacks, options);
+	const service = resolveEcsServiceTarget(target, stacks, imageContext);
+	logger.info(`Target: ${service.stack.stackName}/${service.serviceLogicalId} (service=${service.serviceName}, desiredCount=${service.desiredCount}, task=${service.task.taskDefinitionLogicalId})`);
+	for (const w of service.warnings) logger.warn(w);
+	if (service.serviceConnect) logger.info(`Service Connect: namespace='${service.serviceConnect.namespaceName}', ${service.serviceConnect.services.length} service(s) registered for peer discovery.`);
+	if (service.serviceRegistries.length > 0) logger.info(`Cloud Map: ${service.serviceRegistries.length} ServiceRegistry binding(s).`);
+	const taskNeeds = detectEcsImageResolutionNeeds(stacks.find((s) => s.stackName === service.stack.stackName) ?? service.stack);
+	if (options.fromState && taskNeeds.needsCrossStackResolver) {
+		const consumerRegion = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? service.stack.region ?? "us-east-1";
+		const built = await buildCrossStackResolver(consumerRegion, {
+			...options.stateBucket !== void 0 && { stateBucket: options.stateBucket },
+			statePrefix: options.statePrefix,
+			...options.region !== void 0 && { region: options.region },
+			...options.profile !== void 0 && { profile: options.profile }
+		});
+		if (built) try {
+			const subContext = {
+				resources: imageContext?.stateResources ?? {},
+				...imageContext?.pseudoParameters && { pseudoParameters: imageContext.pseudoParameters },
+				consumerRegion,
+				crossStackResolver: built.resolver
+			};
+			await applyCrossStackResolverToTask(service.task, subContext);
+		} finally {
+			built.dispose();
+		}
+	} else if (!options.fromState && taskNeeds.needsCrossStackResolver) logger.warn("Container Environment / Secrets entries contain Fn::ImportValue / Fn::GetStackOutput intrinsics. Pass --from-state to substitute them against deployed cdkd state.");
+	let assumedCredentials;
+	let resolvedRoleArn;
+	if (options.assumeTaskRole === true) {
+		if (!service.task.taskRoleArn) throw new LocalStartServiceError(`--assume-task-role passed without an ARN but service '${service.serviceLogicalId}' has no resolvable TaskRoleArn. Pass the ARN explicitly: --assume-task-role <arn>`);
+		resolvedRoleArn = await resolvePlaceholderAccount(service.task.taskRoleArn, options.region);
+		assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region);
+	} else if (typeof options.assumeTaskRole === "string") {
+		resolvedRoleArn = options.assumeTaskRole;
+		assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region);
+	}
+	const envOverrides = readEnvOverridesFile$1(options.envVars);
+	const taskOpts = {
+		cluster: options.cluster,
+		containerHost: options.containerHost,
+		skipPull: options.pull === false,
+		keepRunning: false,
+		detach: true
+	};
+	if (envOverrides) taskOpts.envOverrides = envOverrides;
+	if (assumedCredentials) taskOpts.taskCredentials = assumedCredentials;
+	if (resolvedRoleArn) taskOpts.taskRoleArn = resolvedRoleArn;
+	if (options.platform) taskOpts.platformOverride = options.platform;
+	if (options.region) taskOpts.region = options.region;
+	if (options.ecrRoleArn) taskOpts.ecrRoleArn = options.ecrRoleArn;
+	return startEcsService(service, {
+		maxTasks: options.maxTasks,
+		restartPolicy: options.restartPolicy,
+		taskOptions: taskOpts,
+		discovery
+	}, runState);
+}
 async function resolvePlaceholderAccount(arn, region) {
 	if (!arn.includes("${AWS::AccountId}")) return arn;
 	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
@@ -51079,7 +51776,7 @@ function parseRestartPolicy(raw) {
 	throw new LocalStartServiceError(`--restart-policy must be one of 'on-failure', 'always', or 'none' (got '${raw}').`);
 }
 function createLocalStartServiceCommand() {
-	const cmd = new Command("start-service").description("Run an AWS::ECS::Service locally as a long-running emulator. Spins up DesiredCount task replicas (clamped by --max-tasks) using the same per-task docker network + metadata sidecar pattern as `cdkd local run-task`, then keeps each replica running and restarts it on exit per --restart-policy. ^C tears every replica + sidecar + network down. Target accepts a CDK display path (MyStack/MyService) or stack-qualified logical ID (MyStack:MyServiceXYZ); single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the AWS::ECS::Service to run").addOption(new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default("cdkd-local")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"ContainerName\":{\"KEY\":\"VALUE\"}, \"Parameters\":{}})")).addOption(new Option("--container-host <ip>", "Host IP to bind published container ports to. Must be a numeric IP (Docker rejects hostnames here)").default("127.0.0.1")).addOption(new Option("--assume-task-role [arn]", "Assume the task definition's TaskRoleArn (or the supplied ARN) and forward STS-issued temp credentials via the metadata sidecar so containers run with the deployed task role. Bare flag uses the template's TaskRoleArn; pass an explicit ARN to override.")).addOption(new Option("--no-pull", "Skip docker pull for every container image and the metadata sidecar")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries.")).addOption(new Option("--platform <platform>", "Force docker --platform (linux/amd64 or linux/arm64). Default: inferred from task RuntimePlatform.CpuArchitecture")).addOption(new Option("--max-tasks <n>", `Hard cap on local replica count. Caps the template DesiredCount so local dev machines don't run an unbounded number of containers. Cannot exceed ${84} due to the per-replica link-local /24 subnet allocator's range.`).default(3).argParser(parseMaxTasks)).addOption(new Option("--restart-policy <policy>", "How to react when an essential container exits. 'on-failure' (default) restarts only on non-zero exit; 'always' restarts on every exit; 'none' shuts the replica down and runs the service degraded.").default("on-failure").argParser(parseRestartPolicy)).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Fn::Sub / Fn::GetAtt / Fn::ImportValue / Fn::GetStackOutput intrinsics in container images, environment variables, secrets, role ARNs, and volumes.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localStartServiceCommand));
+	const cmd = new Command("start-service").description("Run one or more AWS::ECS::Service resources locally as a long-running emulator. Spins up DesiredCount task replicas per service (clamped by --max-tasks) using the same per-task docker network + metadata sidecar pattern as `cdkd local run-task`, then keeps each replica running and restarts it on exit per --restart-policy. ^C tears every replica + sidecar + network down. Each <target> accepts a CDK display path (MyStack/MyService) or stack-qualified logical ID (MyStack:MyServiceXYZ); single-stack apps may omit the stack prefix. When two or more <target>s are supplied, every service is booted into a shared Cloud Map / Service Connect registry so peer services discover each other via docker --add-host overlay (Issue #460).").argument("<targets...>", "One or more CDK display paths or stack-qualified logical IDs of the AWS::ECS::Service resources to run").addOption(new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default("cdkd-local")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"ContainerName\":{\"KEY\":\"VALUE\"}, \"Parameters\":{}})")).addOption(new Option("--container-host <ip>", "Host IP to bind published container ports to. Must be a numeric IP (Docker rejects hostnames here)").default("127.0.0.1")).addOption(new Option("--assume-task-role [arn]", "Assume the task definition's TaskRoleArn (or the supplied ARN) and forward STS-issued temp credentials via the metadata sidecar so containers run with the deployed task role. Bare flag uses the template's TaskRoleArn; pass an explicit ARN to override.")).addOption(new Option("--no-pull", "Skip docker pull for every container image and the metadata sidecar")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries.")).addOption(new Option("--platform <platform>", "Force docker --platform (linux/amd64 or linux/arm64). Default: inferred from task RuntimePlatform.CpuArchitecture")).addOption(new Option("--max-tasks <n>", `Hard cap on local replica count. Caps the template DesiredCount so local dev machines don't run an unbounded number of containers. Cannot exceed ${84} due to the per-replica link-local /24 subnet allocator's range.`).default(3).argParser(parseMaxTasks)).addOption(new Option("--restart-policy <policy>", "How to react when an essential container exits. 'on-failure' (default) restarts only on non-zero exit; 'always' restarts on every exit; 'none' shuts the replica down and runs the service degraded.").default("on-failure").argParser(parseRestartPolicy)).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Fn::Sub / Fn::GetAtt / Fn::ImportValue / Fn::GetStackOutput intrinsics in container images, environment variables, secrets, role ARNs, and volumes.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localStartServiceCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -54262,7 +54959,7 @@ function reorderArgs(argv) {
 */
 async function main() {
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.138.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.139.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());