start-command 0.37.8 → 0.38.0

package/src/lib/execution-recovery.js

@@ -379,6 +379,23 @@ function recoverKilledExecution(params = {}) {
     }
   }
 
+  if (opts.commandHandoff && record.uuid) {
+    // `docker start` keeps the creation env; refresh START_ATTEMPT (#230).
+    try {
+      require('./docker-command-handoff').writeExecutionEnvHandoff(
+        containerName,
+        require('./execution-env').buildExecutionEnv({
+          executionId: record.uuid,
+          sessionName: containerName,
+          attempt: require('./execution-attempt').nextAttemptNumber(record),
+        }),
+        runner
+      );
+    } catch {
+      // Non-fatal: the command still runs, with the previous START_ATTEMPT.
+    }
+  }
+
   const since = now().toISOString();
   const {
     appendLifecycle,
@@ -458,6 +475,8 @@ function recoverKilledExecution(params = {}) {
   record.observedAt = undefined;
   record.staleDetectedAt = undefined;
   record.containerStartedAt = undefined;
+  record.containerState = undefined;
+  record.containerRemovedObservedAt = undefined;
   const previousData = globalThis.structuredClone(store.get(executionId));
   const previous = record.constructor.fromObject
     ? record.constructor.fromObject(previousData)

package/src/lib/execution-resume.js

@@ -34,6 +34,7 @@ const {
   appendLifecycle,
   archiveAttempt,
   createAttempt,
+  nextAttemptNumber,
   patchAttempt,
 } = require('./execution-attempt');
 const { runCommand } = require('./execution-control');
@@ -46,6 +47,7 @@ const { SessionState, probeSession } = require('./session-probe');
 const { getDockerNetworks } = require('./docker-network-lifecycle');
 const {
   writeCommandHandoff,
+  writeExecutionEnvHandoff,
   buildCommandHandoffArgs,
   commandHandoffPath,
 } = require('./docker-command-handoff');
@@ -54,6 +56,7 @@ const {
   preflightSnapshot,
   SNAPSHOT_IMAGE_LABEL,
 } = require('./docker-snapshot-safety');
+const snapshotResume = require('./docker-snapshot-resume');
 const {
   ResumeAllAction,
   resumeAllExecutions,
@@ -109,6 +112,8 @@ function buildLaunchOptions(record) {
     rootSession:
       opts.rootSession || opts.sessionNameHistory?.[0] || opts.sessionName,
     resumeCount: (Number(opts.resumeCount) || 0) + 1,
+    // START_ATTEMPT of the relaunched command (issue #230).
+    attemptNumber: nextAttemptNumber(record),
     image: opts.image || null,
     session: opts.sessionName,
     detached: true,
@@ -288,6 +293,7 @@ function buildResumePlan(
               session: newSessionName,
               containerName: newSessionName,
               sessionId: record.uuid,
+              attemptNumber: nextAttemptNumber(record),
               rootSession:
                 opts.rootSession || opts.sessionNameHistory?.[0] || sessionName,
               resumeCount: attempt,
@@ -441,8 +447,10 @@ function activeSessionName(plan) {
  * Resume a tracked execution by UUID or session name.
  * @param {?object} store - Execution store
  * @param {string} identifier - UUID or session name
- * @param {object} deps - {command, outputFormat, probe, runner, startWatcher, runIsolated}
- * @returns {Promise<{success: boolean, output?: string, error?: string}>}
+ * @param {object} deps - {command, outputFormat, probe, runner, runAsync,
+ *   startWatcher, runIsolated, removeOriginal, removeOriginalAfter,
+ *   snapshotOptions, notify}
+ * @returns {Promise<{success: boolean, output?: string, error?: string, exitCode?: number}>}
  */
 async function resumeExecution(store, identifier, deps = {}) {
   if (!store) {
@@ -605,16 +613,34 @@ async function resumeExecution(store, identifier, deps = {}) {
     }
     containerId = launchResult.containerId || null;
   } else {
+    const notify = deps.notify || ((line) => process.stderr.write(`${line}\n`));
+    const snapshotOptions = { notify, ...deps.snapshotOptions };
+    const progress = {
+      sessionName: plan.sessionName,
+      logPath: record.logPath,
+      notify,
+    };
     let snapshotLock;
     let snapshotCreated = false;
     let derivedCreated = false;
     try {
       if (plan.mode === ResumeMode.DOCKER_SNAPSHOT) {
-        snapshotLock = acquireSnapshotLock(deps.snapshotOptions);
+        snapshotLock = acquireSnapshotLock({
+          ...snapshotOptions,
+          holder: plan.sessionName,
+        });
+        if (snapshotOptions.prepare) {
+          snapshotResume.runSnapshotPrepare(
+            plan.sessionName,
+            snapshotOptions.prepare,
+            runner,
+            progress
+          );
+        }
         const preflight = preflightSnapshot(
           plan.sessionName,
           runner,
-          deps.snapshotOptions
+          snapshotOptions
         );
         plan.message += `\n${preflight.message}`;
         if (record.logPath) {
@@ -636,10 +662,33 @@ async function resumeExecution(store, identifier, deps = {}) {
           );
         }
       }
+      if (plan.mode === ResumeMode.DOCKER_START && opts.commandHandoff) {
+        // `docker start` keeps the creation env; refresh START_ATTEMPT (#230).
+        writeExecutionEnvHandoff(
+          plan.sessionName,
+          require('./execution-env').buildExecutionEnv({
+            executionId: record.uuid,
+            sessionName: plan.sessionName,
+            attempt: attempt.number,
+          }),
+          runner
+        );
+      }
       for (const step of plan.steps) {
         let result;
         try {
-          result = runner(step.command, step.args);
+          result =
+            step.args[0] === 'commit'
+              ? await snapshotResume.commitWithProgress(step, {
+                  ...progress,
+                  runAsync:
+                    deps.runAsync ||
+                    (deps.runner
+                      ? (command, args) =>
+                          Promise.resolve().then(() => runner(command, args))
+                      : snapshotResume.runCommandAsync),
+                })
+              : runner(step.command, step.args);
         } catch (error) {
           result = { success: false, error: error.message };
         }
@@ -661,7 +710,11 @@ async function resumeExecution(store, identifier, deps = {}) {
           containerId = (result.stdout || '').trim() || containerId;
         }
       }
-      if (plan.mode === ResumeMode.DOCKER_SNAPSHOT && deps.removeOriginal) {
+      if (
+        plan.mode === ResumeMode.DOCKER_SNAPSHOT &&
+        deps.removeOriginal &&
+        !(deps.removeOriginalAfter > 0)
+      ) {
         const running = runner(getDockerCommand(), [
           'inspect',
           '-f',
@@ -704,6 +757,7 @@ async function resumeExecution(store, identifier, deps = {}) {
       return {
         success: false,
         error: `Failed to resume ${plan.backend} session "${plan.sessionName}": ${error.message}`,
+        ...(error.exitCode ? { exitCode: error.exitCode } : {}),
       };
     } finally {
       snapshotLock?.release();
@@ -793,6 +847,23 @@ async function resumeExecution(store, identifier, deps = {}) {
     };
   }
 
+  if (
+    plan.mode === ResumeMode.DOCKER_SNAPSHOT &&
+    deps.removeOriginal &&
+    deps.removeOriginalAfter > 0
+  ) {
+    plan.message += `\n${await snapshotResume.removeOriginalAfter(
+      plan,
+      deps.removeOriginalAfter,
+      runner,
+      {
+        logPath: record.logPath,
+        notify: deps.notify || ((line) => process.stderr.write(`${line}\n`)),
+        sleep: deps.sleep,
+      }
+    )}`;
+  }
+
   return {
     success: true,
     output: formatResumeResult(

package/src/lib/execution-store.js

@@ -77,6 +77,8 @@ class ExecutionRecord {
     this.endTime = options.endTime || null;
     this.attempt = options.attempt;
     this.attemptHistory = options.attemptHistory;
+    // UUID of the execution this one continues (`--continues`, issue #231).
+    this.continues = options.continues || undefined;
     // Provenance of `endTime` (issue #170.2). `--status` used to fabricate a
     // finish time with `new Date()` whenever the record had none, which made an
     // observation indistinguishable from a real finish time. One of
@@ -101,6 +103,14 @@ class ExecutionRecord {
       options.containerStartedAt !== undefined
         ? options.containerStartedAt
         : undefined;
+    // `removed` once the container is known to be gone (issue #225), with
+    // when that was observed; `options.containerId` is kept as history.
+    this.containerState =
+      options.containerState !== undefined ? options.containerState : undefined;
+    this.containerRemovedObservedAt =
+      options.containerRemovedObservedAt !== undefined
+        ? options.containerRemovedObservedAt
+        : undefined;
     this.oomKilled =
       options.oomKilled !== undefined ? options.oomKilled : undefined;
     // Query-time hint explaining an opaque exit code (issue #162). Derived from
@@ -164,6 +174,9 @@ class ExecutionRecord {
     if (this.attemptHistory) {
       obj.attemptHistory = this.attemptHistory;
     }
+    if (this.continues) {
+      obj.continues = this.continues;
+    }
     if (this.endTimeSource !== undefined && this.endTimeSource !== null) {
       obj.endTimeSource = this.endTimeSource;
     }
@@ -179,6 +192,15 @@ class ExecutionRecord {
     ) {
       obj.containerStartedAt = this.containerStartedAt;
     }
+    if (this.containerState !== undefined && this.containerState !== null) {
+      obj.containerState = this.containerState;
+    }
+    if (
+      this.containerRemovedObservedAt !== undefined &&
+      this.containerRemovedObservedAt !== null
+    ) {
+      obj.containerRemovedObservedAt = this.containerRemovedObservedAt;
+    }
     if (this.oomKilled !== undefined && this.oomKilled !== null) {
       obj.oomKilled = this.oomKilled;
     }
@@ -489,36 +511,55 @@ class ExecutionStore {
     }
   }
 
+  /**
+   * Record that a finished execution's container no longer exists
+   * (issue #225). Applied under the database lock to the stored record, and
+   * only while it is still finished, so a concurrent resume is never undone.
+   * @param {string} uuid - Execution UUID
+   * @param {string} observedAt - When the removal was observed
+   * @returns {ExecutionRecord|null} The updated record, or null
+   */
+  markContainerRemoved(uuid, observedAt) {
+    const lock = new LockManager(this.lockFilePath);
+    if (!lock.acquire()) {
+      throw new Error('Failed to acquire lock for container state');
+    }
+    try {
+      const records = this.readLinoRecords();
+      const current = records.find((record) => record.uuid === uuid);
+      if (
+        !current ||
+        current.status !== ExecutionStatus.EXECUTED ||
+        current.containerState === 'removed'
+      ) {
+        return null;
+      }
+      current.containerState = 'removed';
+      current.containerRemovedObservedAt = observedAt;
+      this.writeLinoRecords(records);
+      if (this.useLinks) {
+        this.writeLinksRecord(current);
+      }
+      return current;
+    } finally {
+      lock.release();
+    }
+  }
+
   /**
    * Get an execution record by UUID or session name
    * First tries exact UUID match, then the current session name, then any
-   * session name the execution used before it was resumed
+   * session name the execution used before it was resumed, then the display
+   * name and aliases
    * @param {string} identifier - UUID or session name
    * @returns {ExecutionRecord|null}
    */
   get(identifier) {
-    const records = this.readLinoRecords();
-    // First try exact UUID match
-    const byUuid = records.find((r) => r.uuid === identifier);
-    if (byUuid) {
-      return byUuid;
-    }
-    // Fall back to session name lookup (stored in options.sessionName)
-    const bySessionName = records.find(
-      (r) => r.options && r.options.sessionName === identifier
-    );
-    if (bySessionName) {
-      return bySessionName;
-    }
-    // Finally, honor session names this record used before it was resumed, so
-    // one logical session stays addressable across restarts (issue #162).
-    const byPreviousSessionName = records.find(
-      (r) =>
-        r.options &&
-        Array.isArray(r.options.sessionNameHistory) &&
-        r.options.sessionNameHistory.includes(identifier)
+    // Names, display names and aliases resolve too (issues #162, #231).
+    return require('./execution-identity').findRecord(
+      this.readLinoRecords(),
+      identifier
     );
-    return byPreviousSessionName || null;
   }
 
   /**

package/src/lib/isolation.js

@@ -201,7 +201,8 @@ function runScreenWithLogCapture(
   sessionName,
   shellInfo,
   user = null,
-  logPath = null
+  logPath = null,
+  env = null
 ) {
   return _runScreenWithLogCapture(
     command,
@@ -210,7 +211,8 @@ function runScreenWithLogCapture(
     user,
     wrapCommandWithUser,
     isInteractiveShellCommand,
-    logPath
+    logPath,
+    env
   );
 }
 
@@ -241,6 +243,7 @@ function runInScreen(command, options = {}) {
           keepAlive: options.keepAlive,
           logPath: options.logPath,
           wrapCommandWithUser,
+          env: options.executionEnv,
         })
       );
     } else {
@@ -249,7 +252,8 @@ function runInScreen(command, options = {}) {
         sessionName,
         shellInfo,
         options.user,
-        options.logPath
+        options.logPath,
+        options.executionEnv
       );
     }
   } catch (err) {
@@ -813,8 +817,10 @@ function runInDocker(command, options = {}) {
             !containerExistedBeforeLaunch &&
             readDockerContainerStatus(containerName) === 'created';
 
+          let containerRemoved = false;
           if (launchFailed) {
             if (removeDockerContainer(containerName, options.logPath)) {
+              containerRemoved = true;
               message += `\nContainer removed after launch failure.`;
             } else {
               message += `\nWarning: failed to remove container after launch failure.`;
@@ -823,6 +829,7 @@ function runInDocker(command, options = {}) {
             shouldCleanupDockerContainer(cleanupPolicy, exitCode, oomKilled)
           ) {
             if (removeDockerContainer(containerName, options.logPath)) {
+              containerRemoved = true;
               message += `\nContainer removed after completion.${postMortem(true)}`;
             } else {
               message += `\nWarning: failed to remove container automatically.`;
@@ -848,6 +855,7 @@ function runInDocker(command, options = {}) {
             diagnostics: diagnosticFacts,
             message,
             exitCode,
+            containerRemoved,
           });
         });
 
@@ -905,6 +913,20 @@ function runIsolated(backend, command, options = {}) {
     session: options.sessionStack ? options.sessionStack[0] : options.session,
     logPath: options.logPath,
   };
+  // START_* identity (issue #230): docker passes it with `-e`; a bare screen
+  // shell inherits the spawn env; everything else gets an `export` prefix.
+  const identity = require('./execution-env');
+  currentOptions.executionEnv =
+    identity.executionEnvFromOptions(currentOptions);
+  if (
+    backend !== 'docker' &&
+    !(backend === 'screen' && isInteractiveShellCommand(effectiveCommand))
+  ) {
+    effectiveCommand = identity.prefixWithExecutionEnv(
+      effectiveCommand,
+      currentOptions.executionEnv
+    );
+  }
 
   switch (backend) {
     case 'screen':

package/src/lib/launch-identity-options.js

@@ -0,0 +1,81 @@
+/**
+ * Launch options about the identity of a new execution:
+ *   --append-attempt    run as the next attempt of the tracked execution named
+ *                       by --session-id instead of being refused (issue #229)
+ *   --continues <id>    record that this execution continues an earlier one,
+ *                       which `--status` and `--upload-log` follow (issue #231)
+ *
+ * Both only apply when a command is launched, not to the query modes.
+ */
+const { activeQueryModes } = require('./args-parser-queries');
+
+function createLaunchIdentityOptionDefaults() {
+  return {
+    appendAttempt: false,
+    continues: null,
+  };
+}
+
+/**
+ * Parse one launch identity option.
+ * @param {string[]} args - Arguments array
+ * @param {number} index - Current index
+ * @param {object} options - Options object to populate
+ * @returns {number} Number of arguments consumed (0 if not recognized)
+ */
+function parse(args, index, options) {
+  const arg = args[index];
+  if (arg === '--append-attempt') {
+    options.appendAttempt = true;
+    return 1;
+  }
+  if (arg === '--continues') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.continues = args[index + 1];
+      return 2;
+    }
+    throw new Error(
+      'Option --continues requires a UUID or session name argument'
+    );
+  }
+  if (arg.startsWith('--continues=')) {
+    const value = arg.slice('--continues='.length);
+    if (!value) {
+      throw new Error(
+        'Option --continues requires a UUID or session name argument'
+      );
+    }
+    options.continues = value;
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ * Validate the launch identity options.
+ * @param {object} options - Parsed wrapper options
+ * @throws {Error} When the combination is not supported
+ */
+function validate(options) {
+  const used = [
+    ...(options.appendAttempt ? ['--append-attempt'] : []),
+    ...(options.continues !== null && options.continues !== undefined
+      ? ['--continues']
+      : []),
+  ];
+  if (used.length === 0) {
+    return;
+  }
+  if (activeQueryModes(options).length > 0) {
+    throw new Error(`${used[0]} option is only valid when launching a command`);
+  }
+  if (options.appendAttempt && !options.sessionId) {
+    throw new Error('--append-attempt option requires --session-id <uuid>');
+  }
+}
+
+module.exports = {
+  createLaunchIdentityOptionDefaults,
+  parse,
+  validate,
+};