groove-dev 0.27.213 → 0.27.215

package/CLAUDE.md

@@ -134,6 +134,7 @@ groove agents             — list agents
 groove status             — daemon status
 groove nuke               — kill all + stop
 groove rotate <id>        — context rotation (kill + respawn with handoff brief)
+groove handoff <id>       — succession: fresh agent interviews this one via InnerChat, then takes over
 groove team create <name> — create a new team
 groove team rename <id>   — rename a team
 groove team list          — list teams
@@ -167,6 +168,7 @@ All endpoints on `http://localhost:31415/api/`. CORS restricted to localhost. 50
 | Health | GET | /api/health, /api/status | Health check, daemon status |
 | Agents | GET/POST/DELETE | /api/agents, /api/agents/:id | Agent CRUD, detail, update |
 | Agent Actions | POST | /api/agents/:id/rotate, instruct, query | Rotation, instructions, queries |
+| Succession | POST | /api/agents/:id/handoff, /api/handoff/:id/complete | Spawn successor + interview, retire predecessor |
 | Agent Routing | GET | /api/agents/:id/routing/recommend | Model routing recommendations |
 | Teams | GET/POST | /api/teams | List, create teams |
 | Teams | PATCH/DELETE | /api/teams/:id | Rename, delete teams |

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

@@ -12,6 +12,7 @@ import { agents } from '../src/commands/agents.js';
 import { status } from '../src/commands/status.js';
 import { nuke } from '../src/commands/nuke.js';
 import { rotate } from '../src/commands/rotate.js';
+import { handoff } from '../src/commands/handoff.js';
 import { teamCreate, teamSave, teamLoad, teamList, teamDelete, teamRename, teamExport, teamImport } from '../src/commands/team.js';
 import { approvals, approve, reject } from '../src/commands/approve.js';
 import { providers, setKey } from '../src/commands/providers.js';
@@ -99,6 +100,13 @@ program
   .description('Rotate an agent (kill + respawn with fresh context)')
   .action(rotate);
 
+program
+  .command('handoff <id>')
+  .description('Succession: spawn a fresh agent that interviews this one, then takes over')
+  .option('--name <name>', 'successor name (default: <agent>-successor)')
+  .option('--no-keep-name', 'successor keeps its own name instead of inheriting')
+  .action(handoff);
+
 // Teams
 const team = program.command('team').description('Manage agent teams');
 team.command('create <name>').description('Create a new team').action(teamCreate);

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

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

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

@@ -0,0 +1,22 @@
+// GROOVE CLI — handoff command (succession to a fresh agent)
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import chalk from 'chalk';
+import { apiCall } from '../client.js';
+
+export async function handoff(id, options = {}) {
+  try {
+    console.log(chalk.yellow(`  Preparing succession dossier for ${id}...`));
+    const record = await apiCall('POST', `/api/agents/${id}/handoff`, {
+      name: options.name,
+      inheritName: options.keepName !== false,
+    });
+    console.log(chalk.green(`  Succession started.`));
+    console.log(`  ${chalk.bold(record.successorName)} is interviewing ${chalk.bold(record.predecessorName)} over InnerChat.`);
+    console.log(`  When done it will retire the predecessor${record.inheritName ? ` and take over the name "${record.predecessorName}"` : ''}.`);
+    console.log(chalk.dim(`  Handoff id: ${record.id}`));
+  } catch (err) {
+    console.error(chalk.red('  Handoff failed:'), err.message);
+    process.exit(1);
+  }
+}

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

@@ -1,6 +1,6 @@
 {
   "name": "@groove-dev/daemon",
-  "version": "0.27.213",
+  "version": "0.27.215",
   "description": "GROOVE daemon — agent orchestration engine",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

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

@@ -4,7 +4,8 @@
 import { createServer as createHttpServer, request as httpProxyRequest } from 'http';
 import { createServer as createNetServer } from 'net';
 import { execFileSync } from 'child_process';
-import { resolve } from 'path';
+import { resolve, dirname, basename } from 'path';
+import { homedir } from 'os';
 import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync, readdirSync, rmdirSync, rmSync, statSync } from 'fs';
 import express from 'express';
 import { WebSocketServer } from 'ws';
@@ -630,6 +631,22 @@ export class Daemon {
         // Read back actual port (critical for port 0 / dynamic allocation)
         this.port = this.server.address().port;
         writeFileSync(this.pidFile, String(process.pid));
+
+        // Anchor for restart tooling. grooveDir — the daemon's entire world of
+        // teams/agents/state — is derived from the cwd `groove start` ran in.
+        // Remote restart paths (tunnel autoStart, upgrades, the desktop shell)
+        // each guess a cwd; a wrong guess boots a fresh empty .groove that
+        // looks exactly like total data loss. Record where this world lives at
+        // a FIXED path so every restarter can re-enter it instead of guessing.
+        // Staging/override daemons (custom GROOVE_DIR) skip this — they must
+        // not hijack the anchor of the real daemon.
+        try {
+          if (basename(this.grooveDir) === '.groove') {
+            const anchorHome = resolve(homedir(), '.groove');
+            mkdirSync(anchorHome, { recursive: true });
+            writeFileSync(resolve(anchorHome, 'last-run-dir'), dirname(this.grooveDir));
+          }
+        } catch { /* non-fatal */ }
         // Write actual port and host so CLI can find us
         writeFileSync(resolve(this.grooveDir, 'daemon.port'), String(this.port));
         writeFileSync(resolve(this.grooveDir, 'daemon.host'), this.host);

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

@@ -1057,6 +1057,34 @@ export class Journalist {
     return brief;
   }
 
+  /**
+   * Succession dossier — the deep version of the handoff brief, for handing a
+   * long-lived agent's role to a NEW agent. The regular brief is recency-biased
+   * by design (last 3 chain entries, current session); after weeks of work the
+   * older accumulated knowledge matters just as much. The dossier adds the full
+   * handoff chain and the project decision log, and its reader is expected to
+   * fill remaining gaps by interviewing the predecessor directly.
+   */
+  async generateSuccessionDossier(agent) {
+    const brief = await this.generateHandoffBrief(agent, { reason: 'succession' });
+
+    // The whole chain (up to the retained 10 generations), not the last 3.
+    const fullChain = this.daemon.memory?.getRecentHandoffMarkdown(
+      agent.role, 10, 12000, agent.workingDir, agent.teamId,
+    ) || '';
+
+    let decisions = '';
+    try {
+      const p = resolve(this.daemon.projectDir, 'GROOVE_DECISIONS.md');
+      if (existsSync(p)) decisions = readFileSync(p, 'utf8').slice(0, 8000);
+    } catch { /* optional */ }
+
+    const parts = [brief];
+    if (fullChain) parts.push(`## Full Rotation History (oldest knowledge — read it, it is why things are the way they are)\n\n${fullChain}`);
+    if (decisions) parts.push(`## Project Decision Log\n\n${decisions}`);
+    return parts.join('\n\n');
+  }
+
   // --- Conversation Thread Extraction (for idle resume) ---
 
   /**

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

@@ -4,7 +4,9 @@
 import { EventEmitter } from 'events';
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { resolve } from 'path';
+import { randomUUID } from 'crypto';
 import { getProvider } from './providers/index.js';
+import { deliverInstruction } from './deliver.js';
 
 const DEFAULT_THRESHOLD = 0.65;      // For non-self-managing providers (was 0.75)
 const HARD_CEILING = 0.80;           // Force rotate (was 0.85) — only for non-self-managing
@@ -40,6 +42,7 @@ export class Rotator extends EventEmitter {
     this.interval = null;
     this.rotationHistory = [];
     this.rotating = new Set();
+    this.handoffs = new Map(); // handoffId -> { predecessorId, successorId, status, ... }
     this.lastRotationTime = new Map(); // agentId -> timestamp of last rotation
     this._lastContextState = new Map(); // agentId -> { contextUsage, timestamp }
     this.compactionCounts = new Map(); // agentId -> number of natural compactions
@@ -638,6 +641,182 @@ export class Rotator extends EventEmitter {
     }
   }
 
+  // ── Succession handoff ─────────────────────────────────────────
+  //
+  // Rotation replaces an agent with a same-name clone and is recency-biased —
+  // right for context pressure, wrong for retiring a long-lived agent. A
+  // succession spawns the successor ALONGSIDE the still-running predecessor,
+  // seeded with a deep dossier, and mandates an InnerChat interview before the
+  // predecessor is retired. The interview is the point: after weeks of work
+  // the highest-bandwidth transfer is questions answered by the agent that
+  // still remembers, not any summary.
+
+  async successionHandoff(agentId, options = {}) {
+    const registry = this.daemon.registry;
+    const agent = registry.get(agentId);
+    if (!agent) throw new Error('Agent not found');
+    if (this.rotating.has(agentId)) throw new Error('Agent is mid-rotation — try again shortly');
+    for (const h of this.handoffs.values()) {
+      if (h.status === 'interviewing' && (h.predecessorId === agentId || h.successorId === agentId)) {
+        throw new Error('A handoff is already in progress for this agent');
+      }
+    }
+
+    const handoffId = randomUUID().slice(0, 12);
+    const dossier = await this.daemon.journalist.generateSuccessionDossier(agent);
+
+    // Persist to the chain up front — even a failed handoff leaves the record.
+    if (this.daemon.memory) {
+      this.daemon.memory.appendHandoffBrief(agent.role, {
+        timestamp: new Date().toISOString(),
+        agentId: agent.id,
+        newAgentId: null,
+        reason: 'succession',
+        oldTokens: agent.tokensUsed,
+        contextUsage: agent.contextUsage,
+        brief: dossier.slice(0, 6000),
+      }, agent.workingDir, agent.teamId);
+    }
+
+    const inheritName = options.inheritName !== false;
+    const successorName = (options.name && String(options.name).trim())
+      || `${agent.name}-successor`;
+    const port = this.daemon.port || 31415;
+
+    const prompt = [
+      `# SUCCESSION — you are taking over from ${agent.name}`,
+      ``,
+      `${agent.name} has been working this role for a long time and is being retired`,
+      `for context degradation. You are its successor. Its accumulated knowledge is`,
+      `below; its live memory is still available for a short window — use it.`,
+      ``,
+      dossier,
+      ``,
+      `## Step 1 — Interview your predecessor (do this FIRST)`,
+      ``,
+      `${agent.name} is still running and has been told to expect your questions.`,
+      `Ask via InnerChat (blocking; run in the foreground):`,
+      ``,
+      '```bash',
+      `curl -s http://localhost:${port}/api/innerchat/ask -X POST -H 'Content-Type: application/json' \\`,
+      `  -d '{"from":"${successorName}","to":"${agent.name}","message":"YOUR_QUESTION"}'`,
+      '```',
+      ``,
+      `Ask about: work currently in flight and exactly where it stands; fragile or`,
+      `dangerous areas; unwritten conventions the dossier missed; what it planned to`,
+      `do next and why. Several focused rounds beat one broad one. The exchange`,
+      `budget is shared — stop when answers stop teaching you.`,
+      ``,
+      `## Step 2 — Declare takeover`,
+      ``,
+      `When you have what you need (interview done or predecessor unresponsive):`,
+      ``,
+      '```bash',
+      `curl -s -X POST http://localhost:${port}/api/handoff/${handoffId}/complete`,
+      '```',
+      ``,
+      `This retires ${agent.name}${inheritName ? ` and renames you to "${agent.name}"` : ''}. Then continue the work — you own it now.`,
+      `Do NOT start new work before completing both steps.`,
+    ].join('\n');
+
+    const successor = await this.daemon.processes.spawn({
+      role: agent.role,
+      scope: agent.scope,
+      provider: options.provider || agent.provider,
+      model: options.model || agent.model,
+      prompt,
+      permission: agent.permission || 'full',
+      workingDir: agent.workingDir,
+      name: successorName,
+      teamId: agent.teamId,
+    });
+
+    // Survives a daemon restart: /complete can reconstruct from this metadata.
+    registry.update(successor.id, {
+      metadata: {
+        ...(successor.metadata || {}),
+        handoff: { handoffId, predecessorId: agent.id, predecessorName: agent.name, inheritName },
+      },
+    });
+
+    const record = {
+      id: handoffId,
+      predecessorId: agent.id,
+      predecessorName: agent.name,
+      successorId: successor.id,
+      successorName: successor.name || successorName,
+      inheritName,
+      status: 'interviewing',
+      startedAt: new Date().toISOString(),
+    };
+    this.handoffs.set(handoffId, record);
+
+    // Heads-up to the predecessor — best effort; InnerChat will wake it anyway.
+    deliverInstruction(this.daemon, agent.id,
+      `[Succession] ${record.successorName} is taking over your role. It will interview you `
+      + `over InnerChat shortly. Answer its questions completely and concretely — in-flight work, `
+      + `fragile areas, unwritten conventions, planned next steps. Do NOT start new work. `
+      + `Anything only you know must get said now; after the interview you will be retired.`,
+      { recordFeedback: false },
+    ).catch((err) => console.warn(`  Rotator: could not brief predecessor ${agent.name}: ${err.message}`));
+
+    this.daemon.audit?.log('agent.handoff.start', { handoffId, predecessor: agent.id, successor: successor.id });
+    this.daemon.broadcast({ type: 'handoff:started', data: record });
+    if (this.daemon.timeline) {
+      this.daemon.timeline.recordEvent('handoff', {
+        agentId: successor.id, oldAgentId: agent.id,
+        agentName: record.successorName, role: agent.role, reason: 'succession',
+      });
+    }
+    return record;
+  }
+
+  async completeHandoff(handoffId) {
+    const registry = this.daemon.registry;
+    let record = this.handoffs.get(handoffId);
+    if (!record) {
+      // Daemon restarted mid-handoff — reconstruct from successor metadata.
+      const successor = registry.getAll().find((a) => a.metadata?.handoff?.handoffId === handoffId);
+      if (!successor) throw new Error('Handoff not found');
+      const h = successor.metadata.handoff;
+      record = {
+        id: handoffId, predecessorId: h.predecessorId, predecessorName: h.predecessorName,
+        successorId: successor.id, successorName: successor.name,
+        inheritName: h.inheritName, status: 'interviewing', startedAt: null,
+      };
+    }
+    if (record.status === 'complete') return record;
+
+    const successor = registry.get(record.successorId);
+    if (!successor) throw new Error('Successor no longer exists — cannot complete handoff');
+
+    const predecessor = registry.get(record.predecessorId);
+    if (predecessor) {
+      try { await this.daemon.processes.kill(predecessor.id); } catch { /* already dead */ }
+      registry.remove(predecessor.id);
+      this.daemon.locks?.release(predecessor.id);
+    }
+
+    if (record.inheritName && predecessor) {
+      registry.update(successor.id, { name: record.predecessorName });
+      record.successorName = record.predecessorName;
+    }
+    // Clear the marker — the successor is now just a normal agent.
+    const meta = { ...(successor.metadata || {}) };
+    delete meta.handoff;
+    registry.update(successor.id, { metadata: meta });
+
+    record.status = 'complete';
+    record.completedAt = new Date().toISOString();
+    this.handoffs.set(handoffId, record);
+
+    this.daemon.audit?.log('agent.handoff.complete', {
+      handoffId, predecessor: record.predecessorId, successor: record.successorId,
+    });
+    this.daemon.broadcast({ type: 'handoff:completed', data: record });
+    return record;
+  }
+
   _schedulePostRotationCheck(newAgentId, oldQualityScore, record) {
     // Wait for the new agent to accumulate MIN_EVENTS classifier events,
     // checking every 15s for up to 5 minutes (20 checks)

package/node_modules/@groove-dev/daemon/src/routes/agents.js

@@ -246,6 +246,31 @@ export function registerAgentRoutes(app, daemon) {
     }
   });
 
+  // Succession handoff — spawn a fresh successor alongside a degrading agent,
+  // seeded with a deep dossier; it interviews the predecessor over InnerChat,
+  // then calls /api/handoff/:id/complete to retire it and take over.
+  app.post('/api/agents/:id/handoff', async (req, res) => {
+    try {
+      const { name, inheritName, model, provider } = req.body || {};
+      const record = await daemon.rotator.successionHandoff(req.params.id, {
+        name, inheritName, model, provider,
+      });
+      res.json(record);
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  // Called by the successor itself when it has finished interviewing.
+  app.post('/api/handoff/:handoffId/complete', async (req, res) => {
+    try {
+      const record = await daemon.rotator.completeHandoff(req.params.handoffId);
+      res.json(record);
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
   // Instruct an agent — send message to agent loop, resume session, or rotate
   // Agent loop = direct message to running loop (local models)
   // Resume = zero cold-start (uses --resume SESSION_ID)