@zhengjunyao/dsh-restart 0.1.0

package/lib/index.js

@@ -0,0 +1,1401 @@
+import { access, chmod, mkdir, readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
+import { constants, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/config.ts
+/**
+* dsh-restart — plugin config, on-disk layout, and restart history.
+*
+* Everything this plugin owns lives under one directory
+* (`~/.dsh/dsh-restart` by default, override with `DSH_RESTART_HOME`):
+*
+*   config.json    plugin settings (0600)
+*   history.json   one record per requested restart (newest first)
+*   status.json    written by the detached helper — live restart state
+*   pending-spec.json  handoff payload for the next helper run
+*   logs/<stamp>.log   stdout+stderr of one restarted host
+*/
+/** Shipped defaults. */
+const DEFAULT_CONFIG = {
+	enabled: true,
+	announceToAgent: true,
+	entry: "sidebar",
+	restartMode: "auto",
+	fallbackPort: 3099,
+	bootTimeoutMs: 12e4,
+	maxAttempts: 2,
+	killGraceMs: 6e3,
+	portFreeTimeoutMs: 25e3,
+	lingerMs: 4e3,
+	logLines: 200,
+	autoReload: true,
+	showOverlay: true,
+	probeIntervalMs: 1200,
+	historyLimit: 30
+};
+/**
+* Plugin directory.
+*
+* Resolution order mirrors DSH's own: an explicit `DSH_RESTART_HOME` (used by
+* the tests and by anyone running a throwaway instance), then DSH's own
+* `DSH_HOME` when it is set — a launcher or a rescue capsule may relocate the
+* whole home — and only then the conventional `~/.dsh`. Hardcoding `~/.dsh`
+* would silently write a second, wrong home on such setups.
+*/
+function restartHome() {
+	const override = process.env.DSH_RESTART_HOME;
+	if (typeof override === "string" && override.trim() !== "") return override;
+	const dshHome = process.env.DSH_HOME;
+	return join(typeof dshHome === "string" && dshHome.trim() !== "" ? dshHome : join(homedir(), ".dsh"), "dsh-restart");
+}
+/** Settings file (override with DSH_RESTART_CONFIG). */
+function configPath() {
+	const override = process.env.DSH_RESTART_CONFIG;
+	if (typeof override === "string" && override.trim() !== "") return override;
+	return join(restartHome(), "config.json");
+}
+/** Restart history file. */
+function historyPath() {
+	return join(restartHome(), "history.json");
+}
+/** Live helper status file. */
+function statusPath() {
+	return join(restartHome(), "status.json");
+}
+/** Handoff payload for the helper. */
+function specPath() {
+	return join(restartHome(), "pending-spec.json");
+}
+/** Directory holding one log file per restarted host. */
+function logsDir() {
+	return join(restartHome(), "logs");
+}
+/**
+* The detached helper shipped with this package. Resolved from the module URL
+* so it works both from a local checkout and from an installed copy.
+*/
+function helperPath() {
+	return fileURLToPath(new URL("../helper/restart-helper.mjs", import.meta.url));
+}
+/** Coerce an unknown value into a bounded integer. */
+function intIn(value, fallback, min, max) {
+	const raw = typeof value === "number" ? value : Number(value);
+	if (!Number.isFinite(raw)) return fallback;
+	return Math.max(min, Math.min(max, Math.round(raw)));
+}
+/** Normalize a partial config against the defaults (never throws). */
+function normalizeConfig(patch, base = DEFAULT_CONFIG) {
+	const source = patch ?? {};
+	const entry = source.entry;
+	return {
+		enabled: typeof source.enabled === "boolean" ? source.enabled : base.enabled,
+		announceToAgent: typeof source.announceToAgent === "boolean" ? source.announceToAgent : base.announceToAgent,
+		entry: entry === "sidebar" || entry === "ball" || entry === "both" || entry === "off" ? entry : base.entry,
+		restartMode: source.restartMode === "helper" || source.restartMode === "launchd" || source.restartMode === "auto" ? source.restartMode : base.restartMode,
+		fallbackPort: intIn(source.fallbackPort ?? base.fallbackPort, base.fallbackPort, 1, 65535),
+		bootTimeoutMs: intIn(source.bootTimeoutMs ?? base.bootTimeoutMs, base.bootTimeoutMs, 5e3, 9e5),
+		maxAttempts: intIn(source.maxAttempts ?? base.maxAttempts, base.maxAttempts, 1, 5),
+		killGraceMs: intIn(source.killGraceMs ?? base.killGraceMs, base.killGraceMs, 0, 12e4),
+		portFreeTimeoutMs: intIn(source.portFreeTimeoutMs ?? base.portFreeTimeoutMs, base.portFreeTimeoutMs, 0, 3e5),
+		lingerMs: intIn(source.lingerMs ?? base.lingerMs, base.lingerMs, 0, 6e5),
+		logLines: intIn(source.logLines ?? base.logLines, base.logLines, 20, 2e3),
+		autoReload: typeof source.autoReload === "boolean" ? source.autoReload : base.autoReload,
+		showOverlay: typeof source.showOverlay === "boolean" ? source.showOverlay : base.showOverlay,
+		probeIntervalMs: intIn(source.probeIntervalMs ?? base.probeIntervalMs, base.probeIntervalMs, 300, 3e4),
+		historyLimit: intIn(source.historyLimit ?? base.historyLimit, base.historyLimit, 1, 500)
+	};
+}
+/** Read a JSON file, returning null when it is missing or unparsable. */
+async function readJson(file) {
+	try {
+		const text = await readFile(file, "utf8");
+		const parsed = JSON.parse(text);
+		return typeof parsed === "object" && parsed !== null ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/** Write JSON atomically with mode 0600. */
+async function writeJson$1(file, value) {
+	await mkdir(dirname(file), { recursive: true });
+	const tmp = `${file}.${process.pid}.tmp`;
+	await writeFile(tmp, JSON.stringify(value, null, 2), { mode: 384 });
+	await rename(tmp, file);
+	await chmod(file, 384).catch(() => void 0);
+}
+/** The effective config (defaults + file), plus where it came from. */
+async function loadConfig() {
+	const file = configPath();
+	const stored = await readJson(file);
+	if (stored === null) return {
+		config: normalizeConfig(void 0),
+		exists: false,
+		file
+	};
+	return {
+		config: normalizeConfig(stored),
+		exists: true,
+		file
+	};
+}
+/** Merge a patch into the stored config and return the fresh value. */
+async function saveConfig(patch) {
+	const { config } = await loadConfig();
+	const next = normalizeConfig(patch, config);
+	await writeJson$1(configPath(), next);
+	return next;
+}
+/** Delete the stored config (back to shipped defaults). */
+async function resetConfig() {
+	await writeJson$1(configPath(), DEFAULT_CONFIG);
+	return { ...DEFAULT_CONFIG };
+}
+/** Append one restart record (newest first, bounded by historyLimit). */
+async function appendHistory(record, limit) {
+	const existing = await readJson(historyPath()) ?? [];
+	const list = Array.isArray(existing) ? existing : [];
+	list.unshift(record);
+	await writeJson$1(historyPath(), list.slice(0, Math.max(1, limit)));
+}
+/** Read the restart history (newest first). */
+async function readHistory(limit = 20) {
+	const existing = await readJson(historyPath());
+	return (Array.isArray(existing) ? existing : []).slice(0, Math.max(1, limit));
+}
+/** Ensure the plugin directories exist (0600 where it matters). */
+async function ensureLayout() {
+	await mkdir(logsDir(), { recursive: true });
+	await chmod(restartHome(), 448).catch(() => void 0);
+}
+/**
+* Synchronous config read, for the plugin's apply() path.
+*
+* Mounting must stay synchronous: cordis effects have to be created inside the
+* plugin's own apply scope, so the roster cannot wait on a promise.
+*/
+function loadConfigSync() {
+	const file = configPath();
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf8"));
+		if (typeof parsed === "object" && parsed !== null) return {
+			config: normalizeConfig(parsed),
+			exists: true,
+			file
+		};
+	} catch {}
+	return {
+		config: normalizeConfig(void 0),
+		exists: false,
+		file
+	};
+}
+/**
+* Materialize the config file on first run so the settings become discoverable
+* and editable; the composition row only seeds it, the file is authoritative.
+* @param seed - values from the plugin row (enabled / announceToAgent / …).
+*/
+function seedConfigSync(seed) {
+	const file = configPath();
+	if (existsSync(file)) return false;
+	try {
+		mkdirSync(restartHome(), {
+			recursive: true,
+			mode: 448
+		});
+		writeFileSync(file, JSON.stringify(normalizeConfig(seed), null, 2), { mode: 384 });
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/launchd.ts
+/**
+* dsh-restart — macOS launchd awareness.
+*
+* A DSH host is often managed by a launchd job (`com.dsh.web` with
+* `KeepAlive: true` on this machine). That changes the correct restart from
+* "relaunch it ourselves" to "ask launchd to restart it": a helper that spawns
+* its own child would race the job for the listening port, and whichever loses
+* dies with `EADDRINUSE`.
+*
+* So the plugin detects the situation and switches strategy:
+*
+*   launchd-managed → `launchctl kickstart -k gui/<uid>/<label>` (the job comes
+*                     back with the plist's own cwd/env/argv) + the helper runs
+*                     in observe mode, following the plist's stdout/stderr.
+*   anything else   → the helper relaunches the exact same command itself.
+*
+* Detection is a pure read of `XPC_SERVICE_NAME` (set by launchd on every
+* process it starts) confirmed by `launchctl print`, and every failure mode
+* falls back to the self-relaunch path — a host that is not launchd-managed must
+* never end up depending on launchctl.
+*/
+const run = promisify(execFile);
+/** Run a command, resolving to { ok, stdout } instead of throwing. */
+async function tryRun(file, args, timeoutMs = 4e3) {
+	try {
+		const { stdout, stderr } = await run(file, [...args], {
+			timeout: timeoutMs,
+			encoding: "utf8"
+		});
+		return {
+			ok: true,
+			stdout: stdout ?? "",
+			stderr: stderr ?? ""
+		};
+	} catch (error) {
+		const failure = error;
+		return {
+			ok: false,
+			stdout: failure.stdout ?? "",
+			stderr: failure.stderr ?? failure.message ?? ""
+		};
+	}
+}
+/** Read one raw key out of a plist (empty string when absent/unparsable). */
+async function plistValue(plistPath, key) {
+	const result = await tryRun("/usr/bin/plutil", [
+		"-extract",
+		key,
+		"raw",
+		"-o",
+		"-",
+		plistPath
+	], 3e3);
+	return result.ok ? result.stdout.trim() : "";
+}
+/**
+* Which launchd job owns a pid.
+*
+* `launchctl list` prints `PID  Status  Label`, so matching our own pid is the
+* authoritative answer — and the only reliable one: **Node rewrites
+* `XPC_SERVICE_NAME` to `0` in `process.env`**, so the environment variable
+* launchd set (still visible in the kernel environment, e.g. `ps eww -p <pid>`)
+* cannot be read from inside the process. The env var is kept only as a
+* secondary signal for the case where `launchctl list` is unavailable.
+*
+* @param pid - the process to look up.
+* @returns the job label, or null when the process is not a launchd job.
+*/
+async function labelForPid(pid) {
+	const listed = await tryRun("/bin/launchctl", ["list"], 5e3);
+	if (listed.ok) for (const line of listed.stdout.split("\n")) {
+		const fields = line.trim().split(/\s+/);
+		if (fields.length < 3) continue;
+		if (fields[0] !== String(pid)) continue;
+		const candidate = fields[2];
+		if (candidate !== void 0 && candidate !== "" && candidate !== "-") return candidate;
+	}
+	const fromEnv = (process.env.XPC_SERVICE_NAME ?? "").trim();
+	if (fromEnv !== "" && fromEnv !== "0" && fromEnv !== "-" && !fromEnv.includes("/")) return fromEnv;
+	return null;
+}
+/**
+* Detect a managing launchd job for this process.
+*
+* Returns null on non-macOS, when the process is not launchd-managed, or when
+* `launchctl print` cannot see the job — every one of those means the caller
+* must fall back to the self-relaunch strategy.
+*/
+async function detectLaunchd() {
+	return detectLaunchdFor(process.pid);
+}
+/**
+* Detect the launchd job owning an arbitrary pid.
+*
+* The plugin calls it for its own pid (the host is the job); tooling outside the
+* host — a one-off handoff script, a test — needs it for a *different* pid, and
+* in that case `process.env.XPC_SERVICE_NAME` says nothing useful.
+*
+* @param pid - the process to look up.
+*/
+async function detectLaunchdFor(pid) {
+	if (process.platform !== "darwin") return null;
+	const label = await labelForPid(pid);
+	if (label === null) return null;
+	const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+	const domain = `gui/${uid}`;
+	const printed = await tryRun("/bin/launchctl", ["print", `${domain}/${label}`], 4e3);
+	if (!printed.ok) return null;
+	const pidMatch = /^\s*pid = (\d+)\s*$/m.exec(printed.stdout);
+	const stateMatch = /^\s*state = (\S+)\s*$/m.exec(printed.stdout);
+	const plistPath = process.env.DSH_RESTART_PLIST ?? join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+	const [stdoutPath, stderrPath] = await Promise.all([plistValue(plistPath, "StandardOutPath"), plistValue(plistPath, "StandardErrorPath")]);
+	return {
+		label,
+		uid,
+		domain,
+		plistPath,
+		stdoutPath,
+		stderrPath,
+		state: stateMatch?.[1] ?? "unknown",
+		pid: pidMatch === null ? null : Number(pidMatch[1])
+	};
+}
+/**
+* Ask launchd to restart the job (`kickstart -k`).
+*
+* @param info - the detected job.
+* @returns ok plus launchctl's own output when it refused.
+*/
+async function kickstart(info) {
+	const result = await tryRun("/bin/launchctl", [
+		"kickstart",
+		"-k",
+		`${info.domain}/${info.label}`
+	], 1e4);
+	if (result.ok) return {
+		ok: true,
+		error: ""
+	};
+	const message = (result.stderr || result.stdout).trim();
+	return {
+		ok: false,
+		error: `launchctl kickstart 失败：${message === "" ? "未知错误" : message}`
+	};
+}
+/** The command a retry should re-run for a managed host. */
+function kickCommand(info) {
+	return [
+		"/bin/launchctl",
+		"kickstart",
+		"-k",
+		`${info.domain}/${info.label}`
+	];
+}
+/** Read the tail of a launchd log file ('' when missing). */
+async function readLaunchdLog(file, lines) {
+	if (file === "") return "";
+	try {
+		return (await readFile(file, "utf8")).split(/\r?\n/).filter((line) => line !== "").slice(-Math.max(1, lines)).join("\n");
+	} catch {
+		return "";
+	}
+}
+//#endregion
+//#region src/restart.ts
+/**
+* dsh-restart — the restart engine (host half).
+*
+* A host cannot restart itself in place: the moment it exits, the browser has
+* nothing to talk to, and any failure would be invisible. So the handoff goes
+* through a detached helper process that survives the host:
+*
+*   panel / tool ──POST /api/dsh-restart/restart──▶ host
+*   host ──writes pending-spec.json, spawns helper──▶ helper (detached)
+*   host ──SIGTERM after a short delay──▶ exit
+*   helper ──waits for the port to free, relaunches the same command──▶ new host
+*   helper ──status.json + fallback console──▶ the page shows progress / errors
+*
+* The relaunch reuses the exact invocation the running host was started with
+* (`process.execArgv` + `argv[1:]`), so `dsh web --port 3080`, a `node` path
+* override, a custom port and a custom cwd all survive a restart unchanged.
+*/
+/**
+* Lines that usually carry the reason a boot failed. The stack-frame branch
+* insists on a real file-ish frame so timestamps ("… at 2026-09-12T02:08:18Z")
+* are not mistaken for errors.
+*/
+const ERROR_HINT = new RegExp([
+	"\\bError\\b",
+	"\\bERROR\\b",
+	"error:",
+	"EADDRINUSE",
+	"ECONNREFUSED",
+	"ENOENT",
+	"EACCES",
+	"MODULE_NOT_FOUND",
+	"Cannot find (module|package)",
+	"UnhandledPromiseRejection",
+	"uncaughtException",
+	"FATAL",
+	"fatal:",
+	"SyntaxError",
+	"TypeError",
+	"ReferenceError",
+	"is not a function",
+	"failed to load",
+	"加载失败",
+	"启动失败",
+	"\\bat\\s+.*(?:\\.(?:js|mjs|cjs|ts|tsx|jsx|json)|node:[\\w/]+):\\d+:\\d+"
+].join("|"));
+/** True when a pid is alive (signal 0 probe). */
+function isAlive(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Cached launchd detection (the check shells out, so do not repeat it per poll). */
+let launchdCache = null;
+const LAUNCHD_TTL_MS = 3e4;
+/** Detect (and cache) the launchd job managing this host. */
+async function launchdInfo(force = false) {
+	if (!force && launchdCache !== null && Date.now() - launchdCache.at < LAUNCHD_TTL_MS) return launchdCache.info;
+	const info = await detectLaunchd().catch(() => null);
+	launchdCache = {
+		at: Date.now(),
+		info
+	};
+	return info;
+}
+/** Read the DSH version from the package that owns the running entry script. */
+async function readDshVersion() {
+	const entry = process.argv[1];
+	if (typeof entry !== "string" || entry === "") return "";
+	let resolved = entry;
+	try {
+		resolved = realpathSync(entry);
+	} catch {
+		resolved = entry;
+	}
+	let dir = dirname(resolved);
+	for (let i = 0; i < 3; i++) {
+		try {
+			const text = await readFile(join(dir, "package.json"), "utf8");
+			const parsed = JSON.parse(text);
+			const name = parsed.name;
+			const version = parsed.version;
+			if (typeof version === "string" && typeof name === "string" && name.includes("dsh")) return version;
+			if (typeof version === "string" && i === 1) return version;
+		} catch {}
+		dir = dirname(dir);
+	}
+	return "";
+}
+/** Best-effort profile name for diagnostics. */
+function readProfile() {
+	for (const key of [
+		"DSH_PROFILE",
+		"DSH_ACTIVE_PROFILE",
+		"DSH_PROFILE_NAME"
+	]) {
+		const value = process.env[key];
+		if (typeof value === "string" && value.trim() !== "") return value.trim();
+	}
+	const args = process.argv.slice(2);
+	const index = args.findIndex((token) => token === "--profile" || token === "-P");
+	if (index >= 0 && typeof args[index + 1] === "string") return args[index + 1] ?? "";
+	return "";
+}
+/** The relaunch command, exactly as this host was started. */
+function launchSignature() {
+	const entry = process.argv[1] ?? "";
+	return {
+		file: process.argv[0] ?? process.execPath,
+		args: [
+			...process.execArgv,
+			entry,
+			...process.argv.slice(2)
+		],
+		cwd: process.cwd()
+	};
+}
+/** Describe the running host. */
+async function hostInfo(options) {
+	const signature = launchSignature();
+	const helper = helperPath();
+	let helperExists = false;
+	try {
+		await access(helper, constants.R_OK);
+		helperExists = true;
+	} catch {
+		helperExists = false;
+	}
+	const helperPid = Number(process.env.DSH_RESTART_HELPER_PID ?? "");
+	const { config } = await loadConfig();
+	const job = config.restartMode === "helper" ? null : await launchdInfo();
+	const forced = config.restartMode === "launchd";
+	return {
+		pid: process.pid,
+		ppid: process.ppid,
+		startedAt: (/* @__PURE__ */ new Date(Date.now() - process.uptime() * 1e3)).toISOString(),
+		uptimeMs: Math.round(process.uptime() * 1e3),
+		port: options.port,
+		host: options.host,
+		url: options.url,
+		cwd: signature.cwd,
+		nodeVersion: process.version,
+		dshVersion: await readDshVersion(),
+		profile: readProfile(),
+		command: [signature.file, ...signature.args].join(" "),
+		restarted: Number.isInteger(helperPid) && helperPid > 0,
+		platform: process.platform,
+		logsDir: logsDir(),
+		statusFile: statusPath(),
+		helperFile: helper,
+		helperExists,
+		launchd: {
+			managed: job !== null,
+			label: job?.label ?? "",
+			state: job?.state ?? "",
+			pid: job?.pid ?? null,
+			plistPath: job?.plistPath ?? "",
+			logFile: job?.stderrPath !== void 0 && job.stderrPath !== "" ? job.stderrPath : job?.stdoutPath ?? "",
+			strategy: job !== null || forced ? job === null ? "helper" : "launchd" : "helper"
+		}
+	};
+}
+/** Timestamp used in log file names (filesystem-safe, local time). */
+function stamp() {
+	const now = /* @__PURE__ */ new Date();
+	const pad = (value, width = 2) => String(value).padStart(width, "0");
+	return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+/** Build the helper spec for a restart of the current host. */
+async function buildSpec(options) {
+	const signature = launchSignature();
+	const logFile = join(logsDir(), `${stamp()}-${process.pid}.log`);
+	const job = options.launchd ?? null;
+	return {
+		port: options.port,
+		host: options.host,
+		url: options.url,
+		file: signature.file,
+		args: signature.args,
+		cwd: signature.cwd,
+		env: { ...process.env },
+		oldPid: process.pid,
+		logFile,
+		statusFile: statusPath(),
+		fallbackPort: options.config.fallbackPort,
+		bootTimeoutMs: options.config.bootTimeoutMs,
+		maxAttempts: options.config.maxAttempts,
+		killGraceMs: options.config.killGraceMs,
+		portFreeTimeoutMs: options.config.portFreeTimeoutMs,
+		lingerMs: options.config.lingerMs,
+		ringLines: options.config.logLines,
+		dshVersion: await readDshVersion(),
+		profile: readProfile(),
+		mode: job === null ? "spawn" : "observe",
+		owner: job === null ? "dsh-restart helper" : `launchd ${job.label}`,
+		kickCommand: job === null ? [] : kickCommand(job),
+		kickDelayMs: 1200,
+		observeLog: job === null ? "" : job.stderrPath !== "" ? job.stderrPath : job.stdoutPath,
+		failureReport: failureReportPath()
+	};
+}
+/**
+* Hand the restart over to a detached helper.
+*
+* Returns as soon as the helper is running; the caller is responsible for
+* answering the HTTP request first and only then ending this process (see
+* {@link scheduleSelfExit}), so the browser always gets a definite reply.
+*
+* @param options - config, listen address, and who asked.
+*/
+async function requestRestart(options) {
+	const { config } = options;
+	await ensureLayout();
+	const job = config.restartMode === "helper" ? null : await launchdInfo();
+	const forcedLaunchd = config.restartMode === "launchd";
+	const spec = await buildSpec({
+		...options,
+		launchd: job
+	});
+	const mode = job === null ? "helper" : "launchd";
+	const specFile = specPath();
+	const record = {
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		source: options.source,
+		reason: options.reason,
+		oldPid: process.pid,
+		helperPid: null,
+		port: spec.port,
+		logFile: spec.logFile,
+		statusFile: spec.statusFile,
+		outcome: "pending"
+	};
+	const fail = (error, helperPid = null) => ({
+		ok: false,
+		error,
+		helperPid,
+		logFile: spec.logFile,
+		statusFile: spec.statusFile,
+		specFile,
+		fallbackPort: config.fallbackPort,
+		fallbackUrl: `http://${spec.host}:${config.fallbackPort}`,
+		exitInMs: 0,
+		mode,
+		record,
+		commit: async () => void 0
+	});
+	if (forcedLaunchd && job === null) return fail("配置 restartMode=launchd，但没有检测到管理本宿主的 launchd 任务（XPC_SERVICE_NAME 未设置或 launchctl print 失败）");
+	const helper = helperPath();
+	try {
+		await access(helper, constants.R_OK);
+	} catch {
+		return fail(`找不到重启助手脚本：${helper}（包内 helper/ 目录缺失时请重新安装 dsh-restart）`);
+	}
+	try {
+		await mkdir(dirname(specFile), { recursive: true });
+		await writeFile(specFile, JSON.stringify(spec, null, 2), { mode: 384 });
+		await chmod(specFile, 384).catch(() => void 0);
+	} catch (error) {
+		return fail(`写入交接文件失败：${String(error?.message ?? error)}`);
+	}
+	let helperPid = null;
+	try {
+		const child = spawn(process.execPath, [
+			helper,
+			"--spec",
+			specFile
+		], {
+			detached: true,
+			stdio: "ignore",
+			cwd: spec.cwd,
+			env: { ...process.env }
+		});
+		child.unref();
+		helperPid = child.pid ?? null;
+	} catch (error) {
+		return fail(`拉起重启助手失败：${String(error?.message ?? error)}`);
+	}
+	record.helperPid = helperPid;
+	await appendHistory(record, config.historyLimit).catch(() => void 0);
+	const exitInMs = options.exitDelayMs ?? 700;
+	return {
+		ok: true,
+		error: "",
+		helperPid,
+		logFile: spec.logFile,
+		statusFile: spec.statusFile,
+		specFile,
+		fallbackPort: config.fallbackPort,
+		fallbackUrl: `http://${spec.host}:${config.fallbackPort}`,
+		exitInMs,
+		mode,
+		record,
+		commit: async () => {
+			if (mode === "launchd") return;
+			scheduleSelfExit(exitInMs);
+		}
+	};
+}
+/**
+* End this host so the helper can take over.
+*
+* SIGTERM first (lets DSH close sessions and release the port), then a hard
+* exit as a backstop — the helper SIGKILLs anything still holding the port
+* after its own grace period.
+* @param delayMs - how long to wait before signalling (the HTTP reply needs to flush).
+*/
+function scheduleSelfExit(delayMs) {
+	setTimeout(() => {
+		try {
+			process.kill(process.pid, "SIGTERM");
+		} catch {}
+		setTimeout(() => {
+			process.exit(0);
+		}, 15e3).unref();
+	}, Math.max(0, delayMs)).unref();
+}
+/** Read the live helper status, if any. */
+async function readHelperStatus() {
+	const file = statusPath();
+	try {
+		const [text, info] = await Promise.all([readFile(file, "utf8"), stat(file)]);
+		const parsed = JSON.parse(text);
+		const helperPid = Number(parsed.helperPid ?? 0);
+		const ageMs = Date.now() - info.mtimeMs;
+		return {
+			status: parsed,
+			alive: helperPid > 0 && isAlive(helperPid) && ageMs < 15 * 6e4,
+			ageMs
+		};
+	} catch {
+		return {
+			status: null,
+			alive: false,
+			ageMs: null
+		};
+	}
+}
+/** Tail a log file (missing files come back as an empty tail, not an error). */
+async function tailFile(file, limit) {
+	const empty = {
+		file,
+		exists: false,
+		mtime: "",
+		text: "",
+		lines: [],
+		errorLines: []
+	};
+	try {
+		const [text, info] = await Promise.all([readFile(file, "utf8"), stat(file)]);
+		const all = text.split(/\r?\n/).filter((line) => line !== "");
+		const lines = all.slice(-limit);
+		return {
+			file,
+			exists: true,
+			mtime: new Date(info.mtimeMs).toISOString(),
+			text: lines.join("\n"),
+			lines,
+			errorLines: all.filter((line) => ERROR_HINT.test(line)).slice(-40)
+		};
+	} catch {
+		return empty;
+	}
+}
+/** Where the helper drops the copy-ready failure report. */
+function failureReportPath() {
+	return join(restartHome(), "last-failure.md");
+}
+/** The newest log file in the logs directory (null when none exist). */
+async function newestLogFile() {
+	try {
+		const logs = (await readdir(logsDir())).filter((name) => name.endsWith(".log"));
+		if (logs.length === 0) return null;
+		const stats = await Promise.all(logs.map(async (name) => ({
+			name,
+			mtime: (await stat(join(logsDir(), name))).mtimeMs
+		})));
+		stats.sort((a, b) => b.mtime - a.mtime);
+		const newest = stats[0];
+		return newest === void 0 ? null : join(logsDir(), newest.name);
+	} catch {
+		return null;
+	}
+}
+/** List recent log files (newest first). */
+async function listLogs(limit = 20) {
+	try {
+		const logs = (await readdir(logsDir())).filter((name) => name.endsWith(".log"));
+		const rows = await Promise.all(logs.map(async (name) => {
+			const info = await stat(join(logsDir(), name));
+			return {
+				name,
+				file: join(logsDir(), name),
+				size: info.size,
+				mtime: new Date(info.mtimeMs).toISOString()
+			};
+		}));
+		rows.sort((a, b) => a.mtime < b.mtime ? 1 : -1);
+		return rows.slice(0, Math.max(1, limit));
+	} catch {
+		return [];
+	}
+}
+//#endregion
+//#region src/routes.ts
+/** Route paths. */
+const RESTART_API = {
+	status: "/api/dsh-restart/status",
+	probe: "/api/dsh-restart/probe",
+	restart: "/api/dsh-restart/restart",
+	logs: "/api/dsh-restart/logs",
+	history: "/api/dsh-restart/history",
+	config: "/api/dsh-restart/config",
+	helper: "/api/dsh-restart/helper",
+	helperRetry: "/api/dsh-restart/helper/retry"
+};
+/** Cap on JSON request bodies. */
+const MAX_JSON_BODY_BYTES = 64 * 1024;
+/** Strict loopback fence for every route (the panel is same-origin only). */
+function isLoopbackRequest(request) {
+	const address = request.socket.remoteAddress;
+	if (address !== "127.0.0.1" && address !== "::1" && address !== "::ffff:127.0.0.1") return false;
+	const host = request.headers.host;
+	if (typeof host !== "string") return false;
+	let hostUrl;
+	try {
+		hostUrl = new URL(`http://${host}`);
+	} catch {
+		return false;
+	}
+	if (hostUrl.hostname !== "127.0.0.1" && hostUrl.hostname !== "localhost" && hostUrl.hostname !== "[::1]") return false;
+	if (request.headers["sec-fetch-site"] === "cross-site") return false;
+	const origin = request.headers.origin;
+	if (origin === void 0) return true;
+	try {
+		return new URL(origin).host === hostUrl.host;
+	} catch {
+		return false;
+	}
+}
+/** One JSON response. */
+function writeJson(res, status, body) {
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"cache-control": "no-store",
+		"referrer-policy": "no-referrer"
+	});
+	res.end(JSON.stringify(body));
+}
+/** Read and parse a JSON request body (undefined when invalid). */
+async function readJsonBody(request) {
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of request) {
+		const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		size += buffer.length;
+		if (size > MAX_JSON_BODY_BYTES) return void 0;
+		chunks.push(buffer);
+	}
+	if (size === 0) return {};
+	try {
+		const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+		return typeof parsed === "object" && parsed !== null ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+/** Ask the helper (via its console port) for its live status. */
+async function fetchHelperJson(url, timeoutMs = 2e3) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const response = await fetch(url, {
+			signal: controller.signal,
+			cache: "no-store"
+		});
+		if (!response.ok) return null;
+		return await response.json();
+	} catch {
+		return null;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/** Build the route list for ctx.webServer.register. */
+function makeRoutes(deps) {
+	const guard = (req, res, method) => {
+		if (!isLoopbackRequest(req)) {
+			writeJson(res, 403, { error: "forbidden: loopback-only" });
+			return false;
+		}
+		if (req.method !== method) {
+			writeJson(res, 405, { error: `method not allowed: ${req.method}` });
+			return false;
+		}
+		return true;
+	};
+	const queryOf = (req) => new URL(req.url ?? "/", "http://127.0.0.1").searchParams;
+	const intParam = (params, key, fallback, min, max) => {
+		const raw = Number(params.get(key) ?? "");
+		if (!Number.isFinite(raw)) return fallback;
+		return Math.max(min, Math.min(max, Math.floor(raw)));
+	};
+	/**
+	* Whether a helper snapshot is about THIS host.
+	*
+	* The plugin home is shared by every DSH instance on the machine, so a fresh
+	* `status.json` with a live helper pid may describe a sibling instance's
+	* restart. A helper names the pid it replaced (`oldPid`) and the pid it
+	* started (`childPid`); one of them being us is the only proof it concerns our
+	* restart — freshness alone is not ownership.
+	*/
+	const belongsToThisHost = (status) => status !== null && (status.oldPid === process.pid || (status.childPid ?? null) === process.pid);
+	/**
+	* Live helper status.
+	*
+	* status.json is authoritative (it carries the helper pid, so a stale file
+	* from an earlier restart is detectable). Only when no live helper is on
+	* record do we probe a console port — and the responder must prove it is
+	* *our* helper for *this* host:
+	*
+	*   1. it identifies as dsh-restart,
+	*   2. it writes the status file belonging to this plugin home, and
+	*   3. it is about this process — either the pid that requested the restart
+	*      (still running, restart in flight) or the pid it launched (we are the
+	*      process it started).
+	*
+	* Without (2) and (3) anything shaped like a helper passes: a leftover helper
+	* from a different test/demo on the fallback port was reported as "the current
+	* restart is failing", which is exactly the kind of lie this surface must not
+	* tell.
+	*/
+	const helperState = async (config) => {
+		const fromFile = await readHelperStatus();
+		if (fromFile.alive && fromFile.status !== null && belongsToThisHost(fromFile.status)) return fromFile;
+		if (fromFile.alive && fromFile.status !== null && !belongsToThisHost(fromFile.status)) return {
+			status: null,
+			alive: false,
+			ageMs: fromFile.ageMs
+		};
+		const reported = fromFile.status?.fallbackPort;
+		const port = typeof reported === "number" && reported > 0 ? reported : config.fallbackPort;
+		const live = await fetchHelperJson(`http://${deps.host}:${port}/status`, 1200);
+		if (live !== null && live.helper === "dsh-restart" && live.statusFile === statusPath() && belongsToThisHost(live)) return {
+			status: live,
+			alive: true,
+			ageMs: 0
+		};
+		return {
+			status: null,
+			alive: false,
+			ageMs: null
+		};
+	};
+	return [
+		{
+			kind: "exact",
+			path: RESTART_API.probe,
+			handler: (req, res) => {
+				if (!isLoopbackRequest(req)) {
+					writeJson(res, 403, { error: "forbidden: loopback-only" });
+					return;
+				}
+				if (req.method !== "GET" && req.method !== "HEAD") {
+					writeJson(res, 405, { error: `method not allowed: ${req.method}` });
+					return;
+				}
+				writeJson(res, 200, {
+					ok: true,
+					pid: process.pid,
+					startedAt: (/* @__PURE__ */ new Date(Date.now() - process.uptime() * 1e3)).toISOString(),
+					uptimeMs: Math.round(process.uptime() * 1e3)
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: RESTART_API.status,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				const { config, exists, file } = await loadConfig();
+				const [host, helper, history, logs, job] = await Promise.all([
+					hostInfo(deps),
+					helperState(config),
+					readHistory(8),
+					listLogs(8),
+					config.restartMode === "helper" ? Promise.resolve(null) : launchdInfo()
+				]);
+				writeJson(res, 200, {
+					ok: true,
+					host,
+					helper: helper.status,
+					helperAlive: helper.alive,
+					helperAgeMs: helper.ageMs,
+					config,
+					configFile: file,
+					configExists: exists,
+					statusFile: statusPath(),
+					consoleUrl: `http://${deps.host}:${config.fallbackPort}`,
+					launchd: job === null ? null : {
+						managed: true,
+						label: job.label,
+						state: job.state,
+						logFile: job.stderrPath !== "" ? job.stderrPath : job.stdoutPath,
+						strategy: config.restartMode === "helper" ? "helper" : "launchd"
+					},
+					history,
+					logFiles: logs,
+					endpoints: RESTART_API
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: RESTART_API.restart,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req) ?? {};
+				const { config } = await loadConfig();
+				const source = typeof body.source === "string" && body.source !== "" ? body.source : "web";
+				const reason = typeof body.reason === "string" ? body.reason : "";
+				const outcome = await requestRestart({
+					config,
+					port: deps.port,
+					host: deps.host,
+					url: deps.url,
+					source,
+					reason
+				});
+				if (!outcome.ok) {
+					writeJson(res, 500, {
+						...outcome,
+						ok: false,
+						error: outcome.error
+					});
+					return;
+				}
+				writeJson(res, 202, {
+					ok: true,
+					helperPid: outcome.helperPid,
+					logFile: outcome.logFile,
+					statusFile: outcome.statusFile,
+					fallbackPort: outcome.fallbackPort,
+					fallbackUrl: outcome.fallbackUrl,
+					exitInMs: outcome.exitInMs,
+					mode: outcome.mode,
+					restartingAt: (/* @__PURE__ */ new Date()).toISOString(),
+					oldPid: process.pid
+				});
+				outcome.commit();
+			}
+		},
+		{
+			kind: "exact",
+			path: RESTART_API.logs,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				const params = queryOf(req);
+				const { config } = await loadConfig();
+				const lines = intParam(params, "lines", config.logLines, 10, 2e3);
+				const which = (params.get("which") ?? "latest").trim();
+				let file;
+				if (which === "latest" || which === "auto") file = await newestLogFile();
+				else if (which === "helper") file = statusPath().replace(/status\.json$/, "pending-spec.json");
+				else file = which.startsWith("/") ? which : null;
+				if (file === null) {
+					writeJson(res, 200, {
+						ok: true,
+						file: "",
+						exists: false,
+						mtime: "",
+						text: "",
+						lines: [],
+						errorLines: [],
+						logFiles: await listLogs(8)
+					});
+					return;
+				}
+				writeJson(res, 200, {
+					ok: true,
+					...await tailFile(file, lines),
+					logFiles: await listLogs(8)
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: RESTART_API.history,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				const { config } = await loadConfig();
+				writeJson(res, 200, {
+					ok: true,
+					history: await readHistory(intParam(queryOf(req), "limit", 20, 1, config.historyLimit))
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: RESTART_API.config,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				if (body === void 0) {
+					writeJson(res, 400, { error: "invalid JSON body" });
+					return;
+				}
+				writeJson(res, 200, {
+					ok: true,
+					config: body.reset === true ? await resetConfig() : await saveConfig(body),
+					configFile: configPath()
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: RESTART_API.helper,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				const { config } = await loadConfig();
+				const state = await helperState(config);
+				writeJson(res, 200, {
+					ok: true,
+					alive: state.alive,
+					ageMs: state.ageMs,
+					consoleUrl: `http://${deps.host}:${config.fallbackPort}`,
+					status: state.status
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: RESTART_API.helperRetry,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const { config } = await loadConfig();
+				const consoleUrl = `http://${deps.host}:${config.fallbackPort}`;
+				const controller = new AbortController();
+				const timer = setTimeout(() => controller.abort(), 2e3);
+				try {
+					writeJson(res, 200, {
+						ok: (await fetch(`${consoleUrl}/retry`, {
+							method: "POST",
+							signal: controller.signal
+						})).ok,
+						consoleUrl
+					});
+				} catch (error) {
+					writeJson(res, 502, {
+						ok: false,
+						error: `无法连接重启控制台 ${consoleUrl}：${String(error?.message ?? error)}`,
+						consoleUrl
+					});
+				} finally {
+					clearTimeout(timer);
+				}
+			}
+		}
+	];
+}
+//#endregion
+//#region src/tools.ts
+/** One text content block (the only render shape these tools emit). */
+function text(value) {
+	return [{
+		type: "text",
+		text: value
+	}];
+}
+/** Render the tool's `message` field. */
+function renderMessage(_args, value) {
+	return text(String(value.message ?? ""));
+}
+/** Clamp a model-supplied integer. */
+function clampInt(value, fallback, min, max) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+	return Math.max(min, Math.min(max, Math.floor(value)));
+}
+/** One-line description of a helper phase. */
+function phaseLine(status) {
+	if (status === null) return "";
+	return `重启助手：${status.phase ?? "unknown"}（第 ${status.attempt ?? 1}/${status.maxAttempts ?? 1} 次尝试${typeof status.elapsedMs === "number" ? `，已 ${(status.elapsedMs / 1e3).toFixed(1)}s` : ""}）`;
+}
+/** Tool: restart status, live helper state, last boot errors. */
+function restartStatusTool(ctx) {
+	return defineTool({
+		name: "dsh_restart_status",
+		description: "查看 DSH 宿主与 dsh-restart 插件的重启状态：宿主 pid/端口/版本/启动时长/启动命令、是否有重启助手在运行（以及它当前处于哪个阶段、上次尝试的失败原因）、最近几次重启记录、以及最近一次启动日志里疑似报错的行。不会重启任何东西。",
+		parameters: { lines: {
+			type: "number",
+			description: "启动日志返回的行数（默认 40，范围 10-400）"
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: {
+						type: "boolean",
+						required: true
+					},
+					message: {
+						type: "string",
+						required: true
+					},
+					pid: { type: "number" },
+					port: { type: "number" },
+					url: { type: "string" },
+					dshVersion: { type: "string" },
+					nodeVersion: { type: "string" },
+					uptimeMs: { type: "number" },
+					command: { type: "string" },
+					helperAlive: { type: "boolean" },
+					helperPhase: { type: "string" },
+					helperFailure: { type: "string" },
+					consoleUrl: { type: "string" },
+					logFile: { type: "string" },
+					errorLines: { type: "array" },
+					history: { type: "array" }
+				}
+			},
+			render: renderMessage
+		},
+		async execute(args) {
+			const lines = clampInt((args ?? {}).lines, 40, 10, 400);
+			const { config } = await loadConfig();
+			const host = await hostInfo(ctx.endpoint);
+			const helper = await readHelperStatus();
+			const logFile = await newestLogFile();
+			const tail = logFile === null ? {
+				file: "",
+				exists: false,
+				errorLines: [],
+				lines: [],
+				text: "",
+				mtime: ""
+			} : await tailFile(logFile, lines);
+			const history = await readHistory(5);
+			const failure = helper.status?.failure?.message ?? "";
+			return {
+				ok: true,
+				message: "dsh-restart：" + [
+					`宿主：pid ${host.pid}，${host.url}，DSH ${host.dshVersion || "未知版本"}，Node ${host.nodeVersion}`,
+					`已运行 ${(host.uptimeMs / 1e3).toFixed(0)}s`,
+					helper.alive ? phaseLine(helper.status) : "当前没有重启助手在运行",
+					failure === "" ? "" : `上次重启失败：${failure}`,
+					tail.exists && tail.errorLines.length > 0 ? `上次启动日志有 ${tail.errorLines.length} 行疑似报错（${tail.file}）` : tail.exists ? "上次启动日志未发现明显报错" : "暂无启动日志"
+				].filter((part) => part !== "").join("；") + "。",
+				pid: host.pid,
+				port: host.port,
+				url: host.url,
+				dshVersion: host.dshVersion,
+				nodeVersion: host.nodeVersion,
+				uptimeMs: host.uptimeMs,
+				command: host.command,
+				helperAlive: helper.alive,
+				helperPhase: helper.status?.phase ?? "",
+				helperFailure: failure,
+				consoleUrl: `http://${ctx.endpoint.host}:${config.fallbackPort}`,
+				logFile: tail.file,
+				errorLines: tail.errorLines.slice(-25),
+				history: history.map((record) => `${record.at} · ${record.source}${record.reason === "" ? "" : "（" + record.reason + "）"} · pid ${record.oldPid} → 助手 ${record.helperPid ?? "—"} · ${record.outcome ?? "unknown"}`)
+			};
+		}
+	});
+}
+/** Tool: restart the host. */
+function restartTool(ctx) {
+	return defineTool({
+		name: "dsh_restart",
+		description: "重启 DSH 宿主（网页端会自动重连并刷新）：把重启交给一个分离的重启助手，它等端口释放后用完全相同的命令重新拉起 DSH，并在此期间提供一个恢复控制台（默认 http://127.0.0.1:3099）显示启动进度与报错。**重启会立即中断当前回合与当前会话的连接**，因此必须先获得用户明确同意再调用，并设置 confirm: true；未确认时本工具只返回提示不执行。安装/更新插件后需要让新代码生效时用本工具。",
+		parameters: {
+			confirm: {
+				type: "boolean",
+				description: "必须为 true 才真正执行（表示已获得用户同意）"
+			},
+			reason: {
+				type: "string",
+				description: "重启原因（会记录进重启历史）"
+			},
+			delayMs: {
+				type: "number",
+				description: "回包后多少毫秒再退出本进程（默认 1500，给当前回合留出落盘时间）"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: {
+						type: "boolean",
+						required: true
+					},
+					message: {
+						type: "string",
+						required: true
+					},
+					helperPid: { type: "number" },
+					logFile: { type: "string" },
+					consoleUrl: { type: "string" },
+					exitInMs: { type: "number" },
+					scheduled: { type: "boolean" }
+				}
+			},
+			render: renderMessage
+		},
+		async execute(args) {
+			const input = args ?? {};
+			if (input.confirm !== true) return {
+				ok: false,
+				scheduled: false,
+				message: "未执行重启：dsh_restart 需要 confirm: true。请先用 ask_user_question（或口头）征得用户明确同意——本机铁律规定未经同意不得重启 DSH。",
+				helperPid: 0,
+				logFile: "",
+				consoleUrl: "",
+				exitInMs: 0
+			};
+			const { config } = await loadConfig();
+			const reason = typeof input.reason === "string" && input.reason !== "" ? input.reason : "agent tool";
+			const exitDelayMs = clampInt(input.delayMs, 1500, 200, 3e4);
+			const outcome = await requestRestart({
+				config,
+				port: ctx.endpoint.port,
+				host: ctx.endpoint.host,
+				url: ctx.endpoint.url,
+				source: "agent",
+				reason,
+				exitDelayMs
+			});
+			if (!outcome.ok) return {
+				ok: false,
+				scheduled: false,
+				message: "重启失败（未执行）：" + outcome.error,
+				helperPid: 0,
+				logFile: outcome.logFile,
+				consoleUrl: outcome.fallbackUrl,
+				exitInMs: 0
+			};
+			outcome.commit();
+			return {
+				ok: true,
+				scheduled: true,
+				message: `已安排重启（原因：${reason}；方式：${outcome.mode === "launchd" ? "launchd 托管重启" : "分离助手自拉起"}）。重启助手 pid ${outcome.helperPid ?? "?"}${outcome.mode === "launchd" ? "，由助手在回包后 kickstart 托管任务" : `，约 ${outcome.exitInMs}ms 后本进程退出`}；新宿主启动日志：${outcome.logFile}；若启动失败，恢复控制台 http://${ctx.endpoint.host}:${outcome.fallbackPort} 会显示报错。当前回合将随进程结束而中断，网页端会自动重连刷新。`,
+				helperPid: outcome.helperPid ?? 0,
+				logFile: outcome.logFile,
+				consoleUrl: outcome.fallbackUrl,
+				exitInMs: outcome.exitInMs
+			};
+		}
+	});
+}
+/** Build the tool roster. */
+function buildTools(ctx) {
+	return [restartStatusTool(ctx), restartTool(ctx)];
+}
+//#endregion
+//#region src/index.ts
+/** Stable cordis plugin name. */
+const name = "dsh-restart";
+/** Services required before the plugin surfaces can mount. */
+const inject = [
+	"tools",
+	"systemPrompt",
+	"webServer"
+];
+/** Order of the announcement section within the tool-guidance band. */
+const SECTION_ORDER = 216;
+/** Model-facing announcement: plugin presence, capabilities, and limits. */
+const RESTART_GUIDANCE = "本机已安装 @zhengjunyao/dsh-restart 插件（一键重启 DSH）：装完/更新插件后不必再去终端重启——Web GUI 侧边栏有「重启」入口、设置页有「重启」卡片，点一下即把重启交给一个**分离的重启助手**（等端口释放后用完全相同的命令重新拉起 DSH），网页会自动重连并刷新；失败时该插件会直接把报错显示出来（页面内置重启遮罩 + 恢复控制台 http://127.0.0.1:3099，含启动日志与检测到的报错行），不必去翻终端日志。Agent 侧工具：dsh_restart_status（查看宿主 pid/端口/版本/启动时长/启动命令、重启助手阶段与失败原因、最近重启记录、上次启动日志里的疑似报错行——只读）、dsh_restart（真正重启，**必须已获得用户明确同意**并传 confirm: true，否则只返回提示不执行；重启会中断当前回合与连接，网页端自动重连）。配置存 ~/.dsh/dsh-restart.json（0600），日志在 ~/.dsh/dsh-restart/logs/。注意：本机铁律规定**未经用户同意不得重启或关闭 DSH**，所以即使装了本插件，也要先问过用户再调用 dsh_restart。用户提到「重启 / 重启一下 / 重启 DSH / 重载插件 / 一键重启」时即指本插件，请据此协作。";
+/**
+* Mount the restart routes, tools and announcement.
+* @param ctx - host plugin context carrying tools/systemPrompt/webServer.
+* @param config - plugin config from the composition row (seeds the JSON file).
+*/
+function apply(ctx, config) {
+	if (!(config?.enabled !== false)) return;
+	seedConfigSync(config ?? {});
+	const announceToAgent = config?.announceToAgent !== false;
+	/**
+	* Live endpoint view. Read through getters: the plugin mounts while the
+	* web server is initialized but the port may only be final once it listens,
+	* and a restart must always target the port actually in use.
+	*/
+	const endpoint = {
+		get port() {
+			const live = ctx.webServer.port;
+			if (Number.isInteger(live) && live > 0) return live;
+			const fromEnv = Number(process.env.DSH_PORT ?? "");
+			return Number.isInteger(fromEnv) && fromEnv > 0 ? fromEnv : 3080;
+		},
+		get host() {
+			return "127.0.0.1";
+		},
+		get url() {
+			return `http://127.0.0.1:${this.port}`;
+		}
+	};
+	ctx.effect(() => {
+		const disposers = makeRoutes(endpoint).map((route) => ctx.webServer.register(route));
+		return () => {
+			for (const dispose of disposers) dispose();
+		};
+	}, "dsh-restart: routes");
+	ctx.effect(() => {
+		const disposers = buildTools({ endpoint }).map((tool) => ctx.tools.register(tool));
+		return () => {
+			for (const dispose of disposers) dispose();
+		};
+	}, "dsh-restart: tools");
+	if (announceToAgent) ctx.effect(() => ctx.systemPrompt.section({
+		name: "plugin:dsh-restart",
+		order: SECTION_ORDER,
+		text: RESTART_GUIDANCE
+	}), "dsh-restart: prompt section");
+}
+//#endregion
+export { DEFAULT_CONFIG, RESTART_API, RESTART_GUIDANCE, appendHistory, apply, buildSpec, buildTools, configPath, detectLaunchd, detectLaunchdFor, ensureLayout, helperPath, historyPath, hostInfo, inject, isAlive, kickCommand, kickstart, labelForPid, launchSignature, launchdInfo, listLogs, loadConfig, loadConfigSync, logsDir, makeRoutes, name, newestLogFile, normalizeConfig, readHelperStatus, readHistory, readLaunchdLog, requestRestart, resetConfig, restartHome, restartStatusTool, restartTool, saveConfig, scheduleSelfExit, seedConfigSync, specPath, statusPath, tailFile };