@link-assistant/hive-mind 2.0.29 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @link-assistant/hive-mind
 
+## 2.1.0
+
+### Minor Changes
+
+- 4e21d2a: Fix Docker task disk-usage reporting so Telegram completion messages use task container writable-layer samples instead of filesystem-capacity resource markers from the parent deployment.
+- fdbf448: Add full support for Claude Sonnet 5 (`claude-sonnet-5`) and make it the default model for `--tool claude`. The bare `sonnet` alias now resolves to `claude-sonnet-5` (previously `claude-sonnet-4-6`). Sonnet 5 supports 1M context (`[1m]`), the full effort ladder including `xhigh` and `max`, 128K max output tokens, and adaptive-thinking-only environment handling. The `sonnet-4-6`/`claude-sonnet-4-6` aliases are retained for backward compatibility. (Issue #2003)
+
 ## 2.0.29
 
 ### Patch Changes

package/package.json

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

package/src/config.lib.mjs

@@ -266,6 +266,22 @@ const isSonnet46OrLater = model => {
   return m === 'sonnet' || m === 'sonnet-4-6' || m.includes('sonnet-4-6') || m.includes('sonnet-5');
 };
 
+/**
+ * Check if a model is Claude Sonnet 5 (Issue #2003)
+ * Sonnet 5 (`claude-sonnet-5`) is the current default for `--tool claude` (the bare
+ * `sonnet` alias now resolves to it). Unlike Sonnet 4.6 it supports the `xhigh` effort
+ * level, up to 128k output tokens, and uses adaptive thinking only (extended/manual
+ * thinking with an explicit budget is unavailable), matching the Fable/Mythos 5 API
+ * constraints. See: https://www.anthropic.com/news/claude-sonnet-5
+ * @param {string} model - The model name or ID
+ * @returns {boolean} True if the model is Claude Sonnet 5
+ */
+export const isSonnet5 = model => {
+  if (!model) return false;
+  const m = model.toLowerCase();
+  return m === 'sonnet' || m === 'sonnet-5' || m.includes('sonnet-5');
+};
+
 const isMythosPreview = model => {
   if (!model) return false;
   return model.toLowerCase().includes('mythos');
@@ -328,11 +344,11 @@ export const supportsEffortLevel = model => {
 /**
  * Check if a model supports the xhigh effort level.
  * Official docs list xhigh for Claude Fable 5, Claude Mythos 5, Claude Opus 4.7,
- * and Opus 4.8 (Issue #1832, Issue #1875).
+ * Opus 4.8, and Sonnet 5 (Issue #1832, Issue #1875, Issue #2003).
  * @param {string} model - The model name or ID
  * @returns {boolean} True if the model supports xhigh effort
  */
-export const supportsXHighEffortLevel = model => isFable5OrMythos5(model) || isOpus47(model);
+export const supportsXHighEffortLevel = model => isFable5OrMythos5(model) || isOpus47(model) || isSonnet5(model);
 
 /**
  * Check if a model supports the max effort level.
@@ -344,14 +360,14 @@ export const supportsXHighEffortLevel = model => isFable5OrMythos5(model) || isO
 export const supportsMaxEffortLevel = model => isFable5OrMythos5(model) || isMythosPreview(model) || isOpus47OrLater(model) || isOpus46(model) || isSonnet46OrLater(model);
 
 /**
- * Get the max output tokens for a specific model (Issue #1221, Issue #1875)
- * Claude Fable 5 and Claude Mythos 5 support up to 128k output tokens, matching
- * the Opus 4.6+ ceiling.
+ * Get the max output tokens for a specific model (Issue #1221, Issue #1875, Issue #2003)
+ * Claude Fable 5, Claude Mythos 5, and Claude Sonnet 5 support up to 128k output tokens,
+ * matching the Opus 4.6+ ceiling.
  * @param {string} model - The model name or ID
  * @returns {number} The max output tokens for the model
  */
 export const getMaxOutputTokensForModel = model => {
-  if (isOpus46OrLater(model) || isFable5OrMythos5(model)) {
+  if (isOpus46OrLater(model) || isFable5OrMythos5(model) || isSonnet5(model)) {
     return claudeCode.maxOutputTokensOpus46;
   }
   return claudeCode.maxOutputTokens;
@@ -564,12 +580,12 @@ export const getClaudeEnv = (options = {}) => {
 
   // Opus 4.7+ always uses adaptive thinking — MAX_THINKING_TOKENS has no effect (Issue #1620, Issue #1832)
   // Opus 4.8 inherits this constraint: adaptive thinking is the only thinking mode.
-  // Claude Fable 5 and Claude Mythos 5 are adaptive-thinking-only too: extended/manual
-  // thinking is unavailable and `thinking: {type: "disabled"}` is rejected, so a
-  // MAX_THINKING_TOKENS=0 would be invalid for them (Issue #1875).
+  // Claude Fable 5, Claude Mythos 5, and Claude Sonnet 5 are adaptive-thinking-only too:
+  // extended/manual thinking is unavailable and `thinking: {type: "disabled"}` is rejected,
+  // so a MAX_THINKING_TOKENS=0 would be invalid for them (Issue #1875, Issue #2003).
   // For Opus 4.6 and earlier, MAX_THINKING_TOKENS controls extended thinking (Claude Code >= 2.1.12)
   // Default is 0 (thinking disabled) per Issue #1238.
-  const adaptiveThinkingOnly = options.model && (isOpus47OrLater(options.model) || isFable5OrMythos5(options.model));
+  const adaptiveThinkingOnly = options.model && (isOpus47OrLater(options.model) || isFable5OrMythos5(options.model) || isSonnet5(options.model));
   if (adaptiveThinkingOnly) {
     // Remove any inherited MAX_THINKING_TOKENS from process.env — these models ignore it
     delete env.MAX_THINKING_TOKENS;

package/src/models/index.mjs

@@ -29,10 +29,10 @@ const execFileAsync = promisify(execFile);
 // ─── MODEL DATA ──────────────────────────────────────────────────────────────
 
 // Claude models (Anthropic API)
-// Updated for Opus 4.5/4.6/4.7/4.8, Sonnet 4.6, and Fable 5 / Mythos 5 support
-// (Issue #1221, Issue #1238, Issue #1329, Issue #1433, Issue #1620, Issue #1832, Issue #1875)
+// Updated for Opus 4.5/4.6/4.7/4.8, Sonnet 4.6/5, and Fable 5 / Mythos 5 support
+// (Issue #1221, Issue #1238, Issue #1329, Issue #1433, Issue #1620, Issue #1832, Issue #1875, Issue #2003)
 export const claudeModels = {
-  sonnet: 'claude-sonnet-4-6', // Sonnet 4.6 (default, Issue #1329)
+  sonnet: 'claude-sonnet-5', // Sonnet 5 (default, Issue #2003)
   opus: 'claude-opus-4-8', // Opus 4.8 (Issue #1832)
   haiku: 'claude-haiku-4-5-20251001', // Haiku 4.5
   'haiku-3-5': 'claude-3-5-haiku-20241022', // Haiku 3.5
@@ -46,6 +46,7 @@ export const claudeModels = {
   'mythos-5': 'claude-mythos-5', // Mythos 5 short alias
   'claude-mythos-5': 'claude-mythos-5', // Mythos 5 full ID
   // Shorter version aliases (Issue #1221, Issue #1329 - PR comment feedback)
+  'sonnet-5': 'claude-sonnet-5', // Sonnet 5 short alias (Issue #2003)
   'sonnet-4-6': 'claude-sonnet-4-6', // Sonnet 4.6 short alias (Issue #1329)
   'opus-4-8': 'claude-opus-4-8', // Opus 4.8 short alias (Issue #1832)
   'opus-4-7': 'claude-opus-4-7', // Opus 4.7 short alias (backward compatibility)
@@ -56,6 +57,7 @@ export const claudeModels = {
   // Version aliases for backward compatibility (Issue #1221, Issue #1329, Issue #1620, Issue #1832)
   'claude-opus-4-8': 'claude-opus-4-8', // Opus 4.8 (Issue #1832)
   'claude-opus-4-7': 'claude-opus-4-7', // Opus 4.7 (backward compatibility)
+  'claude-sonnet-5': 'claude-sonnet-5', // Sonnet 5 (Issue #2003)
   'claude-sonnet-4-6': 'claude-sonnet-4-6', // Sonnet 4.6 (Issue #1329)
   'claude-opus-4-6': 'claude-opus-4-6', // Opus 4.6 (backward compatibility)
   'claude-opus-4-5': 'claude-opus-4-5-20251101', // Opus 4.5
@@ -207,10 +209,12 @@ export const MODELS_SUPPORTING_1M_CONTEXT = [
   'claude-opus-4-7', // Opus 4.7 (Issue #1620)
   'claude-opus-4-6',
   'claude-opus-4-5-20251101',
+  'claude-sonnet-5', // Sonnet 5 — 1M context (Issue #2003)
   'claude-sonnet-4-6', // Sonnet 4.6 (Issue #1329)
   'claude-sonnet-4-5-20250929',
   'claude-sonnet-4-5',
-  'sonnet', // Now maps to Sonnet 4.6 (Issue #1329)
+  'sonnet', // Now maps to Sonnet 5 (Issue #2003)
+  'sonnet-5', // Short alias (Issue #2003)
   'sonnet-4-6', // Short alias (Issue #1329)
   'opus', // Now maps to Opus 4.8 (Issue #1832)
   'opus-4-8', // Short alias (Issue #1832)
@@ -1148,6 +1152,8 @@ export const defaultFallbackModels = {
     'claude-mythos-5': 'fable',
     'claude-opus-4-8': 'opus-4-7',
     'claude-opus-4-7': 'opus-4-6',
+    // Claude Sonnet 5 falls back to the prior Sonnet generation (Issue #2003).
+    'claude-sonnet-5': 'sonnet-4-6',
   },
   codex: {
     'gpt-5.6-sol': 'gpt-5.5',

package/src/session-monitor.lib.mjs

@@ -193,6 +193,15 @@ function isPersistableSession(sessionInfo) {
   return Boolean(sessionInfo?.isolationBackend && sessionInfo?.sessionId);
 }
 
+function persistSessionSnapshot(sessionName, sessionInfo) {
+  if (!sessionStore || !isPersistableSession(sessionInfo)) return;
+  try {
+    sessionStore.persist(sessionName, sessionInfo);
+  } catch {
+    /* best effort — persistence must never break monitoring */
+  }
+}
+
 /**
  * Look up the in-memory record for a session id (UUID for isolation sessions
  * or the screen session name for non-isolation sessions). Returns null when no
@@ -347,7 +356,6 @@ export async function buildDiskDiagnosticsExtraSection(logPath, { verbose = fals
   if (!logPath && !Number.isFinite(containerFilesystemStartBytes) && !Number.isFinite(containerFilesystemAfterBytes)) return '';
   try {
     const diskLib = await import('./solve.disk-diagnostics.lib.mjs');
-    const resourceLib = await import('./solve.resource-diagnostics.lib.mjs');
     let logText = '';
     if (logPath) {
       try {
@@ -359,17 +367,11 @@ export async function buildDiskDiagnosticsExtraSection(logPath, { verbose = fals
       }
     }
     const parsed = diskLib.parseDiskMarkers(logText);
-    const parsedResources = resourceLib.parseResourceMarkers(logText);
-    const bestResourceMarker = resourceLib.selectBestDiskResourceMarker(parsedResources);
-    const solveStartResourceMarker = parsedResources.byPhase?.[resourceLib.RESOURCE_PHASE_SOLVE_START] || null;
-    const useResourceFallback = String(isolationBackend || '').toLowerCase() === 'docker' && !Number.isFinite(containerFilesystemAfterBytes) && Number.isFinite(bestResourceMarker?.disk?.usedBytes);
-    const effectiveContainerFilesystemAfterBytes = useResourceFallback ? bestResourceMarker.disk.usedBytes : containerFilesystemAfterBytes;
-    const effectiveContainerFilesystemStartBytes = useResourceFallback && Number.isFinite(solveStartResourceMarker?.disk?.usedBytes) ? solveStartResourceMarker.disk.usedBytes : containerFilesystemStartBytes;
-    if (!parsed.afterClone && !parsed.afterAgent && !Number.isFinite(effectiveContainerFilesystemStartBytes) && !Number.isFinite(effectiveContainerFilesystemAfterBytes)) return '';
+    if (!parsed.afterClone && !parsed.afterAgent && !Number.isFinite(containerFilesystemStartBytes) && !Number.isFinite(containerFilesystemAfterBytes)) return '';
     return diskLib.formatDiskDiagnosticsBlock(parsed, {
       isolationBackend,
-      containerFilesystemStartBytes: effectiveContainerFilesystemStartBytes,
-      containerFilesystemAfterBytes: effectiveContainerFilesystemAfterBytes,
+      containerFilesystemStartBytes,
+      containerFilesystemAfterBytes,
     });
   } catch (error) {
     if (verbose) {
@@ -399,6 +401,19 @@ async function getDockerContainerFilesystemSizeForSession(sessionName, sessionIn
   }
 }
 
+async function refreshDockerContainerFilesystemSizeForSession(sessionName, sessionInfo, { verbose = false, sizeProvider = null } = {}) {
+  const bytes = await getDockerContainerFilesystemSizeForSession(sessionName, sessionInfo, { verbose, sizeProvider });
+  if (!Number.isFinite(bytes)) return null;
+  sessionInfo.containerFilesystemLastBytes = bytes;
+  sessionInfo.containerFilesystemLastObservedAt = new Date().toISOString();
+  persistSessionSnapshot(sessionName, sessionInfo);
+  return bytes;
+}
+
+function getLastKnownDockerContainerFilesystemSize(sessionInfo) {
+  return Number.isFinite(sessionInfo?.containerFilesystemLastBytes) ? sessionInfo.containerFilesystemLastBytes : null;
+}
+
 function isSuccessfulTaskCompletion({ exitCode = null, status = null } = {}) {
   const outcome = classifySessionOutcome({ exitCode, status });
   if (outcome.failed) return false;
@@ -664,6 +679,7 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
     let exitCode = null;
     let statusResult = null;
     let resolvedStatus = null;
+    let observedContainerFilesystemBytes = null;
 
     if (sessionInfo.isolationBackend && sessionInfo.sessionId) {
       // Isolation mode: use $ --status, with screen -ls only as a fallback
@@ -689,13 +705,7 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
       // the log footer to learn whether it was killed.
       if (statusResult?.logPath && sessionInfo.logPath !== statusResult.logPath) {
         sessionInfo.logPath = statusResult.logPath;
-        if (sessionStore) {
-          try {
-            sessionStore.persist(sessionName, sessionInfo);
-          } catch {
-            /* best effort — persistence must never break monitoring */
-          }
-        }
+        persistSessionSnapshot(sessionName, sessionInfo);
       }
     } else {
       // Issue #1586: Non-isolation screen sessions cannot reliably detect
@@ -717,6 +727,13 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
       }
     }
 
+    if (sessionInfo?.isolationBackend === 'docker') {
+      observedContainerFilesystemBytes = await refreshDockerContainerFilesystemSizeForSession(sessionName, sessionInfo, {
+        verbose,
+        sizeProvider: options.dockerContainerSizeProvider,
+      });
+    }
+
     if (!stillRunning) {
       console.log(`Session ${sessionName} has finished. Sending notification to chat ${sessionInfo.chatId}`);
 
@@ -828,10 +845,7 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
         const diskExtraSections = [];
         try {
           const diskLogPath = statusResult?.logPath || sessionInfo?.logPath || null;
-          const containerFilesystemAfterBytes = await getDockerContainerFilesystemSizeForSession(sessionName, sessionInfo, {
-            verbose,
-            sizeProvider: options.dockerContainerSizeProvider,
-          });
+          const containerFilesystemAfterBytes = Number.isFinite(observedContainerFilesystemBytes) ? observedContainerFilesystemBytes : getLastKnownDockerContainerFilesystemSize(sessionInfo);
           const diskBlock = await buildDiskDiagnosticsExtraSection(diskLogPath, {
             verbose,
             readFile: options.readFile,

package/src/session-store.lib.mjs

@@ -33,7 +33,7 @@ import path from 'node:path';
 // excluded so the snapshot stays small and safe to reload.
 // `args` (#1927 review follow-up) is persisted so a killed /solve can be resumed
 // with its exact original invocation plus `--resume <lastSessionId>`.
-const PERSISTABLE_FIELDS = ['chatId', 'messageId', 'startTime', 'url', 'command', 'isolationBackend', 'sessionId', 'containerFilesystemStartBytes', 'tool', 'infoBlock', 'urlContext', 'requesterUserId', 'showLimits', 'locale', 'logPath', 'args'];
+const PERSISTABLE_FIELDS = ['chatId', 'messageId', 'startTime', 'url', 'command', 'isolationBackend', 'sessionId', 'containerFilesystemStartBytes', 'containerFilesystemLastBytes', 'containerFilesystemLastObservedAt', 'tool', 'infoBlock', 'urlContext', 'requesterUserId', 'showLimits', 'locale', 'logPath', 'args'];
 
 /**
  * Resolve the directory durable bot state is written to. Honors

package/src/solve.config.lib.mjs

@@ -299,7 +299,7 @@ export const SOLVE_OPTION_DEFINITIONS = {
   },
   think: {
     type: 'string',
-    description: 'Thinking level hint. For Claude, translated to --thinking-budget for Claude Code >= 2.1.12 (off=0, low=~8000, medium=~16000, high=~24000, xhigh/max=31999) and to CLAUDE_CODE_EFFORT_LEVEL when supported. Fable 5/Mythos 5/Opus 4.8/4.7 support xhigh and max; Opus 4.6/Sonnet 4.6/Mythos Preview support max; Opus 4.5 uses high for xhigh/max. For Codex, mapped to reasoning effort (off=none, low=low, medium=medium, high=high, xhigh/max=xhigh).',
+    description: 'Thinking level hint. For Claude, translated to --thinking-budget for Claude Code >= 2.1.12 (off=0, low=~8000, medium=~16000, high=~24000, xhigh/max=31999) and to CLAUDE_CODE_EFFORT_LEVEL when supported. Fable 5/Mythos 5/Sonnet 5/Opus 4.8/4.7 support xhigh and max; Opus 4.6/Sonnet 4.6/Mythos Preview support max; Opus 4.5 uses high for xhigh/max. For Codex, mapped to reasoning effort (off=none, low=low, medium=medium, high=high, xhigh/max=xhigh).',
     choices: ['off', 'low', 'medium', 'high', 'xhigh', 'max'],
     default: undefined,
   },

package/src/solve.escalate.lib.mjs

@@ -72,8 +72,10 @@ const TIER_ALIASES = {
   'claude-haiku-4-5': 'haiku',
   'claude-haiku-4-5-20251001': 'haiku',
   sonnet: 'sonnet',
+  'sonnet-5': 'sonnet',
   'sonnet-4-6': 'sonnet',
   'sonnet-4-5': 'sonnet',
+  'claude-sonnet-5': 'sonnet',
   'claude-sonnet-4-6': 'sonnet',
   'claude-sonnet-4-5': 'sonnet',
   opus: 'opus',

package/src/solve.mjs

@@ -106,7 +106,7 @@ configureGitHubRateLimitLogging({
   enabled: argv.githubRateLimitsLogging === true,
   log,
 });
-await recordResourceSnapshot({ phase: RESOURCE_PHASE_SOLVE_START, log, diskPath: '/', label: 'solve start' });
+await recordResourceSnapshot({ phase: RESOURCE_PHASE_SOLVE_START, log, diskPath: '/', label: 'solve start', logExecutionContext: true }); // #2001: detect+report container context
 
 // Early logs go to cwd; custom log dir takes effect after argv is parsed
 // Conditionally import tool-specific functions after argv is parsed

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

@@ -34,6 +34,110 @@ function readLinuxMemAvailableBytes(readFileSync = fs.readFileSync, platform = p
   }
 }
 
+/**
+ * Detect where the current process is running so the solve command can scope
+ * per-task disk usage to the correct context (issue #2001).
+ *
+ * When solve runs inside a Docker/container isolation backend, the per-task
+ * disk measurement must come from container-scoped signals (the cloned working
+ * tree measured with `du` inside the container, plus the host-side
+ * `docker inspect --size` writable-layer size) rather than the whole-VM
+ * filesystem reported by `statfs('/')`. This helper makes that detection
+ * explicit and observable in the solve log.
+ *
+ * It is intentionally defensive: any injected `existsSync`/`readFileSync`
+ * implementation that lacks a method or throws is treated as "signal absent"
+ * rather than propagating an error, so callers never crash on detection.
+ *
+ * @returns {{ inContainer: boolean, runtime: string|null, indicators: string[] }}
+ */
+export function detectExecutionContext(options = {}) {
+  const { existsSync = fs.existsSync, readFileSync = fs.readFileSync, env = process.env, platform = process.platform } = options;
+
+  const indicators = [];
+  let runtime = null;
+
+  const safeExists = target => {
+    try {
+      return typeof existsSync === 'function' ? existsSync(target) === true : false;
+    } catch {
+      return false;
+    }
+  };
+
+  const safeRead = target => {
+    try {
+      return typeof readFileSync === 'function' ? String(readFileSync(target, 'utf8')) : '';
+    } catch {
+      return '';
+    }
+  };
+
+  if (safeExists('/.dockerenv')) {
+    indicators.push('/.dockerenv');
+    runtime = runtime || 'docker';
+  }
+  if (safeExists('/run/.containerenv')) {
+    indicators.push('/run/.containerenv');
+    runtime = runtime || 'podman';
+  }
+
+  if (platform === 'linux') {
+    const cgroup = safeRead('/proc/1/cgroup');
+    if (cgroup) {
+      if (/\bdocker\b/.test(cgroup)) {
+        indicators.push('cgroup:docker');
+        runtime = runtime || 'docker';
+      }
+      if (/kubepods/.test(cgroup)) {
+        indicators.push('cgroup:kubepods');
+        runtime = runtime || 'kubernetes';
+      }
+      if (/libpod|podman/.test(cgroup)) {
+        indicators.push('cgroup:podman');
+        runtime = runtime || 'podman';
+      }
+      if (/containerd/.test(cgroup)) {
+        indicators.push('cgroup:containerd');
+        runtime = runtime || 'containerd';
+      }
+    }
+  }
+
+  const envObj = env && typeof env === 'object' ? env : {};
+  if (envObj.HIVE_MIND_ISOLATION || envObj.HIVE_MIND_CONTAINER) {
+    indicators.push('env:hive-mind-isolation');
+    runtime = runtime || 'container';
+  }
+  if (envObj.KUBERNETES_SERVICE_HOST) {
+    indicators.push('env:kubernetes');
+    runtime = runtime || 'kubernetes';
+  }
+
+  return {
+    inContainer: indicators.length > 0,
+    runtime,
+    indicators,
+  };
+}
+
+/**
+ * Human-readable one-liner describing the detected execution context, used to
+ * make the disk-usage scope explicit in the solve log.
+ *
+ * @param {ReturnType<typeof detectExecutionContext>} context
+ * @returns {string}
+ */
+export function formatExecutionContextForLog(context) {
+  const ctx = context || detectExecutionContext();
+  if (ctx.inContainer) {
+    const runtime = ctx.runtime || 'container';
+    const detail = ctx.indicators.length ? ` (indicators: ${ctx.indicators.join(', ')})` : '';
+    return `🧭 Execution context: ${runtime} container${detail} — per-task disk usage is scoped to this container.`;
+  }
+  return '🧭 Execution context: host (no container isolation detected) — per-task disk usage is scoped to the working tree.';
+}
+
 export function captureResourceSnapshot(options = {}) {
   const { phase = 'snapshot', diskPath = '/', now = () => new Date(), osImpl = os, fsImpl = fs, processImpl = process } = options;
 
@@ -278,9 +382,18 @@ export function formatResourceSnapshotForLog(snapshot, label = null) {
   return lines.join('\n');
 }
 
-export async function recordResourceSnapshot({ phase, log, diskPath = '/', label = null, capture = captureResourceSnapshot } = {}) {
+export async function recordResourceSnapshot({ phase, log, diskPath = '/', label = null, capture = captureResourceSnapshot, logExecutionContext = false, detectContext = detectExecutionContext } = {}) {
   if (typeof log !== 'function') return null;
   try {
+    // Issue #2001: optionally report the execution context (host vs container)
+    // so it is explicit that per-task disk usage is scoped to the container.
+    if (logExecutionContext) {
+      try {
+        await log(formatExecutionContextForLog(detectContext()));
+      } catch {
+        /* context detection is best-effort and must never block the snapshot */
+      }
+    }
     const snapshot = capture({ phase, diskPath });
     await log(formatResourceSnapshotForLog(snapshot, label));
     return snapshot;