start-command 0.27.2 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # start-command
 
+## 0.29.0
+
+### Minor Changes
+
+- Add Docker isolation runtime controls: `--volume`/`-v`, `--mount`, `--env`/`-e`, and `--privileged`. These are threaded into the underlying `docker run` invocation and recorded in `--status`/`--list` metadata, allowing callers to mount tool credentials, pass environment variables, and run Docker-in-Docker images without wrapping `docker run` themselves.
+
+  Add `--isolation` as an alias for `--isolated` and fail fast on unknown wrapper options.
+
+## 0.28.0
+
+### Minor Changes
+
+- 38d1fe4: Add `--upload-log <id>` to upload a stored execution log with `gh-upload-log`, installing the uploader on demand when it is missing.
+
 ## 0.27.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.27.2",
+  "version": "0.29.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

@@ -22,6 +22,8 @@ const {
   appendLogFile,
   createLogPath,
   getDefaultDockerImage,
+  buildDockerRuntimeStatusLines,
+  buildDockerRuntimeMetadata,
 } = require('../lib/isolation');
 const {
   createIsolatedUser,
@@ -33,6 +35,7 @@ const { handleFailure } = require('../lib/failure-handler');
 const { ExecutionStore, ExecutionRecord } = require('../lib/execution-store');
 const { queryStatus, listExecutions } = require('../lib/status-formatter');
 const { ControlAction, controlExecution } = require('../lib/execution-control');
+const { uploadExecutionLog } = require('../lib/log-uploader');
 const { printVersion } = require('../lib/version');
 const { createStartBlock, createFinishBlock } = require('../lib/output-blocks');
 const { runWithBunSpawn, runWithNodeSpawn } = require('../lib/spawn-helpers');
@@ -201,6 +204,12 @@ if (wrapperOptions.list) {
   process.exit(0);
 }
 
+// Handle --upload-log flag
+if (wrapperOptions.uploadLog) {
+  const exitCode = handleUploadLogQuery(wrapperOptions.uploadLog);
+  process.exit(exitCode);
+}
+
 // Handle --stop flag
 if (wrapperOptions.stop !== null && wrapperOptions.stop !== undefined) {
   handleControlQuery(wrapperOptions.stop, ControlAction.STOP);
@@ -300,6 +309,16 @@ function handleListQuery(outputFormat) {
   }
 }
 
+function handleUploadLogQuery(identifier) {
+  const result = uploadExecutionLog(getExecutionStore(), identifier);
+  if (result.success) {
+    return result.exitCode || 0;
+  }
+
+  console.error(`Error: ${result.error}`);
+  return result.exitCode || 1;
+}
+
 function handleControlQuery(identifier, action) {
   const result = controlExecution(getExecutionStore(), identifier, action);
   if (result.success) {
@@ -453,6 +472,7 @@ async function runWithIsolation(
   if (effectiveImage) {
     extraLines.push(`[Isolation] Image: ${effectiveImage}`);
   }
+  extraLines.push(...buildDockerRuntimeStatusLines(options));
   if (options.endpoint) {
     extraLines.push(`[Isolation] Endpoint: ${options.endpoint}`);
   }
@@ -479,6 +499,7 @@ async function runWithIsolation(
         isolationMode: mode,
         sessionName,
         image: effectiveImage,
+        ...buildDockerRuntimeMetadata(options),
         endpoint: options.endpoint,
         user: options.user,
         keepAlive: options.keepAlive,
@@ -553,6 +574,10 @@ async function runWithIsolation(
       user: createdUser,
       keepAlive: options.keepAlive,
       autoRemoveDockerContainer: options.autoRemoveDockerContainer,
+      volumes: options.volumes,
+      mounts: options.mounts,
+      env: options.env,
+      privileged: options.privileged,
       shell: options.shell,
       logPath: logFilePath,
     });

package/src/lib/args-parser.js

@@ -6,11 +6,15 @@
  * 2. $ [wrapper-options] command [command-options]
  *
  * Wrapper Options:
- * --isolated, -i <backend>         Run in isolated environment (screen, tmux, docker, ssh)
+ * --isolated, --isolation, -i <backend> Run in isolated environment (screen, tmux, docker, ssh)
  * --attached, -a                   Run in attached mode (foreground)
  * --detached, -d                   Run in detached mode (background)
  * --session, -s <name>             Session name for isolation
  * --image <image>                  Docker image (optional, defaults to OS-matched image)
+ * --volume, -v <host:container[:mode]> Docker bind mount/volume (repeatable, docker only)
+ * --mount <mount-spec>             Docker --mount spec (repeatable, docker only)
+ * --env, -e <KEY=VALUE>            Environment variable for docker container (repeatable, docker only)
+ * --privileged                     Run docker container in privileged mode (docker only)
  * --endpoint <endpoint>            SSH endpoint (required for ssh isolation, e.g., user@host)
  * --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)
@@ -21,6 +25,7 @@
  * --verbose                        Enable verbose/debug output (sets START_VERBOSE=1)
  * --status <uuid>                  Show status of a previous command execution by UUID
  * --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
  * --terminate <uuid-or-session-name> Terminate a detached execution immediately
@@ -166,6 +171,10 @@ function parseArgs(args) {
     sessionId: null, // Session ID (UUID) for tracking - auto-generated if not provided
     image: null, // Docker image (current level)
     imageStack: null, // Docker images for each level (with nulls for non-docker levels)
+    volumes: [], // Docker bind mounts/volumes (-v/--volume), applied to docker levels
+    mounts: [], // Docker --mount specs, applied to docker levels
+    env: [], // Docker environment variables (-e/--env, KEY=VALUE), applied to docker levels
+    privileged: false, // Run docker container in privileged mode
     endpoint: null, // SSH endpoint (current level, e.g., user@host)
     endpointStack: null, // SSH endpoints for each level (with nulls for non-ssh levels)
     user: false, // Create isolated user
@@ -177,6 +186,7 @@ function parseArgs(args) {
     useCommandStream: false, // Use command-stream library for command execution
     status: null, // UUID to show status for
     list: false, // List all tracked execution records
+    uploadLog: null, // UUID/session name whose stored log should be uploaded
     outputFormat: null, // Output format for status/list (links-notation, json, text)
     stop: null, // UUID/session name to stop gracefully
     terminate: null, // UUID/session name to terminate immediately
@@ -204,9 +214,7 @@ function parseArgs(args) {
       if (arg.startsWith('-')) {
         const consumed = parseOption(args, i, wrapperOptions);
         if (consumed === 0) {
-          // Unknown option, treat rest as command
-          commandArgs = args.slice(i);
-          break;
+          throw new Error(`Unknown wrapper option: ${arg}`);
         }
         i += consumed;
       } else {
@@ -237,6 +245,9 @@ function parseWrapperArgs(args, options) {
   while (i < args.length) {
     const consumed = parseOption(args, i, options);
     if (consumed === 0) {
+      if (args[i].startsWith('-')) {
+        throw new Error(`Unknown wrapper option: ${args[i]}`);
+      }
       if (DEBUG) {
         console.warn(`Unknown wrapper option: ${args[i]}`);
       }
@@ -257,8 +268,8 @@ function parseWrapperArgs(args, options) {
 function parseOption(args, index, options) {
   const arg = args[index];
 
-  // --isolated or -i
-  if (arg === '--isolated' || arg === '-i') {
+  // --isolated, --isolation, or -i
+  if (arg === '--isolated' || arg === '--isolation' || arg === '-i') {
     if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
       const value = args[index + 1];
       parseIsolatedValue(value, options);
@@ -270,8 +281,8 @@ function parseOption(args, index, options) {
     }
   }
 
-  // --isolated=<value>
-  if (arg.startsWith('--isolated=')) {
+  // --isolated=<value> or --isolation=<value>
+  if (arg.startsWith('--isolated=') || arg.startsWith('--isolation=')) {
     const value = arg.split('=')[1];
     parseIsolatedValue(value, options);
     return 1;
@@ -323,6 +334,62 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  // --volume or -v (for docker) - repeatable bind mount / volume
+  if (arg === '--volume' || arg === '-v') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.volumes.push(args[index + 1]);
+      return 2;
+    } else {
+      throw new Error(
+        `Option ${arg} requires a volume argument (host:container[:mode])`
+      );
+    }
+  }
+
+  // --volume=<value> or -v=<value>
+  if (arg.startsWith('--volume=') || arg.startsWith('-v=')) {
+    options.volumes.push(arg.slice(arg.indexOf('=') + 1));
+    return 1;
+  }
+
+  // --mount (for docker) - repeatable mount spec
+  if (arg === '--mount') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.mounts.push(args[index + 1]);
+      return 2;
+    } else {
+      throw new Error(`Option ${arg} requires a mount spec argument`);
+    }
+  }
+
+  // --mount=<value>
+  if (arg.startsWith('--mount=')) {
+    options.mounts.push(arg.slice('--mount='.length));
+    return 1;
+  }
+
+  // --env or -e (for docker) - repeatable environment variable
+  if (arg === '--env' || arg === '-e') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.env.push(args[index + 1]);
+      return 2;
+    } else {
+      throw new Error(`Option ${arg} requires a KEY=VALUE argument`);
+    }
+  }
+
+  // --env=<value> or -e=<value>
+  if (arg.startsWith('--env=') || arg.startsWith('-e=')) {
+    options.env.push(arg.slice(arg.indexOf('=') + 1));
+    return 1;
+  }
+
+  // --privileged (for docker)
+  if (arg === '--privileged') {
+    options.privileged = true;
+    return 1;
+  }
+
   // --endpoint (for ssh) - supports sequence for stacked isolation
   if (arg === '--endpoint') {
     if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
@@ -450,6 +517,28 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  // --upload-log <uuid-or-session-name>
+  if (arg === '--upload-log') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.uploadLog = args[index + 1];
+      return 2;
+    } else {
+      throw new Error(`Option ${arg} requires a UUID or session name argument`);
+    }
+  }
+
+  // --upload-log=<value>
+  if (arg.startsWith('--upload-log=')) {
+    const value = arg.slice('--upload-log='.length);
+    if (!value) {
+      throw new Error(
+        `Option --upload-log requires a UUID or session name argument`
+      );
+    }
+    options.uploadLog = value;
+    return 1;
+  }
+
   // --stop <uuid-or-session-name>
   if (arg === '--stop') {
     if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
@@ -531,6 +620,35 @@ function parseOption(args, index, options) {
   return 0;
 }
 
+/**
+ * Throw if docker runtime options (--volume, --mount, --env, --privileged)
+ * are present but the isolation configuration does not include docker.
+ * @param {object} options - Parsed options
+ * @throws {Error} If a docker-only option is set without docker isolation
+ */
+function validateDockerRuntimeOptionsRequireDocker(options) {
+  if (options.volumes && options.volumes.length > 0) {
+    throw new Error(
+      '--volume option is only valid when isolation stack includes docker'
+    );
+  }
+  if (options.mounts && options.mounts.length > 0) {
+    throw new Error(
+      '--mount option is only valid when isolation stack includes docker'
+    );
+  }
+  if (options.env && options.env.length > 0) {
+    throw new Error(
+      '--env option is only valid when isolation stack includes docker'
+    );
+  }
+  if (options.privileged) {
+    throw new Error(
+      '--privileged option is only valid when isolation stack includes docker'
+    );
+  }
+}
+
 /**
  * Validate parsed options
  * @param {object} options - Parsed options
@@ -653,6 +771,11 @@ function validateOptions(options) {
       );
     }
 
+    // Docker runtime options (--volume, --mount, --env, --privileged) require docker
+    if (!stack.includes('docker')) {
+      validateDockerRuntimeOptionsRequireDocker(options);
+    }
+
     // User isolation is not supported with Docker as first level
     if (options.user && currentBackend === 'docker') {
       throw new Error(
@@ -677,6 +800,7 @@ function validateOptions(options) {
         '--endpoint option is only valid when isolation stack includes ssh'
       );
     }
+    validateDockerRuntimeOptionsRequireDocker(options);
   }
 
   // Session name is only valid with isolation
@@ -724,6 +848,7 @@ function validateOptions(options) {
   const queryModes = [
     hasValue(options.status),
     options.list,
+    hasValue(options.uploadLog),
     hasValue(options.stop),
     hasValue(options.terminate),
     options.cleanup,
@@ -731,7 +856,7 @@ function validateOptions(options) {
 
   if (queryModes > 1) {
     throw new Error(
-      'Cannot combine --status, --list, --stop, --terminate, or --cleanup in the same invocation'
+      'Cannot combine --status, --list, --upload-log, --stop, --terminate, or --cleanup in the same invocation'
     );
   }
 

package/src/lib/command-builder.js

@@ -54,6 +54,23 @@ function buildNextLevelCommand(options, command) {
     }
   }
 
+  // Docker runtime options are flat (not per-level); forward them only when a
+  // remaining level still uses docker so the nested $ invocation can apply them.
+  if (remainingStack.includes('docker')) {
+    for (const volume of options.volumes || []) {
+      parts.push(`--volume "${volume}"`);
+    }
+    for (const mount of options.mounts || []) {
+      parts.push(`--mount "${mount}"`);
+    }
+    for (const envVar of options.env || []) {
+      parts.push(`--env "${envVar}"`);
+    }
+    if (options.privileged) {
+      parts.push('--privileged');
+    }
+  }
+
   // Pass through global flags
   if (options.detached) {
     parts.push('--detached');

package/src/lib/isolation.js

@@ -486,10 +486,75 @@ const {
   canRunLinuxDockerImages,
 } = require('./docker-utils');
 
+/**
+ * Build the docker run runtime argument list contributed by configurable
+ * container options: privileged mode, environment variables, volumes/bind
+ * mounts, and --mount specs. Returned in a stable order so they can be spliced
+ * into the `docker run` argv before the image name.
+ * @param {object} options - Options (privileged, env, volumes, mounts)
+ * @returns {string[]} Docker CLI arguments
+ */
+function buildDockerRuntimeArgs(options = {}) {
+  const args = [];
+  if (options.privileged) {
+    args.push('--privileged');
+  }
+  for (const envVar of options.env || []) {
+    args.push('-e', envVar);
+  }
+  for (const volume of options.volumes || []) {
+    args.push('-v', volume);
+  }
+  for (const mount of options.mounts || []) {
+    args.push('--mount', mount);
+  }
+  return args;
+}
+
+/**
+ * Build the human-readable `[Isolation]` status lines for docker runtime
+ * options (volumes, mounts, env, privileged). Empty collections and a falsy
+ * privileged flag contribute no lines.
+ * @param {object} options - Options (volumes, mounts, env, privileged)
+ * @returns {string[]} Status lines for the start block / log header
+ */
+function buildDockerRuntimeStatusLines(options = {}) {
+  const lines = [];
+  if (options.volumes && options.volumes.length > 0) {
+    lines.push(`[Isolation] Volumes: ${options.volumes.join(', ')}`);
+  }
+  if (options.mounts && options.mounts.length > 0) {
+    lines.push(`[Isolation] Mounts: ${options.mounts.join(', ')}`);
+  }
+  if (options.env && options.env.length > 0) {
+    lines.push(`[Isolation] Env: ${options.env.join(', ')}`);
+  }
+  if (options.privileged) {
+    lines.push(`[Isolation] Privileged: true`);
+  }
+  return lines;
+}
+
+/**
+ * Build the execution-record metadata for docker runtime options, normalizing
+ * empty collections and a falsy privileged flag to `null`.
+ * @param {object} options - Options (volumes, mounts, env, privileged)
+ * @returns {{volumes: ?string[], mounts: ?string[], env: ?string[], privileged: ?boolean}}
+ */
+function buildDockerRuntimeMetadata(options = {}) {
+  return {
+    volumes:
+      options.volumes && options.volumes.length > 0 ? options.volumes : null,
+    mounts: options.mounts && options.mounts.length > 0 ? options.mounts : null,
+    env: options.env && options.env.length > 0 ? options.env : null,
+    privileged: options.privileged || null,
+  };
+}
+
 /**
  * Run command in Docker container
  * @param {string} command - Command to execute
- * @param {object} options - Options (image, session/name, detached, user, keepAlive, autoRemoveDockerContainer)
+ * @param {object} options - Options (image, session/name, detached, user, keepAlive, autoRemoveDockerContainer, volumes, mounts, env, privileged)
  * @returns {Promise<{success: boolean, containerName: string, message: string}>}
  */
 function runInDocker(command, options = {}) {
@@ -558,6 +623,8 @@ function runInDocker(command, options = {}) {
         dockerArgs.push('--user', options.user);
       }
 
+      dockerArgs.push(...buildDockerRuntimeArgs(options));
+
       const effectiveCommand = options.keepAlive
         ? `${command}; exec ${shellToUse}`
         : command;
@@ -640,6 +707,7 @@ function runInDocker(command, options = {}) {
       if (options.user) {
         dockerArgs.push('--user', options.user);
       }
+      dockerArgs.push(...buildDockerRuntimeArgs(options));
       if (DEBUG) {
         console.log(`[DEBUG] shell: ${shellToUse}`);
       }
@@ -784,6 +852,9 @@ module.exports = {
   runInScreen,
   runInTmux,
   runInDocker,
+  buildDockerRuntimeArgs,
+  buildDockerRuntimeStatusLines,
+  buildDockerRuntimeMetadata,
   runInSsh,
   runIsolated,
   runAsIsolatedUser,

package/src/lib/log-uploader.js

@@ -0,0 +1,192 @@
+/**
+ * Helpers for uploading stored execution logs with gh-upload-log.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function isExecutable(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isCommandFile(filePath) {
+  if (process.platform === 'win32') {
+    return fs.existsSync(filePath);
+  }
+
+  return isExecutable(filePath);
+}
+
+function getPathCommandNames(commandName) {
+  if (process.platform !== 'win32' || path.extname(commandName)) {
+    return [commandName];
+  }
+
+  const extensions = (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
+    .split(';')
+    .filter(Boolean);
+
+  return [commandName, ...extensions.map((ext) => `${commandName}${ext}`)];
+}
+
+function resolveCommandFromPath(commandName) {
+  const pathValue = process.env.PATH || '';
+  for (const pathEntry of pathValue.split(path.delimiter)) {
+    if (!pathEntry) {
+      continue;
+    }
+
+    const directory = pathEntry.replace(/^"|"$/g, '');
+    for (const candidateName of getPathCommandNames(commandName)) {
+      const candidate = path.join(directory, candidateName);
+      if (isCommandFile(candidate)) {
+        return candidate;
+      }
+    }
+  }
+
+  return null;
+}
+
+function resolveCommand(commandName) {
+  const isWindows = process.platform === 'win32';
+  const lookupCommand = isWindows ? 'where' : 'which';
+  const pathMatch = resolveCommandFromPath(commandName);
+  if (pathMatch) {
+    return pathMatch;
+  }
+
+  try {
+    const result = spawnSync(lookupCommand, [commandName], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (result.status === 0 && result.stdout.trim()) {
+      return result.stdout.trim().split(/\r?\n/)[0];
+    }
+  } catch {
+    // Fall through to common locations.
+  }
+
+  if (!isWindows && commandName === 'gh-upload-log') {
+    const bunGlobalPath = path.join(os.homedir(), '.bun', 'bin', commandName);
+    if (isExecutable(bunGlobalPath)) {
+      return bunGlobalPath;
+    }
+  }
+
+  return null;
+}
+
+function shouldRunThroughShell(command) {
+  return process.platform === 'win32' && /\.(cmd|bat)$/i.test(command);
+}
+
+function runCommand(command, args, options = {}) {
+  return spawnSync(command, args, {
+    ...options,
+    shell: shouldRunThroughShell(command),
+  });
+}
+
+function runInstall(command, displayName, args) {
+  console.log(
+    `gh-upload-log not found; installing with: ${displayName} ${args.join(' ')}`
+  );
+  const result = runCommand(command, args, { stdio: 'inherit' });
+  return result.status === 0;
+}
+
+function ensureGhUploadLogAvailable() {
+  const existing = resolveCommand('gh-upload-log');
+  if (existing) {
+    return { success: true, command: existing };
+  }
+
+  const installers = [
+    ['bun', ['install', '-g', 'gh-upload-log']],
+    ['npm', ['install', '-g', 'gh-upload-log']],
+  ];
+
+  for (const [command, args] of installers) {
+    const installer = resolveCommand(command);
+    if (!installer) {
+      continue;
+    }
+    if (runInstall(installer, command, args)) {
+      const installed = resolveCommand('gh-upload-log');
+      if (installed) {
+        return { success: true, command: installed };
+      }
+    }
+  }
+
+  return {
+    success: false,
+    error:
+      'gh-upload-log is not installed and automatic installation did not make it available on PATH.',
+  };
+}
+
+function uploadLogPath(logPath) {
+  if (!logPath) {
+    return {
+      success: false,
+      error: 'Execution record does not have a log path.',
+    };
+  }
+  if (!fs.existsSync(logPath)) {
+    return { success: false, error: `Log file not found: ${logPath}` };
+  }
+
+  const availability = ensureGhUploadLogAvailable();
+  if (!availability.success) {
+    return availability;
+  }
+
+  const result = runCommand(availability.command, [logPath], {
+    stdio: 'inherit',
+  });
+
+  const exitCode =
+    result.status !== null && result.status !== undefined ? result.status : 1;
+  if (exitCode !== 0) {
+    return {
+      success: false,
+      exitCode,
+      error: `gh-upload-log exited with code ${exitCode}`,
+    };
+  }
+
+  return { success: true, exitCode: 0 };
+}
+
+function uploadExecutionLog(store, identifier) {
+  if (!store) {
+    return { success: false, error: 'Execution tracking is disabled.' };
+  }
+
+  const record = store.get(identifier);
+  if (!record) {
+    return {
+      success: false,
+      error: `No execution found with UUID or session name: ${identifier}`,
+    };
+  }
+
+  return uploadLogPath(record.logPath);
+}
+
+module.exports = {
+  ensureGhUploadLogAvailable,
+  resolveCommand,
+  uploadExecutionLog,
+  uploadLogPath,
+};

package/src/lib/usage.js

@@ -1,15 +1,19 @@
 /** Print usage information */
 function printUsage() {
-  console.log(`Usage: $ [options] [--] <command> | $ --status <uuid> [--output-format <fmt>] | $ --list [--output-format <fmt>] | $ --stop <id> | $ --terminate <id>
+  console.log(`Usage: $ [options] [--] <command> | $ --status <uuid> [--output-format <fmt>] | $ --list [--output-format <fmt>] | $ --upload-log <id> | $ --stop <id> | $ --terminate <id>
 
 Options:
-  --isolated, -i <env>  Run in isolated environment (screen, tmux, docker, ssh)
+  --isolated, --isolation, -i <env>  Run in isolated environment (screen, tmux, docker, ssh)
   --attached, -a        Run in attached mode (foreground)
   --detached, -d        Run in detached mode (background)
   --session, -s <name>  Session name for isolation
   --session-id <uuid>   Session UUID for tracking (auto-generated if not provided)
   --session-name <uuid> Alias for --session-id
   --image <image>       Docker image (optional, defaults to OS-matched image)
+  --volume, -v <spec>   Docker bind mount/volume host:container[:mode] (repeatable, docker only)
+  --mount <spec>        Docker --mount spec (repeatable, docker only)
+  --env, -e <KEY=VALUE> Environment variable for docker container (repeatable, docker only)
+  --privileged          Run docker container in privileged mode (docker only)
   --endpoint <endpoint> SSH endpoint (required for ssh isolation, e.g., user@host)
   --isolated-user, -u [name]  Create isolated user with same permissions
   --keep-user           Keep isolated user after command completes
@@ -19,6 +23,7 @@ Options:
   --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
   --terminate <id>      Terminate a detached isolated execution immediately
   --cleanup             Clean up stale "executing" records (crashed/killed processes)
@@ -32,6 +37,8 @@ Examples:
   $ -i screen -d bun start
   $ --isolated docker -- echo "hi"       # uses OS-matched default image
   $ --isolated docker --image ghcr.io/link-foundation/box-js:latest -- bun --version
+  $ -i docker -v ~/.config/gh:/root/.config/gh -e TOKEN=abc -- gh repo list
+  $ -i docker --image konard/hive-mind-dind:latest --privileged -- solve ...
   $ --isolated ssh --endpoint user@remote.server -- ls -la
   $ --isolated-user -- npm test            # Create isolated user
   $ -u myuser -- npm start                 # Custom username
@@ -39,6 +46,7 @@ Examples:
   $ --isolated-user --keep-user -- npm start
   $ --list                                 # List stored execution records
   $ --list --output-format json            # List stored records as JSON
+  $ --upload-log my-screen-session         # Upload stored execution log
   $ --stop my-screen-session               # Ask detached execution to stop gracefully
   $ --terminate my-screen-session          # Terminate detached execution immediately
   $ --use-command-stream echo "Hello"      # Use command-stream library`);

package/test/args-parser-control.js

@@ -54,7 +54,13 @@ describe('control options', () => {
   it('should reject combining query and control modes', () => {
     assert.throws(() => {
       parseArgs(['--status', 'uuid-here', '--stop', 'my-session']);
-    }, /Cannot combine --status, --list, --stop, --terminate, or --cleanup/);
+    }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, or --cleanup/);
+  });
+
+  it('should reject combining upload-log with control modes', () => {
+    assert.throws(() => {
+      parseArgs(['--upload-log', 'uuid-here', '--terminate', 'my-session']);
+    }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, or --cleanup/);
   });
 
   it('should reject output-format with control modes', () => {

package/test/args-parser-isolation-alias.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env bun
+/**
+ * Regression tests for --isolation alias handling and unknown wrapper options.
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const { parseArgs } = require('../src/lib/args-parser');
+
+describe('parseArgs --isolation alias', () => {
+  it('should parse --isolation alias with value', () => {
+    const result = parseArgs(['--isolation', 'docker', '--', 'echo', 'hi']);
+    assert.strictEqual(result.wrapperOptions.isolated, 'docker');
+    assert.strictEqual(result.command, 'echo hi');
+  });
+
+  it('should parse --isolation=value alias format', () => {
+    const result = parseArgs(['--isolation=screen', '--', 'ls', '-la']);
+    assert.strictEqual(result.wrapperOptions.isolated, 'screen');
+  });
+
+  it('should parse --isolation alias before command without separator', () => {
+    const result = parseArgs(['--isolation', 'docker', 'echo', 'hi']);
+    assert.strictEqual(result.wrapperOptions.isolated, 'docker');
+    assert.strictEqual(result.command, 'echo hi');
+  });
+});
+
+describe('parseArgs unknown wrapper options', () => {
+  it('should throw for unknown wrapper option before separator', () => {
+    assert.throws(() => {
+      parseArgs(['--unknown-wrapper', 'value', '--', 'echo', 'hi']);
+    }, /Unknown wrapper option: --unknown-wrapper/);
+  });
+
+  it('should throw for unknown wrapper option without separator', () => {
+    assert.throws(() => {
+      parseArgs(['--unknown-wrapper', 'value', 'echo', 'hi']);
+    }, /Unknown wrapper option: --unknown-wrapper/);
+  });
+});

package/test/args-parser.js

@@ -832,6 +832,36 @@ describe('status option', () => {
   });
 });
 
+describe('upload-log option', () => {
+  it('should parse --upload-log with UUID or session name', () => {
+    const result = parseArgs(['--upload-log', 'my-session']);
+    assert.strictEqual(result.wrapperOptions.uploadLog, 'my-session');
+    assert.strictEqual(result.command, '');
+  });
+
+  it('should parse --upload-log=value format', () => {
+    const result = parseArgs(['--upload-log=my-session']);
+    assert.strictEqual(result.wrapperOptions.uploadLog, 'my-session');
+  });
+
+  it('should throw error for missing --upload-log argument', () => {
+    assert.throws(() => {
+      parseArgs(['--upload-log']);
+    }, /requires a UUID or session name argument/);
+  });
+
+  it('should throw error for empty --upload-log=value argument', () => {
+    assert.throws(() => {
+      parseArgs(['--upload-log=']);
+    }, /requires a UUID or session name argument/);
+  });
+
+  it('should default uploadLog to null', () => {
+    const result = parseArgs(['echo', 'hello']);
+    assert.strictEqual(result.wrapperOptions.uploadLog, null);
+  });
+});
+
 describe('list option', () => {
   it('should parse --list flag', () => {
     const result = parseArgs(['--list']);

package/test/docker-runtime-options.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env bun
+/**
+ * Tests for Docker runtime options: --volume/-v, --mount, --env/-e, --privileged
+ *
+ * Reproduces issue #132: callers need to configure bind mounts, volumes,
+ * environment variables, and privileged mode for the docker isolation backend
+ * so they can mount tool credentials and run Docker-in-Docker images without
+ * wrapping `docker run` themselves.
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const { parseArgs } = require('../src/lib/args-parser');
+const {
+  buildDockerRuntimeArgs,
+  buildDockerRuntimeStatusLines,
+  buildDockerRuntimeMetadata,
+} = require('../src/lib/isolation');
+
+describe('Docker runtime options parsing', () => {
+  it('should parse repeatable --volume and -v', () => {
+    const result = parseArgs([
+      '--isolated',
+      'docker',
+      '--volume',
+      '/host/a:/container/a',
+      '-v',
+      '/host/b:/container/b:ro',
+      '--',
+      'ls',
+    ]);
+    assert.deepStrictEqual(result.wrapperOptions.volumes, [
+      '/host/a:/container/a',
+      '/host/b:/container/b:ro',
+    ]);
+  });
+
+  it('should parse --volume=value and -v=value', () => {
+    const result = parseArgs([
+      '-i',
+      'docker',
+      '--volume=/host/a:/c/a',
+      '-v=/host/b:/c/b',
+      '--',
+      'ls',
+    ]);
+    assert.deepStrictEqual(result.wrapperOptions.volumes, [
+      '/host/a:/c/a',
+      '/host/b:/c/b',
+    ]);
+  });
+
+  it('should parse repeatable --mount', () => {
+    const result = parseArgs([
+      '-i',
+      'docker',
+      '--mount',
+      'type=bind,src=/h,dst=/c',
+      '--mount=type=volume,src=vol,dst=/data',
+      '--',
+      'ls',
+    ]);
+    assert.deepStrictEqual(result.wrapperOptions.mounts, [
+      'type=bind,src=/h,dst=/c',
+      'type=volume,src=vol,dst=/data',
+    ]);
+  });
+
+  it('should parse repeatable --env and -e', () => {
+    const result = parseArgs([
+      '-i',
+      'docker',
+      '--env',
+      'FOO=bar',
+      '-e',
+      'GH_TOKEN=secret',
+      '--env=BAZ=qux',
+      '--',
+      'env',
+    ]);
+    assert.deepStrictEqual(result.wrapperOptions.env, [
+      'FOO=bar',
+      'GH_TOKEN=secret',
+      'BAZ=qux',
+    ]);
+  });
+
+  it('should parse --privileged', () => {
+    const result = parseArgs(['-i', 'docker', '--privileged', '--', 'ls']);
+    assert.strictEqual(result.wrapperOptions.privileged, true);
+  });
+
+  it('should default runtime options to empty/false', () => {
+    const result = parseArgs(['-i', 'docker', '--', 'ls']);
+    assert.deepStrictEqual(result.wrapperOptions.volumes, []);
+    assert.deepStrictEqual(result.wrapperOptions.mounts, []);
+    assert.deepStrictEqual(result.wrapperOptions.env, []);
+    assert.strictEqual(result.wrapperOptions.privileged, false);
+  });
+
+  it('should throw when --volume requires an argument', () => {
+    assert.throws(() => {
+      parseArgs(['-i', 'docker', '--volume', '--', 'ls']);
+    }, /requires a volume argument/);
+  });
+
+  it('should throw when --env requires an argument', () => {
+    assert.throws(() => {
+      parseArgs(['-i', 'docker', '--env', '--', 'ls']);
+    }, /requires a KEY=VALUE argument/);
+  });
+});
+
+describe('Docker runtime options validation', () => {
+  it('should reject --volume with non-docker backend', () => {
+    assert.throws(() => {
+      parseArgs(['-i', 'tmux', '-v', '/a:/b', '--', 'ls']);
+    }, /--volume option is only valid when isolation stack includes docker/);
+  });
+
+  it('should reject --mount without isolation', () => {
+    assert.throws(() => {
+      parseArgs(['--mount', 'type=bind,src=/a,dst=/b', '--', 'ls']);
+    }, /--mount option is only valid when isolation stack includes docker/);
+  });
+
+  it('should reject --env with non-docker backend', () => {
+    assert.throws(() => {
+      parseArgs(['-i', 'ssh', '--endpoint', 'u@h', '-e', 'A=1', '--', 'ls']);
+    }, /--env option is only valid when isolation stack includes docker/);
+  });
+
+  it('should reject --privileged without docker', () => {
+    assert.throws(() => {
+      parseArgs(['--privileged', '--', 'ls']);
+    }, /--privileged option is only valid when isolation stack includes docker/);
+  });
+
+  it('should accept runtime options when stack includes docker', () => {
+    const result = parseArgs([
+      '-i',
+      'screen docker',
+      '-v',
+      '/a:/b',
+      '-e',
+      'A=1',
+      '--privileged',
+      '--',
+      'ls',
+    ]);
+    assert.deepStrictEqual(result.wrapperOptions.volumes, ['/a:/b']);
+    assert.deepStrictEqual(result.wrapperOptions.env, ['A=1']);
+    assert.strictEqual(result.wrapperOptions.privileged, true);
+  });
+});
+
+describe('buildDockerRuntimeArgs', () => {
+  it('should build empty args by default', () => {
+    assert.deepStrictEqual(buildDockerRuntimeArgs({}), []);
+  });
+
+  it('should add --privileged first', () => {
+    assert.deepStrictEqual(buildDockerRuntimeArgs({ privileged: true }), [
+      '--privileged',
+    ]);
+  });
+
+  it('should expand env, volumes, and mounts in order', () => {
+    const args = buildDockerRuntimeArgs({
+      privileged: true,
+      env: ['FOO=bar', 'GH_TOKEN=secret'],
+      volumes: ['/h/a:/c/a', '/h/b:/c/b:ro'],
+      mounts: ['type=bind,src=/h,dst=/c'],
+    });
+    assert.deepStrictEqual(args, [
+      '--privileged',
+      '-e',
+      'FOO=bar',
+      '-e',
+      'GH_TOKEN=secret',
+      '-v',
+      '/h/a:/c/a',
+      '-v',
+      '/h/b:/c/b:ro',
+      '--mount',
+      'type=bind,src=/h,dst=/c',
+    ]);
+  });
+});
+
+describe('buildDockerRuntimeStatusLines', () => {
+  it('should return no lines for empty options', () => {
+    assert.deepStrictEqual(buildDockerRuntimeStatusLines({}), []);
+  });
+
+  it('should format volumes, mounts, env, and privileged lines', () => {
+    const lines = buildDockerRuntimeStatusLines({
+      volumes: ['/h:/c:ro'],
+      mounts: ['type=bind,src=/h,dst=/c'],
+      env: ['FOO=bar'],
+      privileged: true,
+    });
+    assert.deepStrictEqual(lines, [
+      '[Isolation] Volumes: /h:/c:ro',
+      '[Isolation] Mounts: type=bind,src=/h,dst=/c',
+      '[Isolation] Env: FOO=bar',
+      '[Isolation] Privileged: true',
+    ]);
+  });
+
+  it('should join multiple volumes with a comma', () => {
+    assert.deepStrictEqual(
+      buildDockerRuntimeStatusLines({ volumes: ['/a:/a', '/b:/b'] }),
+      ['[Isolation] Volumes: /a:/a, /b:/b']
+    );
+  });
+});
+
+describe('buildDockerRuntimeMetadata', () => {
+  it('should null out empty collections and falsy privileged', () => {
+    assert.deepStrictEqual(buildDockerRuntimeMetadata({}), {
+      volumes: null,
+      mounts: null,
+      env: null,
+      privileged: null,
+    });
+  });
+
+  it('should pass through populated collections and privileged', () => {
+    assert.deepStrictEqual(
+      buildDockerRuntimeMetadata({
+        volumes: ['/h:/c'],
+        mounts: ['type=bind,src=/h,dst=/c'],
+        env: ['FOO=bar'],
+        privileged: true,
+      }),
+      {
+        volumes: ['/h:/c'],
+        mounts: ['type=bind,src=/h,dst=/c'],
+        env: ['FOO=bar'],
+        privileged: true,
+      }
+    );
+  });
+});

package/test/status-query.js

@@ -32,7 +32,7 @@ function cleanupTestDir() {
 
 // Helper to run CLI command
 function runCli(args, env = {}) {
-  const result = spawnSync('bun', [CLI_PATH, ...args], {
+  const result = spawnSync(process.execPath, [CLI_PATH, ...args], {
     encoding: 'utf8',
     env: {
       ...process.env,
@@ -48,6 +48,26 @@ function runCli(args, env = {}) {
   };
 }
 
+function createExecutable(filePath, content) {
+  fs.writeFileSync(filePath, content, 'utf8');
+  fs.chmodSync(filePath, 0o755);
+}
+
+function createFakeUploader(fakeBin, outputPrefix) {
+  if (process.platform === 'win32') {
+    createExecutable(
+      path.join(fakeBin, 'gh-upload-log.cmd'),
+      `@echo off\r\necho ${outputPrefix}: %1\r\n`
+    );
+    return;
+  }
+
+  createExecutable(
+    path.join(fakeBin, 'gh-upload-log'),
+    `#!/bin/sh\necho "${outputPrefix}: $1"\n`
+  );
+}
+
 describe('--status query functionality', () => {
   let store;
   let testRecord;
@@ -241,6 +261,88 @@ describe('--status query functionality', () => {
     });
   });
 
+  describe('--upload-log functionality', () => {
+    it('should run gh-upload-log with the stored execution log path', () => {
+      const fakeBin = fs.mkdtempSync(path.join(os.tmpdir(), 'upload-log-bin-'));
+      const logPath = path.join(TEST_APP_FOLDER, 'command.log');
+      fs.writeFileSync(logPath, 'captured command output\n', 'utf8');
+      createFakeUploader(fakeBin, 'fake uploader received');
+
+      testRecord.logPath = logPath;
+      store.save(testRecord);
+
+      const result = runCli(['--upload-log', testRecord.uuid], {
+        PATH: fakeBin,
+        HOME: fakeBin,
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain(`fake uploader received: ${logPath}`);
+      expect(result.stderr).toBe('');
+
+      fs.rmSync(fakeBin, { recursive: true, force: true });
+    });
+
+    it('should install gh-upload-log when it is missing before uploading', () => {
+      if (process.platform === 'win32') {
+        console.log('  Skipping: shell fixture uses POSIX scripts');
+        return;
+      }
+
+      const fakeBin = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'upload-log-install-bin-')
+      );
+      const installMarker = path.join(fakeBin, 'install.log');
+      const logPath = path.join(TEST_APP_FOLDER, 'install-command.log');
+      fs.writeFileSync(logPath, 'captured command output\n', 'utf8');
+
+      createExecutable(
+        path.join(fakeBin, 'bun'),
+        [
+          '#!/bin/sh',
+          `echo "$@" > "${installMarker}"`,
+          `cat > "${path.join(fakeBin, 'gh-upload-log')}" <<'SCRIPT'`,
+          '#!/bin/sh',
+          'echo "installed uploader received: $1"',
+          'SCRIPT',
+          `chmod +x "${path.join(fakeBin, 'gh-upload-log')}"`,
+          'exit 0',
+          '',
+        ].join('\n')
+      );
+
+      testRecord.logPath = logPath;
+      store.save(testRecord);
+
+      const result = runCli(['--upload-log', testRecord.uuid], {
+        PATH: `${fakeBin}${path.delimiter}/usr/bin${path.delimiter}/bin`,
+        HOME: fakeBin,
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(fs.readFileSync(installMarker, 'utf8').trim()).toBe(
+        'install -g gh-upload-log'
+      );
+      expect(result.stdout).toContain('gh-upload-log not found');
+      expect(result.stdout).toContain(
+        `installed uploader received: ${logPath}`
+      );
+
+      fs.rmSync(fakeBin, { recursive: true, force: true });
+    });
+
+    it('should show an error when the stored log file is missing', () => {
+      testRecord.logPath = path.join(TEST_APP_FOLDER, 'missing.log');
+      store.save(testRecord);
+
+      const result = runCli(['--upload-log', testRecord.uuid]);
+
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toContain('Log file not found');
+      expect(result.stderr).toContain(testRecord.logPath);
+    });
+  });
+
   describe('executing status', () => {
     it('should show executing status for ongoing commands', () => {
       // Create an executing (not completed) record