start-command 0.30.4 → 0.30.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # start-command
 
+## 0.30.5
+
+### Patch Changes
+
+- d0656c2: Stop `--status` from fabricating a detached session exit code out of the command's own output: the terminal exit code is now read from the anchored three-line footer `start` writes (separator / `Finished:` / `Exit Code:`) in the tail of the log only, and Docker's own `.State.ExitCode` takes precedence over the log text.
+
 ## 0.30.4
 
 ### Patch Changes

package/package.json

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

package/src/lib/status-formatter.js

@@ -175,20 +175,88 @@ function isDetachedSessionAlive(record) {
   }
 }
 
+/**
+ * Number of trailing bytes scanned for the terminal log footer. The footer is
+ * always appended at the very end of the log, so there is no reason to read
+ * (potentially megabytes of) command output on every `--status` call.
+ */
+const LOG_TAIL_BYTES = 16 * 1024;
+
+/**
+ * The three-line terminal footer that `start` itself writes (see
+ * `createLogFooter()` and `createShellLogFooterSnippet()`):
+ *
+ *   ==================================================
+ *   Finished: 2026-07-30 23:36:20.295
+ *   Exit Code: 0
+ *
+ * The whole block is anchored at line starts so that a bare `Exit Code: N`
+ * substring emitted by the wrapped command (inside a JSON payload, a quoted
+ * log excerpt, an `rg` dump, ...) can no longer be mistaken for the footer
+ * `start` appends itself (issue #150).
+ */
+const LOG_FOOTER_PATTERN =
+  /^={10,}[ \t]*\r?\n^Finished:[^\r\n]*\r?\n^Exit Code:[ \t]*(-?\d+)[ \t]*(?![^\r\n])/gm;
+
+/**
+ * Read the last `bytes` bytes of a file as UTF-8 text.
+ *
+ * A partial first line is dropped: the slice can start in the middle of a line,
+ * and that fragment must not be treated as the beginning of a line by the
+ * anchored footer pattern.
+ *
+ * @param {string} logPath - Path to the log file
+ * @param {number} [bytes] - Maximum number of trailing bytes to read
+ * @returns {string|null} Tail content, or null when the file cannot be read
+ */
+function readLogTail(logPath, bytes = LOG_TAIL_BYTES) {
+  let fd;
+  try {
+    fd = fs.openSync(logPath, 'r');
+    const size = fs.fstatSync(fd).size;
+    const length = Math.min(size, bytes);
+    const buffer = Buffer.alloc(length);
+    fs.readSync(fd, buffer, 0, length, size - length);
+    const tail = buffer.toString('utf8');
+    if (size <= bytes) {
+      return tail;
+    }
+    const firstNewline = tail.indexOf('\n');
+    return firstNewline === -1 ? '' : tail.slice(firstNewline + 1);
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+/**
+ * Read the terminal exit code from the anchored footer at the end of a log.
+ * Returns null when the log has no footer yet (command still running, or the
+ * host-side watcher has not appended it yet) — never a number parsed out of the
+ * command's own output.
+ * @param {string} logPath - Path to the log file
+ * @returns {number|null}
+ */
 function readExitCodeFromLog(logPath) {
   if (!logPath) {
     return null;
   }
-  try {
-    const content = fs.readFileSync(logPath, 'utf8');
-    const matches = [...content.matchAll(/Exit Code:\s*(-?\d+)/g)];
-    if (matches.length === 0) {
-      return null;
-    }
-    return parseInt(matches[matches.length - 1][1], 10);
-  } catch {
+  const tail = readLogTail(logPath);
+  if (tail === null) {
     return null;
   }
+  const matches = [...tail.matchAll(LOG_FOOTER_PATTERN)];
+  if (matches.length === 0) {
+    return null;
+  }
+  return parseInt(matches[matches.length - 1][1], 10);
 }
 
 /**
@@ -280,15 +348,17 @@ function enrichDetachedStatus(record) {
     // 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. Resolve a real exit
-    // code: prefer the log footer, then the backend's own record (e.g.
-    // `docker inspect .State.ExitCode`), then `137` when the only evidence left
-    // is the OOM observation, and only fall back to the `-1` sentinel as a last
-    // resort when no real code can be obtained (issues #136, #151).
+    // code: prefer the backend's own record (e.g. `docker inspect
+    // .State.ExitCode`, which is authoritative and cannot be spoofed by command
+    // output — issue #150), then the anchored log footer, then `137` when the
+    // only evidence left is the OOM observation, and only fall back to the `-1`
+    // sentinel as a last resort when no real code can be obtained (issues #136,
+    // #151).
     enriched.status = 'executed';
     if (enriched.exitCode === null || enriched.exitCode === undefined) {
       enriched.exitCode =
-        footerExit ??
         backendExitCode(dockerState) ??
+        footerExit ??
         (oomKilled === true ? 137 : -1);
     }
     if (!enriched.endTime) {
@@ -638,6 +708,8 @@ module.exports = {
   listExecutions,
   isDetachedSessionAlive,
   enrichDetachedStatus,
+  readExitCodeFromLog,
+  readLogTail,
   attachCurrentTime,
   attachProcessIds,
 };

package/test/regression-150.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env bun
+/**
+ * Regression tests for issue #150:
+ * "`$ --status` fabricates a detached session exit code from the command's own
+ *  output (unanchored `Exit Code:` scan over the whole log)"
+ *
+ * The exit code of a detached session used to be derived from an *unanchored*
+ * `Exit Code: N` scan over the *whole* session log. Any text the wrapped
+ * command printed that merely contained the substring `Exit Code: N` was
+ * indistinguishable from the terminal footer `start` appends itself, so
+ * `$ --status` could report an exit code the command never produced.
+ *
+ * The fix anchors the scan on the three-line footer block `start` writes
+ * (separator / `Finished:` / `Exit Code:`) and only reads the tail of the log,
+ * where the footer always is.
+ *
+ * Reference: https://github.com/link-foundation/start/issues/150
+ */
+
+const { describe, it, expect, beforeEach, afterEach } = require('bun:test');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { ExecutionRecord } = require('../src/lib/execution-store');
+const {
+  readExitCodeFromLog,
+  readLogTail,
+  enrichDetachedStatus,
+} = require('../src/lib/status-formatter');
+
+const SEPARATOR = '='.repeat(50);
+
+function realFooter(exitCode) {
+  return `\n${SEPARATOR}\nFinished: 2026-07-30 23:36:20.295\nExit Code: ${exitCode}\n`;
+}
+
+describe('anchored log footer parsing (issue #150)', () => {
+  let tempDir;
+  let logPath;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'start-150-'));
+    logPath = path.join(tempDir, 'session.log');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('ignores an `Exit Code:` substring inside the command output', () => {
+    // Exactly the payload from the incident: an older session log dumped by
+    // `rg -n` into the JSON output of the running command.
+    fs.writeFileSync(
+      logPath,
+      '{"type":"item.completed","item":{"aggregated_output":' +
+        '"40-==================================================\\n41-Finished: 2026-07-28 20:04:52.316\\n42-Exit Code: 1\\n",' +
+        '"exit_code":0,"status":"completed"}}\n'
+    );
+    expect(readExitCodeFromLog(logPath)).toBeNull();
+  });
+
+  it('ignores a bare `Exit Code:` line without the footer block around it', () => {
+    fs.writeFileSync(logPath, 'Exit Code: 1\nstill running\n');
+    expect(readExitCodeFromLog(logPath)).toBeNull();
+  });
+
+  it('ignores an `Exit Code:` substring in the middle of a line', () => {
+    fs.writeFileSync(
+      logPath,
+      `${SEPARATOR}\nFinished: now\nlog: Exit Code: 3\n`
+    );
+    expect(readExitCodeFromLog(logPath)).toBeNull();
+  });
+
+  it('reads the real footer that `start` appends', () => {
+    fs.writeFileSync(logPath, `hello\n${realFooter(0)}`);
+    expect(readExitCodeFromLog(logPath)).toBe(0);
+  });
+
+  it('reads the real footer even when the output forged one earlier', () => {
+    fs.writeFileSync(
+      logPath,
+      `${SEPARATOR}\nFinished: fake\nExit Code: 1\n${realFooter(0)}`
+    );
+    // The last anchored footer wins - here the genuine one, appended last.
+    expect(readExitCodeFromLog(logPath)).toBe(0);
+  });
+
+  it('reads negative and multi-digit codes, and tolerates CRLF logs', () => {
+    fs.writeFileSync(
+      logPath,
+      `${SEPARATOR}\r\nFinished: t\r\nExit Code: 137\r\n`
+    );
+    expect(readExitCodeFromLog(logPath)).toBe(137);
+    fs.writeFileSync(logPath, realFooter(-1));
+    expect(readExitCodeFromLog(logPath)).toBe(-1);
+  });
+
+  it('returns null for a log without a footer and for a missing file', () => {
+    fs.writeFileSync(logPath, 'still running, no footer yet\n');
+    expect(readExitCodeFromLog(logPath)).toBeNull();
+    expect(readExitCodeFromLog(path.join(tempDir, 'missing.log'))).toBeNull();
+    expect(readExitCodeFromLog(null)).toBeNull();
+  });
+
+  it('finds the footer at the end of a large log without reading it all', () => {
+    fs.writeFileSync(
+      logPath,
+      `${'x'.repeat(2 * 1024 * 1024)}\n${realFooter(42)}`
+    );
+    expect(readExitCodeFromLog(logPath)).toBe(42);
+    // Only the tail is read, so an `Exit Code:` far from the end is invisible.
+    const tail = readLogTail(logPath);
+    expect(tail.length).toBeLessThan(32 * 1024);
+  });
+
+  it('drops the partial first line of the tail so it cannot be a line start', () => {
+    const filler = 'y'.repeat(32 * 1024);
+    fs.writeFileSync(
+      logPath,
+      `${filler}${SEPARATOR}\nFinished: t\nExit Code: 7\n`
+    );
+    // The separator is a line *continuation* (the line starts with the filler),
+    // so it is not a footer even though the tail slice may begin mid-line.
+    expect(readExitCodeFromLog(logPath)).toBeNull();
+  });
+});
+
+describe('detached status is not derailed by forged output (issue #150)', () => {
+  let tempDir;
+  let logPath;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'start-150-enrich-'));
+    logPath = path.join(tempDir, 'session.log');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function makeRecord() {
+    return new ExecutionRecord({
+      command: 'solve.mjs',
+      logPath,
+      options: {
+        // A container name that cannot be inspected: liveness is unknown, the
+        // exact window in which the incident happened.
+        sessionName: `issue150-absent-${process.pid}-${Date.now()}`,
+        isolated: 'docker',
+        isolationMode: 'detached',
+      },
+    });
+  }
+
+  it('keeps an executing record executing when only the output claims an exit code', () => {
+    fs.writeFileSync(
+      logPath,
+      '{"aggregated_output":"41-Finished: x\\n42-Exit Code: 1\\n","exit_code":0}\n'
+    );
+    const enriched = enrichDetachedStatus(makeRecord());
+    expect(enriched.status).toBe('executing');
+    expect(enriched.exitCode).toBeNull();
+    expect(enriched.endTime).toBeNull();
+  });
+
+  it('marks the record executed once the genuine footer is appended', () => {
+    fs.writeFileSync(
+      logPath,
+      `{"aggregated_output":"42-Exit Code: 1\\n"}\n${realFooter(0)}`
+    );
+    const enriched = enrichDetachedStatus(makeRecord());
+    expect(enriched.status).toBe('executed');
+    expect(enriched.exitCode).toBe(0);
+    expect(enriched.endTime).not.toBeNull();
+  });
+});

package/test/session-name-status.js

@@ -846,7 +846,12 @@ describe('Issue #151: OOMKilled is an observation, not a verdict', () => {
   });
 
   it('prefers the log footer exit code over the OOM fallback when the container is gone', () => {
-    fs.writeFileSync(logPath, 'Finished: now\nExit Code: 0\n', 'utf8');
+    // The anchored footer block `start` itself writes (issue #150).
+    fs.writeFileSync(
+      logPath,
+      `${'='.repeat(50)}\nFinished: now\nExit Code: 0\n`,
+      'utf8'
+    );
     const record = saveDockerRecord({ oomKilled: true });
 
     withFakeDockerMissingContainer(() => {