@covibes/zeroshot 1.3.0 → 1.5.0

package/src/status-footer.js

@@ -86,6 +86,7 @@ class StatusFooter {
     this.clusterId = null;
     this.clusterState = 'initializing';
     this.startTime = Date.now();
+    this.messageBus = null; // MessageBus for token usage tracking
 
     // Robust resize handling state
     this.isRendering = false; // Render lock - prevents concurrent renders
@@ -95,6 +96,11 @@ class StatusFooter {
     this.minRows = 8; // Minimum rows for footer display (graceful degradation)
     this.hidden = false; // True when terminal too small for footer
 
+    // Output queue - serializes all stdout to prevent cursor corruption
+    // When scroll region is active, console.log() can corrupt cursor position
+    // All output must go through print() to coordinate with render cycles
+    this.printQueue = [];
+
     // Debounced resize handler (100ms) - prevents rapid-fire redraws
     this._debouncedResize = debounce(() => this._handleResize(), 100);
   }
@@ -107,6 +113,38 @@ class StatusFooter {
     return process.stdout.isTTY === true;
   }
 
+  /**
+   * Print text to stdout, coordinating with the render cycle.
+   * When a render is in progress, queues output to prevent cursor corruption.
+   * When no render is active, writes immediately.
+   *
+   * MUST be used instead of console.log() when status footer is active.
+   * @param {string} text - Text to print (newline will be added)
+   */
+  print(text) {
+    if (this.isRendering) {
+      // Queue for later - render() will flush after restoring cursor
+      this.printQueue.push(text);
+    } else {
+      // Write immediately - no render in progress
+      process.stdout.write(text + '\n');
+    }
+  }
+
+  /**
+   * Flush queued output to stdout.
+   * Called after render() restores cursor to ensure proper positioning.
+   * @private
+   */
+  _flushPrintQueue() {
+    if (this.printQueue.length === 0) return;
+
+    // Write all queued output
+    const output = this.printQueue.map(text => text + '\n').join('');
+    this.printQueue = [];
+    process.stdout.write(output);
+  }
+
   /**
    * Get terminal dimensions
    * @returns {{ rows: number, cols: number }}
@@ -137,23 +175,60 @@ class StatusFooter {
   }
 
   /**
-   * Clear all footer lines (uses last known height for safety)
+   * Generate move cursor ANSI sequence (returns string, doesn't write)
+   * Used for atomic buffered writes to prevent interleaving
+   * @param {number} row - 1-based row
+   * @param {number} col - 1-based column
+   * @returns {string} ANSI escape sequence
    * @private
    */
-  _clearFooterArea() {
+  _moveToStr(row, col) {
+    return `${CSI}${row};${col}H`;
+  }
+
+  /**
+   * Generate clear line ANSI sequence (returns string, doesn't write)
+   * Used for atomic buffered writes to prevent interleaving
+   * @param {number} row - 1-based row number
+   * @returns {string} ANSI escape sequence
+   * @private
+   */
+  _clearLineStr(row) {
+    return `${CSI}${row};1H${CLEAR_LINE}`;
+  }
+
+  /**
+   * Generate ANSI sequences to clear all footer lines (returns string)
+   * Used for atomic buffered writes to prevent interleaving
+   * @returns {string} ANSI escape sequences
+   * @private
+   */
+  _clearFooterAreaStr() {
     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);
 
+    let buffer = '';
     for (let row = startRow; row <= rows; row++) {
-      this._clearLine(row);
+      buffer += this._clearLineStr(row);
     }
+    return buffer;
+  }
+
+  /**
+   * Clear all footer lines (uses last known height for safety)
+   * Uses single atomic write to prevent interleaving with other processes
+   * @private
+   */
+  _clearFooterArea() {
+    process.stdout.write(this._clearFooterAreaStr());
   }
 
   /**
    * Set up scroll region to reserve space for footer
    * ROBUST: Clears footer area first, resets to full screen, then sets new region
+   * Uses single atomic write to prevent interleaving with other processes
    */
   setupScrollRegion() {
     if (!this.isTTY()) return;
@@ -178,39 +253,53 @@ class StatusFooter {
 
     const scrollEnd = rows - this.footerHeight;
 
-    // CRITICAL: Save cursor before any manipulation
-    process.stdout.write(SAVE_CURSOR);
-    process.stdout.write(HIDE_CURSOR);
+    // BUILD ENTIRE OUTPUT INTO SINGLE BUFFER for atomic write
+    let buffer = '';
+
+    // Step 1: Save cursor before any manipulation
+    buffer += SAVE_CURSOR;
+    buffer += HIDE_CURSOR;
 
-    // Step 1: Reset scroll region to full screen first (prevents artifacts)
-    process.stdout.write(`${CSI}1;${rows}r`);
+    // Step 2: Reset scroll region to full screen first (prevents artifacts)
+    buffer += `${CSI}1;${rows}r`;
 
-    // Step 2: Clear footer area completely (prevents ghosting)
-    this._clearFooterArea();
+    // Step 3: Clear footer area completely (prevents ghosting)
+    buffer += this._clearFooterAreaStr();
 
-    // Step 3: Set new scroll region (lines 1 to scrollEnd)
-    process.stdout.write(`${CSI}1;${scrollEnd}r`);
+    // Step 4: Set new scroll region (lines 1 to scrollEnd)
+    buffer += `${CSI}1;${scrollEnd}r`;
 
-    // Step 4: Move cursor to bottom of scroll region (safe position)
-    process.stdout.write(`${CSI}${scrollEnd};1H`);
+    // Step 5: Move cursor to bottom of scroll region (safe position)
+    buffer += this._moveToStr(scrollEnd, 1);
 
-    // Restore cursor and show it
-    process.stdout.write(RESTORE_CURSOR);
-    process.stdout.write(SHOW_CURSOR);
+    // Step 6: Restore cursor and show it
+    buffer += RESTORE_CURSOR;
+    buffer += SHOW_CURSOR;
+
+    // SINGLE ATOMIC WRITE - prevents interleaving
+    process.stdout.write(buffer);
 
     this.scrollRegionSet = true;
     this.lastKnownRows = rows;
     this.lastKnownCols = cols;
   }
 
+  /**
+   * Generate reset scroll region string (returns string, doesn't write)
+   * @private
+   */
+  _resetScrollRegionStr() {
+    const { rows } = this.getTerminalSize();
+    return `${CSI}1;${rows}r`;
+  }
+
   /**
    * Reset scroll region to full terminal
    */
   resetScrollRegion() {
     if (!this.isTTY()) return;
 
-    const { rows } = this.getTerminalSize();
-    process.stdout.write(`${CSI}1;${rows}r`);
+    process.stdout.write(this._resetScrollRegionStr());
     this.scrollRegionSet = false;
   }
 
@@ -251,6 +340,14 @@ class StatusFooter {
     this.clusterId = clusterId;
   }
 
+  /**
+   * Set message bus for token usage tracking
+   * @param {object} messageBus - MessageBus instance with getTokensByRole()
+   */
+  setMessageBus(messageBus) {
+    this.messageBus = messageBus;
+  }
+
   /**
    * Update cluster state
    * @param {string} state
@@ -401,35 +498,53 @@ class StatusFooter {
       const agentRows = this.buildAgentRows(executingAgents, cols);
       const summaryLine = this.buildSummaryLine(cols);
 
-      // Save cursor, render footer, restore cursor
-      process.stdout.write(SAVE_CURSOR);
-      process.stdout.write(HIDE_CURSOR);
+      // BUILD ENTIRE OUTPUT INTO SINGLE BUFFER for atomic write
+      // This prevents interleaving with other processes writing to stdout
+      let buffer = '';
+      buffer += SAVE_CURSOR;
+      buffer += HIDE_CURSOR;
 
       // Render from top of footer area
       let currentRow = rows - this.footerHeight + 1;
 
       // Header line
-      this.moveTo(currentRow++, 1);
-      process.stdout.write(CLEAR_LINE);
-      process.stdout.write(`${COLORS.bgBlack}${headerLine}${COLORS.reset}`);
+      buffer += this._moveToStr(currentRow++, 1);
+      buffer += CLEAR_LINE;
+      buffer += `${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}`);
+        buffer += this._moveToStr(currentRow++, 1);
+        buffer += CLEAR_LINE;
+        buffer += `${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}`);
+      buffer += this._moveToStr(currentRow, 1);
+      buffer += CLEAR_LINE;
+      buffer += `${COLORS.bgBlack}${summaryLine}${COLORS.reset}`;
+
+      buffer += RESTORE_CURSOR;
+      buffer += SHOW_CURSOR;
 
-      process.stdout.write(RESTORE_CURSOR);
-      process.stdout.write(SHOW_CURSOR);
+      // SINGLE ATOMIC WRITE - prevents interleaving
+      process.stdout.write(buffer);
     } finally {
       this.isRendering = false;
 
+      // CRITICAL: Position cursor at bottom of scroll region before flushing
+      // Without this, output goes below footer if cursor was restored outside scroll region
+      // (RESTORE_CURSOR at line 527 may restore to row outside the scrollable area)
+      if (this.scrollRegionSet) {
+        const { rows } = this.getTerminalSize();
+        const scrollEnd = rows - this.footerHeight;
+        process.stdout.write(this._moveToStr(scrollEnd, 1));
+      }
+
+      // Flush any output that was queued during render
+      // Must happen BEFORE pending resize to preserve output order
+      this._flushPrintQueue();
+
       // Process pending resize if one was queued during render
       if (this.pendingResize) {
         this.pendingResize = false;
@@ -554,6 +669,21 @@ class StatusFooter {
     const total = this.agents.size;
     parts.push(` ${COLORS.gray}│${COLORS.reset} ${COLORS.green}${executing}/${total}${COLORS.reset} active`);
 
+    // Token cost (from message bus)
+    if (this.messageBus && this.clusterId) {
+      try {
+        const tokensByRole = this.messageBus.getTokensByRole(this.clusterId);
+        const totalCost = tokensByRole?._total?.totalCostUsd || 0;
+        if (totalCost > 0) {
+          // Format: $0.05 or $1.23 or $12.34
+          const costStr = totalCost < 0.01 ? '<$0.01' : `$${totalCost.toFixed(2)}`;
+          parts.push(` ${COLORS.gray}│${COLORS.reset} ${COLORS.yellow}${costStr}${COLORS.reset}`);
+        }
+      } catch {
+        // Ignore errors - token tracking is optional
+      }
+    }
+
     // Aggregate metrics
     let totalCpu = 0;
     let totalMem = 0;
@@ -621,7 +751,9 @@ class StatusFooter {
     process.stdout.on('resize', this._debouncedResize);
 
     // Start refresh interval
+    // Guard: Skip if previous render still running (prevents overlapping renders)
     this.intervalId = setInterval(() => {
+      if (this.isRendering) return;
       this.render();
     }, this.refreshInterval);
 
@@ -642,17 +774,27 @@ class StatusFooter {
     process.stdout.removeListener('resize', this._debouncedResize);
 
     if (this.isTTY() && !this.hidden) {
-      // Reset scroll region
-      this.resetScrollRegion();
+      // BUILD SINGLE BUFFER for atomic shutdown write
+      // Prevents interleaving with agent output during cleanup
+      let buffer = '';
 
-      // Clear all footer lines
-      this._clearFooterArea();
+      // CRITICAL: Clear footer area BEFORE resetting scroll region
+      // While scroll region is active, footer area contains only status bar content
+      // After reset, those lines may contain scrolled output (which we DON'T want to clear)
+      buffer += this._clearFooterAreaStr();
 
-      // Move cursor to safe position
+      // Now reset scroll region (full terminal is scrollable again)
+      buffer += this._resetScrollRegionStr();
+      this.scrollRegionSet = false;
+
+      // Move cursor to safe position and show cursor
       const { rows } = this.getTerminalSize();
       const startRow = rows - this.footerHeight + 1;
-      this.moveTo(startRow, 1);
-      process.stdout.write(SHOW_CURSOR);
+      buffer += this._moveToStr(startRow, 1);
+      buffer += SHOW_CURSOR;
+
+      // SINGLE ATOMIC WRITE
+      process.stdout.write(buffer);
     }
   }
 
@@ -662,8 +804,12 @@ class StatusFooter {
   hide() {
     if (!this.isTTY()) return;
 
-    this.resetScrollRegion();
-    this._clearFooterArea();
+    // Single atomic write for hide operation
+    // CRITICAL: Clear footer BEFORE resetting scroll region (same reason as stop())
+    let buffer = this._clearFooterAreaStr();
+    buffer += this._resetScrollRegionStr();
+    this.scrollRegionSet = false;
+    process.stdout.write(buffer);
   }
 
   /**

package/src/template-resolver.js

@@ -43,8 +43,11 @@ class TemplateResolver {
     // Validate required params
     this._validateParams(template, params);
 
+    // Apply defaults for missing params (e.g., timeout: 0)
+    const paramsWithDefaults = this._applyDefaults(template, params);
+
     // Deep clone and resolve
-    const resolved = this._resolveObject(JSON.parse(JSON.stringify(template)), params);
+    const resolved = this._resolveObject(JSON.parse(JSON.stringify(template)), paramsWithDefaults);
 
     // Filter out conditional agents that don't meet their condition
     if (resolved.agents) {
@@ -86,6 +89,25 @@ class TemplateResolver {
     }
   }
 
+  /**
+   * Apply template defaults for any missing params
+   * @private
+   * @param {any} template
+   * @param {any} params
+   * @returns {any} params with defaults applied
+   */
+  _applyDefaults(template, params) {
+    if (!template.params) return params;
+
+    const result = { ...params };
+    for (const [name, schema] of Object.entries(template.params)) {
+      if (result[name] === undefined && schema.default !== undefined) {
+        result[name] = schema.default;
+      }
+    }
+    return result;
+  }
+
   /**
    * Recursively resolve placeholders in an object
    * @private