start-command 0.32.1 → 0.33.0

package/src/lib/status-formatter.js

@@ -8,13 +8,17 @@
  */
 
 const { execSync, spawnSync } = require('child_process');
-const fs = require('fs');
 const {
   escapeForLinksNotation,
   formatAsNestedLinksNotation,
 } = require('./output-blocks');
 const { collectProcessIds } = require('./execution-control');
 const { getDockerCommand, getDockerSpawnOptions } = require('./docker-cleanup');
+const { resolveExitReason, resolveMemoryExhaustion } = require('./exit-reason');
+const {
+  FATAL_MARKER_TAIL_BYTES,
+  readLogTail,
+} = require('./isolation-log-utils');
 
 /**
  * Inspect the live state of a detached docker container by name.
@@ -175,13 +179,6 @@ 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()`):
@@ -198,44 +195,6 @@ const LOG_TAIL_BYTES = 16 * 1024;
 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
@@ -244,12 +203,8 @@ function readLogTail(logPath, bytes = LOG_TAIL_BYTES) {
  * @param {string} logPath - Path to the log file
  * @returns {number|null}
  */
-function readExitCodeFromLog(logPath) {
-  if (!logPath) {
-    return null;
-  }
-  const tail = readLogTail(logPath);
-  if (tail === null) {
+function parseExitCodeFromTail(tail) {
+  if (tail === null || tail === undefined) {
     return null;
   }
   const matches = [...tail.matchAll(LOG_FOOTER_PATTERN)];
@@ -259,16 +214,24 @@ function readExitCodeFromLog(logPath) {
   return parseInt(matches[matches.length - 1][1], 10);
 }
 
+function readExitCodeFromLog(logPath) {
+  if (!logPath) {
+    return null;
+  }
+  return parseExitCodeFromTail(readLogTail(logPath));
+}
+
 /**
- * Enrich execution record with live session status for detached executions.
+ * Resolve the live status of a detached execution.
  * If a record shows "executing" but the detached session has actually ended,
  * returns an updated copy with status "executed". If it shows "executed" but
  * the session is still running, returns a copy with status "executing".
  * @param {Object} record - Execution record
+ * @param {string|null} logTail - Tail of the execution log (already read once)
  * @returns {Object} Possibly updated execution record
  */
-function enrichDetachedStatus(record) {
-  const footerExit = readExitCodeFromLog(record.logPath);
+function resolveDetachedStatus(record, logTail) {
+  const footerExit = parseExitCodeFromTail(logTail);
   const dockerState = isDetachedDockerRecord(record)
     ? readDockerState(record)
     : null;
@@ -369,6 +332,96 @@ function enrichDetachedStatus(record) {
   return enriched;
 }
 
+/**
+ * Attach an `exitReason` hint to a finished record.
+ *
+ * The hint explains an otherwise opaque exit code (`139` with `oomKilled
+ * false` is the motivating case from issue #162) and is derived from the same
+ * log tail the footer scan already reads. It is purely additive: `status`,
+ * `exitCode` and `oomKilled` are never changed by it.
+ *
+ * @param {Object} record - Execution record
+ * @param {string|null} logTail - Tail of the execution log
+ * @returns {Object} Record, or a copy carrying `exitReason`
+ */
+function attachExitReason(record, logTail) {
+  if (!record || record.status !== 'executed') {
+    return record;
+  }
+
+  const exitReason = resolveExitReason({
+    exitCode: record.exitCode,
+    logTail,
+    oomKilled: record.oomKilled,
+  });
+
+  if (!exitReason) {
+    return record;
+  }
+
+  const enriched = Object.create(Object.getPrototypeOf(record));
+  Object.assign(enriched, record);
+  enriched.exitReason = exitReason;
+  return enriched;
+}
+
+/**
+ * Attach the memory-exhaustion observation to a finished record (issue #165).
+ *
+ * A runtime that aborts on its own heap limit (`FATAL ERROR: Reached heap limit
+ * ...`) never trips a container signal, so `oomKilled false` next to `exitCode
+ * 139` is a false negative for "out of memory" every single time. The evidence
+ * is in the log tail this scan already holds, so it is surfaced explicitly
+ * instead of leaving every consumer to re-derive it.
+ *
+ * Like `exitReason`, this is purely additive: `status`, `exitCode` and
+ * `oomKilled` are never changed by it.
+ *
+ * @param {Object} record - Execution record
+ * @param {string|null} logTail - Tail of the execution log
+ * @returns {Object} Record, or a copy carrying the memory fields
+ */
+function attachMemoryExhaustion(record, logTail) {
+  if (!record || record.status !== 'executed') {
+    return record;
+  }
+
+  const memory = resolveMemoryExhaustion({
+    exitCode: record.exitCode,
+    logTail,
+    oomKilled: record.oomKilled,
+  });
+
+  if (!memory) {
+    return record;
+  }
+
+  const enriched = Object.create(Object.getPrototypeOf(record));
+  Object.assign(enriched, record);
+  enriched.memoryExhausted = memory.memoryExhausted;
+  enriched.memoryExhaustedReason = memory.memoryExhaustedReason;
+  return enriched;
+}
+
+/**
+ * Enrich execution record with live session status and exit diagnostics.
+ *
+ * The tail is read once, with the wider fatal-marker window: a dying runtime
+ * prints a native stack trace *after* its `FATAL ERROR` line, which can push
+ * the marker out of the narrower footer window (issue #165).
+ *
+ * @param {Object} record - Execution record
+ * @returns {Object} Possibly updated execution record
+ */
+function enrichDetachedStatus(record) {
+  const logTail =
+    record && record.logPath
+      ? readLogTail(record.logPath, FATAL_MARKER_TAIL_BYTES)
+      : null;
+  const resolved = resolveDetachedStatus(record, logTail);
+  return attachMemoryExhaustion(attachExitReason(resolved, logTail), logTail);
+}
+
 /**
  * Wrap a record so its serialized form includes a `currentTime` field when
  * the status is "executing". This reflects the moment `--status` was invoked,
@@ -513,6 +566,15 @@ function formatRecordAsText(record) {
     ...(obj.oomKilled !== undefined
       ? [`OOM Killed:        ${obj.oomKilled}`]
       : []),
+    ...(obj.exitReason !== undefined
+      ? [`Exit Reason:       ${obj.exitReason}`]
+      : []),
+    ...(obj.memoryExhausted !== undefined
+      ? [`Memory Exhausted:  ${obj.memoryExhausted}`]
+      : []),
+    ...(obj.memoryExhaustedReason !== undefined
+      ? [`Memory Evidence:   ${obj.memoryExhaustedReason}`]
+      : []),
     `PID:               ${obj.pid !== null ? obj.pid : 'N/A'}`,
     `Working Directory: ${obj.workingDirectory}`,
     `Shell:             ${obj.shell}`,
@@ -677,17 +739,25 @@ function queryStatus(store, identifier, outputFormat) {
  * Handle execution list query and output the result
  * @param {Object} store - ExecutionStore instance
  * @param {string|null} outputFormat - Output format (links-notation, json, text)
+ * @param {Object} [options] - List options
+ * @param {boolean} [options.running] - Only list executions that are still running
  * @returns {{success: boolean, output?: string, error?: string}}
  */
-function listExecutions(store, outputFormat) {
+function listExecutions(store, outputFormat, options = {}) {
   if (!store) {
     return { success: false, error: 'Execution tracking is disabled.' };
   }
 
   try {
-    const records = sortRecordsByStartTimeDesc(
+    const enriched = sortRecordsByStartTimeDesc(
       store.getAll().map(prepareRecordForList)
     );
+    // --running reports the reconciled status, not the stored one: a record
+    // whose session already died is listed as executed even if the store still
+    // says "executing" (issue #162).
+    const records = options.running
+      ? enriched.filter((record) => record.status === 'executing')
+      : enriched;
     return {
       success: true,
       output: formatRecordList(records, outputFormat || 'links-notation'),
@@ -710,6 +780,9 @@ module.exports = {
   enrichDetachedStatus,
   readExitCodeFromLog,
   readLogTail,
+  attachExitReason,
+  attachMemoryExhaustion,
+  resolveDetachedStatus,
   attachCurrentTime,
   attachProcessIds,
 };

package/src/lib/usage.js

@@ -1,6 +1,6 @@
 /** Print usage information */
 function printUsage() {
-  console.log(`Usage: $ [options] [--] <command> | $ --status <uuid> [--output-format <fmt>] | $ --list [--output-format <fmt>] | $ --upload-log <id> | $ --stop <id> | $ --terminate <id>
+  console.log(`Usage: $ [options] [--] <command> | $ --status <uuid> [--output-format <fmt>] | $ --list [--running] [--output-format <fmt>] | $ --upload-log <id> | $ --stop <id> | $ --terminate <id> | $ --attach <id> [--read-only] | $ --resume <id> [-- <command>] | $ --resume-all
 
 Options:
   --isolated, --isolation, -i <env>  Run in isolated environment (screen, tmux, docker, ssh)
@@ -28,9 +28,15 @@ Options:
   --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)
   --list                List all tracked executions (--output-format: links-notation|json|text)
+  --running             With --list, only report executions that are still running
   --upload-log <id>     Upload the stored log for an execution UUID or session name
   --stop <id>           Ask a detached isolated execution to stop gracefully
   --terminate <id>      Terminate a detached isolated execution immediately
+  --attach <id>         Attach to a running detached isolated execution
+  --read-only           With --attach, follow output without sending input
+  --resume <id>         Restart a stopped detached execution in the same environment
+                        (append -- <command> to run a different command there)
+  --resume-all          Re-attach or reconcile every execution still marked running
   --cleanup             Clean up stale "executing" records (crashed/killed processes)
   --cleanup-dry-run     Show stale records that would be cleaned up (without cleaning)
   --version, -v         Show version information
@@ -54,6 +60,12 @@ Examples:
   $ --upload-log my-screen-session         # Upload stored execution log
   $ --stop my-screen-session               # Ask detached execution to stop gracefully
   $ --terminate my-screen-session          # Terminate detached execution immediately
+  $ --list --running                       # Only executions that are still running
+  $ --attach my-docker-session             # Re-enter a running detached session
+  $ --attach my-docker-session --read-only # Follow its output without stdin
+  $ --resume my-docker-session             # Restart the stored command in the same container
+  $ --resume my-docker-session -- bash     # Run a different command in the same container
+  $ --resume-all                           # Re-attach every still-running execution
   $ --use-command-stream echo "Hello"      # Use command-stream library`);
   console.log('');
   console.log('Piping with $:');

package/src/lib/user-manager.js

@@ -8,6 +8,7 @@
  */
 
 const { execSync, spawnSync } = require('child_process');
+const { randomInt } = require('crypto');
 
 // Debug mode from environment
 const DEBUG =
@@ -73,6 +74,19 @@ function groupExists(groupname) {
   }
 }
 
+/**
+ * Generate `length` cryptographically random base36 characters.
+ * @param {number} length
+ * @returns {string}
+ */
+function randomBase36(length) {
+  let value = '';
+  while (value.length < length) {
+    value += randomInt(36).toString(36);
+  }
+  return value;
+}
+
 /**
  * Generate a unique username for isolation
  * @param {string} [prefix='start'] - Prefix for the username
@@ -80,7 +94,10 @@ function groupExists(groupname) {
  */
 function generateIsolatedUsername(prefix = 'start') {
   const timestamp = Date.now().toString(36);
-  const random = Math.random().toString(36).substring(2, 6);
+  // A CSPRNG, not Math.random: this suffix is the only unguessable part of the
+  // name of a user account that other processes may race to create
+  // (CodeQL js/insecure-randomness).
+  const random = randomBase36(4);
   // Keep username short (max 32 chars on most systems)
   // and valid (only alphanumeric, hyphen, underscore)
   return `${prefix}-${timestamp}${random}`.substring(0, 31);

package/test/args-parser-attach-resume.js

@@ -0,0 +1,159 @@
+/**
+ * Tests for the --attach/--resume/--resume-all/--running options (issue #162)
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert');
+const { parseArgs, validateOptions } = require('../src/lib/args-parser');
+
+function parse(args) {
+  const result = parseArgs(args);
+  validateOptions(result.wrapperOptions);
+  return result;
+}
+
+describe('--attach', () => {
+  test('accepts a session identifier as a separate argument', () => {
+    const { wrapperOptions } = parse(['--attach', 'my-session']);
+    assert.strictEqual(wrapperOptions.attach, 'my-session');
+    assert.strictEqual(wrapperOptions.readOnly, false);
+  });
+
+  test('accepts the --attach=<id> form', () => {
+    const { wrapperOptions } = parse([
+      '--attach=dd1acfbe-3c01-4ffa-8c78-f825457f5813',
+    ]);
+    assert.strictEqual(
+      wrapperOptions.attach,
+      'dd1acfbe-3c01-4ffa-8c78-f825457f5813'
+    );
+  });
+
+  test('supports --read-only', () => {
+    const { wrapperOptions } = parse(['--attach', 'my-session', '--read-only']);
+    assert.strictEqual(wrapperOptions.attach, 'my-session');
+    assert.strictEqual(wrapperOptions.readOnly, true);
+  });
+
+  test('rejects --read-only without --attach', () => {
+    assert.throws(() => {
+      parse(['--read-only', '--status', 'my-session']);
+    }, /--read-only option is only valid with --attach/);
+  });
+
+  test('requires an identifier argument', () => {
+    assert.throws(() => {
+      parseArgs(['--attach']);
+    }, /Option --attach requires a UUID or session name argument/);
+  });
+
+  test('rejects an empty --attach= value', () => {
+    assert.throws(() => {
+      parseArgs(['--attach=']);
+    }, /Option --attach requires a UUID or session name argument/);
+  });
+});
+
+describe('--resume', () => {
+  test('accepts a session identifier', () => {
+    const { wrapperOptions, command } = parse(['--resume', 'my-session']);
+    assert.strictEqual(wrapperOptions.resume, 'my-session');
+    assert.strictEqual(command, '');
+  });
+
+  test('accepts a replacement command after the -- separator', () => {
+    const { wrapperOptions, command, rawCommand } = parse([
+      '--resume',
+      'my-session',
+      '--',
+      'echo',
+      'hello world',
+    ]);
+    assert.strictEqual(wrapperOptions.resume, 'my-session');
+    // Quoted argv elements stay quoted so the inner shell keeps the
+    // boundaries the user typed (issue #164).
+    assert.strictEqual(command, "echo 'hello world'");
+    assert.deepStrictEqual(rawCommand, ['echo', 'hello world']);
+  });
+
+  test('accepts the --resume=<id> form with a replacement command', () => {
+    const { wrapperOptions, rawCommand } = parse([
+      '--resume=my-session',
+      '--',
+      'npm',
+      'test',
+    ]);
+    assert.strictEqual(wrapperOptions.resume, 'my-session');
+    assert.deepStrictEqual(rawCommand, ['npm', 'test']);
+  });
+
+  test('supports --output-format', () => {
+    const { wrapperOptions } = parse([
+      '--resume',
+      'my-session',
+      '--output-format',
+      'json',
+    ]);
+    assert.strictEqual(wrapperOptions.outputFormat, 'json');
+  });
+});
+
+describe('--resume-all', () => {
+  test('is a boolean flag', () => {
+    const { wrapperOptions } = parse(['--resume-all']);
+    assert.strictEqual(wrapperOptions.resumeAll, true);
+  });
+
+  test('supports --output-format', () => {
+    const { wrapperOptions } = parse([
+      '--resume-all',
+      '--output-format',
+      'json',
+    ]);
+    assert.strictEqual(wrapperOptions.resumeAll, true);
+    assert.strictEqual(wrapperOptions.outputFormat, 'json');
+  });
+});
+
+describe('--list --running', () => {
+  test('sets the running filter', () => {
+    const { wrapperOptions } = parse(['--list', '--running']);
+    assert.strictEqual(wrapperOptions.list, true);
+    assert.strictEqual(wrapperOptions.running, true);
+  });
+
+  test('rejects --running without --list', () => {
+    assert.throws(() => {
+      parse(['--running']);
+    }, /--running option is only valid with --list/);
+  });
+});
+
+describe('query mode exclusivity', () => {
+  const combinations = [
+    ['--attach', 'a', '--resume', 'b'],
+    ['--attach', 'a', '--status', 'b'],
+    ['--resume', 'a', '--terminate', 'b'],
+    ['--resume-all', '--list'],
+    ['--resume-all', '--cleanup'],
+  ];
+
+  for (const args of combinations) {
+    test(`rejects ${args.join(' ')}`, () => {
+      assert.throws(() => {
+        parse(args);
+      }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, --attach, --resume, --resume-all, or --cleanup/);
+    });
+  }
+});
+
+describe('defaults', () => {
+  test('are all inactive without query options', () => {
+    const { wrapperOptions } = parse(['echo', 'hi']);
+    assert.strictEqual(wrapperOptions.attach, null);
+    assert.strictEqual(wrapperOptions.readOnly, false);
+    assert.strictEqual(wrapperOptions.resume, null);
+    assert.strictEqual(wrapperOptions.resumeAll, false);
+    assert.strictEqual(wrapperOptions.running, false);
+  });
+});

package/test/args-parser-control.js

@@ -54,19 +54,19 @@ describe('control options', () => {
   it('should reject combining query and control modes', () => {
     assert.throws(() => {
       parseArgs(['--status', 'uuid-here', '--stop', 'my-session']);
-    }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, or --cleanup/);
+    }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, --attach, --resume, --resume-all, or --cleanup/);
   });
 
   it('should reject combining upload-log with control modes', () => {
     assert.throws(() => {
       parseArgs(['--upload-log', 'uuid-here', '--terminate', 'my-session']);
-    }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, or --cleanup/);
+    }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, --attach, --resume, --resume-all, or --cleanup/);
   });
 
   it('should reject output-format with control modes', () => {
     assert.throws(() => {
       parseArgs(['--stop', 'my-session', '--output-format', 'json']);
-    }, /--output-format option is only valid with --status or --list/);
+    }, /--output-format option is only valid with --status, --list, --resume, or --resume-all/);
   });
 
   it('should default control options to null', () => {

package/test/args-parser.js

@@ -859,7 +859,7 @@ describe('output-format option', () => {
   it('should throw error for output-format without status', () => {
     assert.throws(() => {
       parseArgs(['--output-format', 'json', '--', 'npm', 'test']);
-    }, /--output-format option is only valid with --status or --list/);
+    }, /--output-format option is only valid with --status, --list, --resume, or --resume-all/);
   });
 
   it('should accept all valid output formats', () => {

package/test/check-file-size.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env bun
+/**
+ * Behaviour of `scripts/check-file-size.mjs` (issue #168).
+ *
+ * The 1000-line limit is a refactoring rule for this repository's own source.
+ * It fired on `dev/log/issues/168/pulls/169/upstream/use-m-8.15.1-use.js` - a
+ * third-party file archived verbatim as investigation evidence - and failed
+ * both the JavaScript and the Rust pipeline. That is a false positive: the
+ * archive cannot be refactored without destroying the evidence it preserves.
+ *
+ * The paths are compared with forward slashes: the checker normalises them so
+ * the exclusion list matches on Windows too, where `relative()` would otherwise
+ * yield `dev\\log`.
+ *
+ * The Rust suite mirrors these checks in `rust/tests/check_file_size.rs`.
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const { execFileSync } = require('child_process');
+const { mkdtempSync, mkdirSync, writeFileSync, rmSync } = require('fs');
+const { tmpdir } = require('os');
+const { join, resolve } = require('path');
+
+const script = resolve(__dirname, '..', '..', 'scripts', 'check-file-size.mjs');
+
+/**
+ * Run the checker over a throwaway tree.
+ * @param {Record<string, number>} files - relative path -> line count
+ * @returns {{code: number, output: string}}
+ */
+function runChecker(files) {
+  const dir = mkdtempSync(join(tmpdir(), 'check-file-size-'));
+  try {
+    for (const [relativePath, lines] of Object.entries(files)) {
+      const full = join(dir, relativePath);
+      mkdirSync(resolve(full, '..'), { recursive: true });
+      writeFileSync(full, 'const x = 1;\n'.repeat(lines));
+    }
+    try {
+      const output = execFileSync('node', [script], {
+        cwd: dir,
+        encoding: 'utf8',
+      });
+      return { code: 0, output };
+    } catch (error) {
+      return {
+        code: error.status,
+        output: `${error.stdout || ''}${error.stderr || ''}`,
+      };
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe('check-file-size', () => {
+  it('fails on an oversized file in the repository source', () => {
+    const result = runChecker({ 'scripts/huge.mjs': 1500 });
+    assert.strictEqual(result.code, 1);
+    assert.ok(result.output.includes('scripts/huge.mjs'));
+  });
+
+  it('passes when every file is within the limit', () => {
+    const result = runChecker({ 'scripts/small.mjs': 10 });
+    assert.strictEqual(result.code, 0);
+    assert.ok(result.output.includes('within the line limit'));
+  });
+
+  it('ignores archived evidence under dev/log', () => {
+    const result = runChecker({
+      'dev/log/issues/168/pulls/169/upstream/vendored.js': 1500,
+      'scripts/small.mjs': 10,
+    });
+    assert.strictEqual(result.code, 0);
+    assert.ok(!result.output.includes('vendored.js'));
+  });
+
+  it('reports paths with forward slashes on every platform', () => {
+    const result = runChecker({ 'scripts/nested/huge.mjs': 1500 });
+    assert.strictEqual(result.code, 1);
+    assert.ok(result.output.includes('scripts/nested/huge.mjs'));
+    assert.ok(!result.output.includes('scripts\\nested'));
+  });
+
+  it('still checks Rust sources outside the archive', () => {
+    const result = runChecker({ 'rust/src/huge.rs': 1500 });
+    assert.strictEqual(result.code, 1);
+    assert.ok(result.output.includes('rust/src/huge.rs'));
+  });
+});