@swarmclawai/swarmclaw 0.8.9 → 0.9.0

package/Dockerfile.sandbox-browser

@@ -0,0 +1,29 @@
+FROM debian:bookworm-slim@sha256:98f4b71de414932439ac6ac690d7060df1f27161073c5036a7553723881bffbe
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    bash \
+    ca-certificates \
+    chromium \
+    curl \
+    fonts-liberation \
+    fonts-noto-color-emoji \
+    novnc \
+    socat \
+    websockify \
+    x11vnc \
+    xvfb \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY scripts/sandbox-browser-entrypoint.sh /usr/local/bin/swarmclaw-sandbox-browser
+RUN chmod +x /usr/local/bin/swarmclaw-sandbox-browser
+
+RUN useradd --create-home --shell /bin/bash sandbox
+USER sandbox
+WORKDIR /home/sandbox
+
+EXPOSE 9222 5900 6080
+
+CMD ["swarmclaw-sandbox-browser"]

package/README.md

@@ -116,7 +116,7 @@ Skill source and runbook: [`swarmclaw/SKILL.md`](swarmclaw/SKILL.md).
 - **OpenAI Codex CLI** (optional, for `codex-cli` provider) — [Install](https://github.com/openai/codex)
 - **OpenCode CLI** (optional, for `opencode-cli` provider) — [Install](https://github.com/opencode-ai/opencode)
 - **Gemini CLI** (optional, for `delegate` backend `gemini`) — install and authenticate `gemini` on your host
-- **Deno** (required for `sandbox_exec`) — auto-installed by `npm run quickstart` / `npm run setup:easy` when missing
+- **Docker Desktop** (optional, recommended) — enables container sandboxes for shell, browser, and `sandbox_exec`; without Docker, SwarmClaw falls back to host execution
 
 ## Quick Start
 
@@ -133,6 +133,9 @@ swarmclaw server
 ```
 
 `swarmclaw` by itself opens the CLI. `swarmclaw server` launches the packaged standalone server on `http://localhost:3456`.
+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.
 
 ### One-off run
 
@@ -151,7 +154,8 @@ 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.
-To pin a version: `SWARMCLAW_VERSION=v0.8.9 curl ... | bash`
+No Deno install is required; local sandbox execution is Docker-first with automatic host Node fallback.
+To pin a version: `SWARMCLAW_VERSION=v0.9.0 curl ... | bash`
 
 Or run locally from the repo (friendly for non-technical users):
 
@@ -163,8 +167,8 @@ npm run quickstart
 
 `npm run quickstart` will:
 - Check Node/npm versions
-- Install Deno if the sandbox runtime is missing
 - Install dependencies
+- Prepare the Docker sandbox/browser runtime when Docker is available
 - Prepare `.env.local` and `data/`
 - Start the app at `http://localhost:3456`
 
@@ -182,7 +186,9 @@ yarn install && yarn dev
 bun install && bun run dev
 ```
 
-`postinstall` rebuilds `better-sqlite3` natively. If you install with `--ignore-scripts`, run `npm rebuild better-sqlite3` manually.
+`postinstall` rebuilds `better-sqlite3` natively and prepares the sandbox browser image when Docker is available.
+If Docker is missing, SwarmClaw falls back to host execution until Docker is installed.
+If you install with `--ignore-scripts`, run `npm rebuild better-sqlite3` manually and then `node ./scripts/ensure-sandbox-browser-image.mjs`.
 
 On first launch, SwarmClaw will:
 1. Generate an **access key** and display it in the terminal
@@ -383,7 +389,7 @@ Agents can use the following tools when enabled:
 | Image Generation | Generate images from prompts (`generate_image`) via OpenAI, Stability, Replicate, fal.ai, Together, Fireworks, BFL, or custom endpoints; saved to uploads |
 | Email | Send outbound email via SMTP (`email`) with `send`/`status` actions |
 | Calendar | Manage Google/Outlook events (`calendar`) with list/create/update/delete/status actions |
-| Sandbox | Run JS/TS in a Deno sandbox when custom code is necessary. If Deno is unavailable it fails closed with guidance; for simple API calls, prefer HTTP Request. |
+| Sandbox | Run JS/TS in a Docker-preferred Node.js sandbox when custom code is necessary. New and existing agents default to sandbox-enabled configs. If Docker is unavailable, SwarmClaw falls back to host execution; for simple API calls, prefer HTTP Request. |
 | MCP Servers | Connect to external Model Context Protocol servers. Tools from MCP servers are injected as first-class agent tools |
 
 ### Platform Tools
@@ -639,6 +645,7 @@ docker compose up -d
 ```
 
 Data is persisted in `data/` and `.env.local` via volume mounts. Updates: `git pull && docker compose up -d --build`.
+In Docker deployments, local shell, browser, and `sandbox_exec` execution fall back to host execution inside the app container unless you separately provide Docker access to that container.
 
 For prebuilt images (recommended for non-technical users after releases):
 
@@ -699,7 +706,7 @@ npm run dev:webpack
 ### First-Run Helpers
 
 ```bash
-npm run setup:easy      # setup only (installs Deno if missing; does not start server)
+npm run setup:easy      # setup only (prepares sandbox/browser runtime when Docker is available; does not start server)
 npm run quickstart      # setup + start dev server
 npm run quickstart:prod # setup + build + start production server
 npm run update:easy     # safe update helper for local installs
@@ -710,7 +717,7 @@ 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.8.9 style)
+# example release
 npm version patch
 git push origin main --follow-tags
 ```
@@ -720,15 +727,15 @@ 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.8.9 Release Readiness Notes
+#### v0.9.0 Release Readiness Notes
 
-Before shipping `v0.8.9`, confirm the following user-facing changes are reflected in docs:
+Before shipping `v0.9.0`, confirm the following user-facing changes are reflected in docs:
 
-1. Install docs make it explicit that global npm installs use `swarmclaw server`, not the Next dev server, and that the curl installer prebuilds the production bundle.
-2. Update docs note that repository updates rebuild with `npm run build` and packaged installs can use `swarmclaw update` to rebuild the standalone server after upgrading.
-3. Site and README install/version strings are updated to `v0.8.9`, including install snippets, release notes index text, and sidebar/footer labels.
-4. Release notes mention the browser resilience changes and the installer/update build alignment, then absorb any final release bullets from the remaining in-flight work before tagging.
-5. The release branch and `main` stay aligned so the shipped tag points at the same commit users see on the default branch.
+1. Install docs make it explicit that global npm installs use `swarmclaw server`, and that package-manager installs plus the curl installer prepare the sandbox/browser runtime automatically when Docker is available.
+2. Sandbox docs say local `sandbox_exec` no longer requires Deno, defaults to sandbox-enabled agent configs, and falls back to host Node when Docker is unavailable.
+3. Release docs mention the OpenClaw-style sandbox/runtime refresh, heartbeat deferral improvements, and the HMR-safe live chat route fix.
+4. Site and README install/version strings are updated to `v0.9.0`, including pinned install snippets, release notes index text, and sidebar/footer labels.
+5. The release tag, npm package version, and generated GitHub release install snippet all agree on the non-prefixed npm version (`0.9.0`) versus the git tag (`v0.9.0`).
 
 ## CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "0.8.9",
+  "version": "0.9.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": {
@@ -32,7 +32,12 @@
     "bundled-skills/",
     "src/",
     "public/",
+    "Dockerfile.sandbox-browser",
+    "scripts/easy-setup.mjs",
+    "scripts/easy-update.mjs",
+    "scripts/ensure-sandbox-browser-image.mjs",
     "scripts/postinstall.mjs",
+    "scripts/sandbox-browser-entrypoint.sh",
     "next.config.ts",
     "tsconfig.json",
     "postcss.config.mjs",
@@ -52,6 +57,7 @@
     "start:standalone": "node .next/standalone/server.js",
     "smoke:browser": "node ./scripts/browser-route-smoke.mjs",
     "smoke:browser:workbench": "node ./scripts/browser-workbench-smoke.mjs",
+    "sandbox:build:browser": "docker build -f Dockerfile.sandbox-browser -t swarmclaw-sandbox-browser:bookworm-slim .",
     "benchmark:autonomy": "node ./scripts/benchmark-autonomy-harness.mjs",
     "benchmark:agent-regression": "node --import tsx ./scripts/run-agent-regression-suite.ts",
     "lint": "eslint",

package/scripts/easy-setup.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+const args = new Set(process.argv.slice(2))
+const startAfterSetup = args.has('--start') || args.has('--prod')
+const productionMode = args.has('--prod')
+const skipInstall = args.has('--skip-install')
+const cwd = process.cwd()
+
+function log(message) {
+  process.stdout.write(`[setup] ${message}\n`)
+}
+
+function fail(message, code = 1) {
+  process.stderr.write(`[setup] ERROR: ${message}\n`)
+  process.exit(code)
+}
+
+function run(command, commandArgs, options = {}) {
+  const printable = `${command} ${commandArgs.join(' ')}`.trim()
+  log(`$ ${printable}`)
+  const result = spawnSync(command, commandArgs, {
+    cwd,
+    stdio: 'inherit',
+    ...options,
+  })
+  if (result.error) fail(result.error.message)
+  if ((result.status ?? 1) !== 0) {
+    fail(`Command failed: ${printable}`, result.status ?? 1)
+  }
+}
+
+function runOptional(command, commandArgs, options = {}) {
+  const printable = `${command} ${commandArgs.join(' ')}`.trim()
+  log(`$ ${printable}`)
+  const result = spawnSync(command, commandArgs, {
+    cwd,
+    stdio: 'inherit',
+    ...options,
+  })
+  if (result.error || (result.status ?? 1) !== 0) {
+    log(`Optional step failed: ${printable}`)
+    return false
+  }
+  return true
+}
+
+function ensureNodeVersion() {
+  const version = process.versions.node
+  const [majorRaw, minorRaw] = version.split('.')
+  const major = Number.parseInt(majorRaw || '0', 10)
+  const minor = Number.parseInt(minorRaw || '0', 10)
+  if (major < 22 || (major === 22 && minor < 6)) {
+    fail(`Detected Node ${version}. SwarmClaw requires Node 22.6 or newer.`)
+  }
+  log(`Node ${version} detected.`)
+}
+
+function ensureNpm() {
+  const result = spawnSync('npm', ['--version'], { cwd, encoding: 'utf8' })
+  if (result.error || (result.status ?? 1) !== 0) {
+    fail('npm was not found. Install npm and rerun this setup command.')
+  }
+  log(`npm ${String(result.stdout || '').trim()} detected.`)
+}
+
+function commandExists(name) {
+  const lookup = process.platform === 'win32' ? 'where' : 'which'
+  const result = spawnSync(lookup, [name], { cwd, encoding: 'utf8' })
+  return !result.error && (result.status ?? 1) === 0
+}
+
+function ensureProjectRoot() {
+  const pkgPath = path.join(cwd, 'package.json')
+  if (!fs.existsSync(pkgPath)) {
+    fail(`package.json was not found in ${cwd}. Run this command from the SwarmClaw project root.`)
+  }
+}
+
+function ensureEnvFile() {
+  const envPath = path.join(cwd, '.env.local')
+  if (!fs.existsSync(envPath)) {
+    fs.writeFileSync(
+      envPath,
+      '# SwarmClaw local environment variables\n# ACCESS_KEY and CREDENTIAL_SECRET are auto-generated on first app run.\n',
+      'utf8',
+    )
+    log('Created .env.local.')
+  } else {
+    log('.env.local already exists.')
+  }
+}
+
+function ensureDataDir() {
+  const dataDir = path.join(cwd, 'data')
+  fs.mkdirSync(dataDir, { recursive: true })
+  log(`Data directory ready at ${dataDir}.`)
+}
+
+function printNextSteps() {
+  process.stdout.write('\n')
+  log('Setup complete.')
+  process.stdout.write('\n')
+  process.stdout.write('Next steps:\n')
+  process.stdout.write('1. Run `npm run dev`.\n')
+  process.stdout.write('2. Open http://localhost:3456 in your browser.\n')
+  process.stdout.write('3. Copy the access key printed in the terminal and finish the setup wizard.\n')
+  process.stdout.write('   Or run `npx swarmclaw setup init` for interactive CLI setup.\n')
+  process.stdout.write('4. For updates later, run `npm run update:easy`.\n')
+}
+
+function main() {
+  ensureProjectRoot()
+  ensureNodeVersion()
+  ensureNpm()
+  ensureDataDir()
+  ensureEnvFile()
+
+  if (!skipInstall) {
+    run('npm', ['install'])
+  } else {
+    log('Skipping dependency install (--skip-install).')
+  }
+
+  runOptional('node', ['./scripts/ensure-sandbox-browser-image.mjs'])
+  if (!commandExists('docker')) {
+    log('Docker not detected. SwarmClaw will fall back to host execution until Docker Desktop is installed.')
+  }
+
+  if (productionMode) {
+    run('npm', ['run', 'build'])
+  }
+
+  if (startAfterSetup) {
+    run('npm', ['run', productionMode ? 'start' : 'dev'])
+    return
+  }
+
+  printNextSteps()
+}
+
+main()

package/scripts/easy-update.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process'
+
+const args = new Set(process.argv.slice(2))
+const skipBuild = args.has('--skip-build')
+const allowDirty = args.has('--allow-dirty')
+const forceMain = args.has('--main')
+const cwd = process.cwd()
+const RELEASE_TAG_RE = /^v\d+\.\d+\.\d+([-.+][0-9A-Za-z.-]+)?$/
+
+function log(message) {
+  process.stdout.write(`[update] ${message}\n`)
+}
+
+function fail(message, code = 1) {
+  process.stderr.write(`[update] ERROR: ${message}\n`)
+  process.exit(code)
+}
+
+function run(command, commandArgs, options = {}) {
+  const result = spawnSync(command, commandArgs, {
+    cwd,
+    encoding: 'utf8',
+    ...options,
+  })
+  if (result.error) {
+    return { ok: false, out: '', err: result.error.message, code: result.status ?? 1 }
+  }
+  if ((result.status ?? 1) !== 0) {
+    const err = String(result.stderr || result.stdout || '').trim() || `exit ${result.status}`
+    return { ok: false, out: '', err, code: result.status ?? 1 }
+  }
+  return { ok: true, out: String(result.stdout || '').trim(), err: '', code: 0 }
+}
+
+function runOrThrow(command, commandArgs, options = {}) {
+  log(`$ ${command} ${commandArgs.join(' ')}`.trim())
+  const result = spawnSync(command, commandArgs, {
+    cwd,
+    stdio: 'inherit',
+    ...options,
+  })
+  if (result.error) fail(result.error.message)
+  if ((result.status ?? 1) !== 0) {
+    fail(`Command failed: ${command} ${commandArgs.join(' ')}`, result.status ?? 1)
+  }
+}
+
+function runOptional(command, commandArgs, options = {}) {
+  log(`$ ${command} ${commandArgs.join(' ')}`.trim())
+  const result = spawnSync(command, commandArgs, {
+    cwd,
+    stdio: 'inherit',
+    ...options,
+  })
+  if (result.error || (result.status ?? 1) !== 0) {
+    log(`Optional step failed: ${command} ${commandArgs.join(' ')}`)
+    return false
+  }
+  return true
+}
+
+function getLatestStableTag() {
+  const tagList = run('git', ['tag', '--list', 'v*', '--sort=-v:refname'])
+  if (!tagList.ok) return null
+  const tags = tagList.out.split('\n').map((line) => line.trim()).filter(Boolean)
+  return tags.find((tag) => RELEASE_TAG_RE.test(tag)) || null
+}
+
+function main() {
+  const gitCheck = run('git', ['rev-parse', '--is-inside-work-tree'])
+  if (!gitCheck.ok) {
+    fail('This folder is not a git repository. Automatic updates require git.')
+  }
+
+  const dirty = run('git', ['status', '--porcelain'])
+  const isDirty = !!dirty.out
+  if (isDirty && !allowDirty) {
+    const changed = dirty.out.split('\n').map((line) => line.trim()).filter(Boolean)
+    const preview = changed.slice(0, 20)
+    process.stdout.write(`${preview.join('\n')}\n`)
+    if (changed.length > preview.length) {
+      log(`...and ${changed.length - preview.length} more changed file(s).`)
+    }
+    fail('Local changes detected. Commit/stash them first, or rerun with --allow-dirty.')
+  }
+
+  const beforeSha = run('git', ['rev-parse', '--short', 'HEAD'])
+  if (!beforeSha.ok || !beforeSha.out) {
+    fail('Could not resolve current git SHA.')
+  }
+
+  runOrThrow('git', ['fetch', '--tags', 'origin', '--quiet'])
+
+  let updateSource = 'main'
+  let pullOutput = ''
+  const latestTag = forceMain ? null : getLatestStableTag()
+
+  if (latestTag) {
+    const behind = run('git', ['rev-list', `HEAD..${latestTag}^{commit}`, '--count'])
+    const behindBy = Number.parseInt(behind.out || '0', 10) || 0
+
+    if (behindBy <= 0) {
+      log(`Already on latest stable release (${latestTag}) or newer.`)
+      return
+    }
+
+    updateSource = `stable release ${latestTag}`
+    log(`Found ${behindBy} commit(s) behind ${latestTag}. Updating now...`)
+    runOrThrow('git', ['checkout', '-B', 'stable', `${latestTag}^{commit}`])
+    pullOutput = `Updated to ${latestTag}`
+  } else {
+    runOrThrow('git', ['fetch', 'origin', 'main', '--quiet'])
+    const behind = run('git', ['rev-list', 'HEAD..origin/main', '--count'])
+    const behindBy = Number.parseInt(behind.out || '0', 10) || 0
+
+    if (behindBy <= 0) {
+      log('Already up to date. Nothing to install.')
+      return
+    }
+
+    updateSource = 'main branch'
+    log(`Found ${behindBy} new commit(s) on origin/main. Updating now...`)
+    runOrThrow('git', ['pull', '--ff-only', 'origin', 'main'])
+    pullOutput = `Pulled origin/main (+${behindBy})`
+  }
+
+  const changed = run('git', ['diff', '--name-only', `${beforeSha.out}..HEAD`])
+  const changedFiles = new Set((changed.out || '').split('\n').map((s) => s.trim()).filter(Boolean))
+  const depsChanged = changedFiles.has('package.json') || changedFiles.has('package-lock.json')
+
+  if (depsChanged) {
+    runOrThrow('npm', ['install'])
+  } else {
+    log('No dependency changes detected. Skipping npm install.')
+  }
+
+  if (!skipBuild) {
+    runOptional('node', ['./scripts/ensure-sandbox-browser-image.mjs'])
+    runOrThrow('npm', ['run', 'build'])
+  } else {
+    log('Skipping build step (--skip-build).')
+  }
+
+  log('Update complete.')
+  log(`Source: ${updateSource}. ${pullOutput}`.trim())
+  log('Restart SwarmClaw to apply the new version.')
+}
+
+main()

package/scripts/ensure-sandbox-browser-image.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+
+const cwd = process.cwd()
+const args = new Set(process.argv.slice(2))
+const quiet = args.has('--quiet')
+const required = args.has('--required')
+const image = process.env.SWARMCLAW_SANDBOX_BROWSER_IMAGE || 'swarmclaw-sandbox-browser:bookworm-slim'
+const SOURCE_LABEL = 'swarmclaw.sandboxBrowserSourceHash'
+
+function log(message) {
+  if (!quiet) process.stdout.write(`[sandbox-browser] ${message}\n`)
+}
+
+function fail(message, code = 1) {
+  process.stderr.write(`[sandbox-browser] ERROR: ${message}\n`)
+  process.exit(code)
+}
+
+function run(command, commandArgs, options = {}) {
+  return spawnSync(command, commandArgs, {
+    cwd,
+    encoding: 'utf8',
+    ...options,
+  })
+}
+
+function commandExists(name) {
+  const lookup = process.platform === 'win32' ? 'where' : 'which'
+  const result = run(lookup, [name])
+  return !result.error && (result.status ?? 1) === 0
+}
+
+function computeSourceHash() {
+  const hash = crypto.createHash('sha1')
+  for (const relative of ['Dockerfile.sandbox-browser', 'scripts/sandbox-browser-entrypoint.sh']) {
+    const absolute = path.join(cwd, relative)
+    if (!fs.existsSync(absolute)) {
+      fail(`Missing sandbox browser source file: ${relative}`)
+    }
+    hash.update(relative)
+    hash.update(fs.readFileSync(absolute))
+  }
+  return hash.digest('hex')
+}
+
+function readImageLabel(name, label) {
+  const result = run('docker', ['image', 'inspect', '--format', `{{ index .Config.Labels "${label}" }}`, name])
+  if (result.error || (result.status ?? 1) !== 0) return null
+  const value = String(result.stdout || '').trim()
+  return value && value !== '<no value>' ? value : null
+}
+
+function buildImage(sourceHash) {
+  log(`Building sandbox browser image ${image}...`)
+  const result = spawnSync(
+    'docker',
+    [
+      'build',
+      '-f', 'Dockerfile.sandbox-browser',
+      '-t', image,
+      '--label', `${SOURCE_LABEL}=${sourceHash}`,
+      '.',
+    ],
+    {
+      cwd,
+      stdio: 'inherit',
+    },
+  )
+  if (result.error || (result.status ?? 1) !== 0) {
+    if (required) {
+      fail(`Failed to build sandbox browser image ${image}.`, result.status ?? 1)
+    }
+    log(`Skipping sandbox browser image after build failure.`)
+    return false
+  }
+  log(`Sandbox browser image ready: ${image}`)
+  return true
+}
+
+function main() {
+  if (!commandExists('docker')) {
+    if (required) fail('Docker is required to build the sandbox browser image.')
+    log('Docker not available. Skipping sandbox browser image build.')
+    return
+  }
+
+  const sourceHash = computeSourceHash()
+  const currentHash = readImageLabel(image, SOURCE_LABEL)
+  if (currentHash === sourceHash) {
+    log(`Sandbox browser image already current: ${image}`)
+    return
+  }
+
+  buildImage(sourceHash)
+}
+
+main()

package/scripts/postinstall.mjs

@@ -1,8 +1,13 @@
 #!/usr/bin/env node
 
+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))
+const packageRoot = path.resolve(scriptDir, '..')
+const ensureSandboxBrowserScript = path.join(packageRoot, 'scripts', 'ensure-sandbox-browser-image.mjs')
 
 function detectPackageManagerFromUserAgent(userAgent) {
   const normalized = String(userAgent || '').toLowerCase()
@@ -15,6 +20,33 @@ function detectPackageManagerFromUserAgent(userAgent) {
 
 const installedWith = detectPackageManagerFromUserAgent(process.env.npm_config_user_agent) || 'npm'
 
+function logNote(message) {
+  process.stdout.write(`[postinstall] ${message}\n`)
+}
+
+function logWarn(message) {
+  process.stderr.write(`[postinstall] WARN: ${message}\n`)
+}
+
+function commandExists(name) {
+  const lookup = process.platform === 'win32' ? 'where' : 'which'
+  const result = spawnSync(lookup, [name], {
+    cwd: packageRoot,
+    encoding: 'utf8',
+    stdio: 'pipe',
+  })
+  return !result.error && (result.status ?? 1) === 0
+}
+
+function formatFailure(result) {
+  const detail = [
+    result.error?.message,
+    String(result.stderr || '').trim(),
+    String(result.stdout || '').trim(),
+  ].find(Boolean)
+  return detail || `exit ${result.status ?? 1}`
+}
+
 try {
   writeFileSync(
     new URL(`../${INSTALL_METADATA_FILE}`, import.meta.url),
@@ -29,11 +61,30 @@ try {
 }
 
 const result = spawnSync('npm', ['rebuild', 'better-sqlite3', '--silent'], {
-  stdio: 'ignore',
+  cwd: packageRoot,
+  encoding: 'utf8',
+  stdio: 'pipe',
 })
 
-if (result.error) {
-  // Ignore optional native rebuild failures for install resilience.
+if (result.error || (result.status ?? 0) !== 0) {
+  logWarn(`better-sqlite3 rebuild failed: ${formatFailure(result)}`)
+  logWarn('Retry manually with: npm rebuild better-sqlite3')
+}
+
+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 (!commandExists('docker')) {
+    logNote('Docker was not found. Container sandboxes will fall back to host execution until Docker is installed.')
+  }
 }
 
 if (!process.env.CI) {