@covibes/zeroshot 2.0.0 → 3.0.0

package/src/orchestrator.js

@@ -487,6 +487,7 @@ class Orchestrator {
    * @param {Object} options - Start options
    * @param {boolean} options.isolation - Run in Docker container
    * @param {string} options.isolationImage - Docker image to use
+   * @param {boolean} options.worktree - Run in git worktree isolation (lightweight, no Docker)
    * @returns {Object} Cluster object
    */
   start(config, input = {}, options = {}) {
@@ -495,6 +496,7 @@ class Orchestrator {
       cwd: options.cwd || process.cwd(), // Target working directory for agents
       isolation: options.isolation || false,
       isolationImage: options.isolationImage,
+      worktree: options.worktree || false,
       autoPr: process.env.CREW_PR === '1',
     });
   }
@@ -512,14 +514,15 @@ class Orchestrator {
     const ledger = new Ledger(dbPath);
     const messageBus = new MessageBus(ledger);
 
-    // Handle isolation mode (Docker container)
+    // Handle isolation mode (Docker container OR git worktree)
     let isolationManager = null;
     let containerId = null;
+    let worktreeInfo = null;
 
     if (options.isolation) {
       // Check Docker availability
       if (!IsolationManager.isDockerAvailable()) {
-        throw new Error('Docker is not available. Install Docker to use --isolation mode.');
+        throw new Error('Docker is not available. Install Docker to use --docker mode.');
       }
 
       // Ensure image exists (auto-build if missing)
@@ -537,6 +540,16 @@ class Orchestrator {
         image,
       });
       this._log(`[Orchestrator] Container created: ${containerId} (workDir: ${workDir})`);
+    } else if (options.worktree) {
+      // Worktree isolation: lightweight git-based isolation (no Docker required)
+      const workDir = options.cwd || process.cwd();
+
+      isolationManager = new IsolationManager({});
+      worktreeInfo = isolationManager.createWorktreeIsolation(clusterId, workDir);
+
+      this._log(`[Orchestrator] Starting cluster in worktree isolation mode`);
+      this._log(`[Orchestrator] Worktree: ${worktreeInfo.path}`);
+      this._log(`[Orchestrator] Branch: ${worktreeInfo.branch}`);
     }
 
     // Build cluster object
@@ -571,6 +584,17 @@ class Orchestrator {
             workDir: options.cwd || process.cwd(), // Persisted for resume
           }
         : null,
+      // Worktree isolation state (lightweight alternative to Docker)
+      worktree: options.worktree
+        ? {
+            enabled: true,
+            path: worktreeInfo.path,
+            branch: worktreeInfo.branch,
+            repoRoot: worktreeInfo.repoRoot,
+            manager: isolationManager,
+            workDir: options.cwd || process.cwd(), // Persisted for resume
+          }
+        : null,
     };
 
     this.clusters.set(clusterId, cluster);
@@ -636,7 +660,8 @@ class Orchestrator {
       // Initialize agents with optional mock injection
       // Check agent type: regular agent or subcluster
       // CRITICAL: Inject cwd into each agent config for proper working directory
-      const agentCwd = options.cwd || process.cwd();
+      // In worktree mode, agents run in the worktree path (not original cwd)
+      const agentCwd = cluster.worktree ? cluster.worktree.path : options.cwd || process.cwd();
       for (const agentConfig of config.agents) {
         // Inject cwd if not already set (config may override)
         if (!agentConfig.cwd) {
@@ -656,11 +681,10 @@ class Orchestrator {
         // TaskRunner DI - new pattern for mocking task execution
         // Creates a mockSpawnFn wrapper that delegates to the taskRunner
         if (this.taskRunner) {
-          agentOptions.mockSpawnFn = (args, { context }) => {
-            return this.taskRunner.run(context, {
-              agentId: agentConfig.id,
-            });
-          };
+          // CRITICAL: agent is a closure variable capturing the AgentWrapper instance
+          // We cannot access agent._selectModel() here because agent doesn't exist yet
+          // Solution: Pass a factory function that will be called when agent is available
+          agentOptions.taskRunner = this.taskRunner;
         }
 
         // Pass isolation context if enabled
@@ -672,6 +696,16 @@ class Orchestrator {
           };
         }
 
+        // Pass worktree context if enabled (lightweight isolation without Docker)
+        if (cluster.worktree) {
+          agentOptions.worktree = {
+            enabled: true,
+            path: cluster.worktree.path,
+            branch: cluster.worktree.branch,
+            repoRoot: cluster.worktree.repoRoot,
+          };
+        }
+
         // Create agent or subcluster wrapper based on type
         let agent;
         if (agentConfig.type === 'subcluster') {
@@ -836,7 +870,7 @@ class Orchestrator {
             containerId,
           }).catch((err) => {
             console.error(`Failed to execute CLUSTER_OPERATIONS:`, err.message);
-            // Publish failure for conductor to retry
+            // Publish failure message
             messageBus.publish({
               cluster_id: clusterId,
               topic: 'CLUSTER_OPERATIONS_FAILED',
@@ -849,6 +883,18 @@ class Orchestrator {
                 },
               },
             });
+
+            // CRITICAL: Stop cluster on operation failure - cluster cannot continue
+            // without required agents (e.g., planner model mismatch)
+            this._log(`\n${'='.repeat(80)}`);
+            this._log(`❌ CLUSTER_OPERATIONS FAILED - STOPPING CLUSTER`);
+            this._log(`${'='.repeat(80)}`);
+            this._log(`Error: ${err.message}`);
+            this._log(`${'='.repeat(80)}\n`);
+
+            this.stop(clusterId).catch((stopErr) => {
+              console.error(`Failed to stop cluster after operation failure:`, stopErr.message);
+            });
           });
         }
       });
@@ -925,6 +971,14 @@ class Orchestrator {
       this._log(`[Orchestrator] Container stopped, workspace preserved`);
     }
 
+    // Worktree cleanup on stop: preserve for resume capability
+    // Branch stays, worktree stays - can resume work later
+    if (cluster.worktree?.manager) {
+      this._log(`[Orchestrator] Worktree preserved at ${cluster.worktree.path} for resume`);
+      this._log(`[Orchestrator] Branch: ${cluster.worktree.branch}`);
+      // Don't cleanup worktree - it will be reused on resume
+    }
+
     cluster.state = 'stopped';
     cluster.pid = null; // Clear PID - cluster is no longer running
     this._log(`Cluster ${clusterId} stopped`);
@@ -957,6 +1011,14 @@ class Orchestrator {
       this._log(`[Orchestrator] Container and workspace removed`);
     }
 
+    // Force remove worktree (full cleanup, no resume)
+    // Note: Branch is preserved for potential PR creation / inspection
+    if (cluster.worktree?.manager) {
+      this._log(`[Orchestrator] Force removing worktree for ${clusterId}...`);
+      cluster.worktree.manager.cleanupWorktreeIsolation(clusterId, { preserveBranch: true });
+      this._log(`[Orchestrator] Worktree removed, branch ${cluster.worktree.branch} preserved`);
+    }
+
     // Close message bus and ledger
     cluster.messageBus.close();
 
@@ -1113,6 +1175,20 @@ class Orchestrator {
       }
     }
 
+    // Verify worktree still exists for worktree isolation mode
+    if (cluster.worktree?.enabled) {
+      const worktreePath = cluster.worktree.path;
+      if (!fs.existsSync(worktreePath)) {
+        throw new Error(
+          `Cannot resume cluster ${clusterId}: worktree at ${worktreePath} no longer exists. ` +
+            `Was the worktree manually removed? Use 'zeroshot run' to start fresh.`
+        );
+      }
+
+      this._log(`[Orchestrator] Worktree at ${worktreePath} exists, reusing`);
+      this._log(`[Orchestrator] Branch: ${cluster.worktree.branch}`);
+    }
+
     // Restart all agents
     cluster.state = 'running';
     for (const agent of cluster.agents) {
@@ -1561,10 +1637,15 @@ Continue from where you left off. Review your previous output to understand what
 
       // Build agent options
       const agentOptions = {
-        testMode: false,
+        testMode: !!this.taskRunner, // Enable testMode if taskRunner provided
         quiet: this.quiet,
       };
 
+      // TaskRunner DI - propagate to dynamically spawned agents
+      if (this.taskRunner) {
+        agentOptions.taskRunner = this.taskRunner;
+      }
+
       // Pass isolation context if cluster is running in isolation mode
       if (cluster.isolation?.enabled && context.isolationManager) {
         agentOptions.isolation = {
@@ -1658,7 +1739,7 @@ Continue from where you left off. Review your previous output to understand what
    * @private
    */
   _opPublish(cluster, op, sender) {
-    const { topic, content } = op;
+    const { topic, content, metadata } = op;
     if (!topic) {
       throw new Error('publish operation missing topic');
     }
@@ -1669,6 +1750,7 @@ Continue from where you left off. Review your previous output to understand what
       sender: op.sender || sender,
       receiver: op.receiver || 'broadcast',
       content: content || {},
+      metadata: metadata || null,
     });
 
     this._log(`    ✓ Published to topic: ${topic}`);

package/src/preflight.js

@@ -4,7 +4,7 @@
  * Validates:
  * - Claude CLI installed and authenticated
  * - gh CLI installed and authenticated (if using issue numbers)
- * - Docker available (if using --isolation)
+ * - Docker available (if using --docker)
  *
  * Provides CLEAR, ACTIONABLE error messages with recovery instructions.
  */
@@ -232,7 +232,8 @@ function checkDocker() {
  * Run all preflight checks
  * @param {Object} options - Preflight options
  * @param {boolean} options.requireGh - Whether gh CLI is required (true if using issue number)
- * @param {boolean} options.requireDocker - Whether Docker is required (true if using --isolation)
+ * @param {boolean} options.requireDocker - Whether Docker is required (true if using --docker)
+ * @param {boolean} options.requireGit - Whether git repo is required (true if using --worktree)
  * @param {boolean} options.quiet - Suppress success messages
  * @returns {ValidationResult}
  */
@@ -330,6 +331,30 @@ function runPreflight(options = {}) {
     }
   }
 
+  // 5. Check git repo (if required for worktree isolation)
+  if (options.requireGit) {
+    let isGitRepo = false;
+    try {
+      execSync('git rev-parse --git-dir', { stdio: 'pipe' });
+      isGitRepo = true;
+    } catch {
+      // Not a git repo
+    }
+    if (!isGitRepo) {
+      errors.push(
+        formatError(
+          'Not in a git repository',
+          'Worktree isolation requires a git repository',
+          [
+            'Run from within a git repository',
+            'Or use --docker instead of --worktree for non-git directories',
+            'Initialize a repo with: git init',
+          ]
+        )
+      );
+    }
+  }
+
   return {
     valid: errors.length === 0,
     errors,
@@ -342,6 +367,7 @@ function runPreflight(options = {}) {
  * @param {Object} options - Preflight options
  * @param {boolean} options.requireGh - Whether gh CLI is required
  * @param {boolean} options.requireDocker - Whether Docker is required
+ * @param {boolean} options.requireGit - Whether git repo is required
  * @param {boolean} options.quiet - Suppress success messages
  */
 function requirePreflight(options = {}) {

package/src/process-metrics.js

@@ -18,6 +18,18 @@ const fs = require('fs');
 
 const PLATFORM = process.platform;
 
+/**
+ * Escape a string for safe use in shell commands
+ * Prevents shell injection when passing dynamic values to execSync with shell: true
+ * @param {string} str - String to escape
+ * @returns {string} Shell-escaped string
+ */
+function escapeShell(str) {
+  // Replace single quotes with escaped version and wrap in single quotes
+  // This is the safest approach for shell escaping
+  return `'${str.replace(/'/g, "'\\''")}'`;
+}
+
 /**
  * @typedef {Object} ProcessMetrics
  * @property {number} pid - Process ID
@@ -46,7 +58,7 @@ function getChildPids(pid) {
   try {
     if (PLATFORM === 'darwin') {
       // macOS: Use pgrep with -P flag
-      const output = execSync(`pgrep -P ${pid} 2>/dev/null`, {
+      const output = execSync(`pgrep -P ${escapeShell(String(pid))} 2>/dev/null`, {
         encoding: 'utf8',
         timeout: 2000,
       });
@@ -136,7 +148,7 @@ function getProcessMetricsLinux(pid) {
 function getProcessMetricsDarwin(pid) {
   try {
     // ps -p PID -o %cpu=,rss=,state=
-    const output = execSync(`ps -p ${pid} -o %cpu=,rss=,state= 2>/dev/null`, {
+    const output = execSync(`ps -p ${escapeShell(String(pid))} -o %cpu=,rss=,state= 2>/dev/null`, {
       encoding: 'utf8',
       timeout: 2000,
     });
@@ -182,7 +194,7 @@ function getNetworkStateLinux(pid) {
   try {
     // Use ss -tip to get extended TCP info with bytes_sent/bytes_received
     // -t = TCP only, -i = show internal TCP info, -p = show process
-    const output = execSync(`ss -tip 2>/dev/null | grep -A1 "pid=${pid}," || true`, {
+    const output = execSync(`ss -tip 2>/dev/null | grep -A1 "pid=${escapeShell(String(pid))}," || true`, {
       encoding: 'utf8',
       timeout: 3000,
     });
@@ -255,7 +267,7 @@ function getNetworkStateDarwin(pid) {
 
   try {
     // lsof -i -n -P for network connections
-    const output = execSync(`lsof -i -n -P -a -p ${pid} 2>/dev/null || true`, {
+    const output = execSync(`lsof -i -n -P -a -p ${escapeShell(String(pid))} 2>/dev/null || true`, {
       encoding: 'utf8',
       timeout: 3000,
     });

package/src/status-footer.js

@@ -69,17 +69,30 @@ function debounce(fn, ms) {
 class StatusFooter {
   /**
    * @param {Object} options
-   * @param {number} [options.refreshInterval=1000] - Refresh interval in ms
+   * @param {number} [options.samplingInterval=500] - Background metrics sampling interval in ms
+   * @param {number} [options.refreshInterval=100] - Display refresh interval in ms (10 fps)
+   * @param {number} [options.interpolationSpeed=0.15] - Lerp factor (0-1) per refresh tick
    * @param {boolean} [options.enabled=true] - Whether footer is enabled
    * @param {number} [options.maxAgentRows=5] - Max agent rows to display
    */
   constructor(options = {}) {
-    this.refreshInterval = options.refreshInterval || 1000;
+    // INTERPOLATION ARCHITECTURE:
+    // - Sample actual metrics every 500ms (background, non-blocking)
+    // - Display updates every 100ms (10 fps - appears continuous)
+    // - Values smoothly drift toward actual measurements via lerp
+    // - Result: Real-time seeming monitoring even with less frequent polling
+    this.samplingInterval = options.samplingInterval || 500; // Actual metrics poll (ms)
+    this.refreshInterval = options.refreshInterval || 100; // Display update rate (ms) - was 1000
+    this.interpolationSpeed = options.interpolationSpeed || 0.15; // Lerp factor per tick
     this.enabled = options.enabled !== false;
     this.maxAgentRows = options.maxAgentRows || 5;
     this.intervalId = null;
+    this.samplingIntervalId = null; // Background metrics sampler
     this.agents = new Map(); // agentId -> AgentState
-    this.metricsCache = new Map(); // agentId -> ProcessMetrics
+    // Interpolated metrics: { current: {...}, target: {...}, lastSampleTime, exists }
+    // - current: Displayed value (interpolated toward target)
+    // - target: Actual measured value from last sample
+    this.interpolatedMetrics = new Map(); // agentId -> InterpolatedMetrics
     this.footerHeight = 3; // Minimum: header + 1 agent row + summary
     this.lastFooterHeight = 3;
     this.scrollRegionSet = false;
@@ -101,6 +114,9 @@ class StatusFooter {
     // All output must go through print() to coordinate with render cycles
     this.printQueue = [];
 
+    // Blink state for executing agents - toggles on each render for visual pulse
+    this.blinkState = false;
+
     // Debounced resize handler (100ms) - prevents rapid-fire redraws
     this._debouncedResize = debounce(() => this._handleResize(), 100);
   }
@@ -373,30 +389,111 @@ class StatusFooter {
    */
   removeAgent(agentId) {
     this.agents.delete(agentId);
-    this.metricsCache.delete(agentId);
+    this.interpolatedMetrics.delete(agentId);
+  }
+
+  /**
+   * Background metrics sampling - polls actual CPU/RAM every samplingInterval ms
+   * Updates target values that display will interpolate toward
+   * @private
+   */
+  async _sampleMetrics() {
+    for (const [agentId, agent] of this.agents) {
+      if (!agent.pid) continue;
+
+      try {
+        // Get actual metrics with 200ms sample window (for CPU calculation)
+        const raw = await getProcessMetrics(agent.pid, { samplePeriodMs: 200 });
+        const existing = this.interpolatedMetrics.get(agentId);
+
+        this.interpolatedMetrics.set(agentId, {
+          // Keep interpolating from current position (smooth transition)
+          current: existing?.current || {
+            cpuPercent: raw.cpuPercent,
+            memoryMB: raw.memoryMB,
+          },
+          // New target to approach
+          target: {
+            cpuPercent: raw.cpuPercent,
+            memoryMB: raw.memoryMB,
+          },
+          // Network is cumulative - just use latest value (no interpolation)
+          network: raw.network,
+          lastSampleTime: Date.now(),
+          exists: raw.exists,
+        });
+      } catch {
+        // Process may have exited
+        this.interpolatedMetrics.delete(agentId);
+      }
+    }
+  }
+
+  /**
+   * Interpolate current values toward target values
+   * Called each render tick (100ms) for smooth visual updates
+   * @private
+   */
+  _interpolateMetrics() {
+    for (const [, data] of this.interpolatedMetrics) {
+      if (!data.target || !data.current) continue;
+
+      // Lerp CPU and RAM toward target (they fluctuate)
+      data.current.cpuPercent = this._lerp(
+        data.current.cpuPercent,
+        data.target.cpuPercent
+      );
+      data.current.memoryMB = this._lerp(
+        data.current.memoryMB,
+        data.target.memoryMB
+      );
+      // Network is cumulative counter - no interpolation, just use latest
+    }
+  }
+
+  /**
+   * Linear interpolation helper
+   * Moves current 15% of the way toward target each tick
+   * At 100ms ticks: reaches ~87% of target after 1 second
+   * @param {number} current - Current displayed value
+   * @param {number} target - Target measured value
+   * @returns {number} New interpolated value
+   * @private
+   */
+  _lerp(current, target) {
+    if (current === null || current === undefined) return target;
+    if (target === null || target === undefined) return current;
+    const diff = target - current;
+    return current + diff * this.interpolationSpeed;
   }
 
   /**
    * Get status icon for agent state
+   * Uses blinking dot for active states (executing, evaluating, building_context)
    * @param {string} state
    * @returns {string}
    */
   getAgentIcon(state) {
+    // Blinking indicator for active states - alternates between bright and dim
+    const blinkOn = `${COLORS.green}●${COLORS.reset}`;
+    const blinkOff = `${COLORS.dim}○${COLORS.reset}`;
+    const blinkIndicator = this.blinkState ? blinkOn : blinkOff;
+
     switch (state) {
       case 'idle':
-        return '⏳'; // Waiting for trigger
+        return `${COLORS.gray}○${COLORS.reset}`; // Waiting for trigger
       case 'evaluating':
-        return '🔍'; // Evaluating triggers
+        return blinkIndicator; // Evaluating triggers (blinking)
       case 'building_context':
-        return '📝'; // Building context
+        return blinkIndicator; // Building context (blinking)
       case 'executing':
-        return '🔄'; // Running task
+        return blinkIndicator; // Running task (blinking)
       case 'stopped':
-        return '⏹️'; // Stopped
+        return `${COLORS.gray}■${COLORS.reset}`; // Stopped
       case 'error':
-        return '❌'; // Error
+        return `${COLORS.red}●${COLORS.reset}`; // Error
       default:
-        return '⚪';
+        return `${COLORS.gray}○${COLORS.reset}`;
     }
   }
 
@@ -441,7 +538,7 @@ class StatusFooter {
    * Render the footer
    * ROBUST: Uses render lock to prevent concurrent renders from corrupting state
    */
-  async render() {
+  render() {
     if (!this.enabled || !this.isTTY()) return;
 
     // Graceful degradation: don't render if hidden
@@ -453,6 +550,9 @@ class StatusFooter {
     }
     this.isRendering = true;
 
+    // Toggle blink state for visual pulse effect on executing agents
+    this.blinkState = !this.blinkState;
+
     try {
       const { rows, cols } = this.getTerminalSize();
 
@@ -463,18 +563,9 @@ class StatusFooter {
         return;
       }
 
-      // Collect metrics for all agents with PIDs
-      for (const [agentId, agent] of this.agents) {
-        if (agent.pid) {
-          try {
-            const metrics = await getProcessMetrics(agent.pid, { samplePeriodMs: 500 });
-            this.metricsCache.set(agentId, metrics);
-          } catch {
-            // Process may have exited
-            this.metricsCache.delete(agentId);
-          }
-        }
-      }
+      // Interpolate metrics toward targets (called every 100ms for smooth visuals)
+      // Background sampler updates targets every 500ms
+      this._interpolateMetrics();
 
       // Get executing agents for display
       const executingAgents = Array.from(this.agents.entries())
@@ -592,24 +683,25 @@ class StatusFooter {
     const rows = [];
     for (const [agentId, agent] of executingAgents) {
       const icon = this.getAgentIcon(agent.state);
-      const metrics = this.metricsCache.get(agentId);
+      const data = this.interpolatedMetrics.get(agentId);
+      const metrics = data?.current;
 
       // Build columns with fixed widths for alignment
       const iconCol = icon;
       const nameCol = agentId.padEnd(14).slice(0, 14); // Max 14 chars for name
 
       let metricsStr = '';
-      if (metrics && metrics.exists) {
+      if (metrics && data.exists) {
         const cpuColor = metrics.cpuPercent > 50 ? COLORS.yellow : COLORS.green;
-        const cpuVal = `${metrics.cpuPercent}%`.padStart(4);
-        const ramVal = `${metrics.memoryMB}MB`.padStart(6);
+        const cpuVal = `${metrics.cpuPercent.toFixed(1)}%`.padStart(6);
+        const ramVal = `${metrics.memoryMB.toFixed(1)}MB`.padStart(8);
 
         metricsStr += `${COLORS.dim}CPU:${COLORS.reset}${cpuColor}${cpuVal}${COLORS.reset}`;
         metricsStr += `  ${COLORS.dim}RAM:${COLORS.reset}${COLORS.gray}${ramVal}${COLORS.reset}`;
 
-        // Network bytes
-        const net = metrics.network;
-        if (net.bytesSent > 0 || net.bytesReceived > 0) {
+        // Network bytes (cumulative - no interpolation)
+        const net = data.network;
+        if (net && (net.bytesSent > 0 || net.bytesReceived > 0)) {
           const sent = this.formatBytes(net.bytesSent).padStart(7);
           const recv = this.formatBytes(net.bytesReceived).padStart(7);
           metricsStr += `  ${COLORS.dim}NET:${COLORS.reset}${COLORS.cyan}↑${sent} ↓${recv}${COLORS.reset}`;
@@ -684,25 +776,25 @@ class StatusFooter {
       }
     }
 
-    // Aggregate metrics
+    // Aggregate metrics (using interpolated values for smooth display)
     let totalCpu = 0;
     let totalMem = 0;
     let totalBytesSent = 0;
     let totalBytesReceived = 0;
-    for (const metrics of this.metricsCache.values()) {
-      if (metrics.exists) {
-        totalCpu += metrics.cpuPercent;
-        totalMem += metrics.memoryMB;
-        totalBytesSent += metrics.network.bytesSent || 0;
-        totalBytesReceived += metrics.network.bytesReceived || 0;
+    for (const data of this.interpolatedMetrics.values()) {
+      if (data.exists && data.current) {
+        totalCpu += data.current.cpuPercent;
+        totalMem += data.current.memoryMB;
+        totalBytesSent += data.network?.bytesSent || 0;
+        totalBytesReceived += data.network?.bytesReceived || 0;
       }
     }
 
     if (totalCpu > 0 || totalMem > 0) {
       parts.push(` ${COLORS.gray}│${COLORS.reset}`);
       let aggregateStr = ` ${COLORS.cyan}Σ${COLORS.reset} `;
-      aggregateStr += `${COLORS.dim}CPU:${COLORS.reset}${totalCpu.toFixed(0)}%`;
-      aggregateStr += ` ${COLORS.dim}RAM:${COLORS.reset}${totalMem.toFixed(0)}MB`;
+      aggregateStr += `${COLORS.dim}CPU:${COLORS.reset}${totalCpu.toFixed(1)}%`;
+      aggregateStr += ` ${COLORS.dim}RAM:${COLORS.reset}${totalMem.toFixed(1)}MB`;
       if (totalBytesSent > 0 || totalBytesReceived > 0) {
         aggregateStr += ` ${COLORS.dim}NET:${COLORS.reset}${COLORS.cyan}↑${this.formatBytes(totalBytesSent)} ↓${this.formatBytes(totalBytesReceived)}${COLORS.reset}`;
       }
@@ -750,8 +842,19 @@ class StatusFooter {
     // Handle terminal resize with debounced handler
     process.stdout.on('resize', this._debouncedResize);
 
-    // Start refresh interval
-    // Guard: Skip if previous render still running (prevents overlapping renders)
+    // Start background metrics sampling (every 500ms)
+    // Non-blocking - updates target values that display will interpolate toward
+    this.samplingIntervalId = setInterval(() => {
+      this._sampleMetrics().catch(() => {
+        // Ignore sampling errors - display will show stale data
+      });
+    }, this.samplingInterval);
+
+    // Initial metrics sample (async, don't block startup)
+    this._sampleMetrics().catch(() => {});
+
+    // Start display refresh interval (every 100ms - 10 fps)
+    // Interpolates current values toward targets for smooth visual updates
     this.intervalId = setInterval(() => {
       if (this.isRendering) return;
       this.render();
@@ -770,6 +873,12 @@ class StatusFooter {
       this.intervalId = null;
     }
 
+    // Stop background metrics sampling
+    if (this.samplingIntervalId) {
+      clearInterval(this.samplingIntervalId);
+      this.samplingIntervalId = null;
+    }
+
     // Remove resize listener
     process.stdout.removeListener('resize', this._debouncedResize);