groove-dev 0.27.37 → 0.27.39

package/node_modules/@groove-dev/gui/dist/index.html

@@ -6,7 +6,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" type="image/png" href="/favicon.png" />
     <title>Groove GUI</title>
-    <script type="module" crossorigin src="/assets/index-Df4O6yJI.js"></script>
+    <script type="module" crossorigin src="/assets/index-BRZ_leqO.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/vendor-C0HXlhrU.js">
     <link rel="modulepreload" crossorigin href="/assets/reactflow-BQPfi37R.js">
     <link rel="modulepreload" crossorigin href="/assets/codemirror-BBL3i_JW.js">

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

@@ -1,6 +1,6 @@
 {
   "name": "@groove-dev/gui",
-  "version": "0.27.37",
+  "version": "0.27.39",
   "description": "GROOVE GUI — visual agent control plane",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/node_modules/@groove-dev/gui/src/components/onboarding/setup-wizard.jsx

@@ -19,7 +19,7 @@ const PROVIDERS = [
     id: 'claude-code',
     name: 'Claude Code',
     subtitle: 'by Anthropic',
-    models: ['Opus 4.6', 'Sonnet 4.6', 'Haiku 4.5'],
+    models: ['Opus 4.7', 'Opus 4.6', 'Sonnet 4.6', 'Haiku 4.5'],
     authType: 'Subscription or API key',
     authModes: ['subscription', 'apikey'],
     recommended: true,

package/node_modules/@groove-dev/gui/src/components/ui/toast.jsx

@@ -64,6 +64,18 @@ function ToastItem({ toast }) {
           <p className="text-xs text-text-3 font-sans mt-0.5">{toast.detail}</p>
         )}
       </div>
+      {toast.action?.url && (
+        <button
+          onClick={(e) => {
+            e.stopPropagation();
+            try { window.open(toast.action.url, '_blank', 'noopener'); } catch {}
+            removeToast(toast.id);
+          }}
+          className="text-xs font-medium text-accent hover:text-accent-hover bg-surface-5 hover:bg-surface-6 px-3 py-1.5 rounded transition-colors cursor-pointer flex-shrink-0 whitespace-nowrap"
+        >
+          {toast.action.label || 'Open'}
+        </button>
+      )}
       <button
         onClick={(e) => { e.stopPropagation(); removeToast(toast.id); }}
         className="p-1.5 text-text-4 hover:text-text-1 hover:bg-surface-5 rounded transition-colors cursor-pointer flex-shrink-0 z-10"

package/node_modules/@groove-dev/gui/src/stores/groove.js

@@ -381,6 +381,39 @@ export const useGrooveStore = create((set, get) => ({
           get().addToast('info', `QC agent ${msg.name} auto-spawned`, 'Auditing phase 1 work');
           break;
 
+        case 'preview:ready':
+          get().addToast(
+            'success',
+            'Project ready to preview',
+            msg.url,
+            { label: 'View Site', url: msg.url },
+          );
+          break;
+
+        case 'preview:failed':
+          get().addToast(
+            'warning',
+            'Preview could not launch',
+            msg.reason ? String(msg.reason).slice(0, 200) : 'Unknown error',
+          );
+          break;
+
+        case 'preview:stopped':
+          break;
+
+        case 'agent:stalled': {
+          const name = msg.agentName || msg.agentId;
+          const secs = Math.round((msg.silentMs || 0) / 1000);
+          get().addToast('warning', `${name} may be stalled`, `No output for ${secs}s — API stream may be hung`);
+          break;
+        }
+
+        case 'knock:denied': {
+          const name = msg.agentName || msg.agentId;
+          get().addToast('warning', `${name} blocked`, `${msg.toolName} on ${msg.target} — ${msg.reason || 'scope conflict'}`);
+          break;
+        }
+
         case 'phase2:failed':
           get().addToast('error', `QC agent failed to spawn`, msg.error || 'Unknown error');
           break;
@@ -725,9 +758,9 @@ export const useGrooveStore = create((set, get) => ({
 
   // ── Toasts ────────────────────────────────────────────────
 
-  addToast(type, message, detail) {
+  addToast(type, message, detail, action) {
     const id = ++toastCounter;
-    set((s) => ({ toasts: [...s.toasts, { id, type, message, detail }] }));
+    set((s) => ({ toasts: [...s.toasts, { id, type, message, detail, action }] }));
   },
   removeToast(id) {
     set((s) => ({ toasts: s.toasts.filter((t) => t.id !== id) }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groove-dev",
-  "version": "0.27.37",
+  "version": "0.27.39",
   "description": "Open-source agent orchestration layer — the AI company OS. Local model agent engine (GGUF/Ollama/llama-server), HuggingFace model browser, MCP integrations (Slack, Gmail, Stripe, 15+), agent scheduling (cron), business roles (CMO, CFO, EA). GUI dashboard, multi-agent coordination, zero cold-start, infinite sessions. Works with Claude Code, Codex, Gemini CLI, Ollama, any local model.",
   "license": "FSL-1.1-Apache-2.0",
   "author": "Groove Dev <hello@groovedev.ai> (https://groovedev.ai)",

package/packages/cli/package.json

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

package/packages/daemon/package.json

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

package/packages/daemon/src/api.js

@@ -268,6 +268,49 @@ export function createApi(app, daemon) {
     res.json(daemon.locks.getAll());
   });
 
+  // Knock protocol: Claude Code PreToolUse hook POSTs every Bash/Write/Edit
+  // tool call here. The daemon checks the target path (for file ops) against
+  // the agent's declared scope and against other agents' active locks, and
+  // allows or denies. Non-Claude providers don't hit this path.
+  app.post('/api/knock', (req, res) => {
+    const body = req.body || {};
+    const agentId = body.grooveAgentId;
+    const toolName = body.tool_name || body.toolName || '';
+    const toolInput = body.tool_input || body.toolInput || {};
+
+    // Unknown / no agent id → fail open (don't wedge an agent we can't identify)
+    if (!agentId) return res.json({ allow: true });
+    const agent = daemon.registry.get(agentId);
+    if (!agent) return res.json({ allow: true });
+
+    // Extract the target file paths from the tool input
+    const targets = [];
+    if (toolInput.file_path) targets.push(String(toolInput.file_path));
+    if (toolInput.path) targets.push(String(toolInput.path));
+    if (Array.isArray(toolInput.edits)) {
+      for (const e of toolInput.edits) if (e?.file_path) targets.push(String(e.file_path));
+    }
+
+    // Scope guard: if agent has a declared scope and the op targets a path,
+    // verify the path matches the scope or belongs to no one.
+    if (agent.scope && agent.scope.length > 0 && targets.length > 0) {
+      for (const target of targets) {
+        const conflict = daemon.locks.check(agentId, target);
+        if (conflict.conflict) {
+          daemon.audit.log('knock.denied', { agentId, toolName, target, owner: conflict.owner, pattern: conflict.pattern });
+          daemon.broadcast({ type: 'knock:denied', agentId, agentName: agent.name, toolName, target, owner: conflict.owner, reason: 'scope_conflict' });
+          return res.json({
+            allow: false,
+            reason: `GROOVE PM: ${target} is owned by another agent (pattern ${conflict.pattern}). Use the handoff protocol (write .groove/handoffs/<role>.md) or request approval instead of editing it directly.`,
+          });
+        }
+      }
+    }
+
+    daemon.audit.log('knock.allowed', { agentId, toolName, targets });
+    res.json({ allow: true });
+  });
+
   // Coordination protocol — agents declare intent on shared resources
   // (npm install, server restart, package.json edit) to prevent races.
   // Returns 423 Locked if another agent holds a conflicting resource.
@@ -2613,14 +2656,16 @@ Keep responses concise. Help them think, don't lecture them about the system the
       // Delete immediately after reading to prevent duplicate launches from poll races
       try { unlinkSync(found.path); } catch { /* already gone */ }
 
-      // Support both old format (bare array) and new format ({ projectDir, agents })
+      // Support both old format (bare array) and new format ({ projectDir, agents, preview })
       let agentConfigs;
       let projectDir = null;
+      let previewBlock = null;
       if (Array.isArray(raw)) {
         agentConfigs = raw;
       } else if (raw && Array.isArray(raw.agents)) {
         agentConfigs = raw.agents;
         projectDir = raw.projectDir || null;
+        previewBlock = raw.preview || null;
       } else {
         return res.status(400).json({ error: 'Invalid recommended team format' });
       }
@@ -2783,16 +2828,46 @@ Keep responses concise. Help them think, don't lecture them about the system the
         }
       }
 
+      // Stash the preview block so the daemon can launch it when the team
+      // finishes. The plan file gets deleted seconds after this endpoint returns.
+      if (previewBlock && daemon.preview && defaultTeamId) {
+        daemon.preview.stashPlan(defaultTeamId, previewBlock, projectWorkingDir);
+      }
+
       daemon.audit.log('team.launch', {
         phase1: spawned.length, reused: reused.length, phase2Pending: phase2.length, failed: failed.length,
-        agents: [...spawned, ...reused].map((a) => a.role), projectDir: projectDir || null,
+        agents: [...spawned, ...reused].map((a) => a.role), projectDir: projectDir || null, preview: !!previewBlock,
       });
-      res.json({ launched: spawned.length, reused: reused.length, phase2Pending: phase2.length, agents: [...spawned, ...reused], failed, projectDir: projectDir || null });
+      res.json({ launched: spawned.length, reused: reused.length, phase2Pending: phase2.length, agents: [...spawned, ...reused], failed, projectDir: projectDir || null, preview: previewBlock ? previewBlock.kind : null });
     } catch (err) {
       res.status(500).json({ error: err.message });
     }
   });
 
+  // Preview service — one-click View Site for completed teams
+  app.get('/api/preview', (req, res) => {
+    res.json({ previews: daemon.preview?.list() || [] });
+  });
+
+  app.get('/api/preview/:teamId', (req, res) => {
+    const entry = daemon.preview?.get(req.params.teamId);
+    if (!entry) return res.status(404).json({ error: 'No preview for this team' });
+    res.json(entry);
+  });
+
+  app.delete('/api/preview/:teamId', async (req, res) => {
+    const killed = await daemon.preview?.kill(req.params.teamId);
+    res.json({ stopped: !!killed });
+  });
+
+  // Manually (re)launch the preview for a team using the stashed plan.
+  app.post('/api/preview/:teamId/launch', async (req, res) => {
+    const plan = daemon.preview?.getPlan(req.params.teamId);
+    if (!plan) return res.status(404).json({ error: 'No preview plan stashed for this team' });
+    const result = await daemon.preview.launch(req.params.teamId, plan.workingDir, plan.preview);
+    res.json(result);
+  });
+
   // Clean up stale artifacts (old plans, recommended teams, etc.)
   app.post('/api/cleanup', (req, res) => {
     let cleaned = 0;

package/packages/daemon/src/index.js

@@ -16,6 +16,7 @@ import { Introducer } from './introducer.js';
 import { LockManager } from './lockmanager.js';
 import { Supervisor } from './supervisor.js';
 import { Journalist } from './journalist.js';
+import { PreviewService } from './preview.js';
 import { TokenTracker } from './tokentracker.js';
 import { Rotator } from './rotator.js';
 import { AdaptiveThresholds } from './adaptive.js';
@@ -137,6 +138,7 @@ export class Daemon {
     this.fileWatcher = new FileWatcher(this);
     this.terminalManager = new TerminalManager(this);
     this.gateways = new GatewayManager(this);
+    this.preview = new PreviewService(this);
     this.modelManager = new ModelManager(this);
     this.llamaServer = new LlamaServerManager(this);
     this.mcpManager = new McpManager(this);
@@ -657,6 +659,7 @@ export class Daemon {
 
     // Kill all agent processes, stop MCP servers, and stop inference servers
     await this.processes.killAll();
+    if (this.preview) await this.preview.killAll();
     this.mcpManager.stopAll();
     await this.llamaServer.stopAll();
 

package/packages/daemon/src/lockmanager.js

@@ -76,6 +76,50 @@ export class LockManager {
     return { conflict: false };
   }
 
+  /**
+   * Prefix-based overlap test between two scope pattern sets.
+   * Two scopes overlap if any pair of patterns has a prefix containment
+   * relationship (one prefix is a parent dir of the other) or shares an
+   * identical prefix. An empty/broad pattern (e.g. `**`) always overlaps.
+   *
+   * Used at spawn time to block two agents claiming the same files.
+   * Intentionally conservative: returns overlap for ambiguous cases so
+   * collisions fail loud rather than silently.
+   */
+  static scopesOverlap(patternsA, patternsB) {
+    if (!Array.isArray(patternsA) || !Array.isArray(patternsB)) return false;
+    if (patternsA.length === 0 || patternsB.length === 0) return false;
+    const prefixOf = (p) => {
+      const idx = p.search(/[*?[{]/);
+      const head = idx === -1 ? p : p.slice(0, idx);
+      return head.replace(/\/+$/, '');
+    };
+    for (const a of patternsA) {
+      const pa = prefixOf(a);
+      for (const b of patternsB) {
+        const pb = prefixOf(b);
+        if (pa === pb) return { overlap: true, a, b };
+        if (pa === '' || pb === '') return { overlap: true, a, b };
+        const longer = pa.length > pb.length ? pa : pb;
+        const shorter = pa.length > pb.length ? pb : pa;
+        if (longer.startsWith(shorter + '/')) return { overlap: true, a, b };
+      }
+    }
+    return { overlap: false };
+  }
+
+  /**
+   * Find any currently-locked agent whose scope overlaps with candidateScope.
+   * Returns { overlap: true, owner, ... } for the first conflict, else {overlap:false}.
+   */
+  findOverlappingOwner(candidateScope) {
+    for (const [ownerId, patterns] of this.locks) {
+      const res = LockManager.scopesOverlap(candidateScope, patterns);
+      if (res.overlap) return { overlap: true, owner: ownerId, ownerScope: patterns, ...res };
+    }
+    return { overlap: false };
+  }
+
   purgeOrphans(aliveAgentIds) {
     const alive = new Set(aliveAgentIds);
     let purged = 0;

package/packages/daemon/src/memory.js

@@ -19,6 +19,12 @@ const MAX_HANDOFF_ROTATIONS = 25;
 const MAX_DISCOVERIES = 1000;
 const HANDOFF_BRIEF_MAX_CHARS = 4000;
 
+// Legacy auto-extraction (since disabled) captured raw user prompts into a
+// "user-directive" constraint. Existing entries still live in projects that
+// predate the fix and would otherwise leak into every new agent's brief.
+// Suppressed at render time so stored state doesn't need migration.
+const SUPPRESSED_CONSTRAINT_CATEGORIES = new Set(['user-directive']);
+
 function hashText(text) {
   return createHash('sha1').update(text.trim().toLowerCase()).digest('hex').slice(0, 12);
 }
@@ -76,6 +82,9 @@ export class MemoryStore {
 
   addConstraint({ text, category = 'general' }) {
     if (!text || typeof text !== 'string') return { added: false, error: 'text required' };
+    if (SUPPRESSED_CONSTRAINT_CATEGORIES.has(category)) {
+      return { added: false, error: `category "${category}" suppressed — not a real constraint` };
+    }
     const trimmed = text.trim();
     if (trimmed.length < 3) return { added: false, error: 'text too short' };
     if (trimmed.length > 500) return { added: false, error: 'text too long (max 500 chars)' };
@@ -117,7 +126,8 @@ export class MemoryStore {
   }
 
   getConstraintsMarkdown(maxChars = 4000) {
-    const constraints = this.listConstraints();
+    const constraints = this.listConstraints()
+      .filter((c) => !SUPPRESSED_CONSTRAINT_CATEGORIES.has(c.category));
     if (constraints.length === 0) return '';
     const byCategory = {};
     for (const c of constraints) {
@@ -165,13 +175,14 @@ export class MemoryStore {
       const entries = [];
       const blocks = content.split(/\n(?=## Rotation )/);
       for (const block of blocks) {
-        const headerMatch = block.match(/^## Rotation (\d+) — [^(]*\(([\w?-]+) →/);
+        const headerMatch = block.match(/^## Rotation (\d+) — (\S+) \(([\w?-]+) →/);
         if (!headerMatch) continue;
         const body = block.replace(/\n---\s*$/, '').trim();
         entries.push({
           rotationN: parseInt(headerMatch[1], 10),
           body,
-          agentId: headerMatch[2] || null,
+          timestamp: headerMatch[2] || null,
+          agentId: headerMatch[3] || null,
         });
       }
       return entries;
@@ -184,8 +195,14 @@ export class MemoryStore {
     if (!role || !entry) return false;
     const chain = this.getHandoffChain(role, workingDir, teamId);
 
-    // Dedup: prevent the same agent from having multiple entries in the chain
-    if (entry.agentId && chain.some(c => c.agentId === entry.agentId)) return false;
+    // Guard only the pathological double-write case: identical agent AND timestamp
+    // means the same event fired twice (e.g. race). A resumed agent that legitimately
+    // completes multiple sessions produces distinct timestamps and must be kept —
+    // that's how the chain records continuous work across resumes.
+    if (entry.agentId && entry.timestamp
+        && chain.some(c => c.agentId === entry.agentId && c.timestamp === entry.timestamp)) {
+      return false;
+    }
 
     const nextN = (chain[0]?.rotationN || 0) + 1;
 

package/packages/daemon/src/preview.js

@@ -0,0 +1,243 @@
+// GROOVE — Preview Service
+// FSL-1.1-Apache-2.0 — see LICENSE
+//
+// Launches the one-click preview for a completed team. The planner writes a
+// "preview" block in recommended-team.json describing how to run the project
+// (dev-server command, static-html entry, or none). When the last phase
+// agent completes, we spawn the command, parse the URL from stdout, and
+// broadcast a preview:ready event so the GUI can show a View Site toast.
+//
+// One preview process per team. Starting a new preview for the same team
+// kills the previous one. Previews are also killed on team delete and on
+// daemon shutdown.
+
+import { spawn as cpSpawn } from 'child_process';
+import { resolve, extname } from 'path';
+import { existsSync, readFileSync, statSync } from 'fs';
+import { createServer } from 'http';
+import { lookup as mimeLookup } from './mimetypes.js';
+
+const READY_TIMEOUT_MS = 60_000;  // give dev servers a minute to boot
+const MAX_STDOUT_BYTES = 256 * 1024;
+
+export class PreviewService {
+  constructor(daemon) {
+    this.daemon = daemon;
+    this.previews = new Map(); // teamId -> { proc?, server?, url, kind, startedAt }
+    this.pendingPlans = new Map(); // teamId -> { preview, workingDir }
+  }
+
+  /**
+   * Capture a preview plan at team launch time — api cleanup deletes the
+   * source file immediately after read, so the daemon is the only place the
+   * preview block survives.
+   */
+  stashPlan(teamId, preview, workingDir) {
+    if (!teamId || !preview) return;
+    this.pendingPlans.set(teamId, { preview, workingDir });
+  }
+
+  getPlan(teamId) {
+    return this.pendingPlans.get(teamId) || null;
+  }
+
+  clearPlan(teamId) {
+    this.pendingPlans.delete(teamId);
+  }
+
+  /**
+   * Read recommended-team.json for a given working directory and return the
+   * preview block (or null if none). We read from both the team working dir
+   * and the daemon .groove dir to cover the cases the api cleanup hits.
+   */
+  getPlanPreview(workingDir) {
+    const candidates = [
+      workingDir ? resolve(workingDir, '.groove', 'recommended-team.json') : null,
+      resolve(this.daemon.grooveDir, 'recommended-team.json'),
+    ].filter(Boolean);
+    for (const p of candidates) {
+      if (!existsSync(p)) continue;
+      try {
+        const data = JSON.parse(readFileSync(p, 'utf8'));
+        if (data && typeof data.preview === 'object') return data.preview;
+      } catch { /* malformed, keep looking */ }
+    }
+    return null;
+  }
+
+  /**
+   * Preview blocks are embedded in the plan artifact, which /api/cleanup
+   * deletes as soon as the user clicks Launch Team. Callers should grab the
+   * preview upfront at launch time and hand it back when the team completes.
+   */
+  async launch(teamId, workingDir, preview) {
+    if (!preview || !preview.kind || preview.kind === 'none' || preview.kind === 'cli') {
+      return { launched: false, reason: preview?.kind || 'no_preview' };
+    }
+
+    // Kill any existing preview for this team
+    await this.kill(teamId);
+
+    const baseDir = preview.cwd
+      ? resolve(workingDir || this.daemon.projectDir, preview.cwd)
+      : resolve(workingDir || this.daemon.projectDir);
+
+    if (!existsSync(baseDir)) {
+      return { launched: false, reason: `cwd_missing: ${baseDir}` };
+    }
+
+    if (preview.kind === 'static-html') {
+      return this._launchStatic(teamId, baseDir, preview);
+    }
+    if (preview.kind === 'dev-server') {
+      return this._launchDevServer(teamId, baseDir, preview);
+    }
+    return { launched: false, reason: `unknown_kind: ${preview.kind}` };
+  }
+
+  _launchStatic(teamId, baseDir, preview) {
+    const openPath = (preview.openPath || 'index.html').replace(/^\/+/, '');
+    const entryFile = resolve(baseDir, openPath);
+    if (!existsSync(entryFile)) {
+      return Promise.resolve({ launched: false, reason: `entry_missing: ${entryFile}` });
+    }
+    const server = createServer((req, res) => {
+      const url = decodeURIComponent((req.url || '/').split('?')[0]);
+      const rel = url === '/' ? openPath : url.replace(/^\/+/, '');
+      const filePath = resolve(baseDir, rel);
+      if (!filePath.startsWith(baseDir)) { res.statusCode = 403; return res.end(); }
+      if (!existsSync(filePath) || !statSync(filePath).isFile()) {
+        res.statusCode = 404; return res.end('Not found');
+      }
+      res.setHeader('Content-Type', mimeLookup(extname(filePath)) || 'application/octet-stream');
+      res.end(readFileSync(filePath));
+    });
+    return new Promise((done) => {
+      server.listen(0, '127.0.0.1', () => {
+        const port = server.address().port;
+        const url = `http://127.0.0.1:${port}/`;
+        this.previews.set(teamId, { server, url, kind: 'static-html', startedAt: Date.now() });
+        this._broadcastReady(teamId, url, 'static-html');
+        done({ launched: true, url, kind: 'static-html' });
+      });
+      server.on('error', (err) => done({ launched: false, reason: err.message }));
+    });
+  }
+
+  _launchDevServer(teamId, baseDir, preview) {
+    const command = String(preview.command || '').trim();
+    if (!command) {
+      return Promise.resolve({ launched: false, reason: 'no_command' });
+    }
+    const urlPattern = preview.urlPattern
+      ? new RegExp(preview.urlPattern)
+      : /https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0):\d+/;
+    const readyText = preview.readyText || '';
+
+    // Run the command via the user's shell so pipelines, && chains, env var
+    // expansion, and shell builtins work as the planner wrote them.
+    const proc = cpSpawn('bash', ['-lc', command], {
+      cwd: baseDir,
+      env: { ...process.env, FORCE_COLOR: '0', CI: '' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: false,
+    });
+
+    const entry = { proc, url: null, kind: 'dev-server', startedAt: Date.now(), command, baseDir };
+    this.previews.set(teamId, entry);
+
+    let stdoutBuf = '';
+    let stderrBuf = '';
+    let resolved = false;
+
+    return new Promise((done) => {
+      const finish = (result) => {
+        if (resolved) return;
+        resolved = true;
+        clearTimeout(timer);
+        if (result.launched) {
+          entry.url = result.url;
+          this._broadcastReady(teamId, result.url, 'dev-server');
+        } else {
+          // Failed to detect URL — keep the process? Probably kill it; the user
+          // will just see broken output otherwise.
+          try { proc.kill('SIGTERM'); } catch {}
+          this.previews.delete(teamId);
+        }
+        done(result);
+      };
+
+      const timer = setTimeout(() => {
+        finish({ launched: false, reason: `timeout waiting for url in stdout; last stderr: ${stderrBuf.slice(-400)}` });
+      }, READY_TIMEOUT_MS);
+
+      const tryMatch = () => {
+        const combined = stdoutBuf + '\n' + stderrBuf;
+        if (readyText && !combined.includes(readyText)) return;
+        const m = combined.match(urlPattern);
+        if (!m) return;
+        let url = m[0];
+        const openPath = (preview.openPath || '').replace(/^\/+/, '');
+        if (openPath) url = url.replace(/\/$/, '') + '/' + openPath;
+        finish({ launched: true, url, kind: 'dev-server' });
+      };
+
+      proc.stdout.on('data', (c) => {
+        stdoutBuf += c.toString();
+        if (stdoutBuf.length > MAX_STDOUT_BYTES) stdoutBuf = stdoutBuf.slice(-MAX_STDOUT_BYTES);
+        tryMatch();
+      });
+      proc.stderr.on('data', (c) => {
+        stderrBuf += c.toString();
+        if (stderrBuf.length > MAX_STDOUT_BYTES) stderrBuf = stderrBuf.slice(-MAX_STDOUT_BYTES);
+        tryMatch();
+      });
+
+      proc.on('exit', (code, signal) => {
+        this.previews.delete(teamId);
+        if (!resolved) {
+          finish({ launched: false, reason: `process exited before url detected (code=${code} signal=${signal}); stderr tail: ${stderrBuf.slice(-400)}` });
+        } else {
+          this.daemon.broadcast({ type: 'preview:stopped', teamId, code, signal });
+        }
+      });
+      proc.on('error', (err) => {
+        if (!resolved) finish({ launched: false, reason: `spawn error: ${err.message}` });
+      });
+    });
+  }
+
+  _broadcastReady(teamId, url, kind) {
+    this.daemon.audit?.log('preview.ready', { teamId, url, kind });
+    this.daemon.broadcast({ type: 'preview:ready', teamId, url, kind });
+  }
+
+  get(teamId) {
+    const entry = this.previews.get(teamId);
+    if (!entry) return null;
+    return { teamId, url: entry.url, kind: entry.kind, startedAt: entry.startedAt };
+  }
+
+  list() {
+    return Array.from(this.previews.entries()).map(([teamId, e]) => ({
+      teamId, url: e.url, kind: e.kind, startedAt: e.startedAt,
+    }));
+  }
+
+  async kill(teamId) {
+    const entry = this.previews.get(teamId);
+    if (!entry) return false;
+    this.previews.delete(teamId);
+    try {
+      if (entry.server) entry.server.close();
+      if (entry.proc) entry.proc.kill('SIGTERM');
+    } catch { /* best-effort */ }
+    this.daemon.broadcast({ type: 'preview:stopped', teamId });
+    return true;
+  }
+
+  async killAll() {
+    const ids = Array.from(this.previews.keys());
+    await Promise.all(ids.map((id) => this.kill(id)));
+  }
+}