start-command 0.43.0 → 0.44.0

package/.changeset/README.md

@@ -5,4 +5,4 @@ with multi-package repos, or single-package repos to help you version and publis
 find the full documentation for it [in our repository](https://github.com/changesets/changesets)
 
 We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/faq.md)

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # start-command
 
+## 0.44.0
+
+### Minor Changes
+
+- 76efaf3: `--pause <id>` / `--unpause <id>` freeze and thaw a detached Docker execution in place (#263).
+
+  - **Same execution:** `docker pause` (cgroup freezer) keeps the container, its process (same PID), the execution UUID, record and log; `docker unpause` lets the same process continue. No new execution, attempt or recovery is created. Docker is called with argument arrays and a 30 second timeout.
+  - **Resources:** CPU is released while memory and disk stay allocated; `--stop` frees the RAM. Reports include the resource state and container PID.
+  - **Record:** `paused`, `pausedAt`, `pauseCount`, `pausedBy` and `pauseReason` (`--pause-reason`, `--paused-by`); unpause clears the pause and records `pauseEndedBy`. Pausing an already paused container or unpausing a running one is a no-op; stopped or removed containers fail with a pointer to `--status` and `--resume`. screen and tmux sessions are refused.
+  - **Status:** `--status` reports `dockerState`, `paused` and `pausedAt`; a paused execution stays `executing` and `--list --running` includes it. The recorded pause is reconciled with `docker inspect`, so a daemon restart, reboot or external `docker unpause`/`docker rm` never leaves a stale `paused: true`, and a removed container shows `removed`.
+  - **Guards:** a paused execution is never attached to, resumed (no snapshot), resumed by `--resume-all` (skipped with a reason), cleaned up or completed by the watcher. `--stop`/`--terminate` clear the pause and count as an intentional stop, so `--on-kill-resume` does not restart it.
+  - **Parity:** the JavaScript and Rust pause/unpause paths are held to shared golden contracts (`pause-control` in `parity/fixtures/contracts.json`) covering reports in every output format, errors, docker calls and the saved record.
+
 ## 0.43.0
 
 ### Minor Changes

package/README.md

@@ -27,6 +27,8 @@ $ --list
 $ --help
 $ -i docker -d --label task.tool=codex -- my-task
 $ --attach <id>
+$ --pause <id>
+$ --unpause <id>
 $ --resume <id> -- <command>
 $ --resume-all
 $ --session-id <uuid> --append-attempt -- <command>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {
@@ -49,12 +49,12 @@
   "devDependencies": {
     "@changesets/cli": "^3.0.3",
     "@eslint/js": "^10.0.1",
-    "eslint": "^10.14.0",
+    "eslint": "^10.15.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.7",
     "husky": "^9.1.7",
     "lint-staged": "^17.6.0",
-    "prettier": "^3.9.10"
+    "prettier": "^3.10.1"
   },
   "lint-staged": {
     "*.{js,mjs,cjs}": [
@@ -70,10 +70,10 @@
   "dependencies": {
     "@link-foundation/sensitive-data-sanitizer": "^0.14.0",
     "command-stream": "^2.6.0",
-    "lino-objects-codec": "^0.9.5"
+    "lino-objects-codec": "^0.9.6"
   },
   "overrides": {
-    "brace-expansion": "^5.0.12",
+    "brace-expansion": "^5.0.13",
     "flatted": "^3.4.4"
   }
 }

package/src/lib/args-parser-queries.js

@@ -7,6 +7,8 @@
  *
  * Query modes:   --status, --list [--running]
  * Control modes: --upload-log, --stop, --terminate, --attach [--read-only],
+ *                --pause [--pause-reason <text>] [--paused-by <name>],
+ *                --unpause (issue #263),
  *                --resume [-- <command>], --resume-all,
  *                --cleanup [<uuid-or-session-name>]
  * Naming modes:  --alias <id> <name>, --rename <id> <name> (issue #231)
@@ -33,6 +35,10 @@ function createQueryOptionDefaults() {
     outputFormat: null, // Output format (links-notation, json, text)
     stop: null, // UUID/session name to stop gracefully
     terminate: null, // UUID/session name to terminate immediately
+    pause: null, // UUID/session name of a docker execution to freeze
+    unpause: null, // UUID/session name of a paused docker execution to thaw
+    pauseReason: null, // Why --pause froze the execution (recorded)
+    pausedBy: null, // Who --pause froze the execution for (recorded)
     attach: null, // UUID/session name whose terminal should be attached
     readOnly: false, // Follow --attach output without forwarding stdin
     resume: null, // UUID/session name to resume (optionally with a new command)
@@ -55,6 +61,8 @@ const IDENTIFIER_OPTIONS = {
   '--upload-log': 'uploadLog',
   '--stop': 'stop',
   '--terminate': 'terminate',
+  '--pause': 'pause',
+  '--unpause': 'unpause',
   '--attach': 'attach',
   '--resume': 'resume',
 };
@@ -153,6 +161,32 @@ function parseNamingOption(args, index, options) {
   return 3;
 }
 
+/**
+ * `--pause-reason <text>` and `--paused-by <name>` (issue #263) annotate a
+ * `--pause`; their values may contain spaces but not start with `-`.
+ */
+const PAUSE_DETAIL_OPTIONS = {
+  '--pause-reason': 'pauseReason',
+  '--paused-by': 'pausedBy',
+};
+
+function parsePauseDetailOption(args, index, options) {
+  const arg = args[index];
+  const equals = arg.indexOf('=');
+  const name = equals === -1 ? arg : arg.slice(0, equals);
+  const key = PAUSE_DETAIL_OPTIONS[name];
+  if (!key) {
+    return 0;
+  }
+  const inline = equals !== -1;
+  const value = inline ? arg.slice(equals + 1) : args[index + 1];
+  if (!value || (!inline && value.startsWith('-'))) {
+    throw new Error(`Option ${name} requires a value`);
+  }
+  options[key] = value;
+  return inline ? 1 : 2;
+}
+
 /**
  * Parse a single query/control option.
  * @param {string[]} args - Arguments array
@@ -202,6 +236,11 @@ function parseQueryOption(args, index, options) {
     }
   }
 
+  const pauseDetailConsumed = parsePauseDetailOption(args, index, options);
+  if (pauseDetailConsumed > 0) {
+    return pauseDetailConsumed;
+  }
+
   // --output-format <format>
   if (arg === '--output-format') {
     if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
@@ -242,6 +281,12 @@ function activeQueryModes(options) {
   if (hasValue(options.terminate)) {
     modes.push('--terminate');
   }
+  if (hasValue(options.pause)) {
+    modes.push('--pause');
+  }
+  if (hasValue(options.unpause)) {
+    modes.push('--unpause');
+  }
   if (hasValue(options.attach)) {
     modes.push('--attach');
   }
@@ -266,7 +311,14 @@ function activeQueryModes(options) {
 /**
  * Formats are only meaningful for modes that print a machine-readable report.
  */
-const OUTPUT_FORMAT_MODES = ['--status', '--list', '--resume', '--resume-all'];
+const OUTPUT_FORMAT_MODES = [
+  '--status',
+  '--list',
+  '--resume',
+  '--resume-all',
+  '--pause',
+  '--unpause',
+];
 
 /**
  * Validate query/control options.
@@ -292,7 +344,7 @@ function validateQueryOptions(options) {
 
   if (modes.length > 1) {
     throw new Error(
-      'Cannot combine --status, --list, --upload-log, --stop, --terminate, --attach, --resume, --resume-all, --cleanup, --alias, or --rename in the same invocation'
+      'Cannot combine --status, --list, --upload-log, --stop, --terminate, --pause, --unpause, --attach, --resume, --resume-all, --cleanup, --alias, or --rename in the same invocation'
     );
   }
 
@@ -301,7 +353,7 @@ function validateQueryOptions(options) {
     !modes.some((mode) => OUTPUT_FORMAT_MODES.includes(mode))
   ) {
     throw new Error(
-      '--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'
     );
   }
 
@@ -312,6 +364,15 @@ function validateQueryOptions(options) {
   if (options.readOnly && !hasValue(options.attach)) {
     throw new Error('--read-only option is only valid with --attach');
   }
+
+  if (
+    (hasValue(options.pauseReason) || hasValue(options.pausedBy)) &&
+    !hasValue(options.pause)
+  ) {
+    throw new Error(
+      '--pause-reason and --paused-by options are only valid with --pause'
+    );
+  }
 }
 
 module.exports = {

package/src/lib/docker-inspect-batch.js

@@ -27,6 +27,9 @@ const BATCH_FIELDS = [
   '.State.OOMKilled',
   '.State.StartedAt',
   '.State.FinishedAt',
+  // Paused state for --status/--list (issue #263).
+  '.State.Status',
+  '.State.Paused',
 ];
 const BATCH_FORMAT = BATCH_FIELDS.map((field) => `{{${field}}}`).join(' ');
 const NOT_FOUND_LINE = /no such (?:object|container):\s*(\S+)/gi;

package/src/lib/execution-attach.js

@@ -12,7 +12,11 @@ const { spawnSync } = require('child_process');
 const { escapeForLinksNotation } = require('./output-blocks');
 const { getDockerCommand, getDockerSpawnOptions } = require('./docker-cleanup');
 const { runCommand } = require('./execution-control');
-const { SessionState, probeSession } = require('./session-probe');
+const {
+  SessionState,
+  pausedSessionError,
+  probeSession,
+} = require('./session-probe');
 
 /**
  * Run a command with the parent terminal attached (stdin included unless the
@@ -104,6 +108,11 @@ function buildAttachPlan(record, options = {}) {
     return logFollowPlan(record, backend, sessionName);
   }
 
+  if (probe.state === SessionState.PAUSED) {
+    // `docker attach` to a frozen container would hang (issue #263).
+    return pausedSessionError('attach to', record.uuid, sessionName);
+  }
+
   if (!probe.alive) {
     return notRunningError(record, { ...probe, sessionName });
   }

package/src/lib/execution-cleanup.js

@@ -153,6 +153,14 @@ function cleanupExecution(store, identifier, deps = {}) {
   }
   const runner = deps.runner || runCommand;
   const dryRun = deps.dryRun === true;
+  if (require('./execution-pause').isConfirmedPaused(record, runner)) {
+    // A paused container keeps its process; never remove it (issue #263).
+    return {
+      success: false,
+      output: `Retained container ${record.options.sessionName} (paused)`,
+      error: `${identifier} is paused; nothing was removed. Use \`$ --unpause ${record.uuid}\` or \`$ --stop ${record.uuid}\` first.`,
+    };
+  }
   const plan = planExecutionCleanup(record, runner);
   const outcomes = plan.containers.map((name) =>
     removeObject('container', name, runner, dryRun)

package/src/lib/execution-control.js

@@ -271,16 +271,25 @@ function formatControlResultAsLinksNotation(result) {
   return lines.join('\n');
 }
 
+/**
+ * Whether a deliberate stop must be recorded: with launch-time kill recovery
+ * (issue #176), and for a paused container, whose stop is never a crash
+ * (issue #263).
+ */
+function tracksStopIntent(options) {
+  return Boolean(options.onKillResume) || options.paused === true;
+}
+
 /**
  * Record that a stop was requested, for sessions with launch-time kill
- * recovery (issue #176).
+ * recovery (issue #176) or a recorded pause (issue #263).
  * @param {object} store - Execution store
  * @param {object} record - Execution record
  * @returns {string|undefined} The previous marker, to restore on failure
  */
 function markStopRequested(store, record) {
   const options = record.options || {};
-  if (!options.onKillResume) {
+  if (!tracksStopIntent(options)) {
     return undefined;
   }
   const previous = options.stopRequestedAt;
@@ -294,7 +303,7 @@ function markStopRequested(store, record) {
 }
 
 function restoreStopRequested(store, record, previous) {
-  if (!record.options || !record.options.onKillResume) {
+  if (!tracksStopIntent(record.options || {})) {
     return;
   }
   record.options = { ...record.options, stopRequestedAt: previous };
@@ -374,6 +383,8 @@ function controlExecution(store, identifier, action, runner = runCommand) {
     };
   }
 
+  // Stopping a paused container ends its pause (issue #263).
+  require('./execution-pause').clearPauseAfterControl(store, record, action);
   const output = formatControlResultAsLinksNotation({
     action,
     identifier,