@covibes/zeroshot 1.1.4 → 1.3.0

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+# [1.3.0](https://github.com/covibes/zeroshot/compare/v1.2.0...v1.3.0) (2025-12-28)
+
+
+### Features
+
+* **planner:** enforce explicit acceptance criteria via JSON schema ([73009d9](https://github.com/covibes/zeroshot/commit/73009d9ad33e46e546721680be6d2cab9c9e46f0)), closes [#16](https://github.com/covibes/zeroshot/issues/16)
+
+# [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)
 
 

package/cli/index.js

@@ -915,23 +915,44 @@ program
       if (clusters.length > 0) {
         console.log(chalk.bold('\n=== Clusters ==='));
         console.log(
-          `${'ID'.padEnd(25)} ${'State'.padEnd(15)} ${'Agents'.padEnd(10)} ${'Msgs'.padEnd(8)} Created`
+          `${'ID'.padEnd(25)} ${'State'.padEnd(12)} ${'Agents'.padEnd(8)} ${'Tokens'.padEnd(12)} ${'Cost'.padEnd(8)} Created`
         );
         console.log('-'.repeat(100));
 
+        const orchestrator = getOrchestrator();
         for (const cluster of clusters) {
           const created = new Date(cluster.createdAt).toLocaleString();
 
+          // Get token usage
+          let tokenDisplay = '-';
+          let costDisplay = '-';
+          try {
+            const clusterObj = orchestrator.getCluster(cluster.id);
+            if (clusterObj?.messageBus) {
+              const tokensByRole = clusterObj.messageBus.getTokensByRole(cluster.id);
+              if (tokensByRole?._total?.count > 0) {
+                const total = tokensByRole._total;
+                const totalTokens = (total.inputTokens || 0) + (total.outputTokens || 0);
+                tokenDisplay = totalTokens.toLocaleString();
+                if (total.totalCostUsd > 0) {
+                  costDisplay = '$' + total.totalCostUsd.toFixed(3);
+                }
+              }
+            }
+          } catch {
+            /* Token tracking not available */
+          }
+
           // Highlight zombie clusters in red
           const stateDisplay =
             cluster.state === 'zombie'
-              ? chalk.red(cluster.state.padEnd(15))
-              : cluster.state.padEnd(15);
+              ? chalk.red(cluster.state.padEnd(12))
+              : cluster.state.padEnd(12);
 
           const rowColor = cluster.state === 'zombie' ? chalk.red : (s) => s;
 
           console.log(
-            `${rowColor(cluster.id.padEnd(25))} ${stateDisplay} ${cluster.agentCount.toString().padEnd(10)} ${cluster.messageCount.toString().padEnd(8)} ${created}`
+            `${rowColor(cluster.id.padEnd(25))} ${stateDisplay} ${cluster.agentCount.toString().padEnd(8)} ${tokenDisplay.padEnd(12)} ${costDisplay.padEnd(8)} ${created}`
           );
         }
       } else {
@@ -987,6 +1008,24 @@ program
         }
         console.log(`Created: ${new Date(status.createdAt).toLocaleString()}`);
         console.log(`Messages: ${status.messageCount}`);
+
+        // Show token usage if available
+        try {
+          const cluster = getOrchestrator().getCluster(id);
+          if (cluster?.messageBus) {
+            const tokensByRole = cluster.messageBus.getTokensByRole(id);
+            const tokenLines = formatTokenUsage(tokensByRole);
+            if (tokenLines) {
+              console.log('');
+              for (const line of tokenLines) {
+                console.log(line);
+              }
+            }
+          }
+        } catch {
+          /* Token tracking not available */
+        }
+
         console.log(`\nAgents:`);
 
         for (const agent of status.agents) {
@@ -1553,16 +1592,29 @@ Key bindings:
           for (const clusterId of clusters) {
             const agents = await socketDiscovery.listAttachableAgents(clusterId);
             console.log(`  ${clusterId}`);
-            // Get agent models from orchestrator (if available)
+            // Get agent models and token usage from orchestrator (if available)
             let agentModels = {};
+            let tokenUsageLines = null;
             try {
               const orchestrator = OrchestratorModule.getInstance();
               const status = orchestrator.getStatus(clusterId);
               for (const a of status.agents) {
                 agentModels[a.id] = a.model;
               }
+              // Get token usage from message bus
+              const cluster = orchestrator.getCluster(clusterId);
+              if (cluster?.messageBus) {
+                const tokensByRole = cluster.messageBus.getTokensByRole(clusterId);
+                tokenUsageLines = formatTokenUsage(tokensByRole);
+              }
             } catch {
-              /* orchestrator not running - models unavailable */
+              /* orchestrator not running - models/tokens unavailable */
+            }
+            // Display token usage if available
+            if (tokenUsageLines) {
+              for (const line of tokenUsageLines) {
+                console.log(`    ${line}`);
+              }
             }
             for (const agent of agents) {
               const modelLabel = agentModels[agent] ? chalk.dim(` [${agentModels[agent]}]`) : '';
@@ -3087,6 +3139,55 @@ function formatTaskSummary(issueOpened, maxLen = 35) {
   return firstLine.slice(0, maxLen) + (firstLine.length > maxLen ? '...' : '');
 }
 
+// Format token usage for display
+function formatTokenUsage(tokensByRole) {
+  if (!tokensByRole || !tokensByRole._total || tokensByRole._total.count === 0) {
+    return null;
+  }
+
+  const total = tokensByRole._total;
+  const lines = [];
+
+  // Format numbers with commas
+  const fmt = (n) => n.toLocaleString();
+
+  // Total line
+  const inputTokens = total.inputTokens || 0;
+  const outputTokens = total.outputTokens || 0;
+  const totalTokens = inputTokens + outputTokens;
+  const cost = total.totalCostUsd || 0;
+
+  lines.push(
+    chalk.dim('Tokens: ') +
+      chalk.cyan(fmt(totalTokens)) +
+      chalk.dim(' (') +
+      chalk.green(fmt(inputTokens)) +
+      chalk.dim(' in / ') +
+      chalk.yellow(fmt(outputTokens)) +
+      chalk.dim(' out)')
+  );
+
+  // Cost line (if available)
+  if (cost > 0) {
+    lines.push(chalk.dim('Cost: ') + chalk.green('$' + cost.toFixed(4)));
+  }
+
+  // Per-role breakdown (compact)
+  const roles = Object.keys(tokensByRole).filter((r) => r !== '_total');
+  if (roles.length > 1) {
+    const roleStats = roles
+      .map((role) => {
+        const r = tokensByRole[role];
+        const roleTotal = (r.inputTokens || 0) + (r.outputTokens || 0);
+        return `${role}: ${fmt(roleTotal)}`;
+      })
+      .join(chalk.dim(' | '));
+    lines.push(chalk.dim('By role: ') + roleStats);
+  }
+
+  return lines;
+}
+
 // Set terminal title (works in most terminals)
 function setTerminalTitle(title) {
   // ESC ] 0 ; <title> BEL

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

@@ -102,12 +102,27 @@
                 }
               }
             }
+          },
+          "acceptanceCriteria": {
+            "type": "array",
+            "description": "EXPLICIT, TESTABLE acceptance criteria. Each must be verifiable. NO VAGUE BULLSHIT.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": { "type": "string", "description": "AC1, AC2, etc." },
+                "criterion": { "type": "string", "description": "MUST be testable - if you can't verify it, rewrite it" },
+                "verification": { "type": "string", "description": "EXACT steps to verify (command, URL, test name)" },
+                "priority": { "type": "string", "enum": ["MUST", "SHOULD", "NICE"], "description": "MUST = blocks completion" }
+              },
+              "required": ["id", "criterion", "verification", "priority"]
+            },
+            "minItems": 3
           }
         },
-        "required": ["plan", "summary", "filesAffected"]
+        "required": ["plan", "summary", "filesAffected", "acceptanceCriteria"]
       },
       "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 planning agent for a {{complexity}} {{task_type}} task.\n\n## Your Job\nCreate a comprehensive implementation plan.\n\n## Planning Process\n1. Analyze requirements thoroughly\n2. Explore codebase to understand architecture\n3. Identify ALL files that need changes\n4. Break down into concrete, actionable steps\n5. Consider cross-component dependencies\n6. Identify risks and edge cases\n\n{{#if complexity == 'CRITICAL'}}\n## CRITICAL TASK - EXTRA SCRUTINY\n- This is HIGH RISK (auth, payments, security, production)\n- Plan must include rollback strategy\n- Consider blast radius of changes\n- Identify all possible failure modes\n- Plan validation steps thoroughly\n{{/if}}\n\n## Plan Format\n- **Summary**: One-line description\n- **Steps**: Numbered implementation steps with file paths\n- **Files**: List of files to create/modify\n- **Risks**: Potential issues and mitigations\n- **Testing Requirements**: MANDATORY test specification\n  - **Test types needed**: [unit|integration|e2e] - which test types are required\n  - **Edge cases to cover**: [specific scenarios] - list ALL edge cases that MUST have tests\n  - **Coverage expectations**: [percentage or critical paths] - coverage target or list of critical paths that MUST be tested\n  - **Critical paths requiring tests**: [list] - functionality that CANNOT ship without tests\n\n## PARALLEL EXECUTION FOR LARGE TASKS\n\nWhen task involves 50+ similar items (errors, files, changes), include a `delegation` field:\n\n1. ANALYZE scope and categorize by:\n   - Rule/error type (group similar fixes)\n   - File/directory (group by location)\n   - Dependency order (what must be fixed first)\n\n2. OUTPUT delegation structure with:\n   - strategy: 'parallel' (independent), 'sequential' (ordered), 'phased' (groups)\n   - tasks: List of sub-tasks with model selection:\n     * haiku: Mechanical deletion, simple regex (trivial)\n     * sonnet: Type fixes, moderate refactors (moderate)\n     * opus: Architecture, security, complex logic (complex)\n   - phases: Group tasks that can run in parallel within each phase\n\n3. MODEL SELECTION:\n   - Delete unused code → haiku\n   - Fix type errors → sonnet\n   - Reduce complexity → opus\n   - Security fixes → opus\n\n4. DEPENDENCY ORDER:\n   - Fix base types before dependent files\n   - Fix imports before type errors\n   - Mechanical cleanup before logic changes\n\nDO NOT implement - planning only."
+        "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 planning agent for a {{complexity}} {{task_type}} task.\n\n## Your Job\nCreate a comprehensive implementation plan.\n\n## Planning Process\n1. Analyze requirements thoroughly\n2. Explore codebase to understand architecture\n3. Identify ALL files that need changes\n4. Break down into concrete, actionable steps\n5. Consider cross-component dependencies\n6. Identify risks and edge cases\n\n{{#if complexity == 'CRITICAL'}}\n## CRITICAL TASK - EXTRA SCRUTINY\n- This is HIGH RISK (auth, payments, security, production)\n- Plan must include rollback strategy\n- Consider blast radius of changes\n- Identify all possible failure modes\n- Plan validation steps thoroughly\n{{/if}}\n\n## Plan Format\n- **Summary**: One-line description\n- **Steps**: Numbered implementation steps with file paths\n- **Files**: List of files to create/modify\n- **Risks**: Potential issues and mitigations\n- **Testing Requirements**: MANDATORY test specification\n  - **Test types needed**: [unit|integration|e2e] - which test types are required\n  - **Edge cases to cover**: [specific scenarios] - list ALL edge cases that MUST have tests\n  - **Coverage expectations**: [percentage or critical paths] - coverage target or list of critical paths that MUST be tested\n  - **Critical paths requiring tests**: [list] - functionality that CANNOT ship without tests\n\n## 🔴 ACCEPTANCE CRITERIA (REQUIRED - minItems: 3)\n\nYou MUST output explicit, testable acceptance criteria. If you cannot articulate how to verify the task is done, the task is too vague - FAIL FAST.\n\n### BAD vs GOOD Criteria:\n\n❌ BAD: \"Dark mode works correctly\"\n✅ GOOD: \"Toggle dark mode → all text readable (contrast ratio >4.5:1), background #1a1a1a\"\n\n❌ BAD: \"API handles errors\"\n✅ GOOD: \"POST /api/users with invalid email → returns 400 + {error: 'Invalid email format'}\"\n\n❌ BAD: \"Tests pass\"\n✅ GOOD: \"npm run test:unit shows 100% pass, coverage >80% on new files\"\n\n❌ BAD: \"Feature is implemented\"\n✅ GOOD: \"User clicks 'Export' → CSV file downloads with columns: id, name, email, created_at\"\n\n❌ BAD: \"Performance is acceptable\"\n✅ GOOD: \"API response time <200ms for 1000 concurrent users (verified via k6 load test)\"\n\n### Criteria Format:\nEach criterion MUST have:\n- **id**: AC1, AC2, AC3, etc.\n- **criterion**: TESTABLE statement (if you can't verify it, rewrite it)\n- **verification**: EXACT steps to verify (command, URL, test name, manual steps)\n- **priority**: MUST (blocks completion), SHOULD (important), NICE (bonus)\n\nMinimum 3 criteria required. At least 1 MUST be priority=MUST.\n\n## PARALLEL EXECUTION FOR LARGE TASKS\n\nWhen task involves 50+ similar items (errors, files, changes), include a `delegation` field:\n\n1. ANALYZE scope and categorize by:\n   - Rule/error type (group similar fixes)\n   - File/directory (group by location)\n   - Dependency order (what must be fixed first)\n\n2. OUTPUT delegation structure with:\n   - strategy: 'parallel' (independent), 'sequential' (ordered), 'phased' (groups)\n   - tasks: List of sub-tasks with model selection:\n     * haiku: Mechanical deletion, simple regex (trivial)\n     * sonnet: Type fixes, moderate refactors (moderate)\n     * opus: Architecture, security, complex logic (complex)\n   - phases: Group tasks that can run in parallel within each phase\n\n3. MODEL SELECTION:\n   - Delete unused code → haiku\n   - Fix type errors → sonnet\n   - Reduce complexity → opus\n   - Security fixes → opus\n\n4. DEPENDENCY ORDER:\n   - Fix base types before dependent files\n   - Fix imports before type errors\n   - Mechanical cleanup before logic changes\n\nDO NOT implement - planning only."
       },
       "contextStrategy": {
         "sources": [{ "topic": "ISSUE_OPENED", "limit": 1 }],
@@ -126,7 +141,8 @@
                 "summary": "{{result.summary}}",
                 "filesAffected": "{{result.filesAffected}}",
                 "risks": "{{result.risks}}",
-                "delegation": "{{result.delegation}}"
+                "delegation": "{{result.delegation}}",
+                "acceptanceCriteria": "{{result.acceptanceCriteria}}"
               }
             }
           }
@@ -138,8 +154,8 @@
       "role": "implementation",
       "model": "{{worker_model}}",
       "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}}"
+        "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## 🔴 ACCEPTANCE CRITERIA CHECKLIST\n\nBefore publishing IMPLEMENTATION_READY, verify EVERY acceptance criterion from PLAN_READY:\n\n1. **Parse acceptanceCriteria** from PLAN_READY data\n2. **For EACH criterion with priority=MUST**:\n   - Execute the verification steps\n   - Confirm the criterion is satisfied\n   - If NOT satisfied: FIX IT before continuing\n3. **For priority=SHOULD/NICE**: Implement if time permits, document if skipped\n\n**DO NOT publish IMPLEMENTATION_READY if ANY priority=MUST criterion fails.**\n\nValidators will check each criterion explicitly. Missing MUST criteria = instant rejection.\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## 🔴 CHECK ACCEPTANCE CRITERIA AGAIN\n\nValidators check against the acceptance criteria from PLAN_READY. Before resubmitting:\n1. Re-read EACH criterion (especially priority=MUST ones)\n2. Check if rejection was due to failed criteria\n3. Verify EVERY criterion passes before publishing IMPLEMENTATION_READY\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}}"
       },
       "contextStrategy": {
         "sources": [
@@ -188,12 +204,26 @@
         "properties": {
           "approved": { "type": "boolean" },
           "summary": { "type": "string" },
-          "errors": { "type": "array", "items": { "type": "string" } }
+          "errors": { "type": "array", "items": { "type": "string" } },
+          "criteriaResults": {
+            "type": "array",
+            "description": "PASS/FAIL status for each acceptance criterion from PLAN_READY",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": { "type": "string", "description": "AC1, AC2, etc. from plan" },
+                "status": { "type": "string", "enum": ["PASS", "FAIL", "SKIPPED"] },
+                "evidence": { "type": "string", "description": "How you verified (command output, observation)" },
+                "notes": { "type": "string", "description": "Why it failed or additional context" }
+              },
+              "required": ["id", "status"]
+            }
+          }
         },
-        "required": ["approved", "summary"]
+        "required": ["approved", "summary", "criteriaResults"]
       },
       "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 requirements validator for a {{complexity}} {{task_type}} task.\n\n## Your Role\nVerify implementation meets requirements. Be thorough. Hold a high bar.\n\n## Validation Checklist - ALL must pass:\n1. Does implementation address ALL requirements from ISSUE_OPENED?\n2. Are edge cases handled? (empty, null, boundaries, error states)\n3. Is error handling present for failure paths?\n4. Are types strict? (no any, no ts-ignore)\n5. Is input validation present at boundaries?\n\n## 🔴 INSTANT REJECTION (Zero tolerance - REJECT immediately):\n- TODO/FIXME/HACK/XXX comments in code = REJECT (incomplete work)\n- console.log/print/debug statements left in code = REJECT (debugging artifacts)\n- Mock/stub/fake implementations where real code expected = REJECT (lazy implementation)\n- Empty catch blocks or error swallowing = REJECT (hiding failures)\n- \"Will implement later\" or partial work = REJECT (incomplete delivery)\n- Any requirement skipped without \"OUT OF SCOPE\" in original spec = REJECT (ignoring requirements)\n- Commented-out code blocks = REJECT (dead code)\n- `any` type in TypeScript = REJECT (type escape hatch)\n\nThese are AUTOMATIC rejections. No exceptions. No \"it's mostly done\". The code is either COMPLETE or it's REJECTED.\n\n## BLOCKING Issues (must reject):\n- Missing core functionality\n- Missing error handling for common failures\n- Hardcoded values that should be configurable\n- Crashes on empty/null input\n- Types not strict\n\n## NON-BLOCKING Issues (note in summary, don't reject alone):\n- Minor style preferences\n- Could be slightly DRYer\n- Rare edge cases\n\n## Output\n- approved: true if all BLOCKING criteria pass\n- summary: Assessment with blocking and non-blocking issues noted\n- errors: List of BLOCKING issues only"
+        "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 requirements validator for a {{complexity}} {{task_type}} task.\n\n## Your Role\nVerify implementation meets requirements. Be thorough. Hold a high bar.\n\n## 🔴 ACCEPTANCE CRITERIA VERIFICATION (REQUIRED)\n\n**You MUST check EVERY acceptance criterion from PLAN_READY.**\n\n### Verification Process:\n1. **Parse acceptanceCriteria** from PLAN_READY data\n2. **For EACH criterion**:\n   a. Execute the verification steps specified in the criterion\n   b. Record PASS or FAIL with evidence (command output, observation)\n   c. If FAIL: Add to errors array if priority=MUST\n3. **Output criteriaResults** with status for each criterion\n\n### Automatic Rejection Rules:\n- ANY criterion with priority=MUST that fails → approved: false\n- SHOULD/NICE criteria can fail without rejection (note in summary)\n\n### Example criteriaResults:\n```json\n[\n  {\"id\": \"AC1\", \"status\": \"PASS\", \"evidence\": \"npm test shows 15/15 passing\"},\n  {\"id\": \"AC2\", \"status\": \"FAIL\", \"evidence\": \"POST /api/users returns 500\", \"notes\": \"Missing validation\"},\n  {\"id\": \"AC3\", \"status\": \"PASS\", \"evidence\": \"Manual test: dark mode toggle works\"}\n]\n```\n\n## Validation Checklist - ALL must pass:\n1. Does implementation address ALL requirements from ISSUE_OPENED?\n2. Are edge cases handled? (empty, null, boundaries, error states)\n3. Is error handling present for failure paths?\n4. Are types strict? (no any, no ts-ignore)\n5. Is input validation present at boundaries?\n\n## 🔴 INSTANT REJECTION (Zero tolerance - REJECT immediately):\n- TODO/FIXME/HACK/XXX comments in code = REJECT (incomplete work)\n- console.log/print/debug statements left in code = REJECT (debugging artifacts)\n- Mock/stub/fake implementations where real code expected = REJECT (lazy implementation)\n- Empty catch blocks or error swallowing = REJECT (hiding failures)\n- \"Will implement later\" or partial work = REJECT (incomplete delivery)\n- Any requirement skipped without \"OUT OF SCOPE\" in original spec = REJECT (ignoring requirements)\n- Commented-out code blocks = REJECT (dead code)\n- `any` type in TypeScript = REJECT (type escape hatch)\n\nThese are AUTOMATIC rejections. No exceptions. No \"it's mostly done\". The code is either COMPLETE or it's REJECTED.\n\n## BLOCKING Issues (must reject):\n- Missing core functionality\n- Missing error handling for common failures\n- Hardcoded values that should be configurable\n- Crashes on empty/null input\n- Types not strict\n- **ANY priority=MUST criterion that fails**\n\n## NON-BLOCKING Issues (note in summary, don't reject alone):\n- Minor style preferences\n- Could be slightly DRYer\n- Rare edge cases\n- priority=SHOULD/NICE criteria that fail\n\n## Output\n- approved: true if all BLOCKING criteria pass AND all priority=MUST acceptance criteria pass\n- summary: Assessment with blocking and non-blocking issues noted\n- errors: List of BLOCKING issues only\n- criteriaResults: PASS/FAIL for EACH acceptance criterion"
       },
       "contextStrategy": {
         "sources": [
@@ -218,7 +248,8 @@
               "text": "{{result.summary}}",
               "data": {
                 "approved": "{{result.approved}}",
-                "errors": "{{result.errors}}"
+                "errors": "{{result.errors}}",
+                "criteriaResults": "{{result.criteriaResults}}"
               }
             }
           }

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.4",
+  "version": "1.3.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,31 @@ 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
+      // CRITICAL: Include taskId for causal linking - allows consumers to group
+      // messages by task regardless of interleaved timing from async hooks
+      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,
+              taskId: agent.currentTaskId, // Causal linking for message ordering
+              ...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/ledger.js

@@ -116,6 +116,84 @@ class Ledger extends EventEmitter {
     }
   }
 
+  /**
+   * Append multiple messages atomically using a transaction
+   * All messages get contiguous timestamps and are committed together.
+   * If any insert fails, the entire batch is rolled back.
+   *
+   * Use this for task completion messages to prevent interleaving:
+   * - TOKEN_USAGE, TASK_COMPLETED, and hook messages published atomically
+   * - Other agents' messages cannot appear between them
+   *
+   * @param {Array<Object>} messages - Array of message objects
+   * @returns {Array<Object>} Array of appended messages with generated IDs
+   */
+  batchAppend(messages) {
+    if (!Array.isArray(messages) || messages.length === 0) {
+      return [];
+    }
+
+    // Create transaction function - all inserts happen atomically
+    const insertMany = this.db.transaction((msgs) => {
+      const results = [];
+      const baseTimestamp = Date.now();
+
+      for (let i = 0; i < msgs.length; i++) {
+        const message = msgs[i];
+        const id = message.id || `msg_${crypto.randomBytes(16).toString('hex')}`;
+        // Use incrementing timestamps to preserve order within batch
+        const timestamp = message.timestamp || (baseTimestamp + i);
+
+        const record = {
+          id,
+          timestamp,
+          topic: message.topic,
+          sender: message.sender,
+          receiver: message.receiver || 'broadcast',
+          content_text: message.content?.text || null,
+          content_data: message.content?.data ? JSON.stringify(message.content.data) : null,
+          metadata: message.metadata ? JSON.stringify(message.metadata) : null,
+          cluster_id: message.cluster_id,
+        };
+
+        this.stmts.insert.run(
+          record.id,
+          record.timestamp,
+          record.topic,
+          record.sender,
+          record.receiver,
+          record.content_text,
+          record.content_data,
+          record.metadata,
+          record.cluster_id
+        );
+
+        results.push(this._deserializeMessage(record));
+      }
+
+      return results;
+    });
+
+    try {
+      // Execute transaction (atomic - all or nothing)
+      const appendedMessages = insertMany(messages);
+
+      // Invalidate cache
+      this.cache.clear();
+
+      // Emit events for subscriptions AFTER transaction commits
+      // This ensures listeners see consistent state
+      for (const fullMessage of appendedMessages) {
+        this.emit('message', fullMessage);
+        this.emit(`topic:${fullMessage.topic}`, fullMessage);
+      }
+
+      return appendedMessages;
+    } catch (error) {
+      throw new Error(`Failed to batch append messages: ${error.message}`);
+    }
+  }
+
   /**
    * Query messages with filters
    * @param {Object} criteria - Query criteria
@@ -269,6 +347,77 @@ class Ledger extends EventEmitter {
     return rows.map((row) => this._deserializeMessage(row));
   }
 
+  /**
+   * Get aggregated token usage by agent role
+   * Queries TOKEN_USAGE messages and sums tokens per role
+   * @param {String} cluster_id - Cluster ID
+   * @returns {Object} Token usage aggregated by role
+   *   Example: {
+   *     implementation: { inputTokens: 5000, outputTokens: 2000, totalCostUsd: 0.05, count: 3 },
+   *     validator: { inputTokens: 3000, outputTokens: 1500, totalCostUsd: 0.03, count: 2 },
+   *     _total: { inputTokens: 8000, outputTokens: 3500, totalCostUsd: 0.08, count: 5 }
+   *   }
+   */
+  getTokensByRole(cluster_id) {
+    if (!cluster_id) {
+      throw new Error('cluster_id is required for getTokensByRole');
+    }
+
+    // Query all TOKEN_USAGE messages for this cluster
+    const sql = `SELECT * FROM messages WHERE cluster_id = ? AND topic = 'TOKEN_USAGE' ORDER BY timestamp ASC`;
+    const stmt = this.db.prepare(sql);
+    const rows = stmt.all(cluster_id);
+
+    const byRole = {};
+    const total = {
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadInputTokens: 0,
+      cacheCreationInputTokens: 0,
+      totalCostUsd: 0,
+      count: 0,
+    };
+
+    for (const row of rows) {
+      const message = this._deserializeMessage(row);
+      const data = message.content?.data || {};
+      const role = data.role || 'unknown';
+
+      // Initialize role bucket if needed
+      if (!byRole[role]) {
+        byRole[role] = {
+          inputTokens: 0,
+          outputTokens: 0,
+          cacheReadInputTokens: 0,
+          cacheCreationInputTokens: 0,
+          totalCostUsd: 0,
+          count: 0,
+        };
+      }
+
+      // Aggregate tokens for this role
+      byRole[role].inputTokens += data.inputTokens || 0;
+      byRole[role].outputTokens += data.outputTokens || 0;
+      byRole[role].cacheReadInputTokens += data.cacheReadInputTokens || 0;
+      byRole[role].cacheCreationInputTokens += data.cacheCreationInputTokens || 0;
+      byRole[role].totalCostUsd += data.totalCostUsd || 0;
+      byRole[role].count += 1;
+
+      // Aggregate totals
+      total.inputTokens += data.inputTokens || 0;
+      total.outputTokens += data.outputTokens || 0;
+      total.cacheReadInputTokens += data.cacheReadInputTokens || 0;
+      total.cacheCreationInputTokens += data.cacheCreationInputTokens || 0;
+      total.totalCostUsd += data.totalCostUsd || 0;
+      total.count += 1;
+    }
+
+    // Add total as special _total key
+    byRole._total = total;
+
+    return byRole;
+  }
+
   /**
    * Subscribe to new messages
    * @param {Function} callback - Called with each new message

package/src/message-bus.js

@@ -126,6 +126,48 @@ class MessageBus extends EventEmitter {
     return this.ledger.getAll(cluster_id);
   }
 
+  /**
+   * Publish multiple messages atomically
+   * All messages are committed in a single transaction with contiguous timestamps.
+   * Use this for task completion to prevent message interleaving between agents.
+   *
+   * @param {Array<Object>} messages - Array of messages to publish
+   * @returns {Array<Object>} Published messages with IDs
+   */
+  batchPublish(messages) {
+    // Validate all messages
+    for (const message of messages) {
+      if (!message.cluster_id) {
+        throw new Error('cluster_id is required for all messages');
+      }
+      if (!message.topic) {
+        throw new Error('topic is required for all messages');
+      }
+      if (!message.sender) {
+        throw new Error('sender is required for all messages');
+      }
+    }
+
+    // Delegate to ledger's atomic batchAppend
+    const published = this.ledger.batchAppend(messages);
+
+    // Emit to topic-specific listeners for each message
+    for (const msg of published) {
+      this.emit(`topic:${msg.topic}`, msg);
+    }
+
+    return published;
+  }
+
+  /**
+   * Get aggregated token usage by role (passthrough to ledger)
+   * @param {String} cluster_id - Cluster ID
+   * @returns {Object} Token usage aggregated by role with _total key
+   */
+  getTokensByRole(cluster_id) {
+    return this.ledger.getTokensByRole(cluster_id);
+  }
+
   /**
    * Register a WebSocket client for broadcasts
    * @param {WebSocket} ws - WebSocket connection

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();
   }