start-command 0.32.0 → 0.33.0

package/src/lib/execution-store.js

@@ -15,13 +15,14 @@
  * - startTime: Timestamp when execution started
  * - endTime: Timestamp when execution completed (null while executing)
  * - oomKilled: Docker resource-exhaustion signal when available
+ * - memoryExhausted: memory-exhaustion observation derived from the log tail
  * - options: Execution options (isolation mode, etc.)
  */
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { execSync, spawnSync } = require('child_process');
+const { execFileSync, spawnSync } = require('child_process');
 const crypto = require('crypto');
 
 // Synchronous wrapper using Bun's native ESM support
@@ -76,6 +77,21 @@ class ExecutionRecord {
     this.endTime = options.endTime || null;
     this.oomKilled =
       options.oomKilled !== undefined ? options.oomKilled : undefined;
+    // Query-time hint explaining an opaque exit code (issue #162). Derived from
+    // the log tail by the status formatter; never persisted as a verdict.
+    this.exitReason =
+      options.exitReason !== undefined ? options.exitReason : undefined;
+    // Query-time memory-exhaustion observation (issue #165). A runtime that
+    // aborts on its own heap limit is invisible to `oomKilled`, so the evidence
+    // the runtime printed into the log is surfaced separately.
+    this.memoryExhausted =
+      options.memoryExhausted !== undefined
+        ? options.memoryExhausted
+        : undefined;
+    this.memoryExhaustedReason =
+      options.memoryExhaustedReason !== undefined
+        ? options.memoryExhaustedReason
+        : undefined;
     this.workingDirectory = options.workingDirectory || process.cwd();
     this.shell = options.shell || process.env.SHELL || '/bin/sh';
     this.platform = options.platform || process.platform;
@@ -109,6 +125,18 @@ class ExecutionRecord {
     if (this.oomKilled !== undefined && this.oomKilled !== null) {
       obj.oomKilled = this.oomKilled;
     }
+    if (this.exitReason !== undefined && this.exitReason !== null) {
+      obj.exitReason = this.exitReason;
+    }
+    if (this.memoryExhausted !== undefined && this.memoryExhausted !== null) {
+      obj.memoryExhausted = this.memoryExhausted;
+    }
+    if (
+      this.memoryExhaustedReason !== undefined &&
+      this.memoryExhaustedReason !== null
+    ) {
+      obj.memoryExhaustedReason = this.memoryExhaustedReason;
+    }
     Object.assign(obj, {
       workingDirectory: this.workingDirectory,
       shell: this.shell,
@@ -389,7 +417,10 @@ class ExecutionStore {
    */
   execClink(query) {
     try {
-      const result = execSync(`clink '${query}' --db "${this.linksDbPath}"`, {
+      // The query embeds record values verbatim; a shell string would let a
+      // single quote in any of them break out of the argument
+      // (CodeQL js/shell-command-constructed-from-input, issue #168).
+      const result = execFileSync('clink', [query, '--db', this.linksDbPath], {
         encoding: 'utf8',
         timeout: 10000,
         stdio: ['pipe', 'pipe', 'pipe'],
@@ -480,7 +511,8 @@ class ExecutionStore {
 
   /**
    * Get an execution record by UUID or session name
-   * First tries exact UUID match, then falls back to session name lookup
+   * First tries exact UUID match, then the current session name, then any
+   * session name the execution used before it was resumed
    * @param {string} identifier - UUID or session name
    * @returns {ExecutionRecord|null}
    */
@@ -495,7 +527,18 @@ class ExecutionStore {
     const bySessionName = records.find(
       (r) => r.options && r.options.sessionName === identifier
     );
-    return bySessionName || null;
+    if (bySessionName) {
+      return bySessionName;
+    }
+    // Finally, honor session names this record used before it was resumed, so
+    // one logical session stays addressable across restarts (issue #162).
+    const byPreviousSessionName = records.find(
+      (r) =>
+        r.options &&
+        Array.isArray(r.options.sessionNameHistory) &&
+        r.options.sessionNameHistory.includes(identifier)
+    );
+    return byPreviousSessionName || null;
   }
 
   /**

package/src/lib/exit-reason.js

@@ -0,0 +1,234 @@
+/**
+ * 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>}
+ */
+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;
+}
+
+/**
+ * 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,
+  MEMORY_EXHAUSTION_PREFIX,
+  SIGNAL_NAMES,
+  detectExitReason,
+  detectMemoryMarker,
+  findExitReasonMarker,
+  resolveMemoryExhaustion,
+  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

@@ -204,7 +204,65 @@ 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 = {
+  LOG_TAIL_BYTES,
+  FATAL_MARKER_TAIL_BYTES,
+  readLogTail,
   getTempRoot,
   ensureDirectory,
   ensureParentDirectory,

package/src/lib/isolation.js

@@ -27,6 +27,7 @@ const {
   wrapCommandWithLogFooter,
 } = require('./isolation-log-utils');
 const {
+  buildAttachedDockerKeptMessage,
   DOCKER_CONTAINER_CLEANUP_POLICY,
   getDockerContainerCleanupPolicy,
   shouldCleanupDockerContainer,
@@ -168,6 +169,7 @@ const {
   isShellInvocationWithArgs,
   buildShellWithArgsCmdArgs,
   buildDisplayCommand,
+  toShellWords,
 } = require('./shell-utils');
 
 /** Returns true if the current process has a TTY attached. */
@@ -452,7 +454,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 +679,7 @@ function runInDocker(command, options = {}) {
         ? [shellToUse, shellInteractiveFlag]
         : [shellToUse];
       const cmdArgs = isBareShell
-        ? command.trim().split(/\s+/)
+        ? toShellWords(command)
         : isShellInvocationWithArgs(command)
           ? buildShellWithArgsCmdArgs(effectiveCommand)
           : [...shellArgs, '-c', effectiveCommand];
@@ -747,7 +749,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 +779,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 +821,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}`;
@@ -853,11 +855,12 @@ function runInDocker(command, options = {}) {
             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,
+            });
           }
 
           resolve({