@link-assistant/hive-mind 2.11.7 → 2.11.8

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

@@ -0,0 +1,252 @@
+/**
+ * Pull-request side of killed-session handling (issue #2134).
+ *
+ * The issue's screenshot showed the two surfaces disagreeing: Telegram announced
+ * "Work session killed — out of memory or forced kill (SIGKILL) (exit code: 137)"
+ * while the pull request silently carried on, with nothing to tell a reader that
+ * a kill had happened at all — let alone that a new working session had been
+ * started to recover from it.
+ *
+ * This module makes the pull request say exactly what the bot says:
+ *
+ *   - `buildKillRecoveryNotice()` renders the Markdown notice (kill cause,
+ *     diagnostics evidence, what happens next, resume command).
+ *   - `postKillRecoveryNotice()` posts it with `gh pr comment --body-file`.
+ *   - `attachIntermediateSessionLog()` uploads the intermediate working-session
+ *     log — ONLY when `--attach-logs` is enabled, per the issue: "Logs are
+ *     uploaded as usual only if --attach-logs is enabled."
+ *
+ * Every external dependency is injectable so the builders can be unit-tested
+ * without touching GitHub.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2134
+ */
+
+import { spawn } from 'child_process';
+import { KILL_CAUSE_DISK_FULL, KILL_CAUSE_FORCED_KILL, KILL_CAUSE_OUT_OF_MEMORY } from './session-kill-diagnostics.lib.mjs';
+import { ON_SESSION_KILL_RESUME } from './session-kill-policy.lib.mjs';
+
+/** Marker used to recognise (and avoid duplicating) our own notices. */
+export const KILL_RECOVERY_NOTICE_MARKER = '<!-- hive-mind:session-kill-notice -->';
+
+const CAUSE_HEADLINES = {
+  [KILL_CAUSE_OUT_OF_MEMORY]: 'recovered from out of memory',
+  [KILL_CAUSE_FORCED_KILL]: 'recovered from forced kill',
+  [KILL_CAUSE_DISK_FULL]: 'recovered from disk exhaustion',
+};
+
+const CAUSE_TITLES = {
+  [KILL_CAUSE_OUT_OF_MEMORY]: 'Working session was killed: out of memory',
+  [KILL_CAUSE_DISK_FULL]: 'Working session was killed: disk full',
+  [KILL_CAUSE_FORCED_KILL]: 'Working session was force-killed',
+};
+
+/**
+ * Human-readable headline for a recovered session, matching the wording the
+ * issue asks the Telegram bot to use.
+ *
+ * @param {string} cause - One of the KILL_CAUSE_* constants
+ * @returns {string}
+ */
+export function killRecoveryHeadline(cause) {
+  return CAUSE_HEADLINES[cause] || 'recovered from an unexpected kill';
+}
+
+/**
+ * Render the pull-request notice for a killed (and possibly resumed) session.
+ *
+ * @param {Object} options
+ * @param {Object} [options.diagnosis] - Result of describeKillCause()
+ * @param {number|null} [options.exitCode]
+ * @param {string} [options.sessionName]
+ * @param {string|null} [options.observedAt] - ISO timestamp of the kill/OOM event
+ * @param {string} [options.policy] - Resolved --on-session-kill policy
+ * @param {boolean} [options.resumed] - A new working session was started
+ * @param {string|null} [options.recoverySessionId] - Id of that working session
+ * @param {string|null} [options.resumeCommand] - Command to resume manually
+ * @param {number|null} [options.attempt] - Resume attempt number
+ * @param {number|null} [options.maxAttempts]
+ * @param {boolean} [options.attachLogs] - Whether --attach-logs is enabled
+ * @param {string|null} [options.logUrl] - URL of the uploaded intermediate log
+ * @returns {string} Markdown body
+ */
+export function buildKillRecoveryNotice({ diagnosis = null, exitCode = null, sessionName = null, observedAt = null, policy = null, resumed = false, recoverySessionId = null, resumeCommand = null, attempt = null, maxAttempts = null, attachLogs = false, logAttached = false, logUrl = null } = {}) {
+  const cause = diagnosis?.cause || null;
+  const title = resumed ? `⚠️ Working session ${killRecoveryHeadline(cause)}` : `❌ ${CAUSE_TITLES[cause] || 'Working session was killed'}`;
+
+  const lines = [KILL_RECOVERY_NOTICE_MARKER, `## ${title}`, ''];
+
+  if (diagnosis?.summary) lines.push(diagnosis.summary, '');
+
+  const facts = [];
+  if (exitCode !== null && exitCode !== undefined) facts.push(`- **Exit code:** ${exitCode}`);
+  if (observedAt) facts.push(`- **Detected at:** ${observedAt}`);
+  if (sessionName) facts.push(`- **Working session:** \`${sessionName}\``);
+  if (policy) facts.push(`- **On-kill policy:** \`${policy}\`${policy === ON_SESSION_KILL_RESUME ? ' (`--on-session-kill=resume`)' : ' (`--on-session-kill=report`)'}`);
+  if (facts.length > 0) lines.push(...facts, '');
+
+  const evidence = Array.isArray(diagnosis?.evidence) ? diagnosis.evidence.filter(Boolean) : [];
+  if (evidence.length > 0) {
+    lines.push('<details><summary>Kill diagnostics</summary>', '');
+    for (const item of evidence) lines.push(`- ${item}`);
+    lines.push('', '</details>', '');
+  }
+
+  if (resumed) {
+    const attemptSuffix = attempt && maxAttempts ? ` (attempt ${attempt}/${maxAttempts})` : '';
+    const sessionSuffix = recoverySessionId ? ` Its working session is \`${recoverySessionId}\`.` : '';
+    lines.push(`🔄 A **new working session was started** to recover from this event${attemptSuffix}. Progress below continues in that session.${sessionSuffix}`, '');
+  } else {
+    lines.push('This working session did not continue. Nothing below this comment was produced by it.', '');
+  }
+
+  if (logUrl) {
+    lines.push(`📎 Intermediate working-session log: ${logUrl}`, '');
+  } else if (logAttached) {
+    lines.push('📎 The intermediate working-session log was uploaded as a separate comment.', '');
+  } else if (!attachLogs) {
+    lines.push('_The intermediate working-session log was not uploaded because `--attach-logs` is disabled._', '');
+  }
+
+  if (resumeCommand) {
+    lines.push('To continue manually:', '', '```bash', resumeCommand, '```', '');
+  }
+
+  lines.push(`<sub>Reported by Hive Mind — [issue #2134](https://github.com/link-assistant/hive-mind/issues/2134)</sub>`);
+  return lines.join('\n');
+}
+
+/**
+ * Run a command and capture its output, without a shell (the notice body never
+ * touches the command line — it is passed via `--body-file`).
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @param {Object} [options] - Forwarded to child_process.spawn
+ * @returns {Promise<{code: number, stdout: string, stderr: string}>}
+ */
+export function spawnCapture(command, args, options = {}) {
+  return new Promise(resolve => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], env: process.env, ...options });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', data => {
+      stdout += data.toString();
+    });
+    child.stderr.on('data', data => {
+      stderr += data.toString();
+    });
+    child.on('error', error => resolve({ code: 1, stdout, stderr: stderr || error.message }));
+    child.on('close', code => resolve({ code, stdout, stderr }));
+  });
+}
+
+const defaultWriteFile = async (filePath, content) => {
+  const fs = (await import('fs')).promises;
+  await fs.writeFile(filePath, content, 'utf8');
+};
+
+const defaultUnlink = async filePath => {
+  const fs = (await import('fs')).promises;
+  await fs.unlink(filePath).catch(() => {});
+};
+
+/**
+ * Post the notice to a pull request via `gh pr comment --body-file`.
+ *
+ * `--body-file` (not `--body`) is used deliberately: the notice contains
+ * backticks and newlines that would otherwise have to survive shell quoting.
+ *
+ * @param {Object} options
+ * @param {string} options.pullRequestUrl
+ * @param {string} options.body
+ * @param {Function} options.runCommand - async (cmd, args) => { code, stdout, stderr }
+ * @param {string} [options.tempDir=/tmp]
+ * @param {string} [options.fileSuffix] - Deterministic suffix for the temp file
+ * @param {Function} [options.writeFile]
+ * @param {Function} [options.unlink]
+ * @param {boolean} [options.verbose]
+ * @returns {Promise<{posted: boolean, url: string|null, error: string|null}>}
+ */
+export async function postKillRecoveryNotice({ pullRequestUrl, body, runCommand = spawnCapture, tempDir = '/tmp', fileSuffix = 'notice', writeFile = defaultWriteFile, unlink = defaultUnlink, verbose = false }) {
+  if (!pullRequestUrl) return { posted: false, url: null, error: 'no pull request url' };
+  if (typeof runCommand !== 'function') return { posted: false, url: null, error: 'no command runner' };
+
+  const bodyFile = `${tempDir.replace(/\/$/, '')}/hive-mind-kill-notice-${fileSuffix}.md`;
+  try {
+    await writeFile(bodyFile, body);
+    const result = await runCommand('gh', ['pr', 'comment', pullRequestUrl, '--body-file', bodyFile]);
+    if (result?.code === 0) {
+      const url = String(result.stdout || '').trim() || null;
+      if (verbose) console.log(`[VERBOSE] Posted killed-session notice to ${pullRequestUrl}${url ? ` (${url})` : ''}`);
+      return { posted: true, url, error: null };
+    }
+    const error = String(result?.stderr || result?.stdout || `gh pr comment exited with code ${result?.code}`).trim();
+    if (verbose) console.log(`[VERBOSE] Failed to post killed-session notice: ${error}`);
+    return { posted: false, url: null, error };
+  } catch (error) {
+    if (verbose) console.log(`[VERBOSE] Failed to post killed-session notice: ${error?.message || error}`);
+    return { posted: false, url: null, error: error?.message || String(error) };
+  } finally {
+    await unlink(bodyFile);
+  }
+}
+
+/**
+ * Upload the intermediate working-session log to the pull request.
+ *
+ * Per the issue, this is gated on `--attach-logs` exactly like every other log
+ * upload — a killed session never becomes a reason to publish logs the user did
+ * not ask for.
+ *
+ * @param {Object} options
+ * @param {boolean} options.attachLogs - Resolved `--attach-logs` value
+ * @param {string|null} options.logPath
+ * @param {string|null} options.pullRequestUrl
+ * @param {Function} options.attachLog - attachLogToGitHub-compatible uploader
+ * @param {Object} [options.attachOptions] - Extra options forwarded to the uploader
+ * @param {string} [options.customTitle]
+ * @param {boolean} [options.verbose]
+ * @returns {Promise<{uploaded: boolean, skipped: string|null}>}
+ */
+export async function attachIntermediateSessionLog({ attachLogs, logPath, pullRequestUrl, attachLog, attachOptions = {}, customTitle = '📎 Intermediate working-session log (killed session)', verbose = false }) {
+  if (!attachLogs) {
+    if (verbose) console.log('[VERBOSE] Skipping intermediate log upload: --attach-logs is disabled');
+    return { uploaded: false, skipped: 'attach-logs-disabled' };
+  }
+  if (!logPath) return { uploaded: false, skipped: 'no-log-path' };
+  if (!pullRequestUrl) return { uploaded: false, skipped: 'no-pull-request' };
+  if (typeof attachLog !== 'function') return { uploaded: false, skipped: 'no-uploader' };
+
+  const parsed = parsePullRequestUrl(pullRequestUrl);
+  if (!parsed) return { uploaded: false, skipped: 'unparsable-pull-request-url' };
+
+  try {
+    const ok = await attachLog({
+      ...attachOptions,
+      logFile: logPath,
+      targetType: 'pr',
+      targetNumber: parsed.number,
+      owner: parsed.owner,
+      repo: parsed.repo,
+      customTitle,
+      verbose,
+    });
+    return { uploaded: ok !== false, skipped: null };
+  } catch (error) {
+    if (verbose) console.log(`[VERBOSE] Intermediate log upload failed: ${error?.message || error}`);
+    return { uploaded: false, skipped: `error: ${error?.message || error}` };
+  }
+}
+
+/**
+ * Minimal `https://github.com/<owner>/<repo>/pull/<number>` parser.
+ *
+ * @param {string} url
+ * @returns {{owner: string, repo: string, number: number}|null}
+ */
+export function parsePullRequestUrl(url) {
+  const match = /github\.com\/([^/\s]+)\/([^/\s]+)\/pull\/(\d+)/u.exec(String(url || ''));
+  if (!match) return null;
+  return { owner: match[1], repo: match[2], number: Number(match[3]) };
+}

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

@@ -0,0 +1,175 @@
+/**
+ * Automatic recovery of a killed working session (issue #2134).
+ *
+ * `--on-session-kill=resume` (env `HIVE_MIND_ON_SESSION_KILL`) asks for a new
+ * working session to be started when the previous one was killed by the kernel
+ * (out of memory), by a full disk, or by a forced kill. This module performs
+ * that restart, and — just as importantly — reports it: the caller puts the
+ * returned facts into the Telegram completion message AND into the pull request
+ * notice, so a reader of either surface knows a recovery session exists.
+ *
+ * The restart is bounded by `--session-kill-resume-attempts` (default 1), so a
+ * job that reliably runs the host out of memory cannot storm the queue.
+ *
+ * Nothing here runs under the default `report` policy — behaviour is unchanged
+ * unless the operator opts in.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2134
+ */
+
+import { readLastSessionIdFromLog, planKilledSessionResume } from './session-resume.lib.mjs';
+import { resolveOnSessionKillPolicy, resolveSessionKillResumeAttempts, shouldResumeKilledSession, ON_SESSION_KILL_RESUME } from './session-kill-policy.lib.mjs';
+import { argvFromSessionArgs } from './session-monitor.kill-sections.lib.mjs';
+import { formatKillResumeSection } from './session-kill-diagnostics.lib.mjs';
+
+/** Field recording how many automatic recovery sessions this session produced. */
+export const KILL_RESUME_ATTEMPTS_FIELD = 'killRecoveryAttempts';
+
+/**
+ * Decide whether a killed session should be auto-resumed, and with which
+ * command. Pure — no process is started here, so the decision is testable on
+ * its own and the caller can report a skipped resume just as precisely.
+ *
+ * @param {Object} options
+ * @param {Object} options.sessionInfo - Persisted session info
+ * @param {string|null} [options.logPath] - Working-session log to scan for the tool session id
+ * @param {boolean} options.killed - The completion outcome is a kill
+ * @param {Object} [options.env]
+ * @param {boolean} [options.verbose]
+ * @param {Function} [options.readLastSessionId] - Override for tests
+ * @returns {{shouldResume: boolean, reason: string, policy: string, command: Object|null, attempt: number, maxAttempts: number, lastSessionId: string|null}}
+ */
+export function planKillRecovery({ sessionInfo = {}, logPath = null, killed = false, env = process.env, verbose = false, readLastSessionId = readLastSessionIdFromLog } = {}) {
+  const argv = argvFromSessionArgs(sessionInfo?.args);
+  const policy = resolveOnSessionKillPolicy({ argv, env, sessionInfo, verbose });
+  const maxAttempts = resolveSessionKillResumeAttempts({ argv, env });
+  const attempts = Number.isFinite(sessionInfo?.[KILL_RESUME_ATTEMPTS_FIELD]) ? sessionInfo[KILL_RESUME_ATTEMPTS_FIELD] : 0;
+  const base = { shouldResume: false, policy, command: null, attempt: attempts, maxAttempts, lastSessionId: null };
+
+  if (!shouldResumeKilledSession({ policy, killed })) {
+    return { ...base, reason: killed ? 'policy-report' : 'not-killed' };
+  }
+  if (sessionInfo?.stopRequestedByUser === true) {
+    // A `/stop` is a kill the operator asked for; restarting it would fight them.
+    return { ...base, reason: 'stopped-by-user' };
+  }
+
+  const lastSessionId = readLastSessionId(logPath, { verbose });
+  const plan = planKilledSessionResume({ sessionInfo, lastSessionId, attempts, maxAttempts });
+  return { ...base, shouldResume: plan.resumable, reason: plan.reason, command: plan.command, attempt: plan.attempt, lastSessionId: lastSessionId || null };
+}
+
+/**
+ * Start the recovery working session decided by {@link planKillRecovery}.
+ *
+ * The new session is launched through the same isolation runner the original
+ * used and is tracked like any other session, so it reports its own completion
+ * (and, if it is killed too, its own diagnosis) through the normal path.
+ *
+ * @param {Object} options
+ * @param {string} options.sessionName - The killed session's name
+ * @param {Object} options.sessionInfo - Persisted session info
+ * @param {Object} options.plan - Result of planKillRecovery()
+ * @param {Object} options.runner - Isolation runner (executeWithIsolation/generateSessionId)
+ * @param {Function} options.trackSession - Tracker for the new session
+ * @param {Function} [options.persistSnapshot] - Persist the attempt counter
+ * @param {boolean} [options.verbose]
+ * @returns {Promise<{resumed: boolean, reason: string, sessionId: string|null, display: string|null}>}
+ */
+export async function startKillRecoverySession({ sessionName, sessionInfo, plan, runner, trackSession, persistSnapshot = null, verbose = false } = {}) {
+  const fail = reason => ({ resumed: false, reason, sessionId: null, display: plan?.command?.display || null });
+  if (!plan?.shouldResume || !plan.command) return fail(plan?.reason || 'no-plan');
+  if (!runner || typeof runner.executeWithIsolation !== 'function' || typeof runner.generateSessionId !== 'function') return fail('no-isolation-runner');
+  if (typeof trackSession !== 'function') return fail('no-tracker');
+  const backend = sessionInfo?.isolationBackend || null;
+  if (!backend) return fail('no-isolation-backend');
+
+  try {
+    const newSessionId = runner.generateSessionId();
+    const tool = sessionInfo?.tool || 'claude';
+    const result = await runner.executeWithIsolation(sessionInfo?.command || 'solve', plan.command.args, { backend, sessionId: newSessionId, tool, verbose });
+    if (!result?.success) return fail('start-failed');
+
+    trackSession(
+      newSessionId,
+      {
+        ...sessionInfo,
+        startTime: new Date(),
+        sessionId: newSessionId,
+        args: [...plan.command.args],
+        // Carry the counter forward so attempt N+1 is bounded by the same cap,
+        // and remember what this session is recovering from for its own report.
+        [KILL_RESUME_ATTEMPTS_FIELD]: plan.attempt,
+        killRecoveryResumed: true,
+        killRecoveryOfSession: sessionName,
+        oomEventObservedAt: undefined,
+        dockerBackendGoneFirstSeenAt: undefined,
+        containerFilesystemStartBytes: Number.isFinite(result.containerFilesystemStartBytes) ? result.containerFilesystemStartBytes : null,
+      },
+      verbose
+    );
+
+    if (sessionInfo) sessionInfo[KILL_RESUME_ATTEMPTS_FIELD] = plan.attempt;
+    if (typeof persistSnapshot === 'function') {
+      try {
+        persistSnapshot();
+      } catch {
+        // Persisting the counter is best effort; the recovery session is started.
+      }
+    }
+
+    if (verbose) {
+      console.log(`[VERBOSE] Session ${sessionName} was killed; started recovery session ${newSessionId} (attempt ${plan.attempt}/${plan.maxAttempts}): ${plan.command.display}`);
+    }
+    return { resumed: true, reason: 'started', sessionId: newSessionId, display: plan.command.display };
+  } catch (error) {
+    if (verbose) {
+      console.log(`[VERBOSE] Could not start recovery session for ${sessionName}: ${error?.message || error}`);
+    }
+    return fail('start-error');
+  }
+}
+
+/**
+ * Plan and, when the policy asks for it, perform the recovery in one call.
+ * Never throws — a failed recovery must still leave a correct kill report.
+ *
+ * @param {Object} options - See planKillRecovery() and startKillRecoverySession()
+ * @returns {Promise<{resumed: boolean, reason: string, policy: string, sessionId: string|null, display: string|null, attempt: number, maxAttempts: number}>}
+ */
+export async function recoverKilledSession({ sessionName, sessionInfo, logPath = null, killed = false, env = process.env, runner = null, trackSession = null, persistSnapshot = null, verbose = false, readLastSessionId = readLastSessionIdFromLog } = {}) {
+  let plan;
+  try {
+    plan = planKillRecovery({ sessionInfo, logPath, killed, env, verbose, readLastSessionId });
+  } catch (error) {
+    if (verbose) console.log(`[VERBOSE] Could not plan kill recovery for ${sessionName}: ${error?.message || error}`);
+    return { resumed: false, reason: 'plan-error', policy: ON_SESSION_KILL_RESUME, sessionId: null, display: null, attempt: 0, maxAttempts: 0 };
+  }
+
+  if (!plan.shouldResume) {
+    return { resumed: false, reason: plan.reason, policy: plan.policy, sessionId: null, display: plan.command?.display || null, attempt: plan.attempt, maxAttempts: plan.maxAttempts };
+  }
+
+  const started = await startKillRecoverySession({ sessionName, sessionInfo, plan, runner, trackSession, persistSnapshot, verbose });
+  return { resumed: started.resumed, reason: started.reason, policy: plan.policy, sessionId: started.sessionId, display: started.display, attempt: plan.attempt, maxAttempts: plan.maxAttempts };
+}
+
+/**
+ * Completion-time entry point: recover the killed session and render the
+ * Telegram section describing what was started, in one call — the monitor is at
+ * its `max-lines` budget and this keeps the two facts (what happened, what is
+ * said about it) together.
+ *
+ * @param {Object} options - See recoverKilledSession(); plus `locale`
+ * @returns {Promise<{recovery: Object, section: string}>}
+ */
+export async function runKillRecoveryForCompletion({ locale = null, ...options } = {}) {
+  const recovery = await recoverKilledSession(options);
+  const section = formatKillResumeSection({
+    sessionId: recovery.resumed ? recovery.sessionId : null,
+    attempt: recovery.attempt,
+    maxAttempts: recovery.maxAttempts,
+    locale,
+  });
+  return { recovery, section };
+}

package/src/session-monitor.kill-sections.lib.mjs

@@ -0,0 +1,198 @@
+/**
+ * Completion-time reporting for killed and recovered work sessions (issue #2134).
+ *
+ * Glue between the pieces that do the actual work — kill diagnostics, the
+ * on-kill policy, and the pull-request notice — so `session-monitor.lib.mjs`
+ * (already at its `max-lines` budget) gains one call instead of a hundred lines.
+ *
+ * Two situations are reported, and the Telegram message and the pull request are
+ * always given the SAME facts, which is the core complaint in the issue:
+ *
+ *   - The session was killed → say exactly why (out of memory / disk full /
+ *     forced kill) with the evidence behind that verdict.
+ *   - The session survived a kill event → warn "recovered from out of memory" /
+ *     "recovered from forced kill" instead of reading as a plain success.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2134
+ */
+
+import fs from 'fs/promises';
+import { classifySessionOutcome } from './work-session-formatting.lib.mjs';
+import { buildKillDiagnosticsSection, formatKillRecoverySection, KILL_CAUSE_FORCED_KILL, KILL_CAUSE_OUT_OF_MEMORY } from './session-kill-diagnostics.lib.mjs';
+import { getOomEventObservedAt } from './session-monitor.oom.lib.mjs';
+import { resolveOnSessionKillPolicy } from './session-kill-policy.lib.mjs';
+import { buildKillRecoveryNotice, postKillRecoveryNotice, attachIntermediateSessionLog, spawnCapture } from './session-kill-recovery.lib.mjs';
+
+/**
+ * `--attach-logs` as it reaches the bot: a raw CLI argument array recorded on
+ * the tracked session (see telegram-isolation.lib.mjs `args`).
+ *
+ * @param {string[]|null} args
+ * @returns {boolean}
+ */
+export function argsIncludeAttachLogs(args) {
+  if (!Array.isArray(args)) return false;
+  return args.some(arg => {
+    const value = String(arg || '').trim();
+    return value === '--attach-logs' || value.startsWith('--attach-logs=');
+  });
+}
+
+/** Turn a recorded CLI argument array into a minimal argv-like object. */
+export function argvFromSessionArgs(args) {
+  const argv = {};
+  if (!Array.isArray(args)) return argv;
+  for (let i = 0; i < args.length; i++) {
+    const raw = String(args[i] || '');
+    if (!raw.startsWith('--')) continue;
+    const eq = raw.indexOf('=');
+    if (eq > -1) {
+      argv[raw.slice(2, eq)] = raw.slice(eq + 1);
+      continue;
+    }
+    const next = args[i + 1];
+    if (next !== undefined && !String(next).startsWith('--')) {
+      argv[raw.slice(2)] = String(next);
+      i++;
+    } else {
+      argv[raw.slice(2)] = true;
+    }
+  }
+  return argv;
+}
+
+/**
+ * Build the kill/recovery sections for a completed session.
+ *
+ * Never throws: a failed diagnosis must never block a completion notification.
+ *
+ * @param {Object} options
+ * @param {string} options.sessionName
+ * @param {Object} options.sessionInfo
+ * @param {Object|null} [options.statusResult]
+ * @param {number|null} [options.exitCode]
+ * @param {string|null} [options.status]
+ * @param {boolean} [options.verbose]
+ * @param {Function} [options.readFile]
+ * @param {Object} [options.env]
+ * @returns {Promise<{sections: string[], diagnosis: Object|null, killed: boolean, recovered: boolean, policy: string|null, observedAt: string|null}>}
+ */
+export async function buildKillCompletionSections({ sessionName, sessionInfo, statusResult = null, exitCode = null, status = null, verbose = false, readFile = fs.readFile, env = process.env } = {}) {
+  const empty = { sections: [], diagnosis: null, killed: false, recovered: false, policy: null, observedAt: null };
+  try {
+    const outcome = classifySessionOutcome({ exitCode, status });
+    const observedAt = getOomEventObservedAt(sessionInfo);
+    const killed = outcome.killed === true;
+    const recovered = !killed && Boolean(observedAt);
+    if (!killed && !recovered) return empty;
+
+    const locale = sessionInfo?.locale || null;
+    const logPath = statusResult?.logPath || sessionInfo?.logPath || null;
+    const { section, diagnosis } = await buildKillDiagnosticsSection(logPath, {
+      verbose,
+      readFile,
+      oomKilled: statusResult?.oomKilled === true || recovered,
+      exitCode,
+      stopRequestedByUser: sessionInfo?.stopRequestedByUser === true,
+      locale,
+    });
+
+    const argv = argvFromSessionArgs(sessionInfo?.args);
+    const policy = resolveOnSessionKillPolicy({ argv, env, sessionInfo, verbose });
+
+    const sections = [];
+    if (recovered) {
+      // The session outlived the event — this is the warning the issue asks for.
+      sections.push(formatKillRecoverySection({ cause: diagnosis?.cause || KILL_CAUSE_OUT_OF_MEMORY, observedAt, locale, resumed: sessionInfo?.killRecoveryResumed === true }));
+    }
+    if (section) sections.push(section);
+
+    if (verbose) {
+      console.log(`[VERBOSE] Session ${sessionName} kill reporting: killed=${killed} recovered=${recovered} cause=${diagnosis?.cause || 'n/a'} policy=${policy}`);
+    }
+    return { sections: sections.filter(Boolean), diagnosis, killed, recovered, policy, observedAt };
+  } catch (error) {
+    if (verbose) {
+      console.log(`[VERBOSE] Could not build kill sections for ${sessionName}: ${error?.message || error}`);
+    }
+    return empty;
+  }
+}
+
+/**
+ * Default log uploader: `attachLogToGitHub` with the dependencies the bot does
+ * not otherwise carry (`$`, `log`, `sanitizeLogContent`). Imported lazily so the
+ * monitor keeps starting on machines where the heavy GitHub helpers are unused.
+ *
+ * @param {Object} options - attachLogToGitHub options
+ * @returns {Promise<boolean>}
+ */
+export async function defaultAttachLog(options) {
+  if (typeof globalThis.use === 'undefined') {
+    const { ensureUseM } = await import('./use-m-bootstrap.lib.mjs');
+    await ensureUseM();
+  }
+  const [{ attachLogToGitHub }, { sanitizeLogContent }] = await Promise.all([import('./github.lib.mjs'), import('./token-sanitization.lib.mjs')]);
+  const { $ } = await globalThis.use('command-stream');
+  return attachLogToGitHub({
+    $,
+    log: async message => console.log(message),
+    sanitizeLogContent,
+    ...options,
+  });
+}
+
+/**
+ * Post the same kill/recovery report to the pull request, so a reader of the PR
+ * is never left believing an unattended session simply carried on.
+ *
+ * The intermediate working-session log is uploaded only when `--attach-logs` is
+ * enabled, exactly as the issue requires.
+ *
+ * @param {Object} options
+ * @returns {Promise<{posted: boolean, url: string|null, skipped: string|null, logUploaded: boolean}>}
+ */
+export async function announceKillOnPullRequest({ pullRequestUrl, sessionName, sessionInfo, diagnosis, exitCode = null, observedAt = null, policy = null, recovered = false, resumed = false, recoverySessionId = null, attempt = null, maxAttempts = null, resumeCommand = null, runCommand = spawnCapture, attachLog = defaultAttachLog, attachOptions = {}, verbose = false } = {}) {
+  const skip = reason => ({ posted: false, url: null, skipped: reason, logUploaded: false });
+  if (!pullRequestUrl) return skip('no-pull-request');
+  if (typeof runCommand !== 'function') return skip('no-command-runner');
+
+  const attachLogs = argsIncludeAttachLogs(sessionInfo?.args);
+  const logPath = sessionInfo?.logPath || null;
+
+  const upload = await attachIntermediateSessionLog({
+    attachLogs,
+    logPath,
+    pullRequestUrl,
+    attachLog,
+    attachOptions,
+    verbose,
+  });
+
+  const body = buildKillRecoveryNotice({
+    diagnosis,
+    exitCode,
+    sessionName,
+    observedAt,
+    policy,
+    resumed: recovered || resumed || sessionInfo?.killRecoveryResumed === true,
+    recoverySessionId,
+    attempt,
+    maxAttempts,
+    resumeCommand,
+    attachLogs,
+    logAttached: upload.uploaded,
+  });
+
+  const result = await postKillRecoveryNotice({
+    pullRequestUrl,
+    body,
+    runCommand,
+    fileSuffix: String(sessionName || 'session').replace(/[^A-Za-z0-9._-]/g, '-'),
+    verbose,
+  });
+
+  return { posted: result.posted, url: result.url, skipped: result.posted ? null : result.error, logUploaded: upload.uploaded };
+}
+
+export { KILL_CAUSE_FORCED_KILL, KILL_CAUSE_OUT_OF_MEMORY };