start-command 0.36.0 → 0.37.0

package/src/lib/execution-resume.js

@@ -7,13 +7,13 @@
  * addressing one logical session across restarts.
  *
  * Three strategies, chosen from the probed session state:
- * - DOCKER_START:    the container still exists and the stored command is
- *                    re-run by `docker start` (its original entrypoint).
- * - DOCKER_SNAPSHOT: the container still exists but a new command was given,
- *                    so its filesystem is committed to an image and a derived
- *                    container runs the new command. This avoids
- *                    `docker start -ai`, which would re-run the original
- *                    entrypoint from scratch.
+ * - DOCKER_START:    the container still exists. Newly managed containers
+ *                    accept replacement commands through a small handoff
+ *                    script, then restart in place without a snapshot.
+ * - DOCKER_SNAPSHOT: a legacy container needs a replacement command, or
+ *                    immutable labels need changing. After disk preflight,
+ *                    its filesystem is committed under a host-wide lock and
+ *                    a derived container runs the command.
  * - RELAUNCH:        nothing is left of the session, so the command is
  *                    launched again through the stored isolation options.
  */
@@ -44,6 +44,16 @@ const {
 } = require('./launch-persistence');
 const { SessionState, probeSession } = require('./session-probe');
 const { getDockerNetworks } = require('./docker-network-lifecycle');
+const {
+  writeCommandHandoff,
+  buildCommandHandoffArgs,
+  commandHandoffPath,
+} = require('./docker-command-handoff');
+const {
+  acquireSnapshotLock,
+  preflightSnapshot,
+  SNAPSHOT_IMAGE_LABEL,
+} = require('./docker-snapshot-safety');
 const {
   ResumeAllAction,
   resumeAllExecutions,
@@ -94,6 +104,11 @@ function buildLaunchOptions(record) {
   const opts = record.options || {};
   return {
     ...opts,
+    labels: opts.labels || [],
+    sessionId: record.uuid,
+    rootSession:
+      opts.rootSession || opts.sessionNameHistory?.[0] || opts.sessionName,
+    resumeCount: (Number(opts.resumeCount) || 0) + 1,
     image: opts.image || null,
     session: opts.sessionName,
     detached: true,
@@ -214,12 +229,13 @@ function buildResumePlan(
   const attempt = (Number(opts.resumeCount) || 0) + 1;
 
   if (backend === 'docker' && probe.state === SessionState.STOPPED) {
-    if (!newCommand) {
+    if (!opts.forceSnapshot && (!newCommand || opts.commandHandoff)) {
       return {
         mode: ResumeMode.DOCKER_START,
         backend,
         sessionName,
         command,
+        ...(newCommand ? { handoffCommand: command } : {}),
         attempt,
         steps: [
           {
@@ -228,7 +244,9 @@ function buildResumePlan(
             description: `Start stopped container ${sessionName}`,
           },
         ],
-        message: `Resumed detached docker container: ${sessionName}`,
+        message: newCommand
+          ? `Resumed new command in the same detached docker container: ${sessionName} (no filesystem snapshot)`
+          : `Resumed detached docker container: ${sessionName}`,
       };
     }
 
@@ -261,12 +279,24 @@ function buildResumePlan(
           containerArgs: [
             '--name',
             newSessionName,
+            '--label',
+            `${SNAPSHOT_IMAGE_LABEL}=${snapshotImage}`,
             ...(opts.user ? ['--user', opts.user] : []),
-            ...buildDockerRuntimeArgs({ ...opts, resourceLimits }),
+            ...buildDockerRuntimeArgs({
+              ...opts,
+              resourceLimits,
+              session: newSessionName,
+              containerName: newSessionName,
+              sessionId: record.uuid,
+              rootSession:
+                opts.rootSession || opts.sessionNameHistory?.[0] || sessionName,
+              resumeCount: attempt,
+            }),
             snapshotImage,
-            'sh',
-            '-c',
-            command,
+            ...buildCommandHandoffArgs(
+              ['sh', '-c', command],
+              commandHandoffPath(newSessionName)
+            ),
           ],
           extraNetworks: getDockerNetworks(opts).slice(1),
           newSessionName,
@@ -360,6 +390,10 @@ function applyResumeToRecord(
   archiveAttempt(record);
   record.attempt = attempt;
   const options = { ...(record.options || {}) };
+  options.rootSession =
+    options.rootSession ||
+    options.sessionNameHistory?.[0] ||
+    options.sessionName;
   options.resumeCount = plan.attempt;
   options.resumedAt = attempt.startedAt;
   // A resume is a new deliberate start: launch-time recovery applies again.
@@ -378,6 +412,12 @@ function applyResumeToRecord(
   }
   if (plan.snapshotImage) {
     options.image = plan.snapshotImage;
+    options.snapshotImage = plan.snapshotImage;
+    // Every new detached container, including a snapshot successor, supports handoff.
+    options.commandHandoff = true;
+  }
+  if (plan.mode === ResumeMode.RELAUNCH && plan.backend === 'docker') {
+    options.commandHandoff = true;
   }
   if (containerId) {
     options.containerId = containerId;
@@ -445,12 +485,34 @@ async function resumeExecution(store, identifier, deps = {}) {
   } catch (error) {
     return { success: false, error: error.message };
   }
-  const planningRecord = resources
-    ? {
-        ...record,
-        options: { ...opts, resourceLimits: resources.resourceLimits },
-      }
-    : record;
+  const requestedLabels = deps.resourceOptions?.labels || [];
+  const labels = [...(opts.labels || [])];
+  for (const label of requestedLabels) {
+    const key = label.split('=')[0];
+    const existing = labels.findIndex((value) => value.split('=')[0] === key);
+    if (existing >= 0) {
+      labels[existing] = label;
+    } else {
+      labels.push(label);
+    }
+  }
+  if (requestedLabels.length && opts.isolated !== 'docker') {
+    return {
+      success: false,
+      error: 'Docker labels require a Docker execution when resuming.',
+    };
+  }
+  const labelsChanged =
+    JSON.stringify(labels) !== JSON.stringify(opts.labels || []);
+  const planningRecord = {
+    ...record,
+    options: {
+      ...opts,
+      ...(resources ? { resourceLimits: resources.resourceLimits } : {}),
+      ...(requestedLabels.length ? { labels } : {}),
+      ...(labelsChanged ? { forceSnapshot: true } : {}),
+    },
+  };
   const plan = buildResumePlan(
     planningRecord,
     deps.command || null,
@@ -485,6 +547,9 @@ async function resumeExecution(store, identifier, deps = {}) {
   };
   appendLifecycle(lifecycleRecord, 'resume-started');
   const updated = applyResumeToRecord(record, plan, null, attempt);
+  if (requestedLabels.length) {
+    updated.options.labels = labels;
+  }
   if (resources) {
     updated.options.resolvedLimits = resources.resolvedLimits;
     updated.options.resourceLimitSpecs = resources.resourceLimitSpecs;
@@ -540,26 +605,108 @@ async function resumeExecution(store, identifier, deps = {}) {
     }
     containerId = launchResult.containerId || null;
   } else {
-    for (const step of plan.steps) {
-      let result;
-      try {
-        result = runner(step.command, step.args);
-      } catch (error) {
-        result = { success: false, error: error.message };
+    let snapshotLock;
+    let snapshotCreated = false;
+    let derivedCreated = false;
+    try {
+      if (plan.mode === ResumeMode.DOCKER_SNAPSHOT) {
+        snapshotLock = acquireSnapshotLock(deps.snapshotOptions);
+        const preflight = preflightSnapshot(
+          plan.sessionName,
+          runner,
+          deps.snapshotOptions
+        );
+        plan.message += `\n${preflight.message}`;
+        if (record.logPath) {
+          appendLogFile(record.logPath, `${preflight.message}\n`);
+        }
       }
-      if (!result.success) {
-        rollbackLaunch(store, previous);
-        const detail =
-          (result.stderr || '').trim() ||
-          result.error ||
-          `exit code ${result.status}`;
-        appendLifecycle(lifecycleRecord, 'launch-failed', { error: detail });
-        return {
-          success: false,
-          error: `Failed to resume ${plan.backend} session "${plan.sessionName}": ${detail}`,
-        };
+      if (plan.handoffCommand) {
+        const copied = writeCommandHandoff(
+          plan.sessionName,
+          plan.handoffCommand,
+          runner,
+          opts
+        );
+        if (!copied.success) {
+          throw new Error(
+            (copied.stderr || '').trim() ||
+              copied.error ||
+              'Could not copy replacement command into the stopped container'
+          );
+        }
       }
-      containerId = (result.stdout || '').trim() || containerId;
+      for (const step of plan.steps) {
+        let result;
+        try {
+          result = runner(step.command, step.args);
+        } catch (error) {
+          result = { success: false, error: error.message };
+        }
+        if (!result.success) {
+          const detail =
+            (result.stderr || '').trim() ||
+            result.error ||
+            `exit code ${result.status}`;
+          throw new Error(detail);
+        }
+        if (step.args[0] === 'commit') {
+          snapshotCreated = true;
+        }
+        if (step.args[0] === 'create') {
+          derivedCreated = true;
+        }
+        // commit returns an image ID; cp/update/network commands are not IDs.
+        if (['run', 'create'].includes(step.args[0])) {
+          containerId = (result.stdout || '').trim() || containerId;
+        }
+      }
+      if (plan.mode === ResumeMode.DOCKER_SNAPSHOT && deps.removeOriginal) {
+        const running = runner(getDockerCommand(), [
+          'inspect',
+          '-f',
+          '{{.State.Running}}',
+          plan.newSessionName,
+        ]);
+        if (running.success && String(running.stdout).trim() === 'true') {
+          const removed = runner(getDockerCommand(), ['rm', plan.sessionName]);
+          const note = removed.success
+            ? `Stopped original container removed: ${plan.sessionName}`
+            : `Original container retained: ${(removed.stderr || removed.error || 'docker rm failed').trim()}`;
+          plan.message += `\n${note}`;
+          if (record.logPath) {
+            appendLogFile(record.logPath, `${note}\n`);
+          }
+        } else {
+          plan.message +=
+            '\nOriginal container retained: the snapshot container is not running.';
+        }
+      }
+    } catch (error) {
+      if (derivedCreated) {
+        runner(getDockerCommand(), ['rm', plan.newSessionName]);
+      }
+      if (snapshotCreated) {
+        runner(getDockerCommand(), ['rmi', plan.snapshotImage]);
+      }
+      if (plan.handoffCommand) {
+        // A failed start must not leave a replacement hidden behind the old record.
+        try {
+          writeCommandHandoff(plan.sessionName, previous.command, runner, opts);
+        } catch {
+          /* Next explicit command can still repair the handoff. */
+        }
+      }
+      rollbackLaunch(store, previous);
+      appendLifecycle(lifecycleRecord, 'launch-failed', {
+        error: error.message,
+      });
+      return {
+        success: false,
+        error: `Failed to resume ${plan.backend} session "${plan.sessionName}": ${error.message}`,
+      };
+    } finally {
+      snapshotLock?.release();
     }
 
     const limitsLine = buildResourceLimitsStatusLine(plan.resourceLimits);

package/src/lib/failure-handler.js

@@ -9,6 +9,7 @@ const os = require('os');
 const fs = require('fs');
 const path = require('path');
 const { getTimestamp } = require('./isolation');
+const { sanitizeLogToTemp, StreamingSanitizer } = require('./log-sanitizer');
 
 /**
  * Handle command failure - detect repository, upload log, create issue
@@ -55,7 +56,7 @@ function handleFailure(config, cmdName, fullCommand, exitCode, logPath) {
       console.log('Log upload disabled via START_DISABLE_LOG_UPLOAD');
     }
   } else if (isGhUploadLogAvailable()) {
-    logUrl = uploadLog(logPath);
+    logUrl = uploadLog(logPath, { verbose: config.verbose });
     if (logUrl) {
       console.log(`Log uploaded: ${logUrl}`);
     }
@@ -273,9 +274,11 @@ function isGhUploadLogAvailable() {
  * @param {string} logPath - Path to the log file
  * @returns {string|null} URL of the uploaded log or null
  */
-function uploadLog(logPath) {
+function uploadLog(logPath, options = {}) {
+  let prepared;
   try {
-    const result = execFileSync('gh-upload-log', [logPath, '--public'], {
+    prepared = sanitizeLogToTemp(logPath, { verbose: options.verbose });
+    const result = execFileSync('gh-upload-log', [prepared.path, '--private'], {
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'pipe'],
     });
@@ -293,9 +296,13 @@ function uploadLog(logPath) {
     }
 
     return null;
-  } catch (err) {
-    console.log(`Warning: Log upload failed - ${err.message}`);
+  } catch {
+    console.log('Warning: Log preparation or upload failed; upload blocked.');
     return null;
+  } finally {
+    if (prepared) {
+      prepared.cleanup();
+    }
   }
 }
 
@@ -327,6 +334,9 @@ function canCreateIssue(owner, repo) {
  */
 function createIssue(repoInfo, fullCommand, exitCode, logUrl) {
   try {
+    fullCommand = new StreamingSanitizer()
+      .push(Buffer.from(fullCommand), true)
+      .toString();
     const title = `Command failed with exit code ${exitCode}: ${fullCommand.substring(0, 50)}${fullCommand.length > 50 ? '...' : ''}`;
 
     // Get runtime information

package/src/lib/isolation.js

@@ -565,6 +565,14 @@ function runInDocker(command, options = {}) {
     }
   }
   const containerName = options.session || generateSessionName('docker');
+  const attribution = {
+    ...options,
+    containerName,
+    sessionId:
+      options.sessionId ||
+      options.executionId ||
+      require('crypto').randomUUID(),
+  };
   const containerExistedBeforeLaunch =
     readDockerContainerStatus(containerName) !== null;
   const cleanupPolicy = getDockerContainerCleanupPolicy(options);
@@ -604,7 +612,7 @@ function runInDocker(command, options = {}) {
         dockerArgs.push('--user', options.user);
       }
 
-      dockerArgs.push(...buildDockerRuntimeArgs(options));
+      dockerArgs.push(...buildDockerRuntimeArgs(attribution));
 
       const effectiveCommand = options.keepAlive
         ? `${command}; exec ${shellToUse}`
@@ -614,12 +622,12 @@ function runInDocker(command, options = {}) {
         : [shellToUse];
       const mainCmdArgs = isBareShell
         ? toShellWords(command)
-        : isShellInvocationWithArgs(command)
+        : isShellInvocationWithArgs(effectiveCommand)
           ? buildShellWithArgsCmdArgs(effectiveCommand)
           : [...shellArgs, '-c', effectiveCommand];
       // A recovery command is selected by a marker that `docker cp` drops
       // into the container before it is started again (issue #176).
-      const cmdArgs = options.recoveryCommand
+      const recoveryArgs = options.recoveryCommand
         ? buildRecoverySelectorArgs(mainCmdArgs, {
             shell: shellToUse,
             shellFlag: shellInteractiveFlag,
@@ -628,6 +636,14 @@ function runInDocker(command, options = {}) {
               : options.recoveryCommand,
           })
         : mainCmdArgs;
+      const {
+        buildCommandHandoffArgs,
+        commandHandoffPath,
+      } = require('./docker-command-handoff');
+      const cmdArgs = buildCommandHandoffArgs(
+        recoveryArgs,
+        commandHandoffPath(containerName)
+      );
       dockerArgs.push(options.image, ...cmdArgs);
 
       if (DEBUG) {
@@ -717,7 +733,7 @@ function runInDocker(command, options = {}) {
       if (options.user) {
         dockerArgs.push('--user', options.user);
       }
-      dockerArgs.push(...buildDockerRuntimeArgs(options));
+      dockerArgs.push(...buildDockerRuntimeArgs(attribution));
       if (DEBUG) {
         console.log(`[DEBUG] shell: ${shellToUse}`);
       }

package/src/lib/log-sanitizer.js

@@ -0,0 +1,267 @@
+/** Bounded byte-wise sanitization for logs prepared for publication. */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const BLOCK_SIZE = 64 * 1024;
+const MARKER = '[REDACTED]';
+const SECRET_ENV_NAME =
+  /(?:^|_)(?:TOKEN|(?:API|ACCESS|PRIVATE)?KEY|SECRET|PASSWORD|PASSWD|CREDENTIALS?|AUTH|PAT)(?:_|$)/i;
+
+// Prefixes intentionally match even truncated tokens. Unbounded values retain a
+// continuation state, so a token or header larger than a block cannot leak its
+// suffix. Latin-1 provides a reversible byte mapping, including invalid UTF-8.
+const RULES = [
+  {
+    pattern:
+      /\b[A-Za-z0-9_-]{2,512}\.[A-Za-z0-9_-]{2,512}\.[A-Za-z0-9_-]{0,512}/g,
+    validate: (value) => {
+      try {
+        return (
+          typeof JSON.parse(
+            Buffer.from(value.split('.')[0], 'base64url').toString()
+          ).alg === 'string'
+        );
+      } catch {
+        return false;
+      }
+    },
+    continuation: /[A-Za-z0-9_.-]/,
+  },
+  {
+    pattern: /[A-Za-z0-9_-]{512,}[A-Za-z0-9_.-]*/g,
+    continuation: /[A-Za-z0-9_.-]/,
+  },
+  {
+    pattern: /(?:gh[pousr]_|github_pat_|sk-)[A-Za-z0-9_-]*/g,
+    continuation: /[A-Za-z0-9_-]/,
+  },
+  { pattern: /(?:AKIA|ASIA)[A-Z0-9]{16}/g },
+  { pattern: /eyJ[A-Za-z0-9_.-]*/g, continuation: /[A-Za-z0-9_.-]/ },
+  {
+    pattern: /(?:Proxy-)?Authorization[ \t]{0,32}:[^\r\n]*/gi,
+    continuation: /[^\r\n]/,
+  },
+  {
+    pattern:
+      /(?:AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN)[ \t]{0,32}[=:][ \t]*["']?[^\s"';,]*/g,
+    continuation: /[^\s"';,]/,
+  },
+  {
+    pattern: /(?:https?|git|ssh):\/\/[^\s:/@]{1,256}:[^\s@]*/g,
+    continuation: /[^\s@]/,
+  },
+];
+
+class StreamingSanitizer {
+  constructor(env = process.env) {
+    this.secrets = [
+      ...new Set(
+        Object.entries(env)
+          .filter(
+            ([name, value]) =>
+              SECRET_ENV_NAME.test(name) &&
+              typeof value === 'string' &&
+              value.length
+          )
+          .map(([, value]) => Buffer.from(value).toString('latin1'))
+      ),
+    ].sort((a, b) => b.length - a.length);
+    if (this.secrets.some((value) => value.length > BLOCK_SIZE)) {
+      throw new Error(
+        'Known environment secret is too large for bounded sanitization.'
+      );
+    }
+    this.holdback = this.secrets.reduce(
+      (size, value) => Math.max(size, value.length),
+      2048
+    );
+    this.pending = '';
+    this.continuation = null;
+    this.redactions = 0;
+  }
+
+  get pendingBytes() {
+    return this.pending.length;
+  }
+
+  findMatches(input) {
+    const matches = [];
+    for (const rule of RULES) {
+      rule.pattern.lastIndex = 0;
+      for (
+        let match = rule.pattern.exec(input);
+        match;
+        match = rule.pattern.exec(input)
+      ) {
+        if (!rule.validate || rule.validate(match[0])) {
+          matches.push({
+            index: match.index,
+            end: match.index + match[0].length,
+            continuation: rule.continuation,
+          });
+        }
+      }
+    }
+    for (const secret of this.secrets) {
+      for (
+        let index = input.indexOf(secret);
+        index >= 0;
+        index = input.indexOf(secret, index + 1)
+      ) {
+        matches.push({ index, end: index + secret.length });
+      }
+    }
+    matches.sort((a, b) => a.index - b.index || b.end - a.end);
+    const merged = [];
+    for (const match of matches) {
+      const previous = merged[merged.length - 1];
+      if (previous && match.index <= previous.end) {
+        if (match.end > previous.end) {
+          previous.end = match.end;
+          previous.continuation = match.continuation;
+        } else if (match.end === previous.end && match.continuation) {
+          // Nested tokens must not narrow a containing header/URL's suffix.
+          const retained = previous.continuation;
+          const additional = match.continuation;
+          previous.continuation = retained
+            ? { test: (byte) => retained.test(byte) || additional.test(byte) }
+            : additional;
+        }
+      } else {
+        merged.push({ ...match });
+      }
+    }
+    return merged;
+  }
+
+  push(block, final = false) {
+    let input = this.pending + block.toString('latin1');
+    this.pending = '';
+    if (this.continuation) {
+      let end = 0;
+      while (end < input.length && this.continuation.test(input[end])) {
+        end++;
+      }
+      input = input.slice(end);
+      if (!input.length && !final) {
+        return Buffer.alloc(0);
+      }
+      this.continuation = null;
+    }
+    const safeEnd = final
+      ? input.length
+      : Math.max(0, input.length - this.holdback);
+    let offset = 0;
+    const output = [];
+    for (const match of this.findMatches(input)) {
+      if (match.index >= safeEnd) {
+        break;
+      }
+      output.push(input.slice(offset, match.index), MARKER);
+      this.redactions++;
+      offset = match.end;
+      if (offset === input.length && match.continuation && !final) {
+        this.continuation = match.continuation;
+        break;
+      }
+    }
+    const end = Math.max(offset, safeEnd);
+    output.push(input.slice(offset, end));
+    this.pending = input.slice(end);
+    return Buffer.from(output.join(''), 'latin1');
+  }
+}
+
+/** Returns a private copy plus cleanup; every preparation error blocks upload. */
+function sanitizeLogToTemp(sourcePath, options = {}) {
+  let directory;
+  let source;
+  let destination;
+  let ready = false;
+  let stage = 'environment';
+  try {
+    const sanitizer = new StreamingSanitizer(options.env || process.env);
+    stage = 'source';
+    source = fs.openSync(sourcePath, 'r');
+    if (!fs.fstatSync(source).isFile()) {
+      throw new Error('Source must be a regular file.');
+    }
+    stage = 'private-file';
+    directory = fs.mkdtempSync(path.join(os.tmpdir(), 'start-sanitized-'));
+    fs.chmodSync(directory, 0o700);
+    const target = path.join(directory, 'execution.log');
+    destination = fs.openSync(target, 'wx', 0o600);
+    fs.fchmodSync(destination, 0o600);
+    const buffer = Buffer.alloc(BLOCK_SIZE);
+    let bytes = 0;
+    const write = (output) => {
+      stage = 'write';
+      let offset = 0;
+      while (offset < output.length) {
+        const written = fs.writeSync(
+          destination,
+          output,
+          offset,
+          output.length - offset
+        );
+        if (!written) {
+          throw new Error('No progress writing sanitized log.');
+        }
+        offset += written;
+      }
+    };
+    for (;;) {
+      stage = 'read';
+      const length = fs.readSync(source, buffer, 0, buffer.length, null);
+      if (!length) {
+        break;
+      }
+      bytes += length;
+      stage = 'scan';
+      write(sanitizer.push(buffer.subarray(0, length)));
+    }
+    write(sanitizer.push(Buffer.alloc(0), true));
+    stage = 'sync';
+    fs.fsyncSync(destination);
+    fs.closeSync(destination);
+    destination = undefined;
+    fs.closeSync(source);
+    source = undefined;
+    if (options.verbose) {
+      console.log(
+        `Prepared private sanitized log: ${bytes} bytes scanned, ${sanitizer.redactions} redactions.`
+      );
+    }
+    ready = true;
+    return {
+      path: target,
+      cleanup: () => fs.rmSync(directory, { recursive: true, force: true }),
+    };
+  } catch {
+    if (options.verbose) {
+      console.log(`Log sanitization failed at stage: ${stage}.`);
+    }
+    // Do not echo error messages: paths and exception details can carry secrets.
+    throw new Error('Log sanitization failed; upload blocked.');
+  } finally {
+    for (const fd of [destination, source]) {
+      if (fd !== undefined) {
+        try {
+          fs.closeSync(fd);
+        } catch {
+          /* Best effort after failure. */
+        }
+      }
+    }
+    if (directory && !ready) {
+      try {
+        fs.rmSync(directory, { recursive: true, force: true });
+      } catch {
+        /* Upload remains blocked. */
+      }
+    }
+  }
+}
+
+module.exports = { StreamingSanitizer, sanitizeLogToTemp };