start-command 0.29.0 → 0.29.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # start-command
 
+## 0.29.2
+
+### Patch Changes
+
+- 8518034: Record the docker image-preparation phase in the session log (issue #138). When a `--isolated docker` run needs to `docker pull` an image, the pull output is now teed into the session-log file (`/tmp/start-command/logs/isolation/docker/<uuid>.log`) in real time and bracketed with `Preparing image <name>…` / `Image ready (<duration>)` markers (or `Image preparation failed` on error). Previously the minutes spent pulling a (potentially multi-GB) image left no trace in the log, so operators tailing `$ --upload-log <uuid>` during startup saw only the header. The single session-log file is now a gap-free record of the run, including the longest, most failure-prone phase.
+
+## 0.29.1
+
+### Patch Changes
+
+- Fix detached docker `--status`/`--list` reporting a terminal status (`executed`) with the `-1` sentinel while the container is still running (or not visible yet on a slow Docker-in-Docker host). `isDetachedSessionAlive()` now treats a failed `docker inspect` as "unknown" (returns `null`) instead of "stopped", so a session whose container has not appeared yet stays `executing` rather than being marked finished. When a container has genuinely stopped, `enrichDetachedStatus()` resolves the real exit code from the `Exit Code:` log footer and then `docker inspect .State.ExitCode`, only falling back to `-1` when no real code can be obtained.
+
+  Fix `--status` for detached executions resurrecting a completed (killed) record. `enrichDetachedStatus()` no longer flips an already-`executed` record back to `executing` (and nulls its exit code) just because `screen -ls`/`tmux`/`docker` still lists a same-named session — a lingering shell can outlive a SIGKILLed command (e.g. OOM, exit 137). The recorded exit code and the `Exit Code:` log footer that `start` itself writes are now treated as authoritative; the record only flips to `executing` when there is no recorded exit code and no terminal footer in the log.
+
 ## 0.29.0
 
 ### Minor Changes

package/package.json

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

package/src/lib/docker-utils.js

@@ -7,6 +7,8 @@
  */
 
 const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const { execSync, spawnSync } = require('child_process');
 
 /**
@@ -102,31 +104,141 @@ function dockerImageExists(image) {
   }
 }
 
+/**
+ * Run `docker pull <image>` while teeing its output to the session log file.
+ *
+ * When a logPath is given (and tee is available, i.e. non-Windows), the pull
+ * output is streamed to BOTH the console and the log file in real time so the
+ * image-preparation phase is captured in the single session log (issue #138).
+ * docker's own exit code is recovered via a sentinel status file because the
+ * exit status of a `cmd | tee` pipeline reflects tee, not docker.
+ *
+ * Without a logPath, it falls back to the previous behavior: inherited stdio
+ * for real-time console output, with no log capture. On Windows (no portable
+ * shell `tee`) but with a logPath, the pull output is captured, echoed to the
+ * console, and appended to the log after the pull so the session log still
+ * records the image-preparation phase (issue #138) — just not streamed live.
+ *
+ * @param {string} image - Docker image to pull
+ * @param {string|null} logPath - Session log file to append pull output to
+ * @returns {{status: number, error?: Error}} Spawn result (status = docker exit code)
+ */
+function runDockerPull(image, logPath) {
+  const { shellQuote } = require('./isolation-log-utils');
+
+  // Without a log target, keep the original inherited-stdio behavior for
+  // fancy real-time console output.
+  if (!logPath) {
+    return spawnSync('docker', ['pull', image], {
+      stdio: ['pipe', 'inherit', 'inherit'],
+    });
+  }
+
+  // Windows has no portable shell `tee`, so capture the pull output, echo it to
+  // the console, and append it to the log so the image-preparation phase is
+  // still recorded in the session log (issue #138), just not streamed live.
+  if (process.platform === 'win32') {
+    const { appendLogFile } = require('./isolation-log-utils');
+    const result = spawnSync('docker', ['pull', image], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    });
+    const combined = `${result.stdout || ''}${result.stderr || ''}`;
+    if (combined) {
+      process.stdout.write(combined);
+      try {
+        appendLogFile(
+          logPath,
+          combined.endsWith('\n') ? combined : `${combined}\n`
+        );
+      } catch {
+        // best-effort: log capture must never break the pull
+      }
+    }
+    return result;
+  }
+
+  // Tee docker pull output to both the console and the log file. docker writes
+  // to a pipe here, so it emits plain progress lines (ideal for a log). The
+  // sentinel file captures docker's real exit code (the pipeline's own exit
+  // status would be tee's).
+  const statusFile = path.join(
+    os.tmpdir(),
+    `start-docker-pull-${process.pid}-${Date.now()}.status`
+  );
+  try {
+    const pipeline =
+      `{ docker pull ${shellQuote(image)} 2>&1; echo $? > ${shellQuote(statusFile)}; } ` +
+      `| tee -a ${shellQuote(logPath)}`;
+    const result = spawnSync('sh', ['-c', pipeline], {
+      stdio: ['pipe', 'inherit', 'inherit'],
+    });
+    if (result.error) {
+      return result;
+    }
+    let status = result.status;
+    try {
+      const recorded = fs.readFileSync(statusFile, 'utf8').trim();
+      if (recorded !== '') {
+        status = parseInt(recorded, 10);
+      }
+    } catch {
+      // Sentinel missing (e.g. sh/tee failed before docker ran); keep pipeline status.
+    }
+    return { ...result, status };
+  } finally {
+    try {
+      fs.unlinkSync(statusFile);
+    } catch {
+      // best-effort cleanup
+    }
+  }
+}
+
 /**
  * Pull a Docker image with output streaming
- * Displays the pull operation as a virtual command in the timeline
+ * Displays the pull operation as a virtual command in the timeline.
+ *
+ * When a logPath is provided, the image-preparation phase (the `docker pull`)
+ * is also recorded in the session log so the single log file is a gap-free
+ * record of everything that ran (issue #138): a `Preparing image …` marker with
+ * a timestamp is written before the pull, the pull output is teed into the log,
+ * and an `Image ready (<duration>)` marker is written afterwards.
+ *
  * @param {string} image - Docker image to pull
+ * @param {string|null} logPath - Optional session log file to append output to
  * @returns {{success: boolean, output: string}} Pull result
  */
-function dockerPullImage(image) {
+function dockerPullImage(image, logPath = null) {
   const {
     createVirtualCommandBlock,
     createVirtualCommandResult,
     createTimelineSeparator,
   } = require('./output-blocks');
+  const { appendLogFile, getTimestamp } = require('./isolation-log-utils');
 
   // Print the virtual command line followed by empty line for visual separation
   console.log(createVirtualCommandBlock(`docker pull ${image}`));
   console.log();
 
+  // Record the start of the image-preparation phase in the session log so
+  // operators tailing the log see progress instead of a header-only file.
+  const prepStartMs = Date.now();
+  if (logPath) {
+    appendLogFile(
+      logPath,
+      `$ docker pull ${image}\nPreparing image ${image}… (${getTimestamp()})\n`
+    );
+  }
+
   let output = '';
   let success;
 
   try {
-    // Run docker pull with inherited stdio for real-time output
-    const result = spawnSync('docker', ['pull', image], {
-      stdio: ['pipe', 'inherit', 'inherit'],
-    });
+    const result = runDockerPull(image, logPath);
+    if (result.error) {
+      throw result.error;
+    }
 
     success = result.status === 0;
 
@@ -140,6 +252,21 @@ function dockerPullImage(image) {
     console.error(`Failed to run docker pull: ${err.message}`);
     output = err.message;
     success = false;
+    if (logPath) {
+      appendLogFile(logPath, `Failed to run docker pull: ${err.message}\n`);
+    }
+  }
+
+  // Record the end of the image-preparation phase with elapsed duration so the
+  // prep time is visible even when full progress is unavailable (issue #138).
+  if (logPath) {
+    const durationSec = ((Date.now() - prepStartMs) / 1000).toFixed(1);
+    appendLogFile(
+      logPath,
+      success
+        ? `Image ready (${durationSec}s)\n`
+        : `Image preparation failed (${durationSec}s)\n`
+    );
   }
 
   // Print empty line before result marker for visual separation (issue #73)

package/src/lib/isolation.js

@@ -588,7 +588,9 @@ function runInDocker(command, options = {}) {
 
   const containerName = options.session || generateSessionName('docker');
   if (!dockerImageExists(options.image)) {
-    const pullResult = dockerPullImage(options.image);
+    // Pass logPath so the image-preparation phase (docker pull) is recorded in
+    // the session log, keeping it a gap-free record of the run (issue #138).
+    const pullResult = dockerPullImage(options.image, options.logPath);
     if (!pullResult.success) {
       return Promise.resolve({
         success: false,

package/src/lib/status-formatter.js

@@ -7,7 +7,7 @@
  * - Text: Human-readable text format
  */
 
-const { execSync } = require('child_process');
+const { execSync, spawnSync } = require('child_process');
 const fs = require('fs');
 const {
   escapeForLinksNotation,
@@ -15,6 +15,58 @@ const {
 } = require('./output-blocks');
 const { collectProcessIds } = require('./execution-control');
 
+/**
+ * Inspect the live state of a detached docker container by name.
+ *
+ * Distinguishes three outcomes that matter for status reporting:
+ * - the container exists and is running,
+ * - the container exists but has stopped (with a real exit code), and
+ * - the container cannot be inspected at all.
+ *
+ * The last case is crucial on slow Docker-in-Docker hosts (issue #136): right
+ * after `docker run -d` returns, `docker inspect <name>` can transiently fail
+ * because the container is not visible yet. A failed inspect must NOT be read
+ * as "stopped"; it means "unknown", so callers can keep the session running
+ * 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)
+ */
+function inspectDockerState(sessionName) {
+  const result = spawnSync(
+    'docker',
+    ['inspect', '-f', '{{.State.Running}} {{.State.ExitCode}}', sessionName],
+    { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+  );
+  if (result.error || result.status !== 0 || !result.stdout) {
+    return null;
+  }
+  const [runningRaw, exitRaw] = result.stdout.trim().split(/\s+/);
+  const exitCode = Number.parseInt(exitRaw, 10);
+  return {
+    running: runningRaw === 'true',
+    exitCode: Number.isFinite(exitCode) ? exitCode : null,
+  };
+}
+
+/**
+ * Best-effort terminal exit code reported by the isolation backend itself
+ * (currently docker via `docker inspect .State.ExitCode`). Returns null when
+ * the backend cannot provide a real code, so callers never surface the `-1`
+ * sentinel for a session whose real exit code is simply not available yet.
+ * @param {Object} record - Execution record
+ * @returns {number|null}
+ */
+function readBackendExitCode(record) {
+  const opts = record.options || {};
+  if (opts.isolated !== 'docker' || !opts.sessionName) {
+    return null;
+  }
+  const state = inspectDockerState(opts.sessionName);
+  return state && !state.running ? state.exitCode : null;
+}
+
 /**
  * Check if a detached isolation session is still running
  * @param {Object} record - Execution record
@@ -46,11 +98,11 @@ function isDetachedSessionAlive(record) {
         return true;
       }
       case 'docker': {
-        const output = execSync(
-          `docker inspect -f "{{.State.Running}}" ${sessionName}`,
-          { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
-        );
-        return output.trim() === 'true';
+        // A failed inspect means the container is not visible yet (still being
+        // created on a slow DinD host) or already removed — not "stopped".
+        // Return null (unknown) so the session is not falsely marked finished.
+        const state = inspectDockerState(sessionName);
+        return state === null ? null : state.running;
       }
       case 'ssh': {
         // For SSH, check if the PID is still running on remote would require
@@ -100,24 +152,62 @@ function readExitCodeFromLog(logPath) {
  */
 function enrichDetachedStatus(record) {
   const alive = isDetachedSessionAlive(record);
+  const footerExit = readExitCodeFromLog(record.logPath);
+
+  // Create a shallow copy to avoid mutating the original
+  const cloneRecord = () => {
+    const enriched = Object.create(Object.getPrototypeOf(record));
+    Object.assign(enriched, record);
+    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,
+    // or one that has already been removed). Honor a terminal `Exit Code:`
+    // footer if the command wrote one; otherwise leave the record untouched
+    // (still executing) rather than fabricating a `-1` terminal result that
+    // orchestrators misread as a finished/failed run (issue #136).
+    const isDetached =
+      record.options && record.options.isolationMode === 'detached';
+    if (isDetached && record.status === 'executing' && footerExit !== null) {
+      const enriched = cloneRecord();
+      enriched.status = 'executed';
+      enriched.exitCode = footerExit;
+      if (!enriched.endTime) {
+        enriched.endTime = new Date().toISOString();
+      }
+      return enriched;
+    }
     return record;
   }
 
-  // Create a shallow copy to avoid mutating the original
-  const enriched = Object.create(Object.getPrototypeOf(record));
-  Object.assign(enriched, record);
+  const enriched = cloneRecord();
 
   if (alive && enriched.status === 'executed') {
-    // Session still running but record says executed - correct it
-    enriched.status = 'executing';
-    enriched.exitCode = null;
-    enriched.endTime = null;
+    // A live `screen -ls` (or `tmux`/`docker`) session does NOT mean the command
+    // is still running: a lingering shell can outlive a killed command (e.g. the
+    // OOM killer sends SIGKILL, exit 137, but the login shell stays up for a
+    // window after `start` already wrote the terminal footer). The footer/recorded
+    // exit code is authoritative. Only flip back to 'executing' when there is NO
+    // recorded terminal exit code AND no `Exit Code:` footer in the log.
+    const hasRecordedExit =
+      enriched.exitCode !== null && enriched.exitCode !== undefined;
+    if (!hasRecordedExit && footerExit === null) {
+      // Session still running and no terminal record - correct it
+      enriched.status = 'executing';
+      enriched.exitCode = null;
+      enriched.endTime = null;
+    }
+    // Otherwise keep the recorded/footer exit code - the command has finished.
   } else if (!alive && enriched.status === 'executing') {
-    // Session ended but record says executing - correct it
+    // Session ended but record says executing - correct it. Resolve a real exit
+    // code: prefer the log footer, then the backend's own record (e.g.
+    // `docker inspect .State.ExitCode`), and only fall back to the `-1` sentinel
+    // as a last resort when no real code can be obtained (issue #136).
     enriched.status = 'executed';
     if (enriched.exitCode === null || enriched.exitCode === undefined) {
-      enriched.exitCode = readExitCodeFromLog(enriched.logPath) ?? -1;
+      enriched.exitCode = footerExit ?? readBackendExitCode(enriched) ?? -1;
     }
     if (!enriched.endTime) {
       enriched.endTime = new Date().toISOString();

package/test/regression-138.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env bun
+/**
+ * Regression tests for issue #138:
+ * "Detached docker session log omits the image-preparation phase
+ *  (docker pull / dind boot) — $ does not preserve the full log in one file"
+ *
+ * When a command is launched with `--isolated docker`, the image-preparation
+ * phase (the `docker pull`) used to be printed to the console only and never
+ * written to the session log file. An operator tailing the session log (e.g.
+ * via `$ --upload-log <uuid>`) during a multi-GB pull would see only the
+ * header — the minutes spent pulling left no trace in the log.
+ *
+ * The fix tees the pull output into the session log and brackets it with
+ * `Preparing image …` / `Image ready (<duration>)` markers so the single
+ * session-log file is a gap-free record of everything that ran.
+ *
+ * Reference: https://github.com/link-foundation/start/issues/138
+ */
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {
+  dockerPullImage,
+  dockerImageExists,
+  isDockerAvailable,
+} = require('../src/lib/docker-utils');
+
+function makeTempLog() {
+  const logPath = path.join(
+    os.tmpdir(),
+    `start-138-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.log`
+  );
+  fs.writeFileSync(logPath, '=== Start Command Log ===\n');
+  return logPath;
+}
+
+describe('docker pull is recorded in the session log (issue #138)', () => {
+  // Silence the virtual-command console output during these tests.
+  let originalLog;
+  let originalError;
+  beforeEach(() => {
+    originalLog = console.log;
+    originalError = console.error;
+    console.log = () => {};
+    console.error = () => {};
+  });
+  afterEach(() => {
+    console.log = originalLog;
+    console.error = originalError;
+  });
+
+  it('writes prep markers and the docker error into the log on a failed pull', () => {
+    if (!isDockerAvailable()) {
+      console.log = originalLog;
+      console.log('  Skipping: docker daemon not available');
+      return;
+    }
+
+    const logPath = makeTempLog();
+    try {
+      // An invalid reference format fails fast without any network access.
+      const result = dockerPullImage('invalid..badname', logPath);
+      const contents = fs.readFileSync(logPath, 'utf8');
+
+      assert.strictEqual(
+        result.success,
+        false,
+        'pull of invalid ref must fail'
+      );
+      assert.ok(
+        contents.includes('Preparing image invalid..badname'),
+        'log must contain the "Preparing image …" start marker'
+      );
+      assert.ok(
+        contents.includes('Image preparation failed'),
+        'log must contain the failure marker with elapsed duration'
+      );
+      // The docker error itself (teed pull output) must be in the log, not just
+      // on the console — this is the core of issue #138.
+      assert.ok(
+        contents.includes('invalid reference format'),
+        'log must capture the teed docker pull error output'
+      );
+    } finally {
+      fs.rmSync(logPath, { force: true });
+    }
+  });
+
+  it('tees real pull output and an "Image ready" marker into the log', () => {
+    if (!isDockerAvailable()) {
+      console.log = originalLog;
+      console.log('  Skipping: docker daemon not available');
+      return;
+    }
+    if (process.platform === 'win32') {
+      // Windows Docker runners pull Linux images slowly/unreliably and the
+      // capture path is exercised by the failed-pull test above; skip to avoid
+      // network-dependent timeouts. The real-pull streaming path is Unix-only.
+      console.log = originalLog;
+      console.log('  Skipping: real pull is unreliable on Windows Docker');
+      return;
+    }
+
+    // Use a tiny image and force a real pull by removing it first.
+    const image = 'hello-world:latest';
+    try {
+      require('child_process').execSync(`docker rmi ${image}`, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch {
+      // image not present locally — that's fine, the pull below still runs
+    }
+
+    const logPath = makeTempLog();
+    try {
+      const result = dockerPullImage(image, logPath);
+      if (!result.success) {
+        // No network in this environment — cannot exercise the success path.
+        console.log = originalLog;
+        console.log('  Skipping: docker pull failed (no registry access?)');
+        return;
+      }
+
+      const contents = fs.readFileSync(logPath, 'utf8');
+      assert.ok(
+        contents.includes(`Preparing image ${image}`),
+        'log must contain the "Preparing image …" start marker'
+      );
+      assert.ok(
+        /Image ready \(\d+\.\d+s\)/.test(contents),
+        'log must contain "Image ready (<duration>)" marker'
+      );
+      assert.ok(
+        contents.includes('Pulling from') ||
+          contents.includes('Status:') ||
+          contents.includes('Pull complete'),
+        'log must capture the teed docker pull progress output'
+      );
+      assert.ok(
+        dockerImageExists(image),
+        'image should exist locally after a successful pull'
+      );
+    } finally {
+      fs.rmSync(logPath, { force: true });
+    }
+  });
+
+  it('does not write prep markers when no logPath is given (backward compat)', () => {
+    if (!isDockerAvailable()) {
+      console.log = originalLog;
+      console.log('  Skipping: docker daemon not available');
+      return;
+    }
+
+    // Without a logPath, dockerPullImage must still return the {success, output}
+    // shape and must not throw. We only assert the contract here.
+    const result = dockerPullImage('invalid..badname');
+    assert.strictEqual(result.success, false);
+    assert.strictEqual(typeof result.output, 'string');
+  });
+});
+
+describe('runInDocker threads logPath into dockerPullImage (issue #138)', () => {
+  it('source passes options.logPath to dockerPullImage', () => {
+    const isolationSrc = fs.readFileSync(
+      path.join(__dirname, '../src/lib/isolation.js'),
+      'utf8'
+    );
+    assert.ok(
+      /dockerPullImage\(options\.image,\s*options\.logPath\)/.test(
+        isolationSrc
+      ),
+      'runInDocker must pass options.logPath to dockerPullImage'
+    );
+  });
+
+  it('dockerPullImage tees output and writes prep markers in source', () => {
+    const dockerUtilsSrc = fs.readFileSync(
+      path.join(__dirname, '../src/lib/docker-utils.js'),
+      'utf8'
+    );
+    assert.ok(
+      dockerUtilsSrc.includes('Preparing image'),
+      'docker-utils must write a "Preparing image …" marker'
+    );
+    assert.ok(
+      dockerUtilsSrc.includes('Image ready'),
+      'docker-utils must write an "Image ready (<duration>)" marker'
+    );
+    assert.ok(
+      dockerUtilsSrc.includes('tee -a'),
+      'docker-utils must tee docker pull output into the log file'
+    );
+  });
+});

package/test/session-name-status.js

@@ -306,6 +306,249 @@ describe('Issue #101: Detached status enrichment', () => {
         expect(enriched.endTime).not.toBeNull();
       }
     });
+
+    // Issue #134: a lingering screen session must NOT resurrect a completed
+    // (killed, exit 137) record back to 'executing' / null exit code.
+    describe('Issue #134: completed record with a lingering live session', () => {
+      const screenAvailable = (() => {
+        const probe = spawnSync('screen', ['-v'], { encoding: 'utf8' });
+        return probe.status === 0 || /Screen version/.test(probe.stdout || '');
+      })();
+
+      let sessionName;
+      let logPath;
+
+      beforeEach(() => {
+        if (!screenAvailable) {
+          return;
+        }
+        sessionName = `enrich-134-${process.pid}-${Date.now()}`;
+        logPath = path.join(TEST_APP_FOLDER, `${sessionName}.log`);
+        if (!fs.existsSync(TEST_APP_FOLDER)) {
+          fs.mkdirSync(TEST_APP_FOLDER, { recursive: true });
+        }
+        // Footer exactly as `start` writes it for a SIGKILLed command.
+        fs.writeFileSync(
+          logPath,
+          `Killed\n\n${'='.repeat(50)}\nFinished: 2026-06-14 19:10:49.822\nExit Code: 137\n`
+        );
+        // A shell that outlives the (already-finished) command.
+        spawnSync('screen', ['-dmS', sessionName, 'sh', '-c', 'sleep 30'], {
+          encoding: 'utf8',
+        });
+      });
+
+      afterEach(() => {
+        if (!screenAvailable) {
+          return;
+        }
+        spawnSync('screen', ['-S', sessionName, '-X', 'quit'], {
+          stdio: 'ignore',
+        });
+        if (logPath && fs.existsSync(logPath)) {
+          fs.unlinkSync(logPath);
+        }
+      });
+
+      it('keeps the recorded exit code when the session is still listed', () => {
+        if (!screenAvailable) {
+          return;
+        }
+        const record = new ExecutionRecord({
+          command: 'sleep 60',
+          logPath,
+          options: {
+            sessionName,
+            isolated: 'screen',
+            isolationMode: 'detached',
+          },
+        });
+        record.complete(137);
+
+        // Sanity: the session must actually be alive for this test to be meaningful.
+        expect(isDetachedSessionAlive(record)).toBe(true);
+
+        const enriched = enrichDetachedStatus(record);
+        expect(enriched.status).toBe('executed');
+        expect(enriched.exitCode).toBe(137);
+        expect(enriched.endTime).not.toBeNull();
+      });
+
+      it('honors the log footer exit code even without a recorded exit code', () => {
+        if (!screenAvailable) {
+          return;
+        }
+        const record = new ExecutionRecord({
+          command: 'sleep 60',
+          logPath,
+          options: {
+            sessionName,
+            isolated: 'screen',
+            isolationMode: 'detached',
+          },
+        });
+        // Record was never reconciled: status 'executed' but exitCode still null.
+        record.status = 'executed';
+        record.exitCode = null;
+        record.endTime = null;
+
+        expect(isDetachedSessionAlive(record)).toBe(true);
+
+        const enriched = enrichDetachedStatus(record);
+        // Footer says 137, so it must stay finished, not flip to executing.
+        expect(enriched.status).toBe('executed');
+      });
+
+      it('flips to executing only when there is no terminal record at all', () => {
+        if (!screenAvailable) {
+          return;
+        }
+        // Log with NO Exit Code footer and no recorded exit code.
+        fs.writeFileSync(logPath, 'still running, no footer yet\n');
+        const record = new ExecutionRecord({
+          command: 'sleep 60',
+          logPath,
+          options: {
+            sessionName,
+            isolated: 'screen',
+            isolationMode: 'detached',
+          },
+        });
+        record.status = 'executed';
+        record.exitCode = null;
+        record.endTime = null;
+
+        expect(isDetachedSessionAlive(record)).toBe(true);
+
+        const enriched = enrichDetachedStatus(record);
+        expect(enriched.status).toBe('executing');
+        expect(enriched.exitCode).toBeNull();
+        expect(enriched.endTime).toBeNull();
+      });
+    });
+  });
+});
+
+// Issue #136: a detached docker session must not be reported with a terminal
+// status (`executed`) and the `-1` sentinel while its container is still
+// running (or not visible yet on a slow Docker-in-Docker host).
+describe('Issue #136: detached docker session liveness', () => {
+  // Use the repo's own probe: `docker` may be installed yet unable to run Linux
+  // images (e.g. Windows runners in Windows-containers mode, where `alpine`
+  // never starts). In that case `docker inspect` fails and liveness is `null`
+  // (unknown) rather than `false`, which would break the stopped-container
+  // assertions below.
+  const { canRunLinuxDockerImages } = require('../src/lib/isolation');
+  const dockerAvailable = canRunLinuxDockerImages();
+
+  // Whether the container actually exists (was created) per `docker inspect`.
+  function dockerContainerExists(name) {
+    const probe = spawnSync('docker', ['inspect', name], { stdio: 'ignore' });
+    return probe.status === 0;
+  }
+
+  function makeDockerRecord(sessionName, extra = {}) {
+    return new ExecutionRecord({
+      command: 'sleep 120; echo done',
+      options: {
+        sessionName,
+        isolated: 'docker',
+        isolationMode: 'detached',
+      },
+      ...extra,
+    });
+  }
+
+  function dockerRm(name) {
+    spawnSync('docker', ['rm', '-f', name], { stdio: 'ignore' });
+  }
+
+  it('reports unknown (null) — not false — when the container is not visible yet', () => {
+    if (!dockerAvailable) {
+      return;
+    }
+    const record = makeDockerRecord('issue136-container-does-not-exist-yet');
+    expect(isDetachedSessionAlive(record)).toBeNull();
+  });
+
+  it('keeps the record executing while the container is not visible yet', () => {
+    if (!dockerAvailable) {
+      return;
+    }
+    const record = makeDockerRecord('issue136-container-not-visible');
+    // Defaults to executing with a null exit code.
+    const enriched = enrichDetachedStatus(record);
+    expect(enriched.status).toBe('executing');
+    expect(enriched.exitCode).toBeNull();
+    expect(enriched.endTime).toBeNull();
+  });
+
+  it('keeps a running container executing', () => {
+    if (!dockerAvailable) {
+      return;
+    }
+    const name = `issue136-running-${process.pid}`;
+    dockerRm(name);
+    const started = spawnSync('docker', [
+      'run',
+      '-d',
+      '--name',
+      name,
+      'alpine',
+      'sh',
+      '-c',
+      'sleep 30',
+    ]);
+    if (started.status !== 0) {
+      dockerRm(name);
+      return;
+    }
+    try {
+      const record = makeDockerRecord(name);
+      expect(isDetachedSessionAlive(record)).toBe(true);
+      const enriched = enrichDetachedStatus(record);
+      expect(enriched.status).toBe('executing');
+      expect(enriched.exitCode).toBeNull();
+    } finally {
+      dockerRm(name);
+    }
+  });
+
+  it('resolves a stopped container to its real exit code, never the -1 sentinel', () => {
+    if (!dockerAvailable) {
+      return;
+    }
+    const name = `issue136-stopped-${process.pid}`;
+    dockerRm(name);
+    const ran = spawnSync('docker', [
+      'run',
+      '--name',
+      name,
+      'alpine',
+      'sh',
+      '-c',
+      'exit 1',
+    ]);
+    // `docker run` exits with the container's code (1 here); treat spawn errors
+    // (no daemon) or a container that never materialized (e.g. the Linux image
+    // could not be pulled) as a skip — there is nothing stopped to inspect.
+    if (ran.error || !dockerContainerExists(name)) {
+      dockerRm(name);
+      return;
+    }
+    try {
+      // No log footer: force exit-code resolution through `docker inspect`.
+      const record = makeDockerRecord(name, {
+        logPath: '/nonexistent-issue136.log',
+      });
+      expect(isDetachedSessionAlive(record)).toBe(false);
+      const enriched = enrichDetachedStatus(record);
+      expect(enriched.status).toBe('executed');
+      expect(enriched.exitCode).toBe(1);
+      expect(enriched.endTime).not.toBeNull();
+    } finally {
+      dockerRm(name);
+    }
   });
 });