cdk-local 0.65.3 → 0.67.0

package/dist/{local-list-CJj6-Ska.js → local-list-faPgnDlc.js}

@@ -20968,6 +20968,7 @@ async function startEcsService(service, options, runState) {
 	for (let i = 0; i < replicaCount; i++) {
 		const instance = {
 			index: i,
+			generation: 0,
 			state: createEcsRunState(),
 			restartCount: 0,
 			shuttingDown: false,
@@ -21112,8 +21113,11 @@ function buildNetworkAliasesByContainer(service) {
 */
 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 ownerKeyPrefix = `${service.serviceLogicalId}:r${instance.index}`;
+	const gen = instance.generation;
+	const genSuffix = gen > 0 ? `-g${gen}` : "";
+	const ownerKeyGenSuffix = gen > 0 ? `:g${gen}` : "";
+	const perReplicaCluster = `${options.taskOptions.cluster}-svc-${service.serviceLogicalId.toLowerCase()}-r${instance.index}${genSuffix}`;
+	const ownerKeyPrefix = `${service.serviceLogicalId}:r${instance.index}${ownerKeyGenSuffix}`;
 	const addHostFlags = options.discovery?.registry ? options.discovery.registry.buildAddHostFlags(ownerKeyPrefix) : [];
 	const sharedNetwork = options.discovery?.sharedNetwork;
 	const networkAliasesByContainer = buildNetworkAliasesByContainer(service);
@@ -21264,6 +21268,266 @@ function unregisterReplicaFromFrontDoor(instance, frontDoor) {
 	instance.frontDoorOwnerKey = void 0;
 }
 /**
+* Phase 2 of issue #214 — shadow-replica readiness probe budget. Tested
+* with busybox httpd's ~50ms listen window and a non-trivial Node
+* Express startup (~1-3s) — 10s caps the rare slow-start app without
+* blocking the roll for typo'd configurations that will never listen.
+*
+* Mutable so unit tests can shrink the timeout window without
+* standing up a real clock; production callers leave the defaults.
+* Exposed via {@link __setShadowReadyConfig} below.
+*/
+let shadowReadyTimeoutMs = 1e4;
+let shadowReadyIntervalMs = 100;
+/**
+* Phase 2 of issue #214 — per-replica rolling reload primitive used by
+* `cdkl start-service --watch`. Boots one fresh "shadow" replica under a
+* bumped generation suffix, atomically swaps Cloud Map / front-door
+* registrations off the old replica, then stops and cleans up the old
+* container.
+*
+* Sequence:
+*   1. Locate the old replica by `oldReplicaIndex` (rejects when it's
+*      already shutting down or missing — the reloader must not race
+*      itself across overlapping firings, which the emulator's
+*      `reloadChain` serializer guarantees externally).
+*   2. Allocate a shadow {@link ServiceReplicaInstance} with the same
+*      logical `index` and `generation = old.generation + 1`. Appended
+*      to `runState.replicas` so a SIGTERM mid-roll tears it down too.
+*   3. `bootReplica(newService, newOptions, shadow)` boots the new
+*      container, publishes Cloud Map handles under the bumped
+*      generation suffix, and registers the shadow in the front-door
+*      pool. The OLD replica's handles + pool entry stay live during
+*      this window so consumers never see a gap.
+*   4. Atomically swap: unregister old's Cloud Map handles, drop its
+*      front-door pool entry, mark `oldInstance.shuttingDown = true`
+*      so the watcher exits. The shadow is already serving by this
+*      point.
+*   5. `cleanupEcsRun(oldInstance.state)` tears the old container +
+*      network down. The shadow remains in `runState.replicas`.
+*   6. Start the shadow's watcher so restart-on-exit is wired the
+*      same as Phase 1's boot loop.
+*
+* Failure modes:
+*   - `bootReplica` fails: keep the old replica serving. Best-effort
+*     teardown of partial shadow state. Re-throws so the reloader can
+*     log and continue with the remaining replicas.
+*   - Old shutdown fails: surfaced via the logger; the shadow is
+*     already live so the service stays available.
+*
+* @internal — wired only by the emulator's reload pathway.
+*/
+async function rollServiceReplica(args) {
+	const { controller, oldReplicaIndex, newService, newOptions } = args;
+	const logger = getLogger().child("ecs-service");
+	const oldInstance = controller.runState.replicas[oldReplicaIndex];
+	if (!oldInstance) throw new EcsServiceRunnerError(`rollServiceReplica: no replica at index ${oldReplicaIndex} (replicas=${controller.runState.replicas.length}).`);
+	if (oldInstance.shuttingDown) {
+		logger.warn(`Rolling replica r${oldInstance.index} (gen ${oldInstance.generation}): retired by its own watcher mid-roll (essential container exited). Skipping this slot; save again to re-boot it.`);
+		return;
+	}
+	const teardownOldFirst = computeReplicaCount(newService.desiredCount, newOptions.maxTasks) === 1;
+	const shadow = {
+		index: oldInstance.index,
+		generation: oldInstance.generation + 1,
+		state: createEcsRunState(),
+		restartCount: 0,
+		shuttingDown: false,
+		inFlightBoot: void 0,
+		cloudMapHandles: [],
+		frontDoorOwnerKey: void 0
+	};
+	controller.runState.replicas.push(shadow);
+	if (teardownOldFirst) {
+		logger.info(`Rolling replica ${shadow.index} (gen ${shadow.generation}): single-replica + host-port publish — tearing old down before shadow boot to avoid host-port collision.`);
+		if (newOptions.discovery) {
+			for (const handle of oldInstance.cloudMapHandles) try {
+				newOptions.discovery.registry.unregister(handle);
+			} catch {}
+			oldInstance.cloudMapHandles = [];
+		}
+		unregisterReplicaFromFrontDoor(oldInstance, newOptions.frontDoor);
+		oldInstance.shuttingDown = true;
+		try {
+			await cleanupEcsRun(oldInstance.state, { keepRunning: newOptions.taskOptions.keepRunning });
+		} catch (err) {
+			logger.warn(`Rolling replica ${oldInstance.index}: cleanup of old (gen ${oldInstance.generation}) failed: ${err instanceof Error ? err.message : String(err)}. Attempting shadow boot anyway.`);
+		}
+		const oldIdx = controller.runState.replicas.indexOf(oldInstance);
+		if (oldIdx !== -1) controller.runState.replicas.splice(oldIdx, 1);
+	} else logger.info(`Rolling replica ${shadow.index} (gen ${shadow.generation}): booting shadow before retiring old.`);
+	const bootPromise = (async () => {
+		await bootReplica(newService, newOptions, shadow);
+		await waitForReplicaTcpReady(newService, shadow, {
+			timeoutMs: shadowReadyTimeoutMs,
+			intervalMs: shadowReadyIntervalMs
+		});
+	})();
+	shadow.inFlightBoot = bootPromise;
+	try {
+		await bootPromise;
+	} catch (err) {
+		const shadowIdx = controller.runState.replicas.indexOf(shadow);
+		if (shadowIdx !== -1) controller.runState.replicas.splice(shadowIdx, 1);
+		try {
+			await cleanupEcsRun(shadow.state, { keepRunning: false });
+		} catch {}
+		if (teardownOldFirst) logger.error(`Rolling replica ${shadow.index}: shadow boot failed and the old replica was already torn down for the single-replica path. Save again with a clean boot to re-start the service.`);
+		throw err;
+	} finally {
+		shadow.inFlightBoot = void 0;
+	}
+	if (teardownOldFirst) {
+		watchReplica(newService, newOptions, shadow, controller.runState);
+		logger.info(`Rolling replica ${shadow.index} (gen ${shadow.generation}): single-replica reload complete.`);
+		return;
+	}
+	if (newOptions.discovery) {
+		for (const handle of oldInstance.cloudMapHandles) try {
+			newOptions.discovery.registry.unregister(handle);
+		} catch {}
+		oldInstance.cloudMapHandles = [];
+	}
+	unregisterReplicaFromFrontDoor(oldInstance, newOptions.frontDoor);
+	await disconnectOldFromSharedNetwork(oldInstance).catch((err) => {
+		logger.debug(`Rolling replica ${oldInstance.index}: shared-network disconnect of old (gen ${oldInstance.generation}) failed: ${err instanceof Error ? err.message : String(err)}. Proceeding with cleanup (the docker-rm step still tears it down).`);
+	});
+	oldInstance.shuttingDown = true;
+	try {
+		await cleanupEcsRun(oldInstance.state, { keepRunning: newOptions.taskOptions.keepRunning });
+	} catch (err) {
+		logger.warn(`Rolling replica ${oldInstance.index}: cleanup of old (gen ${oldInstance.generation}) failed: ${err instanceof Error ? err.message : String(err)}. The shadow is live; the stale container may need a manual \`docker rm\`.`);
+	}
+	const oldIdx = controller.runState.replicas.indexOf(oldInstance);
+	if (oldIdx !== -1) controller.runState.replicas.splice(oldIdx, 1);
+	watchReplica(newService, newOptions, shadow, controller.runState);
+	logger.info(`Rolling replica ${shadow.index} (gen ${shadow.generation}): swap complete; old retired.`);
+}
+/**
+* Phase 2 of issue #214 — disconnect every container of the dying
+* replica from the shared service network BEFORE `cleanupEcsRun`'s
+* `docker stop → docker rm` sequence. Docker's embedded DNS strips an
+* alias the instant a container is disconnected, so a peer resolving
+* the service's Service Connect / Cloud Map alias right after this
+* step never picks the dying container's IP — closing the race window
+* where the alias points at an IP whose app is already gone. Best-
+* effort: a disconnect failure logs at debug and `cleanupEcsRun`'s
+* `docker rm -f` will still tear the network membership down.
+*
+* No-op for replicas that aren't on a shared network (the defensive
+* "per-replica /24" fallback path); the per-replica network is
+* destroyed by `cleanupEcsRun` directly.
+*/
+async function disconnectOldFromSharedNetwork(oldInstance) {
+	const network = oldInstance.state.network;
+	if (!network || !network.ownedByCaller) return;
+	const networkName = network.networkName;
+	const targets = [];
+	if (network.sidecarContainerId) targets.push(network.sidecarContainerId);
+	for (const c of oldInstance.state.startedContainers) targets.push(c.id);
+	for (const id of targets) try {
+		await dockerNetworkDisconnectImpl(networkName, id);
+	} catch (err) {}
+}
+/**
+* Production `docker network disconnect --force <network> <id>` impl,
+* extracted as a test-overridable function so the rolling-primitive
+* unit test can assert this step actually ran (the reviewer flagged
+* that the test mock previously took the `!ownedByCaller` early-return
+* path and silently never entered the disconnect branch).
+*/
+const defaultDockerNetworkDisconnectImpl = async (networkName, containerId) => {
+	const { execFile } = await import("node:child_process");
+	const { promisify } = await import("node:util");
+	const { getDockerCmd } = await import("./docker-cmd-voNPrcRh.js").then((n) => n.t);
+	await promisify(execFile)(getDockerCmd(), [
+		"network",
+		"disconnect",
+		"--force",
+		networkName,
+		containerId
+	]);
+};
+let dockerNetworkDisconnectImpl = defaultDockerNetworkDisconnectImpl;
+/**
+* Phase 2 of issue #214 — shadow-replica TCP readiness probe used by
+* {@link rollServiceReplica} before the atomic registry swap. Polls the
+* essential container's first port mapping (the one Cloud Map / Service
+* Connect publishes) via TCP-connect on the shadow's docker network IP,
+* retrying every `intervalMs` until either the connect succeeds or the
+* timeout elapses.
+*
+* The probe is best-effort: a timeout logs a warn but DOES NOT throw.
+* Swapping anyway is the lesser evil — the dying old replica's image
+* is about to be torn down, and the shadow's new image is the user's
+* intent. A timed-out probe usually means the app inside the new image
+* has a startup bug; the user will see the connection failures on
+* their probe / curl and fix the app, then save again. Failing the
+* roll here would leave the OLD replica running on stale code with no
+* recovery path other than `^C`.
+*
+* Exposed for the unit test pattern: the probe's `connect` impl is
+* injectable via {@link __setTcpProbeImpl} so the rolling-primitive
+* unit test can avoid any real TCP socket.
+*/
+async function waitForReplicaTcpReady(service, shadow, opts) {
+	const logger = getLogger().child("ecs-service");
+	const networkName = shadow.state.network?.networkName;
+	if (!networkName) return;
+	const essential = service.task.containers.find((c) => c.essential) ?? service.task.containers[0];
+	if (!essential || essential.portMappings.length === 0) return;
+	const started = shadow.state.startedContainers.find((c) => c.name === essential.name);
+	if (!started) return;
+	let ip;
+	try {
+		const resolved = await getContainerNetworkIp(started.id, networkName);
+		if (!resolved) return;
+		ip = resolved;
+	} catch (err) {
+		logger.warn(`Shadow replica r${shadow.index} (gen ${shadow.generation}): TCP-ready probe could not resolve docker IP: ${err instanceof Error ? err.message : String(err)}. Proceeding with swap.`);
+		return;
+	}
+	const port = essential.portMappings[0].containerPort;
+	const deadline = Date.now() + opts.timeoutMs;
+	let lastErr;
+	while (Date.now() < deadline) {
+		try {
+			await tcpProbeImpl(ip, port);
+			logger.debug(`Shadow replica r${shadow.index} (gen ${shadow.generation}): TCP probe ${ip}:${port} accepted; proceeding with swap.`);
+			return;
+		} catch (err) {
+			lastErr = err instanceof Error ? err.message : String(err);
+		}
+		await sleep(opts.intervalMs);
+	}
+	logger.warn(`Shadow replica r${shadow.index} (gen ${shadow.generation}): TCP probe ${ip}:${port} did not accept within ${opts.timeoutMs}ms (last: ${lastErr ?? "n/a"}). Swapping anyway — the new image is the user intent. Initial requests after the swap may 502 until the app finishes binding.`);
+}
+/**
+* Default TCP-connect probe used by {@link waitForReplicaTcpReady}.
+* Opens a socket to `host:port` and resolves on `connect`; rejects on
+* any error. The socket is destroyed immediately on connect — we don't
+* want to keep a connection open or send any bytes.
+*/
+const defaultTcpProbeImpl = async (host, port) => {
+	const { createConnection } = await import("node:net");
+	await new Promise((resolve, reject) => {
+		const socket = createConnection({
+			host,
+			port
+		});
+		const onError = (err) => {
+			socket.destroy();
+			reject(err);
+		};
+		socket.once("connect", () => {
+			socket.destroy();
+			resolve();
+		});
+		socket.once("error", onError);
+	});
+};
+let tcpProbeImpl = defaultTcpProbeImpl;
+/**
 * 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
@@ -23322,7 +23586,18 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 	let frontDoorServers = [];
 	let frontDoorByService = /* @__PURE__ */ new Map();
 	let frontDoorLambdaRunners = [];
+	let watcher;
+	let reloadChain = Promise.resolve();
 	const cleanup = singleFlight(async () => {
+		if (watcher) {
+			try {
+				await watcher.close();
+			} catch (err) {
+				getLogger().warn(`watcher.close() failed: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			watcher = void 0;
+		}
+		await reloadChain.catch(() => void 0);
 		await Promise.allSettled(perTarget.map(async (pt) => {
 			if (pt.controller) await pt.controller.shutdown();
 			else {
@@ -23433,8 +23708,41 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 		} else logger.info(`Service(s) running: ${frontDoorLambdaRunners.length} Lambda target(s) behind the ALB front-door.`);
 		logEndpointsBanner(perTarget, frontDoorServers, logger);
 		logger.info("Press ^C to shut down.");
-		if (perTarget.length > 0) await Promise.all(perTarget.map((pt) => pt.controller.waitForShutdown()));
-		else await new Promise(() => {});
+		if (options.watch === true && strategy.supportsWatch === true) {
+			const watchRoot = process.cwd();
+			const { ignored, shouldTrigger, excludePatterns } = createWatchPredicates({
+				watchRoot,
+				output: options.output,
+				watchConfig: resolveWatchConfig()
+			});
+			watcher = createFileWatcher({
+				paths: [watchRoot],
+				ignored,
+				shouldTrigger,
+				onChange: () => {
+					logger.info("Detected source change; reloading service(s)...");
+					reloadChain = reloadChain.then(() => reloadAllServices({
+						perTarget,
+						synthesizer,
+						synthOpts,
+						strategy,
+						resolvedTargets,
+						cloudMapIndexByStack,
+						options,
+						discovery,
+						skipPull,
+						extraStateProviders,
+						profileCredsFile,
+						frontDoorByService,
+						logger
+					})).catch((err) => {
+						logger.error(`reloadAllServices threw: ${err instanceof Error ? err.message : String(err)}`);
+					});
+				}
+			});
+			logger.info(`Watching ${watchRoot} for source changes (excluding ${excludePatterns.join(", ")}).`);
+		}
+		await new Promise(() => {});
 	} finally {
 		if (sigintHandler) {
 			process.off("SIGINT", sigintHandler);
@@ -23443,6 +23751,143 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 		await cleanup();
 	}
 }
+/**
+* Phase 2 of issue #214 — multi-replica rolling reload cycle for
+* `cdkl start-service --watch`. Mirrors start-api's `reloadAllServers`
+* shape but per-ECS-service, replacing Phase 1's "tear single replica
+* down, boot fresh" sequence with a per-replica rolling loop so the
+* service stays available end-to-end:
+*
+*   1. Re-runs `synthesizer.synthesize(synthOpts)` once (failure → warn
+*      + keep every replica serving).
+*   2. Re-runs `strategy.resolveBoots(stacks, resolvedTargets)` so a
+*      target that disappears from the CDK code is detected (warn +
+*      keep previous).
+*   3. Refreshes `cloudMapIndexByStack` from the new stacks so a peer
+*      service's namespace / discovery-name rename is picked up by the
+*      next shadow replica's Cloud Map publish.
+*   4. Per-target:
+*      a. Resolves the new (service, runnerOpts) pair against the new
+*         stacks (cross-stack env / assume-task-role / `--env-vars`
+*         all re-resolved fresh).
+*      b. For each existing replica `i` in 0..min(old, new) - 1:
+*         {@link rollServiceReplica} boots a shadow replica with the
+*         new image under a bumped generation suffix, atomically swaps
+*         Cloud Map / front-door registrations, then stops + cleans up
+*         the old replica. Sequential — only one replica is mid-swap
+*         at a time, so peer services + the front-door pool always
+*         have at least N-1 live endpoints during a roll.
+*
+* Phase 2 trade-off: when the effective replica count changes mid-roll
+* (the user bumped `DesiredCount` or `--max-tasks` flips a clamp),
+* the rolling pathway keeps the existing replicas on the new image
+* but does not scale up / down to match the new count. A warn surfaces
+* so the user can `^C` + re-launch to scale; a richer "scale + roll"
+* mode is left to a follow-up under #214.
+*
+* Per-replica boot failure during the roll: the OLD replica stays
+* live (the shadow was torn down by `rollServiceReplica`), the
+* remaining replicas are still rolled, and the failure is surfaced
+* via the logger so the user can fix the source + save again.
+*/
+async function reloadAllServices(args) {
+	const { perTarget, synthesizer, synthOpts, strategy, resolvedTargets, cloudMapIndexByStack, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService, logger } = args;
+	let stacks;
+	try {
+		({stacks} = await synthesizer.synthesize(synthOpts));
+	} catch (err) {
+		logger.warn(`cdk synth failed during reload; keeping previous version. (${err instanceof Error ? err.message : String(err)})`);
+		return;
+	}
+	const { boots: newBoots, warnings } = strategy.resolveBoots(stacks, resolvedTargets);
+	for (const w of warnings) logger.warn(w);
+	const newBootByTarget = new Map(newBoots.map((b) => [b.target, b]));
+	cloudMapIndexByStack.clear();
+	for (const stack of stacks) {
+		const index = buildCloudMapIndex(stack);
+		cloudMapIndexByStack.set(stack.stackName, index);
+		for (const w of index.warnings) logger.warn(w);
+	}
+	for (const pt of perTarget) {
+		const newBoot = newBootByTarget.get(pt.boot.target);
+		if (!newBoot) {
+			logger.warn(`Reload: target '${pt.boot.target}' no longer resolves to a service in the synthesized app; keeping the previous replica(s) serving.`);
+			continue;
+		}
+		const controller = pt.controller;
+		if (!controller) {
+			logger.warn(`Reload: target '${pt.boot.target}' has no live controller (previous boot likely failed); skipping roll. \`^C\` and re-run start-service to recover.`);
+			continue;
+		}
+		await rollOneTarget({
+			controller,
+			newBoot,
+			stacks,
+			options,
+			discovery,
+			skipPull,
+			extraStateProviders,
+			profileCredsFile,
+			frontDoorPools: frontDoorByService.get(newBoot.target),
+			suppressLoadBalancerWarning: strategy.suppressLoadBalancerWarning === true,
+			logger
+		});
+	}
+	logger.info("Reload complete.");
+}
+/**
+* Phase 2 of issue #214 — roll every replica of one target through the
+* new task descriptor sequentially. Extracted from {@link reloadAllServices}
+* so the per-target try/catch logic (synth-failure / resolve-failure /
+* per-replica boot-failure) stays uniform and readable.
+*
+* State-provider lifetime mirrors {@link bootOneTarget}: a fresh
+* `LocalStateProvider` is created at the top, disposed in `finally`,
+* even when the resolve / roll throws.
+*/
+async function rollOneTarget(args) {
+	const { controller, newBoot, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, logger } = args;
+	const candidate = pickCandidateStack(parseEcsTarget(newBoot.target).stackPattern, stacks);
+	const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
+	try {
+		let resolved;
+		try {
+			resolved = await resolveServiceAndRunnerOpts(newBoot, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, { quiet: true });
+		} catch (err) {
+			const reason = err instanceof Error ? err.message : String(err);
+			logger.error(`Reload of '${newBoot.target}' was rejected: ${reason}. Existing replica(s) keep serving.`);
+			return;
+		}
+		const { service: newService, runnerOpts: newRunnerOpts } = resolved;
+		const oldReplicas = controller.runState.replicas.filter((r) => !r.shuttingDown);
+		if (oldReplicas.length === 0) {
+			logger.warn(`Reload of '${newBoot.target}': no live replicas to roll (all shutting down). \`^C\` and re-run start-service to recover.`);
+			return;
+		}
+		if (newService.desiredCount !== oldReplicas.length) logger.warn(`Reload of '${newBoot.target}': service DesiredCount=${newService.desiredCount} does not match the ${oldReplicas.length} live replica(s); rolling existing replicas only — scale changes during --watch are not yet supported. \`^C\` and re-run start-service to apply the new replica count.`);
+		logger.info(`Reload of '${newBoot.target}': rolling ${oldReplicas.length} replica(s) one at a time (start new shadow → swap registrations → stop old).`);
+		for (const oldInstance of oldReplicas) {
+			const idx = controller.runState.replicas.indexOf(oldInstance);
+			if (idx === -1) {
+				logger.warn(`Reload of '${newBoot.target}': replica r${oldInstance.index} (gen ${oldInstance.generation}) vanished before its roll; skipping.`);
+				continue;
+			}
+			try {
+				await rollServiceReplica({
+					controller,
+					oldReplicaIndex: idx,
+					newService,
+					newOptions: newRunnerOpts
+				});
+			} catch (err) {
+				const reason = err instanceof Error ? err.message : String(err);
+				logger.error(`Reload of '${newBoot.target}' replica r${oldInstance.index}: ${reason}. The old replica keeps serving; remaining replicas will still be rolled.`);
+			}
+		}
+	} finally {
+		if (stateProvider) stateProvider.dispose();
+	}
+}
 async function bootOneTarget(boot, runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning) {
 	const candidate = pickCandidateStack(parseEcsTarget(boot.target).stackPattern, stacks);
 	const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
@@ -23453,13 +23898,41 @@ async function bootOneTarget(boot, runState, stacks, options, discovery, skipPul
 	}
 }
 async function runOneTarget(boot, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning) {
+	const { service, runnerOpts } = await resolveServiceAndRunnerOpts(boot, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning);
+	return startEcsService(service, runnerOpts, runState);
+}
+/**
+* Resolve a {@link ServiceBoot} to its `(ResolvedEcsService, ServiceRunnerOptions)`
+* pair. Shared by the initial boot path (`runOneTarget`) and the
+* Phase 2 of issue #214 rolling-reload pathway (`reloadAllServices`).
+*
+* Walks the same steps the original `runOneTarget` body did:
+*   1. Build the per-target image-resolution context (resolves
+*      asset / `Fn::Sub` / `--from-cfn-stack` overlays for image URIs).
+*   2. Resolve the ECS service target into a {@link ResolvedEcsService}.
+*   3. Apply the cross-stack env / secret resolver when the task
+*      references `Fn::ImportValue` / `Fn::GetStackOutput` across
+*      stacks.
+*   4. Resolve task-role credentials when `--assume-task-role` is set.
+*   5. Resolve `--env-vars` overrides.
+*   6. Compose {@link ServiceRunnerOptions} (including the shared
+*      `discovery` + per-service `frontDoor` pools the rolling
+*      reload depends on for atomic registry swaps).
+*
+* Side effects: logs the target descriptor + Service Connect /
+* ServiceRegistries banners ONLY on the initial boot. The reload
+* pathway calls this on every save; the banners would otherwise
+* spam the console once per save. Pass `quiet: true` to skip them.
+*/
+async function resolveServiceAndRunnerOpts(boot, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, opts = {}) {
 	const logger = getLogger();
 	const target = boot.target;
+	const quiet = opts.quiet === true;
 	const imageContext = await buildEcsImageResolutionContext(target, stacks, options, stateProvider);
 	const service = resolveEcsServiceTarget(target, stacks, imageContext, { suppressLoadBalancerWarning });
-	logger.info(`Target: ${service.stack.stackName}/${service.serviceLogicalId} (service=${service.serviceName}, desiredCount=${service.desiredCount}, task=${service.task.taskDefinitionLogicalId})`);
-	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).`);
+	if (!quiet) logger.info(`Target: ${service.stack.stackName}/${service.serviceLogicalId} (service=${service.serviceName}, desiredCount=${service.desiredCount}, task=${service.task.taskDefinitionLogicalId})`);
+	if (!quiet && service.serviceConnect) logger.info(`Service Connect: namespace='${service.serviceConnect.namespaceName}', ${service.serviceConnect.services.length} service(s) registered for peer discovery.`);
+	if (!quiet && 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 (stateProvider && taskNeeds.needsCrossStackResolver) {
 		const consumerRegion = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? service.stack.region ?? "us-east-1";
@@ -23508,13 +23981,16 @@ async function runOneTarget(boot, runState, stacks, options, discovery, skipPull
 		containerPath: profileCredsFile.containerPath,
 		profileName: profileCredsFile.profileName
 	};
-	return startEcsService(service, {
-		maxTasks: options.maxTasks,
-		restartPolicy: options.restartPolicy,
-		taskOptions: taskOpts,
-		discovery,
-		...frontDoorPools && frontDoorPools.length > 0 ? { frontDoor: { pools: frontDoorPools } } : {}
-	}, runState);
+	return {
+		service,
+		runnerOpts: {
+			maxTasks: options.maxTasks,
+			restartPolicy: options.restartPolicy,
+			taskOptions: taskOpts,
+			discovery,
+			...frontDoorPools && frontDoorPools.length > 0 ? { frontDoor: { pools: frontDoorPools } } : {}
+		}
+	};
 }
 /**
 * Stand up one host-side reverse-proxy server PER LISTENER PORT from the
@@ -23913,6 +24389,75 @@ function addCommonEcsServiceOptions(cmd) {
 	return cmd;
 }
 
+//#endregion
+//#region src/cli/commands/local-start-service.ts
+/**
+* `cdkl start-service` strategy — a pure ECS replica runner. It picks
+* `AWS::ECS::Service` targets and boots each with NO front-door (the ALB
+* front-door is its own command, `cdkl start-alb`). This keeps `start-service`
+* a leaf compute runner, symmetric with `invoke` / `run-task`.
+*
+* `supportsWatch: true` opts this strategy into the emulator's `--watch`
+* reload pathway (Phase 1 + Phase 2 of issue #214 — per-replica rolling
+* deploy: shadow boot under a bumped generation suffix, TCP-ready probe,
+* atomic Cloud Map / front-door swap, retire old). `start-alb`'s strategy
+* intentionally does NOT set this so a `--watch` flag never leaks into
+* the ALB-front-door path (Phase 3).
+*/
+function serviceStrategy() {
+	return {
+		pickEntries: (stacks) => listTargets(stacks).ecsServices,
+		pickerMessage: "Select one or more ECS services to run",
+		pickerNoun: "ECS services",
+		onMissing: () => new LocalStartServiceError(`${getEmbedConfig().cliName} start-service requires at least one <target>. Pass one or more service paths like 'Stack/Orders' 'Stack/Frontend', or run it in a TTY to pick interactively.`),
+		resolveBoots: (_stacks, chosenTargets) => ({
+			boots: chosenTargets.map((target) => ({ target })),
+			warnings: []
+		}),
+		lbPortOverrides: {},
+		supportsWatch: true
+	};
+}
+/**
+* `cdkl 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 + shared network. Pure compute: to put a local ALB front-door in
+* front of an ALB-fronted service, use `cdkl start-alb`.
+*/
+function createLocalStartServiceCommand(opts = {}) {
+	setEmbedConfig(opts.embedConfig);
+	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 \`${getEmbedConfig().cliName} 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. Omit <targets> in an interactive terminal to multi-select the services from a list. To put a local ALB front-door in front of an ALB-fronted service, use \`${getEmbedConfig().cliName} start-alb\` instead.`).argument("[targets...]", "One or more CDK display paths or stack-qualified logical IDs of the AWS::ECS::Service resources to run (omit to multi-select interactively in a TTY)").action(withErrorHandling(async (targets, options) => {
+		await runEcsServiceEmulator(targets, options, serviceStrategy(), opts.extraStateProviders);
+	}));
+	addStartServiceSpecificOptions(cmd);
+	return addCommonEcsServiceOptions(cmd);
+}
+/**
+* Register the option block that `cdkl start-service` adds on top of the
+* shared {@link addCommonEcsServiceOptions} ECS-service common block — the
+* flags that only make sense for a pure-compute service emulator (no front
+* door). Shared between `cdkl start-service` and any host CLI (e.g. cdkd's
+* `local start-service`) that wraps {@link runEcsServiceEmulator} with the
+* {@link serviceStrategy}, so adding or renaming a `start-service`-only flag
+* here propagates to every embedder without duplicate `.addOption(...)`
+* blocks.
+*
+* Calling order only affects `--help` presentation (Commander parses
+* insertion-order-independent). The host-CLI convention is host-specific
+* options first, then this helper, then {@link addCommonEcsServiceOptions}
+* — host flags / start-service flags / common flags grouped in three
+* `--help` clusters. Chainable: returns `cmd`.
+*
+* `--watch` is intentionally NOT in the shared
+* {@link addCommonEcsServiceOptions} block: `start-alb --watch` is not yet
+* implemented (Phase 3 of issue #214), and the shared block must not
+* advertise a flag one of its consumers does not honor.
+*/
+function addStartServiceSpecificOptions(cmd) {
+	return cmd.addOption(new Option("--host-port <containerPort=hostPort...>", "Publish a container port on a specific host port (e.g. 80=8080); repeatable. Default: host port == container port. Use this on macOS to map a privileged container port (< 1024) to a non-privileged host port and avoid the Docker Desktop admin-password prompt. (Single-replica services only — multi-replica services do not publish host ports.)")).addOption(new Option("--watch", "Hot-reload: re-synth + per-replica rolling deploy when the CDK source changes (honors cdk.json watch.include/exclude; cdk.out, node_modules, .git are always excluded). Each replica is rolled one at a time — boot a shadow under a bumped generation suffix, wait for its container port to accept a TCP connection, atomically swap Service-Connect / Cloud Map registrations, then retire the old container — so peer services see zero connection refusals across the reload even on multi-replica services. Off by default; existing replica(s) keep serving when synth fails mid-reload.").default(false));
+}
+
 //#endregion
 //#region src/local/elb-front-door-resolver.ts
 /**
@@ -24858,5 +25403,5 @@ function addListSpecificOptions(cmd) {
 }
 
 //#endregion
-export { pickResponseTemplate as $, substituteAgainstState as $t, createFileWatcher as A, AgentCoreResolutionError as An, MCP_PATH as At, resolveServiceIntegrationParameters as B, SUPPORTED_CODE_RUNTIMES as Bt, addInvokeAgentCoreSpecificOptions as C, pickRefLogicalId as Cn, isFunctionUrlOacFronted as Ct, createWatchPredicates as D, AGENTCORE_HTTP_PROTOCOL as Dn, A2A_PATH as Dt, createLocalStartApiCommand as E, AGENTCORE_AGUI_PROTOCOL as En, A2A_CONTAINER_PORT as Et, filterRoutesByApiIdentifiers as F, substituteImagePlaceholders as Fn, signAgentCoreInvocation as Ft, invokeRequestAuthorizer as G, addInvokeSpecificOptions as Gt, buildMethodArn as H, computeCodeImageTag as Ht, groupRoutesByServer as I, tryResolveImageFnJoin as In, AGENTCORE_SESSION_ID_HEADER as It, translateLambdaResponse as J, buildContainerImage as Jt, invokeTokenAuthorizer as K, createLocalInvokeCommand as Kt, readMtlsMaterialsFromDisk as L, LocalInvokeBuildError as Ln, invokeAgentCore as Lt, buildStageMap as M, resolveAgentCoreTarget as Mn, mcpInvokeOnce as Mt, availableApiIdentifiers as N, derivePseudoParametersFromRegion as Nn, parseSseForJsonRpc as Nt, resolveApiTargetSubset as O, AGENTCORE_MCP_PROTOCOL as On, a2aInvokeOnce as Ot, filterRoutesByApiIdentifier as P, formatStateRemedy as Pn, AGENTCORE_SIGV4_SERVICE as Pt, evaluateResponseParameters as Q, EcsTaskResolutionError as Qt, startApiServer as R, LocalStartServiceError as Rn, waitForAgentCorePing as Rt, createLocalRunTaskCommand as S, discoverRoutes as Sn, buildCorsConfigFromCloudFrontChain as St, addStartApiSpecificOptions as T, AGENTCORE_A2A_PROTOCOL as Tn, invokeAgentCoreWs as Tt, computeRequestIdentityHash as U, renderCodeDockerfile as Ut, defaultCredentialsLoader as V, buildAgentCoreCodeImage as Vt, evaluateCachedLambdaPolicy as W, toCmdArgv as Wt, buildHttpApiV2Event as X, resolveRuntimeFileExtension as Xt, applyAuthorizerOverlay as Y, resolveRuntimeCodeMountPath as Yt, buildRestV1Event as Z, resolveRuntimeImage as Zt, runEcsServiceEmulator as _, countTargets as _n, verifyJwtAuthorizer as _t, albStrategy as a, LocalStateSourceError as an, bufferToBody as at, getContainerNetworkIp as b, discoverWebSocketApisOrThrow as bn, applyCorsResponseHeaders as bt, resolveAlbTarget as c, rejectExplicitCfnStackWithMultipleStacks as cn, handleConnectionsRequest as ct, MAX_TASKS_SUBNET_RANGE_CAP as d, resolveCfnStackName as dn, buildDisconnectEvent as dt, substituteAgainstStateAsync as en, selectIntegrationResponse as et, addCommonEcsServiceOptions as f, CfnLocalStateProvider as fn, buildMessageEvent as ft, resolveSharedSidecarCredentials as g, resolveSingleTarget as gn, verifyCognitoJwt as gt, parseRestartPolicy as h, resolveWatchConfig as hn, createJwksCache as ht, addAlbSpecificOptions as i, materializeLayerFromArn as in, probeHostGatewaySupport as it, attachStageContext as j, pickAgentCoreCandidateStack as jn, MCP_PROTOCOL_VERSION as jt, createAuthorizerCache as k, AGENTCORE_RUNTIME_TYPE as kn, MCP_CONTAINER_PORT as kt, isApplicationLoadBalancer as l, resolveCfnFallbackRegion as ln, parseConnectionsPath as lt, parseMaxTasks as m, resolveSsmParameters as mn, buildJwksUrlFromIssuer as mt, createLocalListCommand as n, substituteEnvVarsFromStateAsync as nn, VtlEvaluationError as nt, createLocalStartAlbCommand as o, createLocalStateProvider as on, ConnectionRegistry as ot, buildEcsImageResolutionContext as p, collectSsmParameterRefs as pn, buildCognitoJwksUrl as pt, matchRoute as q, architectureToPlatform as qt, formatTargetListing as r, resolveEnvVars as rn, HOST_GATEWAY_MIN_VERSION as rt, parseLbPortOverrides as s, isCfnFlagPresent as sn, buildMgmtEndpointEnvUrl as st, addListSpecificOptions as t, substituteEnvVarsFromState as tn, tryParseStatus as tt, resolveAlbFrontDoor as u, resolveCfnRegion as un, buildConnectEvent as ut, buildCloudMapIndex as v, listTargets as vn, verifyJwtViaDiscovery as vt, createLocalInvokeAgentCoreCommand as w, resolveLambdaArnIntrinsic as wn, matchPreflight as wt, addRunTaskSpecificOptions as x, parseSelectionExpressionPath as xn, buildCorsConfigByApiId as xt, CloudMapRegistry as y, discoverWebSocketApis as yn, attachAuthorizers as yt, resolveSelectionExpression as z, withErrorHandling as zn, downloadAndExtractS3Bundle as zt };
-//# sourceMappingURL=local-list-CJj6-Ska.js.map
+export { buildHttpApiV2Event as $, resolveRuntimeFileExtension as $t, createWatchPredicates as A, AGENTCORE_HTTP_PROTOCOL as An, A2A_PATH as At, readMtlsMaterialsFromDisk as B, LocalInvokeBuildError as Bn, invokeAgentCore as Bt, getContainerNetworkIp as C, discoverWebSocketApisOrThrow as Cn, applyCorsResponseHeaders as Ct, createLocalInvokeAgentCoreCommand as D, resolveLambdaArnIntrinsic as Dn, matchPreflight as Dt, addInvokeAgentCoreSpecificOptions as E, pickRefLogicalId as En, isFunctionUrlOacFronted as Et, buildStageMap as F, resolveAgentCoreTarget as Fn, mcpInvokeOnce as Ft, buildMethodArn as G, computeCodeImageTag as Gt, resolveSelectionExpression as H, downloadAndExtractS3Bundle as Ht, availableApiIdentifiers as I, derivePseudoParametersFromRegion as In, parseSseForJsonRpc as It, invokeRequestAuthorizer as J, addInvokeSpecificOptions as Jt, computeRequestIdentityHash as K, renderCodeDockerfile as Kt, filterRoutesByApiIdentifier as L, formatStateRemedy as Ln, AGENTCORE_SIGV4_SERVICE as Lt, createAuthorizerCache as M, AGENTCORE_RUNTIME_TYPE as Mn, MCP_CONTAINER_PORT as Mt, createFileWatcher as N, AgentCoreResolutionError as Nn, MCP_PATH as Nt, addStartApiSpecificOptions as O, AGENTCORE_A2A_PROTOCOL as On, invokeAgentCoreWs as Ot, attachStageContext as P, pickAgentCoreCandidateStack as Pn, MCP_PROTOCOL_VERSION as Pt, applyAuthorizerOverlay as Q, resolveRuntimeCodeMountPath as Qt, filterRoutesByApiIdentifiers as R, substituteImagePlaceholders as Rn, signAgentCoreInvocation as Rt, CloudMapRegistry as S, discoverWebSocketApis as Sn, attachAuthorizers as St, createLocalRunTaskCommand as T, discoverRoutes as Tn, buildCorsConfigFromCloudFrontChain as Tt, resolveServiceIntegrationParameters as U, SUPPORTED_CODE_RUNTIMES as Ut, startApiServer as V, waitForAgentCorePing as Vt, defaultCredentialsLoader as W, buildAgentCoreCodeImage as Wt, matchRoute as X, architectureToPlatform as Xt, invokeTokenAuthorizer as Y, createLocalInvokeCommand as Yt, translateLambdaResponse as Z, buildContainerImage as Zt, parseMaxTasks as _, resolveSsmParameters as _n, buildJwksUrlFromIssuer as _t, albStrategy as a, substituteEnvVarsFromStateAsync as an, VtlEvaluationError as at, runEcsServiceEmulator as b, countTargets as bn, verifyJwtAuthorizer as bt, resolveAlbTarget as c, LocalStateSourceError as cn, bufferToBody as ct, addStartServiceSpecificOptions as d, rejectExplicitCfnStackWithMultipleStacks as dn, handleConnectionsRequest as dt, resolveRuntimeImage as en, buildRestV1Event as et, createLocalStartServiceCommand as f, resolveCfnFallbackRegion as fn, parseConnectionsPath as ft, buildEcsImageResolutionContext as g, collectSsmParameterRefs as gn, buildCognitoJwksUrl as gt, addCommonEcsServiceOptions as h, CfnLocalStateProvider as hn, buildMessageEvent as ht, addAlbSpecificOptions as i, substituteEnvVarsFromState as in, tryParseStatus as it, resolveApiTargetSubset as j, AGENTCORE_MCP_PROTOCOL as jn, a2aInvokeOnce as jt, createLocalStartApiCommand as k, AGENTCORE_AGUI_PROTOCOL as kn, A2A_CONTAINER_PORT as kt, isApplicationLoadBalancer as l, createLocalStateProvider as ln, ConnectionRegistry as lt, MAX_TASKS_SUBNET_RANGE_CAP as m, resolveCfnStackName as mn, buildDisconnectEvent as mt, createLocalListCommand as n, substituteAgainstState as nn, pickResponseTemplate as nt, createLocalStartAlbCommand as o, resolveEnvVars as on, HOST_GATEWAY_MIN_VERSION as ot, serviceStrategy as p, resolveCfnRegion as pn, buildConnectEvent as pt, evaluateCachedLambdaPolicy as q, toCmdArgv as qt, formatTargetListing as r, substituteAgainstStateAsync as rn, selectIntegrationResponse as rt, parseLbPortOverrides as s, materializeLayerFromArn as sn, probeHostGatewaySupport as st, addListSpecificOptions as t, EcsTaskResolutionError as tn, evaluateResponseParameters as tt, resolveAlbFrontDoor as u, isCfnFlagPresent as un, buildMgmtEndpointEnvUrl as ut, parseRestartPolicy as v, resolveWatchConfig as vn, createJwksCache as vt, addRunTaskSpecificOptions as w, parseSelectionExpressionPath as wn, buildCorsConfigByApiId as wt, buildCloudMapIndex as x, listTargets as xn, verifyJwtViaDiscovery as xt, resolveSharedSidecarCredentials as y, resolveSingleTarget as yn, verifyCognitoJwt as yt, groupRoutesByServer as z, tryResolveImageFnJoin as zn, AGENTCORE_SESSION_ID_HEADER as zt };
+//# sourceMappingURL=local-list-faPgnDlc.js.map