start-command 0.34.0 → 0.34.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # start-command
 
+## 0.34.1
+
+### Patch Changes
+
+- 2dd9a41: Never finalize a still-running detached Docker container as a success. `docker logs -f` also returns when its own write to the log fails (ENOSPC) or when dockerd restarts, so the completion watcher now asks `docker inspect -f '{{.State.Running}}'` and keeps waiting with `docker wait` until the container really exits. If the watcher still sees a running container, it notes this in the log and leaves the container and the execution record alone: no `docker rm -f`, no `Exit Code: 0` footer, and no `executed` status. A zero `FinishedAt` (`0001-01-01T00:00:00Z`) combined with an exit code of 0 is recorded as `-1` with `exitReason: watcher-lost-container`, not as a success. A child process that is killed by a signal now reports `128+n` (for example `137` for SIGKILL) instead of `0` in `runWithNodeSpawn`, `runAsIsolatedUser` and the command-stream wrapper.
+
 ## 0.34.0
 
 ### Minor Changes

package/package.json

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

package/src/bin/cli.js

@@ -38,6 +38,7 @@ const { dispatchQueryCommand, hasQueryMode } = require('../lib/query-commands');
 const { printVersion } = require('../lib/version');
 const { createStartBlock, createFinishBlock } = require('../lib/output-blocks');
 const { runWithBunSpawn, runWithNodeSpawn } = require('../lib/spawn-helpers');
+const { resolveChildExitCode } = require('../lib/exit-reason');
 const { printUsage } = require('../lib/usage');
 const { buildDisplayCommand, getCommandName } = require('../lib/shell-utils');
 
@@ -820,7 +821,7 @@ async function runDirectWithCommandStream(
     // Use raw() to pass the command without auto-escaping
     // This is important for complex commands with pipes, redirects, etc.
     const result = await $cmd`${raw(cmd)}`;
-    exitCode = result.code || 0;
+    exitCode = resolveChildExitCode(result.code);
 
     // Update PID if available from result
     if (executionRecord && result.pid) {

package/src/lib/command-stream.js

@@ -11,6 +11,8 @@
  * - Real-time output capture
  */
 
+const { resolveChildExitCode } = require('./exit-reason');
+
 // Debug mode from environment
 const DEBUG =
   process.env.START_DEBUG === '1' || process.env.START_DEBUG === 'true';
@@ -54,7 +56,7 @@ async function execCommand(command, options = {}) {
     return {
       stdout: (result.stdout || '').trim(),
       stderr: (result.stderr || '').trim(),
-      code: result.code || 0,
+      code: resolveChildExitCode(result.code),
     };
   } catch (err) {
     if (DEBUG) {
@@ -91,7 +93,7 @@ async function execCommandAsync(command, options = {}) {
     return {
       stdout: (result.stdout || '').trim(),
       stderr: (result.stderr || '').trim(),
-      code: result.code || 0,
+      code: resolveChildExitCode(result.code),
     };
   } catch (err) {
     if (DEBUG) {

package/src/lib/detached-finalize.js

@@ -34,6 +34,13 @@ const END_TIME_SOURCE = {
   OBSERVED_AT: 'observed-at',
 };
 
+/**
+ * `exitReason` of a record whose container exit the watcher never observed:
+ * docker had no `FinishedAt` for it, so neither the exit code nor the end time
+ * is a fact (issue #174).
+ */
+const WATCHER_LOST_CONTAINER = 'watcher-lost-container';
+
 /**
  * Persist the terminal state of a detached execution.
  *
@@ -49,6 +56,7 @@ const END_TIME_SOURCE = {
  * @param {string|null} [options.startedAt] - `.State.StartedAt`
  * @param {string|null} [options.finishedAt] - `.State.FinishedAt`
  * @param {string|null} [options.containerError] - `.State.Error`
+ * @param {boolean|string|null} [options.running] - `.State.Running`
  * @returns {{updated: boolean, reason?: string, record?: Object}} Outcome
  */
 function finalizeDetachedExecution(options = {}) {
@@ -56,6 +64,11 @@ function finalizeDetachedExecution(options = {}) {
   if (!store || !executionId) {
     return { updated: false, reason: 'missing-arguments' };
   }
+  if (normalizeBoolean(options.running) === true) {
+    // A running container has not finished: its record stays `executing`, and
+    // `--status` keeps probing the live container (issue #174).
+    return { updated: false, reason: 'still-running' };
+  }
 
   let record;
   try {
@@ -72,15 +85,22 @@ function finalizeDetachedExecution(options = {}) {
     return { updated: false, reason: 'already-final', record };
   }
 
+  const finishedAt = normalizeDockerTimestamp(options.finishedAt);
   const described = describeExitCode(options.exitCode);
+  // Without a `FinishedAt`, `ExitCode=0` is Docker's zero value for a container
+  // that has not finished — never an observed success (issue #174).
+  const exitCode = described.code === 0 && !finishedAt ? null : described.code;
   record.status = 'executed';
-  if (described.code !== null) {
-    record.exitCode = described.code;
-  } else if (record.exitCode === null || record.exitCode === undefined) {
+  if (exitCode !== null) {
+    record.exitCode = exitCode;
+  } else if (
+    record.exitCode === null ||
+    record.exitCode === undefined ||
+    !finishedAt
+  ) {
     record.exitCode = -1;
   }
 
-  const finishedAt = normalizeDockerTimestamp(options.finishedAt);
   if (finishedAt) {
     record.endTime = new Date(finishedAt).toISOString();
     record.endTimeSource = END_TIME_SOURCE.DOCKER_FINISHED_AT;
@@ -103,7 +123,8 @@ function finalizeDetachedExecution(options = {}) {
     record.oomKilled = oomKilled;
   }
 
-  const exitReason = resolveReason(record);
+  const exitReason =
+    resolveReason(record) || (finishedAt ? null : WATCHER_LOST_CONTAINER);
   if (exitReason) {
     record.exitReason = exitReason;
   }
@@ -222,14 +243,14 @@ function buildDetachedFinalizeSnippet(executionId) {
   return (
     `${shellQuote(process.execPath)} ${shellQuote(__filename)} ` +
     `${shellQuote(executionId)} "$${v.exit}" "$${v.oom}" ` +
-    `"$${v.started}" "$${v.finished}" "$${v.error}" ` +
+    `"$${v.started}" "$${v.finished}" "$${v.error}" "$${v.running}" ` +
     `>/dev/null 2>&1 || true`
   );
 }
 
 /**
  * Entry point used by the detached watcher:
- *   <runtime> detached-finalize.js <uuid> <exit> <oom> <started> <finished> <error>
+ *   <runtime> detached-finalize.js <uuid> <exit> <oom> <started> <finished> <error> <running>
  * Always exits 0 — a bookkeeping failure must never turn into a visible error
  * in a log the user is reading for the command's own output.
  * @param {string[]} argv - Positional arguments
@@ -243,6 +264,7 @@ function main(argv) {
     startedAt,
     finishedAt,
     containerError,
+    running,
   ] = argv;
   if (!executionId || process.env.START_DISABLE_TRACKING === 'true') {
     return;
@@ -262,6 +284,7 @@ function main(argv) {
       startedAt,
       finishedAt,
       containerError,
+      running,
     });
   } catch {
     // Deliberately silent: see the exit-0 contract above.
@@ -274,6 +297,7 @@ if (require.main === module) {
 
 module.exports = {
   END_TIME_SOURCE,
+  WATCHER_LOST_CONTAINER,
   buildDetachedFinalizeSnippet,
   finalizeDetachedExecution,
   main,

package/src/lib/docker-cleanup.js

@@ -11,10 +11,13 @@ const {
   buildDockerPostMortemSnippet,
   buildDockerRemovalNoteSnippet,
   buildDockerStateSnippet,
+  buildDockerStillRunningNoteSnippet,
+  buildDockerWaitForExitSnippet,
   DOCKER_STATE_INSPECT_FORMAT,
   formatContainerPostMortem,
   formatContainerRemovalNote,
   normalizeDockerTimestamp,
+  SHELL_VARS,
 } = require('./docker-post-mortem');
 const { buildDetachedFinalizeSnippet } = require('./detached-finalize');
 
@@ -312,6 +315,11 @@ function buildSuccessfulNonOomCondition() {
  *   3. it hands the same facts to the finalizer so the execution record stops
  *      being `executing` forever (issue #170.1).
  *
+ * It only does any of that once the container has really exited: the return of
+ * `docker logs -f` / `docker wait` is not proof of exit (issue #174). A
+ * container that is somehow still running afterwards is never removed, gets no
+ * `Exit Code:` footer and is never finalized — its record stays `executing`.
+ *
  * @param {string} containerName - Docker container name
  * @param {string} policy - One of DOCKER_CONTAINER_CLEANUP_POLICY
  * @param {string|null} logPath - Log file to append to, or null
@@ -326,6 +334,9 @@ function buildDetachedDockerCompletionScript(
 ) {
   const quotedName = shellQuote(containerName);
   const parts = [];
+  // Everything that assumes the container has exited: cleanup, footer and
+  // finalization. Guarded as a whole by `.State.Running` below.
+  const exited = [];
 
   if (logPath) {
     const quotedLogPath = shellQuote(logPath);
@@ -341,33 +352,35 @@ function buildDetachedDockerCompletionScript(
     const keep = `${postMortem}; ${buildDockerKeptLogSnippet(containerName, quotedLogPath)}`;
 
     parts.push(`docker logs -f ${quotedName} >> ${quotedLogPath} 2>&1`);
+    parts.push(buildDockerWaitForExitSnippet(containerName, quotedLogPath));
     parts.push(buildDockerStateSnippet(containerName));
     if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS) {
-      parts.push(remove);
+      exited.push(remove);
     } else if (
       policy === DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT ||
       policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL
     ) {
-      parts.push(
+      exited.push(
         `if ${buildSuccessfulNonOomCondition()}; then ${remove}; else ${keep}; fi`
       );
     } else {
       // KEEP: the container is never removed, so the log used to end with the
       // raw command output and nothing else. The post-mortem is exactly the
       // information an operator needs before deciding what to do with it.
-      parts.push(keep);
+      exited.push(keep);
     }
-    parts.push(`${createShellLogFooterSnippet()} >> ${quotedLogPath}`);
+    exited.push(`${createShellLogFooterSnippet()} >> ${quotedLogPath}`);
   } else {
     parts.push(`docker wait ${quotedName} >/dev/null 2>&1`);
+    parts.push(buildDockerWaitForExitSnippet(containerName));
     parts.push(buildDockerStateSnippet(containerName));
     if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS) {
-      parts.push(`docker rm -f ${quotedName} >/dev/null 2>&1 || true`);
+      exited.push(`docker rm -f ${quotedName} >/dev/null 2>&1 || true`);
     } else if (
       policy === DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT ||
       policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL
     ) {
-      parts.push(
+      exited.push(
         `if ${buildSuccessfulNonOomCondition()}; then docker rm -f ${quotedName} >/dev/null 2>&1 || true; fi`
       );
     }
@@ -375,9 +388,17 @@ function buildDetachedDockerCompletionScript(
 
   if (executionId) {
     // Last, so the record is only marked terminal once the log is complete.
-    parts.push(buildDetachedFinalizeSnippet(executionId));
+    exited.push(buildDetachedFinalizeSnippet(executionId));
   }
 
+  const stillRunning = logPath
+    ? buildDockerStillRunningNoteSnippet(containerName, shellQuote(logPath))
+    : ':';
+  parts.push(
+    `if [ "$${SHELL_VARS.running}" = true ]; then ${stillRunning}; ` +
+      `else ${exited.length ? exited.join('; ') : ':'}; fi`
+  );
+
   return parts.join('; ');
 }
 

package/src/lib/docker-post-mortem.js

@@ -138,15 +138,83 @@ const SHELL_VARS = {
   signal: '__start_command_signal',
   exitText: '__start_command_exit_text',
   lifetime: '__start_command_lifetime',
+  running: '__start_command_running',
 };
 
 /** `docker inspect -f` template collecting every post-mortem fact at once. */
 const DOCKER_STATE_INSPECT_FORMAT =
   '{{.State.ExitCode}} {{.State.OOMKilled}} {{.State.StartedAt}} {{.State.FinishedAt}}';
 
+/** `docker inspect -f` template answering "is the container still running?". */
+const DOCKER_RUNNING_INSPECT_FORMAT = '{{.State.Running}}';
+
+/**
+ * Written into the log when `docker logs -f` returned while the container was
+ * still running (issue #174).
+ */
+const LOG_CAPTURE_STOPPED_NOTE =
+  'Log capture stopped early: docker logs -f returned while the container ' +
+  'was still running (a failed write to this log such as ENOSPC, or a dockerd ' +
+  'restart). Waiting for the container to exit.';
+
+/**
+ * Written into the log when the watcher gave up while the container was still
+ * running. No footer follows: an `Exit Code:` line would be a fabrication.
+ */
+const STILL_RUNNING_NOTE =
+  'The watcher stopped observing it before it exited, so it was not removed ' +
+  'and the execution record stays executing.';
+
+/**
+ * Shell condition that holds while the container is running.
+ * @param {string} quotedName - Already shell-quoted container name
+ * @returns {string} Shell condition
+ */
+function buildDockerRunningCondition(quotedName) {
+  return `[ "$(docker inspect -f '${DOCKER_RUNNING_INSPECT_FORMAT}' ${quotedName} 2>/dev/null)" = true ]`;
+}
+
+/**
+ * Shell fragment blocking until the container has really exited.
+ *
+ * `docker logs -f` and `docker wait` both return early when the *stream* ends
+ * rather than the container: `docker logs -f C >> LOG` returns as soon as its
+ * own write to LOG fails (ENOSPC, when the container filled the disk the log
+ * lives on), and both return when dockerd restarts under live-restore while the
+ * container keeps running. The watcher used to take that return as the
+ * container's exit, inspect a *running* container — Docker reports its zero
+ * values `ExitCode=0 FinishedAt=0001-01-01T00:00:00Z` — and `docker rm -f` the
+ * live workload as a success (issue #174). So the fragment loops on
+ * `.State.Running`, not on the return of the command it waited on; `sleep 1`
+ * keeps a failing `docker wait` from spinning.
+ *
+ * @param {string} containerName - Container to wait for
+ * @param {string|null} [quotedLogPath] - Already shell-quoted log path, to
+ *   record that log capture stopped early; null when there is no log
+ * @returns {string} Shell command
+ */
+function buildDockerWaitForExitSnippet(containerName, quotedLogPath = null) {
+  const quotedName = shellQuote(containerName);
+  const running = buildDockerRunningCondition(quotedName);
+  const parts = [];
+  if (quotedLogPath) {
+    parts.push(
+      `if ${running}; then printf '\\n%s\\n' ${shellQuote(LOG_CAPTURE_STOPPED_NOTE)} >> ${quotedLogPath} 2>/dev/null; fi`
+    );
+  }
+  parts.push(
+    `while ${running}; do docker wait ${quotedName} >/dev/null 2>&1 || sleep 1; done`
+  );
+  return parts.join('; ');
+}
+
 /**
  * Shell fragment reading the container's terminal state.
  *
+ * Also records `.State.Running` in `$__start_command_running`, so the caller
+ * can refuse to remove or finalize a container that is still alive
+ * (issue #174).
+ *
  * The four whitespace-free fields are split with `set --` rather than the
  * `${var%% *}` / `${var##* }` pair the two-field version used: those only ever
  * reach the first and the last field. `State.Error` is read separately because
@@ -168,6 +236,10 @@ function buildDockerStateSnippet(containerName) {
     `${v.error}=$(docker inspect -f '{{.State.Error}}' ${quotedName} 2>/dev/null)`,
     `case "$${v.started}" in ${DOCKER_ZERO_TIME}|'') ${v.started}=${UNKNOWN};; esac`,
     `case "$${v.finished}" in ${DOCKER_ZERO_TIME}|'') ${v.finished}=${UNKNOWN};; esac`,
+    // `ExitCode=0` next to a zero `FinishedAt` is Docker's zero value for a
+    // container that has not finished, never an observed exit 0 (issue #174).
+    `if [ "$${v.finished}" = ${UNKNOWN} ] && [ "$${v.exit}" = 0 ]; then ${v.exit}=-1; fi`,
+    `${v.running}=$(docker inspect -f '${DOCKER_RUNNING_INSPECT_FORMAT}' ${quotedName} 2>/dev/null)`,
     buildSignalDecodeSnippet(),
     buildLifetimeSnippet(),
   ].join('; ');
@@ -252,6 +324,21 @@ function buildDockerPostMortemSnippet(containerName, quotedLogPath) {
   );
 }
 
+/**
+ * Shell fragment appending the note for a container the watcher lost while it
+ * was still running (issue #174).
+ * @param {string} containerName - Container that is still running
+ * @param {string} quotedLogPath - Already shell-quoted log path
+ * @returns {string} Shell command
+ */
+function buildDockerStillRunningNoteSnippet(containerName, quotedLogPath) {
+  const quotedName = shellQuote(containerName);
+  return (
+    `printf '\\nContainer still running: %s\\n%s\\nCheck it with: docker inspect %s\\n' ` +
+    `${quotedName} ${shellQuote(STILL_RUNNING_NOTE)} ${quotedName} >> ${quotedLogPath}`
+  );
+}
+
 /**
  * Shell fragment appending the one-line note for a removed container.
  * @param {string} containerName - Container that was removed
@@ -270,15 +357,21 @@ function buildDockerRemovalNoteSnippet(containerName, quotedLogPath) {
 }
 
 module.exports = {
+  DOCKER_RUNNING_INSPECT_FORMAT,
   DOCKER_STATE_INSPECT_FORMAT,
   DOCKER_ZERO_TIME,
+  LOG_CAPTURE_STOPPED_NOTE,
+  STILL_RUNNING_NOTE,
   NO_ERROR,
   POST_MORTEM_HEADER,
   SHELL_VARS,
   UNKNOWN,
   buildDockerPostMortemSnippet,
   buildDockerRemovalNoteSnippet,
+  buildDockerRunningCondition,
   buildDockerStateSnippet,
+  buildDockerStillRunningNoteSnippet,
+  buildDockerWaitForExitSnippet,
   buildLifetimeSnippet,
   buildSignalDecodeSnippet,
   describeExitCode,

package/src/lib/exit-reason.js

@@ -17,6 +17,8 @@
  * `exitCode` or `oomKilled`.
  */
 
+const os = require('os');
+
 /**
  * Reasons carrying this prefix report memory exhaustion, whatever the mechanism
  * (runtime self-abort, kernel OOM killer, failed allocation).
@@ -182,6 +184,27 @@ function resolveMemoryExhaustion(input) {
   return null;
 }
 
+/**
+ * Exit code of a child process that has finished.
+ *
+ * Node reports `code === null` for a child killed by a signal, and the
+ * `code || 0` this replaces turned that into a successful exit 0 (issue #174).
+ * A signal death follows the shell's `128 + n` convention, so the result
+ * decodes back to the signal through `describeExitCode()`; a missing code with
+ * no known signal is a failure (1), never a success.
+ *
+ * @param {number|null|undefined} code - `code` from `exit`/`close`
+ * @param {string|null} [signal] - `signal` from `exit`/`close`, e.g. `SIGKILL`
+ * @returns {number} Exit code
+ */
+function resolveChildExitCode(code, signal = null) {
+  if (typeof code === 'number' && Number.isFinite(code)) {
+    return code;
+  }
+  const number = signal ? os.constants.signals[signal] : undefined;
+  return typeof number === 'number' ? 128 + number : 1;
+}
+
 /**
  * Map a shell exit code to the signal name it encodes.
  * @param {number|null|undefined} exitCode - Terminal exit code
@@ -259,6 +282,7 @@ module.exports = {
   findExitReasonMarker,
   resolveMemoryExhaustion,
   describeExitCode,
+  resolveChildExitCode,
   resolveExitReason,
   signalNameForExitCode,
 };

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

@@ -4,7 +4,7 @@ const { spawn } = require('child_process');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { describeExitCode } = require('./exit-reason');
+const { describeExitCode, resolveChildExitCode } = require('./exit-reason');
 
 function getTempRoot() {
   return process.env.START_TEMP_ROOT || path.join(os.tmpdir(), 'start-command');
@@ -190,11 +190,15 @@ function runAsIsolatedUser(cmd, username) {
       stdio: 'inherit',
     });
 
-    child.on('exit', (code) => {
+    child.on('exit', (code, signal) => {
+      const exitCode = resolveChildExitCode(code, signal);
       resolve({
-        success: code === 0,
-        message: `Command completed as user "${username}" with exit code ${code}`,
-        exitCode: code || 0,
+        success: exitCode === 0,
+        message: signal
+          ? `Command as user "${username}" was killed by ${signal} (exit code ${exitCode})`
+          : `Command completed as user "${username}" with exit code ${exitCode}`,
+        exitCode,
+        signal: signal || null,
       });
     });
 

package/src/lib/spawn-helpers.js

@@ -12,6 +12,7 @@
 const { spawn } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const { resolveChildExitCode } = require('./exit-reason');
 
 function ensureParentDirectory(filePath) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -282,8 +283,9 @@ function runWithNodeSpawn(options) {
   // The 'close' event fires after all stdio streams have been closed, ensuring
   // all stdout/stderr data has been received. The 'exit' event can fire before
   // buffered data is received, causing output loss on macOS (Issue #57).
-  child.on('close', (code) => {
-    const exitCode = code || 0;
+  child.on('close', (code, signal) => {
+    // A signal death reports `code === null`: never record it as exit 0.
+    const exitCode = resolveChildExitCode(code, signal);
     const durationMs = Date.now() - startTimeMs;
     const endTime = new Date().toISOString().replace('T', ' ').substring(0, 23);
 

package/test/regression-170.js

@@ -301,7 +301,10 @@ describe('issue #170.1: the detached watcher persists the terminal state', () =>
 
     const stored = store.get(record.uuid);
     expect(stored.status).toBe(ExecutionStatus.EXECUTED);
-    expect(stored.exitCode).toBe(0);
+    // `ExitCode=0` next to a zero `FinishedAt` is Docker's zero value, not an
+    // observed success (issue #174).
+    expect(stored.exitCode).toBe(-1);
+    expect(stored.exitReason).toBe('watcher-lost-container');
     expect(stored.endTimeSource).toBe('observed-at');
     expect(stored.observedAt).toBe(stored.endTime);
     expect(new Date(stored.endTime).getUTCFullYear()).toBeGreaterThan(2000);

package/test/regression-174.js

@@ -0,0 +1,397 @@
+/**
+ * Regression tests for issue #174: the detached docker watcher `docker rm -f`ed
+ * a still-running container when `docker logs -f` failed (ENOSPC) and
+ * finalized it as executed / exit 0.
+ *
+ *   - `docker logs -f C >> LOG` also returns when its own write to LOG fails,
+ *     and on a dockerd restart; the watcher must wait for the real exit;
+ *   - a container that is still running must never be removed, get an
+ *     `Exit Code:` footer, or be finalized;
+ *   - `ExitCode=0` next to a zero `FinishedAt` is Docker's zero value, never an
+ *     observed exit 0;
+ *   - a child killed by a signal (`code === null`) must never become exit 0.
+ */
+
+const { describe, it, expect, afterEach } = require('bun:test');
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const {
+  ExecutionStore,
+  ExecutionRecord,
+  ExecutionStatus,
+} = require('../src/lib/execution-store');
+const {
+  buildDetachedDockerCompletionScript,
+  DOCKER_CONTAINER_CLEANUP_POLICY,
+} = require('../src/lib/docker-cleanup');
+const {
+  LOG_CAPTURE_STOPPED_NOTE,
+  STILL_RUNNING_NOTE,
+} = require('../src/lib/docker-post-mortem');
+const {
+  WATCHER_LOST_CONTAINER,
+  finalizeDetachedExecution,
+} = require('../src/lib/detached-finalize');
+const { resolveChildExitCode } = require('../src/lib/exit-reason');
+const { runWithNodeSpawn } = require('../src/lib/spawn-helpers');
+
+const tempDirs = [];
+
+function makeTempDir(prefix) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function detachedDockerRecord(logPath) {
+  return new ExecutionRecord({
+    status: ExecutionStatus.EXECUTING,
+    command: 'work',
+    logPath,
+    options: {
+      isolated: 'docker',
+      isolationMode: 'detached',
+      sessionName: 'start-command-174',
+    },
+  });
+}
+
+// The watcher body is a POSIX `sh` script; Windows has no `/bin/sh`.
+const needsPosixShell = () => {
+  if (process.platform !== 'win32') {
+    return false;
+  }
+  console.log('  Skipping: the watcher needs a POSIX /bin/sh');
+  return true;
+};
+
+/**
+ * Run the real watcher script against a scripted fake `docker`.
+ *
+ * `running` lists the successive answers to `docker inspect -f
+ * '{{.State.Running}}'` (`true`, `false`, or `fail` for an inspect that
+ * errors, as during a dockerd restart); the last answer sticks. `docker logs`
+ * writes one line and fails, exactly like `docker logs -f C >> LOG` whose write
+ * hit ENOSPC. Every call is recorded, and `rm` records whether the container was
+ * running at that moment.
+ */
+function runWatcher({ policy, running, state, withLog = true }) {
+  const dir = makeTempDir('watcher-174-');
+  const binDir = path.join(dir, 'bin');
+  const appFolder = path.join(dir, 'app');
+  fs.mkdirSync(binDir);
+  const logPath = path.join(dir, 'run.log');
+  fs.writeFileSync(path.join(dir, 'running'), `${running.join('\n')}\n`);
+  fs.writeFileSync(path.join(dir, 'state'), `${state}\n`);
+  const calls = path.join(dir, 'calls');
+  const dockerPath = path.join(binDir, 'docker');
+  fs.writeFileSync(
+    dockerPath,
+    [
+      '#!/bin/sh',
+      `dir='${dir}'`,
+      'case "$1" in',
+      '  inspect)',
+      '    case "$3" in',
+      '      *State.Running*)',
+      '        answer=$(head -n 1 "$dir/running")',
+      '        if [ "$(wc -l < "$dir/running")" -gt 1 ]; then',
+      '          tail -n +2 "$dir/running" > "$dir/running.next" && mv "$dir/running.next" "$dir/running"',
+      '        fi',
+      '        echo "inspect-running $answer" >> "$dir/calls"',
+      '        [ "$answer" = fail ] && exit 1',
+      '        echo "$answer" > "$dir/current"',
+      '        echo "$answer" ;;',
+      '      *State.Error*) echo "" ;;',
+      '      *) echo "inspect-state" >> "$dir/calls"; cat "$dir/state" ;;',
+      '    esac ;;',
+      '  logs) echo logs >> "$dir/calls"; echo work; exit 1 ;;',
+      '  wait) echo wait >> "$dir/calls"; echo 0 ;;',
+      '  rm) echo "rm running=$(cat "$dir/current" 2>/dev/null)" >> "$dir/calls" ;;',
+      'esac',
+      '',
+    ].join('\n'),
+    'utf8'
+  );
+  fs.chmodSync(dockerPath, 0o755);
+
+  const store = new ExecutionStore({ appFolder, useLinks: false });
+  const record = detachedDockerRecord(withLog ? logPath : null);
+  store.save(record);
+
+  const script = buildDetachedDockerCompletionScript(
+    'demo',
+    policy,
+    withLog ? logPath : null,
+    record.uuid
+  );
+  const result = spawnSync('/bin/sh', ['-c', script], {
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      PATH: `${binDir}${path.delimiter}${process.env.PATH}`,
+      START_APP_FOLDER: appFolder,
+      START_DISABLE_TRACKING: '',
+    },
+    timeout: 20000,
+  });
+  return {
+    status: result.status,
+    calls: fs.readFileSync(calls, 'utf8').trim().split('\n'),
+    log: fs.existsSync(logPath) ? fs.readFileSync(logPath, 'utf8') : '',
+    record: new ExecutionStore({ appFolder, useLinks: false }).get(record.uuid),
+  };
+}
+
+const FINISHED_7 =
+  '7 false 2026-09-27T10:00:00.000000000Z 2026-09-27T10:00:05.000000000Z';
+const FINISHED_0 =
+  '0 false 2026-09-27T10:00:00.000000000Z 2026-09-27T10:00:05.000000000Z';
+const NOT_FINISHED = '0 false 2026-09-27T10:00:00Z 0001-01-01T00:00:00Z';
+
+describe('issue #174: docker logs -f returning is not the container exiting', () => {
+  it('waits for the real exit after docker logs -f fails (ENOSPC)', () => {
+    if (needsPosixShell()) {
+      return;
+    }
+    const run = runWatcher({
+      policy: DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT,
+      running: ['true', 'true', 'false'],
+      state: FINISHED_7,
+    });
+
+    expect(run.status).toBe(0);
+    expect(run.calls).toContain('wait');
+    expect(run.calls.indexOf('wait')).toBeGreaterThan(
+      run.calls.indexOf('logs')
+    );
+    expect(run.calls.indexOf('inspect-state')).toBeGreaterThan(
+      run.calls.lastIndexOf('wait')
+    );
+    expect(run.log).toContain(LOG_CAPTURE_STOPPED_NOTE);
+    expect(run.log).toContain('Exit Code: 7');
+    expect(run.log).not.toContain('Exit Code: 0');
+    expect(run.record.status).toBe(ExecutionStatus.EXECUTED);
+    expect(run.record.exitCode).toBe(7);
+    expect(run.record.endTimeSource).toBe('docker-finished-at');
+  });
+
+  it('only removes the container once it has really exited', () => {
+    if (needsPosixShell()) {
+      return;
+    }
+    const run = runWatcher({
+      policy: DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS,
+      running: ['true', 'true', 'false'],
+      state: FINISHED_0,
+    });
+
+    expect(run.calls).toContain('rm running=false');
+    expect(run.calls).not.toContain('rm running=true');
+    expect(run.log).toContain('Exit Code: 0');
+    expect(run.record.exitCode).toBe(0);
+  });
+
+  it('keeps waiting across a failed docker inspect (dockerd restart)', () => {
+    if (needsPosixShell()) {
+      return;
+    }
+    const run = runWatcher({
+      policy: DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT,
+      running: ['true', 'true', 'true', 'false'],
+      state: FINISHED_7,
+    });
+
+    expect(run.calls.filter((call) => call === 'wait').length).toBe(2);
+    expect(run.record.exitCode).toBe(7);
+  });
+
+  it('applies the same wait to the no-log watcher', () => {
+    if (needsPosixShell()) {
+      return;
+    }
+    const run = runWatcher({
+      policy: DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS,
+      running: ['true', 'false'],
+      state: FINISHED_7,
+      withLog: false,
+    });
+
+    expect(run.calls.filter((call) => call === 'wait').length).toBe(2);
+    expect(run.calls).toContain('rm running=false');
+    expect(run.calls).not.toContain('rm running=true');
+    expect(run.record.exitCode).toBe(7);
+  });
+});
+
+describe('issue #174: a container that is still running is left alone', () => {
+  it('never removes, footers or finalizes a running container', () => {
+    if (needsPosixShell()) {
+      return;
+    }
+    // logs -f fails -> running; the wait loop's inspect fails (daemon down) ->
+    // the loop ends; once the daemon is back the container is still running.
+    const run = runWatcher({
+      policy: DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS,
+      running: ['true', 'fail', 'true'],
+      state: NOT_FINISHED,
+    });
+
+    expect(run.calls.some((call) => call.startsWith('rm'))).toBe(false);
+    expect(run.log).toContain('Container still running: demo');
+    expect(run.log).toContain(STILL_RUNNING_NOTE);
+    expect(run.log).not.toContain('Exit Code:');
+    expect(run.record.status).toBe(ExecutionStatus.EXECUTING);
+    expect(run.record.exitCode).toBeNull();
+  });
+
+  it('never removes a running container without a log either', () => {
+    if (needsPosixShell()) {
+      return;
+    }
+    const run = runWatcher({
+      policy: DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS,
+      running: ['fail', 'true'],
+      state: NOT_FINISHED,
+      withLog: false,
+    });
+
+    expect(run.calls.some((call) => call.startsWith('rm'))).toBe(false);
+    expect(run.record.status).toBe(ExecutionStatus.EXECUTING);
+  });
+});
+
+describe('issue #174: a zero FinishedAt is never an exit 0', () => {
+  it('keeps the container and records no success in the watcher', () => {
+    if (needsPosixShell()) {
+      return;
+    }
+    const run = runWatcher({
+      policy: DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT,
+      running: ['false'],
+      state: NOT_FINISHED,
+    });
+
+    expect(run.calls.some((call) => call.startsWith('rm'))).toBe(false);
+    expect(run.log).toContain('Exit Code: -1');
+    expect(run.log).not.toContain('Exit Code: 0');
+    expect(run.record.status).toBe(ExecutionStatus.EXECUTED);
+    expect(run.record.exitCode).toBe(-1);
+    expect(run.record.exitReason).toBe(WATCHER_LOST_CONTAINER);
+    expect(run.record.endTimeSource).toBe('observed-at');
+  });
+
+  it('refuses to finalize a record whose container is still running', () => {
+    const appFolder = makeTempDir('finalize-174-running-');
+    const store = new ExecutionStore({ appFolder, useLinks: false });
+    const record = detachedDockerRecord(null);
+    store.save(record);
+
+    const outcome = finalizeDetachedExecution({
+      store,
+      executionId: record.uuid,
+      exitCode: '0',
+      oomKilled: 'false',
+      startedAt: '2026-09-27T10:00:00Z',
+      finishedAt: '0001-01-01T00:00:00Z',
+      containerError: '',
+      running: 'true',
+    });
+
+    expect(outcome).toEqual({ updated: false, reason: 'still-running' });
+    expect(store.get(record.uuid).status).toBe(ExecutionStatus.EXECUTING);
+  });
+
+  it('does not trust exit 0 without a FinishedAt', () => {
+    const appFolder = makeTempDir('finalize-174-zero-');
+    const store = new ExecutionStore({ appFolder, useLinks: false });
+    const record = detachedDockerRecord(null);
+    store.save(record);
+
+    finalizeDetachedExecution({
+      store,
+      executionId: record.uuid,
+      exitCode: '0',
+      oomKilled: 'false',
+      startedAt: '2026-09-27T10:00:00Z',
+      finishedAt: '0001-01-01T00:00:00Z',
+      running: 'false',
+    });
+
+    const stored = store.get(record.uuid);
+    expect(stored.exitCode).toBe(-1);
+    expect(stored.exitReason).toBe(WATCHER_LOST_CONTAINER);
+  });
+
+  it('still records a real exit 0', () => {
+    const appFolder = makeTempDir('finalize-174-real-zero-');
+    const store = new ExecutionStore({ appFolder, useLinks: false });
+    const record = detachedDockerRecord(null);
+    store.save(record);
+
+    finalizeDetachedExecution({
+      store,
+      executionId: record.uuid,
+      exitCode: '0',
+      oomKilled: 'false',
+      startedAt: '2026-09-27T10:00:00Z',
+      finishedAt: '2026-09-27T10:00:05Z',
+      running: 'false',
+    });
+
+    const stored = store.get(record.uuid);
+    expect(stored.exitCode).toBe(0);
+    expect(stored.exitReason).toBeUndefined();
+    expect(stored.endTimeSource).toBe('docker-finished-at');
+  });
+});
+
+describe('issue #174: a signal death is never exit 0', () => {
+  it('maps a null code with a signal to 128+n', () => {
+    expect(resolveChildExitCode(null, 'SIGKILL')).toBe(137);
+    expect(resolveChildExitCode(null, 'SIGTERM')).toBe(143);
+    expect(resolveChildExitCode(null, 'SIGINT')).toBe(130);
+  });
+
+  it('maps a missing code without a signal to a failure', () => {
+    expect(resolveChildExitCode(null)).toBe(1);
+    expect(resolveChildExitCode(undefined)).toBe(1);
+    expect(resolveChildExitCode(null, 'SIGNOTREAL')).toBe(1);
+  });
+
+  it('keeps real exit codes, including 0', () => {
+    expect(resolveChildExitCode(0)).toBe(0);
+    expect(resolveChildExitCode(3, null)).toBe(3);
+  });
+
+  it('records a self-killed child as 137 in the node spawn path', async () => {
+    if (needsPosixShell()) {
+      return;
+    }
+    const dir = makeTempDir('spawn-174-');
+    const logFilePath = path.join(dir, 'run.log');
+    const exitCode = await new Promise((resolve) => {
+      runWithNodeSpawn({
+        shell: '/bin/sh',
+        shellArgs: ['-c', 'kill -KILL $$'],
+        logFilePath,
+        startTimeMs: Date.now(),
+        onComplete: (code) => resolve(code),
+        onError: () => resolve('error'),
+      });
+    });
+
+    expect(exitCode).toBe(137);
+    expect(fs.readFileSync(logFilePath, 'utf8')).toContain('Exit Code: 137');
+  });
+});