boxdown 1.2.0 → 1.3.0

package/dist/{main-Df4E8ARj.cjs → main-CT2n9qcb.cjs}

@@ -2,15 +2,16 @@ let node_fs = require("node:fs");
 let node_crypto = require("node:crypto");
 let node_os = require("node:os");
 let node_path = require("node:path");
-let node_module = require("node:module");
+let node_perf_hooks = require("node:perf_hooks");
 let node_child_process = require("node:child_process");
+let node_module = require("node:module");
 let node_readline = require("node:readline");
 let node_url = require("node:url");
 
 //#region src/claude-app-config.ts
 const CLAUDE_APP_SUPPORT_DIRNAME = "Claude";
 const CLAUDE_SSH_CONFIGS_FILENAME = "ssh_configs.json";
-function isRecord$2(value) {
+function isRecord$1(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function parseRequiredString(value, key) {
@@ -43,7 +44,7 @@ function parseStringArray(value, key) {
 	});
 }
 function parseClaudeSshConfigEntry(value) {
-	if (!isRecord$2(value)) {
+	if (!isRecord$1(value)) {
 		throw new Error("Invalid Claude SSH config: configs entries must be objects");
 	}
 	const source = parseOptionalString(value.source, "source");
@@ -61,7 +62,7 @@ function parseClaudeSshConfigEntry(value) {
 	return parsed;
 }
 function parseClaudeSshConfigs(value) {
-	if (!isRecord$2(value)) {
+	if (!isRecord$1(value)) {
 		throw new Error("Invalid Claude SSH config: top-level value must be an object");
 	}
 	const configs = value.configs;
@@ -217,7 +218,7 @@ const CODEX_APP_CONFIG_VERSION = 1;
 const CODEX_APP_CONFIG_DIRNAME = "codex-app";
 const CODEX_APP_CONFIG_FILENAME = "config.json";
 const CODEX_GLOBAL_STATE_FILENAME = ".codex-global-state.json";
-function isRecord$1(value) {
+function isRecord(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function parseOptionalNonnegativeInteger(value, key) {
@@ -239,7 +240,7 @@ function parseOptionalLabel(value) {
 	return value;
 }
 function parseProjectConfig(value) {
-	if (!isRecord$1(value)) {
+	if (!isRecord(value)) {
 		throw new Error("Invalid Codex app config: project entries must be objects");
 	}
 	const remotePath = value.remotePath;
@@ -253,7 +254,7 @@ function parseProjectConfig(value) {
 	};
 }
 function parseRemoteConnectionConfig(value) {
-	if (!isRecord$1(value)) {
+	if (!isRecord(value)) {
 		throw new Error("Invalid Codex app config: remoteConnections entries must be objects");
 	}
 	const sshAlias = value.sshAlias;
@@ -270,7 +271,7 @@ function parseRemoteConnectionConfig(value) {
 	};
 }
 function parseCodexAppConfig(value) {
-	if (!isRecord$1(value)) {
+	if (!isRecord(value)) {
 		throw new Error("Invalid Codex app config: top-level value must be an object");
 	}
 	const version = value.version;
@@ -397,7 +398,7 @@ function cloneJsonObject(value) {
 	return JSON.parse(JSON.stringify(value));
 }
 function removeObjectKey(value, key) {
-	if (isRecord$1(value)) {
+	if (isRecord(value)) {
 		delete value[key];
 	}
 }
@@ -417,7 +418,7 @@ function cleanupCodexStateContainer(container, hostId, remotePaths) {
 	const remoteProjects = container["remote-projects"];
 	if (Array.isArray(remoteProjects)) {
 		container["remote-projects"] = remoteProjects.filter((project) => {
-			if (!isRecord$1(project)) {
+			if (!isRecord(project)) {
 				return true;
 			}
 			const matches = project.hostId === hostId && typeof project.remotePath === "string" && remotePaths.has(normalizeRemotePath(project.remotePath));
@@ -429,7 +430,7 @@ function cleanupCodexStateContainer(container, hostId, remotePaths) {
 	}
 	const managedConnections = container["codex-managed-remote-connections"];
 	if (Array.isArray(managedConnections)) {
-		container["codex-managed-remote-connections"] = managedConnections.filter((connection) => !isRecord$1(connection) || connection.hostId !== hostId);
+		container["codex-managed-remote-connections"] = managedConnections.filter((connection) => !isRecord(connection) || connection.hostId !== hostId);
 	}
 	for (const key of [
 		"remote-connection-analytics-id-by-host-id",
@@ -453,7 +454,7 @@ function cleanupProjectReferences(state, atomState, removedProjectIds) {
 	for (const projectId of removedProjectIds) {
 		removeObjectKey(state["sidebar-collapsed-groups"], projectId);
 	}
-	if (isRecord$1(atomState)) {
+	if (isRecord(atomState)) {
 		cleanupStringArrayField(atomState, "project-order", removedProjectIds);
 		for (const projectId of removedProjectIds) {
 			removeObjectKey(atomState["sidebar-collapsed-groups"], projectId);
@@ -466,7 +467,7 @@ function removeCodexGlobalStateProject(state, entry, options = {}) {
 	const nextState = cloneJsonObject(state);
 	const removedProjectIds = cleanupCodexStateContainer(nextState, hostId, remotePaths);
 	const atomState = nextState["electron-persisted-atom-state"];
-	if (isRecord$1(atomState)) {
+	if (isRecord(atomState)) {
 		for (const projectId of cleanupCodexStateContainer(atomState, hostId, remotePaths)) {
 			removedProjectIds.add(projectId);
 		}
@@ -482,7 +483,7 @@ function normalizeCodexStateContainer(container, hostId, canonicalRemotePath, le
 	}
 	let matchedProject = false;
 	container["remote-projects"] = remoteProjects.flatMap((project) => {
-		if (!isRecord$1(project) || project.hostId !== hostId || typeof project.remotePath !== "string") {
+		if (!isRecord(project) || project.hostId !== hostId || typeof project.remotePath !== "string") {
 			return [project];
 		}
 		const remotePath = normalizeRemotePath(project.remotePath);
@@ -510,7 +511,7 @@ function normalizeCodexGlobalStateProject(state, entry, options = {}) {
 	const nextState = cloneJsonObject(state);
 	const removedProjectIds = normalizeCodexStateContainer(nextState, hostId, canonicalRemotePath, legacyRemotePaths);
 	const atomState = nextState["electron-persisted-atom-state"];
-	if (isRecord$1(atomState)) {
+	if (isRecord(atomState)) {
 		for (const projectId of normalizeCodexStateContainer(atomState, hostId, canonicalRemotePath, legacyRemotePaths)) {
 			removedProjectIds.add(projectId);
 		}
@@ -608,7 +609,7 @@ function uninstallCodexGlobalStateProject(entry, options = {}) {
 	}
 	const existingJson = (0, node_fs.readFileSync)(statePath, "utf8");
 	const existingState = JSON.parse(existingJson);
-	if (!isRecord$1(existingState)) {
+	if (!isRecord(existingState)) {
 		throw new Error(`Invalid Codex global state JSON: ${statePath}`);
 	}
 	const nextState = removeCodexGlobalStateProject(existingState, entry, { additionalRemotePaths: options.additionalRemotePaths });
@@ -638,7 +639,7 @@ function installCodexGlobalStateProject(entry, options = {}) {
 	}
 	const existingJson = (0, node_fs.readFileSync)(statePath, "utf8");
 	const existingState = JSON.parse(existingJson);
-	if (!isRecord$1(existingState)) {
+	if (!isRecord(existingState)) {
 		throw new Error(`Invalid Codex global state JSON: ${statePath}`);
 	}
 	const nextState = normalizeCodexGlobalStateProject(existingState, entry, { legacyRemotePaths: options.legacyRemotePaths });
@@ -691,6 +692,13 @@ const BOXDOWN_CONTAINER_AGENTS_DIR = "/home/node/.agents";
 const BOXDOWN_CONTAINER_GITCONFIG_PATH = "/home/node/.gitconfig";
 const BOXDOWN_CONTAINER_CODEX_DIR = "/home/node/.codex";
 const BOXDOWN_CONTAINER_CODEX_AUTH_PATH = `${BOXDOWN_CONTAINER_CODEX_DIR}/auth.json`;
+const BOXDOWN_CONTAINER_SECRET_ENV_DIR = "/run/boxdown/secrets";
+const BOXDOWN_CONTAINER_SECRET_ENV_BOOTSTRAP = `${BOXDOWN_CONTAINER_DEVCONTAINER_DIR}/utils/secret-env-bootstrap.sh`;
+const BOXDOWN_SECRET_ENV_NAMES = [
+	"ANTHROPIC_API_KEY",
+	"SNYK_TOKEN",
+	"OP_SERVICE_ACCOUNT_TOKEN"
+];
 const PACKAGE_NAME = "boxdown";
 
 //#endregion
@@ -844,10 +852,14 @@ function interactiveTermSetupScript() {
 function interactiveAgentPathScript() {
 	return ["codex_home=\"${CODEX_HOME:-${HOME}/.codex}\"", "export PATH=\"${HOME}/.local/bin:${HOME}/.opencode/bin:${codex_home}/packages/standalone/current/bin:${PATH}\""].join("\n");
 }
+function runtimeSecretEnvironmentScript() {
+	return "source \"${BASH_ENV:-/opt/boxdown/devcontainer/utils/secret-env-bootstrap.sh}\"";
+}
 function interactiveShellScript() {
 	return [
 		interactiveTermSetupScript(),
 		interactiveTtySetupScript(),
+		runtimeSecretEnvironmentScript(),
 		"exec bash -i"
 	].join("\n");
 }
@@ -856,6 +868,7 @@ function interactiveCommandScript() {
 		interactiveTermSetupScript(),
 		interactiveTtySetupScript(),
 		interactiveAgentPathScript(),
+		runtimeSecretEnvironmentScript(),
 		"exec \"$@\""
 	].join("\n");
 }
@@ -892,7 +905,8 @@ function buildGeneratedDevcontainerConfig(context, signing) {
 	const boxdownMounts = [
 		`type=bind,source=${context.assetsDevcontainerDir},target=${BOXDOWN_CONTAINER_DEVCONTAINER_DIR},readonly`,
 		`type=bind,source=${context.sshPublicKeyRuntimeDir},target=${BOXDOWN_CONTAINER_SSH_DIR},readonly`,
-		`type=bind,source=${context.hostGitconfigSnapshotDir},target=${BOXDOWN_CONTAINER_HOST_GITCONFIG_DIR},readonly`
+		`type=bind,source=${context.hostGitconfigSnapshotDir},target=${BOXDOWN_CONTAINER_HOST_GITCONFIG_DIR},readonly`,
+		`type=bind,source=${context.workspaceSecretEnvDir},target=${BOXDOWN_CONTAINER_SECRET_ENV_DIR},readonly`
 	];
 	if (directoryExists(context.hostAgentsDir) && !hasMountTarget(mounts, "/home/node/.agents")) {
 		boxdownMounts.push(`type=bind,source=${context.hostAgentsDir},target=${BOXDOWN_CONTAINER_AGENTS_DIR},readonly`);
@@ -912,6 +926,7 @@ function buildGeneratedDevcontainerConfig(context, signing) {
 			`BOXDOWN_WORKSPACE_FOLDER=${shellQuote(context.workspaceFolder)}`,
 			`BOXDOWN_HOST_GITCONFIG_PATH=${shellQuote(context.hostGitconfigPath)}`,
 			`BOXDOWN_HOST_GITCONFIG_SNAPSHOT_PATH=${shellQuote(context.hostGitconfigSnapshotPath)}`,
+			`BOXDOWN_SECRET_ENV_DIR=${shellQuote(context.workspaceSecretEnvDir)}`,
 			`BOXDOWN_PROGRESS=${shellQuote("${localEnv:BOXDOWN_PROGRESS}")}`,
 			`BOXDOWN_VERBOSE=${shellQuote("${localEnv:BOXDOWN_VERBOSE}")}`,
 			"bash",
@@ -933,10 +948,16 @@ function buildGeneratedDevcontainerConfig(context, signing) {
 			...baseConfig.containerEnv ?? {},
 			BOXDOWN_CONTAINER_WORKSPACE_FOLDER: "/workspaces/${localWorkspaceFolderBasename}",
 			BOXDOWN_WORKSPACE_BASENAME: "${localWorkspaceFolderBasename}",
+			BOXDOWN_SECRET_ENV_DIR: BOXDOWN_CONTAINER_SECRET_ENV_DIR,
+			BASH_ENV: BOXDOWN_CONTAINER_SECRET_ENV_BOOTSTRAP,
 			DEVCONTAINER_SSH_PUBLIC_KEY_FILE: BOXDOWN_CONTAINER_SSH_PUBLIC_KEY_PATH,
 			BOXDOWN_GIT_SIGNING_ENABLED: signing?.enabled === true ? "1" : "0",
 			BOXDOWN_GIT_SIGNING_KEY_PATH: "/opt/boxdown/state/git-signing/signing-key.pub",
-			...signing?.enabled === true ? { SSH_AUTH_SOCK: "/run/boxdown/ssh-agent.sock" } : {}
+			...signing?.enabled === false && signing.reason !== undefined ? { BOXDOWN_GIT_SIGNING_REASON: signing.reason } : {},
+			...signing?.enabled === true ? {
+				BOXDOWN_GIT_SIGNING_SOURCE_SOCKET: "/run/boxdown/ssh-agent.sock",
+				SSH_AUTH_SOCK: "/run/boxdown/ssh-agent-node.sock"
+			} : {}
 		}
 	};
 }
@@ -950,41 +971,12 @@ function publishContainerPortFromConfig(config) {
 	return config.runArgs?.find((arg) => /^[0-9.]+::[0-9]+$/.test(arg))?.split("::")[1];
 }
 
-//#endregion
-//#region src/devcontainer-cli.ts
-function devcontainerBinFromPackageJson(packageJson) {
-	return typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin?.devcontainer;
-}
-function resolveDevcontainerCli(context) {
-	const requireFromBoxdown = (0, node_module.createRequire)((0, node_path.join)(context.packageRoot, "package.json"));
-	let packageJsonPath;
-	try {
-		packageJsonPath = requireFromBoxdown.resolve("@devcontainers/cli/package.json");
-	} catch (error) {
-		throw new Error(`Boxdown's packaged @devcontainers/cli dependency is missing. Reinstall boxdown so @devcontainers/cli@${DEVCONTAINER_CLI_VERSION} is available.`, { cause: error });
-	}
-	const packageJson = JSON.parse((0, node_fs.readFileSync)(packageJsonPath, "utf8"));
-	const bin = devcontainerBinFromPackageJson(packageJson);
-	if (packageJson.version !== "0.84.1") {
-		throw new Error(`Boxdown expected @devcontainers/cli@${DEVCONTAINER_CLI_VERSION} but resolved ${packageJson.version ?? "an unknown version"}.`);
-	}
-	if (bin === undefined) {
-		throw new Error("Boxdown resolved @devcontainers/cli, but the package does not expose a devcontainer binary.");
-	}
-	const cliPath = (0, node_path.resolve)((0, node_path.dirname)(packageJsonPath), bin);
-	if (!(0, node_fs.existsSync)(cliPath)) {
-		throw new Error(`Boxdown resolved @devcontainers/cli, but its devcontainer binary is missing: ${cliPath}`);
-	}
-	return {
-		command: process.execPath,
-		argsPrefix: [cliPath],
-		path: cliPath,
-		version: packageJson.version
-	};
-}
-
 //#endregion
 //#region src/process.ts
+const realTimeoutControl = {
+	schedule: (callback, milliseconds) => setTimeout(callback, milliseconds),
+	cancel: (handle) => clearTimeout(handle)
+};
 function mergedEnv(env) {
 	const baseEnv = {
 		...process.env,
@@ -1037,6 +1029,9 @@ function writeChunk(target, chunk) {
 	}
 }
 function runBuffered(command, args, options = {}) {
+	if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) {
+		throw new Error("timeoutMs must be a finite non-negative number");
+	}
 	return new Promise((resolve) => {
 		const loggedCommand = options.logger?.startCommand(command, args, { cwd: options.cwd });
 		const child = (0, node_child_process.spawn)(command, args, {
@@ -1050,24 +1045,28 @@ function runBuffered(command, args, options = {}) {
 		});
 		const stdoutChunks = [];
 		const stderrChunks = [];
+		let settled = false;
+		let timeoutHandle;
+		let timeoutScheduled = false;
+		const timeoutControl = options.timeoutControl ?? realTimeoutControl;
 		child.stdout.on("data", (chunk) => {
+			if (settled) return;
 			stdoutChunks.push(chunk);
 			loggedCommand?.stream("stdout", chunk);
 			options.onStdout?.(chunk);
 			writeChunk(options.mirrorStdout ?? "stdout", chunk);
 		});
 		child.stderr.on("data", (chunk) => {
+			if (settled) return;
 			stderrChunks.push(chunk);
 			loggedCommand?.stream("stderr", chunk);
 			options.onStderr?.(chunk);
 			writeChunk(options.mirrorStderr ?? "stderr", chunk);
 		});
-		let resolved = false;
 		child.on("error", (error) => {
-			if (resolved) {
-				return;
-			}
-			resolved = true;
+			if (settled) return;
+			settled = true;
+			if (timeoutScheduled) timeoutControl.cancel(timeoutHandle);
 			loggedCommand?.error(error);
 			loggedCommand?.finish(127);
 			resolve({
@@ -1077,10 +1076,9 @@ function runBuffered(command, args, options = {}) {
 			});
 		});
 		child.on("close", (code) => {
-			if (resolved) {
-				return;
-			}
-			resolved = true;
+			if (settled) return;
+			settled = true;
+			if (timeoutScheduled) timeoutControl.cancel(timeoutHandle);
 			loggedCommand?.finish(code ?? 1);
 			resolve({
 				code: code ?? 1,
@@ -1088,6 +1086,25 @@ function runBuffered(command, args, options = {}) {
 				stderr: Buffer.concat(stderrChunks).toString("utf8")
 			});
 		});
+		if (options.timeoutMs !== undefined) {
+			timeoutHandle = timeoutControl.schedule(() => {
+				if (settled) return;
+				settled = true;
+				const message = `Command timed out after ${options.timeoutMs} milliseconds.`;
+				const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+				const stderr = Buffer.concat(stderrChunks).toString("utf8");
+				loggedCommand?.error(new Error(message));
+				loggedCommand?.finish(124);
+				child.kill("SIGKILL");
+				resolve({
+					code: 124,
+					stdout,
+					stderr: `${stderr}${stderr.length > 0 && !stderr.endsWith("\n") ? "\n" : ""}${message}\n`,
+					timedOut: true
+				});
+			}, options.timeoutMs);
+			timeoutScheduled = true;
+		}
 		if (options.input !== undefined) {
 			child.stdin.end(options.input);
 		} else {
@@ -1116,6 +1133,490 @@ function runInteractive(command, args, options = {}) {
 	});
 }
 
+//#endregion
+//#region src/container-runtime.ts
+const BUILDX_FALLBACK_WARNING = "Docker Buildx is unavailable; the Dev Containers CLI will use its classic-build fallback.";
+async function runContainerRuntimeCommand(command, args, timeoutMs) {
+	return runBuffered(command, args, {
+		mirrorStdout: false,
+		mirrorStderr: false,
+		timeoutMs
+	});
+}
+function compactCommandOutput(result) {
+	const output = result.stderr.trim().length > 0 ? result.stderr : result.stdout;
+	const compact = output.trim().replace(/\s+/gu, " ").slice(0, 500);
+	return compact.length > 0 ? compact : `Command exited with code ${result.code}`;
+}
+function failure(reason, command, result) {
+	return {
+		reason,
+		command,
+		detail: compactCommandOutput(result),
+		...result.timedOut === true ? { timedOut: true } : {}
+	};
+}
+async function probeContainerRuntime(runCommand = runContainerRuntimeCommand) {
+	const dockerVersionCommand = ["docker", "--version"];
+	const dockerVersion = await runCommand(dockerVersionCommand[0], dockerVersionCommand.slice(1));
+	if (dockerVersion.code !== 0) {
+		return {
+			state: "failed",
+			failure: failure("docker-cli-unavailable", dockerVersionCommand, dockerVersion)
+		};
+	}
+	const dockerInfoCommand = ["docker", "info"];
+	const dockerInfo = await runCommand(dockerInfoCommand[0], dockerInfoCommand.slice(1));
+	if (dockerInfo.code !== 0) {
+		return {
+			state: "waiting",
+			failure: failure("docker-daemon-unavailable", dockerInfoCommand, dockerInfo)
+		};
+	}
+	const buildxVersionCommand = [
+		"docker",
+		"buildx",
+		"version"
+	];
+	const buildxVersion = await runCommand(buildxVersionCommand[0], buildxVersionCommand.slice(1));
+	if (buildxVersion.timedOut === true) {
+		return {
+			state: "waiting",
+			failure: failure("buildx-builder-unavailable", buildxVersionCommand, buildxVersion)
+		};
+	}
+	if (buildxVersion.code !== 0) {
+		return {
+			state: "ready",
+			mode: "fallback",
+			warnings: [BUILDX_FALLBACK_WARNING]
+		};
+	}
+	const buildxInspectCommand = [
+		"docker",
+		"buildx",
+		"inspect",
+		"--bootstrap"
+	];
+	const buildxInspect = await runCommand(buildxInspectCommand[0], buildxInspectCommand.slice(1));
+	if (buildxInspect.code !== 0) {
+		return {
+			state: "waiting",
+			failure: failure("buildx-builder-unavailable", buildxInspectCommand, buildxInspect)
+		};
+	}
+	return {
+		state: "ready",
+		mode: "buildx",
+		warnings: []
+	};
+}
+function defaultSleep(milliseconds) {
+	return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function transitionKey(probe) {
+	return probe.state === "ready" ? "ready" : `${probe.state}:${probe.failure.reason}`;
+}
+var ContainerRuntimeDeadlineError = class extends Error {
+	command;
+	constructor(command) {
+		super(`Container runtime deadline expired before ${command.join(" ")}`);
+		this.command = command;
+	}
+};
+function deadlineFailure(command) {
+	const reason = command[1] === "info" ? "docker-daemon-unavailable" : command[1] === "buildx" ? "buildx-builder-unavailable" : "docker-cli-unavailable";
+	return {
+		reason,
+		command,
+		detail: `Readiness deadline expired before ${command.join(" ")} could start.`,
+		timedOut: true
+	};
+}
+/** @internal */
+async function waitForContainerRuntimeInternal(options = {}) {
+	const timeoutMs = options.timeoutMs ?? 6e4;
+	const pollIntervalMs = options.pollIntervalMs ?? 1e3;
+	if (!Number.isFinite(timeoutMs) || timeoutMs < 0 || timeoutMs > 6e4) {
+		throw new Error("timeoutMs must be a finite number between 0 and 60000 milliseconds");
+	}
+	if (pollIntervalMs !== 1e3) {
+		throw new Error("pollIntervalMs must be exactly 1000 milliseconds");
+	}
+	const now = options.now ?? Date.now;
+	const sleep = options.sleep ?? defaultSleep;
+	const deadline = now() + timeoutMs;
+	let lastTransition;
+	let lastWaitingFailure;
+	while (true) {
+		if (lastWaitingFailure !== undefined && deadline - now() <= 0) {
+			return {
+				state: "failed",
+				failure: lastWaitingFailure,
+				timedOut: true,
+				timeoutMs
+			};
+		}
+		const runCommand = options.runCommand ?? runContainerRuntimeCommand;
+		let lastStartedCommand;
+		let probe;
+		try {
+			probe = await probeContainerRuntime(async (command, args) => {
+				const commandArgs = [command, ...args];
+				const remainingMs = Math.floor(deadline - now());
+				if (remainingMs <= 0) throw new ContainerRuntimeDeadlineError(commandArgs);
+				lastStartedCommand = commandArgs;
+				return runCommand(command, args, remainingMs);
+			});
+		} catch (error) {
+			if (!(error instanceof ContainerRuntimeDeadlineError)) throw error;
+			return {
+				state: "failed",
+				failure: lastWaitingFailure ?? deadlineFailure(error.command),
+				timedOut: true,
+				timeoutMs
+			};
+		}
+		if (deadline - now() <= 0) {
+			const currentFailure = probe.state === "ready" ? deadlineFailure(lastStartedCommand ?? ["docker", "--version"]) : probe.failure;
+			return {
+				state: "failed",
+				failure: lastWaitingFailure ?? currentFailure,
+				timedOut: true,
+				timeoutMs
+			};
+		}
+		if (probe.state === "ready") return probe;
+		const currentTransition = transitionKey(probe);
+		if (currentTransition !== lastTransition) {
+			options.onTransition?.(probe);
+			lastTransition = currentTransition;
+		}
+		if (probe.state === "failed") {
+			return {
+				state: "failed",
+				failure: probe.failure,
+				timedOut: probe.failure.timedOut === true,
+				timeoutMs
+			};
+		}
+		lastWaitingFailure = probe.failure;
+		const remainingMs = deadline - now();
+		if (remainingMs <= 0) {
+			return {
+				state: "failed",
+				failure: probe.failure,
+				timedOut: true,
+				timeoutMs
+			};
+		}
+		await sleep(Math.min(pollIntervalMs, remainingMs));
+	}
+}
+async function waitForContainerRuntime(options = {}) {
+	return waitForContainerRuntimeInternal({
+		runCommand: options.runCommand,
+		onTransition: options.onTransition,
+		timeoutMs: 6e4,
+		pollIntervalMs: 1e3,
+		now: () => node_perf_hooks.performance.now(),
+		sleep: defaultSleep
+	});
+}
+function commandText(command) {
+	return command.join(" ");
+}
+function formatContainerRuntimeFailure(result, options = {}) {
+	const seconds = result.timeoutMs / 1e3;
+	const descriptions = {
+		"docker-cli-unavailable": "Docker CLI is required but was not available.",
+		"docker-daemon-unavailable": result.timedOut ? `Docker daemon did not become ready within ${seconds} seconds.` : "Docker daemon is required but was not reachable.",
+		"buildx-builder-unavailable": result.timedOut ? `Docker Buildx builder did not become ready within ${seconds} seconds.` : "Docker Buildx builder was not operational."
+	};
+	const manualCheck = result.failure.reason === "buildx-builder-unavailable" ? "docker buildx inspect" : result.failure.reason === "docker-daemon-unavailable" ? "docker info" : "docker --version";
+	const lines = [
+		descriptions[result.failure.reason],
+		`Last check: ${commandText(result.failure.command)}`,
+		`Detail: ${result.failure.detail}`,
+		`Check ${result.failure.reason === "buildx-builder-unavailable" ? "Buildx" : "Docker"} with: ${manualCheck}`
+	];
+	if (options.logPath !== undefined) lines.push(`Command log: ${options.logPath}`);
+	return lines.join("\n");
+}
+
+//#endregion
+//#region src/devcontainer-cli.ts
+function devcontainerBinFromPackageJson(packageJson) {
+	return typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin?.devcontainer;
+}
+function resolveDevcontainerCli(context) {
+	const requireFromBoxdown = (0, node_module.createRequire)((0, node_path.join)(context.packageRoot, "package.json"));
+	let packageJsonPath;
+	try {
+		packageJsonPath = requireFromBoxdown.resolve("@devcontainers/cli/package.json");
+	} catch (error) {
+		throw new Error(`Boxdown's packaged @devcontainers/cli dependency is missing. Reinstall boxdown so @devcontainers/cli@${DEVCONTAINER_CLI_VERSION} is available.`, { cause: error });
+	}
+	const packageJson = JSON.parse((0, node_fs.readFileSync)(packageJsonPath, "utf8"));
+	const bin = devcontainerBinFromPackageJson(packageJson);
+	if (packageJson.version !== "0.84.1") {
+		throw new Error(`Boxdown expected @devcontainers/cli@${DEVCONTAINER_CLI_VERSION} but resolved ${packageJson.version ?? "an unknown version"}.`);
+	}
+	if (bin === undefined) {
+		throw new Error("Boxdown resolved @devcontainers/cli, but the package does not expose a devcontainer binary.");
+	}
+	const cliPath = (0, node_path.resolve)((0, node_path.dirname)(packageJsonPath), bin);
+	if (!(0, node_fs.existsSync)(cliPath)) {
+		throw new Error(`Boxdown resolved @devcontainers/cli, but its devcontainer binary is missing: ${cliPath}`);
+	}
+	return {
+		command: process.execPath,
+		argsPrefix: [cliPath],
+		path: cliPath,
+		version: packageJson.version
+	};
+}
+
+//#endregion
+//#region src/git-signing.ts
+const GIT_SIGNING_REASON_MESSAGES = {
+	"agent-unavailable": "the host SSH agent is unavailable",
+	"no-identities": "the host SSH agent has no loaded identities",
+	"ambiguous-identities": "multiple SSH identities are loaded and no signing key could be selected safely",
+	"configured-key-unreadable": "the configured SSH signing-key file could not be read",
+	"configured-key-invalid": "the configured SSH signing key is not a valid public key",
+	"configured-key-not-loaded": "the configured SSH signing key is not loaded in the agent",
+	"agent-socket-unavailable": "the host SSH-agent socket is unavailable",
+	"docker-probe-image-unavailable": "no local Docker image is available to probe the SSH-agent mount",
+	"agent-mount-unavailable": "Docker could not mount the host SSH-agent socket"
+};
+function compactDiagnosticDetail(detail) {
+	return detail.trim().replace(/\s+/gu, " ").slice(0, 2e3).replace(/-----BEGIN [^-]*PRIVATE KEY-----.*?(?:-----END [^-]*PRIVATE KEY-----|$)/giu, "[redacted-private-key]").replace(/\b(?:ssh-[A-Za-z0-9-]+|ecdsa-sha2-[A-Za-z0-9-]+|sk-(?:ssh-[A-Za-z0-9-]+|ecdsa-sha2-[A-Za-z0-9-]+))\s+[A-Za-z0-9+/=]{16,}/gu, "[redacted-ssh-key]").replace(/\b(?:github_pat_|gh[pousr]_|glpat-|xox[baprs]-)[A-Za-z0-9_-]{8,}/gu, "[redacted-token]").replace(/\b(?:Bearer\s+|token[=:]\s*)[A-Za-z0-9._~+/-]{8,}/giu, "[redacted-token]").slice(0, 300);
+}
+function reportGitSigningPlan(plan, options = {}) {
+	if (plan.enabled) return;
+	const reason = plan.reason ?? "agent-unavailable";
+	const detail = plan.detail === undefined ? "" : ` detail=${compactDiagnosticDetail(plan.detail)}`;
+	options.logger?.boxdown(`git-signing: enabled=false reason=${reason}${detail}\n`);
+	if (options.quiet !== true) {
+		const writeWarning = options.writeWarning ?? ((message) => process.stderr.write(message));
+		writeWarning(`boxdown: commit signing disabled: ${GIT_SIGNING_REASON_MESSAGES[reason]}; commits will remain unsigned.\n`);
+	}
+}
+function parseSshPublicKey(value) {
+	const [algorithm, key] = value.trim().split(/\s+/, 3);
+	if (algorithm === undefined || key === undefined || !/^ssh-[A-Za-z0-9-]+$/.test(algorithm) || key.length === 0) {
+		return undefined;
+	}
+	return `${algorithm} ${key}`;
+}
+function resolveConfiguredSshSigningKey(value, options) {
+	const inlineValue = value.startsWith("key::") ? value.slice("key::".length) : value;
+	const inlineKey = parseSshPublicKey(inlineValue);
+	if (inlineKey !== undefined) {
+		return { key: inlineKey };
+	}
+	if (value.startsWith("key::")) {
+		return {
+			reason: "configured-key-invalid",
+			detail: "configured inline value is not a valid SSH public key"
+		};
+	}
+	let keyPath;
+	if (value.startsWith("~/")) {
+		if (options.homeDir === undefined) {
+			return {
+				reason: "configured-key-unreadable",
+				detail: "configured public-key file could not be read"
+			};
+		}
+		keyPath = (0, node_path.join)(options.homeDir, value.slice(2));
+	} else {
+		keyPath = (0, node_path.isAbsolute)(value) ? value : (0, node_path.resolve)(options.workspaceFolder, value);
+	}
+	let publicKeyText;
+	try {
+		publicKeyText = (0, node_fs.readFileSync)(keyPath, "utf8");
+	} catch {
+		return {
+			reason: "configured-key-unreadable",
+			detail: "configured public-key file could not be read"
+		};
+	}
+	const publicKey = parseSshPublicKey(publicKeyText.split(/\r?\n/u).find((line) => line.trim().length > 0) ?? "");
+	return publicKey === undefined ? {
+		reason: "configured-key-invalid",
+		detail: "configured public-key file does not contain a valid SSH public key"
+	} : { key: publicKey };
+}
+function selectGitSigningKey(identities, configuredKey, githubKeys) {
+	const keys = identities.map(parseSshPublicKey).filter((key) => key !== undefined);
+	if (keys.length === 0) return { reason: "no-identities" };
+	const configured = configuredKey === undefined ? undefined : parseSshPublicKey(configuredKey);
+	if (configuredKey !== undefined && configured === undefined) {
+		return { reason: "configured-key-invalid" };
+	}
+	if (configured !== undefined) {
+		return keys.includes(configured) ? { key: configured } : { reason: "configured-key-not-loaded" };
+	}
+	const github = new Set((githubKeys ?? []).map(parseSshPublicKey).filter((key) => key !== undefined));
+	const matches = keys.filter((key) => github.has(key));
+	if (matches.length === 1) return { key: matches[0] };
+	if (keys.length === 1) return { key: keys[0] };
+	return { reason: "ambiguous-identities" };
+}
+function writeGitSigningPublicKey(context, key) {
+	(0, node_fs.mkdirSync)(context.gitSigningStateDir, {
+		recursive: true,
+		mode: 448
+	});
+	(0, node_fs.writeFileSync)((0, node_path.join)(context.gitSigningStateDir, "signing-key.pub"), `${parseSshPublicKey(key) ?? key}\n`, { mode: 420 });
+}
+async function runGitSigningCommand(command, args) {
+	return runBuffered(command, args, {
+		mirrorStdout: false,
+		mirrorStderr: false
+	});
+}
+function failedCommandDetail(label, result) {
+	const stderr = compactDiagnosticDetail(result.stderr);
+	return stderr.length === 0 ? `${label} failed with exit code ${result.code}` : `${label} failed with exit code ${result.code}: ${stderr}`;
+}
+async function probeDockerAgentMount(source, runCommand) {
+	const images = await runCommand("docker", [
+		"image",
+		"ls",
+		"--format",
+		"{{.Repository}}:{{.Tag}}"
+	]);
+	const image = images.stdout.split(/\r?\n/).map((value) => value.trim()).find((value) => value.length > 0 && value !== "<none>:<none>");
+	if (images.code !== 0) {
+		return {
+			ok: false,
+			reason: "agent-mount-unavailable",
+			detail: failedCommandDetail("Docker image listing", images)
+		};
+	}
+	if (image === undefined) {
+		return {
+			ok: false,
+			reason: "docker-probe-image-unavailable",
+			detail: "no tagged local Docker image was found"
+		};
+	}
+	const created = await runCommand("docker", [
+		"create",
+		"--pull=never",
+		"--entrypoint",
+		"/bin/true",
+		"--mount",
+		`type=bind,source=${source},target=/run/boxdown/ssh-agent.sock`,
+		image
+	]);
+	const containerId = created.stdout.trim().split(/\r?\n/)[0];
+	if (created.code !== 0 || containerId === undefined || containerId.length === 0) {
+		return {
+			ok: false,
+			reason: "agent-mount-unavailable",
+			detail: failedCommandDetail("Docker SSH-agent mount probe", created)
+		};
+	}
+	await runCommand("docker", [
+		"rm",
+		"-f",
+		containerId
+	]);
+	return { ok: true };
+}
+async function resolveGitSigningPlan(context, options = {}) {
+	const runCommand = options.runCommand ?? runGitSigningCommand;
+	const result = await runCommand("ssh-add", ["-L"]);
+	if (result.code !== 0) {
+		return {
+			enabled: false,
+			reason: "agent-unavailable",
+			detail: failedCommandDetail("ssh-add -L", result)
+		};
+	}
+	const identities = result.stdout.split(/\r?\n/);
+	const format = await runCommand("git", [
+		"config",
+		"--global",
+		"--get",
+		"gpg.format"
+	]);
+	let configuredKey;
+	if (format.code === 0 && format.stdout.trim() === "ssh") {
+		const signingKey = await runCommand("git", [
+			"config",
+			"--global",
+			"--get",
+			"user.signingkey"
+		]);
+		if (signingKey.code === 0 && signingKey.stdout.trim().length > 0) {
+			const resolvedKey = resolveConfiguredSshSigningKey(signingKey.stdout.trim(), {
+				homeDir: options.env?.HOME ?? process.env.HOME,
+				workspaceFolder: context.workspaceFolder
+			});
+			if (resolvedKey.key === undefined) {
+				return {
+					enabled: false,
+					reason: resolvedKey.reason ?? "configured-key-invalid",
+					detail: resolvedKey.detail
+				};
+			}
+			configuredKey = resolvedKey.key;
+		}
+	}
+	let githubKeys;
+	if (configuredKey === undefined && identities.filter((key) => parseSshPublicKey(key) !== undefined).length > 1) {
+		const user = await runCommand("gh", [
+			"api",
+			"user",
+			"--jq",
+			".login"
+		]);
+		const login = user.stdout.trim();
+		if (user.code === 0 && login.length > 0) {
+			const github = await runCommand("gh", [
+				"api",
+				`users/${login}/keys`,
+				"--paginate",
+				"--jq",
+				".[].key"
+			]);
+			if (github.code === 0) githubKeys = github.stdout.split(/\r?\n/);
+		}
+	}
+	const selected = selectGitSigningKey(identities, configuredKey, githubKeys);
+	if (selected.key === undefined) return {
+		enabled: false,
+		reason: selected.reason
+	};
+	const agentSocketSource = (options.platform ?? process.platform) === "darwin" ? "/run/host-services/ssh-auth.sock" : options.env?.SSH_AUTH_SOCK ?? process.env.SSH_AUTH_SOCK;
+	if (agentSocketSource === undefined || agentSocketSource.length === 0) {
+		return {
+			enabled: false,
+			reason: "agent-socket-unavailable",
+			detail: "SSH_AUTH_SOCK is not set"
+		};
+	}
+	const mountProbe = await probeDockerAgentMount(agentSocketSource, runCommand);
+	if (!mountProbe.ok) {
+		return {
+			enabled: false,
+			reason: mountProbe.reason,
+			detail: mountProbe.detail
+		};
+	}
+	writeGitSigningPublicKey(context, selected.key);
+	return {
+		enabled: true,
+		publicKey: selected.key,
+		agentSocketSource
+	};
+}
+
 //#endregion
 //#region src/doctor.ts
 function nodeVersionPasses(version) {
@@ -1129,6 +1630,26 @@ function check(name, pass, okMessage, failMessage) {
 		message: pass ? okMessage : failMessage
 	};
 }
+function secretEnvironmentConfigCheck(context) {
+	let config;
+	try {
+		config = (0, node_fs.existsSync)(context.generatedConfigPath) ? JSON.parse((0, node_fs.readFileSync)(context.generatedConfigPath, "utf8")) : buildGeneratedDevcontainerConfig(context);
+	} catch {
+		return {
+			name: "secret-environment-config",
+			level: "warn",
+			message: "Generated config could not be checked for secret-safe environment handling"
+		};
+	}
+	const runArgs = Array.isArray(config.runArgs) ? config.runArgs : [];
+	const containerEnv = config.containerEnv ?? {};
+	const unsafe = runArgs.includes("--env-file") || runArgs.some((arg) => arg.includes(".env.development")) || BOXDOWN_SECRET_ENV_NAMES.some((name) => Object.hasOwn(containerEnv, name));
+	return {
+		name: "secret-environment-config",
+		level: unsafe ? "warn" : "ok",
+		message: unsafe ? "Generated config still exposes Boxdown secrets through Docker environment settings; recreate after upgrading Boxdown" : "Generated config uses runtime-mounted secrets without Docker environment values"
+	};
+}
 async function runDoctorCommand(command, args) {
 	return runBuffered(command, args, {
 		mirrorStdout: false,
@@ -1149,46 +1670,154 @@ async function runDoctorChecks(context, options = {}) {
 	const nodeVersion = process.versions.node;
 	checks.push(check("node", nodeVersionPasses(nodeVersion), `Node ${nodeVersion}`, `Node ${nodeVersion}; expected >=24.0.0`));
 	const sshAgent = await runCommand("ssh-add", ["-L"]);
-	const identities = sshAgent.code === 0 ? sshAgent.stdout.split(/\r?\n/).filter((line) => line.trim().startsWith("ssh-")).length : 0;
+	const identityLines = sshAgent.code === 0 ? sshAgent.stdout.split(/\r?\n/).filter((line) => line.trim().startsWith("ssh-")) : [];
+	const identities = identityLines.length;
+	let configuredKey;
+	let configuredFailure;
+	const format = await runCommand("git", [
+		"config",
+		"--global",
+		"--get",
+		"gpg.format"
+	]);
+	if (format.code === 0 && format.stdout.trim() === "ssh") {
+		const signingKey = await runCommand("git", [
+			"config",
+			"--global",
+			"--get",
+			"user.signingkey"
+		]);
+		if (signingKey.code === 0 && signingKey.stdout.trim().length > 0) {
+			const resolved = resolveConfiguredSshSigningKey(signingKey.stdout.trim(), {
+				homeDir: (0, node_path.dirname)(context.hostGitconfigPath),
+				workspaceFolder: context.workspaceFolder
+			});
+			if (resolved.key === undefined) {
+				configuredFailure = {
+					reason: resolved.reason ?? "configured-key-invalid",
+					detail: resolved.detail
+				};
+			} else {
+				configuredKey = resolved.key;
+			}
+		}
+	}
+	const includeOptional = options.includeOptional ?? true;
+	let ghAvailable = false;
+	let ghAuth = false;
+	let githubLogin;
+	let githubAuthKeys;
+	if (includeOptional) {
+		ghAvailable = await commandWorks(runCommand, "gh", ["--version"]);
+		if (ghAvailable) {
+			ghAuth = await commandWorks(runCommand, "gh", [
+				"auth",
+				"status",
+				"--hostname",
+				"github.com"
+			]);
+			if (ghAuth && configuredKey === undefined && configuredFailure === undefined && identities > 1) {
+				const user = await runCommand("gh", [
+					"api",
+					"user",
+					"--jq",
+					".login"
+				]);
+				githubLogin = user.code === 0 && user.stdout.trim().length > 0 ? user.stdout.trim() : undefined;
+				if (githubLogin !== undefined) {
+					const authentication = await runCommand("gh", [
+						"api",
+						`users/${githubLogin}/keys`,
+						"--paginate",
+						"--jq",
+						".[].key"
+					]);
+					if (authentication.code === 0) githubAuthKeys = authentication.stdout.split(/\r?\n/);
+				}
+			}
+		}
+	}
+	const selected = configuredFailure ?? selectGitSigningKey(identityLines, configuredKey, githubAuthKeys);
+	const selectedByConfiguration = selected.key !== undefined && configuredKey !== undefined;
+	const selectedByGithub = selected.key !== undefined && configuredKey === undefined && identities > 1;
+	const signingMessages = {
+		"agent-unavailable": "SSH agent is unavailable; Boxdown commits will remain unsigned",
+		"no-identities": "SSH agent has no identities; Boxdown commits will remain unsigned",
+		"ambiguous-identities": "SSH agent has multiple identities; Boxdown will not guess a signing key and commits will remain unsigned",
+		"configured-key-unreadable": "Configured SSH signing-key file could not be read; Boxdown commits will remain unsigned",
+		"configured-key-invalid": "Configured SSH signing key is not a valid public key; Boxdown commits will remain unsigned",
+		"configured-key-not-loaded": "Configured SSH signing key is not loaded in the agent; Boxdown commits will remain unsigned",
+		"agent-socket-unavailable": "Host SSH-agent socket is unavailable; Boxdown commits will remain unsigned",
+		"docker-probe-image-unavailable": "No local Docker image is available to probe commit-signing agent forwarding",
+		"agent-mount-unavailable": "Docker could not mount the host SSH-agent socket; Boxdown commits will remain unsigned"
+	};
 	checks.push({
 		name: "git-signing-agent",
-		level: sshAgent.code === 0 && identities === 1 ? "ok" : "warn",
-		message: sshAgent.code !== 0 ? "SSH agent is unavailable; Boxdown commits will remain unsigned" : identities === 0 ? "SSH agent has no identities; Boxdown commits will remain unsigned" : identities > 1 ? "SSH agent has multiple identities; Boxdown will not guess a signing key and commits will remain unsigned" : "One SSH agent identity is available for Boxdown commit signing"
+		level: sshAgent.code === 0 && selected.key !== undefined ? "ok" : "warn",
+		message: sshAgent.code !== 0 ? signingMessages["agent-unavailable"] : selected.key === undefined ? signingMessages[selected.reason ?? "ambiguous-identities"] : selectedByConfiguration ? "Configured SSH signing key is loaded in the agent" : selectedByGithub ? "GitHub authentication keys identify one SSH agent identity for Boxdown commit signing" : "One SSH agent identity is available for Boxdown commit signing"
 	});
 	checks.push(check("devcontainers-cli", await packagedDevcontainerCliWorks(context, runCommand), "Packaged @devcontainers/cli is available", "Packaged @devcontainers/cli is required but was not available"));
-	const dockerCliWorks = await commandWorks(runCommand, "docker", ["--version"]);
-	checks.push(check("docker-cli", dockerCliWorks, "Docker CLI is available", "Docker CLI is required but was not available"));
-	const dockerDaemonWorks = await commandWorks(runCommand, "docker", ["info"]);
-	checks.push(check("docker-daemon", dockerDaemonWorks, "Docker daemon is reachable", "Docker daemon is required but was not reachable"));
+	let dockerCliWorks = options.containerRuntimeReady === true;
+	let dockerDaemonWorks = options.containerRuntimeReady === true;
+	if (options.containerRuntimeReady !== true) {
+		const runtime = await probeContainerRuntime(runCommand);
+		dockerCliWorks = runtime.state === "ready" || runtime.failure.reason !== "docker-cli-unavailable";
+		dockerDaemonWorks = runtime.state === "ready" || runtime.state === "waiting" && runtime.failure.reason === "buildx-builder-unavailable";
+		checks.push(check("docker-cli", dockerCliWorks, "Docker CLI is available", "Docker CLI is required but was not available"));
+		checks.push(check("docker-daemon", dockerDaemonWorks, "Docker daemon is reachable", "Docker daemon is required but was not reachable"));
+		if (!dockerCliWorks || !dockerDaemonWorks) {
+			checks.push({
+				name: "docker-buildx",
+				level: "warn",
+				message: "Docker Buildx was not checked because the Docker runtime is unavailable"
+			});
+		} else if (runtime.state === "ready" && runtime.mode === "fallback") {
+			checks.push({
+				name: "docker-buildx",
+				level: "warn",
+				message: runtime.warnings[0]
+			});
+		} else if (runtime.state === "waiting") {
+			checks.push({
+				name: "docker-buildx",
+				level: "fail",
+				message: `Docker Buildx builder was not operational: ${runtime.failure.detail}`
+			});
+		} else {
+			checks.push({
+				name: "docker-buildx",
+				level: "ok",
+				message: "Docker Buildx builder is operational"
+			});
+		}
+	}
 	checks.push(check("ssh", await commandExists(runCommand, "ssh", ["-V"]), "ssh is available", "ssh is required but was not available"));
 	if (options.includeDockerMountProbe ?? true) {
 		checks.push(await checkDockerBindMounts(context, runCommand, dockerCliWorks && dockerDaemonWorks));
 	}
 	checks.push(check("ssh-keygen", await commandExists(runCommand, "ssh-keygen", ["-?"]), "ssh-keygen is available", "ssh-keygen is required but was not available"));
 	checks.push(check("assets", (0, node_fs.existsSync)(context.assetsDevcontainerDir), `Devcontainer assets found at ${context.assetsDevcontainerDir}`, `Missing Boxdown devcontainer assets: ${context.assetsDevcontainerDir}`));
-	if (options.includeOptional ?? true) {
-		if (await commandWorks(runCommand, "gh", ["--version"])) {
-			const ghAuth = await commandWorks(runCommand, "gh", [
-				"auth",
-				"status",
-				"--hostname",
-				"github.com"
-			]);
+	checks.push(secretEnvironmentConfigCheck(context));
+	if (includeOptional) {
+		if (ghAvailable) {
 			checks.push({
 				name: "gh-auth",
 				level: ghAuth ? "ok" : "warn",
 				message: ghAuth ? "GitHub CLI auth is available" : "GitHub CLI is available but not authenticated"
 			});
-			if (ghAuth && identities === 1) {
-				const user = await runCommand("gh", [
-					"api",
-					"user",
-					"--jq",
-					".login"
-				]);
-				const signing = user.code === 0 && user.stdout.trim().length > 0 ? await runCommand("gh", [
+			if (ghAuth && selected.key !== undefined) {
+				if (githubLogin === undefined) {
+					const user = await runCommand("gh", [
+						"api",
+						"user",
+						"--jq",
+						".login"
+					]);
+					githubLogin = user.code === 0 && user.stdout.trim().length > 0 ? user.stdout.trim() : undefined;
+				}
+				const signing = githubLogin !== undefined ? await runCommand("gh", [
 					"api",
-					`users/${user.stdout.trim()}/ssh_signing_keys`,
+					`users/${githubLogin}/ssh_signing_keys`,
 					"--paginate",
 					"--jq",
 					".[].key"
@@ -1197,11 +1826,10 @@ async function runDoctorChecks(context, options = {}) {
 					stdout: "",
 					stderr: ""
 				};
-				const identity = sshAgent.stdout.split(/\r?\n/).find((line) => line.trim().startsWith("ssh-"))?.trim();
 				checks.push({
 					name: "git-signing-github",
-					level: signing.code === 0 && identity !== undefined && signing.stdout.includes(identity.split(/\s+/, 3).slice(0, 2).join(" ")) ? "ok" : "warn",
-					message: signing.code !== 0 ? "GitHub SSH signing-key registration could not be checked" : signing.stdout.includes(identity?.split(/\s+/, 3).slice(0, 2).join(" ") ?? "") ? "Selected SSH key is registered with GitHub for commit signing" : "Register the selected public key with GitHub as a signing key to receive Verified badges"
+					level: signing.code === 0 && signing.stdout.includes(selected.key) ? "ok" : "warn",
+					message: signing.code !== 0 ? "GitHub SSH signing-key registration could not be checked" : signing.stdout.includes(selected.key) ? "Selected SSH key is registered with GitHub for commit signing" : "Register the selected public key with GitHub as a signing key to receive Verified badges"
 				});
 			}
 		} else {
@@ -1247,6 +1875,11 @@ async function checkDockerBindMounts(context, runCommand, dockerReady) {
 	}
 	(0, node_fs.mkdirSync)(context.workspaceDataDir, { recursive: true });
 	const runtimeProbeDir = (0, node_fs.mkdtempSync)((0, node_path.join)(context.workspaceDataDir, "doctor-mount-probe-"));
+	(0, node_fs.mkdirSync)(context.workspaceSecretEnvDir, {
+		recursive: true,
+		mode: 448
+	});
+	(0, node_fs.chmodSync)(context.workspaceSecretEnvDir, 448);
 	const sources = [
 		{
 			label: "workspace",
@@ -1259,6 +1892,10 @@ async function checkDockerBindMounts(context, runCommand, dockerReady) {
 		{
 			label: "Boxdown runtime state",
 			path: runtimeProbeDir
+		},
+		{
+			label: "Boxdown runtime secret state",
+			path: context.workspaceSecretEnvDir
 		}
 	];
 	try {
@@ -1491,147 +2128,6 @@ async function runWorkspaceGit(workspaceFolder, args) {
 	});
 }
 
-//#endregion
-//#region src/git-signing.ts
-function parseSshPublicKey(value) {
-	const [algorithm, key] = value.trim().split(/\s+/, 3);
-	if (algorithm === undefined || key === undefined || !/^ssh-[A-Za-z0-9-]+$/.test(algorithm) || key.length === 0) {
-		return undefined;
-	}
-	return `${algorithm} ${key}`;
-}
-function selectGitSigningKey(identities, configuredKey, githubKeys) {
-	const keys = identities.map(parseSshPublicKey).filter((key) => key !== undefined);
-	if (keys.length === 0) return { reason: "no-identities" };
-	const configured = configuredKey === undefined ? undefined : parseSshPublicKey(configuredKey);
-	if (configured !== undefined) {
-		return keys.includes(configured) ? { key: configured } : { reason: "configured-key-not-loaded" };
-	}
-	const github = new Set((githubKeys ?? []).map(parseSshPublicKey).filter((key) => key !== undefined));
-	const matches = keys.filter((key) => github.has(key));
-	if (matches.length === 1) return { key: matches[0] };
-	if (keys.length === 1) return { key: keys[0] };
-	return { reason: "ambiguous-identities" };
-}
-function writeGitSigningPublicKey(context, key) {
-	(0, node_fs.mkdirSync)(context.gitSigningStateDir, {
-		recursive: true,
-		mode: 448
-	});
-	(0, node_fs.writeFileSync)((0, node_path.join)(context.gitSigningStateDir, "signing-key.pub"), `${parseSshPublicKey(key) ?? key}\n`, { mode: 420 });
-}
-async function dockerCanMountAgent(source) {
-	const images = await runBuffered("docker", [
-		"image",
-		"ls",
-		"--format",
-		"{{.Repository}}:{{.Tag}}"
-	], {
-		mirrorStdout: false,
-		mirrorStderr: false
-	});
-	const image = images.stdout.split(/\r?\n/).map((value) => value.trim()).find((value) => value.length > 0 && value !== "<none>:<none>");
-	if (images.code !== 0 || image === undefined) return false;
-	const created = await runBuffered("docker", [
-		"create",
-		"--pull=never",
-		"--entrypoint",
-		"/bin/true",
-		"--mount",
-		`type=bind,source=${source},target=/run/boxdown/ssh-agent.sock`,
-		image
-	], {
-		mirrorStdout: false,
-		mirrorStderr: false
-	});
-	const containerId = created.stdout.trim().split(/\r?\n/)[0];
-	if (created.code !== 0 || containerId === undefined || containerId.length === 0) return false;
-	await runBuffered("docker", [
-		"rm",
-		"-f",
-		containerId
-	], {
-		mirrorStdout: false,
-		mirrorStderr: false
-	});
-	return true;
-}
-async function resolveGitSigningPlan(context) {
-	const result = await runBuffered("ssh-add", ["-L"], {
-		mirrorStdout: false,
-		mirrorStderr: false
-	});
-	if (result.code !== 0) return {
-		enabled: false,
-		reason: "agent-unavailable"
-	};
-	const identities = result.stdout.split(/\r?\n/);
-	const format = await runBuffered("git", [
-		"config",
-		"--global",
-		"--get",
-		"gpg.format"
-	], {
-		mirrorStdout: false,
-		mirrorStderr: false
-	});
-	const configuredKey = format.code === 0 && format.stdout.trim() === "ssh" ? (await runBuffered("git", [
-		"config",
-		"--global",
-		"--get",
-		"user.signingkey"
-	], {
-		mirrorStdout: false,
-		mirrorStderr: false
-	})).stdout.trim() : undefined;
-	let githubKeys;
-	if (identities.filter((key) => parseSshPublicKey(key) !== undefined).length > 1) {
-		const user = await runBuffered("gh", [
-			"api",
-			"user",
-			"--jq",
-			".login"
-		], {
-			mirrorStdout: false,
-			mirrorStderr: false
-		});
-		const login = user.stdout.trim();
-		if (user.code === 0 && login.length > 0) {
-			const github = await runBuffered("gh", [
-				"api",
-				`users/${login}/keys`,
-				"--paginate",
-				"--jq",
-				".[].key"
-			], {
-				mirrorStdout: false,
-				mirrorStderr: false
-			});
-			if (github.code === 0) githubKeys = github.stdout.split(/\r?\n/);
-		}
-	}
-	const selected = selectGitSigningKey(identities, configuredKey, githubKeys);
-	if (selected.key === undefined) return {
-		enabled: false,
-		reason: selected.reason
-	};
-	const agentSocketSource = process.platform === "darwin" ? "/run/host-services/ssh-auth.sock" : process.env.SSH_AUTH_SOCK;
-	if (agentSocketSource === undefined || agentSocketSource.length === 0) return {
-		enabled: false,
-		reason: "agent-mount-unavailable"
-	};
-	if (!await dockerCanMountAgent(agentSocketSource)) return {
-		enabled: false,
-		reason: "agent-mount-unavailable"
-	};
-	writeGitSigningPublicKey(context, selected.key);
-	return {
-		enabled: true,
-		publicKey: selected.key,
-		agentSocketSource
-	};
-}
-
 //#endregion
 //#region src/metadata.ts
 const WORKSPACE_METADATA_VERSION = 1;
@@ -1852,6 +2348,14 @@ var ProgressReporter = class {
 		}
 		this.#writeLine(`${promptRail()}  ${color$1(message, "dim")}`);
 	}
+	status(message) {
+		if (this.mode === "none") return;
+		if (this.mode === "verbose") {
+			this.#write(this.target, message);
+			return;
+		}
+		this.#writeInteractiveLine(`${promptRail()}  ${color$1(message, "dim")}`);
+	}
 	warn(message) {
 		if (this.mode === "none") {
 			return;
@@ -1860,7 +2364,7 @@ var ProgressReporter = class {
 			this.#write(this.target, `Warning: ${message}`);
 			return;
 		}
-		this.#writeLine(`${promptRail()}  ${color$1("!", "dim")} ${message}`);
+		this.#writeInteractiveLine(`${promptRail()}  ${color$1("!", "dim")} ${message}`);
 	}
 	marker(message) {
 		if (this.#steps.length > 0) {
@@ -1973,6 +2477,16 @@ var ProgressReporter = class {
 		}
 		this.#write(this.target, message);
 	}
+	#writeInteractiveLine(message) {
+		if (this.#isTTY && this.#renderedStepLineCount > 0) {
+			this.#writeRaw(this.target, `\u001B[${this.#renderedStepLineCount}A\r\u001B[2K`);
+			this.#write(this.target, message);
+			this.#renderedStepLineCount = 0;
+			this.#renderChecklist();
+			return;
+		}
+		this.#writeLine(message);
+	}
 	#renderSpinner() {
 		const spinner = this.#spinner;
 		if (spinner === undefined) {
@@ -2105,13 +2619,27 @@ function createMarkerSink(progress) {
 function outputWithoutProgressMarkers(output) {
 	return output.split(/\r?\n/u).filter((line) => !isProgressMarkerLine(line)).join("\n");
 }
-function tailLines(output, maxLines) {
-	return output.split(/\r?\n/u).map((line) => line.trimEnd()).filter((line) => line.trim().length > 0).slice(-maxLines);
+function outputLines(output) {
+	return output.split(/\r?\n/u).map((line) => line.trimEnd()).filter((line) => line.trim().length > 0);
+}
+function isDevcontainerErrorEnvelope(line) {
+	try {
+		const value = JSON.parse(line);
+		return value !== null && typeof value === "object" && value.outcome === "error" && typeof value.message === "string";
+	} catch {
+		return false;
+	}
 }
 function formatCommandFailure(label, result, options = {}) {
 	const maxLines = options.tailLines ?? DEFAULT_FAILURE_TAIL_LINES;
-	const stderrTail = tailLines(outputWithoutProgressMarkers(result.stderr), maxLines);
-	const stdoutTail = tailLines(outputWithoutProgressMarkers(result.stdout), Math.max(0, maxLines - stderrTail.length));
+	const stderrLines = outputLines(outputWithoutProgressMarkers(result.stderr));
+	const stderrTail = maxLines <= 0 ? [] : stderrLines.slice(-maxLines);
+	const stdoutLines = outputLines(outputWithoutProgressMarkers(result.stdout));
+	const wrapperPresent = stdoutLines.some(isDevcontainerErrorEnvelope);
+	const specificStdout = stdoutLines.filter((line) => !isDevcontainerErrorEnvelope(line));
+	const hasSpecificDiagnostic = stderrLines.length > 0 || specificStdout.length > 0;
+	const stdoutBudget = Math.max(0, maxLines - stderrTail.length);
+	const stdoutTail = stdoutBudget === 0 ? [] : specificStdout.slice(-stdoutBudget);
 	const lines = [`${label} failed with exit code ${result.code}.`, "Rerun with --verbose to see full command output."];
 	if (stderrTail.length > 0) {
 		lines.push("", "stderr tail:", ...stderrTail.map((line) => `  ${line}`));
@@ -2119,6 +2647,12 @@ function formatCommandFailure(label, result, options = {}) {
 	if (stdoutTail.length > 0) {
 		lines.push("", "stdout tail:", ...stdoutTail.map((line) => `  ${line}`));
 	}
+	if (wrapperPresent && !hasSpecificDiagnostic) {
+		lines.push("", "The Dev Containers CLI reported a nested command failure without diagnostic output.");
+	}
+	if (options.logPath !== undefined) {
+		lines.push("", `Command log: ${options.logPath}`);
+	}
 	return lines.join("\n");
 }
 async function runProgressCommand(label, command, args, options = {}) {
@@ -2163,9 +2697,9 @@ async function runProgressCommand(label, command, args, options = {}) {
 		throw error;
 	}
 }
-function assertProgressCommandSucceeded(label, result, message) {
+function assertProgressCommandSucceeded(label, result, message, options = {}) {
 	if (result.code !== 0) {
-		throw new Error(`${message}\n${formatCommandFailure(label, result)}`);
+		throw new Error(`${message}\n${formatCommandFailure(label, result, options)}`);
 	}
 }
 
@@ -2702,34 +3236,30 @@ async function findRunningContainerId(context, options = {}) {
 	}
 	return result.stdout.split(/\r?\n/).find((line) => line.length > 0);
 }
-function isRecord(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 function parseDockerInspectImage(output, containerId) {
-	const trimmed = output.trim();
-	if (trimmed.length === 0) {
+	const [rawId, rawName] = output.trim().split("|");
+	if (rawId === undefined || rawId.length === 0) {
 		return undefined;
 	}
-	let parsed;
+	let id;
+	let name;
 	try {
-		parsed = JSON.parse(trimmed);
+		id = JSON.parse(rawId);
+		name = rawName === undefined || rawName.length === 0 ? undefined : JSON.parse(rawName);
 	} catch (error) {
 		throw new Error(`Could not parse docker inspect output for ${containerId}`, { cause: error });
 	}
-	if (typeof parsed.Image !== "string" || parsed.Image.length === 0) {
-		return undefined;
-	}
-	const configImage = isRecord(parsed.Config) && typeof parsed.Config.Image === "string" && parsed.Config.Image.length > 0 ? parsed.Config.Image : undefined;
+	if (typeof id !== "string" || id.length === 0) return undefined;
 	return {
-		id: parsed.Image,
-		...configImage === undefined ? {} : { name: configImage }
+		id,
+		...typeof name === "string" && name.length > 0 ? { name } : {}
 	};
 }
 async function inspectContainerImage(containerId, options = {}) {
 	const result = await runBuffered("docker", [
 		"inspect",
 		"--format",
-		"{{json .}}",
+		"{{json .Image}}|{{json .Config.Image}}",
 		containerId
 	], {
 		logger: options.logger,
@@ -2851,7 +3381,15 @@ async function startDevcontainer(context, options = {}) {
 		progress.detail(context.generatedConfigPath);
 	}
 	try {
-		writeGeneratedDevcontainerConfig(context, await resolveGitSigningPlan(context));
+		const signingPlan = await resolveGitSigningPlan(context);
+		reportGitSigningPlan(signingPlan, {
+			logger: options.logger,
+			quiet: proxyMode,
+			...progress === undefined ? {} : { writeWarning: (message) => {
+				progress.warn(message.trimEnd());
+			} }
+		});
+		writeGeneratedDevcontainerConfig(context, signingPlan);
 		if (hasConfigStep) {
 			progress?.completeStep("devcontainer-config");
 		}
@@ -2894,7 +3432,7 @@ async function startDevcontainer(context, options = {}) {
 		mirrorStdout: proxyMode ? "stderr" : "stdout",
 		mirrorStderr: "stderr",
 		logger: options.logger
-	}) : await runProgressCommand("devcontainer up", cli.command, [...cli.argsPrefix, ...args], {
+	}) : await (options.runDevcontainerUp ?? runProgressCommand)("devcontainer up", cli.command, [...cli.argsPrefix, ...args], {
 		progress,
 		spinnerLabel: "Starting devcontainer",
 		stepId: "devcontainer-start",
@@ -2906,7 +3444,7 @@ async function startDevcontainer(context, options = {}) {
 		throw new Error(`devcontainer up failed for ${context.workspaceFolder}`);
 	}
 	if (progress !== undefined) {
-		assertProgressCommandSucceeded("devcontainer up", result, `devcontainer up failed for ${context.workspaceFolder}`);
+		assertProgressCommandSucceeded("devcontainer up", result, `devcontainer up failed for ${context.workspaceFolder}`, { logPath: options.logger?.logPath });
 	}
 	const containerId = parseContainerIdFromUpOutput(`${result.stdout}\n${result.stderr}`) ?? await findRunningContainerId(context, { logger: options.logger });
 	if (containerId === undefined) {
@@ -3004,7 +3542,7 @@ async function ensureContainerSshRuntime(context, options = {}) {
 		throw new Error("Failed to prepare devcontainer SSH runtime");
 	}
 	if (options.progress !== undefined) {
-		assertProgressCommandSucceeded("prepare SSH runtime", result, "Failed to prepare devcontainer SSH runtime");
+		assertProgressCommandSucceeded("prepare SSH runtime", result, "Failed to prepare devcontainer SSH runtime", { logPath: options.logger?.logPath });
 	}
 }
 async function refreshContainerCodingAgentClis(context, proxyMode = false, agents = [], options = {}) {
@@ -3071,7 +3609,7 @@ async function ensureContainerCodingAgentCli(context, agent, options = {}) {
 		throw new Error(`Could not install or refresh ${codingAgentBinary(agent)} inside the devcontainer`);
 	}
 	if (options.progress !== undefined) {
-		assertProgressCommandSucceeded(`prepare ${codingAgentBinary(agent)}`, result, `Could not install or refresh ${codingAgentBinary(agent)} inside the devcontainer`);
+		assertProgressCommandSucceeded(`prepare ${codingAgentBinary(agent)}`, result, `Could not install or refresh ${codingAgentBinary(agent)} inside the devcontainer`, { logPath: options.logger?.logPath });
 	}
 }
 async function runSshdProxy(containerId, options = {}) {
@@ -3137,7 +3675,14 @@ async function refreshContainerGhAuth(context, options = {}) {
 			quiet: true,
 			progress
 		});
-		writeGeneratedDevcontainerConfig(context, await resolveGitSigningPlan(context));
+		const signingPlan = await resolveGitSigningPlan(context);
+		reportGitSigningPlan(signingPlan, {
+			logger: options.logger,
+			...progress === undefined ? {} : { writeWarning: (message) => {
+				progress.warn(message.trimEnd());
+			} }
+		});
+		writeGeneratedDevcontainerConfig(context, signingPlan);
 		if (hasConfigStep) {
 			progress?.completeStep("gh-auth-config");
 		}
@@ -3859,6 +4404,9 @@ function errorMessage$1(error) {
 function argvText(command, args) {
 	return JSON.stringify([command, ...args]);
 }
+function redactKnownSecretEnvironmentAssignments(value) {
+	return value.replace(/ANTHROPIC_API_KEY=[^\s,"\]}]+/gu, "ANTHROPIC_API_KEY=[redacted]").replace(/SNYK_TOKEN=[^\s,"\]}]+/gu, "SNYK_TOKEN=[redacted]").replace(/OP_SERVICE_ACCOUNT_TOKEN=[^\s,"\]}]+/gu, "OP_SERVICE_ACCOUNT_TOKEN=[redacted]");
+}
 var WorkspaceCommandLogger = class {
 	logPath;
 	workspaceFolder;
@@ -3909,7 +4457,7 @@ var WorkspaceCommandLogger = class {
 		return `[${this.#now().toISOString()}]`;
 	}
 	#redact(value) {
-		return this.#redactions.reduce((current, redaction) => current.replaceAll(redaction, "[redacted]"), value);
+		return this.#redactions.reduce((current, redaction) => current.replaceAll(redaction, "[redacted]"), redactKnownSecretEnvironmentAssignments(value));
 	}
 	#stream(stream, chunk) {
 		const text = this.#redact(Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk);
@@ -3992,6 +4540,15 @@ function defaultDataRoot(env = process.env) {
 	}
 	return (0, node_path.join)((0, node_os.homedir)(), ".local", "share", PACKAGE_NAME);
 }
+function defaultRuntimeRoot(env = process.env) {
+	if (env.BOXDOWN_RUNTIME_HOME) {
+		return env.BOXDOWN_RUNTIME_HOME;
+	}
+	if (env.XDG_RUNTIME_DIR) {
+		return (0, node_path.join)(env.XDG_RUNTIME_DIR, PACKAGE_NAME);
+	}
+	return (0, node_path.join)((0, node_os.tmpdir)(), `${PACKAGE_NAME}-${process.getuid?.() ?? "user"}`);
+}
 function defaultHostAgentsDir(env = process.env) {
 	return (0, node_path.join)(env.HOME ?? (0, node_os.homedir)(), ".agents");
 }
@@ -4007,10 +4564,12 @@ function createWorkspaceContextFromIdentity(identity, options = {}) {
 	const assetsDevcontainerDir = options.assetsDevcontainerDir ?? env.BOXDOWN_DEVCONTAINER_ASSETS_DIR ?? (0, node_path.join)(packageRoot, "assets", "devcontainer");
 	const cacheRoot = defaultCacheRoot(env);
 	const dataRoot = defaultDataRoot(env);
+	const runtimeRoot = defaultRuntimeRoot(env);
 	const hostAgentsDir = defaultHostAgentsDir(env);
 	const hostCodexAuthPath = defaultHostCodexAuthPath(env);
 	const workspaceCacheDir = (0, node_path.join)(cacheRoot, "workspaces", identity.workspaceId);
 	const workspaceDataDir = (0, node_path.join)(dataRoot, "workspaces", identity.workspaceId);
+	const workspaceRuntimeDir = (0, node_path.join)(runtimeRoot, "workspaces", identity.workspaceId);
 	const hostGitconfigSnapshotDir = (0, node_path.join)(workspaceDataDir, "gitconfig");
 	return {
 		workspaceFolder: identity.workspaceFolder,
@@ -4020,8 +4579,11 @@ function createWorkspaceContextFromIdentity(identity, options = {}) {
 		assetsDevcontainerDir,
 		cacheRoot,
 		dataRoot,
+		runtimeRoot,
 		workspaceCacheDir,
 		workspaceDataDir,
+		workspaceRuntimeDir,
+		workspaceSecretEnvDir: (0, node_path.join)(workspaceRuntimeDir, "secrets"),
 		generatedConfigPath: (0, node_path.join)(workspaceCacheDir, "devcontainer.json"),
 		hostAgentsDir,
 		hostCodexAuthPath,
@@ -4110,6 +4672,9 @@ function removeWorkspaceStateDir(context, label, path, root) {
 	});
 	process.stdout.write(`Removed ${label}: ${path}\n`);
 }
+function removeWorkspaceRuntimeState(context) {
+	removeWorkspaceStateDir(context, "workspace runtime directory", context.workspaceRuntimeDir, context.runtimeRoot);
+}
 async function purgeAliasIntegrations(context, alias) {
 	let failed = false;
 	failed = await runPurgeStep(`SSH alias ${alias}`, () => {
@@ -4186,6 +4751,9 @@ async function purgeWorkspace(context, options = {}) {
 			await removeDockerImage(removedImageId, { logger: options.logger });
 		}) || failed;
 	}
+	failed = await runPurgeStep("workspace runtime directory", () => {
+		removeWorkspaceRuntimeState(context);
+	}) || failed;
 	failed = await runPurgeStep("workspace cache directory", () => {
 		removeWorkspaceStateDir(context, "workspace cache", context.workspaceCacheDir, context.cacheRoot);
 	}) || failed;
@@ -4354,10 +4922,12 @@ function commandWritesWorkspaceMetadata(command) {
 		"ssh-proxy",
 		"tunnel",
 		"refresh-gh-token",
-		"refresh-gh-token-running",
 		"coding-agent"
 	].includes(command);
 }
+function commandRequiresContainerRuntime(command) {
+	return command === "setup" || command === "start" || command === "ssh-proxy" || command === "tunnel" || command === "refresh-gh-token" || command === "coding-agent";
+}
 function parseCliArgs(argv) {
 	const args = [...argv];
 	const workspaces = [];
@@ -4891,6 +5461,7 @@ async function runDownCommand(workspaces, options) {
 			const context = createWorkspaceContext({ workspace });
 			await runLoggedLifecycle(context, "down", ["down", ...workspace === undefined ? [] : ["--workspace", workspace]], async (logger) => {
 				await removeWorkspaceContainer(context, { logger });
+				removeWorkspaceRuntimeState(context);
 			});
 		} catch (error) {
 			failed = true;
@@ -5052,7 +5623,7 @@ function createCliProgress(parsed, target = "stdout", options = {}) {
 		target
 	});
 }
-function startProgressSteps() {
+function devcontainerStartProgressSteps() {
 	return [
 		{
 			id: "ssh-identity",
@@ -5068,13 +5639,19 @@ function startProgressSteps() {
 		}
 	];
 }
+function startProgressSteps() {
+	return [{
+		id: "container-runtime",
+		label: "Checking container runtime"
+	}, ...devcontainerStartProgressSteps()];
+}
 function sshTargetProgressLabel(target) {
 	const label = SSH_INSTALL_TARGETS.find((candidate) => candidate.value === target)?.label ?? target;
 	return `Installing ${label} SSH target`;
 }
 function setupProgressSteps(targets) {
 	return [
-		...startProgressSteps(),
+		...devcontainerStartProgressSteps(),
 		{
 			id: "ssh-alias",
 			label: "Installing SSH alias"
@@ -5087,6 +5664,9 @@ function setupProgressSteps(targets) {
 }
 function setupPreflightProgressSteps() {
 	return [{
+		id: "container-runtime",
+		label: "Checking container runtime"
+	}, {
 		id: "setup-preflight",
 		label: "Checking host readiness"
 	}];
@@ -5095,13 +5675,55 @@ function setupPreflightFailureMessage(checks) {
 	const failures = checks.filter((check) => check.level === "fail").map((check) => `- ${check.name}: ${check.message}`);
 	return `Setup preflight failed:\n${failures.join("\n")}`;
 }
+function runtimeTransitionMessage(probe) {
+	if (probe.state === "waiting" && probe.failure.reason === "docker-daemon-unavailable") {
+		return "Waiting for Docker daemon";
+	}
+	if (probe.state === "waiting" && probe.failure.reason === "buildx-builder-unavailable") {
+		return "Waiting for Docker Buildx builder";
+	}
+	return undefined;
+}
+async function runContainerRuntimePreflight(context, progress, options, logger) {
+	const wait = options.waitForContainerRuntime ?? waitForContainerRuntime;
+	progress.startStep("container-runtime");
+	const result = await wait({
+		runCommand: async (command, args, timeoutMs) => runBuffered(command, args, {
+			env: options.env,
+			logger,
+			mirrorStdout: false,
+			mirrorStderr: false,
+			timeoutMs
+		}),
+		onTransition: (probe) => {
+			const message = runtimeTransitionMessage(probe);
+			if (message !== undefined) progress.status(message);
+		}
+	});
+	if (result.state === "failed") {
+		progress.failStep("container-runtime");
+		throw new Error(formatContainerRuntimeFailure(result, { logPath: logger === undefined ? undefined : context.workspaceLogPath }));
+	}
+	for (const warning of result.warnings) progress.warn(warning);
+	if (progress.mode === "verbose") progress.status("Container runtime ready");
+	progress.completeStep("container-runtime");
+}
+async function prepareContainerLifecycle(context, alias, progress, options, logger) {
+	await runContainerRuntimePreflight(context, progress, options, logger);
+	const writeMetadata = options.writeWorkspaceMetadata ?? writeWorkspaceMetadata;
+	writeMetadata(context, alias);
+}
 async function runSetupPreflight(context, alias, parsed, options) {
 	const progress = createCliProgress(parsed, "stdout", { env: options.env });
 	const doctor = options.runDoctorChecks ?? runDoctorChecks;
 	await withProgressSection(progress, "Boxdown setup", [`Workspace: ${context.workspaceFolder}`, `SSH alias: ${alias}`], async () => {
 		progress.setSteps(setupPreflightProgressSteps());
+		await runContainerRuntimePreflight(context, progress, options);
 		progress.startStep("setup-preflight");
-		const checks = await doctor(context, { includeOptional: false });
+		const checks = await doctor(context, {
+			includeOptional: false,
+			containerRuntimeReady: true
+		});
 		for (const check of checks.filter((item) => item.level === "warn")) {
 			progress.warn(`${check.name}: ${check.message}`);
 		}
@@ -5213,9 +5835,6 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 		const context = createWorkspaceContext({ workspace: parsed.workspace });
 		const alias = parsed.alias ?? defaultSshAlias(context.workspaceBasename);
 		const aliasSource = parsed.alias === undefined ? "default" : "provided";
-		if (parsed.command !== "ssh-install" && parsed.command !== "setup" && parsed.command !== "tunnel" && commandWritesWorkspaceMetadata(parsed.command)) {
-			writeWorkspaceMetadata(context, alias);
-		}
 		if (parsed.command === "ssh-install") {
 			const resolvedTargets = await resolveSshInstallTargets(parsed, options);
 			if (resolvedTargets.cancelled) {
@@ -5312,6 +5931,7 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 				const progress = createCliProgress(parsed, "stderr", { env: options.env });
 				const containerId = await withProgressSection(progress, "Boxdown SSH proxy", [`Workspace: ${context.workspaceFolder}`, `SSH alias: ${alias}`], async () => {
 					progress.setSteps(sshProxyProgressSteps());
+					await (options.prepareContainerLifecycle ?? prepareContainerLifecycle)(context, alias, progress, options, logger);
 					progress.startStep("ssh-alias");
 					try {
 						await installSshConfig(context, alias, { quiet: true });
@@ -5350,11 +5970,11 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 			if (tunnelPorts.length === 0) {
 				throw new Error("tunnel requires at least one --port value");
 			}
-			writeWorkspaceMetadata(context, alias);
 			return runLoggedLifecycle(context, "tunnel", argv, async (logger) => {
 				const progress = createCliProgress(parsed, "stdout", { env: options.env });
 				await withProgressSection(progress, "Boxdown tunnel", [`Workspace: ${context.workspaceFolder}`, `SSH alias: ${alias}`], async () => {
 					progress.setSteps(tunnelProgressSteps());
+					await (options.prepareContainerLifecycle ?? prepareContainerLifecycle)(context, alias, progress, options, logger);
 					progress.startStep("ssh-alias");
 					try {
 						await installSshConfig(context, alias, { quiet: true });
@@ -5378,7 +5998,7 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 		}
 		if (parsed.command === "refresh-gh-token-running") {
 			return runLoggedLifecycle(context, "refresh-gh-token-running", argv, async (logger) => {
-				const containerId = await findRunningContainerId(context, { logger });
+				const containerId = await (options.findRunningContainerId ?? findRunningContainerId)(context, { logger });
 				if (containerId === undefined) {
 					throw new Error(`No running devcontainer found for: ${context.workspaceFolder}`);
 				}
@@ -5400,6 +6020,7 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 				const progress = createCliProgress(parsed, "stdout", { env: options.env });
 				await withProgressSection(progress, "Boxdown GitHub auth refresh", [`Workspace: ${context.workspaceFolder}`], async () => {
 					progress.setSteps(ghAuthProgressSteps(true));
+					await (options.prepareContainerLifecycle ?? prepareContainerLifecycle)(context, alias, progress, options, logger);
 					await startDevcontainer(context, {
 						progress,
 						logger
@@ -5421,6 +6042,7 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 				const progress = createCliProgress(parsed, "stdout", { env: options.env });
 				await withProgressSection(progress, `Boxdown ${agent}`, [`Workspace: ${context.workspaceFolder}`], async () => {
 					progress.setSteps(codingAgentProgressSteps(agent));
+					await (options.prepareContainerLifecycle ?? prepareContainerLifecycle)(context, alias, progress, options, logger);
 					await startDevcontainer(context, {
 						recreate: parsed.recreate,
 						progress,
@@ -5438,6 +6060,7 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 			const progress = createCliProgress(parsed, "stdout", { env: options.env });
 			const containerId = await withProgressSection(progress, "Boxdown start", [`Workspace: ${context.workspaceFolder}`], async () => {
 				progress.setSteps(startProgressSteps());
+				await (options.prepareContainerLifecycle ?? prepareContainerLifecycle)(context, alias, progress, options, logger);
 				return await startDevcontainer(context, {
 					recreate: parsed.recreate,
 					progress,
@@ -5460,6 +6083,12 @@ Object.defineProperty(exports, 'USAGE', {
     return USAGE;
   }
 });
+Object.defineProperty(exports, 'commandRequiresContainerRuntime', {
+  enumerable: true,
+  get: function () {
+    return commandRequiresContainerRuntime;
+  }
+});
 Object.defineProperty(exports, 'commandWritesWorkspaceMetadata', {
   enumerable: true,
   get: function () {
@@ -5484,12 +6113,24 @@ Object.defineProperty(exports, 'parseTunnelPortList', {
     return parseTunnelPortList;
   }
 });
+Object.defineProperty(exports, 'prepareContainerLifecycle', {
+  enumerable: true,
+  get: function () {
+    return prepareContainerLifecycle;
+  }
+});
 Object.defineProperty(exports, 'runCli', {
   enumerable: true,
   get: function () {
     return runCli;
   }
 });
+Object.defineProperty(exports, 'runContainerRuntimePreflight', {
+  enumerable: true,
+  get: function () {
+    return runContainerRuntimePreflight;
+  }
+});
 Object.defineProperty(exports, 'setupWorkspace', {
   enumerable: true,
   get: function () {