groove-dev 0.26.38 → 0.27.0

package/packages/daemon/src/rotator.js

@@ -2,18 +2,79 @@
 // FSL-1.1-Apache-2.0 — see LICENSE
 
 import { EventEmitter } from 'events';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
 
-const DEFAULT_THRESHOLD = 0.75; // 75% context usage triggers rotation
-const CHECK_INTERVAL = 15_000; // Check every 15 seconds
+const DEFAULT_THRESHOLD = 0.75;
+const CHECK_INTERVAL = 15_000;
+const QUALITY_THRESHOLD = 55;   // Score below this triggers quality rotation (tuned up from 40 — too hair-trigger)
+const MIN_EVENTS = 30;          // Minimum classifier events before scoring (tuned up from 10 — ~100 turns for stable signal)
+const MIN_AGE_SEC = 120;        // Minimum agent age before quality rotation
+const SCORE_HISTORY_MAX = 40;   // ~10 min at 15s intervals
+const ROTATION_COOLDOWN_MS = 5 * 60 * 1000; // 5 min between rotations per agent — prevents churn on persistent low quality
 
 export class Rotator extends EventEmitter {
   constructor(daemon) {
     super();
     this.daemon = daemon;
     this.interval = null;
-    this.rotationHistory = []; // [{ agentId, agentName, oldTokens, timestamp, brief }]
-    this.rotating = new Set(); // Agent IDs currently being rotated
+    this.rotationHistory = [];
+    this.rotating = new Set();
     this.enabled = false;
+    this.liveScores = {};
+    this.scoreHistory = {};
+    this.historyPath = daemon.grooveDir ? resolve(daemon.grooveDir, 'rotation-history.json') : null;
+    this._loadHistory();
+  }
+
+  _loadHistory() {
+    if (this.historyPath && existsSync(this.historyPath)) {
+      try {
+        const data = JSON.parse(readFileSync(this.historyPath, 'utf8'));
+        this.rotationHistory = Array.isArray(data) ? data : [];
+      } catch {
+        this.rotationHistory = [];
+      }
+    }
+    this._recoverFromTimeline();
+  }
+
+  _recoverFromTimeline() {
+    if (!this.daemon.timeline) return;
+    const events = this.daemon.timeline.getEvents(500);
+    const rotateEvents = events.filter((e) => e.type === 'rotate');
+    if (rotateEvents.length === 0) return;
+
+    const existingTimestamps = new Set(this.rotationHistory.map((r) => r.timestamp));
+    let added = 0;
+    for (const e of rotateEvents) {
+      const ts = new Date(e.t).toISOString();
+      if (existingTimestamps.has(ts)) continue;
+      this.rotationHistory.push({
+        agentId: e.oldAgentId || e.agentId,
+        agentName: e.agentName || 'unknown',
+        role: e.role || 'unknown',
+        provider: e.provider || 'unknown',
+        oldTokens: e.tokensBefore || 0,
+        contextUsage: 0,
+        reason: e.reason || 'context_threshold',
+        timestamp: ts,
+        newAgentId: e.agentId,
+        newTokens: 0,
+      });
+      added++;
+    }
+    if (added > 0) {
+      this.rotationHistory.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
+      this._saveHistory();
+    }
+  }
+
+  _saveHistory() {
+    if (!this.historyPath) return;
+    try {
+      writeFileSync(this.historyPath, JSON.stringify(this.rotationHistory, null, 2));
+    } catch { /* best-effort */ }
   }
 
   start() {
@@ -30,26 +91,164 @@ export class Rotator extends EventEmitter {
     this.enabled = false;
   }
 
+  _idleMs(agent) {
+    return agent.lastActivity
+      ? Date.now() - new Date(agent.lastActivity).getTime()
+      : Infinity;
+  }
+
+  // Check if this agent rotated recently. Prevents back-to-back rotation
+  // churn when quality score stays low post-rotation (e.g. genuinely hard task).
+  // Safety triggers bypass cooldown — pathological burn must be stopped.
+  _isInCooldown(agent) {
+    const last = [...this.rotationHistory]
+      .reverse()
+      .find((r) => r.newAgentId === agent.id || r.agentId === agent.id);
+    if (!last) return false;
+    const elapsed = Date.now() - new Date(last.timestamp).getTime();
+    return elapsed < ROTATION_COOLDOWN_MS;
+  }
+
+  scoreLiveSession(agent) {
+    const events = this.daemon.classifier.agentWindows[agent.id] || [];
+    const ageSec = (Date.now() - new Date(agent.spawnedAt).getTime()) / 1000;
+
+    if (events.length < MIN_EVENTS || ageSec < MIN_AGE_SEC) {
+      return { score: 70, signals: {}, hasEnoughData: false, ageSec: Math.round(ageSec), eventCount: events.length };
+    }
+
+    const signals = this.daemon.adaptive.extractSignals(events, agent.scope);
+    let score = this.daemon.adaptive.scoreSession(signals);
+
+    if (ageSec > 1800) score -= 5;
+    if (ageSec > 3600) score -= 10;
+
+    score = Math.max(0, Math.min(100, score));
+
+    const result = { score, signals, hasEnoughData: true, ageSec: Math.round(ageSec), eventCount: events.length };
+    this.liveScores[agent.id] = result;
+
+    if (!this.scoreHistory[agent.id]) this.scoreHistory[agent.id] = [];
+    const hist = this.scoreHistory[agent.id];
+    hist.push({ t: Date.now(), s: score });
+    if (hist.length > SCORE_HISTORY_MAX) hist.shift();
+
+    return result;
+  }
+
+  // Safety triggers — runaway agent detection. Scoped to `spawnedAt` so
+  // a rotation doesn't re-trigger on inherited cumulative tokens.
+  _checkSafetyTriggers(agent) {
+    const safety = this.daemon.config?.safety;
+    if (!safety || safety.autoRotate === false) return null;
+    if (!this.daemon.tokens || !agent.spawnedAt) return null;
+
+    const spawnedAtMs = new Date(agent.spawnedAt).getTime();
+    const ceiling = safety.tokenCeilingPerAgent;
+    if (ceiling > 0) {
+      const instanceTokens = this.daemon.tokens.getTokensInWindow(agent.id, spawnedAtMs);
+      if (instanceTokens >= ceiling) {
+        return {
+          reason: 'token_limit_exceeded',
+          instanceTokens,
+          ceiling,
+        };
+      }
+    }
+
+    const windowMs = (safety.velocityWindowSeconds || 300) * 1000;
+    const velocityThreshold = safety.velocityTokenThreshold;
+    if (velocityThreshold > 0) {
+      const velocity = this.daemon.tokens.getVelocity(agent.id, windowMs);
+      if (velocity >= velocityThreshold) {
+        return {
+          reason: 'runaway_velocity',
+          velocity,
+          windowMs,
+          threshold: velocityThreshold,
+        };
+      }
+    }
+
+    return null;
+  }
+
+  // Compute post-rotation velocity for rotations that are old enough to
+  // have meaningful data. Replaces hardcoded savings assumptions with
+  // measured deltas. Positive velocityDelta = rotation reduced burn rate.
+  _finalizeRotationMeasurements() {
+    if (!this.daemon.tokens?.getVelocity) return;
+    const now = Date.now();
+    let modified = false;
+    for (const record of this.rotationHistory) {
+      if (record.postRotationVelocity != null) continue;
+      if (record.preRotationVelocity == null) continue;
+      if (!record.newAgentId) continue;
+      const rotatedAt = new Date(record.timestamp).getTime();
+      if (now - rotatedAt < 600_000) continue; // need 10 min of post-data
+      const postVelocity = this.daemon.tokens.getVelocity(record.newAgentId, 600_000);
+      record.postRotationVelocity = postVelocity;
+      record.velocityDelta = record.preRotationVelocity - postVelocity;
+      modified = true;
+    }
+    if (modified) this._saveHistory();
+  }
+
   async check() {
+    this._finalizeRotationMeasurements();
+
     const agents = this.daemon.registry.getAll();
     const running = agents.filter((a) => a.status === 'running');
 
     for (const agent of running) {
       if (this.rotating.has(agent.id)) continue;
 
+      // Safety triggers — highest priority, pathological behavior.
+      // Bypasses cooldown: pathological burn must be stopped immediately.
+      const safety = this._checkSafetyTriggers(agent);
+      if (safety) {
+        const summary = safety.reason === 'token_limit_exceeded'
+          ? `${safety.instanceTokens} tokens >= ${safety.ceiling} ceiling`
+          : `${safety.velocity} tokens in ${safety.windowMs / 1000}s >= ${safety.threshold} threshold`;
+        console.log(`  Rotator: ${agent.name} ${safety.reason} (${summary}) — auto-rotating`);
+        await this.rotate(agent.id, safety);
+        continue;
+      }
+
+      // Cooldown check — skip threshold-based rotations if agent just rotated.
+      // Gives the new instance time to stabilize before another judgment.
+      if (this._isInCooldown(agent)) continue;
+
       const threshold = this.daemon.adaptive
         ? this.daemon.adaptive.getThreshold(agent.provider, agent.role)
         : DEFAULT_THRESHOLD;
 
+      // Context-based rotation (original)
       if (agent.contextUsage >= threshold) {
-        // Check for natural pause: if agent has been idle for >10s
-        const idleMs = agent.lastActivity
-          ? Date.now() - new Date(agent.lastActivity).getTime()
-          : Infinity;
-
-        if (idleMs > 10_000) {
-          console.log(`  Rotator: ${agent.name} at ${Math.round(agent.contextUsage * 100)}% — rotating`);
-          await this.rotate(agent.id);
+        if (this._idleMs(agent) > 10_000) {
+          console.log(`  Rotator: ${agent.name} at ${Math.round(agent.contextUsage * 100)}% — rotating (context)`);
+          await this.rotate(agent.id, { reason: 'context_threshold' });
+          continue;
+        }
+      }
+
+      // Quality-based rotation — detects degradation before tokens are wasted.
+      // Converged provider:role profiles have stable thresholds already, so
+      // skip quality rotation there unless score is catastrophically low.
+      const quality = this.scoreLiveSession(agent);
+      if (quality.hasEnoughData && quality.score < QUALITY_THRESHOLD) {
+        const profile = this.daemon.adaptive?.getProfile?.(agent.provider, agent.role);
+        const converged = profile?.converged;
+        // If converged, require a deeper score drop before rotating
+        const floor = converged ? QUALITY_THRESHOLD - 15 : QUALITY_THRESHOLD;
+        if (quality.score < floor && this._idleMs(agent) > 10_000) {
+          console.log(`  Rotator: ${agent.name} quality=${quality.score}${converged ? ' (converged profile)' : ''} — rotating (quality)`);
+          await this.rotate(agent.id, {
+            reason: 'quality_degradation',
+            qualityScore: quality.score,
+            signals: quality.signals,
+          });
+          continue;
         }
       }
     }
@@ -67,28 +266,33 @@ export class Rotator extends EventEmitter {
       type: 'rotation:start',
       agentId,
       agentName: agent.name,
+      reason: options.reason || 'manual',
     });
 
     try {
-      // 1. Record adaptive session so rotation thresholds learn over time
       const classifierEvents = this.daemon.classifier.agentWindows[agentId] || [];
       if (classifierEvents.length > 0) {
         const signals = this.daemon.adaptive.extractSignals(classifierEvents, agent.scope);
         this.daemon.adaptive.recordSession(agent.provider, agent.role, signals);
       }
 
-      // Clear classifier window for the old agent
       this.daemon.classifier.clearAgent(agentId);
+      delete this.liveScores[agentId];
+      delete this.scoreHistory[agentId];
 
-      // 2. Generate handoff brief from Journalist
       let brief = await journalist.generateHandoffBrief(agent);
 
-      // Append additional prompt if provided (used by instruct/continue endpoints)
       if (options.additionalPrompt) {
         brief = brief + '\n\n## User Instruction\n\n' + options.additionalPrompt;
       }
 
-      // 3. Record rotation history
+      // Capture pre-rotation velocity (tokens/10min) so we can later measure
+      // whether the rotation actually improved token efficiency. Stored in
+      // history; finalized by _finalizeRotationMeasurements() on later ticks.
+      const preRotationVelocity = this.daemon.tokens?.getVelocity
+        ? this.daemon.tokens.getVelocity(agent.id, 600_000)
+        : null;
+
       const record = {
         agentId: agent.id,
         agentName: agent.name,
@@ -96,17 +300,26 @@ export class Rotator extends EventEmitter {
         provider: agent.provider,
         oldTokens: agent.tokensUsed,
         contextUsage: agent.contextUsage,
+        reason: options.reason || 'manual',
+        qualityScore: options.qualityScore || null,
+        instanceTokens: options.instanceTokens || null,
+        velocity: options.velocity || null,
+        preRotationVelocity,
+        postRotationVelocity: null,
+        velocityDelta: null,
         timestamp: new Date().toISOString(),
       };
 
-      // 4. Kill/clean up the old agent
-      // processes.kill handles both alive and dead agents:
-      // - alive: sends SIGTERM, waits for exit, removes from registry
-      // - dead: just removes from registry and releases locks
+      // Capture per-session signals for specialization tracking before we clear
+      const sessionSignals = classifierEvents.length > 0
+        ? this.daemon.adaptive.extractSignals(classifierEvents, agent.scope)
+        : null;
+      const sessionScore = sessionSignals
+        ? this.daemon.adaptive.scoreSession(sessionSignals)
+        : null;
+
       await processes.kill(agentId);
 
-      // 5. Respawn with handoff brief as the prompt
-      // Preserve auto routing mode so the router re-evaluates on respawn
       const routingMode = this.daemon.router.getMode(agentId);
       const respawnModel = routingMode.mode === 'auto' ? 'auto' : agent.model;
 
@@ -118,35 +331,64 @@ export class Rotator extends EventEmitter {
         prompt: brief,
         permission: agent.permission || 'full',
         workingDir: agent.workingDir,
-        name: agent.name, // Keep the same name for continuity
-        teamId: agent.teamId, // Keep the same team
+        name: agent.name,
+        teamId: agent.teamId,
       });
 
-      // Carry cumulative token stats so the dashboard shows lifetime totals
       if (agent.tokensUsed > 0) {
         registry.update(newAgent.id, { tokensUsed: agent.tokensUsed });
       }
 
-      // Record rotation savings in token tracker
       this.daemon.tokens.recordRotation(agent.id, agent.tokensUsed);
-      // Each rotation is a cold-start that the Journalist's handoff brief skips
       this.daemon.tokens.recordColdStartSkipped();
 
       record.newAgentId = newAgent.id;
       record.newTokens = 0;
       this.rotationHistory.push(record);
 
-      // Keep last 100 rotations
       if (this.rotationHistory.length > 100) {
         this.rotationHistory = this.rotationHistory.slice(-100);
       }
+      this._saveHistory();
+
+      // Append to persistent handoff chain (Layer 7 memory)
+      // so agent #50 knows what agent #1 struggled with.
+      if (this.daemon.memory) {
+        this.daemon.memory.appendHandoffBrief(agent.role, {
+          agentId: agent.id,
+          newAgentId: newAgent.id,
+          reason: record.reason,
+          oldTokens: agent.tokensUsed,
+          contextUsage: agent.contextUsage,
+          brief,
+          timestamp: record.timestamp,
+        });
+
+        // Update per-agent + per-role specialization profile
+        const files = Array.from(new Set(
+          classifierEvents
+            .map((e) => e.input || e.file || e.path)
+            .filter((f) => typeof f === 'string' && f.length > 0)
+            .slice(-20)
+        ));
+        this.daemon.memory.updateSpecialization(agent.id, {
+          role: agent.role,
+          qualityScore: sessionScore,
+          filesTouched: files,
+          signals: sessionSignals,
+          threshold: this.daemon.adaptive?.getThreshold(agent.provider, agent.role),
+        });
+      }
 
-      // Record rotation lifecycle event for timeline
       if (this.daemon.timeline) {
         this.daemon.timeline.recordEvent('rotate', {
           agentId: newAgent.id, oldAgentId: agentId,
           agentName: newAgent.name, role: agent.role,
           tokensBefore: agent.tokensUsed,
+          reason: record.reason,
+          qualityScore: record.qualityScore,
+          instanceTokens: record.instanceTokens,
+          velocity: record.velocity,
         });
       }
 
@@ -155,6 +397,7 @@ export class Rotator extends EventEmitter {
         agentId: newAgent.id,
         agentName: newAgent.name,
         oldAgentId: agentId,
+        reason: record.reason,
         tokensSaved: agent.tokensUsed,
       });
 
@@ -173,6 +416,50 @@ export class Rotator extends EventEmitter {
     }
   }
 
+  recordNaturalCompaction(agent, peakUsage, currentUsage) {
+    const record = {
+      agentId: agent.id,
+      agentName: agent.name,
+      role: agent.role,
+      provider: agent.provider,
+      oldTokens: agent.tokensUsed || 0,
+      contextUsage: peakUsage,
+      contextAfter: currentUsage,
+      reason: 'natural_compaction',
+      qualityScore: null,
+      timestamp: new Date().toISOString(),
+      newAgentId: agent.id,
+      newTokens: agent.tokensUsed || 0,
+    };
+
+    this.rotationHistory.push(record);
+    if (this.rotationHistory.length > 100) {
+      this.rotationHistory = this.rotationHistory.slice(-100);
+    }
+    this._saveHistory();
+
+    if (this.daemon.timeline) {
+      this.daemon.timeline.recordEvent('rotate', {
+        agentId: agent.id,
+        agentName: agent.name,
+        role: agent.role,
+        reason: 'natural_compaction',
+        contextBefore: peakUsage,
+        contextAfter: currentUsage,
+      });
+    }
+
+    this.daemon.broadcast({
+      type: 'rotation:natural',
+      agentId: agent.id,
+      agentName: agent.name,
+      peakUsage,
+      currentUsage,
+    });
+
+    console.log(`  Rotator: ${agent.name} natural compaction detected (${Math.round(peakUsage * 100)}% → ${Math.round(currentUsage * 100)}%)`);
+  }
+
   isRotating(agentId) {
     return this.rotating.has(agentId);
   }
@@ -181,14 +468,30 @@ export class Rotator extends EventEmitter {
     return this.rotationHistory;
   }
 
+  getLiveScores() {
+    return this.liveScores;
+  }
+
   getStats() {
     const totalRotations = this.rotationHistory.length;
-    const totalTokensSaved = this.rotationHistory.reduce((sum, r) => sum + r.oldTokens, 0);
+    const totalTokensSaved = this.rotationHistory.reduce((sum, r) => sum + (r.oldTokens || 0), 0);
+    const qualityRotations = this.rotationHistory.filter((r) => r.reason === 'quality_degradation').length;
+    const contextRotations = this.rotationHistory.filter((r) => r.reason === 'context_threshold').length;
+    const naturalCompactions = this.rotationHistory.filter((r) => r.reason === 'natural_compaction').length;
+    const tokenLimitRotations = this.rotationHistory.filter((r) => r.reason === 'token_limit_exceeded').length;
+    const velocityRotations = this.rotationHistory.filter((r) => r.reason === 'runaway_velocity').length;
     return {
       enabled: this.enabled,
       totalRotations,
       totalTokensSaved,
+      qualityRotations,
+      contextRotations,
+      naturalCompactions,
+      tokenLimitRotations,
+      velocityRotations,
       rotating: Array.from(this.rotating),
+      liveScores: this.liveScores,
+      scoreHistory: this.scoreHistory,
     };
   }
 }

package/packages/daemon/src/router.js

@@ -142,4 +142,47 @@ export class ModelRouter {
       modes: MODES,
     };
   }
+
+  // Suggest a tier downshift when the classifier has enough confidence that
+  // a lighter model would still handle the task. Returns null when no
+  // suggestion is warranted. NEVER auto-applied — user must accept via UI.
+  // Honors the "heavy defaults" design principle: only suggests downshift,
+  // never upshift to heavier (user always has that available manually).
+  getSuggestion(agentId) {
+    const agent = this.daemon.registry.get(agentId);
+    if (!agent) return null;
+
+    const provider = getProvider(agent.provider);
+    if (!provider) return null;
+    const models = provider.constructor.models;
+
+    const classifier = this.daemon.classifier;
+    if (!classifier) return null;
+    const events = classifier.agentWindows[agentId] || [];
+    // Need enough events for a confident classification
+    if (events.length < 40) return null;
+
+    const currentModelId = agent.model || models[0]?.id;
+    const currentModel = models.find((m) => m.id === currentModelId || currentModelId?.includes(m.id));
+    if (!currentModel) return null;
+
+    const classifiedTier = classifier.classify(agentId);
+    const suggestedModel = models.find((m) => m.tier === classifiedTier);
+    if (!suggestedModel || suggestedModel.id === currentModel.id) return null;
+
+    // Tier order (heavy > medium > light). Only suggest if moving to cheaper tier.
+    const tierRank = { heavy: 3, medium: 2, light: 1 };
+    const currentRank = tierRank[currentModel.tier] || 2;
+    const suggestedRank = tierRank[classifiedTier] || 2;
+    if (suggestedRank >= currentRank) return null;
+
+    return {
+      agentId,
+      currentModel: { id: currentModel.id, name: currentModel.name, tier: currentModel.tier },
+      suggestedModel: { id: suggestedModel.id, name: suggestedModel.name, tier: suggestedModel.tier },
+      classifiedTier,
+      eventCount: events.length,
+      reason: `Last ${events.length} events classified as ${classifiedTier}. A lighter model would likely handle this task and reduce cost.`,
+    };
+  }
 }

package/packages/daemon/src/tokentracker.js

@@ -116,12 +116,35 @@ export class TokenTracker {
       cacheReadTokens: detail.cacheReadTokens || 0,
       cacheCreationTokens: detail.cacheCreationTokens || 0,
       model: detail.model || null,
+      // Reserved for future per-project grouping (workspaces feature).
+      // Caller passes the project's absolute root path when known.
+      projectRoot: detail.projectRoot || null,
       timestamp: new Date().toISOString(),
     });
 
     this.save();
   }
 
+  // Sum tokens recorded for an agent since a given timestamp.
+  // Used by safety rotation triggers to measure per-instance burn
+  // (scoped to spawnedAt avoids counting pre-rotation history).
+  getTokensInWindow(agentId, sinceTs) {
+    const entry = this.usage[agentId];
+    if (!entry || !Array.isArray(entry.sessions)) return 0;
+    const cutoff = typeof sinceTs === 'number' ? sinceTs : new Date(sinceTs).getTime();
+    let total = 0;
+    for (const session of entry.sessions) {
+      const ts = new Date(session.timestamp).getTime();
+      if (ts >= cutoff) total += session.tokens || 0;
+    }
+    return total;
+  }
+
+  // Rolling velocity: tokens consumed in the last `windowMs` milliseconds.
+  getVelocity(agentId, windowMs) {
+    return this.getTokensInWindow(agentId, Date.now() - windowMs);
+  }
+
   // Record session-level result data (cost, duration, turns) — fires once per completion
   recordResult(agentId, { costUsd, durationMs, turns }) {
     this._initAgent(agentId);
@@ -179,29 +202,28 @@ export class TokenTracker {
     return Object.values(this.usage).reduce((sum, a) => sum + (a.totalCostUsd || 0), 0);
   }
 
+  // Cache hit rate = cache reads / all cacheable input (reads + creation).
+  // Fresh inputTokens are conversation turns that were never cache-eligible,
+  // so they must be excluded from the denominator.
   getCacheHitRate() {
-    let totalRead = 0, totalCreation = 0, totalInput = 0;
+    let totalRead = 0, totalCreation = 0;
     for (const a of Object.values(this.usage)) {
       totalRead += a.cacheReadTokens || 0;
       totalCreation += a.cacheCreationTokens || 0;
-      totalInput += a.inputTokens || 0;
     }
-    const total = totalRead + totalCreation + totalInput;
-    return total > 0 ? totalRead / total : 0;
+    const cacheable = totalRead + totalCreation;
+    return cacheable > 0 ? totalRead / cacheable : 0;
   }
 
   // Generate a savings summary
   getSummary() {
     const totalTokens = this.getTotal();
     const totalCostUsd = this.getTotalCost();
-    const agentCount = Object.keys(this.usage).length;
     const sessionDuration = Date.now() - this.sessionStart;
 
-    // Aggregate I/O and cache breakdown
     let totalInputTokens = 0, totalOutputTokens = 0;
     let totalCacheRead = 0, totalCacheCreation = 0;
     let totalDurationMs = 0, totalTurns = 0;
-    let realCostUsd = 0, estimatedCostUsd = 0;
 
     for (const a of Object.values(this.usage)) {
       totalInputTokens += a.inputTokens || 0;
@@ -212,19 +234,44 @@ export class TokenTracker {
       totalTurns += a.totalTurns || 0;
     }
 
-    // Estimate what uncoordinated usage would have cost
+    // Segregate internal overhead (reserved IDs prefixed __) from user agents.
+    // Internal tokens still count in totals (real billing) but show separately.
+    const userEntries = Object.entries(this.usage).filter(([id]) => !id.startsWith('__'));
+    const internalEntries = Object.entries(this.usage).filter(([id]) => id.startsWith('__'));
+    const agentCount = userEntries.length;
+
+    const internalComponents = {};
+    let internalTokens = 0;
+    let internalCostUsd = 0;
+    for (const [id, data] of internalEntries) {
+      internalComponents[id] = {
+        tokens: data.total,
+        costUsd: data.totalCostUsd || 0,
+        inputTokens: data.inputTokens || 0,
+        outputTokens: data.outputTokens || 0,
+        cacheReadTokens: data.cacheReadTokens || 0,
+        cacheCreationTokens: data.cacheCreationTokens || 0,
+        sessions: data.sessions.length,
+      };
+      internalTokens += data.total;
+      internalCostUsd += data.totalCostUsd || 0;
+    }
+
     const coldStartOverhead = this.getColdStartOverhead();
     const coldStartWaste = this.coldStartsSkipped * coldStartOverhead;
     const conflictWaste = this.conflictsPrevented * CONFLICT_OVERHEAD;
-    const totalSavings = this.rotationSavings + coldStartWaste + conflictWaste;
+    const coordinationSavings = this.rotationSavings + coldStartWaste + conflictWaste;
 
-    const estimatedWithout = totalTokens + totalSavings;
-    const savingsPct = estimatedWithout > 0
-      ? Math.round((totalSavings / estimatedWithout) * 100)
-      : 0;
+    const estimatedWithout = totalTokens + coordinationSavings;
+    const rawPct = estimatedWithout > 0 ? (coordinationSavings / estimatedWithout) * 100 : 0;
+    const coordPct = rawPct > 0 && rawPct < 1
+      ? Math.round(rawPct * 10) / 10
+      : Math.round(rawPct);
 
-    const cacheTotal = totalCacheRead + totalCacheCreation + totalInputTokens;
-    const cacheHitRate = cacheTotal > 0 ? totalCacheRead / cacheTotal : 0;
+    // Cache hit rate: reads / (reads + creation). Excludes fresh inputTokens
+    // which are never cache-eligible.
+    const cacheable = totalCacheRead + totalCacheCreation;
+    const cacheHitRate = cacheable > 0 ? totalCacheRead / cacheable : 0;
 
     return {
       totalTokens,
@@ -239,14 +286,19 @@ export class TokenTracker {
       agentCount,
       sessionDurationMs: sessionDuration,
       savings: {
-        total: totalSavings,
+        total: coordinationSavings,
         fromRotation: this.rotationSavings,
         fromConflictPrevention: conflictWaste,
         fromColdStartSkip: coldStartWaste,
-        percentage: savingsPct,
+        percentage: coordPct,
         estimatedWithoutGroove: estimatedWithout,
       },
-      perAgent: Object.entries(this.usage).map(([id, data]) => ({
+      internalOverhead: {
+        tokens: internalTokens,
+        costUsd: internalCostUsd,
+        components: internalComponents,
+      },
+      perAgent: userEntries.map(([id, data]) => ({
         agentId: id,
         tokens: data.total,
         costUsd: data.totalCostUsd || 0,