@swarmclawai/swarmclaw 1.0.0 → 1.0.2

package/src/app/api/webhooks/[id]/helpers.ts

@@ -0,0 +1,253 @@
+import { genId } from '@/lib/id'
+import { NextResponse } from 'next/server'
+import { loadAgents, loadSessions, saveSessions, loadWebhooks, appendWebhookLog, upsertWebhookRetry } from '@/lib/server/storage'
+import { WORKSPACE_DIR } from '@/lib/server/data-dir'
+import { enqueueSessionRun } from '@/lib/server/runtime/session-run-manager'
+import { enqueueSystemEvent } from '@/lib/server/runtime/system-events'
+import { requestHeartbeatNow } from '@/lib/server/runtime/heartbeat-wake'
+import { notFound } from '@/lib/server/collection-helpers'
+import type { WebhookRetryEntry } from '@/types'
+import { triggerWebhookWatchJobs } from '@/lib/server/runtime/watch-jobs'
+import { errorMessage } from '@/lib/shared-utils'
+
+export type WebhookPostDeps = {
+  enqueueRun: typeof enqueueSessionRun
+  enqueueEvent: typeof enqueueSystemEvent
+  requestHeartbeat: typeof requestHeartbeatNow
+}
+
+export const defaultWebhookPostDeps: WebhookPostDeps = {
+  enqueueRun: enqueueSessionRun,
+  enqueueEvent: enqueueSystemEvent,
+  requestHeartbeat: requestHeartbeatNow,
+}
+
+function normalizeEvents(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value
+    .filter((v): v is string => typeof v === 'string')
+    .map((v) => v.trim())
+    .filter(Boolean)
+}
+
+function eventMatches(registered: string[], incoming: string): boolean {
+  if (registered.length === 0) return true
+  if (registered.includes('*')) return true
+  return registered.includes(incoming)
+}
+
+export async function handleWebhookPost(
+  req: Request,
+  id: string,
+  deps: WebhookPostDeps = defaultWebhookPostDeps,
+) {
+  const webhooks = loadWebhooks()
+  const webhook = webhooks[id]
+  if (!webhook) return notFound('Webhook not found')
+  if (webhook.isEnabled === false) {
+    appendWebhookLog(genId(8), {
+      id: genId(8), webhookId: id, event: 'unknown',
+      payload: '', status: 'error', error: 'Webhook is disabled', timestamp: Date.now(),
+    })
+    return NextResponse.json({ error: 'Webhook is disabled' }, { status: 409 })
+  }
+
+  const { timingSafeEqual } = await import('node:crypto')
+  const secret = typeof webhook.secret === 'string' ? webhook.secret.trim() : ''
+  if (secret) {
+    const url = new URL(req.url)
+    const provided = req.headers.get('x-webhook-secret') || url.searchParams.get('secret') || ''
+    const secretBuf = Buffer.from(secret)
+    const providedBuf = Buffer.from(provided)
+    // timingSafeEqual requires equal lengths; compare against secretBuf if lengths differ
+    const compareBuf = providedBuf.length === secretBuf.length ? providedBuf : secretBuf
+    const isInvalid = providedBuf.length !== secretBuf.length || !timingSafeEqual(secretBuf, compareBuf)
+    if (isInvalid) {
+      appendWebhookLog(genId(8), {
+        id: genId(8), webhookId: id, event: 'unknown',
+        payload: '', status: 'error', error: 'Invalid webhook secret', timestamp: Date.now(),
+      })
+      return NextResponse.json({ error: 'Invalid webhook secret' }, { status: 401 })
+    }
+  }
+
+  let payload: unknown = null
+  let rawBody = ''
+  const contentType = req.headers.get('content-type') || ''
+  if (contentType.includes('application/json')) {
+    try {
+      payload = await req.json()
+      rawBody = JSON.stringify(payload)
+    } catch {
+      payload = {}
+      rawBody = '{}'
+    }
+  } else {
+    rawBody = await req.text()
+    try {
+      payload = JSON.parse(rawBody)
+    } catch {
+      payload = { raw: rawBody }
+    }
+  }
+
+  const url = new URL(req.url)
+  const incomingEvent = String(
+    (payload as Record<string, unknown> | null)?.type
+      || (payload as Record<string, unknown> | null)?.event
+      || req.headers.get('x-event-type')
+      || url.searchParams.get('event')
+      || 'unknown',
+  )
+  const registeredEvents = normalizeEvents(webhook.events)
+  if (!eventMatches(registeredEvents, incomingEvent)) {
+    return NextResponse.json({
+      ok: true,
+      ignored: true,
+      reason: 'Event does not match webhook filters',
+      event: incomingEvent,
+    })
+  }
+
+  triggerWebhookWatchJobs({
+    webhookId: id,
+    event: incomingEvent,
+    payloadPreview: rawBody,
+  })
+
+  const agents = loadAgents()
+  const agent = webhook.agentId ? agents[webhook.agentId] : null
+  if (!agent) {
+    appendWebhookLog(genId(8), {
+      id: genId(8), webhookId: id, event: incomingEvent,
+      payload: (rawBody || '').slice(0, 2000), status: 'error', error: 'Webhook agent is not configured or missing', timestamp: Date.now(),
+    })
+    return NextResponse.json({ error: 'Webhook agent is not configured or missing' }, { status: 400 })
+  }
+
+  const sessions = loadSessions()
+  const sessionName = `webhook:${id}`
+  let session = Object.values(sessions).find((s: unknown) => {
+    const rec = s as Record<string, unknown>
+    return rec.name === sessionName && rec.agentId === agent.id
+  }) as Record<string, unknown> | undefined
+  if (!session) {
+    const sessionId = genId()
+    const now = Date.now()
+    session = {
+      id: sessionId,
+      name: sessionName,
+      cwd: WORKSPACE_DIR,
+      user: 'system',
+      provider: agent.provider || 'claude-cli',
+      model: agent.model || '',
+      credentialId: agent.credentialId || null,
+      apiEndpoint: agent.apiEndpoint || null,
+      claudeSessionId: null,
+      codexThreadId: null,
+      opencodeSessionId: null,
+      delegateResumeIds: {
+        claudeCode: null,
+        codex: null,
+        opencode: null,
+      },
+      messages: [],
+      createdAt: now,
+      lastActiveAt: now,
+      sessionType: 'human',
+      agentId: agent.id,
+      parentSessionId: null,
+      tools: agent.tools || [],
+      heartbeatEnabled: agent.heartbeatEnabled ?? false,
+      heartbeatIntervalSec: agent.heartbeatIntervalSec ?? null,
+    }
+    sessions[session.id as string] = session
+    saveSessions(sessions)
+  }
+
+  const sid = session.id as string
+  const payloadPreview = (rawBody || '').slice(0, 12_000)
+  const prompt = [
+    'Webhook event received.',
+    `Webhook ID: ${id}`,
+    `Webhook Name: ${webhook.name || id}`,
+    `Source: ${webhook.source || 'custom'}`,
+    `Event: ${incomingEvent}`,
+    `Received At: ${new Date().toISOString()}`,
+    '',
+    'Payload:',
+    payloadPreview || '(empty payload)',
+    '',
+    'Handle this event now. If this requires notifying the user, use configured connector tools.',
+  ].join('\n')
+
+  try {
+    const run = deps.enqueueRun({
+      sessionId: sid,
+      message: prompt,
+      source: 'webhook',
+      internal: false,
+      mode: 'followup',
+    })
+
+    // Enqueue system event + heartbeat wake
+    deps.enqueueEvent(sid, `Webhook received: ${webhook.name || id} (${incomingEvent})`)
+    if (webhook.agentId) {
+      deps.requestHeartbeat({
+        agentId: webhook.agentId,
+        eventId: `webhook:${id}:${incomingEvent}:${Date.now()}`,
+        reason: 'webhook',
+        source: `webhook:${id}`,
+        resumeMessage: `Webhook received: ${webhook.name || id} (${incomingEvent})`,
+        detail: payloadPreview || '(empty payload)',
+      })
+    }
+
+    appendWebhookLog(genId(8), {
+      id: genId(8), webhookId: id, event: incomingEvent,
+      payload: (rawBody || '').slice(0, 2000), status: 'success',
+      sessionId: sid, runId: run.runId, timestamp: Date.now(),
+    })
+
+    return NextResponse.json({
+      ok: true,
+      webhookId: id,
+      event: incomingEvent,
+      sessionId: sid,
+      runId: run.runId,
+    })
+  } catch (err: unknown) {
+    const errorMsg = errorMessage(err)
+
+    // Enqueue for retry with exponential backoff
+    const retryId = genId()
+    const now = Date.now()
+    const retryEntry: WebhookRetryEntry = {
+      id: retryId,
+      webhookId: id,
+      event: incomingEvent,
+      payload: (rawBody || '').slice(0, 12_000),
+      attempts: 1,
+      maxAttempts: 3,
+      nextRetryAt: now + 30_000,
+      deadLettered: false,
+      createdAt: now,
+    }
+    upsertWebhookRetry(retryId, retryEntry)
+
+    appendWebhookLog(genId(8), {
+      id: genId(8), webhookId: id, event: incomingEvent,
+      payload: (rawBody || '').slice(0, 2000), status: 'error',
+      error: `Dispatch failed, queued for retry: ${errorMsg}`, timestamp: Date.now(),
+    })
+
+    return NextResponse.json({
+      ok: true,
+      webhookId: id,
+      event: incomingEvent,
+      retryQueued: true,
+      retryId,
+      error: errorMsg,
+    })
+  }
+}

package/src/app/api/webhooks/[id]/route.ts

@@ -1,31 +1,11 @@
-import { genId } from '@/lib/id'
-import { timingSafeEqual } from 'node:crypto'
 import { NextResponse } from 'next/server'
-import { loadAgents, loadSessions, loadWebhooks, saveSessions, saveWebhooks, appendWebhookLog, upsertWebhookRetry } from '@/lib/server/storage'
-import { WORKSPACE_DIR } from '@/lib/server/data-dir'
-import { enqueueSessionRun } from '@/lib/server/runtime/session-run-manager'
-import { enqueueSystemEvent } from '@/lib/server/runtime/system-events'
-import { requestHeartbeatNow } from '@/lib/server/runtime/heartbeat-wake'
+import { loadWebhooks, saveWebhooks } from '@/lib/server/storage'
 import { mutateItem, deleteItem, notFound, type CollectionOps } from '@/lib/server/collection-helpers'
-import type { WebhookRetryEntry } from '@/types'
-import { triggerWebhookWatchJobs } from '@/lib/server/runtime/watch-jobs'
-import { errorMessage } from '@/lib/shared-utils'
+import { handleWebhookPost } from './helpers'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const ops: CollectionOps<any> = { load: loadWebhooks, save: saveWebhooks }
 
-type WebhookPostDeps = {
-  enqueueRun: typeof enqueueSessionRun
-  enqueueEvent: typeof enqueueSystemEvent
-  requestHeartbeat: typeof requestHeartbeatNow
-}
-
-const defaultWebhookPostDeps: WebhookPostDeps = {
-  enqueueRun: enqueueSessionRun,
-  enqueueEvent: enqueueSystemEvent,
-  requestHeartbeat: requestHeartbeatNow,
-}
-
 function normalizeEvents(value: unknown): string[] {
   if (!Array.isArray(value)) return []
   return value
@@ -34,12 +14,6 @@ function normalizeEvents(value: unknown): string[] {
     .filter(Boolean)
 }
 
-function eventMatches(registered: string[], incoming: string): boolean {
-  if (registered.length === 0) return true
-  if (registered.includes('*')) return true
-  return registered.includes(incoming)
-}
-
 export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
   const webhooks = loadWebhooks()
@@ -71,221 +45,6 @@ export async function DELETE(_req: Request, { params }: { params: Promise<{ id:
   return NextResponse.json({ ok: true })
 }
 
-export async function handleWebhookPost(
-  req: Request,
-  id: string,
-  deps: WebhookPostDeps = defaultWebhookPostDeps,
-) {
-  const webhooks = loadWebhooks()
-  const webhook = webhooks[id]
-  if (!webhook) return notFound('Webhook not found')
-  if (webhook.isEnabled === false) {
-    appendWebhookLog(genId(8), {
-      id: genId(8), webhookId: id, event: 'unknown',
-      payload: '', status: 'error', error: 'Webhook is disabled', timestamp: Date.now(),
-    })
-    return NextResponse.json({ error: 'Webhook is disabled' }, { status: 409 })
-  }
-
-  const secret = typeof webhook.secret === 'string' ? webhook.secret.trim() : ''
-  if (secret) {
-    const url = new URL(req.url)
-    const provided = req.headers.get('x-webhook-secret') || url.searchParams.get('secret') || ''
-    const secretBuf = Buffer.from(secret)
-    const providedBuf = Buffer.from(provided)
-    // timingSafeEqual requires equal lengths; compare against secretBuf if lengths differ
-    const compareBuf = providedBuf.length === secretBuf.length ? providedBuf : secretBuf
-    const isInvalid = providedBuf.length !== secretBuf.length || !timingSafeEqual(secretBuf, compareBuf)
-    if (isInvalid) {
-      appendWebhookLog(genId(8), {
-        id: genId(8), webhookId: id, event: 'unknown',
-        payload: '', status: 'error', error: 'Invalid webhook secret', timestamp: Date.now(),
-      })
-      return NextResponse.json({ error: 'Invalid webhook secret' }, { status: 401 })
-    }
-  }
-
-  let payload: unknown = null
-  let rawBody = ''
-  const contentType = req.headers.get('content-type') || ''
-  if (contentType.includes('application/json')) {
-    try {
-      payload = await req.json()
-      rawBody = JSON.stringify(payload)
-    } catch {
-      payload = {}
-      rawBody = '{}'
-    }
-  } else {
-    rawBody = await req.text()
-    try {
-      payload = JSON.parse(rawBody)
-    } catch {
-      payload = { raw: rawBody }
-    }
-  }
-
-  const url = new URL(req.url)
-  const incomingEvent = String(
-    (payload as Record<string, unknown> | null)?.type
-      || (payload as Record<string, unknown> | null)?.event
-      || req.headers.get('x-event-type')
-      || url.searchParams.get('event')
-      || 'unknown',
-  )
-  const registeredEvents = normalizeEvents(webhook.events)
-  if (!eventMatches(registeredEvents, incomingEvent)) {
-    return NextResponse.json({
-      ok: true,
-      ignored: true,
-      reason: 'Event does not match webhook filters',
-      event: incomingEvent,
-    })
-  }
-
-  triggerWebhookWatchJobs({
-    webhookId: id,
-    event: incomingEvent,
-    payloadPreview: rawBody,
-  })
-
-  const agents = loadAgents()
-  const agent = webhook.agentId ? agents[webhook.agentId] : null
-  if (!agent) {
-    appendWebhookLog(genId(8), {
-      id: genId(8), webhookId: id, event: incomingEvent,
-      payload: (rawBody || '').slice(0, 2000), status: 'error', error: 'Webhook agent is not configured or missing', timestamp: Date.now(),
-    })
-    return NextResponse.json({ error: 'Webhook agent is not configured or missing' }, { status: 400 })
-  }
-
-  const sessions = loadSessions()
-  const sessionName = `webhook:${id}`
-  let session = Object.values(sessions).find((s: unknown) => {
-    const rec = s as Record<string, unknown>
-    return rec.name === sessionName && rec.agentId === agent.id
-  }) as Record<string, unknown> | undefined
-  if (!session) {
-    const sessionId = genId()
-    const now = Date.now()
-    session = {
-      id: sessionId,
-      name: sessionName,
-      cwd: WORKSPACE_DIR,
-      user: 'system',
-      provider: agent.provider || 'claude-cli',
-      model: agent.model || '',
-      credentialId: agent.credentialId || null,
-      apiEndpoint: agent.apiEndpoint || null,
-      claudeSessionId: null,
-      codexThreadId: null,
-      opencodeSessionId: null,
-      delegateResumeIds: {
-        claudeCode: null,
-        codex: null,
-        opencode: null,
-      },
-      messages: [],
-      createdAt: now,
-      lastActiveAt: now,
-      sessionType: 'human',
-      agentId: agent.id,
-      parentSessionId: null,
-      tools: agent.tools || [],
-      heartbeatEnabled: agent.heartbeatEnabled ?? false,
-      heartbeatIntervalSec: agent.heartbeatIntervalSec ?? null,
-    }
-    sessions[session.id as string] = session
-    saveSessions(sessions)
-  }
-
-  const sid = session.id as string
-  const payloadPreview = (rawBody || '').slice(0, 12_000)
-  const prompt = [
-    'Webhook event received.',
-    `Webhook ID: ${id}`,
-    `Webhook Name: ${webhook.name || id}`,
-    `Source: ${webhook.source || 'custom'}`,
-    `Event: ${incomingEvent}`,
-    `Received At: ${new Date().toISOString()}`,
-    '',
-    'Payload:',
-    payloadPreview || '(empty payload)',
-    '',
-    'Handle this event now. If this requires notifying the user, use configured connector tools.',
-  ].join('\n')
-
-  try {
-    const run = deps.enqueueRun({
-      sessionId: sid,
-      message: prompt,
-      source: 'webhook',
-      internal: false,
-      mode: 'followup',
-    })
-
-    // Enqueue system event + heartbeat wake
-    deps.enqueueEvent(sid, `Webhook received: ${webhook.name || id} (${incomingEvent})`)
-    if (webhook.agentId) {
-      deps.requestHeartbeat({
-        agentId: webhook.agentId,
-        eventId: `webhook:${id}:${incomingEvent}:${Date.now()}`,
-        reason: 'webhook',
-        source: `webhook:${id}`,
-        resumeMessage: `Webhook received: ${webhook.name || id} (${incomingEvent})`,
-        detail: payloadPreview || '(empty payload)',
-      })
-    }
-
-    appendWebhookLog(genId(8), {
-      id: genId(8), webhookId: id, event: incomingEvent,
-      payload: (rawBody || '').slice(0, 2000), status: 'success',
-      sessionId: sid, runId: run.runId, timestamp: Date.now(),
-    })
-
-    return NextResponse.json({
-      ok: true,
-      webhookId: id,
-      event: incomingEvent,
-      sessionId: sid,
-      runId: run.runId,
-    })
-  } catch (err: unknown) {
-    const errorMsg = errorMessage(err)
-
-    // Enqueue for retry with exponential backoff
-    const retryId = genId()
-    const now = Date.now()
-    const retryEntry: WebhookRetryEntry = {
-      id: retryId,
-      webhookId: id,
-      event: incomingEvent,
-      payload: (rawBody || '').slice(0, 12_000),
-      attempts: 1,
-      maxAttempts: 3,
-      nextRetryAt: now + 30_000,
-      deadLettered: false,
-      createdAt: now,
-    }
-    upsertWebhookRetry(retryId, retryEntry)
-
-    appendWebhookLog(genId(8), {
-      id: genId(8), webhookId: id, event: incomingEvent,
-      payload: (rawBody || '').slice(0, 2000), status: 'error',
-      error: `Dispatch failed, queued for retry: ${errorMsg}`, timestamp: Date.now(),
-    })
-
-    return NextResponse.json({
-      ok: true,
-      webhookId: id,
-      event: incomingEvent,
-      retryQueued: true,
-      retryId,
-      error: errorMsg,
-    })
-  }
-}
-
 export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
   return handleWebhookPost(req, id)

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

@@ -2,7 +2,7 @@ import assert from 'node:assert/strict'
 import test, { afterEach } from 'node:test'
 
 import { GET as getWebhookHistory } from './[id]/history/route'
-import { handleWebhookPost } from './[id]/route'
+import { handleWebhookPost } from './[id]/helpers'
 import {
   loadAgents,
   loadSessions,
@@ -126,7 +126,9 @@ test('handleWebhookPost creates a session, records success history, and triggers
   assert.match(String(calls.runs[0].message), /Event: build\.completed/)
 
   assert.deepEqual(calls.events, [[sessionId, 'Webhook received: Webhook Smoke (build.completed)']])
-  assert.deepEqual(calls.heartbeats, [{ agentId: 'agent-webhook-smoke', reason: 'webhook' }])
+  assert.equal(calls.heartbeats.length, 1)
+  assert.equal(calls.heartbeats[0].agentId, 'agent-webhook-smoke')
+  assert.equal(calls.heartbeats[0].reason, 'webhook')
 
   const logEntries = Object.values(loadWebhookLogs()) as Array<Record<string, unknown>>
   const successEntry = logEntries.find((entry) => entry.webhookId === webhookId && entry.status === 'success')

package/src/cli/binary.test.js

@@ -119,6 +119,51 @@ test('binary server help exits successfully', () => {
   assert.match(result.stdout, /Usage: swarmclaw server/i)
 })
 
+test('binary run alias routes to server help', () => {
+  const result = runBinary(['run', '--help'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Usage: swarmclaw server/i)
+})
+
+test('binary help command shows root help', () => {
+  const result = runBinary(['help'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /SwarmClaw CLI/i)
+  assert.match(result.stdout, /swarmclaw help \[command\]/i)
+})
+
+test('binary help command shows command help for run alias', () => {
+  const result = runBinary(['help', 'run'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Usage: swarmclaw server/i)
+})
+
+test('binary help command shows command help for doctor alias', () => {
+  const result = runBinary(['help', 'doctor'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Usage: swarmclaw doctor/i)
+})
+
+test('binary status alias routes to local server status', () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-binary-status-'))
+  const result = runBinary(['status'], {
+    env: {
+      SWARMCLAW_HOME: homeDir,
+    },
+  })
+
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Server: not running/i)
+
+  fs.rmSync(homeDir, { recursive: true, force: true })
+})
+
+test('binary doctor help exits successfully', () => {
+  const result = runBinary(['doctor', '--help'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Usage: swarmclaw doctor/i)
+})
+
 test('binary update help exits successfully', () => {
   const result = runBinary(['update', '--help'])
   assert.equal(result.status, 0, result.stderr)
@@ -131,6 +176,18 @@ test('binary version output matches package version', () => {
   assert.equal(result.stdout.trim(), `${PACKAGE_JSON.name} ${PACKAGE_JSON.version}`)
 })
 
+test('binary bare version alias output matches package version', () => {
+  const result = runBinary(['version'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.equal(result.stdout.trim(), `${PACKAGE_JSON.name} ${PACKAGE_JSON.version}`)
+})
+
+test('binary -v alias output matches package version', () => {
+  const result = runBinary(['-v'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.equal(result.stdout.trim(), `${PACKAGE_JSON.name} ${PACKAGE_JSON.version}`)
+})
+
 test('legacy TS launcher falls back to tsx import when strip-types is unavailable', () => {
   const cliPath = path.join(APP_ROOT, 'src', 'cli', 'index.ts')
   const args = buildLegacyTsCliArgs(cliPath, ['runs', 'list'], {

package/src/cli/index.js

@@ -1183,6 +1183,9 @@ function renderGeneralHelp() {
     'SwarmClaw CLI',
     '',
     'Usage:',
+    '  swarmclaw',
+    '  swarmclaw help [command]',
+    '  swarmclaw run|start|stop|status|doctor|update|version',
     '  swarmclaw <group> <command> [args] [options]',
     '',
     'Global options:',
@@ -1199,6 +1202,15 @@ function renderGeneralHelp() {
     '  --help                 Show help',
     '  --version              Show package version',
     '',
+    'Top-level commands:',
+    '  run, start             Start the SwarmClaw server',
+    '  stop                   Stop the detached SwarmClaw server',
+    '  status                 Show local server status',
+    '  doctor                 Show local install/build diagnostics',
+    '  help                   Show root or command help',
+    '  update                 Update this SwarmClaw installation',
+    '  version                Show package version',
+    '',
     'Groups:',
   ]
 
@@ -1210,7 +1222,7 @@ function renderGeneralHelp() {
     }
   }
 
-  lines.push('', 'Use "swarmclaw <group> --help" for group commands.')
+  lines.push('', 'Use "swarmclaw help <command>" or "swarmclaw <group> --help" for more detail.')
   return lines.join('\n')
 }
 

package/src/lib/server/data-dir.test.ts

@@ -90,4 +90,39 @@ describe('data-dir resolution', () => {
       fs.rmSync(tempDir, { recursive: true, force: true })
     }
   })
+
+  it('derives runtime directories from SWARMCLAW_HOME when set', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-data-dir-home-'))
+    const fakeHome = path.join(tempDir, 'home')
+    const swarmclawHome = path.join(tempDir, 'project', '.swarmclaw')
+
+    try {
+      const env = { ...process.env, HOME: fakeHome, SWARMCLAW_HOME: swarmclawHome }
+      delete (env as any).DATA_DIR
+      delete (env as any).WORKSPACE_DIR
+      delete (env as any).BROWSER_PROFILES_DIR
+
+      const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', `
+        const modNs = await import('./src/lib/server/data-dir')
+        const mod = modNs.default || modNs['module.exports'] || modNs
+        console.log(JSON.stringify({
+          dataDir: mod.DATA_DIR,
+          workspaceDir: mod.WORKSPACE_DIR,
+          browserProfilesDir: mod.BROWSER_PROFILES_DIR,
+        }))
+      `], {
+        cwd: repoRoot,
+        env,
+        encoding: 'utf-8',
+      })
+
+      assert.equal(result.status, 0, result.stderr || result.stdout || 'subprocess failed')
+      const payload = extractLastJson(result.stdout || '')
+      assert.equal(payload.dataDir, path.join(swarmclawHome, 'data'))
+      assert.equal(payload.workspaceDir, path.join(swarmclawHome, 'workspace'))
+      assert.equal(payload.browserProfilesDir, path.join(swarmclawHome, 'browser-profiles'))
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true })
+    }
+  })
 })