@silicaclaw/cli 2026.3.19-9 → 2026.3.20-10

package/scripts/silicaclaw-gateway.mjs

@@ -1,14 +1,20 @@
 #!/usr/bin/env node
 
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import defaults from "../config/silicaclaw-defaults.json" with { type: "json" };
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const ROOT_DIR = resolve(__dirname, "..");
+const LOCAL_CONSOLE_PORT = defaults.ports.local_console;
+const DEFAULT_NETWORK_MODE = defaults.network.default_mode;
+const DEFAULT_SIGNALING_URL = defaults.network.global_preview.relay_url;
+const DEFAULT_ROOM = defaults.network.global_preview.room;
+const LOCAL_CONSOLE_BASE_URL = defaults.bridge.api_base;
 
 const argv = process.argv.slice(2);
 const cmd = String(argv[0] || "help").toLowerCase();
@@ -48,7 +54,7 @@ function headline() {
       version = "unknown";
     }
   }
-  console.log(`${paint("SilicaClaw", COLOR.bold, COLOR.orange)} ${paint(displayVersion(version), COLOR.dim)}`);
+  console.log(`${paint("🦀 SilicaClaw", COLOR.bold, COLOR.orange)} ${paint(displayVersion(version), COLOR.dim)}`);
   console.log(paint("Public identity and discovery for OpenClaw agents.", COLOR.dim));
 }
 
@@ -68,6 +74,11 @@ function readJson(file) {
   }
 }
 
+function readPackageVersionFrom(dir) {
+  const pkg = readJson(resolve(dir, "package.json"));
+  return String(pkg?.version || "latest").trim() || "latest";
+}
+
 function isSilicaClawDir(dir) {
   const pkgPath = join(dir, "package.json");
   if (!existsSync(pkgPath)) return false;
@@ -114,9 +125,17 @@ function detectAppDir() {
   return ROOT_DIR;
 }
 
+function detectWorkspaceDir() {
+  const envDir = process.env.SILICACLAW_WORKSPACE_DIR;
+  if (envDir) return resolve(envDir);
+  return resolve(process.cwd());
+}
+
 const APP_DIR = detectAppDir();
+const WORKSPACE_DIR = detectWorkspaceDir();
 const LOCAL_CONSOLE_DIR = join(APP_DIR, "apps", "local-console");
-const STATE_DIR = join(APP_DIR, ".silicaclaw", "gateway");
+const STATE_DIR = join(homedir(), ".silicaclaw", "gateway");
+const MANAGED_RUNTIME_DIR = join(homedir(), ".silicaclaw", "runtime", "silicaclaw");
 const CONSOLE_PID_FILE = join(STATE_DIR, "local-console.pid");
 const CONSOLE_LOG_FILE = join(STATE_DIR, "local-console.log");
 const SIGNALING_PID_FILE = join(STATE_DIR, "signaling.pid");
@@ -130,10 +149,115 @@ function ensureStateDir() {
   mkdirSync(STATE_DIR, { recursive: true });
 }
 
+function userShimDir() {
+  return join(homedir(), ".silicaclaw", "bin");
+}
+
+function userShimPath() {
+  return join(userShimDir(), "silicaclaw");
+}
+
+function userEnvFile() {
+  return join(homedir(), ".silicaclaw", "env.sh");
+}
+
+function userNpmCacheDir() {
+  return join(homedir(), ".silicaclaw", "npm-cache");
+}
+
+function preferredShellRcFile() {
+  const shell = String(process.env.SHELL || "");
+  if (shell.endsWith("/zsh")) return resolve(homedir(), ".zshrc");
+  if (shell.endsWith("/bash")) return resolve(homedir(), ".bashrc");
+  if (process.env.ZSH_VERSION) return resolve(homedir(), ".zshrc");
+  return resolve(homedir(), ".bashrc");
+}
+
+function shellInitTargets() {
+  const home = homedir();
+  const shell = String(process.env.SHELL || "");
+  const targets = [];
+  const add = (filePath) => {
+    if (!targets.includes(filePath)) targets.push(filePath);
+  };
+
+  if (shell.endsWith("/zsh") || process.env.ZSH_VERSION || existsSync(resolve(home, ".zshrc"))) {
+    add(resolve(home, ".zshrc"));
+  }
+
+  if (
+    shell.endsWith("/bash") ||
+    process.env.BASH_VERSION ||
+    existsSync(resolve(home, ".bashrc")) ||
+    existsSync(resolve(home, ".bash_profile")) ||
+    existsSync(resolve(home, ".profile"))
+  ) {
+    add(resolve(home, ".bashrc"));
+    add(resolve(home, ".bash_profile"));
+    add(resolve(home, ".profile"));
+  }
+
+  if (targets.length === 0) {
+    add(preferredShellRcFile());
+  }
+  return targets;
+}
+
+function ensureLineInFile(filePath, block) {
+  try {
+    const current = existsSync(filePath) ? readFileSync(filePath, "utf8") : "";
+    if (current.includes(block.trim())) return true;
+    const next = `${current.replace(/\s*$/, "")}\n\n${block}\n`;
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, next, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function shimScriptText(specifier = "latest") {
+  return [
+    "#!/usr/bin/env bash",
+    "set -euo pipefail",
+    'export npm_config_cache="${npm_config_cache:-$HOME/.silicaclaw/npm-cache}"',
+    `exec npx -y @silicaclaw/cli@${specifier} "$@"`,
+    "",
+  ].join("\n");
+}
+
+function ensureUserCommandInstalled() {
+  const version = readPackageVersionFrom(APP_DIR);
+  const envBlock = [
+    "#!/usr/bin/env bash",
+    'export PATH="$HOME/.silicaclaw/bin:$PATH"',
+    'export npm_config_cache="$HOME/.silicaclaw/npm-cache"',
+    "",
+  ].join("\n");
+  const rcBlock = [
+    "# >>> silicaclaw >>>",
+    '[ -f "$HOME/.silicaclaw/env.sh" ] && . "$HOME/.silicaclaw/env.sh"',
+    "# <<< silicaclaw <<<",
+  ].join("\n");
+
+  mkdirSync(userShimDir(), { recursive: true });
+  mkdirSync(userNpmCacheDir(), { recursive: true });
+  writeFileSync(userEnvFile(), envBlock, { encoding: "utf8", mode: 0o755 });
+  writeFileSync(userShimPath(), shimScriptText(version), { encoding: "utf8", mode: 0o755 });
+
+  for (const filePath of shellInitTargets()) {
+    ensureLineInFile(filePath, rcBlock);
+  }
+}
+
 function ensureLaunchAgentsDir() {
   mkdirSync(LAUNCH_AGENTS_DIR, { recursive: true });
 }
 
+function ensureManagedRuntimeDir() {
+  mkdirSync(MANAGED_RUNTIME_DIR, { recursive: true });
+}
+
 function readPid(file) {
   if (!existsSync(file)) return null;
   const text = String(readFileSync(file, "utf8")).trim();
@@ -155,6 +279,51 @@ function removeFileIfExists(path) {
   if (existsSync(path)) rmSync(path, { force: true });
 }
 
+function syncManagedRuntime() {
+  if (resolve(APP_DIR) === resolve(MANAGED_RUNTIME_DIR)) return MANAGED_RUNTIME_DIR;
+
+  ensureManagedRuntimeDir();
+  const entries = [
+    "config",
+    "scripts",
+    "apps/local-console/dist",
+    "apps/local-console/package.json",
+    "apps/local-console/public",
+    "apps/public-explorer/dist",
+    "apps/public-explorer/package.json",
+    "apps/public-explorer/public",
+    "social.md",
+    ".openclaw",
+    "package.json",
+    "package-lock.json",
+    "VERSION",
+    "node_modules",
+  ];
+
+  for (const rel of entries) {
+    const src = resolve(APP_DIR, rel);
+    if (!existsSync(src)) continue;
+    const dst = resolve(MANAGED_RUNTIME_DIR, rel);
+    rmSync(dst, { recursive: true, force: true });
+    cpSync(src, dst, {
+      recursive: true,
+      force: true,
+      dereference: rel === "node_modules",
+    });
+  }
+
+  const manifest = {
+    source_app_dir: APP_DIR,
+    synced_at: Date.now(),
+    version: readJson(resolve(APP_DIR, "package.json"))?.version || null,
+    dist_server_mtime: existsSync(resolve(APP_DIR, "apps", "local-console", "dist", "apps", "local-console", "src", "server.js"))
+      ? statSync(resolve(APP_DIR, "apps", "local-console", "dist", "apps", "local-console", "src", "server.js")).mtimeMs
+      : null,
+  };
+  writeFileSync(resolve(MANAGED_RUNTIME_DIR, ".silicaclaw-runtime.json"), JSON.stringify(manifest, null, 2));
+  return MANAGED_RUNTIME_DIR;
+}
+
 async function stopPid(pid, name) {
   if (!pid || !isRunning(pid)) return;
   try {
@@ -243,25 +412,34 @@ function runLaunchctl(args) {
   });
 }
 
-function resolveCommandPath(command) {
-  const result = spawnSync("which", [command], {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "ignore"],
-  });
-  if ((result.status ?? 1) === 0) {
-    const value = String(result.stdout || "").trim();
-    if (value) return value;
-  }
-  return command;
+function launchServiceTarget(label) {
+  return `${launchdDomain()}/${label}`;
+}
+
+function isLaunchctlNotLoadedResult(result) {
+  const text = `${result?.stdout || ""}\n${result?.stderr || ""}`.toLowerCase();
+  return (
+    text.includes("could not find service") ||
+    text.includes("service not found") ||
+    text.includes("bad request") ||
+    text.includes("not loaded")
+  );
+}
+
+function localConsoleProgramArguments(appDir = APP_DIR) {
+  return [
+    process.execPath,
+    resolve(appDir, "apps", "local-console", "dist", "apps", "local-console", "src", "server.js"),
+  ];
 }
 
 function isLaunchAgentLoaded(label) {
-  const result = runLaunchctl(["print", `${launchdDomain()}/${label}`]);
+  const result = runLaunchctl(["print", launchServiceTarget(label)]);
   return (result.status ?? 1) === 0;
 }
 
 function readLaunchAgentRuntime(label) {
-  const result = runLaunchctl(["print", `${launchdDomain()}/${label}`]);
+  const result = runLaunchctl(["print", launchServiceTarget(label)]);
   if ((result.status ?? 1) !== 0) return { loaded: false, pid: null };
   const text = `${result.stdout || ""}\n${result.stderr || ""}`;
   const pidMatch = text.match(/pid = (\d+)/);
@@ -271,7 +449,47 @@ function readLaunchAgentRuntime(label) {
   };
 }
 
-function installLaunchAgent({ label, programArguments, workingDirectory, logFile, environment }) {
+function writeLaunchAgentPlistIfChanged(plistPath, plist) {
+  const current = existsSync(plistPath) ? String(readFileSync(plistPath, "utf8")) : null;
+  if (current === plist) return false;
+  writeFileSync(plistPath, plist, "utf8");
+  return true;
+}
+
+function bootstrapLaunchAgent(label, plistPath) {
+  const result = runLaunchctl(["bootstrap", launchdDomain(), plistPath]);
+  if ((result.status ?? 1) !== 0) {
+    const detail = String(result.stderr || result.stdout || "launchctl bootstrap failed").trim();
+    throw new Error(detail);
+  }
+}
+
+function startLaunchAgent(label, plistPath) {
+  const result = runLaunchctl(["start", launchServiceTarget(label)]);
+  if ((result.status ?? 1) === 0) return;
+  if (!isLaunchctlNotLoadedResult(result)) {
+    const detail = String(result.stderr || result.stdout || "launchctl start failed").trim();
+    throw new Error(detail);
+  }
+  bootstrapLaunchAgent(label, plistPath);
+}
+
+function restartLaunchAgent(label, plistPath) {
+  const result = runLaunchctl(["kickstart", "-k", launchServiceTarget(label)]);
+  if ((result.status ?? 1) === 0) return;
+  if (!isLaunchctlNotLoadedResult(result)) {
+    const detail = String(result.stderr || result.stdout || "launchctl kickstart failed").trim();
+    throw new Error(detail);
+  }
+  bootstrapLaunchAgent(label, plistPath);
+  const retry = runLaunchctl(["kickstart", "-k", launchServiceTarget(label)]);
+  if ((retry.status ?? 1) !== 0) {
+    const detail = String(retry.stderr || retry.stdout || "launchctl kickstart failed").trim();
+    throw new Error(detail);
+  }
+}
+
+function ensureLaunchAgent({ label, programArguments, workingDirectory, logFile, environment }) {
   ensureLaunchAgentsDir();
   ensureStateDir();
   const plistPath = launchAgentPlistPath(label);
@@ -283,17 +501,23 @@ function installLaunchAgent({ label, programArguments, workingDirectory, logFile
     stderrPath: logFile,
     environment,
   });
-  writeFileSync(plistPath, plist, "utf8");
-
-  if (isLaunchAgentLoaded(label)) {
-    runLaunchctl(["bootout", launchdDomain(), plistPath]);
+  const changed = writeLaunchAgentPlistIfChanged(plistPath, plist);
+  const loaded = isLaunchAgentLoaded(label);
+
+  if (changed && loaded) {
+    const bootout = runLaunchctl(["bootout", launchdDomain(), plistPath]);
+    if ((bootout.status ?? 1) !== 0 && !isLaunchctlNotLoadedResult(bootout)) {
+      const detail = String(bootout.stderr || bootout.stdout || "launchctl bootout failed").trim();
+      throw new Error(detail);
+    }
+    bootstrapLaunchAgent(label, plistPath);
+    return { changed: true, loaded: true, plistPath };
   }
 
-  const result = runLaunchctl(["bootstrap", launchdDomain(), plistPath]);
-  if ((result.status ?? 1) !== 0) {
-    const detail = String(result.stderr || result.stdout || "launchctl bootstrap failed").trim();
-    throw new Error(detail);
+  if (!loaded) {
+    bootstrapLaunchAgent(label, plistPath);
   }
+  return { changed, loaded, plistPath };
 }
 
 function stopLaunchAgent(label) {
@@ -357,10 +581,11 @@ function launchdStatusPayload() {
   const state = readState();
   const localRuntime = readLaunchAgentRuntime(LOCAL_CONSOLE_LABEL);
   const signalingRuntime = readLaunchAgentRuntime(SIGNALING_LABEL);
-  const localListener = listeningProcessOnPort(4310);
+  const localListener = listeningProcessOnPort(LOCAL_CONSOLE_PORT);
   const signalingListener = listeningProcessOnPort(4510);
   return {
     app_dir: APP_DIR,
+    workspace_dir: WORKSPACE_DIR,
     mode: state?.mode || "unknown",
     adapter: state?.adapter || "unknown",
     service_manager: "launchd",
@@ -391,10 +616,12 @@ function buildStatusPayload() {
   const localPid = readPid(CONSOLE_PID_FILE);
   const sigPid = readPid(SIGNALING_PID_FILE);
   const state = readState();
-  const localListener = listeningProcessOnPort(4310);
+  const localListener = listeningProcessOnPort(LOCAL_CONSOLE_PORT);
   const signalingListener = listeningProcessOnPort(4510);
   return {
     app_dir: APP_DIR,
+    managed_app_dir: state?.managed_app_dir || null,
+    workspace_dir: state?.workspace_dir || WORKSPACE_DIR,
     mode: state?.mode || "unknown",
     adapter: state?.adapter || "unknown",
     local_console: {
@@ -428,10 +655,10 @@ function showStatusHuman() {
       : `${paint("stopped", COLOR.dim)} · ${payload.mode}`
   );
   if (payload.mode === "global-preview") {
-    kv("Relay", payload.signaling.url || "https://relay.silicaclaw.com");
-    kv("Room", payload.signaling.room || "silicaclaw-global-preview");
+    kv("Relay", payload.signaling.url || DEFAULT_SIGNALING_URL);
+    kv("Room", payload.signaling.room || DEFAULT_ROOM);
   }
-  if (payload.local_console.running) kv("Open", "http://localhost:4310");
+  if (payload.local_console.running) kv("Open", LOCAL_CONSOLE_BASE_URL);
   return payload;
 }
 
@@ -440,10 +667,10 @@ function printConnectionSummary(status, verb = "Started") {
   headline();
   console.log("");
   kv("Status", `${verb.toLowerCase()} · ${status.mode}`);
-  kv("Console", `http://localhost:4310`);
+  kv("Console", LOCAL_CONSOLE_BASE_URL);
   if (status.mode === "global-preview") {
-    const signalingUrl = status?.signaling?.url || "https://relay.silicaclaw.com";
-    const room = status?.signaling?.room || "silicaclaw-global-preview";
+    const signalingUrl = status?.signaling?.url || DEFAULT_SIGNALING_URL;
+    const room = status?.signaling?.room || DEFAULT_ROOM;
     kv("Relay", signalingUrl);
     kv("Room", room);
   }
@@ -476,6 +703,22 @@ function normalizePathForMatch(value) {
   return String(value || "").replace(/\\/g, "/");
 }
 
+function isLocalConsoleCommand(command) {
+  const text = normalizePathForMatch(command).toLowerCase();
+  return (
+    text.includes("@silicaclaw/local-console") ||
+    text.includes("npm run --workspace @silicaclaw/local-console start") ||
+    text.includes("/apps/local-console/") ||
+    text.includes("dist/apps/local-console/src/server.js") ||
+    text.includes("src/server.ts")
+  );
+}
+
+function isSignalingCommand(command) {
+  const text = normalizePathForMatch(command).toLowerCase();
+  return text.includes("webrtc-signaling-server.mjs") || text.includes("npm run webrtc-signaling");
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -502,6 +745,20 @@ async function waitForCurrentAppListener(port, kind, timeoutMs = 5000) {
   return lastListener;
 }
 
+async function waitForLocalConsoleHealth(timeoutMs = 8000) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    try {
+      const response = await fetch(`${LOCAL_CONSOLE_BASE_URL}/api/health`);
+      if (response.ok) return true;
+    } catch {
+      // ignore transient startup failures
+    }
+    await sleep(250);
+  }
+  return false;
+}
+
 async function waitForPortToClear(port, timeoutMs = 5000) {
   const startedAt = Date.now();
   while (Date.now() - startedAt < timeoutMs) {
@@ -520,40 +777,24 @@ function tailText(file, lines = 20) {
 
 function isOwnedListener(listener, kind) {
   if (!listener?.command) return false;
-  const command = normalizePathForMatch(listener.command).toLowerCase();
-  const appDir = normalizePathForMatch(APP_DIR).toLowerCase();
-  const rootDir = normalizePathForMatch(ROOT_DIR).toLowerCase();
-  const inWorkspace = command.includes(appDir) || command.includes(rootDir);
-  if (!inWorkspace) return false;
+  const command = listener.command;
   if (kind === "local-console") {
-    return (
-      command.includes("@silicaclaw/local-console") ||
-      command.includes("/apps/local-console/") ||
-      command.includes("src/server.ts") ||
-      command.includes("dist/server.js")
-    );
+    return isLocalConsoleCommand(command);
   }
   if (kind === "signaling") {
-    return command.includes("webrtc-signaling-server.mjs") || command.includes("npm run webrtc-signaling");
+    return isSignalingCommand(command);
   }
   return false;
 }
 
 function isCurrentAppListener(listener, kind) {
   if (!listener?.command) return false;
-  const command = normalizePathForMatch(listener.command).toLowerCase();
-  const appDir = normalizePathForMatch(APP_DIR).toLowerCase();
-  if (!command.includes(appDir)) return false;
+  const command = listener.command;
   if (kind === "local-console") {
-    return (
-      command.includes("@silicaclaw/local-console") ||
-      command.includes("/apps/local-console/") ||
-      command.includes("src/server.ts") ||
-      command.includes("dist/server.js")
-    );
+    return isLocalConsoleCommand(command);
   }
   if (kind === "signaling") {
-    return command.includes("webrtc-signaling-server.mjs") || command.includes("npm run webrtc-signaling");
+    return isSignalingCommand(command);
   }
   return false;
 }
@@ -592,7 +833,7 @@ async function drainOwnedListener(port, kind, timeoutMs = 5000) {
 }
 
 function printStopSummary() {
-  const localListener = listeningProcessOnPort(4310);
+  const localListener = listeningProcessOnPort(LOCAL_CONSOLE_PORT);
   const signalingListener = listeningProcessOnPort(4510);
   headline();
   console.log("");
@@ -602,9 +843,9 @@ function printStopSummary() {
   } else {
     kv("Console", `${paint("still busy", COLOR.yellow)} (pid=${localListener.pid})`);
     if (isOwnedListener(localListener, "local-console")) {
-      kv("Hint", "an older SilicaClaw local-console process is still holding port 4310");
+      kv("Hint", `an older SilicaClaw local-console process is still holding port ${LOCAL_CONSOLE_PORT}`);
     }
-    kv("Inspect", "lsof -nP -iTCP:4310 -sTCP:LISTEN");
+    kv("Inspect", `lsof -nP -iTCP:${LOCAL_CONSOLE_PORT} -sTCP:LISTEN`);
     kv("Stop pid", `kill ${localListener.pid}`);
   }
   if (!signalingListener) {
@@ -636,7 +877,7 @@ async function stopAll() {
   if (isLaunchdPlatform()) {
     stopLaunchAgent(LOCAL_CONSOLE_LABEL);
     stopLaunchAgent(SIGNALING_LABEL);
-    await drainOwnedListener(4310, "local-console", 8000);
+    await drainOwnedListener(LOCAL_CONSOLE_PORT, "local-console", 8000);
     await drainOwnedListener(4510, "signaling", 5000);
     removeFileIfExists(CONSOLE_PID_FILE);
     removeFileIfExists(SIGNALING_PID_FILE);
@@ -650,7 +891,7 @@ async function stopAll() {
   const sigPid = readPid(SIGNALING_PID_FILE);
   await stopPid(localPid, "local-console");
   await stopPid(sigPid, "signaling");
-  await drainOwnedListener(4310, "local-console", 5000);
+  await drainOwnedListener(LOCAL_CONSOLE_PORT, "local-console", 5000);
   await drainOwnedListener(4510, "signaling", 5000);
   removeFileIfExists(CONSOLE_PID_FILE);
   removeFileIfExists(SIGNALING_PID_FILE);
@@ -662,11 +903,12 @@ async function stopAll() {
 
 async function startAll() {
   ensureStateDir();
+  ensureUserCommandInstalled();
 
-  const mode = parseMode(parseFlag("mode", process.env.NETWORK_MODE || "global-preview"));
+  const mode = parseMode(parseFlag("mode", process.env.NETWORK_MODE || DEFAULT_NETWORK_MODE));
   const adapter = adapterForMode(mode);
-  const signalingUrl = parseFlag("signaling-url", process.env.WEBRTC_SIGNALING_URL || "https://relay.silicaclaw.com");
-  const room = parseFlag("room", process.env.WEBRTC_ROOM || "silicaclaw-global-preview");
+  const signalingUrl = parseFlag("signaling-url", process.env.WEBRTC_SIGNALING_URL || DEFAULT_SIGNALING_URL);
+  const room = parseFlag("room", process.env.WEBRTC_ROOM || DEFAULT_ROOM);
   const shouldDisableSignaling = hasFlag("no-signaling");
 
   const { host, port } = parseUrlHostPort(signalingUrl);
@@ -676,32 +918,34 @@ async function startAll() {
     (host === "localhost" || host === "127.0.0.1");
 
   if (isLaunchdPlatform()) {
-    const npmPath = resolveCommandPath("npm");
-    const signalingEntry = resolve(APP_DIR, "scripts", "webrtc-signaling-server.mjs");
-    await drainOwnedListener(4310, "local-console", 8000);
+    const managedAppDir = syncManagedRuntime();
+    const signalingEntry = resolve(managedAppDir, "scripts", "webrtc-signaling-server.mjs");
+    await drainOwnedListener(LOCAL_CONSOLE_PORT, "local-console", 8000);
     await drainOwnedListener(4510, "signaling", 5000);
     const baseEnv = {
       NETWORK_ADAPTER: adapter,
       NETWORK_MODE: mode,
       WEBRTC_SIGNALING_URL: signalingUrl,
       WEBRTC_ROOM: room,
+      SILICACLAW_APP_DIR: managedAppDir,
+      SILICACLAW_WORKSPACE_DIR: WORKSPACE_DIR,
       PATH: process.env.PATH || "/usr/bin:/bin:/usr/sbin:/sbin",
       HOME: process.env.HOME || homedir(),
     };
 
-    installLaunchAgent({
+    ensureLaunchAgent({
       label: LOCAL_CONSOLE_LABEL,
-      programArguments: [npmPath, "run", "--workspace", "@silicaclaw/local-console", "start"],
-      workingDirectory: APP_DIR,
+      programArguments: localConsoleProgramArguments(managedAppDir),
+      workingDirectory: managedAppDir,
       logFile: CONSOLE_LOG_FILE,
       environment: baseEnv,
     });
 
     if (shouldAutoStartSignaling) {
-      installLaunchAgent({
+      ensureLaunchAgent({
         label: SIGNALING_LABEL,
         programArguments: [process.execPath, signalingEntry],
-        workingDirectory: APP_DIR,
+        workingDirectory: managedAppDir,
         logFile: SIGNALING_LOG_FILE,
         environment: {
           PATH: baseEnv.PATH,
@@ -715,6 +959,8 @@ async function startAll() {
 
     writeState({
       app_dir: APP_DIR,
+      managed_app_dir: managedAppDir,
+      workspace_dir: WORKSPACE_DIR,
       mode,
       adapter,
       signaling_url: signalingUrl,
@@ -726,7 +972,7 @@ async function startAll() {
 
   const currentLocalPid = readPid(CONSOLE_PID_FILE);
   const currentSigPid = readPid(SIGNALING_PID_FILE);
-  const currentListener = listeningProcessOnPort(4310);
+  const currentListener = listeningProcessOnPort(LOCAL_CONSOLE_PORT);
   if (currentListener && isOwnedListener(currentListener, "local-console") && !isRunning(currentLocalPid)) {
     writeFileSync(CONSOLE_PID_FILE, String(currentListener.pid));
   }
@@ -734,16 +980,18 @@ async function startAll() {
   let localPid = readPid(CONSOLE_PID_FILE);
   if (!isRunning(localPid)) {
     removeFileIfExists(CONSOLE_PID_FILE);
-    await drainOwnedListener(4310, "local-console", 8000);
-    const remainingLocalListener = listeningProcessOnPort(4310);
+    await drainOwnedListener(LOCAL_CONSOLE_PORT, "local-console", 8000);
+    const remainingLocalListener = listeningProcessOnPort(LOCAL_CONSOLE_PORT);
     if (remainingLocalListener) {
-      throw new Error(`port 4310 is occupied by pid=${remainingLocalListener.pid}`);
+      throw new Error(`port ${LOCAL_CONSOLE_PORT} is occupied by pid=${remainingLocalListener.pid}`);
     }
     const env = {
       NETWORK_ADAPTER: adapter,
       NETWORK_MODE: mode,
       WEBRTC_SIGNALING_URL: signalingUrl,
       WEBRTC_ROOM: room,
+      SILICACLAW_APP_DIR: APP_DIR,
+      SILICACLAW_WORKSPACE_DIR: WORKSPACE_DIR,
     };
     localPid = spawnBackground(
       process.execPath,
@@ -771,6 +1019,7 @@ async function startAll() {
 
   writeState({
     app_dir: APP_DIR,
+    workspace_dir: WORKSPACE_DIR,
     mode,
     adapter,
     signaling_url: signalingUrl,
@@ -780,6 +1029,82 @@ async function startAll() {
   return { localPid, signalingPid: shouldAutoStartSignaling ? signalingPid : null };
 }
 
+async function restartAll() {
+  ensureUserCommandInstalled();
+  if (!isLaunchdPlatform()) {
+    await stopAll();
+    await startAll();
+    return;
+  }
+
+  ensureStateDir();
+
+  const mode = parseMode(parseFlag("mode", process.env.NETWORK_MODE || DEFAULT_NETWORK_MODE));
+  const adapter = adapterForMode(mode);
+  const signalingUrl = parseFlag("signaling-url", process.env.WEBRTC_SIGNALING_URL || DEFAULT_SIGNALING_URL);
+  const room = parseFlag("room", process.env.WEBRTC_ROOM || DEFAULT_ROOM);
+  const shouldDisableSignaling = hasFlag("no-signaling");
+  const { host, port } = parseUrlHostPort(signalingUrl);
+  const shouldAutoStartSignaling =
+    mode === "global-preview" &&
+    !shouldDisableSignaling &&
+    (host === "localhost" || host === "127.0.0.1");
+
+  const managedAppDir = syncManagedRuntime();
+  const signalingEntry = resolve(managedAppDir, "scripts", "webrtc-signaling-server.mjs");
+  const baseEnv = {
+    NETWORK_ADAPTER: adapter,
+    NETWORK_MODE: mode,
+    WEBRTC_SIGNALING_URL: signalingUrl,
+    WEBRTC_ROOM: room,
+    SILICACLAW_APP_DIR: managedAppDir,
+    SILICACLAW_WORKSPACE_DIR: WORKSPACE_DIR,
+    PATH: process.env.PATH || "/usr/bin:/bin:/usr/sbin:/sbin",
+    HOME: process.env.HOME || homedir(),
+  };
+
+  const localConsoleService = ensureLaunchAgent({
+    label: LOCAL_CONSOLE_LABEL,
+    programArguments: localConsoleProgramArguments(managedAppDir),
+    workingDirectory: managedAppDir,
+    logFile: CONSOLE_LOG_FILE,
+    environment: baseEnv,
+  });
+  if (!localConsoleService.changed) {
+    restartLaunchAgent(LOCAL_CONSOLE_LABEL, localConsoleService.plistPath);
+  }
+
+  if (shouldAutoStartSignaling) {
+    const signalingService = ensureLaunchAgent({
+      label: SIGNALING_LABEL,
+      programArguments: [process.execPath, signalingEntry],
+      workingDirectory: managedAppDir,
+      logFile: SIGNALING_LOG_FILE,
+      environment: {
+        PATH: baseEnv.PATH,
+        HOME: baseEnv.HOME,
+        PORT: String(port),
+      },
+    });
+    if (!signalingService.changed) {
+      restartLaunchAgent(SIGNALING_LABEL, signalingService.plistPath);
+    }
+  } else {
+    uninstallLaunchAgent(SIGNALING_LABEL);
+  }
+
+  writeState({
+    app_dir: APP_DIR,
+    managed_app_dir: managedAppDir,
+    workspace_dir: WORKSPACE_DIR,
+    mode,
+    adapter,
+    signaling_url: signalingUrl,
+    room,
+    updated_at: Date.now(),
+  });
+}
+
 async function main() {
   if (cmd === "help" || cmd === "-h" || cmd === "--help") {
     printHelp();
@@ -795,14 +1120,15 @@ async function main() {
   }
   if (cmd === "start") {
     await startAll();
-    const listener = await waitForCurrentAppListener(4310, "local-console", 15000);
-    if (!listener || !isCurrentAppListener(listener, "local-console")) {
+    const listener = await waitForCurrentAppListener(LOCAL_CONSOLE_PORT, "local-console", 15000);
+    const healthy = listener ? await waitForLocalConsoleHealth(8000) : false;
+    if (!listener || !isCurrentAppListener(listener, "local-console") || !healthy) {
       headline();
       console.log("");
       kv("Status", paint("failed to start", COLOR.red));
       if (listener) {
-        kv("Conflict", `port 4310 is occupied by pid=${listener.pid}`);
-        kv("Inspect", "lsof -nP -iTCP:4310 -sTCP:LISTEN");
+        kv("Conflict", `port ${LOCAL_CONSOLE_PORT} is occupied by pid=${listener.pid}`);
+        kv("Inspect", `lsof -nP -iTCP:${LOCAL_CONSOLE_PORT} -sTCP:LISTEN`);
       }
       const recent = tailText(CONSOLE_LOG_FILE, 18);
       if (recent) {
@@ -822,16 +1148,16 @@ async function main() {
     return;
   }
   if (cmd === "restart") {
-    await stopAll();
-    await startAll();
-    const listener = await waitForCurrentAppListener(4310, "local-console", 15000);
-    if (!listener || !isCurrentAppListener(listener, "local-console")) {
+    await restartAll();
+    const listener = await waitForCurrentAppListener(LOCAL_CONSOLE_PORT, "local-console", 15000);
+    const healthy = listener ? await waitForLocalConsoleHealth(8000) : false;
+    if (!listener || !isCurrentAppListener(listener, "local-console") || !healthy) {
       headline();
       console.log("");
       kv("Status", paint("failed to restart", COLOR.red));
       if (listener) {
-        kv("Conflict", `port 4310 is occupied by pid=${listener.pid}`);
-        kv("Inspect", "lsof -nP -iTCP:4310 -sTCP:LISTEN");
+        kv("Conflict", `port ${LOCAL_CONSOLE_PORT} is occupied by pid=${listener.pid}`);
+        kv("Inspect", `lsof -nP -iTCP:${LOCAL_CONSOLE_PORT} -sTCP:LISTEN`);
       }
       const recent = tailText(CONSOLE_LOG_FILE, 18);
       if (recent) {