@link-assistant/hive-mind 2.15.2 → 2.16.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @link-assistant/hive-mind
 
+## 2.16.0
+
+### Minor Changes
+
+- 7fe1b88: Stop Hive Mind from running itself out of memory while reporting a finished session, classify a runtime self-abort as what it is, and resume the session instead of offering to (issue #2189).
+
+  A `solve` run finished successfully, pushed its work and converted its pull request to ready — then died ten minutes later inside Hive Mind's own `--attach-logs` step with `FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory`, on a machine with 10.3 GB of RAM free. It was reported to the operator as a "forced kill", six hours late, and was never continued. Six changes close that path:
+
+  - **The sanitizer streams.** `--attach-logs` read a 134 MB log into one JS string, sanitized it (full copy), escaped it (full copy), built a comment it was never going to post, then sanitized the raw content again for the upload. `src/log-sanitize-stream.lib.mjs` sanitizes a log file into a destination file 1 MiB at a time, holding back only what could still be part of a token — a partial line, an unterminated PEM block, a trailing wrapped-base64 run — with a hard cap on the hold. `attachLogToGitHub` now picks the publication route from `logStats.size` **before** reading anything, and the content is sanitized exactly once.
+  - **A heap-capped worker behind it.** `sanitizeLogFileToFileBounded` routes logs at or above 16 MiB into a `worker_threads` worker with `resourceLimits.maxOldGenerationSizeMb = 512`, so a residual unbounded allocation costs one thread and one failed log upload rather than the working session. All four whole-file sanitize sites use it: the `--attach-logs` upload, the `/log` Telegram command, the GitHub error reporter and development-log collection.
+  - **A V8 self-abort is out of memory.** `docker inspect` said `OOMKilled=false` and cgroup `memory.events` said `oom_kill 0` — both correct, and both blind to a process that stops at its own ~2.1 GB heap cap. `FATAL_MEMORY_PATTERNS` / `findFatalMemoryMarker` recognise the fatal lines Node/V8, Rust, Go and C++ print on their way out, and an abnormal exit whose log carries one is `KILL_CAUSE_OUT_OF_MEMORY` regardless of cgroup counters. A clean exit is never upgraded, so a log that merely quotes the phrase cannot manufacture a diagnosis.
+  - **`--on-session-kill` defaults to `resume`.** A killed session with a recoverable tool session id now continues on its own instead of waiting for a human to paste a command; `report` and `HIVE_MIND_ON_SESSION_KILL` still opt out, and `--session-kill-resume-attempts` bounds it.
+  - **A killed session reaches a handled state.** The same dead session was re-detected on every poll — re-resolving the pull request, re-scanning the 134 MB log and re-sending the notification each cycle, with bot RSS climbing 1.78 → 1.84 GB against a ~2 GB cap. `src/session-completion-state.lib.mjs` adds a persisted handled latch and caches the recovered tool session id on the session record, so the log is scanned at most once and per-cycle work is no longer O(log size).
+  - **No unbounded log read is left.** Every artifact whose size is decided by how long an AI ran — `/log`, `/terminal_watch`, development-log collection, the error reporter, Claude session accounting and transcript repair, Codex's last-message artifact, and every session-monitor read — is streamed or reads a bounded head/tail. The `require-sanitized-output` ESLint rule learns the streaming sanitizers so a streamed artifact still counts as provably sanitized.
+
+  Telemetry was extended so the next incident is diagnosable: resource snapshots now carry the V8 heap used, total, external and `heap_size_limit` with the used share of it, warn at 85%, and `attachLogToGitHub` brackets itself with `log_upload_start` / `log_upload_end` samples. `describeKillCause` classifies an abnormal exit with a heap at or above 90% of its limit as out of memory even when the fatal line was lost with the truncated tail.
+
+  Full analysis — timeline, root causes, and the requirement-by-requirement plan — is in `docs/case-studies/issue-2189/`. Two upstream issues were filed from it: `link-foundation/start#165` (a V8 self-abort is reported as `oomKilled=false` with no memory signal in `--status`) and `link-foundation/start#164` (command argv is flattened with `join(' ')`, so quoted arguments are re-parsed by the inner shell).
+
 ## 2.15.2
 
 ### Patch Changes

package/package.json

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

package/src/bot-lifecycle.lib.mjs

@@ -12,7 +12,7 @@
  * @see https://github.com/link-assistant/hive-mind/issues/1927
  */
 
-import { RESOURCE_PHASE_BOT_HEARTBEAT, captureResourceSnapshot, summarizeResourceSnapshot } from './solve.resource-diagnostics.lib.mjs';
+import { RESOURCE_PHASE_BOT_HEARTBEAT, captureResourceSnapshot, formatHeapUsage, isHeapUnderPressure, summarizeResourceSnapshot } from './solve.resource-diagnostics.lib.mjs';
 
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 60 * 1000;
 
@@ -51,6 +51,13 @@ export function createHeartbeat({ logger, getActiveSessionCount, intervalMs = DE
         uptimeSec: Math.floor(processImpl.uptime()),
         resources,
       });
+      // Issue #2189: the bot walked from 1.78 GB to 1.84 GB of RSS against its
+      // own ~2 GB heap cap while re-reporting one dead session, and nothing in
+      // the log said so until it died (#733). The heartbeat is the one place
+      // that samples the bot itself, so it is where the warning belongs.
+      if (isHeapUnderPressure(resources?.memory) && typeof logger.warn === 'function') {
+        logger.warn(`Bot V8 heap is under pressure: ${formatHeapUsage(resources.memory)} — the process will abort with "JavaScript heap out of memory" if it keeps growing`, { heap: resources.memory });
+      }
     } catch {
       /* heartbeat must never crash the bot */
     }

package/src/child-exit.lib.mjs

@@ -74,6 +74,58 @@ export const describeChildExit = ({ command, code = null, signal = null }) => {
  */
 export const isLikelyOutOfMemoryExit = ({ code = null, signal = null }) => signal === 'SIGABRT' || signal === 'SIGKILL' || (signal === null && code === 134);
 
+/**
+ * Fatal lines a runtime prints when it exhausts its *own* heap.
+ *
+ * Issue #2189: a session died of `FATAL ERROR: Reached heap limit Allocation
+ * failed - JavaScript heap out of memory` and was reported to the user as a
+ * "forced kill … memory (10.3 GB of 11.7 GB RAM available)". Both statements
+ * were individually true: V8 stopped at its own ~2 GB old-space cap long before
+ * the machine or the container cgroup felt any pressure, so `docker inspect`
+ * said `OOMKilled=false` and `/sys/fs/cgroup/memory.events` said `oom_kill=0`.
+ * Nothing outside the process can observe a runtime self-abort — the only
+ * evidence is the text the runtime printed on its way out, which was sitting in
+ * the log the diagnostics were already reading.
+ *
+ * The patterns are deliberately specific (a bare "out of memory" also appears in
+ * Hive Mind's own diagnostic wording, which ends up in the same logs). Hive Mind
+ * spawns more than Node, so the other runtimes it drives are covered too.
+ */
+export const FATAL_MEMORY_PATTERNS = [
+  { id: 'v8-heap-limit', runtime: 'Node.js/V8', pattern: /FATAL ERROR:[^\n]*Reached heap limit/ },
+  { id: 'v8-ineffective-mark-compacts', runtime: 'Node.js/V8', pattern: /FATAL ERROR:[^\n]*Ineffective mark-compacts near heap limit/ },
+  { id: 'v8-heap-out-of-memory', runtime: 'Node.js/V8', pattern: /JavaScript heap out of memory/ },
+  { id: 'v8-last-few-gcs', runtime: 'Node.js/V8', pattern: /<--- Last few GCs --->/ },
+  { id: 'v8-array-buffer-allocation', runtime: 'Node.js/V8', pattern: /Array buffer allocation failed/ },
+  { id: 'rust-allocation-failed', runtime: 'Rust', pattern: /memory allocation of \d+ bytes failed/ },
+  { id: 'go-runtime-out-of-memory', runtime: 'Go', pattern: /fatal error: runtime: out of memory/ },
+  { id: 'cpp-bad-alloc', runtime: 'C/C++', pattern: /std::bad_alloc/ },
+];
+
+/**
+ * Find the first runtime self-abort marker in a piece of log text.
+ *
+ * Callers must only treat a hit as a cause when the process actually ended
+ * abnormally — the marker upgrades an existing kill to "out of memory", it never
+ * invents one, so an unrelated log that merely quotes the string cannot turn a
+ * healthy run into a reported crash.
+ *
+ * @param {string|null} text - Log text (a tail is enough; the marker is printed last)
+ * @returns {{id: string, runtime: string, line: string}|null}
+ */
+export const findFatalMemoryMarker = text => {
+  if (!text || typeof text !== 'string') return null;
+  for (const { id, runtime, pattern } of FATAL_MEMORY_PATTERNS) {
+    const match = pattern.exec(text);
+    if (!match) continue;
+    const lineStart = text.lastIndexOf('\n', match.index) + 1;
+    const lineEndIndex = text.indexOf('\n', match.index);
+    const line = text.slice(lineStart, lineEndIndex < 0 ? undefined : lineEndIndex).trim();
+    return { id, runtime, line: line.length > 300 ? `${line.slice(0, 300)}…` : line };
+  }
+  return null;
+};
+
 /**
  * Wire `close`/`error` handlers that never lose a signal.
  *
@@ -104,4 +156,4 @@ export const attachChildExitHandlers = ({ child, command, label, errorLabel = la
   });
 };
 
-export default { describeChildExit, isLikelyOutOfMemoryExit, attachChildExitHandlers };
+export default { describeChildExit, isLikelyOutOfMemoryExit, findFatalMemoryMarker, attachChildExitHandlers };

package/src/claude.session-tokens.lib.mjs

@@ -22,6 +22,7 @@ import Decimal from 'decimal.js-light';
 import { accumulateModelUsage, createEmptySubSessionUsage, getRawRequestInputTokens, mergeResultModelUsage } from './claude.budget-stats.lib.mjs';
 import { calculateModelCost } from './claude.cost.lib.mjs';
 import { fetchModelInfo } from './model-info.lib.mjs';
+import { forEachLogLine } from './log-bounded-read.lib.mjs';
 
 export const calculateSessionTokens = async (sessionId, tempDir, resultModelUsage = null, options = {}) => {
   const homeDir = options.homeDir || os.homedir();
@@ -43,10 +44,12 @@ export const calculateSessionTokens = async (sessionId, tempDir, resultModelUsag
   let currentSubSession = createEmptySubSessionUsage();
   const compactifications = [];
   try {
-    const fileContent = await fs.readFile(sessionFile, 'utf8');
-    const lines = fileContent.trim().split('\n');
-    for (const line of lines) {
-      if (!line.trim()) continue;
+    // Issue #2189: read the transcript one record at a time. A long Claude
+    // session produces a JSONL of unbounded size, and `readFile(...).split('\n')`
+    // held the whole file *and* the array of its lines before the first entry
+    // was priced — a full-file allocation just to sum token counters.
+    await forEachLogLine(sessionFile, line => {
+      if (!line.trim()) return;
       try {
         const entry = JSON.parse(line);
         if (entry.type === 'system' && entry.subtype === 'compact_boundary') {
@@ -59,7 +62,7 @@ export const calculateSessionTokens = async (sessionId, tempDir, resultModelUsag
             trigger: entry.compactMetadata?.trigger || 'unknown',
           });
           currentSubSession = createEmptySubSessionUsage();
-          continue;
+          return;
         }
         if (entry.message && entry.message.usage && entry.message.model) {
           // Issue #1501: Skip duplicate JSONL entries (same message ID = same API response)
@@ -67,7 +70,7 @@ export const calculateSessionTokens = async (sessionId, tempDir, resultModelUsag
           if (msgId) {
             if (seenMessageIds.has(msgId)) {
               duplicateCount++;
-              continue;
+              return;
             }
             seenMessageIds.add(msgId);
           }
@@ -100,9 +103,8 @@ export const calculateSessionTokens = async (sessionId, tempDir, resultModelUsag
         }
       } catch {
         // Skip lines that aren't valid JSON
-        continue;
       }
-    }
+    });
     if (currentSubSession.messageCount > 0) {
       subSessions.push(currentSubSession);
     }

package/src/claude.session-transcript-repair.lib.mjs

@@ -25,6 +25,8 @@ import { promises as fs } from 'fs';
 import os from 'os';
 import path from 'path';
 
+import { fileEndsWithNewline, forEachLogLine } from './log-bounded-read.lib.mjs';
+
 /**
  * Resolve the on-disk session transcript path for a Claude Code session. Claude Code stores each
  * session as `~/.claude/projects/<cwd-with-slashes-as-dashes>/<sessionId>.jsonl` (mirrors the
@@ -52,6 +54,36 @@ const isCorruptedThinkingBlock = block => {
   return false;
 };
 
+/**
+ * Repair one transcript record.
+ *
+ * Returns the line to write back (unchanged unless a corrupted block was
+ * dropped), how many corrupted blocks it dropped, and whether the line counted
+ * as a scanned message line. Keeping the decision in one pure function lets the
+ * repair stream the file twice — count, then rewrite — with identical results.
+ *
+ * @param {string} line - One raw JSONL record
+ * @returns {{text: string, removed: number, scanned: number}}
+ */
+const repairTranscriptLine = line => {
+  if (!line.trim()) return { text: line, removed: 0, scanned: 0 };
+  let entry;
+  try {
+    entry = JSON.parse(line);
+  } catch {
+    return { text: line, removed: 0, scanned: 1 }; // preserve anything we can't parse verbatim
+  }
+  const content = entry?.message?.content;
+  if (!Array.isArray(content)) return { text: line, removed: 0, scanned: 1 };
+  const corrupted = content.filter(isCorruptedThinkingBlock).length;
+  if (corrupted === 0) return { text: line, removed: 0, scanned: 1 };
+  const cleaned = content.filter(b => !isCorruptedThinkingBlock(b));
+  // Never leave an assistant message with an empty content array (invalid for the API).
+  if (cleaned.length === 0) return { text: line, removed: 0, scanned: 1 };
+  entry.message.content = cleaned;
+  return { text: JSON.stringify(entry), removed: corrupted, scanned: 1 };
+};
+
 /**
  * Strip corrupted (empty-text) thinking blocks from a Claude Code session transcript so the session
  * can be resumed. Conservative and side-effect-safe:
@@ -75,48 +107,27 @@ export const repairCorruptedThinkingBlocks = async ({ tempDir, sessionId, homeDi
   }
   const sessionFile = resolveSessionTranscriptPath(tempDir, sessionId, homeDir);
   result.sessionFile = sessionFile;
-  let fileContent;
+  let sessionStat;
   try {
-    fileContent = await fs.readFile(sessionFile, 'utf8');
+    sessionStat = await fs.stat(sessionFile);
   } catch {
     // No transcript on disk (e.g. fresh run never persisted, or path mismatch) — nothing to repair.
     return { ...result, reason: 'session transcript not found' };
   }
 
   try {
-    const lines = fileContent.split('\n');
-    const out = [];
+    // Issue #2189: a session transcript grows with the session — the captured
+    // incident's was 134 MB — so this is done in two streaming passes instead of
+    // holding the file, its array of lines and the rebuilt output in the heap at
+    // once. Pass 1 only counts: a transcript with nothing to repair (the common
+    // case) is never rewritten and never copied.
     let removedBlocks = 0;
     let scannedLines = 0;
-    for (const line of lines) {
-      if (!line.trim()) {
-        out.push(line);
-        continue;
-      }
-      scannedLines++;
-      let entry;
-      try {
-        entry = JSON.parse(line);
-      } catch {
-        out.push(line); // preserve anything we can't parse verbatim
-        continue;
-      }
-      const content = entry?.message?.content;
-      if (Array.isArray(content)) {
-        const corrupted = content.filter(isCorruptedThinkingBlock).length;
-        if (corrupted > 0) {
-          const cleaned = content.filter(b => !isCorruptedThinkingBlock(b));
-          // Never leave an assistant message with an empty content array (invalid for the API).
-          if (cleaned.length > 0) {
-            entry.message.content = cleaned;
-            removedBlocks += corrupted;
-            out.push(JSON.stringify(entry));
-            continue;
-          }
-        }
-      }
-      out.push(line);
-    }
+    await forEachLogLine(sessionFile, line => {
+      const repaired = repairTranscriptLine(line);
+      scannedLines += repaired.scanned;
+      removedBlocks += repaired.removed;
+    });
 
     result.scannedLines = scannedLines;
     if (removedBlocks === 0) {
@@ -135,7 +146,27 @@ export const repairCorruptedThinkingBlocks = async ({ tempDir, sessionId, homeDi
       }
     }
 
-    await fs.writeFile(sessionFile, out.join('\n'), 'utf8');
+    // Pass 2: rewrite through a sibling temp file and rename over the original,
+    // so an interrupted repair can never leave a half-written transcript (which
+    // would be worse than the corruption being repaired).
+    const keepTrailingNewline = await fileEndsWithNewline(sessionFile);
+    const tempFile = `${sessionFile}.repair-${process.pid}`;
+    await fs.rm(tempFile, { force: true });
+    const handle = await fs.open(tempFile, 'wx', sessionStat.mode & 0o777);
+    try {
+      let pendingSeparator = '';
+      await forEachLogLine(sessionFile, line => {
+        const repaired = repairTranscriptLine(line);
+        return handle.write(`${pendingSeparator}${repaired.text}`, null, 'utf8').then(() => {
+          pendingSeparator = '\n';
+        });
+      });
+      if (keepTrailingNewline) await handle.write('\n', null, 'utf8');
+    } finally {
+      await handle.close();
+    }
+    await fs.rename(tempFile, sessionFile);
+
     result.repaired = true;
     result.removedBlocks = removedBlocks;
     await log(`🩹 Repaired session transcript: stripped ${removedBlocks} corrupted thinking block(s) from ${scannedLines} message line(s) (Issue #1834). Backup: ${backupFile}`, { verbose: true });

package/src/codex.lib.mjs

@@ -49,10 +49,15 @@ import Decimal from 'decimal.js-light';
 import { ensureAiToolScratchIgnored, filterAiToolScratchFromStatus } from './ai-tool-scratch.lib.mjs';
 import { CODEX_CACHE_READ_USAGE_PATHS, CODEX_CACHE_WRITE_USAGE_PATHS, CODEX_MODEL_DIAGNOSTIC_PATHS, CODEX_REASONING_USAGE_PATHS, CODEX_USAGE_FIELD_NAMES, createCodexTokenFieldAvailability, getFirstObservedNumber, hasAnyObservedPath, hasOwnPath } from './codex.usage-fields.lib.mjs';
 const CODEX_LONG_CONTEXT_PRICE_THRESHOLD = 272000;
+// Issue #2189: ceiling for reading Codex's `--output-last-message` artifact. A
+// final assistant message is a few hundred kilobytes at most; anything larger is
+// a malfunction and must not be turned into an unbounded string.
+const CODEX_LAST_MESSAGE_MAX_BYTES = 1024 * 1024;
 const getCodexExecEnv = (verbose = false) => (verbose ? { ...process.env, RUST_LOG: 'debug' } : { ...process.env });
 // Issue #2175: diagnostic-line parsing lives in its own module to keep this file
 // under the 1350-line warning threshold.
 import { parseCodexDiagnosticLine, rebuildCodexSubSessionsFromCompactifications } from './codex.diagnostics.lib.mjs';
+import { readLogHeadText } from './log-bounded-read.lib.mjs'; // Issue #2189
 export const createCodexTokenUsage = requestedModelId => ({
   inputTokens: 0,
   outputTokens: 0,
@@ -891,7 +896,12 @@ export const executeCodexCommand = async params => {
       let lastMessageFromFile = null;
       let lastMessageReadError = null;
       try {
-        lastMessageFromFile = (await fs.readFile(lastMessageFile, 'utf8')).trim();
+        // Issue #2189: this file holds Codex's final assistant message, but its
+        // size is decided by the tool, not by us. Size it first so a runaway or
+        // corrupted artifact cannot become an unbounded string in a process that
+        // has just finished a long run.
+        const { size } = await fs.stat(lastMessageFile);
+        lastMessageFromFile = size > CODEX_LAST_MESSAGE_MAX_BYTES ? `${(await readLogHeadText(lastMessageFile, { maxBytes: CODEX_LAST_MESSAGE_MAX_BYTES })).trim()}\n…[last message truncated: ${size} bytes on disk, see ${lastMessageFile}]` : (await fs.readFile(lastMessageFile, 'utf8')).trim();
       } catch (readError) {
         lastMessageReadError = readError;
       }

package/src/development-log.lib.mjs

@@ -2,6 +2,8 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { sanitizeForPublication } from './token-sanitization.lib.mjs';
+import { findResidualCredentialBlock } from './log-sanitize-stream.lib.mjs';
+import { sanitizeLogFileToFileBounded } from './log-sanitize-worker.lib.mjs';
 
 const sanitizePathSegment = (value, fallback) => {
   const raw = value === null || value === undefined || value === '' ? fallback : String(value);
@@ -94,13 +96,25 @@ const writePrivatePublicationFile = async (destinationPath, content) => {
   await fs.chmod(destinationPath, 0o600);
 };
 
+// Issue #2189: `sanitizeLogFileToFileBounded` creates its destination exclusively
+// (`wx`) so a pre-planted symlink cannot be followed. Collection may run more
+// than once for the same session directory, so drop a previous artifact first —
+// unlink-then-O_EXCL keeps the symlink guarantee that a plain truncate loses.
+const sanitizeIntoPublicationFile = async ({ sourcePath, destinationPath, startByte = 0, endByte = null }) => {
+  await fs.rm(destinationPath, { force: true });
+  return sanitizeLogFileToFileBounded({ sourcePath, destPath: destinationPath, startByte, endByte });
+};
+
 const copyIfExists = async ({ sourcePath, destinationPath }) => {
   if (!(await fileExists(sourcePath))) return false;
   // Raw local audit sources remain available to the operator but must not be
   // group/world-readable. Only the sanitized copy enters the repository.
   await fs.chmod(sourcePath, 0o600);
-  const content = await fs.readFile(sourcePath, 'utf8');
-  await writePrivatePublicationFile(destinationPath, content);
+  // Issue #2189: transcripts are as large as the run that produced them (the
+  // captured incident had a 134 MB one). Sanitize source → destination block by
+  // block instead of holding the file, its sanitized twin and the sanitizer's
+  // own working copy in the heap at once.
+  await sanitizeIntoPublicationFile({ sourcePath, destinationPath });
   return true;
 };
 
@@ -140,8 +154,7 @@ const copyLogSlice = async ({ logFile, destinationPath, logStartByte = 0 }) => {
     await writePrivatePublicationFile(destinationPath, '');
     return { logStartByte: start, logEndByte: stat.size };
   }
-  const bytes = await fs.readFile(logFile);
-  await writePrivatePublicationFile(destinationPath, bytes.subarray(start, stat.size).toString('utf8'));
+  await sanitizeIntoPublicationFile({ sourcePath: logFile, destinationPath, startByte: start, endByte: stat.size });
   return { logStartByte: start, logEndByte: stat.size };
 };
 
@@ -279,9 +292,11 @@ const verifyDevelopmentLogDirectory = async directoryPath => {
     if (!entry.isFile()) continue;
     const parentPath = entry.parentPath || entry.path;
     const filePath = path.join(parentPath, entry.name);
-    const exactBytes = await fs.readFile(filePath, 'utf8');
-    const rescanned = await sanitizeForPublication(exactBytes);
-    if (rescanned !== exactBytes) {
+    // Issue #2189: rescan block by block. Reading each artifact back whole made
+    // the verification cost as much heap as the artifact — on top of the copy
+    // that had just been written.
+    const residual = await findResidualCredentialBlock(filePath);
+    if (residual) {
       throw new Error('Development-log publication rescan found residual credential material.');
     }
     await fs.chmod(filePath, 0o600);

package/src/github-error-reporter.lib.mjs

@@ -9,6 +9,8 @@ import { createInterface } from 'readline';
 import { log, cleanErrorMessage, getAbsoluteLogPath } from './lib.mjs';
 import { reportError, isSentryEnabled } from './sentry.lib.mjs';
 import { sanitizeForPublication, writeSanitizedPublicationFile } from './token-sanitization.lib.mjs';
+import { sanitizeLogFileToFileBounded } from './log-sanitize-worker.lib.mjs';
+import { readLogTailText } from './log-bounded-read.lib.mjs';
 
 if (typeof globalThis.use === 'undefined') {
   await ensureUseM();
@@ -107,8 +109,87 @@ const createSecretGist = async (logContent, filename) => {
   return null;
 };
 
+/**
+ * Upload a log FILE as a secret gist without ever holding it in memory.
+ *
+ * Issue #2189: the error reporter runs when the process is already in trouble —
+ * frequently because it just exhausted its heap. Reading the log to sanitize it
+ * (`readFile` + `sanitizeForPublication` + write = three full copies) is the one
+ * thing that must not happen there.
+ *
+ * @param {string} logFilePath - Log to upload
+ * @param {string} filename - Name for the gist file
+ * @returns {Promise<string|null>} Gist URL, or null when the upload failed
+ */
+const createSecretGistFromFile = async (logFilePath, filename) => {
+  const tempFile = `/tmp/${filename}`;
+  try {
+    await sanitizeLogFileToFileBounded({ sourcePath: logFilePath, destPath: tempFile });
+    const result = await $`gh gist create ${tempFile} --secret --desc "Error log for hive-mind"`;
+    if (result.exitCode === 0) {
+      return result.stdout.toString().trim();
+    }
+  } catch (error) {
+    reportError(error, {
+      context: 'create_secret_gist',
+      operation: 'gh_gist_create',
+    });
+  } finally {
+    await fs.unlink(tempFile).catch(() => {});
+  }
+  return null;
+};
+
+/**
+ * Format a log FILE for an issue body, choosing the attachment method from the
+ * file's size before reading any of it (issue #2189).
+ *
+ * Only the inline branch — by definition below GitHub's 60 kB issue-body limit —
+ * ever reads log content, and the truncated fallback reads a bounded tail.
+ *
+ * @param {string} logFilePath - Path to the log file
+ * @returns {Promise<{method: string, content: string}>}
+ */
+export const formatLogFileForIssue = async logFilePath => {
+  const { size } = await fs.stat(logFilePath);
+
+  if (size < GITHUB_ISSUE_BODY_MAX_SIZE) {
+    const logContent = await fs.readFile(logFilePath, 'utf8');
+    return {
+      method: 'inline',
+      content: `\`\`\`\n${logContent}\n\`\`\``,
+    };
+  }
+
+  if (size < GITHUB_FILE_MAX_SIZE) {
+    return {
+      method: 'file',
+      content: `Log file is too large to include inline. Please see the attached log file.\n\nLog file path: \`${logFilePath}\``,
+    };
+  }
+
+  const gistUrl = await createSecretGistFromFile(logFilePath, `hive-mind-error-${Date.now()}.log`);
+  if (gistUrl) {
+    return {
+      method: 'gist',
+      content: `Log file is too large for inline attachment.\n\n📄 View full log: ${gistUrl}`,
+    };
+  }
+
+  const tail = await readLogTailText(logFilePath, { maxBytes: 5000 });
+  return {
+    method: 'truncated',
+    content: `Log file is too large. Showing last 5000 characters:\n\n\`\`\`\n${tail}\n\`\`\``,
+  };
+};
+
 /**
  * Format log content for issue body
+ *
+ * Prefer {@link formatLogFileForIssue} when the log is a file on disk: this
+ * variant needs the whole log as a string, which is exactly what issue #2189
+ * removed from the publication path.
+ *
  * @param {string} logContent - Log file content
  * @param {string} logFilePath - Path to log file
  * @returns {Promise<Object>} Object with formatted content and attachment method
@@ -202,8 +283,9 @@ export const createIssueForError = async options => {
 
     if (logFile) {
       try {
-        const logContent = await fs.readFile(logFile, 'utf8');
-        const { method, content } = await formatLogForIssue(logContent, logFile);
+        // Issue #2189: pick the attachment method from the file size first; a
+        // log too large for the issue body is never read into memory here.
+        const { method, content } = await formatLogFileForIssue(logFile);
 
         issueBody += `### Log File\n\n${content}\n\n`;
         await log(`📄 Log attached via: ${method}`);