denchclaw 2.0.0 → 2.0.1

package/dist/{register.bootstrap-D9YhQgaK.js → program-DhxRjAOe.js}

@@ -1,18 +1,517 @@
-import { f as applyCliProfileEnv, i as defaultRuntime, m as resolveRequiredHomeDir, t as isTruthyEnvValue } from "./entry.js";
-import { t as formatDocsLink } from "./links-BTx7dmFj.js";
-import { n as theme, t as isRich } from "./theme-uCBEEejb.js";
-import { spawn } from "node:child_process";
+import { c as hasFlag, d as applyCliProfileEnv, f as expandHomePrefix, i as defaultRuntime, p as resolveRequiredHomeDir, s as getPrimaryCommand, t as isTruthyEnvValue, u as hasRootVersionAlias } from "./entry.js";
+import { a as hasEmittedCliBanner, c as theme, i as formatCliBannerLine, n as resolveCliName, o as VERSION, s as isRich, t as replaceCliName } from "./cli-name-8WJ6gVD5.js";
+import { execFileSync, spawn } from "node:child_process";
 import process$1 from "node:process";
 import os from "node:os";
 import path from "node:path";
-import { copyFileSync, cpSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
+import fs, { copyFileSync, cpSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { Command } from "commander";
 import { confirm, isCancel, spinner } from "@clack/prompts";
+import { fileURLToPath } from "node:url";
 import { createConnection } from "node:net";
 
+//#region src/infra/ports-lsof.ts
+const LSOF_CANDIDATES = process.platform === "darwin" ? ["/usr/sbin/lsof", "/usr/bin/lsof"] : ["/usr/bin/lsof", "/usr/sbin/lsof"];
+function resolveLsofCommandSync() {
+	for (const candidate of LSOF_CANDIDATES) try {
+		fs.accessSync(candidate, fs.constants.X_OK);
+		return candidate;
+	} catch {}
+	return "lsof";
+}
+
+//#endregion
+//#region src/utils.ts
+/**
+* Escapes special regex characters in a string so it can be used in a RegExp constructor.
+*/
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function sleep$1(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function resolveUserPath(input) {
+	const trimmed = input.trim();
+	if (!trimmed) return trimmed;
+	if (trimmed.startsWith("~")) {
+		const expanded = expandHomePrefix(trimmed, {
+			home: resolveRequiredHomeDir(process.env, os.homedir),
+			env: process.env,
+			homedir: os.homedir
+		});
+		return path.resolve(expanded);
+	}
+	return path.resolve(trimmed);
+}
+function resolveConfigDir(env = process.env, homedir = os.homedir) {
+	const override = env.OPENCLAW_STATE_DIR?.trim() || env.CLAWDBOT_STATE_DIR?.trim();
+	if (override) return resolveUserPath(override);
+	const newDir = path.join(resolveRequiredHomeDir(env, homedir), ".openclaw");
+	try {
+		if (fs.existsSync(newDir)) return newDir;
+	} catch {}
+	return newDir;
+}
+function formatTerminalLink(label, url, opts) {
+	const esc = "\x1B";
+	const safeLabel = label.replaceAll(esc, "");
+	const safeUrl = url.replaceAll(esc, "");
+	if (!(opts?.force === true ? true : opts?.force === false ? false : Boolean(process.stdout.isTTY))) return opts?.fallback ?? `${safeLabel} (${safeUrl})`;
+	return `\u001b]8;;${safeUrl}\u0007${safeLabel}\u001b]8;;\u0007`;
+}
+const CONFIG_DIR = resolveConfigDir();
+
+//#endregion
+//#region src/cli/ports.ts
+function parseLsofOutput(output) {
+	const lines = output.split(/\r?\n/).filter(Boolean);
+	const results = [];
+	let current = {};
+	for (const line of lines) if (line.startsWith("p")) {
+		if (current.pid) results.push(current);
+		current = { pid: Number.parseInt(line.slice(1), 10) };
+	} else if (line.startsWith("c")) current.command = line.slice(1);
+	if (current.pid) results.push(current);
+	return results;
+}
+function listPortListeners(port) {
+	try {
+		return parseLsofOutput(execFileSync(resolveLsofCommandSync(), [
+			"-nP",
+			`-iTCP:${port}`,
+			"-sTCP:LISTEN",
+			"-FpFc"
+		], { encoding: "utf-8" }));
+	} catch (err) {
+		const status = err.status;
+		if (err.code === "ENOENT") throw new Error("lsof not found; required for --force", { cause: err });
+		if (status === 1) return [];
+		throw err instanceof Error ? err : new Error(String(err));
+	}
+}
+
+//#endregion
+//#region src/terminal/links.ts
+const DOCS_ROOT = "https://docs.openclaw.ai";
+function formatDocsLink(path, label, opts) {
+	const trimmed = path.trim();
+	const url = trimmed.startsWith("http") ? trimmed : `${DOCS_ROOT}${trimmed.startsWith("/") ? trimmed : `/${trimmed}`}`;
+	return formatTerminalLink(label ?? url, url, {
+		fallback: opts?.fallback ?? url,
+		force: opts?.force
+	});
+}
+
+//#endregion
 //#region src/terminal/prompt-style.ts
 const stylePromptMessage = (message) => isRich() ? theme.accent(message) : message;
 
+//#endregion
+//#region src/cli/web-runtime.ts
+const DEFAULT_WEB_APP_PORT = 3100;
+const WEB_RUNTIME_DIRNAME = "web-runtime";
+const WEB_RUNTIME_APP_DIRNAME = "app";
+const WEB_RUNTIME_MANIFEST_FILENAME = "manifest.json";
+const WEB_RUNTIME_PROCESS_FILENAME = "process.json";
+const WEB_APP_PROBE_ATTEMPTS = 20;
+const WEB_APP_PROBE_DELAY_MS = 750;
+const WEB_APP_PROBE_TIMEOUT_MS = 1500;
+const LEGACY_STANDALONE_SEGMENT = "/apps/web/.next/standalone/apps/web";
+function normalizePathForMatch(value) {
+	return value.replaceAll("\\", "/").toLowerCase();
+}
+function isPathWithin(parentDir, candidatePath) {
+	const relative = path.relative(path.resolve(parentDir), path.resolve(candidatePath));
+	return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function parseOptionalPositiveInt(value) {
+	if (value === void 0) return;
+	const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) return;
+	return parsed;
+}
+function ensureParentDir(filePath) {
+	mkdirSync(path.dirname(filePath), { recursive: true });
+}
+function readJsonFile(filePath) {
+	if (!existsSync(filePath)) return null;
+	try {
+		return JSON.parse(readFileSync(filePath, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+function writeJsonFile(filePath, value) {
+	ensureParentDir(filePath);
+	writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+}
+function isProcessAlive(pid) {
+	try {
+		process$1.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code !== "ESRCH";
+	}
+}
+async function terminatePidWithEscalation(pid) {
+	try {
+		process$1.kill(pid, "SIGTERM");
+	} catch (error) {
+		if (error.code === "ESRCH") return;
+		throw error;
+	}
+	for (let i = 0; i < 8; i += 1) {
+		if (!isProcessAlive(pid)) return;
+		await sleep$1(100);
+	}
+	if (!isProcessAlive(pid)) return;
+	try {
+		process$1.kill(pid, "SIGKILL");
+	} catch (error) {
+		if (error.code === "ESRCH") return;
+		throw error;
+	}
+	for (let i = 0; i < 8; i += 1) {
+		if (!isProcessAlive(pid)) return;
+		await sleep$1(100);
+	}
+}
+function resolveCliPackageRoot() {
+	let dir = path.dirname(fileURLToPath(import.meta.url));
+	for (let i = 0; i < 5; i += 1) {
+		if (existsSync(path.join(dir, "package.json"))) return dir;
+		dir = path.dirname(dir);
+	}
+	return process$1.cwd();
+}
+function resolveProfileStateDir(profile, env = process$1.env) {
+	const home = resolveRequiredHomeDir(env, os.homedir);
+	return path.join(home, ".openclaw-dench");
+}
+function resolveManagedWebRuntimeDir(stateDir) {
+	return path.join(stateDir, WEB_RUNTIME_DIRNAME);
+}
+function resolveManagedWebRuntimeAppDir(stateDir) {
+	return path.join(resolveManagedWebRuntimeDir(stateDir), WEB_RUNTIME_APP_DIRNAME);
+}
+function resolveManagedWebRuntimeServerPath(stateDir) {
+	return path.join(resolveManagedWebRuntimeAppDir(stateDir), "server.js");
+}
+function resolveManagedWebRuntimeManifestPath(stateDir) {
+	return path.join(resolveManagedWebRuntimeDir(stateDir), WEB_RUNTIME_MANIFEST_FILENAME);
+}
+function resolveManagedWebRuntimeProcessPath(stateDir) {
+	return path.join(resolveManagedWebRuntimeDir(stateDir), WEB_RUNTIME_PROCESS_FILENAME);
+}
+function resolvePackagedStandaloneServerPath(packageRoot) {
+	return path.join(packageRoot, "apps/web/.next/standalone/apps/web/server.js");
+}
+function resolvePackagedStandaloneAppDir(packageRoot) {
+	return path.dirname(resolvePackagedStandaloneServerPath(packageRoot));
+}
+function readManagedWebRuntimeManifest(stateDir) {
+	return readJsonFile(resolveManagedWebRuntimeManifestPath(stateDir));
+}
+function readManagedWebRuntimeProcess(stateDir) {
+	return readJsonFile(resolveManagedWebRuntimeProcessPath(stateDir));
+}
+function writeManagedWebRuntimeManifest(stateDir, manifest) {
+	writeJsonFile(resolveManagedWebRuntimeManifestPath(stateDir), manifest);
+	return manifest;
+}
+function writeManagedWebRuntimeProcess(stateDir, processMeta) {
+	writeJsonFile(resolveManagedWebRuntimeProcessPath(stateDir), processMeta);
+}
+function clearManagedWebRuntimeProcess(stateDir) {
+	rmSync(resolveManagedWebRuntimeProcessPath(stateDir), { force: true });
+}
+function updateManifestLastPort(stateDir, webPort, gatewayPort) {
+	const manifest = readManagedWebRuntimeManifest(stateDir);
+	if (!manifest) return null;
+	return writeManagedWebRuntimeManifest(stateDir, {
+		...manifest,
+		lastPort: webPort,
+		lastGatewayPort: gatewayPort
+	});
+}
+function evaluateWebProfilesPayload(payload) {
+	if (!payload || typeof payload !== "object") return {
+		ok: false,
+		reason: "response payload is not an object"
+	};
+	const data = payload;
+	if (!(Array.isArray(data.profiles) ? data.profiles : Array.isArray(data.workspaces) ? data.workspaces : void 0)) return {
+		ok: false,
+		reason: "response payload missing profiles/workspaces array"
+	};
+	if ((data.activeProfile === null || typeof data.activeProfile === "string" ? data.activeProfile : data.activeWorkspace === null || typeof data.activeWorkspace === "string" ? data.activeWorkspace : void 0) === void 0) return {
+		ok: false,
+		reason: "response payload missing active profile/workspace field"
+	};
+	return {
+		ok: true,
+		reason: "profiles payload shape is valid"
+	};
+}
+async function probeWebRuntime(port) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), WEB_APP_PROBE_TIMEOUT_MS);
+	try {
+		const response = await fetch(`http://127.0.0.1:${port}/api/profiles`, {
+			method: "GET",
+			signal: controller.signal,
+			redirect: "manual"
+		});
+		if (response.status < 200 || response.status >= 400) return {
+			ok: false,
+			status: response.status,
+			reason: `/api/profiles returned status ${response.status}`
+		};
+		const evaluation = evaluateWebProfilesPayload(await response.json().catch(() => null));
+		return {
+			ok: evaluation.ok,
+			status: response.status,
+			reason: evaluation.reason
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			reason: (error instanceof Error ? error.message : String(error)) || "probe failed"
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}
+async function waitForWebRuntime(port) {
+	let lastResult = {
+		ok: false,
+		reason: "web runtime did not respond"
+	};
+	for (let attempt = 0; attempt < WEB_APP_PROBE_ATTEMPTS; attempt += 1) {
+		const result = await probeWebRuntime(port);
+		if (result.ok) return result;
+		lastResult = result;
+		await sleep$1(WEB_APP_PROBE_DELAY_MS);
+	}
+	return lastResult;
+}
+function classifyWebPortListener(params) {
+	if (!params.cwd) return "foreign";
+	if (isPathWithin(params.managedRuntimeAppDir, params.cwd)) return "managed";
+	if (normalizePathForMatch(params.cwd).includes(LEGACY_STANDALONE_SEGMENT)) return "legacy-standalone";
+	return "foreign";
+}
+function parseSemverMajor(version) {
+	if (!version) return null;
+	const match = version.trim().match(/^v?(\d+)(?:\.\d+)?(?:\.\d+)?(?:[-+].*)?$/u);
+	if (!match) return null;
+	const major = Number.parseInt(match[1], 10);
+	if (!Number.isFinite(major)) return null;
+	return major;
+}
+function evaluateMajorVersionTransition(params) {
+	const previousMajor = parseSemverMajor(params.previousVersion);
+	const currentMajor = parseSemverMajor(params.currentVersion);
+	return {
+		previousMajor,
+		currentMajor,
+		isMajorTransition: previousMajor !== null && currentMajor !== null && previousMajor !== currentMajor
+	};
+}
+function resolveProcessCwd(pid) {
+	try {
+		const output = execFileSync(resolveLsofCommandSync(), [
+			"-nP",
+			"-a",
+			"-p",
+			String(pid),
+			"-d",
+			"cwd",
+			"-Fn"
+		], { encoding: "utf-8" });
+		for (const line of output.split(/\r?\n/)) if (line.startsWith("n")) {
+			const cwd = line.slice(1).trim();
+			if (cwd.length > 0) return cwd;
+		}
+		return;
+	} catch {
+		return;
+	}
+}
+function inspectWebPortListeners(port, stateDir) {
+	if (process$1.env.VITEST === "true" && process$1.env.OPENCLAW_TEST_REAL_PORTS !== "1") return [];
+	const listeners = listPortListeners(port);
+	const managedRuntimeAppDir = resolveManagedWebRuntimeAppDir(stateDir);
+	return listeners.map((listener) => {
+		const cwd = resolveProcessCwd(listener.pid);
+		const ownership = classifyWebPortListener({
+			cwd,
+			managedRuntimeAppDir
+		});
+		return {
+			...listener,
+			cwd,
+			ownership
+		};
+	});
+}
+function readLastKnownWebPort(stateDir) {
+	const processPort = parseOptionalPositiveInt(readManagedWebRuntimeProcess(stateDir)?.port);
+	if (processPort) return processPort;
+	const manifestPort = parseOptionalPositiveInt(readManagedWebRuntimeManifest(stateDir)?.lastPort);
+	if (manifestPort) return manifestPort;
+	return DEFAULT_WEB_APP_PORT;
+}
+function installManagedWebRuntime(params) {
+	const runtimeDir = resolveManagedWebRuntimeDir(params.stateDir);
+	const runtimeAppDir = resolveManagedWebRuntimeAppDir(params.stateDir);
+	const runtimeServerPath = resolveManagedWebRuntimeServerPath(params.stateDir);
+	const sourceStandaloneServer = resolvePackagedStandaloneServerPath(params.packageRoot);
+	const sourceAppDir = resolvePackagedStandaloneAppDir(params.packageRoot);
+	if (!existsSync(sourceStandaloneServer)) return {
+		installed: false,
+		runtimeDir,
+		runtimeAppDir,
+		runtimeServerPath,
+		reason: "standalone-missing"
+	};
+	mkdirSync(runtimeDir, { recursive: true });
+	rmSync(runtimeAppDir, {
+		recursive: true,
+		force: true
+	});
+	cpSync(sourceAppDir, runtimeAppDir, {
+		recursive: true,
+		force: true
+	});
+	const manifest = {
+		schemaVersion: 1,
+		deployedDenchVersion: params.denchVersion,
+		deployedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		sourceStandaloneServer,
+		...typeof params.webPort === "number" ? { lastPort: params.webPort } : {},
+		...typeof params.gatewayPort === "number" ? { lastGatewayPort: params.gatewayPort } : {}
+	};
+	writeManagedWebRuntimeManifest(params.stateDir, manifest);
+	return {
+		installed: true,
+		runtimeDir,
+		runtimeAppDir,
+		runtimeServerPath,
+		manifest
+	};
+}
+async function stopManagedWebRuntime(params) {
+	const listeners = inspectWebPortListeners(params.port, params.stateDir);
+	const includeLegacyStandalone = params.includeLegacyStandalone ?? true;
+	const stoppable = listeners.filter((listener) => listener.ownership === "managed" || includeLegacyStandalone && listener.ownership === "legacy-standalone");
+	const skippedForeign = listeners.filter((listener) => listener.ownership === "foreign");
+	const uniquePids = [...new Set(stoppable.map((listener) => listener.pid))];
+	const stoppedPids = [];
+	for (const pid of uniquePids) {
+		await terminatePidWithEscalation(pid);
+		if (!isProcessAlive(pid)) stoppedPids.push(pid);
+	}
+	const processMeta = readManagedWebRuntimeProcess(params.stateDir);
+	if (processMeta?.port === params.port && stoppedPids.includes(processMeta.pid)) clearManagedWebRuntimeProcess(params.stateDir);
+	if (inspectWebPortListeners(params.port, params.stateDir).filter((listener) => listener.ownership === "managed").length === 0) clearManagedWebRuntimeProcess(params.stateDir);
+	return {
+		port: params.port,
+		stoppedPids,
+		skippedForeignPids: [...new Set(skippedForeign.map((listener) => listener.pid))]
+	};
+}
+function startManagedWebRuntime(params) {
+	const runtimeServerPath = resolveManagedWebRuntimeServerPath(params.stateDir);
+	if (!existsSync(runtimeServerPath)) return {
+		started: false,
+		runtimeServerPath,
+		reason: "runtime-missing"
+	};
+	const logsDir = path.join(params.stateDir, "logs");
+	mkdirSync(logsDir, { recursive: true });
+	const outFd = openSync(path.join(logsDir, "web-app.log"), "a");
+	const errFd = openSync(path.join(logsDir, "web-app.err.log"), "a");
+	const child = spawn(process$1.execPath, [runtimeServerPath], {
+		cwd: path.dirname(runtimeServerPath),
+		detached: true,
+		stdio: [
+			"ignore",
+			outFd,
+			errFd
+		],
+		env: {
+			...process$1.env,
+			...params.env,
+			PORT: String(params.port),
+			HOSTNAME: "127.0.0.1",
+			OPENCLAW_GATEWAY_PORT: String(params.gatewayPort)
+		}
+	});
+	child.unref();
+	writeManagedWebRuntimeProcess(params.stateDir, {
+		pid: child.pid ?? -1,
+		port: params.port,
+		gatewayPort: params.gatewayPort,
+		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		runtimeAppDir: path.dirname(runtimeServerPath)
+	});
+	updateManifestLastPort(params.stateDir, params.port, params.gatewayPort);
+	return {
+		started: true,
+		pid: child.pid ?? -1,
+		runtimeServerPath
+	};
+}
+async function ensureManagedWebRuntime(params) {
+	if (!installManagedWebRuntime({
+		stateDir: params.stateDir,
+		packageRoot: params.packageRoot,
+		denchVersion: params.denchVersion,
+		webPort: params.port,
+		gatewayPort: params.gatewayPort
+	}).installed) return {
+		ready: false,
+		reason: "standalone web build is missing from package"
+	};
+	await stopManagedWebRuntime({
+		stateDir: params.stateDir,
+		port: params.port,
+		includeLegacyStandalone: true
+	});
+	const foreign = inspectWebPortListeners(params.port, params.stateDir).filter((listener) => listener.ownership === "foreign");
+	if (foreign.length > 0) {
+		const detail = foreign.map((listener) => `${listener.pid}${listener.command ? `:${listener.command}` : ""}`).join(", ");
+		return {
+			ready: false,
+			reason: `port ${params.port} is owned by non-Dench process(es): ${detail}`
+		};
+	}
+	if (!startManagedWebRuntime({
+		stateDir: params.stateDir,
+		port: params.port,
+		gatewayPort: params.gatewayPort
+	}).started) return {
+		ready: false,
+		reason: "managed web runtime is missing after install"
+	};
+	const probe = await waitForWebRuntime(params.port);
+	return {
+		ready: probe.ok,
+		reason: probe.reason
+	};
+}
+function resolveOpenClawCommandOrThrow() {
+	try {
+		const first = execFileSync(process$1.platform === "win32" ? "where" : "which", ["openclaw"], { encoding: "utf-8" }).trim().split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+		if (first) return first;
+		throw new Error("openclaw command not found");
+	} catch {
+		throw new Error("Global `openclaw` CLI was not found on PATH. Install it with: npm install -g openclaw");
+	}
+}
+
 //#endregion
 //#region src/cli/workspace-seed.ts
 const SEED_OBJECTS = [
@@ -328,13 +827,9 @@ function seedWorkspaceFromAssets(params) {
 //#endregion
 //#region src/cli/bootstrap-external.ts
 const DEFAULT_DENCHCLAW_PROFILE = "dench";
-const DENCHCLAW_STATE_DIRNAME = ".openclaw-dench";
 const DEFAULT_GATEWAY_PORT = 18789;
 const DENCHCLAW_GATEWAY_PORT_START = 19001;
 const MAX_PORT_SCAN_ATTEMPTS = 100;
-const DEFAULT_WEB_APP_PORT = 3100;
-const WEB_APP_PROBE_ATTEMPTS = 20;
-const WEB_APP_PROBE_DELAY_MS = 750;
 const DEFAULT_BOOTSTRAP_ROLLOUT_STAGE = "default";
 const DEFAULT_GATEWAY_LAUNCH_AGENT_LABEL = "ai.openclaw.gateway";
 const REQUIRED_TOOLS_PROFILE = "full";
@@ -397,7 +892,7 @@ async function runCommandWithTimeout(argv, options) {
 		});
 	});
 }
-function parseOptionalPort(value) {
+function parseOptionalPort$1(value) {
 	if (value === void 0) return;
 	const raw = typeof value === "number" ? value : Number.parseInt(String(value), 10);
 	if (!Number.isFinite(raw) || raw <= 0) return;
@@ -447,16 +942,12 @@ function normalizeVersionOutput(raw) {
 	const first = raw?.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
 	return first && first.length > 0 ? first : void 0;
 }
-function firstNonEmptyLine(...values) {
+function firstNonEmptyLine$1(...values) {
 	for (const value of values) {
 		const first = value?.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
 		if (first) return first;
 	}
 }
-function resolveProfileStateDir(profile, env = process$1.env) {
-	const home = resolveRequiredHomeDir(env, os.homedir);
-	return path.join(home, DENCHCLAW_STATE_DIRNAME);
-}
 function resolveGatewayLaunchAgentLabel(profile) {
 	const normalized = profile.trim().toLowerCase();
 	if (!normalized || normalized === "default") return DEFAULT_GATEWAY_LAUNCH_AGENT_LABEL;
@@ -551,67 +1042,6 @@ async function ensureToolsProfile(openclawCommand, profile) {
 		errorMessage: `Failed to set tools.profile=${REQUIRED_TOOLS_PROFILE}.`
 	});
 }
-async function probeForWebApp(port) {
-	const controller = new AbortController();
-	const timer = setTimeout(() => controller.abort(), 1500);
-	try {
-		const response = await fetch(`http://127.0.0.1:${port}/api/profiles`, {
-			method: "GET",
-			signal: controller.signal,
-			redirect: "manual"
-		});
-		if (response.status < 200 || response.status >= 400) return false;
-		const payload = await response.json().catch(() => null);
-		return Boolean(payload && typeof payload === "object" && Array.isArray(payload.profiles) && typeof payload.activeProfile === "string");
-	} catch {
-		return false;
-	} finally {
-		clearTimeout(timer);
-	}
-}
-async function waitForWebApp(preferredPort) {
-	for (let attempt = 0; attempt < WEB_APP_PROBE_ATTEMPTS; attempt += 1) {
-		if (await probeForWebApp(preferredPort)) return true;
-		await sleep(WEB_APP_PROBE_DELAY_MS);
-	}
-	return false;
-}
-function resolveCliPackageRoot() {
-	let dir = path.dirname(fileURLToPath(import.meta.url));
-	for (let i = 0; i < 5; i++) {
-		if (existsSync(path.join(dir, "package.json"))) return dir;
-		dir = path.dirname(dir);
-	}
-	return process$1.cwd();
-}
-/**
-* Spawn the pre-built standalone Next.js server as a detached background
-* process if it isn't already running on the target port.
-*/
-function startWebAppIfNeeded(port, stateDir, gatewayPort) {
-	const pkgRoot = resolveCliPackageRoot();
-	const standaloneServer = path.join(pkgRoot, "apps/web/.next/standalone/apps/web/server.js");
-	if (!existsSync(standaloneServer)) return;
-	const logDir = path.join(stateDir, "logs");
-	mkdirSync(logDir, { recursive: true });
-	const outFd = openSync(path.join(logDir, "web-app.log"), "a");
-	const errFd = openSync(path.join(logDir, "web-app.err.log"), "a");
-	spawn(process$1.execPath, [standaloneServer], {
-		cwd: path.dirname(standaloneServer),
-		detached: true,
-		stdio: [
-			"ignore",
-			outFd,
-			errFd
-		],
-		env: {
-			...process$1.env,
-			PORT: String(port),
-			HOSTNAME: "127.0.0.1",
-			OPENCLAW_GATEWAY_PORT: String(gatewayPort)
-		}
-	}).unref();
-}
 async function runOpenClaw(openclawCommand, args, timeoutMs, ioMode = "capture", env) {
 	return await runCommandWithTimeout([openclawCommand, ...args], {
 		timeoutMs,
@@ -622,7 +1052,7 @@ async function runOpenClaw(openclawCommand, args, timeoutMs, ioMode = "capture",
 async function runOpenClawOrThrow(params) {
 	const result = await runOpenClaw(params.openclawCommand, params.args, params.timeoutMs);
 	if (result.code === 0) return result;
-	const detail = firstNonEmptyLine(result.stderr, result.stdout);
+	const detail = firstNonEmptyLine$1(result.stderr, result.stdout);
 	throw new Error(detail ? `${params.errorMessage}\n${detail}` : params.errorMessage);
 }
 /**
@@ -632,7 +1062,7 @@ async function runOpenClawOrThrow(params) {
 async function runOpenClawInteractiveOrThrow(params) {
 	const result = await runOpenClaw(params.openclawCommand, params.args, params.timeoutMs, "inherit");
 	if (result.code === 0) return result;
-	const detail = firstNonEmptyLine(result.stderr, result.stdout);
+	const detail = firstNonEmptyLine$1(result.stderr, result.stdout);
 	throw new Error(detail ? `${params.errorMessage}\n${detail}` : params.errorMessage);
 }
 /**
@@ -689,7 +1119,7 @@ async function runOpenClawWithProgress(params) {
 		s.stop(params.successMessage);
 		return result;
 	}
-	const detail = firstNonEmptyLine(result.stderr, result.stdout);
+	const detail = firstNonEmptyLine$1(result.stderr, result.stdout);
 	const stopMessage = detail ? `${params.errorMessage}: ${detail}` : params.errorMessage;
 	s.stop(stopMessage);
 	throw new Error(detail ? `${params.errorMessage}\n${detail}` : params.errorMessage);
@@ -737,7 +1167,7 @@ async function resolveNpmGlobalBinDir() {
 		"-g"
 	], { timeoutMs: 8e3 }).catch(() => null);
 	if (!result || result.code !== 0) return;
-	const prefix = firstNonEmptyLine(result.stdout);
+	const prefix = firstNonEmptyLine$1(result.stdout);
 	if (!prefix) return;
 	return process$1.platform === "win32" ? prefix : path.join(prefix, "bin");
 }
@@ -748,7 +1178,7 @@ function resolveGlobalOpenClawCommand(globalBinDir) {
 async function resolveShellOpenClawPath() {
 	const result = await runCommandWithTimeout([process$1.platform === "win32" ? "where" : "which", "openclaw"], { timeoutMs: 4e3 }).catch(() => null);
 	if (!result || result.code !== 0) return;
-	return firstNonEmptyLine(result.stdout);
+	return firstNonEmptyLine$1(result.stdout);
 }
 function isProjectLocalOpenClawPath(commandPath) {
 	if (!commandPath) return false;
@@ -803,7 +1233,7 @@ async function probeGateway(openclawCommand, profile, gatewayPort) {
 	if (result.code === 0) return { ok: true };
 	return {
 		ok: false,
-		detail: firstNonEmptyLine(result.stderr, result.stdout)
+		detail: firstNonEmptyLine$1(result.stderr, result.stdout)
 	};
 }
 function readLogTail(logPath, maxLines = 16) {
@@ -911,7 +1341,7 @@ async function attemptGatewayAutoFix(params) {
 		steps.push({
 			name: command.name,
 			ok: result.code === 0,
-			detail: result.code === 0 ? void 0 : firstNonEmptyLine(result.stderr, result.stdout)
+			detail: result.code === 0 ? void 0 : firstNonEmptyLine$1(result.stderr, result.stdout)
 		});
 	}
 	let finalProbe = await probeGateway(params.openclawCommand, params.profile, params.gatewayPort);
@@ -948,7 +1378,11 @@ function remediationForGatewayFailure(detail, port, profile) {
 	return `Run \`openclaw --profile ${profile} doctor --fix\` and retry \`denchclaw bootstrap --profile ${profile} --force-onboard\`.`;
 }
 function remediationForWebUiFailure(port) {
-	return `Web UI did not respond on ${port}. Ensure the apps/web directory exists and rerun with \`denchclaw bootstrap --web-port <port>\` if needed.`;
+	return [
+		`Web UI did not respond on ${port}.`,
+		`Run \`dench update --web-port ${port}\` to refresh the managed web runtime.`,
+		`If the port is stuck, run \`dench stop --web-port ${port}\` first.`
+	].join(" ");
 }
 function describeWorkspaceSeedResult(result) {
 	if (result.seeded) return `seeded ${result.dbPath}`;
@@ -1116,7 +1550,7 @@ async function bootstrapCommand(opts, runtime = defaultRuntime) {
 		successMessage: "OpenClaw is up to date.",
 		errorMessage: "OpenClaw update failed"
 	});
-	const explicitPort = parseOptionalPort(opts.gatewayPort);
+	const explicitPort = parseOptionalPort$1(opts.gatewayPort);
 	let gatewayPort;
 	let portAutoAssigned = false;
 	if (explicitPort) gatewayPort = explicitPort;
@@ -1156,9 +1590,10 @@ async function bootstrapCommand(opts, runtime = defaultRuntime) {
 		timeoutMs: 12 * 6e4,
 		errorMessage: "OpenClaw onboarding failed."
 	});
+	const packageRoot = resolveCliPackageRoot();
 	const workspaceSeed = seedWorkspaceFromAssets({
 		workspaceDir,
-		packageRoot: resolveCliPackageRoot()
+		packageRoot
 	});
 	await ensureGatewayModeLocal(openclawCommand, profile);
 	await ensureGatewayPort(openclawCommand, profile, gatewayPort);
@@ -1180,9 +1615,15 @@ async function bootstrapCommand(opts, runtime = defaultRuntime) {
 		};
 	}
 	const gatewayUrl = `ws://127.0.0.1:${gatewayPort}`;
-	const preferredWebPort = parseOptionalPort(opts.webPort) ?? DEFAULT_WEB_APP_PORT;
-	if (!await probeForWebApp(preferredWebPort)) startWebAppIfNeeded(preferredWebPort, stateDir, gatewayPort);
-	const webReachable = await waitForWebApp(preferredWebPort);
+	const preferredWebPort = parseOptionalPort$1(opts.webPort) ?? DEFAULT_WEB_APP_PORT;
+	const webRuntimeStatus = await ensureManagedWebRuntime({
+		stateDir,
+		packageRoot,
+		denchVersion: VERSION,
+		port: preferredWebPort,
+		gatewayPort
+	});
+	const webReachable = webRuntimeStatus.ready;
 	const webUrl = `http://localhost:${preferredWebPort}`;
 	const diagnostics = buildBootstrapDiagnostics({
 		profile,
@@ -1200,6 +1641,7 @@ async function bootstrapCommand(opts, runtime = defaultRuntime) {
 	const shouldOpen = !opts.noOpen && !opts.json;
 	const opened = shouldOpen ? await openUrl(webUrl) : false;
 	if (!opts.json) {
+		if (!webRuntimeStatus.ready) runtime.log(theme.warn(`Managed web runtime check failed: ${webRuntimeStatus.reason}`));
 		if (installResult.installed) runtime.log(theme.muted("Installed global OpenClaw CLI via npm."));
 		if (isProjectLocalOpenClawPath(installResult.shellCommandPath)) {
 			runtime.log(theme.warn(`\`openclaw\` currently resolves to a project-local binary (${installResult.shellCommandPath}).`));
@@ -1327,4 +1769,397 @@ function registerBootstrapCommand(program) {
 }
 
 //#endregion
-export { registerBootstrapCommand };
+//#region src/cli/web-runtime-command.ts
+function parseOptionalPort(value) {
+	if (value === void 0) return;
+	const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) return;
+	return parsed;
+}
+function firstNonEmptyLine(...values) {
+	for (const value of values) {
+		const first = value?.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+		if (first) return first;
+	}
+}
+async function runOpenClawUpdateWithProgress(openclawCommand) {
+	const s = spinner();
+	s.start("Updating OpenClaw (required for this major Dench upgrade)...");
+	const result = await new Promise((resolve, reject) => {
+		const child = spawn(openclawCommand, ["update", "--yes"], {
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			env: process$1.env
+		});
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		const timer = setTimeout(() => {
+			if (!settled) child.kill("SIGKILL");
+		}, 8 * 6e4);
+		const updateSpinner = (chunk) => {
+			const line = chunk.split(/\r?\n/).map((item) => item.trim()).filter(Boolean).at(-1);
+			if (line) s.message(line.length > 72 ? `${line.slice(0, 69)}...` : line);
+		};
+		child.stdout?.on("data", (chunk) => {
+			const text = String(chunk);
+			stdout += text;
+			updateSpinner(text);
+		});
+		child.stderr?.on("data", (chunk) => {
+			const text = String(chunk);
+			stderr += text;
+			updateSpinner(text);
+		});
+		child.once("error", (error) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			reject(error);
+		});
+		child.once("close", (code) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve({
+				code: typeof code === "number" ? code : 1,
+				stdout,
+				stderr
+			});
+		});
+	});
+	if (result.code === 0) {
+		s.stop("OpenClaw update complete.");
+		return;
+	}
+	const detail = firstNonEmptyLine(result.stderr, result.stdout);
+	s.stop(detail ? `OpenClaw update failed: ${detail}` : "OpenClaw update failed.");
+	throw new Error(detail ? `OpenClaw update failed.\n${detail}` : "OpenClaw update failed. Fix this before running `dench update` again.");
+}
+async function ensureMajorUpgradeAcknowledged(params) {
+	if (!params.required) return;
+	if (params.nonInteractive || !process$1.stdin.isTTY) {
+		if (!params.yes) throw new Error(`Major Dench upgrade detected (${params.previousVersion ?? "unknown"} -> ${params.currentVersion}). Re-run with --yes to approve the required OpenClaw update.`);
+		return;
+	}
+	if (params.yes) return;
+	const decision = await confirm({
+		message: stylePromptMessage(`Major Dench upgrade detected (${params.previousVersion ?? "unknown"} -> ${params.currentVersion}). Continue with mandatory OpenClaw update now?`),
+		initialValue: true
+	});
+	if (isCancel(decision) || !decision) {
+		params.runtime.log(theme.warn("Update cancelled. OpenClaw update is required for major upgrades."));
+		throw new Error("Major upgrade requires OpenClaw update approval.");
+	}
+}
+function resolveGatewayPort(stateDir) {
+	const manifest = readManagedWebRuntimeManifest(stateDir);
+	if (typeof manifest?.lastGatewayPort === "number" && Number.isFinite(manifest.lastGatewayPort) && manifest.lastGatewayPort > 0) return manifest.lastGatewayPort;
+	for (const name of ["openclaw.json", "config.json"]) {
+		const port = readConfigGatewayPort(path.join(stateDir, name));
+		if (typeof port === "number") return port;
+	}
+	return 18789;
+}
+function readConfigGatewayPort(configPath) {
+	try {
+		const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+		const parsedPort = typeof raw.gateway?.port === "number" ? raw.gateway.port : typeof raw.gateway?.port === "string" ? Number.parseInt(raw.gateway.port, 10) : void 0;
+		if (typeof parsedPort === "number" && Number.isFinite(parsedPort) && parsedPort > 0) return parsedPort;
+		return;
+	} catch {
+		return;
+	}
+}
+async function updateWebRuntimeCommand(opts, runtime = defaultRuntime) {
+	const appliedProfile = applyCliProfileEnv({ profile: opts.profile });
+	const profile = appliedProfile.effectiveProfile;
+	if (appliedProfile.warning && !opts.json) runtime.log(theme.warn(appliedProfile.warning));
+	const stateDir = resolveProfileStateDir(profile);
+	const packageRoot = resolveCliPackageRoot();
+	const previousManifest = readManagedWebRuntimeManifest(stateDir);
+	const transition = evaluateMajorVersionTransition({
+		previousVersion: previousManifest?.deployedDenchVersion,
+		currentVersion: VERSION
+	});
+	const nonInteractive = Boolean(opts.nonInteractive || opts.json);
+	await ensureMajorUpgradeAcknowledged({
+		required: transition.isMajorTransition,
+		previousVersion: previousManifest?.deployedDenchVersion,
+		currentVersion: VERSION,
+		nonInteractive,
+		yes: Boolean(opts.yes),
+		runtime
+	});
+	if (transition.isMajorTransition) await runOpenClawUpdateWithProgress(resolveOpenClawCommandOrThrow());
+	const selectedPort = parseOptionalPort(opts.webPort) ?? parseOptionalPort(previousManifest?.lastPort) ?? readLastKnownWebPort(stateDir) ?? DEFAULT_WEB_APP_PORT;
+	const gatewayPort = resolveGatewayPort(stateDir);
+	const stopResult = await stopManagedWebRuntime({
+		stateDir,
+		port: selectedPort,
+		includeLegacyStandalone: true
+	});
+	const ensureResult = await ensureManagedWebRuntime({
+		stateDir,
+		packageRoot,
+		denchVersion: VERSION,
+		port: selectedPort,
+		gatewayPort
+	});
+	const summary = {
+		profile,
+		webPort: selectedPort,
+		version: VERSION,
+		majorGate: {
+			required: transition.isMajorTransition,
+			previousVersion: previousManifest?.deployedDenchVersion,
+			currentVersion: VERSION
+		},
+		stoppedPids: stopResult.stoppedPids,
+		skippedForeignPids: stopResult.skippedForeignPids,
+		ready: ensureResult.ready,
+		reason: ensureResult.reason
+	};
+	if (!opts.json) {
+		runtime.log("");
+		runtime.log(theme.heading("Dench web update"));
+		runtime.log(`Profile: ${profile}`);
+		runtime.log(`Version: ${VERSION}`);
+		runtime.log(`Web port: ${selectedPort}`);
+		runtime.log(`Stopped web processes: ${summary.stoppedPids.length}`);
+		if (summary.skippedForeignPids.length > 0) runtime.log(theme.warn(`Skipped non-Dench listeners on ${selectedPort}: ${summary.skippedForeignPids.join(", ")}`));
+		runtime.log(`Web runtime: ${summary.ready ? "ready" : "not ready"}`);
+		if (!summary.ready) runtime.log(theme.warn(summary.reason));
+	}
+	if (!summary.ready) throw new Error(`Web runtime update failed: ${summary.reason}`);
+	if (opts.json) runtime.log(JSON.stringify(summary, null, 2));
+	return summary;
+}
+async function stopWebRuntimeCommand(opts, runtime = defaultRuntime) {
+	const appliedProfile = applyCliProfileEnv({ profile: opts.profile });
+	const profile = appliedProfile.effectiveProfile;
+	if (appliedProfile.warning && !opts.json) runtime.log(theme.warn(appliedProfile.warning));
+	const stateDir = resolveProfileStateDir(profile);
+	const selectedPort = parseOptionalPort(opts.webPort) ?? readLastKnownWebPort(stateDir);
+	const stopResult = await stopManagedWebRuntime({
+		stateDir,
+		port: selectedPort,
+		includeLegacyStandalone: true
+	});
+	const summary = {
+		profile,
+		webPort: selectedPort,
+		stoppedPids: stopResult.stoppedPids,
+		skippedForeignPids: stopResult.skippedForeignPids
+	};
+	if (opts.json) {
+		runtime.log(JSON.stringify(summary, null, 2));
+		return summary;
+	}
+	runtime.log("");
+	runtime.log(theme.heading("Dench web stop"));
+	runtime.log(`Profile: ${profile}`);
+	runtime.log(`Web port: ${selectedPort}`);
+	runtime.log(summary.stoppedPids.length > 0 ? `Stopped web processes: ${summary.stoppedPids.join(", ")}` : "Stopped web processes: none");
+	if (summary.skippedForeignPids.length > 0) runtime.log(theme.warn(`Left non-Dench listener(s) running on ${selectedPort}: ${summary.skippedForeignPids.join(", ")}`));
+	return summary;
+}
+
+//#endregion
+//#region src/cli/program/register.stop.ts
+function registerStopCommand(program) {
+	program.command("stop").description("Stop Dench managed web runtime on the configured port").option("--profile <name>", "Compatibility flag; non-dench values are ignored with a warning").option("--web-port <port>", "Web runtime port override").option("--json", "Output summary as JSON", false).action(async (opts) => {
+		await runCommandWithRuntime(defaultRuntime, async () => {
+			await stopWebRuntimeCommand({
+				profile: opts.profile,
+				webPort: opts.webPort,
+				json: Boolean(opts.json)
+			});
+		});
+	});
+}
+
+//#endregion
+//#region src/cli/program/register.update.ts
+function registerUpdateCommand(program) {
+	program.command("update").description("Update Dench managed web runtime without onboarding").option("--profile <name>", "Compatibility flag; non-dench values are ignored with a warning").option("--web-port <port>", "Web runtime port override").option("--non-interactive", "Fail instead of prompting for major-gate approval", false).option("--yes", "Approve mandatory major-gate OpenClaw update", false).option("--json", "Output summary as JSON", false).action(async (opts) => {
+		await runCommandWithRuntime(defaultRuntime, async () => {
+			await updateWebRuntimeCommand({
+				profile: opts.profile,
+				webPort: opts.webPort,
+				nonInteractive: Boolean(opts.nonInteractive),
+				yes: Boolean(opts.yes),
+				json: Boolean(opts.json)
+			});
+		});
+	});
+}
+
+//#endregion
+//#region src/cli/program/command-registry.ts
+const CORE_CLI_ENTRIES = [
+	{
+		name: "bootstrap",
+		description: "Bootstrap DenchClaw + OpenClaw and launch the web UI",
+		register: ({ program }) => {
+			registerBootstrapCommand(program);
+		}
+	},
+	{
+		name: "update",
+		description: "Update Dench web runtime without onboarding",
+		register: ({ program }) => {
+			registerUpdateCommand(program);
+		}
+	},
+	{
+		name: "stop",
+		description: "Stop Dench managed web runtime",
+		register: ({ program }) => {
+			registerStopCommand(program);
+		}
+	}
+];
+const CORE_CLI_ENTRY_BY_NAME = new Map(CORE_CLI_ENTRIES.map((entry) => [entry.name, entry]));
+function getCoreCliCommandsWithSubcommands() {
+	return [];
+}
+function registerCoreCliCommands(program, ctx, argv) {
+	const primary = getPrimaryCommand(argv);
+	if (primary) {
+		const entry = CORE_CLI_ENTRY_BY_NAME.get(primary);
+		if (!entry) return;
+		entry.register({
+			program,
+			ctx,
+			argv
+		});
+		return;
+	}
+	for (const entry of CORE_CLI_ENTRIES) entry.register({
+		program,
+		ctx,
+		argv
+	});
+}
+function registerProgramCommands(program, ctx, argv = process.argv) {
+	registerCoreCliCommands(program, ctx, argv);
+}
+
+//#endregion
+//#region src/cli/program/context.ts
+function createProgramContext() {
+	const channelOptions = ["web"];
+	return {
+		programVersion: VERSION,
+		channelOptions,
+		messageChannelOptions: channelOptions.join("|"),
+		agentChannelOptions: ["last", ...channelOptions].join("|")
+	};
+}
+
+//#endregion
+//#region src/cli/program/help.ts
+const CLI_NAME = resolveCliName();
+const CLI_NAME_PATTERN = escapeRegExp(CLI_NAME);
+const ROOT_COMMANDS_WITH_SUBCOMMANDS = new Set(getCoreCliCommandsWithSubcommands());
+const ROOT_COMMANDS_HINT = "Hint: commands suffixed with * have subcommands. Run <command> --help for details.";
+const EXAMPLES = [
+	["openclaw update", "Refresh the managed web runtime and enforce major upgrade gates."],
+	["openclaw stop --web-port 3100", "Stop only the managed web runtime on a specific port."],
+	["openclaw models --help", "Show detailed help for the models command."],
+	["openclaw channels login --verbose", "Link personal WhatsApp Web and show QR + connection logs."],
+	["openclaw message send --target +15555550123 --message \"Hi\" --json", "Send via your web session and print JSON result."],
+	["openclaw gateway --port 18789", "Run the WebSocket Gateway locally."],
+	["openclaw --profile team-a gateway", "Compatibility flag example: warns and still runs with --profile dench."],
+	["openclaw gateway --force", "Kill anything bound to the default gateway port, then start it."],
+	["openclaw gateway ...", "Gateway control via WebSocket."],
+	["openclaw agent --to +15555550123 --message \"Run summary\" --deliver", "Talk directly to the agent using the Gateway; optionally send the WhatsApp reply."],
+	["openclaw message send --channel telegram --target @mychat --message \"Hi\"", "Send via your Telegram bot."]
+];
+function configureProgramHelp(program, ctx) {
+	program.name(CLI_NAME).description("").version(ctx.programVersion).option("--dev", "Compatibility flag; DenchClaw always uses --profile dench and ~/.openclaw-dench").option("--profile <name>", "Compatibility flag; non-dench values are ignored with a warning");
+	program.option("--no-color", "Disable ANSI colors", false);
+	program.helpOption("-h, --help", "Display help for command");
+	program.helpCommand("help [command]", "Display help for command");
+	program.configureHelp({
+		sortSubcommands: true,
+		sortOptions: true,
+		optionTerm: (option) => theme.option(option.flags),
+		subcommandTerm: (cmd) => {
+			const hasSubcommands = cmd.parent === program && ROOT_COMMANDS_WITH_SUBCOMMANDS.has(cmd.name());
+			return theme.command(hasSubcommands ? `${cmd.name()} *` : cmd.name());
+		}
+	});
+	const formatHelpOutput = (str) => {
+		let output = str;
+		if (new RegExp(`^Usage:\\s+${CLI_NAME_PATTERN}\\s+\\[options\\]\\s+\\[command\\]\\s*$`, "m").test(output) && /^Commands:/m.test(output)) output = output.replace(/^Commands:/m, `Commands:\n  ${theme.muted(ROOT_COMMANDS_HINT)}`);
+		return output.replace(/^Usage:/gm, theme.heading("Usage:")).replace(/^Options:/gm, theme.heading("Options:")).replace(/^Commands:/gm, theme.heading("Commands:"));
+	};
+	program.configureOutput({
+		writeOut: (str) => {
+			process.stdout.write(formatHelpOutput(str));
+		},
+		writeErr: (str) => {
+			process.stderr.write(formatHelpOutput(str));
+		},
+		outputError: (str, write) => write(theme.error(str))
+	});
+	if (hasFlag(process.argv, "-V") || hasFlag(process.argv, "--version") || hasRootVersionAlias(process.argv)) {
+		console.log(ctx.programVersion);
+		process.exit(0);
+	}
+	program.addHelpText("beforeAll", () => {
+		if (hasEmittedCliBanner()) return "";
+		const rich = isRich();
+		return `\n${formatCliBannerLine(ctx.programVersion, { richTty: rich })}\n`;
+	});
+	const fmtExamples = EXAMPLES.map(([cmd, desc]) => `  ${theme.command(replaceCliName(cmd, CLI_NAME))}\n    ${theme.muted(desc)}`).join("\n");
+	program.addHelpText("afterAll", ({ command }) => {
+		if (command !== program) return "";
+		const docs = formatDocsLink("/cli", "docs.openclaw.ai/cli");
+		return `\n${theme.heading("Examples:")}\n${fmtExamples}\n\n${theme.muted("Docs:")} ${docs}\n`;
+	});
+}
+
+//#endregion
+//#region src/cli/program/preaction.ts
+function setProcessTitleForCommand(actionCommand) {
+	let current = actionCommand;
+	while (current.parent && current.parent.parent) current = current.parent;
+	const name = current.name();
+	const cliName = resolveCliName();
+	if (!name || name === cliName) return;
+	process.title = `${cliName}-${name}`;
+}
+function registerPreActionHooks(program, programVersion) {
+	program.hook("preAction", (_thisCommand, actionCommand) => {
+		setProcessTitleForCommand(actionCommand);
+	});
+}
+
+//#endregion
+//#region src/cli/program/program-context.ts
+const PROGRAM_CONTEXT_SYMBOL = Symbol.for("openclaw.cli.programContext");
+function setProgramContext(program, ctx) {
+	program[PROGRAM_CONTEXT_SYMBOL] = ctx;
+}
+
+//#endregion
+//#region src/cli/program/build-program.ts
+function buildProgram() {
+	const program = new Command();
+	const ctx = createProgramContext();
+	const argv = process.argv;
+	setProgramContext(program, ctx);
+	configureProgramHelp(program, ctx);
+	registerPreActionHooks(program, ctx.programVersion);
+	registerProgramCommands(program, ctx, argv);
+	return program;
+}
+
+//#endregion
+export { buildProgram };