groove-dev 0.27.211 → 0.27.212

package/CLAUDE.md

@@ -295,11 +295,3 @@ Audit-driven release. Multi-agent orchestration system with 7 coordination layer
 - Dashboard: routing donut, cache panel, context health gauges
 - Monitor/QC agent mode (stay active, loop)
 - Distribution: demo video, HN launch, Twitter content
-
-<!-- GROOVE:START -->
-## GROOVE Orchestration (auto-injected)
-Active agents: 0
-See AGENTS_REGISTRY.md for full agent state, the names of agents on other teams,
-and how to consult them directly (InnerChat).
-**Memory policy:** GROOVE manages project memory automatically. Do not read or write MEMORY.md or .groove/memory/ files directly.
-<!-- GROOVE:END -->

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.211",
+  "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.211",
+  "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/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/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 });

package/node_modules/@groove-dev/daemon/test/reach-hint.test.js

@@ -0,0 +1,100 @@
+// GROOVE — Agent reach hint (InnerChat discoverability)
+// FSL-1.1-Apache-2.0 — see LICENSE
+//
+// Spawn-prompt capabilities decay out of a long session, after which agents
+// deny they can contact anyone. These pin the per-turn hint that replaces it.
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { agentReachHint } from '../src/deliver.js';
+
+function daemonWith(agents, peers = []) {
+  return {
+    registry: { getAll: () => agents },
+    config: { innerchatPeers: peers },
+  };
+}
+
+const me = { name: 'fullstack-3', role: 'fullstack' };
+const roster = [me, { name: 'Integration-Manager', role: 'fullstack' }, { name: 'Axom-UX', role: 'frontend' }];
+
+describe('agentReachHint', () => {
+  it('always names the CLI verbs, even on an unrelated turn', () => {
+    const hint = agentReachHint(daemonWith(roster), me, 'refactor the token parser');
+    assert.match(hint, /groove ask/);
+    assert.match(hint, /groove who/);
+  });
+
+  it('rules out the built-in sub-agent tools that cannot reach GROOVE agents', () => {
+    const hint = agentReachHint(daemonWith(roster), me, 'anything');
+    assert.match(hint, /CANNOT reach them/i);
+  });
+
+  it('expands to a ready-to-run command naming the agent the user meant', () => {
+    const hint = agentReachHint(daemonWith(roster), me, 'ask Integration-Manager about the relay shape');
+    assert.match(hint, /groove ask Integration-Manager "your question here"/);
+    assert.doesNotMatch(hint, /<name>/, 'should not leave a placeholder to fill in');
+  });
+
+  it('falls back to the roster when intent is clear but the target is not', () => {
+    const hint = agentReachHint(daemonWith(roster), me, 'coordinate with the other agents on this');
+    assert.match(hint, /groove who/);
+    assert.match(hint, /Integration-Manager, Axom-UX/);
+  });
+
+  it('does not resolve a target from an ambiguous partial mention', () => {
+    const two = [me, { name: 'fullstack-1', role: 'x' }, { name: 'fullstack-2', role: 'x' }];
+    const hint = agentReachHint(daemonWith(two), me, 'ask fullstack about it');
+    assert.doesNotMatch(hint, /groove ask fullstack-1 "/);
+    assert.match(hint, /groove who/);
+  });
+
+  it('never suggests messaging yourself', () => {
+    const hint = agentReachHint(daemonWith(roster), me, 'ask fullstack-3 what it thinks');
+    assert.doesNotMatch(hint, /groove ask fullstack-3 "/);
+  });
+
+  it('mentions peer machines and the name@peer form when peers exist', () => {
+    const hint = agentReachHint(daemonWith(roster, [{ alias: 'spark' }]), me, 'ask someone about it');
+    assert.match(hint, /name@peer/);
+    assert.match(hint, /spark/);
+  });
+
+  it('stays silent when there is genuinely nobody to talk to', () => {
+    assert.equal(agentReachHint(daemonWith([me]), me, 'ask someone'), null);
+  });
+
+  // Naming the feature is an explicit request — the tier that must never rely
+  // on heuristics, because it is typically typed AFTER the agent has already
+  // claimed the capability does not exist.
+  it('re-sends the full reference when the user names InnerChat', () => {
+    for (const phrase of ['use innerChat', 'inner chat', 'inner-chat', 'InnerChat please', 'run groove ask']) {
+      const hint = agentReachHint({ port: 31415, ...daemonWith(roster) }, me, `${phrase} with the team`);
+      assert.match(hint, /Full reference/, `"${phrase}" should trigger the full block`);
+      assert.match(hint, /groove ask/);
+    }
+  });
+
+  it('tells the agent the feature is real when explicitly asked for it', () => {
+    const hint = agentReachHint({ port: 31415, ...daemonWith(roster) }, me, 'use innerchat');
+    assert.match(hint, /It exists, it is wired up/);
+    assert.match(hint, /Do not tell the user the feature is/);
+  });
+
+  it('still resolves the named target alongside the full reference', () => {
+    const hint = agentReachHint({ port: 31415, ...daemonWith(roster) }, me, 'use innerchat with Axom-UX');
+    assert.match(hint, /groove ask Axom-UX "your question here"/);
+    assert.match(hint, /Full reference/);
+  });
+
+  it('does not pay for the full reference on an ordinary turn', () => {
+    const hint = agentReachHint(daemonWith(roster), me, 'refactor the parser');
+    assert.doesNotMatch(hint, /Full reference/);
+    assert.ok(hint.length < 400, 'the always-on tier must stay cheap');
+  });
+
+  it('survives a broken registry rather than blocking delivery', () => {
+    const broken = { registry: { getAll() { throw new Error('boom'); } } };
+    assert.equal(agentReachHint(broken, me, 'ask someone'), null);
+  });
+});

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

@@ -0,0 +1,183 @@
+// GROOVE — TunnelManager Tests
+// FSL-1.1-Apache-2.0 — see LICENSE
+//
+// Regression coverage for wake-from-sleep recovery. The failure these guard
+// against: an SSH tunnel cut by a laptop sleep leaves a local listener that
+// still ACCEPTS TCP connections but never forwards them. A TCP-connect probe
+// calls that healthy, so the dead tunnel was handed out forever and the remote
+// GUI loaded a port that hung instead of failing — a black window that only a
+// full app restart cleared.
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { resolve } from 'path';
+import { createServer } from 'net';
+import { TunnelManager } from '../src/tunnel-manager.js';
+
+function makeDaemon(grooveDir) {
+  const broadcasts = [];
+  return {
+    broadcasts,
+    grooveDir,
+    projectDir: process.cwd(),
+    audit: { log() {} },
+    broadcast(m) { broadcasts.push(m); },
+  };
+}
+
+// A tunnel wedged by sleep: the socket is accepted and then ignored forever.
+function startWedgedListener() {
+  const sockets = [];
+  const server = createServer((sock) => { sockets.push(sock); });
+  return new Promise((res) => {
+    server.listen(0, '127.0.0.1', () => {
+      res({
+        port: server.address().port,
+        close: () => { for (const s of sockets) s.destroy(); server.close(); },
+      });
+    });
+  });
+}
+
+// A tunnel that works — answers /api/health like the remote daemon would.
+function startHealthyListener() {
+  const server = createServer((sock) => {
+    sock.on('data', () => {
+      const body = '{"ok":true}';
+      sock.end(
+        'HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n'
+        + `Content-Length: ${body.length}\r\nConnection: close\r\n\r\n${body}`,
+      );
+    });
+  });
+  return new Promise((res) => {
+    server.listen(0, '127.0.0.1', () => {
+      res({ port: server.address().port, close: () => server.close() });
+    });
+  });
+}
+
+describe('TunnelManager — wake-from-sleep recovery', () => {
+  let daemon, mgr, grooveDir;
+
+  beforeEach(() => {
+    grooveDir = mkdtempSync(resolve(tmpdir(), 'groove-tunnel-'));
+    daemon = makeDaemon(grooveDir);
+    mgr = new TunnelManager(daemon);
+  });
+
+  afterEach(() => {
+    mgr.shutdown();
+    try { rmSync(grooveDir, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  it('a TCP-accept probe cannot tell a wedged tunnel from a live one', async () => {
+    const wedged = await startWedgedListener();
+    try {
+      // This is what the old code trusted — and why the bug survived.
+      assert.equal(await mgr._isPortInUse(wedged.port), true);
+    } finally { wedged.close(); }
+  });
+
+  it('_tunnelResponds rejects a tunnel that accepts but never answers', async () => {
+    const wedged = await startWedgedListener();
+    try {
+      assert.equal(await mgr._tunnelResponds(wedged.port, 1500), false);
+    } finally { wedged.close(); }
+  });
+
+  it('_tunnelResponds accepts a tunnel that actually serves', async () => {
+    const live = await startHealthyListener();
+    try {
+      assert.equal(await mgr._tunnelResponds(live.port, 3000), true);
+    } finally { live.close(); }
+  });
+
+  it('connect() rebuilds instead of handing back a wedged tunnel', async () => {
+    const wedged = await startWedgedListener();
+    try {
+      mgr.saved.set('s19', {
+        id: 's19', name: 'S19 Agency', host: 'example.invalid',
+        user: 'ops', port: 22, lastConnected: new Date().toISOString(),
+      });
+      mgr.active.set('s19', {
+        pid: 999999, localPort: wedged.port, healthy: true, failCount: 0,
+        startedAt: new Date().toISOString(),
+      });
+
+      // Host is unreachable, so the rebuild fails — the point is that it TRIED
+      // rather than returning the dead port as if it were usable.
+      await assert.rejects(
+        () => mgr.connect('s19', { skipTest: false }),
+        (err) => !/^$/.test(err.message),
+      );
+      assert.equal(mgr.active.has('s19'), false, 'the dead tunnel was torn down');
+    } finally { wedged.close(); }
+  });
+
+  it('connect() reuses a tunnel that is genuinely alive', async () => {
+    const live = await startHealthyListener();
+    try {
+      mgr.saved.set('spark', { id: 'spark', name: 'DGX Spark', host: '10.0.0.5', user: 'rok', port: 22 });
+      mgr.active.set('spark', {
+        pid: 12345, localPort: live.port, healthy: true, failCount: 0,
+        startedAt: new Date().toISOString(),
+      });
+
+      const res = await mgr.connect('spark');
+      assert.equal(res.localPort, live.port, 'a working tunnel is reused, not rebuilt');
+      assert.equal(mgr.active.has('spark'), true);
+    } finally { live.close(); }
+  });
+
+  it('the health pass reaps a dead tunnel so the next connect starts clean', async () => {
+    const wedged = await startWedgedListener();
+    try {
+      mgr.saved.set('s19', { id: 's19', name: 'S19 Agency', host: 'example.invalid', user: 'ops', port: 22 });
+      mgr.active.set('s19', {
+        pid: 999999, localPort: wedged.port, healthy: true,
+        failCount: 99, // already past the failure limit
+        startedAt: new Date().toISOString(),
+      });
+
+      await mgr._healthCheckAll();
+
+      assert.equal(mgr.active.has('s19'), false, 'dead tunnel removed from active');
+      assert.ok(
+        daemon.broadcasts.some((b) => b.type === 'tunnel.unhealthy'),
+        'the GUI is told the tunnel went unhealthy',
+      );
+    } finally { wedged.close(); }
+  });
+
+  it('treats a long timer gap as a sleep and drops the failure tolerance', async () => {
+    const wedged = await startWedgedListener();
+    try {
+      mgr.saved.set('s19', { id: 's19', name: 'S19 Agency', host: 'example.invalid', user: 'ops', port: 22 });
+      mgr.active.set('s19', {
+        pid: 999999, localPort: wedged.port, healthy: true, failCount: 0,
+        startedAt: new Date().toISOString(),
+      });
+
+      // Last check was 10 minutes ago — the machine was asleep.
+      mgr._lastHealthCheck = Date.now() - 10 * 60 * 1000;
+      await mgr._healthCheckAll();
+
+      const conn = mgr.active.get('s19');
+      assert.equal(conn?.healthy, false, 'one failure after a sleep gap is enough');
+    } finally { wedged.close(); }
+  });
+
+  it('_waitForPortFree reports a released port', async () => {
+    const live = await startHealthyListener();
+    assert.equal(await mgr._waitForPortFree(live.port, 600), false, 'still held while listening');
+    live.close();
+    assert.equal(await mgr._waitForPortFree(live.port, 3000), true, 'free once closed');
+  });
+
+  it('_waitForExit returns true for a pid that does not exist', async () => {
+    assert.equal(await mgr._waitForExit(999999, 500), true);
+  });
+});

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

@@ -1,6 +1,6 @@
 {
   "name": "@groove-dev/gui",
-  "version": "0.27.211",
+  "version": "0.27.212",
   "description": "GROOVE GUI — visual agent control plane",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groove-dev",
-  "version": "0.27.211",
+  "version": "0.27.212",
   "description": "Open-source agent orchestration layer — the AI company OS. Local model agent engine (GGUF/Ollama/llama-server), HuggingFace model browser, MCP integrations (Slack, Gmail, Stripe, 15+), agent scheduling (cron), business roles (CMO, CFO, EA). GUI dashboard, multi-agent coordination, zero cold-start, infinite sessions. Works with Claude Code, Codex, Gemini CLI, Ollama, any local model.",
   "license": "FSL-1.1-Apache-2.0",
   "author": "Groove Dev <hello@groovedev.ai> (https://groovedev.ai)",

package/packages/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/packages/cli/package.json

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

package/packages/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/packages/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/packages/daemon/package.json

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

package/packages/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/packages/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/packages/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 });

package/packages/gui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groove-dev/gui",
-  "version": "0.27.211",
+  "version": "0.27.212",
   "description": "GROOVE GUI — visual agent control plane",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",