@mysten-incubation/devstack 0.0.1 → 0.1.1

package/dist/cli/wirings/up.mjs

@@ -0,0 +1,287 @@
+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 { 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 { ExitCode } from "../../surfaces/cli/sysexits.mjs";
+import { CliInternalError, CliSupervisorLiveError } from "../../surfaces/cli/errors.mjs";
+import { DEFAULT_LIFECYCLE_PRUNE_RESOURCES, collectLifecyclePruneInventory, defaultLifecyclePruneSelection, runLifecyclePrune } from "../../orchestrators/lifecycle-prune/index.mjs";
+import "../../surfaces/cli/index.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 { provideFileSystem } from "./provide-file-system.mjs";
+import { Cause, Effect, Exit, FileSystem, Logger, Queue, Ref, 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) => {
+		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) => [{
+				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) => [{
+				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 "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,
+				dryRun: false
+			})), Effect.as([]));
+			default: return Effect.succeed([]);
+		}
+	};
+};
+const installLiveSupervisorRoster = (params) => Effect.gen(function* () {
+	const paths = rosterPathsFor(params.stackRoot);
+	if (!(yield* claim(paths)).soleHolder) {
+		yield* release(paths).pipe(Effect.catch(() => Effect.void));
+		return yield* Effect.fail(new CliSupervisorLiveError({
+			app: params.app,
+			stack: params.stack,
+			hint: "use `devstack apply` from another shell, or choose a different --stack name"
+		}));
+	}
+	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 }
+				});
+				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;
+				});
+				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* 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
+* as the outer Node fiber so SIGINT reaches scope finalizers.
+*
+* Returns a typed `CommandResult` / fails with a typed `CliError` so
+* the dispatcher's `emitFailure` renders the envelope (JSON mode) or
+* human-mode stderr line. Wirings MUST NOT write raw bytes to
+* `process.stderr` or mutate `process.exitCode` for terminal failures —
+* the dispatcher owns the projection.
+*/
+const runUpLive = (configPath, identity, options) => {
+	const loader = makeConfigLoader();
+	return Effect.gen(function* () {
+		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 effectiveIdentity = resolvedIdentityForStack(identity, stack);
+		const identityValue = identityValueFor(effectiveIdentity);
+		const appRoot = dirname(loaded.resolvedConfigPath);
+		const rendererMode = resolveUpRendererMode({
+			cliRenderer: options.renderer,
+			stackRenderer: stack.options.renderer,
+			stdoutIsTty: options.stdoutIsTty
+		});
+		const substrateLayers = buildVerbLayers({
+			identity: identityValue,
+			stack,
+			appRoot,
+			runtimeRoot: effectiveIdentity.runtimeRoot
+		});
+		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({
+					message: "stack failed",
+					cause: Cause.pretty(cause)
+				}));
+			},
+			onSuccess: () => Effect.succeed({ exitCode: ExitCode.OK })
+		}));
+	});
+};
+//#endregion
+export { runUpLive };
+
+//# sourceMappingURL=up.mjs.map

package/dist/cli/wirings/up.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"up.mjs","names":["resolvePath"],"sources":["../../../src/cli/wirings/up.ts"],"sourcesContent":["// `devstack up` verb wiring.\n//\n// Wires the substrate Layer stack, supervisor, attached renderer, and\n// in-process TUI command queue. The Effect runs as the outer Node fiber\n// so SIGINT reaches scope finalizers (see surfaces/cli/index.ts\n// architecture invariant).\n//\n// Logger layer: `Logger.layer([])` (silent). `up` owns the TUI, which is\n// the operator-facing output channel; routing structured `Effect.log*`\n// records to stderr would scribble on top of the live ink renderer in\n// human mode and would duplicate the structured event stream the plain\n// renderer already emits in non-TTY mode. The sibling `apply` verb (no\n// TUI) uses `Logger.consolePretty()` because its consumer is CI.\n\nimport { dirname, resolve as resolvePath } from 'node:path';\n\nimport { Cause, Effect, Exit, FileSystem, Logger, Queue, Ref, Scope, Stream } from 'effect';\n\nimport type { Identity } from '../../substrate/identity.ts';\nimport type { EngineCommand, EngineEvent } from '../../substrate/events.ts';\nimport { StackPathsService } from '../../substrate/runtime/paths.ts';\nimport {\n\tclaim,\n\tcommandChannelPaths,\n\theartbeatFiber,\n\tmakeCommandChannelSubscriber,\n\tmakeProjectionRef,\n\tpersistProjectionChanges,\n\trelease,\n\ttype SupervisedStack,\n\ttype SupervisorCommandHandler,\n\ttype SupervisorHandle,\n} from '../../substrate/runtime/index.ts';\nimport {\n\tcollectLifecyclePruneInventory,\n\tdefaultLifecyclePruneSelection,\n\tDEFAULT_LIFECYCLE_PRUNE_RESOURCES,\n\trunLifecyclePrune,\n} from '../../orchestrators/lifecycle-prune/index.ts';\nimport { superviseStackEffect } from '../../orchestrators/run.ts';\nimport {\n\tbuildProductionOrchestratorSinks,\n\tbuildProductionPostAcquireHook,\n} from '../../orchestrators/runtime-composition.ts';\nimport {\n\textendBuiltInPluginContext,\n\tlayerBuiltInPluginRuntime,\n} from '../../orchestrators/built-in-plugin-layers.ts';\nimport {\n\tcaptureSnapshot,\n\tSnapshotOrchestratorService,\n} from '../../orchestrators/snapshot/index.ts';\nimport {\n\ttype CliError,\n\tCliInternalError,\n\tCliSupervisorLiveError,\n\ttype GlobalFlags,\n} from '../../surfaces/cli/index.ts';\nimport type { CommandResult } from '../../surfaces/cli/commands/index.ts';\nimport { ExitCode } from '../../surfaces/cli/sysexits.ts';\nimport { makeTuiSurface } from '../../surfaces/tui/index.ts';\nimport type { LoadedConfig } from '../../surfaces/cli/commands/config-loader.ts';\n\nimport { cliErrorFromConfigExit } from '../bail.ts';\nimport { makeQueueCommandPublisher, resolveUpRendererMode } from '../up-lifecycle.ts';\nimport { makeConfigLoader } from './config-loader.ts';\nimport { isEngineCommand } from './engine-command.ts';\nimport {\n\tfindCliSupervisorLiveError,\n\tidentityValueFor,\n\tresolvedIdentityForStack,\n\ttype ResolvedIdentity,\n} from './identity.ts';\nimport { buildVerbLayers } from './build-verb-layers.ts';\nimport { provideFileSystem } from './provide-file-system.ts';\n\nconst rosterPathsFor = (stackRoot: string) => ({\n\tstackLockFile: resolvePath(stackRoot, 'stack.lock'),\n\trosterFile: resolvePath(stackRoot, 'roster.json'),\n});\n\n// -----------------------------------------------------------------------------\n// Supervisor command handler — snapshot/wipe/prune injected dispatch\n// -----------------------------------------------------------------------------\n\n/** Captured snapshot metadata is round-tripped through the\n *  command-channel ack payload so the publisher's `awaitCompletion`\n *  can surface it without tailing the engine event stream. */\ninterface SnapshotCaptureAckPayload {\n\treadonly kind: 'captured' | 'failed' | 'skipped';\n\treadonly snapshotId?: string;\n\treadonly name?: string;\n\treadonly summary?: string;\n\treadonly reason?: string;\n}\n\nconst makeSnapshotCommandHandler = (params: {\n\treadonly snapshot: import('../../orchestrators/snapshot/index.ts').SnapshotOrchestrator;\n\treadonly fs: FileSystem.FileSystem;\n\treadonly runtimeRoot: string;\n}): SupervisorCommandHandler => {\n\treturn (cmd, handlerCtx) => {\n\t\tswitch (cmd.tag) {\n\t\t\tcase 'snapshot.capture':\n\t\t\t\treturn captureSnapshot({\n\t\t\t\t\tsnapshotId: cmd.snapshotId,\n\t\t\t\t\tname: cmd.name,\n\t\t\t\t\tonProgress: (progress) =>\n\t\t\t\t\t\thandlerCtx.publish({\n\t\t\t\t\t\t\ttag: 'snapshot.captureProgress',\n\t\t\t\t\t\t\t...(cmd.snapshotId === undefined ? {} : { snapshotId: cmd.snapshotId }),\n\t\t\t\t\t\t\t...(cmd.name === undefined ? {} : { name: cmd.name }),\n\t\t\t\t\t\t\tphase: progress.phase,\n\t\t\t\t\t\t\t...(progress.detail === undefined ? {} : { detail: progress.detail }),\n\t\t\t\t\t\t\t...(progress.pausedContainers === undefined\n\t\t\t\t\t\t\t\t? {}\n\t\t\t\t\t\t\t\t: { pausedContainers: progress.pausedContainers }),\n\t\t\t\t\t\t\t...(progress.totalContainers === undefined\n\t\t\t\t\t\t\t\t? {}\n\t\t\t\t\t\t\t\t: { totalContainers: progress.totalContainers }),\n\t\t\t\t\t\t\tat: Date.now(),\n\t\t\t\t\t\t}),\n\t\t\t\t}).pipe(\n\t\t\t\t\tEffect.provideService(SnapshotOrchestratorService, params.snapshot),\n\t\t\t\t\tEffect.provideService(FileSystem.FileSystem, params.fs),\n\t\t\t\t\tEffect.map((meta) => [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\ttag: 'snapshot.captured',\n\t\t\t\t\t\t\tsnapshotId: meta.id,\n\t\t\t\t\t\t\t...(meta.label === null ? {} : { name: meta.label }),\n\t\t\t\t\t\t\tat: Date.now(),\n\t\t\t\t\t\t},\n\t\t\t\t\t]),\n\t\t\t\t);\n\t\t\tcase 'snapshot.restore':\n\t\t\t\treturn provideFileSystem(params.fs, params.snapshot.restore({ id: cmd.snapshotId })).pipe(\n\t\t\t\t\tEffect.map((meta) => [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\ttag: 'snapshot.restored',\n\t\t\t\t\t\t\tsnapshotId: meta.id,\n\t\t\t\t\t\t\tat: Date.now(),\n\t\t\t\t\t\t},\n\t\t\t\t\t]),\n\t\t\t\t);\n\t\t\tcase 'snapshot.list':\n\t\t\t\treturn provideFileSystem(params.fs, params.snapshot.list).pipe(Effect.as([]));\n\t\t\tcase 'snapshot.delete':\n\t\t\t\treturn provideFileSystem(params.fs, params.snapshot.delete(cmd.snapshotId)).pipe(\n\t\t\t\t\tEffect.as([]),\n\t\t\t\t);\n\t\t\tcase 'wipe.requested':\n\t\t\t\treturn provideFileSystem(params.fs, params.snapshot.wipe({})).pipe(Effect.as([]));\n\t\t\tcase 'prune.requested':\n\t\t\t\t// Route to the same orchestrator the offline `devstack prune`\n\t\t\t\t// verb uses (`runLifecyclePrune`), NOT the snapshot-orchestrator\n\t\t\t\t// prune (which only cleans the snapshot catalog and would leave\n\t\t\t\t// stale containers/networks/volumes/images behind for an attached\n\t\t\t\t// supervisor — silent under-prune is the bug we're closing).\n\t\t\t\t// Live supervisor implies the current stack's group is live and\n\t\t\t\t// therefore excluded from the default selection — exactly the\n\t\t\t\t// invariant the live-attached `prune` needs (operator can prune\n\t\t\t\t// sibling stacks under the same Docker daemon without touching\n\t\t\t\t// the running one).\n\t\t\t\treturn collectLifecyclePruneInventory({ runtimeRoot: params.runtimeRoot }).pipe(\n\t\t\t\t\tEffect.flatMap((inventory) =>\n\t\t\t\t\t\trunLifecyclePrune(\n\t\t\t\t\t\t\t{ runtimeRoot: params.runtimeRoot },\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tgroupKeys: defaultLifecyclePruneSelection(\n\t\t\t\t\t\t\t\t\tinventory,\n\t\t\t\t\t\t\t\t\tDEFAULT_LIFECYCLE_PRUNE_RESOURCES,\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\tresources: DEFAULT_LIFECYCLE_PRUNE_RESOURCES,\n\t\t\t\t\t\t\t\tdryRun: false,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t\tEffect.as([]),\n\t\t\t\t);\n\t\t\tdefault:\n\t\t\t\treturn Effect.succeed([]);\n\t\t}\n\t};\n};\n\nconst installLiveSupervisorRoster = (params: {\n\treadonly stackRoot: string;\n\treadonly app: string;\n\treadonly stack: string;\n}): Effect.Effect<void, unknown, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst paths = rosterPathsFor(params.stackRoot);\n\t\tconst claimed = yield* claim(paths);\n\t\tif (!claimed.soleHolder) {\n\t\t\tyield* release(paths).pipe(Effect.catch(() => Effect.void));\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew CliSupervisorLiveError({\n\t\t\t\t\tapp: params.app,\n\t\t\t\t\tstack: params.stack,\n\t\t\t\t\thint: 'use `devstack apply` from another shell, or choose a different --stack name',\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tyield* Effect.addFinalizer(() => release(paths).pipe(Effect.catch(() => Effect.void)));\n\t\tyield* Effect.forkScoped(heartbeatFiber(paths));\n\t});\n\ninterface PendingSnapshotCapture {\n\treadonly commandId: string;\n\treadonly snapshotId: string;\n\treadonly name?: string;\n}\n\n/** Detect snapshot-capture completion events on the published stream\n *  so we can ack/fail the originating `snapshot.capture` command with\n *  a structured payload (snapshot metadata on success; failure summary\n *  on failure). Drops the legacy tail-fiber on the CLI side — the\n *  `summary` is now surfaced through `awaitCompletion`'s reply.payload. */\nconst snapshotCaptureAckFromEvent = (\n\tevent: unknown,\n): { readonly snapshotId: string; readonly payload: SnapshotCaptureAckPayload } | null => {\n\tif (typeof event !== 'object' || event === null) return null;\n\tconst record = event as {\n\t\treadonly tag?: string;\n\t\treadonly snapshotId?: string;\n\t\treadonly name?: string;\n\t\treadonly summary?: string;\n\t\treadonly reason?: string;\n\t};\n\tif (typeof record.snapshotId !== 'string') return null;\n\tif (record.tag === 'snapshot.captured') {\n\t\treturn {\n\t\t\tsnapshotId: record.snapshotId,\n\t\t\tpayload: {\n\t\t\t\tkind: 'captured',\n\t\t\t\tsnapshotId: record.snapshotId,\n\t\t\t\t...(record.name === undefined ? {} : { name: record.name }),\n\t\t\t},\n\t\t};\n\t}\n\tif (record.tag === 'snapshot.captureFailed') {\n\t\treturn {\n\t\t\tsnapshotId: record.snapshotId,\n\t\t\tpayload: {\n\t\t\t\tkind: 'failed',\n\t\t\t\tsnapshotId: record.snapshotId,\n\t\t\t\t...(record.name === undefined ? {} : { name: record.name }),\n\t\t\t\t...(typeof record.summary === 'string' ? { summary: record.summary } : {}),\n\t\t\t},\n\t\t};\n\t}\n\tif (record.tag === 'snapshot.captureSkipped') {\n\t\treturn {\n\t\t\tsnapshotId: record.snapshotId,\n\t\t\tpayload: {\n\t\t\t\tkind: 'skipped',\n\t\t\t\tsnapshotId: record.snapshotId,\n\t\t\t\t...(typeof record.reason === 'string' ? { reason: record.reason } : {}),\n\t\t\t},\n\t\t};\n\t}\n\treturn null;\n};\n\nconst installCommandChannelBridge = (params: {\n\treadonly stackRoot: string;\n\treadonly handle: SupervisorHandle;\n}): Effect.Effect<\n\t{\n\t\treadonly publishEvent: (event: EngineEvent) => Effect.Effect<void>;\n\t},\n\tunknown,\n\tScope.Scope\n> =>\n\tEffect.gen(function* () {\n\t\tconst subscriber = yield* makeCommandChannelSubscriber(commandChannelPaths(params.stackRoot), {\n\t\t\tfromOffset: 'current',\n\t\t});\n\n\t\t// snapshotId → pending command record id. Populated when the\n\t\t// bridge dispatches a `snapshot.capture` command; drained when\n\t\t// the matching completion event flows through `publishEvent`.\n\t\tconst pendingCaptures = yield* Ref.make<ReadonlyMap<string, PendingSnapshotCapture>>(new Map());\n\n\t\t// Drive the command stream so a stream-LEVEL failure does not\n\t\t// permanently wedge cross-process IPC. The subscriber's `commands`\n\t\t// tail decodes with the `onDecodeError: 'fail'` default, so ONE\n\t\t// malformed/truncated NDJSON line (CLI killed mid-append, partial\n\t\t// disk write) raises `CommandChannelError` and terminates the\n\t\t// stream. If `runForEach` were the only consumer, the live\n\t\t// supervisor would then process NO further commands for the rest of\n\t\t// the `up` session (a sibling `snapshot save`/`apply`/`prune`\n\t\t// appends but is never read, and its `awaitCompletion` times out\n\t\t// with no diagnostic). Instead we log the failure and RE-SUBSCRIBE:\n\t\t// `subscriber.commands` is `tailRecords(... fromOffset: 'current')`,\n\t\t// and each subscription re-runs its builder, re-anchoring the tail\n\t\t// at the file's current EOF — so the corrupt line (and any records\n\t\t// that were buffered alongside it) are skipped and subsequent\n\t\t// commands are processed again. A short delay before resume avoids a\n\t\t// busy spin if the tail keeps failing. The publisher's reply-tail\n\t\t// already uses `onDecodeError: 'skip'` for the same NDJSON-tolerance\n\t\t// reason; this gives the command-subscriber side equivalent\n\t\t// resilience without touching the shared subscriber.\n\t\tconst consumeCommands: Effect.Effect<void, never, Scope.Scope> = subscriber.commands\n\t\t\t.pipe(\n\t\t\t\tStream.runForEach((record) =>\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tif (!isEngineCommand(record.command)) {\n\t\t\t\t\t\t\tyield* subscriber\n\t\t\t\t\t\t\t\t.fail(record.id, 'invalid command', 'command payload did not match EngineCommand')\n\t\t\t\t\t\t\t\t.pipe(Effect.catch(() => Effect.void));\n\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst cmd: EngineCommand = record.command;\n\t\t\t\t\t\t// Snapshot capture is a background task in the supervisor:\n\t\t\t\t\t\t// `runCommand` returns as soon as the fork is scheduled, so\n\t\t\t\t\t\t// auto-acking here would race the actual capture. We defer\n\t\t\t\t\t\t// ack/fail until the matching `snapshot.captured` /\n\t\t\t\t\t\t// `snapshot.captureFailed` / `snapshot.captureSkipped` event\n\t\t\t\t\t\t// flows through `publishEvent` below.\n\t\t\t\t\t\tif (cmd.tag === 'snapshot.capture') {\n\t\t\t\t\t\t\tif (cmd.snapshotId === undefined) {\n\t\t\t\t\t\t\t\t// Without a snapshotId we cannot correlate the completion\n\t\t\t\t\t\t\t\t// event back to this command record. Fall through to the\n\t\t\t\t\t\t\t\t// legacy auto-ack path — the CLI side mints an id today, so\n\t\t\t\t\t\t\t\t// this branch is defensive.\n\t\t\t\t\t\t\t\tyield* params.handle.runCommand(cmd).pipe(\n\t\t\t\t\t\t\t\t\tEffect.andThen(subscriber.ack(record.id)),\n\t\t\t\t\t\t\t\t\tEffect.catchCause((cause) =>\n\t\t\t\t\t\t\t\t\t\tsubscriber\n\t\t\t\t\t\t\t\t\t\t\t.fail(\n\t\t\t\t\t\t\t\t\t\t\t\trecord.id,\n\t\t\t\t\t\t\t\t\t\t\t\t'command failed',\n\t\t\t\t\t\t\t\t\t\t\t\tCause.pretty(cause as Cause.Cause<unknown>),\n\t\t\t\t\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\t\t\t\t\t.pipe(Effect.catch(() => Effect.void)),\n\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tyield* Ref.update(pendingCaptures, (map) => {\n\t\t\t\t\t\t\t\tconst next = new Map(map);\n\t\t\t\t\t\t\t\tnext.set(cmd.snapshotId!, {\n\t\t\t\t\t\t\t\t\tcommandId: record.id,\n\t\t\t\t\t\t\t\t\tsnapshotId: cmd.snapshotId!,\n\t\t\t\t\t\t\t\t\t...(cmd.name === undefined ? {} : { name: cmd.name }),\n\t\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\t\treturn next;\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tyield* params.handle.runCommand(cmd).pipe(\n\t\t\t\t\t\t\t\tEffect.catchCause((cause) =>\n\t\t\t\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\t\t\t\t// Synchronous dispatch failure (e.g. command-loop refused).\n\t\t\t\t\t\t\t\t\t\t// Drain the pending entry and surface the failure now.\n\t\t\t\t\t\t\t\t\t\tyield* Ref.update(pendingCaptures, (map) => {\n\t\t\t\t\t\t\t\t\t\t\tconst next = new Map(map);\n\t\t\t\t\t\t\t\t\t\t\tnext.delete(cmd.snapshotId!);\n\t\t\t\t\t\t\t\t\t\t\treturn next;\n\t\t\t\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\t\t\t\tyield* subscriber\n\t\t\t\t\t\t\t\t\t\t\t.fail(\n\t\t\t\t\t\t\t\t\t\t\t\trecord.id,\n\t\t\t\t\t\t\t\t\t\t\t\t'command failed',\n\t\t\t\t\t\t\t\t\t\t\t\tCause.pretty(cause as Cause.Cause<unknown>),\n\t\t\t\t\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\t\t\t\t\t.pipe(Effect.catch(() => Effect.void));\n\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tyield* params.handle.runCommand(cmd).pipe(\n\t\t\t\t\t\t\tEffect.andThen(subscriber.ack(record.id)),\n\t\t\t\t\t\t\tEffect.catchCause((cause) =>\n\t\t\t\t\t\t\t\tsubscriber\n\t\t\t\t\t\t\t\t\t.fail(record.id, 'command failed', Cause.pretty(cause as Cause.Cause<unknown>))\n\t\t\t\t\t\t\t\t\t.pipe(Effect.catch(() => Effect.void)),\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t);\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t)\n\t\t\t.pipe(\n\t\t\t\tEffect.catchCause((cause): Effect.Effect<void, never, Scope.Scope> => {\n\t\t\t\t\t// Scope-close interrupts this forked fiber via an interrupt\n\t\t\t\t\t// cause. Re-raise it so the fork stops cleanly on `up`\n\t\t\t\t\t// teardown — resuming here would leak the fiber and spam\n\t\t\t\t\t// stderr forever.\n\t\t\t\t\tif (Cause.hasInterrupts(cause as Cause.Cause<unknown>)) {\n\t\t\t\t\t\treturn Effect.failCause(cause as Cause.Cause<never>);\n\t\t\t\t\t}\n\t\t\t\t\t// Otherwise a stream-level failure (e.g. a corrupt NDJSON\n\t\t\t\t\t// line tripping the subscriber's `onDecodeError: 'fail'`\n\t\t\t\t\t// default). Log it, pause briefly to avoid a busy spin, then\n\t\t\t\t\t// re-subscribe by recursing — a fresh tail re-anchors at the\n\t\t\t\t\t// file's current EOF, so the next command is processed\n\t\t\t\t\t// instead of IPC wedging for the session.\n\t\t\t\t\treturn Effect.sync(() => {\n\t\t\t\t\t\tprocess.stderr.write(\n\t\t\t\t\t\t\t`command channel decode failed; resuming tail: ${Cause.pretty(cause as Cause.Cause<unknown>)}\\n`,\n\t\t\t\t\t\t);\n\t\t\t\t\t}).pipe(\n\t\t\t\t\t\tEffect.andThen(Effect.sleep('200 millis')),\n\t\t\t\t\t\tEffect.andThen(Effect.suspend(() => consumeCommands)),\n\t\t\t\t\t);\n\t\t\t\t}),\n\t\t\t);\n\n\t\tyield* Effect.forkScoped(consumeCommands);\n\n\t\tconst publishEvent = (event: EngineEvent): Effect.Effect<void> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\t// First, route the event to the events file so peer\n\t\t\t\t// subscribers see it. THEN drain any matching pending\n\t\t\t\t// capture so the ack lands after the engine event — this\n\t\t\t\t// preserves the \"captured before ack\" ordering tests rely\n\t\t\t\t// on (test/cli/main.test.ts:483-491 publishes captured then\n\t\t\t\t// acks; we mirror that ordering from the supervisor side).\n\t\t\t\tyield* subscriber.publishEvent(event).pipe(Effect.catch(() => Effect.void));\n\t\t\t\tconst ackFromEvent = snapshotCaptureAckFromEvent(event);\n\t\t\t\tif (ackFromEvent === null) return;\n\t\t\t\tconst pending = yield* Ref.modify(pendingCaptures, (map) => {\n\t\t\t\t\tconst entry = map.get(ackFromEvent.snapshotId);\n\t\t\t\t\tif (entry === undefined) return [null, map];\n\t\t\t\t\tconst next = new Map(map);\n\t\t\t\t\tnext.delete(ackFromEvent.snapshotId);\n\t\t\t\t\treturn [entry, next];\n\t\t\t\t});\n\t\t\t\tif (pending === null) return;\n\t\t\t\tif (ackFromEvent.payload.kind === 'captured') {\n\t\t\t\t\tyield* subscriber\n\t\t\t\t\t\t.ack(pending.commandId, 'captured', ackFromEvent.payload)\n\t\t\t\t\t\t.pipe(Effect.catch(() => Effect.void));\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tif (ackFromEvent.payload.kind === 'failed') {\n\t\t\t\t\tyield* subscriber\n\t\t\t\t\t\t.fail(\n\t\t\t\t\t\t\tpending.commandId,\n\t\t\t\t\t\t\t'snapshot capture failed',\n\t\t\t\t\t\t\tackFromEvent.payload.summary,\n\t\t\t\t\t\t\tackFromEvent.payload,\n\t\t\t\t\t\t)\n\t\t\t\t\t\t.pipe(Effect.catch(() => Effect.void));\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\t// skipped\n\t\t\t\tyield* subscriber\n\t\t\t\t\t.fail(\n\t\t\t\t\t\tpending.commandId,\n\t\t\t\t\t\t'snapshot capture skipped',\n\t\t\t\t\t\tackFromEvent.payload.reason,\n\t\t\t\t\t\tackFromEvent.payload,\n\t\t\t\t\t)\n\t\t\t\t\t.pipe(Effect.catch(() => Effect.void));\n\t\t\t});\n\n\t\treturn { publishEvent };\n\t});\n\n/**\n * Run `devstack up`. Wires the substrate Layer stack, supervisor,\n * attached renderer, and in-process TUI command queue. The Effect runs\n * as the outer Node fiber so SIGINT reaches scope finalizers.\n *\n * Returns a typed `CommandResult` / fails with a typed `CliError` so\n * the dispatcher's `emitFailure` renders the envelope (JSON mode) or\n * human-mode stderr line. Wirings MUST NOT write raw bytes to\n * `process.stderr` or mutate `process.exitCode` for terminal failures —\n * the dispatcher owns the projection.\n */\nexport const runUpLive = (\n\tconfigPath: string | undefined,\n\tidentity: ResolvedIdentity,\n\toptions: {\n\t\treadonly renderer: GlobalFlags['renderer'];\n\t\treadonly stdoutIsTty: boolean;\n\t},\n): Effect.Effect<CommandResult, CliError> => {\n\tconst loader = makeConfigLoader();\n\treturn Effect.gen(function* () {\n\t\tconst loadExit = yield* Effect.exit(loader.load(configPath));\n\t\tif (Exit.isFailure(loadExit)) {\n\t\t\treturn yield* Effect.fail(cliErrorFromConfigExit(loadExit));\n\t\t}\n\t\tconst loaded = loadExit.value;\n\t\tconst stack = (loaded as LoadedConfig & { readonly stack: SupervisedStack }).stack;\n\n\t\t// Re-derive the identity against the EFFECTIVE stack (explicit\n\t\t// `--stack`/`$DEVSTACK_STACK` > `config.stackName` > inferred) so\n\t\t// the roster lock, command channel, and container/router naming all\n\t\t// target the same stack the operator selected — matching what\n\t\t// `snapshot.ts` already does. Without this, an explicit `--stack`\n\t\t// would boot the supervisor under the config's `stackName` and a\n\t\t// concurrent default-stack `up` would falsely collide on the live\n\t\t// supervisor (`error: supervisor live for <app>/<stack>`, exit 40).\n\t\tconst effectiveIdentity = resolvedIdentityForStack(identity, stack);\n\t\tconst identityValue: Identity = identityValueFor(effectiveIdentity);\n\n\t\tconst appRoot = dirname(loaded.resolvedConfigPath);\n\t\tconst rendererMode = resolveUpRendererMode({\n\t\t\tcliRenderer: options.renderer,\n\t\t\tstackRenderer: stack.options.renderer,\n\t\t\tstdoutIsTty: options.stdoutIsTty,\n\t\t});\n\t\tconst substrateLayers = buildVerbLayers({\n\t\t\tidentity: identityValue,\n\t\t\tstack,\n\t\t\tappRoot,\n\t\t\truntimeRoot: effectiveIdentity.runtimeRoot,\n\t\t});\n\n\t\tconst program = Effect.gen(function* () {\n\t\t\tconst state = yield* makeProjectionRef();\n\t\t\tconst snapshot = yield* SnapshotOrchestratorService;\n\t\t\tconst fs = yield* FileSystem.FileSystem;\n\t\t\tconst snapshotCommandHandler = makeSnapshotCommandHandler({\n\t\t\t\tsnapshot,\n\t\t\t\tfs,\n\t\t\t\truntimeRoot: effectiveIdentity.runtimeRoot,\n\t\t\t});\n\t\t\tconst orchestratorSinks = yield* buildProductionOrchestratorSinks();\n\t\t\tconst postAcquireHook = yield* buildProductionPostAcquireHook({\n\t\t\t\textras: stack.options.extras,\n\t\t\t});\n\t\t\tyield* superviseStackEffect(\n\t\t\t\t{ _tag: 'Stack', members: stack.members, options: stack.options },\n\t\t\t\tidentityValue,\n\t\t\t\tstate,\n\t\t\t\t{\n\t\t\t\t\torchestratorSinks,\n\t\t\t\t\tcommandHandler: snapshotCommandHandler,\n\t\t\t\t\tpostAcquireHook,\n\t\t\t\t\textendContext: extendBuiltInPluginContext,\n\t\t\t\t\tbeforeInitialAcquire: (handle) =>\n\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\tconst stackPaths = yield* StackPathsService;\n\t\t\t\t\t\t\t// Reconcile any half-promoted snapshot restore from a\n\t\t\t\t\t\t\t// prior supervise (process hard-killed mid `tagImage`\n\t\t\t\t\t\t\t// loop, Docker daemon outage, etc.) BEFORE any plugin\n\t\t\t\t\t\t\t// acquire fires. The scanner is idempotent and a no-op\n\t\t\t\t\t\t\t// when no marker is present; partial recovery surfaces\n\t\t\t\t\t\t\t// via the returned summary's `stillPending` list which\n\t\t\t\t\t\t\t// we log so the operator can investigate.\n\t\t\t\t\t\t\tconst recovery = yield* snapshot.recoverPendingRestore.pipe(\n\t\t\t\t\t\t\t\tEffect.tapCause((cause) =>\n\t\t\t\t\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\t\t\t\t\tprocess.stderr.write(\n\t\t\t\t\t\t\t\t\t\t\t`snapshot recovery scan failed: ${Cause.pretty(cause as Cause.Cause<unknown>)}\\n`,\n\t\t\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\tEffect.catch(() => Effect.succeed(null)),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\tif (recovery && !recovery.noMarker) {\n\t\t\t\t\t\t\t\tconst summary = `snapshot.recover-pending: inspected=${recovery.inspected} recovered=${recovery.recovered} stillPending=${recovery.stillPending.length} markerCleared=${recovery.markerCleared}`;\n\t\t\t\t\t\t\t\tprocess.stderr.write(`${summary}\\n`);\n\t\t\t\t\t\t\t\tif (recovery.stillPending.length > 0) {\n\t\t\t\t\t\t\t\t\tfor (const entry of recovery.stillPending) {\n\t\t\t\t\t\t\t\t\t\tprocess.stderr.write(\n\t\t\t\t\t\t\t\t\t\t\t`  pending: ${entry.targetImageName} ← ${entry.stagedImageTag} (${entry.plugin}/${entry.role})\\n`,\n\t\t\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tconst commandChannel = yield* installCommandChannelBridge({\n\t\t\t\t\t\t\t\tstackRoot: stackPaths.stackRoot,\n\t\t\t\t\t\t\t\thandle,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tyield* installLiveSupervisorRoster({\n\t\t\t\t\t\t\t\tstackRoot: stackPaths.stackRoot,\n\t\t\t\t\t\t\t\tapp: String(identityValue.app),\n\t\t\t\t\t\t\t\tstack: String(identityValue.stack),\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tconst rendererEvents = yield* Queue.unbounded<EngineEvent>();\n\t\t\t\t\t\t\tconst renderer = makeTuiSurface({\n\t\t\t\t\t\t\t\tmode: rendererMode,\n\t\t\t\t\t\t\t\tpublishCommand: makeQueueCommandPublisher(handle.commands),\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tyield* Effect.addFinalizer(() =>\n\t\t\t\t\t\t\t\trenderer.flush.pipe(Effect.catch(() => Effect.void)),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\tyield* Effect.forkScoped(\n\t\t\t\t\t\t\t\trenderer.mount(handle.state, Stream.fromQueue(rendererEvents)).pipe(\n\t\t\t\t\t\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\t\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\t\t\t\t\t\tprocess.stderr.write(`renderer failed: ${cause.detail ?? String(cause)}\\n`);\n\t\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\tyield* Effect.forkScoped(\n\t\t\t\t\t\t\t\tpersistProjectionChanges(stackPaths.stackRoot, handle.state),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\tyield* Effect.forkScoped(\n\t\t\t\t\t\t\t\tStream.fromQueue(handle.events).pipe(\n\t\t\t\t\t\t\t\t\tStream.runForEach((event) =>\n\t\t\t\t\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\t\t\t\t\tyield* Queue.offer(rendererEvents, event);\n\t\t\t\t\t\t\t\t\t\t\tyield* commandChannel.publishEvent(event);\n\t\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}),\n\t\t\t\t},\n\t\t\t).pipe(Effect.provide(layerBuiltInPluginRuntime(orchestratorSinks)));\n\t\t});\n\n\t\t// `Effect.matchCauseEffect` projects the inner program's\n\t\t// cause to a typed `CliError` outcome — `CliSupervisorLiveError`\n\t\t// when the roster-claim path failed, otherwise a wrapped\n\t\t// `CliInternalError` whose `cause` carries the cascade for the\n\t\t// envelope renderer's `error.chain[]`.\n\t\treturn yield* program.pipe(\n\t\t\tEffect.provide(substrateLayers),\n\t\t\tEffect.provide(Logger.layer([])),\n\t\t\tEffect.matchCauseEffect({\n\t\t\t\tonFailure: (cause): Effect.Effect<CommandResult, CliError> => {\n\t\t\t\t\tconst live = findCliSupervisorLiveError(cause as Cause.Cause<unknown>);\n\t\t\t\t\tif (live !== null) {\n\t\t\t\t\t\treturn Effect.fail(live);\n\t\t\t\t\t}\n\t\t\t\t\treturn Effect.fail(\n\t\t\t\t\t\tnew CliInternalError({\n\t\t\t\t\t\t\tmessage: 'stack failed',\n\t\t\t\t\t\t\tcause: Cause.pretty(cause as Cause.Cause<unknown>),\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t},\n\t\t\t\tonSuccess: (): Effect.Effect<CommandResult, CliError> =>\n\t\t\t\t\tEffect.succeed({ exitCode: ExitCode.OK }),\n\t\t\t}),\n\t\t);\n\t});\n};\n"],"mappings":"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"}

package/dist/cli/wirings/wipe.mjs

@@ -0,0 +1,40 @@
+import { SnapshotOrchestratorService } from "../../orchestrators/snapshot/service.mjs";
+import "../../orchestrators/snapshot/index.mjs";
+import { removeRouterDispatchFilesForStack } from "../../orchestrators/router/cleanup.mjs";
+import { ensureNoLiveSupervisor, identityValueFor } from "./identity.mjs";
+import { buildDirectSnapshotLayers } from "./build-verb-layers.mjs";
+import { provideFileSystem } from "./provide-file-system.mjs";
+import { Effect, FileSystem, Logger } from "effect";
+//#region src/cli/wirings/wipe.ts
+const runWipeDirect = (identity) => Effect.gen(function* () {
+	yield* ensureNoLiveSupervisor(identity, "shut down the attached `devstack up` session first");
+	return yield* Effect.gen(function* () {
+		const snapshot = yield* SnapshotOrchestratorService;
+		yield* provideFileSystem(yield* FileSystem.FileSystem, snapshot.wipe({}));
+		yield* removeRouterDispatchFilesForStack({
+			runtimeRoot: identity.runtimeRoot,
+			app: identity.app,
+			stack: identity.stack
+		});
+	}).pipe(Effect.provide(buildDirectSnapshotLayers({
+		identity: identityValueFor(identity),
+		runtimeRoot: identity.runtimeRoot
+	})), Effect.provide(Logger.layer([Logger.consolePretty()])));
+});
+/** Read-only enumeration of the concrete targets a real `wipe` would
+*  remove — backs `devstack wipe --dry-run`. Deliberately does NOT
+*  `ensureNoLiveSupervisor` (a preview must work whether or not a
+*  supervisor is attached; it mutates nothing) and skips the router
+*  dispatch-file removal (that is a destructive side effect of the real
+*  wipe, not part of the preview). */
+const runWipePlanDirect = (identity) => Effect.gen(function* () {
+	const snapshot = yield* SnapshotOrchestratorService;
+	return yield* provideFileSystem(yield* FileSystem.FileSystem, snapshot.wipePlan({}));
+}).pipe(Effect.provide(buildDirectSnapshotLayers({
+	identity: identityValueFor(identity),
+	runtimeRoot: identity.runtimeRoot
+})), Effect.provide(Logger.layer([Logger.consolePretty()])));
+//#endregion
+export { runWipeDirect, runWipePlanDirect };
+
+//# sourceMappingURL=wipe.mjs.map

package/dist/cli/wirings/wipe.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"wipe.mjs","names":[],"sources":["../../../src/cli/wirings/wipe.ts"],"sourcesContent":["// `devstack wipe` verb wiring — direct/offline path.\n//\n// Refuses to run when a supervisor owns the stack (the operator must\n// shut down `devstack up` first). When safe, drains the snapshot\n// catalog AND removes any router-dispatch files this stack contributed\n// so the router doesn't keep referencing endpoints that no longer\n// exist on disk.\n\nimport { Effect, FileSystem, Logger } from 'effect';\n\nimport {\n\tSnapshotOrchestratorService,\n\ttype WipeTargets,\n} from '../../orchestrators/snapshot/index.ts';\nimport { removeRouterDispatchFilesForStack } from '../../orchestrators/router/cleanup.ts';\n\nimport { ensureNoLiveSupervisor, identityValueFor, type ResolvedIdentity } from './identity.ts';\nimport { buildDirectSnapshotLayers } from './build-verb-layers.ts';\nimport { provideFileSystem } from './provide-file-system.ts';\n\nexport const runWipeDirect = (identity: ResolvedIdentity): Effect.Effect<void, unknown> =>\n\tEffect.gen(function* () {\n\t\tyield* ensureNoLiveSupervisor(identity, 'shut down the attached `devstack up` session first');\n\t\tconst program = Effect.gen(function* () {\n\t\t\tconst snapshot = yield* SnapshotOrchestratorService;\n\t\t\tconst fs = yield* FileSystem.FileSystem;\n\t\t\tyield* provideFileSystem(fs, snapshot.wipe({}));\n\t\t\tyield* removeRouterDispatchFilesForStack({\n\t\t\t\truntimeRoot: identity.runtimeRoot,\n\t\t\t\tapp: identity.app,\n\t\t\t\tstack: identity.stack,\n\t\t\t});\n\t\t});\n\t\treturn yield* program.pipe(\n\t\t\tEffect.provide(\n\t\t\t\tbuildDirectSnapshotLayers({\n\t\t\t\t\tidentity: identityValueFor(identity),\n\t\t\t\t\truntimeRoot: identity.runtimeRoot,\n\t\t\t\t}),\n\t\t\t),\n\t\t\tEffect.provide(Logger.layer([Logger.consolePretty()])),\n\t\t);\n\t});\n\n/** Read-only enumeration of the concrete targets a real `wipe` would\n *  remove — backs `devstack wipe --dry-run`. Deliberately does NOT\n *  `ensureNoLiveSupervisor` (a preview must work whether or not a\n *  supervisor is attached; it mutates nothing) and skips the router\n *  dispatch-file removal (that is a destructive side effect of the real\n *  wipe, not part of the preview). */\nexport const runWipePlanDirect = (\n\tidentity: ResolvedIdentity,\n): Effect.Effect<WipeTargets, unknown> =>\n\tEffect.gen(function* () {\n\t\tconst snapshot = yield* SnapshotOrchestratorService;\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\treturn yield* provideFileSystem(fs, snapshot.wipePlan({}));\n\t}).pipe(\n\t\tEffect.provide(\n\t\t\tbuildDirectSnapshotLayers({\n\t\t\t\tidentity: identityValueFor(identity),\n\t\t\t\truntimeRoot: identity.runtimeRoot,\n\t\t\t}),\n\t\t),\n\t\tEffect.provide(Logger.layer([Logger.consolePretty()])),\n\t);\n"],"mappings":";;;;;;;;AAoBA,MAAa,iBAAiB,aAC7B,OAAO,IAAI,aAAa;AACvB,QAAO,uBAAuB,UAAU,qDAAqD;AAW7F,QAAO,OAVS,OAAO,IAAI,aAAa;EACvC,MAAM,WAAW,OAAO;AAExB,SAAO,kBAAkB,OADP,WAAW,YACA,SAAS,KAAK,EAAE,CAAC,CAAC;AAC/C,SAAO,kCAAkC;GACxC,aAAa,SAAS;GACtB,KAAK,SAAS;GACd,OAAO,SAAS;GAChB,CAAC;GAEkB,CAAC,KACrB,OAAO,QACN,0BAA0B;EACzB,UAAU,iBAAiB,SAAS;EACpC,aAAa,SAAS;EACtB,CAAC,CACF,EACD,OAAO,QAAQ,OAAO,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CACtD;EACA;;;;;;;AAQH,MAAa,qBACZ,aAEA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,OAAO;AAExB,QAAO,OAAO,kBAAkB,OADd,WAAW,YACO,SAAS,SAAS,EAAE,CAAC,CAAC;EACzD,CAAC,KACF,OAAO,QACN,0BAA0B;CACzB,UAAU,iBAAiB,SAAS;CACpC,aAAa,SAAS;CACtB,CAAC,CACF,EACD,OAAO,QAAQ,OAAO,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CACtD"}

package/dist/contracts/capability-decl.d.mts

@@ -1,5 +1,4 @@
 import { CodegenableDecl } from "./codegenable.mjs";
-import { LivenessClassifierDecl } from "./liveness-classifier.mjs";
 import { ProjectionDecl } from "./projection.mjs";
 import { RoutableDecl } from "./routable.mjs";
 import { SnapshotableDecl } from "./snapshotable.mjs";
@@ -21,7 +20,6 @@ interface DevstackCapabilityRegistry {
   readonly codegenable: Omit<CodegenableDecl<string>, 'kind'>;
   readonly projection: Omit<ProjectionDecl, 'kind'>;
   readonly 'strategy-contributor': Omit<StrategyContributorDecl<string, unknown>, 'kind'>;
-  readonly 'liveness-classifier': Omit<LivenessClassifierDecl, 'kind'>;
 }
 type CapabilityKind = keyof DevstackCapabilityRegistry & string;
 type RegisteredCapabilityDecl<Kind extends CapabilityKind = CapabilityKind> = { readonly [K in Kind]: Readonly<{

package/dist/contracts/codegenable.d.mts

@@ -22,6 +22,38 @@ interface CodegenEmitContext {
 interface CodegenEmitDone {
   readonly _tag: 'CodegenEmitDone';
 }
+/**
+ * Optional cross-decl aggregation. When present, the codegen
+ * orchestrator additionally folds this decl's exported map into a
+ * shared aggregate file alongside its own per-decl output.
+ *
+ * Architectural note: the orchestrator treats `bucket` as opaque and
+ * delegates the projection to the plugin via `project`. Aggregate
+ * special-casing (e.g. "the Sui `services.ts` row holds `{rpc,
+ * faucet, graphql}`") belongs in the plugin's contributor, NOT in
+ * the codegen orchestrator (architecture: "Orchestrator boundaries
+ * — never names a service").
+ */
+interface AggregateContribution {
+  /** Which aggregate file this decl contributes to (e.g.
+   *  `'accounts.ts'`, `'coins.ts'`, `'packages.ts'`,
+   *  `'services.ts'`). The plugin chooses; the orchestrator treats
+   *  it as opaque. Distinct decls that target the same `bucket`
+   *  shallow-merge into one aggregate file. */
+  readonly bucket: string;
+  /** Project this decl's `exported` map into the value to merge
+   *  into the aggregate bucket. Returning `null` opts out of
+   *  contributing for this cycle (e.g. when the emitter produced
+   *  no usable shape). The returned record is shallow-merged onto
+   *  the bucket; for typed shapes the plugin owns the merge
+   *  semantics via the returned object's key set. */
+  readonly project: (exported: Readonly<Record<string, unknown>>) => Readonly<Record<string, unknown>> | null;
+  /** Optional plugin-supplied kind tag for diagnostics / span
+   *  attributes (e.g. `'sui-network'`, `'account'`). The
+   *  orchestrator MUST NOT branch on this value — it is annotation-
+   *  only. */
+  readonly kind?: string;
+}
 /**
  * Codegen contribution. `Emitter` is a literal emitter name used
  * by the codegen orchestrator for attribution and grouping.
@@ -34,6 +66,17 @@ interface CodegenableDecl<Emitter extends string = string> {
   /** Optional sensitivity flag — drives file permissions and
    *  `.gitignore` inclusion. */
   readonly sensitive?: boolean;
+  /** When `true`, multiple decls may share this `emitterName`
+   *  (the orchestrator skips the emitter-name uniqueness check for
+   *  this decl). Use sparingly — only when the plugin legitimately
+   *  emits one decl per item (e.g. one `Package` per published
+   *  package). Output-path uniqueness is still enforced. */
+  readonly allowEmitterNameRepetition?: boolean;
+  /** Optional aggregation seam — when present, the orchestrator
+   *  folds the per-decl exported map into a shared aggregate file
+   *  via `aggregate.project(exported)`. Plugins own the projection
+   *  shape; the orchestrator is name-blind. */
+  readonly aggregate?: AggregateContribution;
   /** Emit operation; writes generated file declarations through the
    *  supplied context. */
   readonly emit: (ctx: CodegenEmitContext) => Effect.Effect<CodegenEmitDone>;

package/dist/contracts/container-runtime.d.mts

@@ -34,6 +34,16 @@ interface ContainerBuildContext {
    *  Omitted means Docker uses the host/default platform. */
   readonly platform?: string;
   readonly buildArgs?: Readonly<Record<string, string>>;
+  /** Optional owner identity. When set, the runtime stamps
+   *  `{managed:'true', app, stack, plugin?, role?}` as `--label` flags
+   *  on `docker build`, making the resulting image visible to
+   *  label-driven prune. Without it the image lands unlabelled. */
+  readonly owner?: {
+    readonly app: string;
+    readonly stack: string;
+    readonly plugin?: string;
+    readonly role?: string;
+  };
 }
 interface ContainerPortPublish {
   readonly containerPort: number;
@@ -41,6 +51,14 @@ interface ContainerPortPublish {
   readonly hostIp?: string;
 }
 type PortBindingReconciliation = 'exact' | 'adopt-existing';
+/** Per-network DNS alias plumbing. `aliases` are passed through to
+ *  Docker as `--network-alias` (first attach, baked into
+ *  `docker run`) or `--alias` (subsequent attaches via
+ *  `docker network connect`). */
+interface NetworkAttachment {
+  readonly name: string;
+  readonly aliases?: ReadonlyArray<string>;
+}
 interface EnsureContainerSpec {
   readonly name: string;
   readonly image: ImageRef;
@@ -64,7 +82,14 @@ interface EnsureContainerSpec {
    *  container keep its current published ports; callers must read
    *  the returned `ContainerHandle.ports` before constructing URLs. */
   readonly portBindingReconciliation?: PortBindingReconciliation;
-  readonly networkAttach?: ReadonlyArray<string>;
+  /** Networks to attach. Each entry is either a bare network name
+   *  (no extra DNS aliases) or `{ name, aliases }` to register
+   *  per-network DNS aliases via `docker run --network-alias` (for the
+   *  first attach) or `docker network connect --alias` (for any
+   *  subsequent attach). Docker registers the container name on every
+   *  attached network unconditionally; aliases here are *additional*
+   *  DNS names siblings can dial under the same network. */
+  readonly networkAttach?: ReadonlyArray<string | NetworkAttachment>;
   /** Bind mounts. The build-container path lives here: source dir →
    *  container path. `readonly: true` flips on the docker mount
    *  read-only flag. */

package/dist/contracts/faucet-strategy.d.mts

@@ -0,0 +1,25 @@
+import { Effect } from "effect";
+
+//#region src/contracts/faucet-strategy.d.ts
+/** Request passed to faucet strategies. `amount` is the chain-native
+ *  smallest unit (MIST for SUI). Some backends (the local sui-faucet
+ *  binary) grant a fixed amount per request and IGNORE this value;
+ *  the parameter is here for type uniformity and to land
+ *  correctly-denominated values in tagged exhaustion errors. */
+interface FaucetRequest {
+  readonly address: string;
+  readonly amount: bigint;
+}
+/** Strategy interface a contributing plugin satisfies to participate
+ *  in cross-cutting faucet dispatch for a specific chain id. Generic
+ *  over the strategy's own error channel (`E`).
+ *
+ *  The dispatch surface is uniform across strategies — the
+ *  dispatcher doesn't know how a strategy delivers coins, only how
+ *  to invoke it. */
+interface FaucetStrategy<E = unknown> {
+  readonly request: (req: FaucetRequest) => Effect.Effect<void, E>;
+}
+//#endregion
+export { FaucetStrategy };
+//# sourceMappingURL=faucet-strategy.d.mts.map

package/dist/contracts/funding-strategy.d.mts

@@ -0,0 +1,42 @@
+import { Effect } from "effect";
+
+//#region src/contracts/funding-strategy.d.ts
+/** Request passed to account funding strategies. `amount` uses the
+ *  funded coin's smallest unit. The resolved account handle (`account`)
+ *  is present so strategies without an admin signer can perform
+ *  account-owned swaps while still sharing the central funding
+ *  dispatcher. */
+interface AccountFundingRequest<A = unknown> {
+  readonly address: string;
+  readonly amount: bigint;
+  /** Resolved handle for the funded account, when one is available. Present
+   *  for the boot-time funding pass (the funded address IS a stack account) and
+   *  required by account-spending strategies (`requiresRecipientAccount`), which
+   *  swap the recipient's own SUI. Mint-style strategies that transfer to a
+   *  passive recipient ignore it, so it is optional — a caller funding an
+   *  arbitrary `0x…` recipient (e.g. the dashboard) may leave it undefined. */
+  readonly account?: A;
+}
+/** Strategy interface a contributing plugin satisfies to participate in
+ *  cross-cutting account funding for a specific coin key. Generic over
+ *  the resolved account handle (`A`) and the strategy's own error
+ *  channel (`E`). */
+interface AccountFundingStrategy<E = unknown, A = unknown> {
+  readonly request: (req: AccountFundingRequest<A>) => Effect.Effect<void, E>;
+  /** True when the strategy calls `account.withTransactionSigner`.
+   *  The dispatcher must not acquire the same non-reentrant
+   *  per-address lease outside the strategy. */
+  readonly usesAccountSigner?: boolean;
+  /** True when the strategy spends the *recipient's own* funds (an
+   *  account-owned swap — WAL/DEEP buy the coin with the recipient's SUI), so
+   *  the recipient MUST be a resolved account with a signer (`req.account`).
+   *  Distinct from `usesAccountSigner`: a mint-style strategy signs with the
+   *  publisher's account (so `usesAccountSigner` is true) yet transfers to a
+   *  *passive* recipient that need not be a stack account, leaving this false.
+   *  Callers (e.g. the dashboard fund action) gate the "recipient must be an
+   *  account" check on this flag, not on `usesAccountSigner`. */
+  readonly requiresRecipientAccount?: boolean;
+}
+//#endregion
+export { AccountFundingRequest, AccountFundingStrategy };
+//# sourceMappingURL=funding-strategy.d.mts.map