groove-dev 0.27.198 → 0.27.199

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

@@ -1,6 +1,6 @@
 {
   "name": "@groove-dev/cli",
-  "version": "0.27.198",
+  "version": "0.27.199",
   "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.198",
+  "version": "0.27.199",
   "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

@@ -245,12 +245,14 @@ export class AxomConnector {
   // §12 message verb: starts a turn (interrupt steers, stop halts). Status is
   // part of the contract (202 accepted / 409 busy / 413 too_long) so this
   // returns {status, body} verbatim instead of throwing on non-2xx.
-  async message(endpointName, sessionId, text) {
+  async message(endpointName, sessionId, text, clientRef) {
     const ep = this._requireEndpoint(endpointName);
     const res = await fetch(`${ep.url}/session/${encodeURIComponent(sessionId)}/message`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ text }),
+      // §15: opaque, echoed back in pipeline_start. Omitted when absent so
+      // pre-§15 runtimes see exactly today's payload.
+      body: JSON.stringify(clientRef ? { text, client_ref: clientRef } : { text }),
       signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
     });
     const body = await res.json().catch(() => ({}));
@@ -260,6 +262,21 @@ export class AxomConnector {
     return { status: res.status, body };
   }
 
+  // §14: ends the RUNTIME (distinct from stop, which halts a turn). 409 when
+  // a turn is in flight unless forced; statuses pass through so the GUI can
+  // say what happened rather than guess.
+  async shutdown(endpointName, { force = false } = {}) {
+    const ep = this._requireEndpoint(endpointName);
+    const res = await fetch(`${ep.url}/shutdown`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ force }),
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    const body = await res.json().catch(() => ({}));
+    return { status: res.status, body };
+  }
+
   async interrupt(endpointName, sessionId, text) {
     const ep = this._requireEndpoint(endpointName);
     return this._fetch(ep, `/session/${encodeURIComponent(sessionId)}/interrupt`, {
@@ -295,6 +312,14 @@ export class AxomConnector {
   }
 
   status() {
+    // A runtime we spawned can be shut down; one we merely connected to
+    // cannot (no signal reaches another machine's process). The GUI needs
+    // this to avoid offering a kill switch it can't honor.
+    const managed = new Set(
+      (this.daemon.axomServer?.list?.() || [])
+        .filter((i) => i.status === 'running')
+        .map((i) => `http://127.0.0.1:${i.port}`),
+    );
     return {
       endpoints: [...this.endpoints.values()].map((ep) => ({
         name: ep.name,
@@ -303,6 +328,9 @@ export class AxomConnector {
         error: ep.error,
         about: ep.about,
         drift: ep.drift,
+        managed: managed.has(ep.url),
+        instanceId: (this.daemon.axomServer?.list?.() || [])
+          .find((i) => i.status === 'running' && `http://127.0.0.1:${i.port}` === ep.url)?.id || null,
         sessions: [...ep.sessions.values()].map((s) => ({
           session: s.id,
           started: s.started,

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

@@ -29,8 +29,17 @@ export class AxomInstaller {
     this._running = false;
   }
 
+  // Availability is a first-class answer, not an error string. A GROOVE build
+  // with no manifest configured cannot install Axom at all — the UI must say
+  // so up front rather than offering a button that fails on click.
   getStatus() {
-    return { ...this.status };
+    const manifestUrl = this.daemon.config?.axom?.manifestUrl || null;
+    return {
+      ...this.status,
+      available: !!manifestUrl,
+      manifestUrl,
+      unavailableReason: manifestUrl ? null : 'Coming soon',
+    };
   }
 
   _update(patch) {
@@ -39,8 +48,12 @@ export class AxomInstaller {
   }
 
   async install(manifestUrl) {
+    // Gate, don't explain: a build with no configured distribution simply
+    // cannot install. The UI shows "Coming soon" and never offers the action;
+    // this is the server-side half of the same gate (a hand-crafted POST
+    // can't bypass it either).
     const url = manifestUrl || this.daemon.config?.axom?.manifestUrl;
-    if (!url) throw new Error('no install manifest configured (axom.manifestUrl)');
+    if (!url) throw new Error('Coming soon — Axom is not yet available for local install.');
     if (this._running) throw new Error('an install is already running');
     // Same hardware floor as the instance manager — never download 4GB of
     // weights onto a machine that can't safely run them. Manifest min_ram_gb
@@ -58,6 +71,12 @@ export class AxomInstaller {
     try {
       this._update({ phase: 'manifest', file: null, receivedBytes: 0, totalBytes: 0, error: null });
       const res = await fetch(url, { signal: AbortSignal.timeout(15000) });
+      if (res.status === 401 || res.status === 403) {
+        throw new Error('This Axom build is private — your account does not have access to the distribution. Connect to an Axom running elsewhere instead.');
+      }
+      if (res.status === 404) {
+        throw new Error(`No Axom distribution found at ${url} — the configured manifest URL is wrong or the release was removed.`);
+      }
       if (!res.ok) throw new Error(`manifest fetch failed: HTTP ${res.status}`);
       const manifest = await res.json();
       if (!Array.isArray(manifest.models)) throw new Error('manifest has no models list');
@@ -106,6 +125,9 @@ export class AxomInstaller {
     this._update({ phase: 'models', file, receivedBytes: 0, totalBytes: bytes || 0 });
 
     const res = await fetch(url);
+    if (res.status === 401 || res.status === 403) {
+      throw new Error(`${file} is in a private repository your account can't read — the model weights are gated. Nothing was installed.`);
+    }
     if (!res.ok || !res.body) throw new Error(`download failed for ${file}: HTTP ${res.status}`);
 
     const hash = createHash('sha256');

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