start-command 0.29.2 → 0.30.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # start-command
 
+## 0.30.1
+
+### Patch Changes
+
+- 1a040d6: Use `docker stop` for detached Docker `--stop` control so containers follow Docker's graceful stop lifecycle instead of receiving a raw `SIGINT`.
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.29.2",
+  "version": "0.30.1",
   "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)
@@ -27,7 +30,7 @@
  * --list                           List all tracked command executions
  * --upload-log <uuid-or-session>    Upload the stored log for a tracked execution
  * --output-format <format>         Output format for status/list (links-notation, json, text)
- * --stop <uuid-or-session-name>     Send CTRL+C/SIGINT to a detached execution
+ * --stop <uuid-or-session-name>     Ask a detached execution to stop gracefully
  * --terminate <uuid-or-session-name> Terminate a detached execution immediately
  * --cleanup                        Clean up stale "executing" records (processes that crashed or were killed)
  * --cleanup-dry-run                Show stale records that would be cleaned up (without actually cleaning)
@@ -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/execution-control.js

@@ -197,9 +197,9 @@ function getControlCommand(record, action) {
       case 'docker':
         return {
           command: 'docker',
-          args: ['kill', '--signal=SIGINT', sessionName],
-          method: 'SIGINT',
-          message: `Sent SIGINT to detached docker container: ${sessionName}`,
+          args: ['stop', sessionName],
+          method: 'DOCKER_STOP',
+          message: `Requested graceful stop for detached docker container: ${sessionName}`,
         };
       default:
         return {

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,6 +596,7 @@ function runInDocker(command, options = {}) {
   }
 
   const containerName = options.session || generateSessionName('docker');
+  const cleanupPolicy = getDockerContainerCleanupPolicy(options);
   if (!dockerImageExists(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).
@@ -617,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);
@@ -647,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, {
@@ -667,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)}`;
@@ -687,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) {
@@ -705,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);
       }
@@ -739,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';
@@ -753,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,13 +18,16 @@ 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)
   --list                List all tracked executions (--output-format: links-notation|json|text)
   --upload-log <id>     Upload the stored log for an execution UUID or session name
-  --stop <id>           Send CTRL+C/SIGINT to a detached isolated execution
+  --stop <id>           Ask a detached isolated execution to stop gracefully
   --terminate <id>      Terminate a detached isolated execution immediately
   --cleanup             Clean up stale "executing" records (crashed/killed processes)
   --cleanup-dry-run     Show stale records that would be cleaned up (without cleaning)

package/test/args-parser-docker-cleanup.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env bun
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const { parseArgs } = require('../src/lib/args-parser');
+
+function parseDocker(args = []) {
+  return parseArgs([
+    '--isolated',
+    'docker',
+    '--image',
+    'alpine',
+    ...args,
+    '--',
+    'npm',
+    'test',
+  ]);
+}
+
+describe('docker container cleanup options', () => {
+  it('should parse --auto-remove-docker-container flag', () => {
+    const result = parseDocker(['--auto-remove-docker-container']);
+    assert.strictEqual(result.wrapperOptions.autoRemoveDockerContainer, true);
+  });
+
+  it('should parse --always-cleanup-container flag', () => {
+    const result = parseDocker(['--always-cleanup-container']);
+    assert.strictEqual(result.wrapperOptions.alwaysCleanupContainer, true);
+  });
+
+  it('should parse --keep-container flag', () => {
+    const result = parseDocker(['--keep-container']);
+    assert.strictEqual(result.wrapperOptions.keepContainer, true);
+  });
+
+  it('should parse --keep-container-on-fail flag', () => {
+    const result = parseDocker(['--keep-container-on-fail']);
+    assert.strictEqual(result.wrapperOptions.keepContainerOnFail, true);
+  });
+
+  it('should default cleanup flags to false', () => {
+    const result = parseDocker();
+    assert.strictEqual(result.wrapperOptions.autoRemoveDockerContainer, false);
+    assert.strictEqual(result.wrapperOptions.alwaysCleanupContainer, false);
+    assert.strictEqual(result.wrapperOptions.keepContainer, false);
+    assert.strictEqual(result.wrapperOptions.keepContainerOnFail, false);
+  });
+
+  it('should throw error for docker cleanup options without docker isolation', () => {
+    assert.throws(() => {
+      parseArgs([
+        '-i',
+        'tmux',
+        '--auto-remove-docker-container',
+        '--',
+        'npm',
+        'test',
+      ]);
+    }, /--auto-remove-docker-container option is only valid when isolation stack includes docker/);
+    assert.throws(() => {
+      parseArgs([
+        '-i',
+        'tmux',
+        '--always-cleanup-container',
+        '--',
+        'npm',
+        'test',
+      ]);
+    }, /--always-cleanup-container option is only valid when isolation stack includes docker/);
+    assert.throws(() => {
+      parseArgs(['-i', 'tmux', '--keep-container', '--', 'npm', 'test']);
+    }, /--keep-container option is only valid when isolation stack includes docker/);
+    assert.throws(() => {
+      parseArgs([
+        '-i',
+        'tmux',
+        '--keep-container-on-fail',
+        '--',
+        'npm',
+        'test',
+      ]);
+    }, /--keep-container-on-fail option is only valid when isolation stack includes docker/);
+  });
+
+  it('should throw error for docker cleanup options without isolation', () => {
+    assert.throws(() => {
+      parseArgs(['--auto-remove-docker-container', '--', 'npm', 'test']);
+    }, /--auto-remove-docker-container option is only valid when isolation stack includes docker/);
+    assert.throws(() => {
+      parseArgs(['--always-cleanup-container', '--', 'npm', 'test']);
+    }, /--always-cleanup-container option is only valid when isolation stack includes docker/);
+    assert.throws(() => {
+      parseArgs(['--keep-container', '--', 'npm', 'test']);
+    }, /--keep-container option is only valid when isolation stack includes docker/);
+    assert.throws(() => {
+      parseArgs(['--keep-container-on-fail', '--', 'npm', 'test']);
+    }, /--keep-container-on-fail option is only valid when isolation stack includes docker/);
+  });
+
+  it('should work with keep-alive and auto-remove-docker-container', () => {
+    const result = parseArgs([
+      '-i',
+      'docker',
+      '--image',
+      'node:20',
+      '-k',
+      '--auto-remove-docker-container',
+      '--',
+      'npm',
+      'test',
+    ]);
+    assert.strictEqual(result.wrapperOptions.isolated, 'docker');
+    assert.strictEqual(result.wrapperOptions.image, 'node:20');
+    assert.strictEqual(result.wrapperOptions.keepAlive, true);
+    assert.strictEqual(result.wrapperOptions.autoRemoveDockerContainer, true);
+  });
+
+  it('should reject conflicting docker cleanup options', () => {
+    assert.throws(() => {
+      parseArgs([
+        '-i',
+        'docker',
+        '--keep-container',
+        '--always-cleanup-container',
+        '--',
+        'npm',
+        'test',
+      ]);
+    }, /Cannot combine docker container cleanup policies/);
+
+    assert.throws(() => {
+      parseArgs([
+        '-i',
+        'docker',
+        '--keep-container',
+        '--keep-container-on-fail',
+        '--',
+        'npm',
+        'test',
+      ]);
+    }, /Cannot combine docker container cleanup policies/);
+  });
+});

package/test/args-parser.js

@@ -343,75 +343,6 @@ describe('parseArgs', () => {
     });
   });
 
-  describe('auto-remove-docker-container option', () => {
-    it('should parse --auto-remove-docker-container flag', () => {
-      const result = parseArgs([
-        '--isolated',
-        'docker',
-        '--image',
-        'alpine',
-        '--auto-remove-docker-container',
-        '--',
-        'npm',
-        'test',
-      ]);
-      assert.strictEqual(result.wrapperOptions.autoRemoveDockerContainer, true);
-    });
-
-    it('should default autoRemoveDockerContainer to false', () => {
-      const result = parseArgs([
-        '-i',
-        'docker',
-        '--image',
-        'alpine',
-        '--',
-        'npm',
-        'test',
-      ]);
-      assert.strictEqual(
-        result.wrapperOptions.autoRemoveDockerContainer,
-        false
-      );
-    });
-
-    it('should throw error for auto-remove-docker-container without docker isolation', () => {
-      assert.throws(() => {
-        parseArgs([
-          '-i',
-          'tmux',
-          '--auto-remove-docker-container',
-          '--',
-          'npm',
-          'test',
-        ]);
-      }, /--auto-remove-docker-container option is only valid when isolation stack includes docker/);
-    });
-
-    it('should throw error for auto-remove-docker-container without isolation', () => {
-      assert.throws(() => {
-        parseArgs(['--auto-remove-docker-container', '--', 'npm', 'test']);
-      }, /--auto-remove-docker-container option is only valid when isolation stack includes docker/);
-    });
-
-    it('should work with keep-alive and auto-remove-docker-container', () => {
-      const result = parseArgs([
-        '-i',
-        'docker',
-        '--image',
-        'node:20',
-        '-k',
-        '--auto-remove-docker-container',
-        '--',
-        'npm',
-        'test',
-      ]);
-      assert.strictEqual(result.wrapperOptions.isolated, 'docker');
-      assert.strictEqual(result.wrapperOptions.image, 'node:20');
-      assert.strictEqual(result.wrapperOptions.keepAlive, true);
-      assert.strictEqual(result.wrapperOptions.autoRemoveDockerContainer, true);
-    });
-  });
-
   describe('command without separator', () => {
     it('should parse command after options without separator', () => {
       const result = parseArgs(['-i', 'tmux', '-d', 'npm', 'start']);

package/test/command-builder-docker-cleanup.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env bun
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const { buildNextLevelCommand } = require('../src/lib/command-builder');
+
+describe('command-builder docker cleanup forwarding', () => {
+  it('forwards cleanup policy flags when a remaining level uses docker', () => {
+    const command = buildNextLevelCommand(
+      {
+        isolatedStack: ['tmux', 'docker'],
+        imageStack: [null, 'alpine'],
+        keepContainerOnFail: true,
+      },
+      'npm test'
+    );
+
+    assert.match(command, /--isolated "docker"/);
+    assert.match(command, /--keep-container-on-fail/);
+  });
+
+  it('does not forward docker cleanup flags after the docker level is consumed', () => {
+    const command = buildNextLevelCommand(
+      {
+        isolatedStack: ['docker', 'tmux'],
+        imageStack: ['alpine', null],
+        keepContainer: true,
+      },
+      'npm test'
+    );
+
+    assert.match(command, /--isolated "tmux"/);
+    assert.doesNotMatch(command, /--keep-container/);
+  });
+});

package/test/docker-autoremove.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env bun
 /**
- * Tests for Docker auto-remove container feature
+ * Tests for Docker container cleanup behavior
  */
 
 const { describe, it } = require('node:test');
 const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const { isCommandAvailable } = require('../src/lib/isolation');
 const { runInDocker } = require('../src/lib/isolation');
 const { execSync } = require('child_process');
@@ -26,9 +29,9 @@ async function waitFor(conditionFn, timeout = 5000, interval = 100) {
 const { canRunLinuxDockerImages } = require('../src/lib/isolation');
 const DOCKER_TEST_TIMEOUT = 20000;
 
-describe('Docker Auto-Remove Container Feature', () => {
-  // These tests verify the --auto-remove-docker-container option
-  // which automatically removes the container after exit (disabled by default)
+describe('Docker Container Cleanup Policy', () => {
+  // These tests verify that docker isolation removes finished containers by
+  // default while still providing explicit flags to keep them for investigation.
 
   describe('auto-remove enabled', () => {
     it(
@@ -55,8 +58,8 @@ describe('Docker Auto-Remove Container Feature', () => {
 
         assert.strictEqual(result.success, true);
         assert.ok(
-          result.message.includes('automatically removed'),
-          'Message should indicate auto-removal'
+          result.message.includes('will be removed'),
+          'Message should indicate cleanup'
         );
 
         // Wait for container to finish and be removed
@@ -99,9 +102,9 @@ describe('Docker Auto-Remove Container Feature', () => {
     );
   });
 
-  describe('auto-remove disabled (default)', () => {
+  describe('default cleanup', () => {
     it(
-      'should preserve container filesystem by default (without autoRemoveDockerContainer)',
+      'should remove container filesystem by default',
       { timeout: DOCKER_TEST_TIMEOUT },
       async () => {
         if (!canRunLinuxDockerImages()) {
@@ -111,9 +114,10 @@ describe('Docker Auto-Remove Container Feature', () => {
           return;
         }
 
-        const containerName = `test-preserve-${Date.now()}`;
+        const containerName = `test-default-cleanup-${Date.now()}`;
 
-        // Run command without autoRemoveDockerContainer
+        // Run command without any cleanup flag. The default should still remove
+        // the container after the command finishes.
         const result = await runInDocker('echo "test" && sleep 0.1', {
           image: 'alpine:latest',
           session: containerName,
@@ -124,12 +128,76 @@ describe('Docker Auto-Remove Container Feature', () => {
 
         assert.strictEqual(result.success, true);
         assert.ok(
-          result.message.includes('filesystem will be preserved'),
-          'Message should indicate filesystem preservation'
+          result.message.includes('will be removed'),
+          'Message should indicate default cleanup'
         );
 
-        // Wait for container to exit
-        await waitFor(() => {
+        const containerRemoved = await waitFor(() => {
+          try {
+            execSync(`docker inspect -f '{{.State.Status}}' ${containerName}`, {
+              encoding: 'utf8',
+              stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            return false;
+          } catch {
+            return true;
+          }
+        }, 10000);
+
+        assert.ok(
+          containerRemoved,
+          'Container should be removed after exit by default'
+        );
+
+        try {
+          const allContainers = execSync('docker ps -a', {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+          });
+          assert.ok(
+            !allContainers.includes(containerName),
+            'Container should NOT appear in docker ps -a after default cleanup'
+          );
+        } catch (err) {
+          assert.fail(`Failed to verify container cleanup: ${err.message}`);
+        }
+      }
+    );
+  });
+
+  describe('keep-container opt-out', () => {
+    it(
+      'should preserve container filesystem when keepContainer is true',
+      { timeout: DOCKER_TEST_TIMEOUT },
+      async () => {
+        if (!canRunLinuxDockerImages()) {
+          console.log(
+            '  Skipping: docker not available, daemon not running, or Linux containers not supported'
+          );
+          return;
+        }
+
+        const containerName = `test-keep-container-${Date.now()}`;
+
+        const result = await runInDocker('echo "test" && sleep 0.1', {
+          image: 'alpine:latest',
+          session: containerName,
+          detached: true,
+          keepAlive: false,
+          keepContainer: true,
+        });
+
+        assert.strictEqual(result.success, true);
+        assert.ok(
+          result.message.includes('Container kept for investigation'),
+          'Message should explain that the container is kept'
+        );
+        assert.ok(
+          result.message.includes(`docker rm -f ${containerName}`),
+          'Message should include cleanup command'
+        );
+
+        const containerExited = await waitFor(() => {
           try {
             const status = execSync(
               `docker inspect -f '{{.State.Status}}' ${containerName}`,
@@ -144,26 +212,66 @@ describe('Docker Auto-Remove Container Feature', () => {
           }
         }, 10000);
 
-        // Container should still exist (in exited state)
+        assert.ok(containerExited, 'Container should remain in exited state');
+
         try {
-          const allContainers = execSync('docker ps -a', {
-            encoding: 'utf8',
-            stdio: ['pipe', 'pipe', 'pipe'],
-          });
-          assert.ok(
-            allContainers.includes(containerName),
-            'Container should appear in docker ps -a (filesystem preserved)'
-          );
+          execSync(`docker rm -f ${containerName}`, { stdio: 'ignore' });
+        } catch {
+          // Ignore cleanup errors
+        }
+      }
+    );
+
+    it(
+      'should preserve failed containers when keepContainerOnFail is true',
+      { timeout: DOCKER_TEST_TIMEOUT },
+      async () => {
+        if (!canRunLinuxDockerImages()) {
           console.log(
-            '  ✓ Docker container filesystem preserved by default (can be re-entered)'
-          );
-        } catch (err) {
-          assert.fail(
-            `Failed to verify container preservation: ${err.message}`
+            '  Skipping: docker not available, daemon not running, or Linux containers not supported'
           );
+          return;
         }
 
-        // Clean up
+        const containerName = `test-keep-on-fail-${Date.now()}`;
+
+        const result = await runInDocker('echo "test" && exit 7', {
+          image: 'alpine:latest',
+          session: containerName,
+          detached: true,
+          keepAlive: false,
+          keepContainerOnFail: true,
+        });
+
+        assert.strictEqual(result.success, true);
+        assert.ok(
+          result.message.includes(
+            'Container will be kept if the command fails'
+          ),
+          'Message should describe failure retention'
+        );
+        assert.ok(
+          result.message.includes(`docker rm -f ${containerName}`),
+          'Message should include cleanup command'
+        );
+
+        const containerExited = await waitFor(() => {
+          try {
+            const status = execSync(
+              `docker inspect -f '{{.State.Status}} {{.State.ExitCode}}' ${containerName}`,
+              {
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+              }
+            ).trim();
+            return status === 'exited 7';
+          } catch {
+            return false;
+          }
+        }, 10000);
+
+        assert.ok(containerExited, 'Failed container should be preserved');
+
         try {
           execSync(`docker rm -f ${containerName}`, { stdio: 'ignore' });
         } catch {
@@ -172,4 +280,71 @@ describe('Docker Auto-Remove Container Feature', () => {
       }
     );
   });
+
+  describe('attached mode logging', () => {
+    it(
+      'should write attached docker output to the provided host log path',
+      { timeout: DOCKER_TEST_TIMEOUT },
+      async () => {
+        if (!canRunLinuxDockerImages()) {
+          console.log(
+            '  Skipping: docker not available, daemon not running, or Linux containers not supported'
+          );
+          return;
+        }
+
+        const containerName = `test-attached-log-${Date.now()}`;
+        const logPath = path.join(
+          os.tmpdir(),
+          `start-attached-docker-${process.pid}-${Date.now()}.log`
+        );
+        fs.writeFileSync(logPath, '=== test log header ===\n');
+
+        try {
+          const result = await runInDocker("printf 'attached-log-line\\n'", {
+            image: 'alpine:latest',
+            session: containerName,
+            detached: false,
+            keepAlive: false,
+            logPath,
+          });
+
+          assert.strictEqual(result.success, true);
+          assert.ok(
+            result.message.includes('Container removed after completion'),
+            'Attached container should be removed after completion by default'
+          );
+
+          const contents = fs.readFileSync(logPath, 'utf8');
+          assert.ok(
+            contents.includes('attached-log-line'),
+            `Attached docker output should be written to host log, got:\n${contents}`
+          );
+
+          const containerRemoved = await waitFor(() => {
+            try {
+              execSync(
+                `docker inspect -f '{{.State.Status}}' ${containerName}`,
+                {
+                  encoding: 'utf8',
+                  stdio: ['pipe', 'pipe', 'pipe'],
+                }
+              );
+              return false;
+            } catch {
+              return true;
+            }
+          }, 10000);
+          assert.ok(containerRemoved, 'Attached container should be removed');
+        } finally {
+          try {
+            execSync(`docker rm -f ${containerName}`, { stdio: 'ignore' });
+          } catch {
+            // Ignore cleanup errors
+          }
+          fs.rmSync(logPath, { force: true });
+        }
+      }
+    );
+  });
 });

package/test/execution-control.js

@@ -136,6 +136,46 @@ describe('execution control', () => {
     });
   });
 
+  it('should stop a detached docker container with docker stop', () => {
+    const store = createStore();
+    store.save(
+      createDetachedRecord({
+        uuid: 'docker-control-uuid',
+        options: {
+          isolated: 'docker',
+          isolationMode: 'detached',
+          sessionName: 'docker-session',
+          containerId: 'abc123',
+        },
+      })
+    );
+    const runner = createRunner({
+      'docker inspect -f {{.Id}} {{.State.Pid}} docker-session': {
+        success: true,
+        stdout: 'abcdef 0\n',
+        stderr: '',
+        status: 0,
+        error: null,
+      },
+    });
+
+    const result = controlExecution(
+      store,
+      'docker-control-uuid',
+      ControlAction.STOP,
+      runner
+    );
+
+    assert.strictEqual(result.success, true);
+    assert.match(result.output, /action stop/);
+    assert.match(result.output, /method DOCKER_STOP/);
+    assert.match(result.output, /containerId abcdef/);
+    assert.deepStrictEqual(runner.calls[0], {
+      command: 'docker',
+      args: ['stop', 'docker-session'],
+    });
+  });
+
   it('should send docker terminate through docker kill', () => {
     const store = createStore();
     store.save(