@nextclaw/service 0.1.14 → 0.1.15

package/dist/cli/commands/agent/agent-runtime.utils.js

@@ -15,7 +15,7 @@ async function listAvailableAgentRuntimes(params) {
 		createRuntime: createUnusedRuntime
 	});
 	runtimeSourceByKind.set(DEFAULT_AGENT_RUNTIME_ENTRY_ID, { source: "builtin" });
-	for (const provider of new BuiltinNarpRuntimeProviderService(() => config).createProviders()) runtimeRegistry.register(provider);
+	for (const provider of new BuiltinNarpRuntimeProviderService({ loadConfig: () => config }).createProviders()) runtimeRegistry.register(provider);
 	runtimeSourceByKind.set("narp-http", { source: "builtin" });
 	runtimeSourceByKind.set("narp-stdio", { source: "builtin" });
 	const resolvedEntries = resolveAgentRuntimeEntries({ config });

package/dist/cli/commands/agent/cli-agent-runner.utils.js

@@ -30,7 +30,7 @@ function createCliHistoryInterface() {
 	return rl;
 }
 async function runCliInteractiveLoop(params) {
-	const { agentRunRequests, config, logo, metadata, sessionKey, sessionManager } = params;
+	const { agentRunRequests, config, logo, metadata, sessionKey } = params;
 	console.log(`${logo} Interactive mode (type exit or Ctrl+C to quit)\n`);
 	const rl = createCliHistoryInterface();
 	let running = true;
@@ -44,7 +44,6 @@ async function runCliInteractiveLoop(params) {
 		}
 		printAgentResponse(await dispatchPromptOverNcp({
 			config,
-			sessionManager,
 			agentRunRequests,
 			sessionKey,
 			content: trimmed,
@@ -54,7 +53,6 @@ async function runCliInteractiveLoop(params) {
 }
 async function runCliAgentCommand(params) {
 	const { config, kernel, logo, opts } = params;
-	const sessionManager = kernel.sessions;
 	await kernel.extensions.load({ config });
 	await kernel.start();
 	try {
@@ -63,7 +61,6 @@ async function runCliAgentCommand(params) {
 		if (opts.message) {
 			printAgentResponse(await dispatchPromptOverNcp({
 				config,
-				sessionManager,
 				agentRunRequests: kernel.agentRunRequestManager,
 				sessionKey,
 				content: opts.message,
@@ -74,7 +71,6 @@ async function runCliAgentCommand(params) {
 		await runCliInteractiveLoop({
 			logo,
 			config,
-			sessionManager,
 			agentRunRequests: kernel.agentRunRequestManager,
 			sessionKey,
 			metadata: sharedMetadata

package/dist/cli/commands/diagnostics/services/diagnostics-commands.service.d.ts

@@ -3,6 +3,7 @@ import { DoctorCommandOptions, StatusCommandOptions } from "../../../../shared/t
 //#region src/cli/commands/diagnostics/services/diagnostics-commands.service.d.ts
 declare class DiagnosticsCommands {
   private deps;
+  private readonly managedServiceSupervisor;
   constructor(deps: {
     logo: string;
   });
@@ -12,6 +13,7 @@ declare class DiagnosticsCommands {
   private readonly buildDoctorChecks;
   private readonly resolveDoctorExitCode;
   private readonly collectRuntimeStatus;
+  private readonly resolveManagedServiceStatus;
   private readonly probeApiHealth;
   private readonly listProviderStatuses;
   private readonly collectRuntimeIssues;

package/dist/cli/commands/diagnostics/services/diagnostics-commands.service.js

@@ -2,6 +2,7 @@ import { isProcessRunning, resolveUiApiBase, resolveUiConfig } from "../../../..
 import { managedServiceStateStore } from "../../../../shared/stores/managed-service-state.store.js";
 import { resolveNextclawRemoteStatusSnapshot } from "../../../../commands/remote/utils/remote-runtime-support.utils.js";
 import "../../../../commands/remote/index.js";
+import { ManagedServiceSupervisor } from "../../../../shared/services/runtime/managed-service-supervisor.service.js";
 import { printDoctorReport, printStatusReport } from "../utils/diagnostics-render.utils.js";
 import { APP_NAME, getConfigPath, getWorkspacePath, hasSecretRef, loadConfig, resolveAppLogPath } from "@nextclaw/core";
 import { existsSync, readFileSync } from "node:fs";
@@ -9,6 +10,7 @@ import { createServer } from "node:net";
 import { listBuiltinProviders } from "@nextclaw/runtime";
 //#region src/cli/commands/diagnostics/services/diagnostics-commands.service.ts
 var DiagnosticsCommands = class {
+	managedServiceSupervisor = new ManagedServiceSupervisor();
 	constructor(deps) {
 		this.deps = deps;
 	}
@@ -87,8 +89,8 @@ var DiagnosticsCommands = class {
 			},
 			{
 				name: "service-state",
-				status: report.process.staleState ? "fail" : report.process.running ? "pass" : "warn",
-				detail: report.process.running ? `PID ${report.process.pid}` : report.process.staleState ? "state exists but process is not running" : "service not running"
+				status: report.process.staleState ? "fail" : report.process.running ? report.process.lease?.missing ? "warn" : "pass" : "warn",
+				detail: report.process.running ? `PID ${report.process.pid}${report.process.lease?.missing ? " (missing lease heartbeat)" : ""}` : report.process.staleState ? `state is stale (${report.process.staleReason ?? "unknown"})` : "service not running"
 			},
 			{
 				name: "service-health",
@@ -117,16 +119,10 @@ var DiagnosticsCommands = class {
 		const config = loadConfig();
 		const workspacePath = getWorkspacePath(config.agents.defaults.workspace);
 		const serviceStatePath = managedServiceStateStore.path;
-		const fixActions = [];
-		let serviceState = managedServiceStateStore.read();
-		if (params.fix && serviceState && !isProcessRunning(serviceState.pid)) {
-			managedServiceStateStore.clear();
-			fixActions.push("Cleared stale service state file.");
-			serviceState = managedServiceStateStore.read();
-		}
+		const { fixActions, liveness, serviceState } = this.resolveManagedServiceStatus({ fix: params.fix });
 		const managedByState = Boolean(serviceState);
-		const running = Boolean(serviceState && isProcessRunning(serviceState.pid));
-		const staleState = Boolean(serviceState && !running);
+		const running = Boolean(serviceState && liveness.running);
+		const staleState = Boolean(serviceState && liveness.staleState);
 		const configuredUi = resolveUiConfig(config, {
 			enabled: true,
 			host: config.ui.host,
@@ -176,8 +172,15 @@ var DiagnosticsCommands = class {
 				pid: serviceState?.pid ?? null,
 				running,
 				staleState,
+				staleReason: liveness.staleReason,
 				orphanSuspected,
-				startedAt: serviceState?.startedAt ?? null
+				startedAt: serviceState?.startedAt ?? null,
+				lease: serviceState ? {
+					heartbeatAt: liveness.lastHeartbeatAt,
+					expired: liveness.leaseExpired,
+					missing: liveness.leaseMissing
+				} : null,
+				lastExit: serviceState?.lastExit ?? null
 			},
 			endpoints: {
 				uiUrl: managedUiUrl,
@@ -197,6 +200,22 @@ var DiagnosticsCommands = class {
 			exitCode: 0
 		};
 	};
+	resolveManagedServiceStatus = (params) => {
+		const fixActions = [];
+		let serviceState = managedServiceStateStore.read();
+		let liveness = this.managedServiceSupervisor.resolveStateLiveness(serviceState);
+		if (params.fix && serviceState && liveness.staleState && !liveness.processExists) {
+			managedServiceStateStore.clear();
+			fixActions.push("Cleared stale service state file.");
+			serviceState = managedServiceStateStore.read();
+			liveness = this.managedServiceSupervisor.resolveStateLiveness(serviceState);
+		} else if (params.fix && serviceState && liveness.staleState && liveness.processExists) fixActions.push("Skipped clearing stale service state because the recorded PID still exists.");
+		return {
+			fixActions,
+			liveness,
+			serviceState
+		};
+	};
 	probeApiHealth = async (url, timeoutMs = 1500) => {
 		const controller = new AbortController();
 		const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -266,13 +285,18 @@ var DiagnosticsCommands = class {
 			recommendations.push(`Run ${APP_NAME} init to create workspace templates.`);
 		}
 		if (staleState) {
-			issues.push("Service state is stale (state exists but process is not running).");
-			recommendations.push(`Run ${APP_NAME} status --fix to clean stale state.`);
+			const staleDetail = serviceState?.lastExit ? ` Last exit: ${serviceState.lastExit.reason}${serviceState.lastExit.signal ? ` (${serviceState.lastExit.signal})` : ""} at ${serviceState.lastExit.exitedAt}.` : "";
+			issues.push(`Service state is stale (${params.serviceState ? "state no longer represents a live lease" : "state missing"}).${staleDetail}`);
+			recommendations.push(params.serviceState && isProcessRunning(params.serviceState.pid) ? `Run ${APP_NAME} restart to replace the stale leased process.` : `Run ${APP_NAME} status --fix to clean stale state.`);
 		}
 		if (running && managedHealth.state !== "ok") {
 			issues.push(`Managed service health check failed: ${managedHealth.detail}`);
 			recommendations.push(`Check logs at ${serviceState?.logPath ?? resolveAppLogPath("service")}.`);
 		}
+		if (running && serviceState && !serviceState.lease) {
+			issues.push("Managed service state is missing a lease heartbeat.");
+			recommendations.push(`Run ${APP_NAME} restart to refresh the managed service state contract.`);
+		}
 		if (running && serviceState?.startupState === "degraded" && managedHealth.state !== "ok") {
 			const startupHint = serviceState.startupLastProbeError ? ` (${serviceState.startupLastProbeError})` : "";
 			issues.push(`Service is in degraded startup state${startupHint}.`);

package/dist/cli/commands/diagnostics/utils/diagnostics-render.utils.js

@@ -23,6 +23,12 @@ function printProcessSection(report) {
 	console.log(`Process: ${processLabel}`);
 	console.log(`State file: ${report.serviceStatePath} ${report.serviceStateExists ? "✓" : "✗"}`);
 	if (report.process.startedAt) console.log(`Started: ${report.process.startedAt}`);
+	if (report.process.lease?.heartbeatAt) console.log(`Last heartbeat: ${report.process.lease.heartbeatAt}${report.process.lease.expired ? " (expired)" : ""}`);
+	if (report.process.staleReason) console.log(`Stale reason: ${report.process.staleReason}`);
+	if (report.process.lastExit) {
+		const exit = report.process.lastExit;
+		console.log(`Last exit: ${exit.reason}${exit.signal ? ` ${exit.signal}` : ""}${typeof exit.code === "number" ? ` code=${exit.code}` : ""} at ${exit.exitedAt}`);
+	}
 	console.log(`Managed health: ${report.health.managed.state} (${report.health.managed.detail})`);
 	if (!report.process.running) console.log(`Configured health: ${report.health.configured.state} (${report.health.configured.detail})`);
 }

package/dist/commands/plugin/plugin-command.utils.d.ts

@@ -1,11 +1,11 @@
 import { PluginRegistry } from "@nextclaw/openclaw-compat";
 
 //#region src/commands/plugin/plugin-command.utils.d.ts
-declare const RESERVED_PROVIDER_IDS: string[];
+declare const RESERVED_PROVIDER_IDS: any;
 declare function buildReservedPluginLoadOptions(): {
   reservedToolNames: ("read_file" | "write_file" | "edit_file" | "list_dir" | "exec" | "web_search" | "web_fetch" | "message" | "spawn" | "sessions_list" | "sessions_history" | "memory_search" | "memory_get" | "subagents" | "gateway" | "cron")[];
   reservedChannelIds: string[];
-  reservedProviderIds: string[];
+  reservedProviderIds: any;
 };
 declare function appendPluginCapabilityLines(lines: string[], plugin: PluginRegistry["plugins"][number]): void;
 //#endregion

package/dist/commands/remote/services/remote-service-control.service.js

@@ -1,66 +1,84 @@
-import { isProcessRunning, resolveUiApiBase, resolveUiConfig } from "../../../shared/utils/cli.utils.js";
+import { resolveUiApiBase, resolveUiConfig } from "../../../shared/utils/cli.utils.js";
 import { managedServiceStateStore } from "../../../shared/stores/managed-service-state.store.js";
+import { ManagedServiceSupervisor } from "../../../shared/services/runtime/managed-service-supervisor.service.js";
 import { getConfigPath, loadConfig } from "@nextclaw/core";
 import { spawn } from "node:child_process";
 //#region src/commands/remote/services/remote-service-control.service.ts
 const FORCED_PUBLIC_UI_HOST = "0.0.0.0";
-function resolveRemoteServiceView(currentUi) {
-	if (currentUi) return {
-		running: true,
-		currentProcess: true,
-		pid: process.pid,
-		uiUrl: resolveUiApiBase(currentUi.host, currentUi.port),
-		uiPort: currentUi.port
+var RemoteServiceControlService = class {
+	managedServiceSupervisor = new ManagedServiceSupervisor();
+	resolveView = (currentUi) => {
+		if (currentUi) return {
+			running: true,
+			currentProcess: true,
+			pid: process.pid,
+			uiUrl: resolveUiApiBase(currentUi.host, currentUi.port),
+			uiPort: currentUi.port
+		};
+		const serviceState = managedServiceStateStore.read();
+		const liveness = this.managedServiceSupervisor.resolveStateLiveness(serviceState);
+		const serviceRunning = Boolean(serviceState && liveness.running);
+		return {
+			running: serviceRunning,
+			currentProcess: Boolean(serviceRunning && serviceState?.pid === process.pid),
+			...serviceState?.pid ? { pid: serviceState.pid } : {},
+			...serviceState?.uiUrl ? { uiUrl: serviceState.uiUrl } : {},
+			...typeof serviceState?.uiPort === "number" ? { uiPort: serviceState.uiPort } : {}
+		};
 	};
-	const serviceState = managedServiceStateStore.read();
-	const serviceRunning = Boolean(serviceState && isProcessRunning(serviceState.pid));
-	return {
-		running: serviceRunning,
-		currentProcess: Boolean(serviceRunning && serviceState?.pid === process.pid),
-		...serviceState?.pid ? { pid: serviceState.pid } : {},
-		...serviceState?.uiUrl ? { uiUrl: serviceState.uiUrl } : {},
-		...typeof serviceState?.uiPort === "number" ? { uiPort: serviceState.uiPort } : {}
+	control = async (action, deps) => {
+		if (deps.remoteRuntimeController) return this.controlCurrentProcessRuntime(action, deps.remoteRuntimeController);
+		return this.controlManagedService(action, deps);
 	};
-}
-async function controlRemoteService(action, deps) {
-	if (deps.remoteRuntimeController) return controlCurrentProcessRuntime(action, deps.remoteRuntimeController);
-	return controlManagedService(action, deps);
-}
-async function controlCurrentProcessRuntime(action, controller) {
-	if (action === "start") {
-		await controller.start();
+	controlCurrentProcessRuntime = async (action, controller) => {
+		if (action === "start") {
+			await controller.start();
+			return {
+				accepted: true,
+				action,
+				message: "Remote runtime started."
+			};
+		}
+		if (action === "stop") {
+			await controller.stop();
+			return {
+				accepted: true,
+				action,
+				message: "Remote runtime stopped."
+			};
+		}
+		await controller.restart();
 		return {
 			accepted: true,
 			action,
-			message: "Remote runtime started."
+			message: "Remote runtime restarted."
 		};
-	}
-	if (action === "stop") {
-		await controller.stop();
+	};
+	controlManagedService = async (action, deps) => {
+		const serviceState = this.resolveManagedServiceControlState();
+		const uiOverrides = this.resolveManagedUiOverrides();
+		if (action === "start") return this.startManagedService(action, deps, serviceState, uiOverrides);
+		if (!serviceState.running) return this.controlStoppedManagedService(action, deps, serviceState, uiOverrides);
+		if (serviceState.currentProcess) return this.controlCurrentManagedProcess(action, deps, uiOverrides);
+		return this.controlExternalManagedProcess(action, deps, uiOverrides);
+	};
+	resolveManagedServiceControlState = () => {
+		const state = managedServiceStateStore.read();
+		const liveness = this.managedServiceSupervisor.resolveStateLiveness(state);
+		const running = Boolean(state && liveness.running);
 		return {
-			accepted: true,
-			action,
-			message: "Remote runtime stopped."
+			currentProcess: Boolean(running && state?.pid === process.pid),
+			recordedProcessExists: Boolean(state && liveness.processExists),
+			running
 		};
-	}
-	await controller.restart();
-	return {
-		accepted: true,
-		action,
-		message: "Remote runtime restarted."
 	};
-}
-async function controlManagedService(action, deps) {
-	const state = managedServiceStateStore.read();
-	const running = Boolean(state && isProcessRunning(state.pid));
-	const currentProcess = Boolean(running && state?.pid === process.pid);
-	const uiOverrides = resolveManagedUiOverrides();
-	if (action === "start") {
-		if (running) return {
+	startManagedService = async (action, deps, serviceState, uiOverrides) => {
+		if (serviceState.running) return {
 			accepted: true,
 			action,
-			message: currentProcess ? "Managed service is already running for this UI." : "Managed service is already running."
+			message: serviceState.currentProcess ? "Managed service is already running for this UI." : "Managed service is already running."
 		};
+		if (serviceState.recordedProcessExists) return this.controlStaleManagedServiceProcess(action, deps, uiOverrides);
 		await deps.serviceCommands.startService({
 			uiOverrides,
 			open: false
@@ -70,8 +88,9 @@ async function controlManagedService(action, deps) {
 			action,
 			message: "Managed service started."
 		};
-	}
-	if (!running) {
+	};
+	controlStoppedManagedService = async (action, deps, serviceState, uiOverrides) => {
+		if (serviceState.recordedProcessExists) return this.controlStaleManagedServiceProcess(action, deps, uiOverrides);
 		if (action === "restart") {
 			await deps.serviceCommands.startService({
 				uiOverrides,
@@ -88,49 +107,87 @@ async function controlManagedService(action, deps) {
 			action,
 			message: "No managed service is currently running."
 		};
-	}
-	if (currentProcess) {
+	};
+	controlStaleManagedServiceProcess = async (action, deps, uiOverrides) => {
+		if (action === "stop") {
+			await deps.serviceCommands.stopService();
+			return {
+				accepted: true,
+				action,
+				message: "Stale managed service process stopped."
+			};
+		}
+		if (action === "restart") {
+			await deps.serviceCommands.stopService();
+			await deps.serviceCommands.startService({
+				uiOverrides,
+				open: false
+			});
+			return {
+				accepted: true,
+				action,
+				message: "Stale managed service process replaced."
+			};
+		}
+		await deps.serviceCommands.stopService();
+		await deps.serviceCommands.startService({
+			uiOverrides,
+			open: false
+		});
+		return {
+			accepted: true,
+			action,
+			message: "Stale managed service process replaced."
+		};
+	};
+	controlCurrentManagedProcess = async (action, deps, uiOverrides) => {
 		if (action === "restart") await deps.requestManagedServiceRestart({ uiPort: uiOverrides.port ?? 55667 });
-		else scheduleManagedSelfStop();
+		else launchManagedSelfControl();
 		return {
 			accepted: true,
 			action,
 			message: action === "restart" ? "Restart scheduled. This page may disconnect for a few seconds." : "Stop scheduled. This page will disconnect shortly."
 		};
-	}
-	if (action === "stop") {
+	};
+	controlExternalManagedProcess = async (action, deps, uiOverrides) => {
+		if (action === "stop") {
+			await deps.serviceCommands.stopService();
+			return {
+				accepted: true,
+				action,
+				message: "Managed service stopped."
+			};
+		}
 		await deps.serviceCommands.stopService();
+		await deps.serviceCommands.startService({
+			uiOverrides,
+			open: false
+		});
 		return {
 			accepted: true,
 			action,
-			message: "Managed service stopped."
+			message: "Managed service restarted."
 		};
-	}
-	await deps.serviceCommands.stopService();
-	await deps.serviceCommands.startService({
-		uiOverrides,
-		open: false
-	});
-	return {
-		accepted: true,
-		action,
-		message: "Managed service restarted."
 	};
-}
-function resolveManagedUiOverrides() {
-	return {
-		enabled: true,
-		host: FORCED_PUBLIC_UI_HOST,
-		open: false,
-		port: resolveUiConfig(loadConfig(getConfigPath()), {
+	resolveManagedUiOverrides = () => {
+		return {
 			enabled: true,
 			host: FORCED_PUBLIC_UI_HOST,
-			open: false
-		}).port
+			open: false,
+			port: resolveUiConfig(loadConfig(getConfigPath()), {
+				enabled: true,
+				host: FORCED_PUBLIC_UI_HOST,
+				open: false
+			}).port
+		};
 	};
+};
+const remoteServiceControlService = new RemoteServiceControlService();
+function resolveRemoteServiceView(currentUi) {
+	return remoteServiceControlService.resolveView(currentUi);
 }
-function scheduleManagedSelfStop() {
-	launchManagedSelfControl();
+async function controlRemoteService(action, deps) {
+	return remoteServiceControlService.control(action, deps);
 }
 function launchManagedSelfControl(params = {}) {
 	const script = [

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

@@ -17,7 +17,6 @@ function installPluginRuntimeBridge(gateway) {
 				await dispatcherOptions.onReplyStart?.();
 				const response = await dispatchPromptOverNcp({
 					config: gateway.configManager.loadConfig(),
-					sessionManager: gateway.sessionManager,
 					agentRunRequests: gateway.kernel.agentRunRequestManager,
 					...request
 				});

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

@@ -0,0 +1,84 @@
+import { ManagedServiceLastExit, ManagedServiceState, ManagedServiceStateStore } from "../../stores/managed-service-state.store.js";
+import { ManagedServiceSnapshot } from "./utils/managed-service-routing.utils.js";
+import * as NextclawCore from "@nextclaw/core";
+import { ChildProcess } from "node:child_process";
+
+//#region src/shared/services/runtime/managed-service-supervisor.service.d.ts
+type Config$1 = NextclawCore.Config;
+type ManagedServiceStartup = {
+  child: ChildProcess;
+  logPath: string;
+  readinessTimeoutMs: number;
+  quickPhaseTimeoutMs: number;
+  extendedPhaseTimeoutMs: number;
+  snapshot: ManagedServiceSnapshot;
+};
+type ManagedServiceLiveness = {
+  processExists: boolean;
+  running: boolean;
+  staleState: boolean;
+  staleReason: "process-not-running" | "lease-expired" | null;
+  leaseExpired: boolean;
+  leaseMissing: boolean;
+  lastHeartbeatAt: string | null;
+};
+type ManagedServiceSupervisorOptions = {
+  stateStore?: ManagedServiceStateStore;
+  now?: () => Date;
+  isProcessRunningFn?: (pid: number) => boolean;
+  heartbeatIntervalMs?: number;
+  leaseTtlMs?: number;
+};
+declare class ManagedServiceSupervisor {
+  private readonly stateStore;
+  private readonly now;
+  private readonly isProcessRunningFn;
+  private readonly heartbeatIntervalMs;
+  private readonly leaseTtlMs;
+  private readonly serviceStartupLogger;
+  private heartbeatTimer;
+  private lifecycleTrackingInstalled;
+  private pendingExit;
+  constructor(options?: ManagedServiceSupervisorOptions);
+  spawnManagedService: (params: {
+    appName: string;
+    config: Config$1;
+    uiConfig: {
+      host: string;
+      port: number;
+    };
+    uiUrl: string;
+    apiUrl: string;
+    healthUrl: string;
+    startupTimeoutMs?: number;
+    resolveStartupTimeoutMs: (overrideTimeoutMs: number | undefined) => number;
+    appendStartupStage: (logPath: string, message: string) => void;
+    printStartupFailureDiagnostics: (params: {
+      uiUrl: string;
+      apiUrl: string;
+      healthUrl: string;
+      logPath: string;
+      lastProbeError: string | null;
+    }) => void;
+    resolveServiceLogPath?: () => string;
+  }) => ManagedServiceStartup | null;
+  writeReadyState: (params: {
+    readinessTimeoutMs: number;
+    readiness: {
+      ready: boolean;
+      lastProbeError: string | null;
+    };
+    snapshot: ManagedServiceSnapshot;
+  }) => ManagedServiceState;
+  installCurrentProcessLifecycleTracking: () => void;
+  startHeartbeatForCurrentProcess: (pid?: number) => void;
+  stopHeartbeatForCurrentProcess: () => void;
+  resolveStateLiveness: (state: ManagedServiceState | null) => ManagedServiceLiveness;
+  private writeHeartbeat;
+  recordCurrentProcessExit: (exit: ManagedServiceLastExit) => void;
+  private stopHeartbeat;
+  private readonly createLease;
+  private resolveLeaseStatus;
+}
+//#endregion
+export { ManagedServiceSupervisor };

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

@@ -0,0 +1,269 @@
+import { createTopLevelNextclawCommandEnv } from "../../utils/top-level-nextclaw-command-env.utils.js";
+import { resolveCliSubcommandLaunch } from "../../utils/marketplace/cli-subcommand-launch.utils.js";
+import { isProcessRunning, resolveServiceLogPath } from "../../utils/cli.utils.js";
+import { managedServiceStateStore } from "../../stores/managed-service-state.store.js";
+import { writeInitialManagedServiceState, writeReadyManagedServiceState } from "./utils/service-remote-runtime.utils.js";
+import * as NextclawCore from "@nextclaw/core";
+import { FileLogSink } from "@nextclaw/core";
+import { mkdirSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { dirname } from "node:path";
+//#region src/shared/services/runtime/managed-service-supervisor.service.ts
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 2e3;
+const DEFAULT_LEASE_TTL_MS = 1e4;
+const SIGNAL_EXIT_CODES = {
+	SIGHUP: 129,
+	SIGINT: 130,
+	SIGTERM: 143
+};
+var ManagedServiceSupervisor = class {
+	stateStore;
+	now;
+	isProcessRunningFn;
+	heartbeatIntervalMs;
+	leaseTtlMs;
+	serviceStartupLogger = NextclawCore.getAppLogger("service.startup");
+	heartbeatTimer = null;
+	lifecycleTrackingInstalled = false;
+	pendingExit = null;
+	constructor(options = {}) {
+		this.stateStore = options.stateStore ?? managedServiceStateStore;
+		this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+		this.isProcessRunningFn = options.isProcessRunningFn ?? isProcessRunning;
+		this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+		this.leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
+	}
+	spawnManagedService = (params) => {
+		const { appName, apiUrl, appendStartupStage, config, healthUrl, printStartupFailureDiagnostics, resolveStartupTimeoutMs, startupTimeoutMs, uiConfig, uiUrl } = params;
+		const logPath = (params.resolveServiceLogPath ?? resolveServiceLogPath)();
+		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);
+		appendStartupStage(logPath, `start requested: ui=${uiConfig.host}:${uiConfig.port}, readinessTimeoutMs=${readinessTimeoutMs}`);
+		console.log(`Starting ${appName} background service (readiness timeout ${Math.ceil(readinessTimeoutMs / 1e3)}s)...`);
+		const cliLaunch = resolveCliSubcommandLaunch({
+			argvEntry: process.argv[1],
+			importMetaUrl: import.meta.url,
+			cliArgs: [
+				"serve",
+				"--ui-port",
+				String(uiConfig.port)
+			],
+			nodePath: process.execPath
+		});
+		const childArgs = [...process.execArgv, ...cliLaunch.args];
+		appendStartupStage(logPath, `spawning background process: ${cliLaunch.command} ${childArgs.join(" ")}`);
+		const child = spawn(cliLaunch.command, childArgs, {
+			env: createTopLevelNextclawCommandEnv(process.env),
+			stdio: "ignore",
+			detached: true,
+			windowsHide: true
+		});
+		appendStartupStage(logPath, `spawned background process pid=${child.pid ?? "unknown"}`);
+		if (!child.pid) {
+			appendStartupStage(logPath, "spawn failed: child pid missing");
+			console.error("Error: Failed to start background service.");
+			printStartupFailureDiagnostics({
+				uiUrl,
+				apiUrl,
+				healthUrl,
+				logPath,
+				lastProbeError: null
+			});
+			return null;
+		}
+		const snapshot = {
+			pid: child.pid,
+			uiUrl,
+			apiUrl,
+			uiHost: uiConfig.host,
+			uiPort: uiConfig.port,
+			logPath
+		};
+		writeInitialManagedServiceState({
+			config,
+			lease: this.createLease(child.pid),
+			readinessTimeoutMs,
+			snapshot
+		});
+		this.serviceStartupLogger.info("runtime.process.started", {
+			runtimeKind: "managed-service",
+			childPid: child.pid,
+			uiUrl,
+			apiUrl,
+			uiHost: uiConfig.host,
+			uiPort: uiConfig.port,
+			entrypoint: `${cliLaunch.command} ${childArgs.join(" ")}`
+		});
+		this.serviceStartupLogger.info("service_state.written", {
+			runtimeKind: "managed-service",
+			childPid: child.pid,
+			statePath: this.stateStore.path,
+			uiUrl,
+			apiUrl
+		});
+		return {
+			child,
+			logPath,
+			readinessTimeoutMs,
+			quickPhaseTimeoutMs,
+			extendedPhaseTimeoutMs,
+			snapshot
+		};
+	};
+	writeReadyState = (params) => {
+		return writeReadyManagedServiceState({
+			...params,
+			lease: this.createLease(params.snapshot.pid)
+		});
+	};
+	installCurrentProcessLifecycleTracking = () => {
+		if (this.lifecycleTrackingInstalled) return;
+		this.lifecycleTrackingInstalled = true;
+		this.startHeartbeatForCurrentProcess();
+		for (const signal of [
+			"SIGHUP",
+			"SIGINT",
+			"SIGTERM"
+		]) process.once(signal, () => {
+			this.pendingExit = {
+				pid: process.pid,
+				reason: "signal",
+				exitedAt: this.now().toISOString(),
+				code: SIGNAL_EXIT_CODES[signal],
+				signal
+			};
+			this.recordCurrentProcessExit(this.pendingExit);
+			this.stopHeartbeat();
+			process.exit(SIGNAL_EXIT_CODES[signal]);
+		});
+		process.once("uncaughtExceptionMonitor", (error) => {
+			this.pendingExit = {
+				pid: process.pid,
+				reason: "uncaughtException",
+				exitedAt: this.now().toISOString(),
+				message: error instanceof Error ? error.message : String(error)
+			};
+		});
+		process.once("exit", (code) => {
+			this.recordCurrentProcessExit({
+				...this.pendingExit ?? {
+					pid: process.pid,
+					reason: "exit",
+					exitedAt: this.now().toISOString()
+				},
+				code
+			});
+			this.stopHeartbeat();
+		});
+	};
+	startHeartbeatForCurrentProcess = (pid = process.pid) => {
+		if (this.heartbeatTimer) return;
+		if (!this.writeHeartbeat(pid)) return;
+		this.heartbeatTimer = setInterval(() => {
+			if (!this.writeHeartbeat(pid)) this.stopHeartbeat();
+		}, this.heartbeatIntervalMs);
+		this.heartbeatTimer.unref();
+	};
+	stopHeartbeatForCurrentProcess = () => {
+		this.stopHeartbeat();
+	};
+	resolveStateLiveness = (state) => {
+		if (!state) return {
+			processExists: false,
+			running: false,
+			staleState: false,
+			staleReason: null,
+			leaseExpired: false,
+			leaseMissing: false,
+			lastHeartbeatAt: null
+		};
+		const processExists = this.isProcessRunningFn(state.pid);
+		const leaseStatus = this.resolveLeaseStatus(state.lease);
+		if (!processExists) return {
+			processExists,
+			running: false,
+			staleState: true,
+			staleReason: "process-not-running",
+			leaseExpired: leaseStatus.expired,
+			leaseMissing: leaseStatus.missing,
+			lastHeartbeatAt: leaseStatus.heartbeatAt
+		};
+		if (leaseStatus.expired) return {
+			processExists,
+			running: false,
+			staleState: true,
+			staleReason: "lease-expired",
+			leaseExpired: true,
+			leaseMissing: false,
+			lastHeartbeatAt: leaseStatus.heartbeatAt
+		};
+		return {
+			processExists,
+			running: true,
+			staleState: false,
+			staleReason: null,
+			leaseExpired: false,
+			leaseMissing: leaseStatus.missing,
+			lastHeartbeatAt: leaseStatus.heartbeatAt
+		};
+	};
+	writeHeartbeat = (pid) => {
+		let wrote = false;
+		this.stateStore.update((state) => {
+			if (state.pid !== pid) return state;
+			wrote = true;
+			const next = {
+				...state,
+				lease: {
+					...state.lease ?? this.createLease(pid),
+					ownerPid: pid,
+					heartbeatAt: this.now().toISOString(),
+					heartbeatIntervalMs: this.heartbeatIntervalMs,
+					ttlMs: this.leaseTtlMs
+				}
+			};
+			delete next.lastExit;
+			return next;
+		});
+		return wrote;
+	};
+	recordCurrentProcessExit = (exit) => {
+		this.stateStore.update((state) => {
+			if (state.pid !== exit.pid) return state;
+			return {
+				...state,
+				lastExit: exit
+			};
+		});
+	};
+	stopHeartbeat = () => {
+		if (!this.heartbeatTimer) return;
+		clearInterval(this.heartbeatTimer);
+		this.heartbeatTimer = null;
+	};
+	createLease = (ownerPid) => ({
+		ownerPid,
+		heartbeatAt: this.now().toISOString(),
+		heartbeatIntervalMs: this.heartbeatIntervalMs,
+		ttlMs: this.leaseTtlMs
+	});
+	resolveLeaseStatus = (lease) => {
+		if (!lease) return {
+			expired: false,
+			missing: true,
+			heartbeatAt: null
+		};
+		const heartbeatAtMs = Date.parse(lease.heartbeatAt);
+		const ttlMs = Number.isFinite(lease.ttlMs) ? lease.ttlMs : this.leaseTtlMs;
+		return {
+			expired: !Number.isFinite(heartbeatAtMs) || heartbeatAtMs + ttlMs < this.now().getTime(),
+			missing: false,
+			heartbeatAt: lease.heartbeatAt
+		};
+	};
+};
+//#endregion
+export { ManagedServiceSupervisor };

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

@@ -11,6 +11,7 @@ declare class RuntimeCommandService {
   private loggingInstalled;
   private processExitLoggingInstalled;
   private readonly runtimeLogger;
+  private readonly managedServiceSupervisor;
   private readonly managedServiceCommandService;
   constructor(deps: {
     requestRestart: (params: RequestRestartParams) => Promise<void>;

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

@@ -1,6 +1,7 @@
 import { resolveCliSubcommandEntry } from "../../utils/marketplace/cli-subcommand-launch.utils.js";
 import { isLoopbackHost, resolvePublicIp, resolveUiStaticDir } from "../../utils/cli.utils.js";
 import { NextclawDistributionService } from "./nextclaw-distribution.service.js";
+import { ManagedServiceSupervisor } from "./managed-service-supervisor.service.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";
@@ -14,6 +15,7 @@ var RuntimeCommandService = class {
 	loggingInstalled = false;
 	processExitLoggingInstalled = false;
 	runtimeLogger = NextclawCore.getAppLogger("service.runtime");
+	managedServiceSupervisor = new ManagedServiceSupervisor();
 	managedServiceCommandService = new ManagedServiceCommandService({
 		startGateway: async (options) => await this.startGateway(options),
 		printPublicUiUrls: async (host, port) => await this.printPublicUiUrls(host, port),
@@ -27,6 +29,7 @@ var RuntimeCommandService = class {
 	startGateway = async (options = {}) => {
 		this.ensureRuntimeLoggingInstalled();
 		this.installProcessExitLogging();
+		this.managedServiceSupervisor.installCurrentProcessLifecycleTracking();
 		this.runtimeLogger.info("runtime.process.started", {
 			runtimeKind: "serve-process",
 			pid: process.pid,

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

@@ -1,6 +1,5 @@
-import { ManagedServiceSnapshot, resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate } from "./utils/managed-service-routing.utils.js";
+import { 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;
@@ -9,35 +8,6 @@ type StartServiceOptions = {
   open: boolean;
   startupTimeoutMs?: number;
 };
-declare function spawnManagedService(params: {
-  appName: string;
-  config: NextclawCore.Config;
-  uiConfig: {
-    host: string;
-    port: number;
-  };
-  uiUrl: string;
-  apiUrl: string;
-  healthUrl: string;
-  startupTimeoutMs?: number;
-  resolveStartupTimeoutMs: (overrideTimeoutMs: number | undefined) => number;
-  appendStartupStage: (logPath: string, message: string) => void;
-  printStartupFailureDiagnostics: (params: {
-    uiUrl: string;
-    apiUrl: string;
-    healthUrl: string;
-    logPath: string;
-    lastProbeError: string | null;
-  }) => void;
-  resolveServiceLogPath: () => string;
-}): {
-  child: ReturnType<typeof spawn>;
-  logPath: string;
-  readinessTimeoutMs: number;
-  quickPhaseTimeoutMs: number;
-  extendedPhaseTimeoutMs: number;
-  snapshot: ManagedServiceSnapshot;
-} | null;
 declare function waitForManagedServiceReadiness(params: {
   appName: string;
   childPid: number;
@@ -85,6 +55,7 @@ declare class ManagedServiceCommandService {
   private readonly loggingRuntime;
   private readonly serviceLogger;
   private readonly startupLogger;
+  private readonly supervisor;
   constructor(deps: {
     startGateway: (options: {
       uiOverrides: Partial<Config$1["ui"]>;
@@ -120,4 +91,4 @@ declare class ManagedServiceCommandService {
   private printStartupFailureDiagnostics;
 }
 //#endregion
-export { ManagedServiceCommandService, StartServiceOptions, reportManagedServiceStart, resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate, spawnManagedService, waitForManagedServiceReadiness };
+export { ManagedServiceCommandService, StartServiceOptions, reportManagedServiceStart, resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate, waitForManagedServiceReadiness };

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

@@ -1,98 +1,12 @@
-import { createTopLevelNextclawCommandEnv } from "../../utils/top-level-nextclaw-command-env.utils.js";
-import { resolveCliSubcommandLaunch } from "../../utils/marketplace/cli-subcommand-launch.utils.js";
 import { isProcessRunning, openBrowser, resolveServiceLogPath, resolveUiApiBase, resolveUiConfig, waitForExit } from "../../utils/cli.utils.js";
 import { managedServiceStateStore } from "../../stores/managed-service-state.store.js";
 import { localUiRuntimeStore } from "../../stores/local-ui-runtime.store.js";
-import { writeInitialManagedServiceState, writeReadyManagedServiceState } from "./utils/service-remote-runtime.utils.js";
+import { ManagedServiceSupervisor } from "./managed-service-supervisor.service.js";
 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 { spawn } from "node:child_process";
-import { dirname } from "node:path";
 //#region src/shared/services/runtime/service-managed-startup.service.ts
 const { APP_NAME: APP_NAME$1, loadConfig: loadConfig$1 } = NextclawCore;
-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();
-	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);
-	appendStartupStage(logPath, `start requested: ui=${uiConfig.host}:${uiConfig.port}, readinessTimeoutMs=${readinessTimeoutMs}`);
-	console.log(`Starting ${appName} background service (readiness timeout ${Math.ceil(readinessTimeoutMs / 1e3)}s)...`);
-	const cliLaunch = resolveCliSubcommandLaunch({
-		argvEntry: process.argv[1],
-		importMetaUrl: import.meta.url,
-		cliArgs: [
-			"serve",
-			"--ui-port",
-			String(uiConfig.port)
-		],
-		nodePath: process.execPath
-	});
-	const childArgs = [...process.execArgv, ...cliLaunch.args];
-	appendStartupStage(logPath, `spawning background process: ${cliLaunch.command} ${childArgs.join(" ")}`);
-	const child = spawn(cliLaunch.command, childArgs, {
-		env: createTopLevelNextclawCommandEnv(process.env),
-		stdio: "ignore",
-		detached: true,
-		windowsHide: true
-	});
-	appendStartupStage(logPath, `spawned background process pid=${child.pid ?? "unknown"}`);
-	if (!child.pid) {
-		appendStartupStage(logPath, "spawn failed: child pid missing");
-		console.error("Error: Failed to start background service.");
-		printStartupFailureDiagnostics({
-			uiUrl,
-			apiUrl,
-			healthUrl,
-			logPath,
-			lastProbeError: null
-		});
-		return null;
-	}
-	const snapshot = {
-		pid: child.pid,
-		uiUrl,
-		apiUrl,
-		uiHost: uiConfig.host,
-		uiPort: uiConfig.port,
-		logPath
-	};
-	writeInitialManagedServiceState({
-		config,
-		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,
-		readinessTimeoutMs,
-		quickPhaseTimeoutMs,
-		extendedPhaseTimeoutMs,
-		snapshot
-	};
-}
 async function waitForManagedServiceReadiness(params) {
 	params.appendStartupStage(params.logPath, `health probe started: ${params.healthUrl} (phase=quick, timeoutMs=${params.quickPhaseTimeoutMs})`);
 	let readiness = await params.waitForBackgroundServiceReady({
@@ -128,6 +42,7 @@ var ManagedServiceCommandService = class {
 	loggingRuntime = NextclawCore.getLoggingRuntime();
 	serviceLogger = this.loggingRuntime.getLogger("service");
 	startupLogger = this.serviceLogger.child("startup");
+	supervisor = new ManagedServiceSupervisor();
 	constructor(deps) {
 		this.deps = deps;
 	}
@@ -149,7 +64,8 @@ var ManagedServiceCommandService = class {
 		const apiUrl = `${uiUrl}/api`;
 		const staticDir = this.deps.resolveUiStaticDir();
 		const existing = managedServiceStateStore.read();
-		if (existing && isProcessRunning(existing.pid)) {
+		const existingLiveness = this.supervisor.resolveStateLiveness(existing);
+		if (existing && existingLiveness.running) {
 			await this.handleExistingManagedService({
 				existing,
 				uiConfig,
@@ -157,7 +73,7 @@ var ManagedServiceCommandService = class {
 			});
 			return;
 		}
-		if (existing) managedServiceStateStore.clear();
+		if (existing && !existingLiveness.processExists) 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;
@@ -282,7 +198,7 @@ var ManagedServiceCommandService = class {
 	};
 	startNewManagedServiceTarget = async (params) => {
 		const { apiUrl, config, healthUrl, startupTimeoutMs, uiConfig, uiUrl } = params;
-		const startup = spawnManagedService({
+		const startup = this.supervisor.spawnManagedService({
 			appName: APP_NAME$1,
 			config,
 			uiConfig,
@@ -336,7 +252,7 @@ var ManagedServiceCommandService = class {
 		}
 		startup.child.unref();
 		const readySnapshot = resolveManagedServiceReadySnapshot({ snapshot: startup.snapshot });
-		const state = writeReadyManagedServiceState({
+		const state = this.supervisor.writeReadyState({
 			readinessTimeoutMs: startup.readinessTimeoutMs,
 			readiness,
 			snapshot: readySnapshot
@@ -420,4 +336,4 @@ var ManagedServiceCommandService = class {
 	};
 };
 //#endregion
-export { ManagedServiceCommandService, reportManagedServiceStart, resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate, spawnManagedService, waitForManagedServiceReadiness };
+export { ManagedServiceCommandService, reportManagedServiceStart, resolveManagedServiceReadySnapshot, resolveManagedServiceUiBinding, resolveSessionRouteCandidate, waitForManagedServiceReadiness };

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

@@ -1,4 +1,4 @@
-import { ManagedServiceState } from "../../../stores/managed-service-state.store.js";
+import { ManagedServiceLease, ManagedServiceState } from "../../../stores/managed-service-state.store.js";
 import { Config } from "@nextclaw/core";
 import { RemoteRuntimeState, RemoteServiceModule } from "@nextclaw/remote";
 
@@ -40,10 +40,12 @@ declare function createManagedRemoteModuleForUi(params: {
 }): RemoteServiceModule | null;
 declare function writeInitialManagedServiceState(params: {
   config: Config;
+  lease?: ManagedServiceLease;
   readinessTimeoutMs: number;
   snapshot: ManagedServiceSnapshot;
 }): void;
 declare function writeReadyManagedServiceState(params: {
+  lease?: ManagedServiceLease;
   readinessTimeoutMs: number;
   readiness: {
     ready: boolean;

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

@@ -137,33 +137,37 @@ function createManagedRemoteModuleForUi(params) {
 	});
 }
 function writeInitialManagedServiceState(params) {
+	const { config, lease, readinessTimeoutMs, snapshot } = params;
 	managedServiceStateStore.write({
-		pid: params.snapshot.pid,
+		pid: snapshot.pid,
 		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-		uiUrl: params.snapshot.uiUrl,
-		apiUrl: params.snapshot.apiUrl,
-		uiHost: params.snapshot.uiHost,
-		uiPort: params.snapshot.uiPort,
-		logPath: params.snapshot.logPath,
+		uiUrl: snapshot.uiUrl,
+		apiUrl: snapshot.apiUrl,
+		uiHost: snapshot.uiHost,
+		uiPort: snapshot.uiPort,
+		logPath: snapshot.logPath,
+		...lease ? { lease } : {},
 		startupLastProbeError: null,
-		startupTimeoutMs: params.readinessTimeoutMs,
+		startupTimeoutMs: readinessTimeoutMs,
 		startupCheckedAt: (/* @__PURE__ */ new Date()).toISOString(),
-		...params.config.remote.enabled ? { remote: buildNextclawConfiguredRemoteState(params.config) } : {}
+		...config.remote.enabled ? { remote: buildNextclawConfiguredRemoteState(config) } : {}
 	});
 }
 function writeReadyManagedServiceState(params) {
+	const { lease, readiness, readinessTimeoutMs, snapshot } = params;
 	const currentState = managedServiceStateStore.read();
 	const state = {
-		pid: params.snapshot.pid,
+		pid: snapshot.pid,
 		startedAt: currentState?.startedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
-		uiUrl: params.snapshot.uiUrl,
-		apiUrl: params.snapshot.apiUrl,
-		uiHost: params.snapshot.uiHost,
-		uiPort: params.snapshot.uiPort,
-		logPath: params.snapshot.logPath,
-		startupState: params.readiness.ready ? "ready" : "degraded",
-		startupLastProbeError: params.readiness.lastProbeError,
-		startupTimeoutMs: params.readinessTimeoutMs,
+		uiUrl: snapshot.uiUrl,
+		apiUrl: snapshot.apiUrl,
+		uiHost: snapshot.uiHost,
+		uiPort: snapshot.uiPort,
+		logPath: snapshot.logPath,
+		...lease ? { lease } : currentState?.lease ? { lease: currentState.lease } : {},
+		startupState: readiness.ready ? "ready" : "degraded",
+		startupLastProbeError: readiness.lastProbeError,
+		startupTimeoutMs: readinessTimeoutMs,
 		startupCheckedAt: (/* @__PURE__ */ new Date()).toISOString(),
 		...currentState?.remote ? { remote: currentState.remote } : {}
 	};

package/dist/shared/stores/managed-service-state.store.d.ts

@@ -1,6 +1,21 @@
 import { RemoteRuntimeState } from "@nextclaw/remote";
 
 //#region src/shared/stores/managed-service-state.store.d.ts
+type ManagedServiceLease = {
+  ownerPid: number;
+  heartbeatAt: string;
+  heartbeatIntervalMs: number;
+  ttlMs: number;
+};
+type ManagedServiceExitReason = "exit" | "signal" | "uncaughtException";
+type ManagedServiceLastExit = {
+  pid: number;
+  reason: ManagedServiceExitReason;
+  exitedAt: string;
+  code?: number | null;
+  signal?: string | null;
+  message?: string | null;
+};
 type ManagedServiceState = {
   pid: number;
   startedAt: string;
@@ -13,6 +28,8 @@ type ManagedServiceState = {
   startupLastProbeError?: string | null;
   startupTimeoutMs?: number;
   startupCheckedAt?: string;
+  lease?: ManagedServiceLease;
+  lastExit?: ManagedServiceLastExit;
   remote?: RemoteRuntimeState;
 };
 declare class ManagedServiceStateStore {
@@ -25,4 +42,4 @@ declare class ManagedServiceStateStore {
 }
 declare const managedServiceStateStore: ManagedServiceStateStore;
 //#endregion
-export { ManagedServiceState, ManagedServiceStateStore, managedServiceStateStore };
+export { ManagedServiceLastExit, ManagedServiceLease, ManagedServiceState, ManagedServiceStateStore, managedServiceStateStore };

package/dist/shared/types/cli.types.d.ts

@@ -250,8 +250,22 @@ type RuntimeStatusReport = {
     pid: number | null;
     running: boolean;
     staleState: boolean;
+    staleReason: "process-not-running" | "lease-expired" | null;
     orphanSuspected: boolean;
     startedAt: string | null;
+    lease: {
+      heartbeatAt: string | null;
+      expired: boolean;
+      missing: boolean;
+    } | null;
+    lastExit: {
+      pid: number;
+      reason: string;
+      exitedAt: string;
+      code?: number | null;
+      signal?: string | null;
+      message?: string | null;
+    } | null;
   };
   endpoints: {
     uiUrl: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/service",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "private": false,
   "description": "NextClaw long-running service host and runtime lifecycle.",
   "type": "module",
@@ -35,24 +35,24 @@
     "chokidar": "^3.6.0",
     "commander": "^12.1.0",
     "jszip": "^3.10.1",
-    "@nextclaw/channel-extension-feishu": "0.1.5",
-    "@nextclaw/kernel": "0.1.11",
-    "@nextclaw/mcp": "0.1.86",
-    "@nextclaw/ncp": "0.5.14",
-    "@nextclaw/core": "0.12.21",
-    "@nextclaw/ncp-agent-runtime": "0.3.25",
-    "@nextclaw/ncp-mcp": "0.1.88",
-    "@nextclaw/ncp-toolkit": "0.5.19",
-    "@nextclaw/channel-extension-weixin": "0.1.8",
-    "@nextclaw/nextclaw-ncp-runtime-http-client": "0.1.13",
-    "@nextclaw/nextclaw-ncp-runtime-stdio-client": "0.1.14",
-    "@nextclaw/nextclaw-hermes-acp-bridge": "0.1.13",
-    "@nextclaw/remote": "0.1.99",
-    "@nextclaw/runtime": "0.2.53",
-    "@nextclaw/shared": "0.1.8",
-    "@nextclaw/server": "0.12.22",
-    "@nextclaw/openclaw-compat": "1.0.21",
-    "@nextclaw/channel-extension-qq": "0.1.2"
+    "@nextclaw/channel-extension-qq": "0.1.3",
+    "@nextclaw/channel-extension-feishu": "0.1.6",
+    "@nextclaw/channel-extension-weixin": "0.1.9",
+    "@nextclaw/core": "0.12.22",
+    "@nextclaw/kernel": "0.1.12",
+    "@nextclaw/mcp": "0.1.87",
+    "@nextclaw/ncp-agent-runtime": "0.3.26",
+    "@nextclaw/ncp": "0.5.15",
+    "@nextclaw/ncp-toolkit": "0.5.20",
+    "@nextclaw/ncp-mcp": "0.1.89",
+    "@nextclaw/nextclaw-ncp-runtime-http-client": "0.1.14",
+    "@nextclaw/nextclaw-hermes-acp-bridge": "0.1.14",
+    "@nextclaw/nextclaw-ncp-runtime-stdio-client": "0.1.15",
+    "@nextclaw/remote": "0.1.100",
+    "@nextclaw/openclaw-compat": "1.0.22",
+    "@nextclaw/runtime": "0.2.54",
+    "@nextclaw/shared": "0.1.9",
+    "@nextclaw/server": "0.12.23"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",