start-command 0.43.0 → 0.44.0

package/src/lib/execution-resume-all.js

@@ -34,6 +34,7 @@ const ResumeAllAction = {
   RUNNING: 'running',
   RECONCILED: 'reconciled',
   UNKNOWN: 'unknown',
+  PAUSED: 'paused',
 };
 
 function formatResumeAllAsLinksNotation(summary) {
@@ -137,6 +138,19 @@ function resumeAllExecutions(store, deps = {}) {
       continue;
     }
 
+    if (probe.state === SessionState.PAUSED) {
+      // Neither restarted nor re-watched while frozen (issue #263).
+      executions.push(
+        describeRecord(
+          record,
+          probe,
+          ResumeAllAction.PAUSED,
+          `Skipped paused container: ${sessionName}. Use \`$ --unpause ${record.uuid}\` to continue it.`
+        )
+      );
+      continue;
+    }
+
     if (probe.alive && probe.backend === 'docker') {
       startWatcher(
         sessionName,

package/src/lib/execution-resume.js

@@ -43,7 +43,11 @@ const {
   rollbackLaunch,
   failLaunchedPersistence,
 } = require('./launch-persistence');
-const { SessionState, probeSession } = require('./session-probe');
+const {
+  SessionState,
+  pausedSessionError,
+  probeSession,
+} = require('./session-probe');
 const { getDockerNetworks } = require('./docker-network-lifecycle');
 const {
   writeCommandHandoff,
@@ -217,6 +221,10 @@ function buildResumePlan(
     return { error: 'Only detached isolated executions can be resumed.' };
   }
 
+  if (probe.state === SessionState.PAUSED) {
+    return pausedSessionError('resume', record.uuid, sessionName);
+  }
+
   if (probe.alive) {
     return {
       error:
@@ -481,6 +489,13 @@ async function resumeExecution(store, identifier, deps = {}) {
   const runner = deps.runner || runCommand;
   const probeFn = deps.probe || ((r) => probeSession(r, runner));
   const probe = probeFn(record);
+  if (probe.state === SessionState.PAUSED) {
+    // Refused before any snapshot or resource change (issue #263).
+    return {
+      success: false,
+      ...pausedSessionError('resume', record.uuid, probe.sessionName),
+    };
+  }
   const opts = record.options || {};
   let resources;
   try {

package/src/lib/execution-store.js

@@ -663,7 +663,11 @@ class ExecutionStore {
     const staleRecords = [];
 
     for (const record of executingRecords) {
-      if (require('./launch-owner').hasActiveLaunch(record)) {
+      if (
+        require('./launch-owner').hasActiveLaunch(record) ||
+        require('./execution-pause').isConfirmedPaused(record)
+      ) {
+        // A paused container is alive, just frozen (issue #263).
         continue;
       }
       let isStale = false;

package/src/lib/log-sanitizer.js

@@ -13,9 +13,10 @@
  * keeps the rest of its line (issue #249, sensitive-data-sanitizer#45); the
  * pre-pass that did this here is gone (issue #253).
  *
- * The package depends on ^0.14.0, the current release flagged by the
- * dependency freshness check; the Rust installer and its version check
- * require the same release (rust/src/lib/log_sanitizer.rs).
+ * The package stays on ^0.14.0: 0.20.0 and later drop the bytes after a
+ * credential that is followed by a NUL byte (sensitive-data-sanitizer#180,
+ * the blocker in .github/dependency-blockers.json). The Rust installer and its
+ * version check require the same release (rust/src/lib/log_sanitizer.rs).
  */
 
 const fs = require('fs');

package/src/lib/query-commands.js

@@ -3,7 +3,8 @@
  *
  * Every option in this module addresses an execution that already exists in
  * the tracking store instead of launching a new one: --status, --list,
- * --upload-log, --stop, --terminate, --attach, --resume, --resume-all and
+ * --upload-log, --stop, --terminate, --pause, --unpause, --attach, --resume,
+ * --resume-all and
  * --cleanup, plus --alias and --rename. `dispatchQueryCommand` is the single
  * entry point the CLI calls before it starts interpreting the command line as
  * a command to run.
@@ -54,6 +55,28 @@ function handleControlQuery(store, identifier, action) {
   return reportResult(controlExecution(store, identifier, action));
 }
 
+/**
+ * Handle --pause / --unpause (issue #263).
+ * @param {?object} store - Execution store
+ * @param {string} identifier - UUID or session name
+ * @param {string} action - pause or unpause
+ * @param {object} [options] - {outputFormat, pauseReason, pausedBy}
+ * @returns {number} Exit code
+ */
+function handlePauseQuery(store, identifier, action, options = {}) {
+  const pause = require('./execution-pause');
+  const deps = {
+    outputFormat: options.outputFormat,
+    reason: options.pauseReason || null,
+    by: options.pausedBy || null,
+  };
+  return reportResult(
+    action === pause.PauseAction.PAUSE
+      ? pause.pauseExecution(store, identifier, deps)
+      : pause.unpauseExecution(store, identifier, deps)
+  );
+}
+
 function handleAttachQuery(store, identifier, readOnly) {
   return reportResult(attachExecution(store, identifier, { readOnly }));
 }
@@ -155,6 +178,8 @@ function hasQueryMode(options) {
     hasValue(options.uploadLog) ||
     hasValue(options.stop) ||
     hasValue(options.terminate) ||
+    hasValue(options.pause) ||
+    hasValue(options.unpause) ||
     hasValue(options.attach) ||
     hasValue(options.resume) ||
     options.resumeAll === true ||
@@ -193,6 +218,12 @@ async function dispatchQueryCommand(options, context = {}) {
       ControlAction.TERMINATE
     );
   }
+  if (hasValue(options.pause)) {
+    return handlePauseQuery(store, options.pause, 'pause', options);
+  }
+  if (hasValue(options.unpause)) {
+    return handlePauseQuery(store, options.unpause, 'unpause', options);
+  }
   if (hasValue(options.attach)) {
     return handleAttachQuery(store, options.attach, options.readOnly === true);
   }
@@ -234,6 +265,7 @@ module.exports = {
   handleCleanup,
   handleControlQuery,
   handleListQuery,
+  handlePauseQuery,
   handleResumeAllQuery,
   handleResumeQuery,
   handleStatusQuery,

package/src/lib/session-probe.js

@@ -13,12 +13,16 @@ const { getDockerCommand } = require('./docker-cleanup');
 /**
  * States a tracked isolation session can be observed in.
  * - RUNNING: the session/container is alive and can be attached to
+ * - PAUSED: the container is frozen by `docker pause` (issue #263); it is
+ *   alive (its process and memory are kept) but can be neither attached to nor
+ *   resumed until `$ --unpause` thaws it
  * - STOPPED: the container still exists but is not running (resumable)
  * - MISSING: no trace of the session/container remains
  * - UNKNOWN: the backend cannot be probed locally (e.g. ssh)
  */
 const SessionState = {
   RUNNING: 'running',
+  PAUSED: 'paused',
   STOPPED: 'stopped',
   MISSING: 'missing',
   UNKNOWN: 'unknown',
@@ -39,6 +43,11 @@ function mapDockerStatusToState(status) {
   if (normalized === 'running' || normalized === 'restarting') {
     return SessionState.RUNNING;
   }
+  if (normalized === 'paused') {
+    // Paused is alive, not stopped: reading it as stopped made `--resume`
+    // plan a `docker start`/snapshot of a frozen container (issue #263).
+    return SessionState.PAUSED;
+  }
   return SessionState.STOPPED;
 }
 
@@ -109,13 +118,30 @@ function probeSession(record, runner = runCommand) {
     probe.state = result.success ? SessionState.RUNNING : SessionState.MISSING;
   }
 
-  probe.alive = probe.state === SessionState.RUNNING;
+  probe.alive =
+    probe.state === SessionState.RUNNING || probe.state === SessionState.PAUSED;
   return probe;
 }
 
+/**
+ * Refusal for a control that cannot act on a paused container (issue #263).
+ * @param {string} action - What was refused, e.g. "attach to" or "resume"
+ * @param {string} uuid - Execution UUID, for the suggested command
+ * @param {string} sessionName - Container name
+ * @returns {{error: string}} Error result
+ */
+function pausedSessionError(action, uuid, sessionName) {
+  return {
+    error:
+      `Session "${sessionName}" is paused (frozen by docker pause), so start cannot ${action} it. ` +
+      `Use \`$ --unpause ${uuid}\` first to continue the same process, or \`$ --stop ${uuid}\` to end it.`,
+  };
+}
+
 module.exports = {
   SessionState,
   mapDockerStatusToState,
   parseScreenSessionState,
+  pausedSessionError,
   probeSession,
 };

package/src/lib/status-formatter.js

@@ -33,6 +33,7 @@ const {
   persistContainerRemoval,
 } = require('./container-removal');
 const { withDockerInspectBatch } = require('./docker-inspect-batch');
+const pause = require('./execution-pause');
 const {
   backendExitCode,
   dockerProbeSpawnOptions,
@@ -460,8 +461,11 @@ function enrichDetachedStatus(record) {
     ? readAttemptLogTail(record, FATAL_MARKER_TAIL_BYTES)
     : null;
   const probe = dockerProbe();
-  const resolved = attachContainerRemoval(
-    resolveDetachedStatus(record, logTail, probe),
+  const resolved = pause.attachPauseState(
+    attachContainerRemoval(
+      resolveDetachedStatus(record, logTail, probe),
+      probe
+    ),
     probe
   );
   const enriched = attachMemoryExhaustion(
@@ -664,6 +668,7 @@ function formatRecordAsText(record) {
   if (obj.staleDetectedAt) {
     lines.push(`Stale Detected At: ${obj.staleDetectedAt}`);
   }
+  lines.push(...pause.pauseTextLines(obj));
   if (obj.containerState) {
     // The container no longer exists; `containerId` is history (issue #225).
     lines.push(`Container State:   ${obj.containerState}`);
@@ -821,6 +826,7 @@ function queryStatus(store, identifier, outputFormat) {
       () => {
         const enrichedRecord = enrichDetachedStatus(record);
         persistContainerRemoval(store, record, enrichedRecord);
+        pause.persistPauseReconciliation(store, enrichedRecord);
         return attachProcessIds(enrichedRecord);
       }
     );
@@ -856,7 +862,11 @@ function listExecutions(store, outputFormat, options = {}) {
     // One docker inspect for every listed container (issue #243).
     const enriched = sortRecordsByStartTimeDesc(
       withDockerInspectBatch(all, dockerProbe(), () =>
-        all.map(prepareRecordForList)
+        all.map((record) => {
+          const prepared = prepareRecordForList(record);
+          pause.persistPauseReconciliation(store, prepared);
+          return prepared;
+        })
       )
     );
     // --running reports the reconciled status, not the stored one: a record

package/src/lib/status-probe.js

@@ -29,7 +29,8 @@ const {
  *
  * @param {string} sessionName - Container name
  * @param {Object|null} [probe] - Receives `sessionNotFound` (issue #225)
- * @returns {{running: boolean, exitCode: number|null, oomKilled: boolean|null}|null} State,
+ * @returns {{running: boolean, exitCode: number|null, oomKilled: boolean|null,
+ *   status: ?string, paused: boolean}|null} State,
  *   or null when the container cannot be inspected (not found yet, removed, or docker error)
  */
 function inspectDockerState(sessionName, probe = null) {
@@ -37,7 +38,8 @@ function inspectDockerState(sessionName, probe = null) {
     getDockerCommand(),
     dockerProbeSpawnOptions(),
     '{{.State.Running}} {{.State.ExitCode}} {{.State.OOMKilled}} ' +
-      '{{.State.StartedAt}} {{.State.FinishedAt}}',
+      '{{.State.StartedAt}} {{.State.FinishedAt}} ' +
+      '{{.State.Status}} {{.State.Paused}}',
     sessionName
   );
   if (probe) {
@@ -50,9 +52,15 @@ function inspectDockerState(sessionName, probe = null) {
   }
   // Parsed positionally and defensively: an older docker (or a stubbed one)
   // may answer with fewer fields than the template asks for.
-  const [runningRaw, exitRaw, oomKilledRaw, startedRaw, finishedRaw] = stdout
-    .trim()
-    .split(/\s+/);
+  const [
+    runningRaw,
+    exitRaw,
+    oomKilledRaw,
+    startedRaw,
+    finishedRaw,
+    statusRaw,
+    pausedRaw,
+  ] = stdout.trim().split(/\s+/);
   const exitCode = Number.parseInt(exitRaw, 10);
   return {
     running: runningRaw === 'true',
@@ -61,6 +69,9 @@ function inspectDockerState(sessionName, probe = null) {
       oomKilledRaw === 'true' ? true : oomKilledRaw === 'false' ? false : null,
     startedAt: normalizeDockerTimestamp(startedRaw),
     finishedAt: normalizeDockerTimestamp(finishedRaw),
+    // A paused container is still `.State.Running` (issue #263).
+    status: statusRaw || null,
+    paused: pausedRaw === 'true' || statusRaw === 'paused',
   };
 }
 
@@ -99,6 +110,9 @@ function readDockerState(record, probe = null) {
   ) {
     return null;
   }
+  if (probe) {
+    probe.dockerState = state;
+  }
   return state;
 }
 

package/src/lib/usage.js

@@ -1,6 +1,6 @@
 /** Print usage information */
 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 | $ --alias <id> <name> | $ --rename <id> <name>
+  console.log(`Usage: $ [options] [--] <command> | $ --status <uuid> [--output-format <fmt>] | $ --list [--running] [--output-format <fmt>] | $ --upload-log <id> | $ --stop <id> | $ --terminate <id> | $ --pause <id> | $ --unpause <id> | $ --attach <id> [--read-only] | $ --resume <id> [-- <command>] | $ --resume-all | $ --alias <id> <name> | $ --rename <id> <name>
 
 Options:
   --help, -h           Show this usage and exit successfully
@@ -54,6 +54,11 @@ Options:
   --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
+  --pause <id>          Freeze a detached Docker execution (docker pause): CPU is
+                        released, memory stays allocated (--stop frees it)
+  --pause-reason <text> With --pause, record why the execution was frozen
+  --paused-by <name>    With --pause, record who froze the execution
+  --unpause <id>        Thaw a paused Docker execution; the same process continues
   --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
@@ -93,6 +98,8 @@ Examples:
   $ --upload-log my-screen-session         # Upload stored execution log
   $ --stop my-screen-session               # Ask detached execution to stop gracefully
   $ --terminate my-screen-session          # Terminate detached execution immediately
+  $ --pause my-docker-session --pause-reason 'rate limit'  # Freeze, keep RAM
+  $ --unpause my-docker-session            # Continue the same frozen process
   $ --list --running                       # Only executions that are still running
   $ --attach my-docker-session             # Re-enter a running detached session
   $ --attach my-docker-session --read-only # Follow its output without stdin

package/test/args-parser-attach-resume.js

@@ -142,7 +142,7 @@ describe('query mode exclusivity', () => {
     test(`rejects ${args.join(' ')}`, () => {
       assert.throws(() => {
         parse(args);
-      }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, --attach, --resume, --resume-all, --cleanup, --alias, or --rename/);
+      }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, --pause, --unpause, --attach, --resume, --resume-all, --cleanup, --alias, or --rename/);
     });
   }
 });

package/test/args-parser-control.js

@@ -54,19 +54,19 @@ describe('control options', () => {
   it('should reject combining query and control modes', () => {
     assert.throws(() => {
       parseArgs(['--status', 'uuid-here', '--stop', 'my-session']);
-    }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, --attach, --resume, --resume-all, --cleanup, --alias, or --rename/);
+    }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, --pause, --unpause, --attach, --resume, --resume-all, --cleanup, --alias, or --rename/);
   });
 
   it('should reject combining upload-log with control modes', () => {
     assert.throws(() => {
       parseArgs(['--upload-log', 'uuid-here', '--terminate', 'my-session']);
-    }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, --attach, --resume, --resume-all, --cleanup, --alias, or --rename/);
+    }, /Cannot combine --status, --list, --upload-log, --stop, --terminate, --pause, --unpause, --attach, --resume, --resume-all, --cleanup, --alias, or --rename/);
   });
 
   it('should reject output-format with control modes', () => {
     assert.throws(() => {
       parseArgs(['--stop', 'my-session', '--output-format', 'json']);
-    }, /--output-format option is only valid with --status, --list, --resume, or --resume-all/);
+    }, /--output-format option is only valid with --status, --list, --resume, --resume-all, --pause, or --unpause/);
   });
 
   it('should default control options to null', () => {

package/test/args-parser.js

@@ -859,7 +859,7 @@ describe('output-format option', () => {
   it('should throw error for output-format without status', () => {
     assert.throws(() => {
       parseArgs(['--output-format', 'json', '--', 'npm', 'test']);
-    }, /--output-format option is only valid with --status, --list, --resume, or --resume-all/);
+    }, /--output-format option is only valid with --status, --list, --resume, --resume-all, --pause, or --unpause/);
   });
 
   it('should accept all valid output formats', () => {

package/test/fixtures/pause-golden.cjs

@@ -0,0 +1,142 @@
+/**
+ * Issue #263: runs one `pause-control` shared golden case
+ * (parity/fixtures/contracts.json) through the JavaScript `--pause` /
+ * `--unpause` control path. rust/tests/shared_golden.rs runs the same cases
+ * through the Rust path, so both runtimes are held to identical reports,
+ * errors, docker argv and persisted records.
+ *
+ * The in-memory docker follows the rules spelled out in
+ * `pause-control.docker` of the fixture file; keep it in step with
+ * `GoldenDocker` in rust/tests/shared_golden.rs.
+ */
+
+const TIMESTAMP =
+  /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})/g;
+
+/** Replace every ISO-8601 timestamp, which differs per run, with a marker. */
+function normalize(value) {
+  if (typeof value === 'string') {
+    return value.replace(TIMESTAMP, '<timestamp>');
+  }
+  if (Array.isArray(value)) {
+    return value.map(normalize);
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, normalize(entry)])
+    );
+  }
+  return value;
+}
+
+function goldenDocker(initial, name) {
+  const docker = { state: initial, calls: [] };
+  const ok = (stdout = '') => ({
+    success: true,
+    stdout,
+    stderr: '',
+    status: 0,
+    error: null,
+  });
+  const fail = (stderr) => ({
+    success: false,
+    stdout: '',
+    stderr,
+    status: 1,
+    error: null,
+  });
+  docker.runner = (command, args, extra = {}) => {
+    docker.calls.push({ args: [...args], bounded: Boolean(extra.timeout) });
+    const verb = args[0];
+    if (docker.state === 'removed' && verb !== 'rm') {
+      return fail(`Error response from daemon: No such container: ${name}`);
+    }
+    const alive = docker.state === 'running' || docker.state === 'paused';
+    switch (verb) {
+      case 'inspect': {
+        const format = args[args.indexOf('-f') + 1];
+        if (format === '{{.State.Status}} {{.State.Paused}}') {
+          return ok(`${docker.state} ${docker.state === 'paused'}\n`);
+        }
+        if (format === '{{.State.Status}}') {
+          return ok(`${docker.state}\n`);
+        }
+        if (format === '{{.Id}} {{.State.Pid}}') {
+          return ok(`abc263def ${alive ? 4242 : 0}\n`);
+        }
+        return ok('');
+      }
+      case 'pause':
+        if (docker.state !== 'running') {
+          return fail(`container ${name} is not running`);
+        }
+        docker.state = 'paused';
+        return ok(`${name}\n`);
+      case 'unpause':
+        if (docker.state !== 'paused') {
+          return fail(`container ${name} is not paused`);
+        }
+        docker.state = 'running';
+        return ok(`${name}\n`);
+      default:
+        return ok('');
+    }
+  };
+  return docker;
+}
+
+/**
+ * Run one case and return its normalized observable result.
+ * @param {{ExecutionRecord: Function, pause: object}} modules - Code under test
+ * @param {object} store - An empty ExecutionStore
+ * @param {object} section - `pause-control` from the contracts file
+ * @param {object} fixture - One of `section.cases`
+ * @returns {object} The value `fixture.expected` must equal
+ */
+function runPauseCase({ ExecutionRecord, pause }, store, section, fixture) {
+  const base = section.record;
+  store.save(
+    ExecutionRecord.fromObject({
+      ...base,
+      status: fixture.status || base.status,
+      exitCode:
+        fixture.exitCode === undefined ? base.exitCode : fixture.exitCode,
+      options: { ...base.options, ...(fixture.options || {}) },
+    })
+  );
+  const docker = goldenDocker(fixture.docker, base.options.sessionName);
+  const deps = {
+    runner: docker.runner,
+    outputFormat: fixture.outputFormat,
+    reason: fixture.reason,
+    by: fixture.by,
+  };
+  const result =
+    fixture.action === 'pause'
+      ? pause.pauseExecution(store, fixture.identifier, deps)
+      : pause.unpauseExecution(store, fixture.identifier, deps);
+  const saved = store.get(base.uuid).toObject();
+  let output = result.output === undefined ? null : result.output;
+  if (output !== null && fixture.outputFormat === 'json') {
+    output = JSON.parse(output);
+  }
+  return normalize({
+    success: result.success,
+    output,
+    error: result.error === undefined ? null : result.error,
+    dockerCalls: docker.calls.map((call) => call.args),
+    unboundedDockerCalls: docker.calls
+      .filter((call) => !call.bounded)
+      .map((call) => call.args),
+    dockerState: docker.state,
+    record: {
+      status: saved.status,
+      exitCode: saved.exitCode === undefined ? null : saved.exitCode,
+      containerState:
+        saved.containerState === undefined ? null : saved.containerState,
+      options: saved.options,
+    },
+  });
+}
+
+module.exports = { normalize, goldenDocker, runPauseCase };

package/test/regression-243.js

@@ -82,6 +82,9 @@ const CONTAINERS = [
   '.State.OOMKilled': String(oom),
   '.State.StartedAt': startedAt || '0001-01-01T00:00:00Z',
   '.State.FinishedAt': finishedAt || '0001-01-01T00:00:00Z',
+  // Paused state for --status/--list (issue #263).
+  '.State.Status': running ? 'running' : 'exited',
+  '.State.Paused': 'false',
 }));
 
 /**
@@ -290,7 +293,7 @@ posix('issue #243: one docker inspect per query, same output', () => {
 });
 
 describe('issue #243: batched inspect answers', () => {
-  const row = (name, id) => `/${name} ${id} 7 true 0 false s f`;
+  const row = (name, id) => `/${name} ${id} 7 true 0 false s f running false`;
 
   it('matches lines by name or ID prefix, not by order', () => {
     const answers = parseBatchInspect(