start-command 0.35.4 → 0.37.0

package/src/lib/cpu-penalty-monitor.js

@@ -0,0 +1,226 @@
+/** A watcher-owned monitor. Sidecars avoid writing the store for every sample. */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { initialState, evaluate } = require('./cpu-penalty');
+const { LockManager } = require('./store-lock');
+const { shellQuote } = require('./isolation-log-utils');
+const { cpuCount, cpuUpdateArgs } = require('./docker-resource-limits');
+function statePath(record) {
+  return `${record.logPath}.cpu-penalty.json`;
+}
+function readState(record) {
+  if (!record.options?.cpuPenaltyConfig || !record.logPath) {
+    return null;
+  }
+  try {
+    const state = JSON.parse(fs.readFileSync(statePath(record), 'utf8'));
+    if (
+      state.containerName !== record.options.sessionName ||
+      state.attemptNumber !== (record.attempt?.number || 1)
+    ) {
+      return null;
+    }
+    if (state.phase === 'penalized' && Number.isFinite(state.updatedAt)) {
+      const until = record.endTime ? Date.parse(record.endTime) : Date.now();
+      state.penalizedMs += Math.max(0, until - state.updatedAt);
+      state.updatedAt = Math.max(until, state.updatedAt);
+    }
+    return state;
+  } catch {
+    return null;
+  }
+}
+function publicState(state) {
+  const result = { ...state };
+  delete result.samples;
+  delete result.lastAt;
+  delete result.capacity;
+  return result;
+}
+function run(command, args) {
+  const result = spawnSync(command, args, { encoding: 'utf8' });
+  return { success: result.status === 0, stdout: result.stdout || '' };
+}
+async function monitor(uuid, name, attemptNumber, standalone) {
+  const { ExecutionStore } = require('./execution-store');
+  const store = uuid
+    ? new ExecutionStore(
+        process.env.START_APP_FOLDER
+          ? { appFolder: path.resolve(process.env.START_APP_FOLDER) }
+          : {}
+      )
+    : null;
+  const record = store ? store.get(uuid) : JSON.parse(standalone || 'null');
+  if (
+    !record?.options.cpuPenaltyConfig ||
+    !record.logPath ||
+    record.options.sessionName !== name
+  ) {
+    return;
+  }
+  const config = record.options.cpuPenaltyConfig;
+  const lock = new LockManager(`${statePath(record)}.lock`);
+  if (!lock.acquire(100)) {
+    return;
+  }
+  const docker = require('./docker-cleanup').getDockerCommand();
+  const baseFlags =
+    record.options.baseResourceLimits || record.options.resourceLimits || [];
+  const baseCpus = cpuCount(baseFlags);
+  let state = initialState(baseCpus, Date.now(), readState(record));
+  const interval = Math.min(
+    30000,
+    Math.max(50, Math.min(config.triggerWindowMs, config.releaseWindowMs) / 8)
+  );
+  const publish = () => {
+    const file = statePath(record),
+      tmp = `${file}.${process.pid}.tmp`;
+    try {
+      fs.writeFileSync(
+        tmp,
+        JSON.stringify({
+          ...publicState(state),
+          containerName: name,
+          attemptNumber: Number(attemptNumber),
+          updatedAt: Date.now(),
+        })
+      );
+      fs.renameSync(tmp, file);
+    } finally {
+      try {
+        fs.unlinkSync(tmp);
+      } catch {
+        /* Optional diagnostics are best effort. */
+      }
+    }
+  };
+  const log = (text) => {
+    try {
+      fs.appendFileSync(record.logPath, `${text}\n`);
+    } catch {
+      /* Optional diagnostics are best effort. */
+    }
+  };
+  const started = Date.now();
+  try {
+    publish();
+    while (true) {
+      const current = store ? store.get(uuid) : record;
+      if (
+        !current ||
+        current.options.sessionName !== name ||
+        (current.attempt?.number || 1) !== Number(attemptNumber)
+      ) {
+        break;
+      }
+      const live = run(docker, ['inspect', '-f', '{{.State.Running}}', name]);
+      if (live.success && live.stdout.trim() === 'false') {
+        break;
+      }
+      if (!live.success && Date.now() - started > 30000) {
+        break;
+      }
+      const info = run(docker, ['info', '--format', '{{json .}}']);
+      const stats = run(docker, [
+        'stats',
+        '--no-stream',
+        '--format',
+        '{{json .}}',
+      ]);
+      let daemonCpus = NaN,
+        cores = NaN;
+      try {
+        if (info.success) {
+          daemonCpus = JSON.parse(info.stdout).NCPU;
+        }
+        if (stats.success) {
+          const row = stats.stdout
+            .trim()
+            .split('\n')
+            .map((s) => JSON.parse(s))
+            .find((s) => s.Name === name);
+          if (row && /^\d+(?:\.\d+)?%$/.test(row.CPUPerc)) {
+            cores = Number(row.CPUPerc.slice(0, -1)) / 100;
+          }
+        }
+      } catch {
+        /* Optional diagnostics are best effort. */
+      }
+      const decision = evaluate(
+        state,
+        {
+          now: Date.now(),
+          cores,
+          daemonCpus,
+          maxGapMs: Math.max(5000, interval * 3),
+        },
+        config
+      );
+      if (decision.action) {
+        const action = decision.action;
+        const update = run(docker, [
+          'update',
+          ...cpuUpdateArgs(baseFlags, action.cpus),
+          name,
+        ]);
+        if (update.success) {
+          state = decision.state;
+          log(
+            `[start] CPU penalty ${action.kind === 'apply' ? 'applied' : 'lifted'}: ${action.cpus} CPUs (${action.average === null || action.average === undefined ? 'capacity changed' : `${action.average.toFixed(2)} of ${action.capacity} CPUs`})`
+          );
+        } else {
+          state = {
+            ...decision.state,
+            phase: state.phase,
+            since: state.since,
+            limitCpus: state.limitCpus,
+            penaltyCount: state.penaltyCount,
+            samples: [],
+          };
+        }
+      } else {
+        state = decision.state;
+      }
+      publish();
+      await new Promise((resolve) => globalThis.setTimeout(resolve, interval));
+    }
+  } finally {
+    lock.release();
+  }
+}
+function startSnippet(uuid, name, attempt = 1, options = null) {
+  const standalone =
+    !uuid && options?.cpuPenaltyConfig && options.logPath
+      ? JSON.stringify({
+          logPath: options.logPath,
+          options: {
+            sessionName: name,
+            cpuPenaltyConfig: options.cpuPenaltyConfig,
+            baseResourceLimits: options.resourceLimits,
+          },
+        })
+      : null;
+  if (!uuid && !standalone) {
+    return '';
+  }
+  return `${shellQuote(process.execPath)} ${shellQuote(__filename)} ${shellQuote(uuid || '')} ${shellQuote(name)} ${Number(attempt)} ${shellQuote(standalone || '')} >/dev/null 2>&1 & __start_cpu_monitor=$!`;
+}
+function stopSnippet() {
+  return 'if [ -n "$__start_cpu_monitor" ]; then kill "$__start_cpu_monitor" 2>/dev/null; wait "$__start_cpu_monitor" 2>/dev/null; fi';
+}
+module.exports = {
+  statePath,
+  readState,
+  publicState,
+  monitor,
+  startSnippet,
+  stopSnippet,
+};
+if (require.main === module) {
+  monitor(...process.argv.slice(2)).catch((error) => {
+    if (process.env.START_DEBUG === '1') {
+      console.error(`[DEBUG] CPU monitor: ${error.stack}`);
+    }
+  });
+}

package/src/lib/cpu-penalty.js

@@ -0,0 +1,175 @@
+/** Docker CPU hysteresis with timestamp-weighted, fully covered windows. */
+const DEFAULTS = {
+  cpus: 2,
+  trigger: 95,
+  triggerWindowMs: 900000,
+  release: 65,
+  releaseWindowMs: 900000,
+};
+const FIELDS = {
+  '--cpu-penalty-cpus': 'cpus',
+  '--cpu-penalty-trigger': 'trigger',
+  '--cpu-penalty-trigger-window': 'triggerWindowMs',
+  '--cpu-penalty-release': 'release',
+  '--cpu-penalty-release-window': 'releaseWindowMs',
+};
+function duration(value) {
+  const m = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/.exec(value);
+  const n = m
+    ? Number(m[1]) * { ms: 1, s: 1000, m: 60000, h: 3600000 }[m[2]]
+    : NaN;
+  if (!Number.isSafeInteger(n) || n <= 0) {
+    throw Error(`Invalid CPU penalty duration: ${value}`);
+  }
+  return n;
+}
+function parse(args, index, options) {
+  const [flag, inline] = args[index].split('=', 2);
+  if (flag === '--cpu-penalty') {
+    if (inline !== undefined) {
+      throw Error('--cpu-penalty does not take a value');
+    }
+    options.cpuPenalty = true;
+    return 1;
+  }
+  const field = FIELDS[flag];
+  if (!field) {
+    return 0;
+  }
+  const value = inline ?? args[index + 1];
+  if (!value) {
+    throw Error(`${flag} requires a value`);
+  }
+  const number = field.endsWith('Ms')
+    ? duration(value)
+    : Number(field === 'cpus' ? value : value.replace(/%$/, ''));
+  if (
+    !(number > 0) ||
+    !Number.isFinite(number) ||
+    (field !== 'cpus' && !field.endsWith('Ms') && number > 100)
+  ) {
+    throw Error(`Invalid ${flag}: ${value}`);
+  }
+  options.cpuPenaltyConfig = {
+    ...DEFAULTS,
+    ...options.cpuPenaltyConfig,
+    [field]: number,
+  };
+  return inline === undefined ? 2 : 1;
+}
+function validate(options) {
+  if (!options.cpuPenalty && !options.cpuPenaltyConfig) {
+    return;
+  }
+  if (!options.cpuPenalty) {
+    throw Error('CPU penalty settings require --cpu-penalty');
+  }
+  if (!(options.isolatedStack || [options.isolated]).includes('docker')) {
+    throw Error('--cpu-penalty requires Docker isolation');
+  }
+  options.cpuPenaltyConfig = { ...DEFAULTS, ...options.cpuPenaltyConfig };
+}
+function initialState(baseCpus = null, now = Date.now(), saved = null) {
+  return {
+    phase: saved?.phase === 'penalized' ? 'penalized' : 'observing',
+    since: saved?.phase === 'penalized' ? saved.since : now,
+    limitCpus: saved?.phase === 'penalized' ? saved.limitCpus : baseCpus,
+    baseCpus,
+    penaltyCount: saved?.penaltyCount || 0,
+    penalizedMs: saved?.penalizedMs || 0,
+    samples: [],
+    lastAt: now,
+    capacity: null,
+  };
+}
+function average(samples, now, window) {
+  const start = now - window;
+  if (
+    samples.length < 2 ||
+    samples[0].at > start ||
+    samples.at(-1).at !== now
+  ) {
+    return null;
+  }
+  let weighted = 0;
+  for (let i = 1; i < samples.length; i++) {
+    const left = Math.max(start, samples[i - 1].at),
+      right = samples[i].at;
+    if (right > left) {
+      weighted += (right - left) * samples[i - 1].cores;
+    }
+  }
+  return weighted / window;
+}
+function evaluate(
+  state,
+  { now, cores, daemonCpus, maxGapMs },
+  config = DEFAULTS
+) {
+  const s = { ...state, samples: [...state.samples] };
+  if (s.phase === 'penalized') {
+    s.penalizedMs += Math.max(0, now - s.lastAt);
+  }
+  s.lastAt = now;
+  const capacity = Number.isFinite(daemonCpus)
+    ? Math.min(s.baseCpus || Infinity, daemonCpus)
+    : NaN;
+  if (
+    !(cores >= 0) ||
+    !Number.isFinite(cores) ||
+    !(capacity > 0) ||
+    now <= (s.samples.at(-1)?.at ?? -Infinity) ||
+    (s.samples.length && now - s.samples.at(-1).at > maxGapMs) ||
+    s.capacity !== capacity
+  ) {
+    s.samples = [];
+  }
+  s.capacity = capacity;
+  if (!(cores >= 0) || !Number.isFinite(cores) || !(capacity > 0)) {
+    return { state: s, action: null };
+  }
+  s.samples.push({ at: now, cores });
+  const window =
+    s.phase === 'penalized' ? config.releaseWindowMs : config.triggerWindowMs;
+  while (s.samples.length > 2 && s.samples[1].at <= now - window) {
+    s.samples.shift();
+  }
+  const avg = average(s.samples, now, window);
+  let action = null;
+  if (
+    s.phase === 'observing' &&
+    config.cpus < capacity &&
+    avg !== null &&
+    avg >= (config.trigger / 100) * capacity
+  ) {
+    action = { kind: 'apply', cpus: config.cpus, average: avg, capacity };
+    s.phase = 'penalized';
+    s.since = now;
+    s.limitCpus = config.cpus;
+    s.penaltyCount++;
+  } else if (
+    s.phase === 'penalized' &&
+    (config.cpus >= capacity ||
+      (now - s.since >= config.releaseWindowMs &&
+        avg !== null &&
+        avg < (config.release / 100) * config.cpus))
+  ) {
+    action = { kind: 'lift', cpus: capacity, average: avg, capacity };
+    s.phase = 'observing';
+    s.since = now;
+    s.limitCpus = capacity;
+  }
+  if (action) {
+    s.samples = [];
+  }
+  return { state: s, action };
+}
+module.exports = {
+  DEFAULTS,
+  parse,
+  validate,
+  duration,
+  initialState,
+  average,
+  evaluate,
+};

package/src/lib/detached-finalize.js

@@ -146,6 +146,21 @@ function finalizeDetachedExecution(options = {}) {
     record.cgroupMemory = cgroupMemory;
   }
 
+  const evidence = require('./exit-evidence');
+  const logged = evidence.fromLog(
+    record.logPath
+      ? require('./execution-attempt').readAttemptLogTail(record, 65536)
+      : null
+  );
+  record.options.exitEvidence = {
+    daemonRestart: logged.daemonRestart,
+    mainOom:
+      !logged.daemonRestart &&
+      (logged.mainOom ||
+        (evidence.recentOomDelta(options.cgroupMemory, options.finishedAt) &&
+          record.oomKilled === true &&
+          (record.exitCode === 137 || record.exitCode < 0))),
+  };
   const exitReason =
     resolveReason(record) || (finishedAt ? null : WATCHER_LOST_CONTAINER);
   if (exitReason) {
@@ -197,6 +212,7 @@ function resolveReason(record) {
       logTail,
       oomKilled: record.oomKilled,
       cgroupMemory: record.cgroupMemory,
+      exitEvidence: record.options?.exitEvidence,
     });
   } catch {
     return null;

package/src/lib/docker-cleanup.js

@@ -83,7 +83,7 @@ function getDockerContainerCleanupInstructions(containerName) {
     `Container kept for investigation: ${containerName}`,
     `Re-enter while running: $ --attach ${containerName}`,
     `Continue the stored command: $ --resume ${containerName}`,
-    `Run another command in the same container: $ --resume ${containerName} -- <command>`,
+    `Run another command (legacy containers snapshot the filesystem into a new container): $ --resume ${containerName} -- <command>`,
     `Remove when done: docker rm -f ${containerName}`,
   ].join('\n');
 }
@@ -275,10 +275,13 @@ function buildAttachedDockerKeptMessage({
   oomKilled,
   logPath,
 }) {
+  const logTail = logPath
+    ? readLogTail(logPath, FATAL_MARKER_TAIL_BYTES)
+    : null;
   let message;
   if (oomKilled !== true) {
     message = `\nContainer kept because the command failed.`;
-  } else if (isOomKillOfCommand({ exitCode, oomKilled })) {
+  } else if (isOomKillOfCommand({ exitCode, oomKilled, logTail })) {
     message = `\nContainer kept because Docker reports it was OOM-killed.`;
   } else {
     // The flag is container-wide (#180): a child was OOM-killed, the command
@@ -287,7 +290,7 @@ function buildAttachedDockerKeptMessage({
   }
   const memory = resolveMemoryExhaustion({
     exitCode,
-    logTail: logPath ? readLogTail(logPath, FATAL_MARKER_TAIL_BYTES) : null,
+    logTail,
     oomKilled,
   });
   if (memory) {
@@ -303,7 +306,7 @@ function buildDockerKeptLogSnippet(containerName, quotedLogPath) {
     `printf '\\nContainer kept for investigation: %s\\nReason: %s\\n` +
     `Re-enter while running: $ --attach %s\\n` +
     `Continue the stored command: $ --resume %s\\n` +
-    `Run another command in the same container: $ --resume %s -- <command>\\n` +
+    `Run another command (legacy containers snapshot the filesystem into a new container): $ --resume %s -- <command>\\n` +
     `Remove when done: docker rm -f %s\\n' ` +
     `${quotedName} "$__start_command_reason" ` +
     `${quotedName} ${quotedName} ${quotedName} ${quotedName} >> ${quotedLogPath}`
@@ -358,9 +361,24 @@ function buildDetachedDockerCompletionScript(
   watcherOptions = {}
 ) {
   const quotedName = shellQuote(containerName);
+  const imageCleanup =
+    require('./docker-snapshot-safety').snapshotImageCleanupSnippet(
+      containerName,
+      logPath ? `>> ${shellQuote(logPath)} 2>&1` : '>/dev/null 2>&1'
+    );
   // The container's cgroup disappears with it, so its memory counters are
   // sampled while it runs (issue #182).
+  const cpuMonitor = require('./cpu-penalty-monitor');
   const parts = [buildCgroupSamplerStartSnippet(containerName)];
+  const cpuStart = cpuMonitor.startSnippet(
+    executionId,
+    containerName,
+    watcherOptions.attemptNumber || 1,
+    watcherOptions.cpuOptions
+  );
+  if (cpuStart) {
+    parts.push(cpuStart);
+  }
   // Everything that assumes the container has exited: cleanup, footer and
   // finalization. Guarded as a whole by `.State.Running` below.
   const exited = [];
@@ -376,7 +394,7 @@ function buildDetachedDockerCompletionScript(
       quotedLogPath
     );
     const memory = buildCgroupMemoryLogSnippet(quotedLogPath);
-    const remove = `docker rm -f ${quotedName} >> ${quotedLogPath} 2>&1 || true; ${removalNote}; ${memory}`;
+    const remove = `${imageCleanup.capture}; if docker rm -f ${quotedName} >> ${quotedLogPath} 2>&1; then ${imageCleanup.remove}; fi; ${removalNote}; ${memory}`;
     const keep = `${postMortem}; ${memory}; ${buildDockerKeptLogSnippet(containerName, quotedLogPath)}`;
 
     const since = watcherOptions.since
@@ -393,8 +411,15 @@ function buildDetachedDockerCompletionScript(
       );
     }
     parts.push(buildDockerWaitForExitSnippet(containerName, quotedLogPath));
+    parts.push(cpuMonitor.stopSnippet());
     parts.push(buildCgroupSamplerStopSnippet());
     parts.push(buildDockerStateSnippet(containerName));
+    parts.push(
+      require('./exit-evidence').buildExitEvidenceSnippet(
+        containerName,
+        quotedLogPath
+      )
+    );
     if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS) {
       exited.push(remove);
     } else if (
@@ -414,16 +439,19 @@ function buildDetachedDockerCompletionScript(
   } else {
     parts.push(`docker wait ${quotedName} >/dev/null 2>&1`);
     parts.push(buildDockerWaitForExitSnippet(containerName));
+    parts.push(cpuMonitor.stopSnippet());
     parts.push(buildCgroupSamplerStopSnippet());
     parts.push(buildDockerStateSnippet(containerName));
     if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS) {
-      exited.push(`docker rm -f ${quotedName} >/dev/null 2>&1 || true`);
+      exited.push(
+        `${imageCleanup.capture}; if docker rm -f ${quotedName} >/dev/null 2>&1; then ${imageCleanup.remove}; fi`
+      );
     } else if (
       policy === DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT ||
       policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL
     ) {
       exited.push(
-        `if ${buildSuccessfulNonOomCondition()}; then docker rm -f ${quotedName} >/dev/null 2>&1 || true; fi`
+        `if ${buildSuccessfulNonOomCondition()}; then ${imageCleanup.capture}; if docker rm -f ${quotedName} >/dev/null 2>&1; then ${imageCleanup.remove}; fi; fi`
       );
     }
   }

package/src/lib/docker-command-handoff.js

@@ -0,0 +1,75 @@
+/** Copy only a command script into a stopped container, never its writable layer. */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { shellQuote } = require('./isolation-log-utils');
+
+function commandHandoffPath(sessionName) {
+  return `/.start-command-resume-${String(sessionName).replace(/[^A-Za-z0-9_.-]/g, '_')}`;
+}
+
+function buildCommandHandoffArgs(mainArgs, markerPath) {
+  return [
+    'sh',
+    '-c',
+    'p=$1; shift; if [ -f "$p" ]; then exec sh "$p"; fi; exec "$@"',
+    'start-command-handoff',
+    markerPath,
+    ...mainArgs,
+  ];
+}
+
+function buildCommandHandoffScript(command, options = {}) {
+  const {
+    isInteractiveShellCommand,
+    isShellInvocationWithArgs,
+    buildShellWithArgsCmdArgs,
+    toShellWords,
+  } = require('./shell-utils');
+  if (
+    !options.keepAlive &&
+    (isInteractiveShellCommand(command) || isShellInvocationWithArgs(command))
+  ) {
+    const args = isShellInvocationWithArgs(command)
+      ? buildShellWithArgsCmdArgs(command)
+      : toShellWords(command);
+    return `exec ${args.map(shellQuote).join(' ')}\n`;
+  }
+  if (!options.shell || options.shell === 'auto') {
+    const effective = options.keepAlive
+      ? `${command}; exec "$__START_COMMAND_HANDOFF_SHELL"`
+      : command;
+    return `__START_COMMAND_HANDOFF_SHELL=$(command -v bash || command -v zsh || command -v sh); export __START_COMMAND_HANDOFF_SHELL\ncase "$__START_COMMAND_HANDOFF_SHELL" in */bash|bash|*/zsh|zsh) exec "$__START_COMMAND_HANDOFF_SHELL" -i -c ${shellQuote(effective)};; *) exec "$__START_COMMAND_HANDOFF_SHELL" -c ${shellQuote(effective)};; esac\n`;
+  }
+  const shell = options.shell;
+  const interactive = /(?:^|\/)(?:bash|zsh)$/.test(shell) ? ' -i' : '';
+  const effective = options.keepAlive
+    ? `${command}; exec ${shellQuote(shell)}`
+    : command;
+  return `exec ${shellQuote(shell)}${interactive} -c ${shellQuote(effective)}\n`;
+}
+
+function writeCommandHandoff(containerName, command, runner, options = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'start-handoff-'));
+  const file = path.join(dir, 'command');
+  try {
+    fs.writeFileSync(file, buildCommandHandoffScript(command, options), {
+      mode: 0o644,
+    });
+    fs.chmodSync(file, 0o644);
+    return runner(require('./docker-cleanup').getDockerCommand(), [
+      'cp',
+      file,
+      `${containerName}:${commandHandoffPath(containerName)}`,
+    ]);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+module.exports = {
+  commandHandoffPath,
+  buildCommandHandoffArgs,
+  buildCommandHandoffScript,
+  writeCommandHandoff,
+};

package/src/lib/docker-labels.js

@@ -0,0 +1,33 @@
+/** Docker attribution shared by initial launches and snapshot resumes (#199). */
+function validateLabel(label) {
+  if (typeof label !== 'string' || !/^[^=\s]+=[\s\S]*$/.test(label)) {
+    throw new Error('--label requires KEY=VALUE with a nonempty key');
+  }
+  if (label.startsWith('start-command.')) {
+    throw new Error(
+      'start-command.* labels are reserved for execution attribution'
+    );
+  }
+}
+
+function dockerLabels(options = {}) {
+  const labels = [...(options.labels || [])];
+  const session = options.containerName || options.session;
+  if (session) {
+    const inferredRoot =
+      Number(options.resumeCount) > 0
+        ? session.replace(/(?:-resume-\d+)+$/, '')
+        : session;
+    labels.push(`start-command.session=${session}`);
+    labels.push(
+      `start-command.root-session=${options.rootSession || inferredRoot}`
+    );
+    labels.push(`start-command.resume-count=${options.resumeCount || 0}`);
+  }
+  if (options.sessionId || options.uuid) {
+    labels.push(`start-command.uuid=${options.sessionId || options.uuid}`);
+  }
+  return labels;
+}
+
+module.exports = { validateLabel, dockerLabels };

package/src/lib/docker-resource-limits.js

@@ -200,8 +200,36 @@ function buildResourceLimitsStatusLine(value) {
     : null;
 }
 
+/** Preserve Docker's CPU representation: an existing quota cannot become NanoCPUs in place. */
+function cpuCount(limits) {
+  const get = (prefix) =>
+    positive(limits.find((s) => s.startsWith(prefix))?.slice(prefix.length));
+  return (
+    get('--cpus=') ||
+    (get('--cpu-quota=')
+      ? get('--cpu-quota=') / (get('--cpu-period=') || 100000)
+      : null)
+  );
+}
+function cpuUpdateArgs(limits, cpus) {
+  return !limits.some((s) => s.startsWith('--cpus=')) &&
+    limits.some((s) => /^--cpu-(quota|period)=/.test(s))
+    ? ['--cpu-period=100000', `--cpu-quota=${Math.ceil(cpus * 100000)}`]
+    : ['--cpus', String(cpus)];
+}
+function withCpuLimit(limits, cpus) {
+  const args = cpuUpdateArgs(limits, cpus);
+  return [
+    ...limits.filter((s) => !/^--(?:cpus|cpu-quota|cpu-period)=/.test(s)),
+    ...(args[0] === '--cpus' ? [`--cpus=${args[1]}`] : args),
+  ];
+}
+
 module.exports = {
   DEFAULT_SHM_SIZE,
+  cpuCount,
+  cpuUpdateArgs,
+  withCpuLimit,
   buildResourceLimitsStatusLine,
   formatDockerBytes,
   formatDockerCpus,