groove-dev 0.26.38 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## v0.27.0 — Audit-driven release: visibility, safety, Layer 7 memory (2026-04-12)
+
+Backend audit after a 275M-token stress test revealed three classes of gaps: blind spots (invisible tokens), unvalidated claims (hardcoded coefficients posing as measurements), and missing memory (every new agent started from scratch). This release closes all three.
+
+**Visibility — you can now see what's actually happening**
+- Journalist, PM, planner, negotiator, gateway, and agent-QA headless calls now record tokens under reserved IDs (`__journalist__`, `__pm__`, etc.) — previously invisible 1-6M tokens/day now tracked
+- Cache hit rate formula fixed: denominator was incorrectly including fresh input tokens; corrected to `reads / (reads + creation)` so the number reflects real cache efficiency
+- New `GET /api/tokens/by-team` endpoint — ranked team burn breakdown answers "which team used the most tokens?" in one call
+- Dashboard gets a new Team Burn panel with per-team bars, cost, and agent count
+- Per-agent cache rate in `/api/dashboard` uses the corrected formula
+- `projectRoot` field reserved in token session records for future per-workspace grouping
+
+**Safety — the system self-heals on pathological agents**
+- Token ceiling auto-rotate: when an agent burns more than `safety.tokenCeilingPerAgent` (default 5M) since its spawn, rotator fires `token_limit_exceeded` rotation with journalist handoff brief
+- Velocity auto-rotate: when an agent burns more than `safety.velocityTokenThreshold` (default 1.5M) in a rolling `safety.velocityWindowSeconds` window (default 300s), rotator fires `runaway_velocity`
+- Both triggers use existing rotation infrastructure — no new kill/respawn code, just new `shouldRotate()` conditions
+- Triggers scoped to `spawnedAt` so post-rotation agents don't re-trigger on inherited cumulative tokens
+- Coordination protocol is now enforced, not advisory: `POST /api/coordination/declare` acquires a short-lived resource lock; returns 423 on conflict with owner + expiry info; auto-expires after 10min to prevent deadlock
+- Introducer now instructs agents to use the HTTP protocol instead of editing `.groove/coordination.md`
+- Intel panel shows safety-triggered rotations with distinct badges (`T:5M` red, `V:1.5M` orange) and hover tooltips
+
+**Layer 7 — persistent agent memory**
+- New `MemoryStore` module (`memory.js`) persists four file types in `.groove/memory/`:
+  - `project-constraints.md` — hash-deduped project rules (capped at 50)
+  - `handoff-chain/<role>.md` — last 10 rotation briefs per role, newest first
+  - `agent-discoveries.jsonl` — error→fix pairs (success-only, 1000-entry cap)
+  - `agent-specializations.json` — per-agent + per-role quality profiles
+- Rotator appends brief to chain on every rotation; journalist reads last 3 into new briefs for causal continuity across rotations
+- Introducer injects accumulated memory into every new agent spawn (constraints + recent handoffs + known patterns, 12K char budget)
+- Process manager updates specializations on agent completion/crash (avg quality, file touches, error signatures)
+- 9 new API endpoints for CRUD on all four memory types
+- 26 new unit tests covering dedup, size caps, role-scoped filtering, persistence
+
+**Rotation intelligence**
+- `QUALITY_THRESHOLD` raised 40 → 55 (tuned up from hair-trigger threshold)
+- `MIN_EVENTS` raised 10 → 30 (require ~100 turns of stable signal before scoring)
+- New 5-minute rotation cooldown prevents back-to-back churn on persistently low-quality tasks
+- Safety triggers bypass cooldown (pathological burn must stop immediately)
+- Converged adaptive profiles get a deeper quality floor (threshold - 15) before rotating — if the threshold has stabilized, trust it
+- Pre/post-rotation velocity captured on every rotation; `velocityDelta` computed after new agent has 10 min of data — replaces hardcoded 30% assumption with measurable signal for future accuracy tuning
+
+**Mid-session classification (never silent downshift)**
+- Classifier broadcasts `classifier:update` events every 20 events once it has 40+ — enables UI to surface downshift suggestions
+- `GET /api/agents/:id/routing/suggestion` returns `{ currentModel, suggestedModel, classifiedTier, eventCount, reason }` when a lighter model would handle the current task
+- NEVER auto-applied — user must accept via UI click (heavy defaults principle preserved)
+- Never upshifts — only suggests moving to a cheaper tier
+- Returns 204 when classifier has no strong suggestion
+
+**Cleanup and dependencies**
+- Removed unused code: `sanitizeForFilename`, `formatDuration`, `dashTelemetry`, `ccChartTimeline`, entire `dropdown-menu.jsx` and `use-media-query.js`
+- Removed unused Radix deps (`react-popover`, `react-separator`, `react-dropdown-menu`)
+- Fixed duplicate `bundledDependencies` / `bundleDependencies` keys in root package.json
+- Archived v1 build plan to `docs/archive/GROVE_BUILD_PLAN.md`; v2 plan is the active document
+- Workspace versions synced: daemon/cli/gui/root all at 0.26.39 (tagged 0.27.0 on release)
+- `.DS_Store` and stale logs cleaned
+- GUI dist/ rebuilt from scratch
+
+**Tests: 137 → 218 (+81 new)**
+
 ## v0.26.33 — Self-building pipeline, team persistence, agent quality overhaul (2026-04-11)
 
 Major release: Groove now builds itself. Full team lifecycle, intelligent context synthesis, and agent quality improvements across the board.

package/CLAUDE.md

@@ -33,19 +33,20 @@ groove/
 - **MimeTypes** (`mimetypes.js`) — MIME type lookup utilities
 
 **Coordination:**
-- **Introducer** (`introducer.js`) — generates AGENTS_REGISTRY.md, injects GROOVE section into CLAUDE.md, team context for new agents
-- **LockManager** (`lockmanager.js`) — file scope ownership via glob patterns, conflict detection with minimatch
+- **Introducer** (`introducer.js`) — generates AGENTS_REGISTRY.md, injects GROOVE section into CLAUDE.md, team context + Project Memory (Layer 7) injection for new agents
+- **LockManager** (`lockmanager.js`) — file scope ownership via glob patterns, coordination operations (enforced knock protocol, 10-min TTL), conflict detection with minimatch
 - **Supervisor** (`supervisor.js`) — QC approval routing, conflict recording, GROOVE_CONFLICTS.md, auto-QC at 4+ agents
 - **Teams** (`teams.js`) — live organizational groups (CRUD), auto-migration of legacy agents, backward compat stubs
 
 **Intelligence:**
-- **Journalist** (`journalist.js`) — AI-powered context synthesis (headless claude -p), log filtering (stream-json parsing), GROOVE_PROJECT_MAP.md, GROOVE_DECISIONS.md, per-agent session logs, handoff brief generation
-- **Rotator** (`rotator.js`) — context rotation engine (kill + respawn with fresh context), auto-rotation at adaptive threshold, timeline integration
-- **Adaptive** (`adaptive.js`) — per-provider per-role rotation thresholds, session scoring 0-100, threshold adjustment (+2%/-5%), convergence detection
-- **TokenTracker** (`tokentracker.js`) — per-agent token accounting, session metrics (duration/turns/cost), savings calculator
-- **Classifier** (`classifier.js`) — task complexity classification (light/medium/heavy) via sliding window pattern matching
-- **Router** (`router.js`) — adaptive model routing (Fixed/Auto/Auto-with-floor modes), cost tracking
-- **Timeline** (`timeline.js`) — historical metrics snapshots (30s intervals, max 2K), lifecycle events (spawn/complete/crash/kill/rotate, max 500)
+- **Journalist** (`journalist.js`) — AI-powered context synthesis (headless claude -p), log filtering (stream-json parsing), GROOVE_PROJECT_MAP.md, GROOVE_DECISIONS.md, per-agent session logs, handoff brief generation (prepends last 3 rotations from memory), reserved-ID token tracking for synthesis overhead
+- **Rotator** (`rotator.js`) — context rotation engine (kill + respawn with fresh context), adaptive threshold + quality + safety triggers (token ceiling, velocity spike), 5-min cooldown, pre/post velocity measurement, appends brief to persistent chain, updates specializations
+- **Adaptive** (`adaptive.js`) — per-provider per-role rotation thresholds, session scoring 0-100, threshold adjustment (+2%/-5%), convergence detection (used to gate quality rotations)
+- **TokenTracker** (`tokentracker.js`) — per-agent token accounting, session metrics (duration/turns/cost), corrected cache hit rate, velocity + windowed-tokens queries, internal overhead segregation, savings calculator
+- **Classifier** (`classifier.js`) — task complexity classification (light/medium/heavy) via sliding window, broadcasts mid-session updates every 20 events for downshift suggestions
+- **Router** (`router.js`) — adaptive model routing (Fixed/Auto/Auto-with-floor modes), cost tracking, downshift suggestion API (never auto-applied, requires user click)
+- **Memory** (`memory.js`) — **Layer 7** persistent agent memory: project-constraints.md, handoff-chain/<role>.md (last 10 per role), agent-discoveries.jsonl (error→fix pairs, dedup), agent-specializations.json (per-agent + per-role quality profiles)
+- **Timeline** (`timeline.js`) — historical metrics snapshots (30s intervals, max 2K), lifecycle events (spawn/complete/crash/kill/rotate with reason, max 500)
 
 **Services:**
 - **Skills** (`skills.js`) — skill marketplace management, API integration, local cache, auth tokens
@@ -226,9 +227,9 @@ GROOVE is a process manager, NOT a harness. Hard rules:
 - **Website:** groovedev.ai
 - **Docs:** docs.groovedev.ai
 
-## Current Status (v0.20.0)
+## Current Status (v0.27.0)
 
-Fully functional multi-agent orchestration system with complete GUI v2 rebuild. 29 daemon source files, 59 GUI components, 21+ CLI commands, 50+ API endpoints.
+Audit-driven release. Multi-agent orchestration system with 7 coordination layers: Journalist, Introducer/Knock Protocol, Rotator, Adaptive Thresholds, Token Tracker, Router/Classifier, and Persistent Agent Memory (new).
 
 **Key capabilities:**
 - GUI v2: VS Code-style layout, Tailwind CSS v4, Radix UI, zero inline styles
@@ -236,25 +237,29 @@ Fully functional multi-agent orchestration system with complete GUI v2 rebuild.
 - Agent panel: chat (bubble UI, mode pills), stats (canvas charts), controls (model swap, rotate, kill)
 - Marketplace: NFT-style skill cards, integrations, search, ratings
 - Editor: CodeMirror 6, file tree, terminal (xterm.js)
-- Dashboard: KPI sparklines, token/cost charts, fleet panel, savings breakdown
+- Dashboard: KPI sparklines, token/cost charts, fleet panel, savings breakdown, per-team burn panel
 - Quick Launch: planner recommends team, one-click spawns all agents
 - Chat continuation: reply to completed agents, streaming text, markdown rendering
 - Context chain: planner output flows automatically to builders
-- Journalist: zero cold-start, synthesis on completion, 40K char budget
-- Infinite Sessions: adaptive rotation, degradation detection
-- Token tracking: wired end-to-end, session metrics, savings data real
+- Journalist: zero cold-start, synthesis on completion, 40K char budget, synthesis tokens now tracked
+- Infinite Sessions: adaptive rotation, degradation detection, 5-min cooldown, converged-profile awareness
+- Token tracking: wired end-to-end, session metrics, cache-corrected hit rate, internal overhead segregated from user agents
 - Timeline: historical metrics snapshots, lifecycle events
-- Teams: live organizational groups with CRUD operations
-- Coordination: knock protocol, task negotiation, memory containment
+- Teams: live organizational groups with CRUD operations, per-team burn tracking
+- Coordination: enforced knock protocol via HTTP, task negotiation, scope locks
+- Safety: auto-rotate on token ceiling (5M) or velocity spike (1.5M/5min), scoped to agent instance
+- Persistent Memory (Layer 7): project constraints, handoff chains, error→fix discoveries, per-agent specializations — agent #50 knows what agent #1 learned
+- Mid-session classification: surfaces downshift suggestions, never silently downshifts
 - Federation: daemon-to-daemon pairing over Tailscale mesh
 - Scheduling: cron-based agent scheduling
 - Audit: append-only operation logging
 
 **Next steps:**
+- GUI: memory view (constraints/chains/discoveries tabs)
+- GUI: downshift suggestion pill in agent panel
+- Stress test: reproduce 275M burn with v0.27 to measure real improvements
 - Terminal multi-tab support
 - Marketplace detail modal for integrations
 - Dashboard: routing donut, cache panel, context health gauges
-- Settings view
 - Monitor/QC agent mode (stay active, loop)
-- Semantic degradation detection
 - Distribution: demo video, HN launch, Twitter content

package/node_modules/@groove-dev/cli/bin/groove.js

@@ -39,6 +39,7 @@ program
 program
   .command('stop')
   .description('Stop the GROOVE daemon')
+  .option('-f, --force', 'Stop even if agents are still running (destroys their work)')
   .action(stop);
 
 program
@@ -69,6 +70,7 @@ program
 program
   .command('nuke')
   .description('Kill all agents and stop the daemon')
+  .option('-f, --force', 'Required when agents are still running')
   .action(nuke);
 
 program

package/node_modules/@groove-dev/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groove-dev/cli",
-  "version": "0.11.0",
+  "version": "0.27.0",
   "description": "GROOVE CLI \u2014 manage AI coding agents from your terminal",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/node_modules/@groove-dev/cli/src/commands/nuke.js

@@ -4,14 +4,26 @@
 import chalk from 'chalk';
 import { apiCall } from '../client.js';
 
-export async function nuke() {
+export async function nuke(options = {}) {
+  let status;
+  try {
+    status = await apiCall('GET', '/api/status');
+  } catch {
+    console.log(chalk.yellow('No running daemon found.'));
+    return;
+  }
+
+  if (status.running > 0 && !options.force) {
+    console.error(chalk.red(`Refusing to nuke: ${status.running} agent(s) still running.`));
+    console.error(chalk.dim('  Nuke will kill every agent in every team and stop the daemon.'));
+    console.error(chalk.dim('  Re-run with "groove nuke --force" to confirm.'));
+    process.exit(1);
+  }
+
   try {
     console.log(chalk.yellow('Nuking all agents...'));
     await apiCall('DELETE', '/api/agents');
-
-    const status = await apiCall('GET', '/api/status');
     process.kill(status.pid, 'SIGTERM');
-
     console.log(chalk.green('All agents killed. Daemon stopped.'));
   } catch {
     console.log(chalk.yellow('No running daemon found.'));

package/node_modules/@groove-dev/cli/src/commands/stop.js

@@ -4,9 +4,24 @@
 import chalk from 'chalk';
 import { apiCall } from '../client.js';
 
-export async function stop() {
+export async function stop(options = {}) {
+  let status;
+  try {
+    status = await apiCall('GET', '/api/status');
+  } catch {
+    console.log(chalk.yellow('No running daemon found.'));
+    return;
+  }
+
+  if (status.running > 0 && !options.force) {
+    console.error(chalk.red(`Refusing to stop: ${status.running} agent(s) still running.`));
+    console.error(chalk.dim('  Stopping the daemon destroys all running agents in every team.'));
+    console.error(chalk.dim('  Kill specific agents first with "groove kill <id>",'));
+    console.error(chalk.dim('  or override with "groove stop --force".'));
+    process.exit(1);
+  }
+
   try {
-    const status = await apiCall('GET', '/api/status');
     process.kill(status.pid, 'SIGTERM');
     console.log(chalk.green('GROOVE daemon stopped.'));
   } catch {