groove-dev 0.27.210 → 0.27.212

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

@@ -21,6 +21,7 @@ import { disconnect } from '../src/commands/disconnect.js';
 import { remotes } from '../src/commands/remotes.js';
 import { audit } from '../src/commands/audit.js';
 import { federationPair, federationUnpair, federationList, federationStatus } from '../src/commands/federation.js';
+import { ask, tell, who } from '../src/commands/ask.js';
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const { version } = require('../../../package.json');
@@ -74,6 +75,25 @@ program
   .option('-f, --force', 'Required when agents are still running')
   .action(nuke);
 
+// InnerChat — agent-to-agent messaging. Listed high in --help because an
+// agent that has lost the capability from context rediscovers it here.
+program
+  .command('ask <agent> <message>')
+  .description('Ask another agent a question and wait for their answer')
+  .option('--from <name>', 'your agent name (defaults to $GROOVE_AGENT_NAME)')
+  .action(ask);
+
+program
+  .command('tell <agent> <message>')
+  .description('Send another agent a message without waiting for a reply')
+  .option('--from <name>', 'your agent name (defaults to $GROOVE_AGENT_NAME)')
+  .action(tell);
+
+program
+  .command('who')
+  .description('List agents you can message with `groove ask` / `groove tell`')
+  .action(who);
+
 program
   .command('rotate <id>')
   .description('Rotate an agent (kill + respawn with fresh context)')

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

@@ -1,6 +1,6 @@
 {
   "name": "@groove-dev/cli",
-  "version": "0.27.210",
+  "version": "0.27.212",
   "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/client.js

@@ -33,8 +33,15 @@ export async function apiCall(method, path, body) {
   const res = await fetch(url, options);
 
   if (!res.ok) {
-    const err = await res.json().catch(() => ({ error: res.statusText }));
-    throw new Error(err.error || `HTTP ${res.status}`);
+    const body = await res.json().catch(() => ({ error: res.statusText }));
+    const err = new Error(body.error || `HTTP ${res.status}`);
+    // Carry the response body onto the error. The daemon's actionable fields
+    // (availableAgents, didYouMean, note) are the whole point of its error
+    // messages — dropping them leaves the caller with a dead end.
+    err.status = res.status;
+    err.body = body;
+    Object.assign(err, body);
+    throw err;
   }
 
   return res.json();

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

@@ -0,0 +1,99 @@
+// GROOVE CLI — InnerChat ask/tell/who
+// FSL-1.1-Apache-2.0 — see LICENSE
+//
+// Agent-to-agent messaging as first-class CLI verbs.
+//
+// The HTTP endpoints came first, and agents were taught them via a curl
+// snippet in the spawn prompt. That decays: on a long session the snippet
+// scrolls out of context and the agent no longer knows the capability exists,
+// or half-remembers it and reaches for a built-in tool that cannot see GROOVE
+// agents. A CLI verb survives that — an agent that has forgotten the details
+// can still run `groove --help` or simply guess `groove ask`, and the command
+// itself explains the rest.
+
+import chalk from 'chalk';
+import { apiCall } from '../client.js';
+
+// The caller is almost always an agent, and the daemon injects its identity
+// into the environment — so `--from` is a manual override, not a requirement.
+function resolveFrom(opts) {
+  const from = opts.from || process.env.GROOVE_AGENT_NAME;
+  if (!from) {
+    console.error(chalk.red('  Could not tell who is asking.'));
+    console.error(chalk.dim('  Pass --from <your-agent-name> (GROOVE_AGENT_NAME is unset — are you running outside an agent?)'));
+    process.exit(1);
+  }
+  return from;
+}
+
+function reportError(err, to) {
+  console.error(chalk.red('  Failed:'), err.message);
+  // The daemon returns actionable bodies (unknown name + roster, ambiguous
+  // name + candidates, exchange cap). Surface them rather than a bare status.
+  if (err.availableAgents?.length) {
+    console.error(chalk.dim(`  Agents you can reach: ${err.availableAgents.join(', ')}`));
+  }
+  if (err.didYouMean?.length) {
+    console.error(chalk.dim(`  "${to}" is ambiguous — did you mean: ${err.didYouMean.join(', ')}?`));
+  }
+  process.exit(1);
+}
+
+export async function ask(to, message, opts = {}) {
+  const from = resolveFrom(opts);
+  try {
+    console.error(chalk.dim(`  Asking ${to}… (this blocks until they answer — that is expected)`));
+    const res = await apiCall('POST', '/api/innerchat/ask', { from, to, message });
+    // The reply goes to stdout alone so it can be piped/read cleanly; the
+    // status chatter goes to stderr.
+    console.log(res.reply);
+    if (res.exchangesRemaining !== undefined) {
+      console.error(chalk.dim(`  (${res.exchangesRemaining} exchanges left in this conversation)`));
+    }
+  } catch (err) {
+    reportError(err, to);
+  }
+}
+
+export async function tell(to, message, opts = {}) {
+  const from = resolveFrom(opts);
+  try {
+    const res = await apiCall('POST', '/api/innerchat/tell', { from, to, message });
+    console.error(chalk.green('  Delivered.'), chalk.dim(res.note || `${to} will reply later if needed.`));
+  } catch (err) {
+    reportError(err, to);
+  }
+}
+
+// Who can I talk to? The question an agent asks first when it has lost the
+// roster from context — and the reason it otherwise starts guessing names.
+export async function who() {
+  try {
+    const me = process.env.GROOVE_AGENT_NAME;
+    const data = await apiCall('GET', '/api/agents');
+    const agents = Array.isArray(data) ? data : (data.agents || []);
+    const others = agents.filter((a) => a.name !== me);
+
+    if (!others.length) {
+      console.log(chalk.dim('  No other agents are running right now.'));
+    } else {
+      console.log(chalk.bold('  Agents you can message:'));
+      for (const a of others) {
+        const status = a.status === 'running' ? chalk.green('●') : chalk.dim('○');
+        console.log(`    ${status} ${chalk.bold(a.name)} ${chalk.dim(`(${a.role}${a.status !== 'running' ? `, ${a.status}` : ''})`)}`);
+      }
+    }
+
+    const peers = await apiCall('GET', '/api/innerchat/peers').catch(() => ({ peers: [] }));
+    if (peers.peers?.length) {
+      console.log(chalk.bold('\n  Peer machines (address as name@peer):'));
+      for (const p of peers.peers) console.log(`    ${chalk.bold('@' + p.alias)} ${chalk.dim(p.url)}`);
+    }
+
+    console.log(chalk.dim('\n  groove ask <name> "<question>"   — blocks until they answer'));
+    console.log(chalk.dim('  groove tell <name> "<message>"   — returns immediately'));
+  } catch (err) {
+    console.error(chalk.red('  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.210",
+  "version": "0.27.212",
   "description": "GROOVE daemon — agent orchestration engine",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/node_modules/@groove-dev/daemon/src/axom-connector.js

@@ -33,8 +33,16 @@ export const KNOWN_KINDS = Object.freeze([
   'narration', 'narration_dropped',
   'candidate_arrived', 'evidence_scored', 'champion_changed',
   'confidence_updated', 'verifier_verdict',
+  'resolution_delta', 'context_compile',
 ]);
 
+// Cosmetic, append-only chunks of an answer still being written. The terminal
+// `resolution` always follows with the authoritative text, so a delta is
+// worthless the moment it lands — keeping them would crowd the ring with
+// history that replay deliberately omits anyway (they are transient runtime
+// side, so a `?since` replay never returns them either).
+const TRANSIENT_KINDS = new Set(['resolution_delta']);
+
 const RING_SIZE = 4096;
 const SESSION_POLL_MS = 15000;
 const BACKOFF_BASE_MS = 1000;
@@ -243,13 +251,19 @@ export class AxomConnector {
       // Dedup on ring-buffer replay after reconnect — ids are monotonic.
       if (seq !== null && seq <= s.lastSeq) return;
       if (seq !== null) s.lastSeq = seq;
-      if (s.ring.length >= this.ringSize) {
-        s.ring.shift();
-        // The ring bounds memory, not delivery: overflow is counted, never
-        // silent, and every event still broadcasts — mirrors the runtime.
-        s.overflow += 1;
+      // Transient kinds broadcast but are never retained: they are superseded
+      // by a terminal event, and a backfilled tab must see the same history a
+      // reconnecting one does. `lastSeq` still advances above, so dedup and
+      // ordering are unaffected.
+      if (!TRANSIENT_KINDS.has(envelope.kind)) {
+        if (s.ring.length >= this.ringSize) {
+          s.ring.shift();
+          // The ring bounds memory, not delivery: overflow is counted, never
+          // silent, and every event still broadcasts — mirrors the runtime.
+          s.overflow += 1;
+        }
+        s.ring.push(envelope);
       }
-      s.ring.push(envelope);
       if (envelope.kind && !KNOWN_KINDS.includes(envelope.kind)) {
         s.unknownKinds[envelope.kind] = (s.unknownKinds[envelope.kind] || 0) + 1;
       }

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

@@ -141,21 +141,37 @@ export class ChatStore {
   }
 
   /**
-   * History for the GUI: live agents keyed by their CURRENT id (what the GUI
-   * looks up by), everything else under its stored name key so an agent
-   * respawned under the same name picks its history back up.
+   * History for the GUI: LIVE agents only, keyed by their current id (what the
+   * GUI looks up by). Buckets for agents that no longer exist stay on disk —
+   * a respawn under the same name picks them back up — but aren't shipped:
+   * they were 97% of a 5.6MB payload, which blew the browser's ~5MB
+   * localStorage quota and froze the local cache.
    */
   view() {
     const out = {};
-    const agents = this.daemon.registry?.getAll?.() || [];
-    const liveNames = new Map(agents.map((a) => [a.name, a.id]));
-    for (const [key, msgs] of Object.entries(this.history)) {
-      if (!Array.isArray(msgs) || !msgs.length) continue;
-      out[liveNames.get(key) || key] = msgs;
+    for (const agent of this.daemon.registry?.getAll?.() || []) {
+      const msgs = this.history[agent.name];
+      if (Array.isArray(msgs) && msgs.length) out[agent.id] = msgs;
     }
     return out;
   }
 
+  /**
+   * Drop the oldest buckets belonging to agents that no longer exist, so a
+   * long-lived daemon's store stays bounded. Live agents are never pruned.
+   */
+  prune(maxDeadBuckets = 200) {
+    const liveNames = new Set((this.daemon.registry?.getAll?.() || []).map((a) => a.name));
+    const dead = Object.keys(this.history)
+      .filter((k) => !liveNames.has(k))
+      .map((k) => [k, lastTs(this.history[k])])
+      .sort((x, y) => y[1] - x[1]);
+    if (dead.length <= maxDeadBuckets) return 0;
+    for (const [key] of dead.slice(maxDeadBuckets)) delete this.history[key];
+    this._scheduleSave();
+    return dead.length - maxDeadBuckets;
+  }
+
   getAll() {
     return this.history;
   }
@@ -178,18 +194,46 @@ export class ChatStore {
   }
 }
 
-// Union of two message arrays, deduped on (timestamp, from, text), time-sorted,
-// capped. Exported for tests and the migration path.
+function lastTs(msgs) {
+  return (Array.isArray(msgs) && msgs.length && msgs[msgs.length - 1]?.timestamp) || 0;
+}
+
+/**
+ * Union of two message arrays, time-sorted and capped.
+ *
+ * Messages carry a stable `id`. A streamed agent reply coalesces client-side
+ * into ONE growing message that keeps its id, so an id collision means "same
+ * message, later state" — we keep the longer text rather than accumulating a
+ * fragment per chunk. Messages without an id (older clients) fall back to a
+ * (timestamp, from, text) signature.
+ */
 export function mergeMessages(a, b) {
-  const seen = new Set();
+  const byId = new Map();
+  const bySig = new Set();
   const out = [];
+
   for (const m of [...(a || []), ...(b || [])]) {
     if (!m || typeof m !== 'object') continue;
+
+    if (m.id) {
+      const prev = byId.get(m.id);
+      if (!prev) {
+        byId.set(m.id, m);
+        out.push(m);
+      } else if (String(m.text || '').length > String(prev.text || '').length) {
+        // Same message, further along — replace in place.
+        out[out.indexOf(prev)] = m;
+        byId.set(m.id, m);
+      }
+      continue;
+    }
+
     const sig = `${m.timestamp}:${m.from}:${typeof m.text === 'string' ? m.text.slice(0, 200) : ''}`;
-    if (seen.has(sig)) continue;
-    seen.add(sig);
+    if (bySig.has(sig)) continue;
+    bySig.add(sig);
     out.push(m);
   }
+
   out.sort((x, y) => (x.timestamp || 0) - (y.timestamp || 0));
   return out.slice(-MAX_PER_AGENT);
 }

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

@@ -2,6 +2,7 @@
 
 import { wrapWithRoleReminder } from './process.js';
 import { getProvider } from './providers/index.js';
+import { innerChatInstructions } from './innerchat-docs.js';
 
 // Reviving a >5M-token claude session has crashed the CLI mid-HTTP-parse
 // (V8 fatal in JsonStringifier) — past this ceiling the rotator's handoff
@@ -42,7 +43,12 @@ export async function deliverInstruction(daemon, agentId, message, opts = {}) {
   // and the user's direction, not by how much context has piled up.
   const clock = daemon.processes.sessionClock?.(agent);
   const timedMessage = clock ? `${clock}\n\n${finalMessage}` : finalMessage;
-  const wrappedMessage = wrapWithRoleReminder(agent.role, timedMessage);
+  // Spawn-prompt capabilities scroll out of a long session, after which the
+  // agent denies it can reach other agents at all. This rides every turn, so
+  // it cannot decay — terse by default, expanded when the turn actually asks
+  // the agent to contact someone.
+  const reach = agentReachHint(daemon, agent, finalMessage);
+  const wrappedMessage = wrapWithRoleReminder(agent.role, reach ? `${reach}\n\n${timedMessage}` : timedMessage);
 
   // Agent loop path — send straight to the running loop.
   if (daemon.processes.hasAgentLoop(agentId)) {
@@ -132,3 +138,97 @@ async function respawn(daemon, config) {
     throw spawnErr;
   }
 }
+
+// Phrases that mean "go talk to another agent". Deliberately broad: a false
+// positive costs a few tokens of accurate instruction, a false negative costs
+// the user a turn spent watching their agent claim the capability isn't real.
+const CONTACT_INTENT = /\b(ask|message|msg|tell|consult|coordinate|check|sync|reach out|talk|speak|ping|liaise|confer|follow up|loop in)\b/i;
+
+// Naming the feature is an EXPLICIT request for it — usually typed after the
+// agent has already failed to find it. That earns the full instructions
+// verbatim, not a hint: no inference, no heuristic that can miss. Matches
+// innerchat / inner chat / inner-chat / InnerChat, and the CLI verbs by name.
+const INNERCHAT_KEYWORD = /\b(inner[\s_-]?chat|groove\s+(?:ask|tell|who))\b/i;
+
+/**
+ * A capability line appended to every delivered turn.
+ *
+ * Spawn-time instructions decay — on a long session (or under a model that
+ * compacts aggressively) they scroll away, and the agent then insists it has
+ * no way to contact anyone, or reaches for a built-in sub-agent tool that
+ * cannot see GROOVE agents. Two tiers:
+ *
+ *   - Always: one terse line naming the CLI verbs. ~20 tokens.
+ *   - When the turn expresses intent to contact someone: the exact command,
+ *     with the target's real name already filled in.
+ */
+export function agentReachHint(daemon, agent, message) {
+  let others;
+  try {
+    others = (daemon.registry.getAll() || []).filter((a) => a.name !== agent.name);
+  } catch { return null; }
+
+  const peers = Array.isArray(daemon.config?.innerchatPeers) ? daemon.config.innerchatPeers : [];
+  if (!others.length && !peers.length) return null;
+
+  const base = '[You can talk to other GROOVE agents: `groove ask <name> "<question>"` waits for their '
+    + 'answer, `groove tell <name> "<message>"` does not. `groove who` lists who is reachable. '
+    + 'Your own built-in sub-agent/task tools CANNOT reach them.]';
+
+  const explicit = INNERCHAT_KEYWORD.test(message);
+  if (!explicit && !CONTACT_INTENT.test(message)) return base;
+
+  // Name the agent the user is actually pointing at, so the model has a
+  // runnable command rather than a template it has to fill in from memory.
+  const lower = message.toLowerCase();
+  const named = others.filter((a) => lower.includes(a.name.toLowerCase()));
+  const target = named.length === 1 ? named[0] : null;
+
+  const lines = [
+    '[REACHING ANOTHER AGENT — this capability is real and available right now.]',
+  ];
+  if (explicit) {
+    // The user named the feature. Say plainly that it exists, since the usual
+    // failure is the agent asserting it doesn't and stopping there.
+    lines.push(
+      'The user explicitly asked you to use InnerChat. It exists, it is wired up, and the',
+      'commands below work from your shell right now. Do not tell the user the feature is',
+      'unavailable and do not ask them how to use it — run the command.',
+      '',
+    );
+  }
+  if (target) {
+    lines.push(
+      `To contact ${target.name}, run exactly:`,
+      `    groove ask ${target.name} "your question here"`,
+      'That blocks until they answer and prints their reply. Use `groove tell` instead if you '
+      + 'do not need the answer before continuing.',
+    );
+  } else {
+    lines.push(
+      '    groove who                         — list who is reachable',
+      '    groove ask <name> "<question>"     — blocks until they answer, prints the reply',
+      '    groove tell <name> "<message>"     — returns immediately',
+      `Agents reachable now: ${others.map((a) => a.name).join(', ') || '(none)'}`,
+    );
+  }
+  if (peers.length) {
+    lines.push(`Agents on peer machines use name@peer (peers: ${peers.map((p) => p.alias).join(', ')}).`);
+  }
+  lines.push(
+    'Do NOT use your built-in sub-agent/Task/SendMessage tools for this — they cannot see GROOVE '
+    + 'agents and will fail. If a name is wrong the command tells you the valid ones; read it and retry.',
+  );
+
+  // Explicit request → re-attach the full reference, so the agent has the
+  // complete semantics (blocking vs not, exchange budget, peer addressing)
+  // even if the spawn prompt scrolled away long ago.
+  if (explicit) {
+    lines.push(
+      '',
+      '--- Full reference (re-sent because you asked for InnerChat by name) ---',
+      ...innerChatInstructions(daemon.port || 31415, agent.name, peers),
+    );
+  }
+  return lines.join('\n');
+}

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

@@ -653,6 +653,8 @@ export class Daemon {
         try {
           const moved = this.chatStore.migrate();
           if (moved) console.log(`[chat] migrated ${moved} id-keyed histories to agent names`);
+          const pruned = this.chatStore.prune();
+          if (pruned) console.log(`[chat] pruned ${pruned} histories for long-gone agents`);
         } catch { /* best effort */ }
 
         // Regenerate the on-disk registry files once on boot. They otherwise

package/node_modules/@groove-dev/daemon/src/innerchat-docs.js

@@ -21,14 +21,26 @@ export function innerChatInstructions(port = 31415, agentName = 'YOUR_NAME', pee
     '',
     'Other GROOVE agents may be working alongside you, including on other teams.',
     'When the user asks you to reach out to, coordinate with, or get input from',
-    'another agent, use this — it sends them a message and waits for their reply:',
+    'another agent, use the `groove` CLI — it is already installed and on your PATH:',
     '',
-    '> **Do NOT use your built-in `SendMessage` / Agent tools to reach a GROOVE agent.**',
-    '> Those only address sub-agents you spawned yourself in this session, so they will',
-    '> fail with "not reachable" or ask you for an `a…-…` agent ID that does not exist',
-    '> here. GROOVE agents are separate processes. The curl below is the only way to',
-    '> reach them. Do not invent a fallback (writing a message into a file, etc.) —',
-    '> if the curl fails, read the error and report it to the user.',
+    '```bash',
+    'groove who                              # who can I reach right now?',
+    'groove ask <AGENT_NAME> "<QUESTION>"    # send + WAIT for their answer',
+    'groove tell <AGENT_NAME> "<MESSAGE>"    # send without waiting',
+    '```',
+    '',
+    '`groove ask` prints their reply to stdout. It knows who you are from your',
+    'environment, so there is no id or token to look up. If you get the name wrong,',
+    'the error lists the valid names — read it and retry rather than giving up.',
+    '',
+    '> **Do NOT use your built-in `SendMessage` / Task / sub-agent tools to reach a**',
+    '> **GROOVE agent.** Those only address sub-agents you spawned yourself in this',
+    '> session, so they will fail with "not reachable" or ask you for an `a…-…` agent',
+    '> ID that does not exist here. GROOVE agents are separate processes. Do not invent',
+    '> a fallback (writing a message into a file, etc.) — if the command fails, read the',
+    '> error and report it to the user.',
+    '',
+    'If the `groove` CLI is somehow unavailable, the same thing over HTTP:',
     '',
     '```bash',
     `curl -s http://localhost:${port}/api/innerchat/ask -X POST -H 'Content-Type: application/json' \\`,
@@ -54,6 +66,12 @@ export function innerChatInstructions(port = 31415, agentName = 'YOUR_NAME', pee
     'delivered back to you later, waking you if your turn has ended:',
     '',
     '```bash',
+    'groove tell <AGENT_NAME> "<MESSAGE>"',
+    '```',
+    '',
+    'Or over HTTP:',
+    '',
+    '```bash',
     `curl -s http://localhost:${port}/api/innerchat/tell -X POST -H 'Content-Type: application/json' \\`,
     `  -d '{"from":"${agentName}","to":"AGENT_NAME","message":"YOUR_MESSAGE"}'`,
     '```',

package/node_modules/@groove-dev/daemon/src/tunnel-manager.js

@@ -283,9 +283,19 @@ export class TunnelManager {
     const config = this.saved.get(id);
     if (!config) throw new Error(`Remote ${id} not found`);
 
+    // An existing entry is only reusable if the tunnel actually still carries
+    // traffic. After a laptop sleep the SSH client can survive with its forward
+    // dead: the local port still ACCEPTS connections but never forwards them, so
+    // handing this back returns a port that hangs forever instead of failing —
+    // which is what left the remote GUI on a black screen. Probe before reusing,
+    // and tear it down if it's a corpse.
     if (this.active.has(id)) {
       const existing = this.active.get(id);
-      return { localPort: existing.localPort, pid: existing.pid, name: config.name };
+      if (await this._tunnelResponds(existing.localPort)) {
+        return { localPort: existing.localPort, pid: existing.pid, name: config.name };
+      }
+      console.log(`[Groove:Tunnel] ${config.name}: existing tunnel is not responding — rebuilding`);
+      await this.disconnect(id);
     }
 
     this.daemon.broadcast({ type: 'tunnel.status', data: { id, step: 'testing' } });
@@ -432,11 +442,23 @@ export class TunnelManager {
     return { localPort, pid: tunnel.pid, name: config.name, url };
   }
 
+  // Does the tunnel actually serve a request, as opposed to merely holding an
+  // open listening socket? A wedged forward passes a TCP connect test but never
+  // answers, so only an HTTP round-trip proves it.
+  async _tunnelResponds(localPort, timeoutMs = HEALTH_TIMEOUT) {
+    try {
+      const res = await fetch(`http://localhost:${localPort}/api/health`, {
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      return res.ok;
+    } catch { return false; }
+  }
+
   async disconnect(id) {
     const conn = this.active.get(id);
     if (!conn) return;
 
-    const { pid } = conn;
+    const { pid, localPort } = conn;
     try {
       const cmd = execFileSync('ps', ['-p', String(pid), '-o', 'command='], {
         encoding: 'utf8',
@@ -444,9 +466,20 @@ export class TunnelManager {
       }).trim();
       if (cmd.includes('ssh')) {
         process.kill(pid, 'SIGTERM');
+        // An SSH client stuck on a dead TCP session can sit on SIGTERM long
+        // enough that the next connect() finds the port still bound. Give it a
+        // moment, then stop asking politely — otherwise the leftover listener
+        // keeps answering (and hanging) on the port we're about to reuse.
+        const gone = await this._waitForExit(pid, 3000);
+        if (!gone) {
+          try { process.kill(pid, 'SIGKILL'); } catch { /* already gone */ }
+          await this._waitForExit(pid, 2000);
+        }
       }
     } catch { /* process already dead */ }
 
+    if (localPort) await this._waitForPortFree(localPort, 3000);
+
     this.active.delete(id);
 
     const config = this.saved.get(id);
@@ -873,6 +906,26 @@ export class TunnelManager {
   }
 
   async _healthCheckAll() {
+    // Reaping now awaits process death, which can outlast the interval — don't
+    // let a second pass start on top of one already tearing a tunnel down.
+    if (this._healthRunning) return;
+    this._healthRunning = true;
+    try { await this._healthCheckPass(); } finally { this._healthRunning = false; }
+  }
+
+  async _healthCheckPass() {
+    // Timers don't fire while the machine is asleep, so an interval that should
+    // have run every HEALTH_INTERVAL arriving far later means we just woke up.
+    // Every tunnel is suspect at that point: verify them now rather than waiting
+    // for MAX_FAIL_COUNT normal cycles to notice.
+    const now = Date.now();
+    const gap = now - (this._lastHealthCheck || now);
+    this._lastHealthCheck = now;
+    const wokeFromSleep = gap > HEALTH_INTERVAL * 3;
+    if (wokeFromSleep && this.active.size > 0) {
+      console.log(`[Groove:Tunnel] Detected a ${Math.round(gap / 1000)}s gap (system sleep) — verifying tunnels`);
+    }
+
     for (const [id, conn] of this.active) {
       try {
         const start = Date.now();
@@ -889,9 +942,23 @@ export class TunnelManager {
         }
       } catch {
         conn.failCount = (conn.failCount || 0) + 1;
-        if (conn.failCount >= MAX_FAIL_COUNT) {
+        // After a sleep gap, one failure is enough — the tunnel was almost
+        // certainly cut with the network.
+        const limit = wokeFromSleep ? 1 : MAX_FAIL_COUNT;
+        if (conn.failCount >= limit) {
           conn.healthy = false;
           this.daemon.broadcast({ type: 'tunnel.unhealthy', data: { id } });
+
+          // Reap it. Previously a dead tunnel was only FLAGGED, so it stayed in
+          // `active` indefinitely and every later connect() handed back its dead
+          // port — the reason reconnecting never helped and only a full restart
+          // did. Removing it means the next connect() builds a real tunnel.
+          if (conn.failCount >= limit + 1) {
+            console.log(`[Groove:Tunnel] Reaping dead tunnel ${id} after ${conn.failCount} failed checks`);
+            this.daemon.broadcast({ type: 'tunnel.status', data: { id, step: 'reaping' } });
+            await this.disconnect(id);
+            continue;
+          }
         }
       }
       this.daemon.broadcast({
@@ -901,6 +968,25 @@ export class TunnelManager {
     }
   }
 
+  // Signal 0 only tests for existence — no signal is delivered.
+  async _waitForExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      try { process.kill(pid, 0); } catch { return true; } // gone
+      await new Promise((r) => setTimeout(r, 150));
+    }
+    try { process.kill(pid, 0); return false; } catch { return true; }
+  }
+
+  async _waitForPortFree(port, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (!(await this._isPortInUse(port))) return true;
+      await new Promise((r) => setTimeout(r, 200));
+    }
+    return !(await this._isPortInUse(port));
+  }
+
   _isPortInUse(port) {
     return new Promise((resolve) => {
       const conn = createConnection({ host: '127.0.0.1', port });