start-command 0.37.9 → 0.38.0

package/src/lib/launch-identity.js

@@ -0,0 +1,411 @@
+/**
+ * What a new launch may do with its execution id (issue #229).
+ *
+ * A launch with an explicit `--session-id` that is already tracked used to
+ * replace the record and truncate the log. It is now refused unless
+ * `--append-attempt` is given, which keeps the record, archives the previous
+ * attempt into `attemptHistory`, and appends the new attempt to the same log
+ * after a lifecycle header (the layout `--resume` already writes).
+ *
+ * Two cases keep the earlier behaviour:
+ * - the next level of a stacked isolation, which receives the same
+ *   `--session-id` from its parent and runs with START_EXECUTION_ID already
+ *   set to it (`isNestedLaunchOf`);
+ * - a generated UUID, which cannot collide.
+ */
+const fs = require('fs');
+const { isNestedLaunchOf, ATTEMPT_ENV } = require('./execution-env');
+const { findRecord, withStoreLock } = require('./execution-identity');
+
+const LOG_HEADER = '=== Start Command Log ===';
+
+class LaunchRefusedError extends Error {}
+
+function alreadyExistsMessage(uuid) {
+  return `execution ${uuid} already exists; use $ --resume ${uuid} -- <command> to continue it, or pass --append-attempt`;
+}
+
+function isPidAlive(pid) {
+  if (!pid) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+/** True while the stored execution may still be running. */
+function isExecutionLive(record) {
+  if (require('./launch-owner').hasActiveLaunch(record)) {
+    return true;
+  }
+  if (record.status !== 'executing') {
+    return false;
+  }
+  if (record.options && record.options.isolated) {
+    try {
+      return require('./session-probe').probeSession(record).alive === true;
+    } catch {
+      return true;
+    }
+  }
+  return isPidAlive(record.pid);
+}
+
+/** Attempts already in a log written without tracking, from its headers. */
+function countLoggedAttempts(logPath) {
+  try {
+    return fs.readFileSync(logPath, 'utf8').split(LOG_HEADER).length - 1;
+  } catch {
+    return 0;
+  }
+}
+
+function logSize(logPath) {
+  try {
+    return fs.statSync(logPath).size;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Decide how a launch uses its execution id, before anything is printed or
+ * created.
+ * @param {object} params - {store, sessionId, explicitSessionId,
+ *   appendAttempt, logPath, env}
+ * @returns {{append: boolean, previous: object|null, attemptNumber: number,
+ *   logPath: string, nested: boolean, checked: boolean}}
+ * @throws {LaunchRefusedError} When the launch must not run
+ */
+function preflightLaunch(params) {
+  const { store, sessionId, logPath } = params;
+  const env = params.env || process.env;
+  const fresh = {
+    append: false,
+    previous: null,
+    attemptNumber: 1,
+    logPath,
+    nested: false,
+    checked: false,
+  };
+  if (!params.explicitSessionId) {
+    return fresh;
+  }
+  if (isNestedLaunchOf(sessionId, env)) {
+    const inherited = Number(env[ATTEMPT_ENV]);
+    return {
+      ...fresh,
+      nested: true,
+      attemptNumber:
+        Number.isSafeInteger(inherited) && inherited > 0 ? inherited : 1,
+    };
+  }
+  const existing = store ? store.get(sessionId) : null;
+  if (existing && existing.uuid !== sessionId) {
+    throw new LaunchRefusedError(
+      `execution id ${sessionId} is already used as a name of execution ${existing.uuid}; pick another --session-id`
+    );
+  }
+  if (existing) {
+    if (!params.appendAttempt) {
+      throw new LaunchRefusedError(alreadyExistsMessage(sessionId));
+    }
+    if (isExecutionLive(existing)) {
+      throw new LaunchRefusedError(
+        `execution ${sessionId} is still running; wait for it to finish or use $ --stop ${sessionId} before --append-attempt`
+      );
+    }
+    const { nextAttemptNumber } = require('./execution-attempt');
+    return {
+      ...fresh,
+      append: true,
+      previous: existing,
+      attemptNumber: nextAttemptNumber(existing),
+      logPath: existing.logPath || logPath,
+      checked: true,
+    };
+  }
+  // Untracked (or deleted) executions are recognised by their log file.
+  if (logPath && fs.existsSync(logPath)) {
+    if (!params.appendAttempt) {
+      throw new LaunchRefusedError(alreadyExistsMessage(sessionId));
+    }
+    return {
+      ...fresh,
+      append: true,
+      attemptNumber: countLoggedAttempts(logPath) + 1,
+      checked: true,
+    };
+  }
+  return { ...fresh, checked: true };
+}
+
+/**
+ * Turn the record a launch built into the next attempt of `previous`,
+ * keeping the identity, history and log of the execution.
+ * @param {object} record - Freshly built ExecutionRecord (mutated)
+ * @param {object} previous - Stored record of the same UUID
+ * @returns {object} The record
+ */
+function mergeAppendedAttempt(record, previous) {
+  const {
+    archiveAttempt,
+    createAttempt,
+    currentAttemptNumber,
+  } = require('./execution-attempt');
+  const prior = require('./execution-store').ExecutionRecord.fromObject(
+    JSON.parse(JSON.stringify(previous.toObject()))
+  );
+  if (!prior.attempt && currentAttemptNumber(prior) === 1) {
+    // A launch writes a fresh log, so its first attempt starts at offset 0.
+    prior.attempt = { number: 1, startedAt: prior.startTime, logOffset: 0 };
+  }
+  const attempt = createAttempt(prior, {
+    mode: 'append-attempt',
+    sessionName: record.options.sessionName || null,
+  });
+  archiveAttempt(prior);
+  const keep = prior.options || {};
+  const history = [...(keep.sessionNameHistory || [])];
+  if (keep.sessionName && keep.sessionName !== record.options.sessionName) {
+    history.push(keep.sessionName);
+  }
+  record.attempt = attempt;
+  record.attemptHistory = prior.attemptHistory;
+  record.startTime = prior.startTime;
+  record.logPath = prior.logPath || record.logPath;
+  record.continues = record.continues || prior.continues;
+  record.options = {
+    ...record.options,
+    ...(history.length ? { sessionNameHistory: [...new Set(history)] } : {}),
+    ...(keep.aliases ? { aliases: keep.aliases } : {}),
+    ...(keep.name ? { name: keep.name } : {}),
+    ...(keep.resumeCount ? { resumeCount: keep.resumeCount } : {}),
+  };
+  return record;
+}
+
+/**
+ * Persist the launch's record, refusing if another launch claimed the id in
+ * the meantime: a new id must still be free, an appended attempt must still
+ * follow the attempt the preflight saw.
+ * @param {object} store - ExecutionStore
+ * @param {object} record - Record to save
+ * @param {object} launch - preflightLaunch() result
+ */
+function claimLaunch(store, record, launch) {
+  if (!launch.checked) {
+    store.save(record);
+    return;
+  }
+  withStoreLock(store, (records) => {
+    const index = records.findIndex((r) => r.uuid === record.uuid);
+    if (launch.previous) {
+      const current = records[index];
+      if (
+        !current ||
+        require('./launch-owner').hasActiveLaunch(current) ||
+        (current.attempt?.number || 0) !==
+          (launch.previous.attempt?.number || 0)
+      ) {
+        throw new LaunchRefusedError(
+          `execution ${record.uuid} was claimed by another launch`
+        );
+      }
+      records[index] = record;
+    } else {
+      if (findRecord(records, record.uuid)) {
+        throw new LaunchRefusedError(alreadyExistsMessage(record.uuid));
+      }
+      records.push(record);
+    }
+    return record;
+  });
+}
+
+/**
+ * Header a launch writes into its log: unchanged for a fresh log; for an
+ * appended attempt, preceded by a lifecycle line in the format `--resume`
+ * writes, so the attempts stay apart.
+ * @param {string} content - Header content
+ * @param {object} launch - preflightLaunch() result
+ * @param {object|null} record - Record of the launch, when tracked
+ * @returns {string} Content to write
+ */
+function launchLogContent(content, launch, record = null) {
+  if (!launch.append) {
+    return content;
+  }
+  const lifecycle = {
+    event: 'attempt-appended',
+    at: new Date().toISOString(),
+    uuid: record ? record.uuid : null,
+    attemptNumber: launch.attemptNumber,
+    ...(record && record.attempt ? record.attempt : {}),
+  };
+  return `\n[Start Command Lifecycle] ${JSON.stringify(lifecycle)}\n${content}`;
+}
+
+/**
+ * Save the initial record of a direct run, before it starts. A refused
+ * claim ends the launch with exit code 1; other failures only lose tracking.
+ * @param {object|null} store - ExecutionStore
+ * @param {object|null} record - Execution record
+ * @param {object} launch - prepareLaunch() result
+ * @param {object} [config] - CLI configuration ({verbose})
+ */
+function claimDirectLaunch(store, record, launch, config = {}) {
+  if (!record || !store) {
+    return;
+  }
+  try {
+    claimLaunch(store, record, launch);
+  } catch (err) {
+    if (err instanceof LaunchRefusedError) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    if (config.verbose) {
+      console.error(
+        `[Tracking] Warning: Could not save execution record: ${err.message}`
+      );
+    }
+  }
+}
+
+/**
+ * Write the launch header: a fresh log, or, for an appended attempt, a
+ * lifecycle line and the header after the earlier attempts.
+ * @param {string} logPath - Log path
+ * @param {string} content - Header content
+ * @param {object} launch - preflightLaunch() result
+ * @param {object|null} record - Record of the launch, when tracked
+ */
+function writeLaunchLog(logPath, content, launch, record = null) {
+  const { appendLogFile, writeLogFile } = require('./isolation-log-utils');
+  const text = launchLogContent(content, launch, record);
+  if (launch.append) {
+    appendLogFile(logPath, text);
+  } else {
+    writeLogFile(logPath, text);
+  }
+}
+
+/**
+ * Preflight of the CLI: how this launch uses its id (#229) and which
+ * execution it continues (#231).
+ * @param {object} store - ExecutionStore, or null when tracking is off
+ * @param {object} options - Parsed wrapper options
+ * @param {string} sessionId - Execution UUID of the launch
+ * @param {string} logPath - Default log path of the launch
+ * @returns {object} preflightLaunch() result plus `continues`
+ * @throws {Error} When the launch must not run
+ */
+function prepareLaunch(store, options, sessionId, logPath) {
+  const launch = preflightLaunch({
+    store,
+    sessionId,
+    explicitSessionId: Boolean(options.sessionId),
+    appendAttempt: Boolean(options.appendAttempt),
+    logPath,
+  });
+  launch.continues = options.continues
+    ? require('./execution-chain').resolveContinues(
+        store,
+        options.continues,
+        sessionId
+      )
+    : null;
+  return launch;
+}
+
+/**
+ * Apply the preflight to the record a launch built: the continued UUID and,
+ * for `--append-attempt`, the identity and history of the stored execution.
+ * @param {object|null} record - Freshly built ExecutionRecord (mutated)
+ * @param {object} launch - prepareLaunch() result
+ * @returns {object|null} The record
+ */
+function applyLaunch(record, launch) {
+  if (!record) {
+    return record;
+  }
+  if (launch.continues) {
+    record.continues = launch.continues;
+  }
+  if (launch.previous) {
+    mergeAppendedAttempt(record, launch.previous);
+  } else if (launch.attemptNumber > 1) {
+    // A nested level or an untracked log: number the attempt all the same.
+    record.attempt = {
+      number: launch.attemptNumber,
+      startedAt: new Date().toISOString(),
+      logOffset: launch.append ? logSize(launch.logPath) : 0,
+      mode: launch.nested ? 'nested' : 'append-attempt',
+    };
+  }
+  return record;
+}
+
+/**
+ * START_* variables of a run without a backend session (direct, or
+ * `--isolated-user` alone): the session name is empty.
+ * @param {string} sessionId - Execution UUID
+ * @param {object} launch - prepareLaunch() result
+ * @returns {object} Variables
+ */
+function directExecutionEnv(sessionId, launch) {
+  return require('./execution-env').buildExecutionEnv({
+    executionId: sessionId,
+    sessionName: '',
+    attempt: launch.attemptNumber,
+  });
+}
+
+/**
+ * Child environment of a direct run.
+ * @param {string} sessionId - Execution UUID
+ * @param {object} launch - prepareLaunch() result
+ * @returns {object} Child environment
+ */
+function directLaunchEnv(sessionId, launch) {
+  return require('./execution-env').withExecutionEnv(
+    directExecutionEnv(sessionId, launch)
+  );
+}
+
+/**
+ * Command of an `--isolated-user` run without a backend: `sudo` resets the
+ * environment, so the variables are exported by the command itself.
+ * @param {string} cmd - Shell command
+ * @param {string} sessionId - Execution UUID
+ * @param {object} launch - prepareLaunch() result
+ * @returns {string} Prefixed command
+ */
+function isolatedUserCommand(cmd, sessionId, launch) {
+  return require('./execution-env').prefixWithExecutionEnv(
+    cmd,
+    directExecutionEnv(sessionId, launch)
+  );
+}
+
+module.exports = {
+  LaunchRefusedError,
+  alreadyExistsMessage,
+  applyLaunch,
+  claimDirectLaunch,
+  claimLaunch,
+  directExecutionEnv,
+  directLaunchEnv,
+  isolatedUserCommand,
+  isExecutionLive,
+  launchLogContent,
+  mergeAppendedAttempt,
+  prepareLaunch,
+  preflightLaunch,
+  writeLaunchLog,
+};

package/src/lib/log-uploader.js

@@ -200,7 +200,21 @@ function uploadExecutionLog(store, identifier, options = {}) {
     };
   }
 
-  return uploadLogPath(record.logPath, options);
+  // A continuation chain uploads every execution, oldest first (#231).
+  let prepared;
+  try {
+    prepared = require('./execution-chain').prepareUploadLog(store, record);
+  } catch (error) {
+    return {
+      success: false,
+      error: `Could not join chain logs: ${error.message}`,
+    };
+  }
+  try {
+    return uploadLogPath(prepared.path, options);
+  } finally {
+    prepared.cleanup();
+  }
 }
 
 module.exports = {

package/src/lib/query-commands.js

@@ -4,8 +4,9 @@
  * Every option in this module addresses an execution that already exists in
  * the tracking store instead of launching a new one: --status, --list,
  * --upload-log, --stop, --terminate, --attach, --resume, --resume-all and
- * --cleanup. `dispatchQueryCommand` is the single entry point the CLI calls
- * before it starts interpreting the command line as a command to run.
+ * --cleanup, plus --alias and --rename. `dispatchQueryCommand` is the single
+ * entry point the CLI calls before it starts interpreting the command line as
+ * a command to run.
  */
 
 const { queryStatus, listExecutions } = require('./status-formatter');
@@ -157,7 +158,9 @@ function hasQueryMode(options) {
     hasValue(options.attach) ||
     hasValue(options.resume) ||
     options.resumeAll === true ||
-    options.cleanup === true
+    options.cleanup === true ||
+    hasValue(options.alias) ||
+    hasValue(options.rename)
   );
 }
 
@@ -208,6 +211,18 @@ async function dispatchQueryCommand(options, context = {}) {
   if (options.cleanup) {
     return handleCleanup(store, options.cleanupDryRun, options.cleanupTarget);
   }
+  if (hasValue(options.alias) || hasValue(options.rename)) {
+    const { nameExecution } = require('./execution-identity');
+    const rename = hasValue(options.rename);
+    return reportResult(
+      nameExecution(
+        store,
+        rename ? options.rename : options.alias,
+        options.newName,
+        { rename }
+      )
+    );
+  }
 
   return null;
 }

package/src/lib/screen-isolation.js

@@ -128,6 +128,8 @@ function supportsLogfileOption() {
  * @param {string|null} user - Username to run command as (optional)
  * @param {Function} wrapCommandWithUser - Function to wrap command with user
  * @param {Function} isInteractiveShellCommand - Function to check if command is interactive shell
+ * @param {string|null} logPath - Log file to append to (optional)
+ * @param {object|null} env - Extra environment, e.g. START_* (optional)
  * @returns {Promise<{success: boolean, sessionName: string, message: string, output: string, exitCode: number}>}
  */
 function runScreenWithLogCapture(
@@ -137,7 +139,8 @@ function runScreenWithLogCapture(
   user = null,
   wrapCommandWithUser,
   isInteractiveShellCommand,
-  logPath = null
+  logPath = null,
+  env = null
 ) {
   const { shell, shellArg } = shellInfo;
   const screenTempDir = getTempDir('isolation', 'screen');
@@ -237,8 +240,10 @@ function runScreenWithLogCapture(
       }
 
       // Use spawnSync with array args (not execSync string) to avoid quoting issues (issue #25)
+      // Each `screen -dmS` server inherits this env (START_*, issue #230).
       const result = spawnSync('screen', screenArgs, {
         stdio: 'inherit',
+        env: { ...process.env, ...env },
       });
 
       if (result.error) {
@@ -424,6 +429,7 @@ function startDetachedScreenWithLogCapture(
     keepAlive = false,
     logPath = null,
     wrapCommandWithUser,
+    env = null,
   } = options;
 
   const screenTempDir = getTempDir('isolation', 'screen');
@@ -471,7 +477,10 @@ function startDetachedScreenWithLogCapture(
   }
 
   try {
-    const result = spawnSync('screen', screenArgs, { stdio: 'inherit' });
+    const result = spawnSync('screen', screenArgs, {
+      stdio: 'inherit',
+      env: { ...process.env, ...env },
+    });
     if (result.error) {
       throw result.error;
     }

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

@@ -729,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}`]
@@ -924,7 +925,10 @@ function queryStatus(store, identifier, outputFormat) {
     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/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)
@@ -64,6 +66,8 @@ Options:
   --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:
@@ -91,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`);