@link-assistant/hive-mind 2.15.2 → 2.17.0

package/src/solve.clone-errors.lib.mjs

@@ -0,0 +1,86 @@
+/**
+ * Clone failure classification and partial-clone cleanup for the solve command.
+ *
+ * Extracted from solve.repository.lib.mjs, which had grown past the 1350-line
+ * warning threshold that scripts/check-file-line-limits.sh enforces (issue
+ * #1593, surfaced again by issue #2198). These two helpers are pure decision
+ * logic with no dependency on the repository-setup flow around them, so they
+ * are the natural seam.
+ *
+ * Both names stay re-exported from solve.repository.lib.mjs so existing
+ * importers - and tests/anonymous-clone-auth-2192.test.mjs,
+ * tests/test-issue-1957-incomplete-clone.mjs - are unaffected.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { isENOSPC } from './lib.mjs';
+import { reportError } from './sentry.lib.mjs';
+// Issue #2192: GitHub throttles *anonymous* git downloads; the wording overlaps
+// the permission, not-found and rate-limit cases, so it is checked before them.
+import { isAnonymousDownloadLimit } from './git-auth-transport.lib.mjs';
+
+// Classify git clone errors to determine if they are retryable
+export const classifyCloneError = errorOutput => {
+  const output = errorOutput.toLowerCase();
+  // Issue #1211: ENOSPC (disk full) errors - NOT retryable, requires user action
+  if (isENOSPC(errorOutput) || output.includes('no space left on device') || (output.includes('unable to write file') && output.includes('error')) || output.includes('errno -28')) {
+    return { type: 'ENOSPC', retryable: false, description: 'No space left on device' };
+  }
+
+  // Transient server errors (5xx) - typically retryable
+  if (output.includes('error: 500') || output.includes('internal server error') || output.includes('error: 502') || output.includes('error: 503') || output.includes('error: 504')) {
+    return { type: 'TRANSIENT', retryable: true, description: 'GitHub server error' };
+  }
+  // Network-related errors - typically retryable
+  // Issue #1957: git fetch-pack/sideband disconnects (e.g.
+  // "fetch-pack: unexpected disconnect while reading sideband packet",
+  // "early EOF", "the remote end hung up unexpectedly", "RPC failed",
+  // "index-pack failed") leave an incomplete or missing clone but are transient.
+  if (output.includes('connection refused') || output.includes('connection timed out') || output.includes('connection reset') || output.includes('unable to connect') || output.includes('network is unreachable') || output.includes('ssl error') || output.includes('unexpected disconnect') || output.includes('sideband') || output.includes('early eof') || output.includes('remote end hung up') || output.includes('rpc failed') || output.includes('fetch-pack') || output.includes('index-pack failed') || output.includes('transfer closed')) {
+    return { type: 'NETWORK', retryable: true, description: 'Network connectivity issue (interrupted transfer)' };
+  }
+
+  // Issue #2192: GitHub refusing an *unauthenticated* download. Retryable, but
+  // waiting is not the remedy — the clone has to be authenticated. Checked
+  // before PERMISSION/NOT_FOUND/RATE_LIMIT because GitHub's wording ("limiting",
+  // "retry later or authenticate") overlaps all three.
+  if (isAnonymousDownloadLimit(errorOutput)) {
+    return { type: 'ANONYMOUS_RATE_LIMIT', retryable: true, description: 'GitHub is limiting unauthenticated downloads (this clone was not authenticated)' };
+  }
+
+  // Authentication/permission errors - not retryable
+  if (output.includes('error: 401') || output.includes('error: 403') || output.includes('authentication failed') || output.includes('permission denied')) {
+    return { type: 'PERMISSION', retryable: false, description: 'Authentication or permission error' };
+  }
+  // Repository not found - not retryable
+  if (output.includes('error: 404') || output.includes('not found') || output.includes('repository not found')) {
+    return { type: 'NOT_FOUND', retryable: false, description: 'Repository not found' };
+  }
+
+  // Rate limiting - retryable with backoff
+  if (output.includes('rate limit') || output.includes('too many requests') || output.includes('api rate limit exceeded')) {
+    return { type: 'RATE_LIMIT', retryable: true, description: 'Rate limit exceeded' };
+  }
+  // Default to retryable for unknown errors
+  return { type: 'UNKNOWN', retryable: true, description: 'Unknown error' };
+};
+
+// Issue #1957: remove leftovers from an interrupted clone so a retry can start clean.
+// We empty the directory in place (rather than removing it) because the path was
+// created up-front by setupTempDirectory and may be the configured working directory.
+export const cleanPartialClone = async tempDir => {
+  try {
+    const entries = await fs.readdir(tempDir);
+    for (const entry of entries) {
+      await fs.rm(path.join(tempDir, entry), { recursive: true, force: true });
+    }
+  } catch (error) {
+    // Directory may not exist yet, or be unreadable — non-fatal; the retry/clone
+    // will surface any real problem with a clearer message.
+    if (error?.code !== 'ENOENT') {
+      reportError(error, { context: 'clean_partial_clone', tempDir, operation: 'empty_directory' });
+    }
+  }
+};

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.repository.lib.mjs

@@ -28,12 +28,13 @@ const { log, formatAligned } = lib;
 // Import exit handler
 import { safeExit } from './exit-handler.lib.mjs';
 import { ensureAiToolScratchIgnored } from './ai-tool-scratch.lib.mjs';
+import { reclaimAgentSnapshotStores } from './agent-snapshot-store.lib.mjs';
 import { parseForkFullNameFromGhOutput } from './github-repository-names.lib.mjs';
 import { checkReplacementRepositoryBranchSafety } from './solve.repository-safety.lib.mjs';
 import { buildForkReplacementBlockedReason, buildForkReplacementSafetyCheckDescription } from './solve.repository-recovery-message.lib.mjs';
 // Issue #2192: GitHub throttles *anonymous* git downloads; a token must be sent
 // preemptively (a credential helper is never consulted for a public repository).
-import { GIT_AUTH_TRANSPORT_DISABLE, ensureAuthenticatedGitTransport, isAnonymousDownloadLimit } from './git-auth-transport.lib.mjs';
+import { GIT_AUTH_TRANSPORT_DISABLE, ensureAuthenticatedGitTransport } from './git-auth-transport.lib.mjs';
 
 // Import GitHub utilities for permission checks
 const githubLib = await import('./github.lib.mjs');
@@ -931,69 +932,12 @@ Thank you!`;
 
   return { repoToClone, forkedRepo, upstreamRemote, prForkOwner: forkOwner };
 };
-// Classify git clone errors to determine if they are retryable
-export const classifyCloneError = errorOutput => {
-  const output = errorOutput.toLowerCase();
-  // Issue #1211: ENOSPC (disk full) errors - NOT retryable, requires user action
-  if (lib.isENOSPC(errorOutput) || output.includes('no space left on device') || (output.includes('unable to write file') && output.includes('error')) || output.includes('errno -28')) {
-    return { type: 'ENOSPC', retryable: false, description: 'No space left on device' };
-  }
-
-  // Transient server errors (5xx) - typically retryable
-  if (output.includes('error: 500') || output.includes('internal server error') || output.includes('error: 502') || output.includes('error: 503') || output.includes('error: 504')) {
-    return { type: 'TRANSIENT', retryable: true, description: 'GitHub server error' };
-  }
-  // Network-related errors - typically retryable
-  // Issue #1957: git fetch-pack/sideband disconnects (e.g.
-  // "fetch-pack: unexpected disconnect while reading sideband packet",
-  // "early EOF", "the remote end hung up unexpectedly", "RPC failed",
-  // "index-pack failed") leave an incomplete or missing clone but are transient.
-  if (output.includes('connection refused') || output.includes('connection timed out') || output.includes('connection reset') || output.includes('unable to connect') || output.includes('network is unreachable') || output.includes('ssl error') || output.includes('unexpected disconnect') || output.includes('sideband') || output.includes('early eof') || output.includes('remote end hung up') || output.includes('rpc failed') || output.includes('fetch-pack') || output.includes('index-pack failed') || output.includes('transfer closed')) {
-    return { type: 'NETWORK', retryable: true, description: 'Network connectivity issue (interrupted transfer)' };
-  }
-
-  // Issue #2192: GitHub refusing an *unauthenticated* download. Retryable, but
-  // waiting is not the remedy — the clone has to be authenticated. Checked
-  // before PERMISSION/NOT_FOUND/RATE_LIMIT because GitHub's wording ("limiting",
-  // "retry later or authenticate") overlaps all three.
-  if (isAnonymousDownloadLimit(errorOutput)) {
-    return { type: 'ANONYMOUS_RATE_LIMIT', retryable: true, description: 'GitHub is limiting unauthenticated downloads (this clone was not authenticated)' };
-  }
-
-  // Authentication/permission errors - not retryable
-  if (output.includes('error: 401') || output.includes('error: 403') || output.includes('authentication failed') || output.includes('permission denied')) {
-    return { type: 'PERMISSION', retryable: false, description: 'Authentication or permission error' };
-  }
-  // Repository not found - not retryable
-  if (output.includes('error: 404') || output.includes('not found') || output.includes('repository not found')) {
-    return { type: 'NOT_FOUND', retryable: false, description: 'Repository not found' };
-  }
+// Issue #2198: clone-failure classification and partial-clone cleanup live in
+// their own module to keep this file under the line-limit warning threshold.
+// Re-exported so importers keep working.
+import { classifyCloneError, cleanPartialClone } from './solve.clone-errors.lib.mjs';
 
-  // Rate limiting - retryable with backoff
-  if (output.includes('rate limit') || output.includes('too many requests') || output.includes('api rate limit exceeded')) {
-    return { type: 'RATE_LIMIT', retryable: true, description: 'Rate limit exceeded' };
-  }
-  // Default to retryable for unknown errors
-  return { type: 'UNKNOWN', retryable: true, description: 'Unknown error' };
-};
-
-// Issue #1957: remove leftovers from an interrupted clone so a retry can start clean.
-// We empty the directory in place (rather than removing it) because the path was
-// created up-front by setupTempDirectory and may be the configured working directory.
-export const cleanPartialClone = async tempDir => {
-  try {
-    const entries = await fs.readdir(tempDir);
-    for (const entry of entries) {
-      await fs.rm(path.join(tempDir, entry), { recursive: true, force: true });
-    }
-  } catch (error) {
-    // Directory may not exist yet, or be unreadable — non-fatal; the retry/clone
-    // will surface any real problem with a clearer message.
-    if (error?.code !== 'ENOENT') {
-      reportError(error, { context: 'clean_partial_clone', tempDir, operation: 'empty_directory' });
-    }
-  }
-};
+export { classifyCloneError, cleanPartialClone };
 // Clone repository and set up remotes with retry mechanism
 export const cloneRepository = async (repoToClone, tempDir, argv, owner, repo) => {
   const maxRetries = 3;
@@ -1340,6 +1284,30 @@ export const checkoutPrBranch = async (tempDir, branchName, prForkRemote, prFork
 
   return checkoutResult;
 };
+/**
+ * Reclaim orphaned `@link-assistant/agent` snapshot stores (issue #2186).
+ *
+ * Deliberately *not* gated on `--auto-cleanup`: the stores this removes belong to
+ * worktrees that no longer exist, so there is nothing left to restore them into
+ * and keeping them has no debugging value. On a public repository auto-cleanup
+ * defaults to off, and that must not also mean "leak ~5 GB/h of home-directory
+ * state that no Hive Mind disk check can even see".
+ *
+ * Never fatal: this runs while solve is finalizing, after the work is done.
+ */
+export const cleanupAgentSnapshotStores = async () => {
+  try {
+    const { removed } = await reclaimAgentSnapshotStores({ log: async (message, options) => log(message, options) });
+    if (removed.length > 0) await log(`🧹 Reclaimed ${removed.length} orphaned agent snapshot store(s)`);
+  } catch (cleanupError) {
+    reportError(cleanupError, {
+      context: 'cleanup_agent_snapshot_stores',
+      operation: 'reclaim_agent_snapshots',
+    });
+    await log(`⚠️  Could not reclaim orphaned agent snapshot stores: ${cleanupError.message}`, { level: 'warning' });
+  }
+};
+
 // Cleanup temporary directory
 export const cleanupTempDirectory = async (tempDir, argv, limitReached) => {
   // Determine if we should skip cleanup
@@ -1370,4 +1338,9 @@ export const cleanupTempDirectory = async (tempDir, argv, limitReached) => {
     const reason = argv.autoCleanupSource === 'repository-visibility-default' ? 'auto-cleanup is off by default for public repositories' : '--no-auto-cleanup';
     await log(`\n📁 Keeping directory (${reason}): ${tempDir}`);
   }
+
+  // Issue #2186: whatever was decided about the workspace above, agent state
+  // whose worktree is already gone is reclaimed. The store belonging to
+  // `tempDir` is untouched while `tempDir` still exists.
+  await cleanupAgentSnapshotStores();
 };

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

@@ -1,5 +1,8 @@
 import fs from 'node:fs';
 import os from 'node:os';
+import v8 from 'node:v8';
+
+import { measureAgentSnapshotUsage } from './agent-snapshot-store.lib.mjs';
 
 export const RESOURCE_MARKER_PREFIX = '📈 [RESOURCES]';
 
@@ -10,8 +13,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';
+
+// 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_AFTER_AGENT, RESOURCE_PHASE_RESTART_AFTER, RESOURCE_PHASE_AFTER_CLONE, RESOURCE_PHASE_SOLVE_START, RESOURCE_PHASE_RESTART_BEFORE];
+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 +153,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,12 +210,27 @@ 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 || '/');
     try {
@@ -243,6 +272,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,11 +303,33 @@ 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 || {};
   const memory = s.memory || {};
   const disk = s.disk || {};
+  const agentState = s.agentState || null;
   return [
     RESOURCE_MARKER_PREFIX,
     `phase=${encodeValue(s.phase || 'snapshot')}`,
@@ -287,6 +342,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,7 +354,13 @@ 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`)}`,
+    // Issue #2186: only emitted when the agent state was actually measured, so
+    // markers written before this existed keep parsing byte-for-byte the same.
+    agentState ? `agentStatePath=${encodeValue(agentState.path)}` : null,
+    agentState ? numberField('agentStoreCount', finiteNumber(agentState.count)) : null,
+    agentState ? numberField('agentStoreBytes', finiteNumber(agentState.bytes)) : null,
   ]
     .filter(Boolean)
     .join(' ');
@@ -332,6 +398,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 || '/'),
@@ -341,6 +412,15 @@ function parseMarkerLine(line) {
       usedPercent: parseNumber(fields.diskUsedPercent),
       error: fields.error ? decodeURIComponent(fields.error) : null,
     },
+    // Issue #2186: absent in markers produced before agent state was measured,
+    // and absent on hosts where the agent data home does not exist.
+    agentState: fields.agentStatePath
+      ? {
+          path: decodeURIComponent(fields.agentStatePath),
+          count: parseNumber(fields.agentStoreCount),
+          bytes: parseNumber(fields.agentStoreBytes),
+        }
+      : null,
   };
 }
 
@@ -376,13 +456,19 @@ 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)` : ''}`];
+  // Issue #2186: `/` alone hid ~5 GB/h of agent snapshot growth under
+  // `~/.local/share`, so name the directory that is actually filling up.
+  if (s.agentState && Number(s.agentState.count) > 0) {
+    lines.push(`   Agent snapshot stores (${s.agentState.path}): ${s.agentState.count} store(s), ${formatBytes(s.agentState.bytes)}${s.agentState.truncated ? '+ (measurement truncated)' : ''}`);
+  }
+  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');
 }
 
-export async function recordResourceSnapshot({ phase, log, diskPath = '/', label = null, capture = captureResourceSnapshot, logExecutionContext = false, detectContext = detectExecutionContext } = {}) {
+export async function recordResourceSnapshot({ phase, log, diskPath = '/', label = null, capture = captureResourceSnapshot, logExecutionContext = false, detectContext = detectExecutionContext, measureAgentState = measureAgentSnapshotUsage } = {}) {
   if (typeof log !== 'function') return null;
   try {
     // Issue #2001: optionally report the execution context (host vs container)
@@ -395,6 +481,17 @@ export async function recordResourceSnapshot({ phase, log, diskPath = '/', label
       }
     }
     const snapshot = capture({ phase, diskPath });
+    // Issue #2186: agent state lives outside `diskPath` and needs the file
+    // system, so it is measured separately and stays best-effort — a missing or
+    // unreadable agent data home must never cost us the rest of the snapshot.
+    if (typeof measureAgentState === 'function') {
+      try {
+        const agentState = await measureAgentState();
+        if (agentState && Number(agentState.count) > 0) snapshot.agentState = agentState;
+      } catch {
+        /* agent state is a diagnostic extra, not a precondition */
+      }
+    }
     await log(formatResourceSnapshotForLog(snapshot, label));
     return snapshot;
   } catch (error) {
@@ -422,6 +519,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/start-command-cli.lib.mjs

@@ -0,0 +1,60 @@
+/**
+ * Shared access to the `$` CLI (start-command, link-foundation/start).
+ *
+ * Extracted from src/isolation-runner.lib.mjs (issue #2189) so the resume/attach
+ * wrappers added for `start-command@0.33.0` can reach the same lazily-loaded
+ * `command-stream` `$` and the same PATH lookup without importing the runner —
+ * which would create a cycle — and without duplicating either.
+ *
+ * @see https://github.com/link-foundation/start
+ * @see https://github.com/link-assistant/hive-mind/issues/2189
+ */
+
+import { ensureUseM } from './use-m-bootstrap.lib.mjs';
+
+/** The message every wrapper reports when `$` is not installed. */
+export const START_COMMAND_MISSING_ERROR = '`$` (start-command) binary not found on PATH. Install link-foundation/start.';
+
+let commandStreamDollarPromise = null;
+
+/**
+ * Lazily load `command-stream`'s `$` template tag.
+ *
+ * Cached across calls; a failed load clears the cache so a transient failure
+ * (a cold `use-m` fetch, say) does not poison every later call.
+ *
+ * @returns {Promise<Function>} The `$` template tag
+ */
+export async function getCommandStreamDollar() {
+  if (!commandStreamDollarPromise) {
+    commandStreamDollarPromise = (async () => {
+      if (typeof globalThis.use === 'undefined') {
+        await ensureUseM();
+      }
+      const { $ } = await globalThis.use('command-stream');
+      return $;
+    })();
+  }
+  try {
+    return await commandStreamDollarPromise;
+  } catch (error) {
+    commandStreamDollarPromise = null;
+    throw error;
+  }
+}
+
+/**
+ * Find the `$` CLI binary path.
+ *
+ * @returns {Promise<string|null>} Path to the `$` binary, or null when absent
+ */
+export async function findStartCommandBinary() {
+  try {
+    const $ = await getCommandStreamDollar();
+    const result = await $({ mirror: false })`which $`;
+    const resolved = result.stdout?.toString().trim() || '';
+    return resolved || null;
+  } catch {
+    return null;
+  }
+}