@link-assistant/hive-mind 2.11.7 → 2.11.8

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @link-assistant/hive-mind
 
+## 2.11.8
+
+### Patch Changes
+
+- 881e604: Stop announcing kills that did not happen, and say exactly what happened when one did. Docker sets `State.OOMKilled` when any process in the container cgroup is OOM-killed, so a container whose helper process died keeps running and can still exit 0 — Hive Mind treated the flag as terminal and reported a task as "killed — out of memory or forced kill (SIGKILL)" while it went on working for another 3.5 hours and merged its pull request with nothing said there. The flag is now an observation: the log footer wins, then container liveness, and only a dead container with no footer is reported as killed.
+
+  Every kill now carries a diagnosis built from evidence already collected — the resource markers in the working-session log, cgroup v2 `memory.events`, `/proc/meminfo`, disk usage and the kernel OOM report — so the message names out of memory, disk exhaustion or a forced kill instead of guessing, and names the process the kernel killed. A session that survived the event completes with a `recovered from out of memory` / `recovered from forced kill` warning (en/ru/zh/hi) instead of reading as a plain success, and the same report is posted to the pull request; the intermediate working-session log is uploaded alongside it only when `--attach-logs` is enabled. Behaviour is one option honoured identically by the bot and by `solve`: `--on-session-kill=report|resume` (env `HIVE_MIND_ON_SESSION_KILL`), defaulting to today's `report`. Under `resume`, a killed session is restarted through the same isolation backend from the last tool session id found in its own log, the new session is tracked like any other, and both the Telegram completion and the pull-request notice name it; `--session-kill-resume-attempts` (default 1) caps how many recovery sessions one killed session may produce, and a session stopped on purpose is never restarted.
+
 ## 2.11.7
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.11.7",
+  "version": "2.11.8",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/locales/en.lino

@@ -658,6 +658,16 @@ en
       label "Duration"
     session
       label "Session"
+      recovered
+        oom "recovered from out of memory"
+        kill "recovered from forced kill"
+        at "The event was observed at {{observedAt}}; the work session kept running and completed."
+        resumed "A new working session was started to recover from the kill."
+      kill
+        cause "Cause"
+        diagnostics "Kill diagnostics"
+        resumed "🔄 A new working session was started to recover from this kill: {{sessionId}}"
+        resumed_attempt "🔄 A new working session was started to recover from this kill (attempt {{attempt}}): {{sessionId}}"
     isolation
       label "Isolation"
     error

package/src/locales/hi.lino

@@ -658,6 +658,16 @@ hi
       label "अवधि"
     session
       label "सत्र"
+      recovered
+        oom "मेमोरी समाप्त होने से पुनर्प्राप्त"
+        kill "जबरन समाप्ति से पुनर्प्राप्त"
+        at "यह घटना {{observedAt}} पर देखी गई; कार्य सत्र चलता रहा और पूरा हुआ।"
+        resumed "समाप्ति से पुनर्प्राप्ति हेतु नया कार्य सत्र शुरू किया गया।"
+      kill
+        cause "कारण"
+        diagnostics "समाप्ति निदान"
+        resumed "🔄 इस समाप्ति से पुनर्प्राप्ति हेतु नया कार्य सत्र शुरू किया गया: {{sessionId}}"
+        resumed_attempt "🔄 इस समाप्ति से पुनर्प्राप्ति हेतु नया कार्य सत्र शुरू किया गया (प्रयास {{attempt}}): {{sessionId}}"
     isolation
       label "Isolation"
     error

package/src/locales/ru.lino

@@ -658,6 +658,16 @@ ru
       label "Длительность"
     session
       label "Сеанс"
+      recovered
+        oom "восстановлено после нехватки памяти"
+        kill "восстановлено после принудительного завершения"
+        at "Событие зафиксировано в {{observedAt}}; рабочая сессия продолжилась и завершилась."
+        resumed "Для восстановления после завершения запущена новая рабочая сессия."
+      kill
+        cause "Причина"
+        diagnostics "Диагностика завершения"
+        resumed "🔄 Запущена новая рабочая сессия для восстановления после этого завершения: {{sessionId}}"
+        resumed_attempt "🔄 Запущена новая рабочая сессия для восстановления после этого завершения (попытка {{attempt}}): {{sessionId}}"
     isolation
       label "Изоляция"
     error

package/src/locales/zh.lino

@@ -658,6 +658,16 @@ zh
       label "耗时"
     session
       label "会话"
+      recovered
+        oom "已从内存不足中恢复"
+        kill "已从强制终止中恢复"
+        at "事件发生于 {{observedAt}}；工作会话继续运行并已完成。"
+        resumed "已启动新的工作会话以从终止中恢复。"
+      kill
+        cause "原因"
+        diagnostics "终止诊断"
+        resumed "🔄 已启动新的工作会话以从此次终止中恢复：{{sessionId}}"
+        resumed_attempt "🔄 已启动新的工作会话以从此次终止中恢复（第 {{attempt}} 次尝试）：{{sessionId}}"
     isolation
       label "隔离"
     error

package/src/option-suggestions.lib.mjs

@@ -194,6 +194,8 @@ const KNOWN_OPTION_NAMES = [
   'auto-resume-on-limit-reset',
   'auto-resume-on-errors',
   'auto-close-pull-request-on-fail',
+  'on-session-kill',
+  'session-kill-resume-attempts',
   'auto-pull-request-creation',
   'auto-commit-uncommitted-changes',
   'auto-restart-on-uncommitted-changes',

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;
+}