groove-dev 0.27.49 → 0.27.51

package/default/security-review-prompt.md

@@ -0,0 +1,98 @@
+# Security Review: Groove Network Integration
+
+You are auditing the Groove Network feature — a decentralized LLM inference network integrated into the Groove desktop app. This feature is beta-gated behind invite codes. Review all network-related code for security vulnerabilities and attack vectors.
+
+## Scope
+
+All code added in these commits (newest first):
+- daemon: switch network from relay to signal service
+- gui: handle signal_connected and matched WS events in network feed
+- daemon: spawn Python from venv so msgpack/torch are available
+- daemon: use python3.12 for brew Python
+- network: wire install/uninstall endpoints with progress broadcast
+- network: gate view on network package install
+- beta: validate invite codes against groovedev.ai with offline fallback
+- settings: hide groove-network provider from Settings UI
+- provider: default claude-code to Opus 4.6
+- network: add beta-gated Groove Network integration
+
+## Files to Review
+
+Daemon (packages/daemon/src/):
+- api.js — search for "Network" section (~lines 3720-4200): beta gate, invite code validation, node start/stop, install/uninstall, network status, version check/update endpoints
+- providers/groove-network.js — provider that spawns Python consumer subprocess
+- providers/index.js — provider registration
+- index.js — networkNode state, startup re-validation
+- firstrun.js — networkBeta config defaults
+
+GUI (packages/gui/src/):
+- views/network.jsx — install gate, main network view
+- views/settings.jsx — Early Access invite code section
+- stores/groove.js — networkUnlocked state, install/update progress, WebSocket handlers
+- components/network/* — NodeToggle, NetworkStatus, NodeDetails
+- components/layout/activity-bar.jsx — conditional Globe icon
+
+## Threat Model
+
+The feature involves:
+1. An invite code system validating against a remote server (groovedev.ai)
+2. Cloning a GitHub repo to the user's machine and running a setup script
+3. Spawning Python subprocesses that connect outbound to a signal service (signal.groovedev.ai)
+4. WebSocket connections to an external service carrying msgpack-encoded inference data
+5. Ethereum-style keypair stored at ~/.groove/node_key.json
+6. Config persistence with unlocked state, codes, and paths
+
+## Attack Vectors to Investigate
+
+### Code Execution & Injection
+- Can the install endpoint be tricked into cloning a malicious repo? (repo URL hardcoded or configurable?)
+- Does setup.sh run with proper sandboxing? What if the repo contents are compromised?
+- Are Python spawn commands safe from injection? (check all spawn() calls use array args, not shell strings)
+- Can the deployPath config value be manipulated to point outside ~/.groove/?
+- Is the git clone --depth 1 safe from git-specific attacks?
+
+### Authentication & Authorization
+- Can the beta gate be bypassed? (check all /api/network/* endpoints go through networkGate)
+- Is the hardcoded fallback code list a risk? (codes visible in source)
+- Can invite codes be brute-forced? (rate limiting — daemon side and server side)
+- Is the machineId derivation stable and non-spoofable?
+- Can a deactivated user re-activate by manipulating local config?
+
+### Network Security
+- Is the WebSocket connection to signal.groovedev.ai using TLS? (wss:// vs ws://)
+- Can a MITM intercept inference data between node and signal?
+- Is the signal URL validated? Can it be pointed to a malicious server via config manipulation?
+- Are there SSRF risks from the network status fetch?
+- Does the daemon properly validate responses from groovedev.ai and signal.groovedev.ai?
+
+### Data Security
+- Is the node keypair (~/.groove/node_key.json) properly protected? (file permissions)
+- Is the private key ever exposed via API endpoints or logs?
+- Are invite codes logged in full or truncated?
+- Can the API credentials endpoint leak the beta code?
+- Is config.networkBeta.code exposed in GET /api/config?
+
+### Denial of Service
+- Can the install/update endpoints be called repeatedly to exhaust disk?
+- Is there a limit on networkEvents array growth?
+- Can the node process be spawned multiple times simultaneously?
+- Does the version check cache actually prevent GitHub API abuse?
+
+### Filesystem Safety
+- Does uninstall properly scope deletion to ~/.groove/network/?
+- Can path traversal in deployPath escape the intended directory?
+- Are there symlink attacks possible in the install path?
+- Does rmSync with recursive: true risk deleting unintended files?
+
+### Supply Chain
+- The install clones from GitHub — is the repo URL hardcoded or injectable?
+- Is the tag pinned or can an attacker push a malicious tag?
+- setup.sh runs arbitrary shell — what if the repo is compromised?
+
+## Deliverables
+
+1. List every vulnerability found with severity (critical/high/medium/low)
+2. For each: describe the attack, the affected file and line number, and the fix
+3. Flag any patterns that are risky even if not immediately exploitable
+4. Confirm which security measures are already in place and working correctly
+5. Commit all fixes

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

@@ -1,6 +1,6 @@
 {
   "name": "@groove-dev/cli",
-  "version": "0.27.49",
+  "version": "0.27.51",
   "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.49",
+  "version": "0.27.51",
   "description": "GROOVE daemon — agent orchestration engine",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/node_modules/@groove-dev/daemon/src/api.js

@@ -12,6 +12,7 @@ import { lookup as mimeLookup } from './mimetypes.js';
 import { listProviders, getProvider } from './providers/index.js';
 import { OllamaProvider } from './providers/ollama.js';
 import { ClaudeCodeProvider } from './providers/claude-code.js';
+import { supportsSignalFlag, compareSemver, parseSemver } from './providers/groove-network.js';
 import { validateAgentConfig } from './validate.js';
 import { ROLE_INTEGRATIONS } from './process.js';
 
@@ -3674,7 +3675,13 @@ Keep responses concise. Help them think, don't lecture them about the system the
   // --- Config ---
 
   app.get('/api/config', (req, res) => {
-    res.json(daemon.config || {});
+    const cfg = daemon.config || {};
+    const sanitized = { ...cfg };
+    if (sanitized.networkBeta) {
+      sanitized.networkBeta = { ...sanitized.networkBeta };
+      delete sanitized.networkBeta.code;
+    }
+    res.json(sanitized);
   });
 
   app.patch('/api/config', async (req, res) => {
@@ -3724,18 +3731,26 @@ Keep responses concise. Help them think, don't lecture them about the system the
 
   // --- Groove Network (Beta) ---
 
-  // Offline fallback allowlist — used only when groovedev.ai is unreachable
-  // so beta testers aren't locked out by network failures.
-  const BETA_CODES_FALLBACK = new Set([
-    'GROOVE-NET-ALPHA-001',
-    'GROOVE-NET-ALPHA-002',
-    'GROOVE-NET-ALPHA-003',
-    'GROOVE-NET-ALPHA-004',
-    'GROOVE-NET-ALPHA-005',
+  // Offline fallback allowlist — SHA-256 hashes of valid codes so plaintext
+  // codes aren't exposed in source. Used only when groovedev.ai is unreachable.
+  const BETA_CODES_FALLBACK_HASHES = new Set([
+    '2dd41c615fd155f322e8381fed28f346ed6592e2bbab1c068f156fa225c02110',
+    '034d771385b608bb85d8f0225c561fe3c084b8ce7851221b01f9c2226dfe3e7b',
+    'fad2c7b09f9161db518d8c9a8d338831eb3894ef0f36e2c7cb1884cffbb05768',
+    '0ff4c9c1d224e59ac370d6f4bf315ae2ec750af014758c8206f38980cb7603ba',
+    '08b2ffe7f40afe2894db335860d67af877fa31201b3e2c25736480eb3f7c58ef',
   ]);
 
+  function hashCode(code) {
+    return createHash('sha256').update(code).digest('hex');
+  }
+
   const BETA_VALIDATE_URL = 'https://groovedev.ai/api/beta/validate';
 
+  const betaAttempts = [];
+  const BETA_RATE_LIMIT = 5;
+  const BETA_RATE_WINDOW_MS = 60_000;
+
   function getMachineId() {
     const nets = networkInterfaces();
     const macs = [];
@@ -3790,6 +3805,13 @@ Keep responses concise. Help them think, don't lecture them about the system the
   });
 
   app.post('/api/beta/activate', async (req, res) => {
+    const now = Date.now();
+    while (betaAttempts.length && betaAttempts[0] < now - BETA_RATE_WINDOW_MS) betaAttempts.shift();
+    if (betaAttempts.length >= BETA_RATE_LIMIT) {
+      return res.status(429).json({ error: 'Too many attempts. Try again in a minute.' });
+    }
+    betaAttempts.push(now);
+
     const { code } = req.body || {};
     if (typeof code !== 'string' || code.length > 64 || !/^[A-Z0-9-]+$/.test(code)) {
       return res.status(400).json({ error: 'Invalid code format' });
@@ -3811,9 +3833,9 @@ Keep responses concise. Help them think, don't lecture them about the system the
       }
       if (Array.isArray(remote.result.features)) features = remote.result.features;
     } else {
-      // Offline fallback — only trust the hardcoded list when we can't reach the server
+      // Offline fallback — only trust the hashed list when we can't reach the server
       source = 'fallback';
-      if (BETA_CODES_FALLBACK.has(code)) {
+      if (BETA_CODES_FALLBACK_HASHES.has(hashCode(code))) {
         valid = true;
         message = 'Activated (offline)';
         features = ['network-node', 'network-consumer'];
@@ -3977,7 +3999,10 @@ Keep responses concise. Help them think, don't lecture them about the system the
     }
 
     const cfg = daemon.config.networkBeta || {};
-    const relay = cfg.relayUrl || 'localhost:8770';
+    const signal = stripScheme(cfg.signalUrl);
+    if (!isAllowedSignalHost(signal)) {
+      return res.status(400).json({ error: 'Invalid signal host' });
+    }
     const device = cfg.devicePreference || 'auto';
     const maxContext = Number.isFinite(cfg.maxContext) ? cfg.maxContext : 4096;
 
@@ -3993,16 +4018,18 @@ Keep responses concise. Help them think, don't lecture them about the system the
       return res.status(400).json({ error: `Deploy path not found: ${deployPath}` });
     }
 
+    const signalFlag = supportsSignalFlag(cfg.version) ? '--signal' : '--relay';
     const args = [
       '-m', 'src.node.server',
-      '--relay', relay,
+      signalFlag, signal,
+      '--tls',
       '--device', device,
       '--max-context', String(maxContext),
     ];
 
     let proc;
     try {
-      proc = spawn(join(deployPath, 'venv', 'bin', 'python3.12'), args, {
+      proc = spawn(join(deployPath, 'venv', 'bin', 'python3'), args, {
         cwd: deployPath,
         env: { ...process.env, PYTHONUNBUFFERED: '1' },
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -4025,7 +4052,7 @@ Keep responses concise. Help them think, don't lecture them about the system the
       events: [],
     };
 
-    pushNodeEvent('starting', { pid: proc.pid, relay, device });
+    pushNodeEvent('starting', { pid: proc.pid, signal, device });
     broadcastNodeStatus();
 
     let stderrBuf = '';
@@ -4037,7 +4064,33 @@ Keep responses concise. Help them think, don't lecture them about the system the
         stderrBuf = stderrBuf.slice(idx + 1);
         if (!line) continue;
         if (line[0] !== '{') {
+          // Python node emits plain-text logs like "Node identity: abc123",
+          // "shard loaded: layers 0-12", "registered with signal". Parse those
+          // here so the GUI reflects reality even without structured logging.
+          let changed = false;
+          const idMatch = line.match(/Node identity:\s*([A-Za-z0-9_\-:.]+)/i);
+          if (idMatch && idMatch[1] !== daemon.networkNode.nodeId) {
+            daemon.networkNode.nodeId = idMatch[1]; changed = true;
+          }
+          const layerMatch = line.match(/layers?\s*(\d+)\s*[-–to]+\s*(\d+)/i);
+          if (layerMatch) {
+            const start = parseInt(layerMatch[1], 10);
+            const end = parseInt(layerMatch[2], 10);
+            if (Number.isFinite(start) && Number.isFinite(end)) {
+              daemon.networkNode.layers = [start, end]; changed = true;
+            }
+          }
+          const modelMatch = line.match(/model[:\s]+([A-Za-z0-9_\-./]+\/[A-Za-z0-9_\-.]+)/i);
+          if (modelMatch && modelMatch[1] !== daemon.networkNode.model) {
+            daemon.networkNode.model = modelMatch[1]; changed = true;
+          }
+          if (/\bregistered\b/i.test(line) || /\bconnected\b/i.test(line)) {
+            if (daemon.networkNode.status !== 'connected') {
+              daemon.networkNode.status = 'connected'; changed = true;
+            }
+          }
           pushNodeEvent('log', { line });
+          if (changed) broadcastNodeStatus();
           continue;
         }
         let entry;
@@ -4090,7 +4143,7 @@ Keep responses concise. Help them think, don't lecture them about the system the
       broadcastNodeStatus();
     });
 
-    daemon.audit.log('network.node.start', { pid: proc.pid, relay, device });
+    daemon.audit.log('network.node.start', { pid: proc.pid, signal, device });
     res.status(202).json({ started: true, ...snapshotNode() });
   });
 
@@ -4111,9 +4164,59 @@ Keep responses concise. Help them think, don't lecture them about the system the
     res.json({ stopping: true });
   });
 
-  app.get('/api/network/status', networkGate, (req, res) => {
-    // Mocked relay status until the relay /status HTTP endpoint lands.
-    // Shape matches the spec in groove-comms/GETTING-STARTED.md.
+  function isAllowedSignalHost(host) {
+    const h = (host || '').replace(/^(wss?|https?):\/\//i, '').replace(/\/.*$/, '').toLowerCase();
+    return h === 'signal.groovedev.ai' || h.endsWith('.groovedev.ai');
+  }
+
+  // The Python node/client code prepends the scheme itself from `--tls`.
+  // Daemon must pass a BARE host to --relay/--signal; otherwise the Python
+  // side ends up with a double-scheme URI like wss://wss://host.
+  function stripScheme(url) {
+    if (!url) return 'signal.groovedev.ai';
+    return url.replace(/^wss?:\/\//i, '').replace(/\/.*$/, '');
+  }
+
+  app.get('/api/network/status', networkGate, async (req, res) => {
+    const cfg = daemon.config.networkBeta || {};
+    const signalHost = cfg.signalUrl || 'signal.groovedev.ai';
+
+    if (!isAllowedSignalHost(signalHost)) {
+      return res.status(400).json({ error: 'Invalid signal host' });
+    }
+
+    const bareHost = signalHost.replace(/^(wss?|https?):\/\//i, '').replace(/\/.*$/, '');
+    const statusUrl = `https://${bareHost}/status`;
+
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), 5000);
+      const r = await fetch(statusUrl, { signal: controller.signal });
+      clearTimeout(timer);
+      if (r.ok) {
+        const data = await r.json();
+        // Signal service returns snake_case; GUI expects camelCase.
+        const models = Array.isArray(data.models) ? data.models.map((m) => {
+          if (!m || typeof m !== 'object') return m;
+          const { covered_layers, total_layers, ...rest } = m;
+          return {
+            ...rest,
+            ...(covered_layers !== undefined ? { coveredLayers: covered_layers } : {}),
+            ...(total_layers !== undefined ? { totalLayers: total_layers } : {}),
+          };
+        }) : [];
+        return res.json({
+          nodes: Array.isArray(data.nodes) ? data.nodes : [],
+          models,
+          coverage: data.covered_layers ?? data.coverage ?? 0,
+          totalLayers: data.total_layers ?? data.totalLayers ?? 24,
+          activeSessions: data.active_sessions ?? data.activeSessions ?? 0,
+          totalNodes: data.total_nodes ?? data.totalNodes ?? (Array.isArray(data.nodes) ? data.nodes.length : 0),
+        });
+      }
+    } catch { /* fall through to local snapshot */ }
+
+    // Fallback: local node snapshot when signal is unreachable.
     const node = daemon.networkNode || {};
     const selfNode = node.active && node.nodeId ? [{
       node_id: node.nodeId,
@@ -4128,23 +4231,29 @@ Keep responses concise. Help them think, don't lecture them about the system the
       coverage,
       totalLayers: 24,
       activeSessions: node.sessions || 0,
+      totalNodes: selfNode.length,
     });
   });
 
   // --- Network package install/uninstall ---
 
   const NETWORK_REPO_URL = 'https://github.com/grooveai-dev/groove-network.git';
-  const NETWORK_VERSION = 'v0.1.0';
+  const NETWORK_VERSION = 'v0.2.0';
 
   function networkRoot() {
     return resolve(homedir(), '.groove', 'network');
   }
 
   // Defensive: only permit fs ops on paths that resolve inside ~/.groove/.
+  // Uses realpathSync when the path exists to defeat symlink escapes.
   function isInsideGrooveHome(target) {
     const home = resolve(homedir(), '.groove') + '/';
-    const full = resolve(target) + '/';
-    return full.startsWith(home);
+    const resolved = resolve(target);
+    let full;
+    try { full = existsSync(resolved) ? realpathSync(resolved) + '/' : resolved + '/'; }
+    catch { full = resolved + '/'; }
+    const realHome = existsSync(home.slice(0, -1)) ? realpathSync(home.slice(0, -1)) + '/' : home;
+    return full.startsWith(realHome);
   }
 
   function broadcastInstallProgress(step, message, percent) {
@@ -4209,21 +4318,33 @@ Keep responses concise. Help them think, don't lecture them about the system the
           ? NETWORK_REPO_URL.replace('https://', `https://${pat}@`)
           : NETWORK_REPO_URL;
 
-        broadcastInstallProgress('cloning', 'Cloning network package...', 0);
+        // Resolve the latest released tag so fresh installs track new releases
+        // without requiring a code change. Falls back to NETWORK_VERSION if the
+        // remote lookup fails (offline, rate-limited, no tags yet).
+        let installVersion;
+        try {
+          installVersion = (await getLatestNetworkTag()) || NETWORK_VERSION;
+        } catch {
+          installVersion = NETWORK_VERSION;
+        }
 
-        const cloneArgs = ['clone', '--branch', NETWORK_VERSION, '--depth', '1', cloneUrl, installPath];
+        broadcastInstallProgress('cloning', `Cloning network package ${installVersion}...`, 0);
+
+        const cloneArgs = ['clone', '--branch', installVersion, '--depth', '1', cloneUrl, installPath];
         const clone = spawn('git', cloneArgs, {
           stdio: ['ignore', 'pipe', 'pipe'],
           env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
         });
 
+        const stripCredentials = (s) => s.replace(/https:\/\/[^@]+@/g, 'https://***@');
+
         let cloneErr = '';
         clone.stderr.on('data', (chunk) => {
           const s = chunk.toString();
           cloneErr += s;
           // git writes progress to stderr — relay last line as status.
           const line = s.split('\n').map((l) => l.trim()).filter(Boolean).pop();
-          if (line) broadcastInstallProgress('cloning', line, 5);
+          if (line) broadcastInstallProgress('cloning', stripCredentials(line), 5);
         });
 
         const cloneCode = await new Promise((resolveClone) => {
@@ -4232,7 +4353,7 @@ Keep responses concise. Help them think, don't lecture them about the system the
         });
 
         if (cloneCode.code !== 0) {
-          const hint = cloneErr.trim().split('\n').slice(-1)[0] || 'git clone failed';
+          const hint = stripCredentials(cloneErr.trim().split('\n').slice(-1)[0] || 'git clone failed');
           return fail(`Clone failed: ${hint}`);
         }
 
@@ -4285,12 +4406,12 @@ Keep responses concise. Help them think, don't lecture them about the system the
           ...(daemon.config.networkBeta || {}),
           installed: true,
           deployPath: installPath,
-          version: NETWORK_VERSION,
+          version: installVersion,
         };
         await persistConfig();
         daemon.broadcast({ type: 'config:updated' });
-        broadcastInstallProgress('done', 'Network package installed', 100);
-        daemon.audit.log('network.install', { path: installPath, version: NETWORK_VERSION });
+        broadcastInstallProgress('done', `Network package ${installVersion} installed`, 100);
+        daemon.audit.log('network.install', { path: installPath, version: installVersion });
         daemon.networkInstall = { running: false };
       } catch (err) {
         fail(err?.message || 'Install failed');
@@ -4339,6 +4460,232 @@ Keep responses concise. Help them think, don't lecture them about the system the
     res.json({ status: 'uninstalled' });
   });
 
+  // --- Network package update check / update ---
+
+  // 5-minute cache of the latest-tag lookup so startup + GUI polls don't
+  // hammer GitHub. Shape: { latest, fetchedAt }. null until first check.
+  let networkUpdateCache = null;
+  const NETWORK_UPDATE_CACHE_MS = 5 * 60 * 1000;
+
+  // Run `git ls-remote --tags <repo>` and return the highest semver tag.
+  // Resolves to null on git errors / network failure; caller decides how to
+  // surface that. Uses spawn with array args — no shell interpolation.
+  function fetchLatestNetworkTag() {
+    return new Promise((resolvePromise) => {
+      const proc = spawn('git', ['ls-remote', '--tags', NETWORK_REPO_URL], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+      });
+      let stdout = '';
+      let stderr = '';
+      proc.stdout.on('data', (c) => { stdout += c.toString(); });
+      proc.stderr.on('data', (c) => { stderr += c.toString(); });
+      const timeout = setTimeout(() => {
+        try { proc.kill('SIGTERM'); } catch { /* ignore */ }
+      }, 10_000);
+      proc.on('error', () => { clearTimeout(timeout); resolvePromise(null); });
+      proc.on('close', (code) => {
+        clearTimeout(timeout);
+        if (code !== 0) return resolvePromise(null);
+        const tags = [];
+        for (const line of stdout.split('\n')) {
+          // Format: <sha>\trefs/tags/v0.1.0 (or .../v0.1.0^{} for annotated)
+          const m = line.match(/refs\/tags\/(v?\d+\.\d+\.\d+[^\s^]*)(?:\^\{\})?$/);
+          if (m && parseSemver(m[1])) tags.push(m[1]);
+        }
+        if (tags.length === 0) return resolvePromise(null);
+        tags.sort(compareSemver);
+        resolvePromise(tags[tags.length - 1]);
+      });
+    });
+  }
+
+  async function getLatestNetworkTag(force = false) {
+    if (!force && networkUpdateCache && (Date.now() - networkUpdateCache.fetchedAt) < NETWORK_UPDATE_CACHE_MS) {
+      return networkUpdateCache.latest;
+    }
+    const latest = await fetchLatestNetworkTag();
+    if (latest) networkUpdateCache = { latest, fetchedAt: Date.now() };
+    return latest;
+  }
+
+  app.get('/api/network/update/check', networkGate, async (req, res) => {
+    const installed = daemon.config?.networkBeta?.version || null;
+    const force = req.query.force === '1' || req.query.force === 'true';
+    const latest = await getLatestNetworkTag(force);
+    if (!latest) {
+      return res.status(502).json({
+        installed,
+        latest: null,
+        updateAvailable: false,
+        error: 'Could not reach github.com to check for updates',
+      });
+    }
+    const updateAvailable = !!installed && compareSemver(latest, installed) > 0;
+    res.json({ installed, latest, updateAvailable });
+  });
+
+  function broadcastUpdateProgress(step, message, percent) {
+    daemon.broadcast({
+      type: 'network:update:progress',
+      data: { step, message, percent },
+    });
+  }
+
+  app.post('/api/network/update', networkGate, async (req, res) => {
+    if (daemon.networkInstall?.running) {
+      return res.status(409).json({ error: 'Install/update already in progress' });
+    }
+    if (!daemon.config?.networkBeta?.installed) {
+      return res.status(400).json({ error: 'Network package not installed' });
+    }
+
+    const installPath = networkRoot();
+    if (!existsSync(installPath) || !isInsideGrooveHome(installPath)) {
+      return res.status(400).json({ error: 'Install path missing or invalid' });
+    }
+
+    const latest = await getLatestNetworkTag(true);
+    if (!latest) {
+      return res.status(502).json({ error: 'Could not reach github.com to check for updates' });
+    }
+    const current = daemon.config.networkBeta.version || null;
+    if (current && compareSemver(latest, current) <= 0) {
+      return res.status(400).json({ error: 'Already at latest version', installed: current, latest });
+    }
+
+    daemon.networkInstall = { running: true, startedAt: Date.now(), kind: 'update' };
+    res.status(200).json({ status: 'updating', from: current, to: latest });
+
+    (async () => {
+      const fail = (message) => {
+        broadcastUpdateProgress('error', message, -1);
+        daemon.audit.log('network.update.failed', { message, from: current, to: latest });
+        daemon.networkInstall = { running: false };
+      };
+
+      try {
+        // Stop the running node first so we don't update files under its feet.
+        try {
+          const node = daemon.networkNode;
+          if (node?.active && node.proc && !node.proc.killed) {
+            try { node.proc.kill('SIGINT'); } catch { /* ignore */ }
+            daemon.networkNode.status = 'stopping';
+            pushNodeEvent('stopping', { pid: node.pid, reason: 'update' });
+            broadcastNodeStatus();
+            // Small grace window for the process to exit cleanly.
+            await new Promise((r) => setTimeout(r, 500));
+          }
+        } catch { /* ignore */ }
+
+        broadcastUpdateProgress('fetching', `Fetching ${latest}...`, 5);
+
+        const fetchProc = spawn('git', ['-C', installPath, 'fetch', '--tags', '--force'], {
+          stdio: ['ignore', 'pipe', 'pipe'],
+          env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        });
+        let fetchErr = '';
+        fetchProc.stderr.on('data', (c) => { fetchErr += c.toString(); });
+        const fetchCode = await new Promise((r) => {
+          fetchProc.on('error', (e) => r({ code: -1, err: e.message }));
+          fetchProc.on('close', (code) => r({ code }));
+        });
+        if (fetchCode.code !== 0) {
+          const hint = fetchErr.trim().split('\n').slice(-1)[0] || 'git fetch failed';
+          return fail(`Fetch failed: ${hint}`);
+        }
+
+        broadcastUpdateProgress('checkout', `Checking out ${latest}...`, 20);
+
+        const checkoutProc = spawn('git', ['-C', installPath, 'checkout', latest], {
+          stdio: ['ignore', 'pipe', 'pipe'],
+          env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        });
+        let checkoutErr = '';
+        checkoutProc.stderr.on('data', (c) => { checkoutErr += c.toString(); });
+        const checkoutCode = await new Promise((r) => {
+          checkoutProc.on('error', (e) => r({ code: -1, err: e.message }));
+          checkoutProc.on('close', (code) => r({ code }));
+        });
+        if (checkoutCode.code !== 0) {
+          const hint = checkoutErr.trim().split('\n').slice(-1)[0] || 'git checkout failed';
+          return fail(`Checkout failed: ${hint}`);
+        }
+
+        broadcastUpdateProgress('deps', 'Updating dependencies...', 30);
+
+        const setup = spawn('bash', ['setup.sh', '--json'], {
+          cwd: installPath,
+          stdio: ['ignore', 'pipe', 'pipe'],
+          env: { ...process.env, PYTHONUNBUFFERED: '1' },
+        });
+
+        daemon.networkInstall.proc = setup;
+
+        let stdoutBuf = '';
+        setup.stdout.on('data', (chunk) => {
+          stdoutBuf += chunk.toString();
+          let idx;
+          while ((idx = stdoutBuf.indexOf('\n')) !== -1) {
+            const line = stdoutBuf.slice(0, idx).trim();
+            stdoutBuf = stdoutBuf.slice(idx + 1);
+            if (!line || line[0] !== '{') continue;
+            try {
+              const event = JSON.parse(line);
+              const step = typeof event.step === 'string' ? event.step : 'progress';
+              const message = typeof event.message === 'string' ? event.message : '';
+              const percent = Number.isFinite(event.percent) ? event.percent : null;
+              broadcastUpdateProgress(step, message, percent);
+            } catch { /* non-JSON line, ignore */ }
+          }
+        });
+
+        let stderrBuf = '';
+        setup.stderr.on('data', (chunk) => { stderrBuf += chunk.toString(); });
+
+        const setupResult = await new Promise((r) => {
+          setup.on('error', (e) => r({ code: -1, err: e.message }));
+          setup.on('close', (code) => r({ code }));
+        });
+
+        if (setupResult.code !== 0) {
+          const hint = stderrBuf.trim().split('\n').slice(-1)[0] || `setup.sh exited ${setupResult.code}`;
+          return fail(`Setup failed: ${hint}`);
+        }
+
+        daemon.config.networkBeta = {
+          ...(daemon.config.networkBeta || {}),
+          version: latest,
+        };
+        await persistConfig();
+        // Invalidate the update cache now that we've moved forward.
+        networkUpdateCache = { latest, fetchedAt: Date.now() };
+        daemon.networkUpdateAvailable = { latest, updateAvailable: false, installed: latest };
+        daemon.broadcast({ type: 'config:updated' });
+        daemon.broadcast({ type: 'network:update:available', data: daemon.networkUpdateAvailable });
+        broadcastUpdateProgress('done', `Updated to ${latest}`, 100);
+        daemon.audit.log('network.update', { from: current, to: latest, path: installPath });
+        daemon.networkInstall = { running: false };
+      } catch (err) {
+        fail(err?.message || 'Update failed');
+      }
+    })();
+  });
+
+  // Startup hook — called from index.js once the server is up. Non-blocking;
+  // updates daemon.networkUpdateAvailable and broadcasts so the GUI can badge.
+  daemon.checkNetworkUpdate = async function checkNetworkUpdate() {
+    if (!daemon.config?.networkBeta?.installed) return;
+    try {
+      const latest = await getLatestNetworkTag(true);
+      if (!latest) return;
+      const installed = daemon.config.networkBeta.version || null;
+      const updateAvailable = !!installed && compareSemver(latest, installed) > 0;
+      daemon.networkUpdateAvailable = { installed, latest, updateAvailable };
+      daemon.broadcast({ type: 'network:update:available', data: daemon.networkUpdateAvailable });
+    } catch { /* non-fatal */ }
+  };
+
   // Serve GUI static files (built GUI) — no-cache headers to prevent stale bundles
   const guiPath = process.env.GROOVE_GUI_PATH || resolve(__dirname, '../../gui/dist');
   app.use(express.static(guiPath, { etag: false, maxAge: 0, lastModified: false }));