nextclaw 0.18.12-beta.2 → 0.18.12-beta.20

package/dist/cli/app/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { _ as waitForExit, a as findExecutableOnPath, c as isProcessRunning, d as prompt, f as resolvePublicIp, g as resolveUiStaticDir, h as resolveUiConfig, i as NpmRuntimeBundleLayoutStore, l as openBrowser, m as resolveUiApiBase, n as NpmRuntimeBundleService, o as getPackageVersion$1, p as resolveServiceLogPath, r as compareNpmRuntimeVersions, s as isLoopbackHost, t as NpmRuntimeUpdateStateStore, u as printAgentResponse } from "../../npm-runtime-update-state.store-DaF0iDY9.js";
+import { S as waitForExit, _ as resolvePublicIp, a as compareNpmRuntimeVersions, b as resolveUiConfig, c as NpmRuntimeBundleLayoutStore, d as getPackageVersion$1, f as isLoopbackHost, g as prompt, h as printAgentResponse, i as NpmRuntimeBundleService, l as findExecutableOnPath, m as openBrowser, n as NpmRuntimeUpdateSourceService, o as resolveEffectiveNpmRuntimeVersion, p as isProcessRunning, t as NpmRuntimeUpdateStateStore, u as findListeningProcessByPort, v as resolveServiceLogPath, x as resolveUiStaticDir, y as resolveUiApiBase } from "../../npm-runtime-update-state.store-75vzvn0B.js";
 import { createRequire } from "node:module";
 import * as NextclawCore from "@nextclaw/core";
-import { APP_NAME, APP_TAGLINE, AgentRouteResolver, BUILTIN_MAIN_AGENT_ID, ChannelManager, CommandRegistry, ConfigSchema, ContextBuilder, CronService, CronTool, DEFAULT_WORKSPACE_DIR, DEFAULT_WORKSPACE_PATH, DisposableStore, EditFileTool, ExecTool, ExtensionToolAdapter, FileLogSink, GatewayTool, InputBudgetPruner, LLMProvider, ListDirTool, MemoryGetTool, MemorySearchTool, MessageBus, MessageTool, ProviderManager, ReadFileTool, RequestedSkillsMetadataReader, SessionManager, SessionsHistoryTool, SessionsListTool, SkillsLoader, Tool, ToolRegistry, WebFetchTool, WebSearchTool, WriteFileTool, buildConfigSchema, buildMinimalSystemExecutionPrompt, buildReloadPlan, buildToolCatalogEntries, createAgentProfile, createAssistantStreamDeltaControlMessage, createAssistantStreamResetControlMessage, createGlobalTypedEventBus, createTypedEventKey, createTypingStopControlMessage, diffConfigPaths, expandHome, findEffectiveAgentProfile, getAppLogger, getConfigPath, getDataDir, getDataPath, getLoggingRuntime, getWorkspacePath, hasSecretRef, loadConfig, normalizeInlineSecretRefs, parseAgentScopedSessionKey, parseThinkingLevel, readSessionProjectRoot, redactConfigObject, removeAgentProfile, resolveAppLogPath, resolveConfigSecrets, resolveDefaultAgentProfileId, resolveEffectiveAgentProfiles, resolveLocalUiBaseUrl, resolveProviderRuntime, resolveSessionWorkspacePath, resolveThinkingLevel, saveConfig, toDisposable, updateAgentProfile } from "@nextclaw/core";
+import { APP_NAME, APP_TAGLINE, AgentRouteResolver, BUILTIN_MAIN_AGENT_ID, ChannelManager, CommandRegistry, ConfigSchema, ContextBuilder, CronService, CronTool, DEFAULT_WORKSPACE_DIR, DEFAULT_WORKSPACE_PATH, DisposableStore, EditFileTool, ExecTool, ExtensionToolAdapter, FileLogSink, GatewayTool, InputBudgetPruner, LLMProvider, ListDirTool, MemoryGetTool, MemorySearchTool, MessageBus, MessageTool, ProviderManager, ReadFileTool, RequestedSkillsMetadataReader, SessionManager, SessionsHistoryTool, SessionsListTool, SkillsLoader, Tool, ToolRegistry, WebFetchTool, WebSearchTool, WriteFileTool, buildConfigSchema, buildMinimalSystemExecutionPrompt, buildReloadPlan, buildToolCatalogEntries, createAgentProfile, createAssistantStreamDeltaControlMessage, createAssistantStreamResetControlMessage, createExternalCommandEnv, createGlobalTypedEventBus, createTypedEventKey, createTypingStopControlMessage, diffConfigPaths, expandHome, findEffectiveAgentProfile, getAppLogger, getConfigPath, getDataDir, getDataPath, getLoggingRuntime, getWorkspacePath, hasSecretRef, loadConfig, normalizeInlineSecretRefs, parseAgentScopedSessionKey, parseThinkingLevel, readSessionProjectRoot, redactConfigObject, removeAgentProfile, resolveAppLogPath, resolveConfigSecrets, resolveDefaultAgentProfileId, resolveEffectiveAgentProfiles, resolveLocalUiBaseUrl, resolveProviderRuntime, resolveSessionWorkspacePath, resolveThinkingLevel, saveConfig, toDisposable, updateAgentProfile } from "@nextclaw/core";
 import { Command } from "commander";
 import fs, { appendFileSync, closeSync, constants, cpSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import path, { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep, win32 } from "node:path";
@@ -30,6 +30,7 @@ import { setImmediate as setImmediate$1, setTimeout as setTimeout$1 } from "node
 import { request } from "node:http";
 import { request as request$1 } from "node:https";
 import chokidar from "chokidar";
+import { eventKeys, nextclaw } from "@nextclaw/kernel";
 import { parse } from "yaml";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
@@ -168,7 +169,7 @@ function maskToken(value) {
 	if (value.length <= 12) return "<redacted>";
 	return `${value.slice(0, 6)}...${value.slice(-4)}`;
 }
-function normalizeOptionalString$10(value) {
+function normalizeOptionalString$9(value) {
 	if (typeof value !== "string") return;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : void 0;
@@ -266,8 +267,8 @@ var RemotePlatformClient = class {
 		if (tokenState.reason === "missing") throw new Error("NextClaw platform token is missing. Run \"nextclaw login\" first.");
 		if (tokenState.reason === "expired") throw new Error("NextClaw platform token expired. Run \"nextclaw login\" or browser sign-in again.");
 		if (tokenState.reason === "malformed") throw new Error("NextClaw platform token is invalid. Run \"nextclaw login\" again.");
-		const configuredApiBase = normalizeOptionalString$10(config.remote.platformApiBase) ?? (typeof nextclawProvider?.apiBase === "string" ? nextclawProvider.apiBase.trim() : "");
-		const rawApiBase = normalizeOptionalString$10(opts.apiBase) ?? configuredApiBase;
+		const configuredApiBase = normalizeOptionalString$9(config.remote.platformApiBase) ?? (typeof nextclawProvider?.apiBase === "string" ? nextclawProvider.apiBase.trim() : "");
+		const rawApiBase = normalizeOptionalString$9(opts.apiBase) ?? configuredApiBase;
 		if (!rawApiBase) throw new Error("Platform API base is missing. Pass --api-base, run nextclaw login, or set remote.platformApiBase.");
 		return {
 			platformBase: this.deps.resolvePlatformBase(rawApiBase),
@@ -276,14 +277,14 @@ var RemotePlatformClient = class {
 		};
 	}
 	resolveLocalOrigin(config, opts) {
-		const explicitOrigin = normalizeOptionalString$10(opts.localOrigin);
+		const explicitOrigin = normalizeOptionalString$9(opts.localOrigin);
 		if (explicitOrigin) return explicitOrigin.replace(/\/$/, "");
 		const state = this.deps.readManagedServiceState?.();
 		if (state && this.deps.isProcessRunning?.(state.pid) && Number.isFinite(state.uiPort)) return `http://127.0.0.1:${state.uiPort}`;
 		return `http://127.0.0.1:${typeof config.ui?.port === "number" && Number.isFinite(config.ui.port) ? config.ui.port : 55667}`;
 	}
 	resolveDisplayName(config, opts) {
-		return normalizeOptionalString$10(opts.name) ?? normalizeOptionalString$10(config.remote.deviceName) ?? hostname();
+		return normalizeOptionalString$9(opts.name) ?? normalizeOptionalString$9(config.remote.deviceName) ?? hostname();
 	}
 };
 //#endregion
@@ -4493,7 +4494,7 @@ var RemoteConnector = class {
 };
 //#endregion
 //#region ../nextclaw-remote/src/remote-status-store.ts
-function normalizeOptionalString$9(value) {
+function normalizeOptionalString$8(value) {
 	if (typeof value !== "string") return;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : void 0;
@@ -4504,8 +4505,8 @@ function buildConfiguredRemoteState(config) {
 		enabled: Boolean(remote.enabled),
 		mode: "service",
 		state: remote.enabled ? "disconnected" : "disabled",
-		...normalizeOptionalString$9(remote.deviceName) ? { deviceName: normalizeOptionalString$9(remote.deviceName) } : {},
-		...normalizeOptionalString$9(remote.platformApiBase) ? { platformBase: normalizeOptionalString$9(remote.platformApiBase) } : {},
+		...normalizeOptionalString$8(remote.deviceName) ? { deviceName: normalizeOptionalString$8(remote.deviceName) } : {},
+		...normalizeOptionalString$8(remote.platformApiBase) ? { platformBase: normalizeOptionalString$8(remote.platformApiBase) } : {},
 		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
 	};
 }
@@ -4518,7 +4519,7 @@ function resolveRemoteStatusSnapshot(params) {
 		configuredEnabled: true,
 		runtime: {
 			...buildConfiguredRemoteState(params.config),
-			deviceName: normalizeOptionalString$9(params.config.remote.deviceName) ?? normalizeOptionalString$9(params.fallbackDeviceName) ?? hostname()
+			deviceName: normalizeOptionalString$8(params.config.remote.deviceName) ?? normalizeOptionalString$8(params.fallbackDeviceName) ?? hostname()
 		}
 	};
 	return {
@@ -5062,28 +5063,12 @@ function parseSessionKey(sessionKey) {
 	};
 }
 //#endregion
-//#region src/cli/shared/utils/runtime-helpers.ts
-function resolveSkillsInstallWorkdir(params) {
-	if (params.explicitWorkdir) return expandHome(params.explicitWorkdir);
-	return getWorkspacePath(params.configuredWorkspace);
-}
-function parseStartTimeoutMs(value) {
-	if (value === void 0) return;
-	const parsed = Number(value);
-	if (!Number.isFinite(parsed) || parsed <= 0) {
-		console.error("Invalid --start-timeout value. Provide milliseconds (e.g. 45000).");
-		process.exit(1);
-	}
-	return Math.floor(parsed);
-}
-function resolveManagedServiceUiOverrides(params) {
-	const uiOverrides = {
-		enabled: true,
-		host: params.forcedPublicHost,
-		open: false
-	};
-	if (params.uiPort) uiOverrides.port = Number(params.uiPort);
-	return uiOverrides;
+//#region src/cli/shared/utils/top-level-nextclaw-command-env.utils.ts
+const NEXTCLAW_RUNTIME_BUNDLE_ENV_KEYS = ["NEXTCLAW_RUNTIME_BUNDLE_CHILD", "NEXTCLAW_DISABLE_RUNTIME_BUNDLE_LAUNCHER"];
+function createTopLevelNextclawCommandEnv(baseEnv = process.env, extraEnv = {}) {
+	const env = createExternalCommandEnv(baseEnv, extraEnv);
+	for (const key of NEXTCLAW_RUNTIME_BUNDLE_ENV_KEYS) delete env[key];
+	return env;
 }
 //#endregion
 //#region src/cli/shared/utils/startup-trace.ts
@@ -5260,10 +5245,14 @@ var NpmRuntimeUpdateManager = class {
 	};
 	syncStateFromCurrentPointer = () => {
 		const currentPointer = this.options.layout.readCurrentPointer();
-		if (!currentPointer) return;
+		const effectiveCurrentVersion = resolveEffectiveNpmRuntimeVersion({
+			launcherVersion: this.launcherVersion,
+			currentBundleVersion: currentPointer?.version ?? null
+		});
+		if (!effectiveCurrentVersion) return;
 		this.options.stateStore.update((state) => ({
 			...state,
-			currentVersion: state.currentVersion ?? currentPointer.version
+			currentVersion: effectiveCurrentVersion
 		}));
 	};
 	toSnapshotFromState = (state, patch) => {
@@ -5467,49 +5456,6 @@ function readDirectoryNames(directory) {
 	return readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
 }
 //#endregion
-//#region src/cli/launcher/npm-runtime-update-source.service.ts
-const DEFAULT_NPM_RUNTIME_UPDATE_BASE_URL = "https://Peiiii.github.io/nextclaw/npm-runtime-updates";
-function normalizeOptionalString$8(value) {
-	if (typeof value !== "string") return null;
-	const trimmed = value.trim();
-	return trimmed ? trimmed : null;
-}
-function normalizeChannel(value) {
-	return typeof value === "string" && value.trim().toLowerCase() === "beta" ? "beta" : "stable";
-}
-function resolvePackagedPublicKeyPath() {
-	return resolve(dirname(fileURLToPath(import.meta.url)), "../../..", "resources", "update-bundle-public.pem");
-}
-var NpmRuntimeUpdateSourceService = class {
-	env;
-	platform;
-	arch;
-	constructor(options = {}) {
-		this.env = options.env ?? process.env;
-		this.platform = options.platform ?? process.platform;
-		this.arch = options.arch ?? process.arch;
-	}
-	resolveChannel = (explicitChannel) => {
-		return normalizeChannel(explicitChannel ?? this.env.NEXTCLAW_UPDATE_CHANNEL);
-	};
-	resolveManifestUrl = (channel, explicitManifestUrl) => {
-		const manifestUrl = normalizeOptionalString$8(explicitManifestUrl) ?? normalizeOptionalString$8(this.env.NEXTCLAW_UPDATE_MANIFEST_URL);
-		if (manifestUrl) return manifestUrl;
-		const baseUrl = normalizeOptionalString$8(this.env.NEXTCLAW_UPDATE_MANIFEST_BASE_URL) ?? DEFAULT_NPM_RUNTIME_UPDATE_BASE_URL;
-		return new URL(`${channel}/manifest-${channel}-${this.platform}-${this.arch}.json`, `${baseUrl.replace(/\/+$/, "")}/`).toString();
-	};
-	resolveBundlePublicKey = () => {
-		const explicitPublicKey = normalizeOptionalString$8(this.env.NEXTCLAW_UPDATE_BUNDLE_PUBLIC_KEY);
-		if (explicitPublicKey) return explicitPublicKey;
-		const publicKeyPath = normalizeOptionalString$8(this.env.NEXTCLAW_UPDATE_BUNDLE_PUBLIC_KEY_PATH);
-		if (!publicKeyPath || !existsSync(publicKeyPath)) {
-			const packagedPublicKeyPath = resolvePackagedPublicKeyPath();
-			return existsSync(packagedPublicKeyPath) ? readFileSync(packagedPublicKeyPath, "utf8").trim() : null;
-		}
-		return readFileSync(publicKeyPath, "utf8").trim();
-	};
-};
-//#endregion
 //#region src/cli/launcher/npm-runtime-update-command.service.ts
 var NpmRuntimeUpdateCommandService = class {
 	run = async (opts) => {
@@ -5520,11 +5466,11 @@ var NpmRuntimeUpdateCommandService = class {
 	};
 	runManaged = async (opts) => {
 		const source = new NpmRuntimeUpdateSourceService();
-		const channel = source.resolveChannel(opts.channel);
+		const launcherVersion = getPackageVersion$1();
+		const channel = source.resolveChannel(opts.channel, launcherVersion);
 		const manifestUrl = source.resolveManifestUrl(channel, opts.manifestUrl);
 		const layout = new NpmRuntimeBundleLayoutStore();
-		const stateStore = new NpmRuntimeUpdateStateStore(layout.getStatePath());
-		const launcherVersion = getPackageVersion$1();
+		const stateStore = new NpmRuntimeUpdateStateStore(layout.getStatePath(), { defaultChannel: channel });
 		const bundleService = new NpmRuntimeBundleService({
 			layout,
 			stateStore,
@@ -5748,11 +5694,9 @@ const readInstalledFirstPartyPluginMatches = (workspaceExtensionsDir) => {
 		const workspacePackage = workspacePackageByName.get(packageName);
 		if (!workspacePackage) continue;
 		matches.push({
-			pluginId: workspacePackage.pluginId,
 			packageName,
 			workspaceDir: workspacePackage.dir,
-			installPath: packageDir,
-			supportsDevelopmentSource: workspacePackage.supportsDevelopmentSource
+			installPath: packageDir
 		});
 	}
 	return matches;
@@ -5772,35 +5716,6 @@ const findWorkspacePackageForInstallRecord = (installRecord, workspacePackages,
 	if (installPathCandidates.size === 0) return;
 	return workspacePackages.find((workspacePackage) => installPathCandidates.has(path.resolve(workspacePackage.dir)));
 };
-const buildDevelopmentSourceEntryDefaults = (config, workspacePackages, installedPluginMatches) => {
-	const packageByName = new Map(workspacePackages.map((entry) => [entry.packageName, entry]));
-	const nextEntries = { ...config.plugins.entries ?? {} };
-	let didDefaultDevelopmentSource = false;
-	for (const installedPlugin of installedPluginMatches) {
-		if (!installedPlugin.supportsDevelopmentSource) continue;
-		const existingEntry = nextEntries[installedPlugin.pluginId];
-		if (existingEntry?.source) continue;
-		nextEntries[installedPlugin.pluginId] = {
-			...existingEntry,
-			source: "development"
-		};
-		didDefaultDevelopmentSource = true;
-	}
-	for (const [pluginId, installRecord] of Object.entries(config.plugins.installs ?? {})) {
-		if (!findWorkspacePackageForInstallRecord(installRecord, workspacePackages, packageByName)?.supportsDevelopmentSource) continue;
-		const existingEntry = nextEntries[pluginId];
-		if (existingEntry?.source) continue;
-		nextEntries[pluginId] = {
-			...existingEntry,
-			source: "development"
-		};
-		didDefaultDevelopmentSource = true;
-	}
-	return {
-		didDefaultDevelopmentSource,
-		nextEntries
-	};
-};
 const resolveDevFirstPartyPluginLoadPaths = (config, workspaceExtensionsDir) => {
 	const rootDir = resolveDevFirstPartyPluginDir(workspaceExtensionsDir);
 	if (!rootDir) return [];
@@ -5850,18 +5765,15 @@ const resolveDevFirstPartyPluginInstallRoots = (config, workspaceExtensionsDir)
 const applyDevFirstPartyPluginLoadPaths = (config, workspaceExtensionsDir) => {
 	const rootDir = resolveDevFirstPartyPluginDir(workspaceExtensionsDir);
 	if (!rootDir) return config;
-	const workspacePackages = readWorkspacePluginPackages(rootDir);
-	if (workspacePackages.length === 0) return config;
-	const installedPluginMatches = readInstalledFirstPartyPluginMatches(rootDir);
+	if (readWorkspacePluginPackages(rootDir).length === 0) return config;
+	readInstalledFirstPartyPluginMatches(rootDir);
 	const devLoadPaths = resolveDevFirstPartyPluginLoadPaths(config, rootDir);
 	if (devLoadPaths.length === 0) return config;
 	const mergedLoadPaths = mergeLoadPaths$1(Array.isArray(config.plugins.load?.paths) ? config.plugins.load.paths.filter((entry) => typeof entry === "string" && entry.trim().length > 0) : [], devLoadPaths);
-	const { didDefaultDevelopmentSource, nextEntries } = buildDevelopmentSourceEntryDefaults(config, workspacePackages, installedPluginMatches);
 	return {
 		...config,
 		plugins: {
 			...config.plugins,
-			entries: didDefaultDevelopmentSource ? nextEntries : config.plugins.entries,
 			load: {
 				...config.plugins.load,
 				paths: mergedLoadPaths
@@ -5872,10 +5784,10 @@ const applyDevFirstPartyPluginLoadPaths = (config, workspaceExtensionsDir) => {
 //#endregion
 //#region src/cli/commands/plugin/development-source/dev-plugin-overrides.utils.ts
 const DEV_PLUGIN_OVERRIDES_ENV = "NEXTCLAW_DEV_PLUGIN_OVERRIDES";
-function isRecord$6(value) {
+function isRecord$7(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function readOptionalString$6(value) {
+function readOptionalString$7(value) {
 	if (typeof value !== "string") return;
 	return value.trim() || void 0;
 }
@@ -5901,9 +5813,9 @@ function assertOverridePluginReadable(override) {
 	}
 }
 function readOverrideRecord(value, index) {
-	if (!isRecord$6(value)) throw new Error(`[dev-plugin-override] override[${index}] must be an object`);
-	const pluginId = readOptionalString$6(value.pluginId);
-	const pluginPath = readOptionalString$6(value.pluginPath);
+	if (!isRecord$7(value)) throw new Error(`[dev-plugin-override] override[${index}] must be an object`);
+	const pluginId = readOptionalString$7(value.pluginId);
+	const pluginPath = readOptionalString$7(value.pluginPath);
 	const source = value.source === "development" ? "development" : "production";
 	if (!pluginId || !pluginPath) throw new Error(`[dev-plugin-override] override[${index}] requires pluginId and pluginPath`);
 	const normalized = {
@@ -5960,7 +5872,7 @@ function resolveDevPluginOverrideInstallRoots(config, overrides) {
 	const installRoots = [];
 	for (const override of overrides) {
 		const installRecord = config.plugins.installs?.[override.pluginId];
-		const installPath = readOptionalString$6(installRecord?.installPath);
+		const installPath = readOptionalString$7(installRecord?.installPath);
 		if (!installPath || installRoots.includes(installPath)) continue;
 		installRoots.push(installPath);
 	}
@@ -8423,13 +8335,13 @@ var AgentCommands = class {
 };
 //#endregion
 //#region src/cli/commands/ncp/features/runtime/ncp-asset-tools.ts
-function readOptionalString$5(value) {
+function readOptionalString$6(value) {
 	if (typeof value !== "string") return null;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : null;
 }
 function readOptionalBase64Bytes(value) {
-	const base64 = readOptionalString$5(value);
+	const base64 = readOptionalString$6(value);
 	if (!base64) return null;
 	try {
 		return Buffer.from(base64, "base64");
@@ -8480,18 +8392,18 @@ var AssetPutTool = class {
 		this.contentBasePath = contentBasePath;
 	}
 	validateArgs = (args) => {
-		const path = readOptionalString$5(args.path);
-		const bytesBase64 = readOptionalString$5(args.bytesBase64);
-		const fileName = readOptionalString$5(args.fileName);
+		const path = readOptionalString$6(args.path);
+		const bytesBase64 = readOptionalString$6(args.bytesBase64);
+		const fileName = readOptionalString$6(args.fileName);
 		if (path && bytesBase64) return ["Provide either path, or bytesBase64 + fileName, not both."];
 		if (path) return [];
 		if (bytesBase64) return fileName ? [] : ["fileName is required when using bytesBase64."];
 		return ["Provide either path, or bytesBase64 + fileName."];
 	};
 	execute = async (args) => {
-		const path = readOptionalString$5(args?.path);
-		const fileName = readOptionalString$5(args?.fileName);
-		const mimeType = readOptionalString$5(args?.mimeType);
+		const path = readOptionalString$6(args?.path);
+		const fileName = readOptionalString$6(args?.fileName);
+		const mimeType = readOptionalString$6(args?.mimeType);
 		const bytes = readOptionalBase64Bytes(args?.bytesBase64);
 		if (path) return {
 			ok: true,
@@ -8534,8 +8446,8 @@ var AssetExportTool = class {
 		this.assetStore = assetStore;
 	}
 	execute = async (args) => {
-		const assetUri = readOptionalString$5(args?.assetUri);
-		const targetPath = readOptionalString$5(args?.targetPath);
+		const assetUri = readOptionalString$6(args?.assetUri);
+		const targetPath = readOptionalString$6(args?.targetPath);
 		if (!assetUri || !targetPath) throw new Error("asset_export requires assetUri and targetPath.");
 		return {
 			ok: true,
@@ -8561,7 +8473,7 @@ var AssetStatTool = class {
 		this.contentBasePath = contentBasePath;
 	}
 	execute = async (args) => {
-		const assetUri = readOptionalString$5(args?.assetUri);
+		const assetUri = readOptionalString$6(args?.assetUri);
 		if (!assetUri) throw new Error("asset_stat requires assetUri.");
 		const record = await this.assetStore.statRecord(assetUri);
 		if (!record) return {
@@ -8593,11 +8505,11 @@ function normalizeString(value) {
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : null;
 }
-function isRecord$5(value) {
+function isRecord$6(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function cloneMetadata(value) {
-	return isRecord$5(value) ? structuredClone(value) : void 0;
+	return isRecord$6(value) ? structuredClone(value) : void 0;
 }
 function readStringArray(value) {
 	if (!Array.isArray(value)) return null;
@@ -9088,7 +9000,7 @@ function readRequiredString$1(params, key) {
 	if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${key} must be a non-empty string.`);
 	return value.trim();
 }
-function readOptionalString$4(params, key) {
+function readOptionalString$5(params, key) {
 	const value = params[key];
 	if (typeof value !== "string") return;
 	const trimmed = value.trim();
@@ -9149,14 +9061,14 @@ var SessionRequestTool = class extends Tool {
 		const target = params.target;
 		if (!target || typeof target !== "object" || Array.isArray(target)) throw new Error("target must be an object.");
 		const task = readRequiredString$1(params, "task");
-		const notifyMode = readOptionalString$4(params, "notify")?.toLowerCase();
+		const notifyMode = readOptionalString$5(params, "notify")?.toLowerCase();
 		if (notifyMode !== "none" && notifyMode !== "final_reply") throw new Error("notify must be \"none\" or \"final_reply\".");
 		return this.broker.requestSession({
 			sourceSessionId: this.sourceSessionId,
 			sourceToolCallId: toolCallId,
 			targetSessionId: readRequiredString$1(target, "session_id"),
 			task,
-			title: readOptionalString$4(params, "title"),
+			title: readOptionalString$5(params, "title"),
 			notify: notifyMode,
 			handoffDepth: this.handoffDepth
 		});
@@ -9168,13 +9080,13 @@ function readRequiredString(value, key) {
 	if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${key} must be a non-empty string.`);
 	return value.trim();
 }
-function readOptionalString$3(value) {
+function readOptionalString$4(value) {
 	if (typeof value !== "string") return;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : void 0;
 }
 function readSpawnScope(value) {
-	const normalized = readOptionalString$3(value)?.toLowerCase();
+	const normalized = readOptionalString$4(value)?.toLowerCase();
 	if (!normalized || normalized === "standalone") return "standalone";
 	if (normalized === "child") return "child";
 	throw new Error("scope must be \"standalone\" or \"child\".");
@@ -9182,7 +9094,7 @@ function readSpawnScope(value) {
 function readSpawnRequestOptions(value) {
 	if (typeof value === "undefined") return;
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("request must be an object.");
-	const notifyMode = readOptionalString$3(value.notify)?.toLowerCase();
+	const notifyMode = readOptionalString$4(value.notify)?.toLowerCase();
 	if (notifyMode === "none" || notifyMode === "final_reply") return { notify: notifyMode };
 	throw new Error("request.notify must be \"none\" or \"final_reply\".");
 }
@@ -9260,21 +9172,21 @@ var SessionSpawnTool = class extends Tool {
 			sourceToolCallId: toolCallId,
 			sourceSessionMetadata: this.sourceSessionMetadata,
 			task,
-			title: readOptionalString$3(rawTitle),
-			agentId: readOptionalString$3(rawAgentId),
-			model: readOptionalString$3(rawModel),
-			runtime: readOptionalString$3(rawRuntime),
+			title: readOptionalString$4(rawTitle),
+			agentId: readOptionalString$4(rawAgentId),
+			model: readOptionalString$4(rawModel),
+			runtime: readOptionalString$4(rawRuntime),
 			handoffDepth: this.handoffDepth,
 			...parentSessionId ? { parentSessionId } : {},
 			notify: request.notify
 		});
 		const session = this.sessionCreationService.createSession({
 			task,
-			title: readOptionalString$3(rawTitle),
+			title: readOptionalString$4(rawTitle),
 			sourceSessionMetadata: this.sourceSessionMetadata,
-			agentId: readOptionalString$3(rawAgentId),
-			model: readOptionalString$3(rawModel),
-			runtime: readOptionalString$3(rawRuntime),
+			agentId: readOptionalString$4(rawAgentId),
+			model: readOptionalString$4(rawModel),
+			runtime: readOptionalString$4(rawRuntime),
 			...parentSessionId ? { parentSessionId } : {}
 		});
 		return {
@@ -9298,10 +9210,10 @@ var SessionSpawnTool = class extends Tool {
 //#endregion
 //#region src/cli/commands/ncp/nextclaw-ncp-tool-registry.ts
 function toToolParams(args) {
-	if (isRecord$5(args)) return args;
+	if (isRecord$6(args)) return args;
 	if (typeof args === "string") try {
 		const parsed = JSON.parse(args);
-		return isRecord$5(parsed) ? parsed : {};
+		return isRecord$6(parsed) ? parsed : {};
 	} catch {
 		return {};
 	}
@@ -9479,14 +9391,14 @@ function readAccountIdForHints(metadata, sessionMetadata) {
 //#endregion
 //#region src/cli/commands/ncp/nextclaw-ncp-context-builder.ts
 const TIME_HINT_TRIGGER_PATTERNS = [/\b(now|right now|current time|what time|today|tonight|tomorrow|yesterday|this morning|this afternoon|this evening|date)\b/i, /(现在|此刻|当前时间|现在几点|几点了|今天|今晚|今早|今晨|明天|昨天|日期)/];
-function isRecord$4(value) {
+function isRecord$5(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function mergeInputMetadata(input) {
-	const messageMetadata = input.messages.slice().reverse().find((message) => isRecord$4(message.metadata))?.metadata;
+	const messageMetadata = input.messages.slice().reverse().find((message) => isRecord$5(message.metadata))?.metadata;
 	return {
-		...isRecord$4(messageMetadata) ? structuredClone(messageMetadata) : {},
-		...isRecord$4(input.metadata) ? structuredClone(input.metadata) : {}
+		...isRecord$5(messageMetadata) ? structuredClone(messageMetadata) : {},
+		...isRecord$5(input.metadata) ? structuredClone(input.metadata) : {}
 	};
 }
 const REQUESTED_SKILLS_METADATA_READER = new RequestedSkillsMetadataReader();
@@ -10110,7 +10022,7 @@ const CHILD_SESSION_PARENT_METADATA_KEY = "parent_session_id";
 const CHILD_SESSION_REQUEST_METADATA_KEY = "spawned_by_request_id";
 const CHILD_SESSION_LIFECYCLE_METADATA_KEY = "session_lifecycle";
 const CHILD_SESSION_PROMOTED_METADATA_KEY = "child_session_promoted";
-function readOptionalString$2(value) {
+function readOptionalString$3(value) {
 	if (typeof value !== "string") return null;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : null;
@@ -10150,14 +10062,14 @@ function buildSessionId() {
 	return `ncp-${Date.now().toString(36)}-${randomUUID().replace(/-/g, "").slice(0, 8)}`;
 }
 function resolveSessionAgentId(params) {
-	return readOptionalString$2(params.agentId) ?? resolveDefaultAgentProfileId(params.getConfig());
+	return readOptionalString$3(params.agentId) ?? resolveDefaultAgentProfileId(params.getConfig());
 }
 function resolveSessionTitle(params) {
-	return readOptionalString$2(params.title) ?? summarizeTask(params.task);
+	return readOptionalString$3(params.title) ?? summarizeTask(params.task);
 }
 function resolveSessionType(params) {
 	const { metadata, runtime, sessionType } = params;
-	return readOptionalString$2(runtime) ?? readOptionalString$2(metadata.runtime) ?? readOptionalString$2(sessionType) ?? readOptionalString$2(metadata.session_type) ?? DEFAULT_SESSION_TYPE;
+	return readOptionalString$3(runtime) ?? readOptionalString$3(metadata.runtime) ?? readOptionalString$3(sessionType) ?? readOptionalString$3(metadata.session_type) ?? DEFAULT_SESSION_TYPE;
 }
 function applySessionOverrides(params) {
 	const { lifecycle, metadata, model, parentSessionId, projectRoot, requestId, sessionType, thinkingLevel, title } = params;
@@ -10170,15 +10082,15 @@ function applySessionOverrides(params) {
 		metadata[CHILD_SESSION_PROMOTED_METADATA_KEY] = false;
 	}
 	if (requestId) metadata[CHILD_SESSION_REQUEST_METADATA_KEY] = requestId;
-	if (readOptionalString$2(model)) {
+	if (readOptionalString$3(model)) {
 		metadata.model = model?.trim();
 		metadata.preferred_model = model?.trim();
 	}
-	if (readOptionalString$2(thinkingLevel)) {
+	if (readOptionalString$3(thinkingLevel)) {
 		metadata.thinking = thinkingLevel?.trim();
 		metadata.preferred_thinking = thinkingLevel?.trim();
 	}
-	if (readOptionalString$2(projectRoot)) metadata.project_root = projectRoot?.trim();
+	if (readOptionalString$3(projectRoot)) metadata.project_root = projectRoot?.trim();
 }
 var SessionCreationService = class {
 	constructor(sessionManager, getConfig, onSessionUpdated) {
@@ -10200,8 +10112,8 @@ var SessionCreationService = class {
 			task
 		});
 		const metadata = cloneInheritedMetadata(sourceSessionMetadata);
-		const parentSessionId = readOptionalString$2(rawParentSessionId);
-		const requestId = readOptionalString$2(rawRequestId);
+		const parentSessionId = readOptionalString$3(rawParentSessionId);
+		const requestId = readOptionalString$3(rawRequestId);
 		const sessionType = resolveSessionType({
 			runtime,
 			sessionType: requestedSessionType,
@@ -10254,12 +10166,12 @@ var SessionCreationService = class {
 		return true;
 	};
 	isChildSessionRecord = (metadata) => {
-		return Boolean(readOptionalString$2(metadata?.[CHILD_SESSION_PARENT_METADATA_KEY]));
+		return Boolean(readOptionalString$3(metadata?.[CHILD_SESSION_PARENT_METADATA_KEY]));
 	};
 };
 //#endregion
 //#region src/cli/commands/ncp/session-request/session-request-result.ts
-function readOptionalString$1(value) {
+function readOptionalString$2(value) {
 	if (typeof value !== "string") return null;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : null;
@@ -10280,7 +10192,7 @@ function extractSessionMessageText(message) {
 	return parts.join("\n\n");
 }
 function readParentSessionId(metadata) {
-	return readOptionalString$1(metadata?.["parent_session_id"]) ?? void 0;
+	return readOptionalString$2(metadata?.["parent_session_id"]) ?? void 0;
 }
 function buildSessionRequestToolResult(params) {
 	const { request, task, title, agentId, isChildSession, parentSessionId, spawnedByRequestId, message } = params;
@@ -10419,7 +10331,7 @@ var SessionRequestBroker = class {
 			sourceToolCallId,
 			targetSessionId: normalizedTargetSessionId,
 			task,
-			title: readOptionalString$1(title) ?? readOptionalString$1(targetSummary.metadata?.label) ?? summarizeSessionRequestTask(task),
+			title: readOptionalString$2(title) ?? readOptionalString$2(targetSummary.metadata?.label) ?? summarizeSessionRequestTask(task),
 			handoffDepth: handoffDepth ?? 0,
 			notify,
 			agentId: targetSummary.agentId,
@@ -10955,7 +10867,7 @@ var SessionSearchStoreService = class {
 };
 //#endregion
 //#region src/cli/commands/ncp/session-search/session-search-tool.service.ts
-function isRecord$3(value) {
+function isRecord$4(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function readOptionalInteger(value) {
@@ -11005,7 +10917,7 @@ var SessionSearchTool = class {
 		return issues;
 	};
 	execute = async (args) => {
-		if (!isRecord$3(args)) throw new Error("session_search requires an object argument.");
+		if (!isRecord$4(args)) throw new Error("session_search requires an object argument.");
 		const issues = this.validateArgs(args);
 		if (issues.length > 0) throw new Error(issues.join(" "));
 		return this.queryService.search({
@@ -11937,12 +11849,12 @@ function createContextWindowUpdatedEvent(params) {
 		}
 	};
 }
-function isRecord$2(value) {
+function isRecord$3(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function resolveNativeReasoningNormalizationMode(params) {
 	const runtimeEntry = params.config.agents.runtimes.entries.native?.config ?? params.config.ui.ncp.runtimes.native;
-	const runtimeMetadata = isRecord$2(runtimeEntry) ? runtimeEntry : {};
+	const runtimeMetadata = isRecord$3(runtimeEntry) ? runtimeEntry : {};
 	return readAssistantReasoningNormalizationModeFromMetadata(params.sessionMetadata) ?? readAssistantReasoningNormalizationMode(runtimeMetadata.reasoningNormalization) ?? readAssistantReasoningNormalizationMode(runtimeMetadata.reasoning_normalization) ?? readAssistantReasoningNormalizationMode(runtimeMetadata.reasoningNormalizationMode) ?? readAssistantReasoningNormalizationMode(runtimeMetadata.reasoning_normalization_mode) ?? "think-tags";
 }
 function createMcpRuntimeSupport(getConfig) {
@@ -14004,7 +13916,7 @@ var ServiceMarketplaceInstaller = class {
 };
 //#endregion
 //#region src/cli/shared/utils/marketplace/cli-subcommand-launch.utils.ts
-const require$2 = createRequire(import.meta.url);
+const require$3 = createRequire(import.meta.url);
 const TYPESCRIPT_EXTENSIONS$1 = new Set([
 	".ts",
 	".tsx",
@@ -14012,7 +13924,7 @@ const TYPESCRIPT_EXTENSIONS$1 = new Set([
 	".cts"
 ]);
 const isTypeScriptEntry = (entry) => TYPESCRIPT_EXTENSIONS$1.has(extname(entry).toLowerCase());
-const resolveTsxCliEntry = () => require$2.resolve("tsx/cli");
+const resolveTsxCliEntry = () => require$3.resolve("tsx/cli");
 const resolveCliAppEntryFromImportMeta$1 = (importMetaUrl) => {
 	const modulePath = fileURLToPath(importMetaUrl);
 	const cliRootIndex = modulePath.replace(/\\/g, "/").lastIndexOf("/cli/");
@@ -14369,6 +14281,27 @@ async function describeUnmanagedHealthyTargetMessage(params) {
 //#endregion
 //#region src/cli/shared/services/runtime/service-managed-startup.service.ts
 const { APP_NAME: APP_NAME$1, loadConfig: loadConfig$4 } = NextclawCore;
+function resolveManagedServiceReadySnapshot(params) {
+	const { snapshot, readLocalUiRuntimeState, isProcessRunningFn: providedIsProcessRunningFn } = params;
+	const localUiRuntimeState = (readLocalUiRuntimeState ?? localUiRuntimeStore.read)();
+	const isProcessRunningFn = providedIsProcessRunningFn ?? isProcessRunning;
+	if (!localUiRuntimeState || typeof localUiRuntimeState.pid !== "number" || !Number.isFinite(localUiRuntimeState.pid) || localUiRuntimeState.uiPort !== snapshot.uiPort || !isProcessRunningFn(localUiRuntimeState.pid)) return snapshot;
+	return {
+		...snapshot,
+		pid: localUiRuntimeState.pid,
+		uiUrl: localUiRuntimeState.uiUrl,
+		apiUrl: localUiRuntimeState.apiUrl,
+		uiHost: localUiRuntimeState.uiHost ?? snapshot.uiHost,
+		uiPort: localUiRuntimeState.uiPort ?? snapshot.uiPort
+	};
+}
+function resolveLauncherCliEntry(importMetaUrl) {
+	const modulePath = fileURLToPath(importMetaUrl);
+	const cliRootIndex = modulePath.replace(/\\/g, "/").lastIndexOf("/cli/");
+	if (cliRootIndex === -1) return fileURLToPath(new URL("../../../launcher/index.js", importMetaUrl));
+	const extension = extname(modulePath) || ".js";
+	return resolve(modulePath.slice(0, cliRootIndex + 5), "launcher", `index${extension}`);
+}
 function toObjectRecord(value) {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
 	return value;
@@ -14420,7 +14353,7 @@ function spawnManagedService(params) {
 	appendStartupStage(logPath, `start requested: ui=${uiConfig.host}:${uiConfig.port}, readinessTimeoutMs=${readinessTimeoutMs}`);
 	console.log(`Starting ${appName} background service (readiness timeout ${Math.ceil(readinessTimeoutMs / 1e3)}s)...`);
 	const cliLaunch = resolveCliSubcommandLaunch({
-		argvEntry: process.argv[1],
+		argvEntry: resolveLauncherCliEntry(import.meta.url),
 		importMetaUrl: import.meta.url,
 		cliArgs: [
 			"serve",
@@ -14432,7 +14365,7 @@ function spawnManagedService(params) {
 	const childArgs = [...process.execArgv, ...cliLaunch.args];
 	appendStartupStage(logPath, `spawning background process: ${cliLaunch.command} ${childArgs.join(" ")}`);
 	const child = spawn(cliLaunch.command, childArgs, {
-		env: process.env,
+		env: createTopLevelNextclawCommandEnv(process.env),
 		stdio: "ignore",
 		detached: true
 	});
@@ -14691,12 +14624,13 @@ var ManagedServiceCommandService = class {
 			return;
 		}
 		startup.child.unref();
+		const readySnapshot = resolveManagedServiceReadySnapshot({ snapshot: startup.snapshot });
 		await reportManagedServiceStart({
 			appName: APP_NAME$1,
 			state: writeReadyManagedServiceState({
 				readinessTimeoutMs: startup.readinessTimeoutMs,
 				readiness,
-				snapshot: startup.snapshot
+				snapshot: readySnapshot
 			}),
 			uiConfig,
 			uiUrl,
@@ -15199,6 +15133,179 @@ function createRemoteAccessHost(params) {
 	});
 }
 //#endregion
+//#region src/cli/shared/services/ui/npm-runtime-update-host.service.ts
+const INITIAL_DOWNLOAD_PROGRESS = {
+	downloadedBytes: 0,
+	totalBytes: null,
+	percent: null
+};
+var NpmRuntimeUpdateHost = class {
+	source = new NpmRuntimeUpdateSourceService();
+	layout = new NpmRuntimeBundleLayoutStore();
+	launcherVersion = getPackageVersion$1();
+	stateStore = new NpmRuntimeUpdateStateStore(this.layout.getStatePath(), { defaultChannel: this.source.resolveChannel(void 0, this.launcherVersion) });
+	bundleService = new NpmRuntimeBundleService({
+		layout: this.layout,
+		stateStore: this.stateStore,
+		launcherVersion: this.launcherVersion
+	});
+	updateService = new NpmRuntimeUpdateService({
+		layout: this.layout,
+		bundleService: this.bundleService,
+		launcherVersion: this.launcherVersion,
+		bundlePublicKey: this.source.resolveBundlePublicKey() ?? void 0
+	});
+	snapshot;
+	activeTask = null;
+	automaticSyncStarted = false;
+	constructor(deps) {
+		this.deps = deps;
+		this.snapshot = this.createManager().getSnapshot();
+		this.startAutomaticSync();
+	}
+	getState = async () => {
+		this.startAutomaticSync();
+		return this.snapshot;
+	};
+	checkForUpdates = async () => {
+		return this.startCheck({ autoDownload: false });
+	};
+	downloadUpdate = async () => {
+		return this.startDownload();
+	};
+	applyDownloadedUpdate = async () => {
+		if (this.activeTask) return this.snapshot;
+		this.setSnapshot({
+			...this.snapshot,
+			status: "applying",
+			progress: null,
+			errorMessage: null
+		});
+		try {
+			const snapshot = this.createManager().applyDownloadedUpdate();
+			this.setSnapshot(this.deps.applyRestartMode === "managed-service-restart" ? snapshot : {
+				...snapshot,
+				recoveryCommand: "Restart this NextClaw process to launch the downloaded runtime."
+			});
+			if (this.deps.applyRestartMode === "managed-service-restart") await requestManagedServiceRestart(this.deps.requestRestart, {
+				reason: "runtime update apply",
+				uiPort: this.deps.uiConfig.port
+			});
+			return this.snapshot;
+		} catch (error) {
+			this.setSnapshot(this.toFailedSnapshot(error));
+			throw error;
+		}
+	};
+	updatePreferences = async (preferences) => {
+		const nextState = this.stateStore.update((current) => ({
+			...current,
+			updatePreferences: {
+				...current.updatePreferences,
+				...preferences
+			}
+		}));
+		this.setSnapshot(this.createManager(nextState.channel).getSnapshot());
+		if (nextState.updatePreferences.automaticChecks) this.startAutomaticSync({ force: true });
+		return this.snapshot;
+	};
+	updateChannel = async (channel) => {
+		const nextState = this.stateStore.update((current) => ({
+			...current,
+			channel
+		}));
+		this.setSnapshot(this.createManager(nextState.channel).getSnapshot());
+		if (nextState.updatePreferences.automaticChecks) return this.startCheck({ autoDownload: nextState.updatePreferences.autoDownload });
+		return this.snapshot;
+	};
+	startAutomaticSync = (options = {}) => {
+		if (this.activeTask) return;
+		if (this.automaticSyncStarted && !options.force) return;
+		this.automaticSyncStarted = true;
+		const state = this.stateStore.read();
+		if (!state.updatePreferences.automaticChecks || state.downloadedVersion) return;
+		this.startCheck({ autoDownload: state.updatePreferences.autoDownload });
+	};
+	startCheck = async (options) => {
+		if (this.activeTask) return this.snapshot;
+		this.setSnapshot({
+			...this.createManager().getSnapshot(),
+			status: "checking",
+			progress: null,
+			errorMessage: null
+		});
+		this.activeTask = (async () => {
+			try {
+				const checkedSnapshot = await this.createManager().checkForUpdate();
+				this.setSnapshot(checkedSnapshot);
+				if (options.autoDownload && checkedSnapshot.status === "update-available") await this.runDownloadTask();
+			} catch (error) {
+				this.setSnapshot(this.toFailedSnapshot(error));
+			} finally {
+				this.activeTask = null;
+			}
+		})();
+		return this.snapshot;
+	};
+	startDownload = async () => {
+		if (this.activeTask) return this.snapshot;
+		this.setSnapshot({
+			...this.createManager().getSnapshot(),
+			status: "downloading",
+			progress: INITIAL_DOWNLOAD_PROGRESS,
+			errorMessage: null
+		});
+		this.activeTask = (async () => {
+			try {
+				await this.runDownloadTask();
+			} catch (error) {
+				this.setSnapshot(this.toFailedSnapshot(error));
+			} finally {
+				this.activeTask = null;
+			}
+		})();
+		return this.snapshot;
+	};
+	runDownloadTask = async () => {
+		const downloadedSnapshot = await this.createManager().downloadUpdate((progress) => {
+			this.setSnapshot({
+				...this.snapshot,
+				status: "downloading",
+				progress,
+				errorMessage: null
+			});
+		});
+		this.setSnapshot(downloadedSnapshot);
+	};
+	createManager = (channel = this.stateStore.read().channel) => {
+		return new NpmRuntimeUpdateManager({
+			layout: this.layout,
+			stateStore: this.stateStore,
+			bundleService: this.bundleService,
+			updateService: this.updateService,
+			resolveManifestUrl: (resolvedChannel) => this.source.resolveManifestUrl(resolvedChannel),
+			launcherVersion: this.launcherVersion,
+			channel
+		});
+	};
+	toFailedSnapshot = (error) => {
+		return {
+			...this.createManager().getSnapshot(),
+			status: "failed",
+			progress: null,
+			errorMessage: error instanceof Error ? error.message : String(error ?? "Unknown error")
+		};
+	};
+	setSnapshot = (snapshot) => {
+		this.snapshot = snapshot;
+		nextclaw.eventBus.emit(eventKeys.runtimeUpdateSnapshot, snapshot, { source: "backend" });
+		return snapshot;
+	};
+};
+function createNpmRuntimeUpdateHost(params) {
+	return new NpmRuntimeUpdateHost(params);
+}
+//#endregion
 //#region src/cli/shared/stores/pending-restart.store.ts
 const clonePendingRestartState = (state) => {
 	if (!state) return null;
@@ -15319,13 +15426,26 @@ function createRuntimeControlHost(params) {
 }
 //#endregion
 //#region src/cli/shared/services/ui/service-ui-hosts.service.ts
+function resolveApplyRestartMode(uiPort) {
+	const serviceState = managedServiceStateStore.read();
+	if (serviceState?.pid === process.pid) return "managed-service-restart";
+	if (process.env.NEXTCLAW_RUNTIME_BUNDLE_CHILD === "1" && typeof serviceState?.uiPort === "number" && serviceState.uiPort === uiPort) return "managed-service-restart";
+	return "manual-process-restart";
+}
 function createServiceUiHosts(params) {
+	const { requestRestart, serviceCommands, uiConfig } = params;
+	const applyRestartMode = resolveApplyRestartMode(uiConfig.port);
 	return {
 		remoteAccess: createRemoteAccessHost(params),
 		runtimeControl: createRuntimeControlHost({
-			serviceCommands: params.serviceCommands,
-			requestRestart: params.requestRestart,
-			uiConfig: params.uiConfig
+			serviceCommands,
+			requestRestart,
+			uiConfig
+		}),
+		runtimeUpdate: process.env.NEXTCLAW_DISABLE_RUNTIME_UPDATE_HOST === "1" ? void 0 : createNpmRuntimeUpdateHost({
+			applyRestartMode,
+			requestRestart,
+			uiConfig
 		})
 	};
 }
@@ -15665,6 +15785,9 @@ var ConfigReloader = class {
 	setReloadMcp(callback) {
 		this.options.reloadMcp = callback;
 	}
+	setReloadCompanion(callback) {
+		this.options.reloadCompanion = callback;
+	}
 	async applyReloadPlan(nextConfig) {
 		const changedPaths = diffConfigPaths(this.currentConfig, nextConfig);
 		if (!changedPaths.length) return;
@@ -15686,6 +15809,13 @@ var ConfigReloader = class {
 			});
 			console.log("Config reload: MCP servers reloaded.");
 		}
+		if (plan.reloadCompanion) {
+			await this.reloadCompanion({
+				config: nextConfig,
+				changedPaths
+			});
+			console.log("Config reload: companion setting applied.");
+		}
 		if (plan.restartChannels || reloadPluginsResult?.restartChannels) {
 			await this.reloadChannels(nextConfig, { start: true });
 			console.log("Config reload: channels restarted.");
@@ -15781,6 +15911,10 @@ var ConfigReloader = class {
 		if (!this.options.reloadMcp) return;
 		await this.options.reloadMcp(params);
 	}
+	async reloadCompanion(params) {
+		if (!this.options.reloadCompanion) return;
+		await this.options.reloadCompanion(params);
+	}
 };
 //#endregion
 //#region src/cli/shared/services/gateway/cron-job-handler.service.ts
@@ -16161,11 +16295,11 @@ function createSystemSessionUpdatedPublisher(params) {
 }
 async function startUiShell(params) {
 	logStartupTrace("service.start_ui_shell.begin");
-	const { applyLiveConfigReload, configPath, cronService, getBootstrapStatus, getPluginChannelBindings, getPluginUiMetadata, initializeAgentHomeDirectory, marketplace, ncpSessionService, openBrowserWindow, productVersion, remoteAccess, runtimeControl, uiConfig, uiStaticDir } = params;
+	const { applyLiveConfigReload, configPath, cronService, getBootstrapStatus, getPluginChannelBindings, getPluginUiMetadata, initializeAgentHomeDirectory, marketplace, ncpSessionService, openBrowserWindow, productVersion, remoteAccess, runtimeControl, runtimeUpdate, uiConfig, uiStaticDir } = params;
 	if (!uiConfig.enabled) return null;
 	let publishUiEvent = null;
 	const deferredNcpAgent = createDeferredUiNcpAgent();
-	const uiServer = startUiServer({
+	const uiServer = await startUiServer({
 		host: uiConfig.host,
 		port: uiConfig.port,
 		configPath,
@@ -16177,6 +16311,7 @@ async function startUiShell(params) {
 		marketplace,
 		remoteAccess,
 		runtimeControl,
+		runtimeUpdate,
 		getBootstrapStatus,
 		getPluginChannelBindings,
 		getPluginUiMetadata,
@@ -16779,17 +16914,17 @@ function readStringList(value) {
 	if (!Array.isArray(value)) return [];
 	return value.map((entry) => typeof entry === "string" ? entry.trim() : "").filter(Boolean);
 }
-function readOptionalString(value) {
+function readOptionalString$1(value) {
 	if (typeof value !== "string") return;
 	return value.trim() || void 0;
 }
 function resolvePluginRuntimeAttachments(ctx) {
 	const mediaPaths = readStringList(ctx.MediaPaths);
 	const mediaUrls = readStringList(ctx.MediaUrls);
-	const fallbackPath = readOptionalString(ctx.MediaPath);
-	const fallbackUrl = readOptionalString(ctx.MediaUrl);
+	const fallbackPath = readOptionalString$1(ctx.MediaPath);
+	const fallbackUrl = readOptionalString$1(ctx.MediaUrl);
 	const mediaTypes = readStringList(ctx.MediaTypes);
-	const fallbackType = readOptionalString(ctx.MediaType);
+	const fallbackType = readOptionalString$1(ctx.MediaType);
 	const entryCount = Math.max(mediaPaths.length, mediaUrls.length, fallbackPath ? 1 : 0, fallbackUrl ? 1 : 0);
 	const attachments = [];
 	for (let index = 0; index < entryCount; index += 1) {
@@ -16812,7 +16947,7 @@ function resolvePluginRuntimeAttachments(ctx) {
 //#region src/cli/shared/services/plugin/service-plugin-reload.service.ts
 async function reloadServicePlugins(params) {
 	const nextWorkspace = getWorkspacePath(params.nextConfig.agents.defaults.workspace);
-	const nextPluginRegistry = loadPluginRegistry(params.nextConfig, nextWorkspace);
+	const nextPluginRegistry = await loadPluginRegistryProgressively(params.nextConfig, nextWorkspace);
 	const nextExtensionRegistry = toExtensionRegistry(nextPluginRegistry);
 	const nextPluginChannelBindings = getPluginChannelBindings(nextPluginRegistry);
 	const shouldRestartChannels = shouldRestartChannelsForPluginReload({
@@ -16868,30 +17003,52 @@ function applyGatewayRuntimeCapabilityState(params) {
 	params.state.extensionRegistry = params.next.extensionRegistry;
 	params.state.pluginChannelBindings = params.next.pluginChannelBindings;
 }
+async function applyGatewayPluginReload(params) {
+	const result = await reloadServicePlugins({
+		nextConfig: params.nextConfig,
+		changedPaths: params.changedPaths,
+		pluginRegistry: params.state.pluginRegistry,
+		extensionRegistry: params.state.extensionRegistry,
+		pluginChannelBindings: params.state.pluginChannelBindings,
+		pluginGatewayHandles: params.state.pluginGatewayHandles,
+		pluginGatewayLogger,
+		logPluginGatewayDiagnostics
+	});
+	applyGatewayRuntimeCapabilityState({
+		gateway: params.gateway,
+		state: params.state,
+		next: {
+			pluginRegistry: result.pluginRegistry,
+			extensionRegistry: result.extensionRegistry,
+			pluginChannelBindings: result.pluginChannelBindings
+		}
+	});
+	params.state.pluginUiMetadata = getPluginUiMetadataFromRegistry(result.pluginRegistry);
+	params.state.pluginGatewayHandles = result.pluginGatewayHandles;
+	params.getLiveUiNcpAgent()?.applyExtensionRegistry?.(result.extensionRegistry);
+	return { restartChannels: result.restartChannels };
+}
+async function reloadGatewayPluginRuntimeForChanges(params) {
+	const nextConfig = resolveConfigSecrets$2(loadConfig$2(), { configPath: params.gateway.runtimeConfigPath });
+	const result = await applyGatewayPluginReload({
+		gateway: params.gateway,
+		state: params.state,
+		getLiveUiNcpAgent: params.getLiveUiNcpAgent,
+		nextConfig,
+		changedPaths: params.changedPaths
+	});
+	if (result.restartChannels) await params.gateway.reloader.rebuildChannels(nextConfig, { start: true });
+	return result;
+}
 function configureGatewayPluginRuntime(params) {
 	params.gateway.reloader.setReloadPlugins(async ({ config: nextConfig, changedPaths }) => {
-		const result = await reloadServicePlugins({
-			nextConfig,
-			changedPaths,
-			pluginRegistry: params.state.pluginRegistry,
-			extensionRegistry: params.state.extensionRegistry,
-			pluginChannelBindings: params.state.pluginChannelBindings,
-			pluginGatewayHandles: params.state.pluginGatewayHandles,
-			pluginGatewayLogger,
-			logPluginGatewayDiagnostics
-		});
-		applyGatewayRuntimeCapabilityState({
+		const result = await applyGatewayPluginReload({
 			gateway: params.gateway,
 			state: params.state,
-			next: {
-				pluginRegistry: result.pluginRegistry,
-				extensionRegistry: result.extensionRegistry,
-				pluginChannelBindings: result.pluginChannelBindings
-			}
+			getLiveUiNcpAgent: params.getLiveUiNcpAgent,
+			nextConfig,
+			changedPaths
 		});
-		params.state.pluginUiMetadata = getPluginUiMetadataFromRegistry(result.pluginRegistry);
-		params.state.pluginGatewayHandles = result.pluginGatewayHandles;
-		params.getLiveUiNcpAgent()?.applyExtensionRegistry?.(result.extensionRegistry);
 		if (result.restartChannels) console.log("Config reload: plugin channel gateways restarted.");
 		return { restartChannels: result.restartChannels };
 	});
@@ -16962,8 +17119,282 @@ async function cleanupGatewayRuntime(params) {
 	setPluginRuntimeBridge(null);
 }
 //#endregion
+//#region src/cli/shared/services/plugin/service-plugin-dev-hot-reload.service.ts
+const DEV_PLUGIN_HOT_RELOAD_TARGETS_ENV = "NEXTCLAW_DEV_PLUGIN_HOT_RELOAD_TARGETS";
+function isRecord$2(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readOptionalString(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : null;
+}
+function normalizeWatchPaths(value) {
+	if (!Array.isArray(value)) return [];
+	const watchPaths = [];
+	for (const entry of value) {
+		const normalized = readOptionalString(entry);
+		if (!normalized) continue;
+		const resolvedPath = resolve(normalized);
+		if (!watchPaths.includes(resolvedPath)) watchPaths.push(resolvedPath);
+	}
+	return watchPaths;
+}
+function resolveDevPluginHotReloadTargets(rawValue = process.env[DEV_PLUGIN_HOT_RELOAD_TARGETS_ENV]) {
+	if (typeof rawValue !== "string" || rawValue.trim().length === 0) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse(rawValue);
+	} catch (error) {
+		throw new Error(`[dev-plugin-hot-reload] failed to parse ${DEV_PLUGIN_HOT_RELOAD_TARGETS_ENV}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!Array.isArray(parsed)) throw new Error(`[dev-plugin-hot-reload] ${DEV_PLUGIN_HOT_RELOAD_TARGETS_ENV} must be a JSON array`);
+	const seenPluginIds = /* @__PURE__ */ new Set();
+	const targets = [];
+	for (const entry of parsed) {
+		if (!isRecord$2(entry)) continue;
+		const pluginId = readOptionalString(entry.pluginId);
+		const pluginPath = readOptionalString(entry.pluginPath);
+		const watchPaths = normalizeWatchPaths(entry.watchPaths);
+		if (!pluginId || !pluginPath || watchPaths.length === 0) continue;
+		if (seenPluginIds.has(pluginId)) throw new Error(`[dev-plugin-hot-reload] duplicate plugin target for "${pluginId}"`);
+		seenPluginIds.add(pluginId);
+		targets.push({
+			pluginId,
+			pluginPath: resolve(pluginPath),
+			watchPaths
+		});
+	}
+	return targets;
+}
+function startDevPluginHotReloadWatcher(params) {
+	const targets = params.targets ?? resolveDevPluginHotReloadTargets();
+	if (targets.length === 0) return;
+	const pendingPluginIds = /* @__PURE__ */ new Set();
+	let flushTimer = null;
+	let reloadRunning = false;
+	let reloadPending = false;
+	const flushReload = async () => {
+		if (reloadRunning) {
+			reloadPending = true;
+			return;
+		}
+		const pluginIds = [...pendingPluginIds];
+		pendingPluginIds.clear();
+		if (pluginIds.length === 0) return;
+		reloadRunning = true;
+		try {
+			console.log(`[dev] Plugin dist updated: ${pluginIds.join(", ")}`);
+			await params.reloadPlugins(pluginIds);
+			console.log(`[dev] Plugin hot reload applied: ${pluginIds.join(", ")}`);
+		} catch (error) {
+			console.error(`[dev] Plugin hot reload failed: ${error instanceof Error ? error.message : String(error)}`);
+		} finally {
+			reloadRunning = false;
+			if (reloadPending || pendingPluginIds.size > 0) {
+				reloadPending = false;
+				await flushReload();
+			}
+		}
+	};
+	const scheduleReload = (pluginId) => {
+		pendingPluginIds.add(pluginId);
+		if (flushTimer) clearTimeout(flushTimer);
+		flushTimer = setTimeout(() => {
+			flushTimer = null;
+			flushReload();
+		}, 150);
+	};
+	const watcher = chokidar.watch(targets.flatMap((entry) => entry.watchPaths), {
+		ignoreInitial: true,
+		awaitWriteFinish: {
+			stabilityThreshold: 200,
+			pollInterval: 50
+		}
+	});
+	params.watcherRegistry.remember(watcher);
+	watcher.on("all", (_event, changedPath) => {
+		const normalizedChangedPath = resolve(changedPath);
+		for (const target of targets) if (target.watchPaths.some((watchPath) => normalizedChangedPath === watchPath || normalizedChangedPath.startsWith(`${watchPath}${sep}`))) scheduleReload(target.pluginId);
+	});
+	console.log(`[dev] Plugin hot reload watcher: ${targets.map((entry) => entry.pluginId).join(", ")}`);
+}
+function wrapStartChannelsWithDevPluginHotReload(params) {
+	return async () => {
+		await params.startChannels();
+		console.log(`[dev] Plugin hot reload watcher will arm after ${params.startupSettleMs}ms startup settle window.`);
+		setTimeout(() => {
+			if (!params.isRuntimeActive()) return;
+			startDevPluginHotReloadWatcher({
+				watcherRegistry: params.watcherRegistry,
+				reloadPlugins: params.reloadPlugins
+			});
+		}, params.startupSettleMs).unref?.();
+	};
+}
+//#endregion
+//#region src/cli/shared/stores/companion-runtime.store.ts
+var CompanionRuntimeStore = class {
+	get path() {
+		return resolve(getDataDir(), "run", "companion.json");
+	}
+	read = () => {
+		if (!existsSync(this.path)) return null;
+		try {
+			return JSON.parse(readFileSync(this.path, "utf-8"));
+		} catch {
+			return null;
+		}
+	};
+	write = (state) => {
+		mkdirSync(resolve(this.path, ".."), { recursive: true });
+		writeFileSync(this.path, JSON.stringify(state, null, 2));
+	};
+	clear = () => {
+		if (existsSync(this.path)) rmSync(this.path, { force: true });
+	};
+};
+const companionRuntimeStore = new CompanionRuntimeStore();
+//#endregion
+//#region src/cli/shared/services/ui/companion-runtime.service.ts
+const require$2 = createRequire(import.meta.url);
+var CompanionRuntimeService = class {
+	constructor(runtimeStore = companionRuntimeStore, uiDiscoveryService = localUiDiscoveryService) {
+		this.runtimeStore = runtimeStore;
+		this.uiDiscoveryService = uiDiscoveryService;
+	}
+	getRunningState = () => {
+		const state = this.runtimeStore.read();
+		if (!state) return null;
+		if (!isProcessRunning(state.pid)) {
+			this.runtimeStore.clear();
+			return null;
+		}
+		return state;
+	};
+	resolveDiscoveredBaseUrl = () => {
+		return this.uiDiscoveryService.resolveApiBase();
+	};
+	applyConfig = async (config) => {
+		if (!config.companion.enabled) {
+			await this.ensureStopped();
+			return;
+		}
+		await this.ensureStarted({ baseUrl: this.uiDiscoveryService.resolveLocalOrigin(config) });
+	};
+	updateEnabled = async (enabled, options = {}) => {
+		const config = loadConfig(getConfigPath());
+		const next = {
+			...config,
+			companion: {
+				...config.companion,
+				enabled
+			}
+		};
+		saveConfig(next, getConfigPath());
+		if (enabled) {
+			const explicitBaseUrl = options.baseUrl?.trim();
+			if (explicitBaseUrl) {
+				await this.ensureStarted({ baseUrl: explicitBaseUrl });
+				return next;
+			}
+			const discoveredBaseUrl = this.uiDiscoveryService.resolveApiBase();
+			if (discoveredBaseUrl) await this.ensureStarted({ baseUrl: discoveredBaseUrl });
+			return next;
+		}
+		await this.ensureStopped();
+		return next;
+	};
+	ensureStarted = async (options) => {
+		const baseUrl = options.baseUrl.trim().replace(/\/+$/, "");
+		const runningState = this.getRunningState();
+		if (runningState?.baseUrl === baseUrl) return runningState;
+		if (runningState) {
+			this.killProcess(runningState.pid, false);
+			this.runtimeStore.clear();
+		}
+		const launchSpec = this.resolveLaunchSpec();
+		const child = spawn(launchSpec.command, [
+			...launchSpec.args,
+			"--base-url",
+			baseUrl
+		], {
+			detached: true,
+			stdio: "ignore",
+			env: {
+				...process.env,
+				NEXTCLAW_COMPANION_RUNTIME_STATE_PATH: this.runtimeStore.path
+			}
+		});
+		child.unref();
+		return await this.waitForRunningState(baseUrl, child.pid ?? -1);
+	};
+	ensureStopped = async (options = {}) => {
+		const state = this.runtimeStore.read();
+		if (!state) return false;
+		if (!isProcessRunning(state.pid)) {
+			this.runtimeStore.clear();
+			return false;
+		}
+		this.killProcess(state.pid, options.force === true);
+		this.runtimeStore.clear();
+		return true;
+	};
+	printStatus = (options = {}) => {
+		const runningState = this.getRunningState();
+		const config = loadConfig(getConfigPath());
+		const view = runningState ? {
+			configuredEnabled: config.companion.enabled,
+			running: true,
+			...runningState
+		} : {
+			configuredEnabled: config.companion.enabled,
+			running: false
+		};
+		if (options.json) {
+			console.log(JSON.stringify(view, null, 2));
+			return;
+		}
+		if (!runningState) {
+			console.log(config.companion.enabled ? "Companion is enabled in config but is not running." : "Companion is disabled and not running.");
+			return;
+		}
+		console.log(`Companion is running (pid ${runningState.pid}) at ${runningState.baseUrl}. Configured enabled: ${config.companion.enabled ? "yes" : "no"}.`);
+	};
+	printStarted = (state) => {
+		console.log(`Started ${APP_NAME} companion (pid ${state.pid}) using ${state.baseUrl}.`);
+	};
+	printStopped = (stopped) => {
+		console.log(stopped ? "Stopped companion process." : "Companion is not running.");
+	};
+	killProcess = (pid, force) => {
+		process.kill(pid, force ? "SIGKILL" : "SIGTERM");
+	};
+	resolveLaunchSpec = () => {
+		const packageJsonPath = require$2.resolve("@nextclaw/companion/package.json");
+		const packageRoot = dirname(packageJsonPath);
+		const mainPath = resolve(packageRoot, "dist", "src", "main.js");
+		if (!existsSync(mainPath)) throw new Error(`Companion app build is missing at ${mainPath}. Build @nextclaw/companion first.`);
+		return {
+			command: createRequire(packageJsonPath)("electron"),
+			args: [packageRoot]
+		};
+	};
+	waitForRunningState = async (baseUrl, fallbackPid) => {
+		const timeoutAt = Date.now() + 5e3;
+		while (Date.now() < timeoutAt) {
+			const state = this.getRunningState();
+			if (state?.baseUrl === baseUrl) return state;
+			await new Promise((resolvePromise) => setTimeout(resolvePromise, 100));
+		}
+		throw new Error(fallbackPid > 0 ? `Companion started but did not report a live runtime state (launcher pid ${fallbackPid}).` : "Companion started but did not report a live runtime state.");
+	};
+};
+const companionRuntimeService = new CompanionRuntimeService();
+//#endregion
 //#region src/cli/shared/services/runtime/runtime-command.service.ts
 const { getApiBase, getConfigPath: getConfigPath$1, getProvider, getProviderName, getWorkspacePath: getWorkspacePath$1, loadConfig: loadConfig$1, LiteLLMProvider, MessageBus: MessageBus$1, resolveConfigSecrets: resolveConfigSecrets$1, SessionManager: SessionManager$1, parseAgentScopedSessionKey: parseAgentScopedSessionKey$1 } = NextclawCore;
+const DEV_PLUGIN_HOT_RELOAD_STARTUP_SETTLE_MS = 5e3;
 function createSkillsLoader(workspace) {
 	const ctor = NextclawCore.SkillsLoader;
 	if (!ctor) return null;
@@ -17008,38 +17439,16 @@ var RuntimeCommandService = class {
 			runCliSubcommand: (args) => this.runCliSubcommand(args),
 			installBuiltinSkill: (slug, force) => this.installBuiltinMarketplaceSkill(slug, force)
 		}).createInstaller();
-		const { remoteAccess, runtimeControl } = createServiceUiHosts({
-			serviceCommands: this,
-			requestRestart: this.deps.requestRestart,
-			uiConfig: shellContext.uiConfig,
-			remoteModule: shellContext.remoteModule
-		});
-		const uiStartup = await measureStartupAsync("service.start_ui_shell", async () => await startUiShell({
-			uiConfig: shellContext.uiConfig,
-			uiStaticDir: shellContext.uiStaticDir,
-			cronService: shellContext.cron,
-			getConfig: getRuntimeConfig,
-			configPath: getConfigPath$1(),
-			productVersion: getPackageVersion$1(),
-			getPluginChannelBindings: () => runtimeState?.pluginChannelBindings ?? [],
-			getPluginUiMetadata: () => runtimeState?.pluginUiMetadata ?? [],
-			marketplace: {
-				apiBaseUrl: process.env.NEXTCLAW_MARKETPLACE_API_BASE,
-				installer: marketplaceInstaller
-			},
-			remoteAccess,
-			runtimeControl,
-			getBootstrapStatus: () => bootstrapStatus.getStatus(),
-			openBrowserWindow: shellContext.uiConfig.open,
+		const uiStartup = await this.startGatewayUiShell({
+			shellContext,
 			applyLiveConfigReload,
-			ncpSessionService: ncpSessionRealtimeBridge.sessionService,
-			initializeAgentHomeDirectory: this.deps.initializeAgentHomeDirectory
-		}));
-		finalizeLocalUiStartup({
-			uiStartup,
-			setUiEventPublisher: (publish) => ncpSessionRealtimeBridge.setUiEventPublisher(publish),
-			uiConfig: shellContext.uiConfig
+			bootstrapStatus,
+			marketplaceInstaller,
+			ncpSessionRealtimeBridge,
+			getRuntimeConfig,
+			getRuntimeState: () => runtimeState
 		});
+		await companionRuntimeService.applyConfig(shellContext.config);
 		bootstrapStatus.markShellReady();
 		await setImmediate$1();
 		const gateway = measureStartupSync("service.create_gateway_startup_context", () => createGatewayStartupContext({
@@ -17057,33 +17466,14 @@ var RuntimeCommandService = class {
 		const loadGatewayConfig = () => resolveConfigSecrets$1(loadConfig$1(), { configPath: gateway.runtimeConfigPath });
 		const gatewayRuntimeState = createGatewayRuntimeState(gateway);
 		runtimeState = gatewayRuntimeState;
-		uiStartup?.publish({
-			type: "config.updated",
-			payload: { path: "channels" }
+		gateway.reloader.setReloadCompanion(async ({ config: nextConfig }) => {
+			await companionRuntimeService.applyConfig(nextConfig);
 		});
-		uiStartup?.publish({
-			type: "config.updated",
-			payload: { path: "plugins" }
-		});
-		configureGatewayPluginRuntime({
+		await this.hydrateGatewayRuntime({
 			gateway,
-			state: gatewayRuntimeState,
-			getLiveUiNcpAgent: () => this.liveUiNcpAgent
+			gatewayRuntimeState,
+			uiStartup
 		});
-		console.log("✓ Capability hydration: scheduled in background");
-		await measureStartupAsync("service.start_gateway_support_services", async () => await startGatewayRuntimeSupport({
-			cronJobs: gateway.cron.status().jobs,
-			remoteModule: gateway.remoteModule,
-			watchConfigFile: () => watchServiceConfigFile({
-				configPath: resolve(getConfigPath$1()),
-				watcherRegistry: this.fileWatchers,
-				scheduleReload: (reason) => gateway.reloader.scheduleReload(reason)
-			}),
-			startCron: () => gateway.cron.start(),
-			cronStorePath: resolve(join(NextclawCore.getDataDir(), "cron", "jobs.json")),
-			reloadCronStore: () => gateway.cron.reloadFromStore(),
-			watcherRegistry: this.fileWatchers
-		}));
 		const deferredGatewayStartupHooks = createDeferredGatewayStartupHooks({
 			uiStartup,
 			gateway,
@@ -17098,6 +17488,20 @@ var RuntimeCommandService = class {
 				sessionManager: gateway.sessionManager
 			})
 		});
+		deferredGatewayStartupHooks.startChannels = wrapStartChannelsWithDevPluginHotReload({
+			startChannels: deferredGatewayStartupHooks.startChannels,
+			watcherRegistry: this.fileWatchers,
+			isRuntimeActive: () => Boolean(this.applyLiveConfigReload),
+			reloadPlugins: async (pluginIds) => {
+				await reloadGatewayPluginRuntimeForChanges({
+					gateway,
+					state: gatewayRuntimeState,
+					getLiveUiNcpAgent: () => this.liveUiNcpAgent,
+					changedPaths: pluginIds.map((pluginId) => `plugins.entries.${pluginId}.source`)
+				});
+			},
+			startupSettleMs: DEV_PLUGIN_HOT_RELOAD_STARTUP_SETTLE_MS
+		});
 		await runConfiguredGatewayRuntime({
 			uiStartup,
 			bootstrapStatus,
@@ -17125,14 +17529,84 @@ var RuntimeCommandService = class {
 					this.applyLiveConfigReload = null;
 					this.liveUiNcpAgent = null;
 				},
-				clearRealtimeBridge: () => ncpSessionRealtimeBridge.clear(),
+				clearRealtimeBridge: () => {
+					ncpSessionRealtimeBridge.clear();
+				},
 				uiStartup,
 				remoteModule: gateway.remoteModule,
 				runtimeState
 			})
 		});
+		await companionRuntimeService.ensureStopped();
 		logStartupTrace("service.start_gateway.end");
 	};
+	startGatewayUiShell = async (params) => {
+		const { applyLiveConfigReload, bootstrapStatus, getRuntimeConfig, getRuntimeState, marketplaceInstaller, ncpSessionRealtimeBridge, shellContext } = params;
+		const { remoteAccess, runtimeControl, runtimeUpdate } = createServiceUiHosts({
+			serviceCommands: this,
+			requestRestart: this.deps.requestRestart,
+			uiConfig: shellContext.uiConfig,
+			remoteModule: shellContext.remoteModule
+		});
+		const uiStartup = await measureStartupAsync("service.start_ui_shell", async () => await startUiShell({
+			uiConfig: shellContext.uiConfig,
+			uiStaticDir: shellContext.uiStaticDir,
+			cronService: shellContext.cron,
+			getConfig: getRuntimeConfig,
+			configPath: getConfigPath$1(),
+			productVersion: getPackageVersion$1(),
+			getPluginChannelBindings: () => getRuntimeState()?.pluginChannelBindings ?? [],
+			getPluginUiMetadata: () => getRuntimeState()?.pluginUiMetadata ?? [],
+			marketplace: {
+				apiBaseUrl: process.env.NEXTCLAW_MARKETPLACE_API_BASE,
+				installer: marketplaceInstaller
+			},
+			remoteAccess,
+			runtimeControl,
+			runtimeUpdate,
+			getBootstrapStatus: () => bootstrapStatus.getStatus(),
+			openBrowserWindow: shellContext.uiConfig.open,
+			applyLiveConfigReload,
+			ncpSessionService: ncpSessionRealtimeBridge.sessionService,
+			initializeAgentHomeDirectory: this.deps.initializeAgentHomeDirectory
+		}));
+		finalizeLocalUiStartup({
+			uiStartup,
+			setUiEventPublisher: (publish) => ncpSessionRealtimeBridge.setUiEventPublisher(publish),
+			uiConfig: shellContext.uiConfig
+		});
+		return uiStartup;
+	};
+	hydrateGatewayRuntime = async (params) => {
+		const { gateway, gatewayRuntimeState, uiStartup } = params;
+		uiStartup?.publish({
+			type: "config.updated",
+			payload: { path: "channels" }
+		});
+		uiStartup?.publish({
+			type: "config.updated",
+			payload: { path: "plugins" }
+		});
+		configureGatewayPluginRuntime({
+			gateway,
+			state: gatewayRuntimeState,
+			getLiveUiNcpAgent: () => this.liveUiNcpAgent
+		});
+		console.log("✓ Capability hydration: scheduled in background");
+		await measureStartupAsync("service.start_gateway_support_services", async () => await startGatewayRuntimeSupport({
+			cronJobs: gateway.cron.status().jobs,
+			remoteModule: gateway.remoteModule,
+			watchConfigFile: () => watchServiceConfigFile({
+				configPath: resolve(getConfigPath$1()),
+				watcherRegistry: this.fileWatchers,
+				scheduleReload: (reason) => gateway.reloader.scheduleReload(reason)
+			}),
+			startCron: () => gateway.cron.start(),
+			cronStorePath: resolve(join(NextclawCore.getDataDir(), "cron", "jobs.json")),
+			reloadCronStore: () => gateway.cron.reloadFromStore(),
+			watcherRegistry: this.fileWatchers
+		}));
+	};
 	normalizeOptionalString = (value) => {
 		if (typeof value !== "string") return;
 		return value.trim() || void 0;
@@ -18167,7 +18641,7 @@ var MacosLaunchAgentAutostartService = class {
 			`    <string>${this.escapeXml(homeDir)}</string>`,
 			"  </dict>",
 			"  <key>RunAtLoad</key><true/>",
-			"  <key>KeepAlive</key><true/>",
+			"  <key>KeepAlive</key><false/>",
 			`  <key>StandardOutPath</key><string>${this.escapeXml(stdoutPath)}</string>`,
 			`  <key>StandardErrorPath</key><string>${this.escapeXml(stderrPath)}</string>`,
 			"</dict>",
@@ -19035,6 +19509,30 @@ var RuntimeRestartRequestService = class {
 	};
 };
 //#endregion
+//#region src/cli/shared/utils/runtime-helpers.ts
+function resolveSkillsInstallWorkdir(params) {
+	if (params.explicitWorkdir) return expandHome(params.explicitWorkdir);
+	return getWorkspacePath(params.configuredWorkspace);
+}
+function parseStartTimeoutMs(value) {
+	if (value === void 0) return;
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed <= 0) {
+		console.error("Invalid --start-timeout value. Provide milliseconds (e.g. 45000).");
+		process.exit(1);
+	}
+	return Math.floor(parsed);
+}
+function resolveManagedServiceUiOverrides(params) {
+	const uiOverrides = {
+		enabled: true,
+		host: params.forcedPublicHost,
+		open: false
+	};
+	if (params.uiPort) uiOverrides.port = Number(params.uiPort);
+	return uiOverrides;
+}
+//#endregion
 //#region src/cli/commands/skills/marketplace-command-options.utils.ts
 function buildMarketplacePublishOptions(options) {
 	const { apiBaseUrl, author, description, dir, homepage, meta, name, packageName, publishedAt, scope, slug, sourceRepo, summary, tag, token, updatedAt } = options;
@@ -20079,17 +20577,31 @@ var RestartCommands = class {
 			uiPort: opts.uiPort,
 			forcedPublicHost: this.deps.forcedPublicHost
 		});
+		const targetUi = resolveUiConfig(loadConfig(), uiOverrides);
 		const state = managedServiceStateStore.read();
 		if (state && isProcessRunning(state.pid)) {
 			console.log(`Restarting ${APP_NAME}...`);
 			await this.deps.runtimeCommandService.stopService();
 		} else {
+			const foregroundRuntime = localUiRuntimeStore.read();
+			const foregroundMatchesTarget = Boolean(foregroundRuntime && isProcessRunning(foregroundRuntime.pid) && foregroundRuntime.uiPort === targetUi.port);
+			if (foregroundRuntime && foregroundMatchesTarget) {
+				if (!await this.restartForegroundRuntime(foregroundRuntime.pid)) return;
+				await this.deps.startCommands.run(opts);
+				return;
+			}
 			if (state) {
 				managedServiceStateStore.clear();
 				console.log("Service state was stale and has been cleaned up.");
 			}
 			const unmanagedHealthyServiceMessage = await describeUnmanagedHealthyTargetMessage({ uiOverrides });
 			if (unmanagedHealthyServiceMessage) {
+				const adoptedRuntimePid = this.resolveAdoptableForegroundRuntimePid(targetUi.port);
+				if (adoptedRuntimePid) {
+					if (!await this.restartForegroundRuntime(adoptedRuntimePid)) return;
+					await this.deps.startCommands.run(opts);
+					return;
+				}
 				console.error(`Error: Cannot restart ${APP_NAME} because the target UI/API port is already served by a healthy unmanaged instance.`);
 				console.error(unmanagedHealthyServiceMessage);
 				return;
@@ -20098,6 +20610,40 @@ var RestartCommands = class {
 		}
 		await this.deps.startCommands.run(opts);
 	};
+	restartForegroundRuntime = async (pid) => {
+		console.log(`Restarting ${APP_NAME} foreground runtime (PID ${pid})...`);
+		try {
+			process.kill(pid, "SIGTERM");
+		} catch (error) {
+			console.error(`Failed to stop foreground runtime: ${String(error)}`);
+			return false;
+		}
+		if (!await waitForExit(pid, 3e3)) {
+			try {
+				process.kill(pid, "SIGKILL");
+			} catch (error) {
+				console.error(`Failed to force stop foreground runtime: ${String(error)}`);
+				return false;
+			}
+			if (!await waitForExit(pid, 2e3)) {
+				console.error(`Failed to stop foreground runtime PID ${pid}.`);
+				return false;
+			}
+		}
+		localUiRuntimeStore.clearIfOwnedByProcess(pid);
+		console.log(`✓ ${APP_NAME} foreground runtime stopped`);
+		return true;
+	};
+	resolveAdoptableForegroundRuntimePid = (port) => {
+		const listeningProcess = findListeningProcessByPort(port);
+		if (!listeningProcess || !isProcessRunning(listeningProcess.pid)) return null;
+		return this.isAdoptableNextclawRuntimeCommand(listeningProcess.command) ? listeningProcess.pid : null;
+	};
+	isAdoptableNextclawRuntimeCommand = (command) => {
+		const normalized = command?.trim() ?? "";
+		if (!normalized) return false;
+		return /\bserve\b/.test(normalized) && (normalized.includes("/dist/cli/app/index.js") || normalized.includes("/src/cli/app/index.js") || normalized.includes("/runtime/dist/cli/app/index.js"));
+	};
 };
 //#endregion
 //#region src/cli/commands/serve/index.ts
@@ -20127,6 +20673,74 @@ var StopCommands = class {
 	};
 };
 //#endregion
+//#region src/cli/commands/companion/services/companion-process.service.ts
+var CompanionProcessService = class {
+	constructor(runtimeService = companionRuntimeService) {
+		this.runtimeService = runtimeService;
+	}
+	start = async (options = {}) => {
+		const state = await this.runtimeService.ensureStarted({ baseUrl: this.resolveBaseUrl(options) });
+		this.runtimeService.printStarted(state);
+	};
+	status = async (options = {}) => {
+		this.runtimeService.printStatus(options);
+	};
+	stop = async (options = {}) => {
+		const stopped = await this.runtimeService.ensureStopped(options);
+		this.runtimeService.printStopped(stopped);
+	};
+	enable = async (options = {}) => {
+		const nextConfig = await this.runtimeService.updateEnabled(true, options);
+		this.printConfigEnabled(nextConfig, options.baseUrl);
+	};
+	disable = async (_options = {}) => {
+		const nextConfig = await this.runtimeService.updateEnabled(false);
+		console.log(nextConfig.companion.enabled ? "Companion remains enabled." : "Companion feature disabled. It will stay off until you enable it again.");
+	};
+	resolveBaseUrl = (options) => {
+		const explicitBaseUrl = options.baseUrl?.trim();
+		if (explicitBaseUrl) return explicitBaseUrl.replace(/\/+$/, "");
+		const discoveredBaseUrl = this.runtimeService.resolveDiscoveredBaseUrl();
+		if (discoveredBaseUrl) return discoveredBaseUrl;
+		const runningState = this.runtimeService.getRunningState();
+		if (runningState) return runningState.baseUrl;
+		throw new Error("Cannot resolve NextClaw UI base URL. Start NextClaw first or pass --base-url.");
+	};
+	printConfigEnabled = (config, baseUrl) => {
+		if (this.runtimeService.getRunningState()) {
+			console.log("Companion feature enabled and companion started.");
+			return;
+		}
+		if (baseUrl?.trim()) {
+			console.log("Companion feature enabled.");
+			return;
+		}
+		console.log(config.companion.enabled ? "Companion feature enabled. It will auto-start the next time a local NextClaw runtime is available." : "Companion feature is not enabled.");
+	};
+};
+//#endregion
+//#region src/cli/commands/companion/index.ts
+var CompanionCommands = class {
+	constructor(companionProcessService = new CompanionProcessService()) {
+		this.companionProcessService = companionProcessService;
+	}
+	start = async (options = {}) => {
+		await this.companionProcessService.start(options);
+	};
+	enable = async (options = {}) => {
+		await this.companionProcessService.enable(options);
+	};
+	disable = async (options = {}) => {
+		await this.companionProcessService.disable(options);
+	};
+	status = async (options = {}) => {
+		await this.companionProcessService.status(options);
+	};
+	stop = async (options = {}) => {
+		await this.companionProcessService.stop(options);
+	};
+};
+//#endregion
 //#region src/cli/app/runtime.ts
 const LOGO = "🤖";
 const FORCED_PUBLIC_UI_HOST = "0.0.0.0";
@@ -20158,6 +20772,7 @@ var CliRuntime = class {
 	restartCommands;
 	serveCommands;
 	stopCommands;
+	companionCommands;
 	constructor(options = {}) {
 		logStartupTrace("cli.runtime.constructor.begin");
 		this.logo = options.logo ?? "🤖";
@@ -20190,6 +20805,7 @@ var CliRuntime = class {
 			forcedPublicHost: FORCED_PUBLIC_UI_HOST
 		}));
 		this.stopCommands = measureStartupSync("cli.runtime.stop_commands", () => new StopCommands({ runtimeCommandService: this.runtimeCommandService }));
+		this.companionCommands = measureStartupSync("cli.runtime.companion_commands", () => new CompanionCommands());
 		this.serviceCommands = measureStartupSync("cli.runtime.service_commands", () => new ServiceCommands());
 		this.configCommands = measureStartupSync("cli.runtime.config_commands", () => new ConfigCommands({ requestRestart: (params) => this.requestRestart(params) }));
 		this.mcpCommands = measureStartupSync("cli.runtime.mcp_commands", () => new McpCommands());
@@ -20341,7 +20957,7 @@ var CliRuntime = class {
 			spawn(process.execPath, ["-e", helperScript], {
 				detached: true,
 				stdio: "ignore",
-				env: process.env
+				env: createTopLevelNextclawCommandEnv(process.env)
 			}).unref();
 			this.selfRelaunchArmed = true;
 			console.warn(`Gateway self-restart armed (${reason}).`);
@@ -20422,6 +21038,21 @@ var CliRuntime = class {
 	stop = async () => {
 		await this.stopCommands.run();
 	};
+	companionStart = async (opts = {}) => {
+		await this.companionCommands.start(opts);
+	};
+	companionEnable = async (opts = {}) => {
+		await this.companionCommands.enable(opts);
+	};
+	companionDisable = async (opts = {}) => {
+		await this.companionCommands.disable(opts);
+	};
+	companionStatus = async (opts = {}) => {
+		await this.companionCommands.status(opts);
+	};
+	companionStop = async (opts = {}) => {
+		await this.companionCommands.stop(opts);
+	};
 	agent = async (opts) => {
 		const configPath = getConfigPath();
 		const config = resolveConfigSecrets(loadConfig(), { configPath });
@@ -20594,6 +21225,16 @@ function registerAgentsCommands(program, runtime) {
 	agents.command("remove <agentId>").description("Remove an agent").option("--json", "Output JSON", false).action(async (agentId, opts) => runtime.agentsRemove(agentId, opts));
 }
 //#endregion
+//#region src/cli/app/register-companion-commands.ts
+function registerCompanionCommands(program, runtime) {
+	const companion = program.command("companion").description("Manage the standalone NextClaw companion shell");
+	companion.command("start").description("Start the companion shell in the background").option("--base-url <url>", "Explicit NextClaw UI base URL").action(async (opts) => runtime.companionStart(opts));
+	companion.command("enable").description("Enable the companion feature and start it when a local runtime is available").option("--base-url <url>", "Explicit NextClaw UI base URL").action(async (opts) => runtime.companionEnable(opts));
+	companion.command("disable").description("Disable the companion feature and stop any running companion process").action(async (opts) => runtime.companionDisable(opts));
+	companion.command("status").description("Show companion process status").option("--json", "Output JSON", false).action(async (opts) => runtime.companionStatus(opts));
+	companion.command("stop").description("Stop the companion process").option("--force", "Force kill the companion process", false).action(async (opts) => runtime.companionStop(opts));
+}
+//#endregion
 //#region src/cli/app/service-command-registration.service.ts
 const registerServiceCommands = ({ program, getServiceCommands }) => {
 	const service = program.command("service").description("Manage host service integrations");
@@ -20649,6 +21290,7 @@ program.command("start").description(`Start the ${APP_NAME} gateway + UI in the
 program.command("restart").description(`Restart the ${APP_NAME} background service`).option("--ui-port <port>", "UI port").option("--start-timeout <ms>", "Maximum wait time for startup readiness in milliseconds").option("--open", "Open browser after restart", false).action(async (opts) => runtime.restart(opts));
 program.command("serve").description(`Run the ${APP_NAME} gateway + UI in the foreground`).option("--ui-port <port>", "UI port").option("--open", "Open browser after start", false).action(async (opts) => runtime.serve(opts));
 program.command("stop").description(`Stop the ${APP_NAME} background service`).action(async () => runtime.stop());
+registerCompanionCommands(program, runtime);
 registerServiceCommands({
 	program,
 	getServiceCommands
@@ -20699,6 +21341,6 @@ const logs = program.command("logs").description("Inspect local runtime logs");
 logs.command("path").description("Show local log file paths").action(() => runtime.logsPath());
 logs.command("tail").description("Show recent local log entries").option("--lines <n>", "Number of lines to show", "40").option("--crash", "Tail crash.log instead of service.log", false).action((opts) => runtime.logsTail(opts));
 program.command("usage").description("Show observed LLM usage snapshots, history, and prompt cache stats").option("--history", "Show recent usage history", false).option("--stats", "Show aggregated usage stats from local history", false).option("--limit <n>", "Maximum number of history records to show", "10").option("--json", "Output JSON", false).action(async (opts) => llmUsageCommands.show(opts));
-program.parseAsync(process.argv);
+await program.parseAsync(process.argv);
 //#endregion
 export {};