fix: harden local dev stack flow

Author: PerishCode

AGENTS.md

@@ -24,7 +24,11 @@ All commands use pnpm. Target a single app with `pnpm --filter <package>`.
 
 ```bash
 pnpm install                          # Install
+pnpm --filter @nexu/shared build      # Build shared dist required by cold-start dev flows
+pnpm dev start                        # Start the lightweight local stack: openclaw -> controller -> web -> desktop
 pnpm dev start <service>              # Start one local-dev service: desktop|openclaw|controller|web
+pnpm dev restart                      # Restart the lightweight local stack
+pnpm dev stop                         # Stop the lightweight local stack in reverse order
 pnpm dev stop <service>               # Stop one local-dev service
 pnpm dev restart <service>            # Restart one local-dev service
 pnpm dev status <service>             # Show status for one local-dev service
@@ -67,9 +71,13 @@ This repo is desktop-first. Prefer the controller-first path and remove or ignor
 
 ## Desktop local development
 
-- For script-managed local development, use explicit per-service commands only: `pnpm dev start <desktop|openclaw|controller|web>`, `pnpm dev stop <service>`, `pnpm dev restart <service>`, `pnpm dev status <service>`, and `pnpm dev logs <service>`.
-- `pnpm dev` has no implicit aggregate default and intentionally does not support `all`; start each service deliberately in dependency order when you want the full local stack: `openclaw` -> `controller` -> `web` -> `desktop`.
+- 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.
+- 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>`.
+- `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.
 - 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`.
@@ -252,11 +260,12 @@ 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`
+- 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`
 - 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
-- Local service startup order for the script-managed dev path: `pnpm dev start openclaw` -> `pnpm dev start controller` -> `pnpm dev start web` -> `pnpm dev start desktop`
-- Local service shutdown order for the script-managed dev path: `pnpm dev stop desktop` -> `pnpm dev stop web` -> `pnpm dev stop controller` -> `pnpm dev stop openclaw`
+- 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`
 - 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.

packages/dev-utils/src/index.ts

@@ -2,6 +2,7 @@ export { waitFor } from "./conditions.js";
 export {
   createNodeOptions,
   getListeningPortPid,
+  isProcessRunning,
   terminateProcess,
   waitForChildExit,
   waitForListeningPortPid,

packages/dev-utils/src/process.ts

@@ -13,6 +13,10 @@ export function createNodeOptions(): string {
 }
 
 export async function terminateProcess(pid: number): Promise<void> {
+  if (!isProcessRunning(pid)) {
+    return;
+  }
+
   if (process.platform === "win32") {
     await new Promise<void>((resolve, reject) => {
       const child = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], {
@@ -22,7 +26,7 @@ export async function terminateProcess(pid: number): Promise<void> {
 
       child.once("error", reject);
       child.once("exit", (code) => {
-        if (code === 0) {
+        if (code === 0 || !isProcessRunning(pid)) {
           resolve();
           return;
         }
@@ -42,6 +46,15 @@ export async function terminateProcess(pid: number): Promise<void> {
   }
 }
 
+export function isProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export async function waitForProcessStart(
   child: ChildProcess,
   processName: string,
@@ -140,8 +153,41 @@ export async function getListeningPortPid(
 export async function waitForListeningPortPid(
   port: number,
   serviceName: string,
-  options: { attempts: number; delayMs?: number },
+  options: {
+    attempts: number;
+    delayMs?: number;
+    supervisorPid?: number;
+    supervisorName?: string;
+  },
 ): Promise<number> {
+  const supervisorLabel = options.supervisorName ?? `${serviceName} supervisor`;
+
+  if (options.supervisorPid) {
+    for (let index = 0; index < options.attempts; index += 1) {
+      try {
+        return await getListeningPortPid(port, serviceName);
+      } catch {}
+
+      if (!isProcessRunning(options.supervisorPid)) {
+        throw new Error(
+          `${supervisorLabel} exited before opening port ${port}`,
+        );
+      }
+
+      if (index < options.attempts - 1) {
+        await new Promise((resolve) =>
+          setTimeout(resolve, options.delayMs ?? 250),
+        );
+      }
+    }
+
+    if (!isProcessRunning(options.supervisorPid)) {
+      throw new Error(`${supervisorLabel} exited before opening port ${port}`);
+    }
+
+    throw new Error(`${serviceName} did not open port ${port}`);
+  }
+
   return waitFor(
     () => getListeningPortPid(port, serviceName),
     () => new Error(`${serviceName} did not open port ${port}`),

scripts/dev/AGENTS.md

@@ -25,17 +25,24 @@ This file captures local guidance for the `scripts/dev` CLI surface.
 ## Command surface
 
 - Keep the command surface small and intentional.
-- Preferred commands are explicit single-service commands: `pnpm dev start <desktop|openclaw|controller|web>`, `pnpm dev restart <service>`, `pnpm dev stop <service>`, `pnpm dev status <service>`, and `pnpm dev logs <service>`.
-- Do not reintroduce implicit aggregate defaults such as bare `pnpm dev start` or an `all` target.
+- Fresh-machine cold start is: `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).
+- Daily full-stack flow is: `pnpm dev start` -> work -> `pnpm dev restart` when you need a clean full restart -> `pnpm dev stop` when done.
+- Bare `pnpm dev start` runs the lightweight full local stack in dependency order: `openclaw` -> `controller` -> `web` -> `desktop`.
+- Bare `pnpm dev restart` restarts that stack by stopping in reverse order and starting again in dependency order.
+- Bare `pnpm dev stop` stops that stack in reverse order: `desktop` -> `web` -> `controller` -> `openclaw`.
+- Explicit single-service control remains available: `pnpm dev start <desktop|openclaw|controller|web>`, `pnpm dev restart <service>`, `pnpm dev stop <service>`, `pnpm dev status <service>`, and `pnpm dev logs <service>`.
+- Do not reintroduce an `all` target or any other alias target name.
 - Validate behavior through the real command surface instead of temporary harness scripts.
 - Acceptance must be run from the repo root through `pnpm dev ...`, not by invoking `scripts/dev` internals directly.
-- The default end-to-end acceptance chain is: `pnpm dev start openclaw` -> `pnpm dev logs openclaw` -> `pnpm dev start controller` -> `pnpm dev logs controller` -> `pnpm dev start web` -> `pnpm dev logs web` -> `pnpm dev start desktop` -> `pnpm dev logs desktop` -> stop each service explicitly.
+- The focused acceptance chain is: `pnpm dev start` -> `pnpm dev status <service>` / `pnpm dev logs <service>` as needed -> `pnpm dev stop`.
 
 ## Runtime model
 
 - Root entrypoint stays `pnpm dev ...`.
 - The CLI executes through `pnpm --dir ./scripts/dev exec tsx ./src/index.ts`.
 - `scripts/dev` may use its own `tsconfig.json` features such as `paths`.
+- `scripts/dev/.env.example` is the source-of-truth template for dev-only overrides. Only create `scripts/dev/.env` when you need local overrides for ports, URLs, state paths, config path, log dir, or the shared OpenClaw gateway token.
+- Keep the repo-level pnpm build-script allowlist tight. Do not add Windows-only packaging tools such as `electron-winstaller` unless the team explicitly wants that behavior on every machine.
 - Logs should live under `.tmp/dev/logs/<run_id>/...`.
 - `pnpm dev logs <service>` should resolve the active session only, prepend a fixed metadata header, and tail at most 200 lines by default.
 - Lightweight state should use per-service pid locks under `.tmp/dev/*.pid`.
@@ -53,10 +60,11 @@ This file captures local guidance for the `scripts/dev` CLI surface.
 
 ## FAQ
 
-- Q: `pnpm dev stop <service>` fails because that side is already down. A: This is currently acceptable. Read the matching `.tmp/dev/*.pid`, kill the remaining supervisor manually if needed, remove stale pid locks, then rerun `pnpm dev start <service>` or `pnpm dev restart <service>`.
-- Q: `pnpm dev status <service>` shows `stale`. A: The pid lock still exists but the supervisor pid is no longer alive. Remove the stale `.tmp/dev/*.pid` file and start that service again.
+- Q: A service will not start. A: Start with `pnpm dev status <service>` and `pnpm dev logs <service>`. If the error says a dependency is missing, start that dependency first; if it says a port is busy, kill the listener and retry.
+- Q: `pnpm dev status <service>` shows `stale`. A: The supervisor pid is gone but the lock survived. Prefer `pnpm dev stop <service>` first; if the lock still remains, remove the matching `.tmp/dev/*.pid` file and start again.
 - Q: `pnpm dev logs web` shows `Port 5173 is already in use`. A: A stale Vite process from an earlier experiment is still listening. Kill the listener on `5173`, remove `web.pid` if present, and restart the dev flow.
 - Q: Which pid is stored in each `.tmp/dev/*.pid` file? A: The pid lock stores the supervisor pid, not the transient worker/listener pid. Worker/listener pids are resolved at runtime via snapshots.
-- Q: Where should logs be inspected first? A: Start with `pnpm dev logs <service>` for the active session. If that is not enough, inspect the backing file under `.tmp/dev/logs/<run_id>/...` or `.tmp/logs/desktop-dev.log` for desktop.
+- Q: Where should logs be inspected first? A: Start with `pnpm dev logs <service>` for the active session. If that is not enough, inspect the backing file under `.tmp/dev/logs/<run_id>/...`.
 - Q: How do I correlate a leaked or suspicious process to a specific dev run? A: Start with `sessionId` from `pnpm dev status <service>` or `.tmp/dev/*.pid`, then search process command lines for `--nexu-dev-session=<sessionId>` and `--nexu-dev-service=<service>`.
-- Q: What is the expected worst-case recovery path? A: Kill the known listener/supervisor pid for the affected service, remove the stale `.tmp/dev/*.pid` file, rerun `pnpm dev start <service>`, and if the local environment is still inconsistent, reboot the machine to clear any orphaned OS-level process state.
+- Q: `pnpm install` warns that `electron-winstaller` build scripts were ignored. A: Keep it out of the shared repo allowlist unless Windows packaging support is intentionally being enabled for the whole team. Use per-machine approval when only one Windows environment needs it.
+- Q: What is the expected worst-case recovery path? A: Run `pnpm dev stop`, kill any leftover listener/supervisor pid for the affected service, remove stale `.tmp/dev/*.pid` files, then run `pnpm dev start` again.

scripts/dev/src/index.ts

@@ -52,6 +52,25 @@ function readTargetOrThrow(target: string | undefined): DevTarget {
   return target as DevTarget;
 }
 
+async function startDefaultStack(): Promise<void> {
+  await startTarget("openclaw", createDevSessionId());
+  await startTarget("controller", createDevSessionId());
+  await startTarget("web", createDevSessionId());
+  await startTarget("desktop", createDevSessionId());
+}
+
+async function stopDefaultStack(): Promise<void> {
+  await stopTarget("desktop");
+  await stopTarget("web");
+  await stopTarget("controller");
+  await stopTarget("openclaw");
+}
+
+async function restartDefaultStack(): Promise<void> {
+  await stopDefaultStack();
+  await startDefaultStack();
+}
+
 async function startTarget(
   target: DevTarget,
   sessionId: string,
@@ -307,6 +326,11 @@ function printLogHeader(logFilePath: string, totalLineCount: number): void {
 cli
   .command("start [target]", "Start one local dev service")
   .action(async (target?: string) => {
+    if (!target) {
+      await startDefaultStack();
+      return;
+    }
+
     const resolvedTarget = readTargetOrThrow(target);
     const sessionId = createDevSessionId();
     await startTarget(resolvedTarget, sessionId);
@@ -315,6 +339,11 @@ cli
 cli
   .command("restart [target]", "Restart one local dev service")
   .action(async (target?: string) => {
+    if (!target) {
+      await restartDefaultStack();
+      return;
+    }
+
     const resolvedTarget = readTargetOrThrow(target);
     const sessionId = createDevSessionId();
     await restartTarget(resolvedTarget, sessionId);
@@ -323,6 +352,11 @@ cli
 cli
   .command("stop [target]", "Stop one local dev service")
   .action(async (target?: string) => {
+    if (!target) {
+      await stopDefaultStack();
+      return;
+    }
+
     const resolvedTarget = readTargetOrThrow(target);
     await stopTarget(resolvedTarget);
   });

scripts/dev/src/services/controller.ts

@@ -25,6 +25,7 @@ import {
   getControllerDevLogPath,
 } from "../shared/paths.js";
 import { createDevMarkerArgs } from "../shared/trace.js";
+import { getCurrentOpenclawDevSnapshot } from "./openclaw.js";
 
 export type ControllerDevSnapshot = {
   service: "controller";
@@ -74,9 +75,22 @@ async function waitForControllerPortPid(): Promise<number> {
   );
 }
 
+async function ensureOpenclawReadyForController(): Promise<void> {
+  const openclawSnapshot = await getCurrentOpenclawDevSnapshot();
+
+  ensure(openclawSnapshot.status === "running").orThrow(
+    () =>
+      new Error(
+        "openclaw is not running; start it with `pnpm dev start openclaw` before starting controller",
+      ),
+  );
+}
+
 export async function startControllerDevProcess(options: {
   sessionId: string;
 }): Promise<ControllerDevSnapshot> {
+  await ensureOpenclawReadyForController();
+
   const existingSnapshot = await getCurrentControllerDevSnapshot();
 
   ensure(existingSnapshot.status !== "running").orThrow(
@@ -144,12 +158,13 @@ export async function startControllerDevProcess(options: {
 export async function stopControllerDevProcess(): Promise<ControllerDevSnapshot> {
   const snapshot = await getCurrentControllerDevSnapshot();
 
-  ensure(snapshot.status === "running" && Boolean(snapshot.pid)).orThrow(
+  ensure(snapshot.status !== "stopped").orThrow(
     () => new Error("controller dev process is not running"),
   );
-  const supervisorPid = snapshot.pid as number;
 
-  await terminateProcess(supervisorPid);
+  if (snapshot.status === "running" && snapshot.pid) {
+    await terminateProcess(snapshot.pid);
+  }
 
   try {
     const workerPid = await getControllerPortPid();