groove-dev 0.27.207 → 0.27.208

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

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

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

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

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

@@ -186,6 +186,7 @@ export class AxomConnector {
           live: !!info.live,
           ws: null,
           lastSeq: 0,
+          epoch: null,
           ring: [],
           overflow: 0,
           unknownKinds: {},
@@ -209,14 +210,35 @@ export class AxomConnector {
 
   _watchSession(ep, s) {
     if (this.destroyed) return;
-    const since = s.lastSeq > 0 ? `?since=ev-${String(s.lastSeq).padStart(6, '0')}` : '';
-    const wsUrl = `${ep.url.replace(/^http/, 'ws')}/ws/session/${encodeURIComponent(s.id)}${since}`;
+    // §16.4: reconnects carry both cursor and epoch; a stale epoch voids the
+    // cursor runtime-side and we get a full replay instead of a silent gap.
+    const params = [];
+    if (s.lastSeq > 0) params.push(`since=ev-${String(s.lastSeq).padStart(6, '0')}`);
+    if (s.epoch) params.push(`epoch=${encodeURIComponent(s.epoch)}`);
+    const query = params.length ? `?${params.join('&')}` : '';
+    const wsUrl = `${ep.url.replace(/^http/, 'ws')}/ws/session/${encodeURIComponent(s.id)}${query}`;
     const ws = new WebSocket(wsUrl);
     s.ws = ws;
 
     ws.on('message', (data) => {
       let envelope;
       try { envelope = JSON.parse(data.toString()); } catch { return; }
+      // §16.4 handshake frame — transport metadata, never a transcript event.
+      // A changed epoch means the runtime restarted and its event ids reset:
+      // our monotonic dedup would silently swallow the entire replay, so the
+      // cursor, ring, and GUI copy are all voided together.
+      if (envelope.kind === 'ws_hello') {
+        const epoch = envelope.payload?.epoch;
+        if (epoch && s.epoch && epoch !== s.epoch) {
+          s.lastSeq = 0;
+          s.ring = [];
+          s.overflow = 0;
+          s.unknownKinds = {};
+          this.daemon.broadcast({ type: 'axom:session:reset', endpoint: ep.name, session: s.id, epoch });
+        }
+        if (epoch) s.epoch = epoch;
+        return;
+      }
       const seq = seqOf(envelope.id);
       // Dedup on ring-buffer replay after reconnect — ids are monotonic.
       if (seq !== null && seq <= s.lastSeq) return;
@@ -371,6 +393,32 @@ export class AxomConnector {
 
   _broadcastStatus() {
     this.daemon.broadcast({ type: 'axom:status', data: this.status() });
+    // Runtime-level state is derived from connector state — push it too so
+    // the GUI's runtime cards move on events, not on a poll.
+    this.daemon.axomRuntimes?.broadcastStatus?.();
+  }
+
+  // Collapse the 'running but not connected' window: when a runtime is known
+  // to be answering /about, don't make the user wait out our backoff.
+  nudge(name) {
+    const ep = this.endpoints.get(name);
+    if (!ep || ep.status === 'connected' || this.destroyed) return;
+    if (ep.retryTimer) { clearTimeout(ep.retryTimer); ep.retryTimer = null; }
+    ep.backoffMs = this.backoffBaseMs;
+    this._handshake(ep);
+  }
+
+  // The inverse of nudge: after a deliberate stop, 'connected' is presumed
+  // stale — re-probe now so the endpoint transitions (and broadcasts) with the
+  // verb instead of lingering until the next scheduled poll fails.
+  recheck(name) {
+    const ep = this.endpoints.get(name);
+    if (!ep || this.destroyed) return;
+    if (ep.status === 'connected') {
+      this._pollSessions(ep).catch(() => this._endpointLost(ep));
+    } else {
+      this.nudge(name);
+    }
   }
 
   _teardownEndpoint(ep) {

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

@@ -55,8 +55,8 @@ export class AxomRemote {
     return this.daemon.config?.axom?.remote || null;
   }
 
-  _ssh(command, timeoutMs = 30000) {
-    const cfg = this._config();
+  _ssh(command, timeoutMs = 30000, cfgOverride = null) {
+    const cfg = cfgOverride || 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}`));
@@ -71,14 +71,15 @@ export class AxomRemote {
   }
 
   // Is a runtime listening on the remote port right now?
-  async status() {
-    const cfg = this._config();
+  async status(cfgOverride = null) {
+    const cfg = cfgOverride || 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,
+        cfg,
       );
       return {
         configured: true,
@@ -94,11 +95,11 @@ export class AxomRemote {
     }
   }
 
-  async start() {
-    const cfg = this._config();
+  async start(cfgOverride = null) {
+    const cfg = cfgOverride || this._config();
     if (!cfg) throw new Error('no remote Axom host configured');
     const port = cfg.port || AXOM_DEFAULT_PORT;
-    const already = await this.status();
+    const already = await this.status(cfg);
     if (already.running) return { started: false, alreadyRunning: true, port };
 
     const command = cfg.command
@@ -112,12 +113,12 @@ export class AxomRemote {
     // NOTHING while reporting success. Found by running it.
     const log = cfg.logPath || '~/axom-serve/serve.log';
     const quoted = `'${command.replace(/'/g, `'\\''`)}'`;
-    await this._ssh(`nohup bash -lc ${quoted} >> ${log} 2>&1 < /dev/null & disown; echo STARTED`, 30000);
+    await this._ssh(`nohup bash -lc ${quoted} >> ${log} 2>&1 < /dev/null & disown; echo STARTED`, 30000, cfg);
 
     // 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();
+      const s = await this.status(cfg);
       if (s.running) {
         this.daemon.audit.log('axom.remote.start', { host: cfg.host, port });
         this._broadcast();
@@ -127,8 +128,8 @@ export class AxomRemote {
     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();
+  async stop({ force = false } = {}, cfgOverride = null) {
+    const cfg = cfgOverride || this._config();
     if (!cfg) throw new Error('no remote Axom host configured');
     const port = cfg.port || AXOM_DEFAULT_PORT;
 
@@ -141,6 +142,7 @@ export class AxomRemote {
         + `-H 'Content-Type: application/json' -d '{"force":${force ? 'true' : 'false'}}' `
         + `http://127.0.0.1:${port}/shutdown`,
         20000,
+        cfg,
       );
       const code = parseInt(stdout.trim().slice(-3), 10);
       if (code === 202) {
@@ -156,7 +158,7 @@ export class AxomRemote {
 
     // 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);
+    await this._ssh(`PID=$(lsof -t -i:${port} 2>/dev/null | head -1); [ -n "$PID" ] && kill $PID && echo KILLED || echo NOTFOUND`, 20000, cfg);
     this.daemon.audit.log('axom.remote.stop', { host: cfg.host, port, via: 'signal' });
     this._broadcast();
     return { stopped: true, via: 'signal' };
@@ -181,8 +183,8 @@ export class AxomRemote {
     }
   }
 
-  async ensureTunnel() {
-    const cfg = this._config();
+  async ensureTunnel(cfgOverride = null) {
+    const cfg = cfgOverride || this._config();
     if (!cfg) return { tunneled: false, reason: 'no remote configured' };
     const problem = validateRemote(cfg);
     if (problem) return { tunneled: false, reason: problem };

package/node_modules/@groove-dev/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/node_modules/@groove-dev/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/node_modules/@groove-dev/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
@@ -642,7 +644,7 @@ export class Daemon {
         this.orchestrator.start();
         this.timeline.start();
         this.gateways.start();
-        this.axom.start();
+        this.axomRuntimes.start();
         this.federation.initialize();
         this._startGarbageCollector();
 

package/node_modules/@groove-dev/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) => {

package/node_modules/@groove-dev/daemon/src/routes/watch.js

@@ -20,6 +20,17 @@ export function registerWatchRoutes(app, daemon) {
       if (!who) return res.status(404).json({ error: `Unknown agent: ${agent}` });
 
       const watch = daemon.watcher.create(who.id, { command, until, label, timeoutMs, intervalMs });
+      if (watch.reattached) {
+        return res.json({
+          ok: true,
+          watchId: watch.id,
+          reattached: true,
+          message: `That command is ALREADY RUNNING under watch ${watch.id} ("${watch.label}") — `
+            + 'this request re-attached to it instead of starting a second copy. '
+            + 'Do NOT launch it again by hand. You will be resumed with the result when it finishes; '
+            + 'you can end your turn now.',
+        });
+      }
       res.json({
         ok: true,
         watchId: watch.id,