chore: finish slimclaw runtime convergence (#1087)

* docs: add slimclaw runtime unification plan

* docs: clarify slimclaw optimization payoff

* docs: tighten slimclaw plan wording

* docs: harden slimclaw artifact and patch boundaries

* docs: refine slimclaw prepare contract

* docs: refine slimclaw desktop runtime constraints

* chore: introduce slimclaw runtime path contract

* chore: route runtime consumers through slimclaw prepare contracts

* chore: consolidate slimclaw runtime producer ownership

* chore: centralize slimclaw runtime orchestration

* chore: move slimclaw runtime assets behind package ownership

* chore: finish slimclaw runtime convergence

* chore: retarget runtime workflows to slimclaw

* docs: update runtime patch guidance for slimclaw

* fix: tighten dev runtime health boundaries

* chore: simplify scripts dev cli

* chore: tighten scripts dev logger usage

* chore: move dev tooling into tools

* chore: finish tools/dev migration and harden readiness checks

* chore: surface openclaw dev startup progress

* chore: inline slimclaw tsconfig base options

* fix: require injected openclaw runtime in controller

* fix: harden tools dev service boundaries

* fix: split desktop readiness contract

* fix: start openclaw in launchd lifecycle e2e

* fix: allow unconfigured openclaw in launchd e2e

* fix: harden packaged desktop startup sequencing

* fix: respect external desktop runtime mode

* fix: relax controller dev readiness timeout

* fix: update scripts dev test import path

* fix: relax controller startup timeouts for macos CI

* fix: align desktop dev health checks with external runtime mode

Author: PerishCode

.github/workflows/ci.yml

@@ -121,8 +121,8 @@ jobs:
           fail_ci_if_error: false
           verbose: true
 
-  # ── openclaw-runtime lockfile sync ─────────────────────────────────────────
-  openclaw-runtime-lockfile:
+  # ── slimclaw runtime-seed lockfile sync ────────────────────────────────────
+  slimclaw-runtime-seed-lockfile:
     runs-on: ubuntu-latest
 
     steps:
@@ -134,9 +134,9 @@ jobs:
         with:
           node-version: 24
 
-      - name: Verify openclaw-runtime lockfile is in sync
+      - name: Verify slimclaw runtime-seed lockfile is in sync
         run: corepack npm ci --ignore-scripts --no-audit --no-fund
-        working-directory: openclaw-runtime
+        working-directory: packages/slimclaw/runtime-seed
 
   # ── Build + ESM check ─────────────────────────────────────────────────────
   build:

.github/workflows/desktop-build.yml

@@ -105,7 +105,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.npm
-          key: desktop-npm-cache-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('openclaw-runtime/package-lock.json', 'apps/controller/static/runtime-plugins/openclaw-weixin/package-lock.json') }}
+          key: desktop-npm-cache-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('packages/slimclaw/runtime-seed/package-lock.json', 'apps/controller/static/runtime-plugins/openclaw-weixin/package-lock.json') }}
           restore-keys: |
             desktop-npm-cache-${{ runner.os }}-${{ matrix.arch }}-
             desktop-npm-cache-${{ runner.os }}-

.github/workflows/desktop-ci-dev.yml

@@ -7,10 +7,10 @@ on:
       - 'apps/controller/**'
       - 'apps/web/**'
       - 'packages/shared/**'
-      - 'openclaw-runtime/**'
+      - 'packages/slimclaw/**'
       - 'tests/desktop/**'
       - 'scripts/dev-launchd.sh'
-      - 'scripts/dev/**'
+      - 'tools/dev/**'
       - 'scripts/desktop-check-dev.sh'
       - 'scripts/desktop-stop-smoke.sh'
       - 'scripts/desktop-ci-check.mjs'
@@ -33,10 +33,10 @@ on:
       - 'apps/controller/**'
       - 'apps/web/**'
       - 'packages/shared/**'
-      - 'openclaw-runtime/**'
+      - 'packages/slimclaw/**'
       - 'tests/desktop/**'
       - 'scripts/dev-launchd.sh'
-      - 'scripts/dev/**'
+      - 'tools/dev/**'
       - 'scripts/desktop-check-dev.sh'
       - 'scripts/desktop-stop-smoke.sh'
       - 'scripts/desktop-ci-check.mjs'
@@ -96,7 +96,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.npm
-          key: desktop-npm-cache-${{ runner.os }}-arm64-${{ hashFiles('openclaw-runtime/package-lock.json', 'apps/controller/static/runtime-plugins/openclaw-weixin/package-lock.json') }}
+          key: desktop-npm-cache-${{ runner.os }}-arm64-${{ hashFiles('packages/slimclaw/runtime-seed/package-lock.json', 'apps/controller/static/runtime-plugins/openclaw-weixin/package-lock.json') }}
           restore-keys: |
             desktop-npm-cache-${{ runner.os }}-arm64-
             desktop-npm-cache-${{ runner.os }}-

.github/workflows/desktop-ci-dist-full.yml

@@ -4,8 +4,7 @@ on:
   pull_request:
     paths:
       - "apps/desktop/**"
-      - "openclaw-runtime/**"
-      - "openclaw-runtime-patches/**"
+      - "packages/slimclaw/**"
       - "pnpm-lock.yaml"
       - "scripts/desktop-check-dist.sh"
       - "scripts/desktop-verify-extracted-runner.sh"
@@ -17,8 +16,7 @@ on:
       - main
     paths:
       - "apps/desktop/**"
-      - "openclaw-runtime/**"
-      - "openclaw-runtime-patches/**"
+      - "packages/slimclaw/**"
       - "pnpm-lock.yaml"
       - "scripts/desktop-check-dist.sh"
       - "scripts/desktop-verify-extracted-runner.sh"
@@ -72,7 +70,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.npm
-          key: desktop-npm-cache-${{ runner.os }}-arm64-${{ hashFiles('openclaw-runtime/package-lock.json', 'apps/controller/static/runtime-plugins/openclaw-weixin/package-lock.json') }}
+          key: desktop-npm-cache-${{ runner.os }}-arm64-${{ hashFiles('packages/slimclaw/runtime-seed/package-lock.json', 'apps/controller/static/runtime-plugins/openclaw-weixin/package-lock.json') }}
           restore-keys: |
             desktop-npm-cache-${{ runner.os }}-arm64-
             desktop-npm-cache-${{ runner.os }}-
@@ -153,7 +151,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.npm
-          key: desktop-npm-cache-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('openclaw-runtime/package-lock.json', 'apps/controller/static/runtime-plugins/openclaw-weixin/package-lock.json') }}
+          key: desktop-npm-cache-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('packages/slimclaw/runtime-seed/package-lock.json', 'apps/controller/static/runtime-plugins/openclaw-weixin/package-lock.json') }}
           restore-keys: |
             desktop-npm-cache-${{ runner.os }}-${{ matrix.arch }}-
             desktop-npm-cache-${{ runner.os }}-
@@ -330,7 +328,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~\AppData\Local\npm-cache
-          key: desktop-npm-cache-${{ runner.os }}-x64-${{ hashFiles('openclaw-runtime/package-lock.json', 'apps/controller/static/runtime-plugins/openclaw-weixin/package-lock.json') }}
+          key: desktop-npm-cache-${{ runner.os }}-x64-${{ hashFiles('packages/slimclaw/runtime-seed/package-lock.json', 'apps/controller/static/runtime-plugins/openclaw-weixin/package-lock.json') }}
           restore-keys: |
             desktop-npm-cache-${{ runner.os }}-x64-
             desktop-npm-cache-${{ runner.os }}-

.github/workflows/desktop-ci-dist-lite.yml

@@ -7,8 +7,7 @@ on:
       - "apps/controller/**"
       - "apps/web/**"
       - "packages/shared/**"
-      - "openclaw-runtime/**"
-      - "openclaw-runtime-patches/**"
+      - "packages/slimclaw/**"
       - "scripts/desktop-check-dist.sh"
       - "scripts/desktop-verify-extracted-runner.sh"
       - "scripts/desktop-ci-check.mjs"
@@ -28,8 +27,7 @@ on:
       - "apps/controller/**"
       - "apps/web/**"
       - "packages/shared/**"
-      - "openclaw-runtime/**"
-      - "openclaw-runtime-patches/**"
+      - "packages/slimclaw/**"
       - "scripts/desktop-check-dist.sh"
       - "scripts/desktop-verify-extracted-runner.sh"
       - "scripts/desktop-ci-check.mjs"
@@ -80,7 +78,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.npm
-          key: desktop-npm-cache-${{ runner.os }}-arm64-${{ hashFiles('openclaw-runtime/package-lock.json', 'apps/controller/static/runtime-plugins/openclaw-weixin/package-lock.json') }}
+          key: desktop-npm-cache-${{ runner.os }}-arm64-${{ hashFiles('packages/slimclaw/runtime-seed/package-lock.json', 'apps/controller/static/runtime-plugins/openclaw-weixin/package-lock.json') }}
           restore-keys: |
             desktop-npm-cache-${{ runner.os }}-arm64-
             desktop-npm-cache-${{ runner.os }}-

.github/workflows/desktop-release.yml

@@ -58,7 +58,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.npm
-          key: desktop-npm-cache-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('openclaw-runtime/package-lock.json', 'apps/controller/static/runtime-plugins/openclaw-weixin/package-lock.json') }}
+          key: desktop-npm-cache-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('packages/slimclaw/runtime-seed/package-lock.json', 'apps/controller/static/runtime-plugins/openclaw-weixin/package-lock.json') }}
           restore-keys: |
             desktop-npm-cache-${{ runner.os }}-${{ matrix.arch }}-
             desktop-npm-cache-${{ runner.os }}-

.gitignore

@@ -28,10 +28,10 @@ playwright-report/
 .worktrees/
 .ralph/
 *.p8
-openclaw-runtime/.postinstall-cache.json
 apps/desktop/release/
 apps/desktop/.dist-runtime/
 apps/controller/.dist-runtime/
+packages/slimclaw/.dist-runtime/
 apps/desktop/.cache/
 apps/desktop/build-config.json
 .claude/settings.local.json

AGENTS.md

@@ -10,7 +10,7 @@ Nexu is a desktop-first OpenClaw platform. Users create AI bots, connect them to
 - `apps/controller` — Single-user local control plane for Nexu config, OpenClaw sync, and runtime orchestration
 - `apps/desktop` — Electron desktop runtime shell and sidecar orchestrator
 - `apps/web` — React + Ant Design + Vite
-- `openclaw-runtime` — Repo-local packaged OpenClaw runtime for local dev and desktop packaging; replaces global `openclaw` CLI
+- `packages/slimclaw` — Repo-local Nexu-owned OpenClaw runtime contract, prepared runtime root, and staging/patch ownership for local dev and desktop packaging
 - `packages/shared` — Shared Zod schemas
 - `packages/dev-utils` — TS-first reusable utilities for local script tooling
 
@@ -78,19 +78,19 @@ This repo is desktop-first. Prefer the controller-first path and remove or ignor
 
 ## Desktop local development
 
-- Minimal cold-start setup on a fresh machine is: `pnpm install` -> `pnpm --filter @nexu/shared build` -> copy `scripts/dev/.env.example` to `scripts/dev/.env` only if you need dev-only overrides.
+- Minimal cold-start setup on a fresh machine is: `pnpm install` -> `pnpm --filter @nexu/shared build` -> copy `tools/dev/.env.example` to `tools/dev/.env` only if you need dev-only overrides.
 - Default daily flow is: `pnpm dev start` -> `pnpm dev status <service>` / `pnpm dev logs <service>` as needed -> `pnpm dev stop`.
 - Use `pnpm dev restart` for a clean full-stack recycle; use `pnpm dev restart <service>` only when you are intentionally touching one service.
 - Explicit single-service control remains available through `pnpm dev start <desktop|openclaw|controller|web>`, `pnpm dev stop <service>`, `pnpm dev restart <service>`, `pnpm dev status <service>`, and `pnpm dev logs <service>`.
 - Desktop dev inspect is available through `pnpm dev inspect screenshot`, `pnpm dev inspect eval "<expr>"`, `pnpm dev inspect dom`, and `pnpm dev inspect logs` for agent-friendly renderer inspection without exposing a public production API.
 - `pnpm dev` intentionally does not support `all`; the full local stack order remains `openclaw` -> `controller` -> `web` -> `desktop`.
 - `pnpm dev logs <service>` is session-scoped, prints a fixed header, and tails at most the last 200 lines from the active service session.
-- `scripts/dev/.env.example` is the source-of-truth template for dev-only overrides. Copy it to `scripts/dev/.env` only when you need to override ports, URLs, state paths, or the shared OpenClaw gateway token for local development.
+- `tools/dev/.env.example` is the source-of-truth template for dev-only overrides. Copy it to `tools/dev/.env` only when you need to override ports, URLs, state paths, or the shared OpenClaw gateway token for local development.
 - Keep the detailed startup optimization rules, cache invalidation behavior, and troubleshooting notes in `specs/guides/desktop-runtime-guide.md`; keep only the core workflow expectations here.
 - The repo also includes a local Slack reply smoke probe at `scripts/probe/slack-reply-probe.mjs` (`pnpm probe:slack prepare` / `pnpm probe:slack run`) for verifying the end-to-end Slack DM reply path after local runtime or OpenClaw changes.
 - The Slack smoke probe is not zero-setup: install Chrome Canary first, then manually log into Slack in the opened Canary window before running `pnpm probe:slack run`.
-- The desktop dev launcher is `scripts/dev/`; it is the unified source of truth for local dev orchestration, including platform-specific desktop launch preparation and runtime cleanup.
-- `pnpm dev` desktop launch is owned by `scripts/dev`, which starts the desktop Vite worker and Electron main process explicitly while routing platform-specific setup through `scripts/dev/src/shared/platform/desktop-dev-platform.*`. On macOS, the darwin helper patches the dev Electron binary's `LSUIElement` and refreshes Launch Services metadata before launch.
+- The desktop dev launcher is `tools/dev/`; it is the unified source of truth for local dev orchestration, including platform-specific desktop launch preparation and runtime cleanup.
+- `pnpm dev` desktop launch is owned by `tools/dev`, which starts the desktop Vite worker and Electron main process explicitly while routing platform-specific setup through `tools/dev/src/shared/platform/desktop-dev-platform.*`. On macOS, the darwin helper patches the dev Electron binary's `LSUIElement` and refreshes Launch Services metadata before launch.
 - `pnpm stop` behavior: sends SIGTERM first (triggers `gracefulShutdown` inside Electron → teardown launchd services → dispose orchestrator → kill orphans), waits up to 10 seconds for graceful exit, then SIGKILL as fallback. Also kills tsc watcher and web watcher background processes.
 - Treat `pnpm start` as the canonical cold-start entrypoint for the full local desktop runtime.
 - The active desktop runtime path is controller-first: desktop launches `controller + web + openclaw` and no longer starts local `api`, `gateway`, or `pglite` sidecars.
@@ -173,7 +173,7 @@ The desktop test suite includes real launchd integration tests that run on macOS
 - `scripts/launchd-lifecycle-e2e.sh` — shell-based e2e: bootstrap → verify → teardown → orphan cleanup → re-bootstrap
 - `scripts/desktop-stop-smoke.sh` — post-stop verification: no residual processes, free ports, no stale state
 - `tests/desktop/data-directory-runtime.test.ts` — verifies every plist env var value by calling real `generatePlist()`
-- `tests/desktop/dev-toolchain-invariants.test.ts` — guards against desktop dev-launch regressions (scripts/dev platform helpers remain the single desktop launch decision point, launchd manifests keep `ELECTRON_RUN_AS_NODE`, etc.)
+- `tests/desktop/dev-toolchain-invariants.test.ts` — guards against desktop dev-launch regressions (tools/dev platform helpers remain the single desktop launch decision point, launchd manifests keep `ELECTRON_RUN_AS_NODE`, etc.)
 
 ## Hard rules
 
@@ -217,7 +217,7 @@ See `ARCHITECTURE.md` for the full bird's-eye view. Key points:
 - Monorepo: `apps/controller` (Hono), `apps/web` (React), `apps/desktop` (Electron), `packages/shared` (Zod schemas), `nexu-skills/` (skill repo)
 - Type safety: Zod -> OpenAPI -> generated frontend SDK. Never duplicate types.
 - Config generator: `apps/controller/src/lib/openclaw-config-compiler.ts` builds OpenClaw config from local controller state
-- Local runtime flow: `apps/controller` owns Nexu config/state, writes OpenClaw config/skills/templates, and manages `openclaw-runtime` directly; desktop wraps that controller-first stack with Electron + web sidecars
+- Local runtime flow: `apps/controller` owns Nexu config/state, writes OpenClaw config/skills/templates, and manages the slimclaw-backed OpenClaw runtime contract directly; desktop wraps that controller-first stack with Electron + web sidecars
 - Key data flows: local config compilation, desktop runtime boot, channel sync, file-based skill catalog
 
 ## Code style (quick reference)
@@ -244,7 +244,7 @@ See `ARCHITECTURE.md` for the full bird's-eye view. Key points:
 | API coding patterns | `specs/references/api-patterns.md` |
 | Workspace templates | `specs/guides/workspace-templates.md` |
 | Local Slack smoke probe | `scripts/probe/README.md`, `scripts/probe/slack-reply-probe.mjs` |
-| Local dev CLI guidance | `scripts/dev/AGENTS.md` |
+| Local dev CLI guidance | `tools/dev/AGENTS.md` |
 | Frontend conventions | `specs/FRONTEND.md` |
 | Desktop runtime guide | `specs/guides/desktop-runtime-guide.md` |
 | Desktop update testing guide | `specs/guides/desktop-update-testing.md` |
@@ -264,7 +264,7 @@ See `ARCHITECTURE.md` for the full bird's-eye view. Key points:
 | External runner extraction | `apps/desktop/main/services/launchd-bootstrap.ts` (`ensureExternalNodeRunner`, `resolveLaunchdPaths`) |
 | Desktop auto-updater | `apps/desktop/main/updater/update-manager.ts` (`checkCriticalPathsLocked`, `ensureNexuProcessesDead`) |
 | Entitlements (V8 JIT) | `apps/desktop/build/entitlements.mac.plist`, `apps/desktop/build/entitlements.mac.inherit.plist` |
-| Dev launch scripts | `scripts/dev-launchd.sh`, `scripts/dev/src/services/desktop.ts`, `scripts/dev/src/shared/platform/desktop-dev-platform.*` |
+| Dev launch scripts | `scripts/dev-launchd.sh`, `tools/dev/src/services/desktop.ts`, `tools/dev/src/shared/platform/desktop-dev-platform.*` |
 | Launchd stability tests | `tests/desktop/launchd-integration.test.ts`, `scripts/launchd-lifecycle-e2e.sh` |
 | Entitlements regression tests | `tests/desktop/entitlements-plist.test.ts` |
 | Stop smoke test | `scripts/desktop-stop-smoke.sh` |
@@ -345,14 +345,14 @@ This note should track:
 ## Local quick reference
 
 - Controller env path: `apps/controller/.env`
-- Fresh local-dev cold start: `pnpm install` -> `pnpm --filter @nexu/shared build` -> optional `copy scripts/dev/.env.example scripts/dev/.env` (Windows) or `cp scripts/dev/.env.example scripts/dev/.env` (POSIX) -> `pnpm dev start`
+- Fresh local-dev cold start: `pnpm install` -> `pnpm --filter @nexu/shared build` -> optional `copy tools/dev/.env.example tools/dev/.env` (Windows) or `cp tools/dev/.env.example tools/dev/.env` (POSIX) -> `pnpm dev start`
 - Daily local-dev flow: `pnpm dev start` -> `pnpm dev logs <service>` / `pnpm dev status <service>` when needed -> `pnpm dev restart` for a clean recycle -> `pnpm dev stop`
 - Desktop inspect quick checks: `pnpm dev inspect screenshot`, `pnpm dev inspect eval "document.title"`, `pnpm dev inspect dom --max-html-length 1200`, `pnpm dev inspect logs --limit 20`
 - Desktop proxy env vars: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` (desktop normalizes mixed-case inputs, always merges `localhost,127.0.0.1,::1` into `NO_PROXY`, and propagates uppercase values to child processes)
 - OpenClaw managed skills dir (expected default): `~/.openclaw/skills/`
 - Slack smoke probe setup: install Chrome Canary, set `PROBE_SLACK_URL`, run `pnpm probe:slack prepare`, then manually log into Slack in Canary before `pnpm probe:slack run`
-- `openclaw-runtime` is installed implicitly by `pnpm install`; local development should normally not use a global `openclaw` CLI
+- the slimclaw-managed prepared OpenClaw runtime is installed implicitly by `pnpm install`; local development should normally not use a global `openclaw` CLI
 - Full-stack startup order is `openclaw` -> `controller` -> `web` -> `desktop`; shutdown order is the reverse
-- Prefer `./openclaw-wrapper` over global `openclaw` in local development; it executes `openclaw-runtime/node_modules/openclaw/openclaw.mjs`
+- Prefer `./openclaw-wrapper` over global `openclaw` in local development; it resolves the prepared runtime entry through slimclaw and executes that local OpenClaw CLI entry
 - When OpenClaw is started manually, set `RUNTIME_MANAGE_OPENCLAW_PROCESS=false` for `@nexu/controller` to avoid launching a second OpenClaw process
 - If behavior differs, verify effective `OPENCLAW_STATE_DIR` / `OPENCLAW_CONFIG_PATH` used by the running controller process.

CONTRIBUTING.md

@@ -31,7 +31,7 @@ If you want a lower-friction entry point, we are actively looking for **Good Fir
 - **Git**
 - **Node.js** 24+ (LTS recommended; enforced via `package.json` `engines`)
 - **pnpm** 10.26+ (repo pins `pnpm@10.26.0` via `packageManager`)
-- **npm** 11+ (required for `openclaw-runtime` maintenance flows)
+- **npm** 11+ (required for repo-local OpenClaw runtime maintenance flows)
 
 ### Clone and install
 
@@ -54,7 +54,7 @@ nexu/
 │   ├── desktop/          # Electron desktop shell
 │   └── controller/       # Hono backend + OpenClaw orchestration
 ├── packages/shared/      # Shared Zod schemas
-├── openclaw-runtime/     # Repo-local packaged OpenClaw runtime
+├── packages/slimclaw/    # Repo-local OpenClaw runtime contract + prepared runtime ownership
 ├── scripts/              # Dev/CI scripts (launchd, probes, e2e)
 ├── tests/                # Vitest test suites
 ├── docs/                 # VitePress documentation site