start-command 0.32.1 → 0.34.0

package/src/lib/exit-reason.js

@@ -0,0 +1,264 @@
+/**
+ * Exit reason hints for finished executions.
+ *
+ * A numeric exit code alone is frequently misleading: a Bun/Node process that
+ * exhausts its heap aborts itself, so the container reports `exitCode 139` with
+ * `OOMKilled false` even though the run died of memory exhaustion (issue #162,
+ * related to #144, #148 and #151). `start` already reads the tail of the log to
+ * find the terminal footer, so the same tail is scanned for well-known fatal
+ * markers and the finding is surfaced as an extra `exitReason` field.
+ *
+ * The same scan answers a narrower question for consumers that key off
+ * `oomKilled`: was this run killed by memory exhaustion at all? That answer is
+ * surfaced as `memoryExhausted` plus `memoryExhaustedReason`, the log line that
+ * carried the evidence (issue #165).
+ *
+ * Both fields are hints, never verdicts: they never change `status`,
+ * `exitCode` or `oomKilled`.
+ */
+
+/**
+ * Reasons carrying this prefix report memory exhaustion, whatever the mechanism
+ * (runtime self-abort, kernel OOM killer, failed allocation).
+ */
+const MEMORY_EXHAUSTION_PREFIX = 'memory-exhaustion';
+
+/**
+ * Fatal markers, most specific first. The first matching entry wins.
+ * @type {{reason: string, pattern: RegExp}[]}
+ */
+const EXIT_REASON_MARKERS = [
+  {
+    reason: 'memory-exhaustion (v8-heap-limit)',
+    pattern:
+      /FATAL ERROR:[^\r\n]*(?:Reached heap limit|JavaScript heap out of memory)/i,
+  },
+  {
+    reason: 'memory-exhaustion (v8-heap-limit)',
+    pattern: /JavaScript heap out of memory/i,
+  },
+  {
+    reason: 'memory-exhaustion (kernel-oom-killer)',
+    pattern:
+      /Out of memory: Kill(?:ed)? process|oom-kill(?:er)?[: ]|Killed process \d+/i,
+  },
+  {
+    reason: 'memory-exhaustion (go-runtime)',
+    pattern: /fatal error: runtime: out of memory/i,
+  },
+  {
+    reason: 'memory-exhaustion (allocation-failure)',
+    pattern:
+      /std::bad_alloc|Cannot allocate memory|memory allocation of \d+ bytes failed|Allocation failed - process out of memory|Array buffer allocation failed/i,
+  },
+];
+
+/**
+ * Exit codes above 128 encode the signal that killed the process.
+ * Only the signals that actually show up in command logs are named.
+ * @type {Object<number, string>}
+ */
+/** Rendered when an exit code is unavailable or not numeric. */
+const UNKNOWN_EXIT_CODE = 'unknown';
+
+const SIGNAL_NAMES = {
+  1: 'SIGHUP',
+  2: 'SIGINT',
+  3: 'SIGQUIT',
+  4: 'SIGILL',
+  6: 'SIGABRT',
+  8: 'SIGFPE',
+  9: 'SIGKILL',
+  11: 'SIGSEGV',
+  13: 'SIGPIPE',
+  15: 'SIGTERM',
+};
+
+/**
+ * Longest `memoryExhaustedReason` reported. A marker line is a single line of
+ * runtime output, but a log can contain arbitrarily long lines, and the reason
+ * travels inside status records that stay readable only when bounded.
+ */
+const MAX_MARKER_LINE_LENGTH = 300;
+
+/**
+ * Extract the whole log line containing `index`, trimmed and length-bounded.
+ * @param {string} text - Log text
+ * @param {number} index - Offset of the match inside `text`
+ * @returns {string} The line the match sits on
+ */
+function extractLineAt(text, index) {
+  const start = text.lastIndexOf('\n', index) + 1;
+  const end = text.indexOf('\n', index);
+  const line = text.slice(start, end === -1 ? undefined : end).trim();
+  return line.length > MAX_MARKER_LINE_LENGTH
+    ? `${line.slice(0, MAX_MARKER_LINE_LENGTH)}...`
+    : line;
+}
+
+/**
+ * Find the first known fatal marker in log text.
+ * @param {string|null|undefined} text - Log text (usually the log tail)
+ * @param {(marker: {reason: string, pattern: RegExp}) => boolean} [accept] - Marker filter
+ * @returns {{reason: string, line: string}|null} Marker and the line carrying it
+ */
+function findExitReasonMarker(text, accept = () => true) {
+  if (!text) {
+    return null;
+  }
+  for (const marker of EXIT_REASON_MARKERS) {
+    if (!accept(marker)) {
+      continue;
+    }
+    const match = marker.pattern.exec(text);
+    if (match) {
+      return { reason: marker.reason, line: extractLineAt(text, match.index) };
+    }
+  }
+  return null;
+}
+
+/**
+ * Scan log text for a known fatal marker.
+ * @param {string|null|undefined} text - Log text (usually the log tail)
+ * @returns {string|null} Detected reason, or null when nothing matched
+ */
+function detectExitReason(text) {
+  const marker = findExitReasonMarker(text);
+  return marker ? marker.reason : null;
+}
+
+/**
+ * Scan log text for a marker that specifically reports memory exhaustion.
+ * @param {string|null|undefined} text - Log text (usually the log tail)
+ * @returns {{reason: string, line: string}|null} Marker and the line carrying it
+ */
+function detectMemoryMarker(text) {
+  return findExitReasonMarker(text, (marker) =>
+    marker.reason.startsWith(MEMORY_EXHAUSTION_PREFIX)
+  );
+}
+
+/**
+ * Resolve the memory-exhaustion observation for a finished execution (#165).
+ *
+ * A runtime that aborts on its own heap limit is invisible to every container
+ * signal: it dies below the container limit, so `State.OOMKilled` stays `false`
+ * and the cgroup `oom_kill` counter stays `0`. The only evidence is what the
+ * runtime printed on its way out, which sits in the very log tail the footer
+ * scan already reads.
+ *
+ * Like `oomKilled` (#151) this is an *observation*, never a verdict: it is only
+ * derived for a run that already ended abnormally, so a log that merely quotes
+ * a fatal marker (a test fixture, an `rg` dump) cannot turn a clean run into a
+ * reported memory failure.
+ *
+ * @param {{exitCode?: number|null, logTail?: string|null, oomKilled?: boolean}|null} input
+ * @returns {{memoryExhausted: true, memoryExhaustedReason: string}|null}
+ */
+function resolveMemoryExhaustion(input) {
+  if (!input) {
+    return null;
+  }
+  const { exitCode } = input;
+  if (
+    typeof exitCode !== 'number' ||
+    !Number.isFinite(exitCode) ||
+    exitCode === 0
+  ) {
+    return null;
+  }
+
+  const marker = detectMemoryMarker(input.logTail);
+  if (marker) {
+    return { memoryExhausted: true, memoryExhaustedReason: marker.line };
+  }
+  if (input.oomKilled === true) {
+    return {
+      memoryExhausted: true,
+      memoryExhaustedReason: 'Docker reported State.OOMKilled=true',
+    };
+  }
+  return null;
+}
+
+/**
+ * Map a shell exit code to the signal name it encodes.
+ * @param {number|null|undefined} exitCode - Terminal exit code
+ * @returns {string|null} Signal name, or null when the code is not a signal
+ */
+function signalNameForExitCode(exitCode) {
+  if (typeof exitCode !== 'number' || !Number.isFinite(exitCode)) {
+    return null;
+  }
+  if (exitCode <= 128 || exitCode > 128 + 64) {
+    return null;
+  }
+  return SIGNAL_NAMES[exitCode - 128] || null;
+}
+
+/**
+ * Describe a terminal exit code, decoding the `128+n` signal convention.
+ *
+ * Single source of truth for issue #171.4: the detached Docker watcher writes
+ * this text into the log at completion time (through the shell it generates),
+ * and `--status` renders the same text at query time from the stored record.
+ * Both used to decode `128+n` on their own, so they could disagree.
+ *
+ * @param {number|string|null|undefined} exitCode - Terminal exit code
+ * @returns {{code: number|null, signal: string|null, text: string}} Description
+ */
+function describeExitCode(exitCode) {
+  const code =
+    typeof exitCode === 'number' ? exitCode : Number.parseInt(exitCode, 10);
+  if (!Number.isFinite(code)) {
+    return { code: null, signal: null, text: UNKNOWN_EXIT_CODE };
+  }
+  const signal = signalNameForExitCode(code);
+  return {
+    code,
+    signal,
+    text: signal ? `${code} (${signal} - 128+${code - 128})` : String(code),
+  };
+}
+
+/**
+ * Resolve the best available hint for why an execution ended.
+ *
+ * Precedence: the log marker (evidence written by the command itself), then the
+ * cgroup OOM observation, then the signal encoded in the exit code.
+ *
+ * @param {{exitCode?: number|null, logTail?: string|null, oomKilled?: boolean}|null} input
+ * @returns {string|null} Exit reason hint, or null when nothing is known
+ */
+function resolveExitReason(input) {
+  if (!input) {
+    return null;
+  }
+
+  const fromLog = detectExitReason(input.logTail);
+  if (fromLog) {
+    return fromLog;
+  }
+
+  if (input.oomKilled === true) {
+    return 'memory-exhaustion (cgroup-oom-killer)';
+  }
+
+  const signalName = signalNameForExitCode(input.exitCode);
+  return signalName ? `signal (${signalName})` : null;
+}
+
+module.exports = {
+  EXIT_REASON_MARKERS,
+  UNKNOWN_EXIT_CODE,
+  MEMORY_EXHAUSTION_PREFIX,
+  SIGNAL_NAMES,
+  detectExitReason,
+  detectMemoryMarker,
+  findExitReasonMarker,
+  resolveMemoryExhaustion,
+  describeExitCode,
+  resolveExitReason,
+  signalNameForExitCode,
+};

package/src/lib/failure-handler.js

@@ -4,7 +4,7 @@
  * Handles command failures - detects repository, uploads logs, creates issues
  */
 
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 const os = require('os');
 const fs = require('fs');
 const path = require('path');
@@ -97,7 +97,7 @@ function detectRepository(cmdName) {
     let cmdPath;
 
     try {
-      cmdPath = execSync(`${whichCmd} ${cmdName}`, {
+      cmdPath = execFileSync(whichCmd, [cmdName], {
         encoding: 'utf8',
         stdio: ['pipe', 'pipe', 'pipe'],
       }).trim();
@@ -117,7 +117,7 @@ function detectRepository(cmdName) {
     // Check if it's in npm global modules
     let npmGlobalPath;
     try {
-      npmGlobalPath = execSync('npm root -g', {
+      npmGlobalPath = execFileSync('npm', ['root', '-g'], {
         encoding: 'utf8',
         stdio: ['pipe', 'pipe', 'pipe'],
       }).trim();
@@ -183,42 +183,28 @@ function detectRepository(cmdName) {
       packageName = cmdName;
     }
 
-    // Try to get repository URL from npm
-    try {
-      const npmInfo = execSync(
-        `npm view ${packageName} repository.url 2>/dev/null`,
-        {
+    // Try the repository URL, then the bugs URL, from the npm registry.
+    // execFileSync, not execSync: packageName comes from a path or from the
+    // failing command's own name, and a shell would run anything it carries
+    // (CodeQL js/shell-command-injection-from-environment).
+    for (const field of ['repository.url', 'bugs.url']) {
+      let url;
+      try {
+        url = execFileSync('npm', ['view', packageName, field], {
           encoding: 'utf8',
-          stdio: ['pipe', 'pipe', 'pipe'],
-        }
-      ).trim();
-
-      if (npmInfo) {
-        // Parse git URL to extract owner and repo
-        const parsed = parseGitUrl(npmInfo);
-        if (parsed) {
-          return parsed;
-        }
+          stdio: ['pipe', 'pipe', 'ignore'],
+        }).trim();
+      } catch {
+        // npm view failed: package might not exist or have no such field.
+        continue;
       }
-    } catch {
-      // npm view failed, package might not exist or have no repository
-    }
 
-    // Try to get homepage or bugs URL as fallback
-    try {
-      const bugsUrl = execSync(`npm view ${packageName} bugs.url 2>/dev/null`, {
-        encoding: 'utf8',
-        stdio: ['pipe', 'pipe', 'pipe'],
-      }).trim();
-
-      if (bugsUrl && bugsUrl.includes('github.com')) {
-        const parsed = parseGitUrl(bugsUrl);
-        if (parsed) {
-          return parsed;
-        }
+      // parseGitUrl anchors on the github.com host itself, so no separate
+      // (and substring-only) host check is needed here.
+      const parsed = parseGitUrl(url);
+      if (parsed) {
+        return parsed;
       }
-    } catch {
-      // Fallback also failed
     }
 
     return null;
@@ -258,7 +244,7 @@ function parseGitUrl(url) {
  */
 function isGhAuthenticated() {
   try {
-    execSync('gh auth status', { stdio: ['pipe', 'pipe', 'pipe'] });
+    execFileSync('gh', ['auth', 'status'], { stdio: ['pipe', 'pipe', 'pipe'] });
     return true;
   } catch {
     return false;
@@ -273,7 +259,9 @@ function isGhUploadLogAvailable() {
   const isWindows = process.platform === 'win32';
   try {
     const whichCmd = isWindows ? 'where' : 'which';
-    execSync(`${whichCmd} gh-upload-log`, { stdio: ['pipe', 'pipe', 'pipe'] });
+    execFileSync(whichCmd, ['gh-upload-log'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
     return true;
   } catch {
     return false;
@@ -287,7 +275,7 @@ function isGhUploadLogAvailable() {
  */
 function uploadLog(logPath) {
   try {
-    const result = execSync(`gh-upload-log "${logPath}" --public`, {
+    const result = execFileSync('gh-upload-log', [logPath, '--public'], {
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'pipe'],
     });
@@ -320,7 +308,7 @@ function uploadLog(logPath) {
 function canCreateIssue(owner, repo) {
   try {
     // Check if the repository exists and we have access
-    execSync(`gh repo view ${owner}/${repo} --json name`, {
+    execFileSync('gh', ['repo', 'view', `${owner}/${repo}`, '--json', 'name'], {
       stdio: ['pipe', 'pipe', 'pipe'],
     });
     return true;
@@ -364,8 +352,22 @@ function createIssue(repoInfo, fullCommand, exitCode, logUrl) {
     body += `---\n`;
     body += `*This issue was automatically created by [start-command](https://github.com/link-foundation/start)*\n`;
 
-    const result = execSync(
-      `gh issue create --repo ${repoInfo.owner}/${repoInfo.repo} --title "${title.replace(/"/g, '\\"')}" --body "${body.replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`,
+    // execFileSync passes the title and body as argv entries, so no quoting is
+    // involved: the failing command they quote reached the shell verbatim
+    // before, and its newlines survived only as the two characters "\n"
+    // (CodeQL js/incomplete-sanitization, issue #168).
+    const result = execFileSync(
+      'gh',
+      [
+        'issue',
+        'create',
+        '--repo',
+        `${repoInfo.owner}/${repoInfo.repo}`,
+        '--title',
+        title,
+        '--body',
+        body,
+      ],
       {
         encoding: 'utf8',
         stdio: ['pipe', 'pipe', 'pipe'],

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

@@ -4,6 +4,7 @@ const { spawn } = require('child_process');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { describeExitCode } = require('./exit-reason');
 
 function getTempRoot() {
   return process.env.START_TEMP_ROOT || path.join(os.tmpdir(), 'start-command');
@@ -158,8 +159,11 @@ function shellQuote(value) {
 }
 
 function createShellLogFooterSnippet() {
+  // UTC, to match `createLogFooter()` (which formats an ISO timestamp). Two
+  // writers of the same `Finished:` line disagreeing on the timezone makes the
+  // footer useless as a source for `endTime` (issue #170.2).
   const dateCommand =
-    "date '+%Y-%m-%d %H:%M:%S.%3N' 2>/dev/null || date '+%Y-%m-%d %H:%M:%S'";
+    "date -u '+%Y-%m-%d %H:%M:%S.%3N' 2>/dev/null || date -u '+%Y-%m-%d %H:%M:%S'";
   return `printf '\\n==================================================\\nFinished: %s\\nExit Code: %s\\n' "$(${dateCommand})" "$__start_command_exit"`;
 }
 
@@ -204,7 +208,68 @@ function runAsIsolatedUser(cmd, username) {
   });
 }
 
+/**
+ * Number of trailing bytes scanned for the terminal log footer. The footer is
+ * always appended at the very end of the log, so there is no reason to read
+ * (potentially megabytes of) command output on every `--status` call.
+ */
+const LOG_TAIL_BYTES = 16 * 1024;
+
+/**
+ * Number of trailing bytes scanned for a fatal marker (issue #165).
+ *
+ * Wider than the footer window because a dying runtime keeps printing after the
+ * marker: V8 emits a full native stack trace between `FATAL ERROR: Reached heap
+ * limit ...` and the end of the log, which can push the marker several tens of
+ * kilobytes away from EOF.
+ */
+const FATAL_MARKER_TAIL_BYTES = 64 * 1024;
+
+/**
+ * Read the last `bytes` bytes of a file as UTF-8 text.
+ *
+ * A partial first line is dropped: the slice can start in the middle of a line,
+ * and that fragment must not be treated as the beginning of a line by the
+ * anchored footer pattern.
+ *
+ * @param {string} logPath - Path to the log file
+ * @param {number} [bytes] - Maximum number of trailing bytes to read
+ * @returns {string|null} Tail content, or null when the file cannot be read
+ */
+function readLogTail(logPath, bytes = LOG_TAIL_BYTES) {
+  let fd;
+  try {
+    fd = fs.openSync(logPath, 'r');
+    const size = fs.fstatSync(fd).size;
+    const length = Math.min(size, bytes);
+    const buffer = Buffer.alloc(length);
+    fs.readSync(fd, buffer, 0, length, size - length);
+    const tail = buffer.toString('utf8');
+    if (size <= bytes) {
+      return tail;
+    }
+    const firstNewline = tail.indexOf('\n');
+    return firstNewline === -1 ? '' : tail.slice(firstNewline + 1);
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
 module.exports = {
+  // Re-exported so the log writers and the status formatter share one decoder
+  // for the `128 + n` signal convention (issue #171.4).
+  describeExitCode,
+  LOG_TAIL_BYTES,
+  FATAL_MARKER_TAIL_BYTES,
+  readLogTail,
   getTempRoot,
   ensureDirectory,
   ensureParentDirectory,

package/src/lib/isolation.js

@@ -27,12 +27,14 @@ const {
   wrapCommandWithLogFooter,
 } = require('./isolation-log-utils');
 const {
+  buildAttachedDockerKeptMessage,
+  readDockerContainerState,
+  recordAttachedDockerPostMortem,
   DOCKER_CONTAINER_CLEANUP_POLICY,
   getDockerContainerCleanupPolicy,
   shouldCleanupDockerContainer,
   getDockerContainerCleanupInstructions,
   appendDockerContainerCleanupPolicyMessage,
-  readDockerContainerOomKilled,
   readDockerContainerStatus,
   removeDockerContainer,
   startDetachedDockerCompletionWatcher,
@@ -168,6 +170,7 @@ const {
   isShellInvocationWithArgs,
   buildShellWithArgsCmdArgs,
   buildDisplayCommand,
+  toShellWords,
 } = require('./shell-utils');
 
 /** Returns true if the current process has a TTY attached. */
@@ -452,7 +455,7 @@ function runInSsh(command, options = {}) {
     } else {
       const extraFlags = shellInteractiveFlag ? [shellInteractiveFlag] : [];
       const sshArgs = isInteractiveShellCommand(command)
-        ? [sshTarget, ...command.trim().split(/\s+/)]
+        ? [sshTarget, ...toShellWords(command)]
         : useExplicitShell
           ? [sshTarget, useExplicitShell, ...extraFlags, '-c', command]
           : [sshTarget, command];
@@ -677,7 +680,7 @@ function runInDocker(command, options = {}) {
         ? [shellToUse, shellInteractiveFlag]
         : [shellToUse];
       const cmdArgs = isBareShell
-        ? command.trim().split(/\s+/)
+        ? toShellWords(command)
         : isShellInvocationWithArgs(command)
           ? buildShellWithArgsCmdArgs(effectiveCommand)
           : [...shellArgs, '-c', effectiveCommand];
@@ -732,7 +735,8 @@ function runInDocker(command, options = {}) {
       startDetachedDockerCompletionWatcher(
         containerName,
         cleanupPolicy,
-        options.logPath
+        options.logPath,
+        options.executionId || null
       );
 
       let message = `Command started in detached docker container: ${containerName}`;
@@ -747,7 +751,7 @@ function runInDocker(command, options = {}) {
         containerName,
         cleanupPolicy
       );
-      message += `\nAttach with: docker attach ${containerName}`;
+      message += `\nAttach with: $ --attach ${containerName} (or docker attach ${containerName})`;
       message += `\nView logs: docker logs ${containerName}`;
       if (options.logPath) {
         message += `\nLive log: ${options.logPath}`;
@@ -777,7 +781,7 @@ function runInDocker(command, options = {}) {
       // Shell with -c: pass directly as argv (avoids double-wrapping and quote-stripping, issue #91).
       let attachedCmdArgs;
       if (isBareShell) {
-        const parts = command.trim().split(/\s+/);
+        const parts = toShellWords(command);
         const bareFlag = getShellInteractiveFlag(parts[0]);
         attachedCmdArgs =
           bareFlag && !parts.includes(bareFlag)
@@ -819,7 +823,7 @@ function runInDocker(command, options = {}) {
           let message = `Docker container "${containerName}" exited with code ${exitCode}`;
           // Bare shell exited non-zero quickly → startup file error; suggest --norc (issue #84).
           if (isBareShell && exitCode !== 0 && durationMs < 3000) {
-            const shell0 = command.trim().split(/\s+/)[0];
+            const shell0 = toShellWords(command)[0];
             // prettier-ignore
             const norc = path.basename(shell0) === 'zsh' ? '--no-rcs' : '--norc';
             const hint = `Hint: The shell exited immediately — its startup file (.bashrc/.zshrc) may have errors.\nTry skipping startup files: ${shell0} ${norc}`;
@@ -827,7 +831,15 @@ function runInDocker(command, options = {}) {
             message += `\n${hint}`;
           }
 
-          const oomKilled = readDockerContainerOomKilled(containerName);
+          const dockerState = readDockerContainerState(containerName);
+          const oomKilled = dockerState ? dockerState.oomKilled : null;
+          const postMortem = (removed) =>
+            recordAttachedDockerPostMortem({
+              containerName,
+              state: dockerState,
+              logPath: options.logPath,
+              removed,
+            });
           const launchFailed =
             !containerExistedBeforeLaunch &&
             readDockerContainerStatus(containerName) === 'created';
@@ -842,22 +854,23 @@ function runInDocker(command, options = {}) {
             shouldCleanupDockerContainer(cleanupPolicy, exitCode, oomKilled)
           ) {
             if (removeDockerContainer(containerName, options.logPath)) {
-              message += `\nContainer removed after completion.`;
+              message += `\nContainer removed after completion.${postMortem(true)}`;
             } else {
               message += `\nWarning: failed to remove container automatically.`;
               message += `\nRemove when done: docker rm -f ${containerName}`;
             }
           } else if (cleanupPolicy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP) {
-            message += `\n${getDockerContainerCleanupInstructions(containerName)}`;
+            message += `\n${getDockerContainerCleanupInstructions(containerName)}${postMortem(false)}`;
           } else if (
             cleanupPolicy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL ||
             cleanupPolicy === DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT
           ) {
-            message +=
-              oomKilled === true
-                ? `\nContainer kept because Docker reports it was OOM-killed.`
-                : `\nContainer kept because the command failed.`;
-            message += `\nRemove when done: docker rm -f ${containerName}`;
+            message += `${buildAttachedDockerKeptMessage({
+              containerName,
+              exitCode,
+              oomKilled,
+              logPath: options.logPath,
+            })}${postMortem(false)}`;
           }
 
           resolve({