@swarmclawai/swarmclaw 1.0.2 → 1.0.4

package/README.md

@@ -136,6 +136,17 @@ Running `swarmclaw` with no arguments starts the server on `http://localhost:345
 Global install runs `postinstall`, which rebuilds `better-sqlite3` and prepares the sandbox browser image when Docker is available.
 If Docker is not installed yet, SwarmClaw keeps running and falls back to host execution for shell, browser, and `sandbox_exec`.
 No Deno install is required for the local `sandbox_exec` path.
+Runtime state defaults to `~/.swarmclaw` unless you set `SWARMCLAW_HOME`.
+If the standalone server bundle is missing, the first launch builds it under `<swarmclaw-home>/builds/package-<version>` before starting.
+
+### Local project install
+
+```bash
+npm i @swarmclawai/swarmclaw
+npx swarmclaw
+```
+
+Local installs keep runtime state in `<project>/.swarmclaw` by default. The same project-local install works with `pnpm`, `yarn`, or `bun`; use that package manager's exec command to launch the local binary, or run `./node_modules/.bin/swarmclaw` directly.
 
 ### One-off run
 
@@ -146,6 +157,8 @@ yarn dlx @swarmclawai/swarmclaw
 bunx @swarmclawai/swarmclaw
 ```
 
+One-off runs use the published package without keeping a project-local install. Runtime state defaults to `~/.swarmclaw` unless you set `SWARMCLAW_HOME`.
+
 ### Install script
 
 ```bash
@@ -155,7 +168,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.
 It also builds the production bundle so `npm run start` is ready immediately after install.
 No Deno install is required; local sandbox execution is Docker-first with automatic host Node fallback.
-To pin a version: `SWARMCLAW_VERSION=v0.9.6 curl ... | bash`
+To pin a version: `SWARMCLAW_VERSION=v1.0.3 curl ... | bash`
 
 Or run locally from the repo (friendly for non-technical users):
 
@@ -603,7 +616,7 @@ A fuller step-by-step walkthrough lives at https://swarmclaw.ai/docs/plugin-tuto
 
 ### Browser, Watch, and Delegation Upgrades
 
-- **Persistent Browser Profiles**: The built-in `browser` plugin now keeps a reusable profile per chat/session, and subagents inherit the parent profile by default. Profiles live under `~/.swarmclaw/browser-profiles` unless you override `BROWSER_PROFILES_DIR`, so cookies, storage, and authenticated state survive longer-running work without polluting the project tree. Browser state is exposed at `GET /api/chats/[id]/browser`.
+- **Persistent Browser Profiles**: The built-in `browser` plugin now keeps a reusable profile per chat/session, and subagents inherit the parent profile by default. Profiles live under `<swarmclaw-home>/browser-profiles` by default (`~/.swarmclaw/browser-profiles` for global installs, `<project>/.swarmclaw/browser-profiles` for local installs) unless you override `BROWSER_PROFILES_DIR`, so cookies, storage, and authenticated state survive longer-running work without polluting the project tree. Browser state is exposed at `GET /api/chats/[id]/browser`.
 - **Higher-Level Browser Actions**: In addition to raw Playwright-style actions, `browser` supports workflow-oriented actions such as `read_page`, `extract_links`, `extract_form_fields`, `extract_table`, `fill_form`, `submit_form`, `scroll_until`, `download_file`, `complete_web_task`, `verify_text`, `verify_element`, `verify_list`, `verify_value`, `profile`, and `reset_profile`.
 - **Structured Browser State**: Browser sessions persist recent observations, tabs, artifacts (screenshots / PDFs / downloads), current URL, and last errors in `browser_sessions`, which makes autonomous browser tasks easier to resume, inspect, and hand off across turns.
 - **Durable Watches**: `schedule_wake` now uses persisted watch jobs instead of an in-memory timer, and `monitor_tool` supports `create_watch`, `list_watches`, `get_watch`, and `cancel_watch` across `time`, `http`, `file`, `task`, `webhook`, and `page` conditions. The same watch system also powers the new `mailbox`, session-mailbox, and approval waits used by human-loop flows. Watches support common checks like status/status sets, regex or text matches, content changes, existence checks, inbound mailbox correlation IDs, and webhook event filters.

package/bin/doctor-cmd.js

@@ -11,6 +11,8 @@ const {
   SWARMCLAW_HOME,
   findStandaloneServer,
   isGitCheckout,
+  resolvePackageBuildRoot,
+  resolveInstalledNext,
 } = require('./server-cmd.js')
 
 function readPid(pidFile) {
@@ -38,8 +40,10 @@ function buildDoctorReport(opts = {}) {
   const dataDir = path.join(homeDir, 'data')
   const workspaceDir = path.join(homeDir, 'workspace')
   const browserProfilesDir = path.join(homeDir, 'browser-profiles')
-  const nextCliPath = path.join(pkgRoot, 'node_modules', 'next', 'dist', 'bin', 'next')
+  const nextInstall = resolveInstalledNext(pkgRoot)
+  const nextCliPath = nextInstall?.nextCli || path.join(pkgRoot, 'node_modules', 'next', 'dist', 'bin', 'next')
   const standaloneServer = findStandaloneServer({ pkgRoot })
+  const buildRoot = resolvePackageBuildRoot(pkgRoot)
   const pid = readPid(pidFile)
   const running = pid ? isProcessRunning(pid) : false
 
@@ -64,6 +68,7 @@ function buildDoctorReport(opts = {}) {
   return {
     packageVersion: readPackageVersion(pkgRoot) || 'unknown',
     packageRoot: pkgRoot,
+    buildRoot,
     installKind: isGitCheckout(pkgRoot) ? 'git' : 'package',
     homeDir,
     dataDir,
@@ -96,6 +101,7 @@ function printHumanReport(report) {
     `Package version: ${report.packageVersion}`,
     `Install kind: ${report.installKind}`,
     `Package root: ${report.packageRoot}`,
+    `Build root: ${report.buildRoot}`,
     `Home: ${report.homeDir}`,
     `Data: ${report.dataDir}`,
     `Workspace: ${report.workspaceDir}`,

package/bin/server-cmd.js

@@ -3,6 +3,7 @@
 /* eslint-disable @typescript-eslint/no-require-imports */
 
 const fs = require('node:fs')
+const http = require('node:http')
 const path = require('node:path')
 const { spawn, execFileSync } = require('node:child_process')
 const {
@@ -36,6 +37,7 @@ const LOG_FILE = path.join(SWARMCLAW_HOME, 'server.log')
 const DATA_DIR = path.join(SWARMCLAW_HOME, 'data')
 const WORKSPACE_DIR = path.join(SWARMCLAW_HOME, 'workspace')
 const BROWSER_PROFILES_DIR = path.join(SWARMCLAW_HOME, 'browser-profiles')
+const BUILD_WORKSPACES_DIR = path.join(SWARMCLAW_HOME, 'builds')
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -71,6 +73,62 @@ function isProcessRunning(pid) {
   }
 }
 
+function resolveReadyCheckHost(host) {
+  if (host === '0.0.0.0') return '127.0.0.1'
+  if (host === '::') return '::1'
+  return host
+}
+
+function probeHttpReady(host, port, timeoutMs = 1_000) {
+  return new Promise((resolve) => {
+    const req = http.request(
+      {
+        host,
+        port: Number(port),
+        path: '/api/auth',
+        method: 'GET',
+        timeout: timeoutMs,
+      },
+      (res) => {
+        res.resume()
+        resolve(res.statusCode >= 200 && res.statusCode < 500)
+      },
+    )
+
+    req.once('timeout', () => {
+      req.destroy()
+      resolve(false)
+    })
+    req.once('error', () => resolve(false))
+    req.end()
+  })
+}
+
+async function waitForPortReady({
+  host,
+  port,
+  timeoutMs = 30_000,
+  intervalMs = 250,
+  pid = null,
+  isProcessRunningFn = isProcessRunning,
+  probeFn = probeHttpReady,
+} = {}) {
+  const readyHost = resolveReadyCheckHost(host)
+  const deadline = Date.now() + timeoutMs
+
+  while (Date.now() < deadline) {
+    if (pid && !isProcessRunningFn(pid)) {
+      throw new Error(`Detached server process ${pid} exited before becoming ready.`)
+    }
+
+    if (await probeFn(readyHost, port)) return
+
+    await new Promise((resolve) => setTimeout(resolve, intervalMs))
+  }
+
+  throw new Error(`Timed out waiting for ${readyHost}:${port} to become ready.`)
+}
+
 function resolveStandaloneBase(pkgRoot = PKG_ROOT) {
   return path.join(pkgRoot, '.next', 'standalone')
 }
@@ -83,15 +141,112 @@ function getVersion() {
   return readPackageVersion(PKG_ROOT) || 'unknown'
 }
 
+function resolveInstalledNext(pkgRoot = PKG_ROOT) {
+  try {
+    const nextPackageJson = require.resolve('next/package.json', { paths: [pkgRoot] })
+    const nextPackageDir = path.dirname(nextPackageJson)
+    return {
+      nextCli: path.join(nextPackageDir, 'dist', 'bin', 'next'),
+      nodeModulesDir: path.dirname(nextPackageDir),
+    }
+  } catch {
+    return null
+  }
+}
+
 function ensurePackageDependencies(pkgRoot = PKG_ROOT) {
-  const nextCli = path.join(pkgRoot, 'node_modules', 'next', 'dist', 'bin', 'next')
-  if (fs.existsSync(nextCli)) return nextCli
+  const resolved = resolveInstalledNext(pkgRoot)
+  if (resolved && fs.existsSync(resolved.nextCli)) return resolved
 
   const packageManager = detectPackageManager(pkgRoot, process.env)
   const install = getInstallCommand(packageManager)
   log(`Installing dependencies with ${packageManager}...`)
   execFileSync(install.command, install.args, { cwd: pkgRoot, stdio: 'inherit' })
-  return nextCli
+
+  const installed = resolveInstalledNext(pkgRoot)
+  if (installed && fs.existsSync(installed.nextCli)) return installed
+
+  throw new Error('Next.js CLI was not found after installing dependencies.')
+}
+
+function resolvePackageBuildRoot(pkgRoot = PKG_ROOT) {
+  if (isGitCheckout(pkgRoot)) return pkgRoot
+  const version = readPackageVersion(pkgRoot) || 'unknown'
+  return path.join(BUILD_WORKSPACES_DIR, `package-${version}`)
+}
+
+function copyBuildWorkspaceContents(sourceRoot, targetRoot) {
+  const excluded = new Set([
+    '.git',
+    '.next',
+    'data',
+    'node_modules',
+  ])
+
+  ensureDir(targetRoot)
+
+  for (const entry of fs.readdirSync(sourceRoot, { withFileTypes: true })) {
+    if (excluded.has(entry.name)) continue
+
+    const sourcePath = path.join(sourceRoot, entry.name)
+    const targetPath = path.join(targetRoot, entry.name)
+    fs.rmSync(targetPath, { recursive: true, force: true })
+    fs.cpSync(sourcePath, targetPath, {
+      recursive: true,
+      force: true,
+      dereference: true,
+    })
+  }
+}
+
+function symlinkDir(targetPath, linkPath) {
+  fs.rmSync(linkPath, { recursive: true, force: true })
+  fs.symlinkSync(targetPath, linkPath, process.platform === 'win32' ? 'junction' : 'dir')
+}
+
+function prepareBuildWorkspace({ pkgRoot = PKG_ROOT, buildRoot = resolvePackageBuildRoot(pkgRoot), nodeModulesDir } = {}) {
+  copyBuildWorkspaceContents(pkgRoot, buildRoot)
+  symlinkDir(nodeModulesDir, path.join(buildRoot, 'node_modules'))
+  return buildRoot
+}
+
+function resolveStandaloneCandidateRoots(pkgRoot = PKG_ROOT) {
+  const roots = [pkgRoot]
+  const buildRoot = resolvePackageBuildRoot(pkgRoot)
+  if (buildRoot !== pkgRoot) roots.push(buildRoot)
+  return roots
+}
+
+function locateStandaloneServer({ pkgRoot = PKG_ROOT } = {}) {
+  for (const root of resolveStandaloneCandidateRoots(pkgRoot)) {
+    const standaloneBase = resolveStandaloneBase(root)
+    if (!fs.existsSync(standaloneBase)) continue
+
+    const direct = path.join(standaloneBase, 'server.js')
+    if (fs.existsSync(direct)) {
+      return { root, serverJs: direct }
+    }
+
+    function search(dir) {
+      const entries = fs.readdirSync(dir, { withFileTypes: true })
+      for (const entry of entries) {
+        const full = path.join(dir, entry.name)
+        if (entry.isFile() && entry.name === 'server.js') return full
+        if (entry.isDirectory() && entry.name !== 'node_modules') {
+          const found = search(full)
+          if (found) return found
+        }
+      }
+      return null
+    }
+
+    const nested = search(standaloneBase)
+    if (nested) {
+      return { root, serverJs: nested }
+    }
+  }
+
+  return null
 }
 
 // ---------------------------------------------------------------------------
@@ -108,11 +263,17 @@ function runBuild({ pkgRoot = PKG_ROOT } = {}) {
   ensureDir(SWARMCLAW_HOME)
   ensureDir(DATA_DIR)
 
-  const nextCli = ensurePackageDependencies(pkgRoot)
+  const { nextCli, nodeModulesDir } = ensurePackageDependencies(pkgRoot)
+  const buildRoot = resolvePackageBuildRoot(pkgRoot)
+
+  if (buildRoot !== pkgRoot) {
+    prepareBuildWorkspace({ pkgRoot, buildRoot, nodeModulesDir })
+    log(`Using build workspace: ${buildRoot}`)
+  }
 
   log('Building Next.js application (this may take a minute)...')
   execFileSync(process.execPath, [nextCli, 'build', '--webpack'], {
-    cwd: pkgRoot,
+    cwd: buildRoot,
     stdio: 'inherit',
     env: {
       ...process.env,
@@ -130,41 +291,20 @@ function runBuild({ pkgRoot = PKG_ROOT } = {}) {
 // ---------------------------------------------------------------------------
 
 function findStandaloneServer({ pkgRoot = PKG_ROOT } = {}) {
-  const standaloneBase = resolveStandaloneBase(pkgRoot)
-
-  if (!fs.existsSync(standaloneBase)) {
-    return null
-  }
-
-  const direct = path.join(standaloneBase, 'server.js')
-  if (fs.existsSync(direct)) return direct
-
-  function search(dir) {
-    const entries = fs.readdirSync(dir, { withFileTypes: true })
-    for (const entry of entries) {
-      const full = path.join(dir, entry.name)
-      if (entry.isFile() && entry.name === 'server.js') return full
-      if (entry.isDirectory() && entry.name !== 'node_modules') {
-        const found = search(full)
-        if (found) return found
-      }
-    }
-    return null
-  }
-
-  return search(standaloneBase)
+  return locateStandaloneServer({ pkgRoot })?.serverJs || null
 }
 
 // ---------------------------------------------------------------------------
 // Start server
 // ---------------------------------------------------------------------------
 
-function startServer(opts, { pkgRoot = PKG_ROOT } = {}) {
-  const serverJs = findStandaloneServer({ pkgRoot })
-  if (!serverJs) {
+async function startServer(opts, { pkgRoot = PKG_ROOT } = {}) {
+  const standalone = locateStandaloneServer({ pkgRoot })
+  if (!standalone) {
     logError('Standalone server.js not found in the installed package. Try running: swarmclaw server --build')
     process.exit(1)
   }
+  const { root: runtimeRoot, serverJs } = standalone
 
   ensureDir(SWARMCLAW_HOME)
   ensureDir(DATA_DIR)
@@ -186,26 +326,38 @@ function startServer(opts, { pkgRoot = PKG_ROOT } = {}) {
 
   log(`Starting server on ${host}:${port} (WebSocket: ${wsPort})...`)
   log(`Package root: ${pkgRoot}`)
+  log(`Runtime root: ${runtimeRoot}`)
   log(`Home: ${SWARMCLAW_HOME}`)
   log(`Data directory: ${DATA_DIR}`)
 
   if (opts.detach) {
     const logStream = fs.openSync(LOG_FILE, 'a')
     const child = spawn(process.execPath, [serverJs], {
-      cwd: pkgRoot,
+      cwd: runtimeRoot,
       detached: true,
       env,
       stdio: ['ignore', logStream, logStream],
     })
 
-    child.unref()
     fs.writeFileSync(PID_FILE, String(child.pid))
-    log(`Server started in background (PID: ${child.pid})`)
-    log(`Logs: ${LOG_FILE}`)
-    process.exit(0)
+    try {
+      await waitForPortReady({ host, port, pid: child.pid })
+      child.unref()
+      log(`Server started in background (PID: ${child.pid})`)
+      log(`Logs: ${LOG_FILE}`)
+      process.exit(0)
+    } catch (err) {
+      try {
+        if (isProcessRunning(child.pid)) process.kill(child.pid, 'SIGTERM')
+      } catch {}
+      try { fs.unlinkSync(PID_FILE) } catch {}
+      logError(`Detached start failed: ${err.message}`)
+      logError(`Check logs: ${LOG_FILE}`)
+      process.exit(1)
+    }
   } else {
     const child = spawn(process.execPath, [serverJs], {
-      cwd: pkgRoot,
+      cwd: runtimeRoot,
       env,
       stdio: 'inherit',
     })
@@ -263,6 +415,7 @@ function showStatus() {
   }
 
   log(`Package: ${PKG_ROOT}`)
+  log(`Build workspace: ${resolvePackageBuildRoot()}`)
   log(`Home: ${SWARMCLAW_HOME}`)
   log(`Data: ${DATA_DIR}`)
   log(`Workspace: ${WORKSPACE_DIR}`)
@@ -301,7 +454,7 @@ Options:
   console.log(help)
 }
 
-function main(args = process.argv.slice(3)) {
+async function main(args = process.argv.slice(3)) {
   let command = 'start'
   let forceBuild = false
   let detach = false
@@ -361,15 +514,19 @@ function main(args = process.argv.slice(3)) {
     }
   }
 
-  startServer({ port, wsPort, host, detach })
+  await startServer({ port, wsPort, host, detach })
 }
 
 if (require.main === module) {
-  main()
+  void main().catch((err) => {
+    logError(err?.message || String(err))
+    process.exit(1)
+  })
 }
 
 module.exports = {
   DATA_DIR,
+  BUILD_WORKSPACES_DIR,
   BROWSER_PROFILES_DIR,
   PKG_ROOT,
   SWARMCLAW_HOME,
@@ -377,8 +534,15 @@ module.exports = {
   findStandaloneServer,
   getVersion,
   isGitCheckout,
+  locateStandaloneServer,
   main,
   needsBuild,
+  prepareBuildWorkspace,
+  resolveInstalledNext,
+  resolvePackageBuildRoot,
+  resolveReadyCheckHost,
+  resolveStandaloneCandidateRoots,
   resolveStandaloneBase,
   runBuild,
+  waitForPortReady,
 }

package/bin/swarmclaw.js

@@ -128,7 +128,7 @@ async function runHelp(argv) {
   }
 
   if (target === 'run' || target === 'start' || target === 'stop' || target === 'status' || target === 'server') {
-    require('./server-cmd.js').main(['--help'])
+    await require('./server-cmd.js').main(['--help'])
     return
   }
   if (target === 'worker') {
@@ -164,7 +164,7 @@ async function main() {
 
   // Default to 'server' when invoked with no arguments.
   if (!top) {
-    require('./server-cmd.js').main([])
+    await require('./server-cmd.js').main([])
     return
   }
 
@@ -185,15 +185,15 @@ async function main() {
 
   // Route local lifecycle/maintenance commands to CJS scripts (no TS dependency).
   if (top === 'server') {
-    require('./server-cmd.js').main(argv.slice(1))
+    await require('./server-cmd.js').main(argv.slice(1))
     return
   }
   if (top === 'run' || top === 'start') {
-    require('./server-cmd.js').main(argv.slice(1))
+    await require('./server-cmd.js').main(argv.slice(1))
     return
   }
   if (top === 'status' || top === 'stop') {
-    require('./server-cmd.js').main([top, ...argv.slice(1)])
+    await require('./server-cmd.js').main([top, ...argv.slice(1)])
     return
   }
   if (top === 'worker') {
@@ -217,7 +217,10 @@ async function main() {
 }
 
 if (require.main === module) {
-  void main()
+  void main().catch((err) => {
+    process.stderr.write(`${err?.message || String(err)}\n`)
+    process.exit(1)
+  })
 }
 
 module.exports = {

package/bin/worker-cmd.js

@@ -9,7 +9,7 @@ const {
   PKG_ROOT,
   SWARMCLAW_HOME,
   WORKSPACE_DIR,
-  findStandaloneServer,
+  locateStandaloneServer,
 } = require('./server-cmd.js')
 
 function printHelp() {
@@ -51,14 +51,15 @@ function main(args = process.argv.slice(3)) {
   console.log(`[swarmclaw] Workspace directory: ${WORKSPACE_DIR}`)
   console.log(`[swarmclaw] Browser profiles: ${BROWSER_PROFILES_DIR}`)
 
-  const serverJs = findStandaloneServer()
-  if (!serverJs) {
+  const standalone = locateStandaloneServer()
+  if (!standalone) {
     console.error('[swarmclaw] Standalone server.js not found in the installed package. Try running: swarmclaw server --build')
     process.exit(1)
   }
+  const { root: runtimeRoot, serverJs } = standalone
 
   const child = spawn(process.execPath, [serverJs], {
-    cwd: PKG_ROOT,
+    cwd: runtimeRoot,
     env: process.env,
     stdio: 'inherit',
   })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Self-hosted AI agent orchestration dashboard with OpenClaw integration, multi-provider support, LangGraph workflows, and chat platform connectors.",
   "license": "MIT",
   "publishConfig": {
@@ -65,7 +65,7 @@
     "lint:baseline": "node ./scripts/lint-baseline.mjs check",
     "lint:baseline:update": "node ./scripts/lint-baseline.mjs update",
     "cli": "node ./bin/swarmclaw.js",
-    "test:cli": "node --test src/cli/*.test.js bin/*.test.js",
+    "test:cli": "node --test src/cli/*.test.js bin/*.test.js scripts/postinstall.test.mjs",
     "test:setup": "tsx --test src/app/api/setup/check-provider/route.test.ts src/lib/server/provider-model-discovery.test.ts src/components/auth/setup-wizard/utils.test.ts src/components/auth/setup-wizard/types.test.ts src/hooks/setup-done-detection.test.ts src/lib/setup-defaults.test.ts",
     "test:openclaw": "tsx --test src/lib/openclaw/openclaw-agent-id.test.ts src/lib/openclaw/openclaw-endpoint.test.ts src/lib/server/agents/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw/agent-resolver.test.ts src/lib/server/openclaw/deploy.test.ts src/lib/server/openclaw/skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/tasks/task-quality-gate.test.ts src/lib/server/tasks/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts src/lib/providers/openclaw-exports.test.ts src/app/api/openclaw/dashboard-url/route.test.ts",
     "test:mcp:conformance": "node --import tsx ./scripts/mcp-conformance-check.ts",
@@ -122,12 +122,11 @@
     "sonner": "^2.0.7",
     "tailwindcss": "^4",
     "tailwind-merge": "^3.4.1",
+    "typescript": "^5",
     "tw-animate-css": "^1.4.0",
     "ws": "^8.19.0",
     "zod": "^4.3.6",
-    "zustand": "^5.0.11"
-  },
-  "devDependencies": {
+    "zustand": "^5.0.11",
     "@types/better-sqlite3": "^7.6.13",
     "@types/mailparser": "^3.4.6",
     "@types/node": "^20",
@@ -135,11 +134,12 @@
     "@types/qrcode": "^1.5.6",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-    "@types/ws": "^8.18.1",
+    "@types/ws": "^8.18.1"
+  },
+  "devDependencies": {
     "eslint": "^9",
     "eslint-config-next": "16.1.6",
-    "tsx": "^4.20.6",
-    "typescript": "^5"
+    "tsx": "^4.20.6"
   },
   "optionalDependencies": {
     "botbuilder": "^4.23.3",

package/scripts/postinstall.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
+import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { writeFileSync } from 'node:fs'
 import { spawnSync } from 'node:child_process'
 const INSTALL_METADATA_FILE = '.swarmclaw-install.json'
 const scriptDir = path.dirname(fileURLToPath(import.meta.url))
@@ -48,7 +48,7 @@ function formatFailure(result) {
 }
 
 try {
-  writeFileSync(
+  fs.writeFileSync(
     new URL(`../${INSTALL_METADATA_FILE}`, import.meta.url),
     JSON.stringify({
       packageManager: installedWith,
@@ -72,18 +72,22 @@ if (result.error || (result.status ?? 0) !== 0) {
 }
 
 if (!process.env.CI) {
-  const sandboxImage = spawnSync(process.execPath, [ensureSandboxBrowserScript, '--quiet'], {
-    cwd: packageRoot,
-    encoding: 'utf8',
-    stdio: 'pipe',
-  })
-  if (sandboxImage.error || (sandboxImage.status ?? 0) !== 0) {
-    logWarn(`sandbox browser image setup failed: ${formatFailure(sandboxImage)}`)
-    logWarn('Retry manually with: node ./scripts/ensure-sandbox-browser-image.mjs')
-  }
+  if (!fs.existsSync(ensureSandboxBrowserScript)) {
+    logNote('Sandbox browser image helper is not present in this install context. Skipping setup.')
+  } else {
+    const sandboxImage = spawnSync(process.execPath, [ensureSandboxBrowserScript, '--quiet'], {
+      cwd: packageRoot,
+      encoding: 'utf8',
+      stdio: 'pipe',
+    })
+    if (sandboxImage.error || (sandboxImage.status ?? 0) !== 0) {
+      logWarn(`sandbox browser image setup failed: ${formatFailure(sandboxImage)}`)
+      logWarn('Retry manually with: node ./scripts/ensure-sandbox-browser-image.mjs')
+    }
 
-  if (!commandExists('docker')) {
-    logNote('Docker was not found. Container sandboxes will fall back to host execution until Docker is installed.')
+    if (!commandExists('docker')) {
+      logNote('Docker was not found. Container sandboxes will fall back to host execution until Docker is installed.')
+    }
   }
 }
 

package/src/app/usage/page.tsx

@@ -61,6 +61,16 @@ const CHART_COLORS = [
   '#60A5FA', '#4ADE80',
 ]
 
+function numericChartValue(value: unknown): number {
+  if (Array.isArray(value)) return numericChartValue(value[0])
+  if (typeof value === 'number') return Number.isFinite(value) ? value : 0
+  if (typeof value === 'string') {
+    const parsed = Number(value)
+    return Number.isFinite(parsed) ? parsed : 0
+  }
+  return 0
+}
+
 
 function formatBucketLabel(bucket: string, range: Range): string {
   if (range === '24h') {
@@ -306,7 +316,7 @@ export default function UsagePage() {
                       <CartesianGrid strokeDasharray="3 3" stroke="rgba(255,255,255,0.06)" />
                       <XAxis dataKey="label" tick={{ fill: '#888', fontSize: 11 }} axisLine={false} tickLine={false} />
                       <YAxis tick={{ fill: '#888', fontSize: 11 }} axisLine={false} tickLine={false} tickFormatter={formatTokens} />
-                      <Tooltip {...tooltipStyle} formatter={(value: number | undefined) => [formatTokens(value ?? 0), 'Tokens']} />
+                      <Tooltip {...tooltipStyle} formatter={(value) => [formatTokens(numericChartValue(value)), 'Tokens']} />
                       <Line type="monotone" dataKey="tokens" stroke="#818CF8" strokeWidth={2} dot={false} activeDot={{ r: 4, fill: '#818CF8' }} />
                     </LineChart>
                   </ResponsiveContainer>
@@ -324,8 +334,8 @@ export default function UsagePage() {
                     <BarChart data={providerData} margin={{ top: 5, right: 20, bottom: 5, left: 0 }}>
                       <CartesianGrid strokeDasharray="3 3" stroke="rgba(255,255,255,0.06)" />
                       <XAxis dataKey="name" tick={{ fill: '#888', fontSize: 11 }} axisLine={false} tickLine={false} />
-                      <YAxis tick={{ fill: '#888', fontSize: 11 }} axisLine={false} tickLine={false} tickFormatter={(v: number) => `$${v}`} />
-                      <Tooltip {...tooltipStyle} formatter={(value: number | undefined) => [formatCost(value ?? 0), 'Cost']} />
+                      <YAxis tick={{ fill: '#888', fontSize: 11 }} axisLine={false} tickLine={false} tickFormatter={(value) => `$${numericChartValue(value)}`} />
+                      <Tooltip {...tooltipStyle} formatter={(value) => [formatCost(numericChartValue(value)), 'Cost']} />
                       <Bar dataKey="cost" radius={[4, 4, 0, 0]}>
                         {providerData.map((_entry, i) => (
                           <Cell key={i} fill={CHART_COLORS[i % CHART_COLORS.length]} />
@@ -343,9 +353,9 @@ export default function UsagePage() {
                   <ResponsiveContainer width="100%" height={280}>
                     <BarChart data={agentData} layout="vertical" margin={{ top: 5, right: 20, bottom: 5, left: 0 }}>
                       <CartesianGrid strokeDasharray="3 3" stroke="rgba(255,255,255,0.06)" horizontal={false} />
-                      <XAxis type="number" tick={{ fill: '#888', fontSize: 11 }} axisLine={false} tickLine={false} tickFormatter={(v: number) => `$${v}`} />
+                      <XAxis type="number" tick={{ fill: '#888', fontSize: 11 }} axisLine={false} tickLine={false} tickFormatter={(value) => `$${numericChartValue(value)}`} />
                       <YAxis type="category" dataKey="name" tick={{ fill: '#888', fontSize: 11 }} axisLine={false} tickLine={false} width={100} />
-                      <Tooltip {...tooltipStyle} formatter={(value: number | undefined) => [formatCost(value ?? 0), 'Cost']} />
+                      <Tooltip {...tooltipStyle} formatter={(value) => [formatCost(numericChartValue(value)), 'Cost']} />
                       <Bar dataKey="cost" radius={[0, 4, 4, 0]}>
                         {agentData.map((_entry, i) => (
                           <Cell key={i} fill={CHART_COLORS[i % CHART_COLORS.length]} />
@@ -370,9 +380,9 @@ export default function UsagePage() {
                       <YAxis type="category" dataKey="name" tick={{ fill: '#888', fontSize: 11 }} axisLine={false} tickLine={false} width={120} />
                       <Tooltip
                         {...tooltipStyle}
-                        formatter={(value: number | undefined, name?: string) => [
-                          formatTokens(value ?? 0),
-                          name === 'definitionTokens' ? 'Context (definitions)' : 'Invocations',
+                        formatter={(value, name) => [
+                          formatTokens(numericChartValue(value)),
+                          String(name) === 'definitionTokens' ? 'Context (definitions)' : 'Invocations',
                         ]}
                       />
                       <Bar dataKey="definitionTokens" fill="#818CF8" radius={[0, 0, 0, 0]} stackId="a" name="definitionTokens" />
@@ -381,9 +391,9 @@ export default function UsagePage() {
                         verticalAlign="bottom"
                         iconType="circle"
                         iconSize={8}
-                        formatter={(value: string) => (
+                        formatter={(value) => (
                           <span style={{ color: '#a0a0b0', fontSize: 11 }}>
-                            {value === 'definitionTokens' ? 'Context (definitions)' : 'Invocations'}
+                            {String(value) === 'definitionTokens' ? 'Context (definitions)' : 'Invocations'}
                           </span>
                         )}
                       />
@@ -431,7 +441,7 @@ export default function UsagePage() {
                           <CartesianGrid strokeDasharray="3 3" stroke="rgba(255,255,255,0.06)" />
                           <XAxis dataKey="label" tick={{ fill: '#888', fontSize: 11 }} axisLine={false} tickLine={false} />
                           <YAxis tick={{ fill: '#888', fontSize: 11 }} axisLine={false} tickLine={false} allowDecimals={false} />
-                          <Tooltip {...tooltipStyle} formatter={(value: number | undefined) => [value ?? 0, 'Completed']} />
+                          <Tooltip {...tooltipStyle} formatter={(value) => [numericChartValue(value), 'Completed']} />
                           <Bar dataKey="count" fill="#34D399" radius={[4, 4, 0, 0]} />
                         </BarChart>
                       </ResponsiveContainer>
@@ -458,7 +468,7 @@ export default function UsagePage() {
                           <Bar dataKey="completed" fill="#34D399" radius={[4, 4, 0, 0]} stackId="a" name="Completed" />
                           <Bar dataKey="failed" fill="#F87171" radius={[4, 4, 0, 0]} stackId="a" name="Failed" />
                           <Legend verticalAlign="bottom" iconType="circle" iconSize={8}
-                            formatter={(value: string) => <span style={{ color: '#a0a0b0', fontSize: 11 }}>{value}</span>} />
+                            formatter={(value) => <span style={{ color: '#a0a0b0', fontSize: 11 }}>{String(value)}</span>} />
                         </BarChart>
                       </ResponsiveContainer>
                     ) : (

package/src/cli/server-cmd.test.js

@@ -58,3 +58,133 @@ test('findStandaloneServer recursively resolves nested standalone server paths',
   fs.rmSync(homeDir, { recursive: true, force: true })
   fs.rmSync(pkgRoot, { recursive: true, force: true })
 })
+
+test('resolvePackageBuildRoot uses a versioned workspace for registry installs', () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-home-'))
+  const pkgRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-pkg-'))
+  const serverCmd = loadServerCmdForHome(homeDir)
+
+  fs.writeFileSync(
+    path.join(pkgRoot, 'package.json'),
+    JSON.stringify({ name: '@swarmclawai/swarmclaw', version: '1.0.2' }),
+    'utf8',
+  )
+
+  assert.equal(
+    serverCmd.resolvePackageBuildRoot(pkgRoot),
+    path.join(homeDir, 'builds', 'package-1.0.2'),
+  )
+
+  fs.rmSync(homeDir, { recursive: true, force: true })
+  fs.rmSync(pkgRoot, { recursive: true, force: true })
+})
+
+test('findStandaloneServer falls back to the external build workspace for registry installs', () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-home-'))
+  const pkgRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-pkg-'))
+  const serverCmd = loadServerCmdForHome(homeDir)
+
+  fs.writeFileSync(
+    path.join(pkgRoot, 'package.json'),
+    JSON.stringify({ name: '@swarmclawai/swarmclaw', version: '1.0.2' }),
+    'utf8',
+  )
+
+  const nestedServer = path.join(
+    serverCmd.resolvePackageBuildRoot(pkgRoot),
+    '.next',
+    'standalone',
+    'Users',
+    'wayde',
+    'Dev',
+    'swarmclaw',
+    'server.js',
+  )
+  fs.mkdirSync(path.dirname(nestedServer), { recursive: true })
+  fs.writeFileSync(nestedServer, 'console.log("ok")\n', 'utf8')
+
+  assert.equal(serverCmd.findStandaloneServer({ pkgRoot }), nestedServer)
+
+  fs.rmSync(homeDir, { recursive: true, force: true })
+  fs.rmSync(pkgRoot, { recursive: true, force: true })
+})
+
+test('prepareBuildWorkspace copies the package tree and links node_modules outside node_modules paths', () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-home-'))
+  const pkgRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-pkg-'))
+  const externalNodeModules = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-node-modules-'))
+  const serverCmd = loadServerCmdForHome(homeDir)
+
+  fs.writeFileSync(
+    path.join(pkgRoot, 'package.json'),
+    JSON.stringify({ name: '@swarmclawai/swarmclaw', version: '1.0.2' }),
+    'utf8',
+  )
+  fs.mkdirSync(path.join(pkgRoot, 'src', 'app'), { recursive: true })
+  fs.writeFileSync(path.join(pkgRoot, 'src', 'app', 'page.tsx'), 'export default function Page() { return null }\n', 'utf8')
+
+  const buildRoot = serverCmd.resolvePackageBuildRoot(pkgRoot)
+  serverCmd.prepareBuildWorkspace({ pkgRoot, buildRoot, nodeModulesDir: externalNodeModules })
+
+  assert.equal(fs.readFileSync(path.join(buildRoot, 'package.json'), 'utf8'), fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'))
+  assert.equal(fs.readFileSync(path.join(buildRoot, 'src', 'app', 'page.tsx'), 'utf8'), 'export default function Page() { return null }\n')
+  assert.equal(fs.lstatSync(path.join(buildRoot, 'node_modules')).isSymbolicLink(), true)
+  assert.equal(fs.realpathSync(path.join(buildRoot, 'node_modules')), fs.realpathSync(externalNodeModules))
+
+  fs.rmSync(homeDir, { recursive: true, force: true })
+  fs.rmSync(pkgRoot, { recursive: true, force: true })
+  fs.rmSync(externalNodeModules, { recursive: true, force: true })
+})
+
+test('resolveReadyCheckHost maps wildcard bind hosts to loopback', () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-home-'))
+  const serverCmd = loadServerCmdForHome(homeDir)
+
+  assert.equal(serverCmd.resolveReadyCheckHost('0.0.0.0'), '127.0.0.1')
+  assert.equal(serverCmd.resolveReadyCheckHost('::'), '::1')
+  assert.equal(serverCmd.resolveReadyCheckHost('127.0.0.1'), '127.0.0.1')
+
+  fs.rmSync(homeDir, { recursive: true, force: true })
+})
+
+test('waitForPortReady resolves once the readiness probe succeeds', async () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-home-'))
+  const serverCmd = loadServerCmdForHome(homeDir)
+  const calls = []
+  let attempts = 0
+
+  await serverCmd.waitForPortReady({
+    host: '0.0.0.0',
+    port: 3456,
+    timeoutMs: 1_000,
+    intervalMs: 10,
+    probeFn: async (host, port) => {
+      calls.push({ host, port })
+      attempts += 1
+      return attempts >= 3
+    },
+  })
+
+  assert.deepEqual(calls[0], { host: '127.0.0.1', port: 3456 })
+  assert.equal(calls.length, 3)
+  fs.rmSync(homeDir, { recursive: true, force: true })
+})
+
+test('waitForPortReady fails fast when the detached process exits before readiness', async () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-server-home-'))
+  const serverCmd = loadServerCmdForHome(homeDir)
+
+  await assert.rejects(
+    serverCmd.waitForPortReady({
+      host: '127.0.0.1',
+      port: 6553,
+      pid: 4242,
+      timeoutMs: 500,
+      intervalMs: 25,
+      isProcessRunningFn: () => false,
+    }),
+    /exited before becoming ready/,
+  )
+
+  fs.rmSync(homeDir, { recursive: true, force: true })
+})

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

@@ -60,9 +60,9 @@ describe('data-dir resolution', () => {
 
     try {
       const env = { ...process.env, HOME: fakeHome, npm_lifecycle_event: 'build:ci' }
-      delete (env as any).DATA_DIR
-      delete (env as any).WORKSPACE_DIR
-      delete (env as any).BROWSER_PROFILES_DIR
+      delete env.DATA_DIR
+      delete env.WORKSPACE_DIR
+      delete env.BROWSER_PROFILES_DIR
 
       const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', `
         const modNs = await import('./src/lib/server/data-dir')
@@ -98,9 +98,9 @@ describe('data-dir resolution', () => {
 
     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
+      delete env.DATA_DIR
+      delete env.WORKSPACE_DIR
+      delete env.BROWSER_PROFILES_DIR
 
       const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', `
         const modNs = await import('./src/lib/server/data-dir')