start-command 0.37.8 → 0.38.0

package/src/lib/snapshot-resume-options.js

@@ -0,0 +1,174 @@
+/**
+ * Options for the guarded Docker snapshot resume (issue #224):
+ *   --snapshot-wait <seconds>          wait for the host snapshot lock
+ *   --snapshot-disk-wait <seconds>     wait for free disk instead of refusing
+ *   --remove-original-after <seconds>  remove the original only if the
+ *                                      replacement still runs after the delay
+ *   --snapshot-size-hint <bytes>       skip the `docker inspect --size` walk
+ *   --snapshot-prepare <command>       `docker exec` a command in the original
+ *                                      before it is committed
+ *
+ * They only apply to `--resume`. The two waits also read
+ * START_SNAPSHOT_LOCK_WAIT and START_SNAPSHOT_DISK_WAIT when the flags are
+ * absent, so a supervisor can set them once for every resume it runs.
+ */
+
+const FIELDS = {
+  '--snapshot-wait': 'snapshotWait',
+  '--snapshot-disk-wait': 'snapshotDiskWait',
+  '--remove-original-after': 'removeOriginalAfter',
+  '--snapshot-size-hint': 'snapshotSizeHint',
+  '--snapshot-prepare': 'snapshotPrepare',
+};
+
+const ENV_DEFAULTS = {
+  snapshotWait: ['START_SNAPSHOT_LOCK_WAIT', '--snapshot-wait'],
+  snapshotDiskWait: ['START_SNAPSHOT_DISK_WAIT', '--snapshot-disk-wait'],
+};
+
+const UNITS = {
+  '': 1,
+  b: 1,
+  k: 1024,
+  m: 1024 ** 2,
+  g: 1024 ** 3,
+  t: 1024 ** 4,
+};
+
+function createSnapshotOptionDefaults() {
+  return {
+    snapshotWait: null,
+    snapshotDiskWait: null,
+    removeOriginalAfter: null,
+    snapshotSizeHint: null,
+    snapshotPrepare: null,
+  };
+}
+
+/**
+ * Parse a non-negative number of seconds; fractions are allowed.
+ * @param {string} value - Raw value
+ * @param {string} name - Option or variable name for the error message
+ * @returns {number} Seconds
+ */
+function parseSeconds(value, name) {
+  const text = String(value).trim();
+  const seconds = Number(text);
+  if (!/^\d+(?:\.\d+)?$/.test(text) || !Number.isFinite(seconds)) {
+    throw new Error(
+      `Invalid ${name} value: "${value}". Expected a non-negative number of seconds.`
+    );
+  }
+  return seconds;
+}
+
+/**
+ * Parse a size in bytes; k, m, g and t suffixes are 1024-based.
+ * @param {string} value - Raw value
+ * @returns {number} Bytes
+ */
+function parseSizeHint(value) {
+  const match = /^(\d+)([bkmgt])?$/.exec(String(value).trim().toLowerCase());
+  const bytes = match ? Number(match[1]) * UNITS[match[2] || ''] : NaN;
+  if (!Number.isSafeInteger(bytes)) {
+    throw new Error(
+      `Invalid --snapshot-size-hint value: "${value}". Expected a number of bytes (k, m, g, t suffixes allowed).`
+    );
+  }
+  return bytes;
+}
+
+function parseValue(flag, value) {
+  if (flag === '--snapshot-size-hint') {
+    return parseSizeHint(value);
+  }
+  if (flag === '--snapshot-prepare') {
+    if (String(value).trim() === '') {
+      throw new Error('--snapshot-prepare requires a non-empty command');
+    }
+    return value;
+  }
+  return parseSeconds(value, flag);
+}
+
+/**
+ * Parse one snapshot option.
+ * @returns {number} Arguments consumed, 0 when `args[index]` is not one
+ */
+function parse(args, index, options) {
+  const arg = args[index];
+  const equals = arg.indexOf('=');
+  const flag = equals === -1 ? arg : arg.slice(0, equals);
+  const field = FIELDS[flag];
+  if (!field) {
+    return 0;
+  }
+  if (equals !== -1) {
+    options[field] = parseValue(flag, arg.slice(equals + 1));
+    return 1;
+  }
+  const value = args[index + 1];
+  // A prepare command may itself start with a dash only through `=`.
+  if (value === undefined || value.startsWith('-')) {
+    const kind = {
+      '--snapshot-size-hint': 'bytes',
+      '--snapshot-prepare': 'command',
+    }[flag];
+    throw new Error(`Option ${flag} requires a ${kind || 'seconds'} argument`);
+  }
+  options[field] = parseValue(flag, value);
+  return 2;
+}
+
+function hasValue(value) {
+  return value !== null && value !== undefined;
+}
+
+/**
+ * Reject snapshot options outside `--resume` and fill the waits from the
+ * environment.
+ * @param {object} options - Parsed wrapper options
+ * @param {object} [env] - Environment
+ */
+function validate(options, env = process.env) {
+  if (!hasValue(options.resume)) {
+    for (const [flag, field] of Object.entries(FIELDS)) {
+      if (hasValue(options[field])) {
+        throw new Error(`${flag} is only valid with --resume`);
+      }
+    }
+    return;
+  }
+  for (const [field, [name, flag]] of Object.entries(ENV_DEFAULTS)) {
+    if (!hasValue(options[field]) && hasValue(env[name]) && env[name] !== '') {
+      options[field] = parseSeconds(env[name], `${name} (${flag})`);
+    }
+  }
+  if (hasValue(options.removeOriginalAfter)) {
+    options.removeOriginal = true;
+  }
+}
+
+/**
+ * The `snapshotOptions` `resumeExecution` reads from the wrapper options.
+ * @param {object} options - Parsed wrapper options
+ * @returns {object} {waitSeconds, diskWaitSeconds, sizeHint, prepare}
+ */
+function snapshotResumeSettings(options = {}) {
+  return {
+    waitSeconds: options.snapshotWait ?? 0,
+    diskWaitSeconds: options.snapshotDiskWait ?? 0,
+    sizeHint: options.snapshotSizeHint ?? null,
+    prepare: options.snapshotPrepare ?? null,
+  };
+}
+
+module.exports = {
+  FIELDS,
+  createSnapshotOptionDefaults,
+  parse,
+  parseSeconds,
+  parseSizeHint,
+  snapshotResumeSettings,
+  validate,
+};

package/src/lib/spawn-helpers.js

@@ -18,9 +18,14 @@ function ensureParentDirectory(filePath) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
 }
 
-function writeInitialLog(logFilePath, logContent) {
+function writeInitialLog(logFilePath, logContent, append = false) {
   ensureParentDirectory(logFilePath);
-  fs.writeFileSync(logFilePath, logContent || '', 'utf8');
+  if (append) {
+    // `--append-attempt` (issue #229): never truncate earlier attempts.
+    fs.appendFileSync(logFilePath, logContent || '', 'utf8');
+  } else {
+    fs.writeFileSync(logFilePath, logContent || '', 'utf8');
+  }
 }
 
 function appendLog(logFilePath, content) {
@@ -40,6 +45,8 @@ function appendLog(logFilePath, content) {
  * @param {Object} options.executionRecord - Execution tracking record
  * @param {Object} options.store - Execution store
  * @param {Object} options.config - CLI configuration
+ * @param {Object} [options.env] - Child environment (defaults to process.env)
+ * @param {boolean} [options.appendLog] - Append to an existing log (issue #229)
  * @param {Function} options.onComplete - Callback for completion (exitCode, endTime, logContent, durationMs)
  * @param {Function} options.onError - Callback for errors (errorMessage, endTime, durationMs)
  */
@@ -54,18 +61,21 @@ async function runWithBunSpawn(options) {
     config,
     onComplete,
     onError,
+    env,
+    appendLog: appendToLog = false,
   } = options;
 
   let logContent = options.logContent || '';
 
   try {
-    writeInitialLog(logFilePath, logContent);
+    writeInitialLog(logFilePath, logContent, appendToLog);
 
     // Spawn the process using Bun's native API
     const proc = Bun.spawn([shell, ...shellArgs], {
       stdout: 'pipe',
       stderr: 'pipe',
       stdin: 'inherit',
+      ...(env ? { env } : {}),
     });
 
     // Update execution record with PID and save initial state
@@ -186,14 +196,16 @@ async function runWithBunSpawn(options) {
     const endTime = new Date().toISOString().replace('T', ' ').substring(0, 23);
     const errorMessage = `Error executing command: ${err.message}`;
 
-    logContent += `\n${errorMessage}\n`;
-    logContent += `\n${'='.repeat(50)}\n`;
-    logContent += `Finished: ${endTime}\n`;
-    logContent += `Exit Code: 1\n`;
+    const errorTail = `\n${errorMessage}\n\n${'='.repeat(50)}\nFinished: ${endTime}\nExit Code: 1\n`;
+    logContent += errorTail;
 
-    // Write log file
+    // Write log file; an appended attempt keeps the earlier attempts (#229).
     try {
-      writeInitialLog(logFilePath, logContent);
+      if (appendToLog) {
+        writeInitialLog(logFilePath, errorTail, true);
+      } else {
+        writeInitialLog(logFilePath, logContent);
+      }
     } catch (writeErr) {
       console.error(`\nWarning: Could not save log file: ${writeErr.message}`);
     }
@@ -238,15 +250,18 @@ function runWithNodeSpawn(options) {
     config,
     onComplete,
     onError,
+    env,
+    appendLog: appendToLog = false,
   } = options;
 
   let logContent = options.logContent || '';
-  writeInitialLog(logFilePath, logContent);
+  writeInitialLog(logFilePath, logContent, appendToLog);
 
   // Execute the command with captured output
   const child = spawn(shell, shellArgs, {
     stdio: ['inherit', 'pipe', 'pipe'],
     shell: false,
+    ...(env ? { env } : {}),
   });
 
   // Update execution record with PID and save initial state
@@ -330,14 +345,16 @@ function runWithNodeSpawn(options) {
     const endTime = new Date().toISOString().replace('T', ' ').substring(0, 23);
     const errorMessage = `Error executing command: ${err.message}`;
 
-    logContent += `\n${errorMessage}\n`;
-    logContent += `\n${'='.repeat(50)}\n`;
-    logContent += `Finished: ${endTime}\n`;
-    logContent += `Exit Code: 1\n`;
+    const errorTail = `\n${errorMessage}\n\n${'='.repeat(50)}\nFinished: ${endTime}\nExit Code: 1\n`;
+    logContent += errorTail;
 
-    // Write log file
+    // Write log file; an appended attempt keeps the earlier attempts (#229).
     try {
-      writeInitialLog(logFilePath, logContent);
+      if (appendToLog) {
+        writeInitialLog(logFilePath, errorTail, true);
+      } else {
+        writeInitialLog(logFilePath, logContent);
+      }
     } catch (writeErr) {
       console.error(`\nWarning: Could not save log file: ${writeErr.message}`);
     }

package/src/lib/status-formatter.js

@@ -7,11 +7,12 @@
  * - Text: Human-readable text format
  */
 
-const { execSync, spawnSync } = require('child_process');
+const { execSync } = require('child_process');
+const { escapeForLinksNotation } = require('./output-blocks');
 const {
-  escapeForLinksNotation,
-  formatAsNestedLinksNotation,
-} = require('./output-blocks');
+  appendLinksValue,
+  formatTextOptionValue,
+} = require('./status-links-notation');
 const { collectProcessIds } = require('./execution-control');
 const { getDockerCommand, getDockerSpawnOptions } = require('./docker-cleanup');
 const {
@@ -27,6 +28,11 @@ const {
 const { normalizeDockerTimestamp } = require('./docker-post-mortem');
 const { END_TIME_SOURCE } = require('./detached-finalize');
 const { formatCgroupMemory } = require('./cgroup-memory');
+const {
+  attachContainerRemoval,
+  dockerInspect,
+  persistContainerRemoval,
+} = require('./container-removal');
 
 /**
  * Inspect the live state of a detached docker container by name.
@@ -43,32 +49,31 @@ const { formatCgroupMemory } = require('./cgroup-memory');
  * instead of fabricating a terminal `-1` result.
  *
  * @param {string} sessionName - Container name
+ * @param {Object|null} [probe] - Receives `sessionNotFound` (issue #225)
  * @returns {{running: boolean, exitCode: number|null, oomKilled: boolean|null}|null} State,
  *   or null when the container cannot be inspected (not found yet, removed, or docker error)
  */
-function inspectDockerState(sessionName) {
-  const result = spawnSync(
+function inspectDockerState(sessionName, probe = null) {
+  const { stdout, notFound } = dockerInspect(
     getDockerCommand(),
-    [
-      'inspect',
-      '-f',
-      '{{.State.Running}} {{.State.ExitCode}} {{.State.OOMKilled}} ' +
-        '{{.State.StartedAt}} {{.State.FinishedAt}}',
-      sessionName,
-    ],
-    getDockerSpawnOptions({
-      encoding: 'utf8',
-      env: process.env,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    })
+    dockerProbeSpawnOptions(),
+    '{{.State.Running}} {{.State.ExitCode}} {{.State.OOMKilled}} ' +
+      '{{.State.StartedAt}} {{.State.FinishedAt}}',
+    sessionName
   );
-  if (result.error || result.status !== 0 || !result.stdout) {
+  if (probe) {
+    // "No such container" is a fact, unlike a docker that cannot be reached
+    // (issue #225); it still reads as unknown liveness here (issue #136).
+    probe.sessionNotFound = notFound;
+  }
+  if (stdout === null) {
     return null;
   }
   // 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 [runningRaw, exitRaw, oomKilledRaw, startedRaw, finishedRaw] = stdout
+    .trim()
+    .split(/\s+/);
   const exitCode = Number.parseInt(exitRaw, 10);
   return {
     running: runningRaw === 'true',
@@ -89,12 +94,20 @@ function isDetachedDockerRecord(record) {
   );
 }
 
-function readDockerState(record) {
+function dockerProbeSpawnOptions() {
+  return getDockerSpawnOptions({
+    encoding: 'utf8',
+    env: process.env,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+function readDockerState(record, probe = null) {
   const opts = record.options || {};
   if (opts.isolated !== 'docker' || !opts.sessionName) {
     return null;
   }
-  const state = inspectDockerState(opts.sessionName);
+  const state = inspectDockerState(opts.sessionName, probe);
   if (
     record.attempt &&
     state?.startedAt &&
@@ -325,14 +338,14 @@ function applyEndTime(enriched, dockerState, footerFinishedAt) {
   enriched.observedAt = enriched.endTime;
 }
 
-function resolveDetachedStatus(record, logTail) {
+function resolveDetachedStatus(record, logTail, probe = null) {
   if (require('./launch-owner').hasActiveLaunch(record)) {
     return record;
   }
   const footer = parseFooterFromTail(logTail);
   const footerExit = footer.exitCode;
   const dockerState = isDetachedDockerRecord(record)
-    ? readDockerState(record)
+    ? readDockerState(record, probe)
     : null;
   const alive = isDetachedDockerRecord(record)
     ? dockerState === null
@@ -550,7 +563,14 @@ function enrichDetachedStatus(record) {
   const logTail = record
     ? readAttemptLogTail(record, FATAL_MARKER_TAIL_BYTES)
     : null;
-  const resolved = resolveDetachedStatus(record, logTail);
+  const probe = {
+    dockerCommand: getDockerCommand(),
+    spawnOptions: dockerProbeSpawnOptions(),
+  };
+  const resolved = attachContainerRemoval(
+    resolveDetachedStatus(record, logTail, probe),
+    probe
+  );
   const enriched = attachMemoryExhaustion(
     attachExitReason(resolved, logTail),
     logTail
@@ -671,22 +691,21 @@ function formatRecordAsLinksNotation(record) {
   for (const [key, value] of Object.entries(obj)) {
     if (value !== null && value !== undefined) {
       if (key === 'options' && typeof value === 'object') {
-        // Format options as nested Links notation
+        // Nested option values (launchOwner, exitEvidence, resolvedLimits…)
+        // are rendered as nested Links notation, never "[object Object]"
+        // (issue #226).
         const optionEntries = Object.entries(value).filter(
           ([, v]) => v !== null && v !== undefined
         );
         if (optionEntries.length > 0) {
           lines.push('  options');
           for (const [optKey, optValue] of optionEntries) {
-            const formattedOptValue = escapeForLinksNotation(optValue);
-            lines.push(`    ${optKey} ${formattedOptValue}`);
+            appendLinksValue(lines, optKey, optValue, 4);
           }
         }
       } else if (typeof value === 'object') {
-        // For other objects, still format as nested Links notation
-        lines.push(`  ${key}`);
-        const nested = formatAsNestedLinksNotation(value, 2, 2);
-        lines.push(nested);
+        // Other objects use the same nested layout as the Rust formatter.
+        appendLinksValue(lines, key, value, 2);
       } else {
         const formattedValue = escapeForLinksNotation(value);
         lines.push(`  ${key} ${formattedValue}`);
@@ -710,6 +729,7 @@ function formatRecordAsText(record) {
     `UUID:              ${obj.uuid}`,
     `Status:            ${obj.status}`,
     `Command:           ${obj.command}`,
+    ...require('./execution-chain').identityTextLines(obj),
     `Exit Code:         ${obj.exitCode !== null ? describeExitCode(obj.exitCode).text : 'N/A'}`,
     ...(obj.oomKilled !== undefined
       ? [`OOM Killed:        ${obj.oomKilled}`]
@@ -751,6 +771,11 @@ function formatRecordAsText(record) {
   if (obj.staleDetectedAt) {
     lines.push(`Stale Detected At: ${obj.staleDetectedAt}`);
   }
+  if (obj.containerState) {
+    // The container no longer exists; `containerId` is history (issue #225).
+    lines.push(`Container State:   ${obj.containerState}`);
+    lines.push(`Container Removed: ${obj.containerRemovedObservedAt || 'N/A'}`);
+  }
   lines.push(`Log Path:          ${obj.logPath}`);
   if (obj.attempt) {
     lines.push(
@@ -770,7 +795,7 @@ function formatRecordAsText(record) {
   if (optionEntries.length > 0) {
     lines.push(`Options:`);
     for (const [key, value] of optionEntries) {
-      lines.push(`  ${key}: ${value}`);
+      lines.push(`  ${key}: ${formatTextOptionValue(value)}`);
     }
   }
 
@@ -897,9 +922,13 @@ function queryStatus(store, identifier, outputFormat) {
   try {
     // Enrich detached execution status with live session check
     const enrichedRecord = enrichDetachedStatus(record);
+    persistContainerRemoval(store, record, enrichedRecord);
     const withProcessIds = attachProcessIds(enrichedRecord);
     // Attach currentTime so callers can see how long an executing command has been running
-    const withCurrentTime = attachCurrentTime(withProcessIds);
+    const withCurrentTime = require('./execution-chain').attachIdentity(
+      attachCurrentTime(withProcessIds),
+      store
+    );
     return {
       success: true,
       output: formatRecord(withCurrentTime, outputFormat || 'links-notation'),

package/src/lib/status-links-notation.js

@@ -0,0 +1,97 @@
+/**
+ * Links-notation and text rendering of nested `--status` values.
+ *
+ * `--status` stores structured option values such as `launchOwner`,
+ * `exitEvidence`, `resolvedLimits` and `resourceLimitSpecs`. They used to be
+ * passed through `escapeForLinksNotation` (and a template string in the text
+ * format), which printed `"[object Object]"` and lost the values (issue #226).
+ * These helpers render nested objects and arrays the same way the Rust
+ * formatter's `append_links_value` does, so both implementations print the
+ * same layout.
+ */
+
+const { escapeForLinksNotation } = require('./output-blocks');
+
+function isPresent(value) {
+  return value !== null && value !== undefined;
+}
+
+/**
+ * Append an array as a `(` … `)` block.
+ * @param {string[]} lines - Output lines
+ * @param {Array} values - Array to render
+ * @param {number} indent - Indentation of the parentheses
+ */
+function appendLinksArray(lines, values, indent) {
+  const prefix = ' '.repeat(indent);
+  if (values.length === 0) {
+    lines.push(`${prefix}()`);
+    return;
+  }
+  lines.push(`${prefix}(`);
+  for (const value of values) {
+    if (Array.isArray(value)) {
+      appendLinksArray(lines, value, indent + 2);
+    } else if (isPresent(value) && typeof value === 'object') {
+      for (const [childKey, childValue] of Object.entries(value)) {
+        if (isPresent(childValue)) {
+          appendLinksValue(lines, childKey, childValue, indent + 2);
+        }
+      }
+    } else {
+      lines.push(`${' '.repeat(indent + 2)}${escapeForLinksNotation(value)}`);
+    }
+  }
+  lines.push(`${prefix})`);
+}
+
+/**
+ * Append `key value`, or `key` followed by its nested children.
+ * Children of an object are indented by four more spaces, matching the
+ * top-level `  key` / `      child` layout `--status` has always used.
+ * @param {string[]} lines - Output lines
+ * @param {string} key - Field name
+ * @param {*} value - Field value
+ * @param {number} indent - Indentation of the key
+ */
+function appendLinksValue(lines, key, value, indent) {
+  const prefix = ' '.repeat(indent);
+  if (Array.isArray(value)) {
+    lines.push(`${prefix}${key}`);
+    appendLinksArray(lines, value, indent + 2);
+    return;
+  }
+  if (isPresent(value) && typeof value === 'object') {
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+      return;
+    }
+    lines.push(`${prefix}${key}`);
+    for (const [childKey, childValue] of entries) {
+      if (isPresent(childValue)) {
+        appendLinksValue(lines, childKey, childValue, indent + 4);
+      }
+    }
+    return;
+  }
+  lines.push(`${prefix}${key} ${escapeForLinksNotation(value)}`);
+}
+
+/**
+ * Render an option value for the text format: scalars as-is, structured
+ * values as compact JSON (the Rust formatter uses `serde_json::to_string`).
+ * @param {*} value - Option value
+ * @returns {string} Rendered value
+ */
+function formatTextOptionValue(value) {
+  if (isPresent(value) && typeof value === 'object') {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+
+module.exports = {
+  appendLinksArray,
+  appendLinksValue,
+  formatTextOptionValue,
+};

package/src/lib/store-lock.js

@@ -14,6 +14,8 @@ class LockManager {
     this.identity = null;
     this.token = null;
     this.monitorOwner = monitorOwner;
+    // Extra fields published in the lock file, for example who holds it.
+    this.metadata = {};
   }
 
   acquire(timeout = LOCK_TIMEOUT_MS) {
@@ -44,6 +46,7 @@ class LockManager {
         this.fs.writeFileSync(
           temp,
           JSON.stringify({
+            ...this.metadata,
             pid: process.pid,
             timestamp: Date.now(),
             hostname: os.hostname(),

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 [--running] [--output-format <fmt>] | $ --upload-log <id> | $ --stop <id> | $ --terminate <id> | $ --attach <id> [--read-only] | $ --resume <id> [-- <command>] | $ --resume-all
+  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 | $ --alias <id> <name> | $ --rename <id> <name>
 
 Options:
   --help, -h           Show this usage and exit successfully
@@ -10,6 +10,8 @@ Options:
   --session, -s <name>  Session name for isolation
   --session-id <uuid>   Session UUID for tracking (auto-generated if not provided)
   --session-name <uuid> Alias for --session-id
+  --append-attempt      Run as the next attempt of the existing --session-id execution
+  --continues <id>      Record that this execution continues an earlier one
   --image <image>       Docker image (optional, defaults to OS-matched image)
   --volume, -v <spec>   Docker bind mount/volume host:container[:mode] (repeatable, docker only)
   --mount <spec>        Docker --mount spec (repeatable, docker only)
@@ -54,9 +56,18 @@ Options:
   --resume <id>         Restart a stopped detached execution in the same environment
                         (append -- <command> to run a different command there)
   --remove-original    With legacy snapshot resume, remove the stopped original after launch
+  --remove-original-after <s>  Remove it only if the replacement still runs after <s> seconds
+  --snapshot-wait <s>   Wait up to <s> seconds for another snapshot on this host (exit 75 after)
+  --snapshot-disk-wait <s>  Wait up to <s> seconds for free disk instead of refusing (exit 75 after)
+  --snapshot-size-hint <bytes>  Use this writable-layer size instead of docker inspect --size
+  --snapshot-prepare <cmd>  docker exec <cmd> in the started original before it is snapshotted
   --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)
+  --cleanup <id>        Remove a Docker execution's containers and snapshot images (never forced)
+  --cleanup-dry-run <id>  Show the containers and images --cleanup <id> would remove
+  --alias <id> <name>   Add a name the execution can be addressed by
+  --rename <id> <name>  Rename the execution, keeping its previous name as an alias
   --version, -v         Show version information
 
 Examples:
@@ -84,6 +95,9 @@ Examples:
   $ --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
+  $ --session-id <uuid> --append-attempt -- npm test  # Next attempt, same log
+  $ --continues <uuid> -- npm test         # Fresh execution chained to <uuid>
+  $ --rename <uuid> nightly-build          # Address it as nightly-build from now on
   $ -i docker -d --on-kill-resume 3 --recovery-command 'solve --resume' -- solve
   $ -i docker -d --on-kill-resume 3 --on-kill-resume-delay 30-90 -- cargo test
   $ --use-command-stream echo "Hello"      # Use command-stream library`);

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

@@ -142,7 +142,7 @@ describe('query mode exclusivity', () => {
     test(`rejects ${args.join(' ')}`, () => {
       assert.throws(() => {
         parse(args);
-      }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, --attach, --resume, --resume-all, or --cleanup/);
+      }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, --attach, --resume, --resume-all, --cleanup, --alias, or --rename/);
     });
   }
 });

package/test/args-parser-control.js

@@ -54,13 +54,13 @@ 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, --attach, --resume, --resume-all, or --cleanup/);
+    }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, --attach, --resume, --resume-all, --cleanup, --alias, or --rename/);
   });
 
   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, --attach, --resume, --resume-all, or --cleanup/);
+    }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, --attach, --resume, --resume-all, --cleanup, --alias, or --rename/);
   });
 
   it('should reject output-format with control modes', () => {