@covibes/zeroshot 1.1.3 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+# [1.2.0](https://github.com/covibes/zeroshot/compare/v1.1.4...v1.2.0) (2025-12-28)
+
+
+### Bug Fixes
+
+* **status-footer:** robust terminal resize handling ([767a610](https://github.com/covibes/zeroshot/commit/767a610027b3e2bb238b54c31a3a7e93db635319))
+
+
+### Features
+
+* **agent:** publish TOKEN_USAGE events with task completion ([c79482c](https://github.com/covibes/zeroshot/commit/c79482c82582b75a692ba71005c821decdc1d769))
+* **stream-parser:** add token usage tracking to result events ([91ad850](https://github.com/covibes/zeroshot/commit/91ad8507f42fd1a398bdc06f3b91b0a13eec8941))
+
+## [1.1.4](https://github.com/covibes/zeroshot/compare/v1.1.3...v1.1.4) (2025-12-28)
+
+
+### Bug Fixes
+
+* **cli:** read version from package.json instead of hardcoded value ([a6e0e57](https://github.com/covibes/zeroshot/commit/a6e0e570feeaffa64dbc46d494eeef000f32b708))
+* **cli:** resolve streaming mode crash and refactor message formatters ([efb9264](https://github.com/covibes/zeroshot/commit/efb9264ce0d3ede0eb7d502d4625694c2c525230))
+
 ## [1.1.3](https://github.com/covibes/zeroshot/compare/v1.1.2...v1.1.3) (2025-12-28)
 
 

package/cli/index.js

@@ -341,7 +341,7 @@ if (shouldShowBanner) {
 program
   .name('zeroshot')
   .description('Multi-agent orchestration and task management for Claude')
-  .version('1.0.0')
+  .version(require('../package.json').version)
   .addHelpText(
     'after',
     `
@@ -3666,7 +3666,7 @@ function printMessage(msg, showClusterId = false, watchMode = false, isActive =
   }
 
   if (msg.topic === 'ISSUE_OPENED') {
-    formatIssueOpenedNormal(msg, prefix, timestamp);
+    formatIssueOpenedNormal(msg, prefix, timestamp, shownNewTaskForCluster);
     return;
   }
 

package/cluster-templates/base-templates/debug-workflow.json

@@ -81,7 +81,6 @@
       "id": "fixer",
       "role": "implementation",
       "model": "{{fixer_model}}",
-      "outputFormat": "stream-json",
       "prompt": {
         "system": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are a bug fixer. Apply the fix from the investigator.\n\n## Your Job\nFix the root cause identified in INVESTIGATION_COMPLETE.\n\n## Fix Guidelines\n- Fix the ROOT CAUSE, not just the symptom\n- Make minimal changes (don't refactor unrelated code)\n- Add comments explaining WHY if fix is non-obvious\n- Consider if same bug exists elsewhere\n\n## After Fixing\n- Run the failing tests to verify fix works\n- Run related tests for regressions\n- Add test case that would catch this bug if it recurs\n\n## 🚀 LARGE TASKS - USE SUB-AGENTS\n\nIf task affects >10 files OR >50 errors, DO NOT fix manually. Use the Task tool to spawn parallel sub-agents:\n\n1. **Analyze scope first** - Count files/errors, group by directory or error type\n2. **Spawn sub-agents** - One per group, run in parallel\n3. **Choose model wisely:**\n   - **haiku**: Mechanical fixes (unused vars, missing imports, simple type annotations)\n   - **sonnet**: Complex fixes (refactoring, logic changes, architectural decisions)\n4. **Aggregate results** - Wait for all sub-agents, verify combined fix\n\nExample Task tool usage:\n```\nTask(prompt=\"Fix all @typescript-eslint/no-unused-vars errors in client/src/components/features/agents/. Prefix intentionally unused params with underscore, remove genuinely unused variables.\", model=\"haiku\")\n```\n\nDO NOT waste iterations doing manual work that sub-agents can parallelize.\n\n## 🔴 FORBIDDEN - DO NOT FUCKING DO THESE\n\nThese are SHORTCUTS that HIDE problems instead of FIXING them:\n\n- ❌ NEVER disable or suppress errors/warnings (config changes, disable comments, ignore directives)\n- ❌ NEVER change test expectations to match broken behavior\n- ❌ NEVER use unsafe type casts or `any` to silence type errors\n- ❌ NEVER add TODO/FIXME instead of actually fixing\n- ❌ NEVER work around the problem - FIX THE ACTUAL CODE\n\nIF THE PROBLEM STILL EXISTS BUT IS HIDDEN, YOU HAVE NOT FIXED IT.\n\n## On Rejection - READ THE FUCKING FEEDBACK\n\nWhen tester rejects:\n1. STOP. READ what they wrote. UNDERSTAND the issue.\n2. If same problem persists → your fix is WRONG, try DIFFERENT approach\n3. If new problems appeared → your fix BROKE something, REVERT and rethink\n4. Do NOT blindly retry the same approach\n5. If you are STUCK, say so. Do not waste iterations doing nothing.\n\nRepeating failed approaches = wasted time and money. LEARN from rejection."
       },

package/cluster-templates/base-templates/full-workflow.json

@@ -137,7 +137,6 @@
       "id": "worker",
       "role": "implementation",
       "model": "{{worker_model}}",
-      "outputFormat": "stream-json",
       "prompt": {
         "initial": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are an implementation agent for a {{complexity}} {{task_type}} task.\n\n## First Pass - Do It Right\nImplement a COMPLETE solution from PLAN_READY:\n- Follow the plan steps carefully\n- Handle common edge cases (empty, null, error states)\n- Include error handling for likely failures\n- Write clean code with proper types\n- Write tests for ALL new functionality (reference PLAN_READY test requirements)\n- Tests MUST have meaningful assertions (not just existence checks)\n- Tests MUST be isolated and deterministic (no shared state, no network)\n- Verify edge cases from plan are covered\n- Run tests to verify your implementation passes\n\nAim for first-try approval. Don't leave obvious gaps for validators to find.\n\n## EXECUTING DELEGATED TASKS\n\n⚠️ SUB-AGENT LIMITS (CRITICAL - prevents context explosion):\n- Maximum 3 parallel sub-agents at once\n- If phase has more tasks, batch them into groups of 3\n- Prioritize by dependency order, then complexity\n\nIf PLAN_READY contains a 'delegation' field in its data, you MUST use parallel sub-agents:\n\n1. Parse delegation.phases and delegation.tasks from the plan data\n2. For each phase in order:\n   a. Find all tasks for this phase (matching taskIds)\n   b. Split into batches of MAX 3 tasks each\n   c. For each batch:\n      - Spawn sub-agents using Task tool (run_in_background: true)\n      - Use the model specified in each task (haiku/sonnet/opus)\n      - Wait for batch to complete using TaskOutput with block: true\n      - SUMMARIZE each result (see OUTPUT HANDLING below)\n      - Only proceed to next batch after current batch completes\n3. After ALL phases complete, verify changes work together\n4. Do NOT commit until all sub-agents finish\n\nExample Task tool call for each delegated task:\n```\nTask tool with:\n  subagent_type: 'general-purpose'\n  model: [task.model from delegation]\n  prompt: '[task.description]. Files: [task.scope]. Do NOT commit.'\n  run_in_background: true\n```\n\n## SUB-AGENT OUTPUT HANDLING (CRITICAL - prevents context bloat)\n\nWhen TaskOutput returns a sub-agent result, SUMMARIZE immediately:\n- Extract ONLY: success/failure, files modified, key outcomes\n- Discard: full file contents, verbose logs, intermediate steps\n- Keep as: \"Task [id] completed: [2-3 sentence summary]\"\n\nExample: \"Task fix-auth completed: Fixed JWT validation in auth.ts, added null check. Tests pass.\"\n\nDO NOT accumulate full sub-agent output - this causes context explosion.\n\nIf NO delegation field, implement directly as normal.\n\n{{#if complexity == 'CRITICAL'}}\n## CRITICAL TASK - EXTRA CARE\n- Double-check every change\n- No shortcuts or assumptions\n- Consider security implications\n- Add comprehensive error handling\n{{/if}}",
         "subsequent": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are an implementation agent for a {{complexity}} {{task_type}} task.\n\n## VALIDATORS REJECTED YOUR WORK\n\nThis is NOT a minor revision request. Senior engineers reviewed your code and found it UNACCEPTABLE. Read ALL VALIDATION_RESULT messages carefully.\n\n## FIX LIKE A SENIOR ARCHITECT WOULD\n\n### 1. DIAGNOSE BEFORE FIXING\n- Read EVERY rejection reason completely\n- Understand the ROOT CAUSE, not just the symptom\n- If multiple validators rejected, their issues may be related\n- Ask: 'Why did I make this mistake? Is my approach fundamentally flawed?'\n\n### 2. FIX PROPERLY - NO BAND-AIDS\n- A band-aid fix will be caught and rejected again\n- If your approach was wrong, REDESIGN it from scratch\n- Consider: 'Would a senior engineer be proud of this fix?'\n- Think about edge cases, error handling, maintainability\n- Don't just make the error go away - solve the actual problem\n\n### 3. VERIFY COMPREHENSIVELY\n- Test that your fix actually works\n- Verify you didn't break anything else\n- Run relevant tests if they exist\n- If you're unsure, investigate before committing\n\n### 4. ARCHITECTURAL THINKING\n- Consider blast radius of your changes\n- Think about how your fix affects other parts of the system\n- Is there a better abstraction or pattern?\n- Future maintainers will inherit your decisions\n\n## MINDSET\n- Validators are not being pedantic - they found REAL problems\n- Every rejection is expensive - get it right this time\n- Shortcuts and hacks will be caught immediately\n- Pride in craftsmanship: deliver code you'd want to maintain\n\n{{#if complexity == 'CRITICAL'}}\n## CRITICAL TASK - ZERO TOLERANCE FOR SHORTCUTS\n- This is HIGH RISK code (auth, payments, security, production)\n- Triple-check every change\n- Consider all failure modes\n- Security implications must be addressed\n- Comprehensive error handling is MANDATORY\n- If unsure, err on the side of caution\n{{/if}}"

package/cluster-templates/base-templates/single-worker.json

@@ -19,7 +19,6 @@
       "id": "worker",
       "role": "implementation",
       "model": "{{worker_model}}",
-      "outputFormat": "stream-json",
       "prompt": {
         "system": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are an agent handling a {{task_type}} task.\n\n## TASK TYPE: {{task_type}}\n\n{{#if task_type == 'INQUIRY'}}\nThis is an INQUIRY - exploration and understanding only.\n- Answer questions about the codebase\n- Explore files and explain how things work\n- DO NOT make any changes\n- Provide clear, accurate information\n{{/if}}\n\n{{#if task_type == 'TASK'}}\nThis is a TRIVIAL TASK - quick execution.\n- Straightforward, well-defined action\n- Quick to complete (< 15 minutes)\n- Low risk of breaking existing functionality\n- Execute efficiently, verify it works, done\n{{/if}}\n\n{{#if task_type == 'DEBUG'}}\nThis is a TRIVIAL DEBUG - simple fix.\n- Obvious issue with clear solution\n- Fix the root cause, not symptoms\n- Verify the fix works\n{{/if}}"
       },

package/cluster-templates/base-templates/worker-validator.json

@@ -25,7 +25,6 @@
       "id": "worker",
       "role": "implementation",
       "model": "{{worker_model}}",
-      "outputFormat": "stream-json",
       "prompt": {
         "system": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are an implementation agent for a SIMPLE {{task_type}} task.\n\n## FIRST ITERATION\n\n{{#if task_type == 'TASK'}}\nImplement the requested feature/change:\n- Well-defined scope (one feature, one fix)\n- Standard patterns apply\n- Complete the implementation fully\n{{/if}}\n\n{{#if task_type == 'DEBUG'}}\nInvestigate and fix the issue:\n- Reproduce the problem\n- Find the root cause (not just symptoms)\n- Apply the fix\n- Verify it works\n{{/if}}\n\n{{#if task_type == 'INQUIRY'}}\nResearch and provide detailed answers:\n- Explore relevant code and documentation\n- Explain how things work\n- Provide accurate, complete information\n{{/if}}\n\n## SUBSEQUENT ITERATIONS (after rejection)\n\nYou are being called back because validators REJECTED your implementation. This is NOT a minor issue.\n\n### FIX LIKE A SENIOR ENGINEER\n\n1. **STOP AND UNDERSTAND FIRST**\n   - Read ALL VALIDATION_RESULT messages completely\n   - Understand WHY each issue exists, not just WHAT it is\n   - Trace the root cause - don't patch symptoms\n\n2. **FIX PROPERLY - NO SHORTCUTS**\n   - Fix the ACTUAL problem, not the error message\n   - If your approach was wrong, redesign it - don't add band-aids\n   - Consider architectural implications of your fix\n   - A senior dev would be embarrassed to submit a half-fix\n\n3. **VERIFY YOUR FIX**\n   - Test your changes actually work\n   - Check you didn't break anything else\n   - If unsure, investigate before committing\n\n### MINDSET\n- Validators are senior engineers reviewing your code\n- They found REAL problems - take them seriously\n- Shortcuts will be caught and rejected again"
       },

package/lib/settings.js

@@ -15,7 +15,7 @@ const DEFAULT_SETTINGS = {
   defaultModel: 'sonnet',
   defaultConfig: 'conductor-bootstrap',
   defaultIsolation: false,
-  strictSchema: false, // false = live streaming (default), true = guaranteed schema compliance (no streaming)
+  strictSchema: true, // true = reliable json output (default), false = live streaming (may crash - see bold-meadow-11)
   logLevel: 'normal',
 };
 

package/lib/stream-json-parser.js

@@ -45,8 +45,9 @@ function parseStreamLine(line) {
     return parseUserMessage(event.message);
   }
 
-  // result - final task result
+  // result - final task result (includes token usage and cost)
   if (event.type === 'result') {
+    const usage = event.usage || {};
     return {
       type: 'result',
       success: event.subtype === 'success',
@@ -54,6 +55,13 @@ function parseStreamLine(line) {
       error: event.is_error ? event.result : null,
       cost: event.total_cost_usd,
       duration: event.duration_ms,
+      // Token usage from Claude API
+      inputTokens: usage.input_tokens || 0,
+      outputTokens: usage.output_tokens || 0,
+      cacheReadInputTokens: usage.cache_read_input_tokens || 0,
+      cacheCreationInputTokens: usage.cache_creation_input_tokens || 0,
+      // Per-model breakdown (for multi-model tasks)
+      modelUsage: event.modelUsage || null,
     };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@covibes/zeroshot",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Multi-agent orchestration engine for Claude - cluster coordinator and CLI",
   "main": "src/orchestrator.js",
   "bin": {

package/src/agent/agent-lifecycle.js

@@ -278,8 +278,28 @@ async function executeTask(agent, triggeringMessage) {
         iteration: agent.iteration,
         success: true,
         taskId: agent.currentTaskId,
+        tokenUsage: result.tokenUsage || null,
       });
 
+      // Publish TOKEN_USAGE event for aggregation and tracking
+      if (result.tokenUsage) {
+        agent.messageBus.publish({
+          cluster_id: agent.cluster.id,
+          topic: 'TOKEN_USAGE',
+          sender: agent.id,
+          content: {
+            text: `${agent.id} used ${result.tokenUsage.inputTokens} input + ${result.tokenUsage.outputTokens} output tokens`,
+            data: {
+              agentId: agent.id,
+              role: agent.role,
+              model: agent._selectModel(),
+              iteration: agent.iteration,
+              ...result.tokenUsage,
+            },
+          },
+        });
+      }
+
       // Execute onComplete hook
       await executeHook({
         hook: agent.config.hooks?.onComplete,

package/src/agent/agent-task-executor.js

@@ -54,6 +54,44 @@ function sanitizeErrorMessage(error) {
 // Track if we've already ensured the AskUserQuestion hook is installed
 let askUserQuestionHookInstalled = false;
 
+/**
+ * Extract token usage from NDJSON output.
+ * Looks for the 'result' event line which contains usage data.
+ *
+ * @param {string} output - Full NDJSON output from Claude CLI
+ * @returns {Object|null} Token usage data or null if not found
+ */
+function extractTokenUsage(output) {
+  if (!output) return null;
+
+  const lines = output.split('\n');
+
+  // Find the result line containing usage data
+  for (const line of lines) {
+    if (!line.trim()) continue;
+
+    try {
+      const event = JSON.parse(line.trim());
+      if (event.type === 'result') {
+        const usage = event.usage || {};
+        return {
+          inputTokens: usage.input_tokens || 0,
+          outputTokens: usage.output_tokens || 0,
+          cacheReadInputTokens: usage.cache_read_input_tokens || 0,
+          cacheCreationInputTokens: usage.cache_creation_input_tokens || 0,
+          totalCostUsd: event.total_cost_usd || null,
+          durationMs: event.duration_ms || null,
+          modelUsage: event.modelUsage || null,
+        };
+      }
+    } catch {
+      // Not valid JSON, continue
+    }
+  }
+
+  return null;
+}
+
 /**
  * Ensure the AskUserQuestion blocking hook is installed in user's Claude config.
  * This adds defense-in-depth by blocking the tool at the Claude CLI level.
@@ -569,6 +607,7 @@ function followClaudeTaskLogs(agent, taskId) {
               success,
               output,
               error: sanitizeErrorMessage(errorContext),
+              tokenUsage: extractTokenUsage(output),
             });
           }, 500);
         }
@@ -590,6 +629,7 @@ function followClaudeTaskLogs(agent, taskId) {
           success: false,
           output,
           error: reason,
+          tokenUsage: extractTokenUsage(output),
         });
       },
     };
@@ -907,6 +947,7 @@ function followClaudeTaskLogsIsolated(agent, taskId) {
                 output: fullOutput,
                 taskId,
                 result: parsedResult,
+                tokenUsage: extractTokenUsage(fullOutput),
               });
             }
           } catch (pollErr) {

package/src/process-metrics.js

@@ -366,7 +366,11 @@ async function getProcessMetricsLinuxAggregated(pid, samplePeriodMs) {
   const clockTicks = 100; // Usually 100 on Linux
   const cpuSeconds = totalCpuTicksDelta / clockTicks;
   const sampleSeconds = samplePeriodMs / 1000;
-  const cpuPercent = (cpuSeconds / sampleSeconds) * 100;
+  const rawCpuPercent = (cpuSeconds / sampleSeconds) * 100;
+
+  // Normalize to per-core average (0-100% range)
+  const cpuCores = require('os').cpus().length;
+  const cpuPercent = Math.min(100, rawCpuPercent / cpuCores);
 
   // Get network state for all processes
   let network = { established: 0, hasActivity: false, sendQueueBytes: 0, recvQueueBytes: 0, bytesSent: 0, bytesReceived: 0 };
@@ -444,10 +448,14 @@ function getProcessMetricsDarwinAggregated(pid) {
     if (netState.hasActivity) network.hasActivity = true;
   }
 
+  // Normalize to per-core average (0-100% range)
+  const cpuCores = require('os').cpus().length;
+  const normalizedCpu = Math.min(100, totalCpuPercent / cpuCores);
+
   return {
     pid,
     exists: true,
-    cpuPercent: parseFloat(totalCpuPercent.toFixed(1)),
+    cpuPercent: parseFloat(normalizedCpu.toFixed(1)),
     memoryMB: parseFloat((totalMemoryKB / 1024).toFixed(1)),
     state: rootState,
     threads: totalThreads,

package/src/status-footer.js

@@ -8,6 +8,13 @@
  *
  * Uses ANSI escape sequences to maintain a fixed footer while
  * allowing normal terminal output to scroll above it.
+ *
+ * ROBUST RESIZE HANDLING:
+ * - Debounced resize events (100ms) prevent rapid-fire redraws
+ * - Render lock prevents concurrent renders from corrupting state
+ * - Full footer clear before scroll region reset prevents artifacts
+ * - Dimension checkpointing skips unnecessary redraws
+ * - Graceful degradation for terminals < 8 rows
  */
 
 const { getProcessMetrics } = require('./process-metrics');
@@ -37,6 +44,20 @@ const COLORS = {
   bgBlack: `${CSI}40m`,
 };
 
+/**
+ * Debounce function - prevents rapid-fire calls during resize
+ * @param {Function} fn - Function to debounce
+ * @param {number} ms - Debounce delay in milliseconds
+ * @returns {Function} Debounced function
+ */
+function debounce(fn, ms) {
+  let timeout;
+  return (...args) => {
+    clearTimeout(timeout);
+    timeout = setTimeout(() => fn(...args), ms);
+  };
+}
+
 /**
  * @typedef {Object} AgentState
  * @property {string} id - Agent ID
@@ -65,6 +86,17 @@ class StatusFooter {
     this.clusterId = null;
     this.clusterState = 'initializing';
     this.startTime = Date.now();
+
+    // Robust resize handling state
+    this.isRendering = false; // Render lock - prevents concurrent renders
+    this.pendingResize = false; // Queue resize if render in progress
+    this.lastKnownRows = 0; // Track terminal dimensions for change detection
+    this.lastKnownCols = 0;
+    this.minRows = 8; // Minimum rows for footer display (graceful degradation)
+    this.hidden = false; // True when terminal too small for footer
+
+    // Debounced resize handler (100ms) - prevents rapid-fire redraws
+    this._debouncedResize = debounce(() => this._handleResize(), 100);
   }
 
   /**
@@ -95,22 +127,80 @@ class StatusFooter {
     process.stdout.write(`${CSI}${row};${col}H`);
   }
 
+  /**
+   * Clear a specific line completely
+   * @param {number} row - 1-based row number
+   * @private
+   */
+  _clearLine(row) {
+    process.stdout.write(`${CSI}${row};1H${CLEAR_LINE}`);
+  }
+
+  /**
+   * Clear all footer lines (uses last known height for safety)
+   * @private
+   */
+  _clearFooterArea() {
+    const { rows } = this.getTerminalSize();
+    // Use max of current and last footer height to ensure full cleanup
+    const heightToClear = Math.max(this.footerHeight, this.lastFooterHeight, 3);
+    const startRow = Math.max(1, rows - heightToClear + 1);
+
+    for (let row = startRow; row <= rows; row++) {
+      this._clearLine(row);
+    }
+  }
+
   /**
    * Set up scroll region to reserve space for footer
+   * ROBUST: Clears footer area first, resets to full screen, then sets new region
    */
   setupScrollRegion() {
     if (!this.isTTY()) return;
 
-    const { rows } = this.getTerminalSize();
+    const { rows, cols } = this.getTerminalSize();
+
+    // Graceful degradation: hide footer if terminal too small
+    if (rows < this.minRows) {
+      if (!this.hidden) {
+        this.hidden = true;
+        // Reset to full screen scroll
+        process.stdout.write(`${CSI}1;${rows}r`);
+        this.scrollRegionSet = false;
+      }
+      return;
+    }
+
+    // Restore footer if terminal grew large enough
+    if (this.hidden) {
+      this.hidden = false;
+    }
+
     const scrollEnd = rows - this.footerHeight;
 
-    // Set scroll region (lines 1 to scrollEnd)
+    // CRITICAL: Save cursor before any manipulation
+    process.stdout.write(SAVE_CURSOR);
+    process.stdout.write(HIDE_CURSOR);
+
+    // Step 1: Reset scroll region to full screen first (prevents artifacts)
+    process.stdout.write(`${CSI}1;${rows}r`);
+
+    // Step 2: Clear footer area completely (prevents ghosting)
+    this._clearFooterArea();
+
+    // Step 3: Set new scroll region (lines 1 to scrollEnd)
     process.stdout.write(`${CSI}1;${scrollEnd}r`);
 
-    // Move cursor to top of scroll region
-    process.stdout.write(`${CSI}1;1H`);
+    // Step 4: Move cursor to bottom of scroll region (safe position)
+    process.stdout.write(`${CSI}${scrollEnd};1H`);
+
+    // Restore cursor and show it
+    process.stdout.write(RESTORE_CURSOR);
+    process.stdout.write(SHOW_CURSOR);
 
     this.scrollRegionSet = true;
+    this.lastKnownRows = rows;
+    this.lastKnownCols = cols;
   }
 
   /**
@@ -124,6 +214,35 @@ class StatusFooter {
     this.scrollRegionSet = false;
   }
 
+  /**
+   * Handle terminal resize event
+   * Called via debounced wrapper to prevent rapid-fire redraws
+   * @private
+   */
+  _handleResize() {
+    if (!this.isTTY()) return;
+
+    const { rows, cols } = this.getTerminalSize();
+
+    // Skip if dimensions haven't actually changed (debounce may still fire)
+    if (rows === this.lastKnownRows && cols === this.lastKnownCols) {
+      return;
+    }
+
+    // If render in progress, queue resize for after
+    if (this.isRendering) {
+      this.pendingResize = true;
+      return;
+    }
+
+    // Update dimensions and reconfigure
+    this.lastKnownRows = rows;
+    this.lastKnownCols = cols;
+
+    this.setupScrollRegion();
+    this.render();
+  }
+
   /**
    * Register cluster for monitoring
    * @param {string} clusterId
@@ -223,72 +342,101 @@ class StatusFooter {
 
   /**
    * Render the footer
+   * ROBUST: Uses render lock to prevent concurrent renders from corrupting state
    */
   async render() {
     if (!this.enabled || !this.isTTY()) return;
 
-    const { rows, cols } = this.getTerminalSize();
+    // Graceful degradation: don't render if hidden
+    if (this.hidden) 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);
-        }
-      }
+    // Render lock: prevent concurrent renders
+    if (this.isRendering) {
+      return;
     }
+    this.isRendering = true;
 
-    // Get executing agents for display
-    const executingAgents = Array.from(this.agents.entries())
-      .filter(([, agent]) => agent.state === 'executing')
-      .slice(0, this.maxAgentRows);
+    try {
+      const { rows, cols } = this.getTerminalSize();
 
-    // Calculate dynamic footer height: header + agent rows + separator + summary
-    // Minimum 3 lines (header + "no agents" message + summary)
-    const agentRowCount = Math.max(1, executingAgents.length);
-    const newHeight = 2 + agentRowCount + 1; // header + agents + summary (separator merged with summary)
+      // Double-check terminal size (may have changed since last check)
+      if (rows < this.minRows) {
+        this.hidden = true;
+        this.resetScrollRegion();
+        return;
+      }
 
-    // Update scroll region if height changed
-    if (newHeight !== this.footerHeight) {
-      this.footerHeight = newHeight;
-      this.setupScrollRegion();
-    }
+      // 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);
+          }
+        }
+      }
 
-    // Build footer lines
-    const headerLine = this.buildHeaderLine(cols);
-    const agentRows = this.buildAgentRows(executingAgents, cols);
-    const summaryLine = this.buildSummaryLine(cols);
+      // Get executing agents for display
+      const executingAgents = Array.from(this.agents.entries())
+        .filter(([, agent]) => agent.state === 'executing')
+        .slice(0, this.maxAgentRows);
+
+      // Calculate dynamic footer height: header + agent rows + summary
+      // Minimum 3 lines (header + "no agents" message + summary)
+      const agentRowCount = Math.max(1, executingAgents.length);
+      const newHeight = 2 + agentRowCount + 1; // header + agents + summary
+
+      // Update scroll region if height changed
+      if (newHeight !== this.footerHeight) {
+        this.lastFooterHeight = this.footerHeight;
+        this.footerHeight = newHeight;
+        this.setupScrollRegion();
+      }
 
-    // Save cursor, render footer, restore cursor
-    process.stdout.write(SAVE_CURSOR);
-    process.stdout.write(HIDE_CURSOR);
+      // Build footer lines
+      const headerLine = this.buildHeaderLine(cols);
+      const agentRows = this.buildAgentRows(executingAgents, cols);
+      const summaryLine = this.buildSummaryLine(cols);
 
-    // Render from top of footer area
-    let currentRow = rows - this.footerHeight + 1;
+      // Save cursor, render footer, restore cursor
+      process.stdout.write(SAVE_CURSOR);
+      process.stdout.write(HIDE_CURSOR);
 
-    // Header line
-    this.moveTo(currentRow++, 1);
-    process.stdout.write(CLEAR_LINE);
-    process.stdout.write(`${COLORS.bgBlack}${headerLine}${COLORS.reset}`);
+      // Render from top of footer area
+      let currentRow = rows - this.footerHeight + 1;
 
-    // Agent rows
-    for (const agentRow of agentRows) {
+      // Header line
       this.moveTo(currentRow++, 1);
       process.stdout.write(CLEAR_LINE);
-      process.stdout.write(`${COLORS.bgBlack}${agentRow}${COLORS.reset}`);
-    }
+      process.stdout.write(`${COLORS.bgBlack}${headerLine}${COLORS.reset}`);
+
+      // Agent rows
+      for (const agentRow of agentRows) {
+        this.moveTo(currentRow++, 1);
+        process.stdout.write(CLEAR_LINE);
+        process.stdout.write(`${COLORS.bgBlack}${agentRow}${COLORS.reset}`);
+      }
 
-    // Summary line (with bottom border)
-    this.moveTo(currentRow, 1);
-    process.stdout.write(CLEAR_LINE);
-    process.stdout.write(`${COLORS.bgBlack}${summaryLine}${COLORS.reset}`);
+      // Summary line (with bottom border)
+      this.moveTo(currentRow, 1);
+      process.stdout.write(CLEAR_LINE);
+      process.stdout.write(`${COLORS.bgBlack}${summaryLine}${COLORS.reset}`);
 
-    process.stdout.write(RESTORE_CURSOR);
-    process.stdout.write(SHOW_CURSOR);
+      process.stdout.write(RESTORE_CURSOR);
+      process.stdout.write(SHOW_CURSOR);
+    } finally {
+      this.isRendering = false;
+
+      // Process pending resize if one was queued during render
+      if (this.pendingResize) {
+        this.pendingResize = false;
+        // Use setImmediate to avoid deep recursion
+        setImmediate(() => this._handleResize());
+      }
+    }
   }
 
   /**
@@ -402,7 +550,7 @@ class StatusFooter {
     parts.push(` ${COLORS.gray}│${COLORS.reset} ${COLORS.dim}${duration}${COLORS.reset}`);
 
     // Agent counts
-    const executing = Array.from(this.agents.values()).filter(a => a.state === 'executing').length;
+    const executing = Array.from(this.agents.values()).filter((a) => a.state === 'executing').length;
     const total = this.agents.size;
     parts.push(` ${COLORS.gray}│${COLORS.reset} ${COLORS.green}${executing}/${total}${COLORS.reset} active`);
 
@@ -456,13 +604,21 @@ class StatusFooter {
       return;
     }
 
+    // Initialize dimension tracking
+    const { rows, cols } = this.getTerminalSize();
+    this.lastKnownRows = rows;
+    this.lastKnownCols = cols;
+
+    // Check for graceful degradation at startup
+    if (rows < this.minRows) {
+      this.hidden = true;
+      return; // Don't set up scroll region for tiny terminals
+    }
+
     this.setupScrollRegion();
 
-    // Handle terminal resize
-    process.stdout.on('resize', () => {
-      this.setupScrollRegion();
-      this.render();
-    });
+    // Handle terminal resize with debounced handler
+    process.stdout.on('resize', this._debouncedResize);
 
     // Start refresh interval
     this.intervalId = setInterval(() => {
@@ -482,19 +638,19 @@ class StatusFooter {
       this.intervalId = null;
     }
 
-    if (this.isTTY()) {
+    // Remove resize listener
+    process.stdout.removeListener('resize', this._debouncedResize);
+
+    if (this.isTTY() && !this.hidden) {
       // Reset scroll region
       this.resetScrollRegion();
 
-      // Clear all footer lines (dynamic height)
-      const { rows } = this.getTerminalSize();
-      const startRow = rows - this.footerHeight + 1;
-      for (let row = startRow; row <= rows; row++) {
-        this.moveTo(row, 1);
-        process.stdout.write(CLEAR_LINE);
-      }
+      // Clear all footer lines
+      this._clearFooterArea();
 
       // Move cursor to safe position
+      const { rows } = this.getTerminalSize();
+      const startRow = rows - this.footerHeight + 1;
       this.moveTo(startRow, 1);
       process.stdout.write(SHOW_CURSOR);
     }
@@ -507,14 +663,7 @@ class StatusFooter {
     if (!this.isTTY()) return;
 
     this.resetScrollRegion();
-
-    // Clear all footer lines (dynamic height)
-    const { rows } = this.getTerminalSize();
-    const startRow = rows - this.footerHeight + 1;
-    for (let row = startRow; row <= rows; row++) {
-      this.moveTo(row, 1);
-      process.stdout.write(CLEAR_LINE);
-    }
+    this._clearFooterArea();
   }
 
   /**
@@ -523,6 +672,14 @@ class StatusFooter {
   show() {
     if (!this.isTTY()) return;
 
+    // Reset hidden state and check terminal size
+    const { rows } = this.getTerminalSize();
+    if (rows < this.minRows) {
+      this.hidden = true;
+      return;
+    }
+
+    this.hidden = false;
     this.setupScrollRegion();
     this.render();
   }

package/src/tui/formatters.js

@@ -62,7 +62,12 @@ const formatBytes = (bytes) => {
  */
 const formatCPU = (percent) => {
   if (typeof percent !== 'number' || percent < 0) return '0.0%';
-  if (percent > 100) percent = 100;
+
+  // Assert normalized range (should never exceed 100% after per-core normalization)
+  if (percent > 100) {
+    console.warn(`[formatCPU] CPU percent ${percent}% exceeds 100% - normalization bug?`);
+    percent = 100;
+  }
 
   return `${percent.toFixed(1)}%`;
 };