start-command 0.35.4 → 0.37.0

package/src/lib/store-lock.js

@@ -0,0 +1,133 @@
+/** Populate before publishing: a failed write must never poison the shared lock. */
+const fs = require('fs');
+const os = require('os');
+const crypto = require('crypto');
+const LOCK_TIMEOUT_MS = 30000;
+const LOCK_STALE_MS = 60000;
+const MALFORMED_LOCK_GRACE_MS = 3000;
+
+class LockManager {
+  constructor(lockFilePath, filesystem = fs) {
+    this.lockFilePath = lockFilePath;
+    this.fs = filesystem;
+    this.lockAcquired = false;
+    this.identity = null;
+  }
+
+  acquire(timeout = LOCK_TIMEOUT_MS) {
+    const started = Date.now();
+    const debug = (message) => {
+      if (process.env.START_DEBUG === '1') {
+        console.error(`[DEBUG] Store lock ${this.lockFilePath}: ${message}`);
+      }
+    };
+    while (Date.now() - started < timeout) {
+      const temp = `${this.lockFilePath}.${process.pid}.${crypto.randomUUID()}`;
+      try {
+        try {
+          const stat = this.fs.statSync(this.lockFilePath);
+          if (this.isLockStale(this.readLockFile(), stat)) {
+            const current = this.fs.statSync(this.lockFilePath);
+            if (current.ino === stat.ino && current.mtimeMs === stat.mtimeMs) {
+              debug('reclaiming stale or malformed lock');
+              this.fs.unlinkSync(this.lockFilePath);
+            }
+          }
+        } catch (error) {
+          if (error.code !== 'ENOENT') {
+            throw error;
+          }
+        }
+        this.fs.writeFileSync(
+          temp,
+          JSON.stringify({
+            pid: process.pid,
+            timestamp: Date.now(),
+            hostname: os.hostname(),
+          }),
+          { flag: 'wx' }
+        );
+        const handle = this.fs.openSync(temp, 'r+');
+        try {
+          this.fs.fsyncSync(handle);
+        } finally {
+          this.fs.closeSync(handle);
+        }
+        const identity = this.fs.statSync(temp);
+        this.fs.linkSync(temp, this.lockFilePath);
+        this.identity = identity;
+        this.lockAcquired = true;
+        debug(`acquired after ${Date.now() - started}ms`);
+        return true;
+      } catch (error) {
+        if (error.code !== 'EEXIST') {
+          throw error;
+        }
+        this.sleep(100);
+      } finally {
+        try {
+          this.fs.unlinkSync(temp);
+        } catch {
+          /* May not have been created. */
+        }
+      }
+    }
+    debug('acquisition timed out');
+    return false;
+  }
+
+  release() {
+    if (!this.lockAcquired) {
+      return;
+    }
+    try {
+      const current = this.fs.statSync(this.lockFilePath);
+      if (
+        current.dev === this.identity.dev &&
+        current.ino === this.identity.ino
+      ) {
+        this.fs.unlinkSync(this.lockFilePath);
+      }
+    } catch {
+      /* The lock may already be gone. */
+    }
+    this.lockAcquired = false;
+  }
+
+  readLockFile() {
+    try {
+      return JSON.parse(this.fs.readFileSync(this.lockFilePath, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  isLockStale(data, stat) {
+    if (
+      !data ||
+      !Number.isFinite(data.timestamp) ||
+      !Number.isInteger(data.pid) ||
+      data.pid <= 0 ||
+      data.pid > 2147483647
+    ) {
+      return Boolean(
+        stat && Date.now() - stat.mtimeMs >= MALFORMED_LOCK_GRACE_MS
+      );
+    }
+    if (data.hostname === os.hostname()) {
+      try {
+        process.kill(data.pid, 0);
+        return false;
+      } catch (error) {
+        return error.code === 'ESRCH';
+      }
+    }
+    return Date.now() - data.timestamp > LOCK_STALE_MS;
+  }
+
+  sleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  }
+}
+
+module.exports = { LockManager, LOCK_TIMEOUT_MS, MALFORMED_LOCK_GRACE_MS };

package/src/lib/usage.js

@@ -3,6 +3,7 @@ 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
 
 Options:
+  --help, -h           Show this usage and exit successfully
   --isolated, --isolation, -i <env>  Run in isolated environment (screen, tmux, docker, ssh)
   --attached, -a        Run in attached mode (foreground)
   --detached, -d        Run in detached mode (background)
@@ -13,12 +14,24 @@ Options:
   --volume, -v <spec>   Docker bind mount/volume host:container[:mode] (repeatable, docker only)
   --mount <spec>        Docker --mount spec (repeatable, docker only)
   --env, -e <KEY=VALUE> Environment variable for docker container (repeatable, docker only)
+  --label <KEY=VALUE>   Container attribution (repeatable, docker only; start-command.* reserved)
   --privileged          Run docker container in privileged mode (docker only)
   --network <name>      Connect to a named network (repeatable, docker only)
   --network-alias <alias> Add alias to the first network (repeatable, docker only)
   --on-kill-resume <N>  Resume a killed (exit 137 / OOM) detached docker session up to N times
   --recovery-command <cmd>  Command to run in the same container on such a resume
   --on-kill-resume-delay <min[-max]>  Wait a random number of seconds before each such resume (default 0)
+  --memory <size|N%|MIN%-MAX%>  Docker RAM cap; percentages use daemon capacity
+  --memory-swap <spec>  Combined memory+swap cap (defaults to memory, no extra swap)
+  --cpus <n|N%|MIN%-MAX%>  Docker CPU cap; ranges draw once per creation
+  --on-kill-resume-memory <spec>  New memory cap before a qualifying OOM recovery
+  --cpu-penalty        Enable delayed Docker CPU penalty (default off)
+  --cpu-penalty-cpus <n>  Penalty cap (default 2 CPUs)
+  --cpu-penalty-trigger <p%>  Busy threshold (default 95% of usable CPUs)
+  --cpu-penalty-trigger-window <d>  Fully covered busy window (default 15m)
+  --cpu-penalty-release <p%>  Quiet threshold (default 65% of penalty cap)
+  --cpu-penalty-release-window <d>  Minimum quiet/capped window (default 15m)
+                        Durations accept ms, s, m, h; --status reports penalty state
   --endpoint <endpoint> SSH endpoint (required for ssh isolation, e.g., user@host)
   --isolated-user, -u [name]  Create isolated user with same permissions
   --keep-user           Keep isolated user after command completes
@@ -32,13 +45,15 @@ Options:
   --status <id>         Show status of execution by UUID or session name (--output-format: links-notation|json|text)
   --list                List all tracked executions (--output-format: links-notation|json|text)
   --running             With --list, only report executions that are still running
-  --upload-log <id>     Upload the stored log for an execution UUID or session name
+  --upload-log <id>     Upload a sanitized copy of the stored log privately
+  --no-sanitize        With --upload-log, explicitly upload without secret redaction
   --stop <id>           Ask a detached isolated execution to stop gracefully
   --terminate <id>      Terminate a detached isolated execution immediately
   --attach <id>         Attach to a running detached isolated execution
   --read-only           With --attach, follow output without sending input
   --resume <id>         Restart a stopped detached execution in the same environment
                         (append -- <command> to run a different command there)
+  --remove-original    With legacy snapshot resume, remove the stopped original after launch
   --resume-all          Re-attach or reconcile every execution still marked running
   --cleanup             Clean up stale "executing" records (crashed/killed processes)
   --cleanup-dry-run     Show stale records that would be cleaned up (without cleaning)

package/test/ci-workflow-invariants.js

@@ -156,6 +156,10 @@ describe('CI workflow invariants', () => {
   it('gives every job a timeout', () => {
     for (const name of workflows) {
       for (const job of parseJobs(readWorkflow(name))) {
+        if (jobKey(job.body, 'uses')) {
+          // Reusable-workflow callers cannot declare a timeout; their jobs do.
+          continue;
+        }
         assert.ok(
           jobKey(job.body, 'timeout-minutes'),
           `${name}: job "${job.name}" has no timeout-minutes`
@@ -186,7 +190,7 @@ describe('CI workflow invariants', () => {
     }
   });
 
-  it('makes writers non-cancellable and read-only checks cancellable', () => {
+  it('protects main and the gated Rust stage from cancellation', () => {
     for (const name of workflows) {
       for (const job of parseJobs(readWorkflow(name))) {
         const group = concurrencyKey(job.body, 'group');
@@ -212,8 +216,10 @@ describe('CI workflow invariants', () => {
           );
           assert.strictEqual(
             cancel,
-            'true',
-            `${name}: superseded check "${job.name}" should be cancelled`
+            name === 'rust.yml' || job.name === 'rust-stage'
+              ? 'false'
+              : "${{ github.ref != 'refs/heads/main' }}",
+            `${name}: checks must preserve main and the gated Rust stage`
           );
         }
       }
@@ -223,7 +229,7 @@ describe('CI workflow invariants', () => {
   it('uses !cancelled() rather than always() outside the status job', () => {
     for (const name of workflows) {
       for (const job of parseJobs(readWorkflow(name))) {
-        if (job.name === 'pipeline-status') {
+        if (job.name === 'pipeline-status' || job.name === 'rust-stage') {
           continue;
         }
         assert.doesNotMatch(
@@ -246,7 +252,7 @@ describe('CI workflow invariants', () => {
         `${name}: pipeline-status must run even when jobs are cancelled`
       );
       for (const job of jobs) {
-        if (job.name === 'pipeline-status') {
+        if (job.name === 'pipeline-status' || job.name === 'rust-stage') {
           continue;
         }
         assert.match(
@@ -395,15 +401,10 @@ describe('CI workflow invariants', () => {
 
   it('audits both dependency graphs for advisories', () => {
     const security = readWorkflow('security.yml');
-    const jobs = parseJobs(security).map((job) => job.name);
-    for (const job of ['cargo-audit', 'npm-audit']) {
-      assert.ok(jobs.includes(job), `security.yml has no ${job} job`);
-    }
-    assert.match(
-      security,
-      /cargo audit/,
-      'cargo-audit job must run cargo audit'
-    );
+    const rust = readWorkflow('rust.yml');
+    assert.ok(parseJobs(security).some((job) => job.name === 'npm-audit'));
+    assert.ok(parseJobs(rust).some((job) => job.name === 'cargo-audit'));
+    assert.match(rust, /cargo audit/, 'cargo-audit job must run cargo audit');
     assert.match(security, /npm audit/, 'npm-audit job must run npm audit');
   });
 

package/test/docker-command-handoff.js

@@ -0,0 +1,107 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const {
+  buildCommandHandoffArgs,
+  buildCommandHandoffScript,
+  commandHandoffPath,
+  writeCommandHandoff,
+} = require('../src/lib/docker-command-handoff');
+const { buildResumePlan, ResumeMode } = require('../src/lib/execution-resume');
+const { SessionState } = require('../src/lib/session-probe');
+
+test('new stopped containers choose a copy-free command handoff', () => {
+  const plan = buildResumePlan(
+    {
+      uuid: 'uuid',
+      command: 'old-command',
+      options: {
+        isolated: 'docker',
+        isolationMode: 'detached',
+        sessionName: 'box',
+        commandHandoff: true,
+      },
+    },
+    'printf new-command',
+    { state: SessionState.STOPPED, alive: false }
+  );
+  assert.equal(plan.mode, ResumeMode.DOCKER_START);
+  assert.equal(plan.handoffCommand, 'printf new-command');
+  assert.deepEqual(
+    plan.steps.map((step) => step.args),
+    [['start', 'box']]
+  );
+  assert.equal(plan.snapshotImage, undefined);
+});
+
+test('handoff preserves argv and accepts a replacement without executing it on the host', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'handoff-test-'));
+  const marker = path.join(dir, 'command');
+  try {
+    const args = buildCommandHandoffArgs(
+      ['sh', '-c', 'printf original'],
+      'command'
+    );
+    const shellOptions = { cwd: dir, encoding: 'utf8' };
+    assert.equal(
+      spawnSync(args[0], args.slice(1), shellOptions).stdout,
+      'original'
+    );
+    let script;
+    const copied = writeCommandHandoff(
+      'box',
+      "printf '%s' 'new $value'",
+      (_bin, argv) => {
+        assert.equal(argv[0], 'cp');
+        assert.equal(argv[2], `box:${commandHandoffPath('box')}`);
+        script = fs.readFileSync(argv[1], 'utf8');
+        fs.copyFileSync(argv[1], marker);
+        fs.accessSync(argv[1], fs.constants.R_OK);
+        // Windows chmod supports write permission, not Unix mode bits.
+        if (process.platform !== 'win32') {
+          assert.equal(fs.statSync(argv[1]).mode & 0o777, 0o644);
+        }
+        return { success: true };
+      },
+      { shell: 'sh' }
+    );
+    assert.equal(copied.success, true);
+    assert.ok(script.includes('new $value'));
+    assert.equal(
+      spawnSync(args[0], args.slice(1), shellOptions).stdout,
+      'new $value'
+    );
+    // docker start without another replacement runs the current stored command.
+    assert.equal(
+      spawnSync(args[0], args.slice(1), shellOptions).stdout,
+      'new $value'
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('handoff preserves direct shell positional argv and evaluates compound commands as scripts', () => {
+  for (const [command, expected] of [
+    ['sh -c \'printf "%s:%s" "$0" "$1"\' tag \'two words\'', 'tag:two words'],
+    ["sh -c 'exit 7'; printf 'after%s' \"$?\"", 'after7'],
+  ]) {
+    const script = buildCommandHandoffScript(command, { shell: 'sh' });
+    const result = spawnSync('sh', ['-c', script], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stdout, expected);
+  }
+});
+
+test('auto handoff chooses an installed shell inside the existing container', () => {
+  const script = buildCommandHandoffScript('printf auto');
+  assert.ok(
+    script.includes('command -v bash || command -v zsh || command -v sh')
+  );
+  const result = spawnSync('sh', ['-c', script], { encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.stdout, 'auto');
+});

package/test/docker-runtime-options.js

@@ -300,11 +300,16 @@ describe('buildDockerRuntimeMetadata', () => {
       volumes: null,
       mounts: null,
       env: null,
+      labels: null,
+      commandHandoff: null,
       privileged: null,
       network: null,
       networks: null,
       networkAliases: null,
       resourceLimits: null,
+      resolvedLimits: null,
+      resourceLimitSpecs: null,
+      onKillResumeMemory: null,
       onKillResume: null,
       recoveryCommand: null,
       onKillResumeDelay: null,
@@ -331,6 +336,11 @@ describe('buildDockerRuntimeMetadata', () => {
         networks: ['hive-formal-ai', 'public-egress'],
         networkAliases: ['formal-ai', 'checker'],
         resourceLimits: null,
+        labels: null,
+        commandHandoff: null,
+        resolvedLimits: null,
+        resourceLimitSpecs: null,
+        onKillResumeMemory: null,
         onKillResume: null,
         recoveryCommand: null,
         onKillResumeDelay: null,

package/test/docker-snapshot-safety.js

@@ -0,0 +1,106 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const {
+  preflightSnapshot,
+  acquireSnapshotLock,
+  containerdRoot,
+} = require('../src/lib/docker-snapshot-safety');
+
+const GiB = 1024 ** 3;
+function runner(size, containerd = false) {
+  return (_bin, args) => ({
+    success: true,
+    stdout:
+      args[0] === 'info'
+        ? JSON.stringify({
+            DockerRootDir: '/docker',
+            DriverStatus: containerd
+              ? [['driver-type', 'io.containerd.snapshotter.v1']]
+              : [],
+          })
+        : String(size),
+  });
+}
+
+test('preflight refuses insufficient space before any snapshot', () => {
+  assert.throws(
+    () =>
+      preflightSnapshot('box', runner(12 * GiB), {
+        freeBytes: () => 20 * GiB,
+      }),
+    /Insufficient disk.*34\.00 GiB/
+  );
+});
+
+test('containerd image store checks Docker and containerd filesystems separately', () => {
+  const checked = [];
+  assert.throws(
+    () =>
+      preflightSnapshot('box', runner(8 * GiB, true), {
+        containerdRoot: '/containerd',
+        freeBytes: (root) => {
+          checked.push(root);
+          return root === '/docker' ? 100 * GiB : 25 * GiB;
+        },
+      }),
+    /\/containerd/
+  );
+  assert.deepEqual(checked, ['/docker', '/containerd']);
+});
+
+test('preflight logs the layer size and rejects unknown sizes or roots', () => {
+  assert.match(
+    preflightSnapshot('box', runner(GiB), { freeBytes: () => 100 * GiB })
+      .message,
+    /snapshotting 1\.00 GiB/
+  );
+  assert.throws(
+    () => preflightSnapshot('box', runner('unknown')),
+    /writable layer/
+  );
+  assert.equal(
+    containerdRoot('version = 2\nroot = "/custom"\n[plugins]\nroot = "/wrong"'),
+    '/custom'
+  );
+});
+
+test('snapshot lock is separate from store locks and excludes concurrent processes', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'snapshot-lock-'));
+  const lockPath = path.join(dir, 'snapshot.lock');
+  try {
+    const lock = acquireSnapshotLock({ lockPath });
+    assert.throws(
+      () => acquireSnapshotLock({ lockPath }),
+      /snapshot.*in progress/
+    );
+    const child = spawnSync(
+      process.execPath,
+      [
+        '-e',
+        `
+      try {
+        require(${JSON.stringify(require.resolve('../src/lib/docker-snapshot-safety'))}).acquireSnapshotLock();
+        process.exitCode = 3;
+      } catch (error) {
+        console.log(error.message);
+        process.exitCode = 2;
+      }
+    `,
+      ],
+      {
+        encoding: 'utf8',
+        env: { ...process.env, START_SNAPSHOT_LOCK: lockPath },
+      }
+    );
+    assert.equal(child.status, 2, child.stderr);
+    assert.match(child.stdout, /snapshot.*in progress/);
+    lock.release();
+    acquireSnapshotLock({ lockPath }).release();
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/test/execution-resume.js

@@ -101,12 +101,8 @@ describe('buildResumePlan', () => {
       '--name',
       'box-resume-1',
     ]);
-    assert.deepStrictEqual(runArgs.slice(-4), [
-      'start-command-resume/box:1',
-      'sh',
-      '-c',
-      'npm run build',
-    ]);
+    assert.ok(runArgs.includes('start-command-resume/box:1'));
+    assert.deepStrictEqual(runArgs.slice(-3), ['sh', '-c', 'npm run build']);
   });
 
   test('carries stored docker runtime options into the snapshot run', () => {
@@ -270,11 +266,14 @@ describe('resumeExecution', () => {
         watchers.push([name, policy, logPath]),
     });
     assert.strictEqual(result.success, true, result.error);
-    assert.deepStrictEqual(calls, [['docker', 'start', 'box']]);
+    assert.deepStrictEqual(
+      calls.filter((call) => call[1] !== 'inspect'),
+      [['docker', 'start', 'box']]
+    );
     assert.strictEqual(watchers.length, 1);
     assert.strictEqual(watchers[0][0], 'box');
     assert.strictEqual(watchers[0][2], '/tmp/session.log');
-    assert.strictEqual(store.saved.length, 2);
+    assert.strictEqual(store.saved.length, 3);
     assert.strictEqual(store.saved[0].uuid, record.uuid);
     assert.strictEqual(store.saved[0].status, 'executing');
     assert.strictEqual(store.saved[0].options.resumeCount, 1);
@@ -286,9 +285,15 @@ describe('resumeExecution', () => {
     const result = await resumeExecution(store, 'box', {
       command: 'npm run build',
       probe: () => probeWith(SessionState.STOPPED, 'exited'),
-      runner: () => ({
+      snapshotOptions: { freeBytes: () => 100 * 1024 ** 3 },
+      runner: (_bin, args) => ({
         success: true,
-        stdout: 'deadbeef\n',
+        stdout:
+          args[0] === 'info'
+            ? JSON.stringify({ DockerRootDir: '/docker' })
+            : args.includes('--size')
+              ? '1024'
+              : 'deadbeef\n',
         stderr: '',
         status: 0,
       }),
@@ -320,7 +325,10 @@ describe('resumeExecution', () => {
     });
     assert.strictEqual(result.success, false);
     assert.match(result.error, /no such container/);
-    assert.strictEqual(store.saved.length, 0);
+    assert.strictEqual(store.saved.length, 2);
+    assert.strictEqual(store.saved.at(-1).status, 'executing');
+    assert.strictEqual(store.saved.at(-1).options.sessionName, 'box');
+    assert.strictEqual(store.saved.at(-1).options.launchPending, undefined);
   });
 
   test('relaunches through the isolation backend when the container is gone', async () => {

package/test/exit-reason.js

@@ -111,7 +111,11 @@ describe('resolveExitReason', () => {
   });
 
   it('should report the cgroup OOM observation when there is no marker', () => {
-    const reason = resolveExitReason({ exitCode: 137, oomKilled: true });
+    const reason = resolveExitReason({
+      exitCode: 137,
+      oomKilled: true,
+      exitEvidence: { mainOom: true },
+    });
     assert.strictEqual(reason, 'memory-exhaustion (cgroup-oom-killer)');
   });
 
@@ -173,6 +177,7 @@ describe('resolveMemoryExhaustion', () => {
       resolveMemoryExhaustion({
         exitCode: 137,
         logTail: 'killed\n',
+        exitEvidence: { mainOom: true },
         oomKilled: true,
       }),
       {

package/test/failure-handler.js

@@ -175,6 +175,17 @@ describe('failure-handler', () => {
       assert.ok(!body.includes('\\"'), 'body must not contain escaped quotes');
     });
 
+    it('sanitizes credentials in the issue title and body', () => {
+      if (process.platform === 'win32') {
+        return;
+      }
+      const token = `gh${'p_'}${'a'.repeat(36)}`;
+      const { argv } = createIssueWithFakeGh(`echo ${token}`);
+      assert.ok(!argv[5].includes(token));
+      assert.ok(!argv[7].includes(token));
+      assert.ok(argv[7].includes('[REDACTED]'));
+    });
+
     it('writes real newlines into the issue body', () => {
       if (process.platform === 'win32') {
         return;

package/test/isolation.js

@@ -16,6 +16,7 @@ const {
   supportsLogfileOption,
   resetScreenVersionCache,
   getDefaultDockerImage,
+  canRunLinuxDockerImages,
 } = require('../src/lib/isolation');
 
 describe('Isolation Module', () => {
@@ -665,8 +666,8 @@ describe('detectShellInEnvironment', () => {
   });
 
   it('should auto-detect shell in docker if docker is available', () => {
-    if (!isCommandAvailable('docker')) {
-      console.log('  Skipping: docker not installed');
+    if (!canRunLinuxDockerImages()) {
+      console.log('  Skipping: Docker cannot run Linux container images');
       return;
     }
     // Use alpine:latest which is commonly available and has sh
@@ -703,8 +704,8 @@ describe('Shell option forwarding to isolation runners', () => {
 
   describe('runInDocker shell option', () => {
     it('should accept shell option in options object', async () => {
-      if (!isCommandAvailable('docker')) {
-        console.log('  Skipping: docker not installed');
+      if (!canRunLinuxDockerImages()) {
+        console.log('  Skipping: Docker cannot run Linux container images');
         return;
       }