start-command 0.35.4 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # start-command
 
+## 0.36.0
+
+### Minor Changes
+
+- dbf7ba6: Add Docker launch/recovery resource limits with daemon percentages and random ranges, opt-in delayed CPU penalties, and remote/DinD memory diagnostics. Reserve launches before side effects, atomically publish store locks and database writes, and require exit-time evidence for OOM verdicts while recognizing attributed Docker daemon restarts.
+
 ## 0.35.4
 
 ### Patch Changes

package/README.md

@@ -56,3 +56,13 @@ GitHub Releases. The release title carries the `[JavaScript]` prefix, e.g.
 ## License
 
 Released into the public domain under the [Unlicense](../LICENSE).
+
+### Docker resource and recovery controls
+
+Launch with `--memory 64m`, `--memory-swap 64m` and `--cpus 1`, or use daemon
+percentages and uniform ranges such as `--memory '70%-80%'`. Memory-swap defaults
+to memory. `--cpu-penalty` enables delayed caps and reports state through status.
+Manual `--resume <id> --memory 128m` updates before starting;
+`--on-kill-resume-memory` changes memory only after a fresh qualifying OOM.
+See the [full resource and recovery guide](../README.md#docker-launch-limits-recovery-limits-and-cpu-penalty)
+and [incident research](../docs/case-studies/issue-195/README.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.35.4",
+  "version": "0.36.0",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {

package/src/bin/cli.js

@@ -241,6 +241,18 @@ const sessionId = wrapperOptions.sessionId || generateUUID();
     process.exit(queryExitCode === null ? 0 : queryExitCode);
   }
 
+  if (wrapperOptions.isolated === 'docker') {
+    const {
+      resolveResourceOptions,
+    } = require('../lib/docker-resource-options');
+    Object.assign(
+      wrapperOptions,
+      resolveResourceOptions(
+        wrapperOptions,
+        require('../lib/execution-control').runCommand
+      )
+    );
+  }
   // Check if running in isolation mode or with user isolation
   if (hasIsolation(wrapperOptions) || wrapperOptions.user) {
     await runWithIsolation(
@@ -419,14 +431,21 @@ async function runWithIsolation(
   // Save initial execution record and set global reference for signal cleanup
   if (executionRecord && store) {
     currentExecutionRecord = executionRecord;
+    require('../lib/launch-owner').markLaunch(executionRecord);
     try {
       store.save(executionRecord);
     } catch (err) {
-      if (config.verbose) {
-        console.error(
-          `[Tracking] Warning: Could not save execution record: ${err.message}`
-        );
-      }
+      console.error(
+        JSON.stringify({
+          code: 'LAUNCH_RESERVATION_FAILED',
+          uuid: executionRecord.uuid,
+          containerName: sessionName,
+          error: err.message,
+        })
+      );
+      currentExecutionRecord = null;
+      process.exitCode = 1;
+      return 1;
     }
   }
 
@@ -458,6 +477,7 @@ async function runWithIsolation(
     // Note: Isolation environments currently use native spawn/execSync
     // Future: Add command-stream support with raw() function for multiplexers
     result = await runIsolated(environment, cmd, {
+      ...options,
       session: sessionName,
       image: effectiveImage,
       endpoint: options.endpoint,
@@ -502,6 +522,11 @@ async function runWithIsolation(
 
   // Update execution record: detached keeps "executing" (resolved at query time)
   if (executionRecord && store) {
+    executionRecord.options.launchPending = false;
+    if (result.diagnostics) {
+      executionRecord.cgroupMemory = result.diagnostics.cgroupMemory;
+      executionRecord.options.exitEvidence = result.diagnostics.exitEvidence;
+    }
     if (result.containerId) {
       executionRecord.options.containerId = result.containerId;
     }
@@ -515,11 +540,22 @@ async function runWithIsolation(
           : executionRecord
       );
     } catch (err) {
-      if (config.verbose) {
+      if (environment === 'docker' && mode === 'detached' && result.success) {
         console.error(
-          `[Tracking] Warning: Could not update execution record: ${err.message}`
+          require('../lib/launch-persistence').failLaunchedPersistence(
+            store,
+            executionRecord,
+            require('../lib/execution-control').runCommand,
+            err
+          )
         );
+        currentExecutionRecord = null;
+        process.exitCode = 1;
+        return 1;
       }
+      console.error(
+        `[Tracking] Could not update execution record: ${err.message}`
+      );
     }
     currentExecutionRecord = null;
   }

package/src/lib/args-parser.js

@@ -44,6 +44,8 @@
 const { getDefaultDockerImage } = require('./docker-utils');
 const dockerNetworkOptions = require('./docker-network-options');
 const dockerRecoveryOptions = require('./docker-recovery-options');
+const cpuPenalty = require('./cpu-penalty');
+const dockerResourceOptions = require('./docker-resource-options');
 const { parseSequence, isSequence } = require('./sequence-parser');
 const { buildCommandString } = require('./shell-utils');
 const {
@@ -414,6 +416,14 @@ function parseOption(args, index, options) {
     return networkOption;
   }
 
+  const cpuConsumed = cpuPenalty.parse(args, index, options);
+  if (cpuConsumed) {
+    return cpuConsumed;
+  }
+  const resourceOption = dockerResourceOptions.parse(args, index, options);
+  if (resourceOption) {
+    return resourceOption;
+  }
   const recoveryOption = dockerRecoveryOptions.parse(args, index, options);
   if (recoveryOption) {
     return recoveryOption;
@@ -756,6 +766,8 @@ function validateOptions(options) {
   }
 
   dockerRecoveryOptions.validate(options);
+  dockerResourceOptions.validate(options);
+  cpuPenalty.validate(options);
 
   // Session name is only valid with isolation
   if (options.session && !options.isolated) {

package/src/lib/atomic-write.js

@@ -0,0 +1,34 @@
+/** Keep the previous database intact when a write fails, including ENOSPC. */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+function atomicWrite(file, content) {
+  const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, content, { flag: 'wx' });
+    const handle = fs.openSync(temporary, 'r+');
+    try {
+      fs.fsyncSync(handle);
+    } finally {
+      fs.closeSync(handle);
+    }
+    fs.renameSync(temporary, file);
+    if (process.platform !== 'win32') {
+      const directory = fs.openSync(path.dirname(file), 'r');
+      try {
+        fs.fsyncSync(directory);
+      } finally {
+        fs.closeSync(directory);
+      }
+    }
+  } finally {
+    try {
+      fs.unlinkSync(temporary);
+    } catch {
+      /* Renamed or never created. */
+    }
+  }
+}
+
+module.exports = { atomicWrite };

package/src/lib/attached-diagnostics.js

@@ -0,0 +1,90 @@
+/** Keep the same memory and CPU monitors alive during an attached Docker run. */
+const { spawn, spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const cgroup = require('./cgroup-memory');
+const cpu = require('./cpu-penalty-monitor');
+const evidence = require('./exit-evidence');
+const { shellQuote } = require('./isolation-log-utils');
+
+function startAttachedDiagnostics(name, options) {
+  const file = path.join(os.tmpdir(), `start-attached-${crypto.randomUUID()}`);
+  let worker;
+  {
+    const script = [
+      cgroup.buildCgroupSamplerStartSnippet(name),
+      cpu.startSnippet(options.executionId, name, 1, options),
+      'read __start_stop',
+      cgroup.buildCgroupSamplerStopSnippet(),
+      cpu.stopSnippet(),
+      `printf '%s' "$__start_command_cgroup" > ${shellQuote(file)}`,
+      `printf '%s' "$__start_command_memory_unavailable" > ${shellQuote(`${file}.reason`)}`,
+    ]
+      .filter(Boolean)
+      .join('; ');
+    worker = spawn('sh', ['-c', script], {
+      stdio: ['pipe', 'ignore', 'ignore'],
+    });
+    worker.on('error', () => {});
+    // Subscribe before a fast command finishes, including shell startup failure.
+    worker.done = new Promise((resolve) => worker.once('close', resolve));
+    worker.stdin.on('error', () => {});
+  }
+  return {
+    async finish(state) {
+      if (worker) {
+        worker.stdin.end();
+        await worker.done;
+      }
+      let sample = '';
+      let unavailable = 'sampler could not start (sh unavailable)';
+      try {
+        sample = fs.readFileSync(file, 'utf8');
+        unavailable =
+          fs.readFileSync(`${file}.reason`, 'utf8') ||
+          'sampler stopped before a reading';
+      } catch {
+        /* Optional diagnostics are best effort. */
+      }
+      try {
+        fs.unlinkSync(file);
+        fs.unlinkSync(`${file}.reason`);
+      } catch {
+        /* Optional diagnostics are best effort. */
+      }
+      const docker = require('./docker-cleanup').getDockerCommand();
+      const limit = spawnSync(
+        docker,
+        ['inspect', '-f', '{{.HostConfig.Memory}}', name],
+        { encoding: 'utf8' }
+      );
+      const line = evidence.collectExitEvidence({
+        containerName: name,
+        sample,
+        finishedAt: state?.finishedAt,
+        exitCode: state?.exitCode,
+        oomKilled: state?.oomKilled,
+      });
+      if (options.logPath) {
+        try {
+          fs.appendFileSync(
+            options.logPath,
+            `${cgroup.formatCgroupMemoryLogLine(sample, limit.status === 0 ? limit.stdout.trim() : 'unknown', unavailable)}\n${line}\n`
+          );
+        } catch (error) {
+          if (process.env.START_DEBUG === '1') {
+            console.error(`[DEBUG] Attached diagnostics: ${error.message}`);
+          }
+        }
+      }
+      return {
+        cgroupMemory: cgroup.parseCgroupMemorySample(sample),
+        exitEvidence: evidence.fromLog(line),
+      };
+    },
+  };
+}
+
+module.exports = { startAttachedDiagnostics };

package/src/lib/cgroup-memory.js

@@ -67,6 +67,7 @@ function buildCgroupFunctionsSnippet() {
     '__start_command_cgroup_read() { __scr_events=$(cat "$1/memory.events" 2>/dev/null) || return 1; ' +
       "__scr_oom=$(printf '%s\\n' \"$__scr_events\" | sed -n 's/^oom //p'); " +
       "__scr_kill=$(printf '%s\\n' \"$__scr_events\" | sed -n 's/^oom_kill //p'); " +
+      'case "$__scr_oom:$__scr_kill" in *[!0-9:]*|:*|*:) return 1;; esac; ' +
       '__scr_max=$(cat "$1/memory.max" 2>/dev/null); __scr_peak=$(cat "$1/memory.peak" 2>/dev/null); ' +
       'printf \'%s %s %s %s %s\\n\' "${__scr_max:--}" "${__scr_peak:--}" ' +
       '"${__scr_oom:--}" "${__scr_kill:--}" "$1"; }',
@@ -82,13 +83,33 @@ function buildCgroupFunctionsSnippet() {
  */
 function buildCgroupSamplerStartSnippet(containerName) {
   const v = CGROUP_SHELL_VARS;
+  const name = shellQuote(containerName);
+  const remoteRead = '__start_command_cgroup_read /sys/fs/cgroup';
   return [
     buildCgroupFunctionsSnippet(),
     `${v.file}="\${TMPDIR:-/tmp}/start-command-cgroup.$$"`,
-    `rm -f "$${v.file}" "$${v.file}.tmp"`,
-    `( __scs_dir=$(__start_command_cgroup_dir ${shellQuote(containerName)}) || exit 0; ` +
-      'while __scs_line=$(__start_command_cgroup_read "$__scs_dir"); do ' +
-      `printf '%s\\n' "$__scs_line" > "$${v.file}.tmp" && mv -f "$${v.file}.tmp" "$${v.file}"; ` +
+    `rm -f "$${v.file}" "$${v.file}.tmp" "$${v.file}.reason"`,
+    `__start_command_memory_limit=$(docker inspect -f '{{.HostConfig.Memory}}' ${name} 2>/dev/null)`,
+    `__start_command_sample_name=${name}`,
+    // The first counter is a baseline, including after watcher restart. Only
+    // changes between adjacent successful samples supply exit-time evidence.
+    `( export START_COMMAND_CGROUP_SAMPLING=1; __scs_previous=''; __scs_previous_at=0; __scs_changed=0; ` +
+      `__scs_dir=$(__start_command_cgroup_dir ${name}); while :; do ` +
+      '__scs_line=""; if [ -n "$__scs_dir" ]; then __scs_line=$(__start_command_cgroup_read "$__scs_dir"); fi; ' +
+      `if [ -z "$__scs_line" ]; then __scs_ns=$(docker inspect -f '{{.HostConfig.CgroupnsMode}}' ${name} 2>/dev/null); ` +
+      `if [ "$__scs_ns" = private ]; then ` +
+      `__scs_remote=$(docker exec ${name} sh -c ${shellQuote(`${buildCgroupFunctionsSnippet()}; ${remoteRead}`)} 2>&1); __scs_exit=$?; ` +
+      'if [ "$__scs_exit" = 0 ]; then __scs_line=$__scs_remote; ' +
+      'else __scs_detail=$(printf "%s" "$__scs_remote" | sed -n "1p" | cut -c 1-240); ' +
+      `printf '%s\n' "local cgroup unavailable; Docker exec exit=$__scs_exit: \${__scs_detail:-private cgroup v2 counters unreadable}" > "$${v.file}.reason"; fi; ` +
+      `else printf '%s\n' "local cgroup unavailable; container cgroup namespace=\${__scs_ns:-unavailable}, private required" > "$${v.file}.reason"; fi; fi; ` +
+      '__scs_now=$(date +%s); if [ -n "$__scs_line" ]; then ' +
+      '__scs_kill=$(printf "%s" "$__scs_line" | cut -d " " -f 4); ' +
+      'if [ -n "$__scs_previous" ] && [ "$__scs_kill" -gt "$__scs_previous" ] 2>/dev/null && [ "$((__scs_now-__scs_previous_at))" -le 3 ]; then __scs_changed=$__scs_now; fi; ' +
+      '__scs_previous=$__scs_kill; __scs_previous_at=$__scs_now; ' +
+      '__scs_fields=$(printf "%s" "$__scs_line" | cut -d " " -f 1-4); ' +
+      `printf '%s %s %s %s\\n' "$__scs_fields" "$__scs_changed" "$__scs_now" "$__scs_dir" > "$${v.file}.tmp" && mv -f "$${v.file}.tmp" "$${v.file}"; fi; ` +
+      `if [ "$(docker inspect -f '{{.State.Running}}' ${name} 2>/dev/null)" = false ]; then break; fi; ` +
       `sleep ${CGROUP_SAMPLE_INTERVAL_SECONDS}; done ) >/dev/null 2>&1 & ${v.sampler}=$!`,
   ].join('; ');
 }
@@ -106,10 +127,16 @@ function buildCgroupSamplerStopSnippet() {
     `kill "$${v.sampler}" 2>/dev/null`,
     `wait "$${v.sampler}" 2>/dev/null`,
     `${v.sample}=$(cat "$${v.file}" 2>/dev/null)`,
-    `__scs_dir=$(printf '%s' "$${v.sample}" | cut -s -d ' ' -f 5-)`,
-    `if [ -n "$__scs_dir" ] && __scs_line=$(__start_command_cgroup_read "$__scs_dir"); then ${v.sample}=$__scs_line; fi`,
-    `rm -f "$${v.file}" "$${v.file}.tmp"`,
-    `${v.sample}=$(printf '%s' "$${v.sample}" | cut -d ' ' -f 1-4)`,
+    `__start_command_memory_unavailable=$(cat "$${v.file}.reason" 2>/dev/null)`,
+    `__scs_dir=$(printf '%s' "$${v.sample}" | cut -s -d ' ' -f 7-)`,
+    `if [ -n "$__scs_dir" ] && __scs_line=$(__start_command_cgroup_read "$__scs_dir"); then ` +
+      `__scs_old=$(printf '%s' "$${v.sample}" | cut -d ' ' -f 4); __scs_at=$(printf '%s' "$${v.sample}" | cut -d ' ' -f 6); ` +
+      `__scs_changed=$(printf '%s' "$${v.sample}" | cut -d ' ' -f 5); __scs_now=$(date +%s); ` +
+      `__scs_new=$(printf '%s' "$__scs_line" | cut -d ' ' -f 4); ` +
+      `if [ "$__scs_new" -gt "$__scs_old" ] 2>/dev/null && [ "$((__scs_now-__scs_at))" -le 3 ]; then __scs_changed=$__scs_now; fi; ` +
+      `${v.sample}="$(printf '%s' "$__scs_line" | cut -d ' ' -f 1-4) $__scs_changed $__scs_now"; fi`,
+    `rm -f "$${v.file}" "$${v.file}.tmp" "$${v.file}.reason"`,
+    `${v.sample}=$(printf '%s' "$${v.sample}" | cut -d ' ' -f 1-6)`,
   ].join('; ');
 }
 
@@ -128,7 +155,8 @@ function buildCgroupMemoryLogSnippet(quotedLogPath) {
     `__scm_note=' (${OOM_SCOPE_NOTES[OOM_SCOPE.UNKNOWN]})'; fi; ` +
     `printf 'Memory:     memory.max=%s memory.peak=%s oom=%s oom_kill=%s%s\\n' ` +
     `"$1" "$2" "$3" "$4" "$__scm_note"; }; ` +
-    `if [ -n "$${v.sample}" ]; then __start_command_cgroup_log $${v.sample} >> ${quotedLogPath}; fi`
+    `if [ -n "$${v.sample}" ]; then __start_command_cgroup_log $${v.sample} >> ${quotedLogPath}; ` +
+    `else printf 'Memory:     unavailable (%s) memory.limit=%s (HostConfig)\\n' "\${__start_command_memory_unavailable:-sampler stopped before a reading; local cgroup unavailable}" "\${__start_command_memory_limit:-unknown}" >> ${quotedLogPath}; fi`
   );
 }
 
@@ -138,10 +166,14 @@ function buildCgroupMemoryLogSnippet(quotedLogPath) {
  * @param {string|null|undefined} text - `<memory.max> <memory.peak> <oom> <oom_kill>`
  * @returns {?string} Line without a trailing newline, or null without a sample
  */
-function formatCgroupMemoryLogLine(text) {
+function formatCgroupMemoryLogLine(
+  text,
+  memoryLimit = 'unknown',
+  unavailable = 'sampler unavailable; local cgroup hidden or unreadable'
+) {
   const counters = parseCgroupMemorySample(text);
   if (!counters) {
-    return null;
+    return `Memory:     unavailable (${unavailable}) memory.limit=${memoryLimit} (HostConfig)`;
   }
   const [max, peak, oom, kill] = String(text).trim().split(/\s+/);
   const scope = describeCgroupOomScope(counters);

package/src/lib/command-builder.js

@@ -57,6 +57,46 @@ function buildNextLevelCommand(options, command) {
   // Docker runtime options are flat (not per-level); forward them only when a
   // remaining level still uses docker so the nested $ invocation can apply them.
   if (remainingStack.includes('docker')) {
+    for (const [key, flag] of [
+      ['memory', '--memory'],
+      ['memorySwap', '--memory-swap'],
+      ['cpus', '--cpus'],
+      ['onKillResumeMemory', '--on-kill-resume-memory'],
+    ]) {
+      if (options[key] !== null && options[key] !== undefined) {
+        parts.push(
+          `${flag} ${require('./shell-utils').quoteShellArg(String(options[key]))}`
+        );
+      }
+    }
+    if (options.cpuPenaltyConfig) {
+      parts.push('--cpu-penalty');
+      for (const [key, flag] of [
+        ['cpus', '--cpu-penalty-cpus'],
+        ['trigger', '--cpu-penalty-trigger'],
+        ['triggerWindowMs', '--cpu-penalty-trigger-window'],
+        ['release', '--cpu-penalty-release'],
+        ['releaseWindowMs', '--cpu-penalty-release-window'],
+      ]) {
+        parts.push(
+          `${flag} ${options.cpuPenaltyConfig[key]}${key.endsWith('Ms') ? 'ms' : ''}`
+        );
+      }
+    }
+    if (options.onKillResume !== null && options.onKillResume !== undefined) {
+      parts.push(`--on-kill-resume ${options.onKillResume}`);
+    }
+    if (
+      options.onKillResumeDelay !== null &&
+      options.onKillResumeDelay !== undefined
+    ) {
+      parts.push(`--on-kill-resume-delay ${options.onKillResumeDelay}`);
+    }
+    if (options.recoveryCommand) {
+      parts.push(
+        `--recovery-command ${require('./shell-utils').quoteShellArg(options.recoveryCommand)}`
+      );
+    }
     for (const volume of options.volumes || []) {
       parts.push(`--volume "${volume}"`);
     }

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}`);
+    }
+  });
+}