@link-assistant/hive-mind 2.11.7 → 2.11.9

package/src/session-kill-diagnostics.lib.mjs

@@ -0,0 +1,388 @@
+/**
+ * Kill-cause diagnostics for work sessions (issue #2134).
+ *
+ * "Work session killed — out of memory **or** forced kill (SIGKILL)" was as much
+ * as Hive Mind could say, because nothing ever looked at the machine state — even
+ * though every ingredient was already being collected and thrown away:
+ *
+ *   - `src/solve.resource-diagnostics.lib.mjs` writes `📈 [RESOURCES]` markers
+ *     (memory available/total, disk used percent) into every session log;
+ *   - the bot records the same snapshot every heartbeat;
+ *   - on Linux the kernel exposes the ground truth in
+ *     `/sys/fs/cgroup/memory.events` (`oom`, `oom_kill`), `/proc/meminfo`,
+ *     `/proc/pressure/memory` and the OOM killer's `dmesg` lines, which name the
+ *     exact victim process.
+ *
+ * This module turns those into ONE explicit verdict — out of memory / disk full /
+ * forced kill — with the evidence that produced it, so both the Telegram message
+ * and the pull-request notice can say what actually happened. Every probe is
+ * injectable and never throws: a diagnosis is a best-effort enrichment, never a
+ * reason to fail a completion notification.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2134
+ */
+
+import fsPromises from 'fs/promises';
+import { exec as execCallback } from 'child_process';
+import { promisify } from 'util';
+import { t } from './i18n.lib.mjs';
+import { formatBytes, parseResourceMarkers } from './solve.resource-diagnostics.lib.mjs';
+
+const exec = promisify(execCallback);
+
+export const KILL_CAUSE_OUT_OF_MEMORY = 'out-of-memory';
+export const KILL_CAUSE_DISK_FULL = 'disk-full';
+export const KILL_CAUSE_FORCED_KILL = 'forced-kill';
+export const KILL_CAUSE_UNKNOWN = 'unknown';
+
+/** Memory is considered exhausted below this share of total RAM still available. */
+export const MEMORY_EXHAUSTED_AVAILABLE_RATIO = 0.1;
+/** Disk is considered full at or above this used percentage… */
+export const DISK_FULL_USED_PERCENT = 95;
+/** …or below this much free space, whichever triggers first. */
+export const DISK_FULL_AVAILABLE_BYTES = 512 * 1024 * 1024;
+
+function text(locale, key, fallback, params = {}) {
+  if (!locale) return fallback;
+  return t(key, params, { locale });
+}
+
+function finite(value) {
+  return Number.isFinite(value) ? value : null;
+}
+
+/**
+ * The most recent `📈 [RESOURCES]` marker that carries usable memory data —
+ * i.e. the closest reading to the moment the session died.
+ *
+ * @param {{markers: Array}|null} parsed - Output of parseResourceMarkers()
+ * @returns {Object|null}
+ */
+export function selectLastMemoryResourceMarker(parsed) {
+  const markers = Array.isArray(parsed?.markers) ? parsed.markers : [];
+  for (let i = markers.length - 1; i >= 0; i--) {
+    if (finite(markers[i]?.memory?.availableBytes) !== null) return markers[i];
+  }
+  return null;
+}
+
+/**
+ * The most recent marker that carries usable disk data.
+ *
+ * @param {{markers: Array}|null} parsed
+ * @returns {Object|null}
+ */
+export function selectLastDiskResourceMarker(parsed) {
+  const markers = Array.isArray(parsed?.markers) ? parsed.markers : [];
+  for (let i = markers.length - 1; i >= 0; i--) {
+    if (finite(markers[i]?.disk?.usedPercent) !== null || finite(markers[i]?.disk?.availableBytes) !== null) return markers[i];
+  }
+  return null;
+}
+
+function parseCgroupKeyedFile(content) {
+  const out = {};
+  for (const line of String(content || '').split(/\r?\n/)) {
+    const match = /^(\S+)\s+(\d+)$/.exec(line.trim());
+    if (match) out[match[1]] = Number(match[2]);
+  }
+  return out;
+}
+
+function parseMeminfo(content) {
+  const fields = {};
+  for (const line of String(content || '').split(/\r?\n/)) {
+    const match = /^(\w+):\s+(\d+)\s*kB$/.exec(line.trim());
+    if (match) fields[match[1]] = Number(match[2]) * 1024;
+  }
+  return {
+    totalBytes: finite(fields.MemTotal),
+    availableBytes: finite(fields.MemAvailable),
+    swapTotalBytes: finite(fields.SwapTotal),
+    swapFreeBytes: finite(fields.SwapFree),
+  };
+}
+
+/**
+ * Parse the kernel OOM killer's own report out of `dmesg` output. Both the
+ * modern `oom-kill:...,task=<comm>,pid=<pid>` summary and the classic
+ * `Killed process <pid> (<comm>)` line are recognised, because which one appears
+ * depends on the kernel version.
+ *
+ * @param {string} dmesgText
+ * @returns {Array<{pid: number|null, comm: string|null, line: string}>}
+ */
+export function parseOomVictims(dmesgText) {
+  const victims = [];
+  for (const line of String(dmesgText || '').split(/\r?\n/)) {
+    const killed = /Killed process (\d+)\s+\(([^)]+)\)/.exec(line);
+    if (killed) {
+      victims.push({ pid: Number(killed[1]), comm: killed[2], line: line.trim() });
+      continue;
+    }
+    const oomKill = /oom-kill:.*?task=([^,\s]+).*?pid=(\d+)/.exec(line);
+    if (oomKill) {
+      victims.push({ pid: Number(oomKill[2]), comm: oomKill[1], line: line.trim() });
+    }
+  }
+  return victims;
+}
+
+/**
+ * Read every kernel-side kill signal this machine exposes. Linux-only in
+ * practice; on other platforms (or in a sandbox where the files are not
+ * readable) the corresponding fields stay null and the reason is recorded in
+ * `errors` so a `--verbose` run can show why a diagnosis was thin (R8/#2134).
+ *
+ * @param {Object} [options]
+ * @param {Function} [options.readFile] - Injectable fs.promises.readFile
+ * @param {Function} [options.execImpl] - Injectable promisified exec (for dmesg)
+ * @param {boolean} [options.verbose]
+ * @param {boolean} [options.includeDmesg=true]
+ * @returns {Promise<Object>} System diagnostics (never throws)
+ */
+export async function collectSystemKillDiagnostics({ readFile = fsPromises.readFile, execImpl = exec, verbose = false, includeDmesg = true, cgroupPath = '/sys/fs/cgroup' } = {}) {
+  const result = { cgroup: { oom: null, oomKill: null, maxBytes: null, currentBytes: null }, memory: { totalBytes: null, availableBytes: null, swapTotalBytes: null, swapFreeBytes: null }, pressure: null, victims: [], errors: [] };
+
+  const readOptional = async (file, label) => {
+    try {
+      return await readFile(file, 'utf8');
+    } catch (error) {
+      result.errors.push(`${label}: ${error?.message || error}`);
+      if (verbose) console.log(`[VERBOSE] kill-diagnostics: could not read ${file}: ${error?.message || error}`);
+      return null;
+    }
+  };
+
+  const events = await readOptional(`${cgroupPath}/memory.events`, 'cgroup memory.events');
+  if (events) {
+    const parsed = parseCgroupKeyedFile(events);
+    result.cgroup.oom = finite(parsed.oom);
+    result.cgroup.oomKill = finite(parsed.oom_kill);
+  }
+  const max = await readOptional(`${cgroupPath}/memory.max`, 'cgroup memory.max');
+  if (max) {
+    const trimmed = max.trim();
+    result.cgroup.maxBytes = trimmed === 'max' ? null : finite(Number(trimmed));
+  }
+  const current = await readOptional(`${cgroupPath}/memory.current`, 'cgroup memory.current');
+  if (current) result.cgroup.currentBytes = finite(Number(current.trim()));
+
+  const meminfo = await readOptional('/proc/meminfo', '/proc/meminfo');
+  if (meminfo) result.memory = parseMeminfo(meminfo);
+
+  const pressure = await readOptional('/proc/pressure/memory', '/proc/pressure/memory');
+  if (pressure) result.pressure = pressure.trim().split(/\r?\n/)[0] || null;
+
+  if (includeDmesg) {
+    try {
+      const { stdout } = await execImpl('dmesg -T 2>/dev/null | grep -iE "out of memory|oom-kill|killed process" | tail -20', { timeout: 10000, maxBuffer: 1024 * 1024 });
+      result.victims = parseOomVictims(stdout);
+    } catch (error) {
+      // A non-root container usually cannot read the kernel ring buffer, and
+      // grep exits 1 when nothing matched. Both are normal, not failures.
+      result.errors.push(`dmesg: ${error?.message || error}`);
+      if (verbose) console.log(`[VERBOSE] kill-diagnostics: dmesg probe unavailable: ${error?.message || error}`);
+    }
+  }
+
+  if (verbose) {
+    console.log(`[VERBOSE] kill-diagnostics: cgroup oom=${result.cgroup.oom} oom_kill=${result.cgroup.oomKill}, mem available=${formatBytes(result.memory.availableBytes)}/${formatBytes(result.memory.totalBytes)}, victims=${result.victims.length}`);
+  }
+  return result;
+}
+
+function memoryRatio(memory) {
+  const available = finite(memory?.availableBytes);
+  const total = finite(memory?.totalBytes);
+  if (available === null || total === null || total <= 0) return null;
+  return available / total;
+}
+
+function describeMemory(memory, timestamp) {
+  const available = finite(memory?.availableBytes);
+  const total = finite(memory?.totalBytes);
+  if (available === null || total === null) return null;
+  const usedPercent = total > 0 ? (100 * (total - available)) / total : null;
+  const at = timestamp ? ` at ${timestamp}` : '';
+  return `${formatBytes(available)} of ${formatBytes(total)} RAM available${usedPercent === null ? '' : ` (${usedPercent.toFixed(1)}% used)`}${at}`;
+}
+
+function describeDisk(disk, timestamp) {
+  const usedPercent = finite(disk?.usedPercent);
+  const available = finite(disk?.availableBytes);
+  if (usedPercent === null && available === null) return null;
+  const at = timestamp ? ` at ${timestamp}` : '';
+  const parts = [];
+  if (available !== null) parts.push(`${formatBytes(available)} free`);
+  if (finite(disk?.totalBytes) !== null) parts.push(`of ${formatBytes(disk.totalBytes)}`);
+  if (usedPercent !== null) parts.push(`(${usedPercent.toFixed(1)}% used)`);
+  return `disk ${disk?.path || '/'}: ${parts.join(' ')}${at}`;
+}
+
+/**
+ * Decide WHY a session was killed, from the evidence available.
+ *
+ * The order encodes confidence: a kernel OOM report or a container OOM flag is
+ * proof; a resource marker showing exhausted memory/disk is strong
+ * circumstantial evidence; a signal exit with healthy resources is a forced
+ * kill (an operator, a supervisor, or `docker stop`).
+ *
+ * @param {Object} [params]
+ * @param {string} [params.logText] - Session log text (parsed for markers)
+ * @param {Object} [params.resourceMarkers] - Pre-parsed parseResourceMarkers() output
+ * @param {boolean} [params.oomKilled] - Docker `State.OOMKilled`
+ * @param {number|null} [params.exitCode]
+ * @param {Object|null} [params.system] - collectSystemKillDiagnostics() result
+ * @param {boolean} [params.stopRequestedByUser] - The operator asked for the stop
+ * @returns {{cause: string, summary: string, evidence: string[], memory: Object|null, disk: Object|null, victims: Array}}
+ */
+export function describeKillCause({ logText = null, resourceMarkers = null, oomKilled = false, exitCode = null, system = null, stopRequestedByUser = false } = {}) {
+  const parsed = resourceMarkers || (logText ? parseResourceMarkers(logText) : { markers: [], byPhase: {} });
+  const memoryMarker = selectLastMemoryResourceMarker(parsed);
+  const diskMarker = selectLastDiskResourceMarker(parsed);
+  const memory = memoryMarker?.memory || null;
+  const disk = diskMarker?.disk || null;
+  const victims = Array.isArray(system?.victims) ? system.victims : [];
+  const cgroupOomKills = finite(system?.cgroup?.oomKill);
+
+  const evidence = [];
+  const memoryLine = describeMemory(memory, memoryMarker?.timestamp || null);
+  if (memoryLine) evidence.push(`last session memory reading — ${memoryLine} (phase \`${memoryMarker.phase}\`)`);
+  const diskLine = describeDisk(disk, diskMarker?.timestamp || null);
+  if (diskLine) evidence.push(`last session ${diskLine} (phase \`${diskMarker.phase}\`)`);
+  if (oomKilled) evidence.push('container reports `State.OOMKilled = true` (an OOM event hit the container cgroup)');
+  if (cgroupOomKills !== null && cgroupOomKills > 0) evidence.push(`cgroup \`memory.events\` reports ${cgroupOomKills} OOM kill(s)`);
+  const systemMemoryLine = describeMemory(system?.memory, null);
+  if (systemMemoryLine) evidence.push(`host memory now — ${systemMemoryLine}`);
+  if (system?.pressure) evidence.push(`\`/proc/pressure/memory\`: ${system.pressure}`);
+  for (const victim of victims.slice(-3)) {
+    evidence.push(`kernel OOM killer terminated \`${victim.comm || 'unknown'}\` (pid ${victim.pid ?? '?'})`);
+  }
+
+  const ratio = memoryRatio(memory);
+  const memoryExhausted = ratio !== null && ratio <= MEMORY_EXHAUSTED_AVAILABLE_RATIO;
+  const diskUsedPercent = finite(disk?.usedPercent);
+  const diskAvailable = finite(disk?.availableBytes);
+  const diskFull = (diskUsedPercent !== null && diskUsedPercent >= DISK_FULL_USED_PERCENT) || (diskAvailable !== null && diskAvailable <= DISK_FULL_AVAILABLE_BYTES);
+
+  let cause = KILL_CAUSE_UNKNOWN;
+  if (stopRequestedByUser) {
+    cause = KILL_CAUSE_FORCED_KILL;
+  } else if (victims.length > 0 || (cgroupOomKills !== null && cgroupOomKills > 0) || oomKilled || memoryExhausted) {
+    cause = KILL_CAUSE_OUT_OF_MEMORY;
+  } else if (diskFull) {
+    cause = KILL_CAUSE_DISK_FULL;
+  } else if (exitCode !== null && exitCode > 128) {
+    cause = KILL_CAUSE_FORCED_KILL;
+  }
+
+  let summary;
+  if (cause === KILL_CAUSE_OUT_OF_MEMORY) {
+    const victim = victims.length > 0 ? `, kernel OOM killer terminated \`${victims[victims.length - 1].comm || 'unknown'}\` (pid ${victims[victims.length - 1].pid ?? '?'})` : '';
+    summary = `out of memory${memoryLine ? ` — ${memoryLine}` : ''}${victim}`;
+  } else if (cause === KILL_CAUSE_DISK_FULL) {
+    summary = `disk full${diskLine ? ` — ${diskLine}` : ''}`;
+  } else if (cause === KILL_CAUSE_FORCED_KILL) {
+    const healthy = [memoryLine ? `memory (${memoryLine})` : null, diskLine ? diskLine : null].filter(Boolean).join(', ');
+    summary = stopRequestedByUser ? 'forced kill — an operator requested the stop' : `forced kill${healthy ? ` — ${healthy} were within normal limits` : ' — no resource exhaustion was observed'}`;
+  } else {
+    summary = 'unknown — no resource marker, cgroup counter or kernel OOM report was available';
+  }
+
+  return { cause, summary, evidence, memory, disk, victims };
+}
+
+/**
+ * Telegram/PR section describing why the session was killed.
+ *
+ * @param {Object} diagnosis - describeKillCause() result
+ * @param {Object} [options]
+ * @param {string|null} [options.locale]
+ * @returns {string} Markdown block, or '' when there is nothing to report
+ */
+export function formatKillDiagnosticsSection(diagnosis, { locale = null } = {}) {
+  if (!diagnosis || diagnosis.cause === KILL_CAUSE_UNKNOWN) {
+    if (!diagnosis?.evidence?.length) return '';
+  }
+  const title = text(locale, 'telegram.session_kill_diagnostics', 'Kill diagnostics');
+  const causeLabel = text(locale, 'telegram.session_kill_cause', 'Cause');
+  const lines = [`🔎 *${title}*`, `${causeLabel}: ${diagnosis.summary}`];
+  for (const item of diagnosis.evidence) lines.push(`• ${item}`);
+  return lines.join('\n');
+}
+
+/**
+ * The warning the issue asks for: a session that hit an out-of-memory event (or
+ * any other kill) and nevertheless completed must say so, instead of reading as
+ * an ordinary success.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.cause] - Kill cause constant
+ * @param {string|null} [options.observedAt] - When the event was observed
+ * @param {string|null} [options.locale]
+ * @param {boolean} [options.resumed] - A new working session was started
+ * @returns {string} Markdown block, or '' when nothing was recovered from
+ */
+export function formatKillRecoverySection({ cause = KILL_CAUSE_OUT_OF_MEMORY, observedAt = null, locale = null, resumed = false } = {}) {
+  const key = cause === KILL_CAUSE_OUT_OF_MEMORY ? 'telegram.session_recovered_oom' : 'telegram.session_recovered_kill';
+  const fallback = cause === KILL_CAUSE_OUT_OF_MEMORY ? 'recovered from out of memory' : 'recovered from forced kill';
+  const lines = [`⚠️ *${text(locale, key, fallback)}*`];
+  if (observedAt) {
+    lines.push(text(locale, 'telegram.session_recovered_at', `The event was observed at ${observedAt}; the work session kept running and completed.`, { observedAt }));
+  }
+  if (resumed) {
+    lines.push(text(locale, 'telegram.session_recovered_resumed', 'A new working session was started to recover from the kill.'));
+  }
+  return lines.join('\n');
+}
+
+/**
+ * The counterpart for a session that did NOT survive: `--on-session-kill=resume`
+ * started a fresh working session, and the Telegram report must say so with the
+ * same words the pull-request notice uses — that is the "consistent in ALL
+ * places" requirement of issue #2134.
+ *
+ * @param {Object} [options]
+ * @param {string|null} [options.sessionId] - Id of the recovery working session
+ * @param {number|null} [options.attempt]
+ * @param {number|null} [options.maxAttempts]
+ * @param {string|null} [options.locale]
+ * @returns {string} Markdown block, or '' when no recovery session was started
+ */
+export function formatKillResumeSection({ sessionId = null, attempt = null, maxAttempts = null, locale = null } = {}) {
+  if (!sessionId) return '';
+  const withAttempt = Number.isFinite(attempt) && Number.isFinite(maxAttempts);
+  const attemptText = withAttempt ? `${attempt}/${maxAttempts}` : '';
+  const key = withAttempt ? 'telegram.session_kill_resumed_attempt' : 'telegram.session_kill_resumed';
+  const fallback = withAttempt ? `🔄 A new working session was started to recover from this kill (attempt ${attemptText}): ${sessionId}` : `🔄 A new working session was started to recover from this kill: ${sessionId}`;
+  return text(locale, key, fallback, { attempt: attemptText, sessionId });
+}
+
+/**
+ * Read a session log, diagnose the kill and render the Telegram section in one
+ * call. Never throws — returns '' when nothing can be said.
+ *
+ * @param {string|null} logPath
+ * @param {Object} [options]
+ * @returns {Promise<{section: string, diagnosis: Object|null}>}
+ */
+export async function buildKillDiagnosticsSection(logPath, { verbose = false, readFile = fsPromises.readFile, oomKilled = false, exitCode = null, stopRequestedByUser = false, locale = null, collectSystem = collectSystemKillDiagnostics } = {}) {
+  try {
+    let logText = '';
+    if (logPath) {
+      try {
+        logText = await readFile(logPath, 'utf8');
+      } catch (readError) {
+        if (verbose) console.log(`[VERBOSE] kill-diagnostics: could not read session log ${logPath}: ${readError?.message || readError}`);
+      }
+    }
+    const system = await collectSystem({ verbose });
+    const diagnosis = describeKillCause({ logText, oomKilled, exitCode, system, stopRequestedByUser });
+    if (verbose) console.log(`[VERBOSE] kill-diagnostics: cause=${diagnosis.cause} — ${diagnosis.summary}`);
+    return { section: formatKillDiagnosticsSection(diagnosis, { locale }), diagnosis };
+  } catch (error) {
+    if (verbose) console.log(`[VERBOSE] kill-diagnostics: diagnosis failed: ${error?.message || error}`);
+    return { section: '', diagnosis: null };
+  }
+}

package/src/session-kill-policy.lib.mjs

@@ -0,0 +1,96 @@
+/**
+ * How Hive Mind reacts when a detached work session is killed (issue #2134).
+ *
+ * The issue asks for one configurable behaviour that every surface honours
+ * identically — the Telegram completion message and the pull-request notice must
+ * never disagree about what happened:
+ *
+ *   - `report` (default, today's behaviour): the kill is terminal. The Telegram
+ *     message says the session was killed, with the diagnosed cause, and offers
+ *     the resume command. The pull request gets the same notice.
+ *   - `resume`: the kill is treated as recoverable. A new working session is
+ *     started from the last tool session id, and BOTH surfaces say so
+ *     ("recovered from out of memory" / "a new working session was started").
+ *
+ * Selected by `--on-session-kill=<policy>` or `HIVE_MIND_ON_SESSION_KILL`, with
+ * the CLI flag winning over the environment. Nothing is removed by choosing one
+ * over the other: `resume` still reports the kill and its cause, it just adds
+ * the recovery, and log uploads stay gated on `--attach-logs` in both modes.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2134
+ */
+
+export const ON_SESSION_KILL_REPORT = 'report';
+export const ON_SESSION_KILL_RESUME = 'resume';
+export const ON_SESSION_KILL_POLICIES = [ON_SESSION_KILL_REPORT, ON_SESSION_KILL_RESUME];
+export const DEFAULT_ON_SESSION_KILL_POLICY = ON_SESSION_KILL_REPORT;
+
+export const ON_SESSION_KILL_ENV_VAR = 'HIVE_MIND_ON_SESSION_KILL';
+
+/** Hard cap on automatic resumes per session, so a reliably OOM-ing job cannot storm. */
+export const DEFAULT_SESSION_KILL_RESUME_ATTEMPTS = 1;
+export const SESSION_KILL_RESUME_ATTEMPTS_ENV_VAR = 'HIVE_MIND_SESSION_KILL_RESUME_ATTEMPTS';
+
+function normalize(value) {
+  return String(value ?? '')
+    .trim()
+    .toLowerCase();
+}
+
+/**
+ * Resolve the configured on-kill policy.
+ *
+ * @param {Object} [options]
+ * @param {Object} [options.argv] - yargs argv (`onSessionKill` / `on-session-kill`)
+ * @param {Object} [options.env=process.env]
+ * @param {Object} [options.sessionInfo] - Persisted session info (per-session override)
+ * @param {boolean} [options.verbose]
+ * @returns {string} One of ON_SESSION_KILL_POLICIES
+ */
+export function resolveOnSessionKillPolicy({ argv = null, env = process.env, sessionInfo = null, verbose = false } = {}) {
+  const candidates = [
+    { source: 'session', raw: sessionInfo?.onSessionKill },
+    { source: '--on-session-kill', raw: argv?.onSessionKill ?? argv?.['on-session-kill'] },
+    { source: ON_SESSION_KILL_ENV_VAR, raw: env?.[ON_SESSION_KILL_ENV_VAR] },
+  ];
+  for (const { source, raw } of candidates) {
+    const normalized = normalize(raw);
+    if (!normalized) continue;
+    if (ON_SESSION_KILL_POLICIES.includes(normalized)) return normalized;
+    if (verbose) {
+      console.log(`[VERBOSE] Invalid ${source}='${raw}', using '${DEFAULT_ON_SESSION_KILL_POLICY}' (valid: ${ON_SESSION_KILL_POLICIES.join(', ')})`);
+    }
+  }
+  return DEFAULT_ON_SESSION_KILL_POLICY;
+}
+
+/**
+ * Maximum number of automatic resumes for one killed session.
+ *
+ * @param {Object} [options]
+ * @param {Object} [options.argv]
+ * @param {Object} [options.env=process.env]
+ * @returns {number} A non-negative integer
+ */
+export function resolveSessionKillResumeAttempts({ argv = null, env = process.env } = {}) {
+  const raw = argv?.sessionKillResumeAttempts ?? argv?.['session-kill-resume-attempts'] ?? env?.[SESSION_KILL_RESUME_ATTEMPTS_ENV_VAR];
+  const text = String(raw ?? '').trim();
+  // An unset flag/variable is an empty string, and `Number('')` is 0 — which
+  // would silently disable resuming instead of using the default.
+  if (text === '') return DEFAULT_SESSION_KILL_RESUME_ATTEMPTS;
+  const parsed = Number(text);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_SESSION_KILL_RESUME_ATTEMPTS;
+  return Math.floor(parsed);
+}
+
+/**
+ * Whether a killed session should be auto-resumed under the resolved policy.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.policy]
+ * @param {boolean} [options.killed] - The completion outcome is a kill
+ * @returns {boolean}
+ */
+export function shouldResumeKilledSession({ policy = DEFAULT_ON_SESSION_KILL_POLICY, killed = false } = {}) {
+  return killed === true && policy === ON_SESSION_KILL_RESUME;
+}