boxdown 1.2.1 → 1.3.0

package/src/container-runtime.ts

@@ -0,0 +1,295 @@
+import { performance } from 'node:perf_hooks'
+
+import { runBuffered, type CommandResult } from './process.ts'
+
+export type ContainerRuntimeReason =
+  | 'docker-cli-unavailable'
+  | 'docker-daemon-unavailable'
+  | 'buildx-builder-unavailable'
+
+export type ContainerRuntimeMode = 'buildx' | 'fallback'
+export type ContainerRuntimeCommandResult = CommandResult
+export type ContainerRuntimeCommandRunner = (
+  command: string,
+  args: string[],
+  timeoutMs?: number
+) => Promise<ContainerRuntimeCommandResult>
+
+export interface ContainerRuntimeFailure {
+  reason: ContainerRuntimeReason
+  command: string[]
+  detail: string
+  timedOut?: true
+}
+
+export type ContainerRuntimeProbe =
+  | { state: 'ready', mode: ContainerRuntimeMode, warnings: string[] }
+  | { state: 'waiting', failure: ContainerRuntimeFailure }
+  | { state: 'failed', failure: ContainerRuntimeFailure }
+
+const BUILDX_FALLBACK_WARNING = 'Docker Buildx is unavailable; the Dev Containers CLI will use its classic-build fallback.'
+
+async function runContainerRuntimeCommand (
+  command: string,
+  args: string[],
+  timeoutMs?: number
+): Promise<ContainerRuntimeCommandResult> {
+  return runBuffered(command, args, {
+    mirrorStdout: false,
+    mirrorStderr: false,
+    timeoutMs
+  })
+}
+
+function compactCommandOutput (result: ContainerRuntimeCommandResult): string {
+  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: ContainerRuntimeReason,
+  command: string[],
+  result: ContainerRuntimeCommandResult
+): ContainerRuntimeFailure {
+  return {
+    reason,
+    command,
+    detail: compactCommandOutput(result),
+    ...(result.timedOut === true ? { timedOut: true as const } : {})
+  }
+}
+
+export async function probeContainerRuntime (
+  runCommand: ContainerRuntimeCommandRunner = runContainerRuntimeCommand
+): Promise<ContainerRuntimeProbe> {
+  const dockerVersionCommand = ['docker', '--version']
+  const dockerVersion = await runCommand(dockerVersionCommand[0] as string, 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] as string, 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] as string, 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] as string, buildxInspectCommand.slice(1))
+  if (buildxInspect.code !== 0) {
+    return {
+      state: 'waiting',
+      failure: failure('buildx-builder-unavailable', buildxInspectCommand, buildxInspect)
+    }
+  }
+
+  return { state: 'ready', mode: 'buildx', warnings: [] }
+}
+
+export type ContainerRuntimeWaitResult =
+  | { state: 'ready', mode: ContainerRuntimeMode, warnings: string[] }
+  | {
+      state: 'failed'
+      failure: ContainerRuntimeFailure
+      timedOut: boolean
+      timeoutMs: number
+    }
+
+export interface WaitForContainerRuntimeOptions {
+  runCommand?: ContainerRuntimeCommandRunner
+  onTransition?: (probe: ContainerRuntimeProbe) => void
+}
+
+/** @internal */
+export interface InternalContainerRuntimeWaitOptions extends WaitForContainerRuntimeOptions {
+  timeoutMs?: number
+  pollIntervalMs?: number
+  now?: () => number
+  sleep?: (milliseconds: number) => Promise<void>
+}
+
+function defaultSleep (milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds))
+}
+
+function transitionKey (probe: ContainerRuntimeProbe): string {
+  return probe.state === 'ready' ? 'ready' : `${probe.state}:${probe.failure.reason}`
+}
+
+class ContainerRuntimeDeadlineError extends Error {
+  readonly command: string[]
+
+  constructor (command: string[]) {
+    super(`Container runtime deadline expired before ${command.join(' ')}`)
+    this.command = command
+  }
+}
+
+function deadlineFailure (command: string[]): ContainerRuntimeFailure {
+  const reason: ContainerRuntimeReason = 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 */
+export async function waitForContainerRuntimeInternal (
+  options: InternalContainerRuntimeWaitOptions = {}
+): Promise<ContainerRuntimeWaitResult> {
+  const timeoutMs = options.timeoutMs ?? 60_000
+  const pollIntervalMs = options.pollIntervalMs ?? 1_000
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0 || timeoutMs > 60_000) {
+    throw new Error('timeoutMs must be a finite number between 0 and 60000 milliseconds')
+  }
+  if (pollIntervalMs !== 1_000) {
+    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: string | undefined
+  let lastWaitingFailure: ContainerRuntimeFailure | undefined
+
+  while (true) {
+    if (lastWaitingFailure !== undefined && deadline - now() <= 0) {
+      return { state: 'failed', failure: lastWaitingFailure, timedOut: true, timeoutMs }
+    }
+
+    const runCommand = options.runCommand ?? runContainerRuntimeCommand
+    let lastStartedCommand: string[] | undefined
+    let probe: ContainerRuntimeProbe
+    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))
+  }
+}
+
+export async function waitForContainerRuntime (
+  options: WaitForContainerRuntimeOptions = {}
+): Promise<ContainerRuntimeWaitResult> {
+  return waitForContainerRuntimeInternal({
+    runCommand: options.runCommand,
+    onTransition: options.onTransition,
+    timeoutMs: 60_000,
+    pollIntervalMs: 1_000,
+    now: () => performance.now(),
+    sleep: defaultSleep
+  })
+}
+
+function commandText (command: readonly string[]): string {
+  return command.join(' ')
+}
+
+export function formatContainerRuntimeFailure (
+  result: Extract<ContainerRuntimeWaitResult, { state: 'failed' }>,
+  options: { logPath?: string } = {}
+): string {
+  const seconds = result.timeoutMs / 1_000
+  const descriptions: Record<ContainerRuntimeReason, string> = {
+    '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')
+}

package/src/devcontainer.ts

@@ -21,6 +21,7 @@ export interface StartOptions {
   progress?: ProgressReporter
   logger?: WorkspaceCommandLogger
   reuseRunning?: boolean
+  runDevcontainerUp?: typeof runProgressCommand
 }
 
 export interface ContainerCommandOptions {
@@ -374,7 +375,7 @@ export async function startDevcontainer (context: WorkspaceContext, options: Sta
         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',
@@ -388,7 +389,12 @@ export async function startDevcontainer (context: WorkspaceContext, options: Sta
   }
 
   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 })
@@ -503,7 +509,12 @@ export async function ensureContainerSshRuntime (context: WorkspaceContext, opti
   }
 
   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 }
+    )
   }
 }
 
@@ -590,7 +601,12 @@ export async function ensureContainerCodingAgentCli (
   }
 
   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 }
+    )
   }
 }
 

package/src/doctor.ts

@@ -1,6 +1,11 @@
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 
+import {
+  probeContainerRuntime,
+  type ContainerRuntimeCommandResult,
+  type ContainerRuntimeCommandRunner
+} from './container-runtime.ts'
 import { resolveDevcontainerCli } from './devcontainer-cli.ts'
 import { buildGeneratedDevcontainerConfig, type DevcontainerConfig } from './config.ts'
 import { BOXDOWN_SECRET_ENV_NAMES } from './constants.ts'
@@ -16,17 +21,13 @@ export interface DoctorCheck {
   message: string
 }
 
-export interface DoctorCommandResult {
-  code: number
-  stdout: string
-  stderr: string
-}
-
-export type DoctorCommandRunner = (command: string, args: string[]) => Promise<DoctorCommandResult>
+export type DoctorCommandResult = ContainerRuntimeCommandResult
+export type DoctorCommandRunner = ContainerRuntimeCommandRunner
 
 export interface RunDoctorChecksOptions {
   includeOptional?: boolean
   includeDockerMountProbe?: boolean
+  containerRuntimeReady?: boolean
   runCommand?: DoctorCommandRunner
 }
 
@@ -183,21 +184,46 @@ export async function runDoctorChecks (context: WorkspaceContext, options: RunDo
     '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] as string })
+    } 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',

package/src/main.ts

@@ -4,6 +4,7 @@ import { claudeSshConfigEntryForWorkspace, uninstallClaudeSshConfigHost } from '
 import { codexProjectEntryForWorkspace, legacyCodexRemotePathForWorkspace, uninstallCodexAppConfigProject, uninstallCodexGlobalStateProject } from './codex-app-config.ts'
 import { codingAgentBinary, codingAgentFromCommand, type CodingAgentCli } from './coding-agents.ts'
 import { buildGeneratedDevcontainerConfig, publishContainerPortFromConfig } from './config.ts'
+import { formatContainerRuntimeFailure, waitForContainerRuntime, type ContainerRuntimeProbe } from './container-runtime.ts'
 import { doctorHasFailures, formatDoctorText, runDoctorChecks, type DoctorCheck } from './doctor.ts'
 import { startDevcontainer, printPortHint, openShell, openCodingAgentCli, ensureContainerSshRuntime, runSshdProxy, refreshContainerGhAuth, refreshContainerCodingAgentClis, ensureContainerCodingAgentCli, findRunningContainerId, findWorkspaceContainer, stopWorkspaceContainer, removeWorkspaceContainer, listWorkspaceContainers, openSshTunnel, type TunnelPortForward } from './devcontainer.ts'
 import { canPromptInteractively, promptConfirm, promptMultiSelect, promptText, type PromptInput, type PromptOutput } from './interactive-prompts.ts'
@@ -13,6 +14,7 @@ import { listWorkspaceMetadata, readWorkspaceMetadata, writeWorkspaceMetadata, t
 import { readPackageVersion } from './package-info.ts'
 import { createWorkspaceContext, createWorkspaceContextFromIdentity, defaultDataRoot, type WorkspaceContext } from './paths.ts'
 import { createProgress, resolveProgressMode, type ProgressReporter, type ProgressOutputTarget, type ProgressStepDefinition } from './progress.ts'
+import { runBuffered } from './process.ts'
 import { purgeWorkspace, removeWorkspaceRuntimeState } from './purge.ts'
 import { defaultSshAlias, installSshConfig, uninstallSshConfig } from './ssh-config.ts'
 import { dedupeSshInstallTargets, installSshInstallTarget, isSshConfigInstallTarget, SSH_INSTALL_TARGETS, sshInstallTargetFlagHintsText, supportedSshInstallTargetsText, type SshConfigInstallTarget } from './ssh-install-targets.ts'
@@ -59,6 +61,10 @@ export interface RunCliOptions {
   env?: NodeJS.ProcessEnv
   runDoctorChecks?: typeof runDoctorChecks
   setupWorkspace?: typeof setupWorkspace
+  waitForContainerRuntime?: typeof waitForContainerRuntime
+  writeWorkspaceMetadata?: (context: WorkspaceContext, alias: string) => void
+  prepareContainerLifecycle?: typeof prepareContainerLifecycle
+  findRunningContainerId?: typeof findRunningContainerId
 }
 
 export const USAGE = `Usage:
@@ -151,11 +157,19 @@ export function commandWritesWorkspaceMetadata (command: BoxdownCommand): boolea
     'ssh-proxy',
     'tunnel',
     'refresh-gh-token',
-    'refresh-gh-token-running',
     'coding-agent'
   ].includes(command)
 }
 
+export function commandRequiresContainerRuntime (command: BoxdownCommand): boolean {
+  return command === 'setup' ||
+    command === 'start' ||
+    command === 'ssh-proxy' ||
+    command === 'tunnel' ||
+    command === 'refresh-gh-token' ||
+    command === 'coding-agent'
+}
+
 export function parseCliArgs (argv: string[]): ParsedCli {
   const args = [...argv]
   const workspaces: string[] = []
@@ -1057,7 +1071,7 @@ function createCliProgress (
   })
 }
 
-function startProgressSteps (): ProgressStepDefinition[] {
+function devcontainerStartProgressSteps (): ProgressStepDefinition[] {
   return [
     { id: 'ssh-identity', label: 'Preparing SSH identity' },
     { id: 'devcontainer-config', label: 'Writing generated devcontainer config' },
@@ -1065,6 +1079,13 @@ function startProgressSteps (): ProgressStepDefinition[] {
   ]
 }
 
+function startProgressSteps (): ProgressStepDefinition[] {
+  return [
+    { id: 'container-runtime', label: 'Checking container runtime' },
+    ...devcontainerStartProgressSteps()
+  ]
+}
+
 function sshTargetProgressLabel (target: SshConfigInstallTarget): string {
   const label = SSH_INSTALL_TARGETS.find((candidate) => candidate.value === target)?.label ?? target
   return `Installing ${label} SSH target`
@@ -1072,7 +1093,7 @@ function sshTargetProgressLabel (target: SshConfigInstallTarget): string {
 
 function setupProgressSteps (targets: readonly SshConfigInstallTarget[]): ProgressStepDefinition[] {
   return [
-    ...startProgressSteps(),
+    ...devcontainerStartProgressSteps(),
     { id: 'ssh-alias', label: 'Installing SSH alias' },
     ...targets.map((target) => ({
       id: `ssh-target:${target}`,
@@ -1082,7 +1103,10 @@ function setupProgressSteps (targets: readonly SshConfigInstallTarget[]): Progre
 }
 
 function setupPreflightProgressSteps (): ProgressStepDefinition[] {
-  return [{ id: 'setup-preflight', label: 'Checking host readiness' }]
+  return [
+    { id: 'container-runtime', label: 'Checking container runtime' },
+    { id: 'setup-preflight', label: 'Checking host readiness' }
+  ]
 }
 
 function setupPreflightFailureMessage (checks: DoctorCheck[]): string {
@@ -1093,6 +1117,62 @@ function setupPreflightFailureMessage (checks: DoctorCheck[]): string {
   return `Setup preflight failed:\n${failures.join('\n')}`
 }
 
+function runtimeTransitionMessage (probe: ContainerRuntimeProbe): string | undefined {
+  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
+}
+
+export async function runContainerRuntimePreflight (
+  context: WorkspaceContext,
+  progress: ProgressReporter,
+  options: RunCliOptions,
+  logger?: WorkspaceCommandLogger
+): Promise<void> {
+  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')
+}
+
+export async function prepareContainerLifecycle (
+  context: WorkspaceContext,
+  alias: string,
+  progress: ProgressReporter,
+  options: RunCliOptions,
+  logger?: WorkspaceCommandLogger
+): Promise<void> {
+  await runContainerRuntimePreflight(context, progress, options, logger)
+  const writeMetadata = options.writeWorkspaceMetadata ?? writeWorkspaceMetadata
+  writeMetadata(context, alias)
+}
+
 async function runSetupPreflight (
   context: WorkspaceContext,
   alias: string,
@@ -1107,8 +1187,12 @@ async function runSetupPreflight (
     `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}`)
@@ -1221,10 +1305,6 @@ export async function runCli (argv: string[] = process.argv.slice(2), options: R
     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)
 
@@ -1364,6 +1444,7 @@ export async function runCli (argv: string[] = process.argv.slice(2), options: R
           `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 })
@@ -1400,7 +1481,6 @@ export async function runCli (argv: string[] = process.argv.slice(2), options: R
         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', [
@@ -1408,6 +1488,7 @@ export async function runCli (argv: string[] = process.argv.slice(2), options: R
           `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 })
@@ -1437,7 +1518,7 @@ export async function runCli (argv: string[] = process.argv.slice(2), options: R
 
     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}`)
         }
@@ -1461,6 +1542,7 @@ export async function runCli (argv: string[] = process.argv.slice(2), options: R
           `Workspace: ${context.workspaceFolder}`
         ], async () => {
           progress.setSteps(ghAuthProgressSteps(true))
+          await (options.prepareContainerLifecycle ?? prepareContainerLifecycle)(context, alias, progress, options, logger)
           await startDevcontainer(context, { progress, logger })
           await refreshContainerGhAuth(context, { progress, logger })
         })
@@ -1480,6 +1562,7 @@ export async function runCli (argv: string[] = process.argv.slice(2), options: R
           `Workspace: ${context.workspaceFolder}`
         ], async () => {
           progress.setSteps(codingAgentProgressSteps(agent))
+          await (options.prepareContainerLifecycle ?? prepareContainerLifecycle)(context, alias, progress, options, logger)
           await startDevcontainer(context, {
             recreate: parsed.recreate,
             progress,
@@ -1497,6 +1580,7 @@ export async function runCli (argv: string[] = process.argv.slice(2), options: R
         `Workspace: ${context.workspaceFolder}`
       ], async () => {
         progress.setSteps(startProgressSteps())
+        await (options.prepareContainerLifecycle ?? prepareContainerLifecycle)(context, alias, progress, options, logger)
         return await startDevcontainer(context, {
           recreate: parsed.recreate,
           progress,