@swarmclawai/swarmclaw 0.7.7 → 0.8.0

package/README.md

@@ -148,7 +148,7 @@ curl -fsSL https://raw.githubusercontent.com/swarmclawai/swarmclaw/main/install.
 ```
 
 The installer resolves the latest stable release tag and installs that version by default.
-To pin a version: `SWARMCLAW_VERSION=v0.7.7 curl ... | bash`
+To pin a version: `SWARMCLAW_VERSION=v0.8.0 curl ... | bash`
 
 Or run locally from the repo (friendly for non-technical users):
 
@@ -464,7 +464,7 @@ Policy is enforced in both chat tool construction and direct forced tool invocat
 
 Configure these in **Settings**:
 
-- **Voice** — set `ElevenLabs API Key`, `ElevenLabs Voice ID`, and `Speech Recognition Language`
+- **Voice** — set `ElevenLabs API Key`, `ElevenLabs Voice ID`, and `Speech Recognition Language`. Outbound voice-note sends retry with the built-in fallback ElevenLabs voice when a saved default voice is rejected as paid-only.
 - **Heartbeat** — set `Heartbeat Interval (Seconds)` and `Heartbeat Prompt` for ongoing chat pings
 - **Global heartbeat safety** — use `Stop All Heartbeats` to disable heartbeat across all chats and cancel in-flight heartbeat runs.
 
@@ -529,7 +529,7 @@ Built-in capabilities now resolve to a single canonical plugin family ID across
 
 Agents in SwarmClaw are "aware" of the plugin system. If an agent lacks a tool needed for a task, it can:
 1. **Discover**: Scan the system for all installed plugins.
-2. **Search Marketplace**: Autonomously search **ClawHub** and the **SwarmClaw Registry** for new capabilities.
+2. **Search Marketplace**: Autonomously search **ClawHub** and the **SwarmForge-backed first-party marketplace** for new capabilities.
 3. **Request Access**: Prompt the user in-chat to enable a specific installed plugin.
 4. **Install Request**: Suggest installing a new plugin from a marketplace URL to fill a capability gap (requires user approval).
 
@@ -663,8 +663,8 @@ npm run dev:webpack  # Fallback to webpack dev server (if Turbopack crashes)
 npm run dev:clean    # Clear .next cache then restart dev server
 npm run build        # Production build
 npm run build:ci     # CI build (skips ESLint; lint baseline runs separately)
-npm run start        # Start production server
-npm run start:standalone # Start standalone server after build
+npm run start        # Start the standalone production server after build
+npm run start:standalone # Alias for the standalone production server
 npm run lint         # ESLint
 npm run lint:baseline # Fail only on net-new lint issues vs .eslint-baseline.json
 npm run lint:baseline:update # Refresh lint baseline intentionally
@@ -701,8 +701,8 @@ npm run update:easy     # safe update helper for local installs
 SwarmClaw uses tag-based releases (`vX.Y.Z`) as the stable channel.
 
 ```bash
-# example patch release (v0.7.7 style)
-npm version patch
+# example minor release (v0.8.0 style)
+npm version minor
 git push origin main --follow-tags
 ```
 
@@ -711,15 +711,13 @@ On `v*` tags, GitHub Actions will:
 2. Create a GitHub Release
 3. Build and publish Docker images to `ghcr.io/swarmclawai/swarmclaw` (`:vX.Y.Z`, `:latest`, `:sha-*`)
 
-#### v0.7.7 Release Readiness Notes
+#### v0.8.0 Release Readiness Notes
 
-Before shipping `v0.7.7`, confirm the following user-facing changes are reflected in docs:
+Before shipping `v0.8.0`, confirm the following user-facing changes are reflected in docs:
 
-1. OpenClaw docs cover Smart Deploy end-to-end: onboarding, Providers, gateway editor, official-only SSH/VPS flows, safe exposure presets, and restore/backup lifecycle controls.
-2. Agent and provider docs explain gateway routing by tags/use-case, richer external runtime visibility, and import/export/clone flows for saved gateways.
-3. Site and README install/version strings are updated to `v0.7.7`, including install snippets, release notes index text, and sidebar/footer labels.
-4. Release notes summarize the user-visible operator changes from the current worktree, especially SSH deploy, remote lifecycle controls, routing preferences, and onboarding persistence.
-5. CLI docs include the expanded `openclaw deploy-*`, `openclaw remote-*`, and verify surfaces and do not reference removed or unofficial deployment paths.
+1. Voice and connector docs mention that outbound voice-note sends now retry with the built-in ElevenLabs fallback voice when a configured default voice is rejected as paid-only.
+2. Release notes call out the Molly-style regression case explicitly: WhatsApp voice-note delivery should keep working even if the saved default voice ID points at a paid library voice.
+3. Site and README install/version strings are updated to `v0.8.0`, including install snippets, release notes index text, and sidebar/footer labels.
 
 ## CLI
 

package/next.config.ts

@@ -1,8 +1,12 @@
 import type { NextConfig } from "next";
 import { execSync } from "child_process";
 import { networkInterfaces } from "os";
+import path from "path";
+import { fileURLToPath } from "url";
 import { DIRECT_NAV_SEGMENTS } from "./view-route-paths";
 
+const PROJECT_ROOT = path.dirname(fileURLToPath(import.meta.url))
+
 function getGitSha(): string {
   try {
     return execSync('git rev-parse --short HEAD', { encoding: 'utf-8' }).trim()
@@ -40,10 +44,17 @@ function getAllowedDevOrigins(): string[] {
 
 const nextConfig: NextConfig = {
   output: 'standalone',
+  outputFileTracingExcludes: {
+    '/api/**': ['data/browser-profiles/**/*', 'data/browser-profiles-regression/**/*'],
+    instrumentation: ['data/browser-profiles/**/*', 'data/browser-profiles-regression/**/*'],
+    '/instrumentation': ['data/browser-profiles/**/*', 'data/browser-profiles-regression/**/*'],
+    'next-server': ['data/browser-profiles/**/*', 'data/browser-profiles-regression/**/*'],
+  },
   turbopack: {
     // Pin workspace root to the project directory so a stale lockfile
-    // in a parent folder (e.g. ~/) doesn't confuse native module resolution.
-    root: process.cwd(),
+    // in a parent folder (e.g. ~/) or a nested launch cwd doesn't confuse
+    // native module resolution.
+    root: PROJECT_ROOT,
   },
   experimental: {
     // Disable Turbopack persistent cache — concurrent HMR writes cause

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "0.7.7",
+  "version": "0.8.0",
   "description": "Self-hosted AI agent orchestration dashboard — manage LLM providers, orchestrate agent swarms, schedule tasks, and bridge agents to chat platforms.",
   "license": "MIT",
   "publishConfig": {
@@ -47,8 +47,9 @@
     "dev:clean": "rm -rf .next && next dev --hostname 0.0.0.0 -p 3456",
     "build": "next build",
     "build:ci": "NEXT_DISABLE_ESLINT=1 next build",
-    "start": "next start",
+    "start": "node .next/standalone/server.js",
     "start:standalone": "node .next/standalone/server.js",
+    "smoke:browser": "node ./scripts/browser-route-smoke.mjs",
     "benchmark:autonomy": "node ./scripts/benchmark-autonomy-harness.mjs",
     "benchmark:agent-regression": "node --import tsx ./scripts/run-agent-regression-suite.ts",
     "lint": "eslint",
@@ -81,6 +82,7 @@
     "cron-parser": "^5.5.0",
     "cronstrue": "^3.12.0",
     "discord.js": "^14.25.1",
+    "ethers": "^6.16.0",
     "exceljs": "^4.4.0",
     "grammy": "^1.40.0",
     "highlight.js": "^11.11.1",

package/src/app/api/agents/[id]/thread/route.ts

@@ -1,12 +1,21 @@
 import { NextResponse } from 'next/server'
+import { buildAgentDisabledMessage, isAgentDisabled } from '@/lib/server/agent-availability'
 import { ensureAgentThreadSession } from '@/lib/server/agent-thread-session'
+import { loadAgents } from '@/lib/server/storage'
 
 export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id: agentId } = await params
   const body = await req.json().catch(() => ({}))
   const user = body.user || 'default'
+  const agent = loadAgents()[agentId]
+  if (!agent) {
+    return NextResponse.json({ error: 'Agent not found' }, { status: 404 })
+  }
   const session = ensureAgentThreadSession(agentId, user)
   if (!session) {
+    if (isAgentDisabled(agent)) {
+      return NextResponse.json({ error: buildAgentDisabledMessage(agent, 'start new chats') }, { status: 409 })
+    }
     return NextResponse.json({ error: 'Agent not found' }, { status: 404 })
   }
   return NextResponse.json(session)

package/src/app/api/agents/route.ts

@@ -3,6 +3,7 @@ import { genId } from '@/lib/id'
 import { loadAgents, loadSessions, loadUsage, saveAgents, logActivity } from '@/lib/server/storage'
 import { normalizeProviderEndpoint } from '@/lib/openclaw-endpoint'
 import { notify } from '@/lib/server/ws-hub'
+import { ensureDaemonStarted } from '@/lib/server/daemon-state'
 import { getAgentSpendWindows } from '@/lib/server/cost'
 import { AgentCreateSchema, formatZodError } from '@/lib/validation/schemas'
 import { z } from 'zod'
@@ -10,6 +11,7 @@ export const dynamic = 'force-dynamic'
 
 
 export async function GET(req: Request) {
+  ensureDaemonStarted('api/agents:get')
   const agents = loadAgents()
   const sessions = loadSessions()
   const usage = loadUsage()
@@ -42,6 +44,7 @@ export async function GET(req: Request) {
 }
 
 export async function POST(req: Request) {
+  ensureDaemonStarted('api/agents:post')
   const raw = await req.json()
   const parsed = AgentCreateSchema.safeParse(raw)
   if (!parsed.success) {
@@ -82,6 +85,7 @@ export async function POST(req: Request) {
     capabilities: body.capabilities,
     thinkingLevel: body.thinkingLevel || undefined,
     autoRecovery: body.autoRecovery || false,
+    disabled: body.disabled || false,
     heartbeatEnabled: body.heartbeatEnabled || false,
     heartbeatInterval: body.heartbeatInterval,
     heartbeatIntervalSec: body.heartbeatIntervalSec,

package/src/app/api/agents/thread-route.test.ts

@@ -0,0 +1,133 @@
+import assert from 'node:assert/strict'
+import test, { afterEach } from 'node:test'
+
+import { POST as createAgentThread } from './[id]/thread/route'
+import { loadAgents, loadSessions, saveAgents, saveSessions } from '@/lib/server/storage'
+
+const originalAgents = loadAgents()
+const originalSessions = loadSessions()
+
+function routeParams(id: string) {
+  return { params: Promise.resolve({ id }) }
+}
+
+function seedAgent(id: string, overrides: Record<string, unknown> = {}) {
+  const agents = loadAgents()
+  const now = Date.now()
+  agents[id] = {
+    id,
+    name: 'Thread Test Agent',
+    description: 'Agent thread route smoke',
+    systemPrompt: 'Be helpful.',
+    provider: 'openai',
+    model: 'gpt-4o-mini',
+    credentialId: null,
+    fallbackCredentialIds: [],
+    apiEndpoint: null,
+    gatewayProfileId: null,
+    plugins: ['memory'],
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  }
+  saveAgents(agents)
+}
+
+afterEach(() => {
+  saveAgents(originalAgents)
+  saveSessions(originalSessions)
+})
+
+test('POST /api/agents/[id]/thread returns 409 for a disabled agent without an existing thread', async () => {
+  seedAgent('agent-thread-disabled', { disabled: true })
+
+  const response = await createAgentThread(new Request('http://local/api/agents/agent-thread-disabled/thread', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ user: 'default' }),
+  }), routeParams('agent-thread-disabled'))
+
+  assert.equal(response.status, 409)
+  const payload = await response.json() as Record<string, unknown>
+  assert.match(String(payload.error || ''), /disabled/i)
+})
+
+test('POST /api/agents/[id]/thread reuses an existing thread for a disabled agent', async () => {
+  seedAgent('agent-thread-disabled-existing', {
+    disabled: true,
+    threadSessionId: 'session-disabled-existing',
+  })
+
+  const sessions = loadSessions()
+  sessions['session-disabled-existing'] = {
+    id: 'session-disabled-existing',
+    name: 'Thread Test Agent',
+    shortcutForAgentId: 'agent-thread-disabled-existing',
+    cwd: '/tmp',
+    user: 'default',
+    provider: 'openai',
+    model: 'gpt-4o-mini',
+    credentialId: null,
+    fallbackCredentialIds: [],
+    apiEndpoint: null,
+    gatewayProfileId: null,
+    routePreferredGatewayTags: [],
+    routePreferredGatewayUseCase: null,
+    claudeSessionId: null,
+    codexThreadId: null,
+    opencodeSessionId: null,
+    delegateResumeIds: { claudeCode: null, codex: null, opencode: null, gemini: null },
+    messages: [],
+    createdAt: 1,
+    lastActiveAt: 1,
+    active: false,
+    sessionType: 'human',
+    agentId: 'agent-thread-disabled-existing',
+    parentSessionId: null,
+    plugins: ['memory'],
+    tools: ['memory'],
+    heartbeatEnabled: false,
+    heartbeatIntervalSec: null,
+    heartbeatTarget: null,
+    sessionResetMode: null,
+    sessionIdleTimeoutSec: null,
+    sessionMaxAgeSec: null,
+    sessionDailyResetAt: null,
+    sessionResetTimezone: null,
+    thinkingLevel: null,
+    browserProfileId: null,
+    connectorThinkLevel: null,
+    connectorSessionScope: null,
+    connectorReplyMode: null,
+    connectorThreadBinding: null,
+    connectorGroupPolicy: null,
+    connectorIdleTimeoutSec: null,
+    connectorMaxAgeSec: null,
+    mailbox: null,
+    connectorContext: null,
+    lastAutoMemoryAt: null,
+    lastHeartbeatText: null,
+    lastHeartbeatSentAt: null,
+    lastSessionResetAt: null,
+    lastSessionResetReason: null,
+    identityState: null,
+    sessionArchiveState: null,
+    pinned: false,
+    file: null,
+    queuedCount: 0,
+    currentRunId: null,
+    canvasContent: null,
+  }
+  saveSessions(sessions)
+
+  const response = await createAgentThread(new Request('http://local/api/agents/agent-thread-disabled-existing/thread', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ user: 'default' }),
+  }), routeParams('agent-thread-disabled-existing'))
+
+  assert.equal(response.status, 200)
+  const payload = await response.json() as Record<string, unknown>
+  assert.equal(payload.id, 'session-disabled-existing')
+  assert.equal(payload.agentId, 'agent-thread-disabled-existing')
+})

package/src/app/api/approvals/route.test.ts

@@ -0,0 +1,148 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import test from 'node:test'
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../../..')
+
+function runWithTempDataDir(script: string) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-approvals-route-'))
+  try {
+    const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', script], {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        DATA_DIR: path.join(tempDir, 'data'),
+        WORKSPACE_DIR: path.join(tempDir, 'workspace'),
+      },
+      encoding: 'utf-8',
+    })
+    assert.equal(result.status, 0, result.stderr || result.stdout || 'subprocess failed')
+    const lines = (result.stdout || '')
+      .trim()
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+    const jsonLine = [...lines].reverse().find((line) => line.startsWith('{'))
+    return JSON.parse(jsonLine || '{}')
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  }
+}
+
+test('GET and POST /api/approvals smoke the pending approval flow end-to-end', () => {
+  const output = runWithTempDataDir(`
+    const storageMod = await import('./src/lib/server/storage.ts')
+    const approvalsMod = await import('./src/lib/server/approvals.ts')
+    const routeMod = await import('./src/app/api/approvals/route.ts')
+    const storage = storageMod.default || storageMod
+    const approvals = approvalsMod.default || approvalsMod
+    const route = routeMod.default || routeMod
+
+    const now = Date.now()
+    storage.saveSettings({
+      approvalsEnabled: true,
+      approvalAutoApproveCategories: [],
+    })
+
+    const approval = await approvals.requestApprovalMaybeAutoApprove({
+      category: 'tool_access',
+      title: 'Enable Plugin: shell',
+      description: 'Need shell access for a smoke test.',
+      data: { toolId: 'shell', pluginId: 'shell' },
+    })
+
+    const pendingBefore = await route.GET()
+    const pendingBeforeJson = await pendingBefore.json()
+
+    const approveResponse = await route.POST(new Request('http://local/api/approvals', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ id: approval.id, approved: true }),
+    }))
+    const approvePayload = await approveResponse.json()
+
+    const pendingAfter = await route.GET()
+    const pendingAfterJson = await pendingAfter.json()
+
+    const storedApproval = storage.loadApprovals()[approval.id]
+    console.log(JSON.stringify({
+      pendingBeforeCount: Array.isArray(pendingBeforeJson) ? pendingBeforeJson.length : -1,
+      pendingBeforeId: Array.isArray(pendingBeforeJson) ? pendingBeforeJson[0]?.id || null : null,
+      approveStatus: approveResponse.status,
+      approvePayload,
+      pendingAfterCount: Array.isArray(pendingAfterJson) ? pendingAfterJson.length : -1,
+      storedStatus: storedApproval?.status || null,
+    }))
+  `)
+
+  assert.equal(output.pendingBeforeCount, 1)
+  assert.notEqual(output.pendingBeforeId, null)
+  assert.equal(output.approveStatus, 200)
+  assert.equal(output.approvePayload?.ok, true)
+  assert.equal(output.pendingAfterCount, 0)
+  assert.equal(output.storedStatus, 'approved')
+})
+
+test('POST /api/approvals rejects invalid payloads and remains idempotent for repeated decisions', () => {
+  const output = runWithTempDataDir(`
+    const storageMod = await import('./src/lib/server/storage.ts')
+    const approvalsMod = await import('./src/lib/server/approvals.ts')
+    const routeMod = await import('./src/app/api/approvals/route.ts')
+    const storage = storageMod.default || storageMod
+    const approvals = approvalsMod.default || approvalsMod
+    const route = routeMod.default || routeMod
+
+    const now = Date.now()
+    storage.saveSettings({
+      approvalsEnabled: true,
+      approvalAutoApproveCategories: [],
+    })
+
+    const approval = await approvals.requestApprovalMaybeAutoApprove({
+      category: 'tool_access',
+      title: 'Enable Plugin: shell',
+      description: 'Need shell access for idempotency test.',
+      data: { toolId: 'shell', pluginId: 'shell' },
+    })
+
+    const invalidResponse = await route.POST(new Request('http://local/api/approvals', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ id: approval.id }),
+    }))
+    const invalidPayload = await invalidResponse.json()
+
+    const firstApprove = await route.POST(new Request('http://local/api/approvals', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ id: approval.id, approved: true }),
+    }))
+    const secondApprove = await route.POST(new Request('http://local/api/approvals', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ id: approval.id, approved: true }),
+    }))
+
+    const pending = await route.GET()
+    const pendingJson = await pending.json()
+    const storedApproval = storage.loadApprovals()[approval.id]
+    console.log(JSON.stringify({
+      invalidStatus: invalidResponse.status,
+      invalidError: invalidPayload?.error || null,
+      firstApproveStatus: firstApprove.status,
+      secondApproveStatus: secondApprove.status,
+      pendingCount: Array.isArray(pendingJson) ? pendingJson.length : -1,
+      storedStatus: storedApproval?.status || null,
+    }))
+  `)
+
+  assert.equal(output.invalidStatus, 400)
+  assert.match(String(output.invalidError || ''), /id and approved required/i)
+  assert.equal(output.firstApproveStatus, 200)
+  assert.equal(output.secondApproveStatus, 200)
+  assert.equal(output.pendingCount, 0)
+  assert.equal(output.storedStatus, 'approved')
+})

package/src/app/api/canvas/[sessionId]/route.ts

@@ -1,6 +1,7 @@
 import { NextResponse } from 'next/server'
 import { loadSessions, saveSessions } from '@/lib/server/storage'
 import { notify } from '@/lib/server/ws-hub'
+import { normalizeCanvasContent } from '@/lib/canvas-content'
 
 export async function GET(_req: Request, { params }: { params: Promise<{ sessionId: string }> }) {
   const { sessionId } = await params
@@ -21,7 +22,8 @@ export async function POST(req: Request, { params }: { params: Promise<{ session
   const session = sessions[sessionId]
   if (!session) return NextResponse.json({ error: 'Session not found' }, { status: 404 })
 
-  ;(session as Record<string, unknown>).canvasContent = body.content || null
+  const nextContent = normalizeCanvasContent(body.document ?? body.content)
+  ;(session as Record<string, unknown>).canvasContent = nextContent
   session.lastActiveAt = Date.now()
   sessions[sessionId] = session
   saveSessions(sessions)

package/src/app/api/chatrooms/[id]/chat/route.ts

@@ -23,6 +23,7 @@ import { evaluateRoutingRules } from '@/lib/server/chatroom-routing'
 import { markProviderFailure, markProviderSuccess } from '@/lib/server/provider-health'
 import { applyAgentReactionsFromText } from '@/lib/server/chatroom-orchestration'
 import { resolvePrimaryAgentRoute } from '@/lib/server/agent-runtime-config'
+import { shouldSuppressHiddenControlText, stripHiddenControlTokens } from '@/lib/server/assistant-control'
 import type { Chatroom, ChatroomMessage, Agent } from '@/types'
 
 export const dynamic = 'force-dynamic'
@@ -228,7 +229,8 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
               history,
             })
 
-            const responseText = result.finalResponse || result.fullText || fullText
+            const rawResponseText = result.finalResponse || result.fullText || fullText
+            const responseText = stripHiddenControlTokens(rawResponseText)
 
             // Don't persist empty or error-only messages — they pollute chat history
             if (!responseText.trim() && agentError) {
@@ -238,7 +240,7 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
               return []
             }
 
-            if (responseText.trim()) {
+            if (responseText.trim() && !shouldSuppressHiddenControlText(rawResponseText)) {
               appendSyntheticSessionMessage(syntheticSession.id, 'assistant', responseText)
               const parsedMentions = parseMentions(responseText, agents, freshChatroom.agentIds)
               const chainedHealth = filterHealthyChatroomAgents(parsedMentions, agents)

package/src/app/api/chats/[id]/devserver/route.ts

@@ -2,6 +2,27 @@ import { NextResponse } from 'next/server'
 import { spawn } from 'child_process'
 import { loadSessions, devServers, localIP } from '@/lib/server/storage'
 import { notFound } from '@/lib/server/collection-helpers'
+import { resolveDevServerLaunchDir } from '@/lib/server/devserver-launch'
+import net from 'net'
+
+function findFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer()
+    server.listen(0, '0.0.0.0', () => {
+      const address = server.address()
+      const port = typeof address === 'object' && address ? address.port : 0
+      server.close((err) => err ? reject(err) : resolve(port))
+    })
+    server.on('error', reject)
+  })
+}
+
+function buildDevArgs(framework: string, port: number): string[] {
+  if (framework === 'next') {
+    return ['--', '--hostname', '0.0.0.0', '--port', String(port)]
+  }
+  return ['--', '--host', '0.0.0.0', '--port', String(port)]
+}
 
 export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
@@ -17,10 +38,12 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
       return NextResponse.json({ running: true, url: ds.url })
     }
 
-    const proc = spawn('npm', ['run', 'dev', '--', '--host', '0.0.0.0'], {
-      cwd: session.cwd,
+    const launch = resolveDevServerLaunchDir(session.cwd)
+    const port = await findFreePort()
+    const proc = spawn('npm', ['run', 'dev', ...buildDevArgs(launch.framework, port)], {
+      cwd: launch.launchDir,
       stdio: ['ignore', 'pipe', 'pipe'],
-      env: { ...process.env, FORCE_COLOR: '0' },
+      env: { ...process.env, FORCE_COLOR: '0', PORT: String(port) },
     })
 
     let output = ''
@@ -45,19 +68,37 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
     proc.on('close', () => { devServers.delete(id); console.log(`[${id}] dev server stopped`) })
     proc.on('error', () => devServers.delete(id))
 
-    devServers.set(id, { proc, url: `http://${localIP()}:4321` })
-    console.log(`[${id}] starting dev server in ${session.cwd}`)
+    devServers.set(id, { proc, url: `http://${localIP()}:${port}` })
+    console.log(`[${id}] starting dev server in ${launch.launchDir} (session cwd=${session.cwd})`)
 
     // Wait for URL detection
     await new Promise(resolve => setTimeout(resolve, 4000))
     const ds = devServers.get(id)
-    return NextResponse.json({ running: !!ds, url: ds?.url || `http://${localIP()}:4321` })
+    if (!ds) {
+      return NextResponse.json({
+        running: false,
+        error: 'Dev server exited during startup',
+        cwd: launch.launchDir,
+        sessionCwd: session.cwd,
+        framework: launch.framework,
+        output: output.slice(-4000),
+      }, { status: 502 })
+    }
+    return NextResponse.json({
+      running: true,
+      url: ds.url,
+      cwd: launch.launchDir,
+      sessionCwd: session.cwd,
+      framework: launch.framework,
+    })
 
   } else if (action === 'stop') {
     if (devServers.has(id)) {
       const ds = devServers.get(id)!
       try { ds.proc.kill('SIGTERM') } catch {}
-      try { process.kill(-ds.proc.pid, 'SIGTERM') } catch {}
+      if (typeof ds.proc.pid === 'number') {
+        try { process.kill(-ds.proc.pid, 'SIGTERM') } catch {}
+      }
       devServers.delete(id)
     }
     return NextResponse.json({ running: false })