@mysten-incubation/devstack 0.1.1 → 0.2.0

package/dist/cli/wirings/up.mjs

@@ -1,64 +1,72 @@
-import { StackPathsService } from "../../substrate/runtime/paths.mjs";
-import { makeProjectionRef } from "../../substrate/runtime/projection/state-ref.mjs";
-import { persistProjectionChanges } from "../../substrate/runtime/projection/persisted.mjs";
-import { commandChannelPaths, makeCommandChannelSubscriber } from "../../substrate/runtime/cross-process/command-channel/channel.mjs";
 import { claim, heartbeatFiber, release } from "../../substrate/runtime/cross-process/roster.mjs";
+import { StackPathsService } from "../../substrate/runtime/paths.mjs";
+import { computeSnapshotGraphInputFromStack } from "../../orchestrators/snapshot/descriptor.mjs";
+import { recoverInterruptedRestore } from "../../orchestrators/snapshot/interrupted-restore.mjs";
 import { SnapshotOrchestratorService } from "../../orchestrators/snapshot/service.mjs";
-import "../../substrate/runtime/index.mjs";
-import { superviseStackEffect } from "../../orchestrators/run.mjs";
-import { captureSnapshot } from "../../orchestrators/snapshot/capture-command.mjs";
 import "../../orchestrators/snapshot/index.mjs";
-import { buildProductionOrchestratorSinks, buildProductionPostAcquireHook } from "../../orchestrators/runtime-composition.mjs";
-import { extendBuiltInPluginContext, layerBuiltInPluginRuntime } from "../../orchestrators/built-in-plugin-layers.mjs";
+import "../../substrate/runtime/index.mjs";
+import { runStackWithBoot } from "../../api/run-stack-internal.mjs";
 import { ExitCode } from "../../surfaces/cli/sysexits.mjs";
-import { CliInternalError, CliSupervisorLiveError } from "../../surfaces/cli/errors.mjs";
+import { CliInternalError, CliSnapshotNotFoundError, CliSupervisorLiveError, CliUsageError } from "../../surfaces/cli/errors.mjs";
 import { DEFAULT_LIFECYCLE_PRUNE_RESOURCES, collectLifecyclePruneInventory, defaultLifecyclePruneSelection, runLifecyclePrune } from "../../orchestrators/lifecycle-prune/index.mjs";
+import { readDevstackVersion } from "./read-devstack-version.mjs";
 import "../../surfaces/cli/index.mjs";
+import { makeSnapshotReader } from "../snapshot-reader.mjs";
 import { makeTuiSurface } from "../../surfaces/tui/index.mjs";
 import { cliErrorFromConfigExit } from "../bail.mjs";
 import { makeQueueCommandPublisher, resolveUpRendererMode } from "../up-lifecycle.mjs";
 import { makeConfigLoader } from "./config-loader.mjs";
-import { isEngineCommand } from "./engine-command.mjs";
 import { findCliSupervisorLiveError, identityValueFor, resolvedIdentityForStack } from "./identity.mjs";
-import { buildVerbLayers } from "./build-verb-layers.mjs";
+import { installCommandChannelBridge } from "./up-ipc.mjs";
 import { provideFileSystem } from "./provide-file-system.mjs";
-import { Cause, Effect, Exit, FileSystem, Logger, Queue, Ref, Stream } from "effect";
+import { Cause, Effect, Exit, FileSystem, Queue, Stream } from "effect";
 import { dirname, resolve } from "node:path";
 //#region src/cli/wirings/up.ts
 const rosterPathsFor = (stackRoot) => ({
 	stackLockFile: resolve(stackRoot, "stack.lock"),
 	rosterFile: resolve(stackRoot, "roster.json")
 });
-const makeSnapshotCommandHandler = (params) => {
-	return (cmd, handlerCtx) => {
+/** Build the snapshot/wipe/prune `commandHandler` as a FACTORY the seam
+*  resolves against its LIVE substrate (see `CommandHandlerFactory`). The
+*  factory yields the seam's `SnapshotOrchestratorService` + `FileSystem` —
+*  the SAME orchestrator instance the supervisor's contribution dispatcher
+*  registers live participants on, so an operator `snapshot save` captures
+*  real chain/blob/db state, not an empty set — and returns a handler
+*  (R = `never`, as the command loop requires) that closes over them
+*  directly. No Deferred hand-off: the seam runs this factory before
+*  `startSupervisor` consumes the handler. */
+const makeSnapshotCommandHandler = (params) => Effect.gen(function* () {
+	const snapshot = yield* SnapshotOrchestratorService;
+	const fs = yield* FileSystem.FileSystem;
+	const computeGraphInput = computeSnapshotGraphInputFromStack({
+		stack: params.stack,
+		devstackVersion: params.devstackVersion
+	});
+	const handler = (cmd) => {
 		switch (cmd.tag) {
-			case "snapshot.capture": return captureSnapshot({
-				snapshotId: cmd.snapshotId,
-				name: cmd.name,
-				onProgress: (progress) => handlerCtx.publish({
-					tag: "snapshot.captureProgress",
-					...cmd.snapshotId === void 0 ? {} : { snapshotId: cmd.snapshotId },
-					...cmd.name === void 0 ? {} : { name: cmd.name },
-					phase: progress.phase,
-					...progress.detail === void 0 ? {} : { detail: progress.detail },
-					...progress.pausedContainers === void 0 ? {} : { pausedContainers: progress.pausedContainers },
-					...progress.totalContainers === void 0 ? {} : { totalContainers: progress.totalContainers },
-					at: Date.now()
-				})
-			}).pipe(Effect.provideService(SnapshotOrchestratorService, params.snapshot), Effect.provideService(FileSystem.FileSystem, params.fs), Effect.map((meta) => [{
+			case "snapshot.capture": return provideFileSystem(fs, computeGraphInput.pipe(Effect.flatMap((graphInput) => snapshot.capture({
+				id: cmd.snapshotId,
+				...cmd.name === void 0 ? {} : { label: cmd.name },
+				graphInput,
+				...cmd.replaceExisting === true ? { replaceExistingLabel: true } : {}
+			})))).pipe(Effect.map((meta) => [{
 				tag: "snapshot.captured",
 				snapshotId: meta.id,
 				...meta.label === null ? {} : { name: meta.label },
 				at: Date.now()
 			}]));
-			case "snapshot.restore": return provideFileSystem(params.fs, params.snapshot.restore({ id: cmd.snapshotId })).pipe(Effect.map((meta) => [{
+			case "snapshot.restore": return provideFileSystem(fs, computeGraphInput.pipe(Effect.flatMap((currentGraphInput) => snapshot.restore({
+				id: cmd.snapshotId,
+				currentGraphInput,
+				graphInputMismatchPolicy: "warn"
+			})))).pipe(Effect.map((meta) => [{
 				tag: "snapshot.restored",
 				snapshotId: meta.id,
 				at: Date.now()
 			}]));
-			case "snapshot.list": return provideFileSystem(params.fs, params.snapshot.list).pipe(Effect.as([]));
-			case "snapshot.delete": return provideFileSystem(params.fs, params.snapshot.delete(cmd.snapshotId)).pipe(Effect.as([]));
-			case "wipe.requested": return provideFileSystem(params.fs, params.snapshot.wipe({})).pipe(Effect.as([]));
+			case "snapshot.list": return provideFileSystem(fs, snapshot.list).pipe(Effect.as([]));
+			case "snapshot.delete": return provideFileSystem(fs, snapshot.delete(cmd.snapshotId)).pipe(Effect.as([]));
+			case "wipe.requested": return provideFileSystem(fs, snapshot.wipe({})).pipe(Effect.as([]));
 			case "prune.requested": return collectLifecyclePruneInventory({ runtimeRoot: params.runtimeRoot }).pipe(Effect.flatMap((inventory) => runLifecyclePrune({ runtimeRoot: params.runtimeRoot }, {
 				groupKeys: defaultLifecyclePruneSelection(inventory, DEFAULT_LIFECYCLE_PRUNE_RESOURCES),
 				resources: DEFAULT_LIFECYCLE_PRUNE_RESOURCES,
@@ -67,7 +75,8 @@ const makeSnapshotCommandHandler = (params) => {
 			default: return Effect.succeed([]);
 		}
 	};
-};
+	return handler;
+});
 const installLiveSupervisorRoster = (params) => Effect.gen(function* () {
 	const paths = rosterPathsFor(params.stackRoot);
 	if (!(yield* claim(paths)).soleHolder) {
@@ -81,107 +90,108 @@ const installLiveSupervisorRoster = (params) => Effect.gen(function* () {
 	yield* Effect.addFinalizer(() => release(paths).pipe(Effect.catch(() => Effect.void)));
 	yield* Effect.forkScoped(heartbeatFiber(paths));
 });
-/** Detect snapshot-capture completion events on the published stream
-*  so we can ack/fail the originating `snapshot.capture` command with
-*  a structured payload (snapshot metadata on success; failure summary
-*  on failure). Drops the legacy tail-fiber on the CLI side — the
-*  `summary` is now surfaced through `awaitCompletion`'s reply.payload. */
-const snapshotCaptureAckFromEvent = (event) => {
-	if (typeof event !== "object" || event === null) return null;
-	const record = event;
-	if (typeof record.snapshotId !== "string") return null;
-	if (record.tag === "snapshot.captured") return {
-		snapshotId: record.snapshotId,
-		payload: {
-			kind: "captured",
-			snapshotId: record.snapshotId,
-			...record.name === void 0 ? {} : { name: record.name }
-		}
-	};
-	if (record.tag === "snapshot.captureFailed") return {
-		snapshotId: record.snapshotId,
-		payload: {
-			kind: "failed",
-			snapshotId: record.snapshotId,
-			...record.name === void 0 ? {} : { name: record.name },
-			...typeof record.summary === "string" ? { summary: record.summary } : {}
-		}
-	};
-	if (record.tag === "snapshot.captureSkipped") return {
-		snapshotId: record.snapshotId,
-		payload: {
-			kind: "skipped",
-			snapshotId: record.snapshotId,
-			...typeof record.reason === "string" ? { reason: record.reason } : {}
-		}
-	};
-	return null;
-};
-const installCommandChannelBridge = (params) => Effect.gen(function* () {
-	const subscriber = yield* makeCommandChannelSubscriber(commandChannelPaths(params.stackRoot), { fromOffset: "current" });
-	const pendingCaptures = yield* Ref.make(/* @__PURE__ */ new Map());
-	const consumeCommands = subscriber.commands.pipe(Stream.runForEach((record) => Effect.gen(function* () {
-		if (!isEngineCommand(record.command)) {
-			yield* subscriber.fail(record.id, "invalid command", "command payload did not match EngineCommand").pipe(Effect.catch(() => Effect.void));
-			return;
-		}
-		const cmd = record.command;
-		if (cmd.tag === "snapshot.capture") {
-			if (cmd.snapshotId === void 0) {
-				yield* params.handle.runCommand(cmd).pipe(Effect.andThen(subscriber.ack(record.id)), Effect.catchCause((cause) => subscriber.fail(record.id, "command failed", Cause.pretty(cause)).pipe(Effect.catch(() => Effect.void))));
-				return;
-			}
-			yield* Ref.update(pendingCaptures, (map) => {
-				const next = new Map(map);
-				next.set(cmd.snapshotId, {
-					commandId: record.id,
-					snapshotId: cmd.snapshotId,
-					...cmd.name === void 0 ? {} : { name: cmd.name }
+/**
+* Build the CLI's boot concerns as a VALUE bundle the seam consumes — the
+* snapshot/wipe/prune `commandHandler` plus the `beforeInitialAcquire`
+* (recover → IPC bridge → roster claim → TUI mount + event tee). Pure
+* value construction: no substrate is touched here; the hooks pull the
+* SEAM's substrate services at boot (they run inside the supervised scope).
+*
+* Extracted from `runUpLive` so the Docker-free CLI-boot smoke test drives
+* the EXACT bundle the production path feeds `runStackWithBoot` — the only
+* non-e2e gate on the cutover (`main.test.ts` only runs `up --help`).
+*/
+const buildUpBootBundle = (input) => {
+	const { stack, identityValue, runtimeRoot, devstackVersion, rendererMode, startFromSnapshot, snapshotCache } = input;
+	const computeGraphInput = computeSnapshotGraphInputFromStack({
+		stack,
+		devstackVersion
+	});
+	let refreshSnapshotCache = snapshotCache !== void 0 && snapshotCache.existingSnapshotId === void 0;
+	return {
+		commandHandler: makeSnapshotCommandHandler({
+			runtimeRoot,
+			stack,
+			devstackVersion
+		}),
+		boot: {
+			devstackVersion,
+			beforeInitialAcquire: (h) => Effect.gen(function* () {
+				const snapshot = yield* SnapshotOrchestratorService;
+				const fs = yield* FileSystem.FileSystem;
+				const stackPaths = yield* StackPathsService;
+				yield* recoverInterruptedRestore({
+					liveRoot: stackPaths.stackRoot,
+					restoreSnapshot: (id) => computeGraphInput.pipe(Effect.flatMap((currentGraphInput) => snapshot.restore({
+						id,
+						currentGraphInput,
+						graphInputMismatchPolicy: "warn"
+					})))
 				});
-				return next;
-			});
-			yield* params.handle.runCommand(cmd).pipe(Effect.catchCause((cause) => Effect.gen(function* () {
-				yield* Ref.update(pendingCaptures, (map) => {
-					const next = new Map(map);
-					next.delete(cmd.snapshotId);
-					return next;
+				if (snapshotCache !== void 0) if (snapshotCache.existingSnapshotId === void 0) yield* Effect.logWarning(`snapshot cache ${snapshotCache.name} was not found; boot will refresh it`);
+				else {
+					const graphInput = yield* computeGraphInput;
+					if (((yield* provideFileSystem(fs, snapshot.list)).find((snapshotEntry) => snapshotEntry.id === snapshotCache.existingSnapshotId)?.metadata?.graphInput.graphInputId ?? null) === graphInput.graphInputId) {
+						refreshSnapshotCache = false;
+						yield* provideFileSystem(fs, snapshot.restore({
+							id: snapshotCache.existingSnapshotId,
+							currentGraphInput: graphInput,
+							graphInputMismatchPolicy: "block"
+						}));
+					} else {
+						refreshSnapshotCache = true;
+						yield* Effect.logWarning(`snapshot cache ${snapshotCache.name} graph input is stale or unreadable; boot will refresh it`);
+					}
+				}
+				else if (startFromSnapshot !== void 0) {
+					const graphInput = yield* computeGraphInput;
+					if (startFromSnapshot.stalePolicy === "clean-start") if (((yield* provideFileSystem(fs, snapshot.list)).find((snapshotEntry) => snapshotEntry.id === startFromSnapshot.id)?.metadata?.graphInput.graphInputId ?? null) !== graphInput.graphInputId) yield* Effect.logWarning(`snapshot ${startFromSnapshot.id} graph input is stale; clean-start policy skipped restore`);
+					else yield* provideFileSystem(fs, snapshot.restore({
+						id: startFromSnapshot.id,
+						currentGraphInput: graphInput,
+						graphInputMismatchPolicy: "block"
+					}));
+					else yield* provideFileSystem(fs, snapshot.restore({
+						id: startFromSnapshot.id,
+						currentGraphInput: graphInput,
+						graphInputMismatchPolicy: startFromSnapshot.stalePolicy
+					}));
+				}
+				const commandChannel = yield* installCommandChannelBridge({
+					stackRoot: stackPaths.stackRoot,
+					handle: h.supervisor
 				});
-				yield* subscriber.fail(record.id, "command failed", Cause.pretty(cause)).pipe(Effect.catch(() => Effect.void));
-			})));
-			return;
-		}
-		yield* params.handle.runCommand(cmd).pipe(Effect.andThen(subscriber.ack(record.id)), Effect.catchCause((cause) => subscriber.fail(record.id, "command failed", Cause.pretty(cause)).pipe(Effect.catch(() => Effect.void))));
-	}))).pipe(Effect.catchCause((cause) => {
-		if (Cause.hasInterrupts(cause)) return Effect.failCause(cause);
-		return Effect.sync(() => {
-			process.stderr.write(`command channel decode failed; resuming tail: ${Cause.pretty(cause)}\n`);
-		}).pipe(Effect.andThen(Effect.sleep("200 millis")), Effect.andThen(Effect.suspend(() => consumeCommands)));
-	}));
-	yield* Effect.forkScoped(consumeCommands);
-	const publishEvent = (event) => Effect.gen(function* () {
-		yield* subscriber.publishEvent(event).pipe(Effect.catch(() => Effect.void));
-		const ackFromEvent = snapshotCaptureAckFromEvent(event);
-		if (ackFromEvent === null) return;
-		const pending = yield* Ref.modify(pendingCaptures, (map) => {
-			const entry = map.get(ackFromEvent.snapshotId);
-			if (entry === void 0) return [null, map];
-			const next = new Map(map);
-			next.delete(ackFromEvent.snapshotId);
-			return [entry, next];
-		});
-		if (pending === null) return;
-		if (ackFromEvent.payload.kind === "captured") {
-			yield* subscriber.ack(pending.commandId, "captured", ackFromEvent.payload).pipe(Effect.catch(() => Effect.void));
-			return;
-		}
-		if (ackFromEvent.payload.kind === "failed") {
-			yield* subscriber.fail(pending.commandId, "snapshot capture failed", ackFromEvent.payload.summary, ackFromEvent.payload).pipe(Effect.catch(() => Effect.void));
-			return;
+				yield* installLiveSupervisorRoster({
+					stackRoot: stackPaths.stackRoot,
+					app: String(identityValue.app),
+					stack: String(identityValue.stack)
+				});
+				const rendererEvents = yield* Queue.unbounded();
+				const renderer = makeTuiSurface({
+					mode: rendererMode,
+					publishCommand: makeQueueCommandPublisher(h.commands),
+					quiet: process.env.DEVSTACK_PLAIN_QUIET === "1"
+				});
+				yield* Effect.addFinalizer(() => renderer.flush.pipe(Effect.catch(() => Effect.void)));
+				yield* Effect.forkScoped(renderer.mount(h.state, Stream.fromQueue(rendererEvents)).pipe(Effect.catch((cause) => Effect.sync(() => {
+					process.stderr.write(`renderer failed: ${cause.detail ?? String(cause)}\n`);
+				}))));
+				yield* Effect.forkScoped(h.events.pipe(Stream.runForEach((event) => Effect.gen(function* () {
+					yield* Queue.offer(rendererEvents, event);
+					yield* commandChannel.publishEvent(event);
+				}))));
+			}),
+			withinScope: (h) => Effect.gen(function* () {
+				if (snapshotCache === void 0 || !refreshSnapshotCache) return;
+				yield* h.supervisor.runCommand({
+					tag: "snapshot.capture",
+					name: snapshotCache.name,
+					replaceExisting: true
+				});
+			})
 		}
-		yield* subscriber.fail(pending.commandId, "snapshot capture skipped", ackFromEvent.payload.reason, ackFromEvent.payload).pipe(Effect.catch(() => Effect.void));
-	});
-	return { publishEvent };
-});
+	};
+};
 /**
 * Run `devstack up`. Wires the substrate Layer stack, supervisor,
 * attached renderer, and in-process TUI command queue. The Effect runs
@@ -196,88 +206,98 @@ const installCommandChannelBridge = (params) => Effect.gen(function* () {
 const runUpLive = (configPath, identity, options) => {
 	const loader = makeConfigLoader();
 	return Effect.gen(function* () {
+		if (options.fromSnapshot !== void 0 && options.snapshotCache !== void 0) return yield* Effect.fail(new CliUsageError({ message: "--snapshot-cache cannot be combined with --from-snapshot" }));
+		if (options.snapshotCache !== void 0 && options.snapshotStalePolicy !== void 0) return yield* Effect.fail(new CliUsageError({ message: "--snapshot-stale is only valid with --from-snapshot" }));
 		const loadExit = yield* Effect.exit(loader.load(configPath));
 		if (Exit.isFailure(loadExit)) return yield* Effect.fail(cliErrorFromConfigExit(loadExit));
 		const loaded = loadExit.value;
-		const stack = loaded.stack;
+		const publicStack = loaded.stack;
+		const stack = loaded.engine;
 		const effectiveIdentity = resolvedIdentityForStack(identity, stack);
 		const identityValue = identityValueFor(effectiveIdentity);
 		const appRoot = dirname(loaded.resolvedConfigPath);
+		const devstackVersion = readDevstackVersion({ fallback: "0.0.0" });
 		const rendererMode = resolveUpRendererMode({
 			cliRenderer: options.renderer,
 			stackRenderer: stack.options.renderer,
 			stdoutIsTty: options.stdoutIsTty
 		});
-		const substrateLayers = buildVerbLayers({
-			identity: identityValue,
+		let startFromSnapshot;
+		let snapshotCache;
+		if (options.fromSnapshot !== void 0) {
+			const resolved = yield* makeSnapshotReader({ stackRoot: effectiveIdentity.stackRoot }).resolve(options.fromSnapshot).pipe(Effect.mapError((cause) => new CliInternalError({
+				message: "snapshot lookup failed",
+				cause
+			})));
+			switch (resolved.tag) {
+				case "found":
+					startFromSnapshot = {
+						id: resolved.entry.snapshotId,
+						stalePolicy: options.snapshotStalePolicy ?? "warn"
+					};
+					break;
+				case "not-found": return yield* Effect.fail(new CliSnapshotNotFoundError({ snapshotRef: options.fromSnapshot }));
+				case "ambiguous": return yield* Effect.fail(new CliUsageError({
+					message: `snapshot reference is ambiguous: ${resolved.snapshotRef}`,
+					hint: `matches: ${resolved.matches.map((entry) => entry.snapshotId).join(", ")}`
+				}));
+			}
+		}
+		if (options.snapshotCache !== void 0) {
+			const resolved = yield* makeSnapshotReader({ stackRoot: effectiveIdentity.stackRoot }).resolve(options.snapshotCache).pipe(Effect.mapError((cause) => new CliInternalError({
+				message: "snapshot lookup failed",
+				cause
+			})));
+			switch (resolved.tag) {
+				case "found":
+					snapshotCache = {
+						name: options.snapshotCache,
+						existingSnapshotId: resolved.entry.snapshotId
+					};
+					break;
+				case "not-found":
+					snapshotCache = { name: options.snapshotCache };
+					break;
+				case "ambiguous": return yield* Effect.fail(new CliUsageError({
+					message: `snapshot reference is ambiguous: ${resolved.snapshotRef}`,
+					hint: `matches: ${resolved.matches.map((entry) => entry.snapshotId).join(", ")}`
+				}));
+			}
+		}
+		const { commandHandler, boot } = buildUpBootBundle({
 			stack,
+			identityValue,
+			runtimeRoot: effectiveIdentity.runtimeRoot,
+			devstackVersion,
+			rendererMode,
+			...startFromSnapshot === void 0 ? {} : { startFromSnapshot },
+			...snapshotCache === void 0 ? {} : { snapshotCache }
+		});
+		const handle = runStackWithBoot(publicStack, {
+			identity: {
+				app: String(identityValue.app),
+				stack: String(identityValue.stack),
+				network: String(identityValue.network)
+			},
 			appRoot,
-			runtimeRoot: effectiveIdentity.runtimeRoot
+			runtimeRoot: effectiveIdentity.runtimeRoot,
+			codegen: stack.options.codegen,
+			commandHandler,
+			boot
 		});
-		return yield* Effect.gen(function* () {
-			const state = yield* makeProjectionRef();
-			const snapshot = yield* SnapshotOrchestratorService;
-			const snapshotCommandHandler = makeSnapshotCommandHandler({
-				snapshot,
-				fs: yield* FileSystem.FileSystem,
-				runtimeRoot: effectiveIdentity.runtimeRoot
-			});
-			const orchestratorSinks = yield* buildProductionOrchestratorSinks();
-			const postAcquireHook = yield* buildProductionPostAcquireHook({ extras: stack.options.extras });
-			yield* superviseStackEffect({
-				_tag: "Stack",
-				members: stack.members,
-				options: stack.options
-			}, identityValue, state, {
-				orchestratorSinks,
-				commandHandler: snapshotCommandHandler,
-				postAcquireHook,
-				extendContext: extendBuiltInPluginContext,
-				beforeInitialAcquire: (handle) => Effect.gen(function* () {
-					const stackPaths = yield* StackPathsService;
-					const recovery = yield* snapshot.recoverPendingRestore.pipe(Effect.tapCause((cause) => Effect.sync(() => {
-						process.stderr.write(`snapshot recovery scan failed: ${Cause.pretty(cause)}\n`);
-					})), Effect.catch(() => Effect.succeed(null)));
-					if (recovery && !recovery.noMarker) {
-						const summary = `snapshot.recover-pending: inspected=${recovery.inspected} recovered=${recovery.recovered} stillPending=${recovery.stillPending.length} markerCleared=${recovery.markerCleared}`;
-						process.stderr.write(`${summary}\n`);
-						if (recovery.stillPending.length > 0) for (const entry of recovery.stillPending) process.stderr.write(`  pending: ${entry.targetImageName} ← ${entry.stagedImageTag} (${entry.plugin}/${entry.role})\n`);
-					}
-					const commandChannel = yield* installCommandChannelBridge({
-						stackRoot: stackPaths.stackRoot,
-						handle
-					});
-					yield* installLiveSupervisorRoster({
-						stackRoot: stackPaths.stackRoot,
-						app: String(identityValue.app),
-						stack: String(identityValue.stack)
-					});
-					const rendererEvents = yield* Queue.unbounded();
-					const renderer = makeTuiSurface({
-						mode: rendererMode,
-						publishCommand: makeQueueCommandPublisher(handle.commands)
-					});
-					yield* Effect.addFinalizer(() => renderer.flush.pipe(Effect.catch(() => Effect.void)));
-					yield* Effect.forkScoped(renderer.mount(handle.state, Stream.fromQueue(rendererEvents)).pipe(Effect.catch((cause) => Effect.sync(() => {
-						process.stderr.write(`renderer failed: ${cause.detail ?? String(cause)}\n`);
-					}))));
-					yield* Effect.forkScoped(persistProjectionChanges(stackPaths.stackRoot, handle.state));
-					yield* Effect.forkScoped(Stream.fromQueue(handle.events).pipe(Stream.runForEach((event) => Effect.gen(function* () {
-						yield* Queue.offer(rendererEvents, event);
-						yield* commandChannel.publishEvent(event);
-					}))));
-				})
-			}).pipe(Effect.provide(layerBuiltInPluginRuntime(orchestratorSinks)));
-		}).pipe(Effect.provide(substrateLayers), Effect.provide(Logger.layer([])), Effect.matchCauseEffect({
-			onFailure: (cause) => {
-				const live = findCliSupervisorLiveError(cause);
-				if (live !== null) return Effect.fail(live);
-				return Effect.fail(new CliInternalError({
+		return yield* Effect.scoped(Effect.gen(function* () {
+			yield* handle.start.pipe(Effect.catch((bootError) => {
+				const live = findCliSupervisorLiveError(bootError.cause);
+				return Effect.fail(live ?? new CliInternalError({
 					message: "stack failed",
-					cause: Cause.pretty(cause)
+					cause: Cause.pretty(bootError.cause)
 				}));
-			},
-			onSuccess: () => Effect.succeed({ exitCode: ExitCode.OK })
+			}));
+			yield* handle.awaitShutdown.pipe(Effect.catchCause((cause) => Effect.fail(new CliInternalError({
+				message: "stack failed",
+				cause: Cause.pretty(cause)
+			}))));
+			return { exitCode: ExitCode.OK };
 		}));
 	});
 };