start-command 0.29.1 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # start-command
 
+## 0.30.0
+
+### Minor Changes
+
+- 3d7fe09: Clean up Docker isolation containers by default after completion, preserve host log files, and add explicit `--keep-container`, `--always-cleanup-container`, and `--keep-container-on-fail` cleanup policy flags.
+
+## 0.29.2
+
+### Patch Changes
+
+- 8518034: Record the docker image-preparation phase in the session log (issue #138). When a `--isolated docker` run needs to `docker pull` an image, the pull output is now teed into the session-log file (`/tmp/start-command/logs/isolation/docker/<uuid>.log`) in real time and bracketed with `Preparing image <name>…` / `Image ready (<duration>)` markers (or `Image preparation failed` on error). Previously the minutes spent pulling a (potentially multi-GB) image left no trace in the log, so operators tailing `$ --upload-log <uuid>` during startup saw only the header. The single session-log file is now a gap-free record of the run, including the longest, most failure-prone phase.
+
 ## 0.29.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {

package/src/bin/cli.js

@@ -503,6 +503,10 @@ async function runWithIsolation(
         endpoint: options.endpoint,
         user: options.user,
         keepAlive: options.keepAlive,
+        autoRemoveDockerContainer: options.autoRemoveDockerContainer,
+        alwaysCleanupContainer: options.alwaysCleanupContainer,
+        keepContainer: options.keepContainer,
+        keepContainerOnFail: options.keepContainerOnFail,
         useCommandStream,
       },
     });
@@ -574,6 +578,9 @@ async function runWithIsolation(
       user: createdUser,
       keepAlive: options.keepAlive,
       autoRemoveDockerContainer: options.autoRemoveDockerContainer,
+      alwaysCleanupContainer: options.alwaysCleanupContainer,
+      keepContainer: options.keepContainer,
+      keepContainerOnFail: options.keepContainerOnFail,
       volumes: options.volumes,
       mounts: options.mounts,
       env: options.env,

package/src/lib/args-parser.js

@@ -19,7 +19,10 @@
  * --isolated-user, -u [username]   Create isolated user with same permissions (auto-generated name if not specified)
  * --keep-user                      Keep isolated user after command completes (don't delete)
  * --keep-alive, -k                 Keep isolation environment alive after command exits
- * --auto-remove-docker-container   Automatically remove docker container after exit (disabled by default)
+ * --auto-remove-docker-container   Always remove docker container after exit (compatibility alias)
+ * --always-cleanup-container       Always remove docker container after exit (default)
+ * --keep-container                 Keep docker container filesystem after exit
+ * --keep-container-on-fail         Remove successful docker containers, keep failed ones
  * --shell <shell>                  Shell to use in isolation environments: auto, bash, zsh, sh (default: auto)
  * --use-command-stream             Use command-stream library for command execution (experimental)
  * --verbose                        Enable verbose/debug output (sets START_VERBOSE=1)
@@ -181,7 +184,10 @@ function parseArgs(args) {
     userName: null, // Optional custom username for isolated user
     keepUser: false, // Keep isolated user after command completes (don't delete)
     keepAlive: false, // Keep environment alive after command exits
-    autoRemoveDockerContainer: false, // Auto-remove docker container after exit
+    autoRemoveDockerContainer: false, // Always remove docker container after exit (compatibility alias)
+    alwaysCleanupContainer: false, // Explicitly request default always-cleanup docker policy
+    keepContainer: false, // Keep docker container filesystem after exit
+    keepContainerOnFail: false, // Keep docker container filesystem only when command fails
     shell: 'auto', // Shell to use in isolation environments: auto, bash, zsh, sh
     useCommandStream: false, // Use command-stream library for command execution
     status: null, // UUID to show status for
@@ -449,6 +455,24 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  // --always-cleanup-container
+  if (arg === '--always-cleanup-container') {
+    options.alwaysCleanupContainer = true;
+    return 1;
+  }
+
+  // --keep-container
+  if (arg === '--keep-container') {
+    options.keepContainer = true;
+    return 1;
+  }
+
+  // --keep-container-on-fail
+  if (arg === '--keep-container-on-fail') {
+    options.keepContainerOnFail = true;
+    return 1;
+  }
+
   // --shell <shell>
   if (arg === '--shell') {
     if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
@@ -649,6 +673,35 @@ function validateDockerRuntimeOptionsRequireDocker(options) {
   }
 }
 
+function validateDockerCleanupOptions(options, hasDocker) {
+  const cleanupFlags = [
+    ['--auto-remove-docker-container', options.autoRemoveDockerContainer],
+    ['--always-cleanup-container', options.alwaysCleanupContainer],
+    ['--keep-container', options.keepContainer],
+    ['--keep-container-on-fail', options.keepContainerOnFail],
+  ];
+
+  for (const [flag, enabled] of cleanupFlags) {
+    if (enabled && !hasDocker) {
+      throw new Error(
+        `${flag} option is only valid when isolation stack includes docker`
+      );
+    }
+  }
+
+  const selectedPolicies = [
+    options.autoRemoveDockerContainer || options.alwaysCleanupContainer,
+    options.keepContainer,
+    options.keepContainerOnFail,
+  ].filter(Boolean).length;
+
+  if (selectedPolicies > 1) {
+    throw new Error(
+      'Cannot combine docker container cleanup policies. Choose only one of --always-cleanup-container, --keep-container, or --keep-container-on-fail.'
+    );
+  }
+}
+
 /**
  * Validate parsed options
  * @param {object} options - Parsed options
@@ -764,12 +817,7 @@ function validateOptions(options) {
       );
     }
 
-    // Auto-remove-docker-container is only valid with docker in stack
-    if (options.autoRemoveDockerContainer && !stack.includes('docker')) {
-      throw new Error(
-        '--auto-remove-docker-container option is only valid when isolation stack includes docker'
-      );
-    }
+    validateDockerCleanupOptions(options, stack.includes('docker'));
 
     // Docker runtime options (--volume, --mount, --env, --privileged) require docker
     if (!stack.includes('docker')) {
@@ -785,11 +833,7 @@ function validateOptions(options) {
     }
   } else {
     // Validate options that require isolation when no isolation is specified
-    if (options.autoRemoveDockerContainer) {
-      throw new Error(
-        '--auto-remove-docker-container option is only valid when isolation stack includes docker'
-      );
-    }
+    validateDockerCleanupOptions(options, false);
     if (options.image) {
       throw new Error(
         '--image option is only valid when isolation stack includes docker'

package/src/lib/command-builder.js

@@ -84,8 +84,19 @@ function buildNextLevelCommand(options, command) {
     parts.push(`--session-id ${options.sessionId}`);
   }
 
-  if (options.autoRemoveDockerContainer) {
-    parts.push('--auto-remove-docker-container');
+  if (remainingStack.includes('docker')) {
+    if (options.autoRemoveDockerContainer) {
+      parts.push('--auto-remove-docker-container');
+    }
+    if (options.alwaysCleanupContainer) {
+      parts.push('--always-cleanup-container');
+    }
+    if (options.keepContainer) {
+      parts.push('--keep-container');
+    }
+    if (options.keepContainerOnFail) {
+      parts.push('--keep-container-on-fail');
+    }
   }
 
   if (options.shell && options.shell !== 'auto') {

package/src/lib/docker-cleanup.js

@@ -0,0 +1,145 @@
+const { spawn, spawnSync } = require('child_process');
+const {
+  appendLogFile,
+  createShellLogFooterSnippet,
+  shellQuote,
+} = require('./isolation-log-utils');
+
+const DOCKER_CONTAINER_CLEANUP_POLICY = {
+  ALWAYS: 'always',
+  KEEP: 'keep',
+  KEEP_ON_FAIL: 'keep-on-fail',
+};
+
+function getDockerContainerCleanupPolicy(options = {}) {
+  if (options.keepContainer) {
+    return DOCKER_CONTAINER_CLEANUP_POLICY.KEEP;
+  }
+  if (options.keepContainerOnFail) {
+    return DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL;
+  }
+  return DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS;
+}
+
+function shouldCleanupDockerContainer(policy, exitCode) {
+  if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS) {
+    return true;
+  }
+  if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL) {
+    return exitCode === 0;
+  }
+  return false;
+}
+
+function getDockerContainerCleanupInstructions(containerName) {
+  return [
+    `Container kept for investigation: ${containerName}`,
+    `Inspect: docker exec -it ${containerName} sh (if running) or docker start -ai ${containerName}`,
+    `Remove when done: docker rm -f ${containerName}`,
+  ].join('\n');
+}
+
+function appendDockerContainerCleanupPolicyMessage(
+  message,
+  containerName,
+  policy
+) {
+  if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP) {
+    return `${message}\n${getDockerContainerCleanupInstructions(containerName)}`;
+  }
+  if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL) {
+    return (
+      `${message}\nContainer will be removed after successful completion.` +
+      `\nContainer will be kept if the command fails.` +
+      `\nRemove when done: docker rm -f ${containerName}`
+    );
+  }
+  return `${message}\nContainer will be removed after command completes.`;
+}
+
+function removeDockerContainer(containerName, logPath = null) {
+  const result = spawnSync('docker', ['rm', '-f', containerName], {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  const output = `${result.stdout || ''}${result.stderr || ''}`;
+  if (logPath && output) {
+    appendLogFile(logPath, output.endsWith('\n') ? output : `${output}\n`);
+  }
+  return !result.error && result.status === 0;
+}
+
+function buildDetachedDockerCompletionScript(containerName, policy, logPath) {
+  const quotedName = shellQuote(containerName);
+  const parts = [];
+
+  if (logPath) {
+    const quotedLogPath = shellQuote(logPath);
+    parts.push(`docker logs -f ${quotedName} >> ${quotedLogPath} 2>&1`);
+    parts.push(
+      `__start_command_exit=$(docker inspect -f '{{.State.ExitCode}}' ${quotedName} 2>/dev/null || printf '%s' '-1')`
+    );
+    if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS) {
+      parts.push(`docker rm -f ${quotedName} >> ${quotedLogPath} 2>&1 || true`);
+    } else if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL) {
+      parts.push(
+        `if [ "$__start_command_exit" -eq 0 ] 2>/dev/null; then docker rm -f ${quotedName} >> ${quotedLogPath} 2>&1 || true; fi`
+      );
+    }
+    parts.push(`${createShellLogFooterSnippet()} >> ${quotedLogPath}`);
+  } else {
+    parts.push(`docker wait ${quotedName} >/dev/null 2>&1`);
+    parts.push(
+      `__start_command_exit=$(docker inspect -f '{{.State.ExitCode}}' ${quotedName} 2>/dev/null || printf '%s' '-1')`
+    );
+    if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS) {
+      parts.push(`docker rm -f ${quotedName} >/dev/null 2>&1 || true`);
+    } else if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL) {
+      parts.push(
+        `if [ "$__start_command_exit" -eq 0 ] 2>/dev/null; then docker rm -f ${quotedName} >/dev/null 2>&1 || true; fi`
+      );
+    }
+  }
+
+  return parts.join('; ');
+}
+
+function startDetachedDockerCompletionWatcher(containerName, policy, logPath) {
+  const watcher = spawn(
+    'sh',
+    ['-c', buildDetachedDockerCompletionScript(containerName, policy, logPath)],
+    {
+      detached: true,
+      stdio: 'ignore',
+    }
+  );
+  watcher.unref();
+}
+
+function spawnAttachedDocker(dockerArgs, logPath) {
+  if (!logPath) {
+    return spawn('docker', dockerArgs, { stdio: 'inherit' });
+  }
+
+  const child = spawn('docker', dockerArgs, {
+    stdio: ['inherit', 'pipe', 'pipe'],
+  });
+  const tee = (chunk, stream) => {
+    stream.write(chunk);
+    appendLogFile(logPath, chunk.toString());
+  };
+  child.stdout.on('data', (chunk) => tee(chunk, process.stdout));
+  child.stderr.on('data', (chunk) => tee(chunk, process.stderr));
+  return child;
+}
+
+module.exports = {
+  DOCKER_CONTAINER_CLEANUP_POLICY,
+  getDockerContainerCleanupPolicy,
+  shouldCleanupDockerContainer,
+  getDockerContainerCleanupInstructions,
+  appendDockerContainerCleanupPolicyMessage,
+  removeDockerContainer,
+  startDetachedDockerCompletionWatcher,
+  spawnAttachedDocker,
+};

package/src/lib/docker-utils.js

@@ -7,6 +7,8 @@
  */
 
 const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const { execSync, spawnSync } = require('child_process');
 
 /**
@@ -102,31 +104,141 @@ function dockerImageExists(image) {
   }
 }
 
+/**
+ * Run `docker pull <image>` while teeing its output to the session log file.
+ *
+ * When a logPath is given (and tee is available, i.e. non-Windows), the pull
+ * output is streamed to BOTH the console and the log file in real time so the
+ * image-preparation phase is captured in the single session log (issue #138).
+ * docker's own exit code is recovered via a sentinel status file because the
+ * exit status of a `cmd | tee` pipeline reflects tee, not docker.
+ *
+ * Without a logPath, it falls back to the previous behavior: inherited stdio
+ * for real-time console output, with no log capture. On Windows (no portable
+ * shell `tee`) but with a logPath, the pull output is captured, echoed to the
+ * console, and appended to the log after the pull so the session log still
+ * records the image-preparation phase (issue #138) — just not streamed live.
+ *
+ * @param {string} image - Docker image to pull
+ * @param {string|null} logPath - Session log file to append pull output to
+ * @returns {{status: number, error?: Error}} Spawn result (status = docker exit code)
+ */
+function runDockerPull(image, logPath) {
+  const { shellQuote } = require('./isolation-log-utils');
+
+  // Without a log target, keep the original inherited-stdio behavior for
+  // fancy real-time console output.
+  if (!logPath) {
+    return spawnSync('docker', ['pull', image], {
+      stdio: ['pipe', 'inherit', 'inherit'],
+    });
+  }
+
+  // Windows has no portable shell `tee`, so capture the pull output, echo it to
+  // the console, and append it to the log so the image-preparation phase is
+  // still recorded in the session log (issue #138), just not streamed live.
+  if (process.platform === 'win32') {
+    const { appendLogFile } = require('./isolation-log-utils');
+    const result = spawnSync('docker', ['pull', image], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    });
+    const combined = `${result.stdout || ''}${result.stderr || ''}`;
+    if (combined) {
+      process.stdout.write(combined);
+      try {
+        appendLogFile(
+          logPath,
+          combined.endsWith('\n') ? combined : `${combined}\n`
+        );
+      } catch {
+        // best-effort: log capture must never break the pull
+      }
+    }
+    return result;
+  }
+
+  // Tee docker pull output to both the console and the log file. docker writes
+  // to a pipe here, so it emits plain progress lines (ideal for a log). The
+  // sentinel file captures docker's real exit code (the pipeline's own exit
+  // status would be tee's).
+  const statusFile = path.join(
+    os.tmpdir(),
+    `start-docker-pull-${process.pid}-${Date.now()}.status`
+  );
+  try {
+    const pipeline =
+      `{ docker pull ${shellQuote(image)} 2>&1; echo $? > ${shellQuote(statusFile)}; } ` +
+      `| tee -a ${shellQuote(logPath)}`;
+    const result = spawnSync('sh', ['-c', pipeline], {
+      stdio: ['pipe', 'inherit', 'inherit'],
+    });
+    if (result.error) {
+      return result;
+    }
+    let status = result.status;
+    try {
+      const recorded = fs.readFileSync(statusFile, 'utf8').trim();
+      if (recorded !== '') {
+        status = parseInt(recorded, 10);
+      }
+    } catch {
+      // Sentinel missing (e.g. sh/tee failed before docker ran); keep pipeline status.
+    }
+    return { ...result, status };
+  } finally {
+    try {
+      fs.unlinkSync(statusFile);
+    } catch {
+      // best-effort cleanup
+    }
+  }
+}
+
 /**
  * Pull a Docker image with output streaming
- * Displays the pull operation as a virtual command in the timeline
+ * Displays the pull operation as a virtual command in the timeline.
+ *
+ * When a logPath is provided, the image-preparation phase (the `docker pull`)
+ * is also recorded in the session log so the single log file is a gap-free
+ * record of everything that ran (issue #138): a `Preparing image …` marker with
+ * a timestamp is written before the pull, the pull output is teed into the log,
+ * and an `Image ready (<duration>)` marker is written afterwards.
+ *
  * @param {string} image - Docker image to pull
+ * @param {string|null} logPath - Optional session log file to append output to
  * @returns {{success: boolean, output: string}} Pull result
  */
-function dockerPullImage(image) {
+function dockerPullImage(image, logPath = null) {
   const {
     createVirtualCommandBlock,
     createVirtualCommandResult,
     createTimelineSeparator,
   } = require('./output-blocks');
+  const { appendLogFile, getTimestamp } = require('./isolation-log-utils');
 
   // Print the virtual command line followed by empty line for visual separation
   console.log(createVirtualCommandBlock(`docker pull ${image}`));
   console.log();
 
+  // Record the start of the image-preparation phase in the session log so
+  // operators tailing the log see progress instead of a header-only file.
+  const prepStartMs = Date.now();
+  if (logPath) {
+    appendLogFile(
+      logPath,
+      `$ docker pull ${image}\nPreparing image ${image}… (${getTimestamp()})\n`
+    );
+  }
+
   let output = '';
   let success;
 
   try {
-    // Run docker pull with inherited stdio for real-time output
-    const result = spawnSync('docker', ['pull', image], {
-      stdio: ['pipe', 'inherit', 'inherit'],
-    });
+    const result = runDockerPull(image, logPath);
+    if (result.error) {
+      throw result.error;
+    }
 
     success = result.status === 0;
 
@@ -140,6 +252,21 @@ function dockerPullImage(image) {
     console.error(`Failed to run docker pull: ${err.message}`);
     output = err.message;
     success = false;
+    if (logPath) {
+      appendLogFile(logPath, `Failed to run docker pull: ${err.message}\n`);
+    }
+  }
+
+  // Record the end of the image-preparation phase with elapsed duration so the
+  // prep time is visible even when full progress is unavailable (issue #138).
+  if (logPath) {
+    const durationSec = ((Date.now() - prepStartMs) / 1000).toFixed(1);
+    appendLogFile(
+      logPath,
+      success
+        ? `Image ready (${durationSec}s)\n`
+        : `Image preparation failed (${durationSec}s)\n`
+    );
   }
 
   // Print empty line before result marker for visual separation (issue #73)

package/src/lib/isolation.js

@@ -18,10 +18,19 @@ const {
 } = require('./screen-isolation');
 const {
   appendLogFile,
-  createShellLogFooterSnippet,
   shellQuote,
   wrapCommandWithLogFooter,
 } = require('./isolation-log-utils');
+const {
+  DOCKER_CONTAINER_CLEANUP_POLICY,
+  getDockerContainerCleanupPolicy,
+  shouldCleanupDockerContainer,
+  getDockerContainerCleanupInstructions,
+  appendDockerContainerCleanupPolicyMessage,
+  removeDockerContainer,
+  startDetachedDockerCompletionWatcher,
+  spawnAttachedDocker,
+} = require('./docker-cleanup');
 
 /**
  * Check if a command is available on the system
@@ -554,7 +563,7 @@ function buildDockerRuntimeMetadata(options = {}) {
 /**
  * Run command in Docker container
  * @param {string} command - Command to execute
- * @param {object} options - Options (image, session/name, detached, user, keepAlive, autoRemoveDockerContainer, volumes, mounts, env, privileged)
+ * @param {object} options - Options (image, session/name, detached, user, keepAlive, container cleanup policy, volumes, mounts, env, privileged)
  * @returns {Promise<{success: boolean, containerName: string, message: string}>}
  */
 function runInDocker(command, options = {}) {
@@ -587,8 +596,11 @@ function runInDocker(command, options = {}) {
   }
 
   const containerName = options.session || generateSessionName('docker');
+  const cleanupPolicy = getDockerContainerCleanupPolicy(options);
   if (!dockerImageExists(options.image)) {
-    const pullResult = dockerPullImage(options.image);
+    // Pass logPath so the image-preparation phase (docker pull) is recorded in
+    // the session log, keeping it a gap-free record of the run (issue #138).
+    const pullResult = dockerPullImage(options.image, options.logPath);
     if (!pullResult.success) {
       return Promise.resolve({
         success: false,
@@ -615,9 +627,6 @@ function runInDocker(command, options = {}) {
         dockerArgs.push('-i', '-t');
       }
       dockerArgs.push('--name', containerName);
-      if (options.autoRemoveDockerContainer) {
-        dockerArgs.push('--rm');
-      }
 
       if (options.user) {
         dockerArgs.push('--user', options.user);
@@ -645,6 +654,7 @@ function runInDocker(command, options = {}) {
         console.log(
           `[DEBUG] autoRemoveDockerContainer: ${options.autoRemoveDockerContainer || false}`
         );
+        console.log(`[DEBUG] docker cleanup policy: ${cleanupPolicy}`);
       }
 
       const dockerResult = spawnSync('docker', dockerArgs, {
@@ -665,18 +675,11 @@ function runInDocker(command, options = {}) {
 
       const containerId = dockerResult.stdout.trim();
 
-      if (options.logPath) {
-        const loggerScript = [
-          `docker logs -f ${shellQuote(containerName)} >> ${shellQuote(options.logPath)} 2>&1`,
-          `__start_command_exit=$(docker inspect -f '{{.State.ExitCode}}' ${shellQuote(containerName)} 2>/dev/null || printf '%s' '-1')`,
-          `${createShellLogFooterSnippet()} >> ${shellQuote(options.logPath)}`,
-        ].join('; ');
-        const logger = spawn('sh', ['-c', loggerScript], {
-          detached: true,
-          stdio: 'ignore',
-        });
-        logger.unref();
-      }
+      startDetachedDockerCompletionWatcher(
+        containerName,
+        cleanupPolicy,
+        options.logPath
+      );
 
       let message = `Command started in detached docker container: ${containerName}`;
       message += `\nContainer ID: ${containerId.substring(0, 12)}`;
@@ -685,11 +688,11 @@ function runInDocker(command, options = {}) {
       } else {
         message += `\nContainer will exit automatically after command completes.`;
       }
-      if (options.autoRemoveDockerContainer) {
-        message += `\nContainer will be automatically removed after exit.`;
-      } else {
-        message += `\nContainer filesystem will be preserved after exit.`;
-      }
+      message = appendDockerContainerCleanupPolicyMessage(
+        message,
+        containerName,
+        cleanupPolicy
+      );
       message += `\nAttach with: docker attach ${containerName}`;
       message += `\nView logs: docker logs ${containerName}`;
       if (options.logPath) {
@@ -703,7 +706,9 @@ function runInDocker(command, options = {}) {
         message,
       });
     } else {
-      const dockerArgs = ['run', '-it', '--rm', '--name', containerName];
+      const dockerArgs = ['run'];
+      dockerArgs.push(hasTTY() ? '-it' : '-i');
+      dockerArgs.push('--name', containerName);
       if (options.user) {
         dockerArgs.push('--user', options.user);
       }
@@ -737,13 +742,14 @@ function runInDocker(command, options = {}) {
 
       return new Promise((resolve) => {
         const startTime = Date.now();
-        const child = spawn('docker', dockerArgs, { stdio: 'inherit' });
+        const child = spawnAttachedDocker(dockerArgs, options.logPath);
 
         child.on('exit', (code) => {
           const durationMs = Date.now() - startTime;
-          let message = `Docker container "${containerName}" exited with code ${code}`;
+          const exitCode = code ?? 1;
+          let message = `Docker container "${containerName}" exited with code ${exitCode}`;
           // Bare shell exited non-zero quickly → startup file error; suggest --norc (issue #84).
-          if (isBareShell && code !== 0 && durationMs < 3000) {
+          if (isBareShell && exitCode !== 0 && durationMs < 3000) {
             const shell0 = command.trim().split(/\s+/)[0];
             // prettier-ignore
             const norc = path.basename(shell0) === 'zsh' ? '--no-rcs' : '--norc';
@@ -751,11 +757,28 @@ function runInDocker(command, options = {}) {
             console.log(hint);
             message += `\n${hint}`;
           }
+
+          if (shouldCleanupDockerContainer(cleanupPolicy, exitCode)) {
+            if (removeDockerContainer(containerName, options.logPath)) {
+              message += `\nContainer removed after completion.`;
+            } else {
+              message += `\nWarning: failed to remove container automatically.`;
+              message += `\nRemove when done: docker rm -f ${containerName}`;
+            }
+          } else if (cleanupPolicy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP) {
+            message += `\n${getDockerContainerCleanupInstructions(containerName)}`;
+          } else if (
+            cleanupPolicy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL
+          ) {
+            message += `\nContainer kept because the command failed.`;
+            message += `\nRemove when done: docker rm -f ${containerName}`;
+          }
+
           resolve({
-            success: code === 0,
+            success: exitCode === 0,
             containerName,
             message,
-            exitCode: code,
+            exitCode,
           });
         });
 

package/src/lib/usage.js

@@ -18,7 +18,10 @@ Options:
   --isolated-user, -u [name]  Create isolated user with same permissions
   --keep-user           Keep isolated user after command completes
   --keep-alive, -k      Keep isolation environment alive after command exits
-  --auto-remove-docker-container  Auto-remove docker container after exit
+  --auto-remove-docker-container  Always remove docker container after exit (compatibility alias)
+  --always-cleanup-container  Always remove docker container after exit (default)
+  --keep-container     Keep docker container filesystem after exit
+  --keep-container-on-fail  Remove successful docker containers, keep failed ones
   --shell <shell>       Shell to use in isolation environments: auto, bash, zsh, sh (default: auto)
   --use-command-stream  Use command-stream library for execution (experimental)
   --status <id>         Show status of execution by UUID or session name (--output-format: links-notation|json|text)