@link-assistant/hive-mind 2.15.2 → 2.16.0

package/src/session-monitor.lib.mjs

@@ -25,7 +25,8 @@ import { formatSessionCompletionMessage, getSessionCompletionExitCode, classifyS
 import { notifySubscribers, getSubscriberCount } from './telegram-subscribers.lib.mjs';
 import { safeSendMessage, safeEditMessageText } from './telegram-safe-reply.lib.mjs';
 import { classifyExitStatus, normalizeExitCode } from './session-status.lib.mjs';
-import { readLastSessionIdFromLog, buildResumeCommand, formatResumeSection } from './session-resume.lib.mjs';
+import { buildResumeCommand, formatResumeSection } from './session-resume.lib.mjs';
+import { readLogMarkerLines, readLogTextBounded, scanLogTextChunks } from './log-bounded-read.lib.mjs';
 import { resolveFailedSessionPullRequestState } from './github-pr-state.lib.mjs';
 // Issue #2117: a docker terminal failure that no anchored log footer corroborates may be an exit code start-command fabricated from the command's own output.
 import { clearUnverifiedDockerTerminalMarker as clearUnverifiedDockerTerminalMarkerImpl, shouldDeferUnverifiedDockerTerminal as shouldDeferUnverifiedDockerTerminalImpl } from './session-monitor.docker-terminal.lib.mjs';
@@ -33,6 +34,8 @@ import { isDockerIsolation, sessionStartMs, resolveOomKilledState, resolveStaleE
 // Issue #2134: kill-cause diagnostics + the matching pull-request notice.
 import { buildKillCompletionSections, announceKillOnPullRequest } from './session-monitor.kill-sections.lib.mjs';
 import { runKillRecoveryForCompletion } from './session-kill-resume.lib.mjs';
+// Issue #2189: the handled latch + the memoized last-tool-session-id read that keep a completed session from replaying its whole completion pipeline on every poll.
+import { isCompletionHandled, markCompletionHandled, resolveCachedLastToolSessionId } from './session-completion-state.lib.mjs';
 import { createSessionRegistryQueries } from './session-monitor.queries.lib.mjs';
 export { formatSessionCompletionMessage, getSessionCompletionExitCode } from './work-session-formatting.lib.mjs';
 export { DOCKER_TERMINAL_FOOTER_GRACE_MS } from './session-monitor.docker-terminal.lib.mjs';
@@ -326,6 +329,8 @@ function normalizeSessionUrl(url) {
   return url.replace(/#.*$/, '').replace(/\/+$/, '').toLowerCase();
 }
 const GITHUB_PULL_REQUEST_URL_RE = /https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/pull\/([0-9]+)/g;
+/** Marker prefix parsed by `parseDiskMarkers` (issue #1945/#1988), used to collect just those lines. */
+const DISK_MARKER_LINE_RE = /📊 \[DISK\] /;
 export function extractPullRequestUrlFromText(text, { owner = null, repo = null } = {}) {
   if (!text) return null;
   const expectedOwner = owner ? String(owner).toLowerCase() : null;
@@ -344,8 +349,12 @@ export function extractPullRequestUrlFromText(text, { owner = null, repo = null
 async function resolvePullRequestUrlFromSessionLog(logPath, ctx, { verbose = false, readFile = fs.readFile } = {}) {
   if (!logPath) return null;
   try {
-    const logText = await readFile(logPath, 'utf8');
-    const pullRequestUrl = extractPullRequestUrlFromText(logText, { owner: ctx.owner, repo: ctx.repo });
+    // Issue #2189: this used to be `readFile(logPath, 'utf8')`, run once per
+    // monitor tick for a session the bot never marked handled — a 134 MB
+    // transcript pulled into the bot's own heap over and over. The chunked scan
+    // still covers the whole log, one chunk at a time, and stops at the first
+    // matching URL (which is printed early, when the PR is created).
+    const pullRequestUrl = await scanLogTextChunks(logPath, text => extractPullRequestUrlFromText(text, { owner: ctx.owner, repo: ctx.repo }), { readFile, verbose });
     if (pullRequestUrl && verbose) {
       console.log(`[VERBOSE] Found PR ${pullRequestUrl} in completed session log ${logPath}`);
     }
@@ -370,7 +379,10 @@ export async function buildDiskDiagnosticsExtraSection(logPath, { verbose = fals
     let logText = '';
     if (logPath) {
       try {
-        logText = await readFile(logPath, 'utf8');
+        // Issue #2189: `parseDiskMarkers` only ever looks at `📊 [DISK]` lines,
+        // so collect those lines instead of the whole transcript. Cost is one
+        // chunk plus a few kilobytes of markers, whatever the log's size.
+        logText = await readLogMarkerLines(logPath, DISK_MARKER_LINE_RE, { readFile, verbose });
       } catch (readError) {
         if (verbose) {
           console.log(`[VERBOSE] Could not read session log ${logPath} for disk diagnostics: ${readError?.message || readError}`);
@@ -402,7 +414,10 @@ export async function buildSubscriptionBlockedExtraSection(logPath, { verbose =
   try {
     let logText = '';
     try {
-      logText = await readFile(logPath, 'utf8');
+      // Issue #2189: the blocked report is printed as the run stops, so the
+      // bounded head+tail excerpt always contains it; the middle of a multi-
+      // gigabyte transcript never has to be resident to find it.
+      logText = await readLogTextBounded(logPath, { readFile, verbose });
     } catch (readError) {
       if (verbose) {
         console.log(`[VERBOSE] Could not read session log ${logPath} for subscription block: ${readError?.message || readError}`);
@@ -439,6 +454,35 @@ async function getDockerContainerFilesystemSizeForSession(sessionName, sessionIn
     return null;
   }
 }
+/**
+ * How long a docker writable-layer measurement stays good enough while the
+ * session is still running (issue #2189).
+ *
+ * `docker ps --size` walks the container's whole writable layer. On the 27 GB
+ * layer in the captured incident that is expensive, and the monitor was paying
+ * it once per session per 30-second poll for no gain: the number is only ever
+ * *reported* at completion. The completion measurement is never throttled, so
+ * the number in the report is still fresh.
+ */
+export const DOCKER_FILESYSTEM_REFRESH_INTERVAL_MS = 5 * 60 * 1000;
+/**
+ * Whether the writable-layer size should be measured on this poll.
+ *
+ * @param {Object} sessionInfo
+ * @param {Object} [options]
+ * @param {boolean} [options.stillRunning] - The session is still executing
+ * @param {number} [options.now] - Epoch ms (injectable for tests)
+ * @param {number} [options.intervalMs]
+ * @returns {boolean}
+ */
+export function shouldRefreshDockerFilesystemSize(sessionInfo, { stillRunning = true, now = Date.now(), intervalMs = DOCKER_FILESYSTEM_REFRESH_INTERVAL_MS } = {}) {
+  if (sessionInfo?.isolationBackend !== 'docker') return false;
+  // The completion report quotes this number, so it is always measured fresh.
+  if (!stillRunning) return true;
+  const observedAt = Date.parse(sessionInfo?.containerFilesystemLastObservedAt || '');
+  if (!Number.isFinite(observedAt)) return true;
+  return now - observedAt >= intervalMs;
+}
 async function refreshDockerContainerFilesystemSizeForSession(sessionName, sessionInfo, { verbose = false, sizeProvider = null } = {}) {
   const bytes = await getDockerContainerFilesystemSizeForSession(sessionName, sessionInfo, { verbose, sizeProvider });
   if (!Number.isFinite(bytes)) return null;
@@ -665,6 +709,20 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
     console.log(`[VERBOSE] Checking ${sessions.length} active session(s)...`);
   }
   for (const { sessionName, sessionInfo } of sessions) {
+    // Issue #2189: a session whose completion notification was already
+    // delivered is terminal. Without this latch the monitor re-entered the whole
+    // completion pipeline on every poll — re-resolving the linked pull request,
+    // re-scanning a 134 MB log, re-walking a 27 GB writable layer and re-sending
+    // a notification the user already had — because a late failure in that
+    // pipeline (or a bot restart) left the session tracked. Finalize it here,
+    // before any status probe, and do none of that work again.
+    if (isCompletionHandled(sessionInfo)) {
+      if (verbose) {
+        console.log(`[VERBOSE] Session ${sessionName} was already reported at ${sessionInfo.completionNotifiedAt}; finalizing without repeating the completion work (issue #2189)`);
+      }
+      completeSession(sessionName, sessionInfo.completionExitCode ?? 0, verbose, sessionInfo.completionStatus ?? null);
+      continue;
+    }
     let stillRunning;
     let exitCode = null;
     let statusResult = null;
@@ -727,11 +785,13 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
         }
       }
     }
-    if (sessionInfo?.isolationBackend === 'docker') {
+    if (shouldRefreshDockerFilesystemSize(sessionInfo, { stillRunning })) {
       observedContainerFilesystemBytes = await refreshDockerContainerFilesystemSizeForSession(sessionName, sessionInfo, {
         verbose,
         sizeProvider: options.dockerContainerSizeProvider,
       });
+    } else if (sessionInfo?.isolationBackend === 'docker' && verbose) {
+      console.log(`[VERBOSE] Session ${sessionName}: reusing the writable-layer size observed at ${sessionInfo.containerFilesystemLastObservedAt} (issue #2189: not re-walking the layer every poll)`);
     }
     if (!stillRunning) {
       console.log(`Session ${sessionName} has finished. Sending notification to chat ${sessionInfo.chatId}`);
@@ -756,6 +816,10 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
             statusResult,
             readFile: options.readFile,
           });
+          if (pullRequestUrl && sessionInfo.resolvedPullRequestUrl !== pullRequestUrl) {
+            sessionInfo.resolvedPullRequestUrl = pullRequestUrl;
+            persistSessionSnapshot(sessionName, sessionInfo);
+          }
         } catch (lookupError) {
           if (verbose) {
             console.log(`[VERBOSE] Pull request lookup failed for ${sessionName}: ${lookupError?.message || lookupError}`);
@@ -806,8 +870,20 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
             }
           }
         }
+        // Issue #2189: the last tool session id is read through the session
+        // record's cache, so the working-session log is scanned once per session
+        // instead of once per poll per consumer (the resume section below and the
+        // automatic recovery further down both need it, and both used to scan).
+        const resolveLastToolSessionId = logPath => {
+          const resolution = resolveCachedLastToolSessionId({ sessionInfo, logPath, verbose });
+          if (resolution.scanned) persistSessionSnapshot(sessionName, sessionInfo);
+          return resolution.id;
+        };
         // Issue #1927: for a killed /solve, offer a command using the last tool
-        // session ID in the log. Do not auto-relaunch work that may reliably OOM.
+        // session ID in the log. Issue #2189 additionally *starts* that command
+        // by default (`--on-session-kill=resume`), bounded by
+        // `--session-kill-resume-attempts`, so the work is not left for a human
+        // to notice hours later.
         const resumeExtraSections = [];
         let killResumeCommand = null;
         try {
@@ -821,7 +897,7 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
             //   `Session ID:` marker. Do not guess from neighboring UUID-named
             //   logs: start-command stores unrelated tasks in the same backend
             //   directory, which caused issue #2109's invalid resume id.
-            const lastSessionId = readLastSessionIdFromLog(logPath, { verbose });
+            const lastSessionId = resolveLastToolSessionId(logPath);
             const resumeCommand = buildResumeCommand({ sessionInfo, lastSessionId });
             const resumeSection = formatResumeSection({ lastSessionId, command: resumeCommand });
             killResumeCommand = resumeCommand || null;
@@ -900,10 +976,21 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
             runner: options.isolationRunner || null,
             trackSession: options.trackSession || trackSession,
             persistSnapshot: () => persistSessionSnapshot(sessionName, sessionInfo),
+            // Issue #2189: reuse the id already read above instead of scanning
+            // the same (possibly multi-gigabyte) log a second time.
+            readLastSessionId: logPath => resolveLastToolSessionId(logPath),
             locale: sessionInfo?.locale || null,
             verbose,
           });
           killRecovery = recovered.recovery;
+          if (killRecovery.resumed && killRecovery.sessionId) {
+            // Issue #2189: remember which session took over, so the durable
+            // history says what happened to this work and a restart cannot start
+            // a second recovery for the same kill.
+            sessionInfo.killRecoverySessionId = killRecovery.sessionId;
+            persistSessionSnapshot(sessionName, sessionInfo);
+            logEvent('session_kill_recovered', { sessionName, recoverySessionId: killRecovery.sessionId, attempt: killRecovery.attempt, maxAttempts: killRecovery.maxAttempts, policy: killRecovery.policy || null });
+          }
           if (recovered.section) killReport.sections.push(recovered.section);
         }
         const message = formatSessionCompletionMessage({
@@ -952,6 +1039,16 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
           notifyFromChatId = sent?.chat?.id || sessionInfo.chatId;
           notifyMessageId = sent?.message_id || null;
         }
+        // Issue #2189: the user has now been told. Latch that fact durably
+        // BEFORE the remaining best-effort work (subscriber fan-out, container
+        // cleanup), because any failure after this point used to send the whole
+        // completion pipeline — and this notification — round again on the next
+        // poll. The snapshot write means even a bot restart in this window
+        // finalizes the session silently instead of re-notifying.
+        if (markCompletionHandled(sessionInfo, { exitCode: finalExitCode, status: resolvedStatus })) {
+          persistSessionSnapshot(sessionName, sessionInfo);
+          logEvent('session_completion_notified', { sessionName, exitCode: finalExitCode ?? null, status: resolvedStatus || null, notifiedAt: sessionInfo.completionNotifiedAt });
+        }
         // Issue #1688: forward the same completion message to every /subscribe-d user
         //   in their private chat with the bot. Failures are logged but don't block
         //   completion of the parent session.
@@ -1024,6 +1121,13 @@ async function resolvePullRequestUrlForSession(sessionInfo, { verbose = false, l
   if (!ctx || ctx.type !== 'issue' || !ctx.owner || !ctx.repo || !ctx.number) {
     return null;
   }
+  // Issue #2189: a completion that has to be retried must not re-run the linked-PR
+  // lookup (an API round trip, then a scan of the session log). The answer cannot
+  // change for a session that has already finished, so remember it.
+  if (typeof sessionInfo.resolvedPullRequestUrl === 'string' && sessionInfo.resolvedPullRequestUrl) {
+    if (verbose) console.log(`[VERBOSE] Reusing resolved pull request ${sessionInfo.resolvedPullRequestUrl} for this session (not looked up again)`);
+    return sessionInfo.resolvedPullRequestUrl;
+  }
   if (typeof lookupLinkedPullRequest === 'function') {
     const linkedPullRequestUrl = await lookupLinkedPullRequest(ctx);
     if (linkedPullRequestUrl) return linkedPullRequestUrl;
@@ -1089,6 +1193,22 @@ export function startSessionMonitoring(bot, verbose = false, intervalMs = 30000,
  * record whose startTime is after the current bot start (it cannot belong to a
  * previous run), satisfying requirement #2's "started before bot start time".
  *
+ * Issue #2189 asks for the other half of that sentence — "on startup resume all
+ * still-running / interrupted commands". Both cases are handled here plus the
+ * first monitor tick, which runs synchronously after this function:
+ *
+ *   - a session that is **still running** keeps running; re-registering it is
+ *     exactly what resumes it, and the bot reports it when it ends;
+ *   - a session that was **interrupted** (its backend is gone, or its log footer
+ *     records a kill) is detected as finished on that first tick and, under the
+ *     now-default `--on-session-kill=resume`, a recovery working session is
+ *     started from its last tool session id — bounded by
+ *     `--session-kill-resume-attempts`, whose counter is persisted, so a job
+ *     that dies every time cannot be relaunched once per bot restart forever;
+ *   - a session that was already **reported** before the previous process died
+ *     carries the persisted `completionNotifiedAt` latch and is finalized
+ *     silently, so a restart never re-notifies.
+ *
  * @param {object} [options]
  * @param {object} [options.store] - Session store to load from (default: the store set via setSessionStore).
  * @param {number} [options.botStartTime] - Epoch seconds; only sessions started strictly before this are resumed. Defaults to now.
@@ -1137,7 +1257,10 @@ export async function resumeTrackedSessions(options = {}) {
     }
   }
   if (resumed.length > 0) {
-    console.log(`♻️  Resumed monitoring of ${resumed.length} session(s) from durable store after restart`);
+    // Issue #2189: say how many of these are already-reported leftovers, so the
+    // startup line is not read as "N sessions are still working".
+    const alreadyReported = resumed.filter(({ sessionInfo }) => isCompletionHandled(sessionInfo)).length;
+    console.log(`♻️  Resumed monitoring of ${resumed.length} session(s) from durable store after restart${alreadyReported > 0 ? ` (${alreadyReported} already reported, will be finalized silently)` : ''}`);
   } else if (verbose) {
     console.log('[VERBOSE] resumeTrackedSessions: no eligible sessions to resume');
   }

package/src/session-store.lib.mjs

@@ -38,7 +38,21 @@ import path from 'node:path';
 // `executionUuid` (#2154) is start-command's own identifier for the execution —
 // the one `$ --list` prints. It differs from `sessionId`, so persisting it is
 // what lets a restarted bot still correlate its sessions with the session list.
-const PERSISTABLE_FIELDS = ['chatId', 'messageId', 'startTime', 'url', 'command', 'commandAlias', 'isolationBackend', 'sessionId', 'executionUuid', 'containerFilesystemStartBytes', 'containerFilesystemLastBytes', 'containerFilesystemLastObservedAt', 'tool', 'infoBlock', 'urlContext', 'requesterUserId', 'showLimits', 'locale', 'logPath', 'args'];
+// Issue #2189 adds the fields that keep a completed session terminal and its
+// per-poll cost constant:
+//   - `completionNotifiedAt`/`completionExitCode`/`completionStatus` latch the
+//     one delivered notification, so a restart between "notified" and
+//     "untracked" finalizes silently instead of re-running the whole completion
+//     pipeline and notifying the user again.
+//   - `lastToolSessionId` caches the marker found by scanning the working
+//     session log, so that scan is never O(log size) per poll.
+//   - `killRecoveryAttempts`/`killRecoverySessionId`/`killRecoveryOfSession`
+//     bound and record automatic recovery across restarts — without them a
+//     reliably-crashing job could restart once per bot launch forever.
+//   - `stopRequestedByUser`/`stopRequestedBy` must survive a restart too: with
+//     `--on-session-kill=resume` now the default, forgetting that an operator
+//     asked for the stop would relaunch the very work they cancelled.
+const PERSISTABLE_FIELDS = ['chatId', 'messageId', 'startTime', 'url', 'command', 'commandAlias', 'isolationBackend', 'sessionId', 'executionUuid', 'containerFilesystemStartBytes', 'containerFilesystemLastBytes', 'containerFilesystemLastObservedAt', 'tool', 'infoBlock', 'urlContext', 'requesterUserId', 'showLimits', 'locale', 'logPath', 'args', 'completionNotifiedAt', 'completionExitCode', 'completionStatus', 'lastToolSessionId', 'killRecoveryAttempts', 'killRecoverySessionId', 'killRecoveryOfSession', 'killRecoveryResumed', 'stopRequestedByUser', 'stopRequestedBy', 'onSessionKill', 'resolvedPullRequestUrl'];
 
 /**
  * Resolve the directory durable bot state is written to. Honors

package/src/solve.config.lib.mjs

@@ -159,9 +159,12 @@ export const SOLVE_OPTION_DEFINITIONS = {
   // solve honour the exact same value, so the report never differs by surface.
   'on-session-kill': {
     type: 'string',
-    description: 'What to do when a working session is killed (out of memory, disk full, forced kill): "report" describes exactly what happened in the pull request and in Telegram, "resume" additionally starts a new working session to recover and says so in both places. Can also be set with HIVE_MIND_ON_SESSION_KILL.',
+    description: 'What to do when a working session is killed (out of memory, disk full, forced kill): "resume" (default) starts a new working session from the killed one\'s last tool session id and says so in the pull request and in Telegram, "report" only describes exactly what happened without restarting anything. Can also be set with HIVE_MIND_ON_SESSION_KILL.',
     choices: ['report', 'resume'],
-    default: 'report',
+    // Issue #2189: a kill that is only ever *offered* for resume is a kill
+    // nobody recovers from — the offer in the captured incident reached its
+    // operator six hours late. Bounded by --session-kill-resume-attempts.
+    default: 'resume',
   },
   'session-kill-resume-attempts': {
     type: 'number',

package/src/solve.resource-diagnostics.lib.mjs

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import os from 'node:os';
+import v8 from 'node:v8';
 
 export const RESOURCE_MARKER_PREFIX = '📈 [RESOURCES]';
 
@@ -10,8 +11,19 @@ export const RESOURCE_PHASE_SOLVE_EXIT = 'solve_exit';
 export const RESOURCE_PHASE_RESTART_BEFORE = 'restart_before';
 export const RESOURCE_PHASE_RESTART_AFTER = 'restart_after';
 export const RESOURCE_PHASE_BOT_HEARTBEAT = 'bot_heartbeat';
+// Issue #2189: the run that died of a V8 heap OOM inside the log sanitizer had
+// its last resource sample at `after_agent` (RSS 373 MB), ten minutes before the
+// fatal error — the whole log-upload phase was untelemetered, so the post-mortem
+// could not tell a heap blow-up from an external kill. These phases bracket it.
+export const RESOURCE_PHASE_LOG_UPLOAD_START = 'log_upload_start';
+export const RESOURCE_PHASE_LOG_UPLOAD_END = 'log_upload_end';
 
-const RESOURCE_PHASES_BY_PREFERENCE = [RESOURCE_PHASE_SOLVE_EXIT, RESOURCE_PHASE_AFTER_AGENT, RESOURCE_PHASE_RESTART_AFTER, RESOURCE_PHASE_AFTER_CLONE, RESOURCE_PHASE_SOLVE_START, RESOURCE_PHASE_RESTART_BEFORE];
+// A V8 heap this close to its own limit is the shape of an imminent
+// "FATAL ERROR: Reached heap limit" abort; surface it while the process is
+// still alive to print it.
+export const HEAP_PRESSURE_WARN_PERCENT = 85;
+
+const RESOURCE_PHASES_BY_PREFERENCE = [RESOURCE_PHASE_SOLVE_EXIT, RESOURCE_PHASE_LOG_UPLOAD_END, RESOURCE_PHASE_LOG_UPLOAD_START, RESOURCE_PHASE_AFTER_AGENT, RESOURCE_PHASE_RESTART_AFTER, RESOURCE_PHASE_AFTER_CLONE, RESOURCE_PHASE_SOLVE_START, RESOURCE_PHASE_RESTART_BEFORE];
 
 function finiteNumber(value) {
   return Number.isFinite(value) ? value : null;
@@ -139,7 +151,7 @@ export function formatExecutionContextForLog(context) {
 }
 
 export function captureResourceSnapshot(options = {}) {
-  const { phase = 'snapshot', diskPath = '/', now = () => new Date(), osImpl = os, fsImpl = fs, processImpl = process } = options;
+  const { phase = 'snapshot', diskPath = '/', now = () => new Date(), osImpl = os, fsImpl = fs, processImpl = process, v8Impl = v8 } = options;
 
   const timestamp = (() => {
     try {
@@ -196,11 +208,26 @@ export function captureResourceSnapshot(options = {}) {
       return {
         rssBytes: finiteNumber(usage.rss),
         heapUsedBytes: finiteNumber(usage.heapUsed),
+        heapTotalBytes: finiteNumber(usage.heapTotal),
+        externalBytes: finiteNumber(usage.external),
       };
     } catch {
-      return { rssBytes: null, heapUsedBytes: null };
+      return { rssBytes: null, heapUsedBytes: null, heapTotalBytes: null, externalBytes: null };
+    }
+  })();
+
+  // Issue #2189: the heap *limit* is the number that was missing. A process can
+  // die of "JavaScript heap out of memory" with 10 GB of the machine still free,
+  // so RSS against total RAM says nothing; used heap against `heap_size_limit`
+  // says everything.
+  const heapLimitBytes = (() => {
+    try {
+      return finiteNumber(v8Impl.getHeapStatistics().heap_size_limit);
+    } catch {
+      return null;
     }
   })();
+  const heapUsedPercent = Number.isFinite(processMemory.heapUsedBytes) && Number.isFinite(heapLimitBytes) && heapLimitBytes > 0 ? clampPercent((processMemory.heapUsedBytes / heapLimitBytes) * 100) : null;
 
   const disk = (() => {
     const path = String(diskPath || '/');
@@ -243,6 +270,10 @@ export function captureResourceSnapshot(options = {}) {
       usedBytes: usedMemoryBytes,
       processRssBytes: processMemory.rssBytes,
       processHeapUsedBytes: processMemory.heapUsedBytes,
+      processHeapTotalBytes: processMemory.heapTotalBytes,
+      processExternalBytes: processMemory.externalBytes,
+      processHeapLimitBytes: heapLimitBytes,
+      processHeapUsedPercent: heapUsedPercent,
     },
     disk,
   };
@@ -270,6 +301,27 @@ function numberField(name, value) {
   return Number.isFinite(value) ? `${name}=${value}` : `${name}=null`;
 }
 
+/**
+ * Human-readable "used heap of the heap limit" summary. Issue #2189: this is the
+ * single line that would have made the incident self-diagnosing.
+ */
+export function formatHeapUsage(memory) {
+  const m = memory || {};
+  if (!Number.isFinite(m.processHeapUsedBytes)) return 'unknown';
+  const limit = Number.isFinite(m.processHeapLimitBytes) ? ` of ${formatBytes(m.processHeapLimitBytes)} limit` : '';
+  const percent = Number.isFinite(m.processHeapUsedPercent) ? ` (${m.processHeapUsedPercent.toFixed(1)}%)` : '';
+  return `${formatBytes(m.processHeapUsedBytes)} used${limit}${percent}`;
+}
+
+/**
+ * True when the V8 heap is close enough to its own limit that the next big
+ * allocation can abort the process (issue #2189).
+ */
+export function isHeapUnderPressure(memory, warnPercent = HEAP_PRESSURE_WARN_PERCENT) {
+  const percent = memory?.processHeapUsedPercent;
+  return Number.isFinite(percent) && percent >= warnPercent;
+}
+
 export function buildResourceMarker(snapshot) {
   const s = snapshot || {};
   const cpu = s.cpu || {};
@@ -287,6 +339,11 @@ export function buildResourceMarker(snapshot) {
     numberField('memAvailableBytes', memory.availableBytes),
     numberField('memUsedBytes', memory.usedBytes),
     numberField('processRssBytes', memory.processRssBytes),
+    numberField('processHeapUsedBytes', memory.processHeapUsedBytes),
+    numberField('processHeapTotalBytes', memory.processHeapTotalBytes),
+    numberField('processExternalBytes', memory.processExternalBytes),
+    numberField('processHeapLimitBytes', memory.processHeapLimitBytes),
+    numberField('processHeapUsedPercent', memory.processHeapUsedPercent),
     `diskPath=${encodeValue(disk.path || '/')}`,
     numberField('diskTotalBytes', disk.totalBytes),
     numberField('diskAvailableBytes', disk.availableBytes),
@@ -294,6 +351,7 @@ export function buildResourceMarker(snapshot) {
     numberField('diskUsedPercent', disk.usedPercent),
     disk.error ? `error=${encodeValue(disk.error)}` : null,
     `mem=${encodeValue(`${formatBytes(memory.availableBytes)} available / ${formatBytes(memory.totalBytes)} total`)}`,
+    `heap=${encodeValue(formatHeapUsage(memory))}`,
     `disk=${encodeValue(`${formatBytes(disk.availableBytes)} available / ${formatBytes(disk.totalBytes)} total`)}`,
   ]
     .filter(Boolean)
@@ -332,6 +390,11 @@ function parseMarkerLine(line) {
       availableBytes: parseNumber(fields.memAvailableBytes),
       usedBytes: parseNumber(fields.memUsedBytes),
       processRssBytes: parseNumber(fields.processRssBytes),
+      processHeapUsedBytes: parseNumber(fields.processHeapUsedBytes),
+      processHeapTotalBytes: parseNumber(fields.processHeapTotalBytes),
+      processExternalBytes: parseNumber(fields.processExternalBytes),
+      processHeapLimitBytes: parseNumber(fields.processHeapLimitBytes),
+      processHeapUsedPercent: parseNumber(fields.processHeapUsedPercent),
     },
     disk: {
       path: decodeURIComponent(fields.diskPath || '/'),
@@ -376,7 +439,8 @@ export function formatResourceSnapshotForLog(snapshot, label = null) {
   const cpu = s.cpu || {};
   const memory = s.memory || {};
   const disk = s.disk || {};
-  const lines = [`📈 Resource usage (${phaseLabel}):`, `   CPU load: ${formatNumber(cpu.load1)} ${formatNumber(cpu.load5)} ${formatNumber(cpu.load15)}${Number.isFinite(cpu.cpuCount) ? ` (${cpu.cpuCount} CPUs)` : ''}`, `   Memory: ${formatBytes(memory.availableBytes)} available / ${formatBytes(memory.totalBytes)} total (${formatBytes(memory.usedBytes)} used)`, `   Process RSS: ${formatBytes(memory.processRssBytes)}${Number.isFinite(memory.processHeapUsedBytes) ? `, heap ${formatBytes(memory.processHeapUsedBytes)}` : ''}`, `   Disk (${disk.path || '/'}): ${formatBytes(disk.availableBytes)} available / ${formatBytes(disk.totalBytes)} total${Number.isFinite(disk.usedPercent) ? ` (${disk.usedPercent.toFixed(1)}% used)` : ''}`];
+  const lines = [`📈 Resource usage (${phaseLabel}):`, `   CPU load: ${formatNumber(cpu.load1)} ${formatNumber(cpu.load5)} ${formatNumber(cpu.load15)}${Number.isFinite(cpu.cpuCount) ? ` (${cpu.cpuCount} CPUs)` : ''}`, `   Memory: ${formatBytes(memory.availableBytes)} available / ${formatBytes(memory.totalBytes)} total (${formatBytes(memory.usedBytes)} used)`, `   Process RSS: ${formatBytes(memory.processRssBytes)}, V8 heap: ${formatHeapUsage(memory)}`, `   Disk (${disk.path || '/'}): ${formatBytes(disk.availableBytes)} available / ${formatBytes(disk.totalBytes)} total${Number.isFinite(disk.usedPercent) ? ` (${disk.usedPercent.toFixed(1)}% used)` : ''}`];
+  if (isHeapUnderPressure(memory)) lines.push(`   ⚠️  V8 heap is at ${memory.processHeapUsedPercent.toFixed(1)}% of its limit — a further allocation can abort the process with "JavaScript heap out of memory"`);
   if (disk.error) lines.push(`   Disk probe error: ${disk.error}`);
   lines.push(buildResourceMarker(snapshot));
   return lines.join('\n');
@@ -422,6 +486,9 @@ export function summarizeResourceSnapshot(snapshot) {
       availableBytes: memory.availableBytes,
       usedBytes: memory.usedBytes,
       processRssBytes: memory.processRssBytes,
+      processHeapUsedBytes: memory.processHeapUsedBytes,
+      processHeapLimitBytes: memory.processHeapLimitBytes,
+      processHeapUsedPercent: memory.processHeapUsedPercent,
     },
     disk: {
       path: disk.path,

package/src/telegram-log-command.lib.mjs

@@ -24,7 +24,8 @@ import path from 'path';
 import os from 'os';
 import fs from 'fs/promises';
 import { constants as fsConstants } from 'fs';
-import { sanitizeForPublication, writeSanitizedPublicationFile } from './token-sanitization.lib.mjs';
+import { sanitizeForPublication } from './token-sanitization.lib.mjs';
+import { sanitizeLogFileToFileBounded } from './log-sanitize-worker.lib.mjs';
 import { safeReply, safeReplyWithDocument, safeSendDocument } from './telegram-safe-reply.lib.mjs';
 
 const UUID_RE = /\b([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/i;
@@ -43,8 +44,11 @@ async function prepareSanitizedLogUpload(logPath, caption) {
   const sanitizedPath = path.join(tempDir, path.basename(logPath));
 
   try {
-    const [rawLog, safeCaption] = await Promise.all([fs.readFile(logPath, 'utf8'), sanitizeForPublication(caption)]);
-    await writeSanitizedPublicationFile(sanitizedPath, rawLog);
+    // Issue #2189: `/log` accepts files up to Telegram's 50 MB document limit,
+    // and this used to hold the log twice (raw string + sanitized string) plus a
+    // third copy inside the sanitizer. The streaming sanitizer writes the same
+    // artifact one block at a time, so a 50 MB log costs the same as a 50 kB one.
+    const [, safeCaption] = await Promise.all([sanitizeLogFileToFileBounded({ sourcePath: logPath, destPath: sanitizedPath }), sanitizeForPublication(caption)]);
     return {
       path: sanitizedPath,
       caption: safeCaption,

package/src/telegram-terminal-watch-command.lib.mjs

@@ -7,6 +7,7 @@
 
 import fs from 'fs/promises';
 import { extractSessionIdFromText, decideLogDestination, resolveLogPath } from './telegram-log-command.lib.mjs';
+import { readLogTailText } from './log-bounded-read.lib.mjs';
 import { parseSessionExitFooter } from './isolation-runner.lib.mjs';
 import { safeReply, safeSendMessage, safeEditMessageText } from './telegram-safe-reply.lib.mjs';
 import { classifyExitStatus, isFailureSessionStatus } from './session-status.lib.mjs';
@@ -15,6 +16,11 @@ const DEFAULT_WIDTH = 120;
 const DEFAULT_HEIGHT = 25;
 const DEFAULT_INTERVAL_MS = 2500;
 const DEFAULT_MAX_CHARS = 3400;
+// Issue #2189: the watch loop re-reads the log every `intervalMs`, but it only
+// ever renders the last `height` lines and looks for the exit footer, both of
+// which live at the very end. Reading the whole file made a poll tick cost
+// O(log size) — a 134 MB session log allocated 134 MB of string per tick.
+const TERMINAL_WATCH_TAIL_BYTES = 256 * 1024;
 const GITHUB_URL_RE = /https:\/\/github\.com\/[^\s"'`<>]+/i;
 const activeWatches = new Map();
 
@@ -141,7 +147,9 @@ export function formatTerminalWatchMessage({ sessionId, statusResult = null, log
 
 async function readLogFile(logPath) {
   try {
-    return await fs.readFile(logPath, 'utf8');
+    const { size } = await fs.stat(logPath);
+    if (!size) return '';
+    return await readLogTailText(logPath, { maxBytes: TERMINAL_WATCH_TAIL_BYTES });
   } catch (error) {
     if (error?.code === 'ENOENT') return '';
     throw error;