nextclaw 0.17.6 → 0.17.9

package/dist/cli/index.js

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import * as NextclawCore from "@nextclaw/core";
-import { APP_NAME, APP_TAGLINE, AgentLoop, AgentRouteResolver, BUILTIN_MAIN_AGENT_ID, ChannelManager, CommandRegistry, ConfigSchema, ContextBuilder, CronService, CronTool, DEFAULT_WORKSPACE_DIR, DEFAULT_WORKSPACE_PATH, DisposableStore, EditFileTool, ExecTool, ExtensionToolAdapter, GatewayTool, InputBudgetPruner, LLMProvider, ListDirTool, MemoryGetTool, MemorySearchTool, MessageBus, MessageTool, NativeAgentEngine, ProviderManager, ReadFileTool, SessionsHistoryTool, SessionsListTool, SkillsLoader, Tool, ToolRegistry, WebFetchTool, WebSearchTool, WriteFileTool, buildConfigSchema, buildReloadPlan, buildToolCatalogEntries, createAgentProfile, createAssistantStreamDeltaControlMessage, createAssistantStreamResetControlMessage, createExternalCommandEnv, diffConfigPaths, expandHome, findEffectiveAgentProfile, getConfigPath, getDataDir, getPackageVersion, getWorkspacePath, hasSecretRef, loadConfig, normalizeInlineSecretRefs, parseAgentScopedSessionKey, parseThinkingLevel, readSessionProjectRoot, redactConfigObject, removeAgentProfile, resolveConfigSecrets, resolveDefaultAgentProfileId, resolveEffectiveAgentProfiles, 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, SessionManager, SessionsHistoryTool, SessionsListTool, SkillsLoader, Tool, ToolRegistry, WebFetchTool, WebSearchTool, WriteFileTool, buildConfigSchema, buildMinimalSystemExecutionPrompt, buildReloadPlan, buildToolCatalogEntries, createAgentProfile, createAssistantStreamDeltaControlMessage, createAssistantStreamResetControlMessage, createExternalCommandEnv, createTypingStopControlMessage, diffConfigPaths, expandHome, findEffectiveAgentProfile, getAppLogger, getConfigPath, getDataDir, getLoggingRuntime, getLogsPath, getPackageVersion, getWorkspacePath, hasSecretRef, loadConfig, normalizeInlineSecretRefs, parseAgentScopedSessionKey, parseThinkingLevel, readSessionProjectRoot, redactConfigObject, removeAgentProfile, resolveAppLogPath, resolveConfigSecrets, resolveDefaultAgentProfileId, resolveEffectiveAgentProfiles, resolveLocalUiBaseUrl, resolveSessionWorkspacePath, resolveThinkingLevel, saveConfig, toDisposable, updateAgentProfile } from "@nextclaw/core";
 import { Command } from "commander";
 import fs, { appendFileSync, closeSync, cpSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import path, { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { hostname, platform } from "node:os";
 import { ensureUiBridgeSecret, startUiServer } from "@nextclaw/server";
-import { addPluginLoadPath, buildPluginStatusReport, disablePluginInConfig, discoverPluginStatusReport, enablePluginInConfig, getPluginChannelBindings, getPluginUiMetadataFromRegistry, installPluginFromNpmSpec, installPluginFromPath, loadOpenClawPlugins, loadOpenClawPluginsProgressively, mergePluginConfigView, recordPluginInstall, resolvePluginChannelMessageToolHints, resolveUninstallDirectoryTargets, setPluginRuntimeBridge, startPluginChannelGateways, stopPluginChannelGateways, toPluginConfigView, toPluginConfigView as toPluginConfigView$1, uninstallPlugin } from "@nextclaw/openclaw-compat";
-import { createInterface } from "node:readline";
+import { addPluginLoadPath, buildPluginStatusReport, disablePluginInConfig, discoverPluginStatusReport, enablePluginInConfig, getPackageManifestExtensions, getPluginChannelBindings, getPluginUiMetadataFromRegistry, installPluginFromNpmSpec, installPluginFromPath, loadOpenClawPlugins, loadOpenClawPluginsProgressively, loadPluginManifest, mergePluginConfigView, recordPluginInstall, resolvePluginChannelMessageToolHints, resolveUninstallDirectoryTargets, setPluginRuntimeBridge, startPluginChannelGateways, stopPluginChannelGateways, toPluginConfigView, toPluginConfigView as toPluginConfigView$1, uninstallPlugin } from "@nextclaw/openclaw-compat";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import { parse } from "yaml";
+import { createInterface } from "node:readline";
 import { createServer, isIP } from "node:net";
 import { BUILTIN_CHANNEL_PLUGIN_IDS, builtinProviderIds, listBuiltinProviders } from "@nextclaw/runtime";
 import { McpDoctorFacade, McpMutationService, McpRegistryService, McpServerLifecycleManager } from "@nextclaw/mcp";
@@ -24,6 +24,7 @@ import { McpNcpToolRegistryAdapter } from "@nextclaw/ncp-mcp";
 import { NCP_INTERNAL_VISIBILITY_METADATA_KEY, NcpEventType, readAssistantReasoningNormalizationMode, readAssistantReasoningNormalizationModeFromMetadata, sanitizeAssistantReplyTags, writeAssistantReasoningNormalizationModeToMetadata } from "@nextclaw/ncp";
 import { DefaultNcpAgentBackend, createAgentClientFromServer } from "@nextclaw/ncp-toolkit";
 import { createHash, randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -161,7 +162,7 @@ function maskToken(value) {
 	if (value.length <= 12) return "<redacted>";
 	return `${value.slice(0, 6)}...${value.slice(-4)}`;
 }
-function normalizeOptionalString$7(value) {
+function normalizeOptionalString$9(value) {
 	if (typeof value !== "string") return;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : void 0;
@@ -259,8 +260,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$7(config.remote.platformApiBase) ?? (typeof nextclawProvider?.apiBase === "string" ? nextclawProvider.apiBase.trim() : "");
-		const rawApiBase = normalizeOptionalString$7(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),
@@ -269,14 +270,14 @@ var RemotePlatformClient = class {
 		};
 	}
 	resolveLocalOrigin(config, opts) {
-		const explicitOrigin = normalizeOptionalString$7(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$7(opts.name) ?? normalizeOptionalString$7(config.remote.deviceName) ?? hostname();
+		return normalizeOptionalString$9(opts.name) ?? normalizeOptionalString$9(config.remote.deviceName) ?? hostname();
 	}
 };
 //#endregion
@@ -4486,7 +4487,7 @@ var RemoteConnector = class {
 };
 //#endregion
 //#region ../nextclaw-remote/src/remote-status-store.ts
-function normalizeOptionalString$6(value) {
+function normalizeOptionalString$8(value) {
 	if (typeof value !== "string") return;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : void 0;
@@ -4497,8 +4498,8 @@ function buildConfiguredRemoteState(config) {
 		enabled: Boolean(remote.enabled),
 		mode: "service",
 		state: remote.enabled ? "disconnected" : "disabled",
-		...normalizeOptionalString$6(remote.deviceName) ? { deviceName: normalizeOptionalString$6(remote.deviceName) } : {},
-		...normalizeOptionalString$6(remote.platformApiBase) ? { platformBase: normalizeOptionalString$6(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()
 	};
 }
@@ -4511,7 +4512,7 @@ function resolveRemoteStatusSnapshot(params) {
 		configuredEnabled: true,
 		runtime: {
 			...buildConfiguredRemoteState(params.config),
-			deviceName: normalizeOptionalString$6(params.config.remote.deviceName) ?? normalizeOptionalString$6(params.fallbackDeviceName) ?? hostname()
+			deviceName: normalizeOptionalString$8(params.config.remote.deviceName) ?? normalizeOptionalString$8(params.fallbackDeviceName) ?? hostname()
 		}
 	};
 	return {
@@ -4623,6 +4624,299 @@ var RemoteServiceModule = class {
 	}
 };
 //#endregion
+//#region src/cli/runtime-state/llm-usage-history.store.ts
+var LlmUsageHistoryStore = class {
+	constructor(explicitPath) {
+		this.explicitPath = explicitPath;
+	}
+	get path() {
+		return this.explicitPath ?? resolve(getDataDir(), "logs", "llm-usage.jsonl");
+	}
+	list = () => {
+		if (!existsSync(this.path)) return [];
+		try {
+			return readFileSync(this.path, "utf-8").split("\n").map((line) => line.trim()).filter((line) => line.length > 0).flatMap((line) => {
+				try {
+					return [JSON.parse(line)];
+				} catch {
+					return [];
+				}
+			});
+		} catch {
+			return [];
+		}
+	};
+	append = (record) => {
+		mkdirSync(resolve(this.path, ".."), { recursive: true });
+		appendFileSync(this.path, `${JSON.stringify(record)}\n`);
+	};
+	clear = () => {
+		if (existsSync(this.path)) rmSync(this.path, { force: true });
+	};
+};
+const llmUsageHistoryStore = new LlmUsageHistoryStore();
+//#endregion
+//#region src/cli/runtime-state/llm-usage-snapshot.store.ts
+var LlmUsageSnapshotStore = class {
+	constructor(explicitPath) {
+		this.explicitPath = explicitPath;
+	}
+	get path() {
+		return this.explicitPath ?? resolve(getDataDir(), "run", "llm-usage.json");
+	}
+	read = () => {
+		if (!existsSync(this.path)) return null;
+		try {
+			const raw = readFileSync(this.path, "utf-8");
+			return JSON.parse(raw);
+		} catch {
+			return null;
+		}
+	};
+	write = (snapshot) => {
+		mkdirSync(resolve(this.path, ".."), { recursive: true });
+		writeFileSync(this.path, JSON.stringify(snapshot, null, 2));
+	};
+	clear = () => {
+		if (existsSync(this.path)) rmSync(this.path, { force: true });
+	};
+};
+const llmUsageSnapshotStore = new LlmUsageSnapshotStore();
+//#endregion
+//#region src/cli/commands/shared/llm-usage-query.service.ts
+var LlmUsageQueryService = class {
+	constructor(deps = {}) {
+		this.deps = deps;
+	}
+	get snapshotPath() {
+		return this.snapshotStore.path;
+	}
+	get historyPath() {
+		return this.historyStore.path;
+	}
+	getSnapshot = () => {
+		return this.snapshotStore.read();
+	};
+	getHistory = (limit) => {
+		const records = this.historyStore.list();
+		const resolvedLimit = this.resolveLimit(limit);
+		return records.slice(-resolvedLimit).reverse();
+	};
+	getStats = () => {
+		const records = this.historyStore.list();
+		const sources = /* @__PURE__ */ new Map();
+		const models = /* @__PURE__ */ new Map();
+		let totalPromptTokens = 0;
+		let totalCompletionTokens = 0;
+		let totalTokens = 0;
+		let totalCachedTokens = 0;
+		let cacheHitRecords = 0;
+		for (const record of records) {
+			totalPromptTokens += record.summary.promptTokens;
+			totalCompletionTokens += record.summary.completionTokens;
+			totalTokens += record.summary.totalTokens;
+			totalCachedTokens += record.summary.cachedTokens;
+			if (record.summary.cacheHit) cacheHitRecords += 1;
+			this.bumpCounter(sources, record.source);
+			this.bumpCounter(models, record.model ?? "unknown");
+		}
+		return {
+			totalRecords: records.length,
+			oldestObservedAt: records[0]?.observedAt ?? null,
+			latestObservedAt: records.at(-1)?.observedAt ?? null,
+			totalPromptTokens,
+			totalCompletionTokens,
+			totalTokens,
+			totalCachedTokens,
+			cacheHitRecords,
+			cacheHitRate: records.length > 0 ? cacheHitRecords / records.length : 0,
+			sources: this.toSortedCounts(sources),
+			models: this.toSortedCounts(models)
+		};
+	};
+	get snapshotStore() {
+		return this.deps.snapshotStore ?? llmUsageSnapshotStore;
+	}
+	get historyStore() {
+		return this.deps.historyStore ?? llmUsageHistoryStore;
+	}
+	resolveLimit = (value) => {
+		if (typeof value === "number" && Number.isFinite(value) && value > 0) return Math.floor(value);
+		if (typeof value === "string" && value.trim().length > 0) {
+			const parsed = Number(value);
+			if (Number.isFinite(parsed) && parsed > 0) return Math.floor(parsed);
+		}
+		return 10;
+	};
+	bumpCounter = (map, value) => {
+		map.set(value, (map.get(value) ?? 0) + 1);
+	};
+	toSortedCounts = (map) => {
+		return [...map.entries()].map(([value, count]) => ({
+			value,
+			count
+		})).sort((left, right) => {
+			if (right.count !== left.count) return right.count - left.count;
+			return left.value.localeCompare(right.value);
+		});
+	};
+};
+const llmUsageQueryService = new LlmUsageQueryService();
+//#endregion
+//#region src/cli/commands/shared/llm-usage.commands.ts
+var LlmUsageCommands = class {
+	constructor(deps = {}) {
+		this.deps = deps;
+	}
+	show = async (opts = {}) => {
+		if (opts.history && opts.stats) {
+			console.error("Choose only one usage mode: `--history` or `--stats`.");
+			process.exitCode = 1;
+			return;
+		}
+		if (opts.history) {
+			this.showHistory(opts);
+			return;
+		}
+		if (opts.stats) {
+			this.showStats(opts);
+			return;
+		}
+		this.showSnapshot(opts);
+	};
+	get queryService() {
+		return this.deps.queryService ?? llmUsageQueryService;
+	}
+	showSnapshot = (opts) => {
+		const snapshot = this.queryService.getSnapshot();
+		if (opts.json) {
+			console.log(JSON.stringify({
+				ok: Boolean(snapshot),
+				mode: "snapshot",
+				path: this.queryService.snapshotPath,
+				snapshot
+			}, null, 2));
+			process.exitCode = 0;
+			return;
+		}
+		if (!snapshot) {
+			console.log([
+				"No LLM usage snapshot recorded yet.",
+				`Snapshot path: ${this.queryService.snapshotPath}`,
+				"Run `nextclaw agent -m \"ping\"` or use the local UI once, then retry `nextclaw usage`."
+			].join("\n"));
+			process.exitCode = 0;
+			return;
+		}
+		console.log(this.renderSnapshot(snapshot));
+		process.exitCode = 0;
+	};
+	showHistory = (opts) => {
+		const records = this.queryService.getHistory(opts.limit);
+		if (opts.json) {
+			console.log(JSON.stringify({
+				ok: records.length > 0,
+				mode: "history",
+				path: this.queryService.historyPath,
+				limit: this.resolveLimit(opts.limit),
+				records
+			}, null, 2));
+			process.exitCode = 0;
+			return;
+		}
+		if (records.length === 0) {
+			console.log([
+				"No LLM usage history recorded yet.",
+				`History path: ${this.queryService.historyPath}`,
+				"Run `nextclaw agent -m \"ping\"` or use the local UI once, then retry `nextclaw usage --history`."
+			].join("\n"));
+			process.exitCode = 0;
+			return;
+		}
+		console.log(this.renderHistory(records));
+		process.exitCode = 0;
+	};
+	showStats = (opts) => {
+		const stats = this.queryService.getStats();
+		if (opts.json) {
+			console.log(JSON.stringify({
+				ok: stats.totalRecords > 0,
+				mode: "stats",
+				path: this.queryService.historyPath,
+				stats
+			}, null, 2));
+			process.exitCode = 0;
+			return;
+		}
+		if (stats.totalRecords === 0) {
+			console.log([
+				"No LLM usage history recorded yet.",
+				`History path: ${this.queryService.historyPath}`,
+				"Run `nextclaw agent -m \"ping\"` or use the local UI once, then retry `nextclaw usage --stats`."
+			].join("\n"));
+			process.exitCode = 0;
+			return;
+		}
+		console.log(this.renderStats(stats));
+		process.exitCode = 0;
+	};
+	renderSnapshot = (snapshot) => {
+		const lines = [
+			"Latest LLM usage snapshot",
+			`Observed at: ${snapshot.observedAt}`,
+			`Source: ${snapshot.source}`,
+			`Model: ${snapshot.model ?? "unknown"}`,
+			`Prompt tokens: ${snapshot.summary.promptTokens}`,
+			`Completion tokens: ${snapshot.summary.completionTokens}`,
+			`Total tokens: ${snapshot.summary.totalTokens}`,
+			`Cached tokens: ${snapshot.summary.cachedTokens}`,
+			`Cache hit: ${snapshot.summary.cacheHit ? "yes" : "no"}`,
+			`Snapshot path: ${this.queryService.snapshotPath}`
+		];
+		if (snapshot.summary.cacheMetricKeys.length > 0) lines.push(`Cache metric keys: ${snapshot.summary.cacheMetricKeys.join(", ")}`);
+		if (Object.keys(snapshot.usage).length > 0) lines.push("", "Raw usage:", JSON.stringify(snapshot.usage, null, 2));
+		return lines.join("\n");
+	};
+	renderHistory = (records) => {
+		const lines = [
+			"Recent LLM usage history",
+			`History path: ${this.queryService.historyPath}`,
+			`Showing: ${records.length} record(s)`,
+			""
+		];
+		for (const [index, record] of records.entries()) lines.push(`${index + 1}. ${record.observedAt} | source=${record.source} | model=${record.model ?? "unknown"} | total=${record.summary.totalTokens} | cached=${record.summary.cachedTokens} | cache-hit=${record.summary.cacheHit ? "yes" : "no"}`);
+		return lines.join("\n");
+	};
+	renderStats = (stats) => {
+		const lines = [
+			"LLM usage history stats",
+			`History path: ${this.queryService.historyPath}`,
+			`Records: ${stats.totalRecords}`,
+			`Oldest observed at: ${stats.oldestObservedAt ?? "n/a"}`,
+			`Latest observed at: ${stats.latestObservedAt ?? "n/a"}`,
+			`Prompt tokens: ${stats.totalPromptTokens}`,
+			`Completion tokens: ${stats.totalCompletionTokens}`,
+			`Total tokens: ${stats.totalTokens}`,
+			`Cached tokens: ${stats.totalCachedTokens}`,
+			`Cache hits: ${stats.cacheHitRecords}/${stats.totalRecords} (${this.toPercent(stats.cacheHitRate)})`
+		];
+		if (stats.sources.length > 0) lines.push(`Sources: ${stats.sources.map((item) => `${item.value}=${item.count}`).join(", ")}`);
+		if (stats.models.length > 0) lines.push(`Models: ${stats.models.map((item) => `${item.value}=${item.count}`).join(", ")}`);
+		return lines.join("\n");
+	};
+	resolveLimit = (value) => {
+		if (typeof value === "number" && Number.isFinite(value) && value > 0) return Math.floor(value);
+		if (typeof value === "string" && value.trim().length > 0) {
+			const parsed = Number(value);
+			if (Number.isFinite(parsed) && parsed > 0) return Math.floor(parsed);
+		}
+		return 10;
+	};
+	toPercent = (value) => {
+		return `${(value * 100).toFixed(1)}%`;
+	};
+};
+//#endregion
 //#region src/cli/restart-coordinator.ts
 var RestartCoordinator = class {
 	restartingService = false;
@@ -4851,7 +5145,7 @@ function parseSkillFrontmatter(raw) {
 		const message = error instanceof Error ? error.message : String(error);
 		throw new Error(`Invalid SKILL.md frontmatter: ${message}`);
 	}
-	if (!isRecord$4(parsed)) return {};
+	if (!isRecord$5(parsed)) return {};
 	const summaryI18n = readLocalizedTextMapField(parsed, [["summaryi18n"], ["summary_i18n"]]);
 	const descriptionI18n = readLocalizedTextMapField(parsed, [["descriptioni18n"], ["description_i18n"]]);
 	const summaryZh = readFrontmatterStringField(parsed, [["summaryzh"], ["summary_zh"]]);
@@ -4882,7 +5176,7 @@ function readMarketplaceMetadataFile(skillDir, explicitMetaFile) {
 		const message = error instanceof Error ? error.message : String(error);
 		throw new Error(`Invalid marketplace metadata file: ${metadataPath} (${message})`);
 	}
-	if (!isRecord$4(parsed)) throw new Error(`Invalid marketplace metadata file: ${metadataPath} (root must be an object)`);
+	if (!isRecord$5(parsed)) throw new Error(`Invalid marketplace metadata file: ${metadataPath} (root must be an object)`);
 	return {
 		slug: readMetadataString(parsed, "slug"),
 		name: readMetadataString(parsed, "name"),
@@ -4930,7 +5224,7 @@ function readMetadataStringArray(record, fieldName) {
 function readMetadataLocalizedTextMap(record, fieldName) {
 	const value = record[fieldName];
 	if (value == null) return;
-	if (!isRecord$4(value)) throw new Error(`Invalid marketplace metadata field: ${fieldName} must be an object`);
+	if (!isRecord$5(value)) throw new Error(`Invalid marketplace metadata field: ${fieldName} must be an object`);
 	const localized = {};
 	for (const [locale, text] of Object.entries(value)) {
 		if (typeof text !== "string") throw new Error(`Invalid marketplace metadata field: ${fieldName}.${locale} must be a string`);
@@ -4951,7 +5245,7 @@ function readFrontmatterStringField(record, keyPaths) {
 function readLocalizedTextMapField(record, keyPaths) {
 	for (const keyPath of keyPaths) {
 		const value = readNestedFrontmatterValue(record, keyPath);
-		if (!isRecord$4(value)) continue;
+		if (!isRecord$5(value)) continue;
 		const normalized = {};
 		for (const [locale, text] of Object.entries(value)) {
 			if (typeof text !== "string") continue;
@@ -4975,7 +5269,7 @@ function readFrontmatterTags(record) {
 function readNestedFrontmatterValue(record, keyPath) {
 	let current = record;
 	for (const rawKey of keyPath) {
-		if (!isRecord$4(current)) return;
+		if (!isRecord$5(current)) return;
 		const normalizedKey = normalizeFrontmatterKey(rawKey);
 		const matchingKey = Object.keys(current).find((candidate) => normalizeFrontmatterKey(candidate) === normalizedKey);
 		if (!matchingKey) return;
@@ -4989,7 +5283,7 @@ function normalizeFrontmatterKey(raw) {
 function normalizeLocaleTag(raw) {
 	return raw.trim().toLowerCase();
 }
-function isRecord$4(value) {
+function isRecord$5(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
@@ -5130,7 +5424,10 @@ function resolveUiConfig(config, overrides) {
 	};
 }
 function resolveUiApiBase(host, port) {
-	return `http://${host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host}:${port}`;
+	return resolveLocalUiBaseUrl({
+		host,
+		port
+	});
 }
 function isLoopbackHost(host) {
 	const normalized = host.trim().toLowerCase();
@@ -5161,37 +5458,8 @@ async function resolvePublicIp(timeoutMs = 1500) {
 	}
 	return null;
 }
-function readServiceState() {
-	const path = resolveServiceStatePath();
-	if (!existsSync(path)) return null;
-	try {
-		const raw = readFileSync(path, "utf-8");
-		return JSON.parse(raw);
-	} catch {
-		return null;
-	}
-}
-function writeServiceState(state) {
-	const path = resolveServiceStatePath();
-	mkdirSync(resolve(path, ".."), { recursive: true });
-	writeFileSync(path, JSON.stringify(state, null, 2));
-}
-function updateServiceState(updater) {
-	const current = readServiceState();
-	if (!current) return null;
-	const next = updater(current);
-	writeServiceState(next);
-	return next;
-}
-function clearServiceState() {
-	const path = resolveServiceStatePath();
-	if (existsSync(path)) rmSync(path, { force: true });
-}
-function resolveServiceStatePath() {
-	return resolve(getDataDir(), "run", "service.json");
-}
 function resolveServiceLogPath() {
-	return resolve(getDataDir(), "logs", "service.log");
+	return resolve(getLogsPath(), "service.log");
 }
 function isProcessRunning(pid) {
 	try {
@@ -5584,9 +5852,9 @@ async function fetchMarketplaceSkillFiles(apiBase, slug) {
 			const message = payload.error?.message || `marketplace skill file fetch failed: ${response.status}`;
 			throw new Error(message);
 		}
-		if (!isRecord$3(payload.data) || !Array.isArray(payload.data.files)) throw new Error("Invalid marketplace skill file manifest response");
+		if (!isRecord$4(payload.data) || !Array.isArray(payload.data.files)) throw new Error("Invalid marketplace skill file manifest response");
 		return { files: payload.data.files.map((entry, index) => {
-			if (!isRecord$3(entry) || typeof entry.path !== "string" || entry.path.trim().length === 0) throw new Error(`Invalid marketplace skill file manifest at index ${index}`);
+			if (!isRecord$4(entry) || typeof entry.path !== "string" || entry.path.trim().length === 0) throw new Error(`Invalid marketplace skill file manifest at index ${index}`);
 			const normalized = { path: entry.path.trim() };
 			if (typeof entry.downloadPath === "string" && entry.downloadPath.trim().length > 0) normalized.downloadPath = entry.downloadPath.trim();
 			if (typeof entry.contentBase64 === "string" && entry.contentBase64.trim().length > 0) normalized.contentBase64 = entry.contentBase64.trim();
@@ -5613,7 +5881,7 @@ async function readMarketplaceEnvelope(response) {
 	} catch {
 		throw new Error(`Invalid marketplace response: ${response.status}`);
 	}
-	if (!isRecord$3(payload) || typeof payload.ok !== "boolean") throw new Error(`Invalid marketplace response shape: ${response.status}`);
+	if (!isRecord$4(payload) || typeof payload.ok !== "boolean") throw new Error(`Invalid marketplace response shape: ${response.status}`);
 	return payload;
 }
 function resolveSkillFileDownloadUrl(apiBase, slug, file) {
@@ -5628,7 +5896,7 @@ function extractMarketplaceErrorMessage(raw, fallbackStatus) {
 		return raw || `Request failed (${fallbackStatus})`;
 	}
 }
-function isRecord$3(value) {
+function isRecord$4(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
@@ -5936,6 +6204,41 @@ function decodeMarketplaceFileContent(path, contentBase64) {
 	return Buffer.from(normalized, "base64");
 }
 //#endregion
+//#region src/cli/update/self-update-report.utils.ts
+function reportSelfUpdateResult(params) {
+	const { appName, currentVersion, result, readInstalledVersion } = params;
+	const printSteps = () => {
+		for (const step of result.steps) {
+			console.log(`- ${step.cmd} ${step.args.join(" ")} (code ${step.code ?? "?"})`);
+			if (step.stderr) console.log(`  stderr: ${step.stderr}`);
+			if (step.stdout) console.log(`  stdout: ${step.stdout}`);
+		}
+	};
+	if (!result.ok) {
+		console.error(`Update failed: ${result.error ?? "unknown error"}`);
+		if (result.steps.length > 0) printSteps();
+		return {
+			ok: false,
+			shouldSuggestRestart: false
+		};
+	}
+	if (result.strategy === "noop") {
+		console.log(`✓ ${appName} is already up to date (${result.latestVersion ?? currentVersion})`);
+		return {
+			ok: true,
+			shouldSuggestRestart: false
+		};
+	}
+	const versionAfter = result.latestVersion ?? readInstalledVersion();
+	console.log(`✓ Update complete (${result.strategy})`);
+	if (versionAfter === currentVersion) console.log(`Version unchanged: ${currentVersion}`);
+	else console.log(`Version updated: ${currentVersion} -> ${versionAfter}`);
+	return {
+		ok: true,
+		shouldSuggestRestart: true
+	};
+}
+//#endregion
 //#region src/cli/update/runner.ts
 const DEFAULT_TIMEOUT_MS = 20 * 6e4;
 function runSelfUpdate(options = {}) {
@@ -5943,6 +6246,7 @@ function runSelfUpdate(options = {}) {
 	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 	const updateCommand = options.updateCommand ?? process.env.NEXTCLAW_UPDATE_COMMAND?.trim();
 	const packageName = options.packageName ?? "nextclaw";
+	const currentVersion = options.currentVersion?.trim() || null;
 	const resolveShellCommand = (command) => {
 		if (process.platform === "win32") return {
 			cmd: process.env.ComSpec || "cmd.exe",
@@ -5966,19 +6270,33 @@ function runSelfUpdate(options = {}) {
 			timeout: timeoutMs,
 			stdio: "pipe"
 		});
+		const stdout = (result.stdout ?? "").toString().slice(0, 4e3);
+		const stderr = (result.stderr ?? "").toString().slice(0, 4e3);
 		steps.push({
 			cmd,
 			args,
 			cwd,
 			code: result.status,
-			stdout: (result.stdout ?? "").toString().slice(0, 4e3),
-			stderr: (result.stderr ?? "").toString().slice(0, 4e3)
+			stdout,
+			stderr
 		});
 		return {
 			ok: result.status === 0,
-			code: result.status
+			code: result.status,
+			stdout,
+			stderr
 		};
 	};
+	const parseLatestVersion = (raw) => {
+		const trimmed = raw.trim();
+		if (!trimmed) return null;
+		try {
+			const parsed = JSON.parse(trimmed);
+			return typeof parsed === "string" && parsed.trim() ? parsed.trim() : null;
+		} catch {
+			return trimmed;
+		}
+	};
 	if (updateCommand) {
 		const cwd = options.cwd ? resolve(options.cwd) : process.cwd();
 		const shellCommand = resolveShellCommand(updateCommand);
@@ -5996,19 +6314,35 @@ function runSelfUpdate(options = {}) {
 	}
 	const npmExecutable = findExecutableOnPath("npm");
 	if (npmExecutable) {
+		const cwd = options.cwd ? resolve(options.cwd) : process.cwd();
+		const latestVersionStep = runStep(npmExecutable, [
+			"view",
+			packageName,
+			"version",
+			"--json"
+		], cwd);
+		const latestVersion = latestVersionStep.ok ? parseLatestVersion(latestVersionStep.stdout) : null;
+		if (latestVersion && currentVersion && latestVersion === currentVersion) return {
+			ok: true,
+			strategy: "noop",
+			latestVersion,
+			steps
+		};
 		if (!runStep(npmExecutable, [
 			"i",
 			"-g",
 			packageName
-		], process.cwd()).ok) return {
+		], cwd).ok) return {
 			ok: false,
 			error: `npm install -g ${packageName} failed`,
 			strategy: "npm",
+			latestVersion: latestVersion ?? void 0,
 			steps
 		};
 		return {
 			ok: true,
 			strategy: "npm",
+			latestVersion: latestVersion ?? void 0,
 			steps
 		};
 	}
@@ -6020,6 +6354,40 @@ function runSelfUpdate(options = {}) {
 	};
 }
 //#endregion
+//#region src/cli/runtime-state/managed-service-state.store.ts
+var ManagedServiceStateStore = class {
+	get path() {
+		return resolve(getDataDir(), "run", "service.json");
+	}
+	read = () => {
+		if (!existsSync(this.path)) return null;
+		try {
+			const raw = readFileSync(this.path, "utf-8");
+			return JSON.parse(raw);
+		} catch {
+			return null;
+		}
+	};
+	write = (state) => {
+		mkdirSync(resolve(this.path, ".."), { recursive: true });
+		writeFileSync(this.path, JSON.stringify(state, null, 2));
+	};
+	update = (updater) => {
+		const current = this.read();
+		if (!current) return null;
+		const next = updater(current);
+		this.write(next);
+		return next;
+	};
+	clear = () => {
+		if (existsSync(this.path)) rmSync(this.path, { force: true });
+	};
+	clearIfOwnedByProcess = (pid = process.pid) => {
+		if (this.read()?.pid === pid) this.clear();
+	};
+};
+const managedServiceStateStore = new ManagedServiceStateStore();
+//#endregion
 //#region src/cli/commands/plugin/plugin-command-utils.ts
 const RESERVED_PROVIDER_IDS$1 = builtinProviderIds();
 const RESERVED_TOOL_NAMES = [
@@ -6045,7 +6413,6 @@ function buildReservedPluginLoadOptions() {
 		reservedToolNames: [...RESERVED_TOOL_NAMES],
 		reservedChannelIds: [],
 		reservedProviderIds: RESERVED_PROVIDER_IDS$1,
-		reservedEngineKinds: ["native"],
 		reservedNcpAgentRuntimeKinds: ["native"]
 	};
 }
@@ -6053,11 +6420,10 @@ function appendPluginCapabilityLines(lines, plugin) {
 	if (plugin.toolNames.length > 0) lines.push(`Tools: ${plugin.toolNames.join(", ")}`);
 	if (plugin.channelIds.length > 0) lines.push(`Channels: ${plugin.channelIds.join(", ")}`);
 	if (plugin.providerIds.length > 0) lines.push(`Providers: ${plugin.providerIds.join(", ")}`);
-	if (plugin.engineKinds.length > 0) lines.push(`Engines: ${plugin.engineKinds.join(", ")}`);
 	if (plugin.ncpAgentRuntimeKinds.length > 0) lines.push(`NCP runtimes: ${plugin.ncpAgentRuntimeKinds.join(", ")}`);
 }
 //#endregion
-//#region src/cli/commands/plugin/dev-first-party-plugin-load-paths.ts
+//#region src/cli/commands/plugin/development-source/first-party-plugin-load-paths.ts
 const readJsonFile = (filePath) => {
 	try {
 		const raw = fs.readFileSync(filePath, "utf-8");
@@ -6074,7 +6440,7 @@ const readString = (value) => {
 const resolveDevFirstPartyPluginDir = (explicitDir, moduleDir = path.dirname(fileURLToPath(import.meta.url))) => {
 	const configured = explicitDir?.trim();
 	if (configured) return configured;
-	const inferred = path.resolve(moduleDir, "../../../../extensions");
+	const inferred = path.resolve(moduleDir, "../../../../../extensions");
 	return fs.existsSync(inferred) ? inferred : void 0;
 };
 const hasOpenClawExtensions = (pkg) => {
@@ -6083,6 +6449,14 @@ const hasOpenClawExtensions = (pkg) => {
 	const extensions = openclaw.extensions;
 	return Array.isArray(extensions) && extensions.some((entry) => typeof entry === "string" && entry.trim().length > 0);
 };
+const hasOpenClawDevelopmentExtensions = (pkg) => {
+	const openclaw = pkg.openclaw;
+	if (!openclaw || typeof openclaw !== "object" || Array.isArray(openclaw)) return false;
+	const development = openclaw.development;
+	if (!development || typeof development !== "object" || Array.isArray(development)) return false;
+	const extensions = development.extensions;
+	return Array.isArray(extensions) && extensions.some((entry) => typeof entry === "string" && entry.trim().length > 0);
+};
 const normalizePackageSpec = (spec) => {
 	const trimmed = spec.trim();
 	if (!trimmed) return;
@@ -6108,11 +6482,38 @@ const readWorkspacePluginPackages = (workspaceExtensionsDir) => {
 		if (!packageName?.startsWith("@nextclaw/")) continue;
 		packages.push({
 			packageName,
-			dir: packageDir
+			dir: packageDir,
+			supportsDevelopmentSource: hasOpenClawDevelopmentExtensions(pkg)
 		});
 	}
 	return packages;
 };
+const mergeLoadPaths$1 = (existingLoadPaths, devLoadPaths) => {
+	const mergedLoadPaths = [...devLoadPaths];
+	for (const entry of existingLoadPaths) if (!mergedLoadPaths.includes(entry)) mergedLoadPaths.push(entry);
+	return mergedLoadPaths;
+};
+const buildDevelopmentSourceEntryDefaults = (config, workspacePackages) => {
+	const packageByName = new Map(workspacePackages.map((entry) => [entry.packageName, entry]));
+	const nextEntries = { ...config.plugins.entries ?? {} };
+	let didDefaultDevelopmentSource = false;
+	for (const [pluginId, installRecord] of Object.entries(config.plugins.installs ?? {})) {
+		const packageName = normalizePackageSpec(installRecord.spec ?? "");
+		if (!packageName) continue;
+		if (!packageByName.get(packageName)?.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 [];
@@ -6147,15 +6548,19 @@ const resolveDevFirstPartyPluginInstallRoots = (config, workspaceExtensionsDir)
 	return installRoots;
 };
 const applyDevFirstPartyPluginLoadPaths = (config, workspaceExtensionsDir) => {
-	const devLoadPaths = resolveDevFirstPartyPluginLoadPaths(config, workspaceExtensionsDir);
+	const rootDir = resolveDevFirstPartyPluginDir(workspaceExtensionsDir);
+	if (!rootDir) return config;
+	const workspacePackages = readWorkspacePluginPackages(rootDir);
+	if (workspacePackages.length === 0) return config;
+	const devLoadPaths = resolveDevFirstPartyPluginLoadPaths(config, rootDir);
 	if (devLoadPaths.length === 0) return config;
-	const existingLoadPaths = Array.isArray(config.plugins.load?.paths) ? config.plugins.load.paths.filter((entry) => typeof entry === "string" && entry.trim().length > 0) : [];
-	const mergedLoadPaths = [...devLoadPaths];
-	for (const entry of existingLoadPaths) if (!mergedLoadPaths.includes(entry)) mergedLoadPaths.push(entry);
+	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);
 	return {
 		...config,
 		plugins: {
 			...config.plugins,
+			entries: didDefaultDevelopmentSource ? nextEntries : config.plugins.entries,
 			load: {
 				...config.plugins.load,
 				paths: mergedLoadPaths
@@ -6164,6 +6569,112 @@ 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$3(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readOptionalString$6(value) {
+	if (typeof value !== "string") return;
+	return value.trim() || void 0;
+}
+function readPackageManifest(pluginPath) {
+	const packageJsonPath = path.join(pluginPath, "package.json");
+	if (!fs.existsSync(packageJsonPath)) return null;
+	try {
+		return JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+function assertOverridePluginReadable(override) {
+	if (!fs.existsSync(override.pluginPath)) throw new Error(`[dev-plugin-override] plugin path does not exist for "${override.pluginId}": ${override.pluginPath}`);
+	const packageManifest = readPackageManifest(override.pluginPath);
+	if (!packageManifest) throw new Error(`[dev-plugin-override] package.json is missing or invalid for "${override.pluginId}": ${override.pluginPath}`);
+	const pluginManifest = loadPluginManifest(override.pluginPath);
+	if (!pluginManifest.ok) throw new Error(`[dev-plugin-override] ${pluginManifest.error} for "${override.pluginId}": ${override.pluginPath}`);
+	if (pluginManifest.manifest.id !== override.pluginId) throw new Error(`[dev-plugin-override] plugin id mismatch: expected "${override.pluginId}" but found "${pluginManifest.manifest.id}" at ${override.pluginPath}`);
+	if (getPackageManifestExtensions(packageManifest, override.source).length === 0) {
+		const missingEntry = override.source === "development" ? "openclaw.development.extensions" : "openclaw.extensions";
+		throw new Error(`[dev-plugin-override] ${missingEntry} is missing for "${override.pluginId}" at ${override.pluginPath}`);
+	}
+}
+function readOverrideRecord(value, index) {
+	if (!isRecord$3(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);
+	const source = value.source === "development" ? "development" : "production";
+	if (!pluginId || !pluginPath) throw new Error(`[dev-plugin-override] override[${index}] requires pluginId and pluginPath`);
+	const normalized = {
+		pluginId,
+		pluginPath: path.resolve(pluginPath),
+		source
+	};
+	assertOverridePluginReadable(normalized);
+	return normalized;
+}
+function resolveDevPluginOverrides(rawEnv = process.env[DEV_PLUGIN_OVERRIDES_ENV]) {
+	if (typeof rawEnv !== "string" || rawEnv.trim().length === 0) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse(rawEnv);
+	} catch (error) {
+		throw new Error(`[dev-plugin-override] failed to parse ${DEV_PLUGIN_OVERRIDES_ENV}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!Array.isArray(parsed)) throw new Error(`[dev-plugin-override] ${DEV_PLUGIN_OVERRIDES_ENV} must be a JSON array`);
+	const seenPluginIds = /* @__PURE__ */ new Set();
+	const overrides = parsed.map((entry, index) => readOverrideRecord(entry, index));
+	for (const entry of overrides) {
+		if (seenPluginIds.has(entry.pluginId)) throw new Error(`[dev-plugin-override] duplicate plugin override for "${entry.pluginId}"`);
+		seenPluginIds.add(entry.pluginId);
+	}
+	return overrides;
+}
+function mergeLoadPaths(existingLoadPaths, overrideLoadPaths) {
+	const merged = [...overrideLoadPaths];
+	for (const entry of existingLoadPaths) if (!merged.includes(entry)) merged.push(entry);
+	return merged;
+}
+function applyExplicitDevPluginOverrides(config, overrides) {
+	if (overrides.length === 0) return config;
+	const nextEntries = { ...config.plugins.entries ?? {} };
+	for (const override of overrides) nextEntries[override.pluginId] = {
+		...nextEntries[override.pluginId] ?? {},
+		source: override.source
+	};
+	const existingLoadPaths = Array.isArray(config.plugins.load?.paths) ? config.plugins.load.paths.filter((entry) => typeof entry === "string" && entry.trim().length > 0) : [];
+	return {
+		...config,
+		plugins: {
+			...config.plugins,
+			entries: nextEntries,
+			load: {
+				...config.plugins.load,
+				paths: mergeLoadPaths(existingLoadPaths, overrides.map((entry) => entry.pluginPath))
+			}
+		}
+	};
+}
+function resolveDevPluginOverrideInstallRoots(config, overrides) {
+	const installRoots = [];
+	for (const override of overrides) {
+		const installRecord = config.plugins.installs?.[override.pluginId];
+		const installPath = readOptionalString$6(installRecord?.installPath);
+		if (!installPath || installRoots.includes(installPath)) continue;
+		installRoots.push(installPath);
+	}
+	return installRoots;
+}
+function resolveDevPluginLoadingContext(config, workspaceExtensionsDir, rawOverridesEnv = process.env[DEV_PLUGIN_OVERRIDES_ENV]) {
+	const configWithFirstPartyOverrides = applyDevFirstPartyPluginLoadPaths(config, workspaceExtensionsDir);
+	const overrides = resolveDevPluginOverrides(rawOverridesEnv);
+	return {
+		configWithDevPluginOverrides: applyExplicitDevPluginOverrides(configWithFirstPartyOverrides, overrides),
+		excludedRoots: [...resolveDevFirstPartyPluginInstallRoots(config, workspaceExtensionsDir), ...resolveDevPluginOverrideInstallRoots(config, overrides)].filter((entry, index, list) => list.indexOf(entry) === index),
+		overrides
+	};
+}
+//#endregion
 //#region src/cli/commands/plugin/plugin-mutation-actions.ts
 const pluginInstallLogger = {
 	info: (message) => console.log(message),
@@ -6335,12 +6846,6 @@ function toExtensionRegistry(pluginRegistry) {
 			channel: channel.channel,
 			source: channel.source
 		})),
-		engines: pluginRegistry.engines.map((engine) => ({
-			extensionId: engine.pluginId,
-			kind: engine.kind,
-			factory: engine.factory,
-			source: engine.source
-		})),
 		ncpAgentRuntimes: pluginRegistry.ncpAgentRuntimes.map((runtime) => ({
 			pluginId: runtime.pluginId,
 			kind: runtime.kind,
@@ -6360,11 +6865,11 @@ function toExtensionRegistry(pluginRegistry) {
 //#endregion
 //#region src/cli/commands/plugins.ts
 function loadPluginRegistry(config, workspaceDir) {
-	const workspaceExtensionsDir = resolveDevFirstPartyPluginDir(process.env.NEXTCLAW_DEV_FIRST_PARTY_PLUGIN_DIR);
+	const { configWithDevPluginOverrides, excludedRoots } = resolveDevPluginLoadingContext(config, resolveDevFirstPartyPluginDir(process.env.NEXTCLAW_DEV_FIRST_PARTY_PLUGIN_DIR));
 	return loadOpenClawPlugins({
-		config: applyDevFirstPartyPluginLoadPaths(config, workspaceExtensionsDir),
+		config: configWithDevPluginOverrides,
 		workspaceDir,
-		excludeRoots: resolveDevFirstPartyPluginInstallRoots(config, workspaceExtensionsDir),
+		excludeRoots: excludedRoots,
 		...buildReservedPluginLoadOptions(),
 		logger: {
 			info: (message) => console.log(message),
@@ -6894,7 +7399,7 @@ var ConfigCommands = class {
 };
 //#endregion
 //#region src/cli/commands/mcp.ts
-function normalizeOptionalString$5(value) {
+function normalizeOptionalString$7(value) {
 	if (typeof value !== "string") return;
 	return value.trim() || void 0;
 }
@@ -6917,9 +7422,9 @@ function parseTimeoutMs$1(value) {
 	return Math.trunc(parsed);
 }
 function buildMcpServerDefinition(command, opts) {
-	const transport = (normalizeOptionalString$5(opts.transport) ?? "stdio").toLowerCase();
+	const transport = (normalizeOptionalString$7(opts.transport) ?? "stdio").toLowerCase();
 	const disabled = Boolean(opts.disabled);
-	const explicitAgents = Array.from(new Set((opts.agent ?? []).map((agentId) => normalizeOptionalString$5(agentId)).filter((agentId) => Boolean(agentId))));
+	const explicitAgents = Array.from(new Set((opts.agent ?? []).map((agentId) => normalizeOptionalString$7(agentId)).filter((agentId) => Boolean(agentId))));
 	const allAgents = explicitAgents.length === 0 ? true : Boolean(opts.allAgents);
 	if (transport === "stdio") {
 		if (command.length === 0) throw new Error("stdio transport requires a command after --");
@@ -6929,9 +7434,9 @@ function buildMcpServerDefinition(command, opts) {
 				type: "stdio",
 				command: command[0],
 				args: command.slice(1),
-				cwd: normalizeOptionalString$5(opts.cwd),
+				cwd: normalizeOptionalString$7(opts.cwd),
 				env: parsePairs(opts.env, "env"),
-				stderr: normalizeOptionalString$5(opts.stderr) ?? "pipe"
+				stderr: normalizeOptionalString$7(opts.stderr) ?? "pipe"
 			},
 			scope: {
 				allAgents,
@@ -6947,7 +7452,7 @@ function buildMcpServerDefinition(command, opts) {
 			}
 		};
 	}
-	const url = normalizeOptionalString$5(opts.url);
+	const url = normalizeOptionalString$7(opts.url);
 	if (!url) throw new Error(`${transport} transport requires --url`);
 	const timeoutMs = parseTimeoutMs$1(opts.timeoutMs);
 	const shared = {
@@ -7094,7 +7599,7 @@ function normalizeSecretSource(value) {
 	const normalized = value.trim().toLowerCase();
 	return SECRET_SOURCES.includes(normalized) ? normalized : null;
 }
-function normalizeOptionalString$4(value) {
+function normalizeOptionalString$6(value) {
 	if (typeof value !== "string") return;
 	return value.trim() || void 0;
 }
@@ -7105,9 +7610,9 @@ function parseTimeoutMs(value) {
 	return Math.trunc(parsed);
 }
 function inferProviderAlias(config, ref) {
-	const explicit = normalizeOptionalString$4(ref.provider);
+	const explicit = normalizeOptionalString$6(ref.provider);
 	if (explicit) return explicit;
-	const defaultAlias = normalizeOptionalString$4(config.secrets.defaults[ref.source]);
+	const defaultAlias = normalizeOptionalString$6(config.secrets.defaults[ref.source]);
 	if (defaultAlias) return defaultAlias;
 	return ref.source;
 }
@@ -7125,8 +7630,8 @@ function parseRefsPatch(raw) {
 	for (const [path, value] of Object.entries(raw)) {
 		if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`invalid ref for ${path}`);
 		const source = normalizeSecretSource(value.source);
-		const id = normalizeOptionalString$4(value.id);
-		const provider = normalizeOptionalString$4(value.provider);
+		const id = normalizeOptionalString$6(value.id);
+		const provider = normalizeOptionalString$6(value.provider);
 		if (!source || !id) throw new Error(`invalid ref for ${path}: source/id is required`);
 		output[path] = {
 			source,
@@ -7213,7 +7718,7 @@ var SecretsCommands = class {
 		if (Boolean(opts.strict) && summary.failed > 0) process.exitCode = 1;
 	}
 	async secretsConfigure(opts) {
-		const alias = normalizeOptionalString$4(opts.provider);
+		const alias = normalizeOptionalString$6(opts.provider);
 		if (!alias) throw new Error("provider alias is required");
 		const prevConfig = loadConfig();
 		const nextConfig = structuredClone(prevConfig);
@@ -7226,10 +7731,10 @@ var SecretsCommands = class {
 			if (!source) throw new Error("source is required and must be one of env/file/exec");
 			if (source === "env") nextConfig.secrets.providers[alias] = {
 				source,
-				...normalizeOptionalString$4(opts.prefix) ? { prefix: normalizeOptionalString$4(opts.prefix) } : {}
+				...normalizeOptionalString$6(opts.prefix) ? { prefix: normalizeOptionalString$6(opts.prefix) } : {}
 			};
 			else if (source === "file") {
-				const path = normalizeOptionalString$4(opts.path);
+				const path = normalizeOptionalString$6(opts.path);
 				if (!path) throw new Error("file source requires --path");
 				nextConfig.secrets.providers[alias] = {
 					source,
@@ -7237,13 +7742,13 @@ var SecretsCommands = class {
 					format: "json"
 				};
 			} else {
-				const command = normalizeOptionalString$4(opts.command);
+				const command = normalizeOptionalString$6(opts.command);
 				if (!command) throw new Error("exec source requires --command");
 				nextConfig.secrets.providers[alias] = {
 					source,
 					command,
 					args: Array.isArray(opts.arg) ? opts.arg : [],
-					...normalizeOptionalString$4(opts.cwd) ? { cwd: normalizeOptionalString$4(opts.cwd) } : {},
+					...normalizeOptionalString$6(opts.cwd) ? { cwd: normalizeOptionalString$6(opts.cwd) } : {},
 					timeoutMs: parseTimeoutMs(opts.timeoutMs) ?? 5e3
 				};
 			}
@@ -7288,9 +7793,9 @@ var SecretsCommands = class {
 			if (opts.remove) delete nextConfig.secrets.refs[path];
 			else {
 				const source = normalizeSecretSource(opts.source);
-				const id = normalizeOptionalString$4(opts.id);
+				const id = normalizeOptionalString$6(opts.id);
 				if (!source || !id) throw new Error("apply single ref requires --source and --id");
-				const provider = normalizeOptionalString$4(opts.provider);
+				const provider = normalizeOptionalString$6(opts.provider);
 				nextConfig.secrets.refs[path] = {
 					source,
 					id,
@@ -7636,34 +8141,114 @@ function printCronJobs(jobs) {
 	for (const job of jobs) console.log(`${job.id} [${job.enabled ? "enabled" : "disabled"}] ${job.name} ${formatCronSchedule(job.schedule)}`);
 }
 //#endregion
-//#region src/cli/commands/shared/ui-bridge-api.service.ts
-function resolveManagedApiBase() {
-	const state = readServiceState();
-	if (!state?.pid) return null;
-	if (!isProcessRunning(state.pid)) return null;
-	if (typeof state.uiUrl === "string" && state.uiUrl.trim().length > 0) return state.uiUrl.replace(/\/+$/, "");
-	if (typeof state.apiUrl === "string" && state.apiUrl.trim().length > 0) return state.apiUrl.replace(/\/api\/?$/, "").replace(/\/+$/, "");
-	return null;
-}
-var UiBridgeApiClient = class {
-	cookie;
-	constructor(apiBase) {
-		this.apiBase = apiBase;
+//#region src/cli/runtime-state/local-ui-runtime.store.ts
+var LocalUiRuntimeStore = class {
+	get path() {
+		return resolve(getDataDir(), "run", "ui-runtime.json");
 	}
-	getCookie = async () => {
-		if (this.cookie !== void 0) return this.cookie;
-		const bridgeSecret = ensureUiBridgeSecret();
-		const response = await fetch(`${this.apiBase}/api/auth/bridge`, {
-			method: "POST",
-			headers: { "x-nextclaw-ui-bridge-secret": bridgeSecret }
-		});
-		if (!response.ok) throw new Error(`bridge auth failed with status ${response.status}`);
-		const payload = await response.json();
-		if (!payload.ok) throw new Error(payload.error?.message ?? "bridge auth failed");
-		this.cookie = typeof payload.data.cookie === "string" && payload.data.cookie.trim() ? payload.data.cookie.trim() : null;
-		return this.cookie;
+	read = () => {
+		if (!existsSync(this.path)) return null;
+		try {
+			const raw = readFileSync(this.path, "utf-8");
+			return JSON.parse(raw);
+		} catch {
+			return null;
+		}
 	};
-	request = async (params) => {
+	write = (state) => {
+		mkdirSync(resolve(this.path, ".."), { recursive: true });
+		writeFileSync(this.path, JSON.stringify(state, null, 2));
+	};
+	update = (updater) => {
+		const current = this.read();
+		if (!current) return null;
+		const next = updater(current);
+		this.write(next);
+		return next;
+	};
+	clear = () => {
+		if (existsSync(this.path)) rmSync(this.path, { force: true });
+	};
+	clearIfOwnedByProcess = (pid = process.pid) => {
+		if (this.read()?.pid === pid) this.clear();
+	};
+	writeCurrentProcess = (uiConfig, pid = process.pid) => {
+		const existing = this.read();
+		const uiUrl = resolveUiApiBase(uiConfig.host, uiConfig.port);
+		const state = {
+			pid,
+			startedAt: existing?.pid === pid && typeof existing.startedAt === "string" ? existing.startedAt : (/* @__PURE__ */ new Date()).toISOString(),
+			uiUrl,
+			apiUrl: `${uiUrl}/api`,
+			uiHost: uiConfig.host,
+			uiPort: uiConfig.port,
+			...existing?.remote ? { remote: existing.remote } : {}
+		};
+		this.write(state);
+		return state;
+	};
+};
+const localUiRuntimeStore = new LocalUiRuntimeStore();
+//#endregion
+//#region src/cli/runtime-state/local-ui-discovery.service.ts
+var LocalUiDiscoveryService = class {
+	constructor(localUiStore = localUiRuntimeStore, managedServiceStore = managedServiceStateStore, isProcessRunningFn = (pid) => isProcessRunning(pid)) {
+		this.localUiStore = localUiStore;
+		this.managedServiceStore = managedServiceStore;
+		this.isProcessRunningFn = isProcessRunningFn;
+	}
+	readRunningState = (state) => {
+		if (!state || !this.isProcessRunningFn(state.pid)) return null;
+		return state;
+	};
+	readRunningRuntimeState = () => {
+		return this.readRunningState(this.localUiStore.read()) ?? this.readRunningState(this.managedServiceStore.read());
+	};
+	resolveApiBase = () => {
+		const state = this.readRunningRuntimeState();
+		if (!state) return null;
+		if (typeof state.uiUrl === "string" && state.uiUrl.trim().length > 0) return state.uiUrl.replace(/\/+$/, "");
+		if (typeof state.apiUrl === "string" && state.apiUrl.trim().length > 0) return state.apiUrl.replace(/\/api\/?$/, "").replace(/\/+$/, "");
+		return null;
+	};
+	resolveLocalOrigin = (config) => {
+		const state = this.readRunningRuntimeState();
+		const runtimePort = state && typeof state.uiPort === "number" && Number.isFinite(state.uiPort) ? state.uiPort : null;
+		if (runtimePort !== null) return resolveLocalUiBaseUrl({
+			host: "0.0.0.0",
+			port: runtimePort
+		});
+		return resolveLocalUiBaseUrl({
+			host: "0.0.0.0",
+			port: typeof config.ui.port === "number" && Number.isFinite(config.ui.port) ? config.ui.port : 55667
+		});
+	};
+};
+const localUiDiscoveryService = new LocalUiDiscoveryService();
+//#endregion
+//#region src/cli/commands/shared/ui-bridge-api.service.ts
+function resolveLocalUiApiBase() {
+	return localUiDiscoveryService.resolveApiBase();
+}
+var UiBridgeApiClient = class {
+	cookie;
+	constructor(apiBase) {
+		this.apiBase = apiBase;
+	}
+	getCookie = async () => {
+		if (this.cookie !== void 0) return this.cookie;
+		const bridgeSecret = ensureUiBridgeSecret();
+		const response = await fetch(`${this.apiBase}/api/auth/bridge`, {
+			method: "POST",
+			headers: { "x-nextclaw-ui-bridge-secret": bridgeSecret }
+		});
+		if (!response.ok) throw new Error(`bridge auth failed with status ${response.status}`);
+		const payload = await response.json();
+		if (!payload.ok) throw new Error(payload.error?.message ?? "bridge auth failed");
+		this.cookie = typeof payload.data.cookie === "string" && payload.data.cookie.trim() ? payload.data.cookie.trim() : null;
+		return this.cookie;
+	};
+	request = async (params) => {
 		const cookie = await this.getCookie();
 		const response = await fetch(`${this.apiBase}${params.path}`, {
 			method: params.method ?? "GET",
@@ -7690,7 +8275,7 @@ var CronCommands = class {
 		this.local = local;
 	}
 	createApiClient = () => {
-		const apiBase = resolveManagedApiBase();
+		const apiBase = resolveLocalUiApiBase();
 		if (!apiBase) return null;
 		return new UiBridgeApiClient(apiBase);
 	};
@@ -7857,13 +8442,13 @@ function createUnusedRuntime(_params) {
 	throw new Error("runtime creation is not available during runtime listing");
 }
 function loadRuntimeOnlyPluginRegistry(config, workspaceDir) {
-	const workspaceExtensionsDir = resolveDevFirstPartyPluginDir(process.env.NEXTCLAW_DEV_FIRST_PARTY_PLUGIN_DIR);
+	const { configWithDevPluginOverrides, excludedRoots } = resolveDevPluginLoadingContext(config, resolveDevFirstPartyPluginDir(process.env.NEXTCLAW_DEV_FIRST_PARTY_PLUGIN_DIR));
 	return loadOpenClawPlugins({
-		config: applyDevFirstPartyPluginLoadPaths(config, workspaceExtensionsDir),
+		config: configWithDevPluginOverrides,
 		workspaceDir,
 		includeBundled: false,
 		kinds: ["agent-runtime"],
-		excludeRoots: resolveDevFirstPartyPluginInstallRoots(config, workspaceExtensionsDir),
+		excludeRoots: excludedRoots,
 		...buildReservedPluginLoadOptions(),
 		logger: {
 			info: (message) => console.log(message),
@@ -8025,7 +8610,7 @@ var AgentCommands = class {
 //#region src/cli/commands/remote-support/remote-runtime-support.ts
 let currentProcessRemoteRuntimeState = null;
 function hasRunningNextclawManagedService() {
-	const state = readServiceState();
+	const state = managedServiceStateStore.read();
 	return Boolean(state && isProcessRunning(state.pid));
 }
 function createNextclawRemotePlatformClient() {
@@ -8038,7 +8623,7 @@ function createNextclawRemotePlatformClient() {
 			requireConfigured: true
 		}).platformBase,
 		readManagedServiceState: () => {
-			const state = readServiceState();
+			const state = managedServiceStateStore.read();
 			if (!state) return null;
 			return {
 				pid: state.pid,
@@ -8057,9 +8642,13 @@ function createNextclawRemoteConnector(params = {}) {
 function createNextclawRemoteStatusStore(mode) {
 	return new RemoteStatusStore(mode, { writeRemoteState: (next) => {
 		currentProcessRemoteRuntimeState = next;
-		const serviceState = readServiceState();
+		if (localUiRuntimeStore.read()?.pid === process.pid) localUiRuntimeStore.update((state) => ({
+			...state,
+			remote: next
+		}));
+		const serviceState = managedServiceStateStore.read();
 		if (!serviceState || serviceState.pid !== process.pid) return;
-		updateServiceState((state) => ({
+		managedServiceStateStore.update((state) => ({
 			...state,
 			remote: next
 		}));
@@ -8069,10 +8658,12 @@ function buildNextclawConfiguredRemoteState(config) {
 	return buildConfiguredRemoteState(config);
 }
 function readCurrentNextclawRemoteRuntimeState() {
-	const serviceState = readServiceState();
-	const currentRemoteState = currentProcessRemoteRuntimeState ?? serviceState?.remote ?? null;
+	const uiRuntimeState = localUiRuntimeStore.read();
+	const serviceState = managedServiceStateStore.read();
+	const currentRemoteState = currentProcessRemoteRuntimeState ?? uiRuntimeState?.remote ?? serviceState?.remote ?? null;
 	if (!currentRemoteState) return null;
-	if (!serviceState || isProcessRunning(serviceState.pid)) return currentRemoteState;
+	const owningRuntime = uiRuntimeState ?? serviceState;
+	if (!owningRuntime || isProcessRunning(owningRuntime.pid)) return currentRemoteState;
 	return {
 		...currentRemoteState,
 		state: currentRemoteState.enabled ? "disconnected" : "disabled",
@@ -8088,15 +8679,13 @@ function resolveNextclawRemoteStatusSnapshot(config) {
 }
 //#endregion
 //#region src/cli/commands/remote.ts
-function normalizeOptionalString$3(value) {
+function normalizeOptionalString$5(value) {
 	if (typeof value !== "string") return;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : void 0;
 }
 function resolveConfiguredLocalOrigin(config) {
-	const state = readServiceState();
-	if (state && 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}`;
+	return localUiDiscoveryService.resolveLocalOrigin(config);
 }
 async function probeLocalUi(localOrigin) {
 	try {
@@ -8187,8 +8776,8 @@ var RemoteCommands = class {
 			configuredEnabled: snapshot.configuredEnabled,
 			runtime: snapshot.runtime,
 			localOrigin: resolvedLocalOrigin,
-			deviceName: snapshot.runtime?.deviceName ?? normalizeOptionalString$3(config.remote.deviceName) ?? hostname(),
-			platformBase: snapshot.runtime?.platformBase ?? normalizeOptionalString$3(config.remote.platformApiBase) ?? normalizeOptionalString$3(config.providers.nextclaw?.apiBase) ?? null
+			deviceName: snapshot.runtime?.deviceName ?? normalizeOptionalString$5(config.remote.deviceName) ?? hostname(),
+			platformBase: snapshot.runtime?.platformBase ?? normalizeOptionalString$5(config.remote.platformApiBase) ?? normalizeOptionalString$5(config.providers.nextclaw?.apiBase) ?? null
 		};
 	}
 	async status(opts = {}) {
@@ -8214,8 +8803,8 @@ var RemoteCommands = class {
 		const snapshot = resolveNextclawRemoteStatusSnapshot(config);
 		const localOrigin = snapshot.runtime?.localOrigin ?? this.deps.currentLocalOrigin ?? resolveConfiguredLocalOrigin(config);
 		const localUi = await probeLocalUi(localOrigin);
-		const token = normalizeOptionalString$3(config.providers.nextclaw?.apiKey);
-		const platformApiBase = normalizeOptionalString$3(config.remote.platformApiBase) ?? normalizeOptionalString$3(config.providers.nextclaw?.apiBase);
+		const token = normalizeOptionalString$5(config.providers.nextclaw?.apiKey);
+		const platformApiBase = normalizeOptionalString$5(config.remote.platformApiBase) ?? normalizeOptionalString$5(config.providers.nextclaw?.apiBase);
 		const checks = [
 			{
 				name: "remote-enabled",
@@ -8324,7 +8913,7 @@ var DiagnosticsCommands = class {
 	constructor(deps) {
 		this.deps = deps;
 	}
-	async status(opts = {}) {
+	status = async (opts = {}) => {
 		const report = await this.collectRuntimeStatus({
 			verbose: Boolean(opts.verbose),
 			fix: Boolean(opts.fix)
@@ -8340,25 +8929,53 @@ var DiagnosticsCommands = class {
 			verbose: Boolean(opts.verbose)
 		});
 		process.exitCode = 0;
-	}
-	async doctor(opts = {}) {
+	};
+	doctor = async (opts = {}) => {
 		const report = await this.collectRuntimeStatus({
 			verbose: Boolean(opts.verbose),
 			fix: Boolean(opts.fix)
 		});
-		const checkPort = await this.checkPortAvailability({
-			host: report.process.running ? report.endpoints.uiUrl ? new URL(report.endpoints.uiUrl).hostname : "127.0.0.1" : "127.0.0.1",
-			port: (() => {
-				try {
-					const base = report.process.running && report.endpoints.uiUrl ? report.endpoints.uiUrl : report.endpoints.configuredUiUrl;
-					return Number(new URL(base).port || 80);
-				} catch {
-					return 55667;
-				}
-			})()
+		const checkPort = await this.checkPortAvailability(this.resolveDoctorPortCheckTarget(report));
+		const checks = this.buildDoctorChecks(report, checkPort);
+		const exitCode = this.resolveDoctorExitCode(checks);
+		if (opts.json) {
+			console.log(JSON.stringify({
+				generatedAt: report.generatedAt,
+				checks,
+				status: report,
+				exitCode
+			}, null, 2));
+			process.exitCode = exitCode;
+			return;
+		}
+		printDoctorReport({
+			logo: this.deps.logo,
+			generatedAt: report.generatedAt,
+			checks,
+			recommendations: report.recommendations,
+			verbose: Boolean(opts.verbose),
+			logTail: report.logTail
 		});
+		process.exitCode = exitCode;
+	};
+	resolveDoctorPortCheckTarget = (report) => {
+		const host = report.process.running && report.endpoints.uiUrl ? new URL(report.endpoints.uiUrl).hostname : "127.0.0.1";
+		try {
+			const base = report.process.running && report.endpoints.uiUrl ? report.endpoints.uiUrl : report.endpoints.configuredUiUrl;
+			return {
+				host,
+				port: Number(new URL(base).port || 80)
+			};
+		} catch {
+			return {
+				host,
+				port: 55667
+			};
+		}
+	};
+	buildDoctorChecks = (report, checkPort) => {
 		const providerConfigured = report.providers.some((provider) => provider.configured);
-		const checks = [
+		return [
 			{
 				name: "config-file",
 				status: report.configExists ? "pass" : "fail",
@@ -8376,12 +8993,12 @@ var DiagnosticsCommands = class {
 			},
 			{
 				name: "service-health",
-				status: report.process.running ? report.health.managed.state === "ok" ? "pass" : "fail" : report.health.configured.state === "ok" ? "warn" : "warn",
+				status: report.process.running ? report.health.managed.state === "ok" ? "pass" : "fail" : "warn",
 				detail: report.process.running ? `${report.health.managed.state}: ${report.health.managed.detail}` : `${report.health.configured.state}: ${report.health.configured.detail}`
 			},
 			{
 				name: "ui-port-availability",
-				status: report.process.running ? "pass" : checkPort.available ? "pass" : "fail",
+				status: report.process.running || checkPort.available ? "pass" : "fail",
 				detail: report.process.running ? "managed by running service" : checkPort.available ? "available" : checkPort.detail
 			},
 			{
@@ -8390,40 +9007,23 @@ var DiagnosticsCommands = class {
 				detail: providerConfigured ? "at least one provider configured" : "no provider api key configured"
 			}
 		];
-		const failed = checks.filter((check) => check.status === "fail");
-		const warned = checks.filter((check) => check.status === "warn");
-		const exitCode = failed.length > 0 ? 1 : warned.length > 0 ? 1 : 0;
-		if (opts.json) {
-			console.log(JSON.stringify({
-				generatedAt: report.generatedAt,
-				checks,
-				status: report,
-				exitCode
-			}, null, 2));
-			process.exitCode = exitCode;
-			return;
-		}
-		printDoctorReport({
-			logo: this.deps.logo,
-			generatedAt: report.generatedAt,
-			checks,
-			recommendations: report.recommendations,
-			verbose: Boolean(opts.verbose),
-			logTail: report.logTail
-		});
-		process.exitCode = exitCode;
-	}
-	async collectRuntimeStatus(params) {
+	};
+	resolveDoctorExitCode = (checks) => {
+		if (checks.some((check) => check.status === "fail")) return 1;
+		if (checks.some((check) => check.status === "warn")) return 1;
+		return 0;
+	};
+	collectRuntimeStatus = async (params) => {
 		const configPath = getConfigPath();
 		const config = loadConfig();
 		const workspacePath = getWorkspacePath(config.agents.defaults.workspace);
-		const serviceStatePath = resolve(getDataDir(), "run", "service.json");
+		const serviceStatePath = managedServiceStateStore.path;
 		const fixActions = [];
-		let serviceState = readServiceState();
+		let serviceState = managedServiceStateStore.read();
 		if (params.fix && serviceState && !isProcessRunning(serviceState.pid)) {
-			clearServiceState();
+			managedServiceStateStore.clear();
 			fixActions.push("Cleared stale service state file.");
-			serviceState = readServiceState();
+			serviceState = managedServiceStateStore.read();
 		}
 		const managedByState = Boolean(serviceState);
 		const running = Boolean(serviceState && isProcessRunning(serviceState.pid));
@@ -8459,7 +9059,7 @@ var DiagnosticsCommands = class {
 			issues,
 			recommendations
 		});
-		const logTail = params.verbose ? this.readLogTail(serviceState?.logPath ?? resolveServiceLogPath(), 25) : [];
+		const logTail = params.verbose ? this.readLogTail(serviceState?.logPath ?? resolveAppLogPath("service"), 25) : [];
 		const level = running ? managedHealth.state === "ok" ? issues.length > 0 ? "degraded" : "healthy" : "degraded" : "stopped";
 		return {
 			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -8497,8 +9097,8 @@ var DiagnosticsCommands = class {
 			level,
 			exitCode: 0
 		};
-	}
-	async probeApiHealth(url, timeoutMs = 1500) {
+	};
+	probeApiHealth = async (url, timeoutMs = 1500) => {
 		const controller = new AbortController();
 		const timer = setTimeout(() => controller.abort(), timeoutMs);
 		try {
@@ -8529,8 +9129,8 @@ var DiagnosticsCommands = class {
 		} finally {
 			clearTimeout(timer);
 		}
-	}
-	listProviderStatuses(config) {
+	};
+	listProviderStatuses = (config) => {
 		return listBuiltinProviders().map((spec) => {
 			const provider = config.providers[spec.name];
 			const apiKeyRefSet = hasSecretRef(config, `providers.${spec.name}.apiKey`);
@@ -8555,8 +9155,8 @@ var DiagnosticsCommands = class {
 				detail: provider.apiKey ? "apiKey set" : apiKeyRefSet ? "apiKey ref set" : "apiKey not set"
 			};
 		});
-	}
-	collectRuntimeIssues(params) {
+	};
+	collectRuntimeIssues = (params) => {
 		if (!existsSync(params.configPath)) {
 			params.issues.push("Config file is missing.");
 			params.recommendations.push(`Run ${APP_NAME} init to create config files.`);
@@ -8571,7 +9171,7 @@ var DiagnosticsCommands = class {
 		}
 		if (params.running && params.managedHealth.state !== "ok") {
 			params.issues.push(`Managed service health check failed: ${params.managedHealth.detail}`);
-			params.recommendations.push(`Check logs at ${params.serviceState?.logPath ?? resolveServiceLogPath()}.`);
+			params.recommendations.push(`Check logs at ${params.serviceState?.logPath ?? resolveAppLogPath("service")}.`);
 		}
 		if (params.running && params.serviceState?.startupState === "degraded" && params.managedHealth.state !== "ok") {
 			const startupHint = params.serviceState.startupLastProbeError ? ` (${params.serviceState.startupLastProbeError})` : "";
@@ -8584,8 +9184,8 @@ var DiagnosticsCommands = class {
 			params.recommendations.push("Another process may be occupying the UI port; stop it or use --ui-port with a free port.");
 		}
 		if (!params.providers.some((provider) => provider.configured)) params.recommendations.push("Configure at least one provider API key in UI or config before expecting agent replies.");
-	}
-	readLogTail(path, maxLines = 25) {
+	};
+	readLogTail = (path, maxLines = 25) => {
 		if (!existsSync(path)) return [];
 		try {
 			const lines = readFileSync(path, "utf-8").split(/\r?\n/).filter(Boolean);
@@ -8594,8 +9194,8 @@ var DiagnosticsCommands = class {
 		} catch {
 			return [];
 		}
-	}
-	async checkPortAvailability(params) {
+	};
+	checkPortAvailability = async (params) => {
 		return await new Promise((resolve) => {
 			const server = createServer();
 			server.once("error", (error) => {
@@ -8613,7 +9213,34 @@ var DiagnosticsCommands = class {
 				});
 			});
 		});
-	}
+	};
+};
+//#endregion
+//#region src/cli/commands/logs.ts
+var LogsCommands = class {
+	constructor(runtime = getLoggingRuntime()) {
+		this.runtime = runtime;
+	}
+	logsPath = () => {
+		const paths = this.runtime.getPaths();
+		console.log([
+			`Logs directory: ${paths.logsDir}`,
+			`Service log: ${paths.serviceLogPath}`,
+			`Crash log: ${paths.crashLogPath}`,
+			`Archive: ${paths.archiveDir}`
+		].join("\n"));
+	};
+	logsTail = (opts = {}) => {
+		const kind = opts.crash ? "crash" : "service";
+		const rawLines = Number(opts.lines);
+		const lines = Number.isFinite(rawLines) && rawLines > 0 ? Math.floor(rawLines) : 40;
+		const output = this.runtime.tail(kind, lines);
+		if (output.length === 0) {
+			console.log(`No log entries found in ${this.runtime.resolveLogPath(kind)}.`);
+			return;
+		}
+		console.log(output.join("\n"));
+	};
 };
 //#endregion
 //#region src/cli/commands/service-support/runtime/service-port-probe.ts
@@ -8732,17 +9359,42 @@ async function probeHealthEndpoint(healthUrl) {
 		req.end();
 	});
 }
+async function inspectUiTarget(params) {
+	const { checkPortAvailabilityFn, healthUrl, host, port, probeHealthEndpointFn } = params;
+	const availability = await (checkPortAvailabilityFn ?? checkPortAvailability)({
+		host,
+		port
+	});
+	if (availability.available) return {
+		state: "available",
+		availabilityDetail: availability.detail,
+		probeError: null
+	};
+	const probe = await (probeHealthEndpointFn ?? probeHealthEndpoint)(healthUrl);
+	if (probe.healthy) return {
+		state: "healthy-existing",
+		availabilityDetail: availability.detail,
+		probeError: null
+	};
+	return {
+		state: "occupied-unhealthy",
+		availabilityDetail: availability.detail,
+		probeError: probe.error
+	};
+}
 async function describeUnmanagedHealthyTargetMessage(params) {
 	const uiConfig = resolveUiConfig(loadConfig(), params.uiOverrides);
 	const healthUrl = `${resolveUiApiBase(uiConfig.host, uiConfig.port)}/api/health`;
-	if ((await (params.checkPortAvailabilityFn ?? checkPortAvailability)({
+	if ((await inspectUiTarget({
 		host: uiConfig.host,
-		port: uiConfig.port
-	})).available) return null;
-	if (!(await (params.probeHealthEndpointFn ?? probeHealthEndpoint)(healthUrl)).healthy) return null;
+		port: uiConfig.port,
+		healthUrl,
+		checkPortAvailabilityFn: params.checkPortAvailabilityFn,
+		probeHealthEndpointFn: params.probeHealthEndpointFn
+	})).state !== "healthy-existing") return null;
 	return [
 		`Target UI health: ${healthUrl}`,
-		`A healthy ${APP_NAME} service is already responding on this port, but it is not tracked by ${resolveServiceStatePath()}.`,
+		`A healthy ${APP_NAME} service is already responding on this port, but it is not tracked by ${managedServiceStateStore.path}.`,
 		`${APP_NAME} restart only stops the background service recorded in managed state; it will not auto-kill Docker or other external listeners.`,
 		`Fix: stop that external service first or rerun with --ui-port <port>.`
 	].join("\n");
@@ -9076,7 +9728,7 @@ function claimManagedRemoteRuntimeOwnership(params) {
 	const managedConflict = detectManagedRemoteOwnershipConflict({
 		currentPid,
 		isProcessRunningFn,
-		readServiceStateFn: params.readServiceStateFn ?? readServiceState
+		readServiceStateFn: params.readServiceStateFn ?? managedServiceStateStore.read
 	});
 	if (managedConflict) return {
 		ok: false,
@@ -9119,7 +9771,7 @@ function createManagedRemoteModuleForUi(params) {
 	});
 }
 function writeInitialManagedServiceState(params) {
-	writeServiceState({
+	managedServiceStateStore.write({
 		pid: params.snapshot.pid,
 		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
 		uiUrl: params.snapshot.uiUrl,
@@ -9134,7 +9786,7 @@ function writeInitialManagedServiceState(params) {
 	});
 }
 function writeReadyManagedServiceState(params) {
-	const currentState = readServiceState();
+	const currentState = managedServiceStateStore.read();
 	const state = {
 		pid: params.snapshot.pid,
 		startedAt: currentState?.startedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
@@ -9149,7 +9801,7 @@ function writeReadyManagedServiceState(params) {
 		startupCheckedAt: (/* @__PURE__ */ new Date()).toISOString(),
 		...currentState?.remote ? { remote: currentState.remote } : {}
 	};
-	writeServiceState(state);
+	managedServiceStateStore.write(state);
 	return state;
 }
 //#endregion
@@ -9197,8 +9849,8 @@ function resolveSessionRouteCandidate(params) {
 function spawnManagedService(params) {
 	const { appName, config, uiConfig, uiUrl, apiUrl, healthUrl, startupTimeoutMs, resolveStartupTimeoutMs, appendStartupStage, printStartupFailureDiagnostics, resolveServiceLogPath } = params;
 	const logPath = resolveServiceLogPath();
-	mkdirSync(resolve(logPath, ".."), { recursive: true });
-	const logFd = openSync(logPath, "a");
+	new FileLogSink({ serviceLogPath: logPath }).ensureReady();
+	mkdirSync(dirname(logPath), { recursive: true });
 	const readinessTimeoutMs = resolveStartupTimeoutMs(startupTimeoutMs);
 	const quickPhaseTimeoutMs = Math.min(8e3, readinessTimeoutMs);
 	const extendedPhaseTimeoutMs = Math.max(0, readinessTimeoutMs - quickPhaseTimeoutMs);
@@ -9218,15 +9870,10 @@ function spawnManagedService(params) {
 	appendStartupStage(logPath, `spawning background process: ${cliLaunch.command} ${childArgs.join(" ")}`);
 	const child = spawn(cliLaunch.command, childArgs, {
 		env: process.env,
-		stdio: [
-			"ignore",
-			logFd,
-			logFd
-		],
+		stdio: "ignore",
 		detached: true
 	});
 	appendStartupStage(logPath, `spawned background process pid=${child.pid ?? "unknown"}`);
-	closeSync(logFd);
 	if (!child.pid) {
 		appendStartupStage(logPath, "spawn failed: child pid missing");
 		console.error("Error: Failed to start background service.");
@@ -9371,32 +10018,10 @@ var ServiceFileWatcherRegistry = class {
 		}));
 	};
 };
-function writeLocalServiceDiscoveryState(uiConfig, pid = process.pid) {
-	const uiUrl = resolveUiApiBase(uiConfig.host, uiConfig.port);
-	const apiUrl = `${uiUrl}/api`;
-	const existing = readServiceState();
-	writeServiceState({
-		pid,
-		startedAt: existing?.pid === pid && typeof existing.startedAt === "string" ? existing.startedAt : (/* @__PURE__ */ new Date()).toISOString(),
-		uiUrl,
-		apiUrl,
-		uiHost: uiConfig.host,
-		uiPort: uiConfig.port,
-		logPath: existing?.logPath ?? resolveServiceLogPath(),
-		startupState: existing?.startupState ?? "ready",
-		startupLastProbeError: existing?.startupLastProbeError ?? null,
-		startupTimeoutMs: existing?.startupTimeoutMs,
-		startupCheckedAt: (/* @__PURE__ */ new Date()).toISOString(),
-		...existing?.remote ? { remote: existing.remote } : {}
-	});
-}
-function clearOwnedServiceState(pid = process.pid) {
-	if (readServiceState()?.pid === pid) clearServiceState();
-}
 function finalizeLocalUiStartup(params) {
 	const { setUiEventPublisher, uiConfig, uiStartup } = params;
 	setUiEventPublisher(uiStartup?.publish);
-	if (uiStartup) writeLocalServiceDiscoveryState(uiConfig);
+	if (uiStartup) localUiRuntimeStore.writeCurrentProcess(uiConfig);
 }
 async function startGatewayRuntimeSupport(params) {
 	const { cronJobs, cronStorePath, reloadCronStore, remoteModule, startCron, startHeartbeat, watchConfigFile, watcherRegistry } = params;
@@ -9423,7 +10048,7 @@ function resolveRemoteServiceView(currentUi) {
 		uiUrl: resolveUiApiBase(currentUi.host, currentUi.port),
 		uiPort: currentUi.port
 	};
-	const serviceState = readServiceState();
+	const serviceState = managedServiceStateStore.read();
 	const serviceRunning = Boolean(serviceState && isProcessRunning(serviceState.pid));
 	return {
 		running: serviceRunning,
@@ -9462,7 +10087,7 @@ async function controlCurrentProcessRuntime(action, controller) {
 	};
 }
 async function controlManagedService(action, deps) {
-	const state = readServiceState();
+	const state = managedServiceStateStore.read();
 	const running = Boolean(state && isProcessRunning(state.pid));
 	const currentProcess = Boolean(running && state?.pid === process.pid);
 	const uiOverrides = resolveManagedUiOverrides();
@@ -9548,7 +10173,7 @@ function launchManagedSelfControl(params = {}) {
 		"const { spawn } = require(\"node:child_process\");",
 		"const { rmSync } = require(\"node:fs\");",
 		`const parentPid = ${process.pid};`,
-		`const serviceStatePath = ${JSON.stringify(resolveServiceStatePath())};`,
+		`const serviceStatePath = ${JSON.stringify(managedServiceStateStore.path)};`,
 		`const command = ${JSON.stringify(params.command ?? null)};`,
 		`const args = ${JSON.stringify(params.args ?? [])};`,
 		`const cwd = ${JSON.stringify(process.cwd())};`,
@@ -9597,7 +10222,7 @@ function launchManagedSelfControl(params = {}) {
 }
 //#endregion
 //#region src/cli/commands/remote-support/remote-access-host.ts
-function normalizeOptionalString$2(value) {
+function normalizeOptionalString$4(value) {
 	if (typeof value !== "string") return null;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : null;
@@ -9626,8 +10251,8 @@ var RemoteAccessHost = class {
 		const status = this.deps.remoteCommands.getStatusView();
 		return {
 			account: this.readAccountView({
-				token: normalizeOptionalString$2(config.providers.nextclaw?.apiKey),
-				apiBase: normalizeOptionalString$2(config.providers.nextclaw?.apiBase),
+				token: normalizeOptionalString$4(config.providers.nextclaw?.apiKey),
+				apiBase: normalizeOptionalString$4(config.providers.nextclaw?.apiBase),
 				platformBase: status.platformBase
 			}),
 			settings: {
@@ -9658,7 +10283,7 @@ var RemoteAccessHost = class {
 	pollBrowserAuth = async (input) => {
 		const config = loadConfig(getConfigPath());
 		const result = await this.deps.platformAuthCommands.pollBrowserAuth({
-			apiBase: normalizeOptionalString$2(input.apiBase) ?? normalizeOptionalString$2(config.remote.platformApiBase) ?? normalizeOptionalString$2(config.providers.nextclaw?.apiBase) ?? void 0,
+			apiBase: normalizeOptionalString$4(input.apiBase) ?? normalizeOptionalString$4(config.remote.platformApiBase) ?? normalizeOptionalString$4(config.providers.nextclaw?.apiBase) ?? void 0,
 			sessionId: input.sessionId
 		});
 		if (result.status !== "authorized") return result;
@@ -9784,51 +10409,71 @@ var AssetPutTool = class {
 	description = "Put a normal file path or base64 bytes into the managed asset store.";
 	parameters = {
 		type: "object",
-		properties: {
-			path: {
-				type: "string",
-				description: "Existing local file path to put into the asset store."
-			},
-			bytesBase64: {
-				type: "string",
-				description: "Base64 file bytes. Use together with fileName when no source path exists."
+		oneOf: [{
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Existing local file path to put into the asset store."
+				},
+				fileName: {
+					type: "string",
+					description: "Optional asset file name override."
+				},
+				mimeType: {
+					type: "string",
+					description: "Optional mime type override."
+				}
 			},
-			fileName: {
-				type: "string",
-				description: "Optional asset file name override. Required when using bytesBase64."
+			required: ["path"],
+			additionalProperties: false
+		}, {
+			type: "object",
+			properties: {
+				bytesBase64: {
+					type: "string",
+					description: "Base64 file bytes. Use together with fileName when no source path exists."
+				},
+				fileName: {
+					type: "string",
+					description: "Asset file name. Required when using bytesBase64."
+				},
+				mimeType: {
+					type: "string",
+					description: "Optional mime type override."
+				}
 			},
-			mimeType: {
-				type: "string",
-				description: "Optional mime type override."
-			}
-		}
+			required: ["bytesBase64", "fileName"],
+			additionalProperties: false
+		}]
 	};
 	constructor(assetStore, contentBasePath) {
 		this.assetStore = assetStore;
 		this.contentBasePath = contentBasePath;
 	}
-	async execute(args) {
+	execute = async (args) => {
 		const path = readOptionalString$5(args?.path);
 		const fileName = readOptionalString$5(args?.fileName);
 		const mimeType = readOptionalString$5(args?.mimeType);
 		const bytes = readOptionalBase64Bytes(args?.bytesBase64);
-		let record;
-		if (path) record = await this.assetStore.putPath({
-			path,
-			fileName: fileName ?? void 0,
-			mimeType
-		});
-		else if (bytes && fileName) record = await this.assetStore.putBytes({
-			fileName,
-			mimeType,
-			bytes
-		});
-		else throw new Error("asset_put requires either path, or bytesBase64 + fileName.");
-		return {
+		if (path) return {
 			ok: true,
-			asset: toAssetPayload(record, this.contentBasePath)
+			asset: toAssetPayload(await this.assetStore.putPath({
+				path,
+				fileName: fileName ?? void 0,
+				mimeType
+			}), this.contentBasePath)
 		};
-	}
+		if (bytes && fileName) return {
+			ok: true,
+			asset: toAssetPayload(await this.assetStore.putBytes({
+				fileName,
+				mimeType,
+				bytes
+			}), this.contentBasePath)
+		};
+		throw new Error("asset_put received invalid arguments after validation.");
+	};
 };
 var AssetExportTool = class {
 	name = "asset_export";
@@ -9845,12 +10490,13 @@ var AssetExportTool = class {
 				description: "Destination file path."
 			}
 		},
-		required: ["assetUri", "targetPath"]
+		required: ["assetUri", "targetPath"],
+		additionalProperties: false
 	};
 	constructor(assetStore) {
 		this.assetStore = assetStore;
 	}
-	async execute(args) {
+	execute = async (args) => {
 		const assetUri = readOptionalString$5(args?.assetUri);
 		const targetPath = readOptionalString$5(args?.targetPath);
 		if (!assetUri || !targetPath) throw new Error("asset_export requires assetUri and targetPath.");
@@ -9859,7 +10505,7 @@ var AssetExportTool = class {
 			assetUri,
 			exportedPath: await this.assetStore.export({ uri: assetUri }, resolve(targetPath))
 		};
-	}
+	};
 };
 var AssetStatTool = class {
 	name = "asset_stat";
@@ -9870,13 +10516,14 @@ var AssetStatTool = class {
 			type: "string",
 			description: "Managed asset URI to inspect."
 		} },
-		required: ["assetUri"]
+		required: ["assetUri"],
+		additionalProperties: false
 	};
 	constructor(assetStore, contentBasePath) {
 		this.assetStore = assetStore;
 		this.contentBasePath = contentBasePath;
 	}
-	async execute(args) {
+	execute = async (args) => {
 		const assetUri = readOptionalString$5(args?.assetUri);
 		if (!assetUri) throw new Error("asset_stat requires assetUri.");
 		const record = await this.assetStore.statRecord(assetUri);
@@ -9891,7 +10538,7 @@ var AssetStatTool = class {
 			ok: true,
 			asset: toAssetPayload(record, this.contentBasePath)
 		};
-	}
+	};
 };
 function createAssetTools(params) {
 	const contentBasePath = params.contentBasePath ?? "/api/ncp/assets/content";
@@ -10042,7 +10689,7 @@ function toLegacyMessages(messages, options = {}) {
 }
 //#endregion
 //#region src/cli/commands/ncp/context/nextclaw-ncp-session-preferences.ts
-function normalizeOptionalString$1(value) {
+function normalizeOptionalString$3(value) {
 	if (typeof value !== "string") return;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : void 0;
@@ -10055,7 +10702,7 @@ function readMetadataModel(metadata) {
 		metadata.session_model
 	];
 	for (const candidate of candidates) {
-		const normalized = normalizeOptionalString$1(candidate);
+		const normalized = normalizeOptionalString$3(candidate);
 		if (normalized) return normalized;
 	}
 	return null;
@@ -10082,7 +10729,7 @@ function resolveEffectiveModel(params) {
 	if (params.requestMetadata.clear_model === true || params.requestMetadata.reset_model === true) delete params.session.metadata.preferred_model;
 	const inboundModel = readMetadataModel(params.requestMetadata);
 	if (inboundModel) params.session.metadata.preferred_model = inboundModel;
-	return normalizeOptionalString$1(params.session.metadata.preferred_model) ?? params.fallbackModel;
+	return normalizeOptionalString$3(params.session.metadata.preferred_model) ?? params.fallbackModel;
 }
 function syncSessionThinkingPreference(params) {
 	if (params.requestMetadata.clear_thinking === true || params.requestMetadata.reset_thinking === true) delete params.session.metadata.preferred_thinking;
@@ -10094,8 +10741,8 @@ function syncSessionThinkingPreference(params) {
 	if (inboundThinking) params.session.metadata.preferred_thinking = inboundThinking;
 }
 function resolveSessionChannelContext(params) {
-	const channel = normalizeOptionalString$1(params.requestMetadata.channel) ?? normalizeOptionalString$1(params.session.metadata.last_channel) ?? "ui";
-	const chatId = normalizeOptionalString$1(params.requestMetadata.chatId) ?? normalizeOptionalString$1(params.requestMetadata.chat_id) ?? normalizeOptionalString$1(params.session.metadata.last_to) ?? "web-ui";
+	const channel = normalizeOptionalString$3(params.requestMetadata.channel) ?? normalizeOptionalString$3(params.session.metadata.last_channel) ?? "ui";
+	const chatId = normalizeOptionalString$3(params.requestMetadata.chatId) ?? normalizeOptionalString$3(params.requestMetadata.chat_id) ?? normalizeOptionalString$3(params.session.metadata.last_to) ?? "web-ui";
 	params.session.metadata.last_channel = channel;
 	params.session.metadata.last_to = chatId;
 	return {
@@ -10739,7 +11386,7 @@ var NextclawNcpContextBuilder = class {
 			accountId: accountId ?? null
 		});
 		const toolDefinitions = this.options.toolRegistry.getToolDefinitions();
-		const additionalSystemSections = [buildSessionOrchestrationSection()];
+		const additionalSystemSections = [buildSessionOrchestrationSection(), buildMinimalSystemExecutionPrompt(effectiveModel)].filter(Boolean);
 		const contextBuilder = new ContextBuilder(effectiveWorkspace, config.agents.context, {
 			hostWorkspace: profile.workspace,
 			sessionProjectRoot: readSessionProjectRoot(session.metadata)
@@ -11302,12 +11949,6 @@ function extractSessionMessageText(message) {
 	if (parts.length === 0) return;
 	return parts.join("\n\n");
 }
-function findLatestAssistantMessage(messages) {
-	for (let index = messages.length - 1; index >= 0; index -= 1) {
-		const message = messages[index];
-		if (message?.role === "assistant") return message;
-	}
-}
 function readParentSessionId(metadata) {
 	return readOptionalString$1(metadata?.["parent_session_id"]) ?? void 0;
 }
@@ -11527,8 +12168,6 @@ var SessionRequestBroker = class {
 			task
 		});
 		if (streamedMessage) return streamedMessage;
-		const fallbackMessage = findLatestAssistantMessage(await backend.listSessionMessages(request.targetSessionId));
-		if (fallbackMessage) return fallbackMessage;
 		throw new Error("Session request completed without a final reply.");
 	};
 	appendRequestEvents = (request, type) => {
@@ -11710,33 +12349,151 @@ var SessionRequestDeliveryService = class {
 	};
 };
 //#endregion
+//#region src/cli/commands/shared/llm-usage-observer.ts
+var LlmUsageObserver = class {
+	constructor(recorder, source) {
+		this.recorder = recorder;
+		this.source = source;
+	}
+	observe = (params) => {
+		return this.recorder.record({
+			source: this.source,
+			model: params.model ?? null,
+			usage: params.usage
+		});
+	};
+};
+var ObservedProviderManager = class extends ProviderManager {
+	constructor(delegate, observer) {
+		super(delegate.get(null));
+		this.delegate = delegate;
+		this.observer = observer;
+	}
+	get(model) {
+		return this.delegate.get(model);
+	}
+	set(next) {
+		this.delegate.set(next);
+	}
+	setConfig(nextConfig) {
+		this.delegate.setConfig(nextConfig);
+	}
+	async chat(params) {
+		const response = await this.delegate.chat(params);
+		this.observer.observe({
+			model: params.model ?? null,
+			usage: response.usage
+		});
+		return response;
+	}
+	async *chatStream(params) {
+		for await (const event of this.delegate.chatStream(params)) {
+			if (event.type === "done") this.observer.observe({
+				model: params.model ?? null,
+				usage: event.response.usage
+			});
+			yield event;
+		}
+	}
+};
+//#endregion
 //#region src/cli/commands/ncp/runtime/ui-ncp-agent-handle.ts
 function createUiNcpAgentHandle(params) {
+	const { backend, runtimeRegistry, refreshPluginRuntimeRegistrations, applyExtensionRegistry, applyMcpConfig, dispose, assetStore } = params;
 	return {
 		basePath: "/api/ncp/agent",
-		agentClientEndpoint: createAgentClientFromServer(params.backend),
-		streamProvider: params.backend,
-		sessionApi: params.backend,
+		agentClientEndpoint: createAgentClientFromServer(backend),
+		streamProvider: backend,
+		runApi: backend,
+		sessionApi: backend,
 		listSessionTypes: (describeParams) => {
-			params.refreshPluginRuntimeRegistrations();
-			return params.runtimeRegistry.listSessionTypes(describeParams);
+			refreshPluginRuntimeRegistrations();
+			return runtimeRegistry.listSessionTypes(describeParams);
 		},
 		assetApi: {
-			put: (input) => params.assetStore.putBytes({
+			put: (input) => assetStore.putBytes({
 				fileName: input.fileName,
 				mimeType: input.mimeType,
 				bytes: input.bytes,
 				createdAt: input.createdAt
 			}),
-			stat: (uri) => params.assetStore.statRecord(uri),
-			resolveContentPath: (uri) => params.assetStore.resolveContentPath(uri)
+			stat: (uri) => assetStore.statRecord(uri),
+			resolveContentPath: (uri) => assetStore.resolveContentPath(uri)
 		},
-		applyExtensionRegistry: params.applyExtensionRegistry,
-		applyMcpConfig: params.applyMcpConfig,
-		dispose: params.dispose
+		applyExtensionRegistry,
+		applyMcpConfig,
+		dispose
 	};
 }
 //#endregion
+//#region src/cli/runtime-state/llm-usage-record.ts
+var LlmUsageRecordFactory = class {
+	create = (params) => {
+		const { observedAt, source, model, usage: rawUsage } = params;
+		const usage = this.sanitizeUsage(rawUsage);
+		return {
+			version: 1,
+			observedAt: observedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+			source,
+			model: this.normalizeModel(model),
+			usage,
+			summary: this.buildSummary(usage)
+		};
+	};
+	sanitizeUsage = (usage) => {
+		const next = {};
+		for (const [key, value] of Object.entries(usage)) {
+			if (typeof value !== "number" || !Number.isFinite(value) || value < 0) continue;
+			next[key] = Math.floor(value);
+		}
+		return next;
+	};
+	buildSummary = (usage) => {
+		const promptTokens = usage.prompt_tokens ?? usage.input_tokens ?? 0;
+		const completionTokens = usage.completion_tokens ?? usage.output_tokens ?? 0;
+		const totalTokens = usage.total_tokens ?? promptTokens + completionTokens;
+		const cacheMetricKeys = Object.keys(usage).filter((key) => key.endsWith("cached_tokens"));
+		const cachedTokens = cacheMetricKeys.reduce((max, key) => Math.max(max, usage[key] ?? 0), 0);
+		return {
+			promptTokens,
+			completionTokens,
+			totalTokens,
+			cachedTokens,
+			cacheHit: cachedTokens > 0,
+			cacheMetricKeys
+		};
+	};
+	normalizeModel = (value) => {
+		if (typeof value !== "string") return null;
+		const trimmed = value.trim();
+		return trimmed.length > 0 ? trimmed : null;
+	};
+};
+const llmUsageRecordFactory = new LlmUsageRecordFactory();
+//#endregion
+//#region src/cli/commands/shared/llm-usage-recorder.ts
+var LlmUsageRecorder = class {
+	constructor(deps = {}) {
+		this.deps = deps;
+	}
+	record = (params) => {
+		const record = this.recordFactory.create(params);
+		this.snapshotStore.write(record);
+		this.historyStore.append(record);
+		return record;
+	};
+	get snapshotStore() {
+		return this.deps.snapshotStore ?? llmUsageSnapshotStore;
+	}
+	get historyStore() {
+		return this.deps.historyStore ?? llmUsageHistoryStore;
+	}
+	get recordFactory() {
+		return this.deps.recordFactory ?? llmUsageRecordFactory;
+	}
+};
+const llmUsageRecorder = new LlmUsageRecorder();
+//#endregion
 //#region src/cli/commands/ncp/create-ui-ncp-agent.ts
 const CODEX_RUNTIME_KIND = "codex";
 const CODEX_DIRECT_RUNTIME_BACKEND = "codex-sdk";
@@ -11801,6 +12558,7 @@ async function createMcpRuntimeSupport(getConfig) {
 	};
 }
 function createNativeRuntimeFactory(params, mcpToolRegistryAdapter, assetStore, sessionCreationService, sessionRequestBroker) {
+	const observedProviderManager = new ObservedProviderManager(params.providerManager, new LlmUsageObserver(llmUsageRecorder, "ui-ncp"));
 	return ({ stateManager, sessionMetadata, setSessionMetadata }) => {
 		const reasoningNormalizationMode = resolveNativeReasoningNormalizationMode({
 			config: params.getConfig(),
@@ -11809,7 +12567,7 @@ function createNativeRuntimeFactory(params, mcpToolRegistryAdapter, assetStore,
 		if (reasoningNormalizationMode !== "off" && readAssistantReasoningNormalizationModeFromMetadata(sessionMetadata) !== reasoningNormalizationMode) setSessionMetadata(writeAssistantReasoningNormalizationModeToMetadata(sessionMetadata, reasoningNormalizationMode));
 		const toolRegistry = new NextclawNcpToolRegistry({
 			bus: params.bus,
-			providerManager: params.providerManager,
+			providerManager: observedProviderManager,
 			sessionManager: params.sessionManager,
 			cronService: params.cronService,
 			gatewayController: params.gatewayController,
@@ -11827,7 +12585,7 @@ function createNativeRuntimeFactory(params, mcpToolRegistryAdapter, assetStore,
 				resolveMessageToolHints: params.resolveMessageToolHints,
 				assetStore
 			}),
-			llmApi: new ProviderManagerNcpLLMApi(params.providerManager),
+			llmApi: new ProviderManagerNcpLLMApi(observedProviderManager),
 			toolRegistry,
 			stateManager,
 			reasoningNormalizationMode
@@ -11905,7 +12663,10 @@ async function createUiNcpAgent(params) {
 		onSessionRunStatusChanged: params.onSessionRunStatusChanged,
 		createRuntime: (runtimeParams) => {
 			pluginRuntimeRegistrationController.refreshPluginRuntimeRegistrations();
-			return runtimeRegistry.createRuntime(runtimeParams);
+			return runtimeRegistry.createRuntime({
+				...runtimeParams,
+				resolveAssetContentPath: (assetUri) => assetStore.resolveContentPath(assetUri)
+			});
 		}
 	});
 	await backend.start();
@@ -12372,430 +13133,92 @@ var ConfigReloader = class {
 	}
 };
 //#endregion
-//#region src/cli/commands/agent/agent-runtime-pool.ts
-function normalizeAgentId(value) {
-	return (value ?? "").trim().toLowerCase() || "main";
+//#region src/cli/commands/service-support/gateway/service-cron-job-handler.ts
+function normalizeOptionalString$2(value) {
+	if (typeof value !== "string") return;
+	return value.trim() || void 0;
 }
-function normalizeEngineKind(value) {
-	if (typeof value !== "string") return "native";
-	return value.trim().toLowerCase() || "native";
+function buildCronSessionMetadata(params) {
+	const { job, agentId, accountId } = params;
+	const channel = normalizeOptionalString$2(job.payload.channel) ?? "cli";
+	const chatId = normalizeOptionalString$2(job.payload.to) ?? "direct";
+	const metadata = {
+		agentId,
+		agent_id: agentId,
+		channel,
+		chatId,
+		chat_id: chatId,
+		label: job.name,
+		cron_job_id: job.id,
+		cron_job_name: job.name,
+		session_origin: "cron"
+	};
+	if (accountId) {
+		metadata.accountId = accountId;
+		metadata.account_id = accountId;
+	}
+	return metadata;
 }
-function toRecord(value) {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return;
-	return value;
+function buildCronUserMessage(params) {
+	const { sessionId, content, metadata } = params;
+	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		id: `${sessionId}:user:cron:${timestamp}`,
+		sessionId,
+		role: "user",
+		status: "final",
+		timestamp,
+		parts: [{
+			type: "text",
+			text: content
+		}],
+		metadata: structuredClone(metadata)
+	};
 }
-function resolveAgentProfiles(config) {
-	const defaults = config.agents.defaults;
-	const defaultAgentId = normalizeAgentId(resolveDefaultAgentProfileId(config));
-	const listed = resolveEffectiveAgentProfiles(config);
-	const seed = listed.length > 0 ? listed : [{
-		id: defaultAgentId,
-		workspace: defaults.workspace
-	}];
-	const unique = /* @__PURE__ */ new Map();
-	for (const entry of seed) if (!unique.has(entry.id)) unique.set(entry.id, entry);
-	return Array.from(unique.values()).map((entry) => ({
-		id: entry.id,
-		workspace: getWorkspacePath(entry.workspace),
-		model: entry.model ?? defaults.model,
-		engine: normalizeEngineKind(entry.engine ?? defaults.engine),
-		engineConfig: toRecord(entry.engineConfig) ?? toRecord(defaults.engineConfig),
-		maxIterations: entry.maxToolIterations ?? defaults.maxToolIterations,
-		contextTokens: entry.contextTokens ?? defaults.contextTokens
-	}));
+function extractMessageText(message) {
+	return message.parts.flatMap((part) => {
+		if (part.type === "text" || part.type === "rich-text") return [part.text];
+		return [];
+	}).map((text) => text.trim()).filter((text) => text.length > 0).join("\n\n");
 }
-var GatewayAgentRuntimePool = class {
-	routeResolver;
-	runtimes = /* @__PURE__ */ new Map();
-	dynamicEngineRuntimes = /* @__PURE__ */ new Map();
-	resolvedProfiles = [];
-	running = false;
-	defaultAgentId = "main";
-	onSystemSessionUpdated = null;
-	constructor(options) {
-		this.options = options;
-		this.routeResolver = new AgentRouteResolver(options.config);
-		this.rebuild(options.config);
-	}
-	get primaryAgentId() {
-		return this.defaultAgentId;
-	}
-	applyRuntimeConfig(config) {
-		this.options.config = config;
-		this.options.contextConfig = config.agents.context;
-		this.options.execConfig = config.tools.exec;
-		this.options.restrictToWorkspace = config.tools.restrictToWorkspace;
-		this.options.searchConfig = config.search;
-		this.routeResolver.updateConfig(config);
-		this.rebuild(config);
-	}
-	applyExtensionRegistry(extensionRegistry) {
-		this.options.extensionRegistry = extensionRegistry;
-		this.rebuild(this.options.config);
-	}
-	setSystemSessionUpdatedHandler(handler) {
-		this.onSystemSessionUpdated = handler;
-	}
-	listAvailableEngineKinds() {
-		const kinds = new Set(["native"]);
-		for (const runtime of this.runtimes.values()) kinds.add(normalizeEngineKind(runtime.engine.kind));
-		for (const registration of this.options.extensionRegistry?.engines ?? []) kinds.add(normalizeEngineKind(registration.kind));
-		return Array.from(kinds).sort((left, right) => {
-			if (left === "native") return -1;
-			if (right === "native") return 1;
-			return left.localeCompare(right);
-		});
-	}
-	async processDirect(params) {
-		const { message, route } = this.resolveDirectRoute({
-			content: params.content,
-			sessionKey: params.sessionKey,
-			channel: params.channel,
-			chatId: params.chatId,
-			attachments: params.attachments,
-			metadata: params.metadata,
-			agentId: params.agentId
-		});
-		const forcedEngineKind = this.readForcedEngineKind(message.metadata);
-		const commandResult = await this.executeDirectCommand(params.content, {
-			channel: message.channel,
-			chatId: message.chatId,
-			sessionKey: route.sessionKey
-		});
-		if (commandResult) return commandResult;
-		const runtime = forcedEngineKind ? this.resolveRuntimeForEngineKind(forcedEngineKind, route.agentId) : this.resolveRuntime(route.agentId);
-		if (message.attachments.length > 0) return (await runtime.engine.handleInbound({
-			message,
-			sessionKey: route.sessionKey,
-			publishResponse: false,
-			onAssistantDelta: params.onAssistantDelta
-		}))?.content ?? "";
-		return runtime.engine.processDirect({
-			content: params.content,
-			sessionKey: route.sessionKey,
-			channel: message.channel,
-			chatId: message.chatId,
-			metadata: message.metadata,
-			abortSignal: params.abortSignal,
-			onAssistantDelta: params.onAssistantDelta,
-			onSessionEvent: params.onSessionEvent
-		});
-	}
-	async executeDirectCommand(rawContent, ctx) {
-		const trimmed = rawContent.trim();
-		if (!trimmed.startsWith("/")) return null;
-		const registry = new CommandRegistry(this.options.config, this.options.sessionManager);
-		const executeText = registry.executeText;
-		if (typeof executeText === "function") return (await executeText.call(registry, rawContent, {
-			channel: ctx.channel,
-			chatId: ctx.chatId,
-			senderId: "user",
-			sessionKey: ctx.sessionKey
-		}))?.content ?? null;
-		const commandRaw = trimmed.slice(1).trim();
-		if (!commandRaw) return null;
-		const [nameToken, ...restTokens] = commandRaw.split(/\s+/);
-		const commandName = nameToken.trim().toLowerCase();
-		if (!commandName) return null;
-		const args = parseCommandArgsFromText(commandName, restTokens.join(" ").trim(), registry.listSlashCommands());
-		return (await registry.execute(commandName, args, {
-			channel: ctx.channel,
-			chatId: ctx.chatId,
-			senderId: "user",
-			sessionKey: ctx.sessionKey
-		}))?.content ?? null;
-	}
-	supportsTurnAbort(params) {
-		const { route } = this.resolveDirectRoute({
-			content: "",
-			sessionKey: params.sessionKey,
-			channel: params.channel,
-			chatId: params.chatId,
-			metadata: params.metadata,
-			agentId: params.agentId
-		});
-		const forcedEngineKind = this.readForcedEngineKind(params.metadata);
-		let runtime;
-		try {
-			runtime = forcedEngineKind ? this.resolveRuntimeForEngineKind(forcedEngineKind, route.agentId) : this.resolveRuntime(route.agentId);
-		} catch (error) {
-			return {
-				supported: false,
-				agentId: route.agentId,
-				reason: error instanceof Error ? error.message : String(error)
-			};
-		}
-		if (!(runtime.engine.supportsAbort ?? runtime.engine.kind === "native")) return {
-			supported: false,
-			agentId: route.agentId,
-			reason: `engine "${runtime.engine.kind}" does not support server-side stop yet`
-		};
-		return {
-			supported: true,
-			agentId: route.agentId
-		};
-	}
-	async run() {
-		this.running = true;
-		while (this.running) {
-			const message = await this.options.bus.consumeInbound();
-			try {
-				const explicitSessionKey = this.readString(message.metadata.session_key_override);
-				const forcedAgentId = this.readString(message.metadata.target_agent_id);
-				const route = this.routeResolver.resolveInbound({
-					message,
-					forcedAgentId,
-					sessionKeyOverride: explicitSessionKey
-				});
-				const runtime = this.resolveRuntime(route.agentId);
-				if (message.channel !== "system") await this.options.bus.publishOutbound(createAssistantStreamResetControlMessage(message));
-				await runtime.engine.handleInbound({
-					message,
-					sessionKey: route.sessionKey,
-					publishResponse: true,
-					onAssistantDelta: message.channel !== "system" ? (delta) => {
-						if (!delta) return;
-						this.options.bus.publishOutbound(createAssistantStreamDeltaControlMessage(message, delta));
-					} : void 0
-				});
-				if (message.channel === "system") this.onSystemSessionUpdated?.({
-					sessionKey: route.sessionKey,
-					message
-				});
-			} catch (error) {
-				await this.options.bus.publishOutbound({
-					channel: message.channel,
-					chatId: message.chatId,
-					content: `Sorry, I encountered an error: ${formatUserFacingError(error)}`,
-					media: [],
-					metadata: {}
-				});
-			}
-		}
-	}
-	readString(value) {
-		if (typeof value !== "string") return;
-		return value.trim() || void 0;
-	}
-	resolveDirectRoute(params) {
-		const message = {
-			channel: params.channel ?? "cli",
-			senderId: "user",
-			chatId: params.chatId ?? "direct",
-			content: params.content,
-			timestamp: /* @__PURE__ */ new Date(),
-			attachments: params.attachments ?? [],
-			metadata: params.metadata ?? {}
-		};
-		const forcedAgentId = this.readString(params.agentId) ?? parseAgentScopedSessionKey(params.sessionKey)?.agentId ?? void 0;
-		return {
-			message,
-			route: this.routeResolver.resolveInbound({
-				message,
-				forcedAgentId,
-				sessionKeyOverride: params.sessionKey
-			})
-		};
-	}
-	resolveRuntime(agentId) {
-		const normalized = normalizeAgentId(agentId);
-		const runtime = this.runtimes.get(normalized);
-		if (runtime) return runtime;
-		const fallback = this.runtimes.get(this.defaultAgentId);
-		if (fallback) return fallback;
-		throw new Error("No agent runtime available");
-	}
-	readForcedEngineKind(metadata) {
-		if (!metadata || typeof metadata !== "object") return;
-		const raw = this.readString(metadata.session_type) ?? this.readString(metadata.sessionType) ?? this.readString(metadata.engine_kind) ?? this.readString(metadata.engineKind);
-		return raw ? normalizeEngineKind(raw) : void 0;
-	}
-	findRuntimeByEngineKind(kind, preferredAgentId) {
-		const normalizedKind = normalizeEngineKind(kind);
-		const preferred = preferredAgentId ? this.runtimes.get(normalizeAgentId(preferredAgentId)) : null;
-		if (preferred && normalizeEngineKind(preferred.engine.kind) === normalizedKind) return preferred;
-		for (const runtime of this.runtimes.values()) if (normalizeEngineKind(runtime.engine.kind) === normalizedKind) return runtime;
-		return null;
-	}
-	resolveBaseProfileForDynamicEngine(agentId) {
-		const normalizedAgentId = normalizeAgentId(agentId);
-		return this.resolvedProfiles.find((profile) => profile.id === normalizedAgentId) ?? this.resolvedProfiles.find((profile) => profile.id === this.defaultAgentId) ?? this.resolvedProfiles[0] ?? {
-			id: this.defaultAgentId,
-			workspace: getWorkspacePath(this.options.config.agents.defaults.workspace),
-			model: this.options.config.agents.defaults.model,
-			maxIterations: this.options.config.agents.defaults.maxToolIterations,
-			contextTokens: this.options.config.agents.defaults.contextTokens,
-			engine: "native",
-			engineConfig: toRecord(this.options.config.agents.defaults.engineConfig)
-		};
-	}
-	resolveRuntimeForEngineKind(kind, fallbackAgentId) {
-		const normalizedKind = normalizeEngineKind(kind);
-		const existing = this.findRuntimeByEngineKind(normalizedKind, fallbackAgentId);
-		if (existing) return existing;
-		if (!this.listAvailableEngineKinds().includes(normalizedKind)) throw new Error(`engine "${normalizedKind}" is not available`);
-		const cached = this.dynamicEngineRuntimes.get(normalizedKind);
-		if (cached) return cached;
-		const dynamicProfile = {
-			...this.resolveBaseProfileForDynamicEngine(fallbackAgentId),
-			id: `__session_engine__${normalizedKind}`,
-			engine: normalizedKind
-		};
-		const runtime = {
-			id: dynamicProfile.id,
-			engine: this.createEngine(dynamicProfile, this.options.config)
-		};
-		this.dynamicEngineRuntimes.set(normalizedKind, runtime);
-		return runtime;
-	}
-	createNativeEngineFactory() {
-		return (context) => new NativeAgentEngine({
-			bus: context.bus,
-			providerManager: context.providerManager,
-			workspace: context.workspace,
-			model: context.model,
-			maxIterations: context.maxIterations,
-			contextTokens: context.contextTokens,
-			searchConfig: context.searchConfig,
-			execConfig: context.execConfig,
-			cronService: context.cronService,
-			restrictToWorkspace: context.restrictToWorkspace,
-			sessionManager: context.sessionManager,
-			contextConfig: context.contextConfig,
-			gatewayController: context.gatewayController,
-			config: context.config,
-			extensionRegistry: context.extensionRegistry,
-			resolveMessageToolHints: context.resolveMessageToolHints,
-			agentId: context.agentId
-		});
-	}
-	resolveEngineFactory(kind) {
-		if (kind === "native") return this.createNativeEngineFactory();
-		const matched = (this.options.extensionRegistry?.engines ?? []).find((entry) => normalizeEngineKind(entry.kind) === kind);
-		if (matched) return matched.factory;
-		console.warn(`[engine] unknown engine "${kind}", fallback to "native"`);
-		return this.createNativeEngineFactory();
-	}
-	createEngine(profile, config) {
-		const kind = normalizeEngineKind(profile.engine);
-		const factory = this.resolveEngineFactory(kind);
-		const context = {
-			agentId: profile.id,
-			workspace: profile.workspace,
-			model: profile.model,
-			maxIterations: profile.maxIterations,
-			contextTokens: profile.contextTokens,
-			engineConfig: profile.engineConfig,
-			bus: this.options.bus,
-			providerManager: this.options.providerManager,
-			sessionManager: this.options.sessionManager,
-			cronService: this.options.cronService,
-			restrictToWorkspace: this.options.restrictToWorkspace,
-			searchConfig: this.options.searchConfig,
-			execConfig: this.options.execConfig,
-			contextConfig: this.options.contextConfig,
-			gatewayController: this.options.gatewayController,
-			config,
-			extensionRegistry: this.options.extensionRegistry,
-			resolveMessageToolHints: this.options.resolveMessageToolHints
-		};
-		try {
-			return factory(context);
-		} catch (error) {
-			if (kind === "native") throw error;
-			console.warn(`[engine] failed to create "${kind}" for agent "${profile.id}": ${String(error)}`);
-			return this.createNativeEngineFactory()(context);
-		}
-	}
-	rebuild(config) {
-		const profiles = resolveAgentProfiles(config);
-		this.resolvedProfiles = profiles;
-		this.defaultAgentId = this.readString(config.agents.list.find((entry) => entry.default)?.id) ?? profiles[0]?.id ?? "main";
-		const nextRuntimes = /* @__PURE__ */ new Map();
-		for (const profile of profiles) {
-			const engine = this.createEngine(profile, config);
-			nextRuntimes.set(profile.id, {
-				id: profile.id,
-				engine
-			});
-		}
-		this.runtimes = nextRuntimes;
-		this.dynamicEngineRuntimes.clear();
-	}
-};
-function parseCommandArgsFromText(commandName, rawTail, specs) {
-	if (!rawTail) return {};
-	const options = specs.find((item) => item.name.trim().toLowerCase() === commandName)?.options;
-	if (!options || options.length === 0) return {};
-	const tokens = rawTail.split(/\s+/).filter(Boolean);
-	const args = {};
-	let cursor = 0;
-	for (let i = 0; i < options.length; i += 1) {
-		if (cursor >= tokens.length) break;
-		const option = options[i];
-		const isLastOption = i === options.length - 1;
-		const rawValue = isLastOption ? tokens.slice(cursor).join(" ") : tokens[cursor];
-		cursor += isLastOption ? tokens.length - cursor : 1;
-		const parsedValue = parseCommandOptionValue(option.type, rawValue);
-		if (parsedValue !== void 0) args[option.name] = parsedValue;
-	}
-	return args;
-}
-function parseCommandOptionValue(type, rawValue) {
-	const value = rawValue.trim();
-	if (!value) return;
-	if (type === "number") {
-		const parsed = Number(value);
-		return Number.isFinite(parsed) ? parsed : void 0;
-	}
-	if (type === "boolean") {
-		const lowered = value.toLowerCase();
-		if ([
-			"1",
-			"true",
-			"yes",
-			"on"
-		].includes(lowered)) return true;
-		if ([
-			"0",
-			"false",
-			"no",
-			"off"
-		].includes(lowered)) return false;
-		return;
+async function runJobOverNcp(params) {
+	const { agent, sessionId, message, metadata, missingCompletedMessageError, runErrorMessage } = params;
+	let completedMessage;
+	for await (const event of agent.runApi.send({
+		sessionId,
+		message,
+		metadata
+	})) {
+		if (event.type === NcpEventType.MessageFailed) throw new Error(event.payload.error.message);
+		if (event.type === NcpEventType.RunError) throw new Error(event.payload.error ?? runErrorMessage);
+		if (event.type === NcpEventType.MessageCompleted) completedMessage = event.payload.message;
 	}
-	return value;
-}
-function formatUserFacingError(error, maxChars = 320) {
-	const normalized = (error instanceof Error ? error.message || error.name || "Unknown error" : String(error ?? "Unknown error")).replace(/\s+/g, " ").trim();
-	if (!normalized) return "Unknown error";
-	if (normalized.length <= maxChars) return normalized;
-	return `${normalized.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
-}
-//#endregion
-//#region src/cli/commands/service-support/gateway/service-cron-job-handler.ts
-function normalizeOptionalString(value) {
-	if (typeof value !== "string") return;
-	return value.trim() || void 0;
-}
-function buildCronJobMetadata(accountId) {
-	if (!accountId) return {};
-	return {
-		accountId,
-		account_id: accountId
-	};
+	if (!completedMessage) throw new Error(missingCompletedMessageError);
+	return extractMessageText(completedMessage);
 }
 function createCronJobHandler(params) {
 	return async (job) => {
-		const metadata = buildCronJobMetadata(normalizeOptionalString(job.payload.accountId));
-		const agentId = normalizeOptionalString(job.payload.agentId) ?? params.runtimePool.primaryAgentId;
-		const response = await params.runtimePool.processDirect({
-			content: job.payload.message,
-			sessionKey: `cron:${job.id}`,
-			channel: job.payload.channel ?? "cli",
-			chatId: job.payload.to ?? "direct",
+		const ncpAgent = params.resolveNcpAgent();
+		if (!ncpAgent) throw new Error("NCP agent is not ready for cron execution.");
+		const accountId = normalizeOptionalString$2(job.payload.accountId);
+		const agentId = normalizeOptionalString$2(job.payload.agentId) ?? "main";
+		const sessionId = `cron:${job.id}`;
+		const metadata = buildCronSessionMetadata({
+			job,
+			agentId,
+			accountId
+		});
+		const response = await runJobOverNcp({
+			agent: ncpAgent,
+			sessionId,
+			message: buildCronUserMessage({
+				sessionId,
+				content: job.payload.message,
+				metadata
+			}),
 			metadata,
-			agentId
+			missingCompletedMessageError: "cron job completed without a final assistant message",
+			runErrorMessage: "cron job failed"
 		});
 		if (job.payload.deliver && job.payload.to) await params.bus.publishOutbound({
 			channel: job.payload.channel ?? "cli",
@@ -12807,21 +13230,81 @@ function createCronJobHandler(params) {
 		return response;
 	};
 }
+function buildHeartbeatMetadata(params) {
+	return {
+		agentId: params.agentId,
+		agent_id: params.agentId,
+		channel: "cli",
+		chatId: "direct",
+		chat_id: "direct",
+		label: "heartbeat",
+		session_origin: "heartbeat"
+	};
+}
+function buildHeartbeatUserMessage(params) {
+	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		id: `heartbeat:user:${timestamp}`,
+		sessionId: "heartbeat",
+		role: "user",
+		status: "final",
+		timestamp,
+		parts: [{
+			type: "text",
+			text: params.content
+		}],
+		metadata: structuredClone(params.metadata)
+	};
+}
+function createHeartbeatJobHandler(params) {
+	return async (prompt) => {
+		const ncpAgent = params.resolveNcpAgent();
+		if (!ncpAgent) throw new Error("NCP agent is not ready for heartbeat execution.");
+		const metadata = buildHeartbeatMetadata({ agentId: params.resolveAgentId() });
+		return await runJobOverNcp({
+			agent: ncpAgent,
+			sessionId: "heartbeat",
+			message: buildHeartbeatUserMessage({
+				content: prompt,
+				metadata
+			}),
+			metadata,
+			missingCompletedMessageError: "heartbeat execution completed without a final assistant message",
+			runErrorMessage: "heartbeat execution failed"
+		});
+	};
+}
 //#endregion
 //#region src/cli/commands/service-support/gateway/service-gateway-context.ts
-const { ChannelManager: ChannelManager$1, CronService: CronService$1, getConfigPath: getConfigPath$2, getDataDir: getDataDir$1, getWorkspacePath: getWorkspacePath$2, HeartbeatService, loadConfig: loadConfig$3, MessageBus: MessageBus$2, ProviderManager: ProviderManager$1, resolveConfigSecrets: resolveConfigSecrets$3, saveConfig: saveConfig$1, SessionManager: SessionManager$1 } = NextclawCore;
+const { ChannelManager: ChannelManager$1, CronService: CronService$1, getConfigPath: getConfigPath$2, getDataDir: getDataDir$1, getWorkspacePath: getWorkspacePath$2, HeartbeatService, loadConfig: loadConfig$3, MessageBus: MessageBus$2, ProviderManager: ProviderManager$1, resolveConfigSecrets: resolveConfigSecrets$3, resolveDefaultAgentProfileId: resolveDefaultAgentProfileId$1, saveConfig: saveConfig$1, SessionManager: SessionManager$2 } = NextclawCore;
 function applyGatewayCapabilityState(gateway, next) {
 	gateway.pluginRegistry = next.pluginRegistry;
 	gateway.pluginChannelBindings = next.pluginChannelBindings;
 	gateway.extensionRegistry = next.extensionRegistry;
 }
+function normalizeAgentId(value) {
+	return (value ?? "").trim().toLowerCase() || "main";
+}
+function createGatewayHeartbeat(state, params) {
+	const handleHeartbeat = createHeartbeatJobHandler({
+		resolveNcpAgent: () => params.getLiveUiNcpAgent?.() ?? null,
+		resolveAgentId: () => normalizeAgentId(resolveDefaultAgentProfileId$1(resolveConfigSecrets$3(loadConfig$3(), { configPath: state.runtimeConfigPath })))
+	});
+	return new HeartbeatService(state.workspace, async (promptText) => await handleHeartbeat(promptText), 1800, true);
+}
+function createGatewayCronJobHandler(params) {
+	return createCronJobHandler({
+		resolveNcpAgent: () => params.getLiveUiNcpAgent?.() ?? null,
+		bus: params.bus
+	});
+}
 function createGatewayShellContext(params) {
 	const runtimeConfigPath = getConfigPath$2();
 	const config = resolveConfigSecrets$3(loadConfig$3(), { configPath: runtimeConfigPath });
 	const workspace = getWorkspacePath$2(config.agents.defaults.workspace);
 	const homeDir = getDataDir$1();
 	const cronStorePath = join(getDataDir$1(), "cron", "jobs.json");
-	const sessionManager = measureStartupSync("service.gateway_shell_context.session_manager", () => new SessionManager$1({
+	const sessionManager = measureStartupSync("service.gateway_shell_context.session_manager", () => new SessionManager$2({
 		workspace,
 		homeDir
 	}));
@@ -12842,10 +13325,11 @@ function createGatewayShellContext(params) {
 	};
 }
 function createGatewayStartupContext(params) {
+	const { shellContext: providedShellContext, uiOverrides, allowMissingProvider, uiStaticDir, initialPluginRegistry, makeProvider, makeMissingProvider, requestRestart, getLiveUiNcpAgent } = params;
 	const state = {};
-	const shellContext = params.shellContext ?? createGatewayShellContext({
-		uiOverrides: params.uiOverrides,
-		uiStaticDir: params.uiStaticDir
+	const shellContext = providedShellContext ?? createGatewayShellContext({
+		uiOverrides,
+		uiStaticDir
 	});
 	state.runtimeConfigPath = shellContext.runtimeConfigPath;
 	state.config = shellContext.config;
@@ -12855,14 +13339,14 @@ function createGatewayStartupContext(params) {
 	state.uiConfig = shellContext.uiConfig;
 	state.uiStaticDir = shellContext.uiStaticDir;
 	state.remoteModule = shellContext.remoteModule;
-	state.pluginRegistry = params.initialPluginRegistry ?? measureStartupSync("service.gateway_context.load_plugin_registry", () => loadPluginRegistry(state.config, state.workspace));
+	state.pluginRegistry = initialPluginRegistry ?? measureStartupSync("service.gateway_context.load_plugin_registry", () => loadPluginRegistry(state.config, state.workspace));
 	state.pluginChannelBindings = measureStartupSync("service.gateway_context.get_plugin_channel_bindings", () => getPluginChannelBindings(state.pluginRegistry));
 	state.extensionRegistry = measureStartupSync("service.gateway_context.to_extension_registry", () => toExtensionRegistry(state.pluginRegistry));
 	logPluginDiagnostics(state.pluginRegistry);
 	state.bus = new MessageBus$2();
-	const provider = params.allowMissingProvider === true ? params.makeProvider(state.config, { allowMissing: true }) : params.makeProvider(state.config);
+	const provider = allowMissingProvider === true ? makeProvider(state.config, { allowMissing: true }) : makeProvider(state.config);
 	state.providerManager = measureStartupSync("service.gateway_context.provider_manager", () => new ProviderManager$1({
-		defaultProvider: provider ?? params.makeMissingProvider(state.config),
+		defaultProvider: provider ?? makeMissingProvider(state.config),
 		config: state.config
 	}));
 	if (!provider) console.warn("Warning: No API key configured. The gateway is running, but agent replies are disabled until provider config is set.");
@@ -12873,12 +13357,12 @@ function createGatewayStartupContext(params) {
 		bus: state.bus,
 		sessionManager: state.sessionManager,
 		providerManager: state.providerManager,
-		makeProvider: (nextConfig) => params.makeProvider(nextConfig, { allowMissing: true }) ?? params.makeMissingProvider(nextConfig),
+		makeProvider: (nextConfig) => makeProvider(nextConfig, { allowMissing: true }) ?? makeMissingProvider(nextConfig),
 		loadConfig: () => resolveConfigSecrets$3(loadConfig$3(), { configPath: state.runtimeConfigPath }),
 		resolveChannelConfig: (nextConfig) => resolveChannelConfigView(nextConfig, state.pluginChannelBindings),
 		getExtensionChannels: () => state.extensionRegistry.channels,
 		onRestartRequired: (paths) => {
-			params.requestRestart({
+			requestRestart({
 				reason: `config reload requires restart: ${paths.join(", ")}`,
 				manualMessage: `Config changes require restart: ${paths.join(", ")}`,
 				strategy: "background-service-or-manual"
@@ -12895,7 +13379,7 @@ function createGatewayStartupContext(params) {
 		getConfigPath: getConfigPath$2,
 		saveConfig: saveConfig$1,
 		requestRestart: async (options) => {
-			await params.requestRestart({
+			await requestRestart({
 				reason: options?.reason ?? "gateway tool restart",
 				manualMessage: "Restart the gateway to apply changes.",
 				strategy: "background-service-or-exit",
@@ -12904,37 +13388,356 @@ function createGatewayStartupContext(params) {
 			});
 		}
 	}));
-	state.runtimePool = measureStartupSync("service.gateway_context.runtime_pool", () => new GatewayAgentRuntimePool({
+	state.cron.onJob = createGatewayCronJobHandler({
 		bus: state.bus,
-		providerManager: state.providerManager,
-		sessionManager: state.sessionManager,
-		config: state.config,
-		cronService: state.cron,
-		restrictToWorkspace: state.config.tools.restrictToWorkspace,
-		searchConfig: state.config.search,
-		execConfig: state.config.tools.exec,
-		contextConfig: state.config.agents.context,
-		gatewayController: state.gatewayController,
-		extensionRegistry: state.extensionRegistry,
-		resolveMessageToolHints: ({ channel, accountId }) => resolvePluginChannelMessageToolHints({
-			registry: state.pluginRegistry,
-			channel,
-			cfg: resolveConfigSecrets$3(loadConfig$3(), { configPath: state.runtimeConfigPath }),
-			accountId
-		})
-	}));
-	state.cron.onJob = createCronJobHandler({
-		runtimePool: state.runtimePool,
-		bus: state.bus
+		getLiveUiNcpAgent
 	});
-	state.heartbeat = new HeartbeatService(state.workspace, async (promptText) => state.runtimePool.processDirect({
-		content: promptText,
-		sessionKey: "heartbeat",
-		agentId: state.runtimePool.primaryAgentId
-	}), 1800, true);
+	state.heartbeat = createGatewayHeartbeat(state, { getLiveUiNcpAgent });
 	return state;
 }
 //#endregion
+//#region src/cli/commands/ncp/runtime/nextclaw-ncp-runner.ts
+function normalizeOptionalString$1(value) {
+	if (typeof value !== "string") return;
+	return value.trim() || void 0;
+}
+function resolveAttachmentName(attachment) {
+	const explicitName = normalizeOptionalString$1(attachment.name);
+	if (explicitName) return explicitName;
+	const explicitPath = normalizeOptionalString$1(attachment.path);
+	if (explicitPath) return basename(explicitPath);
+	const explicitUrl = normalizeOptionalString$1(attachment.url);
+	if (explicitUrl) try {
+		return basename(new URL(explicitUrl).pathname) || "asset.bin";
+	} catch {
+		return basename(explicitUrl) || "asset.bin";
+	}
+	return "asset.bin";
+}
+async function attachmentToPart(attachment, assetApi) {
+	const assetUri = normalizeOptionalString$1(attachment.assetUri);
+	if (assetUri) return createFilePartFromAssetUri(attachment, assetUri);
+	const remoteUrl = normalizeOptionalString$1(attachment.url);
+	const localPath = normalizeOptionalString$1(attachment.path);
+	if (localPath) return await createFilePartFromLocalPath(attachment, localPath, assetApi);
+	if (remoteUrl) return createFilePartFromRemoteUrl(attachment, remoteUrl);
+	throw new Error(`Unsupported attachment payload for "${resolveAttachmentName(attachment)}".`);
+}
+function createBaseFilePart(attachment) {
+	return {
+		...attachment.name ? { name: attachment.name } : {},
+		...attachment.mimeType ? { mimeType: attachment.mimeType } : {},
+		...typeof attachment.size === "number" ? { sizeBytes: attachment.size } : {}
+	};
+}
+function createFilePartFromAssetUri(attachment, assetUri) {
+	return {
+		type: "file",
+		assetUri,
+		...createBaseFilePart(attachment)
+	};
+}
+async function createFilePartFromLocalPath(attachment, localPath, assetApi) {
+	if (!assetApi) throw new Error("NCP asset api is unavailable for local attachments.");
+	const fileName = resolveAttachmentName(attachment);
+	const bytes = await readFile(localPath);
+	return {
+		type: "file",
+		assetUri: (await assetApi.put({
+			fileName,
+			mimeType: attachment.mimeType ?? null,
+			bytes
+		})).uri,
+		name: attachment.name ?? fileName,
+		...attachment.mimeType ? { mimeType: attachment.mimeType } : {},
+		...typeof attachment.size === "number" ? { sizeBytes: attachment.size } : {}
+	};
+}
+function createFilePartFromRemoteUrl(attachment, remoteUrl) {
+	return {
+		type: "file",
+		url: remoteUrl,
+		name: attachment.name ?? resolveAttachmentName(attachment),
+		...attachment.mimeType ? { mimeType: attachment.mimeType } : {},
+		...typeof attachment.size === "number" ? { sizeBytes: attachment.size } : {}
+	};
+}
+async function buildUserMessageParts(params) {
+	const parts = [];
+	if (params.content.length > 0) parts.push({
+		type: "text",
+		text: params.content
+	});
+	for (const attachment of params.attachments ?? []) parts.push(await attachmentToPart(attachment, params.assetApi));
+	return parts;
+}
+async function buildNcpUserMessage(params) {
+	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		id: `${params.sessionId}:user:${timestamp}`,
+		sessionId: params.sessionId,
+		role: "user",
+		status: "final",
+		timestamp,
+		parts: await buildUserMessageParts({
+			content: params.content,
+			attachments: params.attachments,
+			assetApi: params.assetApi
+		}),
+		metadata: structuredClone(params.metadata ?? {})
+	};
+}
+async function runPromptOverNcp(params) {
+	const message = await buildNcpUserMessage({
+		sessionId: params.sessionId,
+		content: params.content,
+		attachments: params.attachments,
+		metadata: params.metadata,
+		assetApi: params.agent.assetApi
+	});
+	let completedMessage;
+	for await (const event of params.agent.runApi.send({
+		sessionId: params.sessionId,
+		message,
+		metadata: params.metadata
+	}, { ...params.abortSignal ? { signal: params.abortSignal } : {} })) {
+		params.onEvent?.(event);
+		if (event.type === NcpEventType.MessageTextDelta) {
+			params.onAssistantDelta?.(event.payload.delta);
+			continue;
+		}
+		if (event.type === NcpEventType.MessageFailed) throw new Error(event.payload.error.message);
+		if (event.type === NcpEventType.RunError) throw new Error(event.payload.error ?? params.runErrorMessage ?? "NCP run failed.");
+		if (event.type === NcpEventType.MessageCompleted) completedMessage = event.payload.message;
+	}
+	if (!completedMessage) throw new Error(params.missingCompletedMessageError ?? "NCP run completed without a final assistant message.");
+	return {
+		text: extractTextFromNcpMessage(completedMessage),
+		completedMessage
+	};
+}
+//#endregion
+//#region src/cli/commands/ncp/runtime/nextclaw-ncp-dispatch.ts
+function normalizeOptionalString(value) {
+	if (typeof value !== "string") return;
+	return value.trim() || void 0;
+}
+function requireNcpAgent(resolveNcpAgent, purpose) {
+	const agent = resolveNcpAgent?.() ?? null;
+	if (!agent) throw new Error(`NCP agent is not ready for ${purpose}.`);
+	return agent;
+}
+function createDirectInboundMessage(params) {
+	return {
+		channel: params.channel ?? "cli",
+		senderId: "user",
+		chatId: params.chatId ?? "direct",
+		content: params.content,
+		timestamp: /* @__PURE__ */ new Date(),
+		attachments: params.attachments ?? [],
+		metadata: structuredClone(params.metadata ?? {})
+	};
+}
+function buildRunMetadata(params) {
+	return {
+		...params.message.metadata ?? {},
+		...params.metadata ?? {},
+		channel: params.message.channel,
+		chatId: params.message.chatId,
+		chat_id: params.message.chatId,
+		accountId: params.route.accountId,
+		account_id: params.route.accountId,
+		agentId: params.route.agentId,
+		agent_id: params.route.agentId,
+		sessionKey: params.route.sessionKey,
+		session_key: params.route.sessionKey,
+		senderId: params.message.senderId,
+		sender_id: params.message.senderId
+	};
+}
+function parseCommandOptionValue(type, rawValue) {
+	const value = rawValue.trim();
+	if (!value) return;
+	if (type === "number") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+	if (type === "boolean") {
+		const lowered = value.toLowerCase();
+		if ([
+			"1",
+			"true",
+			"yes",
+			"on"
+		].includes(lowered)) return true;
+		if ([
+			"0",
+			"false",
+			"no",
+			"off"
+		].includes(lowered)) return false;
+		return;
+	}
+	return value;
+}
+function parseCommandArgsFromText(commandName, rawTail, specs) {
+	if (!rawTail) return {};
+	const options = specs.find((item) => item.name.trim().toLowerCase() === commandName)?.options;
+	if (!options || options.length === 0) return {};
+	const tokens = rawTail.split(/\s+/).filter(Boolean);
+	const args = {};
+	let cursor = 0;
+	for (let index = 0; index < options.length; index += 1) {
+		if (cursor >= tokens.length) break;
+		const option = options[index];
+		const isLastOption = index === options.length - 1;
+		const rawValue = isLastOption ? tokens.slice(cursor).join(" ") : tokens[cursor];
+		cursor += isLastOption ? tokens.length - cursor : 1;
+		const parsedValue = parseCommandOptionValue(option.type, rawValue);
+		if (parsedValue !== void 0) args[option.name] = parsedValue;
+	}
+	return args;
+}
+async function executeSlashCommandMaybe(params) {
+	const trimmed = params.rawContent.trim();
+	if (!trimmed.startsWith("/")) return null;
+	const registry = new CommandRegistry(params.config, params.sessionManager);
+	const executeText = registry.executeText;
+	if (typeof executeText === "function") return (await executeText.call(registry, params.rawContent, {
+		channel: params.channel,
+		chatId: params.chatId,
+		senderId: "user",
+		sessionKey: params.sessionKey
+	}))?.content ?? null;
+	const commandRaw = trimmed.slice(1).trim();
+	if (!commandRaw) return null;
+	const [nameToken, ...restTokens] = commandRaw.split(/\s+/);
+	const commandName = nameToken.trim().toLowerCase();
+	if (!commandName) return null;
+	const args = parseCommandArgsFromText(commandName, restTokens.join(" ").trim(), registry.listSlashCommands());
+	return (await registry.execute(commandName, args, {
+		channel: params.channel,
+		chatId: params.chatId,
+		senderId: "user",
+		sessionKey: params.sessionKey
+	}))?.content ?? null;
+}
+function resolveDirectRoute(params) {
+	const message = createDirectInboundMessage(params);
+	const forcedAgentId = normalizeOptionalString(params.agentId) ?? parseAgentScopedSessionKey(params.sessionKey)?.agentId ?? void 0;
+	return {
+		message,
+		route: new AgentRouteResolver(params.config).resolveInbound({
+			message,
+			forcedAgentId,
+			sessionKeyOverride: params.sessionKey
+		})
+	};
+}
+function formatUserFacingError(error, maxChars = 320) {
+	const normalized = (error instanceof Error ? error.message || error.name || "Unknown error" : String(error ?? "Unknown error")).replace(/\s+/g, " ").trim();
+	if (!normalized) return "Unknown error";
+	if (normalized.length <= maxChars) return normalized;
+	return `${normalized.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
+}
+async function dispatchPromptOverNcp(params) {
+	const { message, route } = resolveDirectRoute({
+		config: params.config,
+		content: params.content,
+		sessionKey: params.sessionKey,
+		channel: params.channel,
+		chatId: params.chatId,
+		attachments: params.attachments,
+		metadata: params.metadata,
+		agentId: params.agentId
+	});
+	const commandResult = await executeSlashCommandMaybe({
+		config: params.config,
+		sessionManager: params.sessionManager,
+		rawContent: params.content,
+		channel: message.channel,
+		chatId: message.chatId,
+		sessionKey: route.sessionKey
+	});
+	if (commandResult) return commandResult;
+	return (await runPromptOverNcp({
+		agent: requireNcpAgent(params.resolveNcpAgent, "direct dispatch"),
+		sessionId: route.sessionKey,
+		content: params.content,
+		attachments: params.attachments,
+		metadata: buildRunMetadata({
+			message,
+			route
+		}),
+		abortSignal: params.abortSignal,
+		onAssistantDelta: params.onAssistantDelta,
+		missingCompletedMessageError: `session "${route.sessionKey}" completed without a final assistant message`,
+		runErrorMessage: `session "${route.sessionKey}" failed`
+	})).text;
+}
+async function runGatewayInboundLoop(params) {
+	while (true) {
+		const message = await params.bus.consumeInbound();
+		try {
+			const explicitSessionKey = normalizeOptionalString(message.metadata.session_key_override);
+			const forcedAgentId = normalizeOptionalString(message.metadata.target_agent_id);
+			const route = new AgentRouteResolver(params.getConfig()).resolveInbound({
+				message,
+				forcedAgentId,
+				sessionKeyOverride: explicitSessionKey
+			});
+			const agent = requireNcpAgent(params.resolveNcpAgent, "gateway dispatch");
+			if (message.channel !== "system") await params.bus.publishOutbound(createAssistantStreamResetControlMessage(message));
+			const result = await runPromptOverNcp({
+				agent,
+				sessionId: route.sessionKey,
+				content: message.content,
+				attachments: message.attachments,
+				metadata: buildRunMetadata({
+					message,
+					route
+				}),
+				onAssistantDelta: message.channel !== "system" ? (delta) => {
+					if (!delta) return;
+					params.bus.publishOutbound(createAssistantStreamDeltaControlMessage(message, delta));
+				} : void 0,
+				missingCompletedMessageError: `session "${route.sessionKey}" completed without a final assistant message`,
+				runErrorMessage: `session "${route.sessionKey}" failed`
+			});
+			if (message.channel === "system") {
+				params.onSystemSessionUpdated?.({
+					sessionKey: route.sessionKey,
+					message
+				});
+				continue;
+			}
+			if (!result.text.trim()) {
+				await params.bus.publishOutbound(createTypingStopControlMessage(message));
+				continue;
+			}
+			await params.bus.publishOutbound({
+				channel: message.channel,
+				chatId: message.chatId,
+				content: result.text,
+				media: [],
+				metadata: buildRunMetadata({
+					message,
+					route,
+					metadata: result.completedMessage.metadata
+				})
+			});
+		} catch (error) {
+			await params.bus.publishOutbound({
+				channel: message.channel,
+				chatId: message.chatId,
+				content: `Sorry, I encountered an error: ${formatUserFacingError(error)}`,
+				media: [],
+				metadata: {}
+			});
+		}
+	}
+}
+//#endregion
 //#region src/cli/commands/service-support/session/service-deferred-ncp-agent.ts
 const DEFAULT_BASE_PATH = "/api/ncp/agent";
 const DEFERRED_NCP_AGENT_UNAVAILABLE = "ncp agent unavailable during startup";
@@ -13020,13 +13823,13 @@ function createDeferredUiNcpAgent(basePath = DEFAULT_BASE_PATH) {
 }
 //#endregion
 //#region src/cli/commands/service-support/gateway/service-gateway-startup.ts
-function wireSystemSessionUpdatedPublisher(params) {
-	params.runtimePool.setSystemSessionUpdatedHandler(({ sessionKey }) => {
+function createSystemSessionUpdatedPublisher(params) {
+	return ({ sessionKey }) => {
 		params.publishUiEvent?.({
 			type: "session.updated",
 			payload: { sessionKey }
 		});
-	});
+	};
 }
 async function startUiShell(params) {
 	logStartupTrace("service.start_ui_shell.begin");
@@ -13067,54 +13870,90 @@ async function startUiShell(params) {
 	};
 }
 async function startDeferredGatewayStartup(params) {
+	const { uiStartup, deferredNcpSessionService, bus, sessionManager, providerManager, cronService, gatewayController, getConfig, getExtensionRegistry, resolveMessageToolHints, hydrateCapabilities, startPluginGateways, startChannels, wakeFromRestartSentinel, onNcpAgentReady, publishSessionChange } = params;
 	logStartupTrace("service.deferred_startup.begin");
-	if (params.uiStartup) try {
+	try {
 		const ncpAgent = await measureStartupAsync("service.deferred_startup.create_ui_ncp_agent", async () => await createUiNcpAgent({
-			bus: params.bus,
-			providerManager: params.providerManager,
-			sessionManager: params.sessionManager,
-			cronService: params.cronService,
-			gatewayController: params.gatewayController,
-			getConfig: params.getConfig,
-			getExtensionRegistry: params.getExtensionRegistry,
-			onSessionUpdated: params.publishSessionChange,
+			bus,
+			providerManager,
+			sessionManager,
+			cronService,
+			gatewayController,
+			getConfig,
+			getExtensionRegistry,
+			onSessionUpdated: publishSessionChange,
 			onSessionRunStatusChanged: (payload) => {
-				params.uiStartup?.publish({
+				uiStartup?.publish({
 					type: "session.run-status",
 					payload
 				});
 			},
-			resolveMessageToolHints: ({ channel, accountId }) => params.resolveMessageToolHints({
+			resolveMessageToolHints: ({ channel, accountId }) => resolveMessageToolHints({
 				channel,
 				accountId
 			})
 		}));
-		params.deferredNcpSessionService.activate(ncpAgent.sessionApi);
-		params.onNcpAgentReady(ncpAgent);
-		params.uiStartup.deferredNcpAgent.activate(ncpAgent);
-		console.log("✓ UI NCP agent: ready");
+		deferredNcpSessionService.activate(ncpAgent.sessionApi);
+		onNcpAgentReady(ncpAgent);
+		if (uiStartup) {
+			uiStartup.deferredNcpAgent.activate(ncpAgent);
+			console.log("✓ UI NCP agent: ready");
+		} else console.log("✓ Service NCP agent: ready");
 	} catch (error) {
 		console.error(`UI NCP agent startup failed: ${error instanceof Error ? error.message : String(error)}`);
 	}
-	if (params.hydrateCapabilities) await measureStartupAsync("service.deferred_startup.hydrate_capabilities", params.hydrateCapabilities);
-	await measureStartupAsync("service.deferred_startup.start_plugin_gateways", params.startPluginGateways);
-	await measureStartupAsync("service.deferred_startup.start_channels", params.startChannels);
-	await measureStartupAsync("service.deferred_startup.wake_restart_sentinel", params.wakeFromRestartSentinel);
+	if (hydrateCapabilities) await measureStartupAsync("service.deferred_startup.hydrate_capabilities", hydrateCapabilities);
+	await measureStartupAsync("service.deferred_startup.start_plugin_gateways", startPluginGateways);
+	await measureStartupAsync("service.deferred_startup.start_channels", startChannels);
+	await measureStartupAsync("service.deferred_startup.wake_restart_sentinel", wakeFromRestartSentinel);
 	console.log("✓ Deferred startup: plugin gateways and channels settled");
 	logStartupTrace("service.deferred_startup.end");
 }
 async function runGatewayRuntimeLoop(params) {
 	let startupTask = null;
 	try {
-		const runtimePoolTask = params.runtimePool.run();
+		const runtimeLoopTask = params.runRuntimeLoop();
 		startupTask = params.startDeferredStartup();
 		startupTask.catch(params.onDeferredStartupError);
-		await runtimePoolTask;
+		await runtimeLoopTask;
 	} finally {
 		if (startupTask) await startupTask.catch(() => void 0);
 		await params.cleanup();
 	}
 }
+async function runConfiguredGatewayRuntime(params) {
+	const onSystemSessionUpdated = createSystemSessionUpdatedPublisher({ publishUiEvent: params.publishUiEvent });
+	logStartupTrace("service.start_gateway.runtime_loop_begin");
+	await runGatewayRuntimeLoop({
+		runRuntimeLoop: () => runGatewayInboundLoop({
+			bus: params.gateway.bus,
+			sessionManager: params.gateway.sessionManager,
+			getConfig: params.getConfig,
+			resolveNcpAgent: params.getLiveUiNcpAgent,
+			onSystemSessionUpdated: ({ sessionKey }) => onSystemSessionUpdated({ sessionKey })
+		}),
+		startDeferredStartup: () => startDeferredGatewayStartup({
+			uiStartup: params.uiStartup,
+			deferredNcpSessionService: params.deferredNcpSessionService,
+			bus: params.gateway.bus,
+			sessionManager: params.gateway.sessionManager,
+			providerManager: params.gateway.providerManager,
+			cronService: params.gateway.cron,
+			gatewayController: params.gateway.gatewayController,
+			getConfig: params.getConfig,
+			getExtensionRegistry: params.getExtensionRegistry,
+			resolveMessageToolHints: params.resolveMessageToolHints,
+			hydrateCapabilities: params.deferredStartupHooks.hydrateCapabilities,
+			startPluginGateways: params.deferredStartupHooks.startPluginGateways,
+			startChannels: params.deferredStartupHooks.startChannels,
+			wakeFromRestartSentinel: params.deferredStartupHooks.wakeFromRestartSentinel,
+			onNcpAgentReady: params.deferredStartupHooks.onNcpAgentReady,
+			publishSessionChange: params.publishSessionChange
+		}),
+		onDeferredStartupError: params.onDeferredStartupError,
+		cleanup: params.cleanup
+	});
+}
 //#endregion
 //#region src/cli/commands/ncp/session/ncp-session-realtime-change.ts
 function toNcpSessionRealtimeEvent(change) {
@@ -13242,6 +14081,10 @@ function createDeferredUiNcpSessionService(fallbackService) {
 }
 //#endregion
 //#region src/cli/commands/service-support/session/service-ncp-session-realtime-bridge.ts
+function formatBackgroundTaskError(error) {
+	if (error instanceof Error) return error.stack ?? error.message;
+	return String(error);
+}
 function createLatestOnlySessionChangePublisher(publishSessionChange) {
 	const inFlightTasks = /* @__PURE__ */ new Map();
 	const rerunKeys = /* @__PURE__ */ new Set();
@@ -13272,7 +14115,9 @@ function createServiceNcpSessionRealtimeBridge(params) {
 	let publishSessionChange = async (_sessionKey) => {};
 	let scheduleSessionChange = async (_sessionKey) => {};
 	const deferredSessionService = createDeferredUiNcpSessionService(new UiSessionService(params.sessionManager, { onSessionUpdated: (sessionKey) => {
-		scheduleSessionChange(sessionKey);
+		scheduleSessionChange(sessionKey).catch((error) => {
+			console.error(`[session-realtime] failed to publish session change for ${sessionKey}: ${formatBackgroundTaskError(error)}`);
+		});
 	} }));
 	const publishLatestSessionChange = async (sessionKey) => {
 		await createNcpSessionRealtimeChangePublisher({
@@ -13297,35 +14142,26 @@ function createServiceNcpSessionRealtimeBridge(params) {
 //#endregion
 //#region src/cli/commands/plugin/plugin-registry-loader.ts
 function createPluginLogger() {
-	return {
-		info: (message) => console.log(message),
-		warn: (message) => console.warn(message),
-		error: (message) => console.error(message),
-		debug: (message) => console.debug(message)
-	};
+	return getAppLogger("plugin.registry_loader");
 }
 function withDevFirstPartyPluginPaths(config) {
-	const workspaceExtensionsDir = resolveDevFirstPartyPluginDir(process.env.NEXTCLAW_DEV_FIRST_PARTY_PLUGIN_DIR);
-	return {
-		workspaceExtensionsDir,
-		configWithDevPluginPaths: applyDevFirstPartyPluginLoadPaths(config, workspaceExtensionsDir)
-	};
+	return resolveDevPluginLoadingContext(config, resolveDevFirstPartyPluginDir(process.env.NEXTCLAW_DEV_FIRST_PARTY_PLUGIN_DIR));
 }
 async function loadPluginRegistryProgressively(config, workspaceDir, options = {}) {
-	const { workspaceExtensionsDir, configWithDevPluginPaths } = withDevFirstPartyPluginPaths(config);
+	const { configWithDevPluginOverrides, excludedRoots } = withDevFirstPartyPluginPaths(config);
 	return await loadOpenClawPluginsProgressively({
-		config: configWithDevPluginPaths,
+		config: configWithDevPluginOverrides,
 		workspaceDir,
-		excludeRoots: resolveDevFirstPartyPluginInstallRoots(config, workspaceExtensionsDir),
+		excludeRoots: excludedRoots,
 		...buildReservedPluginLoadOptions(),
 		onPluginProcessed: options.onPluginProcessed,
 		logger: createPluginLogger()
 	});
 }
 function discoverPluginRegistryStatus(config, workspaceDir) {
-	const { configWithDevPluginPaths } = withDevFirstPartyPluginPaths(config);
+	const { configWithDevPluginOverrides } = withDevFirstPartyPluginPaths(config);
 	return discoverPluginStatusReport({
-		config: configWithDevPluginPaths,
+		config: configWithDevPluginOverrides,
 		workspaceDir
 	});
 }
@@ -13335,7 +14171,6 @@ function createEmptyPluginRegistry() {
 		tools: [],
 		channels: [],
 		providers: [],
-		engines: [],
 		ncpAgentRuntimes: [],
 		diagnostics: [],
 		resolvedTools: []
@@ -13554,8 +14389,6 @@ async function hydrateServiceCapabilities(params) {
 		params.state.extensionRegistry = nextExtensionRegistry;
 		params.state.pluginChannelBindings = nextPluginChannelBindings;
 		params.state.pluginUiMetadata = nextPluginUiMetadata;
-		params.gateway.runtimePool.applyExtensionRegistry(nextExtensionRegistry);
-		params.gateway.runtimePool.applyRuntimeConfig(nextConfig);
 		params.getLiveUiNcpAgent()?.applyExtensionRegistry?.(nextExtensionRegistry);
 		if (shouldRebuildChannels) await params.gateway.reloader.rebuildChannels(nextConfig, { start: false });
 		params.uiStartup?.publish({
@@ -13579,7 +14412,7 @@ async function hydrateServiceCapabilities(params) {
 //#endregion
 //#region src/cli/commands/service-support/plugin/service-plugin-runtime-bridge.ts
 function installPluginRuntimeBridge(params) {
-	const { runtimePool, runtimeConfigPath, getPluginChannelBindings } = params;
+	const { dispatchPrompt, runtimeConfigPath, getPluginChannelBindings } = params;
 	setPluginRuntimeBridge({
 		loadConfig: () => toPluginConfigView$1(resolveConfigSecrets(loadConfig(), { configPath: runtimeConfigPath }), getPluginChannelBindings()),
 		writeConfigFile: async (nextConfigView) => {
@@ -13591,7 +14424,7 @@ function installPluginRuntimeBridge(params) {
 			if (!request) return;
 			try {
 				await dispatcherOptions.onReplyStart?.();
-				const response = await runtimePool.processDirect(request);
+				const response = await dispatchPrompt(request);
 				const replyText = typeof response === "string" ? response : String(response ?? "");
 				if (replyText.trim()) await dispatcherOptions.deliver({ text: replyText }, { kind: "final" });
 			} catch (error) {
@@ -13723,7 +14556,6 @@ function applyGatewayRuntimeCapabilityState(params) {
 	params.state.pluginChannelBindings = params.next.pluginChannelBindings;
 }
 function configureGatewayPluginRuntime(params) {
-	params.gateway.reloader.setApplyAgentRuntimeConfig((nextConfig) => params.gateway.runtimePool.applyRuntimeConfig(nextConfig));
 	params.gateway.reloader.setReloadPlugins(async ({ config: nextConfig, changedPaths }) => {
 		const result = await reloadServicePlugins({
 			nextConfig,
@@ -13746,9 +14578,7 @@ function configureGatewayPluginRuntime(params) {
 		});
 		params.state.pluginUiMetadata = getPluginUiMetadataFromRegistry(result.pluginRegistry);
 		params.state.pluginGatewayHandles = result.pluginGatewayHandles;
-		params.gateway.runtimePool.applyExtensionRegistry(result.extensionRegistry);
 		params.getLiveUiNcpAgent()?.applyExtensionRegistry?.(result.extensionRegistry);
-		params.gateway.runtimePool.applyRuntimeConfig(nextConfig);
 		if (result.restartChannels) console.log("Config reload: plugin channel gateways restarted.");
 		return { restartChannels: result.restartChannels };
 	});
@@ -13756,7 +14586,12 @@ function configureGatewayPluginRuntime(params) {
 		await params.getLiveUiNcpAgent()?.applyMcpConfig?.(nextConfig);
 	});
 	installPluginRuntimeBridge({
-		runtimePool: params.gateway.runtimePool,
+		dispatchPrompt: async (request) => await dispatchPromptOverNcp({
+			config: resolveConfigSecrets$2(loadConfig$2(), { configPath: params.gateway.runtimeConfigPath }),
+			sessionManager: params.gateway.sessionManager,
+			resolveNcpAgent: () => params.getLiveUiNcpAgent(),
+			...request
+		}),
 		runtimeConfigPath: params.gateway.runtimeConfigPath,
 		getPluginChannelBindings: () => params.state.pluginChannelBindings
 	});
@@ -13796,8 +14631,26 @@ function createDeferredGatewayStartupHooks(params) {
 	};
 }
 //#endregion
+//#region src/cli/commands/service-support/gateway/service-gateway-runtime-lifecycle.ts
+function handleGatewayDeferredStartupError(params) {
+	const message = params.error instanceof Error ? params.error.message : String(params.error);
+	params.bootstrapStatus.markError(message);
+	if (params.bootstrapStatus.getStatus().pluginHydration.state === "running") params.bootstrapStatus.markPluginHydrationError(message);
+	console.error(`Deferred startup failed: ${params.error instanceof Error ? params.error.message : String(params.error)}`);
+}
+async function cleanupGatewayRuntime(params) {
+	localUiRuntimeStore.clearIfOwnedByProcess();
+	await params.fileWatchers.clear();
+	params.resetRuntimeState();
+	params.clearRealtimeBridge();
+	await params.uiStartup?.deferredNcpAgent.close();
+	await params.remoteModule?.stop();
+	await stopPluginChannelGateways(params.runtimeState?.pluginGatewayHandles ?? []);
+	setPluginRuntimeBridge(null);
+}
+//#endregion
 //#region src/cli/commands/service.ts
-const { APP_NAME: APP_NAME$1, getApiBase, getConfigPath: getConfigPath$1, getProvider, getProviderName, getWorkspacePath: getWorkspacePath$1, LiteLLMProvider, loadConfig: loadConfig$1, MessageBus: MessageBus$1, resolveConfigSecrets: resolveConfigSecrets$1, SessionManager, parseAgentScopedSessionKey: parseAgentScopedSessionKey$1 } = NextclawCore;
+const { APP_NAME: APP_NAME$1, getApiBase, getConfigPath: getConfigPath$1, getProvider, getProviderName, getWorkspacePath: getWorkspacePath$1, LiteLLMProvider, loadConfig: loadConfig$1, MessageBus: MessageBus$1, resolveConfigSecrets: resolveConfigSecrets$1, SessionManager: SessionManager$1, parseAgentScopedSessionKey: parseAgentScopedSessionKey$1 } = NextclawCore;
 function createSkillsLoader(workspace) {
 	const ctor = NextclawCore.SkillsLoader;
 	if (!ctor) return null;
@@ -13807,10 +14660,14 @@ var ServiceCommands = class {
 	applyLiveConfigReload = null;
 	liveUiNcpAgent = null;
 	fileWatchers = new ServiceFileWatcherRegistry();
+	loggingRuntime = NextclawCore.getLoggingRuntime();
+	serviceLogger = this.loggingRuntime.getLogger("service");
+	loggingInstalled = false;
 	constructor(deps) {
 		this.deps = deps;
 	}
 	startGateway = async (options = {}) => {
+		this.ensureRuntimeLoggingInstalled();
 		logStartupTrace("service.start_gateway.begin");
 		await this.fileWatchers.clear();
 		this.applyLiveConfigReload = null;
@@ -13871,9 +14728,11 @@ var ServiceCommands = class {
 			initialPluginRegistry: createEmptyPluginRegistry(),
 			makeProvider: (config, providerOptions) => providerOptions?.allowMissing === true ? this.makeProvider(config, { allowMissing: true }) : this.makeProvider(config),
 			makeMissingProvider: (config) => this.makeMissingProvider(config),
-			requestRestart: (params) => this.deps.requestRestart(params)
+			requestRestart: (params) => this.deps.requestRestart(params),
+			getLiveUiNcpAgent: () => this.liveUiNcpAgent
 		}));
 		this.applyLiveConfigReload = gateway.applyLiveConfigReload;
+		const loadGatewayConfig = () => resolveConfigSecrets$1(loadConfig$1(), { configPath: gateway.runtimeConfigPath });
 		const gatewayRuntimeState = createGatewayRuntimeState(gateway);
 		runtimeState = gatewayRuntimeState;
 		uiStartup?.publish({
@@ -13889,10 +14748,6 @@ var ServiceCommands = class {
 			state: gatewayRuntimeState,
 			getLiveUiNcpAgent: () => this.liveUiNcpAgent
 		});
-		wireSystemSessionUpdatedPublisher({
-			runtimePool: gateway.runtimePool,
-			publishUiEvent: uiStartup?.publish
-		});
 		console.log("✓ Capability hydration: scheduled in background");
 		await measureStartupAsync("service.start_gateway_support_services", async () => await startGatewayRuntimeSupport({
 			cronJobs: gateway.cron.status().jobs,
@@ -13922,49 +14777,37 @@ var ServiceCommands = class {
 				sessionManager: gateway.sessionManager
 			})
 		});
-		logStartupTrace("service.start_gateway.runtime_loop_begin");
-		await runGatewayRuntimeLoop({
-			runtimePool: gateway.runtimePool,
-			startDeferredStartup: () => startDeferredGatewayStartup({
-				uiStartup,
-				deferredNcpSessionService: ncpSessionRealtimeBridge.deferredSessionService,
-				bus: gateway.bus,
-				sessionManager: gateway.sessionManager,
-				providerManager: gateway.providerManager,
-				cronService: gateway.cron,
-				gatewayController: gateway.gatewayController,
-				getConfig: () => resolveConfigSecrets$1(loadConfig$1(), { configPath: gateway.runtimeConfigPath }),
-				getExtensionRegistry: () => gatewayRuntimeState.extensionRegistry,
-				resolveMessageToolHints: ({ channel, accountId }) => resolvePluginChannelMessageToolHints({
-					registry: gatewayRuntimeState.pluginRegistry,
-					channel,
-					cfg: resolveConfigSecrets$1(loadConfig$1(), { configPath: gateway.runtimeConfigPath }),
-					accountId
-				}),
-				hydrateCapabilities: deferredGatewayStartupHooks.hydrateCapabilities,
-				startPluginGateways: deferredGatewayStartupHooks.startPluginGateways,
-				startChannels: deferredGatewayStartupHooks.startChannels,
-				wakeFromRestartSentinel: deferredGatewayStartupHooks.wakeFromRestartSentinel,
-				onNcpAgentReady: deferredGatewayStartupHooks.onNcpAgentReady,
-				publishSessionChange: ncpSessionRealtimeBridge.publishSessionChange
+		await runConfiguredGatewayRuntime({
+			uiStartup,
+			gateway,
+			deferredNcpSessionService: ncpSessionRealtimeBridge.deferredSessionService,
+			getConfig: loadGatewayConfig,
+			getExtensionRegistry: () => gatewayRuntimeState.extensionRegistry,
+			resolveMessageToolHints: ({ channel, accountId }) => resolvePluginChannelMessageToolHints({
+				registry: gatewayRuntimeState.pluginRegistry,
+				channel,
+				cfg: loadGatewayConfig(),
+				accountId
 			}),
-			onDeferredStartupError: (error) => {
-				const message = error instanceof Error ? error.message : String(error);
-				bootstrapStatus.markError(message);
-				if (bootstrapStatus.getStatus().pluginHydration.state === "running") bootstrapStatus.markPluginHydrationError(message);
-				console.error(`Deferred startup failed: ${error instanceof Error ? error.message : String(error)}`);
-			},
-			cleanup: async () => {
-				clearOwnedServiceState();
-				await this.fileWatchers.clear();
-				this.applyLiveConfigReload = null;
-				this.liveUiNcpAgent = null;
-				ncpSessionRealtimeBridge.clear();
-				await uiStartup?.deferredNcpAgent.close();
-				await gateway.remoteModule?.stop();
-				await stopPluginChannelGateways(runtimeState?.pluginGatewayHandles ?? []);
-				setPluginRuntimeBridge(null);
-			}
+			deferredStartupHooks: deferredGatewayStartupHooks,
+			getLiveUiNcpAgent: () => this.liveUiNcpAgent,
+			publishSessionChange: ncpSessionRealtimeBridge.publishSessionChange,
+			publishUiEvent: uiStartup?.publish,
+			onDeferredStartupError: (error) => handleGatewayDeferredStartupError({
+				bootstrapStatus,
+				error
+			}),
+			cleanup: async () => await cleanupGatewayRuntime({
+				fileWatchers: this.fileWatchers,
+				resetRuntimeState: () => {
+					this.applyLiveConfigReload = null;
+					this.liveUiNcpAgent = null;
+				},
+				clearRealtimeBridge: () => ncpSessionRealtimeBridge.clear(),
+				uiStartup,
+				remoteModule: gateway.remoteModule,
+				runtimeState
+			})
 		});
 		logStartupTrace("service.start_gateway.end");
 	};
@@ -14068,7 +14911,7 @@ var ServiceCommands = class {
 		if (binding.host !== uiConfig.host || binding.port !== uiConfig.port) {
 			console.log(`Detected running service UI bind (${binding.host}:${binding.port}); enforcing (${uiConfig.host}:${uiConfig.port})...`);
 			await this.stopService();
-			const stateAfterStop = readServiceState();
+			const stateAfterStop = managedServiceStateStore.read();
 			if (stateAfterStop && isProcessRunning(stateAfterStop.pid)) {
 				process.exitCode = 1;
 				console.error("Error: Failed to stop running service while enforcing public UI exposure.");
@@ -14083,12 +14926,14 @@ var ServiceCommands = class {
 		return true;
 	};
 	startService = async (options) => {
+		this.loggingRuntime.ensureReady();
+		const { open, startupTimeoutMs, uiOverrides } = options;
 		const config = loadConfig$1();
-		const uiConfig = resolveUiConfig(config, options.uiOverrides);
+		const uiConfig = resolveUiConfig(config, uiOverrides);
 		const uiUrl = resolveUiApiBase(uiConfig.host, uiConfig.port);
 		const apiUrl = `${uiUrl}/api`;
 		const staticDir = resolveUiStaticDir();
-		const existing = readServiceState();
+		const existing = managedServiceStateStore.read();
 		if (existing && isProcessRunning(existing.pid)) {
 			await this.handleExistingManagedService({
 				existing,
@@ -14097,7 +14942,7 @@ var ServiceCommands = class {
 			});
 			return;
 		}
-		if (existing) clearServiceState();
+		if (existing) managedServiceStateStore.clear();
 		if (!staticDir) {
 			process.exitCode = 1, console.error(`Error: ${APP_NAME$1} UI frontend bundle not found. Reinstall or rebuild ${APP_NAME$1}. For dev-only overrides, set NEXTCLAW_UI_STATIC_DIR to a built frontend directory.`);
 			return;
@@ -14112,6 +14957,40 @@ var ServiceCommands = class {
 			process.exitCode = 1, console.error(`Error: Cannot start ${APP_NAME$1} because UI port ${uiConfig.port} is already occupied.`), console.error(portPreflight.message);
 			return;
 		}
+		if (portPreflight.reusedExistingHealthyTarget) {
+			await this.reuseExistingHealthyStartTarget({
+				uiConfig,
+				uiUrl,
+				apiUrl,
+				open
+			});
+			return;
+		}
+		await this.startNewManagedServiceTarget({
+			config,
+			uiConfig,
+			uiUrl,
+			apiUrl,
+			healthUrl,
+			startupTimeoutMs
+		});
+		if (open) openBrowser(uiUrl);
+	};
+	reuseExistingHealthyStartTarget = async (params) => {
+		const { apiUrl, open, uiConfig, uiUrl } = params;
+		console.log(`✓ ${APP_NAME$1} is already serving the target UI/API port`);
+		console.log(`UI: ${uiUrl}`);
+		console.log(`API: ${apiUrl}`);
+		console.warn([
+			`Warning: The healthy listener on ${uiConfig.port} is not tracked by ${managedServiceStateStore.path}.`,
+			"This start call reused the existing runtime instead of spawning another one.",
+			"Use the owning process or port-level tools to stop it; managed stop/restart will not control it automatically."
+		].join(" "));
+		await this.printPublicUiUrls(uiConfig.host, uiConfig.port);
+		if (open) openBrowser(uiUrl);
+	};
+	startNewManagedServiceTarget = async (params) => {
+		const { apiUrl, config, healthUrl, startupTimeoutMs, uiConfig, uiUrl } = params;
 		const startup = spawnManagedService({
 			appName: APP_NAME$1,
 			config,
@@ -14119,13 +14998,14 @@ var ServiceCommands = class {
 			uiUrl,
 			apiUrl,
 			healthUrl,
-			startupTimeoutMs: options.startupTimeoutMs,
+			startupTimeoutMs,
 			resolveStartupTimeoutMs: this.resolveStartupTimeoutMs,
 			appendStartupStage: this.appendStartupStage,
 			printStartupFailureDiagnostics: this.printStartupFailureDiagnostics,
 			resolveServiceLogPath
 		});
 		if (!startup) {
+			this.serviceLogger.fatal("managed service startup aborted", { reason: "child_process_not_created" });
 			process.exitCode = 1;
 			return;
 		}
@@ -14141,22 +15021,27 @@ var ServiceCommands = class {
 			waitForBackgroundServiceReady: this.waitForBackgroundServiceReady,
 			isProcessRunning
 		});
-		if (!readiness.ready) {
-			if (!isProcessRunning(startup.snapshot.pid)) {
-				process.exitCode = 1;
-				clearServiceState();
-				const hint = readiness.lastProbeError ? ` Last probe error: ${readiness.lastProbeError}` : "";
-				this.appendStartupStage(startup.logPath, `startup failed: process exited before ready.${hint}`);
-				console.error(`Error: Failed to start background service. Check logs: ${startup.logPath}.${hint}`);
-				this.printStartupFailureDiagnostics({
-					uiUrl,
-					apiUrl,
-					healthUrl,
-					logPath: startup.logPath,
-					lastProbeError: readiness.lastProbeError
-				});
-				return;
-			}
+		if (!readiness.ready && !isProcessRunning(startup.snapshot.pid)) {
+			process.exitCode = 1;
+			managedServiceStateStore.clear();
+			const hint = readiness.lastProbeError ? ` Last probe error: ${readiness.lastProbeError}` : "";
+			this.appendStartupStage(startup.logPath, `startup failed: process exited before ready.${hint}`);
+			this.serviceLogger.fatal("managed service exited before readiness completed", {
+				uiUrl,
+				apiUrl,
+				healthUrl,
+				logPath: startup.logPath,
+				...readiness.lastProbeError ? { lastProbeError: readiness.lastProbeError } : {}
+			});
+			console.error(`Error: Failed to start background service. Check logs: ${startup.logPath}.${hint}`);
+			this.printStartupFailureDiagnostics({
+				uiUrl,
+				apiUrl,
+				healthUrl,
+				logPath: startup.logPath,
+				lastProbeError: readiness.lastProbeError
+			});
+			return;
 		}
 		startup.child.unref();
 		await reportManagedServiceStart({
@@ -14174,17 +15059,16 @@ var ServiceCommands = class {
 			printPublicUiUrls: this.printPublicUiUrls,
 			printServiceControlHints: this.printServiceControlHints
 		});
-		if (options.open) openBrowser(uiUrl);
 	};
 	stopService = async () => {
-		const state = readServiceState();
+		const state = managedServiceStateStore.read();
 		if (!state) {
-			console.log("No running service found.");
+			console.log("No running background service found.");
 			return;
 		}
 		if (!isProcessRunning(state.pid)) {
 			console.log("Service is not running. Cleaning up state.");
-			clearServiceState();
+			managedServiceStateStore.clear();
 			return;
 		}
 		console.log(`Stopping ${APP_NAME$1} (PID ${state.pid})...`);
@@ -14203,7 +15087,8 @@ var ServiceCommands = class {
 			}
 			await waitForExit(state.pid, 2e3);
 		}
-		clearServiceState();
+		managedServiceStateStore.clear();
+		localUiRuntimeStore.clearIfOwnedByProcess(state.pid);
 		console.log(`✓ ${APP_NAME$1} stopped`);
 	};
 	waitForBackgroundServiceReady = async (params) => {
@@ -14243,14 +15128,14 @@ var ServiceCommands = class {
 	};
 	appendStartupStage = (logPath, message) => {
 		try {
-			appendFileSync(logPath, `[${(/* @__PURE__ */ new Date()).toISOString()}] [startup] ${message}\n`, "utf-8");
+			this.serviceLogger.child("startup").info(message, { logPath });
 		} catch (error) {
 			const detail = error instanceof Error ? error.message : String(error);
 			console.error(`Warning: failed to write startup diagnostics log (${logPath}): ${detail}`);
 		}
 	};
 	printStartupFailureDiagnostics = (params) => {
-		const statePath = resolveServiceStatePath();
+		const statePath = managedServiceStateStore.path;
 		const lines = [
 			"Startup diagnostics:",
 			`- UI URL: ${params.uiUrl}`,
@@ -14264,20 +15149,22 @@ var ServiceCommands = class {
 	};
 	checkUiPortPreflight = async (params) => {
 		const { healthUrl, host, port } = params;
-		const availability = await checkPortAvailability({
+		const target = await inspectUiTarget({
 			host,
-			port
-		});
-		if (availability.available) return { ok: true };
-		const probe = await probeHealthEndpoint(healthUrl);
-		const lines = [`Port probe: ${availability.detail}`];
-		if (probe.healthy) {
-			lines.push(`Health probe: ${healthUrl} is already healthy. Another process is already serving this UI/API port.`);
-			lines.push(`This usually means a healthy ${APP_NAME$1} instance is already serving the port, but it is not tracked by the current managed service state, so restart cannot stop it automatically.`);
-		} else if (probe.error) {
-			lines.push(`Health probe: ${probe.error}`);
-			lines.push("The port is occupied by a process that does not answer as a healthy NextClaw HTTP server.");
-		}
+			port,
+			healthUrl
+		});
+		if (target.state === "available") return {
+			ok: true,
+			reusedExistingHealthyTarget: false
+		};
+		if (target.state === "healthy-existing") return {
+			ok: true,
+			reusedExistingHealthyTarget: true
+		};
+		const lines = [`Port probe: ${target.availabilityDetail}`];
+		if (target.probeError) lines.push(`Health probe: ${target.probeError}`);
+		lines.push("The port is occupied by a process that does not answer as a healthy NextClaw HTTP server.");
 		lines.push(`Fix: free port ${port} or start NextClaw with another port via --ui-port <port>.`);
 		lines.push(`Inspect locally with: ss -ltnp | grep ${port} || lsof -iTCP:${port} -sTCP:LISTEN -n -P`);
 		return {
@@ -14334,6 +15221,17 @@ var ServiceCommands = class {
 		console.log("Service controls:");
 		console.log(`  - Check status: ${APP_NAME$1} status`);
 		console.log(`  - If you need to stop the service, run: ${APP_NAME$1} stop`);
+		console.log(`  - View log paths: ${APP_NAME$1} logs path`);
+		console.log(`  - Tail recent logs: ${APP_NAME$1} logs tail`);
+	};
+	ensureRuntimeLoggingInstalled = () => {
+		if (this.loggingInstalled) return;
+		NextclawCore.configureAppLogging({
+			installConsoleMirror: true,
+			installProcessCrashMonitor: true
+		});
+		this.serviceLogger.info("runtime logging ready", { startupId: this.loggingRuntime.getStartupId() });
+		this.loggingInstalled = true;
 	};
 	installBuiltinMarketplaceSkill = (slug, _force) => {
 		if (!(createSkillsLoader(getWorkspacePath$1(loadConfig$1().agents.defaults.workspace))?.listSkills(false) ?? []).find((skill) => skill.name === slug && skill.source === "builtin")) return null;
@@ -14538,8 +15436,7 @@ var WorkspaceManager = class {
 	}
 };
 //#endregion
-//#region src/cli/runtime.ts
-const LOGO = "🤖";
+//#region src/cli/commands/agent/cli-agent-runner.ts
 const EXIT_COMMANDS = new Set([
 	"exit",
 	"quit",
@@ -14547,6 +15444,91 @@ const EXIT_COMMANDS = new Set([
 	"/quit",
 	":q"
 ]);
+function buildCliSharedMetadata(opts) {
+	return typeof opts.model === "string" && opts.model.trim() ? { model: opts.model.trim() } : {};
+}
+function createCliHistoryInterface() {
+	const historyFile = join(getDataDir(), "history", "cli_history");
+	mkdirSync(resolve(historyFile, ".."), { recursive: true });
+	const history = existsSync(historyFile) ? readFileSync(historyFile, "utf-8").split("\n").filter(Boolean) : [];
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	rl.on("close", () => {
+		writeFileSync(historyFile, history.concat(rl.history ?? []).join("\n"));
+		process.exit(0);
+	});
+	return rl;
+}
+async function runCliInteractiveLoop(params) {
+	console.log(`${params.logo} Interactive mode (type exit or Ctrl+C to quit)\n`);
+	const rl = createCliHistoryInterface();
+	let running = true;
+	while (running) {
+		const trimmed = (await prompt(rl, "You: ")).trim();
+		if (!trimmed) continue;
+		if (EXIT_COMMANDS.has(trimmed.toLowerCase())) {
+			rl.close();
+			running = false;
+			break;
+		}
+		printAgentResponse(await dispatchPromptOverNcp({
+			config: params.config,
+			sessionManager: params.sessionManager,
+			resolveNcpAgent: () => params.ncpAgent,
+			sessionKey: params.sessionKey,
+			content: trimmed,
+			metadata: params.metadata
+		}));
+	}
+}
+async function runCliAgentCommand(params) {
+	const bus = new MessageBus();
+	const sessionManager = new SessionManager({
+		workspace: params.workspace,
+		homeDir: getDataDir()
+	});
+	const ncpAgent = await createUiNcpAgent({
+		bus,
+		providerManager: params.providerManager,
+		sessionManager,
+		getConfig: params.loadResolvedConfig,
+		getExtensionRegistry: () => params.extensionRegistry,
+		resolveMessageToolHints: ({ channel, accountId }) => params.resolveMessageToolHints({
+			channel,
+			accountId
+		})
+	});
+	try {
+		const sessionKey = params.opts.session ?? "cli:default";
+		const sharedMetadata = buildCliSharedMetadata(params.opts);
+		if (params.opts.message) {
+			printAgentResponse(await dispatchPromptOverNcp({
+				config: params.config,
+				sessionManager,
+				resolveNcpAgent: () => ncpAgent,
+				sessionKey,
+				content: params.opts.message,
+				metadata: sharedMetadata
+			}));
+			return;
+		}
+		await runCliInteractiveLoop({
+			logo: params.logo,
+			config: params.config,
+			sessionManager,
+			ncpAgent,
+			sessionKey,
+			metadata: sharedMetadata
+		});
+	} finally {
+		await ncpAgent.dispose?.();
+	}
+}
+//#endregion
+//#region src/cli/runtime.ts
+const LOGO = "🤖";
 const FORCED_PUBLIC_UI_HOST = "0.0.0.0";
 var CliRuntime = class {
 	logo;
@@ -14566,6 +15548,7 @@ var CliRuntime = class {
 	remoteCommands;
 	remote;
 	diagnosticsCommands;
+	logsCommands;
 	constructor(options = {}) {
 		logStartupTrace("cli.runtime.constructor.begin");
 		this.logo = options.logo ?? "🤖";
@@ -14598,8 +15581,9 @@ var CliRuntime = class {
 			hasRunningManagedService: hasRunningNextclawManagedService
 		}));
 		this.diagnosticsCommands = measureStartupSync("cli.runtime.diagnostics_commands", () => new DiagnosticsCommands({ logo: this.logo }));
+		this.logsCommands = measureStartupSync("cli.runtime.logs_commands", () => new LogsCommands());
 		this.restartCoordinator = measureStartupSync("cli.runtime.restart_coordinator", () => new RestartCoordinator({
-			readServiceState,
+			readServiceState: managedServiceStateStore.read,
 			isProcessRunning,
 			currentPid: () => process.pid,
 			restartBackgroundService: async (reason) => this.restartBackgroundService(reason),
@@ -14619,7 +15603,7 @@ var CliRuntime = class {
 	restartBackgroundService = async (reason) => {
 		if (this.serviceRestartTask) return this.serviceRestartTask;
 		this.serviceRestartTask = (async () => {
-			const state = readServiceState();
+			const state = managedServiceStateStore.read();
 			if (!state || !isProcessRunning(state.pid) || state.pid === process.pid) return false;
 			const uiHost = FORCED_PUBLIC_UI_HOST;
 			const uiPort = typeof state.uiPort === "number" && Number.isFinite(state.uiPort) ? state.uiPort : 55667;
@@ -14645,7 +15629,7 @@ var CliRuntime = class {
 		const strategy = params.strategy ?? "background-service-or-manual";
 		if (strategy !== "background-service-or-exit" && strategy !== "exit-process") return;
 		if (this.selfRelaunchArmed) return;
-		const state = readServiceState();
+		const state = managedServiceStateStore.read();
 		if (!state || state.pid !== process.pid) return;
 		const uiPort = typeof state.uiPort === "number" && Number.isFinite(state.uiPort) ? state.uiPort : 55667;
 		const delayMs = typeof params.delayMs === "number" && Number.isFinite(params.delayMs) ? Math.max(0, Math.floor(params.delayMs)) : 100;
@@ -14655,7 +15639,7 @@ var CliRuntime = class {
 			"--ui-port",
 			String(uiPort)
 		];
-		const serviceStatePath = resolve(getDataDir(), "run", "service.json");
+		const serviceStatePath = managedServiceStateStore.path;
 		const helperScript = [
 			"const { spawnSync } = require(\"node:child_process\");",
 			"const { readFileSync } = require(\"node:fs\");",
@@ -14840,13 +15824,13 @@ var CliRuntime = class {
 			uiPort: opts.uiPort,
 			forcedPublicHost: FORCED_PUBLIC_UI_HOST
 		});
-		const state = readServiceState();
+		const state = managedServiceStateStore.read();
 		if (state && isProcessRunning(state.pid)) {
 			console.log(`Restarting ${APP_NAME}...`);
 			await this.serviceCommands.stopService();
 		} else {
 			if (state) {
-				clearServiceState();
+				managedServiceStateStore.clear();
 				console.log("Service state was stale and has been cleaned up.");
 			}
 			const unmanagedHealthyServiceMessage = await describeUnmanagedHealthyTargetMessage({ uiOverrides });
@@ -14888,22 +15872,19 @@ var CliRuntime = class {
 			}
 		});
 		try {
-			const agentLoop = new AgentLoop({
-				bus: new MessageBus(),
-				providerManager: new ProviderManager({
-					defaultProvider: this.serviceCommands.createProvider(config) ?? this.serviceCommands.createMissingProvider(config),
-					config
-				}),
-				workspace,
-				model: config.agents.defaults.model,
-				maxIterations: config.agents.defaults.maxToolIterations,
-				contextTokens: config.agents.defaults.contextTokens,
-				searchConfig: config.search,
-				execConfig: config.tools.exec,
-				restrictToWorkspace: config.tools.restrictToWorkspace,
-				contextConfig: config.agents.context,
+			const provider = this.serviceCommands.createProvider(config) ?? this.serviceCommands.createMissingProvider(config);
+			const providerManager = this.createObservedProviderManager(new ProviderManager({
+				defaultProvider: provider,
+				config
+			}), "cli-agent");
+			await runCliAgentCommand({
+				logo: this.logo,
+				opts,
 				config,
+				workspace,
+				providerManager,
 				extensionRegistry,
+				loadResolvedConfig: () => resolveConfigSecrets(loadConfig(), { configPath }),
 				resolveMessageToolHints: ({ channel, accountId }) => resolvePluginChannelMessageToolHints({
 					registry: pluginRegistry,
 					channel,
@@ -14911,43 +15892,6 @@ var CliRuntime = class {
 					accountId
 				})
 			});
-			if (opts.message) {
-				printAgentResponse(await agentLoop.processDirect({
-					content: opts.message,
-					sessionKey: opts.session ?? "cli:default",
-					channel: "cli",
-					chatId: "direct",
-					metadata: typeof opts.model === "string" && opts.model.trim() ? { model: opts.model.trim() } : {}
-				}));
-				return;
-			}
-			console.log(`${this.logo} Interactive mode (type exit or Ctrl+C to quit)\n`);
-			const historyFile = join(getDataDir(), "history", "cli_history");
-			mkdirSync(resolve(historyFile, ".."), { recursive: true });
-			const history = existsSync(historyFile) ? readFileSync(historyFile, "utf-8").split("\n").filter(Boolean) : [];
-			const rl = createInterface({
-				input: process.stdin,
-				output: process.stdout
-			});
-			rl.on("close", () => {
-				writeFileSync(historyFile, history.concat(rl.history ?? []).join("\n"));
-				process.exit(0);
-			});
-			let running = true;
-			while (running) {
-				const trimmed = (await prompt(rl, "You: ")).trim();
-				if (!trimmed) continue;
-				if (EXIT_COMMANDS.has(trimmed.toLowerCase())) {
-					rl.close();
-					running = false;
-					break;
-				}
-				printAgentResponse(await agentLoop.processDirect({
-					content: trimmed,
-					sessionKey: opts.session ?? "cli:default",
-					metadata: typeof opts.model === "string" && opts.model.trim() ? { model: opts.model.trim() } : {}
-				}));
-			}
 		} finally {
 			setPluginRuntimeBridge(null);
 		}
@@ -14964,28 +15908,19 @@ var CliRuntime = class {
 		}
 		const versionBefore = getPackageVersion$1();
 		console.log(`Current version: ${versionBefore}`);
-		const result = runSelfUpdate({
-			timeoutMs,
-			cwd: process.cwd()
+		const report = reportSelfUpdateResult({
+			appName: APP_NAME,
+			currentVersion: versionBefore,
+			result: runSelfUpdate({
+				timeoutMs,
+				cwd: process.cwd(),
+				currentVersion: versionBefore
+			}),
+			readInstalledVersion: getPackageVersion$1
 		});
-		const printSteps = () => {
-			for (const step of result.steps) {
-				console.log(`- ${step.cmd} ${step.args.join(" ")} (code ${step.code ?? "?"})`);
-				if (step.stderr) console.log(`  stderr: ${step.stderr}`);
-				if (step.stdout) console.log(`  stdout: ${step.stdout}`);
-			}
-		};
-		if (!result.ok) {
-			console.error(`Update failed: ${result.error ?? "unknown error"}`);
-			if (result.steps.length > 0) printSteps();
-			process.exit(1);
-		}
-		const versionAfter = getPackageVersion$1();
-		console.log(`✓ Update complete (${result.strategy})`);
-		if (versionAfter === versionBefore) console.log(`Version unchanged: ${versionBefore}`);
-		else console.log(`Version updated: ${versionBefore} -> ${versionAfter}`);
-		const state = readServiceState();
-		if (state && isProcessRunning(state.pid)) console.log(`Tip: restart ${APP_NAME} to apply the update.`);
+		if (!report.ok) process.exit(1);
+		const state = managedServiceStateStore.read();
+		if (report.shouldSuggestRestart && state && isProcessRunning(state.pid)) console.log(`Tip: restart ${APP_NAME} to apply the update.`);
 	};
 	agentsList = (opts = {}) => {
 		this.agentCommands.agentsList(opts);
@@ -15092,6 +16027,12 @@ var CliRuntime = class {
 	doctor = async (opts = {}) => {
 		await this.diagnosticsCommands.doctor(opts);
 	};
+	logsPath = () => {
+		this.logsCommands.logsPath();
+	};
+	logsTail = (opts = {}) => {
+		this.logsCommands.logsTail(opts);
+	};
 	skillsInstall = async (options) => {
 		const config = loadConfig();
 		const workdir = resolveSkillsInstallWorkdir({
@@ -15119,6 +16060,7 @@ var CliRuntime = class {
 		console.log(`  Alias: ${result.slug}`);
 		console.log(`  Files: ${result.fileCount}`);
 	};
+	createObservedProviderManager = (providerManager, source) => new ObservedProviderManager(providerManager, new LlmUsageObserver(llmUsageRecorder, source));
 };
 //#endregion
 //#region src/cli/register-agents-commands.ts
@@ -15135,6 +16077,7 @@ function registerAgentsCommands(program, runtime) {
 logStartupTrace("cli.index.module_loaded");
 const program = new Command();
 const runtime = measureStartupSync("cli.runtime.construct", () => new CliRuntime({ logo: LOGO }));
+const llmUsageCommands = new LlmUsageCommands();
 program.name(APP_NAME).description(`${LOGO} ${APP_NAME} - ${APP_TAGLINE}`).version(getPackageVersion$1(), "-v, --version", "show version");
 program.command("onboard").description(`Initialize ${APP_NAME} configuration and workspace`).action(async () => runtime.onboard());
 program.command("init").description(`Initialize ${APP_NAME} configuration and workspace`).option("-f, --force", "Overwrite existing template files").action(async (opts) => runtime.init({ force: Boolean(opts.force) }));
@@ -15203,6 +16146,10 @@ cron.command("disable <jobId>").action(async (jobId) => runtime.cronEnable(jobId
 cron.command("run <jobId>").option("-f, --force", "Run even if disabled").action(async (jobId, opts) => runtime.cronRun(jobId, opts));
 program.command("status").description(`Show ${APP_NAME} status`).option("--json", "Output JSON", false).option("--verbose", "Show extra diagnostics", false).option("--fix", "Fix stale service state when safe", false).action(async (opts) => runtime.status(opts));
 program.command("doctor").description(`Run ${APP_NAME} diagnostics`).option("--json", "Output JSON", false).option("--verbose", "Show extra diagnostics", false).option("--fix", "Fix stale service state when safe", false).action(async (opts) => runtime.doctor(opts));
+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);
 //#endregion
 export {};