groove-dev 0.27.197 → 0.27.198

package/packages/daemon/src/innerchat.js

@@ -2,6 +2,7 @@
 
 import { randomUUID } from 'crypto';
 import { deliverInstruction } from './deliver.js';
+import { RelayClient, parsePeerRef } from './innerchat-relay.js';
 
 // An unanswered ask holds an HTTP request open and blocks the calling agent,
 // so it has to be bounded.
@@ -16,6 +17,12 @@ const MAX_EXCHANGES = 12;
 const CONTEXT_TURNS = 4;
 const MAX_TURN_CHARS = 1200;
 
+// Sender-side outbox polling for async (tell) replies from a peer. Bounded: we
+// poll a peer only after we've sent it a tell, and stop after a run of empty
+// polls — a heads-down agent gets a generous window to finish, then we let go.
+const OUTBOX_POLL_MS = 3000;
+const OUTBOX_IDLE_STOP = 10; // ~30s of silence ends the poll
+
 /**
  * Agent-to-agent consultation.
  *
@@ -29,13 +36,40 @@ const MAX_TURN_CHARS = 1200;
  * a question reaches its target whether it's mid-task, idle, or stopped.
  */
 export class InnerChat {
-  constructor(daemon) {
+  constructor(daemon, opts = {}) {
     this.daemon = daemon;
     this.threads = new Map();
     // agentId being asked -> pending record (resolve/reject/timer/threadId)
     this.awaiting = new Map();
     // asker id -> id of the agent it is currently blocked on
     this.blockedOn = new Map();
+
+    // Cross-daemon relay (spec: plans/cross-daemon-innerchat-spec.md).
+    this.relay = opts.relay || new RelayClient();
+    // Replies to async (tell) relays, queued here on the answering daemon until
+    // the sending daemon polls its outbox. Entry: { id, forDaemonId, toName,
+    // fromName, fromDaemonId, text, threadId, ts }.
+    this.relayOutbox = [];
+    // alias -> { timer, idle, busy } for active sender-side outbox pollers.
+    this._outboxPollers = new Map();
+  }
+
+  // Configured peers: [{ alias, url, daemonId }]. Empty by default — cross-daemon
+  // routing is off until the user adds a peer on both machines.
+  _peers() {
+    return Array.isArray(this.daemon.config?.innerchatPeers) ? this.daemon.config.innerchatPeers : [];
+  }
+
+  _peerByAlias(alias) {
+    return this._peers().find((p) => p.alias === alias) || null;
+  }
+
+  _peerByDaemonId(daemonId) {
+    return this._peers().find((p) => p.daemonId === daemonId) || null;
+  }
+
+  _daemonId() {
+    return this.daemon.federation.getDaemonId();
   }
 
   /**
@@ -252,6 +286,9 @@ export class InnerChat {
     if (pending.mode === 'async') {
       this._clearAwait(agentId);
       this._forwardAsyncReply(pending, answerTurn, text);
+    } else if (pending.mode === 'relay-async') {
+      this._clearAwait(agentId);
+      this._enqueueOutbox(pending, answerTurn, text);
     } else {
       pending.resolve(text);
     }
@@ -392,6 +429,228 @@ export class InnerChat {
     return pending ? this.threads.get(pending.threadId) : null;
   }
 
+  // ── Cross-daemon relay ──────────────────────────────────────
+  //
+  // A `name@alias` target routes here. The sending side (askRemote/tellRemote)
+  // signs the request with this daemon's federation key and POSTs it to the
+  // peer; the answering side (receiveRelay) verifies the signer, resolves the
+  // name in its OWN registry, and delivers through the normal InnerChat pipe
+  // with a guest identity so caps, threads, and audit all work unchanged.
+
+  // True when `to` names a peer. Lets the route layer branch cheaply.
+  isRemoteRef(to) {
+    const parsed = parsePeerRef(to);
+    return !!(parsed && parsed.alias);
+  }
+
+  // Ask an agent on a peer daemon and BLOCK for its reply (relayed over the
+  // still-open HTTP response — one-way transport suffices for ask/reply).
+  async askRemote(fromAgent, toName, alias, message, opts = {}) {
+    const peer = this._requirePeer(alias);
+    const envelope = this._signRelay('ask', fromAgent, toName, message);
+    const { ok, status, json } = await this._sendRelay(peer, envelope, opts.timeoutMs);
+    if (!ok) throw new Error(json?.error || `Peer "${alias}" refused the relay (HTTP ${status})`);
+    this.daemon.audit.log('innerchat.relay.ask', { peer: alias, from: fromAgent.name, to: toName });
+    return { reply: json.reply, remote: true, peer: alias, threadId: json.threadId };
+  }
+
+  // Send to an agent on a peer daemon WITHOUT blocking. The reply, if any, is
+  // queued in the peer's outbox and picked up by our poller, then delivered
+  // back to the local sender — keeping the one-way topology sufficient.
+  async tellRemote(fromAgent, toName, alias, message) {
+    const peer = this._requirePeer(alias);
+    const envelope = this._signRelay('tell', fromAgent, toName, message);
+    const { ok, status, json } = await this._sendRelay(peer, envelope);
+    if (!ok) throw new Error(json?.error || `Peer "${alias}" refused the relay (HTTP ${status})`);
+    this.daemon.audit.log('innerchat.relay.tell', { peer: alias, from: fromAgent.name, to: toName });
+    this._ensureOutboxPoll(peer);
+    return { delivered: true, remote: true, peer: alias, threadId: json.threadId };
+  }
+
+  _requirePeer(alias) {
+    const peer = this._peerByAlias(alias);
+    if (!peer) {
+      const aliases = this._peers().map((p) => p.alias);
+      throw new Error(
+        `No configured InnerChat peer "${alias}".`
+        + (aliases.length ? ` Known peers: ${aliases.join(', ')}.` : ' No peers are configured.'),
+      );
+    }
+    return peer;
+  }
+
+  _signRelay(kind, fromAgent, toName, message) {
+    const signed = this.daemon.federation.sign({
+      v: 1,
+      type: 'innerchat.relay',
+      kind,
+      fromName: fromAgent.name,
+      fromRole: fromAgent.role,
+      fromDaemonId: this._daemonId(),
+      toName,
+      message,
+    });
+    return { payload: signed.payload, signature: signed.signature };
+  }
+
+  _sendRelay(peer, envelope, timeoutMs) {
+    return this.relay.sendRelay(peer.url, envelope, timeoutMs);
+  }
+
+  /**
+   * Receive a relayed ask/tell from a peer daemon. The route layer has already
+   * verified the signature and confirmed the sender is a configured peer, and
+   * passes the peer's alias for display. Resolves the target in the LOCAL
+   * registry and delivers with a guest sender identity.
+   *
+   * For 'ask' this resolves with the local agent's reply text (relayed back on
+   * the open response). For 'tell' it resolves once delivered; the reply is
+   * later queued to the outbox for the sending daemon.
+   */
+  async receiveRelay({ fromName, fromRole, fromDaemonId, peerAlias, toName, message, kind, threadId, timeoutMs }) {
+    // One hop only: a `name@peer` target here would be a second relay. Refuse
+    // before resolving, so it reads as "transitive" not "no such agent".
+    if (String(toName).includes('@')) throw new Error('Transitive relay refused — InnerChat is one hop only.');
+    const toAgent = this._resolveLocal(toName);
+    if (!toAgent) {
+      const names = this.daemon.registry.getAll().map((a) => a.name);
+      const err = new Error(`No agent named "${toName}" on this daemon.`);
+      err.availableAgents = names;
+      throw err;
+    }
+    if (this.awaiting.has(toAgent.id)) {
+      throw new Error(`${toAgent.name} is already answering another message — try again shortly.`);
+    }
+    if (!message || !message.trim()) throw new Error('message is required');
+
+    const guest = {
+      id: `guest:${fromDaemonId}:${fromName}`,
+      name: peerAlias ? `${fromName}@${peerAlias}` : fromName,
+      role: fromRole || 'remote-agent',
+      remote: { daemonId: fromDaemonId, fromName },
+    };
+
+    const t = this._openThread(guest, toAgent, threadId);
+    this._checkExchangeCap(t, toAgent);
+
+    const { targetId, skipResults } = await this._deliver(t, guest, toAgent, message.trim(), kind);
+
+    if (kind === 'tell') {
+      this.awaiting.set(targetId, {
+        mode: 'relay-async',
+        threadId: t.id,
+        remote: { forDaemonId: fromDaemonId, fromName },
+        skipResults,
+        timer: setTimeout(() => this._clearAwait(targetId), MAX_TIMEOUT_MS),
+      });
+      return { delivered: true, threadId: t.id };
+    }
+
+    const reply = await this._awaitReply(t, guest.id, targetId, {
+      skipResults,
+      timeoutMs: Math.min(Number(timeoutMs) || DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS),
+    });
+    return { reply, threadId: t.id };
+  }
+
+  // Local-only resolution mirroring the route resolver: exact id/name first,
+  // then a single unambiguous partial. Never reaches across daemons (one hop).
+  _resolveLocal(ref) {
+    const all = this.daemon.registry.getAll();
+    const needle = String(ref || '').trim().toLowerCase();
+    const exact = all.find((a) => a.id === ref)
+      || all.find((a) => a.name === ref)
+      || all.find((a) => a.name.toLowerCase() === needle);
+    if (exact) return exact;
+    const partial = all.filter((a) => a.name.toLowerCase() === needle
+      || a.name.toLowerCase().includes(needle));
+    return partial.length === 1 ? partial[0] : null;
+  }
+
+  // ── Outbox (async relay replies) ────────────────────────────
+
+  _enqueueOutbox(pending, answerTurn, text) {
+    this.relayOutbox.push({
+      id: randomUUID().slice(0, 12),
+      forDaemonId: pending.remote.forDaemonId,
+      toName: pending.remote.fromName,          // the remote agent that asked
+      fromName: answerTurn.from.name,            // the local agent that answered
+      fromDaemonId: this._daemonId(),
+      text,
+      threadId: pending.threadId,
+      ts: Date.now(),
+    });
+    this.daemon.audit.log('innerchat.relay.queued', { for: pending.remote.forDaemonId, from: answerTurn.from.name });
+  }
+
+  // Drain and remove outbox entries destined for a given daemon (at-least-once:
+  // removed on read). Called by the relay/outbox route after verifying the caller.
+  drainOutbox(forDaemonId) {
+    const mine = this.relayOutbox.filter((e) => e.forDaemonId === forDaemonId);
+    if (mine.length) this.relayOutbox = this.relayOutbox.filter((e) => e.forDaemonId !== forDaemonId);
+    return mine;
+  }
+
+  // Sender-side: poll a peer for queued replies until they stop arriving.
+  _ensureOutboxPoll(peer) {
+    const existing = this._outboxPollers.get(peer.alias);
+    if (existing) { existing.idle = 0; return; }
+
+    const state = { idle: 0, busy: false, timer: null };
+    const tick = async () => {
+      if (state.busy) return;
+      state.busy = true;
+      try {
+        const entries = await this._pollOutbox(peer);
+        if (entries.length) {
+          state.idle = 0;
+          for (const e of entries) await this._deliverRemoteReply(peer, e);
+        } else {
+          state.idle += 1;
+        }
+      } catch { state.idle += 1; }
+      finally { state.busy = false; }
+      if (state.idle >= OUTBOX_IDLE_STOP) this._stopOutboxPoll(peer.alias);
+    };
+    state.timer = setInterval(tick, OUTBOX_POLL_MS);
+    if (state.timer.unref) state.timer.unref();
+    this._outboxPollers.set(peer.alias, state);
+  }
+
+  async _pollOutbox(peer) {
+    const signed = this.daemon.federation.sign({ v: 1, type: 'innerchat.outbox', fromDaemonId: this._daemonId() });
+    const { json } = await this.relay.fetchOutbox(peer.url, { payload: signed.payload, signature: signed.signature }, 5000);
+    return Array.isArray(json?.entries) ? json.entries : [];
+  }
+
+  _stopOutboxPoll(alias) {
+    const state = this._outboxPollers.get(alias);
+    if (state?.timer) clearInterval(state.timer);
+    this._outboxPollers.delete(alias);
+  }
+
+  // Deliver a peer's async reply to the local agent that sent the original tell.
+  async _deliverRemoteReply(peer, entry) {
+    const sender = this._resolveLocal(entry.toName);
+    if (!sender) {
+      this.daemon.audit.log('innerchat.relay.reply_undeliverable', { to: entry.toName, peer: peer.alias });
+      return;
+    }
+    const msg = [
+      `[InnerChat reply from ${entry.fromName}@${peer.alias}]`,
+      '',
+      entry.text,
+      '',
+      'This is a reply to a message you sent earlier to a peer agent (you were not '
+      + 'blocking on it). Fold it into your work, or reply again to continue.',
+    ].join('\n');
+    try {
+      await deliverInstruction(this.daemon, sender.id, msg, { recordFeedback: false });
+    } catch (err) {
+      this.daemon.audit.log('innerchat.relay.reply_failed', { to: sender.id, error: err.message });
+    }
+  }
+
   // Clear all outstanding timers so a shutdown (or a test) doesn't hang on
   // pending ask/tell timeouts. Blocking asks are rejected so their HTTP
   // requests don't hang either.
@@ -404,6 +663,7 @@ export class InnerChat {
       this.awaiting.delete(targetId);
     }
     this.blockedOn.clear();
+    for (const alias of [...this._outboxPollers.keys()]) this._stopOutboxPoll(alias);
   }
 }
 

package/packages/daemon/src/introducer.js

@@ -561,7 +561,7 @@ export class Introducer {
   // compaction — the spawn prompt alone can scroll out of a long session.
   _innerChatSection() {
     const port = this.daemon.port || 31415;
-    return [...innerChatInstructions(port), '', ...watchInstructions(port), '', ...logFileInstructions()];
+    return [...innerChatInstructions(port, 'YOUR_NAME', this.daemon.config?.innerchatPeers), '', ...watchInstructions(port), '', ...logFileInstructions()];
   }
 
   writeRegistryFile(projectDir) {

package/packages/daemon/src/network-guard.js

@@ -0,0 +1,56 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import { execFileSync } from 'child_process';
+
+// Fingerprint the current network by its default gateway's IP + MAC address.
+// The MAC is the strong part: it's unique to your router and a passive sniffer
+// on a coffee-shop LAN can't make their gateway look like your home router.
+// LAN peering only activates when this fingerprint matches the one recorded
+// when you enabled it at home — so at a hotel/cafe the peer listener never
+// opens in the first place.
+
+function defaultGatewayIp() {
+  try {
+    if (process.platform === 'darwin') {
+      const out = execFileSync('route', ['-n', 'get', 'default'], { encoding: 'utf8', timeout: 3000 });
+      const m = out.match(/gateway:\s*([\d.]+)/);
+      return m ? m[1] : null;
+    }
+    // linux
+    const out = execFileSync('ip', ['route'], { encoding: 'utf8', timeout: 3000 });
+    const m = out.match(/default via ([\d.]+)/);
+    return m ? m[1] : null;
+  } catch { return null; }
+}
+
+function macForIp(ip) {
+  if (!ip) return null;
+  try {
+    const arp = process.platform === 'darwin' ? ['-n', ip] : ['-n', ip];
+    const out = execFileSync('arp', arp, { encoding: 'utf8', timeout: 3000 });
+    // e.g. "? (10.0.0.1) at 5c:7d:7d:2d:11:e0 on en0 …"
+    const m = out.match(/([0-9a-f]{1,2}(:[0-9a-f]{1,2}){5})/i);
+    return m ? normalizeMac(m[1]) : null;
+  } catch { return null; }
+}
+
+function normalizeMac(mac) {
+  // ARP can print "5:7d:..." (no leading zero) — pad each octet so equality is reliable.
+  return mac.toLowerCase().split(':').map((o) => o.padStart(2, '0')).join(':');
+}
+
+// { gatewayIp, gatewayMac } for the network we're on right now, or nulls.
+export function currentNetworkFingerprint() {
+  const gatewayIp = defaultGatewayIp();
+  const gatewayMac = macForIp(gatewayIp);
+  return { gatewayIp, gatewayMac };
+}
+
+// Are we on the trusted network? Requires a MAC match — an IP-only match is not
+// enough (many LANs use 192.168.1.1). If no fingerprint was ever recorded, we
+// are NOT on a trusted network (fail closed).
+export function onTrustedNetwork(trusted) {
+  if (!trusted || !trusted.gatewayMac) return false;
+  const now = currentNetworkFingerprint();
+  return !!now.gatewayMac && now.gatewayMac === normalizeMac(trusted.gatewayMac);
+}

package/packages/daemon/src/process.js

@@ -1196,7 +1196,7 @@ For normal file edits within your scope, proceed without review.
     if (!sandboxedProviders.includes(providerName) && !isOneShotProvider) {
       const port = this.daemon.port || 31415;
       const capabilities = [
-        ...innerChatInstructions(port, agent.name),
+        ...innerChatInstructions(port, agent.name, this.daemon.config?.innerchatPeers),
         '',
         ...watchInstructions(port, agent.name),
         '',

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

@@ -0,0 +1,66 @@
+// GROOVE — Axom Provider (Endpoint Runtime)
+// FSL-1.1-Apache-2.0 — see LICENSE
+//
+// Axom is an ENDPOINT provider, not a CLI provider: the runtime is a daemon
+// (`axom serve`, default port 8737) that GROOVE connects to over the Axom
+// provider protocol. Sessions stream envelope events; the AxomConnector
+// (src/axom-connector.js) owns the live connection. v0 has no session-create
+// verb, so agents are not spawnable — the Axom tab is the surface.
+
+import { Provider } from './base.js';
+import { AXOM_DEFAULT_PORT } from '../axom-connector.js';
+
+let _daemonRef = null;
+export function bindDaemon(daemon) { _daemonRef = daemon; }
+
+export class AxomProvider extends Provider {
+  static name = 'axom';
+  static displayName = 'Axom';
+  static command = 'axom';
+  static authType = 'endpoint'; // configured URL, no key — auth is a v1 protocol item
+  static managesOwnContext = true; // memory ledger + rotation live in the runtime
+  static singleTask = false;
+  static models = []; // the live roster comes from GET /about, not a static list
+
+  static isInstalled() {
+    return (_daemonRef?.config?.axom?.endpoints || []).length > 0;
+  }
+
+  // Settings renders this verbatim as text (string contract — Ollama's object
+  // shape only survives because its render branch never fires when installed).
+  static installCommand() {
+    return 'axom serve';
+  }
+
+  static async isServerRunning(url = `http://127.0.0.1:${AXOM_DEFAULT_PORT}`) {
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 3000);
+      const res = await fetch(`${url.replace(/\/+$/, '')}/about`, { signal: controller.signal });
+      clearTimeout(timeout);
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  buildSpawnCommand() {
+    throw new Error('Axom sessions are not spawnable in v0 — configure an endpoint and use the Axom tab');
+  }
+
+  buildHeadlessCommand() {
+    throw new Error('Axom has no headless command — it is an endpoint runtime, not a CLI');
+  }
+
+  static setupGuide() {
+    return {
+      installSteps: [
+        'Install the Axom runtime on the machine that will run it (localhost is the default topology)',
+        `Start it with: axom serve  (binds 127.0.0.1:${AXOM_DEFAULT_PORT})`,
+        'In GROOVE, open the Axom tab and add the endpoint URL',
+      ],
+      authMethods: [],
+      authInstructions: {},
+    };
+  }
+}

package/packages/daemon/src/providers/index.js

@@ -11,6 +11,7 @@ import { GrokProvider } from './grok.js';
 import { NanaBananaProvider } from './nano-banana.js';
 import { LocalProvider } from './local.js';
 import { GrooveNetworkProvider } from './groove-network.js';
+import { AxomProvider } from './axom.js';
 
 // Electron forks may not inherit the full shell PATH, causing `which` to miss
 // globally-installed CLI tools. Augment PATH with common npm global bin dirs.
@@ -90,6 +91,7 @@ const providers = {
   'nano-banana': new NanaBananaProvider(),
   'local': new LocalProvider(),
   'groove-network': new GrooveNetworkProvider(),
+  'axom': new AxomProvider(),
 };
 
 const installCache = new Map();

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

@@ -0,0 +1,196 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import os from 'os';
+import { saveConfig } from '../firstrun.js';
+import { validateEndpoint, AXOM_DEFAULT_PORT } from '../axom-connector.js';
+import { hardwareReport } from '../axom-server.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
+// the authority on truncation — its flag is the honest signal, not ours.
+const MAX_INTERRUPT_CHARS = 8000;
+
+export function registerAxomRoutes(app, daemon) {
+  app.get('/api/axom/status', (req, res) => {
+    res.json(daemon.axom.status());
+  });
+
+  app.get('/api/axom/sessions', (req, res) => {
+    const sessions = daemon.axom.status().endpoints.flatMap((ep) =>
+      ep.sessions.map((s) => ({ endpoint: ep.name, ...s })));
+    res.json(sessions);
+  });
+
+  // In-daemon ring backfill for the GUI (initial load / scrubber). `since` is
+  // an envelope id ("ev-000123"); events after it are returned.
+  app.get('/api/axom/sessions/:id/events', (req, res) => {
+    try {
+      const sinceSeq = /^ev-\d+$/.test(req.query.since || '')
+        ? parseInt(req.query.since.slice(3), 10) : 0;
+      res.json(daemon.axom.events(req.query.endpoint, req.params.id, sinceSeq));
+    } catch (err) {
+      res.status(404).json({ error: err.message });
+    }
+  });
+
+  // §12: message starts a turn. Contract statuses (202/409/413) mirror
+  // 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 || {};
+      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);
+      daemon.audit.log('axom.message', { session: req.params.id, chars: text.length, status: result.status });
+      res.status(result.status).json(result.body);
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/sessions/:id/interrupt', async (req, res) => {
+    try {
+      const { text, endpoint } = req.body || {};
+      if (!text || typeof text !== 'string' || !text.trim()) {
+        return res.status(400).json({ error: 'text is required' });
+      }
+      if (text.length > MAX_INTERRUPT_CHARS) {
+        return res.status(400).json({ error: `text exceeds ${MAX_INTERRUPT_CHARS} chars` });
+      }
+      const result = await daemon.axom.interrupt(endpoint, req.params.id, text);
+      daemon.audit.log('axom.interrupt', { session: req.params.id, chars: text.length });
+      res.json(result); // verbatim {id, truncated} from the runtime
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/sessions/:id/stop', async (req, res) => {
+    try {
+      const result = await daemon.axom.stop(req.body?.endpoint, req.params.id);
+      daemon.audit.log('axom.stop', { session: req.params.id });
+      res.json(result);
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  // Machine readiness for local inference — powers the welcome page's
+  // "can this device run Axom?" verdict.
+  app.get('/api/axom/hardware', (req, res) => {
+    res.json(hardwareReport(daemon.grooveDir));
+  });
+
+  // This GROOVE's own Axom endpoint — what another instance would paste.
+  // serve binds 127.0.0.1 (§6), so cross-machine reach is the user's own
+  // channel; we hand them the exact tunnel one-liner rather than pretending
+  // the URL travels on its own.
+  app.get('/api/axom/my-endpoint', (req, res) => {
+    const running = daemon.axomServer.list().find((i) => i.status === 'running');
+    const port = running?.port || AXOM_DEFAULT_PORT;
+    const host = os.hostname();
+    const user = os.userInfo().username;
+    res.json({
+      url: `http://127.0.0.1:${port}`,
+      port,
+      host,
+      running: !!running,
+      instanceId: running?.id || null,
+      tunnelCommand: `ssh -N -L ${port}:localhost:${port} ${user}@${host}`,
+    });
+  });
+
+  // ── Managed local instances (contract §11) ──────────────────────────────
+
+  app.get('/api/axom/instances', (req, res) => {
+    res.json(daemon.axomServer.list());
+  });
+
+  app.post('/api/axom/instances', async (req, res) => {
+    try {
+      const instance = await daemon.axomServer.start(req.body?.id || 'default');
+      res.json(instance);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  app.delete('/api/axom/instances/:id', async (req, res) => {
+    try {
+      await daemon.axomServer.stop(req.params.id);
+      res.json({ ok: true });
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  // ── Manifest-driven install (contract §11) ──────────────────────────────
+
+  app.get('/api/axom/install', (req, res) => {
+    res.json(daemon.axomInstaller.getStatus());
+  });
+
+  app.post('/api/axom/install', (req, res) => {
+    // Long-running — kick off and let the axom:install:progress broadcasts
+    // carry the story; the GUI polls GET /api/axom/install as backstop.
+    daemon.axomInstaller.install(req.body?.manifestUrl).catch(() => { /* status carries the error */ });
+    res.json({ started: true });
+  });
+
+  app.get('/api/axom/config', (req, res) => {
+    res.json({ endpoints: daemon.config.axom?.endpoints || [] });
+  });
+
+  app.patch('/api/axom/config', (req, res) => {
+    const { endpoints, command, mock, manifestUrl, modelDir } = req.body || {};
+
+    // Runtime settings (contract §11): serve binary path, mock mode,
+    // install-manifest URL, model dir. Any subset may be patched alone.
+    const settings = {};
+    if (command !== undefined) {
+      if (command !== null && (typeof command !== 'string' || !command.trim())) {
+        return res.status(400).json({ error: 'command must be a non-empty string or null' });
+      }
+      settings.command = command;
+    }
+    if (mock !== undefined) settings.mock = !!mock;
+    if (manifestUrl !== undefined) {
+      if (manifestUrl !== null && !/^https?:\/\//.test(manifestUrl)) {
+        return res.status(400).json({ error: 'manifestUrl must be http(s) or null' });
+      }
+      settings.manifestUrl = manifestUrl;
+    }
+    if (modelDir !== undefined) settings.modelDir = modelDir;
+    if (Object.keys(settings).length > 0) {
+      daemon.config.axom = { ...(daemon.config.axom || {}), ...settings };
+      if (endpoints === undefined) {
+        saveConfig(daemon.grooveDir, daemon.config);
+        daemon.audit.log('axom.config', { keys: Object.keys(settings) });
+        return res.json({ ...daemon.config.axom });
+      }
+    }
+
+    if (!Array.isArray(endpoints)) {
+      return res.status(400).json({ error: 'endpoints array is required' });
+    }
+    if (endpoints.length > 16) {
+      return res.status(400).json({ error: 'too many endpoints (max 16)' });
+    }
+    const seen = new Set();
+    for (const entry of endpoints) {
+      const problem = validateEndpoint(entry);
+      if (problem) return res.status(400).json({ error: problem });
+      if (seen.has(entry.name)) {
+        return res.status(400).json({ error: `duplicate endpoint name: ${entry.name}` });
+      }
+      seen.add(entry.name);
+    }
+    const cleaned = endpoints.map(({ name, url }) => ({ name, url: url.replace(/\/+$/, '') }));
+    daemon.config.axom = { ...(daemon.config.axom || {}), endpoints: cleaned };
+    saveConfig(daemon.grooveDir, daemon.config);
+    daemon.axom.configure(cleaned);
+    daemon.audit.log('axom.config', { endpoints: cleaned.map((e) => e.name) });
+    res.json({ endpoints: cleaned });
+  });
+}