start-command 0.34.0 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # start-command
 
+## 0.35.0
+
+### Minor Changes
+
+- 9679323: Keep Docker resource limits across `--resume <id> -- <command>`, and add `--on-kill-resume <N>` / `--recovery-command <cmd>`. `docker commit` does not capture HostConfig, so the snapshot resume now reads the stopped container's limits with `docker inspect` (including ones applied later with `docker update`) and re-applies the non-default ones (`--memory`, `--memory-swap`, `--memory-reservation`, `--cpus`/`--cpu-quota`/`--cpu-period`, `--cpu-shares`, `--cpuset-cpus`, `--cpuset-mems`, `--pids-limit`, `--shm-size`, `--storage-opt`, `--ulimit`) to the `-resume-N` container, prints them as `[Isolation] Resource limits: ...` and stores them as `resourceLimits`. With `--on-kill-resume <N>` a detached Docker execution whose main process is killed (exit 137 or `OOMKilled`) is resumed in the same container up to N times, running `--recovery-command` (or the original command) with `START_COMMAND_RECOVERY_ATTEMPT` set. The UUID and log file are kept, each attempt is separated by a `[Recovery k/N]` line, and `--status` shows `recoveryAttempts` and `recoveryHistory`. `--stop` cancels further recovery.
+
+## 0.34.1
+
+### Patch Changes
+
+- 2dd9a41: Never finalize a still-running detached Docker container as a success. `docker logs -f` also returns when its own write to the log fails (ENOSPC) or when dockerd restarts, so the completion watcher now asks `docker inspect -f '{{.State.Running}}'` and keeps waiting with `docker wait` until the container really exits. If the watcher still sees a running container, it notes this in the log and leaves the container and the execution record alone: no `docker rm -f`, no `Exit Code: 0` footer, and no `executed` status. A zero `FinishedAt` (`0001-01-01T00:00:00Z`) combined with an exit code of 0 is recorded as `-1` with `exitReason: watcher-lost-container`, not as a success. A child process that is killed by a signal now reports `128+n` (for example `137` for SIGKILL) instead of `0` in `runWithNodeSpawn`, `runAsIsolatedUser` and the command-stream wrapper.
+
 ## 0.34.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {
@@ -72,7 +72,7 @@
     "lino-objects-codec": "^0.4.0"
   },
   "overrides": {
-    "brace-expansion": "^5.0.9",
+    "brace-expansion": "^5.0.12",
     "flatted": "^3.4.2",
     "js-yaml": "^4.3.2"
   }

package/src/bin/cli.js

@@ -38,6 +38,7 @@ const { dispatchQueryCommand, hasQueryMode } = require('../lib/query-commands');
 const { printVersion } = require('../lib/version');
 const { createStartBlock, createFinishBlock } = require('../lib/output-blocks');
 const { runWithBunSpawn, runWithNodeSpawn } = require('../lib/spawn-helpers');
+const { resolveChildExitCode } = require('../lib/exit-reason');
 const { printUsage } = require('../lib/usage');
 const { buildDisplayCommand, getCommandName } = require('../lib/shell-utils');
 
@@ -820,7 +821,7 @@ async function runDirectWithCommandStream(
     // Use raw() to pass the command without auto-escaping
     // This is important for complex commands with pipes, redirects, etc.
     const result = await $cmd`${raw(cmd)}`;
-    exitCode = result.code || 0;
+    exitCode = resolveChildExitCode(result.code);
 
     // Update PID if available from result
     if (executionRecord && result.pid) {

package/src/lib/args-parser.js

@@ -43,6 +43,7 @@
 
 const { getDefaultDockerImage } = require('./docker-utils');
 const dockerNetworkOptions = require('./docker-network-options');
+const dockerRecoveryOptions = require('./docker-recovery-options');
 const { parseSequence, isSequence } = require('./sequence-parser');
 const { buildCommandString } = require('./shell-utils');
 const {
@@ -194,6 +195,8 @@ function parseArgs(args) {
     network: null, // First Docker network name (compatibility accessor)
     networks: [], // Ordered Docker network names
     networkAliases: [], // Docker network-scoped aliases
+    onKillResume: null, // Resume up to N times when the docker main process is killed (issue #176)
+    recoveryCommand: null, // Command run in the same container on such a resume (issue #176)
     endpoint: null, // SSH endpoint (current level, e.g., user@host)
     endpointStack: null, // SSH endpoints for each level (with nulls for non-ssh levels)
     user: false, // Create isolated user
@@ -410,6 +413,11 @@ function parseOption(args, index, options) {
     return networkOption;
   }
 
+  const recoveryOption = dockerRecoveryOptions.parse(args, index, options);
+  if (recoveryOption) {
+    return recoveryOption;
+  }
+
   // --endpoint (for ssh) - supports sequence for stacked isolation
   if (arg === '--endpoint') {
     if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
@@ -746,6 +754,8 @@ function validateOptions(options) {
     validateDockerRuntimeOptionsRequireDocker(options);
   }
 
+  dockerRecoveryOptions.validate(options);
+
   // Session name is only valid with isolation
   if (options.session && !options.isolated) {
     throw new Error('--session option is only valid with --isolated');

package/src/lib/command-stream.js

@@ -11,6 +11,8 @@
  * - Real-time output capture
  */
 
+const { resolveChildExitCode } = require('./exit-reason');
+
 // Debug mode from environment
 const DEBUG =
   process.env.START_DEBUG === '1' || process.env.START_DEBUG === 'true';
@@ -54,7 +56,7 @@ async function execCommand(command, options = {}) {
     return {
       stdout: (result.stdout || '').trim(),
       stderr: (result.stderr || '').trim(),
-      code: result.code || 0,
+      code: resolveChildExitCode(result.code),
     };
   } catch (err) {
     if (DEBUG) {
@@ -91,7 +93,7 @@ async function execCommandAsync(command, options = {}) {
     return {
       stdout: (result.stdout || '').trim(),
       stderr: (result.stderr || '').trim(),
-      code: result.code || 0,
+      code: resolveChildExitCode(result.code),
     };
   } catch (err) {
     if (DEBUG) {

package/src/lib/detached-finalize.js

@@ -34,6 +34,13 @@ const END_TIME_SOURCE = {
   OBSERVED_AT: 'observed-at',
 };
 
+/**
+ * `exitReason` of a record whose container exit the watcher never observed:
+ * docker had no `FinishedAt` for it, so neither the exit code nor the end time
+ * is a fact (issue #174).
+ */
+const WATCHER_LOST_CONTAINER = 'watcher-lost-container';
+
 /**
  * Persist the terminal state of a detached execution.
  *
@@ -49,6 +56,7 @@ const END_TIME_SOURCE = {
  * @param {string|null} [options.startedAt] - `.State.StartedAt`
  * @param {string|null} [options.finishedAt] - `.State.FinishedAt`
  * @param {string|null} [options.containerError] - `.State.Error`
+ * @param {boolean|string|null} [options.running] - `.State.Running`
  * @returns {{updated: boolean, reason?: string, record?: Object}} Outcome
  */
 function finalizeDetachedExecution(options = {}) {
@@ -56,6 +64,11 @@ function finalizeDetachedExecution(options = {}) {
   if (!store || !executionId) {
     return { updated: false, reason: 'missing-arguments' };
   }
+  if (normalizeBoolean(options.running) === true) {
+    // A running container has not finished: its record stays `executing`, and
+    // `--status` keeps probing the live container (issue #174).
+    return { updated: false, reason: 'still-running' };
+  }
 
   let record;
   try {
@@ -72,15 +85,22 @@ function finalizeDetachedExecution(options = {}) {
     return { updated: false, reason: 'already-final', record };
   }
 
+  const finishedAt = normalizeDockerTimestamp(options.finishedAt);
   const described = describeExitCode(options.exitCode);
+  // Without a `FinishedAt`, `ExitCode=0` is Docker's zero value for a container
+  // that has not finished — never an observed success (issue #174).
+  const exitCode = described.code === 0 && !finishedAt ? null : described.code;
   record.status = 'executed';
-  if (described.code !== null) {
-    record.exitCode = described.code;
-  } else if (record.exitCode === null || record.exitCode === undefined) {
+  if (exitCode !== null) {
+    record.exitCode = exitCode;
+  } else if (
+    record.exitCode === null ||
+    record.exitCode === undefined ||
+    !finishedAt
+  ) {
     record.exitCode = -1;
   }
 
-  const finishedAt = normalizeDockerTimestamp(options.finishedAt);
   if (finishedAt) {
     record.endTime = new Date(finishedAt).toISOString();
     record.endTimeSource = END_TIME_SOURCE.DOCKER_FINISHED_AT;
@@ -103,7 +123,8 @@ function finalizeDetachedExecution(options = {}) {
     record.oomKilled = oomKilled;
   }
 
-  const exitReason = resolveReason(record);
+  const exitReason =
+    resolveReason(record) || (finishedAt ? null : WATCHER_LOST_CONTAINER);
   if (exitReason) {
     record.exitReason = exitReason;
   }
@@ -222,14 +243,14 @@ function buildDetachedFinalizeSnippet(executionId) {
   return (
     `${shellQuote(process.execPath)} ${shellQuote(__filename)} ` +
     `${shellQuote(executionId)} "$${v.exit}" "$${v.oom}" ` +
-    `"$${v.started}" "$${v.finished}" "$${v.error}" ` +
+    `"$${v.started}" "$${v.finished}" "$${v.error}" "$${v.running}" ` +
     `>/dev/null 2>&1 || true`
   );
 }
 
 /**
  * Entry point used by the detached watcher:
- *   <runtime> detached-finalize.js <uuid> <exit> <oom> <started> <finished> <error>
+ *   <runtime> detached-finalize.js <uuid> <exit> <oom> <started> <finished> <error> <running>
  * Always exits 0 — a bookkeeping failure must never turn into a visible error
  * in a log the user is reading for the command's own output.
  * @param {string[]} argv - Positional arguments
@@ -243,6 +264,7 @@ function main(argv) {
     startedAt,
     finishedAt,
     containerError,
+    running,
   ] = argv;
   if (!executionId || process.env.START_DISABLE_TRACKING === 'true') {
     return;
@@ -262,6 +284,7 @@ function main(argv) {
       startedAt,
       finishedAt,
       containerError,
+      running,
     });
   } catch {
     // Deliberately silent: see the exit-0 contract above.
@@ -274,6 +297,7 @@ if (require.main === module) {
 
 module.exports = {
   END_TIME_SOURCE,
+  WATCHER_LOST_CONTAINER,
   buildDetachedFinalizeSnippet,
   finalizeDetachedExecution,
   main,

package/src/lib/docker-cleanup.js

@@ -11,10 +11,13 @@ const {
   buildDockerPostMortemSnippet,
   buildDockerRemovalNoteSnippet,
   buildDockerStateSnippet,
+  buildDockerStillRunningNoteSnippet,
+  buildDockerWaitForExitSnippet,
   DOCKER_STATE_INSPECT_FORMAT,
   formatContainerPostMortem,
   formatContainerRemovalNote,
   normalizeDockerTimestamp,
+  SHELL_VARS,
 } = require('./docker-post-mortem');
 const { buildDetachedFinalizeSnippet } = require('./detached-finalize');
 
@@ -312,20 +315,38 @@ function buildSuccessfulNonOomCondition() {
  *   3. it hands the same facts to the finalizer so the execution record stops
  *      being `executing` forever (issue #170.1).
  *
+ * It only does any of that once the container has really exited: the return of
+ * `docker logs -f` / `docker wait` is not proof of exit (issue #174). A
+ * container that is somehow still running afterwards is never removed, gets no
+ * `Exit Code:` footer and is never finalized — its record stays `executing`.
+ *
+ * With `recoverOnKill` (issue #176), a killed main process (exit 137 or
+ * `OOMKilled`) is first handed to the recovery entry point. When it resumes
+ * the container, this watcher stops here — a new one follows the resumed run —
+ * and cleanup, footer and finalization are left to whichever watcher sees the
+ * last run end.
+ *
  * @param {string} containerName - Docker container name
  * @param {string} policy - One of DOCKER_CONTAINER_CLEANUP_POLICY
  * @param {string|null} logPath - Log file to append to, or null
  * @param {string|null} [executionId] - Execution UUID to finalize, or null
+ * @param {{since?: string, recoverOnKill?: boolean}} [watcherOptions] -
+ *   `since` limits `docker logs` to output after a restart, so a resumed run
+ *   does not copy the previous run's output into the log again
  * @returns {string} The shell script
  */
 function buildDetachedDockerCompletionScript(
   containerName,
   policy,
   logPath,
-  executionId = null
+  executionId = null,
+  watcherOptions = {}
 ) {
   const quotedName = shellQuote(containerName);
   const parts = [];
+  // Everything that assumes the container has exited: cleanup, footer and
+  // finalization. Guarded as a whole by `.State.Running` below.
+  const exited = [];
 
   if (logPath) {
     const quotedLogPath = shellQuote(logPath);
@@ -340,34 +361,39 @@ function buildDetachedDockerCompletionScript(
     const remove = `docker rm -f ${quotedName} >> ${quotedLogPath} 2>&1 || true; ${removalNote}`;
     const keep = `${postMortem}; ${buildDockerKeptLogSnippet(containerName, quotedLogPath)}`;
 
-    parts.push(`docker logs -f ${quotedName} >> ${quotedLogPath} 2>&1`);
+    const since = watcherOptions.since
+      ? ` --since ${shellQuote(watcherOptions.since)}`
+      : '';
+    parts.push(`docker logs -f${since} ${quotedName} >> ${quotedLogPath} 2>&1`);
+    parts.push(buildDockerWaitForExitSnippet(containerName, quotedLogPath));
     parts.push(buildDockerStateSnippet(containerName));
     if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS) {
-      parts.push(remove);
+      exited.push(remove);
     } else if (
       policy === DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT ||
       policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL
     ) {
-      parts.push(
+      exited.push(
         `if ${buildSuccessfulNonOomCondition()}; then ${remove}; else ${keep}; fi`
       );
     } else {
       // KEEP: the container is never removed, so the log used to end with the
       // raw command output and nothing else. The post-mortem is exactly the
       // information an operator needs before deciding what to do with it.
-      parts.push(keep);
+      exited.push(keep);
     }
-    parts.push(`${createShellLogFooterSnippet()} >> ${quotedLogPath}`);
+    exited.push(`${createShellLogFooterSnippet()} >> ${quotedLogPath}`);
   } else {
     parts.push(`docker wait ${quotedName} >/dev/null 2>&1`);
+    parts.push(buildDockerWaitForExitSnippet(containerName));
     parts.push(buildDockerStateSnippet(containerName));
     if (policy === DOCKER_CONTAINER_CLEANUP_POLICY.ALWAYS) {
-      parts.push(`docker rm -f ${quotedName} >/dev/null 2>&1 || true`);
+      exited.push(`docker rm -f ${quotedName} >/dev/null 2>&1 || true`);
     } else if (
       policy === DOCKER_CONTAINER_CLEANUP_POLICY.DEFAULT ||
       policy === DOCKER_CONTAINER_CLEANUP_POLICY.KEEP_ON_FAIL
     ) {
-      parts.push(
+      exited.push(
         `if ${buildSuccessfulNonOomCondition()}; then docker rm -f ${quotedName} >/dev/null 2>&1 || true; fi`
       );
     }
@@ -375,9 +401,23 @@ function buildDetachedDockerCompletionScript(
 
   if (executionId) {
     // Last, so the record is only marked terminal once the log is complete.
-    parts.push(buildDetachedFinalizeSnippet(executionId));
+    exited.push(buildDetachedFinalizeSnippet(executionId));
   }
 
+  const stillRunning = logPath
+    ? buildDockerStillRunningNoteSnippet(containerName, shellQuote(logPath))
+    : ':';
+  let recovery = '';
+  if (executionId && watcherOptions.recoverOnKill) {
+    // Lazily required: the recovery module starts watchers itself.
+    const { buildRecoverySnippet } = require('./execution-recovery');
+    recovery = `elif ${buildRecoverySnippet(executionId)}; then :; `;
+  }
+  parts.push(
+    `if [ "$${SHELL_VARS.running}" = true ]; then ${stillRunning}; ` +
+      `${recovery}else ${exited.length ? exited.join('; ') : ':'}; fi`
+  );
+
   return parts.join('; ');
 }
 
@@ -387,13 +427,16 @@ function buildDetachedDockerCompletionScript(
  * @param {string} policy - One of DOCKER_CONTAINER_CLEANUP_POLICY
  * @param {string|null} logPath - Log file to append to, or null
  * @param {string|null} [executionId] - Execution UUID to finalize, or null
+ * @param {{since?: string, recoverOnKill?: boolean}} [watcherOptions] - See
+ *   `buildDetachedDockerCompletionScript`
  * @returns {void}
  */
 function startDetachedDockerCompletionWatcher(
   containerName,
   policy,
   logPath,
-  executionId = null
+  executionId = null,
+  watcherOptions = {}
 ) {
   const watcher = spawn(
     'sh',
@@ -403,7 +446,8 @@ function startDetachedDockerCompletionWatcher(
         containerName,
         policy,
         logPath,
-        executionId
+        executionId,
+        watcherOptions
       ),
     ],
     {

package/src/lib/docker-post-mortem.js

@@ -138,15 +138,83 @@ const SHELL_VARS = {
   signal: '__start_command_signal',
   exitText: '__start_command_exit_text',
   lifetime: '__start_command_lifetime',
+  running: '__start_command_running',
 };
 
 /** `docker inspect -f` template collecting every post-mortem fact at once. */
 const DOCKER_STATE_INSPECT_FORMAT =
   '{{.State.ExitCode}} {{.State.OOMKilled}} {{.State.StartedAt}} {{.State.FinishedAt}}';
 
+/** `docker inspect -f` template answering "is the container still running?". */
+const DOCKER_RUNNING_INSPECT_FORMAT = '{{.State.Running}}';
+
+/**
+ * Written into the log when `docker logs -f` returned while the container was
+ * still running (issue #174).
+ */
+const LOG_CAPTURE_STOPPED_NOTE =
+  'Log capture stopped early: docker logs -f returned while the container ' +
+  'was still running (a failed write to this log such as ENOSPC, or a dockerd ' +
+  'restart). Waiting for the container to exit.';
+
+/**
+ * Written into the log when the watcher gave up while the container was still
+ * running. No footer follows: an `Exit Code:` line would be a fabrication.
+ */
+const STILL_RUNNING_NOTE =
+  'The watcher stopped observing it before it exited, so it was not removed ' +
+  'and the execution record stays executing.';
+
+/**
+ * Shell condition that holds while the container is running.
+ * @param {string} quotedName - Already shell-quoted container name
+ * @returns {string} Shell condition
+ */
+function buildDockerRunningCondition(quotedName) {
+  return `[ "$(docker inspect -f '${DOCKER_RUNNING_INSPECT_FORMAT}' ${quotedName} 2>/dev/null)" = true ]`;
+}
+
+/**
+ * Shell fragment blocking until the container has really exited.
+ *
+ * `docker logs -f` and `docker wait` both return early when the *stream* ends
+ * rather than the container: `docker logs -f C >> LOG` returns as soon as its
+ * own write to LOG fails (ENOSPC, when the container filled the disk the log
+ * lives on), and both return when dockerd restarts under live-restore while the
+ * container keeps running. The watcher used to take that return as the
+ * container's exit, inspect a *running* container — Docker reports its zero
+ * values `ExitCode=0 FinishedAt=0001-01-01T00:00:00Z` — and `docker rm -f` the
+ * live workload as a success (issue #174). So the fragment loops on
+ * `.State.Running`, not on the return of the command it waited on; `sleep 1`
+ * keeps a failing `docker wait` from spinning.
+ *
+ * @param {string} containerName - Container to wait for
+ * @param {string|null} [quotedLogPath] - Already shell-quoted log path, to
+ *   record that log capture stopped early; null when there is no log
+ * @returns {string} Shell command
+ */
+function buildDockerWaitForExitSnippet(containerName, quotedLogPath = null) {
+  const quotedName = shellQuote(containerName);
+  const running = buildDockerRunningCondition(quotedName);
+  const parts = [];
+  if (quotedLogPath) {
+    parts.push(
+      `if ${running}; then printf '\\n%s\\n' ${shellQuote(LOG_CAPTURE_STOPPED_NOTE)} >> ${quotedLogPath} 2>/dev/null; fi`
+    );
+  }
+  parts.push(
+    `while ${running}; do docker wait ${quotedName} >/dev/null 2>&1 || sleep 1; done`
+  );
+  return parts.join('; ');
+}
+
 /**
  * Shell fragment reading the container's terminal state.
  *
+ * Also records `.State.Running` in `$__start_command_running`, so the caller
+ * can refuse to remove or finalize a container that is still alive
+ * (issue #174).
+ *
  * The four whitespace-free fields are split with `set --` rather than the
  * `${var%% *}` / `${var##* }` pair the two-field version used: those only ever
  * reach the first and the last field. `State.Error` is read separately because
@@ -168,6 +236,10 @@ function buildDockerStateSnippet(containerName) {
     `${v.error}=$(docker inspect -f '{{.State.Error}}' ${quotedName} 2>/dev/null)`,
     `case "$${v.started}" in ${DOCKER_ZERO_TIME}|'') ${v.started}=${UNKNOWN};; esac`,
     `case "$${v.finished}" in ${DOCKER_ZERO_TIME}|'') ${v.finished}=${UNKNOWN};; esac`,
+    // `ExitCode=0` next to a zero `FinishedAt` is Docker's zero value for a
+    // container that has not finished, never an observed exit 0 (issue #174).
+    `if [ "$${v.finished}" = ${UNKNOWN} ] && [ "$${v.exit}" = 0 ]; then ${v.exit}=-1; fi`,
+    `${v.running}=$(docker inspect -f '${DOCKER_RUNNING_INSPECT_FORMAT}' ${quotedName} 2>/dev/null)`,
     buildSignalDecodeSnippet(),
     buildLifetimeSnippet(),
   ].join('; ');
@@ -252,6 +324,21 @@ function buildDockerPostMortemSnippet(containerName, quotedLogPath) {
   );
 }
 
+/**
+ * Shell fragment appending the note for a container the watcher lost while it
+ * was still running (issue #174).
+ * @param {string} containerName - Container that is still running
+ * @param {string} quotedLogPath - Already shell-quoted log path
+ * @returns {string} Shell command
+ */
+function buildDockerStillRunningNoteSnippet(containerName, quotedLogPath) {
+  const quotedName = shellQuote(containerName);
+  return (
+    `printf '\\nContainer still running: %s\\n%s\\nCheck it with: docker inspect %s\\n' ` +
+    `${quotedName} ${shellQuote(STILL_RUNNING_NOTE)} ${quotedName} >> ${quotedLogPath}`
+  );
+}
+
 /**
  * Shell fragment appending the one-line note for a removed container.
  * @param {string} containerName - Container that was removed
@@ -270,15 +357,21 @@ function buildDockerRemovalNoteSnippet(containerName, quotedLogPath) {
 }
 
 module.exports = {
+  DOCKER_RUNNING_INSPECT_FORMAT,
   DOCKER_STATE_INSPECT_FORMAT,
   DOCKER_ZERO_TIME,
+  LOG_CAPTURE_STOPPED_NOTE,
+  STILL_RUNNING_NOTE,
   NO_ERROR,
   POST_MORTEM_HEADER,
   SHELL_VARS,
   UNKNOWN,
   buildDockerPostMortemSnippet,
   buildDockerRemovalNoteSnippet,
+  buildDockerRunningCondition,
   buildDockerStateSnippet,
+  buildDockerStillRunningNoteSnippet,
+  buildDockerWaitForExitSnippet,
   buildLifetimeSnippet,
   buildSignalDecodeSnippet,
   describeExitCode,

package/src/lib/docker-recovery-options.js

@@ -0,0 +1,84 @@
+/**
+ * Parse and validate the launch-time recovery options (issue #176):
+ *   --on-kill-resume <N>        resume up to N times when the main process is
+ *                               killed (exit 137 / OOMKilled)
+ *   --recovery-command <cmd>    command to run in the same container on resume
+ *                               (without it, the original command is re-run)
+ */
+
+function parseOnKillResumeValue(value) {
+  const text = String(value).trim();
+  const count = Number(text);
+  if (!/^\d+$/.test(text) || !Number.isSafeInteger(count) || count < 1) {
+    throw new Error(
+      `Invalid --on-kill-resume value: "${value}". Expected a positive integer.`
+    );
+  }
+  return count;
+}
+
+function parseDockerRecoveryOption(args, index, options) {
+  const arg = args[index];
+  if (arg === '--on-kill-resume' || arg === '--recovery-command') {
+    if (index + 1 >= args.length || args[index + 1].startsWith('-')) {
+      const value = arg === '--on-kill-resume' ? 'count' : 'command';
+      throw new Error(`Option ${arg} requires a ${value} argument`);
+    }
+    if (arg === '--on-kill-resume') {
+      options.onKillResume = parseOnKillResumeValue(args[index + 1]);
+    } else {
+      options.recoveryCommand = args[index + 1];
+    }
+    return 2;
+  }
+  if (arg.startsWith('--on-kill-resume=')) {
+    options.onKillResume = parseOnKillResumeValue(
+      arg.slice('--on-kill-resume='.length)
+    );
+    return 1;
+  }
+  if (arg.startsWith('--recovery-command=')) {
+    options.recoveryCommand = arg.slice('--recovery-command='.length);
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ * Recovery is driven by the detached docker completion watcher, so it needs a
+ * detached session whose only isolation level is docker. A recovery command on
+ * its own implies one attempt.
+ * @param {object} options - Parsed options
+ * @throws {Error} If the recovery options are used where they cannot work
+ */
+function validateDockerRecoveryOptions(options) {
+  if (
+    options.recoveryCommand !== null &&
+    options.recoveryCommand !== undefined
+  ) {
+    if (String(options.recoveryCommand).trim() === '') {
+      throw new Error('--recovery-command requires a non-empty command');
+    }
+    options.onKillResume ??= 1;
+  }
+  if (!options.onKillResume) {
+    return;
+  }
+  const flag = options.recoveryCommand
+    ? '--recovery-command'
+    : '--on-kill-resume';
+  const stack = options.isolatedStack || [options.isolated];
+  if (!options.isolated || stack.length !== 1 || stack[0] !== 'docker') {
+    throw new Error(
+      `${flag} option is only valid with --isolated docker as the only isolation level`
+    );
+  }
+  if (!options.detached) {
+    throw new Error(`${flag} option requires --detached`);
+  }
+}
+
+module.exports = {
+  parse: parseDockerRecoveryOption,
+  validate: validateDockerRecoveryOptions,
+};