start-command 0.32.1 → 0.33.0

package/src/lib/args-parser.js

@@ -28,11 +28,15 @@
  * --use-command-stream             Use command-stream library for command execution (experimental)
  * --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
+ * --list [--running]               List all (or only running) 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>     Ask a detached execution to stop gracefully
  * --terminate <uuid-or-session-name> Terminate a detached execution immediately
+ * --attach <uuid-or-session-name>   Attach to a running detached session terminal
+ * --read-only                      Follow --attach output without forwarding stdin
+ * --resume <uuid-or-session> [-- cmd] Resume a stored execution (optionally with a new command)
+ * --resume-all                     Re-attach or reconcile every execution still marked running
  * --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)
  */
@@ -40,6 +44,13 @@
 const { getDefaultDockerImage } = require('./docker-utils');
 const dockerNetworkOptions = require('./docker-network-options');
 const { parseSequence, isSequence } = require('./sequence-parser');
+const { buildCommandString } = require('./shell-utils');
+const {
+  VALID_OUTPUT_FORMATS,
+  createQueryOptionDefaults,
+  parseQueryOption,
+  validateQueryOptions,
+} = require('./args-parser-queries');
 
 // Debug mode from environment
 const DEBUG =
@@ -60,15 +71,6 @@ const VALID_SHELLS = ['auto', 'bash', 'zsh', 'sh'];
  */
 const MAX_ISOLATION_DEPTH = 7;
 
-/**
- * Valid output formats for --status
- */
-const VALID_OUTPUT_FORMATS = ['links-notation', 'json', 'text'];
-
-function hasValue(value) {
-  return value !== null && value !== undefined;
-}
-
 /**
  * UUID v4 regex pattern for validation
  */
@@ -89,18 +91,25 @@ function isValidUUID(str) {
  * @returns {string} A new UUID v4 string
  */
 function generateUUID() {
-  // Try to use Node.js/Bun crypto module
-  try {
-    const crypto = require('crypto');
+  const crypto = require('crypto');
+  if (typeof crypto.randomUUID === 'function') {
     return crypto.randomUUID();
-  } catch {
-    // Fallback for environments without crypto.randomUUID
-    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
-      const r = (Math.random() * 16) | 0;
-      const v = c === 'x' ? r : (r & 0x3) | 0x8;
-      return v.toString(16);
-    });
   }
+
+  // Fallback for runtimes without crypto.randomUUID (Node < 14.17). Still a
+  // CSPRNG: session ids name isolation sessions and users, so a predictable
+  // generator is a security bug, not a cosmetic one (CodeQL js/insecure-randomness).
+  const bytes = crypto.randomBytes(16);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant 1
+  const hex = bytes.toString('hex');
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20),
+  ].join('-');
 }
 
 /**
@@ -164,6 +173,8 @@ function parseEndpointValue(value, options) {
  * Parse command line arguments into wrapper options and command
  * @param {string[]} args - Array of command line arguments
  * @returns {{wrapperOptions: object, command: string, rawCommand: string[]}}
+ *   `command` re-quotes each argv element so the inner shell sees the argument
+ *   boundaries the user typed (issue #164); `rawCommand` keeps the raw argv.
  */
 function parseArgs(args) {
   const wrapperOptions = {
@@ -195,14 +206,7 @@ function parseArgs(args) {
     keepContainerOnFail: false, // Keep docker container filesystem when command fails or OOM-kills
     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
-    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
-    cleanup: false, // Clean up stale "executing" records
-    cleanupDryRun: false, // Show what would be cleaned without actually cleaning
+    ...createQueryOptionDefaults(),
   };
 
   let commandArgs = [];
@@ -241,7 +245,7 @@ function parseArgs(args) {
 
   return {
     wrapperOptions,
-    command: commandArgs.join(' '),
+    command: buildCommandString(commandArgs),
     rawCommand: commandArgs,
   };
 }
@@ -529,125 +533,10 @@ function parseOption(args, index, options) {
     return 1;
   }
 
-  // --status <uuid-or-session-name>
-  if (arg === '--status') {
-    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
-      options.status = args[index + 1];
-      return 2;
-    } else {
-      throw new Error(`Option ${arg} requires a UUID or session name argument`);
-    }
-  }
-
-  // --status=<value>
-  if (arg.startsWith('--status=')) {
-    const value = arg.slice('--status='.length);
-    if (!value) {
-      throw new Error(
-        `Option --status requires a UUID or session name argument`
-      );
-    }
-    options.status = value;
-    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('-')) {
-      options.stop = args[index + 1];
-      return 2;
-    } else {
-      throw new Error(`Option ${arg} requires a UUID or session name argument`);
-    }
-  }
-
-  // --stop=<value>
-  if (arg.startsWith('--stop=')) {
-    const value = arg.slice('--stop='.length);
-    if (!value) {
-      throw new Error(`Option --stop requires a UUID or session name argument`);
-    }
-    options.stop = value;
-    return 1;
-  }
-
-  // --terminate <uuid-or-session-name>
-  if (arg === '--terminate') {
-    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
-      options.terminate = args[index + 1];
-      return 2;
-    } else {
-      throw new Error(`Option ${arg} requires a UUID or session name argument`);
-    }
-  }
-
-  // --terminate=<value>
-  if (arg.startsWith('--terminate=')) {
-    const value = arg.slice('--terminate='.length);
-    if (!value) {
-      throw new Error(
-        `Option --terminate requires a UUID or session name argument`
-      );
-    }
-    options.terminate = value;
-    return 1;
-  }
-
-  // --list
-  if (arg === '--list') {
-    options.list = true;
-    return 1;
-  }
-
-  // --output-format <format>
-  if (arg === '--output-format') {
-    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
-      options.outputFormat = args[index + 1].toLowerCase();
-      return 2;
-    } else {
-      throw new Error(`Option ${arg} requires a format argument`);
-    }
-  }
-
-  // --output-format=<value>
-  if (arg.startsWith('--output-format=')) {
-    options.outputFormat = arg.split('=')[1].toLowerCase();
-    return 1;
-  }
-
-  // --cleanup
-  if (arg === '--cleanup') {
-    options.cleanup = true;
-    return 1;
-  }
-
-  // --cleanup-dry-run
-  if (arg === '--cleanup-dry-run') {
-    options.cleanup = true;
-    options.cleanupDryRun = true;
-    return 1;
+  // Query/control options (--status, --list, --attach, --resume, ...)
+  const queryConsumed = parseQueryOption(args, index, options);
+  if (queryConsumed > 0) {
+    return queryConsumed;
   }
 
   // Not a recognized wrapper option
@@ -889,37 +778,7 @@ function validateOptions(options) {
     throw new Error('--keep-user option is only valid with --isolated-user');
   }
 
-  // Validate output format
-  if (hasValue(options.outputFormat)) {
-    if (!VALID_OUTPUT_FORMATS.includes(options.outputFormat)) {
-      throw new Error(
-        `Invalid output format: "${options.outputFormat}". Valid options are: ${VALID_OUTPUT_FORMATS.join(', ')}`
-      );
-    }
-  }
-
-  // Query/control modes are mutually exclusive
-  const queryModes = [
-    hasValue(options.status),
-    options.list,
-    hasValue(options.uploadLog),
-    hasValue(options.stop),
-    hasValue(options.terminate),
-    options.cleanup,
-  ].filter(Boolean).length;
-
-  if (queryModes > 1) {
-    throw new Error(
-      'Cannot combine --status, --list, --upload-log, --stop, --terminate, or --cleanup in the same invocation'
-    );
-  }
-
-  // Output format is only valid with read-only query modes
-  if (options.outputFormat && !options.status && !options.list) {
-    throw new Error(
-      '--output-format option is only valid with --status or --list'
-    );
-  }
+  validateQueryOptions(options);
 
   // Validate shell option
   if (options.shell !== null && options.shell !== undefined) {

package/src/lib/docker-cleanup.js

@@ -2,8 +2,11 @@ const { spawn, spawnSync } = require('child_process');
 const {
   appendLogFile,
   createShellLogFooterSnippet,
+  FATAL_MARKER_TAIL_BYTES,
+  readLogTail,
   shellQuote,
 } = require('./isolation-log-utils');
+const { resolveMemoryExhaustion } = require('./exit-reason');
 
 const DOCKER_CONTAINER_CLEANUP_POLICY = {
   DEFAULT: 'default',
@@ -56,7 +59,9 @@ function shouldCleanupDockerContainer(policy, exitCode, oomKilled = false) {
 function getDockerContainerCleanupInstructions(containerName) {
   return [
     `Container kept for investigation: ${containerName}`,
-    `Inspect: docker exec -it ${containerName} sh (if running) or docker start -ai ${containerName}`,
+    `Re-enter while running: $ --attach ${containerName}`,
+    `Continue the stored command: $ --resume ${containerName}`,
+    `Run another command in the same container: $ --resume ${containerName} -- <command>`,
     `Remove when done: docker rm -f ${containerName}`,
   ].join('\n');
 }
@@ -142,14 +147,80 @@ function removeDockerContainer(containerName, logPath = null) {
   return !result.error && result.status === 0;
 }
 
+/**
+ * Exit codes of a process that aborted itself: SIGABRT (134) and SIGSEGV (139).
+ * These are exactly the codes a runtime produces when it dies on its own memory
+ * limit — Node/V8 prints `FATAL ERROR: Reached heap limit ...` and aborts — long
+ * before the container limit is reached, so the kernel never OOM-kills anything
+ * and `State.OOMKilled` stays `false` (issue #165).
+ */
+const SELF_ABORT_EXIT_CODES = [134, 139];
+
+/**
+ * Appended to the kept-container reason for a self-abort exit code, so the
+ * footer stops asserting the opposite of the `FATAL ERROR` printed a few lines
+ * above it. The footer is the string downstream tooling greps.
+ */
+const OOM_FLAG_BLIND_NOTE =
+  'a runtime self-abort on its own memory limit is invisible to this flag - ' +
+  'check the log above for a fatal memory marker';
+
+/**
+ * Shell fragment computing `$__start_command_reason` for the kept footer.
+ * @returns {string} Shell command
+ */
+function buildDockerKeptReasonSnippet() {
+  return (
+    '__start_command_reason="exitCode=$__start_command_exit oomKilled=$__start_command_oom"; ' +
+    `case "$__start_command_exit" in ${SELF_ABORT_EXIT_CODES.join('|')}) ` +
+    '[ "$__start_command_oom" = true ] || ' +
+    `__start_command_reason="$__start_command_reason (${OOM_FLAG_BLIND_NOTE})";; ` +
+    'esac'
+  );
+}
+
+/**
+ * Lines appended to an attached session's message when the container is kept
+ * because the command failed. A runtime that aborts on its own memory limit
+ * never trips `State.OOMKilled`, so a bare `oomKilled false` would contradict
+ * the `FATAL ERROR` the runtime just printed into this very log (issue #165).
+ * Best effort: the tail is read right after the child exits.
+ *
+ * @param {object} params - Container name, exit code, OOM flag and log path
+ * @returns {string} Message lines to append
+ */
+function buildAttachedDockerKeptMessage({
+  containerName,
+  exitCode,
+  oomKilled,
+  logPath,
+}) {
+  let message =
+    oomKilled === true
+      ? `\nContainer kept because Docker reports it was OOM-killed.`
+      : `\nContainer kept because the command failed.`;
+  const memory = resolveMemoryExhaustion({
+    exitCode,
+    logTail: logPath ? readLogTail(logPath, FATAL_MARKER_TAIL_BYTES) : null,
+    oomKilled,
+  });
+  if (memory) {
+    message += `\nMemory exhaustion detected in the log: ${memory.memoryExhaustedReason}`;
+  }
+  return `${message}\nRemove when done: docker rm -f ${containerName}`;
+}
+
 function buildDockerKeptLogSnippet(containerName, quotedLogPath) {
   const quotedName = shellQuote(containerName);
   return (
-    `printf '\\nContainer kept for investigation: %s\\nReason: exitCode=%s oomKilled=%s\\n` +
-    `Inspect: docker exec -it %s sh (if running) or docker start -ai %s\\n` +
+    `${buildDockerKeptReasonSnippet()}; ` +
+    `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` +
     `Remove when done: docker rm -f %s\\n' ` +
-    `${quotedName} "$__start_command_exit" "$__start_command_oom" ` +
-    `${quotedName} ${quotedName} ${quotedName} >> ${quotedLogPath}`
+    `${quotedName} "$__start_command_reason" ` +
+    `${quotedName} ${quotedName} ${quotedName} ${quotedName} >> ${quotedLogPath}`
   );
 }
 
@@ -244,7 +315,11 @@ function spawnAttachedDocker(dockerArgs, logPath) {
 }
 
 module.exports = {
+  buildAttachedDockerKeptMessage,
   DOCKER_CONTAINER_CLEANUP_POLICY,
+  SELF_ABORT_EXIT_CODES,
+  OOM_FLAG_BLIND_NOTE,
+  buildDockerKeptReasonSnippet,
   getDockerCommand,
   getDockerSpawnOptions,
   getDockerContainerCleanupPolicy,

package/src/lib/execution-attach.js

@@ -0,0 +1,245 @@
+/**
+ * Attach to a tracked detached execution (issue #162).
+ *
+ * `--stop`/`--terminate` can already address a stored session name; `--attach`
+ * completes the set by re-entering the session's terminal instead of only
+ * tailing its log. `--attach --read-only` follows the output without
+ * forwarding stdin, which is the safe default for supervisors that must not
+ * accidentally type into a long-running agent session.
+ */
+
+const { spawnSync } = require('child_process');
+const { escapeForLinksNotation } = require('./output-blocks');
+const { getDockerCommand, getDockerSpawnOptions } = require('./docker-cleanup');
+const { runCommand } = require('./execution-control');
+const { SessionState, probeSession } = require('./session-probe');
+
+/**
+ * Run a command with the parent terminal attached (stdin included unless the
+ * plan is read-only). Used for `screen -r`, `tmux attach-session`,
+ * `docker attach`, and log following.
+ * @param {string} command - Executable
+ * @param {string[]} args - Arguments
+ * @param {object} plan - Attach plan (interactive flag)
+ * @returns {{success: boolean, status: ?number, error: ?string}}
+ */
+function runInteractive(command, args, plan = {}) {
+  const options = {
+    stdio: plan.interactive ? 'inherit' : ['ignore', 'inherit', 'inherit'],
+  };
+  const result = spawnSync(
+    command,
+    args,
+    command === getDockerCommand() ? getDockerSpawnOptions(options) : options
+  );
+  return {
+    success: !result.error && result.status === 0,
+    status: result.status,
+    error: result.error ? result.error.message : null,
+  };
+}
+
+function logFollowPlan(record, backend, sessionName) {
+  if (!record.logPath) {
+    return {
+      error: `Execution "${record.uuid}" has no stored log to follow.`,
+    };
+  }
+  return {
+    backend,
+    sessionName,
+    command: 'tail',
+    args: ['-f', record.logPath],
+    interactive: false,
+    method: 'LOG_FOLLOW',
+    message: `Following stored log for ${backend} session: ${sessionName}`,
+  };
+}
+
+function notRunningError(record, probe) {
+  const sessionName = probe.sessionName;
+  const uuid = record.uuid;
+  if (probe.state === SessionState.MISSING) {
+    return {
+      error:
+        `Session "${sessionName}" no longer exists, so there is nothing to attach to. ` +
+        `Use \`$ --resume ${uuid}\` to start it again, or \`$ --status ${uuid}\` to inspect the recorded result.`,
+    };
+  }
+  return {
+    error:
+      `Session "${sessionName}" is not running (state: ${probe.containerStatus || probe.state}). ` +
+      `Use \`$ --resume ${uuid}\` to continue it in the same container, or \`$ --status ${uuid}\` to inspect the recorded result.`,
+  };
+}
+
+/**
+ * Build the attach plan for an execution record.
+ * @param {object} record - Execution record
+ * @param {object} options - {readOnly: boolean, probe: object}
+ * @returns {object} Plan with command/args/interactive/method/message, or {error}
+ */
+function buildAttachPlan(record, options = {}) {
+  const readOnly = options.readOnly === true;
+  const probe = options.probe || {};
+  const opts = (record && record.options) || {};
+  const backend = opts.isolated;
+  const sessionName = opts.sessionName;
+
+  if (!sessionName) {
+    return {
+      error: 'Execution record does not contain an isolation session name.',
+    };
+  }
+
+  if (opts.isolationMode !== 'detached') {
+    return {
+      error: 'Only detached isolated executions can be attached to.',
+    };
+  }
+
+  // ssh sessions cannot be probed or re-entered locally: the stored log is the
+  // only channel back into them.
+  if (backend === 'ssh') {
+    return logFollowPlan(record, backend, sessionName);
+  }
+
+  if (!probe.alive) {
+    return notRunningError(record, { ...probe, sessionName });
+  }
+
+  switch (backend) {
+    case 'screen':
+      return readOnly
+        ? logFollowPlan(record, backend, sessionName)
+        : {
+            backend,
+            sessionName,
+            command: 'screen',
+            args: ['-r', sessionName],
+            interactive: true,
+            method: 'SCREEN_ATTACH',
+            message: `Attaching to detached screen session: ${sessionName}`,
+          };
+    case 'tmux':
+      return {
+        backend,
+        sessionName,
+        command: 'tmux',
+        args: readOnly
+          ? ['attach-session', '-r', '-t', sessionName]
+          : ['attach-session', '-t', sessionName],
+        interactive: true,
+        method: readOnly ? 'TMUX_ATTACH_READONLY' : 'TMUX_ATTACH',
+        message: `Attaching to detached tmux session: ${sessionName}${readOnly ? ' (read-only)' : ''}`,
+      };
+    case 'docker':
+      return readOnly
+        ? {
+            backend,
+            sessionName,
+            command: getDockerCommand(),
+            args: ['logs', '-f', sessionName],
+            interactive: false,
+            method: 'DOCKER_LOG_FOLLOW',
+            message: `Following logs of detached docker container: ${sessionName}`,
+          }
+        : {
+            backend,
+            sessionName,
+            command: getDockerCommand(),
+            args: ['attach', sessionName],
+            interactive: true,
+            method: 'DOCKER_ATTACH',
+            message: `Attaching to detached docker container: ${sessionName}`,
+          };
+    default:
+      return {
+        error: `Attaching to detached ${backend || 'unknown'} executions is not supported.`,
+      };
+  }
+}
+
+/**
+ * Format an attach result as links notation.
+ * @param {object} result - Attach result fields
+ * @returns {string} Links notation block
+ */
+function formatAttachResultAsLinksNotation(result) {
+  return [
+    'executionAttach',
+    `  identifier ${escapeForLinksNotation(result.identifier)}`,
+    `  uuid ${escapeForLinksNotation(result.uuid)}`,
+    `  backend ${escapeForLinksNotation(result.backend)}`,
+    `  sessionName ${escapeForLinksNotation(result.sessionName)}`,
+    `  method ${escapeForLinksNotation(result.method)}`,
+    `  readOnly ${result.readOnly === true}`,
+    `  command ${escapeForLinksNotation(result.command)}`,
+    `  message ${escapeForLinksNotation(result.message)}`,
+  ].join('\n');
+}
+
+/**
+ * Attach to a tracked execution by UUID or session name.
+ * @param {?object} store - Execution store
+ * @param {string} identifier - UUID or session name
+ * @param {object} deps - {readOnly, probe, interactiveRunner, runner}
+ * @returns {{success: boolean, output?: string, error?: string, exitCode?: number}}
+ */
+function attachExecution(store, identifier, deps = {}) {
+  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}`,
+    };
+  }
+
+  const runner = deps.runner || runCommand;
+  const probeFn = deps.probe || ((r) => probeSession(r, runner));
+  const plan = buildAttachPlan(record, {
+    readOnly: deps.readOnly === true,
+    probe: probeFn(record),
+  });
+
+  if (plan.error) {
+    return { success: false, error: plan.error };
+  }
+
+  const interactiveRunner = deps.interactiveRunner || runInteractive;
+  const commandLine = [plan.command, ...plan.args].join(' ');
+  const runResult = interactiveRunner(plan.command, plan.args, plan);
+
+  const output = formatAttachResultAsLinksNotation({
+    identifier,
+    uuid: record.uuid,
+    backend: plan.backend,
+    sessionName: plan.sessionName,
+    method: plan.method,
+    readOnly: deps.readOnly === true,
+    command: commandLine,
+    message: plan.message,
+  });
+
+  if (!runResult.success) {
+    const detail = runResult.error || `exit code ${runResult.status}`;
+    return {
+      success: false,
+      error: `Failed to attach to ${plan.backend} session "${plan.sessionName}": ${detail}`,
+      exitCode: typeof runResult.status === 'number' ? runResult.status : 1,
+    };
+  }
+
+  return { success: true, output };
+}
+
+module.exports = {
+  attachExecution,
+  buildAttachPlan,
+  formatAttachResultAsLinksNotation,
+  runInteractive,
+};