@go-to-k/cdkd 0.130.0 → 0.131.0

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { a as setAwsClients, i as resetAwsClients, r as getAwsClients, t as AwsClients } from "./aws-clients-CuHRHcyW.js";
-import { A as AssetPublisher, B as getLegacyStateBucketName, C as applyRoleArnIfSet, Ct as generateResourceNameWithFallback, D as LockManager, E as TemplateParser, F as getDockerCmd, G as resolveStateBucketWithDefaultAndSource, H as resolveCaptureObservedState, I as runDockerForeground, K as warnDeprecatedNoPrefixCliFlag, L as runDockerStreaming, M as WorkGraph, N as buildDockerImage, O as S3StateBackend, P as formatDockerLoginError, R as Synthesizer, S as IntrinsicFunctionResolver, St as generateResourceName, T as DagBuilder, Tt as withStackName, U as resolveSkipPrefix, V as resolveApp, W as resolveStateBucketWithDefault, Y as resolveBucketRegion, Z as CdkdError, _ as normalizeAwsTagsToCfn, a as withRetry, at as ResourceUpdateNotSupportedError, b as CloudControlProvider, bt as PATTERN_B_NAME_PROPERTIES, c as cyan, ct as StackTerminationProtectionError, d as red, et as LocalInvokeBuildError, f as yellow, g as matchesCdkPath, gt as getLogger, h as CDK_PATH_TAG, i as withResourceDeadline, it as ResourceTimeoutError, j as stringifyValue, k as shouldRetainResource, l as gray, m as collectInlinePolicyNamesManagedBySiblings, mt as withErrorHandling, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nt as PartialFailureError, o as IMPLICIT_DELETE_DEPENDENCIES, ot as RouteDiscoveryError, p as IAMRoleProvider, pt as normalizeAwsError, q as AssemblyReader, r as DeployEngine, rt as ProvisioningError, s as bold, st as StackHasActiveImportsError, t as DEFAULT_RESOURCE_TIMEOUT_MS, u as green, v as resolveExplicitPhysicalId, vt as runStackBuffered, w as DiffCalculator, wt as withSkipPrefix, x as assertRegionMatch, xt as PATTERN_B_RESOURCE_TYPES, y as ProviderRegistry, yt as getLiveRenderer, z as getDefaultStateBucketName } from "./deploy-engine-B-w4C_7O.js";
+import { _ as withSkipPrefix, a as runDockerStreaming, c as getLogger, d as getLiveRenderer, f as PATTERN_B_NAME_PROPERTIES, g as generateResourceNameWithFallback, h as generateResourceName, i as runDockerForeground, n as formatDockerLoginError, p as PATTERN_B_RESOURCE_TYPES, r as getDockerCmd, u as runStackBuffered, v as withStackName } from "./docker-cmd-EtWSTAje.js";
+import { $ as PartialFailureError, A as AssetPublisher, B as resolveStateBucketWithDefault, C as applyRoleArnIfSet, D as LockManager, E as TemplateParser, F as getDefaultStateBucketName, G as resolveBucketRegion, H as warnDeprecatedNoPrefixCliFlag, I as getLegacyStateBucketName, L as resolveApp, M as WorkGraph, N as buildDockerImage, O as S3StateBackend, P as Synthesizer, R as resolveCaptureObservedState, S as IntrinsicFunctionResolver, T as DagBuilder, U as AssemblyReader, V as resolveStateBucketWithDefaultAndSource, X as LocalInvokeBuildError, Z as LocalStartServiceError, _ as normalizeAwsTagsToCfn, a as withRetry, at as StackTerminationProtectionError, b as CloudControlProvider, c as cyan, d as red, dt as withErrorHandling, et as ProvisioningError, f as yellow, g as matchesCdkPath, h as CDK_PATH_TAG, i as withResourceDeadline, it as StackHasActiveImportsError, j as stringifyValue, k as shouldRetainResource, l as gray, m as collectInlinePolicyNamesManagedBySiblings, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nt as ResourceUpdateNotSupportedError, o as IMPLICIT_DELETE_DEPENDENCIES, p as IAMRoleProvider, q as CdkdError, r as DeployEngine, rt as RouteDiscoveryError, s as bold, t as DEFAULT_RESOURCE_TIMEOUT_MS, tt as ResourceTimeoutError, u as green, ut as normalizeAwsError, v as resolveExplicitPhysicalId, w as DiffCalculator, x as assertRegionMatch, y as ProviderRegistry, z as resolveSkipPrefix } from "./deploy-engine-Dn7oV5rA.js";
+import { a as setAwsClients, i as resetAwsClients, r as getAwsClients, t as AwsClients } from "./aws-clients-BF03Alpe.js";
 import { createHash, createHmac, createPublicKey, createVerify, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { CopyObjectCommand, CreateBucketCommand, DeleteBucketAnalyticsConfigurationCommand, DeleteBucketCommand, DeleteBucketCorsCommand, DeleteBucketIntelligentTieringConfigurationCommand, DeleteBucketInventoryConfigurationCommand, DeleteBucketLifecycleCommand, DeleteBucketMetricsConfigurationCommand, DeleteBucketPolicyCommand, DeleteBucketReplicationCommand, DeleteBucketTaggingCommand, DeleteBucketWebsiteCommand, DeleteObjectCommand, DeleteObjectsCommand, GetBucketAccelerateConfigurationCommand, GetBucketCorsCommand, GetBucketEncryptionCommand, GetBucketLifecycleConfigurationCommand, GetBucketLocationCommand, GetBucketLoggingCommand, GetBucketNotificationConfigurationCommand, GetBucketPolicyCommand, GetBucketReplicationCommand, GetBucketTaggingCommand, GetBucketVersioningCommand, GetBucketWebsiteCommand, GetObjectCommand, GetObjectLockConfigurationCommand, GetPublicAccessBlockCommand, HeadBucketCommand, ListBucketAnalyticsConfigurationsCommand, ListBucketIntelligentTieringConfigurationsCommand, ListBucketInventoryConfigurationsCommand, ListBucketMetricsConfigurationsCommand, ListBucketsCommand, ListDirectoryBucketsCommand, ListObjectVersionsCommand, ListObjectsV2Command, NoSuchBucket, PutBucketAccelerateConfigurationCommand, PutBucketAnalyticsConfigurationCommand, PutBucketCorsCommand, PutBucketEncryptionCommand, PutBucketIntelligentTieringConfigurationCommand, PutBucketInventoryConfigurationCommand, PutBucketLifecycleConfigurationCommand, PutBucketLoggingCommand, PutBucketMetricsConfigurationCommand, PutBucketNotificationConfigurationCommand, PutBucketOwnershipControlsCommand, PutBucketPolicyCommand, PutBucketReplicationCommand, PutBucketTaggingCommand, PutBucketVersioningCommand, PutBucketWebsiteCommand, PutObjectCommand, PutObjectLockConfigurationCommand, PutPublicAccessBlockCommand, S3Client, S3ServiceException } from "@aws-sdk/client-s3";
 import { AddRoleToInstanceProfileCommand, AddUserToGroupCommand, AttachGroupPolicyCommand, AttachUserPolicyCommand, CreateGroupCommand, CreateInstanceProfileCommand, CreateLoginProfileCommand, CreateUserCommand, DeleteAccessKeyCommand, DeleteGroupCommand, DeleteGroupPolicyCommand, DeleteInstanceProfileCommand, DeleteLoginProfileCommand, DeleteRolePolicyCommand, DeleteUserCommand, DeleteUserPermissionsBoundaryCommand, DeleteUserPolicyCommand, DetachGroupPolicyCommand, DetachUserPolicyCommand, GetGroupCommand, GetGroupPolicyCommand, GetInstanceProfileCommand, GetRolePolicyCommand, GetUserCommand, GetUserPolicyCommand, IAMClient, ListAccessKeysCommand, ListAttachedGroupPoliciesCommand, ListAttachedUserPoliciesCommand, ListGroupPoliciesCommand, ListGroupsForUserCommand, ListInstanceProfilesCommand, ListUserPoliciesCommand, ListUserTagsCommand, ListUsersCommand, NoSuchEntityException, PutGroupPolicyCommand, PutRolePolicyCommand, PutUserPermissionsBoundaryCommand, PutUserPolicyCommand, RemoveRoleFromInstanceProfileCommand, RemoveUserFromGroupCommand, TagUserCommand, UntagUserCommand, UpdateLoginProfileCommand } from "@aws-sdk/client-iam";
@@ -36541,14 +36542,14 @@ function parseTarget(target) {
 function resolveLambdaTarget(target, stacks) {
 	if (stacks.length === 0) throw new LocalInvokeResolutionError("No stacks found in the synthesized assembly.");
 	const parsed = parseTarget(target);
-	const stack = pickStack$1(parsed, stacks);
+	const stack = pickStack$2(parsed, stacks);
 	const template = stack.template;
 	const resources = template.Resources ?? {};
 	let match;
 	if (parsed.isPath) {
 		const index = buildCdkPathIndex(template);
 		const lambdaMatches = resolveCdkPathToLogicalIds(parsed.pathOrId, index).filter(({ logicalId }) => resources[logicalId]?.Type === "AWS::Lambda::Function");
-		if (lambdaMatches.length === 0) throw notFoundError$1(target, stack, resources);
+		if (lambdaMatches.length === 0) throw notFoundError$2(target, stack, resources);
 		if (lambdaMatches.length > 1) throw new LocalInvokeResolutionError(`Target '${target}' matches ${lambdaMatches.length} Lambda functions in ${stack.stackName}: ` + lambdaMatches.map((m) => m.logicalId).join(", ") + ". Refine the path or use the stack:LogicalId form.");
 		const m = lambdaMatches[0];
 		match = {
@@ -36557,7 +36558,7 @@ function resolveLambdaTarget(target, stacks) {
 		};
 	} else {
 		const resource = resources[parsed.pathOrId];
-		if (!resource) throw notFoundError$1(target, stack, resources);
+		if (!resource) throw notFoundError$2(target, stack, resources);
 		match = {
 			logicalId: parsed.pathOrId,
 			resource
@@ -36575,7 +36576,7 @@ function resolveLambdaTarget(target, stacks) {
 * user may omit the stack prefix. Otherwise an explicit stack pattern is
 * required.
 */
-function pickStack$1(parsed, stacks) {
+function pickStack$2(parsed, stacks) {
 	if (parsed.stackPattern === null) {
 		if (stacks.length === 1) return stacks[0];
 		throw new LocalInvokeResolutionError(`Multiple stacks in app, target '${parsed.pathOrId}' is missing a stack prefix. Use 'StackName:${parsed.pathOrId}' or 'StackName/...' (path form). Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
@@ -36912,7 +36913,7 @@ function describeLayerEntry(entry) {
 * the resolved stack so the user can copy/paste a valid target. Mirrors
 * the format the issue spec calls out.
 */
-function notFoundError$1(target, stack, resources) {
+function notFoundError$2(target, stack, resources) {
 	const lambdas = [];
 	for (const [logicalId, resource] of Object.entries(resources)) {
 		if (resource.Type !== "AWS::Lambda::Function") continue;
@@ -37936,28 +37937,28 @@ function parseEcsTarget(target) {
 function resolveEcsTaskTarget(target, stacks, context) {
 	if (stacks.length === 0) throw new EcsTaskResolutionError("No stacks found in the synthesized assembly.");
 	const parsed = parseEcsTarget(target);
-	const stack = pickStack(parsed, stacks);
+	const stack = pickStack$1(parsed, stacks);
 	const resources = stack.template.Resources ?? {};
 	let logicalId;
 	let resource;
 	if (parsed.isPath) {
 		const index = buildCdkPathIndex(stack.template);
 		const taskDefs = resolveCdkPathToLogicalIds(parsed.pathOrId, index).filter(({ logicalId: l }) => resources[l]?.Type === "AWS::ECS::TaskDefinition");
-		if (taskDefs.length === 0) throw notFoundError(target, stack, resources);
+		if (taskDefs.length === 0) throw notFoundError$1(target, stack, resources);
 		if (taskDefs.length > 1) throw new EcsTaskResolutionError(`Target '${target}' matches ${taskDefs.length} task definitions in ${stack.stackName}: ` + taskDefs.map((t) => t.logicalId).join(", ") + ". Refine the path or use the stack:LogicalId form.");
 		logicalId = taskDefs[0].logicalId;
 		resource = resources[logicalId];
 	} else {
 		resource = resources[parsed.pathOrId];
-		if (!resource) throw notFoundError(target, stack, resources);
+		if (!resource) throw notFoundError$1(target, stack, resources);
 		logicalId = parsed.pathOrId;
 	}
-	if (!logicalId || !resource) throw notFoundError(target, stack, resources);
+	if (!logicalId || !resource) throw notFoundError$1(target, stack, resources);
 	if (resource.Type === "AWS::Lambda::Function") throw new EcsTaskResolutionError(`Resource '${logicalId}' in ${stack.stackName} is a Lambda function, not an ECS task definition. Use \`cdkd local invoke\` for Lambda; \`cdkd local run-task\` is ECS only.`);
 	if (resource.Type !== "AWS::ECS::TaskDefinition") throw new EcsTaskResolutionError(`Resource '${logicalId}' in ${stack.stackName} is ${resource.Type}, not an AWS::ECS::TaskDefinition.`);
 	return extractTaskDefinitionProperties(stack, logicalId, resource, context);
 }
-function pickStack(parsed, stacks) {
+function pickStack$1(parsed, stacks) {
 	if (parsed.stackPattern === null) {
 		if (stacks.length === 1) return stacks[0];
 		throw new EcsTaskResolutionError(`Multiple stacks in app, target '${parsed.pathOrId}' is missing a stack prefix. Use 'StackName:${parsed.pathOrId}' or 'StackName/...' (path form). Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
@@ -38480,7 +38481,7 @@ function pickStringArray$1(value) {
 	for (const v of value) if (typeof v === "string") out.push(v);
 	return out;
 }
-function notFoundError(target, stack, resources) {
+function notFoundError$1(target, stack, resources) {
 	const tasks = [];
 	for (const [logicalId, resource] of Object.entries(resources)) {
 		if (resource.Type !== "AWS::ECS::TaskDefinition") continue;
@@ -45074,7 +45075,7 @@ async function localStartApiCommand(target, options) {
 	await ensureDockerAvailable();
 	const appCmd = resolveApp(options.app);
 	if (!appCmd) throw new Error("No CDK app specified. Pass --app, set CDKD_APP, or add \"app\" to cdk.json.");
-	const overrides = readEnvOverridesFile$2(options.envVars);
+	const overrides = readEnvOverridesFile$3(options.envVars);
 	const debugPortBase = options.debugPortBase ? parseDebugPort(options.debugPortBase) : void 0;
 	const perLambdaConcurrency = parsePerLambdaConcurrency(options.perLambdaConcurrency);
 	const inlineTmpDirs = /* @__PURE__ */ new Set();
@@ -45847,7 +45848,7 @@ function getTemplateEnv$1(resource) {
 	return vars;
 }
 /** Read the SAM-shape `--env-vars` JSON file. */
-function readEnvOverridesFile$2(filePath) {
+function readEnvOverridesFile$3(filePath) {
 	if (!filePath) return void 0;
 	let raw;
 	try {
@@ -46196,14 +46197,38 @@ const execFileAsync$1 = promisify(execFile);
 /** AWS-published sidecar image (latest tag). amd64 is the only image AWS ships. */
 const METADATA_ENDPOINT_IMAGE = "amazon/amazon-ecs-local-container-endpoints:latest-amd64";
 /**
-* Well-known IP for the ECS local-container-endpoints sidecar — matches
-* the documented AWS task-metadata endpoint address. Containers inject
-* `ECS_CONTAINER_METADATA_URI_V4=http://169.254.170.2/v4/<container-id>`
-* to reach it.
+* Default well-known IP for the ECS local-container-endpoints sidecar —
+* 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.
 */
 const METADATA_ENDPOINT_IP = "169.254.170.2";
-/** Subnet handed to `docker network create` so the well-known IP is routable. */
-const METADATA_ENDPOINT_SUBNET = "169.254.170.0/24";
+/** Default subnet — used when no `subnetOctet` override is supplied. */
+const DEFAULT_METADATA_ENDPOINT_SUBNET = "169.254.170.0/24";
+/**
+* Pure-functional subnet allocator. `cdkd local run-task` uses the
+* default subnet; `cdkd local start-service` walks `subnetOctet=170,
+* 171, 172, ...` (one per replica) to keep parallel docker networks
+* from clashing. The link-local 169.254.0.0/16 space is reserved AWS-
+* wide for cloud metadata so collisions with user workloads are
+* unlikely, but each replica still gets its own /24 to ensure
+* docker's `--subnet` allocator does not reject "Pool overlaps".
+*
+* `subnetOctet` is the second-from-last byte of the network: 170 →
+* 169.254.170.0/24 (default), 171 → 169.254.171.0/24, etc. Valid
+* range is 1..254; the runner clamps to `(170 + replicaIndex) % 84`
+* + 170 in practice (rolling window) — exported here so the runner
+* keeps the allocation logic in one place.
+*/
+function buildEndpointSubnet(subnetOctet) {
+	if (subnetOctet < 1 || subnetOctet > 254 || !Number.isInteger(subnetOctet)) throw new Error(`buildEndpointSubnet: subnetOctet must be an integer in 1..254 (got ${subnetOctet}).`);
+	return {
+		cidr: `169.254.${subnetOctet}.0/24`,
+		sidecarIp: `169.254.${subnetOctet}.2`
+	};
+}
 /**
 * Create the per-task docker network + start the metadata-endpoints
 * sidecar. The sidecar must come up at the well-known address BEFORE any
@@ -46213,8 +46238,13 @@ const METADATA_ENDPOINT_SUBNET = "169.254.170.0/24";
 async function createTaskNetwork(options = {}) {
 	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);
-	logger.info(`Creating docker network ${networkName} (subnet ${METADATA_ENDPOINT_SUBNET})...`);
+	logger.info(`Creating docker network ${networkName} (subnet ${cidr})...`);
 	try {
 		await execFileAsync$1(getDockerCmd(), [
 			"network",
@@ -46222,12 +46252,12 @@ async function createTaskNetwork(options = {}) {
 			"--driver",
 			"bridge",
 			"--subnet",
-			METADATA_ENDPOINT_SUBNET,
+			cidr,
 			networkName
 		]);
 	} 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 ${METADATA_ENDPOINT_SUBNET}; wait for it to finish, or remove the leftover network with \`docker network ls\` + \`docker network rm\`.`);
+		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.`);
 	}
 	const sidecarArgs = [
 		"run",
@@ -46238,7 +46268,7 @@ async function createTaskNetwork(options = {}) {
 		"--network",
 		networkName,
 		"--ip",
-		METADATA_ENDPOINT_IP
+		sidecarIp
 	];
 	const sidecarEnv = {};
 	if (options.credentials) {
@@ -46249,7 +46279,7 @@ async function createTaskNetwork(options = {}) {
 	if (options.cluster) sidecarEnv["CLUSTER"] = options.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 169.254.170.2...");
+	logger.info(`Starting ECS local-container-endpoints sidecar at ${sidecarIp}...`);
 	let sidecarContainerId;
 	try {
 		const { stdout } = await execFileAsync$1(getDockerCmd(), sidecarArgs, { maxBuffer: 10 * 1024 * 1024 });
@@ -46261,7 +46291,8 @@ async function createTaskNetwork(options = {}) {
 	}
 	return {
 		networkName,
-		sidecarContainerId
+		sidecarContainerId,
+		sidecarIp
 	};
 }
 /**
@@ -46276,9 +46307,10 @@ async function createTaskNetwork(options = {}) {
 * to whichever credentials AWS SDK chains find).
 */
 function buildMetadataEnv(opts) {
+	const ip = opts.sidecarIp ?? "169.254.170.2";
 	const env = {
-		ECS_CONTAINER_METADATA_URI_V4: `http://${METADATA_ENDPOINT_IP}/v4/${opts.containerName}`,
-		ECS_CONTAINER_METADATA_URI: `http://${METADATA_ENDPOINT_IP}/v3/${opts.containerName}`
+		ECS_CONTAINER_METADATA_URI_V4: `http://${ip}/v4/${opts.containerName}`,
+		ECS_CONTAINER_METADATA_URI: `http://${ip}/v3/${opts.containerName}`
 	};
 	if (opts.roleArn) env["AWS_CONTAINER_CREDENTIALS_RELATIVE_URI"] = `/role/${encodeURIComponent(opts.roleArn)}`;
 	if (opts.region) env["AWS_REGION"] = opts.region;
@@ -46527,6 +46559,7 @@ async function runEcsTask(task, options, state) {
 	};
 	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();
@@ -46544,7 +46577,8 @@ async function runEcsTask(task, options, state) {
 			containerHost: options.containerHost,
 			roleArn: options.taskRoleArn,
 			platformOverride: options.platformOverride,
-			region: options.region
+			region: options.region,
+			sidecarIp: state.network.sidecarIp
 		}));
 	}
 	const startedByName = /* @__PURE__ */ new Map();
@@ -46681,7 +46715,7 @@ async function waitForContainerHealthy(containerId, displayName) {
 			if (err instanceof EcsTaskRunnerError) throw err;
 			logger.debug(`docker inspect on '${displayName}' failed: ${err instanceof Error ? err.message : String(err)}`);
 		}
-		await sleep(1e3);
+		await sleep$1(1e3);
 	}
 	throw new EcsTaskRunnerError(`Container '${displayName}' did not become healthy within 5 minutes.`);
 }
@@ -46705,7 +46739,7 @@ async function stopContainer(containerId, graceSeconds) {
 		]);
 	} catch {}
 }
-function sleep(ms) {
+function sleep$1(ms) {
 	return new Promise((res) => setTimeout(res, ms));
 }
 /**
@@ -46885,7 +46919,8 @@ function buildDockerRunArgs(opts) {
 	const metaEnv = buildMetadataEnv({
 		containerName: container.name,
 		...roleArn !== void 0 && { roleArn },
-		...opts.region !== void 0 && { region: opts.region }
+		...opts.region !== void 0 && { region: opts.region },
+		...opts.sidecarIp !== void 0 && { sidecarIp: opts.sidecarIp }
 	});
 	Object.assign(finalEnv, metaEnv);
 	Object.assign(finalEnv, container.environment);
@@ -46986,7 +47021,7 @@ async function localRunTaskCommand(target, options) {
 			...Object.keys(context).length > 0 && { context }
 		};
 		const { stacks } = await synthesizer.synthesize(synthOpts);
-		const imageContext = await buildEcsImageResolutionContext(target, stacks, options);
+		const imageContext = await buildEcsImageResolutionContext$1(target, stacks, options);
 		const task = resolveEcsTaskTarget(target, stacks, imageContext);
 		logger.info(`Target: ${task.stack.stackName}/${task.taskDefinitionLogicalId} (family=${task.family}, containers=${task.containers.length})`);
 		const taskNeeds = detectEcsImageResolutionNeeds(stacks.find((s) => s.stackName === task.stack.stackName) ?? task.stack);
@@ -47028,13 +47063,13 @@ async function localRunTaskCommand(target, options) {
 		let resolvedRoleArn;
 		if (options.assumeTaskRole === true) {
 			if (!task.taskRoleArn) throw new Error("--assume-task-role passed without an ARN but the task definition has no resolvable TaskRoleArn. Either the task definition does not set TaskRoleArn, or it points at a resource cdkd cannot resolve to an IAM Role at synth time. Pass the ARN explicitly: --assume-task-role <arn>");
-			resolvedRoleArn = await resolvePlaceholderAccount(task.taskRoleArn, options.region);
-			assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region);
+			resolvedRoleArn = await resolvePlaceholderAccount$1(task.taskRoleArn, options.region);
+			assumedCredentials = await assumeTaskRole$1(resolvedRoleArn, options.region);
 		} else if (typeof options.assumeTaskRole === "string") {
 			resolvedRoleArn = options.assumeTaskRole;
-			assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region);
+			assumedCredentials = await assumeTaskRole$1(resolvedRoleArn, options.region);
 		}
-		const envOverrides = readEnvOverridesFile$1(options.envVars);
+		const envOverrides = readEnvOverridesFile$2(options.envVars);
 		const runOpts = {
 			cluster: options.cluster,
 			containerHost: options.containerHost,
@@ -47069,7 +47104,7 @@ async function localRunTaskCommand(target, options) {
 * Lazy: callers should only invoke this when the resolved ARN is actually
 * going to be used (i.e. on the bare `--assume-task-role` path).
 */
-async function resolvePlaceholderAccount(arn, region) {
+async function resolvePlaceholderAccount$1(arn, region) {
 	if (!arn.includes("${AWS::AccountId}")) return arn;
 	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
 	const sts = new STSClient({ ...region && { region } });
@@ -47085,7 +47120,7 @@ async function resolvePlaceholderAccount(arn, region) {
 * Assume `roleArn` and return temp credentials. Mirrors the same flow
 * `cdkd local invoke --assume-role` uses.
 */
-async function assumeTaskRole(roleArn, region) {
+async function assumeTaskRole$1(roleArn, region) {
 	const { STSClient, AssumeRoleCommand } = await import("@aws-sdk/client-sts");
 	const sts = new STSClient({ ...region && { region } });
 	try {
@@ -47116,9 +47151,9 @@ async function assumeTaskRole(roleArn, region) {
 * for the candidate stack — same warn-and-fall-back error policy as
 * `cdkd local invoke --from-state`.
 */
-async function buildEcsImageResolutionContext(target, stacks, options) {
+async function buildEcsImageResolutionContext$1(target, stacks, options) {
 	const logger = getLogger();
-	const candidate = pickCandidateStack(parseEcsTarget(target).stackPattern, stacks);
+	const candidate = pickCandidateStack$1(parseEcsTarget(target).stackPattern, stacks);
 	if (!candidate) return void 0;
 	const needs = detectEcsImageResolutionNeeds(candidate);
 	if (!needs.needsPseudoParameters && !needs.needsStateResources && !needs.needsEnvOrSecretSubstitution) return;
@@ -47129,7 +47164,7 @@ async function buildEcsImageResolutionContext(target, stacks, options) {
 		if (!region) logger.warn("Resolver references ${AWS::Region} but cdkd could not determine the target region. Pass --region, set AWS_REGION, or declare env.region on the CDK stack.");
 		let accountId;
 		try {
-			accountId = await resolveCallerAccountId(region);
+			accountId = await resolveCallerAccountId$1(region);
 		} catch (err) {
 			logger.warn(`Resolver needs \${AWS::AccountId} but STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. Substitution will be skipped; affected env / secret entries will be dropped with per-key warnings.`);
 		}
@@ -47157,7 +47192,7 @@ async function buildEcsImageResolutionContext(target, stacks, options) {
 	else if (!options.fromState && needs.needsEnvOrSecretSubstitution) logger.warn("Container Environment / Secrets entries contain CloudFormation intrinsics (Ref / Fn::GetAtt / Fn::Sub / Fn::Join). Pass --from-state to substitute them against the deployed cdkd state. Without --from-state these entries are dropped (per-key warnings will follow).");
 	return ctx;
 }
-function pickCandidateStack(stackPattern, stacks) {
+function pickCandidateStack$1(stackPattern, stacks) {
 	if (stackPattern === null) {
 		if (stacks.length === 1) return stacks[0];
 		return;
@@ -47165,7 +47200,7 @@ function pickCandidateStack(stackPattern, stacks) {
 	const matched = matchStacks(stacks, [stackPattern]);
 	if (matched.length === 1) return matched[0];
 }
-async function resolveCallerAccountId(region) {
+async function resolveCallerAccountId$1(region) {
 	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
 	const sts = new STSClient({ ...region && { region } });
 	try {
@@ -47179,7 +47214,7 @@ async function resolveCallerAccountId(region) {
 * `cdkd local invoke --env-vars`: top-level keys are container names, with
 * `Parameters` reserved for global entries.
 */
-function readEnvOverridesFile$1(filePath) {
+function readEnvOverridesFile$2(filePath) {
 	if (!filePath) return void 0;
 	let raw;
 	try {
@@ -47208,6 +47243,690 @@ function createLocalRunTaskCommand() {
 	return cmd;
 }
 
+//#endregion
+//#region src/local/ecs-service-resolver.ts
+/**
+* Walk the synth template to locate an `AWS::ECS::Service` by display
+* path or stack-qualified logical id, resolve its `TaskDefinition`
+* reference, and chain into the existing `resolveEcsTaskTarget` machinery
+* to produce a `ResolvedEcsService` carrying both the service knobs and
+* the underlying task descriptor.
+*
+* Target shape mirrors `cdkd local run-task`: `<Stack>/<DisplayPath>` or
+* `<Stack>:<LogicalId>`; single-stack apps may omit the stack prefix.
+*
+* Optional `context` (same as the task resolver) carries the ECR image
+* substitution data — pseudo parameters (Tier 1) + state-recorded
+* resources (Tier 2). The CLI builds it lazily when the candidate
+* service's task definition actually needs substitution.
+*/
+function resolveEcsServiceTarget(target, stacks, context) {
+	if (stacks.length === 0) throw new EcsTaskResolutionError("No stacks found in the synthesized assembly.");
+	const parsed = parseEcsTarget(target);
+	const stack = pickStack(parsed, stacks);
+	const resources = stack.template.Resources ?? {};
+	let serviceLogicalId;
+	let serviceResource;
+	if (parsed.isPath) {
+		const index = buildCdkPathIndex(stack.template);
+		const services = resolveCdkPathToLogicalIds(parsed.pathOrId, index).filter(({ logicalId: l }) => resources[l]?.Type === "AWS::ECS::Service");
+		if (services.length === 0) throw notFoundError(target, stack, resources);
+		if (services.length > 1) throw new EcsTaskResolutionError(`Target '${target}' matches ${services.length} ECS services in ${stack.stackName}: ` + services.map((s) => s.logicalId).join(", ") + ". Refine the path or use the stack:LogicalId form.");
+		serviceLogicalId = services[0].logicalId;
+		serviceResource = resources[serviceLogicalId];
+	} else {
+		serviceResource = resources[parsed.pathOrId];
+		if (!serviceResource) throw notFoundError(target, stack, resources);
+		serviceLogicalId = parsed.pathOrId;
+	}
+	if (!serviceLogicalId || !serviceResource) throw notFoundError(target, stack, resources);
+	if (serviceResource.Type === "AWS::ECS::TaskDefinition") throw new EcsTaskResolutionError(`Resource '${serviceLogicalId}' in ${stack.stackName} is an ECS TaskDefinition, not a Service. Use \`cdkd local run-task\` for one-shot tasks; \`cdkd local start-service\` is Service-only.`);
+	if (serviceResource.Type !== "AWS::ECS::Service") throw new EcsTaskResolutionError(`Resource '${serviceLogicalId}' in ${stack.stackName} is ${serviceResource.Type}, not an AWS::ECS::Service.`);
+	return extractServiceProperties(stack, serviceLogicalId, serviceResource, stacks, context);
+}
+/**
+* Pure-functional extraction from the synth resource. Exposed for unit
+* testing the per-field resolution rules (DesiredCount default, missing
+* TaskDefinition, intrinsic shapes).
+*/
+function extractServiceProperties(stack, serviceLogicalId, resource, stacks, context) {
+	const props = resource.Properties ?? {};
+	const warnings = [];
+	const taskDefRef = props["TaskDefinition"];
+	if (taskDefRef === void 0 || taskDefRef === null) throw new EcsTaskResolutionError(`ECS Service '${serviceLogicalId}' in ${stack.stackName} has no TaskDefinition property.`);
+	const taskDefLogicalId = resolveTaskDefinitionReference(taskDefRef, stack, serviceLogicalId);
+	const task = resolveEcsTaskTarget(`${stack.stackName}:${taskDefLogicalId}`, stacks, context);
+	const desiredCount = parseDesiredCount(props["DesiredCount"], serviceLogicalId);
+	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 {
+		stack,
+		serviceLogicalId,
+		resource,
+		serviceName,
+		desiredCount,
+		healthCheckGracePeriodSeconds,
+		task,
+		warnings
+	};
+}
+/**
+* Resolve `Properties.TaskDefinition` to a logical id in the same stack.
+* Accepted shapes — verified against real CDK 2.x `cdk synth` output on
+* 2026-05-22 (per `feedback_verify_cdk_synth_shape_before_resolver.md`):
+*   - `{Ref: '<TaskDefLogicalId>'}` — the CDK-canonical shape emitted by
+*     `new ecs.FargateService({ taskDefinition })`.
+*   - flat string `'<TaskDefLogicalId>'` — accepted defensively but CDK
+*     rarely emits this for cross-resource refs.
+* Other intrinsic shapes (`Fn::ImportValue` / `Fn::GetAtt` / etc.) are
+* rejected — cross-stack task definitions and `Fn::GetAtt` shapes have
+* no clean local resolution and would land here only as user errors.
+*/
+function resolveTaskDefinitionReference(taskDefRef, stack, serviceLogicalId) {
+	if (typeof taskDefRef === "string") return taskDefRef;
+	if (taskDefRef && typeof taskDefRef === "object" && !Array.isArray(taskDefRef)) {
+		const refValue = taskDefRef["Ref"];
+		if (typeof refValue === "string") {
+			const target = (stack.template.Resources ?? {})[refValue];
+			if (!target) throw new EcsTaskResolutionError(`ECS Service '${serviceLogicalId}' references TaskDefinition '${refValue}' but no such resource exists in ${stack.stackName}.`);
+			if (target.Type !== "AWS::ECS::TaskDefinition") throw new EcsTaskResolutionError(`ECS Service '${serviceLogicalId}' references '${refValue}' as TaskDefinition but it is of type ${target.Type}, not AWS::ECS::TaskDefinition.`);
+			return refValue;
+		}
+	}
+	throw new EcsTaskResolutionError(`ECS Service '${serviceLogicalId}' has an unsupported TaskDefinition reference shape: ${JSON.stringify(taskDefRef)}. cdkd local start-service v1 supports only Ref to a same-stack AWS::ECS::TaskDefinition; cross-stack TaskDefinitions are deferred.`);
+}
+function parseDesiredCount(raw, serviceLogicalId) {
+	if (raw === void 0 || raw === null) return 1;
+	if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) return Math.floor(raw);
+	if (typeof raw === "string" && /^\d+$/.test(raw)) return parseInt(raw, 10);
+	throw new EcsTaskResolutionError(`ECS Service '${serviceLogicalId}' has an unsupported DesiredCount value: ${JSON.stringify(raw)}. Must be a non-negative integer.`);
+}
+function parseHealthCheckGrace(raw, _serviceLogicalId) {
+	if (raw === void 0 || raw === null) return 30;
+	if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) return Math.floor(raw);
+	if (typeof raw === "string" && /^\d+$/.test(raw)) return parseInt(raw, 10);
+	return 30;
+}
+function parseServiceName(raw, serviceLogicalId) {
+	if (typeof raw === "string" && raw.length > 0) return raw;
+	return serviceLogicalId;
+}
+/**
+* Local copy of the same `pickStack` helper used by the task resolver.
+* Kept in-file rather than exported from `ecs-task-resolver.ts` so future
+* service-specific extensions (e.g. cross-stack service-to-task refs)
+* can diverge without breaking the run-task code path.
+*/
+function pickStack(parsed, stacks) {
+	if (parsed.stackPattern === null) {
+		if (stacks.length === 1) return stacks[0];
+		throw new EcsTaskResolutionError(`Target has no stack prefix, and the assembly contains ${stacks.length} stacks: ${stacks.map((s) => s.stackName).join(", ")}. Pass the target as 'Stack/Path' or 'Stack:LogicalId'.`);
+	}
+	const matched = matchStacks(stacks, [parsed.stackPattern]);
+	if (matched.length === 0) throw new EcsTaskResolutionError(`No stack matches '${parsed.stackPattern}'. Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
+	if (matched.length > 1) throw new EcsTaskResolutionError(`Multiple stacks match '${parsed.stackPattern}': ${matched.map((s) => s.stackName).join(", ")}. Refine the pattern.`);
+	return matched[0];
+}
+function notFoundError(target, stack, resources) {
+	const services = Object.entries(resources).filter(([, r]) => r.Type === "AWS::ECS::Service").map(([id]) => id);
+	if (services.length === 0) return new EcsTaskResolutionError(`Target '${target}' did not match any resource in ${stack.stackName}, and the stack declares no AWS::ECS::Service resources at all.`);
+	return new EcsTaskResolutionError(`Target '${target}' did not match any ECS Service in ${stack.stackName}. Available services: ${services.join(", ")}.`);
+}
+
+//#endregion
+//#region src/local/ecs-service-runner.ts
+/**
+* Phase 2 of #262 — long-running ECS Service emulator. Wraps the existing
+* `ecs-task-runner` machinery in a replica pool: N concurrent task
+* instances per `DesiredCount`, each with its own docker network +
+* metadata sidecar + container set. Tasks that exit non-zero AFTER the
+* health-check grace period are restarted with exponential backoff so a
+* crash-looping container does not hammer docker.
+*
+* v1 scope (per the issue's PR-split recommendation):
+*   - Replica pool sizing via `DesiredCount` clamped by `--max-tasks`.
+*   - Restart-on-exit with exponential backoff (1s → 30s, capped) +
+*     a per-instance retry counter so a permanently-broken container
+*     stops compounding cleanup work.
+*   - Long-running lifecycle (returns only on shutdown).
+*
+* 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).
+*   - Rolling deployment (`--reload` / `--watch`).
+*/
+var EcsServiceRunnerError = class EcsServiceRunnerError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "EcsServiceRunnerError";
+		Object.setPrototypeOf(this, EcsServiceRunnerError.prototype);
+	}
+};
+function createServiceRunState() {
+	return {
+		replicas: [],
+		shuttingDown: false
+	};
+}
+/**
+* Compute the effective replica count for a service: the smaller of
+* `service.desiredCount` and `--max-tasks`, floored at 1. Pure-
+* functional so the CLI can show the user what cdkd is about to do
+* before any docker calls fire.
+*/
+function computeReplicaCount(desiredCount, maxTasks) {
+	if (maxTasks < 1) throw new EcsServiceRunnerError(`--max-tasks must be >= 1 (got ${maxTasks}); local dev needs at least one running replica.`);
+	if (desiredCount <= 0) return 1;
+	return Math.min(desiredCount, maxTasks);
+}
+/**
+* Exponential backoff schedule: 1s, 2s, 4s, 8s, 16s, 30s, 30s, ... Used
+* between restarts of a crash-looping replica so docker is not hammered
+* by the watcher loop. Exposed for unit testing.
+*/
+function backoffDelayMs(restartCount) {
+	return Math.min(1e3 * Math.pow(2, Math.min(restartCount, 10)), 3e4);
+}
+/**
+* Decide whether a replica that just exited should restart. Pure-
+* functional so the watcher loop's policy is easy to unit-test.
+*/
+function shouldRestart(exitCode, policy) {
+	if (policy === "none") return false;
+	if (policy === "always") return true;
+	return exitCode !== 0;
+}
+/**
+* Long-running entry point. Boots `replicaCount` instances of the
+* service's task descriptor, returns a controller object the CLI uses
+* to (1) wait for the first failure that gives up restarting and (2)
+* shut every replica down on SIGINT / SIGTERM.
+*
+* The returned `shutdown()` is idempotent and safe to call from
+* multiple SIGINT handlers (CLI's single-flight pattern wraps it
+* anyway).
+*/
+async function startEcsService(service, options, runState) {
+	const logger = getLogger().child("ecs-service");
+	for (const w of service.warnings) logger.warn(w);
+	const replicaCount = computeReplicaCount(service.desiredCount, options.maxTasks);
+	if (replicaCount < service.desiredCount) logger.warn(`Service '${service.serviceName}' template DesiredCount=${service.desiredCount} exceeds --max-tasks=${options.maxTasks}; running ${replicaCount} replica(s) locally. Raise --max-tasks to lift the cap, or accept the reduced concurrency for local dev.`);
+	logger.info(`Starting ECS service '${service.serviceName}' with ${replicaCount} replica(s) (restartPolicy=${options.restartPolicy})`);
+	for (let i = 0; i < replicaCount; i++) {
+		const instance = {
+			index: i,
+			state: createEcsRunState(),
+			restartCount: 0,
+			shuttingDown: false,
+			inFlightBoot: void 0
+		};
+		runState.replicas.push(instance);
+		const bootPromise = bootReplica(service, options, instance);
+		instance.inFlightBoot = bootPromise;
+		try {
+			await bootPromise;
+		} catch (err) {
+			instance.lastError = err instanceof Error ? err : new Error(String(err));
+			throw new EcsServiceRunnerError(`Failed to boot replica ${i} of service '${service.serviceName}': ${instance.lastError.message}`);
+		} finally {
+			instance.inFlightBoot = void 0;
+		}
+	}
+	for (const instance of runState.replicas) watchReplica(service, options, instance, runState);
+	return new ServiceController(service, runState, options);
+}
+/**
+* Public controller surface. The CLI awaits `controller.waitForShutdown()`
+* to block until the user ^Cs. `controller.shutdown()` is wired into the
+* SIGINT / SIGTERM handlers.
+*/
+var ServiceController = class {
+	service;
+	runState;
+	options;
+	shutdownResolve;
+	shutdownPromise;
+	/**
+	* Single-flight wrapper for `shutdown()` so the fan-out cleanup runs
+	* exactly once even when SIGINT and the CLI's outer `finally` both
+	* fire (the canonical pattern documented in
+	* `feedback_sigint_finally_cleanup_singleflight.md`). Built in the
+	* constructor so every call to `shutdown()` resolves against the same
+	* underlying promise.
+	*/
+	runShutdown;
+	constructor(service, runState, options) {
+		this.service = service;
+		this.runState = runState;
+		this.options = options;
+		this.shutdownPromise = new Promise((resolve) => {
+			this.shutdownResolve = resolve;
+		});
+		this.runShutdown = singleFlight(() => this.doShutdown());
+	}
+	/**
+	* Returns the count of currently-active (non-shutting-down) replicas.
+	* Exposed so the CLI can surface a one-line "service is degraded"
+	* banner when restarts stop firing.
+	*/
+	activeReplicaCount() {
+		return this.runState.replicas.filter((r) => !r.shuttingDown).length;
+	}
+	/**
+	* Block until `shutdown()` is called. Used by the CLI as the
+	* long-running blocking point — the SIGINT handler resolves it.
+	*/
+	waitForShutdown() {
+		return this.shutdownPromise;
+	}
+	/**
+	* Idempotent fan-out shutdown across every active replica. Wired into
+	* both SIGINT and the outer `finally` of the CLI command; the
+	* `singleFlight`-wrapped `runShutdown` collapses concurrent / repeated
+	* callers to one underlying invocation.
+	*/
+	async shutdown() {
+		await this.runShutdown();
+		return this.shutdownPromise;
+	}
+	async doShutdown() {
+		this.runState.shuttingDown = true;
+		const logger = getLogger().child("ecs-service");
+		logger.info(`Shutting down service '${this.service.serviceName}'...`);
+		for (const r of this.runState.replicas) r.shuttingDown = true;
+		const inFlightBoots = this.runState.replicas.map((r) => r.inFlightBoot).filter((p) => p !== void 0);
+		if (inFlightBoots.length > 0) {
+			logger.debug(`Awaiting ${inFlightBoots.length} in-flight bootReplica() call(s) before cleanup...`);
+			await Promise.allSettled(inFlightBoots);
+		}
+		await Promise.allSettled(this.runState.replicas.map(async (instance) => {
+			try {
+				await cleanupEcsRun(instance.state, { keepRunning: this.options.taskOptions.keepRunning });
+			} catch (err) {
+				logger.debug(`Replica ${instance.index} cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}));
+		this.shutdownResolve?.();
+	}
+};
+/**
+* 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
+* docker doesn't collide on shared per-task network names when N > 1.
+*/
+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 perReplicaTaskOptions = {
+		...options.taskOptions,
+		cluster: perReplicaCluster,
+		subnetOctet: perReplicaSubnetOctet,
+		detach: true
+	};
+	logger.info(`Booting replica ${instance.index} (${perReplicaCluster})`);
+	await runEcsTask(service.task, perReplicaTaskOptions, instance.state);
+}
+/**
+* Long-running watcher loop for one replica. Polls the essential
+* container's exit code via `docker wait`; on exit, decides whether to
+* restart per `restartPolicy` + applies exponential backoff. The loop
+* exits only when the replica's `shuttingDown` flag is set.
+*/
+async function watchReplica(service, options, instance, runState) {
+	const logger = getLogger().child("ecs-service");
+	while (!instance.shuttingDown && !runState.shuttingDown) {
+		const essentialId = pickEssentialContainerId(instance, service);
+		if (!essentialId) {
+			await sleep(500);
+			continue;
+		}
+		let exitCode;
+		try {
+			exitCode = await waitForExitImpl(essentialId);
+		} catch (err) {
+			logger.debug(`docker wait failed for replica ${instance.index}: ${err instanceof Error ? err.message : String(err)}`);
+			exitCode = -1;
+		}
+		if (instance.shuttingDown || runState.shuttingDown) return;
+		logger.warn(`Replica ${instance.index} essential container exited with code ${exitCode} (restartCount=${instance.restartCount}).`);
+		if (!shouldRestart(exitCode, options.restartPolicy)) {
+			logger.warn(`Replica ${instance.index} not restarting (policy=${options.restartPolicy}, exit=${exitCode}). Service running in degraded mode.`);
+			instance.shuttingDown = true;
+			return;
+		}
+		const delay = backoffDelayMs(instance.restartCount);
+		logger.info(`Restarting replica ${instance.index} in ${delay}ms...`);
+		await sleep(delay);
+		if (instance.shuttingDown || runState.shuttingDown) return;
+		try {
+			await cleanupEcsRun(instance.state, { keepRunning: false });
+		} catch (err) {
+			logger.debug(`Replica ${instance.index} pre-restart cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		instance.state = createEcsRunState();
+		instance.restartCount += 1;
+		const bootPromise = bootReplica(service, options, instance);
+		instance.inFlightBoot = bootPromise;
+		try {
+			await bootPromise;
+		} catch (err) {
+			instance.lastError = err instanceof Error ? err : new Error(String(err));
+			logger.error(`Replica ${instance.index} restart failed: ${instance.lastError.message}. Service running in degraded mode.`);
+			instance.shuttingDown = true;
+			return;
+		} finally {
+			instance.inFlightBoot = void 0;
+		}
+	}
+}
+function pickEssentialContainerId(instance, service) {
+	if (service) {
+		const essential = service.task.containers.find((c) => c.essential) ?? service.task.containers[0];
+		if (essential) {
+			const started = instance.state.startedContainers.find((c) => c.name === essential.name);
+			if (started) return started.id;
+		}
+	}
+	return instance.state.startedContainers[0]?.id;
+}
+/**
+* Production `docker wait <id>` implementation. Captured once so the
+* test override can restore it without duplicating the body.
+*/
+const defaultWaitForExitImpl = async (containerId) => {
+	const { execFile } = await import("node:child_process");
+	const { promisify } = await import("node:util");
+	const { getDockerCmd } = await import("./docker-cmd-EtWSTAje.js").then((n) => n.t);
+	const { stdout } = await promisify(execFile)(getDockerCmd(), ["wait", containerId], { maxBuffer: 1024 * 1024 });
+	const code = parseInt(stdout.trim(), 10);
+	return Number.isFinite(code) ? code : -1;
+};
+/**
+* `docker wait <id>` returns the exit code on stdout. Extracted as a
+* test-overridable function so unit tests do not need a real container.
+*/
+let waitForExitImpl = defaultWaitForExitImpl;
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+//#endregion
+//#region src/cli/commands/local-start-service.ts
+/**
+* `cdkd local start-service <Stack/Service>` — Phase 2 of #262. Spins up
+* `DesiredCount` task replicas locally (clamped by `--max-tasks`) using
+* the existing `ecs-task-runner` per replica. Long-running; ^C cleans
+* every replica + sidecar + per-task network.
+*
+* Deferred to follow-up PRs (matches the issue's PR-split):
+*   - Local LB emulator (listener + round-robin + target-group health
+*     check) — PR C of #466.
+*   - Rolling deployment (`--watch` / `--reload`) — PR D of #466.
+*   - Service Connect / Cloud Map — tracked separately in #460.
+*/
+async function localStartServiceCommand(target, options) {
+	const logger = getLogger();
+	if (options.verbose) logger.setLevel("debug");
+	warnIfDeprecatedRegion(options);
+	const runState = createServiceRunState();
+	let sigintHandler;
+	let sigintCount = 0;
+	let controller;
+	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)));
+	}, (err) => getLogger().debug(`service cleanup failed: ${err instanceof Error ? err.message : String(err)}`));
+	try {
+		await applyRoleArnIfSet({
+			roleArn: options.roleArn,
+			region: options.region
+		});
+		await ensureDockerAvailable();
+		const appCmd = resolveApp(options.app);
+		if (!appCmd) throw new Error("No CDK app specified. Pass --app, set CDKD_APP, or add \"app\" to cdk.json.");
+		logger.info("Synthesizing CDK app...");
+		const synthesizer = new Synthesizer();
+		const context = parseContextOptions(options.context);
+		const synthOpts = {
+			app: appCmd,
+			output: options.output,
+			...options.region && { region: options.region },
+			...options.profile && { profile: options.profile },
+			...Object.keys(context).length > 0 && { context }
+		};
+		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 }
+			});
+			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.");
+		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...");
+			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();
+	} finally {
+		if (sigintHandler) {
+			process.off("SIGINT", sigintHandler);
+			process.off("SIGTERM", sigintHandler);
+		}
+		await cleanup();
+	}
+}
+async function resolvePlaceholderAccount(arn, region) {
+	if (!arn.includes("${AWS::AccountId}")) return arn;
+	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({ ...region && { region } });
+	try {
+		const account = (await sts.send(new GetCallerIdentityCommand({}))).Account;
+		if (!account) throw new LocalStartServiceError(`--assume-task-role: GetCallerIdentity returned no Account; cannot resolve placeholder ARN '${arn}'.`);
+		return arn.split(TASK_ROLE_ACCOUNT_PLACEHOLDER).join(account);
+	} finally {
+		sts.destroy();
+	}
+}
+async function assumeTaskRole(roleArn, region) {
+	const { STSClient, AssumeRoleCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({ ...region && { region } });
+	try {
+		const creds = (await sts.send(new AssumeRoleCommand({
+			RoleArn: roleArn,
+			RoleSessionName: `cdkd-local-start-service-${Date.now()}`,
+			DurationSeconds: 3600
+		}))).Credentials;
+		if (!creds?.AccessKeyId || !creds.SecretAccessKey || !creds.SessionToken) throw new LocalStartServiceError(`AssumeRole(${roleArn}) returned no usable credentials.`);
+		return {
+			accessKeyId: creds.AccessKeyId,
+			secretAccessKey: creds.SecretAccessKey,
+			sessionToken: creds.SessionToken
+		};
+	} finally {
+		sts.destroy();
+	}
+}
+/**
+* Build the substitution context the ECS resolver consumes. Identical
+* shape to `local-run-task.ts:buildEcsImageResolutionContext` — only
+* the candidate stack picker differs because services and tasks share
+* the same stack-pattern grammar.
+*/
+async function buildEcsImageResolutionContext(target, stacks, options) {
+	const logger = getLogger();
+	const candidate = pickCandidateStack(parseEcsTarget(target).stackPattern, stacks);
+	if (!candidate) return void 0;
+	const needs = detectEcsImageResolutionNeeds(candidate);
+	if (!needs.needsPseudoParameters && !needs.needsStateResources && !needs.needsEnvOrSecretSubstitution) return;
+	const ctx = {};
+	const wantsPseudoForEnvOrSecret = options.fromState && needs.needsEnvOrSecretSubstitution;
+	if (needs.needsPseudoParameters || wantsPseudoForEnvOrSecret) {
+		const region = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? candidate.region;
+		if (!region) logger.warn("Resolver references ${AWS::Region} but cdkd could not determine the target region. Pass --region, set AWS_REGION, or declare env.region on the CDK stack.");
+		let accountId;
+		try {
+			accountId = await resolveCallerAccountId(region);
+		} catch (err) {
+			logger.warn(`Resolver needs \${AWS::AccountId} but STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. Substitution will be skipped; affected env / secret entries will be dropped with per-key warnings.`);
+		}
+		const partitionAndSuffix = region ? derivePartitionAndUrlSuffix(region) : void 0;
+		ctx.pseudoParameters = {
+			...accountId !== void 0 && { accountId },
+			...region !== void 0 && { region },
+			...partitionAndSuffix && {
+				partition: partitionAndSuffix.partition,
+				urlSuffix: partitionAndSuffix.urlSuffix
+			}
+		};
+	}
+	const wantsState = needs.needsStateResources || needs.needsEnvOrSecretSubstitution;
+	if (options.fromState && wantsState) {
+		const loaded = await loadStateForStack(candidate.stackName, candidate.region, {
+			...options.stackRegion !== void 0 && { stackRegion: options.stackRegion },
+			...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 (loaded) ctx.stateResources = loaded.state.resources;
+	} else if (!options.fromState && needs.needsStateResources) logger.warn("Container Image references a same-stack AWS::ECR::Repository. Pass --from-state to substitute the deployed repository URI.");
+	else if (!options.fromState && needs.needsEnvOrSecretSubstitution) logger.warn("Container Environment / Secrets entries contain CloudFormation intrinsics. Pass --from-state to substitute them against the deployed cdkd state.");
+	return ctx;
+}
+function pickCandidateStack(stackPattern, stacks) {
+	if (stackPattern === null) {
+		if (stacks.length === 1) return stacks[0];
+		return;
+	}
+	const matched = matchStacks(stacks, [stackPattern]);
+	if (matched.length === 1) return matched[0];
+}
+async function resolveCallerAccountId(region) {
+	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({ ...region && { region } });
+	try {
+		return (await sts.send(new GetCallerIdentityCommand({}))).Account;
+	} finally {
+		sts.destroy();
+	}
+}
+function readEnvOverridesFile$1(filePath) {
+	if (!filePath) return void 0;
+	let raw;
+	try {
+		raw = readFileSync(filePath, "utf-8");
+	} catch (err) {
+		throw new LocalStartServiceError(`Failed to read --env-vars file '${filePath}': ${err instanceof Error ? err.message : String(err)}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new LocalStartServiceError(`Failed to parse --env-vars file '${filePath}' as JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new LocalStartServiceError(`--env-vars file '${filePath}' must contain a JSON object at the top level.`);
+	return parsed;
+}
+function parsePositiveInt(raw, flagName) {
+	const parsed = parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed < 1) throw new LocalStartServiceError(`${flagName} must be a positive integer (got '${raw}').`);
+	return parsed;
+}
+/**
+* Hard cap on `--max-tasks` driven by the per-replica subnet allocator
+* in `ecs-service-runner.ts:bootReplica` (`170 + (index % 84)`). The
+* `% 84` modulo wraps at index 84, collapsing replica 84's `/24` onto
+* replica 0's allocation. Docker rejects the duplicate-subnet network
+* creation with a cryptic "Pool overlaps with other one on this address
+* space" error 30s into the boot — by which time some early replicas
+* may have spent docker-run budget. Reject at parse time so the user
+* gets an actionable error before any boot work fires.
+*
+* 84 is the count of usable link-local /24 octets in the range
+* `169.254.170.0..169.254.253.0` (255 reserved for broadcast). Raising
+* this requires extending the allocator to walk a different IP range.
+*/
+const MAX_TASKS_SUBNET_RANGE_CAP = 84;
+function parseMaxTasks(raw) {
+	const parsed = parsePositiveInt(raw, "--max-tasks");
+	if (parsed > 84) throw new LocalStartServiceError(`--max-tasks ${parsed} exceeds the per-replica link-local /24 subnet allocator's range (${84}). The allocator in ecs-service-runner.ts assigns each replica its own 169.254.x.0/24 from the range 169.254.170.0..169.254.253.0; replica indices >= ${84} would collide with earlier replicas via modulo wrap. Lower --max-tasks to <= ${84}, or accept reduced local concurrency for high-DesiredCount services.`);
+	return parsed;
+}
+function parseRestartPolicy(raw) {
+	if (raw === "on-failure" || raw === "always" || raw === "none") return 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));
+	[
+		...commonOptions,
+		...appOptions,
+		...contextOptions,
+		...stateOptions
+	].forEach((opt) => cmd.addOption(opt));
+	cmd.addOption(deprecatedRegionOption);
+	return cmd;
+}
+
 //#endregion
 //#region src/cli/commands/local-invoke.ts
 /**
@@ -47939,6 +48658,7 @@ function createLocalCommand() {
 	local.addCommand(invoke);
 	local.addCommand(createLocalStartApiCommand());
 	local.addCommand(createLocalRunTaskCommand());
+	local.addCommand(createLocalStartServiceCommand());
 	return local;
 }
 
@@ -49311,7 +50031,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.130.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.131.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());