@nextclaw/service 0.1.7 → 0.1.8

package/dist/shared/services/gateway/gateway-restart-wake.service.js

@@ -1,5 +1,6 @@
 import { consumeRestartSentinel, formatRestartSentinelMessage, parseSessionKey } from "../restart/restart-sentinel.service.js";
-import { resolveSessionRouteCandidate } from "../runtime/service-managed-startup.service.js";
+import { resolveSessionRouteCandidate } from "../runtime/utils/managed-service-routing.utils.js";
+import "../runtime/service-managed-startup.service.js";
 import { parseAgentScopedSessionKey } from "@nextclaw/core";
 //#region src/shared/services/gateway/gateway-restart-wake.service.ts
 function normalizeOptionalString(value) {

package/dist/shared/services/gateway/managers/gateway-plugin.manager.js

@@ -1,18 +1,32 @@
 import { toExtensionRegistry } from "../../../../commands/plugin/plugin-extension-registry.js";
-import { createEmptyPluginRegistry, discoverPluginRegistryStatus, loadPluginRegistryProgressively } from "../../../../commands/plugin/plugin-registry-loader.js";
+import { createEmptyPluginRegistry, discoverPluginRegistryStatus, loadPluginRegistryProgressively } from "../../../../commands/plugin/plugin-registry-loader.utils.js";
 import { logPluginDiagnostics } from "../../../../commands/plugin/index.js";
 import { shouldRestartChannelsForPluginReload } from "../../../../commands/plugin/plugin-reload.js";
 import { logPluginGatewayDiagnostics, pluginGatewayLogger } from "../service-startup-support.service.js";
 import { getWorkspacePath } from "@nextclaw/core";
-import { eventKeys } from "@nextclaw/shared";
 import { getPluginChannelBindings, getPluginUiMetadataFromRegistry, toPluginConfigView } from "@nextclaw/openclaw-compat";
+import { eventKeys } from "@nextclaw/shared";
 //#region src/shared/services/gateway/managers/gateway-plugin.manager.ts
+function toManifestChannelRegistrations(channelBindings) {
+	return channelBindings.map((binding) => ({
+		extensionId: binding.pluginId,
+		channel: binding.channel,
+		source: "extension-manifest"
+	}));
+}
 function buildSnapshot(registry, extensionContributions) {
 	const extensionChannelIds = new Set(extensionContributions.channelBindings.map((binding) => binding.channelId));
 	const extensionPluginIds = new Set(extensionContributions.uiMetadata.map((metadata) => metadata.id));
+	const registryExtensionRegistry = toExtensionRegistry(registry);
 	return {
 		registry,
-		extensionRegistry: toExtensionRegistry(registry),
+		extensionRegistry: {
+			...registryExtensionRegistry,
+			channels: [...registryExtensionRegistry.channels.filter((registration) => {
+				const channelId = registration.channel.id?.trim();
+				return !channelId || !extensionChannelIds.has(channelId);
+			}), ...toManifestChannelRegistrations(extensionContributions.channelBindings)]
+		},
 		channelBindings: [...getPluginChannelBindings(registry).filter((binding) => !extensionChannelIds.has(binding.channelId)), ...extensionContributions.channelBindings],
 		uiMetadata: [...getPluginUiMetadataFromRegistry(registry).filter((metadata) => !extensionPluginIds.has(metadata.id)), ...extensionContributions.uiMetadata]
 	};

package/dist/shared/services/gateway/managers/gateway-remote.manager.d.ts

@@ -1,9 +1,9 @@
 import { createManagedRemoteModuleForUi } from "../../runtime/utils/service-remote-runtime.utils.js";
 import { GatewayRuntimeDeps } from "../nextclaw-gateway-runtime.service.js";
 import { Config } from "@nextclaw/core";
-import { UiRemoteAccessHost } from "@nextclaw/server";
-import { RemoteRuntimeState } from "@nextclaw/remote";
 import { ConfigManager } from "@nextclaw/kernel";
+import { RemoteRuntimeState } from "@nextclaw/remote";
+import { UiRemoteAccessHost } from "@nextclaw/server";
 
 //#region src/shared/services/gateway/managers/gateway-remote.manager.d.ts
 type RemoteServiceModule$1 = ReturnType<typeof createManagedRemoteModuleForUi>;

package/dist/shared/services/gateway/managers/gateway-remote.manager.js

@@ -1,5 +1,5 @@
-import { createRemoteAccessHost } from "../../ui/service-remote-access.service.js";
 import { createManagedRemoteModuleForUi } from "../../runtime/utils/service-remote-runtime.utils.js";
+import { createRemoteAccessHost } from "../../ui/service-remote-access.service.js";
 //#region src/shared/services/gateway/managers/gateway-remote.manager.ts
 var GatewayRemoteManager = class {
 	remoteModule;

package/dist/shared/services/gateway/nextclaw-gateway-runtime.service.d.ts

@@ -9,9 +9,9 @@ import { ServiceBootstrapStatusStore } from "./service-bootstrap-status.service.
 import { ServiceFileWatcherRegistry } from "./service-startup-support.service.js";
 import { ServiceExtensionRuntime } from "../extensions/service-extension-runtime.service.js";
 import * as NextclawCore from "@nextclaw/core";
+import { AgentRuntimeHandle, AutomationManager, ConfigManager, LlmProviderManager, NextclawKernel } from "@nextclaw/kernel";
 import { MarketplaceApiConfig, UiNcpAgent, UiRuntimeControlHost, UiRuntimeUpdateHost } from "@nextclaw/server";
 import { EventBus, Ingress } from "@nextclaw/shared";
-import { AgentRuntimeHandle, AutomationManager, ConfigManager, LlmProviderManager, NextclawKernel } from "@nextclaw/kernel";
 
 //#region src/shared/services/gateway/nextclaw-gateway-runtime.service.d.ts
 type Config$1 = NextclawCore.Config;

package/dist/shared/services/gateway/nextclaw-gateway-runtime.service.js

@@ -1,31 +1,31 @@
+import { logStartupTrace, measureStartupAsync, measureStartupSync } from "../../utils/startup-trace.js";
 import { openBrowser, resolveUiConfig, resolveUiStaticDir } from "../../utils/cli.utils.js";
 import { NextclawDistributionService } from "../runtime/nextclaw-distribution.service.js";
-import { localUiRuntimeStore } from "../../stores/local-ui-runtime.store.js";
 import { managedServiceStateStore } from "../../stores/managed-service-state.store.js";
-import { logStartupTrace, measureStartupAsync, measureStartupSync } from "../../utils/startup-trace.js";
-import { GatewayControllerImpl } from "../../controllers/gateway.controller.js";
-import { companionRuntimeService } from "../ui/companion-runtime.service.js";
-import { createRuntimeControlHost } from "../ui/runtime-control-host.service.js";
-import { NpmRuntimeUpdateHost } from "../ui/npm-runtime-update-host.service.js";
-import { ServiceMarketplaceInstaller } from "../marketplace/service-marketplace-installer.service.js";
 import { resolveChannelConfigView } from "../../../commands/channel/channel-config-view.js";
+import { localUiRuntimeStore } from "../../stores/local-ui-runtime.store.js";
+import { GatewayControllerImpl } from "../../controllers/gateway.controller.js";
 import { ServiceExtensionRuntime } from "../extensions/service-extension-runtime.service.js";
 import { ServiceFileWatcherRegistry, markLocalUiRuntimeIfStarted, startGatewayRuntimeSupport, watchServiceConfigFile } from "./service-startup-support.service.js";
 import { GatewayPluginManager } from "./managers/gateway-plugin.manager.js";
 import { GatewayRemoteManager } from "./managers/gateway-remote.manager.js";
 import { GatewayRestartWakeService } from "./gateway-restart-wake.service.js";
 import { createCronJobHandler } from "./cron-job-handler.service.js";
+import { companionRuntimeService } from "../ui/companion-runtime.service.js";
 import { handleGatewayDeferredStartupError } from "./utils/gateway-runtime-lifecycle.utils.js";
 import { NextclawApp } from "./nextclaw-app.service.js";
 import { ServiceBootstrapStatusStore } from "./service-bootstrap-status.service.js";
 import { createDeferredUiNcpAgent } from "../session/service-deferred-ncp-agent.service.js";
 import { installPluginRuntimeBridge } from "../plugin/utils/plugin-runtime-bridge.utils.js";
 import { wrapStartChannelsWithDevPluginHotReload } from "../plugin/utils/plugin-dev-hot-reload.utils.js";
-import { resolve } from "node:path";
+import { ServiceMarketplaceInstaller } from "../marketplace/service-marketplace-installer.service.js";
+import { NpmRuntimeUpdateHost } from "../ui/npm-runtime-update-host.service.js";
+import { createRuntimeControlHost } from "../ui/runtime-control-host.service.js";
 import * as NextclawCore from "@nextclaw/core";
-import { startUiServer } from "@nextclaw/server";
-import { setPluginRuntimeBridge } from "@nextclaw/openclaw-compat";
 import { NextclawKernel, runGatewayInboundLoop } from "@nextclaw/kernel";
+import { setPluginRuntimeBridge } from "@nextclaw/openclaw-compat";
+import { resolve } from "node:path";
+import { startUiServer } from "@nextclaw/server";
 import { setImmediate } from "node:timers/promises";
 //#region src/shared/services/gateway/nextclaw-gateway-runtime.service.ts
 const { getConfigPath: getConfigPath$1, getDataDir: getDataDir$1, getWorkspacePath: getWorkspacePath$1, saveConfig: saveConfig$1 } = NextclawCore;

package/dist/shared/services/gateway/service-bootstrap-status.service.d.ts

@@ -1,5 +1,5 @@
-import { BootstrapRemoteState, BootstrapStatusView } from "@nextclaw/server";
 import { RemoteRuntimeState } from "@nextclaw/remote";
+import { BootstrapRemoteState, BootstrapStatusView } from "@nextclaw/server";
 
 //#region src/shared/services/gateway/service-bootstrap-status.service.d.ts
 declare class ServiceBootstrapStatusStore {

package/dist/shared/services/gateway/service-startup-support.service.d.ts

@@ -1,7 +1,7 @@
 import { Config } from "@nextclaw/core";
+import { AutomationManager } from "@nextclaw/kernel";
 import { RemoteServiceModule } from "@nextclaw/remote";
 import { PluginDiagnostic } from "@nextclaw/openclaw-compat";
-import { AutomationManager } from "@nextclaw/kernel";
 import { FSWatcher } from "chokidar";
 
 //#region src/shared/services/gateway/service-startup-support.service.d.ts

package/dist/shared/services/marketplace/service-marketplace-installer.service.js

@@ -1,9 +1,9 @@
-import { buildMarketplaceSkillInstallArgs, pickUserFacingCommandSummary } from "../../utils/marketplace/service-marketplace-helpers.utils.js";
 import { disablePluginMutation, enablePluginMutation, installPluginMutation, uninstallPluginMutation } from "../../../commands/plugin/plugin-mutation-actions.js";
+import { buildMarketplaceSkillInstallArgs, pickUserFacingCommandSummary } from "../../utils/marketplace/service-marketplace-helpers.utils.js";
 import { ServiceMcpMarketplaceOps } from "./service-mcp-marketplace-ops.js";
-import { join } from "node:path";
 import { getWorkspacePath, loadConfig } from "@nextclaw/core";
 import { existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
 //#region src/shared/services/marketplace/service-marketplace-installer.service.ts
 var ServiceMarketplaceInstaller = class {
 	constructor(deps) {

package/dist/shared/services/plugin/utils/plugin-runtime-bridge.utils.js

@@ -1,6 +1,6 @@
 import { loadConfig, saveConfig } from "@nextclaw/core";
-import { setPluginRuntimeBridge } from "@nextclaw/openclaw-compat";
 import { dispatchPromptOverNcp } from "@nextclaw/kernel";
+import { setPluginRuntimeBridge } from "@nextclaw/openclaw-compat";
 //#region src/shared/services/plugin/utils/plugin-runtime-bridge.utils.ts
 function installPluginRuntimeBridge(gateway) {
 	setPluginRuntimeBridge({

package/dist/shared/services/restart/restart-sentinel.service.js

@@ -1,6 +1,6 @@
-import { resolve } from "node:path";
 import { getDataDir } from "@nextclaw/core";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
 //#region src/shared/services/restart/restart-sentinel.service.ts
 const RESTART_SENTINEL_FILENAME = "restart-sentinel.json";
 const PENDING_SYSTEM_EVENTS_KEY = "pending_system_events";

package/dist/shared/services/runtime/runtime-command.service.d.ts

@@ -9,6 +9,8 @@ type Config$1 = NextclawCore.Config;
 declare class RuntimeCommandService {
   private deps;
   private loggingInstalled;
+  private processExitLoggingInstalled;
+  private readonly runtimeLogger;
   private readonly managedServiceCommandService;
   constructor(deps: {
     requestRestart: (params: RequestRestartParams) => Promise<void>;
@@ -29,6 +31,7 @@ declare class RuntimeCommandService {
   private runCliSubcommand;
   private runCommand;
   private ensureRuntimeLoggingInstalled;
+  private installProcessExitLogging;
   private checkUiPortPreflight;
   private printPublicUiUrls;
   private printServiceControlHints;

package/dist/shared/services/runtime/runtime-command.service.js

@@ -1,17 +1,19 @@
 import { isLoopbackHost, resolvePublicIp, resolveUiStaticDir } from "../../utils/cli.utils.js";
 import { NextclawDistributionService } from "./nextclaw-distribution.service.js";
-import { describeUnmanagedHealthyTargetMessage, inspectUiTarget } from "../../utils/service-port-probe.utils.js";
-import { buildMarketplaceSkillInstallArgs, pickUserFacingCommandSummary } from "../../utils/marketplace/service-marketplace-helpers.utils.js";
 import { resolveCliSubcommandEntry } from "../../utils/marketplace/cli-subcommand-launch.utils.js";
+import { describeUnmanagedHealthyTargetMessage, inspectUiTarget } from "../../utils/service-port-probe.utils.js";
 import { ManagedServiceCommandService } from "./service-managed-startup.service.js";
+import { buildMarketplaceSkillInstallArgs, pickUserFacingCommandSummary } from "../../utils/marketplace/service-marketplace-helpers.utils.js";
 import { NextclawGatewayRuntime } from "../gateway/nextclaw-gateway-runtime.service.js";
 import { createSkillsLoader } from "./utils/skills-loader.utils.js";
-import { spawn } from "node:child_process";
 import * as NextclawCore from "@nextclaw/core";
+import { spawn } from "node:child_process";
 //#region src/shared/services/runtime/runtime-command.service.ts
 const { getWorkspacePath: getWorkspacePath$1, loadConfig: loadConfig$1 } = NextclawCore;
 var RuntimeCommandService = class {
 	loggingInstalled = false;
+	processExitLoggingInstalled = false;
+	runtimeLogger = NextclawCore.getAppLogger("service.runtime");
 	managedServiceCommandService = new ManagedServiceCommandService({
 		startGateway: async (options) => await this.startGateway(options),
 		printPublicUiUrls: async (host, port) => await this.printPublicUiUrls(host, port),
@@ -24,6 +26,12 @@ var RuntimeCommandService = class {
 	}
 	startGateway = async (options = {}) => {
 		this.ensureRuntimeLoggingInstalled();
+		this.installProcessExitLogging();
+		this.runtimeLogger.info("runtime.process.started", {
+			runtimeKind: "serve-process",
+			pid: process.pid,
+			source: "RuntimeCommandService.startGateway"
+		});
 		await new NextclawGatewayRuntime({
 			requestRestart: this.deps.requestRestart,
 			initializeAgentHomeDirectory: this.deps.initializeAgentHomeDirectory,
@@ -32,6 +40,11 @@ var RuntimeCommandService = class {
 			runCliSubcommand: this.runCliSubcommand,
 			installBuiltinMarketplaceSkill: this.installBuiltinMarketplaceSkill
 		}, { ...options }).start();
+		this.runtimeLogger.info("runtime.process.ready", {
+			runtimeKind: "serve-process",
+			pid: process.pid,
+			source: "RuntimeCommandService.startGateway"
+		});
 	};
 	startService = async (options) => {
 		await this.managedServiceCommandService.startService(options);
@@ -115,6 +128,17 @@ var RuntimeCommandService = class {
 		});
 		this.loggingInstalled = true;
 	};
+	installProcessExitLogging = () => {
+		if (this.processExitLoggingInstalled) return;
+		this.processExitLoggingInstalled = true;
+		process.once("exit", (code) => {
+			this.runtimeLogger.warn("runtime.process.exited", {
+				runtimeKind: "serve-process",
+				pid: process.pid,
+				code
+			});
+		});
+	};
 	checkUiPortPreflight = async (params) => {
 		const target = await inspectUiTarget(params);
 		if (target.state === "available") return {

package/dist/shared/services/runtime/service-managed-startup.service.d.ts

@@ -1,7 +1,6 @@
-import { ManagedServiceState } from "../../stores/managed-service-state.store.js";
-import { localUiRuntimeStore } from "../../stores/local-ui-runtime.store.js";
-import { spawn } from "node:child_process";
+import { ManagedServiceSnapshot, resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate } from "./utils/managed-service-routing.utils.js";
 import * as NextclawCore from "@nextclaw/core";
+import { spawn } from "node:child_process";
 
 //#region src/shared/services/runtime/service-managed-startup.service.d.ts
 type Config$1 = NextclawCore.Config;
@@ -10,30 +9,6 @@ type StartServiceOptions = {
   open: boolean;
   startupTimeoutMs?: number;
 };
-type ManagedServiceSnapshot = {
-  pid: number;
-  uiUrl: string;
-  apiUrl: string;
-  uiHost: string;
-  uiPort: number;
-  logPath: string;
-};
-declare function resolveManagedServiceReadySnapshot(params: {
-  snapshot: ManagedServiceSnapshot;
-  readLocalUiRuntimeState?: typeof localUiRuntimeStore.read;
-  isProcessRunningFn?: (pid: number) => boolean;
-}): ManagedServiceSnapshot;
-declare function resolveManagedServiceUiBinding(state: ManagedServiceState): {
-  host: string;
-  port: number;
-};
-declare function resolveSessionRouteCandidate(params: {
-  session: unknown;
-  normalizeOptionalString: (value: unknown) => string | undefined;
-}): {
-  key: string;
-  updatedAt: number;
-} | null;
 declare function spawnManagedService(params: {
   appName: string;
   config: NextclawCore.Config;
@@ -109,6 +84,7 @@ declare class ManagedServiceCommandService {
   private readonly deps;
   private readonly loggingRuntime;
   private readonly serviceLogger;
+  private readonly startupLogger;
   constructor(deps: {
     startGateway: (options: {
       uiOverrides: Partial<Config$1["ui"]>;
@@ -144,4 +120,4 @@ declare class ManagedServiceCommandService {
   private printStartupFailureDiagnostics;
 }
 //#endregion
-export { ManagedServiceCommandService, ManagedServiceSnapshot, StartServiceOptions, reportManagedServiceStart, resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate, spawnManagedService, waitForManagedServiceReadiness };
+export { ManagedServiceCommandService, StartServiceOptions, reportManagedServiceStart, resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate, spawnManagedService, waitForManagedServiceReadiness };

package/dist/shared/services/runtime/service-managed-startup.service.js

@@ -1,71 +1,19 @@
+import { createTopLevelNextclawCommandEnv } from "../../utils/top-level-nextclaw-command-env.utils.js";
 import { isProcessRunning, openBrowser, resolveServiceLogPath, resolveUiApiBase, resolveUiConfig, waitForExit } from "../../utils/cli.utils.js";
-import { localUiRuntimeStore } from "../../stores/local-ui-runtime.store.js";
 import { managedServiceStateStore } from "../../stores/managed-service-state.store.js";
-import { probeHealthEndpoint } from "../../utils/service-port-probe.utils.js";
+import { localUiRuntimeStore } from "../../stores/local-ui-runtime.store.js";
 import { resolveCliSubcommandLaunch } from "../../utils/marketplace/cli-subcommand-launch.utils.js";
-import { createTopLevelNextclawCommandEnv } from "../../utils/top-level-nextclaw-command-env.utils.js";
 import { writeInitialManagedServiceState, writeReadyManagedServiceState } from "./utils/service-remote-runtime.utils.js";
-import { spawn } from "node:child_process";
-import { dirname } from "node:path";
+import { resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate } from "./utils/managed-service-routing.utils.js";
+import { probeHealthEndpoint } from "../../utils/service-port-probe.utils.js";
 import * as NextclawCore from "@nextclaw/core";
 import { FileLogSink } from "@nextclaw/core";
 import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { spawn } from "node:child_process";
 //#region src/shared/services/runtime/service-managed-startup.service.ts
 const { APP_NAME: APP_NAME$1, loadConfig: loadConfig$1 } = NextclawCore;
-function resolveManagedServiceReadySnapshot(params) {
-	const { snapshot, readLocalUiRuntimeState, isProcessRunningFn: providedIsProcessRunningFn } = params;
-	const localUiRuntimeState = (readLocalUiRuntimeState ?? localUiRuntimeStore.read)();
-	const isProcessRunningFn = providedIsProcessRunningFn ?? isProcessRunning;
-	if (!localUiRuntimeState || typeof localUiRuntimeState.pid !== "number" || !Number.isFinite(localUiRuntimeState.pid) || localUiRuntimeState.uiPort !== snapshot.uiPort || !isProcessRunningFn(localUiRuntimeState.pid)) return snapshot;
-	return {
-		...snapshot,
-		pid: localUiRuntimeState.pid,
-		uiUrl: localUiRuntimeState.uiUrl,
-		apiUrl: localUiRuntimeState.apiUrl,
-		uiHost: localUiRuntimeState.uiHost ?? snapshot.uiHost,
-		uiPort: localUiRuntimeState.uiPort ?? snapshot.uiPort
-	};
-}
-function toObjectRecord(value) {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-	return value;
-}
-function hasSessionRoutingMetadata(params) {
-	const context = toObjectRecord(params.metadata.last_delivery_context) ?? {};
-	const hasPrimaryRoute = Boolean(params.normalizeOptionalString(context.channel)) && Boolean(params.normalizeOptionalString(context.chatId));
-	const hasFallbackRoute = Boolean(params.normalizeOptionalString(params.metadata.last_channel)) && Boolean(params.normalizeOptionalString(params.metadata.last_to));
-	return hasPrimaryRoute || hasFallbackRoute;
-}
-function resolveManagedServiceUiBinding(state) {
-	try {
-		const parsed = new URL(state.uiUrl);
-		const parsedPort = Number(parsed.port || 80);
-		return {
-			host: state.uiHost ?? parsed.hostname,
-			port: Number.isFinite(parsedPort) ? parsedPort : state.uiPort ?? 55667
-		};
-	} catch {
-		return {
-			host: state.uiHost ?? "127.0.0.1",
-			port: state.uiPort ?? 55667
-		};
-	}
-}
-function resolveSessionRouteCandidate(params) {
-	const sessionRecord = toObjectRecord(params.session);
-	const key = params.normalizeOptionalString(sessionRecord?.key);
-	if (!key || key.startsWith("cli:")) return null;
-	if (!hasSessionRoutingMetadata({
-		metadata: toObjectRecord(sessionRecord?.metadata) ?? {},
-		normalizeOptionalString: params.normalizeOptionalString
-	})) return null;
-	const updatedAtRaw = params.normalizeOptionalString(sessionRecord?.updated_at);
-	const updatedAt = updatedAtRaw ? Date.parse(updatedAtRaw) : NaN;
-	return {
-		key,
-		updatedAt: Number.isFinite(updatedAt) ? updatedAt : 0
-	};
-}
+const serviceStartupLogger = NextclawCore.getAppLogger("service.startup");
 function spawnManagedService(params) {
 	const { appName, config, uiConfig, uiUrl, apiUrl, healthUrl, startupTimeoutMs, resolveStartupTimeoutMs, appendStartupStage, printStartupFailureDiagnostics, resolveServiceLogPath } = params;
 	const logPath = resolveServiceLogPath();
@@ -119,6 +67,22 @@ function spawnManagedService(params) {
 		readinessTimeoutMs,
 		snapshot
 	});
+	serviceStartupLogger.info("runtime.process.started", {
+		runtimeKind: "managed-service",
+		childPid: child.pid,
+		uiUrl,
+		apiUrl,
+		uiHost: uiConfig.host,
+		uiPort: uiConfig.port,
+		entrypoint: `${cliLaunch.command} ${childArgs.join(" ")}`
+	});
+	serviceStartupLogger.info("service_state.written", {
+		runtimeKind: "managed-service",
+		childPid: child.pid,
+		statePath: managedServiceStateStore.path,
+		uiUrl,
+		apiUrl
+	});
 	return {
 		child,
 		logPath,
@@ -162,6 +126,7 @@ async function reportManagedServiceStart(params) {
 var ManagedServiceCommandService = class {
 	loggingRuntime = NextclawCore.getLoggingRuntime();
 	serviceLogger = this.loggingRuntime.getLogger("service");
+	startupLogger = this.serviceLogger.child("startup");
 	constructor(deps) {
 		this.deps = deps;
 	}
@@ -237,6 +202,13 @@ var ManagedServiceCommandService = class {
 			return;
 		}
 		console.log(`Stopping ${APP_NAME$1} (PID ${state.pid})...`);
+		this.serviceLogger.info("runtime.process.stop_requested", {
+			runtimeKind: "managed-service",
+			pid: state.pid,
+			reason: "nextclaw-stop-command",
+			uiUrl: state.uiUrl,
+			apiUrl: state.apiUrl
+		});
 		try {
 			process.kill(state.pid, "SIGTERM");
 		} catch (error) {
@@ -244,6 +216,14 @@ var ManagedServiceCommandService = class {
 			return;
 		}
 		if (!await waitForExit(state.pid, 3e3)) {
+			this.serviceLogger.warn("runtime.process.stop_requested", {
+				runtimeKind: "managed-service",
+				pid: state.pid,
+				reason: "nextclaw-stop-command-force",
+				signal: "SIGKILL",
+				uiUrl: state.uiUrl,
+				apiUrl: state.apiUrl
+			});
 			try {
 				process.kill(state.pid, "SIGKILL");
 			} catch (error) {
@@ -254,6 +234,13 @@ var ManagedServiceCommandService = class {
 		}
 		managedServiceStateStore.clear();
 		localUiRuntimeStore.clearIfOwnedByProcess(state.pid);
+		this.serviceLogger.info("service_state.cleared", {
+			runtimeKind: "managed-service",
+			pid: state.pid,
+			statePath: managedServiceStateStore.path,
+			uiUrl: state.uiUrl,
+			apiUrl: state.apiUrl
+		});
 		console.log(`✓ ${APP_NAME$1} stopped`);
 	};
 	handleExistingManagedService = async (params) => {
@@ -348,13 +335,22 @@ var ManagedServiceCommandService = class {
 		}
 		startup.child.unref();
 		const readySnapshot = resolveManagedServiceReadySnapshot({ snapshot: startup.snapshot });
+		const state = writeReadyManagedServiceState({
+			readinessTimeoutMs: startup.readinessTimeoutMs,
+			readiness,
+			snapshot: readySnapshot
+		});
+		this.startupLogger.info("runtime.process.ready", {
+			runtimeKind: "managed-service",
+			pid: state.pid,
+			uiUrl: state.uiUrl,
+			apiUrl: state.apiUrl,
+			startupState: state.startupState,
+			readinessTimeoutMs: startup.readinessTimeoutMs
+		});
 		await reportManagedServiceStart({
 			appName: APP_NAME$1,
-			state: writeReadyManagedServiceState({
-				readinessTimeoutMs: startup.readinessTimeoutMs,
-				readiness,
-				snapshot: readySnapshot
-			}),
+			state,
 			uiConfig,
 			uiUrl,
 			apiUrl,
@@ -401,7 +397,7 @@ var ManagedServiceCommandService = class {
 	};
 	appendStartupStage = (logPath, message) => {
 		try {
-			this.serviceLogger.child("startup").info(message, { logPath });
+			this.startupLogger.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}`);

package/dist/shared/services/runtime/utils/managed-service-routing.utils.d.ts

@@ -0,0 +1,30 @@
+import { ManagedServiceState } from "../../../stores/managed-service-state.store.js";
+import { localUiRuntimeStore } from "../../../stores/local-ui-runtime.store.js";
+
+//#region src/shared/services/runtime/utils/managed-service-routing.utils.d.ts
+type ManagedServiceSnapshot = {
+  pid: number;
+  uiUrl: string;
+  apiUrl: string;
+  uiHost: string;
+  uiPort: number;
+  logPath: string;
+};
+declare function resolveManagedServiceReadySnapshot(params: {
+  snapshot: ManagedServiceSnapshot;
+  readLocalUiRuntimeState?: typeof localUiRuntimeStore.read;
+  isProcessRunningFn?: (pid: number) => boolean;
+}): ManagedServiceSnapshot;
+declare function resolveManagedServiceUiBinding(state: ManagedServiceState): {
+  host: string;
+  port: number;
+};
+declare function resolveSessionRouteCandidate(params: {
+  session: unknown;
+  normalizeOptionalString: (value: unknown) => string | undefined;
+}): {
+  key: string;
+  updatedAt: number;
+} | null;
+//#endregion
+export { ManagedServiceSnapshot, resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate };

package/dist/shared/services/runtime/utils/managed-service-routing.utils.js

@@ -0,0 +1,62 @@
+import { isProcessRunning } from "../../../utils/cli.utils.js";
+import "../../../stores/managed-service-state.store.js";
+import { localUiRuntimeStore } from "../../../stores/local-ui-runtime.store.js";
+//#region src/shared/services/runtime/utils/managed-service-routing.utils.ts
+function resolveManagedServiceReadySnapshot(params) {
+	const { snapshot, readLocalUiRuntimeState, isProcessRunningFn: providedIsProcessRunningFn } = params;
+	const localUiRuntimeState = (readLocalUiRuntimeState ?? localUiRuntimeStore.read)();
+	const isProcessRunningFn = providedIsProcessRunningFn ?? isProcessRunning;
+	if (!localUiRuntimeState || typeof localUiRuntimeState.pid !== "number" || !Number.isFinite(localUiRuntimeState.pid) || localUiRuntimeState.uiPort !== snapshot.uiPort || !isProcessRunningFn(localUiRuntimeState.pid)) return snapshot;
+	return {
+		...snapshot,
+		pid: localUiRuntimeState.pid,
+		uiUrl: localUiRuntimeState.uiUrl,
+		apiUrl: localUiRuntimeState.apiUrl,
+		uiHost: localUiRuntimeState.uiHost ?? snapshot.uiHost,
+		uiPort: localUiRuntimeState.uiPort ?? snapshot.uiPort
+	};
+}
+function toObjectRecord(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	return value;
+}
+function hasSessionRoutingMetadata(params) {
+	const { metadata, normalizeOptionalString } = params;
+	const context = toObjectRecord(metadata.last_delivery_context) ?? {};
+	const hasPrimaryRoute = Boolean(normalizeOptionalString(context.channel)) && Boolean(normalizeOptionalString(context.chatId));
+	const hasFallbackRoute = Boolean(normalizeOptionalString(metadata.last_channel)) && Boolean(normalizeOptionalString(metadata.last_to));
+	return hasPrimaryRoute || hasFallbackRoute;
+}
+function resolveManagedServiceUiBinding(state) {
+	try {
+		const parsed = new URL(state.uiUrl);
+		const parsedPort = Number(parsed.port || 80);
+		return {
+			host: state.uiHost ?? parsed.hostname,
+			port: Number.isFinite(parsedPort) ? parsedPort : state.uiPort ?? 55667
+		};
+	} catch {
+		return {
+			host: state.uiHost ?? "127.0.0.1",
+			port: state.uiPort ?? 55667
+		};
+	}
+}
+function resolveSessionRouteCandidate(params) {
+	const { session, normalizeOptionalString } = params;
+	const sessionRecord = toObjectRecord(session);
+	const key = normalizeOptionalString(sessionRecord?.key);
+	if (!key || key.startsWith("cli:")) return null;
+	if (!hasSessionRoutingMetadata({
+		metadata: toObjectRecord(sessionRecord?.metadata) ?? {},
+		normalizeOptionalString
+	})) return null;
+	const updatedAtRaw = normalizeOptionalString(sessionRecord?.updated_at);
+	const updatedAt = updatedAtRaw ? Date.parse(updatedAtRaw) : NaN;
+	return {
+		key,
+		updatedAt: Number.isFinite(updatedAt) ? updatedAt : 0
+	};
+}
+//#endregion
+export { resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate };

package/dist/shared/services/runtime/utils/service-remote-runtime.utils.js

@@ -1,10 +1,10 @@
 import { isProcessRunning, resolveUiApiBase } from "../../../utils/cli.utils.js";
 import { managedServiceStateStore } from "../../../stores/managed-service-state.store.js";
 import { buildNextclawConfiguredRemoteState, createNextclawRemoteConnector, createNextclawRemoteStatusStore } from "../../../../commands/remote/utils/remote-runtime-support.utils.js";
-import { dirname, resolve } from "node:path";
 import { getDataDir } from "@nextclaw/core";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { RemoteServiceModule } from "@nextclaw/remote";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 //#region src/shared/services/runtime/utils/service-remote-runtime.utils.ts
 function resolveRemoteOwnershipLockPath() {
 	return resolve(getDataDir(), "run", "remote-owner.lock.json");

package/dist/shared/services/session/service-deferred-ncp-agent.service.d.ts

@@ -1,5 +1,5 @@
-import { UiNcpAgent } from "@nextclaw/server";
 import { AgentRuntimeHandle } from "@nextclaw/kernel";
+import { UiNcpAgent } from "@nextclaw/server";
 
 //#region src/shared/services/session/service-deferred-ncp-agent.service.d.ts
 type DeferredUiNcpAgentController = {

package/dist/shared/services/ui/companion-runtime.service.d.ts

@@ -9,6 +9,7 @@ declare class CompanionRuntimeService {
   constructor(runtimeStore?: CompanionRuntimeStore, uiDiscoveryService?: LocalUiDiscoveryService);
   readonly getRunningState: () => CompanionRuntimeState | null;
   readonly resolveDiscoveredBaseUrl: () => string | null;
+  readonly isAvailable: () => boolean;
   readonly applyConfig: (config: Config) => Promise<void>;
   readonly updateEnabled: (enabled: boolean, options?: {
     baseUrl?: string;
@@ -25,6 +26,7 @@ declare class CompanionRuntimeService {
   readonly printStarted: (state: CompanionRuntimeState) => void;
   readonly printStopped: (stopped: boolean) => void;
   private readonly killProcess;
+  private readonly ensureStartedIfAvailable;
   private readonly resolveLaunchSpec;
   private readonly waitForRunningState;
 }