groove-dev 0.27.206 → 0.27.208

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

@@ -0,0 +1,301 @@
+// GROOVE — Axom Runtime Model (the redesign's one entity)
+// FSL-1.1-Apache-2.0 — see LICENSE
+//
+// A `runtime` is the single thing the GUI reasons about: a named Axom with a
+// URL and a control mode. Everything else (connector endpoints, spawned
+// instances, SSH lifecycle, tunnels) is a backend behind this model.
+//
+//   control: 'local' — a process THIS daemon spawns/kills (AxomServerManager)
+//   control: 'ssh'   — start/stop over SSH on a machine the user owns
+//   control: 'none'  — someone else's runtime; connect-only
+//
+// States, each owning one recovery action (plans/axom-runtime-flow-redesign.md):
+//   connected → events flowing        (verb: stop / disconnect)
+//   running   → /about answers, WS catching up   (no verb needed)
+//   stopped   → reachable, no runtime            (verb: start, if controllable)
+//   unreachable → can't reach the URL/host       (verb: heal tunnel / retry)
+// `unknown` appears only when probing itself failed — never guessed away.
+
+import { validateEndpoint } from './axom-connector.js';
+import { validateRemote } from './axom-remote.js';
+import { saveConfig } from './firstrun.js';
+
+export function validateRuntime(rt) {
+  if (!rt || typeof rt !== 'object') return 'runtime must be an object';
+  if (!rt.id || !/^[a-zA-Z0-9_-]{1,40}$/.test(rt.id)) return 'invalid runtime id';
+  if (!rt.name || typeof rt.name !== 'string' || rt.name.length > 60) return 'invalid runtime name';
+  if (!['local', 'ssh', 'none'].includes(rt.control)) return 'control must be local, ssh, or none';
+  if (rt.control !== 'local' || rt.url) {
+    // local runtimes get their URL from the spawned port; others must have one
+    const problem = validateEndpoint({ name: rt.id, url: rt.url });
+    if (rt.control !== 'local' && problem) return problem;
+  }
+  if (rt.control === 'ssh') {
+    const problem = validateRemote({ port: undefined, ...rt.ssh });
+    if (problem) return `ssh config: ${problem}`;
+  }
+  if (rt.launch !== undefined) {
+    if (typeof rt.launch !== 'object' || typeof rt.launch.command !== 'string'
+      || rt.launch.command.length === 0 || rt.launch.command.length > 500) {
+      return 'launch.command must be a non-empty string of at most 500 chars';
+    }
+  }
+  return null;
+}
+
+export class AxomRuntimes {
+  constructor(daemon) {
+    this.daemon = daemon;
+  }
+
+  // ── Config ────────────────────────────────────────────────────────────────
+
+  _cfg() {
+    if (!this.daemon.config.axom) this.daemon.config.axom = {};
+    return this.daemon.config.axom;
+  }
+
+  list() {
+    return this._cfg().runtimes || [];
+  }
+
+  get(id) {
+    return this.list().find((r) => r.id === id) || null;
+  }
+
+  activeId() {
+    const cfg = this._cfg();
+    return cfg.activeRuntimeId && this.get(cfg.activeRuntimeId)
+      ? cfg.activeRuntimeId
+      : this.list()[0]?.id || null;
+  }
+
+  // One-time, idempotent: fold the four legacy keys into runtimes[]. Old keys
+  // are kept until the model proves out — compat routes still read them.
+  migrate() {
+    const cfg = this._cfg();
+    if (Array.isArray(cfg.runtimes)) return false;
+    const runtimes = [];
+    const remote = cfg.remote || null;
+    const ep = (cfg.endpoints || [])[0] || null;
+    if (ep && remote && ep.url.endsWith(`:${remote.port || 8737}`)) {
+      runtimes.push({
+        id: 'spark', name: remote.host.split('.')[0] || 'Remote', url: ep.url,
+        control: 'ssh',
+        ssh: { host: remote.host, user: remote.user, sshPort: remote.sshPort, autoTunnel: true },
+        launch: remote.command ? { command: remote.command } : undefined,
+        logPath: remote.logPath,
+      });
+    } else if (ep) {
+      let name = 'Axom';
+      try { name = new URL(ep.url).hostname; } catch { /* keep default */ }
+      runtimes.push({ id: ep.name || 'axom', name, url: ep.url, control: 'none' });
+    }
+    cfg.runtimes = runtimes;
+    if (runtimes.length && !cfg.activeRuntimeId) cfg.activeRuntimeId = runtimes[0].id;
+    return true;
+  }
+
+  _save() {
+    saveConfig(this.daemon.grooveDir, this.daemon.config);
+  }
+
+  start() {
+    this.migrate();
+    this._syncConnector();
+  }
+
+  // Every runtime with a URL becomes a connector endpoint — the connector
+  // stays the single owner of event streams.
+  _syncConnector() {
+    const entries = this.list()
+      .filter((r) => r.url)
+      .map((r) => ({ name: r.id, url: r.url }));
+    this.daemon.axom.configure(entries);
+  }
+
+  add(rt) {
+    const problem = validateRuntime(rt);
+    if (problem) throw new Error(problem);
+    if (this.get(rt.id)) throw new Error(`runtime "${rt.id}" already exists`);
+    this._cfg().runtimes = [...this.list(), rt];
+    if (!this._cfg().activeRuntimeId) this._cfg().activeRuntimeId = rt.id;
+    this._save();
+    this._syncConnector();
+    this.broadcastStatus();
+    return rt;
+  }
+
+  update(id, patch) {
+    const existing = this.get(id);
+    if (!existing) throw new Error(`no runtime "${id}"`);
+    const next = { ...existing, ...patch, id };
+    const problem = validateRuntime(next);
+    if (problem) throw new Error(problem);
+    this._cfg().runtimes = this.list().map((r) => (r.id === id ? next : r));
+    this._save();
+    this._syncConnector();
+    this.broadcastStatus();
+    return next;
+  }
+
+  remove(id) {
+    if (!this.get(id)) throw new Error(`no runtime "${id}"`);
+    this._cfg().runtimes = this.list().filter((r) => r.id !== id);
+    if (this._cfg().activeRuntimeId === id) {
+      this._cfg().activeRuntimeId = this.list()[0]?.id || null;
+    }
+    this._save();
+    this._syncConnector();
+    this.broadcastStatus();
+  }
+
+  activate(id) {
+    if (!this.get(id)) throw new Error(`no runtime "${id}"`);
+    this._cfg().activeRuntimeId = id;
+    this._save();
+    this.broadcastStatus();
+  }
+
+  // ── State derivation ──────────────────────────────────────────────────────
+
+  async state(id) {
+    const rt = this.get(id);
+    if (!rt) throw new Error(`no runtime "${id}"`);
+    const ep = rt.url ? this.daemon.axom.endpoints.get(rt.id) : null;
+
+    if (ep?.status === 'connected') {
+      return { state: 'connected', detail: null };
+    }
+    // Probe the URL directly — the connector's backoff may simply not have
+    // caught up yet, and "running" beats a stale "error".
+    if (rt.url) {
+      try {
+        const res = await fetch(`${rt.url}/about`, { signal: AbortSignal.timeout(3000) });
+        if (res.ok) {
+          // It answers — pull the connector in NOW instead of letting its
+          // backoff stretch the 'running' limbo into a felt stall.
+          this.daemon.axom.nudge?.(rt.id);
+          return { state: 'running', detail: 'connecting to event stream' };
+        }
+      } catch (err) {
+        const refused = /ECONNREFUSED/.test(err.cause?.code || err.message || '');
+        if (refused && rt.control !== 'ssh') {
+          return { state: 'stopped', detail: null };
+        }
+      }
+    }
+    if (rt.control === 'ssh') {
+      // The host knows more than the tunnel does.
+      const remote = await this.daemon.axomRemote.status(this._sshCfg(rt));
+      if (remote.running === true) return { state: 'unreachable', detail: 'runtime is up on the host — the tunnel is down' };
+      if (remote.running === false) return { state: 'stopped', detail: null };
+      return { state: 'unreachable', detail: remote.error || `can't reach ${rt.ssh.host}` };
+    }
+    if (rt.control === 'local') {
+      const inst = this.daemon.axomServer.list().find((i) => i.id === rt.id);
+      if (inst?.status === 'running') return { state: 'running', detail: 'connecting to event stream' };
+      return { state: 'stopped', detail: inst?.error || null };
+    }
+    return { state: 'unreachable', detail: 'nothing answers at this endpoint' };
+  }
+
+  _broadcasting = false;
+  async broadcastStatus() {
+    if (this._broadcasting) return; // status() probes; don't stampede
+    this._broadcasting = true;
+    try {
+      this.daemon.broadcast({ type: 'axom:runtimes', data: await this.status() });
+    } catch { /* next state change rebroadcasts */ } finally {
+      this._broadcasting = false;
+    }
+  }
+
+  async status() {
+    const runtimes = await Promise.all(this.list().map(async (rt) => {
+      let derived;
+      try {
+        derived = await this.state(rt.id);
+      } catch (err) {
+        derived = { state: 'unknown', detail: err.message };
+      }
+      const ep = this.daemon.axom.endpoints.get(rt.id);
+      return {
+        id: rt.id,
+        name: rt.name,
+        control: rt.control,
+        url: rt.url || null,
+        ...derived,
+        about: ep?.about || null,
+        error: ep?.error || null,
+        canStart: rt.control !== 'none' && derived.state === 'stopped',
+        canStop: rt.control !== 'none' && (derived.state === 'connected' || derived.state === 'running'),
+        canHeal: rt.control === 'ssh' && derived.state === 'unreachable',
+      };
+    }));
+    return { runtimes, activeRuntimeId: this.activeId() };
+  }
+
+  // ── Verbs — dispatch on control, never guess ─────────────────────────────
+
+  _sshCfg(rt) {
+    let port = 8737;
+    try { port = Number(new URL(rt.url).port) || 8737; } catch { /* default */ }
+    return {
+      ...rt.ssh,
+      port,
+      command: rt.launch?.command,
+      logPath: rt.logPath,
+    };
+  }
+
+  async startRuntime(id) {
+    const rt = this.get(id);
+    if (!rt) throw new Error(`no runtime "${id}"`);
+    if (rt.control === 'none') throw new Error(`"${rt.name}" is not controlled by GROOVE — start it where it runs`);
+    if (rt.control === 'ssh') {
+      const result = await this.daemon.axomRemote.start(this._sshCfg(rt));
+      if (rt.ssh?.autoTunnel !== false) await this.daemon.axomRemote.ensureTunnel(this._sshCfg(rt));
+      this._syncConnector();
+      this.daemon.axom.nudge?.(rt.id);
+      this.broadcastStatus();
+      return result;
+    }
+    // local: the spawned port becomes the runtime's URL.
+    const instance = await this.daemon.axomServer.start(rt.id, {
+      launch: rt.launch,
+      dataDir: rt.dataDir,
+    });
+    this.update(id, { url: `http://127.0.0.1:${instance.port}` });
+    this.daemon.axom.nudge?.(rt.id);
+    return { started: true, port: instance.port };
+  }
+
+  async stopRuntime(id, { force = false } = {}) {
+    const rt = this.get(id);
+    if (!rt) throw new Error(`no runtime "${id}"`);
+    if (rt.control === 'none') throw new Error(`"${rt.name}" is not controlled by GROOVE`);
+    let result;
+    if (rt.control === 'ssh') {
+      result = await this.daemon.axomRemote.stop({ force }, this._sshCfg(rt));
+    } else {
+      await this.daemon.axomServer.stop(rt.id);
+      result = { stopped: true };
+    }
+    // The connector still believes 'connected' until its next poll fails —
+    // re-probe now so the runtime card moves with the verb, not the poll.
+    this.daemon.axom.recheck?.(rt.id);
+    this.broadcastStatus();
+    return result;
+  }
+
+  async heal(id) {
+    const rt = this.get(id);
+    if (!rt) throw new Error(`no runtime "${id}"`);
+    if (rt.control !== 'ssh') throw new Error('only ssh runtimes have a tunnel to heal');
+    const result = await this.daemon.axomRemote.ensureTunnel(this._sshCfg(rt));
+    this.daemon.axom.nudge?.(rt.id);
+    this.broadcastStatus();
+    return result;
+  }
+}

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

@@ -106,7 +106,14 @@ export class AxomServerManager {
 
   // Start a local instance. `id` doubles as the data-dir name, so the same id
   // across restarts resumes the same sovereign memory.
-  async start(id = 'default') {
+  // opts.launch: {command, cwd?, env?} — a SPEC, not a binary name (source
+  // checkouts launch as `python3 -u -m axom.cli ...` with cwd+env; the
+  // installed default is just `axom`). Specs are verbatim: GROOVE never adds
+  // or removes flags (--cpu on the Spark is policy, not ours to "improve").
+  // opts.dataDir: adopt an existing sovereign ledger instead of minting one
+  // under .groove — one central ledger per user; sessions are recency
+  // scopes, never memory walls (SPARK_DEV_SETUP.md ruling).
+  async start(id = 'default', opts = {}) {
     if (!/^[a-zA-Z0-9_-]{1,40}$/.test(id)) throw new Error('invalid instance id');
     const existing = this.instances.get(id);
     if (existing && existing.status === 'running') return this.list().find((i) => i.id === id);
@@ -124,7 +131,7 @@ export class AxomServerManager {
     }
 
     const port = this._allocatePort();
-    const dataDir = join(this.daemon.grooveDir, 'axom', 'instances', id);
+    const dataDir = opts.dataDir || join(this.daemon.grooveDir, 'axom', 'instances', id);
     mkdirSync(dataDir, { recursive: true });
 
     const args = [
@@ -144,9 +151,21 @@ export class AxomServerManager {
     this.instances.set(id, instance);
     this._broadcast();
 
+    const launch = opts.launch || { command: this._command() };
     let proc;
     try {
-      proc = spawn(this._command(), args, { stdio: ['ignore', 'pipe', 'pipe'] });
+      if (launch.cwd || launch.env || /\s/.test(launch.command)) {
+        // Compound commands run through bash -lc — `nohup cd x && prog`-class
+        // failures taught us a spec is a shell line, not an argv[0].
+        const quotedArgs = args.map((a) => `'${String(a).replace(/'/g, `'\\''`)}'`).join(' ');
+        proc = spawn('bash', ['-lc', `exec ${launch.command} ${quotedArgs}`], {
+          stdio: ['ignore', 'pipe', 'pipe'],
+          cwd: launch.cwd || undefined,
+          env: launch.env ? { ...process.env, ...launch.env } : process.env,
+        });
+      } else {
+        proc = spawn(launch.command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+      }
     } catch (err) {
       instance.status = 'error';
       instance.error = err.message;
@@ -159,7 +178,7 @@ export class AxomServerManager {
     proc.on('error', (err) => {
       instance.status = 'error';
       instance.error = err.code === 'ENOENT'
-        ? `"${this._command()}" not found — install the Axom runtime first`
+        ? `"${launch.command}" not found — install the Axom runtime first`
         : err.message;
       this._broadcast();
     });

package/packages/daemon/src/chatstore.js

@@ -9,14 +9,21 @@ const MAX_PER_AGENT = 200;
 const SAVE_DEBOUNCE_MS = 1500;
 
 /**
- * Server-side chat history.
+ * Server-side chat history, keyed by AGENT NAME.
  *
- * The GUI used to keep chat history only in the browser's localStorage, which
- * is scoped per origin (scheme://host:PORT). For a remote GUI reached over an
- * SSH tunnel the local port changes across reconnects, so the origin — and thus
- * the entire chat store — changed out from under the user, stranding history on
- * old ports. Keeping it on the daemon makes it independent of port, origin, and
- * even which machine connects: reconnect from anywhere and the chats are there.
+ * Two hard-won identity lessons live here:
+ *
+ * 1. localStorage is per-origin (scheme://host:PORT), and a tunnelled GUI's
+ *    port changes across reconnects — so history kept only in the browser gets
+ *    stranded on dead origins. Hence a server-side store at all.
+ *
+ * 2. Agent IDs are NOT stable: every rotation/resume mints a new id. A store
+ *    keyed by id fragments on every rotation — the full history stays under
+ *    the dead id while the new id starts near-empty, and a reconnect then
+ *    "restores" that near-empty stub over the user's real history. The agent
+ *    NAME survives rotation (the Watch system keys by name for the same
+ *    reason), so name is the identity here. IDs are accepted at the API edge
+ *    and resolved immediately.
  */
 export class ChatStore {
   constructor(daemon) {
@@ -36,6 +43,50 @@ export class ChatStore {
     return {};
   }
 
+  // Resolve an id-or-name to the stable storage key (the agent's name).
+  // Unknown refs are used verbatim so nothing is ever dropped — an orphaned
+  // id key re-merges at boot once its agent is known, or stays parked.
+  _keyFor(ref) {
+    if (!ref) return null;
+    const byId = this.daemon.registry?.get?.(ref);
+    if (byId?.name) return byId.name;
+    return String(ref);
+  }
+
+  /**
+   * Fold any id-keyed entries into their agent's name key. Runs at boot (after
+   * registry restore) so stores written by the old id-keyed code reattach to
+   * the agent wherever the id is still resolvable.
+   */
+  migrate() {
+    const agents = this.daemon.registry?.getAll?.() || [];
+    const byId = new Map(agents.map((a) => [a.id, a]));
+    let moved = 0;
+    for (const key of Object.keys(this.history)) {
+      const agent = byId.get(key);
+      if (!agent || agent.name === key) continue;
+      this.history[agent.name] = mergeMessages(this.history[agent.name], this.history[key]);
+      delete this.history[key];
+      moved += 1;
+    }
+    if (moved) this._scheduleSave();
+    return moved;
+  }
+
+  /**
+   * Rotation-time hook: an entry parked under a dead id (written by the old
+   * id-keyed code, or by an old GUI posting under ids) follows the agent to
+   * its new identity.
+   */
+  remap(oldRef, newRef) {
+    const oldKey = String(oldRef);
+    const newKey = this._keyFor(newRef);
+    if (!newKey || oldKey === newKey || !this.history[oldKey]) return;
+    this.history[newKey] = mergeMessages(this.history[newKey], this.history[oldKey]);
+    delete this.history[oldKey];
+    this._scheduleSave();
+  }
+
   _scheduleSave() {
     if (this._saveTimer) return;
     this._saveTimer = setTimeout(() => {
@@ -64,35 +115,59 @@ export class ChatStore {
     return out;
   }
 
-  append(agentId, message) {
-    if (!agentId) return;
+  append(ref, message) {
+    const key = this._keyFor(ref);
+    if (!key) return;
     const clean = this._clean(message);
     if (!clean) return;
-    const arr = this.history[agentId] || [];
+    const arr = this.history[key] || [];
     arr.push(clean);
-    this.history[agentId] = arr.slice(-MAX_PER_AGENT);
+    this.history[key] = arr.slice(-MAX_PER_AGENT);
     this._scheduleSave();
   }
 
-  // Replace an agent's whole history — used when the GUI syncs a batch (e.g.
-  // messages it recorded while briefly disconnected).
-  replace(agentId, messages) {
-    if (!agentId || !Array.isArray(messages)) return;
-    this.history[agentId] = messages.map((m) => this._clean(m)).filter(Boolean).slice(-MAX_PER_AGENT);
+  /**
+   * Merge a batch from a client. This is a UNION by (timestamp, from, text) —
+   * never a replace — so a browser holding messages the server missed adds
+   * them, and a browser with less than the server can never truncate it.
+   * A "restore" must be incapable of destroying what it restores from.
+   */
+  merge(ref, messages) {
+    const key = this._keyFor(ref);
+    if (!key || !Array.isArray(messages)) return;
+    const incoming = messages.map((m) => this._clean(m)).filter(Boolean);
+    this.history[key] = mergeMessages(this.history[key], incoming);
     this._scheduleSave();
   }
 
+  /**
+   * History for the GUI: live agents keyed by their CURRENT id (what the GUI
+   * looks up by), everything else under its stored name key so an agent
+   * respawned under the same name picks its history back up.
+   */
+  view() {
+    const out = {};
+    const agents = this.daemon.registry?.getAll?.() || [];
+    const liveNames = new Map(agents.map((a) => [a.name, a.id]));
+    for (const [key, msgs] of Object.entries(this.history)) {
+      if (!Array.isArray(msgs) || !msgs.length) continue;
+      out[liveNames.get(key) || key] = msgs;
+    }
+    return out;
+  }
+
   getAll() {
     return this.history;
   }
 
-  get(agentId) {
-    return this.history[agentId] || [];
+  get(ref) {
+    return this.history[this._keyFor(ref)] || [];
   }
 
-  remove(agentId) {
-    if (this.history[agentId]) {
-      delete this.history[agentId];
+  remove(ref) {
+    const key = this._keyFor(ref);
+    if (key && this.history[key]) {
+      delete this.history[key];
       this._scheduleSave();
     }
   }
@@ -102,3 +177,19 @@ export class ChatStore {
     this._saveNow();
   }
 }
+
+// Union of two message arrays, deduped on (timestamp, from, text), time-sorted,
+// capped. Exported for tests and the migration path.
+export function mergeMessages(a, b) {
+  const seen = new Set();
+  const out = [];
+  for (const m of [...(a || []), ...(b || [])]) {
+    if (!m || typeof m !== 'object') continue;
+    const sig = `${m.timestamp}:${m.from}:${typeof m.text === 'string' ? m.text.slice(0, 200) : ''}`;
+    if (seen.has(sig)) continue;
+    seen.add(sig);
+    out.push(m);
+  }
+  out.sort((x, y) => (x.timestamp || 0) - (y.timestamp || 0));
+  return out.slice(-MAX_PER_AGENT);
+}

package/packages/daemon/src/index.js

@@ -58,6 +58,7 @@ 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 { AxomRuntimes } from './axom-runtimes.js';
 import { setProviderPaths } from './providers/index.js';
 
 const DEFAULT_PORT = 31415;
@@ -175,6 +176,7 @@ export class Daemon {
     this.axomServer = new AxomServerManager(this);
     this.axomInstaller = new AxomInstaller(this);
     this.axomRemote = new AxomRemote(this);
+    this.axomRuntimes = new AxomRuntimes(this);
     this.trajectoryCapture = null;
 
     // Hook teams.delete to clean up agent-loop session files
@@ -438,6 +440,12 @@ export class Daemon {
   }
 
   broadcast(message) {
+    // Every rotation/resume path announces itself here — the one chokepoint
+    // for "this agent has a new id". Chat history parked under the dead id
+    // (stale client posts, pre-migration data) follows the agent.
+    if (message.type === 'rotation:complete' && message.oldAgentId && message.agentId) {
+      try { this.chatStore.remap(message.oldAgentId, message.agentId); } catch { /* best effort */ }
+    }
     if (!this.wss) return;
     const payload = JSON.stringify(message);
     for (const client of this.wss.clients) {
@@ -636,10 +644,17 @@ export class Daemon {
         this.orchestrator.start();
         this.timeline.start();
         this.gateways.start();
-        this.axom.start();
+        this.axomRuntimes.start();
         this.federation.initialize();
         this._startGarbageCollector();
 
+        // Fold id-keyed chat history into name keys now that the registry is
+        // restored — reattaches histories written by the old id-keyed store.
+        try {
+          const moved = this.chatStore.migrate();
+          if (moved) console.log(`[chat] migrated ${moved} id-keyed histories to agent names`);
+        } catch { /* best effort */ }
+
         // Regenerate the on-disk registry files once on boot. They otherwise
         // only refresh on a registry change, so a daemon upgraded with new
         // agent-facing docs (InnerChat, Watch) would serve stale AGENTS_REGISTRY.md

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

@@ -89,6 +89,10 @@ export function registerAgentRoutes(app, daemon) {
       // Killed/completed agents stay visible so the user can review output.
       const purge = req.query.purge === 'true';
       if (purge) {
+        // Clear chat history while the id still resolves to a name — the
+        // store is name-keyed, and a purged name's history must not haunt a
+        // future agent spawned under the same name.
+        try { daemon.chatStore.remove(agent.name); } catch { /* best effort */ }
         daemon.registry.remove(req.params.id);
       }
 

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

@@ -122,6 +122,79 @@ export function registerAxomRoutes(app, daemon) {
     }
   });
 
+  // ── Runtimes — the one entity (plans/axom-runtime-flow-redesign.md) ─────
+  // The GUI reasons about runtimes only; endpoints/instances/ssh are backends.
+
+  app.get('/api/axom/runtimes', async (req, res) => {
+    res.json(await daemon.axomRuntimes.status());
+  });
+
+  app.post('/api/axom/runtimes', (req, res) => {
+    try {
+      const rt = daemon.axomRuntimes.add(req.body);
+      if (req.body?.activate) daemon.axomRuntimes.activate(rt.id);
+      daemon.audit.log('axom.runtime.add', { id: rt.id, control: rt.control });
+      res.json(rt);
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  app.patch('/api/axom/runtimes/:id', (req, res) => {
+    try {
+      res.json(daemon.axomRuntimes.update(req.params.id, req.body || {}));
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  app.delete('/api/axom/runtimes/:id', (req, res) => {
+    try {
+      daemon.axomRuntimes.remove(req.params.id);
+      daemon.audit.log('axom.runtime.remove', { id: req.params.id });
+      res.json({ ok: true });
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/runtimes/:id/activate', (req, res) => {
+    try {
+      daemon.axomRuntimes.activate(req.params.id);
+      res.json({ ok: true, activeRuntimeId: req.params.id });
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/runtimes/:id/start', async (req, res) => {
+    try {
+      const result = await daemon.axomRuntimes.startRuntime(req.params.id);
+      daemon.audit.log('axom.runtime.start', { id: req.params.id });
+      res.json(result);
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/runtimes/:id/stop', async (req, res) => {
+    try {
+      const result = await daemon.axomRuntimes.stopRuntime(req.params.id, { force: !!req.body?.force });
+      daemon.audit.log('axom.runtime.stop', { id: req.params.id });
+      res.json(result);
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/runtimes/:id/heal', async (req, res) => {
+    try {
+      res.json(await daemon.axomRuntimes.heal(req.params.id));
+    } 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) => {