groove-dev 0.27.198 → 0.27.199

package/packages/daemon/src/axom-remote.js

@@ -0,0 +1,230 @@
+// GROOVE — Axom Remote Runtime Control (SSH)
+// FSL-1.1-Apache-2.0 — see LICENSE
+//
+// Start and stop an `axom serve` on a machine you own, over SSH, from the
+// GROOVE that talks to it. Deliberately MANUAL: nothing here auto-starts, and
+// nothing supervises or restarts a runtime that stops. The user decides when
+// the workhorse is working (Ryan, 2026-07-25: "I will turn it off and on as I
+// need... I just need the control").
+//
+// Only ever runs commands the user configured, on a host the user configured,
+// with their own SSH credentials. GROOVE holds no keys of its own.
+
+import { execFile, spawn } from 'child_process';
+import { AXOM_DEFAULT_PORT } from './axom-connector.js';
+
+const SSH_OPTS = [
+  '-o', 'ConnectTimeout=8',
+  '-o', 'StrictHostKeyChecking=accept-new',
+  '-o', 'BatchMode=yes',
+];
+
+function validateHost(host) {
+  // Hostname or IP only — no user@, no flags, no shell metacharacters. The
+  // value reaches execFile as a single argv entry, never a shell string.
+  return typeof host === 'string' && /^[a-zA-Z0-9._-]{1,253}$/.test(host);
+}
+
+function validateUser(user) {
+  return typeof user === 'string' && /^[a-zA-Z0-9._-]{1,32}$/.test(user);
+}
+
+export function validateRemote(remote) {
+  if (!remote || typeof remote !== 'object') return 'remote config must be an object';
+  if (!validateHost(remote.host)) return 'invalid host';
+  if (!validateUser(remote.user)) return 'invalid user';
+  if (remote.sshPort !== undefined && !(Number.isInteger(remote.sshPort) && remote.sshPort > 0 && remote.sshPort < 65536)) {
+    return 'invalid sshPort';
+  }
+  if (remote.port !== undefined && !(Number.isInteger(remote.port) && remote.port > 0 && remote.port < 65536)) {
+    return 'invalid port';
+  }
+  if (remote.command !== undefined && (typeof remote.command !== 'string' || remote.command.length > 500)) {
+    return 'command must be a string of at most 500 chars';
+  }
+  return null;
+}
+
+export class AxomRemote {
+  constructor(daemon, opts = {}) {
+    this.daemon = daemon;
+    this.exec = opts.exec || execFile; // tests inject
+  }
+
+  _config() {
+    return this.daemon.config?.axom?.remote || null;
+  }
+
+  _ssh(command, timeoutMs = 30000) {
+    const cfg = this._config();
+    if (!cfg) return Promise.reject(new Error('no remote Axom host configured'));
+    const problem = validateRemote(cfg);
+    if (problem) return Promise.reject(new Error(`remote config invalid: ${problem}`));
+
+    const args = [...SSH_OPTS, '-p', String(cfg.sshPort || 22), `${cfg.user}@${cfg.host}`, command];
+    return new Promise((resolve, reject) => {
+      this.exec('ssh', args, { encoding: 'utf8', timeout: timeoutMs }, (err, stdout, stderr) => {
+        if (err && !stdout) return reject(new Error((stderr || err.message || '').trim().split('\n').pop()));
+        resolve({ stdout: String(stdout || ''), stderr: String(stderr || '') });
+      });
+    });
+  }
+
+  // Is a runtime listening on the remote port right now?
+  async status() {
+    const cfg = this._config();
+    if (!cfg) return { configured: false, running: null };
+    const port = cfg.port || AXOM_DEFAULT_PORT;
+    try {
+      const { stdout } = await this._ssh(
+        `curl -sf --max-time 4 http://127.0.0.1:${port}/about >/dev/null 2>&1 && echo UP || echo DOWN`,
+        15000,
+      );
+      return {
+        configured: true,
+        host: cfg.host,
+        user: cfg.user,
+        port,
+        running: stdout.includes('UP'),
+        error: null,
+      };
+    } catch (err) {
+      // Unreachable host is not "not running" — we genuinely do not know.
+      return { configured: true, host: cfg.host, user: cfg.user, port, running: null, error: err.message };
+    }
+  }
+
+  async start() {
+    const cfg = this._config();
+    if (!cfg) throw new Error('no remote Axom host configured');
+    const port = cfg.port || AXOM_DEFAULT_PORT;
+    const already = await this.status();
+    if (already.running) return { started: false, alreadyRunning: true, port };
+
+    const command = cfg.command
+      || `axom serve --port ${port} --data-dir ~/axom-serve/data --model-dir ~/axom-serve/models`;
+    // Detached from this SSH session so it survives the connection closing.
+    // No supervisor, no restart-on-exit: manual control means manual.
+    const log = cfg.logPath || '~/axom-serve/serve.log';
+    await this._ssh(`nohup ${command} >> ${log} 2>&1 < /dev/null & disown; echo STARTED`, 30000);
+
+    // Confirm it actually came up rather than reporting optimism.
+    for (let i = 0; i < 30; i++) {
+      await new Promise((r) => setTimeout(r, 2000));
+      const s = await this.status();
+      if (s.running) {
+        this.daemon.audit.log('axom.remote.start', { host: cfg.host, port });
+        this._broadcast();
+        return { started: true, port, logPath: log };
+      }
+    }
+    throw new Error(`started the command but nothing answered on port ${port} within 60s — check ${log} on ${cfg.host}`);
+  }
+
+  async stop({ force = false } = {}) {
+    const cfg = this._config();
+    if (!cfg) throw new Error('no remote Axom host configured');
+    const port = cfg.port || AXOM_DEFAULT_PORT;
+
+    // Prefer the contract's own verb (§14): it flushes the ledger and
+    // releases the lockfile. Fall back to a signal only if the runtime
+    // predates the verb.
+    try {
+      const { stdout } = await this._ssh(
+        `curl -s -o /dev/null -w '%{http_code}' --max-time 8 -X POST `
+        + `-H 'Content-Type: application/json' -d '{"force":${force ? 'true' : 'false'}}' `
+        + `http://127.0.0.1:${port}/shutdown`,
+        20000,
+      );
+      const code = parseInt(stdout.trim().slice(-3), 10);
+      if (code === 202) {
+        this.daemon.audit.log('axom.remote.stop', { host: cfg.host, port, via: 'shutdown' });
+        this._broadcast();
+        return { stopped: true, via: 'shutdown' };
+      }
+      if (code === 409) return { stopped: false, turnInFlight: true };
+      if (code !== 404) throw new Error(`shutdown returned HTTP ${code}`);
+    } catch (err) {
+      if (!/HTTP 404/.test(err.message)) throw err;
+    }
+
+    // Pre-§14 runtime: signal the process that owns the port. Still the
+    // user's own machine, still an explicit action they asked for.
+    await this._ssh(`PID=$(lsof -t -i:${port} 2>/dev/null | head -1); [ -n "$PID" ] && kill $PID && echo KILLED || echo NOTFOUND`, 20000);
+    this.daemon.audit.log('axom.remote.stop', { host: cfg.host, port, via: 'signal' });
+    this._broadcast();
+    return { stopped: true, via: 'signal' };
+  }
+
+  // ── Reachability (the port-forward), distinct from runtime lifecycle ──────
+  //
+  // The runtime is the user's workhorse and is never touched automatically.
+  // The TUNNEL is plumbing: it dies on every sleep/wake (ssh's keepalive exits
+  // on resume and nothing respawns it), costs the remote machine nothing, and
+  // its death looks identical to "Axom is down" from the GUI. So we heal it on
+  // demand — but only ever a tunnel GROOVE opened, and only after a health
+  // check proves the port is genuinely dead (an unconditional teardown kills
+  // slow-but-working tunnels — learned by fullstack-3 the hard way).
+
+  async _portAnswers(port, timeoutMs = 2500) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/about`, { signal: AbortSignal.timeout(timeoutMs) });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  async ensureTunnel() {
+    const cfg = this._config();
+    if (!cfg) return { tunneled: false, reason: 'no remote configured' };
+    const problem = validateRemote(cfg);
+    if (problem) return { tunneled: false, reason: problem };
+    const port = cfg.port || AXOM_DEFAULT_PORT;
+
+    if (await this._portAnswers(port)) return { tunneled: true, healed: false, port };
+
+    // Port is genuinely dead. If a tunnel process of ours is lingering, drop
+    // it before opening another (a stale forward holds the local port and the
+    // new ssh would fail with "address already in use").
+    if (this._tunnelProc && !this._tunnelProc.killed) {
+      try { this._tunnelProc.kill(); } catch { /* already gone */ }
+      this._tunnelProc = null;
+    }
+
+    const args = [
+      '-N', '-L', `127.0.0.1:${port}:localhost:${port}`,
+      ...SSH_OPTS,
+      '-o', 'ServerAliveInterval=30',
+      '-o', 'ExitOnForwardFailure=yes',
+      '-p', String(cfg.sshPort || 22),
+      `${cfg.user}@${cfg.host}`,
+    ];
+    const proc = spawn('ssh', args, { stdio: 'ignore', detached: false });
+    this._tunnelProc = proc;
+    proc.on('exit', () => { if (this._tunnelProc === proc) this._tunnelProc = null; });
+
+    for (let i = 0; i < 10; i++) {
+      await new Promise((r) => setTimeout(r, 500));
+      if (await this._portAnswers(port, 1500)) {
+        this.daemon.audit.log('axom.remote.tunnel', { host: cfg.host, port });
+        return { tunneled: true, healed: true, port };
+      }
+      if (proc.exitCode !== null) break;
+    }
+    // Honest failure: the forward may be up while the runtime is down — say
+    // what we know (port silent) rather than asserting a cause.
+    return { tunneled: false, healed: false, port, reason: `nothing answers on 127.0.0.1:${port} after opening the forward — the runtime may be stopped` };
+  }
+
+  closeTunnel() {
+    if (this._tunnelProc && !this._tunnelProc.killed) {
+      try { this._tunnelProc.kill(); } catch { /* already gone */ }
+    }
+    this._tunnelProc = null;
+  }
+
+  _broadcast() {
+    this.status().then((s) => this.daemon.broadcast({ type: 'axom:remote', data: s })).catch(() => {});
+  }
+}

package/packages/daemon/src/axom-server.js

@@ -56,6 +56,7 @@ export class AxomServerManager {
     this.daemon = daemon;
     this.command = opts.command || null; // resolved lazily from config
     this.totalRamGbOverride = opts.totalRamGb; // tests inject; prod reads os
+    this.portBase = opts.portBase || AXOM_DEFAULT_PORT;
     this.instances = new Map(); // id -> {id, proc, port, dataDir, status, startedAt, error}
   }
 
@@ -73,7 +74,7 @@ export class AxomServerManager {
     for (const ep of this.daemon.axom?.endpoints?.values?.() || []) {
       try { used.add(Number(new URL(ep.url).port)); } catch { /* non-numeric */ }
     }
-    let port = AXOM_DEFAULT_PORT;
+    let port = this.portBase;
     while (used.has(port)) port += 1;
     return port;
   }
@@ -191,7 +192,26 @@ export class AxomServerManager {
       if (instance.status === 'error') return;
       try {
         const res = await fetch(`http://127.0.0.1:${port}/about`, { signal: AbortSignal.timeout(2000) });
-        if (res.ok) return;
+        if (res.ok) {
+          // Verify the answer is OURS. Another process (or an SSH tunnel to a
+          // remote runtime) can already own this port; adopting it would let
+          // GROOVE claim — and offer to shut down — a runtime it never
+          // launched. §11 gives /about an instance block; when it names a
+          // different pid or data-dir, this port is not ours.
+          const about = await res.json().catch(() => null);
+          const claimed = about?.instance;
+          const foreign = claimed
+            && ((claimed.pid && instance.proc?.pid && claimed.pid !== instance.proc.pid)
+              || (claimed.data_dir && claimed.data_dir !== instance.dataDir));
+          if (foreign) {
+            instance.status = 'error';
+            instance.error = `port ${port} is already served by another Axom runtime `
+              + `(${claimed.data_dir || `pid ${claimed.pid}`}) — refusing to adopt it`;
+            instance.proc?.kill('SIGKILL');
+            return;
+          }
+          return;
+        }
       } catch { /* not up yet */ }
       await new Promise((r) => setTimeout(r, 500));
     }

package/packages/daemon/src/index.js

@@ -57,6 +57,7 @@ import { bindDaemon as bindAxomDaemon } from './providers/axom.js';
 import { AxomConnector } from './axom-connector.js';
 import { AxomServerManager } from './axom-server.js';
 import { AxomInstaller } from './axom-install.js';
+import { AxomRemote } from './axom-remote.js';
 import { setProviderPaths } from './providers/index.js';
 
 const DEFAULT_PORT = 31415;
@@ -173,6 +174,7 @@ export class Daemon {
     this.axom = new AxomConnector(this);
     this.axomServer = new AxomServerManager(this);
     this.axomInstaller = new AxomInstaller(this);
+    this.axomRemote = new AxomRemote(this);
     this.trajectoryCapture = null;
 
     // Hook teams.delete to clean up agent-loop session files
@@ -886,6 +888,7 @@ export class Daemon {
     this.chatStore.stop();
     this.orchestrator.stop();
     this.timeline.stop();
+    this.axomRemote.closeTunnel();
     await this.axomServer.destroy();
     this.axom.destroy();
     if (this._gcInterval) clearInterval(this._gcInterval);

package/packages/daemon/src/routes/axom.js

@@ -4,6 +4,7 @@ import os from 'os';
 import { saveConfig } from '../firstrun.js';
 import { validateEndpoint, AXOM_DEFAULT_PORT } from '../axom-connector.js';
 import { hardwareReport } from '../axom-server.js';
+import { validateRemote } from '../axom-remote.js';
 
 // Interrupt text is capped runtime-side at 2000 chars (contract §2, with a
 // `truncated` flag in the response); we allow headroom and let the runtime be
@@ -37,11 +38,14 @@ export function registerAxomRoutes(app, daemon) {
   // through verbatim — the GUI reads them, we don't reinterpret.
   app.post('/api/axom/sessions/:id/message', async (req, res) => {
     try {
-      const { text, endpoint } = req.body || {};
+      const { text, endpoint, clientRef } = req.body || {};
       if (!text || typeof text !== 'string' || !text.trim()) {
         return res.status(400).json({ error: 'text is required' });
       }
-      const result = await daemon.axom.message(endpoint, req.params.id, text);
+      if (clientRef !== undefined && (typeof clientRef !== 'string' || clientRef.length > 64)) {
+        return res.status(400).json({ error: 'clientRef must be a string of at most 64 chars' });
+      }
+      const result = await daemon.axom.message(endpoint, req.params.id, text, clientRef);
       daemon.audit.log('axom.message', { session: req.params.id, chars: text.length, status: result.status });
       res.status(result.status).json(result.body);
     } catch (err) {
@@ -101,6 +105,73 @@ export function registerAxomRoutes(app, daemon) {
     });
   });
 
+  // §14: shut down the runtime itself. Works for any endpoint that supports
+  // the verb — including remote ones, which GROOVE could never reach with a
+  // signal. A 404 means the runtime predates §14; the GUI must say so rather
+  // than claim the runtime is gone.
+  app.post('/api/axom/shutdown', async (req, res) => {
+    try {
+      const result = await daemon.axom.shutdown(req.body?.endpoint, { force: !!req.body?.force });
+      daemon.audit.log('axom.shutdown', { endpoint: req.body?.endpoint || null, status: result.status });
+      res.status(result.status === 404 ? 501 : result.status)
+        .json(result.status === 404
+          ? { error: 'this runtime does not support remote shutdown (predates contract §14)' }
+          : result.body);
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  // ── Remote runtime control over SSH (manual only, never automatic) ──────
+
+  app.get('/api/axom/remote', async (req, res) => {
+    res.json(await daemon.axomRemote.status());
+  });
+
+  app.patch('/api/axom/remote', (req, res) => {
+    const remote = req.body || {};
+    if (remote.clear === true) {
+      delete daemon.config.axom?.remote;
+      saveConfig(daemon.grooveDir, daemon.config);
+      return res.json({ configured: false });
+    }
+    const problem = validateRemote(remote);
+    if (problem) return res.status(400).json({ error: problem });
+    const { host, user, sshPort, port, command, logPath } = remote;
+    daemon.config.axom = {
+      ...(daemon.config.axom || {}),
+      remote: { host, user, sshPort, port, command, logPath },
+    };
+    saveConfig(daemon.grooveDir, daemon.config);
+    daemon.audit.log('axom.remote.config', { host, user });
+    res.json(daemon.config.axom.remote);
+  });
+
+  // Reachability only — opens/heals the port-forward. Never starts a runtime.
+  app.post('/api/axom/remote/tunnel', async (req, res) => {
+    try {
+      res.json(await daemon.axomRemote.ensureTunnel());
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/remote/start', async (req, res) => {
+    try {
+      res.json(await daemon.axomRemote.start());
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/remote/stop', async (req, res) => {
+    try {
+      res.json(await daemon.axomRemote.stop({ force: !!req.body?.force }));
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
   // ── Managed local instances (contract §11) ──────────────────────────────
 
   app.get('/api/axom/instances', (req, res) => {

package/packages/daemon/src/routes/innerchat.js

@@ -1,9 +1,12 @@
 // FSL-1.1-Apache-2.0 — see LICENSE
 
 import { MAX_EXCHANGES } from '../innerchat.js';
+import { readFileSync } from 'fs';
 import { validatePeer, parsePeerRef } from '../innerchat-relay.js';
 import { saveConfig } from '../firstrun.js';
 
+const pkgVersion = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+
 // Agents know each other by name, not id. Exact matches win first so
 // `fullstack-1` never resolves to `fullstack-14`; only if nothing matches
 // exactly do we accept a single unambiguous partial, since agents routinely
@@ -73,7 +76,101 @@ function verifyRelayCaller(daemon, body, res) {
   return peer;
 }
 
+// A peer relay is accepted only when the sender is BOTH a configured peer
+// (in innerchatPeers — the human's decision) AND signature-verifies against a
+// stored federation public key. Those are independent gates, which is what
+// makes automatic key exchange safe: holding someone's public key grants
+// nothing on its own. So adding a peer can fetch and store its key without a
+// separate manual pairing step.
+async function exchangeKeys(daemon, url, alias) {
+  const base = url.replace(/\/+$/, '');
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 8000);
+  try {
+    const res = await fetch(`${base}/api/innerchat/identity`, { signal: controller.signal });
+    if (!res.ok) throw new Error(`peer returned HTTP ${res.status}`);
+    const id = await res.json();
+    if (!id?.daemonId || !id?.publicKey) throw new Error('peer did not return an identity');
+
+    // Store their key so we can verify what they send us.
+    daemon.federation._savePeer({
+      id: id.daemonId,
+      name: alias,
+      host: new URL(base).hostname,
+      port: Number(new URL(base).port) || 80,
+      publicKey: id.publicKey,
+      pairedAt: new Date().toISOString(),
+    });
+
+    // Push ours so they can verify what WE send — this is the half that
+    // otherwise required a manual step on the other machine.
+    let pushed = false;
+    try {
+      const push = await fetch(`${base}/api/innerchat/identity`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          daemonId: daemon.federation.getDaemonId(),
+          publicKey: daemon.federation.getPublicKeyPem(),
+          name: daemon.config?.daemonName || 'groove',
+        }),
+        signal: controller.signal,
+      });
+      pushed = push.ok;
+    } catch { /* reachable for GET but not POST — report partial */ }
+
+    return { ok: true, peerDaemonId: id.daemonId, peerVersion: id.version, pushed };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 export function registerInnerChatRoutes(app, daemon) {
+  /**
+   * This daemon's federation identity. Read-only and non-secret (a public key
+   * plus an id); the peer needs it to verify signed relays from us.
+   */
+  app.get('/api/innerchat/identity', (req, res) => {
+    res.json({
+      daemonId: daemon.federation.getDaemonId(),
+      publicKey: daemon.federation.getPublicKeyPem(),
+      version: pkgVersion,
+      port: daemon.port,
+      agents: daemon.registry.getAll().map((a) => a.name),
+    });
+  });
+
+  /**
+   * Accept a peer's public key so we can verify its signed relays. Storing a
+   * key authorizes nothing by itself — a relay ALSO requires that daemon to be
+   * listed in innerchatPeers, which only the user can do. That second gate is
+   * what keeps this endpoint safe to accept without a pairing dance.
+   */
+  app.post('/api/innerchat/identity', (req, res) => {
+    const { daemonId, publicKey, name } = req.body || {};
+    if (!daemonId || !/^[a-f0-9]{6,64}$/.test(String(daemonId))) {
+      return res.status(400).json({ error: 'valid daemonId required' });
+    }
+    if (!publicKey || typeof publicKey !== 'string' || !publicKey.includes('PUBLIC KEY')) {
+      return res.status(400).json({ error: 'publicKey (PEM) required' });
+    }
+    daemon.federation._savePeer({
+      id: daemonId,
+      name: typeof name === 'string' && name.trim() ? name.trim().slice(0, 40) : daemonId,
+      host: (req.ip || '').replace('::ffff:', '') || '127.0.0.1',
+      port: 0,
+      publicKey,
+      pairedAt: new Date().toISOString(),
+    });
+    daemon.audit.log('innerchat.key.received', { daemonId });
+    res.json({
+      ok: true,
+      // Hand back ours so a single call completes the exchange either way.
+      daemonId: daemon.federation.getDaemonId(),
+      publicKey: daemon.federation.getPublicKeyPem(),
+    });
+  });
+
   /**
    * Ask another agent a question and BLOCK until it answers.
    *
@@ -223,19 +320,104 @@ export function registerInnerChatRoutes(app, daemon) {
     res.json({ peers: daemon.innerchat._peers() });
   });
 
-  app.post('/api/innerchat/peers', (req, res) => {
-    const entry = { alias: req.body?.alias, url: req.body?.url, daemonId: req.body?.daemonId };
-    const err = validatePeer(entry);
-    if (err) return res.status(400).json({ error: err });
-    entry.url = entry.url.replace(/\/+$/, '');
+  /**
+   * Add a peer. The daemonId is discovered from the peer itself rather than
+   * typed, and public keys are exchanged automatically, so the user only has
+   * to supply a name and a reachable URL.
+   */
+  app.post('/api/innerchat/peers', async (req, res) => {
+    const alias = req.body?.alias;
+    const rawUrl = req.body?.url;
+    if (!alias || typeof alias !== 'string' || !/^[a-zA-Z0-9_-]{1,40}$/.test(alias)) {
+      return res.status(400).json({ error: 'peer name must be 1-40 chars (letters, digits, dash, underscore)' });
+    }
+    if (!rawUrl || typeof rawUrl !== 'string') return res.status(400).json({ error: 'peer url is required' });
+
+    let url;
+    try {
+      const parsed = new URL(rawUrl.trim());
+      if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return res.status(400).json({ error: 'peer url must be http(s)' });
+      }
+      if (parsed.username || parsed.password) return res.status(400).json({ error: 'credentials in the url are not allowed' });
+      url = rawUrl.trim().replace(/\/+$/, '');
+    } catch { return res.status(400).json({ error: `invalid url: ${rawUrl}` }); }
+
+    // Reach the peer, learn its id, and trade keys. This is the step that used
+    // to be a manual federation pairing.
+    let exchange;
+    try {
+      exchange = await exchangeKeys(daemon, url, alias);
+    } catch (err) {
+      return res.status(502).json({
+        error: `Could not reach a Groove daemon at ${url} — ${err.message}. `
+          + 'Check the URL (for a tunnelled peer this is the forwarded local port, not 31415) and that the peer daemon is running the current version.',
+      });
+    }
+
+    if (exchange.peerDaemonId === daemon.federation.getDaemonId()) {
+      return res.status(400).json({
+        error: `That URL points at THIS daemon, not a peer. For a tunnelled machine use the forwarded local port (e.g. http://127.0.0.1:31416), not ${url}.`,
+      });
+    }
+
+    const entry = { alias, url, daemonId: exchange.peerDaemonId };
+    const check = validatePeer(entry);
+    if (check) return res.status(400).json({ error: check });
 
     const peers = Array.isArray(daemon.config.innerchatPeers) ? daemon.config.innerchatPeers : [];
-    const next = peers.filter((p) => p.alias !== entry.alias);
+    const next = peers.filter((p) => p.alias !== alias);
     next.push(entry);
     daemon.config.innerchatPeers = next;
     saveConfig(daemon.grooveDir, daemon.config);
-    daemon.audit.log('innerchat.peer.set', { alias: entry.alias, url: entry.url });
-    res.json({ peers: next });
+    daemon.audit.log('innerchat.peer.set', { alias, url, daemonId: entry.daemonId });
+    // Registry files carry the @peer instructions + alias list — refresh now so
+    // running agents see the new peer without waiting for a spawn or restart.
+    try { daemon.introducer?.writeRegistryFile?.(daemon.projectDir); } catch { /* best effort */ }
+
+    res.json({
+      peers: next,
+      exchanged: true,
+      keyPushed: exchange.pushed,
+      peerDaemonId: exchange.peerDaemonId,
+      note: exchange.pushed
+        ? `Keys exchanged with ${alias}. Add this machine as a peer there too if you want its agents to start conversations.`
+        : `Stored ${alias}'s key, but could not send ours — ${alias} may be running an older version. Update it, then re-add.`,
+    });
+  });
+
+  /**
+   * Verify a configured peer end to end: reachable, identity matches what we
+   * stored, and keys are present on both sides.
+   */
+  app.get('/api/innerchat/peers/:alias/test', async (req, res) => {
+    const peer = daemon.innerchat._peerByAlias(req.params.alias);
+    if (!peer) return res.status(404).json({ error: `No peer named "${req.params.alias}"` });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 8000);
+    try {
+      const r = await fetch(`${peer.url}/api/innerchat/identity`, { signal: controller.signal });
+      if (!r.ok) throw new Error(`HTTP ${r.status}`);
+      const id = await r.json();
+      const idMatches = id.daemonId === peer.daemonId;
+      const weHaveTheirKey = daemon.federation.peers.has(peer.daemonId);
+      res.json({
+        ok: idMatches && weHaveTheirKey,
+        reachable: true,
+        idMatches,
+        weHaveTheirKey,
+        peerDaemonId: id.daemonId,
+        peerVersion: id.version,
+        agents: Array.isArray(id.agents) ? id.agents : [],
+        error: !idMatches
+          ? `The daemon at ${peer.url} reports id ${id.daemonId}, but this peer is configured as ${peer.daemonId}. Re-add the peer.`
+          : !weHaveTheirKey ? 'Missing this peer\'s public key — re-add the peer to exchange keys.' : null,
+      });
+    } catch (err) {
+      res.json({ ok: false, reachable: false, error: `Could not reach ${peer.url} — ${err.message}` });
+    } finally {
+      clearTimeout(timer);
+    }
   });
 
   app.delete('/api/innerchat/peers/:alias', (req, res) => {