start-command 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # start-command
 
+## 0.37.0
+
+### Minor Changes
+
+- 94db203: Add copy-free Docker command resumes with guarded legacy snapshots, persistent
+  task labels, wrapper help flags, private sanitized log uploads, and faithful shell
+  argument and exit-code handling. Enforce JavaScript-first CI and shared Rust parity.
+
 ## 0.36.0
 
 ### Minor Changes

package/README.md

@@ -24,6 +24,8 @@ $ ls -la
 $ bun test
 $ git status
 $ --list
+$ --help
+$ -i docker -d --label task.tool=codex -- my-task
 $ --attach <id>
 $ --resume <id> -- <command>
 $ --resume-all
@@ -34,6 +36,10 @@ See the project-wide [README](../README.md), [docs/USAGE.md](../docs/USAGE.md),
 [docs/EXAMPLES.md](../docs/EXAMPLES.md) for the full user-facing guide and
 checked examples.
 
+`-h` also prints usage. Labels persist across Docker resumes. New detached
+containers support copy-free command handoff; legacy snapshots require capacity
+preflight. Log uploads are private and sanitized; manual `--no-sanitize` opts out.
+
 ## Development
 
 ```bash

package/package.json

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

@@ -192,6 +192,10 @@ try {
 }
 
 const { wrapperOptions, command: parsedCommand } = parsedArgs;
+if (wrapperOptions.help) {
+  printUsage();
+  process.exit(0);
+}
 
 // Query/control modes (--status, --list, --attach, --resume, ...) address an
 // execution that already exists, so they never need a command of their own.
@@ -479,6 +483,7 @@ async function runWithIsolation(
     result = await runIsolated(environment, cmd, {
       ...options,
       session: sessionName,
+      sessionId,
       image: effectiveImage,
       endpoint: options.endpoint,
       detached: mode === 'detached',

package/src/lib/args-parser-queries.js

@@ -26,6 +26,8 @@ function createQueryOptionDefaults() {
     list: false, // List all tracked execution records
     running: false, // Restrict --list to executions that are still running
     uploadLog: null, // UUID/session name whose stored log should be uploaded
+    noSanitize: false,
+    removeOriginal: false,
     outputFormat: null, // Output format (links-notation, json, text)
     stop: null, // UUID/session name to stop gracefully
     terminate: null, // UUID/session name to terminate immediately
@@ -55,6 +57,12 @@ const IDENTIFIER_OPTIONS = {
  * Boolean flags with no argument.
  */
 const FLAG_OPTIONS = {
+  '--no-sanitize': (options) => {
+    options.noSanitize = true;
+  },
+  '--remove-original': (options) => {
+    options.removeOriginal = true;
+  },
   '--list': (options) => {
     options.list = true;
   },
@@ -185,6 +193,12 @@ const OUTPUT_FORMAT_MODES = ['--status', '--list', '--resume', '--resume-all'];
  * @throws {Error} When the combination is not supported
  */
 function validateQueryOptions(options) {
+  if (options.noSanitize && !hasValue(options.uploadLog)) {
+    throw new Error('--no-sanitize is only valid with --upload-log');
+  }
+  if (options.removeOriginal && !hasValue(options.resume)) {
+    throw new Error('--remove-original is only valid with --resume');
+  }
   if (hasValue(options.outputFormat)) {
     if (!VALID_OUTPUT_FORMATS.includes(options.outputFormat)) {
       throw new Error(

package/src/lib/args-parser.js

@@ -193,6 +193,8 @@ function parseArgs(args) {
     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
+    labels: [], // Caller attribution, applied to every Docker level
+    help: false,
     privileged: false, // Run docker container in privileged mode
     network: null, // First Docker network name (compatibility accessor)
     networks: [], // Ordered Docker network names
@@ -247,7 +249,9 @@ function parseArgs(args) {
   }
 
   // Validate options
-  validateOptions(wrapperOptions);
+  if (!wrapperOptions.help) {
+    validateOptions(wrapperOptions);
+  }
 
   return {
     wrapperOptions,
@@ -288,6 +292,16 @@ function parseWrapperArgs(args, options) {
  */
 function parseOption(args, index, options) {
   const arg = args[index];
+  if (arg === '--help' || arg === '-h') {
+    options.help = true;
+    return 1;
+  }
+  if (arg === '--label' || arg.startsWith('--label=')) {
+    const label = arg === '--label' ? args[index + 1] : arg.slice(8);
+    require('./docker-labels').validateLabel(label);
+    options.labels.push(label);
+    return arg === '--label' ? 2 : 1;
+  }
 
   // --isolated, --isolation, or -i
   if (arg === '--isolated' || arg === '--isolation' || arg === '-i') {
@@ -568,6 +582,11 @@ function parseOption(args, index, options) {
  * @throws {Error} If a docker-only option is set without docker isolation
  */
 function validateDockerRuntimeOptionsRequireDocker(options) {
+  if (options.labels?.length > 0 && !options.resume) {
+    throw new Error(
+      '--label option is only valid with docker isolation or --resume'
+    );
+  }
   if (options.volumes && options.volumes.length > 0) {
     throw new Error(
       '--volume option is only valid when isolation stack includes docker'

package/src/lib/command-builder.js

@@ -106,6 +106,9 @@ function buildNextLevelCommand(options, command) {
     for (const envVar of options.env || []) {
       parts.push(`--env "${envVar}"`);
     }
+    for (const label of options.labels || []) {
+      parts.push(`--label ${require('./shell-utils').quoteShellArg(label)}`);
+    }
     if (options.privileged) {
       parts.push('--privileged');
     }

package/src/lib/docker-cleanup.js

@@ -83,7 +83,7 @@ function getDockerContainerCleanupInstructions(containerName) {
     `Container kept for investigation: ${containerName}`,
     `Re-enter while running: $ --attach ${containerName}`,
     `Continue the stored command: $ --resume ${containerName}`,
-    `Run another command in the same container: $ --resume ${containerName} -- <command>`,
+    `Run another command (legacy containers snapshot the filesystem into a new container): $ --resume ${containerName} -- <command>`,
     `Remove when done: docker rm -f ${containerName}`,
   ].join('\n');
 }
@@ -306,7 +306,7 @@ function buildDockerKeptLogSnippet(containerName, quotedLogPath) {
     `printf '\\nContainer kept for investigation: %s\\nReason: %s\\n` +
     `Re-enter while running: $ --attach %s\\n` +
     `Continue the stored command: $ --resume %s\\n` +
-    `Run another command in the same container: $ --resume %s -- <command>\\n` +
+    `Run another command (legacy containers snapshot the filesystem into a new container): $ --resume %s -- <command>\\n` +
     `Remove when done: docker rm -f %s\\n' ` +
     `${quotedName} "$__start_command_reason" ` +
     `${quotedName} ${quotedName} ${quotedName} ${quotedName} >> ${quotedLogPath}`
@@ -361,6 +361,11 @@ function buildDetachedDockerCompletionScript(
   watcherOptions = {}
 ) {
   const quotedName = shellQuote(containerName);
+  const imageCleanup =
+    require('./docker-snapshot-safety').snapshotImageCleanupSnippet(
+      containerName,
+      logPath ? `>> ${shellQuote(logPath)} 2>&1` : '>/dev/null 2>&1'
+    );
   // The container's cgroup disappears with it, so its memory counters are
   // sampled while it runs (issue #182).
   const cpuMonitor = require('./cpu-penalty-monitor');
@@ -389,7 +394,7 @@ function buildDetachedDockerCompletionScript(
       quotedLogPath
     );
     const memory = buildCgroupMemoryLogSnippet(quotedLogPath);
-    const remove = `docker rm -f ${quotedName} >> ${quotedLogPath} 2>&1 || true; ${removalNote}; ${memory}`;
+    const remove = `${imageCleanup.capture}; if docker rm -f ${quotedName} >> ${quotedLogPath} 2>&1; then ${imageCleanup.remove}; fi; ${removalNote}; ${memory}`;
     const keep = `${postMortem}; ${memory}; ${buildDockerKeptLogSnippet(containerName, quotedLogPath)}`;
 
     const since = watcherOptions.since
@@ -438,13 +443,15 @@ function buildDetachedDockerCompletionScript(
     parts.push(buildCgroupSamplerStopSnippet());
     parts.push(buildDockerStateSnippet(containerName));
     if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS) {
-      exited.push(`docker rm -f ${quotedName} >/dev/null 2>&1 || true`);
+      exited.push(
+        `${imageCleanup.capture}; if docker rm -f ${quotedName} >/dev/null 2>&1; then ${imageCleanup.remove}; fi`
+      );
     } else if (
       policy === DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT ||
       policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL
     ) {
       exited.push(
-        `if ${buildSuccessfulNonOomCondition()}; then docker rm -f ${quotedName} >/dev/null 2>&1 || true; fi`
+        `if ${buildSuccessfulNonOomCondition()}; then ${imageCleanup.capture}; if docker rm -f ${quotedName} >/dev/null 2>&1; then ${imageCleanup.remove}; fi; fi`
       );
     }
   }

package/src/lib/docker-command-handoff.js

@@ -0,0 +1,75 @@
+/** Copy only a command script into a stopped container, never its writable layer. */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { shellQuote } = require('./isolation-log-utils');
+
+function commandHandoffPath(sessionName) {
+  return `/.start-command-resume-${String(sessionName).replace(/[^A-Za-z0-9_.-]/g, '_')}`;
+}
+
+function buildCommandHandoffArgs(mainArgs, markerPath) {
+  return [
+    'sh',
+    '-c',
+    'p=$1; shift; if [ -f "$p" ]; then exec sh "$p"; fi; exec "$@"',
+    'start-command-handoff',
+    markerPath,
+    ...mainArgs,
+  ];
+}
+
+function buildCommandHandoffScript(command, options = {}) {
+  const {
+    isInteractiveShellCommand,
+    isShellInvocationWithArgs,
+    buildShellWithArgsCmdArgs,
+    toShellWords,
+  } = require('./shell-utils');
+  if (
+    !options.keepAlive &&
+    (isInteractiveShellCommand(command) || isShellInvocationWithArgs(command))
+  ) {
+    const args = isShellInvocationWithArgs(command)
+      ? buildShellWithArgsCmdArgs(command)
+      : toShellWords(command);
+    return `exec ${args.map(shellQuote).join(' ')}\n`;
+  }
+  if (!options.shell || options.shell === 'auto') {
+    const effective = options.keepAlive
+      ? `${command}; exec "$__START_COMMAND_HANDOFF_SHELL"`
+      : command;
+    return `__START_COMMAND_HANDOFF_SHELL=$(command -v bash || command -v zsh || command -v sh); export __START_COMMAND_HANDOFF_SHELL\ncase "$__START_COMMAND_HANDOFF_SHELL" in */bash|bash|*/zsh|zsh) exec "$__START_COMMAND_HANDOFF_SHELL" -i -c ${shellQuote(effective)};; *) exec "$__START_COMMAND_HANDOFF_SHELL" -c ${shellQuote(effective)};; esac\n`;
+  }
+  const shell = options.shell;
+  const interactive = /(?:^|\/)(?:bash|zsh)$/.test(shell) ? ' -i' : '';
+  const effective = options.keepAlive
+    ? `${command}; exec ${shellQuote(shell)}`
+    : command;
+  return `exec ${shellQuote(shell)}${interactive} -c ${shellQuote(effective)}\n`;
+}
+
+function writeCommandHandoff(containerName, command, runner, options = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'start-handoff-'));
+  const file = path.join(dir, 'command');
+  try {
+    fs.writeFileSync(file, buildCommandHandoffScript(command, options), {
+      mode: 0o644,
+    });
+    fs.chmodSync(file, 0o644);
+    return runner(require('./docker-cleanup').getDockerCommand(), [
+      'cp',
+      file,
+      `${containerName}:${commandHandoffPath(containerName)}`,
+    ]);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+module.exports = {
+  commandHandoffPath,
+  buildCommandHandoffArgs,
+  buildCommandHandoffScript,
+  writeCommandHandoff,
+};

package/src/lib/docker-labels.js

@@ -0,0 +1,33 @@
+/** Docker attribution shared by initial launches and snapshot resumes (#199). */
+function validateLabel(label) {
+  if (typeof label !== 'string' || !/^[^=\s]+=[\s\S]*$/.test(label)) {
+    throw new Error('--label requires KEY=VALUE with a nonempty key');
+  }
+  if (label.startsWith('start-command.')) {
+    throw new Error(
+      'start-command.* labels are reserved for execution attribution'
+    );
+  }
+}
+
+function dockerLabels(options = {}) {
+  const labels = [...(options.labels || [])];
+  const session = options.containerName || options.session;
+  if (session) {
+    const inferredRoot =
+      Number(options.resumeCount) > 0
+        ? session.replace(/(?:-resume-\d+)+$/, '')
+        : session;
+    labels.push(`start-command.session=${session}`);
+    labels.push(
+      `start-command.root-session=${options.rootSession || inferredRoot}`
+    );
+    labels.push(`start-command.resume-count=${options.resumeCount || 0}`);
+  }
+  if (options.sessionId || options.uuid) {
+    labels.push(`start-command.uuid=${options.sessionId || options.uuid}`);
+  }
+  return labels;
+}
+
+module.exports = { validateLabel, dockerLabels };

package/src/lib/docker-runtime-args.js

@@ -42,6 +42,9 @@ function buildDockerRuntimeArgs(options = {}) {
   for (const envVar of options.env || []) {
     args.push('-e', envVar);
   }
+  for (const label of require('./docker-labels').dockerLabels(options)) {
+    args.push('--label', label);
+  }
   for (const volume of options.volumes || []) {
     args.push('-v', volume);
   }
@@ -69,6 +72,9 @@ function buildDockerRuntimeArgs(options = {}) {
  */
 function buildDockerRuntimeStatusLines(options = {}) {
   const lines = [];
+  if (options.labels && options.labels.length > 0) {
+    lines.push(`[Isolation] Labels: ${options.labels.join(', ')}`);
+  }
   if (options.volumes && options.volumes.length > 0) {
     lines.push(`[Isolation] Volumes: ${options.volumes.join(', ')}`);
   }
@@ -129,6 +135,8 @@ function buildDockerRuntimeMetadata(options = {}) {
       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,
+    labels: options.labels && options.labels.length > 0 ? options.labels : null,
+    commandHandoff: options.detached ? true : null,
     privileged: options.privileged || null,
     network: networks[0] || null,
     networks: networks.length > 0 ? networks : null,

package/src/lib/docker-snapshot-safety.js

@@ -0,0 +1,164 @@
+/** Serialize costly snapshot resumes and check every image-store filesystem. */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { LockManager } = require('./store-lock');
+
+const GiB = 1024 ** 3;
+const SNAPSHOT_RESERVE_BYTES = 10 * GiB;
+const SNAPSHOT_IMAGE_LABEL = 'start-command.snapshot-image';
+
+function acquireSnapshotLock(options = {}) {
+  const lockPath =
+    options.lockPath ||
+    process.env.START_SNAPSHOT_LOCK ||
+    path.join(
+      process.platform === 'win32' ? os.tmpdir() : '/tmp',
+      'start-command-docker-snapshot.lock'
+    );
+  const lock = new LockManager(lockPath);
+  // The ordinary store lock is held only for a brief write. A snapshot can
+  // legitimately take hours, so never reclaim this lock merely for its age.
+  lock.isLockStale = (data) => {
+    if (
+      !data ||
+      data.hostname !== os.hostname() ||
+      !Number.isInteger(data.pid) ||
+      data.pid <= 0
+    ) {
+      return false;
+    }
+    try {
+      process.kill(data.pid, 0);
+      return false;
+    } catch (error) {
+      return error.code === 'ESRCH';
+    }
+  };
+  if (!lock.acquire(1000)) {
+    throw new Error(
+      'A Docker snapshot resume is in progress on this host. Retry after it finishes.'
+    );
+  }
+  return lock;
+}
+
+function containerdRoot(config = '') {
+  // Only the root-level TOML key configures containerd's storage root.
+  const topLevel = config.split(/^\s*\[/m)[0];
+  return (
+    topLevel.match(/^\s*root\s*=\s*["']([^"']+)["']/m)?.[1] ||
+    '/var/lib/containerd'
+  );
+}
+
+function defaultContainerdRoot() {
+  if (process.env.START_CONTAINERD_ROOT) {
+    return process.env.START_CONTAINERD_ROOT;
+  }
+  try {
+    return containerdRoot(
+      fs.readFileSync('/etc/containerd/config.toml', 'utf8')
+    );
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return containerdRoot();
+    }
+    throw error;
+  }
+}
+
+function readFreeBytes(root) {
+  const stats = fs.statfsSync(root, { bigint: true });
+  return Number(stats.bavail * stats.bsize);
+}
+
+function preflightSnapshot(containerName, runner, options = {}) {
+  const docker = require('./docker-cleanup').getDockerCommand();
+  const sizeResult = runner(docker, [
+    'inspect',
+    '--size',
+    '--format',
+    '{{.SizeRw}}',
+    containerName,
+  ]);
+  const size = Number(String(sizeResult.stdout || '').trim());
+  if (
+    !sizeResult.success ||
+    !/^\d+$/.test(String(sizeResult.stdout || '').trim()) ||
+    !Number.isSafeInteger(size) ||
+    size < 0
+  ) {
+    throw new Error(
+      'Cannot determine the writable layer size; refusing Docker snapshot resume.'
+    );
+  }
+  const infoResult = runner(docker, ['info', '--format', '{{json .}}']);
+  let info;
+  try {
+    info = JSON.parse(infoResult.stdout);
+  } catch {
+    /* Refuse unknown storage. */
+  }
+  if (!infoResult.success || !info?.DockerRootDir) {
+    throw new Error(
+      'Cannot determine Docker data root; refusing Docker snapshot resume.'
+    );
+  }
+  const roots = [info.DockerRootDir];
+  if (
+    JSON.stringify(info.DriverStatus || []).includes(
+      'io.containerd.snapshotter'
+    )
+  ) {
+    roots.push(options.containerdRoot || defaultContainerdRoot());
+  }
+  const required = 2 * size + (options.reserveBytes ?? SNAPSHOT_RESERVE_BYTES);
+  const free = options.freeBytes || readFreeBytes;
+  for (const root of [...new Set(roots)]) {
+    let available;
+    try {
+      available = free(root);
+    } catch (error) {
+      throw new Error(
+        `Cannot check free disk at ${root}: ${error.message}; refusing Docker snapshot resume.`,
+        { cause: error }
+      );
+    }
+    if (!Number.isFinite(available) || available < required) {
+      throw new Error(
+        `Insufficient disk at ${root}: need ${(required / GiB).toFixed(2)} GiB (2 × writable layer plus reserve), available ${(available / GiB).toFixed(2)} GiB. Docker snapshot resume refused.`
+      );
+    }
+  }
+  return {
+    size,
+    required,
+    roots,
+    message: `[Resume] snapshotting ${(size / GiB).toFixed(2)} GiB; disk preflight passed (${(required / GiB).toFixed(2)} GiB required).`,
+  };
+}
+
+function snapshotImageCleanupSnippet(
+  containerName,
+  redirection = '>/dev/null 2>&1'
+) {
+  const { shellQuote } = require('./isolation-log-utils');
+  const name = shellQuote(containerName);
+  const format = shellQuote(
+    `{{index .Config.Labels "${SNAPSHOT_IMAGE_LABEL}"}}`
+  );
+  return {
+    capture: `__start_snapshot_image=$(docker inspect -f ${format} ${name} 2>/dev/null || true)`,
+    remove: `case "$__start_snapshot_image" in start-command-resume/*) docker rmi "$__start_snapshot_image" ${redirection} || true;; esac`,
+  };
+}
+
+module.exports = {
+  acquireSnapshotLock,
+  containerdRoot,
+  preflightSnapshot,
+  SNAPSHOT_RESERVE_BYTES,
+  SNAPSHOT_IMAGE_LABEL,
+  snapshotImageCleanupSnippet,
+};

package/src/lib/execution-recovery.js

@@ -357,7 +357,14 @@ function recoverKilledExecution(params = {}) {
   if (opts.recoveryCommand) {
     let copied;
     try {
-      copied = writeRecoveryMarker(containerName, attempt, runner);
+      copied = opts.commandHandoff
+        ? require('./docker-command-handoff').writeCommandHandoff(
+            containerName,
+            `export ${RECOVERY_ATTEMPT_ENV}=${attempt}; ${opts.recoveryCommand}`,
+            runner,
+            opts
+          )
+        : writeRecoveryMarker(containerName, attempt, runner);
     } catch (err) {
       copied = { success: false, error: err.message };
     }