start-command 0.32.1 → 0.34.0

package/src/lib/status-formatter.js

@@ -8,13 +8,23 @@
  */
 
 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 {
+  describeExitCode,
+  resolveExitReason,
+  resolveMemoryExhaustion,
+} = require('./exit-reason');
+const {
+  FATAL_MARKER_TAIL_BYTES,
+  readLogTail,
+} = require('./isolation-log-utils');
+const { normalizeDockerTimestamp } = require('./docker-post-mortem');
+const { END_TIME_SOURCE } = require('./detached-finalize');
 
 /**
  * Inspect the live state of a detached docker container by name.
@@ -40,7 +50,8 @@ function inspectDockerState(sessionName) {
     [
       'inspect',
       '-f',
-      '{{.State.Running}} {{.State.ExitCode}} {{.State.OOMKilled}}',
+      '{{.State.Running}} {{.State.ExitCode}} {{.State.OOMKilled}} ' +
+        '{{.State.StartedAt}} {{.State.FinishedAt}}',
       sessionName,
     ],
     getDockerSpawnOptions({
@@ -52,13 +63,18 @@ function inspectDockerState(sessionName) {
   if (result.error || result.status !== 0 || !result.stdout) {
     return null;
   }
-  const [runningRaw, exitRaw, oomKilledRaw] = result.stdout.trim().split(/\s+/);
+  // Parsed positionally and defensively: an older docker (or a stubbed one)
+  // may answer with fewer fields than the template asks for.
+  const [runningRaw, exitRaw, oomKilledRaw, startedRaw, finishedRaw] =
+    result.stdout.trim().split(/\s+/);
   const exitCode = Number.parseInt(exitRaw, 10);
   return {
     running: runningRaw === 'true',
     exitCode: Number.isFinite(exitCode) ? exitCode : null,
     oomKilled:
       oomKilledRaw === 'true' ? true : oomKilledRaw === 'false' ? false : null,
+    startedAt: normalizeDockerTimestamp(startedRaw),
+    finishedAt: normalizeDockerTimestamp(finishedRaw),
   };
 }
 
@@ -175,13 +191,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()`):
@@ -196,44 +205,49 @@ const LOG_TAIL_BYTES = 16 * 1024;
  * `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;
+  /^={10,}[ \t]*\r?\n^Finished:[ \t]*([^\r\n]*)\r?\n^Exit Code:[ \t]*(-?\d+)[ \t]*(?![^\r\n])/gm;
 
 /**
- * Read the last `bytes` bytes of a file as UTF-8 text.
+ * Parse the `Finished:` line of the footer into an ISO timestamp.
  *
- * 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.
+ * `start` writes it as `YYYY-MM-DD HH:MM:SS[.mmm]` in UTC (both from JS and
+ * from the shell snippet). Anything else — a truncated log, a test fixture, a
+ * future format — yields null so the caller falls back instead of inventing a
+ * timestamp out of an unparseable string.
  *
- * @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
+ * @param {string|null|undefined} value - Raw text after `Finished:`
+ * @returns {string|null} ISO timestamp, or null
  */
-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 {
+function parseFooterTimestamp(value) {
+  if (typeof value !== 'string') {
     return null;
-  } finally {
-    if (fd !== undefined) {
-      try {
-        fs.closeSync(fd);
-      } catch {
-        // ignore
-      }
-    }
   }
+  const trimmed = value.trim();
+  if (!/^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(\.\d+)?Z?$/.test(trimmed)) {
+    return null;
+  }
+  const parsed = Date.parse(`${trimmed.replace(' ', 'T').replace(/Z$/, '')}Z`);
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+
+/**
+ * Read the terminal footer written at the very end of a log.
+ * @param {string|null} tail - Tail of the execution log
+ * @returns {{exitCode: number|null, finishedAt: string|null}} Footer facts
+ */
+function parseFooterFromTail(tail) {
+  if (tail === null || tail === undefined) {
+    return { exitCode: null, finishedAt: null };
+  }
+  const matches = [...tail.matchAll(LOG_FOOTER_PATTERN)];
+  if (matches.length === 0) {
+    return { exitCode: null, finishedAt: null };
+  }
+  const last = matches[matches.length - 1];
+  return {
+    exitCode: parseInt(last[2], 10),
+    finishedAt: parseFooterTimestamp(last[1]),
+  };
 }
 
 /**
@@ -244,31 +258,66 @@ 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)];
-  if (matches.length === 0) {
+  return parseFooterFromTail(tail).exitCode;
+}
+
+function readExitCodeFromLog(logPath) {
+  if (!logPath) {
     return null;
   }
-  return parseInt(matches[matches.length - 1][1], 10);
+  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);
+/**
+ * Decide the moment a finished execution ended, and say where that moment came
+ * from (issue #170.2).
+ *
+ * Precedence: the container's own `State.FinishedAt`, then the `Finished:` line
+ * of the footer `start` wrote itself, and only then the time the end was
+ * observed — which is explicitly marked as such, so a consumer can tell a real
+ * finish time from a query-time observation.
+ *
+ * @param {Object} enriched - Record copy being enriched (mutated)
+ * @param {Object|null} dockerState - Inspected docker state, when available
+ * @param {string|null} footerFinishedAt - Footer timestamp, when parseable
+ * @returns {void}
+ */
+function applyEndTime(enriched, dockerState, footerFinishedAt) {
+  if (enriched.endTime) {
+    return;
+  }
+  const dockerFinishedAt = dockerState ? dockerState.finishedAt : null;
+  if (dockerFinishedAt) {
+    enriched.endTime = new Date(dockerFinishedAt).toISOString();
+    enriched.endTimeSource = END_TIME_SOURCE.DOCKER_FINISHED_AT;
+    return;
+  }
+  if (footerFinishedAt) {
+    enriched.endTime = footerFinishedAt;
+    enriched.endTimeSource = END_TIME_SOURCE.LOG_FOOTER;
+    return;
+  }
+  enriched.endTime = new Date().toISOString();
+  enriched.endTimeSource = END_TIME_SOURCE.OBSERVED_AT;
+  enriched.observedAt = enriched.endTime;
+}
+
+function resolveDetachedStatus(record, logTail) {
+  const footer = parseFooterFromTail(logTail);
+  const footerExit = footer.exitCode;
   const dockerState = isDetachedDockerRecord(record)
     ? readDockerState(record)
     : null;
@@ -305,9 +354,7 @@ function enrichDetachedStatus(record) {
         const enriched = cloneRecord();
         enriched.status = 'executed';
         enriched.exitCode = footerExit;
-        if (!enriched.endTime) {
-          enriched.endTime = new Date().toISOString();
-        }
+        applyEndTime(enriched, dockerState, footer.finishedAt);
         return enriched;
       }
       if (oomKilled === true) {
@@ -319,9 +366,7 @@ function enrichDetachedStatus(record) {
         const enriched = cloneRecord();
         enriched.status = 'executed';
         enriched.exitCode = 137;
-        if (!enriched.endTime) {
-          enriched.endTime = new Date().toISOString();
-        }
+        applyEndTime(enriched, dockerState, footer.finishedAt);
         return enriched;
       }
     }
@@ -361,14 +406,102 @@ function enrichDetachedStatus(record) {
         footerExit ??
         (oomKilled === true ? 137 : -1);
     }
-    if (!enriched.endTime) {
-      enriched.endTime = new Date().toISOString();
-    }
+    applyEndTime(enriched, dockerState, footer.finishedAt);
   }
 
   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,
@@ -509,10 +642,19 @@ function formatRecordAsText(record) {
     `UUID:              ${obj.uuid}`,
     `Status:            ${obj.status}`,
     `Command:           ${obj.command}`,
-    `Exit Code:         ${obj.exitCode !== null ? obj.exitCode : 'N/A'}`,
+    `Exit Code:         ${obj.exitCode !== null ? describeExitCode(obj.exitCode).text : 'N/A'}`,
     ...(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}`,
@@ -522,10 +664,19 @@ function formatRecordAsText(record) {
   if (obj.currentTime) {
     lines.push(`Current Time:      ${obj.currentTime}`);
   }
-  lines.push(
-    `End Time:          ${obj.endTime || 'N/A'}`,
-    `Log Path:          ${obj.logPath}`
-  );
+  lines.push(`End Time:          ${obj.endTime || 'N/A'}`);
+  if (obj.endTimeSource) {
+    // Where `End Time` came from: a real finish time, or merely when `start`
+    // noticed the execution was over (issue #170.2).
+    lines.push(`End Time Source:   ${obj.endTimeSource}`);
+  }
+  if (obj.containerStartedAt) {
+    lines.push(`Container Started: ${obj.containerStartedAt}`);
+  }
+  if (obj.staleDetectedAt) {
+    lines.push(`Stale Detected At: ${obj.staleDetectedAt}`);
+  }
+  lines.push(`Log Path:          ${obj.logPath}`);
 
   // Format options as nested list instead of JSON
   const optionEntries = Object.entries(obj.options || {}).filter(
@@ -677,17 +828,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'),
@@ -708,8 +867,13 @@ module.exports = {
   listExecutions,
   isDetachedSessionAlive,
   enrichDetachedStatus,
+  parseFooterFromTail,
+  parseFooterTimestamp,
   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);
+  });
+});