boxdown 1.2.0 → 1.3.0

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,7 +14,8 @@ 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 { purgeWorkspace } from './purge.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'
 import { createStatusInfo, formatStatusText, statusIsHealthy } from './status.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[] = []
@@ -831,6 +845,7 @@ async function runDownCommand (workspaces: string[] | undefined, options: RunCli
       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
@@ -1056,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' },
@@ -1064,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`
@@ -1071,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}`,
@@ -1081,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 {
@@ -1092,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,
@@ -1106,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}`)
@@ -1220,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)
 
@@ -1363,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 })
@@ -1399,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', [
@@ -1407,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 })
@@ -1436,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}`)
         }
@@ -1460,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 })
         })
@@ -1479,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,
@@ -1496,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,

package/src/paths.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto'
 import { existsSync, realpathSync, statSync } from 'node:fs'
-import { homedir } from 'node:os'
+import { homedir, tmpdir } from 'node:os'
 import { basename, dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -22,8 +22,11 @@ export interface WorkspaceContext {
   assetsDevcontainerDir: string
   cacheRoot: string
   dataRoot: string
+  runtimeRoot: string
   workspaceCacheDir: string
   workspaceDataDir: string
+  workspaceRuntimeDir: string
+  workspaceSecretEnvDir: string
   generatedConfigPath: string
   hostAgentsDir: string
   hostCodexAuthPath: string
@@ -92,6 +95,18 @@ export function defaultDataRoot (env: NodeJS.ProcessEnv = process.env): string {
   return join(homedir(), '.local', 'share', PACKAGE_NAME)
 }
 
+export function defaultRuntimeRoot (env: NodeJS.ProcessEnv = process.env): string {
+  if (env.BOXDOWN_RUNTIME_HOME) {
+    return env.BOXDOWN_RUNTIME_HOME
+  }
+
+  if (env.XDG_RUNTIME_DIR) {
+    return join(env.XDG_RUNTIME_DIR, PACKAGE_NAME)
+  }
+
+  return join(tmpdir(), `${PACKAGE_NAME}-${process.getuid?.() ?? 'user'}`)
+}
+
 export function defaultHostAgentsDir (env: NodeJS.ProcessEnv = process.env): string {
   return join(env.HOME ?? homedir(), '.agents')
 }
@@ -113,10 +128,12 @@ export function createWorkspaceContextFromIdentity (
   const assetsDevcontainerDir = options.assetsDevcontainerDir ?? env.BOXDOWN_DEVCONTAINER_ASSETS_DIR ?? 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 = join(cacheRoot, 'workspaces', identity.workspaceId)
   const workspaceDataDir = join(dataRoot, 'workspaces', identity.workspaceId)
+  const workspaceRuntimeDir = join(runtimeRoot, 'workspaces', identity.workspaceId)
   const hostGitconfigSnapshotDir = join(workspaceDataDir, 'gitconfig')
 
   return {
@@ -127,8 +144,11 @@ export function createWorkspaceContextFromIdentity (
     assetsDevcontainerDir,
     cacheRoot,
     dataRoot,
+    runtimeRoot,
     workspaceCacheDir,
     workspaceDataDir,
+    workspaceRuntimeDir,
+    workspaceSecretEnvDir: join(workspaceRuntimeDir, 'secrets'),
     generatedConfigPath: join(workspaceCacheDir, 'devcontainer.json'),
     hostAgentsDir,
     hostCodexAuthPath,

package/src/process.ts

@@ -12,12 +12,25 @@ export interface BufferedCommandOptions {
   logger?: WorkspaceCommandLogger
   onStdout?: (chunk: Buffer) => void
   onStderr?: (chunk: Buffer) => void
+  timeoutMs?: number
+  timeoutControl?: BufferedTimeoutControl
 }
 
 export interface CommandResult {
   code: number
   stdout: string
   stderr: string
+  timedOut?: boolean
+}
+
+export interface BufferedTimeoutControl {
+  schedule: (callback: () => void, milliseconds: number) => unknown
+  cancel: (handle: unknown) => void
+}
+
+const realTimeoutControl: BufferedTimeoutControl = {
+  schedule: (callback, milliseconds) => setTimeout(callback, milliseconds),
+  cancel: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>)
 }
 
 function mergedEnv (env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
@@ -84,6 +97,10 @@ function writeChunk (target: 'stdout' | 'stderr' | false, chunk: Buffer): void {
 }
 
 export function runBuffered (command: string, args: string[], options: BufferedCommandOptions = {}): Promise<CommandResult> {
+  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 = spawn(command, args, {
@@ -94,8 +111,13 @@ export function runBuffered (command: string, args: string[], options: BufferedC
 
     const stdoutChunks: Buffer[] = []
     const stderrChunks: Buffer[] = []
+    let settled = false
+    let timeoutHandle: unknown
+    let timeoutScheduled = false
+    const timeoutControl = options.timeoutControl ?? realTimeoutControl
 
     child.stdout.on('data', (chunk: Buffer) => {
+      if (settled) return
       stdoutChunks.push(chunk)
       loggedCommand?.stream('stdout', chunk)
       options.onStdout?.(chunk)
@@ -103,20 +125,18 @@ export function runBuffered (command: string, args: string[], options: BufferedC
     })
 
     child.stderr.on('data', (chunk: Buffer) => {
+      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
-      }
+      if (settled) return
 
-      resolved = true
+      settled = true
+      if (timeoutScheduled) timeoutControl.cancel(timeoutHandle)
       loggedCommand?.error(error)
       loggedCommand?.finish(127)
       resolve({
@@ -127,11 +147,10 @@ export function runBuffered (command: string, args: string[], options: BufferedC
     })
 
     child.on('close', (code) => {
-      if (resolved) {
-        return
-      }
+      if (settled) return
 
-      resolved = true
+      settled = true
+      if (timeoutScheduled) timeoutControl.cancel(timeoutHandle)
       loggedCommand?.finish(code ?? 1)
       resolve({
         code: code ?? 1,
@@ -140,6 +159,27 @@ export function runBuffered (command: string, args: string[], options: BufferedC
       })
     })
 
+    if (options.timeoutMs !== undefined) {
+      timeoutHandle = timeoutControl.schedule(() => {
+        if (settled) return
+
+        settled = true
+        const message = `Command timed out after ${options.timeoutMs as number} 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 {

package/src/progress.ts

@@ -178,6 +178,16 @@ export class ProgressReporter {
     this.#writeLine(`${promptRail()}  ${color(message, 'dim')}`)
   }
 
+  status (message: string): void {
+    if (this.mode === 'none') return
+    if (this.mode === 'verbose') {
+      this.#write(this.target, message)
+      return
+    }
+
+    this.#writeInteractiveLine(`${promptRail()}  ${color(message, 'dim')}`)
+  }
+
   warn (message: string): void {
     if (this.mode === 'none') {
       return
@@ -188,7 +198,7 @@ export class ProgressReporter {
       return
     }
 
-    this.#writeLine(`${promptRail()}  ${color('!', 'dim')} ${message}`)
+    this.#writeInteractiveLine(`${promptRail()}  ${color('!', 'dim')} ${message}`)
   }
 
   marker (message: string): void {
@@ -329,6 +339,18 @@ export class ProgressReporter {
     this.#write(this.target, message)
   }
 
+  #writeInteractiveLine (message: string): void {
+    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 (): void {
     const spinner = this.#spinner
     if (spinner === undefined) {
@@ -505,18 +527,38 @@ function outputWithoutProgressMarkers (output: string): string {
     .join('\n')
 }
 
-function tailLines (output: string, maxLines: number): string[] {
+export interface CommandFailureOptions {
+  tailLines?: number
+  logPath?: string
+}
+
+function outputLines (output: string): string[] {
   return output
     .split(/\r?\n/u)
     .map((line) => line.trimEnd())
     .filter((line) => line.trim().length > 0)
-    .slice(-maxLines)
 }
 
-export function formatCommandFailure (label: string, result: CommandResult, options: { tailLines?: number } = {}): string {
+function isDevcontainerErrorEnvelope (line: string): boolean {
+  try {
+    const value = JSON.parse(line) as { outcome?: unknown, message?: unknown }
+    return value !== null && typeof value === 'object' &&
+      value.outcome === 'error' && typeof value.message === 'string'
+  } catch {
+    return false
+  }
+}
+
+export function formatCommandFailure (label: string, result: CommandResult, options: CommandFailureOptions = {}): string {
   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.'
@@ -530,6 +572,14 @@ export function formatCommandFailure (label: string, result: CommandResult, opti
     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')
 }
 
@@ -586,8 +636,13 @@ export async function runProgressCommand (
   }
 }
 
-export function assertProgressCommandSucceeded (label: string, result: CommandResult, message: string): void {
+export function assertProgressCommandSucceeded (
+  label: string,
+  result: CommandResult,
+  message: string,
+  options: CommandFailureOptions = {}
+): void {
   if (result.code !== 0) {
-    throw new Error(`${message}\n${formatCommandFailure(label, result)}`)
+    throw new Error(`${message}\n${formatCommandFailure(label, result, options)}`)
   }
 }

package/src/purge.ts

@@ -85,6 +85,10 @@ function removeWorkspaceStateDir (
   process.stdout.write(`Removed ${label}: ${path}\n`)
 }
 
+export function removeWorkspaceRuntimeState (context: WorkspaceContext): void {
+  removeWorkspaceStateDir(context, 'workspace runtime directory', context.workspaceRuntimeDir, context.runtimeRoot)
+}
+
 async function purgeAliasIntegrations (context: WorkspaceContext, alias: string): Promise<boolean> {
   let failed = false
 
@@ -194,6 +198,10 @@ export async function purgeWorkspace (context: WorkspaceContext, options: PurgeO
     }) || 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

package/src/shell.ts

@@ -61,10 +61,15 @@ function interactiveAgentPathScript (): string {
   ].join('\n')
 }
 
+function runtimeSecretEnvironmentScript (): string {
+  return 'source "${BASH_ENV:-/opt/boxdown/devcontainer/utils/secret-env-bootstrap.sh}"'
+}
+
 export function interactiveShellScript (): string {
   return [
     interactiveTermSetupScript(),
     interactiveTtySetupScript(),
+    runtimeSecretEnvironmentScript(),
     'exec bash -i'
   ].join('\n')
 }
@@ -74,6 +79,7 @@ export function interactiveCommandScript (): string {
     interactiveTermSetupScript(),
     interactiveTtySetupScript(),
     interactiveAgentPathScript(),
+    runtimeSecretEnvironmentScript(),
     'exec "$@"'
   ].join('\n')
 }