groove-dev 0.26.39 → 0.27.0

package/node_modules/@groove-dev/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/node_modules/@groove-dev/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,22 +202,23 @@ 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;
 
     let totalInputTokens = 0, totalOutputTokens = 0;
@@ -210,6 +234,29 @@ export class TokenTracker {
       totalTurns += a.totalTurns || 0;
     }
 
+    // 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;
@@ -221,8 +268,10 @@ export class TokenTracker {
       ? 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,
@@ -244,7 +293,12 @@ export class TokenTracker {
         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,

package/node_modules/@groove-dev/daemon/src/validate.js

@@ -127,19 +127,6 @@ export function validateTeamName(name) {
   // Allow spaces and special chars in display name, sanitize for filesystem separately
 }
 
-export function sanitizeForFilename(name) {
-  const sanitized = name
-    .replace(/[^a-zA-Z0-9_-]/g, '_')
-    .replace(/_+/g, '_')
-    .toLowerCase()
-    .slice(0, 50);
-
-  if (!sanitized || /^_+$/.test(sanitized)) {
-    throw new Error('Team name must contain alphanumeric characters');
-  }
-  return sanitized;
-}
-
 const VALID_GATEWAY_TYPES = ['telegram', 'discord', 'slack'];
 const VALID_NOTIFICATION_PRESETS = ['critical', 'lifecycle', 'all', 'custom'];
 

package/node_modules/@groove-dev/daemon/test/lockmanager.test.js

@@ -83,4 +83,68 @@ describe('LockManager', () => {
     assert.equal(locks.check('agent-1', 'src/components/App.jsx').conflict, true);
     assert.equal(locks.check('agent-2', 'src/api/auth.js').conflict, true);
   });
+
+  describe('coordination operations', () => {
+    it('declares an operation with no conflict', () => {
+      const result = locks.declareOperation('agent-1', 'npm install', ['package.json']);
+      assert.equal(result.conflict, false);
+      const ops = locks.getOperations();
+      assert.equal(ops['agent-1'].name, 'npm install');
+    });
+
+    it('detects conflict when another agent holds a resource', () => {
+      locks.declareOperation('agent-1', 'npm install', ['package.json']);
+      const result = locks.declareOperation('agent-2', 'edit manifest', ['package.json']);
+      assert.equal(result.conflict, true);
+      assert.equal(result.owner, 'agent-1');
+      assert.equal(result.resource, 'package.json');
+      assert.equal(result.operation, 'npm install');
+    });
+
+    it('allows non-overlapping resource claims', () => {
+      locks.declareOperation('agent-1', 'npm install', ['package.json']);
+      const result = locks.declareOperation('agent-2', 'restart server', ['server:3000']);
+      assert.equal(result.conflict, false);
+    });
+
+    it('same agent can update its own declaration', () => {
+      locks.declareOperation('agent-1', 'edit', ['file-a']);
+      // Same agent can re-declare without conflict
+      const result = locks.declareOperation('agent-1', 'edit', ['file-a', 'file-b']);
+      assert.equal(result.conflict, false);
+    });
+
+    it('completeOperation releases the claim', () => {
+      locks.declareOperation('agent-1', 'npm install', ['package.json']);
+      locks.completeOperation('agent-1');
+
+      const result = locks.declareOperation('agent-2', 'edit', ['package.json']);
+      assert.equal(result.conflict, false);
+    });
+
+    it('operations auto-expire after TTL', () => {
+      locks.declareOperation('agent-1', 'stale op', ['resource-x'], 1);
+      // Wait past TTL
+      const start = Date.now();
+      while (Date.now() - start < 5) { /* spin briefly */ }
+
+      const result = locks.declareOperation('agent-2', 'takeover', ['resource-x']);
+      assert.equal(result.conflict, false);
+    });
+
+    it('rejects malformed declarations', () => {
+      assert.equal(locks.declareOperation(null, 'op', ['r']).conflict, false);
+      assert.equal(locks.declareOperation('a', null, ['r']).conflict, false);
+      assert.equal(locks.declareOperation('a', 'op', []).conflict, false);
+      // All return error flag
+      assert.ok(locks.declareOperation('a', 'op', []).error);
+    });
+
+    it('release() also clears pending operations', () => {
+      locks.declareOperation('agent-1', 'op', ['r']);
+      locks.release('agent-1');
+      const result = locks.declareOperation('agent-2', 'op2', ['r']);
+      assert.equal(result.conflict, false);
+    });
+  });
 });

package/node_modules/@groove-dev/daemon/test/memory.test.js

@@ -0,0 +1,252 @@
+// GROOVE — MemoryStore Tests (Layer 7)
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { MemoryStore } from '../src/memory.js';
+import { mkdtempSync, existsSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+describe('MemoryStore', () => {
+  let memory;
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'groove-memory-test-'));
+    memory = new MemoryStore(tmpDir);
+  });
+
+  describe('constraints', () => {
+    it('starts with no constraints', () => {
+      assert.deepEqual(memory.listConstraints(), []);
+      assert.equal(memory.getConstraintsMarkdown(), '');
+    });
+
+    it('adds a constraint and returns a hash', () => {
+      const result = memory.addConstraint({ text: 'Never touch packages/daemon/index.js', category: 'hard' });
+      assert.equal(result.added, true);
+      assert.ok(result.hash);
+
+      const list = memory.listConstraints();
+      assert.equal(list.length, 1);
+      assert.equal(list[0].category, 'hard');
+      assert.match(list[0].text, /Never touch/);
+    });
+
+    it('dedups identical constraints', () => {
+      memory.addConstraint({ text: 'ESM only', category: 'pattern' });
+      const result = memory.addConstraint({ text: 'ESM only', category: 'pattern' });
+      assert.equal(result.added, false);
+      assert.equal(result.reason, 'duplicate');
+      assert.equal(memory.listConstraints().length, 1);
+    });
+
+    it('rejects empty and oversized text', () => {
+      assert.equal(memory.addConstraint({ text: '' }).added, false);
+      assert.equal(memory.addConstraint({ text: 'ab' }).added, false);
+      assert.equal(memory.addConstraint({ text: 'x'.repeat(600) }).added, false);
+    });
+
+    it('removes constraints by hash', () => {
+      const r = memory.addConstraint({ text: 'remove me', category: 'test' });
+      assert.equal(memory.removeConstraint(r.hash), true);
+      assert.equal(memory.listConstraints().length, 0);
+      // Removing non-existent hash returns false
+      assert.equal(memory.removeConstraint('nonexistent'), false);
+    });
+
+    it('getConstraintsMarkdown groups by category', () => {
+      memory.addConstraint({ text: 'rule-a', category: 'hard' });
+      memory.addConstraint({ text: 'rule-b', category: 'hard' });
+      memory.addConstraint({ text: 'pattern-x', category: 'pattern' });
+      const md = memory.getConstraintsMarkdown();
+      assert.match(md, /\*\*hard:\*\*/);
+      assert.match(md, /\*\*pattern:\*\*/);
+      assert.match(md, /rule-a/);
+      assert.match(md, /pattern-x/);
+    });
+
+    it('survives restart', () => {
+      memory.addConstraint({ text: 'persists across restart', category: 'test' });
+      const memory2 = new MemoryStore(tmpDir);
+      assert.equal(memory2.listConstraints().length, 1);
+      assert.match(memory2.listConstraints()[0].text, /persists/);
+    });
+  });
+
+  describe('handoff chain', () => {
+    it('starts with no chain', () => {
+      assert.deepEqual(memory.getHandoffChain('backend'), []);
+      assert.equal(memory.getRecentHandoffMarkdown('backend'), '');
+    });
+
+    it('appends a rotation entry', () => {
+      const ok = memory.appendHandoffBrief('backend', {
+        agentId: 'bk-1',
+        newAgentId: 'bk-2',
+        reason: 'context_threshold',
+        oldTokens: 5_000_000,
+        contextUsage: 0.82,
+        brief: 'Finished auth refactor, started on payment flow',
+        timestamp: '2026-04-12T14:00:00Z',
+      });
+      assert.equal(ok, true);
+
+      const chain = memory.getHandoffChain('backend');
+      assert.equal(chain.length, 1);
+      assert.equal(chain[0].rotationN, 1);
+      assert.match(chain[0].body, /Rotation 1/);
+      assert.match(chain[0].body, /context_threshold/);
+    });
+
+    it('increments rotation numbers and keeps newest first', () => {
+      memory.appendHandoffBrief('backend', { brief: 'first' });
+      memory.appendHandoffBrief('backend', { brief: 'second' });
+      memory.appendHandoffBrief('backend', { brief: 'third' });
+
+      const chain = memory.getHandoffChain('backend');
+      assert.equal(chain.length, 3);
+      assert.equal(chain[0].rotationN, 3);
+      assert.equal(chain[2].rotationN, 1);
+    });
+
+    it('caps chain at MAX_HANDOFF_ROTATIONS (10)', () => {
+      for (let i = 0; i < 15; i++) {
+        memory.appendHandoffBrief('backend', { brief: `rotation-${i}` });
+      }
+      const chain = memory.getHandoffChain('backend');
+      assert.equal(chain.length, 10);
+      assert.equal(chain[0].rotationN, 15);
+    });
+
+    it('separate chains per role', () => {
+      memory.appendHandoffBrief('backend', { brief: 'backend work' });
+      memory.appendHandoffBrief('frontend', { brief: 'frontend work' });
+      assert.equal(memory.getHandoffChain('backend').length, 1);
+      assert.equal(memory.getHandoffChain('frontend').length, 1);
+      assert.deepEqual(memory.listHandoffRoles().sort(), ['backend', 'frontend']);
+    });
+
+    it('getRecentHandoffMarkdown returns N newest', () => {
+      for (let i = 0; i < 5; i++) {
+        memory.appendHandoffBrief('backend', { brief: `brief-${i}` });
+      }
+      const md = memory.getRecentHandoffMarkdown('backend', 3);
+      assert.match(md, /brief-4/);
+      assert.match(md, /brief-3/);
+      assert.match(md, /brief-2/);
+      assert.ok(!md.includes('brief-1'));
+    });
+
+    it('sanitizes role names for filesystem safety', () => {
+      const ok = memory.appendHandoffBrief('../evil/role', { brief: 'test' });
+      assert.equal(ok, true);
+      // File should be created with safe name, no path traversal
+      assert.ok(existsSync(tmpDir));
+    });
+  });
+
+  describe('discoveries', () => {
+    it('starts with no discoveries', () => {
+      assert.deepEqual(memory.listDiscoveries(), []);
+      assert.equal(memory.getDiscoveriesMarkdown(), '');
+    });
+
+    it('adds a success discovery', () => {
+      const result = memory.addDiscovery({
+        agentId: 'bk-1',
+        role: 'backend',
+        trigger: 'Cannot find module gray-matter',
+        fix: 'npm install gray-matter',
+        outcome: 'success',
+      });
+      assert.equal(result.added, true);
+
+      const list = memory.listDiscoveries();
+      assert.equal(list.length, 1);
+      assert.equal(list[0].role, 'backend');
+    });
+
+    it('rejects non-success outcomes', () => {
+      const result = memory.addDiscovery({
+        trigger: 'err',
+        fix: 'did not work',
+        outcome: 'failed',
+      });
+      assert.equal(result.added, false);
+    });
+
+    it('rejects incomplete records', () => {
+      assert.equal(memory.addDiscovery({ trigger: 'x' }).added, false);
+      assert.equal(memory.addDiscovery({ fix: 'y' }).added, false);
+    });
+
+    it('dedups identical trigger+fix pairs', () => {
+      memory.addDiscovery({ trigger: 'error X', fix: 'fix X' });
+      const result = memory.addDiscovery({ trigger: 'error X', fix: 'fix X' });
+      assert.equal(result.added, false);
+      assert.equal(result.reason, 'duplicate');
+    });
+
+    it('filters by role', () => {
+      memory.addDiscovery({ role: 'backend', trigger: 'a', fix: 'fa' });
+      memory.addDiscovery({ role: 'frontend', trigger: 'b', fix: 'fb' });
+      memory.addDiscovery({ role: 'backend', trigger: 'c', fix: 'fc' });
+
+      assert.equal(memory.listDiscoveries({ role: 'backend' }).length, 2);
+      assert.equal(memory.listDiscoveries({ role: 'frontend' }).length, 1);
+      assert.equal(memory.listDiscoveries().length, 3);
+    });
+
+    it('getDiscoveriesMarkdown formats for agent consumption', () => {
+      memory.addDiscovery({ role: 'backend', trigger: 'X error', fix: 'do Y' });
+      const md = memory.getDiscoveriesMarkdown('backend');
+      assert.match(md, /X error/);
+      assert.match(md, /do Y/);
+    });
+  });
+
+  describe('specializations', () => {
+    it('starts empty', () => {
+      const all = memory.getAllSpecializations();
+      assert.deepEqual(all.perAgent, {});
+      assert.deepEqual(all.perProjectRole, {});
+    });
+
+    it('updates an agent profile', () => {
+      memory.updateSpecialization('bk-1', {
+        role: 'backend',
+        qualityScore: 80,
+        filesTouched: ['src/a.js', 'src/b.js'],
+      });
+      const spec = memory.getSpecialization('bk-1');
+      assert.ok(spec);
+      assert.equal(spec.role, 'backend');
+      assert.equal(spec.avgQualityScore, 80);
+      assert.equal(spec.sessionCount, 1);
+      assert.equal(spec.fileTouches['src/a.js'], 1);
+    });
+
+    it('averages quality score across sessions', () => {
+      memory.updateSpecialization('bk-1', { role: 'backend', qualityScore: 70 });
+      memory.updateSpecialization('bk-1', { role: 'backend', qualityScore: 90 });
+      assert.equal(memory.getSpecialization('bk-1').avgQualityScore, 80);
+      assert.equal(memory.getSpecialization('bk-1').sessionCount, 2);
+    });
+
+    it('aggregates per-role stats', () => {
+      memory.updateSpecialization('bk-1', { role: 'backend', qualityScore: 80 });
+      memory.updateSpecialization('bk-2', { role: 'backend', qualityScore: 60 });
+      const all = memory.getAllSpecializations();
+      assert.equal(all.perProjectRole.backend.sessionCount, 2);
+      assert.equal(all.perProjectRole.backend.avgQualityScore, 70);
+    });
+
+    it('survives restart', () => {
+      memory.updateSpecialization('bk-1', { role: 'backend', qualityScore: 75 });
+      const memory2 = new MemoryStore(tmpDir);
+      assert.equal(memory2.getSpecialization('bk-1').avgQualityScore, 75);
+    });
+  });
+});

package/node_modules/@groove-dev/daemon/test/rotator.test.js

@@ -162,4 +162,112 @@ describe('Rotator', () => {
     assert.equal(stats.totalRotations, 2);
     assert.equal(stats.totalTokensSaved, 8000);
   });
+
+  describe('safety triggers', () => {
+    const SPAWNED = new Date(Date.now() - 60_000).toISOString(); // spawned 1 min ago
+
+    function mkAgent(overrides = {}) {
+      return {
+        id: 'a1', name: 'backend-1', role: 'backend',
+        provider: 'claude-code', scope: [], model: null,
+        tokensUsed: 0, contextUsage: 0.1, workingDir: '/tmp',
+        spawnedAt: SPAWNED, status: 'running',
+        ...overrides,
+      };
+    }
+
+    it('returns null when safety config is missing', () => {
+      mockDaemon.config = undefined;
+      const trigger = rotator._checkSafetyTriggers(mkAgent());
+      assert.equal(trigger, null);
+    });
+
+    it('returns null when autoRotate is disabled', () => {
+      mockDaemon.config = { safety: { autoRotate: false, tokenCeilingPerAgent: 100 } };
+      mockDaemon.tokens.getTokensInWindow = () => 1000;
+      const trigger = rotator._checkSafetyTriggers(mkAgent());
+      assert.equal(trigger, null);
+    });
+
+    it('fires token_limit_exceeded when instance tokens hit ceiling', () => {
+      mockDaemon.config = {
+        safety: {
+          autoRotate: true,
+          tokenCeilingPerAgent: 1_000_000,
+          velocityWindowSeconds: 300,
+          velocityTokenThreshold: 2_000_000,
+        },
+      };
+      mockDaemon.tokens.getTokensInWindow = () => 1_200_000;
+      mockDaemon.tokens.getVelocity = () => 0;
+
+      const trigger = rotator._checkSafetyTriggers(mkAgent());
+      assert.equal(trigger.reason, 'token_limit_exceeded');
+      assert.equal(trigger.instanceTokens, 1_200_000);
+      assert.equal(trigger.ceiling, 1_000_000);
+    });
+
+    it('fires runaway_velocity when recent burn exceeds threshold', () => {
+      mockDaemon.config = {
+        safety: {
+          autoRotate: true,
+          tokenCeilingPerAgent: 10_000_000,
+          velocityWindowSeconds: 300,
+          velocityTokenThreshold: 1_000_000,
+        },
+      };
+      mockDaemon.tokens.getTokensInWindow = () => 500_000; // under ceiling
+      mockDaemon.tokens.getVelocity = () => 1_500_000;
+
+      const trigger = rotator._checkSafetyTriggers(mkAgent());
+      assert.equal(trigger.reason, 'runaway_velocity');
+      assert.equal(trigger.velocity, 1_500_000);
+      assert.equal(trigger.threshold, 1_000_000);
+      assert.equal(trigger.windowMs, 300_000);
+    });
+
+    it('ceiling check takes priority over velocity check', () => {
+      mockDaemon.config = {
+        safety: {
+          autoRotate: true,
+          tokenCeilingPerAgent: 1_000_000,
+          velocityWindowSeconds: 300,
+          velocityTokenThreshold: 1_000_000,
+        },
+      };
+      mockDaemon.tokens.getTokensInWindow = () => 2_000_000;
+      mockDaemon.tokens.getVelocity = () => 2_000_000;
+      const trigger = rotator._checkSafetyTriggers(mkAgent());
+      assert.equal(trigger.reason, 'token_limit_exceeded');
+    });
+
+    it('returns null when neither threshold hit', () => {
+      mockDaemon.config = {
+        safety: {
+          autoRotate: true,
+          tokenCeilingPerAgent: 5_000_000,
+          velocityWindowSeconds: 300,
+          velocityTokenThreshold: 1_500_000,
+        },
+      };
+      mockDaemon.tokens.getTokensInWindow = () => 100_000;
+      mockDaemon.tokens.getVelocity = () => 10_000;
+      const trigger = rotator._checkSafetyTriggers(mkAgent());
+      assert.equal(trigger, null);
+    });
+
+    it('stats track safety-triggered rotations separately', async () => {
+      mockDaemon.registry.agents = [mkAgent({ tokensUsed: 1_200_000 })];
+      await rotator.rotate('a1', {
+        reason: 'token_limit_exceeded',
+        instanceTokens: 1_200_000,
+        ceiling: 1_000_000,
+      });
+
+      const stats = rotator.getStats();
+      assert.equal(stats.tokenLimitRotations, 1);
+      assert.equal(stats.velocityRotations, 0);
+      assert.equal(stats.totalRotations, 1);
+    });
+  });
 });