start-command 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # start-command
 
+## 0.22.0
+
+### Minor Changes
+
+- 694d85e: feat: Add shell auto-detection and --shell option for isolation environments
+
+  In docker/ssh and other applicable isolation environments, the shell is now
+  automatically detected in order of preference: `bash` → `zsh` → `sh`.
+
+  Previously, `/bin/sh` was hardcoded in Docker and SSH isolation, which prevented
+  access to tools like `nvm` that require bash. Now, the most feature-complete
+  available shell is used automatically.
+
+  Key features:
+  - Auto-detect best available shell in Docker containers and SSH hosts (`bash > zsh > sh`)
+  - New `--shell` option to force a specific shell (`auto`, `bash`, `zsh`, `sh`)
+  - Default mode is `auto` — no need to specify `--shell` for automatic detection
+  - `--shell` is passed through in isolation stacking
+
+  Example usage:
+
+  ```bash
+  # Auto-detect best shell (default behavior, no option needed)
+  $ --isolated docker --image node:20 -- nvm use 20
+
+  # Force bash explicitly
+  $ --isolated docker --image ubuntu:22.04 --shell bash -- echo $BASH_VERSION
+
+  # Use sh specifically
+  $ --isolated ssh --endpoint user@host --shell sh -- echo hello
+  ```
+
 ## 0.21.0
 
 ### Minor Changes

package/package.json

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

package/src/lib/args-parser.js

@@ -16,6 +16,7 @@
  * --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)
+ * --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)
  * --status <uuid>                  Show status of a previous command execution by UUID
  * --output-format <format>         Output format for status (links-notation, json, text)
@@ -35,6 +36,11 @@ const DEBUG =
  */
 const VALID_BACKENDS = ['screen', 'tmux', 'docker', 'ssh'];
 
+/**
+ * Valid shell options for --shell
+ */
+const VALID_SHELLS = ['auto', 'bash', 'zsh', 'sh'];
+
 /**
  * Maximum depth for isolation stacking
  */
@@ -159,6 +165,7 @@ function parseArgs(args) {
     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
+    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
     outputFormat: null, // Output format for status (links-notation, json, text)
@@ -364,6 +371,24 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  // --shell <shell>
+  if (arg === '--shell') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.shell = args[index + 1].toLowerCase();
+      return 2;
+    } else {
+      throw new Error(
+        `Option ${arg} requires a shell argument (auto, bash, zsh, sh)`
+      );
+    }
+  }
+
+  // --shell=<value>
+  if (arg.startsWith('--shell=')) {
+    options.shell = arg.split('=')[1].toLowerCase();
+    return 1;
+  }
+
   // --use-command-stream
   if (arg === '--use-command-stream') {
     options.useCommandStream = true;
@@ -629,6 +654,15 @@ function validateOptions(options) {
     throw new Error('--output-format option is only valid with --status');
   }
 
+  // Validate shell option
+  if (options.shell !== null && options.shell !== undefined) {
+    if (!VALID_SHELLS.includes(options.shell)) {
+      throw new Error(
+        `Invalid shell: "${options.shell}". Valid options are: ${VALID_SHELLS.join(', ')}`
+      );
+    }
+  }
+
   // Validate session ID is a valid UUID if provided
   if (options.sessionId !== null && options.sessionId !== undefined) {
     if (!isValidUUID(options.sessionId)) {
@@ -693,5 +727,6 @@ module.exports = {
   generateUUID,
   VALID_BACKENDS,
   VALID_OUTPUT_FORMATS,
+  VALID_SHELLS,
   MAX_ISOLATION_DEPTH,
 };

package/src/lib/command-builder.js

@@ -71,6 +71,10 @@ function buildNextLevelCommand(options, command) {
     parts.push('--auto-remove-docker-container');
   }
 
+  if (options.shell && options.shell !== 'auto') {
+    parts.push(`--shell ${options.shell}`);
+  }
+
   // Separator and command
   parts.push('--');
   parts.push(command);

package/src/lib/isolation-log-utils.js

@@ -0,0 +1,147 @@
+/** Log utility functions for isolation runners */
+
+const { spawn } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/**
+ * Generate timestamp for logging
+ * @returns {string} ISO timestamp without 'T' and 'Z'
+ */
+function getTimestamp() {
+  return new Date().toISOString().replace('T', ' ').replace('Z', '');
+}
+
+/**
+ * Generate unique log filename
+ * @param {string} environment - The isolation environment name
+ * @returns {string} Log filename
+ */
+function generateLogFilename(environment) {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).substring(2, 8);
+  return `start-command-${environment}-${timestamp}-${random}.log`;
+}
+
+/**
+ * Create log content header
+ * @param {object} params - Log parameters
+ * @param {string} params.command - The command being executed
+ * @param {string} params.environment - The isolation environment
+ * @param {string} params.mode - attached or detached
+ * @param {string} params.sessionName - Session/container name
+ * @param {string} [params.image] - Docker image (for docker environment)
+ * @param {string} [params.user] - User to run command as (optional)
+ * @param {string} params.startTime - Start timestamp
+ * @returns {string} Log header content
+ */
+function createLogHeader(params) {
+  let content = `=== Start Command Log ===\n`;
+  content += `Timestamp: ${params.startTime}\n`;
+  content += `Command: ${params.command}\n`;
+  content += `Environment: ${params.environment}\n`;
+  content += `Mode: ${params.mode}\n`;
+  content += `Session: ${params.sessionName}\n`;
+  if (params.image) {
+    content += `Image: ${params.image}\n`;
+  }
+  if (params.user) {
+    content += `User: ${params.user}\n`;
+  }
+  content += `Platform: ${process.platform}\n`;
+  content += `Node Version: ${process.version}\n`;
+  content += `Working Directory: ${process.cwd()}\n`;
+  content += `${'='.repeat(50)}\n\n`;
+  return content;
+}
+
+/**
+ * Create log content footer
+ * @param {string} endTime - End timestamp
+ * @param {number} exitCode - Exit code
+ * @returns {string} Log footer content
+ */
+function createLogFooter(endTime, exitCode) {
+  let content = `\n${'='.repeat(50)}\n`;
+  content += `Finished: ${endTime}\n`;
+  content += `Exit Code: ${exitCode}\n`;
+  return content;
+}
+
+/**
+ * Write log file
+ * @param {string} logPath - Path to log file
+ * @param {string} content - Log content
+ * @returns {boolean} Success status
+ */
+function writeLogFile(logPath, content) {
+  try {
+    fs.writeFileSync(logPath, content, 'utf8');
+    return true;
+  } catch (err) {
+    console.error(`\nWarning: Could not save log file: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Get log directory from environment or use system temp
+ * @returns {string} Log directory path
+ */
+function getLogDir() {
+  return process.env.START_LOG_DIR || os.tmpdir();
+}
+
+/**
+ * Create log file path
+ * @param {string} environment - The isolation environment
+ * @returns {string} Full path to log file
+ */
+function createLogPath(environment) {
+  const logDir = getLogDir();
+  const logFilename = generateLogFilename(environment);
+  return path.join(logDir, logFilename);
+}
+
+/**
+ * Run command as an isolated user (without isolation environment)
+ * Uses sudo -u to switch users
+ * @param {string} cmd - Command to execute
+ * @param {string} username - User to run as
+ * @returns {Promise<{success: boolean, message: string, exitCode: number}>}
+ */
+function runAsIsolatedUser(cmd, username) {
+  return new Promise((resolve) => {
+    const child = spawn('sudo', ['-n', '-u', username, 'sh', '-c', cmd], {
+      stdio: 'inherit',
+    });
+
+    child.on('exit', (code) => {
+      resolve({
+        success: code === 0,
+        message: `Command completed as user "${username}" with exit code ${code}`,
+        exitCode: code || 0,
+      });
+    });
+
+    child.on('error', (err) => {
+      resolve({
+        success: false,
+        message: `Failed to run as user "${username}": ${err.message}`,
+        exitCode: 1,
+      });
+    });
+  });
+}
+
+module.exports = {
+  getTimestamp,
+  generateLogFilename,
+  createLogHeader,
+  createLogFooter,
+  writeLogFile,
+  getLogDir,
+  createLogPath,
+  runAsIsolatedUser,
+};

package/src/lib/isolation.js

@@ -116,6 +116,101 @@ function getShell() {
   return { shell, shellArg };
 }
 
+/**
+ * Detect the best available shell in an isolation environment (docker/ssh)
+ * Tries shells in order: bash, zsh, sh
+ * @param {'docker'|'ssh'} environment - Isolation environment type
+ * @param {object} options - Options for the isolation environment
+ * @param {string} [shellPreference='auto'] - Shell preference: 'auto', 'bash', 'zsh', 'sh'
+ * @returns {string} Shell path to use
+ */
+function detectShellInEnvironment(
+  environment,
+  options,
+  shellPreference = 'auto'
+) {
+  // If a specific shell is requested (not auto), use it directly
+  if (shellPreference && shellPreference !== 'auto') {
+    if (DEBUG) {
+      console.log(`[DEBUG] Using forced shell: ${shellPreference}`);
+    }
+    return shellPreference;
+  }
+
+  // In auto mode, try shells in order of preference
+  const shellsToTry = ['bash', 'zsh', 'sh'];
+
+  if (environment === 'docker') {
+    const image = options.image;
+    if (!image) {
+      return 'sh';
+    }
+
+    for (const shell of shellsToTry) {
+      try {
+        const result = spawnSync(
+          'docker',
+          ['run', '--rm', image, 'sh', '-c', `command -v ${shell}`],
+          { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+        );
+        if (result.status === 0 && result.stdout.trim()) {
+          if (DEBUG) {
+            console.log(
+              `[DEBUG] Detected shell in docker image ${image}: ${result.stdout.trim()}`
+            );
+          }
+          return result.stdout.trim();
+        }
+      } catch {
+        // Continue to next shell
+      }
+    }
+
+    if (DEBUG) {
+      console.log(
+        `[DEBUG] Could not detect shell in docker image ${image}, falling back to sh`
+      );
+    }
+    return 'sh';
+  }
+
+  if (environment === 'ssh') {
+    const endpoint = options.endpoint;
+    if (!endpoint) {
+      return 'sh';
+    }
+
+    try {
+      // Run a single SSH command to check for available shells in order
+      const checkCmd = shellsToTry.map((s) => `command -v ${s}`).join(' || ');
+      const result = spawnSync('ssh', [endpoint, checkCmd], {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      if (result.status === 0 && result.stdout.trim()) {
+        const detected = result.stdout.trim();
+        if (DEBUG) {
+          console.log(
+            `[DEBUG] Detected shell on SSH host ${endpoint}: ${detected}`
+          );
+        }
+        return detected;
+      }
+    } catch {
+      // Fall through to default
+    }
+
+    if (DEBUG) {
+      console.log(
+        `[DEBUG] Could not detect shell on SSH host ${endpoint}, falling back to sh`
+      );
+    }
+    return 'sh';
+  }
+
+  return 'sh';
+}
+
 /**
  * Check if the current process has a TTY attached
  * @returns {boolean} True if TTY is available
@@ -553,15 +648,25 @@ function runInSsh(command, options = {}) {
   const sessionName = options.session || generateSessionName('ssh');
   const sshTarget = options.endpoint;
 
+  // Detect the shell to use on the remote host
+  // In auto mode, detection may fall back to passing command directly to leverage
+  // the remote user's default login shell (which may already be bash)
+  const shellToUse = detectShellInEnvironment('ssh', options, options.shell);
+  // Whether to wrap command with a shell (only when explicit shell is specified)
+  const useExplicitShell =
+    options.shell && options.shell !== 'auto' ? shellToUse : null;
+
   try {
     if (options.detached) {
       // Detached mode: Run command in background on remote server using nohup
       // The command will continue running even after SSH connection closes
-      const remoteCommand = `nohup ${command} > /tmp/${sessionName}.log 2>&1 &`;
+      const remoteShell = useExplicitShell || shellToUse;
+      const remoteCommand = `nohup ${remoteShell} -c ${JSON.stringify(command)} > /tmp/${sessionName}.log 2>&1 &`;
       const sshArgs = [sshTarget, remoteCommand];
 
       if (DEBUG) {
         console.log(`[DEBUG] Running: ssh ${sshArgs.join(' ')}`);
+        console.log(`[DEBUG] shell: ${remoteShell}`);
       }
 
       const result = spawnSync('ssh', sshArgs, {
@@ -579,11 +684,15 @@ function runInSsh(command, options = {}) {
       });
     } else {
       // Attached mode: Run command interactively over SSH
-      // This creates a direct SSH connection and runs the command
-      const sshArgs = [sshTarget, command];
+      // When a specific shell is requested, wrap the command with that shell.
+      // In auto mode, pass the command directly and let the remote's default shell handle it.
+      const sshArgs = useExplicitShell
+        ? [sshTarget, useExplicitShell, '-c', command]
+        : [sshTarget, command];
 
       if (DEBUG) {
         console.log(`[DEBUG] Running: ssh ${sshArgs.join(' ')}`);
+        console.log(`[DEBUG] shell: ${shellToUse}`);
       }
 
       return new Promise((resolve) => {
@@ -660,6 +769,9 @@ function runInDocker(command, options = {}) {
     }
   }
 
+  // Detect the shell to use in the container
+  const shellToUse = detectShellInEnvironment('docker', options, options.shell);
+
   // Print the user command (this appears after any virtual commands like docker pull)
   const { createCommandLine } = require('./output-blocks');
   console.log(createCommandLine(command));
@@ -674,7 +786,7 @@ function runInDocker(command, options = {}) {
 
       if (options.keepAlive) {
         // With keep-alive: run command, then keep shell alive
-        effectiveCommand = `${command}; exec /bin/sh`;
+        effectiveCommand = `${command}; exec ${shellToUse}`;
       }
       // Without keep-alive: container exits naturally when command completes
 
@@ -691,10 +803,11 @@ function runInDocker(command, options = {}) {
         dockerArgs.push('--user', options.user);
       }
 
-      dockerArgs.push(options.image, '/bin/sh', '-c', effectiveCommand);
+      dockerArgs.push(options.image, shellToUse, '-c', effectiveCommand);
 
       if (DEBUG) {
         console.log(`[DEBUG] Running: docker ${dockerArgs.join(' ')}`);
+        console.log(`[DEBUG] shell: ${shellToUse}`);
         console.log(`[DEBUG] keepAlive: ${options.keepAlive || false}`);
         console.log(
           `[DEBUG] autoRemoveDockerContainer: ${options.autoRemoveDockerContainer || false}`
@@ -735,7 +848,11 @@ function runInDocker(command, options = {}) {
         dockerArgs.push('--user', options.user);
       }
 
-      dockerArgs.push(options.image, '/bin/sh', '-c', command);
+      if (DEBUG) {
+        console.log(`[DEBUG] shell: ${shellToUse}`);
+      }
+
+      dockerArgs.push(options.image, shellToUse, '-c', command);
 
       if (DEBUG) {
         console.log(`[DEBUG] Running: docker ${dockerArgs.join(' ')}`);
@@ -825,105 +942,6 @@ function runIsolated(backend, command, options = {}) {
   }
 }
 
-/**
- * Generate timestamp for logging
- * @returns {string} ISO timestamp without 'T' and 'Z'
- */
-function getTimestamp() {
-  return new Date().toISOString().replace('T', ' ').replace('Z', '');
-}
-
-/**
- * Generate unique log filename
- * @param {string} environment - The isolation environment name
- * @returns {string} Log filename
- */
-function generateLogFilename(environment) {
-  const timestamp = Date.now();
-  const random = Math.random().toString(36).substring(2, 8);
-  return `start-command-${environment}-${timestamp}-${random}.log`;
-}
-
-/**
- * Create log content header
- * @param {object} params - Log parameters
- * @param {string} params.command - The command being executed
- * @param {string} params.environment - The isolation environment
- * @param {string} params.mode - attached or detached
- * @param {string} params.sessionName - Session/container name
- * @param {string} [params.image] - Docker image (for docker environment)
- * @param {string} [params.user] - User to run command as (optional)
- * @param {string} params.startTime - Start timestamp
- * @returns {string} Log header content
- */
-function createLogHeader(params) {
-  let content = `=== Start Command Log ===\n`;
-  content += `Timestamp: ${params.startTime}\n`;
-  content += `Command: ${params.command}\n`;
-  content += `Environment: ${params.environment}\n`;
-  content += `Mode: ${params.mode}\n`;
-  content += `Session: ${params.sessionName}\n`;
-  if (params.image) {
-    content += `Image: ${params.image}\n`;
-  }
-  if (params.user) {
-    content += `User: ${params.user}\n`;
-  }
-  content += `Platform: ${process.platform}\n`;
-  content += `Node Version: ${process.version}\n`;
-  content += `Working Directory: ${process.cwd()}\n`;
-  content += `${'='.repeat(50)}\n\n`;
-  return content;
-}
-
-/**
- * Create log content footer
- * @param {string} endTime - End timestamp
- * @param {number} exitCode - Exit code
- * @returns {string} Log footer content
- */
-function createLogFooter(endTime, exitCode) {
-  let content = `\n${'='.repeat(50)}\n`;
-  content += `Finished: ${endTime}\n`;
-  content += `Exit Code: ${exitCode}\n`;
-  return content;
-}
-
-/**
- * Write log file
- * @param {string} logPath - Path to log file
- * @param {string} content - Log content
- * @returns {boolean} Success status
- */
-function writeLogFile(logPath, content) {
-  try {
-    fs.writeFileSync(logPath, content, 'utf8');
-    return true;
-  } catch (err) {
-    console.error(`\nWarning: Could not save log file: ${err.message}`);
-    return false;
-  }
-}
-
-/**
- * Get log directory from environment or use system temp
- * @returns {string} Log directory path
- */
-function getLogDir() {
-  return process.env.START_LOG_DIR || os.tmpdir();
-}
-
-/**
- * Create log file path
- * @param {string} environment - The isolation environment
- * @returns {string} Full path to log file
- */
-function createLogPath(environment) {
-  const logDir = getLogDir();
-  const logFilename = generateLogFilename(environment);
-  return path.join(logDir, logFilename);
-}
-
 /**
  * Reset screen version cache (useful for testing)
  */
@@ -932,36 +950,17 @@ function resetScreenVersionCache() {
   screenVersionChecked = false;
 }
 
-/**
- * Run command as an isolated user (without isolation environment)
- * Uses sudo -u to switch users
- * @param {string} cmd - Command to execute
- * @param {string} username - User to run as
- * @returns {Promise<{success: boolean, message: string, exitCode: number}>}
- */
-function runAsIsolatedUser(cmd, username) {
-  return new Promise((resolve) => {
-    const child = spawn('sudo', ['-n', '-u', username, 'sh', '-c', cmd], {
-      stdio: 'inherit',
-    });
-
-    child.on('exit', (code) => {
-      resolve({
-        success: code === 0,
-        message: `Command completed as user "${username}" with exit code ${code}`,
-        exitCode: code || 0,
-      });
-    });
-
-    child.on('error', (err) => {
-      resolve({
-        success: false,
-        message: `Failed to run as user "${username}": ${err.message}`,
-        exitCode: 1,
-      });
-    });
-  });
-}
+// Log utilities and runAsIsolatedUser extracted to isolation-log-utils.js
+const {
+  getTimestamp,
+  generateLogFilename,
+  createLogHeader,
+  createLogFooter,
+  writeLogFile,
+  getLogDir,
+  createLogPath,
+  runAsIsolatedUser,
+} = require('./isolation-log-utils');
 
 // Re-export docker utilities from docker-utils for backwards compatibility
 const {
@@ -972,6 +971,7 @@ const {
 module.exports = {
   isCommandAvailable,
   hasTTY,
+  detectShellInEnvironment,
   runInScreen,
   runInTmux,
   runInDocker,

package/test/args-parser-shell.test.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env bun
+/**
+ * Unit tests for shell option in the argument parser
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const { parseArgs, VALID_SHELLS } = require('../src/lib/args-parser');
+
+describe('shell option', () => {
+  it('should default shell to auto', () => {
+    const result = parseArgs(['echo', 'hello']);
+    assert.strictEqual(result.wrapperOptions.shell, 'auto');
+  });
+
+  it('should parse --shell bash', () => {
+    const result = parseArgs([
+      '--isolated',
+      'docker',
+      '--shell',
+      'bash',
+      '--',
+      'npm',
+      'test',
+    ]);
+    assert.strictEqual(result.wrapperOptions.shell, 'bash');
+  });
+
+  it('should parse --shell zsh', () => {
+    const result = parseArgs([
+      '--isolated',
+      'docker',
+      '--shell',
+      'zsh',
+      '--',
+      'npm',
+      'test',
+    ]);
+    assert.strictEqual(result.wrapperOptions.shell, 'zsh');
+  });
+
+  it('should parse --shell sh', () => {
+    const result = parseArgs([
+      '--isolated',
+      'docker',
+      '--shell',
+      'sh',
+      '--',
+      'npm',
+      'test',
+    ]);
+    assert.strictEqual(result.wrapperOptions.shell, 'sh');
+  });
+
+  it('should parse --shell auto', () => {
+    const result = parseArgs([
+      '--isolated',
+      'docker',
+      '--shell',
+      'auto',
+      '--',
+      'npm',
+      'test',
+    ]);
+    assert.strictEqual(result.wrapperOptions.shell, 'auto');
+  });
+
+  it('should parse --shell=value format', () => {
+    const result = parseArgs([
+      '--isolated',
+      'docker',
+      '--shell=bash',
+      '--',
+      'npm',
+      'test',
+    ]);
+    assert.strictEqual(result.wrapperOptions.shell, 'bash');
+  });
+
+  it('should normalize shell to lowercase', () => {
+    const result = parseArgs([
+      '--isolated',
+      'docker',
+      '--shell',
+      'BASH',
+      '--',
+      'npm',
+      'test',
+    ]);
+    assert.strictEqual(result.wrapperOptions.shell, 'bash');
+  });
+
+  it('should throw error for missing shell argument', () => {
+    assert.throws(() => {
+      parseArgs(['--isolated', 'docker', '--shell']);
+    }, /requires a shell argument/);
+  });
+
+  it('should throw error for invalid shell', () => {
+    assert.throws(() => {
+      parseArgs([
+        '--isolated',
+        'docker',
+        '--shell',
+        'fish',
+        '--',
+        'echo',
+        'hi',
+      ]);
+    }, /Invalid shell/);
+  });
+
+  it('should list valid shells in error message', () => {
+    try {
+      parseArgs([
+        '--isolated',
+        'docker',
+        '--shell',
+        'invalid',
+        '--',
+        'echo',
+        'test',
+      ]);
+      assert.fail('Should have thrown an error');
+    } catch (err) {
+      for (const shell of VALID_SHELLS) {
+        assert.ok(err.message.includes(shell), `Error should mention ${shell}`);
+      }
+    }
+  });
+
+  it('should work with ssh isolation', () => {
+    const result = parseArgs([
+      '--isolated',
+      'ssh',
+      '--endpoint',
+      'user@host',
+      '--shell',
+      'bash',
+      '--',
+      'echo',
+      'hi',
+    ]);
+    assert.strictEqual(result.wrapperOptions.shell, 'bash');
+    assert.strictEqual(result.wrapperOptions.isolated, 'ssh');
+  });
+});
+
+describe('VALID_SHELLS', () => {
+  it('should include bash', () => {
+    assert.ok(VALID_SHELLS.includes('bash'));
+  });
+
+  it('should include zsh', () => {
+    assert.ok(VALID_SHELLS.includes('zsh'));
+  });
+
+  it('should include sh', () => {
+    assert.ok(VALID_SHELLS.includes('sh'));
+  });
+
+  it('should include auto', () => {
+    assert.ok(VALID_SHELLS.includes('auto'));
+  });
+});

package/test/args-parser.test.js

@@ -927,3 +927,5 @@ describe('cleanup options', () => {
     assert.strictEqual(result.wrapperOptions.cleanupDryRun, false);
   });
 });
+
+// Shell option tests moved to args-parser-shell.test.js

package/test/isolation.test.js

@@ -10,6 +10,7 @@ const assert = require('assert');
 const {
   isCommandAvailable,
   hasTTY,
+  detectShellInEnvironment,
   getScreenVersion,
   supportsLogfileOption,
   resetScreenVersionCache,
@@ -761,3 +762,66 @@ describe('Default Docker Image Detection', () => {
     });
   });
 });
+
+describe('detectShellInEnvironment', () => {
+  it('should return the forced shell when shellPreference is not auto', () => {
+    const result = detectShellInEnvironment(
+      'docker',
+      { image: 'alpine:latest' },
+      'bash'
+    );
+    assert.strictEqual(result, 'bash');
+  });
+
+  it('should return zsh when shellPreference is zsh', () => {
+    const result = detectShellInEnvironment(
+      'ssh',
+      { endpoint: 'user@host' },
+      'zsh'
+    );
+    assert.strictEqual(result, 'zsh');
+  });
+
+  it('should return sh when shellPreference is sh', () => {
+    const result = detectShellInEnvironment(
+      'docker',
+      { image: 'alpine:latest' },
+      'sh'
+    );
+    assert.strictEqual(result, 'sh');
+  });
+
+  it('should return sh fallback when docker image is not provided', () => {
+    const result = detectShellInEnvironment('docker', {}, 'auto');
+    assert.strictEqual(result, 'sh');
+  });
+
+  it('should return sh fallback when ssh endpoint is not provided', () => {
+    const result = detectShellInEnvironment('ssh', {}, 'auto');
+    assert.strictEqual(result, 'sh');
+  });
+
+  it('should return sh fallback for unknown environment', () => {
+    const result = detectShellInEnvironment('screen', {}, 'auto');
+    assert.strictEqual(result, 'sh');
+  });
+
+  it('should auto-detect shell in docker if docker is available', () => {
+    if (!isCommandAvailable('docker')) {
+      console.log('  Skipping: docker not installed');
+      return;
+    }
+    // Use alpine:latest which is commonly available and has sh
+    // This test just verifies we get a valid shell back
+    const result = detectShellInEnvironment(
+      'docker',
+      { image: 'alpine:latest' },
+      'auto'
+    );
+    assert.ok(
+      ['bash', 'zsh', 'sh'].includes(result),
+      `Expected a valid shell (bash/zsh/sh), got: ${result}`
+    );
+    console.log(`  Detected shell in alpine:latest: ${result}`);
+  });
+});

package/test/user-manager.test.js

@@ -217,7 +217,7 @@ describe('args-parser user isolation options', () => {
           'npm',
           'test',
         ]);
-      }, /--isolated-user is not supported with Docker isolation/);
+      }, /--isolated-user is not supported with Docker as the first isolation level/);
     });
 
     it('should validate custom username format', () => {