start-command 0.30.1 → 0.30.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # start-command
 
+## 0.30.3
+
+### Patch Changes
+
+- 55ff85b: Treat detached Docker sessions with `oomKilled` as terminal in status output, using Docker's exit code when available and 137 as the OOM fallback.
+
+## 0.30.2
+
+### Patch Changes
+
+- Apply the CI test runner's 30 second timeout consistently so slower integration-style tests do not fail at Bun's default 5 second limit.
+
+  Surface detached Docker OOMKilled status and preserve abnormal containers under the default cleanup policy.
+
 ## 0.30.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.30.1",
+  "version": "0.30.3",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {

package/src/lib/args-parser.js

@@ -20,9 +20,9 @@
  * --keep-user                      Keep isolated user after command completes (don't delete)
  * --keep-alive, -k                 Keep isolation environment alive after command exits
  * --auto-remove-docker-container   Always remove docker container after exit (compatibility alias)
- * --always-cleanup-container       Always remove docker container after exit (default)
+ * --always-cleanup-container       Always remove docker container after exit
  * --keep-container                 Keep docker container filesystem after exit
- * --keep-container-on-fail         Remove successful docker containers, keep failed ones
+ * --keep-container-on-fail         Remove successful docker containers, keep failed or OOM-killed ones
  * --shell <shell>                  Shell to use in isolation environments: auto, bash, zsh, sh (default: auto)
  * --use-command-stream             Use command-stream library for command execution (experimental)
  * --verbose                        Enable verbose/debug output (sets START_VERBOSE=1)
@@ -185,9 +185,9 @@ function parseArgs(args) {
     keepUser: false, // Keep isolated user after command completes (don't delete)
     keepAlive: false, // Keep environment alive after command exits
     autoRemoveDockerContainer: false, // Always remove docker container after exit (compatibility alias)
-    alwaysCleanupContainer: false, // Explicitly request default always-cleanup docker policy
+    alwaysCleanupContainer: false, // Force docker container cleanup after exit
     keepContainer: false, // Keep docker container filesystem after exit
-    keepContainerOnFail: false, // Keep docker container filesystem only when command fails
+    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

package/src/lib/docker-cleanup.js

@@ -6,11 +6,23 @@ const {
 } = require('./isolation-log-utils');
 
 const DOCKER_CONTAINER_CLEANUP_POLICY = {
+  DEFAULT: 'default',
   ALWAYS: 'always',
   KEEP: 'keep',
   KEEP_ON_FAIL: 'keep-on-fail',
 };
 
+function getDockerCommand() {
+  return process.env.START_DOCKER_BIN || 'docker';
+}
+
+function getDockerSpawnOptions(options = {}) {
+  if (process.platform === 'win32' && process.env.START_DOCKER_BIN) {
+    return { ...options, shell: true };
+  }
+  return options;
+}
+
 function getDockerContainerCleanupPolicy(options = {}) {
   if (options.keepContainer) {
     return DOCKER_CONTAINER_CLEANUP_POLICY.KEEP;
@@ -18,15 +30,25 @@ function getDockerContainerCleanupPolicy(options = {}) {
   if (options.keepContainerOnFail) {
     return DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL;
   }
-  return DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS;
+  if (options.alwaysCleanupContainer || options.autoRemoveDockerContainer) {
+    return DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS;
+  }
+  return DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT;
+}
+
+function isAbnormalDockerExit(exitCode, oomKilled = false) {
+  return exitCode !== 0 || oomKilled === true;
 }
 
-function shouldCleanupDockerContainer(policy, exitCode) {
+function shouldCleanupDockerContainer(policy, exitCode, oomKilled = false) {
   if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS) {
     return true;
   }
+  if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT) {
+    return !isAbnormalDockerExit(exitCode, oomKilled);
+  }
   if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL) {
-    return exitCode === 0;
+    return !isAbnormalDockerExit(exitCode, oomKilled);
   }
   return false;
 }
@@ -50,18 +72,53 @@ function appendDockerContainerCleanupPolicyMessage(
   if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL) {
     return (
       `${message}\nContainer will be removed after successful completion.` +
-      `\nContainer will be kept if the command fails.` +
+      `\nContainer will be kept if the command fails or Docker reports OOMKilled.` +
+      `\nRemove when done: docker rm -f ${containerName}`
+    );
+  }
+  if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT) {
+    return (
+      `${message}\nContainer will be removed after successful completion.` +
+      `\nContainer will be kept if the command fails or Docker reports OOMKilled.` +
       `\nRemove when done: docker rm -f ${containerName}`
     );
   }
   return `${message}\nContainer will be removed after command completes.`;
 }
 
+function readDockerContainerOomKilled(containerName) {
+  const result = spawnSync(
+    getDockerCommand(),
+    ['inspect', '-f', '{{.State.OOMKilled}}', containerName],
+    getDockerSpawnOptions({
+      encoding: 'utf8',
+      env: process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+  );
+  if (result.error || result.status !== 0) {
+    return null;
+  }
+  const value = String(result.stdout || '').trim();
+  if (value === 'true') {
+    return true;
+  }
+  if (value === 'false') {
+    return false;
+  }
+  return null;
+}
+
 function removeDockerContainer(containerName, logPath = null) {
-  const result = spawnSync('docker', ['rm', '-f', containerName], {
-    encoding: 'utf8',
-    stdio: ['pipe', 'pipe', 'pipe'],
-  });
+  const result = spawnSync(
+    getDockerCommand(),
+    ['rm', '-f', containerName],
+    getDockerSpawnOptions({
+      encoding: 'utf8',
+      env: process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+  );
   const output = `${result.stdout || ''}${result.stderr || ''}`;
   if (logPath && output) {
     appendLogFile(logPath, output.endsWith('\n') ? output : `${output}\n`);
@@ -69,6 +126,24 @@ function removeDockerContainer(containerName, logPath = null) {
   return !result.error && result.status === 0;
 }
 
+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` +
+    `Remove when done: docker rm -f %s\\n' ` +
+    `${quotedName} "$__start_command_exit" "$__start_command_oom" ` +
+    `${quotedName} ${quotedName} ${quotedName} >> ${quotedLogPath}`
+  );
+}
+
+function buildSuccessfulNonOomCondition() {
+  return (
+    '[ "$__start_command_exit" -eq 0 ] 2>/dev/null && ' +
+    '[ "$__start_command_oom" != true ]'
+  );
+}
+
 function buildDetachedDockerCompletionScript(containerName, policy, logPath) {
   const quotedName = shellQuote(containerName);
   const parts = [];
@@ -77,26 +152,37 @@ function buildDetachedDockerCompletionScript(containerName, policy, logPath) {
     const quotedLogPath = shellQuote(logPath);
     parts.push(`docker logs -f ${quotedName} >> ${quotedLogPath} 2>&1`);
     parts.push(
-      `__start_command_exit=$(docker inspect -f '{{.State.ExitCode}}' ${quotedName} 2>/dev/null || printf '%s' '-1')`
+      `__start_command_state=$(docker inspect -f '{{.State.ExitCode}} {{.State.OOMKilled}}' ${quotedName} 2>/dev/null || printf '%s' '-1 false')`
     );
+    parts.push('__start_command_exit=${__start_command_state%% *}');
+    parts.push('__start_command_oom=${__start_command_state##* }');
     if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS) {
       parts.push(`docker rm -f ${quotedName} >> ${quotedLogPath} 2>&1 || true`);
-    } else if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL) {
+    } else if (
+      policy === DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT ||
+      policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL
+    ) {
+      const successCondition = buildSuccessfulNonOomCondition();
       parts.push(
-        `if [ "$__start_command_exit" -eq 0 ] 2>/dev/null; then docker rm -f ${quotedName} >> ${quotedLogPath} 2>&1 || true; fi`
+        `if ${successCondition}; then docker rm -f ${quotedName} >> ${quotedLogPath} 2>&1 || true; else ${buildDockerKeptLogSnippet(containerName, quotedLogPath)}; fi`
       );
     }
     parts.push(`${createShellLogFooterSnippet()} >> ${quotedLogPath}`);
   } else {
     parts.push(`docker wait ${quotedName} >/dev/null 2>&1`);
     parts.push(
-      `__start_command_exit=$(docker inspect -f '{{.State.ExitCode}}' ${quotedName} 2>/dev/null || printf '%s' '-1')`
+      `__start_command_state=$(docker inspect -f '{{.State.ExitCode}} {{.State.OOMKilled}}' ${quotedName} 2>/dev/null || printf '%s' '-1 false')`
     );
+    parts.push('__start_command_exit=${__start_command_state%% *}');
+    parts.push('__start_command_oom=${__start_command_state##* }');
     if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS) {
       parts.push(`docker rm -f ${quotedName} >/dev/null 2>&1 || true`);
-    } else if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL) {
+    } else if (
+      policy === DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT ||
+      policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL
+    ) {
       parts.push(
-        `if [ "$__start_command_exit" -eq 0 ] 2>/dev/null; then docker rm -f ${quotedName} >/dev/null 2>&1 || true; fi`
+        `if ${buildSuccessfulNonOomCondition()}; then docker rm -f ${quotedName} >/dev/null 2>&1 || true; fi`
       );
     }
   }
@@ -118,12 +204,20 @@ function startDetachedDockerCompletionWatcher(containerName, policy, logPath) {
 
 function spawnAttachedDocker(dockerArgs, logPath) {
   if (!logPath) {
-    return spawn('docker', dockerArgs, { stdio: 'inherit' });
+    return spawn(
+      getDockerCommand(),
+      dockerArgs,
+      getDockerSpawnOptions({ stdio: 'inherit' })
+    );
   }
 
-  const child = spawn('docker', dockerArgs, {
-    stdio: ['inherit', 'pipe', 'pipe'],
-  });
+  const child = spawn(
+    getDockerCommand(),
+    dockerArgs,
+    getDockerSpawnOptions({
+      stdio: ['inherit', 'pipe', 'pipe'],
+    })
+  );
   const tee = (chunk, stream) => {
     stream.write(chunk);
     appendLogFile(logPath, chunk.toString());
@@ -135,11 +229,16 @@ function spawnAttachedDocker(dockerArgs, logPath) {
 
 module.exports = {
   DOCKER_CONTAINER_CLEANUP_POLICY,
+  getDockerCommand,
+  getDockerSpawnOptions,
   getDockerContainerCleanupPolicy,
+  isAbnormalDockerExit,
   shouldCleanupDockerContainer,
   getDockerContainerCleanupInstructions,
   appendDockerContainerCleanupPolicyMessage,
+  readDockerContainerOomKilled,
   removeDockerContainer,
+  buildDetachedDockerCompletionScript,
   startDetachedDockerCompletionWatcher,
   spawnAttachedDocker,
 };

package/src/lib/execution-control.js

@@ -10,6 +10,7 @@ const {
   escapeForLinksNotation,
   formatAsNestedLinksNotation,
 } = require('./output-blocks');
+const { getDockerCommand, getDockerSpawnOptions } = require('./docker-cleanup');
 
 const ControlAction = {
   STOP: 'stop',
@@ -17,10 +18,15 @@ const ControlAction = {
 };
 
 function runCommand(command, args) {
-  const result = spawnSync(command, args, {
+  const options = {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
-  });
+  };
+  const result = spawnSync(
+    command,
+    args,
+    command === getDockerCommand() ? getDockerSpawnOptions(options) : options
+  );
 
   return {
     success: !result.error && result.status === 0,
@@ -143,7 +149,7 @@ function collectProcessIds(record, runner = runCommand) {
     addIfPresent(processIds, 'commandPids', commandPids);
   } else if (isolated === 'docker') {
     addIfPresent(processIds, 'containerId', opts.containerId);
-    const result = runner('docker', [
+    const result = runner(getDockerCommand(), [
       'inspect',
       '-f',
       '{{.Id}} {{.State.Pid}}',

package/src/lib/execution-store.js

@@ -14,6 +14,7 @@
  * - logPath: Path to the log file
  * - startTime: Timestamp when execution started
  * - endTime: Timestamp when execution completed (null while executing)
+ * - oomKilled: Docker resource-exhaustion signal when available
  * - options: Execution options (isolation mode, etc.)
  */
 
@@ -73,6 +74,8 @@ class ExecutionRecord {
     this.logPath = options.logPath || '';
     this.startTime = options.startTime || new Date().toISOString();
     this.endTime = options.endTime || null;
+    this.oomKilled =
+      options.oomKilled !== undefined ? options.oomKilled : undefined;
     this.workingDirectory = options.workingDirectory || process.cwd();
     this.shell = options.shell || process.env.SHELL || '/bin/sh';
     this.platform = options.platform || process.platform;
@@ -93,7 +96,7 @@ class ExecutionRecord {
    * Convert to plain object for serialization
    */
   toObject() {
-    return {
+    const obj = {
       uuid: this.uuid,
       pid: this.pid,
       status: this.status,
@@ -102,11 +105,17 @@ class ExecutionRecord {
       logPath: this.logPath,
       startTime: this.startTime,
       endTime: this.endTime,
+    };
+    if (this.oomKilled !== undefined && this.oomKilled !== null) {
+      obj.oomKilled = this.oomKilled;
+    }
+    Object.assign(obj, {
       workingDirectory: this.workingDirectory,
       shell: this.shell,
       platform: this.platform,
       options: this.options,
-    };
+    });
+    return obj;
   }
 
   /**

package/src/lib/isolation.js

@@ -27,6 +27,7 @@ const {
   shouldCleanupDockerContainer,
   getDockerContainerCleanupInstructions,
   appendDockerContainerCleanupPolicyMessage,
+  readDockerContainerOomKilled,
   removeDockerContainer,
   startDetachedDockerCompletionWatcher,
   spawnAttachedDocker,
@@ -758,7 +759,11 @@ function runInDocker(command, options = {}) {
             message += `\n${hint}`;
           }
 
-          if (shouldCleanupDockerContainer(cleanupPolicy, exitCode)) {
+          const oomKilled = readDockerContainerOomKilled(containerName);
+
+          if (
+            shouldCleanupDockerContainer(cleanupPolicy, exitCode, oomKilled)
+          ) {
             if (removeDockerContainer(containerName, options.logPath)) {
               message += `\nContainer removed after completion.`;
             } else {
@@ -768,9 +773,13 @@ function runInDocker(command, options = {}) {
           } else if (cleanupPolicy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP) {
             message += `\n${getDockerContainerCleanupInstructions(containerName)}`;
           } else if (
-            cleanupPolicy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL
+            cleanupPolicy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL ||
+            cleanupPolicy === DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT
           ) {
-            message += `\nContainer kept because the command failed.`;
+            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}`;
           }
 

package/src/lib/status-formatter.js

@@ -14,6 +14,7 @@ const {
   formatAsNestedLinksNotation,
 } = require('./output-blocks');
 const { collectProcessIds } = require('./execution-control');
+const { getDockerCommand, getDockerSpawnOptions } = require('./docker-cleanup');
 
 /**
  * Inspect the live state of a detached docker container by name.
@@ -30,26 +31,54 @@ const { collectProcessIds } = require('./execution-control');
  * instead of fabricating a terminal `-1` result.
  *
  * @param {string} sessionName - Container name
- * @returns {{running: boolean, exitCode: number|null}|null} State, or null when
- *   the container cannot be inspected (not found yet, removed, or docker error)
+ * @returns {{running: boolean, exitCode: number|null, oomKilled: boolean|null}|null} State,
+ *   or null when the container cannot be inspected (not found yet, removed, or docker error)
  */
 function inspectDockerState(sessionName) {
   const result = spawnSync(
-    'docker',
-    ['inspect', '-f', '{{.State.Running}} {{.State.ExitCode}}', sessionName],
-    { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    getDockerCommand(),
+    [
+      'inspect',
+      '-f',
+      '{{.State.Running}} {{.State.ExitCode}} {{.State.OOMKilled}}',
+      sessionName,
+    ],
+    getDockerSpawnOptions({
+      encoding: 'utf8',
+      env: process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
   );
   if (result.error || result.status !== 0 || !result.stdout) {
     return null;
   }
-  const [runningRaw, exitRaw] = result.stdout.trim().split(/\s+/);
+  const [runningRaw, exitRaw, oomKilledRaw] = result.stdout.trim().split(/\s+/);
   const exitCode = Number.parseInt(exitRaw, 10);
   return {
     running: runningRaw === 'true',
     exitCode: Number.isFinite(exitCode) ? exitCode : null,
+    oomKilled:
+      oomKilledRaw === 'true' ? true : oomKilledRaw === 'false' ? false : null,
   };
 }
 
+function isDetachedDockerRecord(record) {
+  const opts = record.options || {};
+  return (
+    opts.isolated === 'docker' &&
+    opts.isolationMode === 'detached' &&
+    Boolean(opts.sessionName)
+  );
+}
+
+function readDockerState(record) {
+  const opts = record.options || {};
+  if (opts.isolated !== 'docker' || !opts.sessionName) {
+    return null;
+  }
+  return inspectDockerState(opts.sessionName);
+}
+
 /**
  * Best-effort terminal exit code reported by the isolation backend itself
  * (currently docker via `docker inspect .State.ExitCode`). Returns null when
@@ -59,14 +88,25 @@ function inspectDockerState(sessionName) {
  * @returns {number|null}
  */
 function readBackendExitCode(record) {
-  const opts = record.options || {};
-  if (opts.isolated !== 'docker' || !opts.sessionName) {
-    return null;
-  }
-  const state = inspectDockerState(opts.sessionName);
+  const state = readDockerState(record);
   return state && !state.running ? state.exitCode : null;
 }
 
+function resolveOomExitCode(footerExit, dockerState) {
+  if (footerExit !== null && footerExit !== undefined) {
+    return footerExit;
+  }
+  if (
+    dockerState &&
+    dockerState.exitCode !== null &&
+    dockerState.exitCode !== undefined &&
+    (!dockerState.running || dockerState.exitCode !== 0)
+  ) {
+    return dockerState.exitCode;
+  }
+  return 137;
+}
+
 /**
  * Check if a detached isolation session is still running
  * @param {Object} record - Execution record
@@ -151,8 +191,15 @@ function readExitCodeFromLog(logPath) {
  * @returns {Object} Possibly updated execution record
  */
 function enrichDetachedStatus(record) {
-  const alive = isDetachedSessionAlive(record);
   const footerExit = readExitCodeFromLog(record.logPath);
+  const dockerState = isDetachedDockerRecord(record)
+    ? readDockerState(record)
+    : null;
+  const alive = isDetachedDockerRecord(record)
+    ? dockerState === null
+      ? null
+      : dockerState.running
+    : isDetachedSessionAlive(record);
 
   // Create a shallow copy to avoid mutating the original
   const cloneRecord = () => {
@@ -161,6 +208,19 @@ function enrichDetachedStatus(record) {
     return enriched;
   };
 
+  if (record.oomKilled === true || dockerState?.oomKilled === true) {
+    const enriched = cloneRecord();
+    enriched.oomKilled = true;
+    enriched.status = 'executed';
+    if (enriched.exitCode === null || enriched.exitCode === undefined) {
+      enriched.exitCode = resolveOomExitCode(footerExit, dockerState);
+    }
+    if (!enriched.endTime) {
+      enriched.endTime = new Date().toISOString();
+    }
+    return enriched;
+  }
+
   if (alive === null) {
     // Liveness is unknown: the backend could not be probed (e.g. a detached
     // docker container that is not visible yet on a slow Docker-in-Docker host,
@@ -183,6 +243,9 @@ function enrichDetachedStatus(record) {
   }
 
   const enriched = cloneRecord();
+  if (dockerState?.oomKilled !== null && dockerState?.oomKilled !== undefined) {
+    enriched.oomKilled = dockerState.oomKilled;
+  }
 
   if (alive && enriched.status === 'executed') {
     // A live `screen -ls` (or `tmux`/`docker`) session does NOT mean the command
@@ -358,6 +421,9 @@ function formatRecordAsText(record) {
     `Status:            ${obj.status}`,
     `Command:           ${obj.command}`,
     `Exit Code:         ${obj.exitCode !== null ? obj.exitCode : 'N/A'}`,
+    ...(obj.oomKilled !== undefined
+      ? [`OOM Killed:        ${obj.oomKilled}`]
+      : []),
     `PID:               ${obj.pid !== null ? obj.pid : 'N/A'}`,
     `Working Directory: ${obj.workingDirectory}`,
     `Shell:             ${obj.shell}`,

package/src/lib/usage.js

@@ -19,9 +19,9 @@ Options:
   --keep-user           Keep isolated user after command completes
   --keep-alive, -k      Keep isolation environment alive after command exits
   --auto-remove-docker-container  Always remove docker container after exit (compatibility alias)
-  --always-cleanup-container  Always remove docker container after exit (default)
+  --always-cleanup-container  Always remove docker container after exit
   --keep-container     Keep docker container filesystem after exit
-  --keep-container-on-fail  Remove successful docker containers, keep failed ones
+  --keep-container-on-fail  Remove successful docker containers, keep failed or OOM-killed ones
   --shell <shell>       Shell to use in isolation environments: auto, bash, zsh, sh (default: auto)
   --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)

package/test/docker-autoremove.js

@@ -11,6 +11,12 @@ const path = require('path');
 const { isCommandAvailable } = require('../src/lib/isolation');
 const { runInDocker } = require('../src/lib/isolation');
 const { execSync } = require('child_process');
+const {
+  DOCKER_CONTAINER_CLEANUP_POLICY,
+  buildDetachedDockerCompletionScript,
+  getDockerContainerCleanupPolicy,
+  shouldCleanupDockerContainer,
+} = require('../src/lib/docker-cleanup');
 
 // Helper to wait for a condition with timeout
 async function waitFor(conditionFn, timeout = 5000, interval = 100) {
@@ -33,6 +39,47 @@ describe('Docker Container Cleanup Policy', () => {
   // These tests verify that docker isolation removes finished containers by
   // default while still providing explicit flags to keep them for investigation.
 
+  describe('cleanup decisions', () => {
+    it('should keep abnormal containers under the default policy', () => {
+      const policy = getDockerContainerCleanupPolicy({});
+      assert.strictEqual(policy, DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT);
+      assert.strictEqual(shouldCleanupDockerContainer(policy, 0, false), true);
+      assert.strictEqual(shouldCleanupDockerContainer(policy, 7, false), false);
+      assert.strictEqual(shouldCleanupDockerContainer(policy, 0, true), false);
+    });
+
+    it('should keep OOM-killed containers with keepContainerOnFail', () => {
+      const policy = getDockerContainerCleanupPolicy({
+        keepContainerOnFail: true,
+      });
+      assert.strictEqual(policy, DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL);
+      assert.strictEqual(shouldCleanupDockerContainer(policy, 0, false), true);
+      assert.strictEqual(shouldCleanupDockerContainer(policy, 0, true), false);
+    });
+
+    it('should honor explicit always-cleanup policy', () => {
+      const policy = getDockerContainerCleanupPolicy({
+        alwaysCleanupContainer: true,
+      });
+      assert.strictEqual(policy, DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS);
+      assert.strictEqual(shouldCleanupDockerContainer(policy, 7, false), true);
+      assert.strictEqual(shouldCleanupDockerContainer(policy, 0, true), true);
+    });
+
+    it('should make the detached watcher inspect OOMKilled before default cleanup', () => {
+      const script = buildDetachedDockerCompletionScript(
+        'issue144-container',
+        DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT,
+        '/tmp/issue144.log'
+      );
+      assert.match(script, /\.State\.ExitCode.*\.State\.OOMKilled/);
+      assert.match(script, /__start_command_oom/);
+      assert.match(script, /Container kept for investigation/);
+      assert.match(script, /docker rm -f/);
+      assert.match(script, /issue144-container/);
+    });
+  });
+
   describe('auto-remove enabled', () => {
     it(
       'should automatically remove container when autoRemoveDockerContainer is true',

package/test/run-js-tests.mjs

@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  applyDefaultTimeout,
+  hasExplicitTimeout,
+} from '../../scripts/run-js-tests.mjs';
+
+describe('run-js-tests timeout defaults', () => {
+  test('adds a 30 second timeout when no timeout is supplied', () => {
+    expect(applyDefaultTimeout(['--coverage'])).toEqual([
+      '--timeout',
+      '30000',
+      '--coverage',
+    ]);
+  });
+
+  test('preserves an explicit long timeout flag', () => {
+    expect(hasExplicitTimeout(['--timeout', '45000'])).toBe(true);
+    expect(applyDefaultTimeout(['--timeout', '45000'])).toEqual([
+      '--timeout',
+      '45000',
+    ]);
+  });
+
+  test('preserves an explicit inline timeout flag', () => {
+    expect(hasExplicitTimeout(['--timeout=45000'])).toBe(true);
+    expect(applyDefaultTimeout(['--timeout=45000'])).toEqual([
+      '--timeout=45000',
+    ]);
+  });
+
+  test('preserves Bun short timeout flag', () => {
+    expect(hasExplicitTimeout(['-t', '45000'])).toBe(true);
+    expect(applyDefaultTimeout(['-t', '45000'])).toEqual(['-t', '45000']);
+  });
+});

package/test/session-name-status.js

@@ -16,6 +16,7 @@ const {
 } = require('../src/lib/execution-store');
 const {
   queryStatus,
+  listExecutions,
   isDetachedSessionAlive,
   enrichDetachedStatus,
   attachCurrentTime,
@@ -55,6 +56,65 @@ function runCli(args, env = {}) {
   };
 }
 
+function createExecutable(filePath, content) {
+  fs.writeFileSync(filePath, content, 'utf8');
+  fs.chmodSync(filePath, 0o755);
+}
+
+function withFakeDockerInspect(stateLine, fn) {
+  const fakeBin = fs.mkdtempSync(path.join(os.tmpdir(), 'fake-docker-'));
+  const dockerPath = path.join(
+    fakeBin,
+    process.platform === 'win32' ? 'docker.cmd' : 'docker'
+  );
+  if (process.platform === 'win32') {
+    createExecutable(
+      dockerPath,
+      [
+        '@echo off',
+        'if not "%1"=="inspect" exit /b 1',
+        'echo %3 | findstr /C:"State.Pid" >nul',
+        'if %errorlevel%==0 (',
+        '  echo fake-container-id 4321',
+        '  exit /b 0',
+        ')',
+        `echo ${stateLine}`,
+        'exit /b 0',
+        '',
+      ].join('\r\n')
+    );
+  } else {
+    createExecutable(
+      dockerPath,
+      [
+        '#!/bin/sh',
+        '[ "$1" = "inspect" ] || exit 1',
+        'case "$3" in',
+        '  *State.Pid*) echo "fake-container-id 4321" ;;',
+        `  *) echo "${stateLine}" ;;`,
+        'esac',
+        '',
+      ].join('\n')
+    );
+  }
+
+  const originalPath = process.env.PATH;
+  const originalDockerBin = process.env.START_DOCKER_BIN;
+  process.env.PATH = `${fakeBin}${path.delimiter}${originalPath || ''}`;
+  process.env.START_DOCKER_BIN = dockerPath;
+  try {
+    return fn();
+  } finally {
+    process.env.PATH = originalPath;
+    if (originalDockerBin === undefined) {
+      delete process.env.START_DOCKER_BIN;
+    } else {
+      process.env.START_DOCKER_BIN = originalDockerBin;
+    }
+    fs.rmSync(fakeBin, { recursive: true, force: true });
+  }
+}
+
 describe('Issue #101: --status with session name lookup', () => {
   let store;
 
@@ -552,6 +612,130 @@ describe('Issue #136: detached docker session liveness', () => {
   });
 });
 
+describe('Issue #144: detached docker OOMKilled status signal', () => {
+  let store;
+
+  beforeEach(() => {
+    cleanupTestDir();
+    store = new ExecutionStore({
+      appFolder: TEST_APP_FOLDER,
+      useLinks: false,
+    });
+  });
+
+  afterEach(() => {
+    cleanupTestDir();
+  });
+
+  function saveDockerRecord() {
+    const record = new ExecutionRecord({
+      command: 'sh -c "exit 0"',
+      logPath: '/tmp/issue-144.log',
+      options: {
+        sessionName: 'issue144-oom',
+        isolated: 'docker',
+        isolationMode: 'detached',
+      },
+    });
+    store.save(record);
+    return record;
+  }
+
+  it('surfaces oomKilled in status output even when Docker exit code is 0', () => {
+    const record = saveDockerRecord();
+
+    withFakeDockerInspect('false 0 true', () => {
+      const jsonResult = queryStatus(store, record.uuid, 'json');
+      expect(jsonResult.success).toBe(true);
+      const parsed = JSON.parse(jsonResult.output);
+      expect(parsed.status).toBe('executed');
+      expect(parsed.exitCode).toBe(0);
+      expect(parsed.oomKilled).toBe(true);
+
+      const linksResult = queryStatus(store, record.uuid, 'links-notation');
+      expect(linksResult.success).toBe(true);
+      expect(linksResult.output).toContain('  oomKilled true');
+
+      const textResult = queryStatus(store, record.uuid, 'text');
+      expect(textResult.success).toBe(true);
+      expect(textResult.output).toContain('OOM Killed:        true');
+    });
+  });
+
+  it('surfaces oomKilled in list output', () => {
+    saveDockerRecord();
+
+    withFakeDockerInspect('false 0 true', () => {
+      const result = listExecutions(store, 'json');
+      expect(result.success).toBe(true);
+      const parsed = JSON.parse(result.output);
+      expect(parsed.count).toBe(1);
+      expect(parsed.executions[0].status).toBe('executed');
+      expect(parsed.executions[0].exitCode).toBe(0);
+      expect(parsed.executions[0].oomKilled).toBe(true);
+    });
+  });
+});
+
+describe('Issue #148: detached docker OOMKilled terminal status', () => {
+  let store;
+
+  beforeEach(() => {
+    cleanupTestDir();
+    store = new ExecutionStore({
+      appFolder: TEST_APP_FOLDER,
+      useLinks: false,
+    });
+  });
+
+  afterEach(() => {
+    cleanupTestDir();
+  });
+
+  function saveDockerRecord() {
+    const record = new ExecutionRecord({
+      command: 'sh -c "allocate memory"',
+      logPath: '/tmp/issue-148.log',
+      options: {
+        sessionName: 'issue148-oom',
+        isolated: 'docker',
+        isolationMode: 'detached',
+      },
+    });
+    store.save(record);
+    return record;
+  }
+
+  it('treats oomKilled as terminal even while Docker still reports running', () => {
+    const record = saveDockerRecord();
+
+    withFakeDockerInspect('true 137 true', () => {
+      const result = queryStatus(store, record.uuid, 'json');
+      expect(result.success).toBe(true);
+      const parsed = JSON.parse(result.output);
+      expect(parsed.status).toBe('executed');
+      expect(parsed.exitCode).toBe(137);
+      expect(parsed.oomKilled).toBe(true);
+      expect(parsed.endTime).toBeTruthy();
+      expect(parsed.currentTime).toBeUndefined();
+    });
+  });
+
+  it('uses 137 when oomKilled is terminal but Docker has no terminal exit code yet', () => {
+    const record = saveDockerRecord();
+
+    withFakeDockerInspect('true 0 true', () => {
+      const result = queryStatus(store, record.uuid, 'json');
+      expect(result.success).toBe(true);
+      const parsed = JSON.parse(result.output);
+      expect(parsed.status).toBe('executed');
+      expect(parsed.exitCode).toBe(137);
+      expect(parsed.oomKilled).toBe(true);
+      expect(parsed.endTime).toBeTruthy();
+    });
+  });
+});
+
 describe('Issue #105: attachCurrentTime for executing status', () => {
   it('should add currentTime to serialization when status is executing', () => {
     const record = new ExecutionRecord({