start-command 0.37.9 → 0.39.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # start-command
 
+## 0.39.0
+
+### Minor Changes
+
+- CI/CD no longer reports false results (#234). A rejected `npm publish` or any failing release command now fails the release instead of printing success, and the published version is confirmed on the registry: npm gets up to 20 minutes to show it, and a "cannot publish over" conflict is read as "already landed" rather than retried. A release push that loses the race for `main` is rebased and retried. Releases wait for every check their stage requires. A failing Rust test is reported as a failed test rather than as low coverage. `bun test -t <pattern>` keeps the 30s default timeout. Snapshot-resume tests in both languages use a private snapshot lock. The link checker fails on every broken live link, re-checks transient 429/5xx answers, persists its cache and uploads its report. ESLint warnings fail CI and the pre-commit hook. The changeset PR is opened with `RELEASE_PR_TOKEN` so its checks run. Step outputs reach `run:` blocks through `env`, tool versions are pinned, path-filtered workflows re-run when their scripts change, and the npm-publish tests no longer reach the real npm on macOS.
+
+  Support Docker `--memory-reservation` with sizes, daemon percentages and percentage ranges. Validate the soft cap against the effective hard memory limit, record it in status, and preserve or override it across resumes and recovery.
+
+  Reduce Docker cgroup sampler polling with a configurable five-second default, one namespace lookup per sampler, and local cgroup liveness checks. Set `START_COMMAND_CGROUP_SAMPLE_INTERVAL_SECONDS` to a positive whole number of seconds to override the default for attached and detached runs.
+
+  Main pushes publish again (#240). Since #234 the Release job was skipped on every push to `main`: at job level the wildcard `needs.*.result` list also saw the deliberately skipped changeset check behind `test`/`coverage`. Release now compares each needed job by name, and the JavaScript Stage prints every term of the release condition and fails a main push whose release was skipped although all of its needs succeeded.
+
+  Attribute a Docker daemon restart without the host journal (#241). With a mounted `docker.sock` (Docker-outside-of-Docker) or a remote daemon, an exit-137 task is now reported as `killed (docker daemon restart)` when another container finished within the 15 s shutdown window with exit 137/143, or was started again after it, and was not OOM-killed. `exitEvidence.daemonRestartSource` records whether the host journal or the Docker API supported the attribution, and `--status` collects the evidence itself when the detached watcher died with the daemon before it could log any.
+
+  Sample Docker cgroup counters through one long-lived `docker exec -i` per run when the cgroup is only readable through the daemon (a mounted `docker.sock`). The host paces it with one tick per interval on stdin, so the container runs only shell builtins and the stream ends with the sampler; the per-round exec stays as a fallback. Docker is asked for `{{.State.Running}}` only after a round without a sample, and `START_COMMAND_CGROUP_SAMPLE_INTERVAL_SECONDS=off` disables sampling.
+
+  `$ --status` and `$ --list` cost far less with many records (#243). The store is decoded once per content within a process, and a JSON copy of the decoded records next to `executions.lino` (tagged with the store's SHA-256) lets the next process skip the decode entirely. One `docker inspect --type container` now answers every docker probe of a query instead of one or two processes per record, and records whose container is already marked removed are no longer probed. Output is unchanged; probes the batch cannot answer (an old or stubbed `docker`) run one by one as before.
+
+  `--init` / `--no-init` run Docker's bundled tini (`docker run --init`) as PID 1 for docker isolation, so orphaned processes of a long-running task are reaped instead of piling up as zombies (#244). The default stays off; `START_COMMAND_DOCKER_INIT=1` turns it on for every docker launch on a host, and `--no-init` overrides that. The choice is stored with the record, shown as an `init` row in the start block and in `--status`, and carried into `--resume` snapshots and stacked launches; records from before keep running without it. Exit codes and OOM evidence are unchanged, but `--stop` (`docker stop`) now ends a command without a SIGTERM handler with 143 at once instead of 137 after the grace period.
+
+## 0.38.0
+
+### Minor Changes
+
+- 8e62079: Executions now carry a stable identity a supervisor can rely on. A launch with an explicit `--session-id` that already exists is refused with exit 1 (`execution <uuid> already exists; use $ --resume <uuid> -- <command> to continue it, or pass --append-attempt`) instead of replacing the record and truncating its log; `--append-attempt` keeps the record, archives the previous attempt in `attemptHistory` and appends the new attempt to the same log (#229). Every backend (direct, `--isolated-user`, screen, tmux, docker, ssh, and docker resumes of stopped containers) exports `START_EXECUTION_ID`, `START_SESSION_NAME` and `START_ATTEMPT` to the command it runs (#230). `$ --alias <id> <name>` adds a name and `$ --rename <id> <name>` sets the display name of an execution, `--continues <id>` records the execution a fresh launch continues, `--status` reports `aliases` and the continuation `chain`, and `--upload-log` uploads the logs of the whole chain, oldest first (#231).
+
 ## 0.37.9
 
 ### Patch Changes

package/README.md

@@ -29,6 +29,9 @@ $ -i docker -d --label task.tool=codex -- my-task
 $ --attach <id>
 $ --resume <id> -- <command>
 $ --resume-all
+$ --session-id <uuid> --append-attempt -- <command>
+$ --continues <id> -- <command>
+$ --rename <id> <name>
 ```
 
 See the project-wide [README](../README.md), [docs/USAGE.md](../docs/USAGE.md),
@@ -70,9 +73,11 @@ 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
+Launch with `--memory 64m`, `--memory-swap 64m`, `--memory-reservation 32m` 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.
+to memory. Reservation is a soft cap and must be below the hard memory cap when
+one is set. It accepts the same sizes and percentages, is shown in `--status`,
+and survives resumes. `--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)

package/bunfig.toml

@@ -1,3 +1,7 @@
 # Bun configuration
 # Tests use repository naming without conventional suffixes, so package scripts pass
 # the test files explicitly instead of relying on Bun's default discovery.
+
+[test]
+# Every test process gets a private Docker snapshot lock (issue #234).
+preload = ["./test/setup/private-snapshot-lock.js"]

package/eslint.config.mjs

@@ -25,6 +25,7 @@ export default [
         process: 'readonly',
         Buffer: 'readonly',
         fetch: 'readonly',
+        structuredClone: 'readonly',
         Bun: 'readonly',
       },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.37.9",
+  "version": "0.39.0",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {
@@ -12,12 +12,12 @@
   },
   "scripts": {
     "test": "bun ../scripts/run-js-tests.mjs",
-    "lint": "eslint .",
+    "lint": "eslint . --max-warnings 0",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "check:file-size": "bun ../scripts/check-file-size.mjs",
-    "lint:scripts": "cd .. && eslint .",
+    "lint:scripts": "cd .. && eslint . --max-warnings 0",
     "format:check:scripts": "cd .. && prettier --check \"scripts/**/*.{js,mjs,cjs}\"",
     "check": "bun run lint && bun run lint:scripts && bun run format:check && bun run format:check:scripts && bun run check:file-size",
     "prepare": "cd .. && husky .husky || true",
@@ -58,7 +58,7 @@
   },
   "lint-staged": {
     "*.{js,mjs,cjs}": [
-      "eslint --fix --max-warnings 6",
+      "eslint --fix --max-warnings 0 --no-warn-ignored",
       "prettier --write",
       "prettier --check"
     ],

package/src/bin/cli.js

@@ -18,7 +18,6 @@ const {
   getTimestamp,
   createLogHeader,
   createLogFooter,
-  writeLogFile,
   appendLogFile,
   createLogPath,
   getDefaultDockerImage,
@@ -41,6 +40,7 @@ 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');
+const launchIdentity = require('../lib/launch-identity');
 
 // A closed stdout/stderr pipe (`$ --version | head -1`) must neither crash
 // start nor replace the command's exit code: drop the failed output and keep
@@ -245,6 +245,8 @@ const useCommandStream =
 
 // Generate session ID if not provided (auto-generate UUID)
 const sessionId = wrapperOptions.sessionId || generateUUID();
+// How this launch uses its execution id (issue #229), set before dispatch
+let launch = null;
 
 // Main execution
 (async () => {
@@ -256,6 +258,19 @@ const sessionId = wrapperOptions.sessionId || generateUUID();
     process.exit(queryExitCode === null ? 0 : queryExitCode);
   }
 
+  // An explicit --session-id must not overwrite a tracked execution (#229).
+  try {
+    launch = launchIdentity.prepareLaunch(
+      getExecutionStore(),
+      wrapperOptions,
+      sessionId,
+      createLogPath(wrapperOptions.isolated || 'direct', sessionId)
+    );
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+
   if (wrapperOptions.isolated === 'docker') {
     const {
       resolveResourceOptions,
@@ -314,8 +329,8 @@ async function runWithIsolation(
     effectiveImage = getDefaultDockerImage();
   }
 
-  // Create log file path
-  const logFilePath = createLogPath(environment || 'direct', sessionId);
+  // Create log file path (an appended attempt keeps the execution's log)
+  const logFilePath = launch.logPath;
 
   // Get session name (will be generated by runIsolated if not provided)
   const sessionName =
@@ -424,6 +439,7 @@ async function runWithIsolation(
         useCommandStream,
       },
     });
+    launchIdentity.applyLaunch(executionRecord, launch);
   }
 
   // Print start block with session ID and isolation info
@@ -448,8 +464,13 @@ async function runWithIsolation(
     currentExecutionRecord = executionRecord;
     require('../lib/launch-owner').markLaunch(executionRecord);
     try {
-      store.save(executionRecord);
+      launchIdentity.claimLaunch(store, executionRecord, launch);
     } catch (err) {
+      if (err instanceof launchIdentity.LaunchRefusedError) {
+        console.error(`Error: ${err.message}`);
+        currentExecutionRecord = null;
+        process.exit(1);
+      }
       console.error(
         JSON.stringify({
           code: 'LAUNCH_RESERVATION_FAILED',
@@ -483,7 +504,12 @@ async function runWithIsolation(
     );
   }
 
-  writeLogFile(logFilePath, logContent);
+  launchIdentity.writeLaunchLog(
+    logFilePath,
+    logContent,
+    launch,
+    executionRecord
+  );
 
   let result;
 
@@ -495,6 +521,7 @@ async function runWithIsolation(
       ...options,
       session: sessionName,
       sessionId,
+      attemptNumber: launch.attemptNumber,
       image: effectiveImage,
       endpoint: options.endpoint,
       detached: mode === 'detached',
@@ -513,7 +540,10 @@ async function runWithIsolation(
     });
   } else if (createdUser) {
     // Run directly as the created user (no isolation environment)
-    result = await runAsIsolatedUser(cmd, createdUser);
+    result = await runAsIsolatedUser(
+      launchIdentity.isolatedUserCommand(cmd, sessionId, launch),
+      createdUser
+    );
   } else {
     // This shouldn't happen in isolation mode, but handle gracefully
     result = { success: false, message: 'No isolation configuration provided' };
@@ -637,8 +667,8 @@ async function runDirect(cmd, sessionId) {
   const shell = isWindows ? 'powershell.exe' : process.env.SHELL || '/bin/sh';
   const shellArgs = isWindows ? ['-Command', cmd] : ['-c', cmd];
 
-  // Setup logging
-  const logFilePath = createLogPath('direct', sessionId);
+  // Setup logging (an appended attempt keeps the execution's log)
+  const logFilePath = launch.logPath;
 
   let logContent = '';
   const startTime = getTimestamp();
@@ -666,6 +696,8 @@ async function runDirect(cmd, sessionId) {
         runtimeVersion,
       },
     });
+    launchIdentity.applyLaunch(executionRecord, launch);
+    launchIdentity.claimDirectLaunch(store, executionRecord, launch, config);
     // Set global reference for signal cleanup
     currentExecutionRecord = executionRecord;
   }
@@ -746,7 +778,13 @@ async function runDirect(cmd, sessionId) {
     shell,
     shellArgs,
     logFilePath,
-    logContent,
+    logContent: launchIdentity.launchLogContent(
+      logContent,
+      launch,
+      executionRecord
+    ),
+    appendLog: launch.append,
+    env: launchIdentity.directLaunchEnv(sessionId, launch),
     startTimeMs,
     executionRecord,
     store,
@@ -786,8 +824,8 @@ async function runDirectWithCommandStream(
   const isWindows = process.platform === 'win32';
   const shell = isWindows ? 'powershell.exe' : process.env.SHELL || '/bin/sh';
 
-  // Setup logging
-  const logFilePath = createLogPath('direct', sessionId);
+  // Setup logging (an appended attempt keeps the execution's log)
+  const logFilePath = launch.logPath;
 
   let logContent = '';
   const startTime = getTimestamp();
@@ -816,6 +854,8 @@ async function runDirectWithCommandStream(
         executionMode: 'command-stream',
       },
     });
+    launchIdentity.applyLaunch(executionRecord, launch);
+    launchIdentity.claimDirectLaunch(store, executionRecord, launch, config);
     // Set global reference for signal cleanup
     currentExecutionRecord = executionRecord;
   }
@@ -853,27 +893,23 @@ async function runDirectWithCommandStream(
   console.log('[command-stream] Using command-stream library');
   console.log('');
 
-  // Save initial execution record (PID will be updated later if available)
-  if (executionRecord && store) {
-    try {
-      store.save(executionRecord);
-    } catch (err) {
-      if (config.verbose) {
-        console.error(
-          `[Tracking] Warning: Could not save execution record: ${err.message}`
-        );
-      }
-    }
-  }
-
   // Execute the command using command-stream with real-time output
   // Using mirror: true to show output in real-time, capture: true to collect it
   // Using raw() to avoid auto-escaping that might interfere with complex shell commands
-  const $cmd = $({ mirror: true, capture: true });
+  const $cmd = $({
+    mirror: true,
+    capture: true,
+    env: launchIdentity.directLaunchEnv(sessionId, launch),
+  });
 
   let exitCode;
   try {
-    writeLogFile(logFilePath, logContent);
+    launchIdentity.writeLaunchLog(
+      logFilePath,
+      logContent,
+      launch,
+      executionRecord
+    );
     // 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)}`;

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

@@ -9,6 +9,7 @@
  * Control modes: --upload-log, --stop, --terminate, --attach [--read-only],
  *                --resume [-- <command>], --resume-all,
  *                --cleanup [<uuid-or-session-name>]
+ * Naming modes:  --alias <id> <name>, --rename <id> <name> (issue #231)
  */
 
 /**
@@ -39,6 +40,9 @@ function createQueryOptionDefaults() {
     cleanup: false, // Clean up stale "executing" records
     cleanupDryRun: false, // Show what would be cleaned without cleaning
     cleanupTarget: null, // UUID/session name whose containers and images --cleanup removes
+    alias: null, // Execution that --alias adds a name to
+    rename: null, // Execution that --rename renames
+    newName: null, // Name given by --alias/--rename
   };
 }
 
@@ -120,6 +124,35 @@ function hasValue(value) {
   return value !== null && value !== undefined;
 }
 
+/**
+ * `--alias <id> <name>` and `--rename <id> <name>` take two arguments.
+ */
+const NAMING_OPTIONS = {
+  '--alias': 'alias',
+  '--rename': 'rename',
+};
+
+function parseNamingOption(args, index, options) {
+  const key = NAMING_OPTIONS[args[index]];
+  if (!key) {
+    return 0;
+  }
+  const [identifier, name] = args.slice(index + 1, index + 3);
+  if (
+    identifier === undefined ||
+    name === undefined ||
+    identifier.startsWith('-') ||
+    name.startsWith('-')
+  ) {
+    throw new Error(
+      `Option ${args[index]} requires a UUID or session name and a new name`
+    );
+  }
+  options[key] = identifier;
+  options.newName = name;
+  return 3;
+}
+
 /**
  * Parse a single query/control option.
  * @param {string[]} args - Arguments array
@@ -135,6 +168,11 @@ function parseQueryOption(args, index, options) {
     return cleanupConsumed;
   }
 
+  const namingConsumed = parseNamingOption(args, index, options);
+  if (namingConsumed > 0) {
+    return namingConsumed;
+  }
+
   const flag = FLAG_OPTIONS[arg];
   if (flag) {
     flag(options);
@@ -216,6 +254,12 @@ function activeQueryModes(options) {
   if (options.cleanup) {
     modes.push('--cleanup');
   }
+  if (hasValue(options.alias)) {
+    modes.push('--alias');
+  }
+  if (hasValue(options.rename)) {
+    modes.push('--rename');
+  }
   return modes;
 }
 
@@ -248,7 +292,7 @@ function validateQueryOptions(options) {
 
   if (modes.length > 1) {
     throw new Error(
-      'Cannot combine --status, --list, --upload-log, --stop, --terminate, --attach, --resume, --resume-all, or --cleanup in the same invocation'
+      'Cannot combine --status, --list, --upload-log, --stop, --terminate, --attach, --resume, --resume-all, --cleanup, --alias, or --rename in the same invocation'
     );
   }
 

package/src/lib/args-parser.js

@@ -14,6 +14,7 @@
  * --mount <mount-spec>             Docker --mount spec (repeatable, docker only)
  * --env, -e <KEY=VALUE>            Environment variable for docker container (repeatable, docker only)
  * --privileged                     Run docker container in privileged mode (docker only)
+ * --init, --no-init                Run an init process (tini) as PID 1 to reap orphans (docker only; default START_COMMAND_DOCKER_INIT)
  * --network <name>                 Connect docker container to a named network (repeatable, docker only)
  * --network-alias <alias>          Add an alias to the first network (repeatable, docker only)
  * --endpoint <endpoint>            SSH endpoint (required for ssh isolation, e.g., user@host)
@@ -39,6 +40,7 @@
  * --resume-all                     Re-attach or reconcile every execution still marked running
  * --cleanup [<uuid-or-session>]    Clean up stale "executing" records, or one execution's containers and snapshot images
  * --cleanup-dry-run                Show stale records that would be cleaned up (without actually cleaning)
+ * --alias <id> <name>, --rename <id> <name>, --append-attempt, --continues <id>: see args-parser-queries.js, launch-identity-options.js
  */
 
 const { getDefaultDockerImage } = require('./docker-utils');
@@ -46,7 +48,9 @@ const dockerNetworkOptions = require('./docker-network-options');
 const dockerRecoveryOptions = require('./docker-recovery-options');
 const cpuPenalty = require('./cpu-penalty');
 const dockerResourceOptions = require('./docker-resource-options');
+const dockerInitOption = require('./docker-init-option');
 const snapshotResumeOptions = require('./snapshot-resume-options');
+const launchIdentityOptions = require('./launch-identity-options');
 const { parseSequence, isSequence } = require('./sequence-parser');
 const { buildCommandString } = require('./shell-utils');
 const {
@@ -197,6 +201,7 @@ function parseArgs(args) {
     labels: [], // Caller attribution, applied to every Docker level
     help: false,
     privileged: false, // Run docker container in privileged mode
+    init: null, // docker run --init; null until resolved from START_COMMAND_DOCKER_INIT (issue #244)
     network: null, // First Docker network name (compatibility accessor)
     networks: [], // Ordered Docker network names
     networkAliases: [], // Docker network-scoped aliases
@@ -217,6 +222,7 @@ function parseArgs(args) {
     useCommandStream: false, // Use command-stream library for command execution
     ...createQueryOptionDefaults(),
     ...snapshotResumeOptions.createSnapshotOptionDefaults(),
+    ...launchIdentityOptions.createLaunchIdentityOptionDefaults(),
   };
 
   let commandArgs = [];
@@ -427,6 +433,11 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  // --init / --no-init (for docker, issue #244)
+  if (dockerInitOption.parse(args, index, options)) {
+    return 1;
+  }
+
   const networkOption = dockerNetworkOptions.parse(args, index, options);
   if (networkOption) {
     return networkOption;
@@ -580,6 +591,12 @@ function parseOption(args, index, options) {
     return queryConsumed;
   }
 
+  // --append-attempt, --continues <id> (issues #229, #231)
+  const identityConsumed = launchIdentityOptions.parse(args, index, options);
+  if (identityConsumed > 0) {
+    return identityConsumed;
+  }
+
   // Not a recognized wrapper option
   return 0;
 }
@@ -794,6 +811,7 @@ function validateOptions(options) {
 
   dockerRecoveryOptions.validate(options);
   dockerResourceOptions.validate(options);
+  dockerInitOption.validate(options);
   cpuPenalty.validate(options);
 
   // Session name is only valid with isolation
@@ -830,6 +848,7 @@ function validateOptions(options) {
 
   snapshotResumeOptions.validate(options);
   validateQueryOptions(options);
+  launchIdentityOptions.validate(options);
 
   // Validate shell option
   if (options.shell !== null && options.shell !== undefined) {

package/src/lib/cgroup-memory.js

@@ -27,8 +27,8 @@
 
 const { shellQuote } = require('./isolation-log-utils');
 
-/** Seconds between two samples of a running container's cgroup. */
-const CGROUP_SAMPLE_INTERVAL_SECONDS = 1;
+/** Default seconds between samples; the watcher environment may override it. */
+const CGROUP_SAMPLE_INTERVAL_SECONDS = 5;
 
 /** Shell variables used by the sampler snippets. */
 const CGROUP_SHELL_VARS = {
@@ -74,10 +74,50 @@ function buildCgroupFunctionsSnippet() {
   ].join('; ');
 }
 
+/**
+ * In-container loop of the long-lived sampler exec (issue #242): `$1` is the
+ * cgroup directory. The host paces it with one newline per interval on stdin
+ * (`docker exec -i`), so it runs only shell builtins: the task's own CPU
+ * limit pays for no `cat`, `sed` or `sleep` processes. Stdin reaches EOF when
+ * the exec's client is gone, so the loop never outlives the sampler; dockerd
+ * would accept its output even then. Exit 3: unreadable counters.
+ * @returns {string} Shell script for `sh -c`
+ */
+function buildCgroupStreamScript() {
+  return [
+    'while read -r __scx_tick; do __scx_oom=; __scx_kill=; __scx_max=-; __scx_peak=-',
+    '[ -r "$1/memory.events" ] || exit 3',
+    'while read -r __scx_key __scx_value; do case "$__scx_key" in ' +
+      'oom) __scx_oom=$__scx_value;; oom_kill) __scx_kill=$__scx_value;; esac; ' +
+      'done < "$1/memory.events"',
+    'case "$__scx_oom:$__scx_kill" in *[!0-9:]*|:*|*:) exit 3;; esac',
+    '[ ! -r "$1/memory.max" ] || read -r __scx_max < "$1/memory.max"',
+    '[ ! -r "$1/memory.peak" ] || read -r __scx_peak < "$1/memory.peak"',
+    'printf \'%s %s %s %s %s\\n\' "${__scx_max:--}" "${__scx_peak:--}" ' +
+      '"$__scx_oom" "$__scx_kill" "$1" || exit 0; done',
+  ].join('; ');
+}
+
+/** `$0` of the long-lived exec, visible in `ps` inside the task container. */
+const CGROUP_STREAM_NAME = 'start-command-cgroup-stream';
+
+/** Interval value that turns the sampler off (issue #242). */
+const CGROUP_SAMPLING_OFF_REASON =
+  'sampling disabled by START_COMMAND_CGROUP_SAMPLE_INTERVAL_SECONDS=off';
+
 /**
  * Shell fragment starting the background sampler. It writes each sample to a
  * temp file with `mv`, so the watcher never reads a half-written line, and
- * ends by itself once the cgroup is gone.
+ * ends by itself once the container is gone.
+ *
+ * Where the cgroup is readable locally it reads it directly. Otherwise, with
+ * a private cgroup namespace (a mounted docker.sock), one long-lived
+ * `docker exec -i` answers one host tick per interval (issue #242); a
+ * successful read proves the container runs, so Docker is asked for liveness
+ * only after a failed round or when the stream ends. Without a usable stream it falls back
+ * to one `docker exec` per round; without `sh` in the image (exit 126/127) or
+ * without any readable cgroup it records the reason and stops.
+ * `START_COMMAND_CGROUP_SAMPLE_INTERVAL_SECONDS=off` disables sampling.
  * @param {string} containerName - Container to sample
  * @returns {string} Shell command
  */
@@ -85,32 +125,61 @@ function buildCgroupSamplerStartSnippet(containerName) {
   const v = CGROUP_SHELL_VARS;
   const name = shellQuote(containerName);
   const remoteRead = '__start_command_cgroup_read /sys/fs/cgroup';
+  const unavailable = (detail) =>
+    `printf '%s\\n' "local cgroup unavailable; ${detail}" > "$${v.file}.reason"`;
+  const execReason = unavailable(
+    'Docker exec exit=$__scs_exit: ${__scs_detail:-private cgroup v2 counters unreadable}'
+  );
   return [
     buildCgroupFunctionsSnippet(),
     `${v.file}="\${TMPDIR:-/tmp}/start-command-cgroup.$$"`,
     `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}=$!`,
+    `( export START_COMMAND_CGROUP_SAMPLING=1; ` +
+      // Validate in the watcher, so attached and detached launches inherit the
+      // same setting. Never allow a malformed/zero sleep to create a busy loop.
+      `__scs_interval=\${START_COMMAND_CGROUP_SAMPLE_INTERVAL_SECONDS:-${CGROUP_SAMPLE_INTERVAL_SECONDS}}; ` +
+      `case "$__scs_interval" in [Oo][Ff][Ff]) printf '%s\\n' '${CGROUP_SAMPLING_OFF_REASON}' > "$${v.file}.reason"; exit 0;; ` +
+      `*[!0-9]*|'') __scs_interval=${CGROUP_SAMPLE_INTERVAL_SECONDS};; esac; ` +
+      `[ "$__scs_interval" -gt 0 ] 2>/dev/null || __scs_interval=${CGROUP_SAMPLE_INTERVAL_SECONDS}; ` +
+      // Store one `<max> <peak> <oom> <oom_kill>` line. The previous sample is
+      // read back from the file, so the stream's reader subshell can record
+      // too. The first counter is a baseline, including after watcher restart;
+      // only changes between adjacent samples supply exit-time evidence.
+      `__scs_record() { set -f; set -- $1; set +f; case "$3:$4" in *[!0-9:]*|:*|*:) return 1;; esac; ` +
+      `__scs_now=$(date +%s); __scs_previous=''; __scs_changed=0; __scs_previous_at=0; ` +
+      `[ ! -r "$${v.file}" ] || read -r __scs_p __scs_p __scs_p __scs_previous __scs_changed __scs_previous_at __scs_p < "$${v.file}"; ` +
+      'if [ -n "$__scs_previous" ] && [ "$4" -gt "$__scs_previous" ] 2>/dev/null && [ "$((__scs_now-__scs_previous_at))" -le 3 ]; then __scs_changed=$__scs_now; fi; ' +
+      `printf '%s %s %s %s %s %s %s\\n' "$1" "$2" "$3" "$4" "$__scs_changed" "$__scs_now" "$__scs_dir" > "$${v.file}.tmp" && mv -f "$${v.file}.tmp" "$${v.file}"; }; ` +
+      `__scs_dir=$(__start_command_cgroup_dir ${name}); ` +
+      // The namespace is fixed at container creation, including when reads fail.
+      `__scs_ns=$(docker inspect -f '{{.HostConfig.CgroupnsMode}}' ${name} 2>/dev/null); __scs_stream=1; __scs_reader=''; ` +
+      `while :; do __scs_ok=''; if [ -n "$__scs_dir" ]; then ` +
+      '__scs_line=$(__start_command_cgroup_read "$__scs_dir") && __scs_record "$__scs_line" && __scs_ok=1; ' +
+      `elif [ "$__scs_ns" != private ]; then ${unavailable('container cgroup namespace=${__scs_ns:-unavailable}, private required')}; break; ` +
+      `elif [ "$__scs_stream" = 1 ]; then ` +
+      // The reader ends with the stream; stopping the sampler stops it too.
+      `trap 'kill "$__scs_reader" 2>/dev/null; wait "$__scs_reader" 2>/dev/null; exit 0' TERM; ` +
+      // The ticker runs in the background, so a failed exec is reported at
+      // once; it ends on its first write after the exec is gone.
+      `{ { while :; do echo || exit 0; sleep "$__scs_interval" || exit 0; done 2>/dev/null & } | ` +
+      `docker exec -i ${name} sh -c ${shellQuote(buildCgroupStreamScript())} ${CGROUP_STREAM_NAME} /sys/fs/cgroup 2>&1; printf '__scs_exit %s\\n' "$?"; } | ` +
+      `{ __scs_got=''; __scs_exit=''; __scs_detail=''; while IFS= read -r __scs_line; do case "$__scs_line" in ` +
+      `'__scs_exit '*) __scs_exit=\${__scs_line#__scs_exit };; ` +
+      `*) if __scs_record "$__scs_line"; then __scs_got=1; elif [ -z "$__scs_detail" ]; then __scs_detail=$(printf '%s' "$__scs_line" | cut -c 1-240); fi;; esac; done; ` +
+      `[ -z "$__scs_got" ] || exit 0; ${execReason}; ` +
+      `case "$__scs_exit" in ''|0|*[!0-9]*) exit 1;; esac; exit "$__scs_exit"; } & ` +
+      `__scs_reader=$!; wait "$__scs_reader"; __scs_exit=$?; trap - TERM; __scs_reader=''; ` +
+      // No shell in the image: a per-round exec cannot succeed either.
+      `case "$__scs_exit" in 0) ;; 126|127) break;; *) __scs_stream=0;; esac; ` +
+      `else __scs_remote=$(docker exec ${name} sh -c ${shellQuote(`${buildCgroupFunctionsSnippet()}; ${remoteRead}`)} 2>&1); __scs_exit=$?; ` +
+      'if [ "$__scs_exit" = 0 ] && __scs_record "$__scs_remote"; then __scs_ok=1; ' +
+      `else __scs_detail=$(printf "%s" "$__scs_remote" | sed -n "1p" | cut -c 1-240); ${execReason}; fi; fi; ` +
+      // A successful read needs no Docker liveness probe, and the completion
+      // watcher still stops us after docker wait.
+      `if [ -z "$__scs_ok" ] && [ "$(docker inspect -f '{{.State.Running}}' ${name} 2>/dev/null)" = false ]; then break; fi; ` +
+      `sleep "$__scs_interval"; done ) >/dev/null 2>&1 & ${v.sampler}=$!`,
   ].join('; ');
 }
 
@@ -305,13 +374,16 @@ function formatCgroupMemory(memory) {
 
 module.exports = {
   CGROUP_SAMPLE_INTERVAL_SECONDS,
+  CGROUP_SAMPLING_OFF_REASON,
   CGROUP_SHELL_VARS,
+  CGROUP_STREAM_NAME,
   OOM_SCOPE,
   OOM_SCOPE_NOTES,
   buildCgroupFunctionsSnippet,
   buildCgroupMemoryLogSnippet,
   buildCgroupSamplerStartSnippet,
   buildCgroupSamplerStopSnippet,
+  buildCgroupStreamScript,
   describeCgroupOomScope,
   formatCgroupMemory,
   formatCgroupMemoryLogLine,