dsh-update-status 0.3.2 → 0.4.1

package/lib/service-cli.js

@@ -1,344 +1,67 @@
-import { createRequire } from "node:module";
-import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
-import { homedir } from "node:os";
-import { createServer } from "node:net";
+import { _ as parseSystemdMainPid, a as planFor, b as bootStampFile, c as specFromArgs, d as servicePathOf, g as parseLaunchdTrackedPid, i as pathsFor, m as WINDOWS_TASK_NAME, n as nativeServiceCommandCandidates, o as servicePlatform, p as SYSTEMD_UNIT, r as nativeServiceCommandOf, s as serviceStateFileFromArgs, t as SERVICE_LABEL, u as normalizeServicePathExt, v as parseWindowsTaskRunning, w as serviceLogDir, x as countRecentRestarts, y as RESTART_STORM_WINDOW_MS } from "./plan-D9Ybaj-3.js";
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute } from "node:path";
 import { spawnSync } from "node:child_process";
-//#region src/service/plan.ts
-/** Build transparent per-OS user-service definitions; do not install them here. */
-const SERVICE_LABEL = "com.idoall.dsh-update-status.web";
-const SUPERVISOR_MARKER = "dsh-update-status";
-function xml(value) {
-	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
-}
-function systemd(value) {
-	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
-}
-function powerShell(value) {
-	return value.replace(/'/g, "''");
-}
-function boundedPort(value) {
-	const port = typeof value === "number" ? value : Number(value);
-	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("`--port` must be an integer from 1 to 65535");
-	return port;
-}
-function valueAfter(args, flag) {
-	const index = args.indexOf(flag);
-	if (index < 0) return void 0;
-	const value = args[index + 1];
-	if (value === void 0 || value.startsWith("--")) throw new Error(`missing value after ${flag}`);
-	return value;
-}
-/**
-* Resolve the real JS file behind `@deepseek-ai/dsh`'s `bin.dsh`, using the
-* selected profile as a Node resolution anchor. This avoids platform shell
-* shims (`dsh.cmd`) and keeps every native service on `node <absolute-js>`.
-*/
-function dshPathOf(env, profile, dshHome, override) {
-	const fromArg = override?.trim();
-	if (fromArg !== void 0 && fromArg !== "") return isAbsolute(fromArg) ? fromArg : resolve(env.cwd, fromArg);
-	const home = dshHome ?? join(env.home || homedir(), ".dsh");
-	try {
-		const anchor = join(home, "profiles", profile, "dsh-update-status-service-resolver.cjs");
-		const manifestPath = createRequire(anchor).resolve("@deepseek-ai/dsh/package.json");
-		const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-		if (manifest.name !== "@deepseek-ai/dsh" || typeof manifest.bin?.dsh !== "string") throw new Error("invalid dsh package manifest");
-		return realpathSync(join(dirname(manifestPath), manifest.bin.dsh));
-	} catch (error) {
-		throw new Error(`cannot resolve @deepseek-ai/dsh from profile ${profile}; rerun with --dsh /absolute/path/to/lib/bin.js (${error instanceof Error ? error.message : String(error)})`);
-	}
-}
-function servicePlatform(value) {
-	if (value === "darwin" || value === "linux" || value === "win32") return value;
-	throw new Error(`unsupported platform: ${value}; supported: macOS, Linux, Windows`);
-}
-function specFromArgs(args, env) {
-	const platform = servicePlatform(env.platform);
-	const profile = valueAfter(args, "--profile") ?? env.env.DSH_PROFILE ?? "web";
-	const workspace = valueAfter(args, "--workspace");
-	if (workspace === void 0) throw new Error("`--workspace` is required and must be the absolute directory DSH should use");
-	const host = valueAfter(args, "--host") ?? "127.0.0.1";
-	const port = boundedPort(valueAfter(args, "--port") ?? 3080);
-	const home = env.home || homedir();
-	const dshHome = valueAfter(args, "--dsh-home") ?? (env.env.DSH_HOME?.trim() || void 0);
-	if (dshHome !== void 0 && !isAbsolute(dshHome)) throw new Error("`--dsh-home` must be an absolute path");
-	const logDir = valueAfter(args, "--log-dir") ?? join(dshHome ?? join(home, ".dsh"), "logs");
-	const dshPath = dshPathOf(env, profile, dshHome, valueAfter(args, "--dsh"));
-	const nodePath = valueAfter(args, "--node") ?? env.execPath;
-	if (!isAbsolute(nodePath)) throw new Error("`--node` must be an absolute executable path");
-	if (!isAbsolute(dshPath)) throw new Error("`--dsh` must be an absolute executable path");
-	if (!isAbsolute(workspace)) throw new Error("`--workspace` must be an absolute path");
-	if (!isAbsolute(logDir)) throw new Error("`--log-dir` must be an absolute path");
-	return {
-		schemaVersion: 1,
-		platform,
-		label: SERVICE_LABEL,
-		nodePath,
-		dshPath,
-		profile,
-		workspace,
-		host,
-		port,
-		home,
-		...dshHome === void 0 ? {} : { dshHome },
-		logDir,
-		supervisorMarker: SUPERVISOR_MARKER
-	};
-}
-function pathsFor(spec) {
-	const root = spec.dshHome ?? join(spec.home, ".dsh");
-	const stdoutFile = join(spec.logDir, "dsh-web-service.stdout.log");
-	const stderrFile = join(spec.logDir, "dsh-web-service.stderr.log");
-	if (spec.platform === "darwin") return {
-		stateFile: join(root, "dsh-update-status-service.json"),
-		definitionFile: join(spec.home, "Library", "LaunchAgents", `${spec.label}.plist`),
-		stdoutFile,
-		stderrFile
-	};
-	if (spec.platform === "linux") return {
-		stateFile: join(root, "dsh-update-status-service.json"),
-		definitionFile: join(spec.home, ".config", "systemd", "user", "dsh-update-status-web.service"),
-		stdoutFile,
-		stderrFile
-	};
-	const base = envLocalAppData(spec);
-	return {
-		stateFile: join(root, "dsh-update-status-service.json"),
-		definitionFile: join(base, "dsh-update-status", "dsh-web-task.xml"),
-		wrapperFile: join(base, "dsh-update-status", "dsh-web-supervisor.ps1"),
-		stdoutFile,
-		stderrFile
-	};
-}
-function envLocalAppData(spec) {
-	return join(spec.home, "AppData", "Local");
-}
-function webArguments(spec) {
-	return [
-		spec.dshPath,
-		"--profile",
-		spec.profile,
-		"--host",
-		spec.host,
-		"--port",
-		String(spec.port),
-		"--no-open"
-	];
-}
-function launchdDefinition(spec, paths) {
-	const args = [spec.nodePath, ...webArguments(spec)].map((value) => `    <string>${xml(value)}</string>`).join("\n");
-	const envXml = [
-		["HOME", spec.home],
-		["PATH", `${dirname(spec.nodePath)}:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`],
-		["DSH_WEB_SUPERVISOR", spec.supervisorMarker],
-		...spec.dshHome === void 0 ? [] : [["DSH_HOME", spec.dshHome]]
-	].map(([key, value]) => `    <key>${xml(key)}</key>\n    <string>${xml(value)}</string>`).join("\n");
-	return `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key>
-  <string>${xml(spec.label)}</string>
-  <key>ProgramArguments</key>
-  <array>
-${args}
-  </array>
-  <key>WorkingDirectory</key>
-  <string>${xml(spec.workspace)}</string>
-  <key>RunAtLoad</key>
-  <true/>
-  <key>KeepAlive</key>
-  <true/>
-  <key>ThrottleInterval</key>
-  <integer>3</integer>
-  <key>EnvironmentVariables</key>
-  <dict>
-${envXml}
-  </dict>
-  <key>StandardOutPath</key>
-  <string>${xml(paths.stdoutFile)}</string>
-  <key>StandardErrorPath</key>
-  <string>${xml(paths.stderrFile)}</string>
-</dict>
-</plist>
-`;
-}
-function systemdDefinition(spec) {
-	const command = [spec.nodePath, ...webArguments(spec)].map((value) => `"${systemd(value)}"`).join(" ");
-	const env = [
-		`Environment="HOME=${systemd(spec.home)}"`,
-		`Environment="PATH=${systemd(`${dirname(spec.nodePath)}:/usr/local/bin:/usr/bin:/bin`)}"`,
-		`Environment="DSH_WEB_SUPERVISOR=${spec.supervisorMarker}"`,
-		...spec.dshHome === void 0 ? [] : [`Environment="DSH_HOME=${systemd(spec.dshHome)}"`]
-	].join("\n");
-	return `[Unit]
-Description=DSH Web managed by dsh-update-status
-After=network-online.target
-
-[Service]
-Type=simple
-WorkingDirectory="${systemd(spec.workspace)}"
-${env}
-ExecStart=${command}
-Restart=on-failure
-RestartSec=3
-
-[Install]
-WantedBy=default.target
-`;
-}
-function windowsWrapper(spec, paths) {
-	const node = powerShell(spec.nodePath);
-	const dsh = powerShell(spec.dshPath);
-	const workspace = powerShell(spec.workspace);
-	const out = powerShell(paths.stdoutFile);
-	const err = powerShell(paths.stderrFile);
-	const home = powerShell(spec.home);
-	const dshHome = spec.dshHome === void 0 ? "" : `$env:DSH_HOME = '${powerShell(spec.dshHome)}'\n`;
-	return `$ErrorActionPreference = 'Stop'
-$env:HOME = '${home}'
-$env:DSH_WEB_SUPERVISOR = '${spec.supervisorMarker}'
-${dshHome}Set-Location -LiteralPath '${workspace}'
-while ($true) {
-  & '${node}' '${dsh}' --profile '${powerShell(spec.profile)}' --host '${powerShell(spec.host)}' --port '${String(spec.port)}' --no-open 1>> '${out}' 2>> '${err}'
-  $exitCode = $LASTEXITCODE
-  Start-Sleep -Seconds 3
-  # The user service owns deliberate restarts (exit 42) and unexpected exits.
-  # Manual uninstall stops the scheduled task, which ends this wrapper.
-}
-`;
-}
-function windowsDefinition(spec, paths) {
-	const wrapper = paths.wrapperFile;
-	if (wrapper === void 0) throw new Error("Windows service plan requires a wrapper path");
-	return `<?xml version="1.0" encoding="UTF-8"?>
-<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
-  <RegistrationInfo><Description>DSH Web managed by dsh-update-status</Description></RegistrationInfo>
-  <Triggers><LogonTrigger><Enabled>true</Enabled></LogonTrigger></Triggers>
-  <Principals><Principal id="Author"><LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals>
-  <Settings><MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy><StartWhenAvailable>true</StartWhenAvailable><ExecutionTimeLimit>PT0S</ExecutionTimeLimit></Settings>
-  <Actions Context="Author"><Exec><Command>powershell.exe</Command><Arguments>-NoProfile -ExecutionPolicy Bypass -File &quot;${xml(wrapper)}&quot;</Arguments></Exec></Actions>
-</Task>
-`;
-}
-/** Generate a service plan without writing, starting, or stopping anything. */
-function planFor(spec, uid = 0) {
-	const paths = pathsFor(spec);
+import { createServer } from "node:net";
+async function observeServiceState(spec, run, uid) {
 	if (spec.platform === "darwin") {
-		const domain = `gui/${uid}`;
-		return {
-			spec,
-			paths,
-			definition: launchdDefinition(spec, paths),
-			installCommand: [
-				"launchctl",
-				"bootstrap",
-				domain,
-				paths.definitionFile
-			],
-			startCommand: [
-				"launchctl",
-				"kickstart",
-				"-k",
-				`${domain}/${spec.label}`
-			],
-			statusCommand: [
-				"launchctl",
-				"print",
-				`${domain}/${spec.label}`
-			],
-			stopCommand: [
-				"launchctl",
-				"bootout",
-				`${domain}/${spec.label}`
-			],
-			uninstallCommand: [
-				"launchctl",
-				"bootout",
-				`${domain}/${spec.label}`
-			]
+		const result = run("launchctl", ["print", `gui/${String(uid)}/${spec.label}`]);
+		const pid = parseLaunchdTrackedPid(result.stdout);
+		return pid === void 0 ? { running: false } : {
+			running: true,
+			pid
 		};
 	}
-	if (spec.platform === "linux") return {
-		spec,
-		paths,
-		definition: systemdDefinition(spec),
-		installCommand: [
-			"systemctl",
-			"--user",
-			"daemon-reload"
-		],
-		startCommand: [
-			"systemctl",
-			"--user",
-			"enable",
-			"--now",
-			"dsh-update-status-web.service"
-		],
-		statusCommand: [
-			"systemctl",
-			"--user",
-			"status",
-			"dsh-update-status-web.service"
-		],
-		stopCommand: [
-			"systemctl",
-			"--user",
-			"disable",
-			"--now",
-			"dsh-update-status-web.service"
-		],
-		uninstallCommand: [
-			"systemctl",
+	if (spec.platform === "linux") {
+		const result = run("systemctl", [
 			"--user",
-			"disable",
-			"--now",
-			"dsh-update-status-web.service"
-		]
-	};
-	return {
-		spec,
-		paths,
-		definition: windowsDefinition(spec, paths),
-		wrapper: windowsWrapper(spec, paths),
-		installCommand: [
-			"schtasks.exe",
-			"/Create",
-			"/TN",
-			"DSH Update Status Web",
-			"/XML",
-			paths.definitionFile,
-			"/F"
-		],
-		startCommand: [
-			"schtasks.exe",
-			"/Run",
-			"/TN",
-			"DSH Update Status Web"
-		],
-		statusCommand: [
-			"schtasks.exe",
-			"/Query",
-			"/TN",
-			"DSH Update Status Web",
-			"/V",
-			"/FO",
-			"LIST"
-		],
-		stopCommand: [
-			"schtasks.exe",
-			"/End",
-			"/TN",
-			"DSH Update Status Web"
-		],
-		uninstallCommand: [
-			"schtasks.exe",
-			"/Delete",
-			"/TN",
-			"DSH Update Status Web",
-			"/F"
-		]
-	};
+			"show",
+			SYSTEMD_UNIT,
+			"-p",
+			"MainPID",
+			"--value"
+		]);
+		const pid = parseSystemdMainPid(result.stdout);
+		return pid === void 0 ? { running: false } : {
+			running: true,
+			pid
+		};
+	}
+	const result = run("powershell.exe", [
+		"-NoProfile",
+		"-NonInteractive",
+		"-Command",
+		`(Get-ScheduledTask -TaskName '${WINDOWS_TASK_NAME}').State`
+	]);
+	return { running: parseWindowsTaskRunning(result.stdout) };
+}
+function defaultSleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+async function verifyActivatedService(spec, options) {
+	const attempts = options.attempts ?? 4;
+	const intervalMs = options.intervalMs ?? 5e3;
+	const sleep = options.sleep ?? defaultSleep;
+	const uid = options.uid ?? 0;
+	const recentRestarts = options.recentRestarts ?? (() => countRecentRestarts(serviceLogDir(), bootStampFile(), Date.now(), 18e4));
+	for (let attempt = 0; attempt < attempts; attempt += 1) {
+		const restarts = recentRestarts();
+		if (restarts >= 4) return {
+			kind: "crash-loop",
+			recentRestarts: restarts,
+			windowMs: RESTART_STORM_WINDOW_MS
+		};
+		if ((await observeServiceState(spec, options.run, uid)).running) {
+			if (attempt === attempts - 1) return { kind: "settled" };
+			await sleep(intervalMs);
+			continue;
+		}
+		if (attempt === attempts - 1) return { kind: "not-running" };
+		await sleep(intervalMs);
+	}
+	return { kind: "not-running" };
 }
 //#endregion
 //#region src/service/cli.ts
@@ -380,14 +103,25 @@ Options:
   --host <127.0.0.1|0.0.0.0>  Bind host (default: 127.0.0.1)
   --port <1..65535>      Web port (default: 3080)
   --node <path>          Absolute Node executable (default: current Node)
-  --dsh <path>           Absolute dsh executable (default: resolve from PATH)
+  --dsh <path>           Absolute dsh executable (default: resolve from profile)
   --log-dir <path>       Absolute log directory (default: $DSH_HOME/logs)
+  --path-source <mode>   Service PATH source: current (default), minimal, explicit
+  --service-path <value> Explicit PATH (implies --path-source explicit)
+  --service-pathext <v>  Windows PATHEXT override (for example .COM;.EXE;.CMD)
+
+current snapshots this command's PATH; it never executes your shell startup files.
+The final PATH, source, capture time and warnings are stored in the receipt and
+reused by preflight and every later service action.
 
 Workflow: plan --dry-run → install → stop the terminal-started DSH yourself → activate.
+
+activate refuses an occupied port, never kills a process, and then verifies that
+the service it started actually took over; a service that begins crash-looping
+makes activate fail instead of reporting success.
 `;
 }
 function assertSafeText(value, description) {
-	if (/[\u0000\r\n]/.test(value)) throw new Error(`${description} must not contain NUL or line breaks`);
+	if (/[\u0000-\u0008\u000A-\u001F\u007F]/.test(value)) throw new Error(`${description} must not contain XML-illegal control characters or line breaks`);
 }
 function assertReadableRegular(path, description) {
 	assertSafeText(path, description);
@@ -408,20 +142,73 @@ function assertExecutable(path, description) {
 		throw new Error(`${description} is not executable: ${path}`);
 	}
 }
-function validateSpec(spec) {
+function envValue(env, key) {
+	return Object.entries(env).find(([name]) => name.toLowerCase() === key.toLowerCase())?.[1];
+}
+function validateSpec(spec, level = "launch", expectedPlatform, expectedHome, expectedSystemRoot) {
+	if (spec.schemaVersion !== 1) throw new Error("managed service receipt has an unsupported schema version");
+	if (spec.platform !== "darwin" && spec.platform !== "linux" && spec.platform !== "win32") throw new Error("managed service receipt has an invalid platform");
+	if (expectedPlatform !== void 0 && spec.platform !== expectedPlatform) throw new Error("managed service receipt belongs to a different platform");
+	if (spec.label !== SERVICE_LABEL || spec.supervisorMarker !== "dsh-update-status") throw new Error("managed service receipt has an unexpected service identity");
+	if (expectedHome !== void 0 && spec.home !== expectedHome) throw new Error("managed service receipt belongs to a different home directory");
 	for (const [description, value] of [
 		["profile", spec.profile],
 		["workspace", spec.workspace],
 		["home", spec.home],
 		["log directory", spec.logDir],
-		["host", spec.host]
-	]) assertSafeText(value, description);
+		["host", spec.host],
+		["Node executable", spec.nodePath],
+		["dsh executable", spec.dshPath]
+	]) {
+		if (typeof value !== "string") throw new Error(`managed service receipt has an invalid ${description}`);
+		assertSafeText(value, description);
+	}
+	for (const [description, value] of [
+		["workspace", spec.workspace],
+		["home", spec.home],
+		["log directory", spec.logDir],
+		["Node executable", spec.nodePath],
+		["dsh executable", spec.dshPath]
+	]) if (!isAbsolute(value)) throw new Error(`managed service receipt has a non-absolute ${description}`);
+	if (spec.dshHome !== void 0) {
+		if (typeof spec.dshHome !== "string") throw new Error("managed service receipt has an invalid DSH_HOME");
+		assertSafeText(spec.dshHome, "DSH_HOME");
+		if (!isAbsolute(spec.dshHome)) throw new Error("managed service receipt has a non-absolute DSH_HOME");
+	}
+	if (!Number.isInteger(spec.port) || spec.port < 1 || spec.port > 65535) throw new Error("managed service receipt has an invalid port");
+	if (spec.servicePath !== void 0 && typeof spec.servicePath !== "string") throw new Error("managed service receipt has an invalid service PATH");
+	if (spec.servicePathSource !== void 0 && spec.servicePathSource !== "current" && spec.servicePathSource !== "minimal" && spec.servicePathSource !== "explicit") throw new Error("managed service receipt has an invalid service PATH source");
+	if (spec.servicePathCapturedAt !== void 0 && (typeof spec.servicePathCapturedAt !== "string" || Number.isNaN(Date.parse(spec.servicePathCapturedAt)))) throw new Error("managed service receipt has an invalid service PATH capture time");
+	if (spec.servicePathExt !== void 0 && typeof spec.servicePathExt !== "string") throw new Error("managed service receipt has an invalid PATHEXT");
+	if (spec.servicePathWarnings !== void 0 && (!Array.isArray(spec.servicePathWarnings) || spec.servicePathWarnings.length > 256 || spec.servicePathWarnings.some((value) => typeof value !== "string"))) throw new Error("managed service receipt has invalid service PATH warnings");
+	if (spec.servicePath === void 0 && (spec.servicePathSource !== void 0 || spec.servicePathCapturedAt !== void 0 || spec.servicePathExt !== void 0 || spec.servicePathWarnings !== void 0)) throw new Error("managed service receipt has PATH metadata without a service PATH");
+	if (spec.servicePath !== void 0 && (spec.servicePathSource === void 0 || spec.servicePathCapturedAt === void 0)) throw new Error("managed service receipt has an incomplete service PATH record");
+	if (spec.platform === "win32" && spec.servicePath !== void 0 && spec.servicePathExt === void 0) throw new Error("managed Windows service receipt has no PATHEXT");
+	if (spec.platform !== "win32" && spec.servicePathExt !== void 0) throw new Error("managed non-Windows service receipt has PATHEXT");
+	if (spec.nativeServiceCommand !== void 0 && typeof spec.nativeServiceCommand !== "string") throw new Error("managed service receipt has an invalid native service command");
+	const servicePath = servicePathOf(spec);
+	assertSafeText(servicePath, "service PATH");
+	if (servicePath.length > 8192) throw new Error("managed service receipt has an overlong service PATH");
+	if (spec.servicePathExt !== void 0) {
+		assertSafeText(spec.servicePathExt, "PATHEXT");
+		if (spec.servicePathExt.length > 8192) throw new Error("managed service receipt has an overlong PATHEXT");
+		normalizeServicePathExt(spec.servicePathExt);
+	}
+	for (const warning of spec.servicePathWarnings ?? []) assertSafeText(warning, "service PATH warning");
+	const nativeCommand = nativeServiceCommandOf(spec);
+	assertSafeText(nativeCommand, "native service command");
+	if (!isAbsolute(nativeCommand)) throw new Error("managed service receipt has a non-absolute native service command");
+	const allowedNativeCommands = nativeServiceCommandCandidates(spec.platform, expectedSystemRoot);
+	const nativeKey = spec.platform === "win32" ? nativeCommand.toLowerCase() : nativeCommand;
+	if (!allowedNativeCommands.some((candidate) => (spec.platform === "win32" ? candidate.toLowerCase() : candidate) === nativeKey)) throw new Error("managed service receipt has an unexpected native service command");
 	if (spec.host !== "127.0.0.1" && spec.host !== "0.0.0.0") throw new Error("`--host` must be 127.0.0.1 or 0.0.0.0");
 	if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(spec.profile)) throw new Error("`--profile` must contain only letters, numbers, dot, underscore, or hyphen");
-	assertExecutable(spec.nodePath, "Node executable");
-	assertReadableRegular(spec.dshPath, "dsh executable");
-	assertSafeText(spec.workspace, "workspace");
-	if (!existsSync(spec.workspace) || !statSync(spec.workspace).isDirectory()) throw new Error(`workspace is not a directory: ${spec.workspace}`);
+	if (level === "launch") {
+		assertExecutable(spec.nodePath, "Node executable");
+		assertReadableRegular(spec.dshPath, "dsh executable");
+		assertExecutable(nativeCommand, "Native service command");
+		if (!existsSync(spec.workspace) || !statSync(spec.workspace).isDirectory()) throw new Error(`workspace is not a directory: ${spec.workspace}`);
+	}
 }
 function atomicWrite(path, content) {
 	mkdirSync(dirname(path), {
@@ -435,7 +222,14 @@ function atomicWrite(path, content) {
 	});
 	renameSync(temporary, path);
 }
-function ensureManagedTarget(path, expected) {
+/**
+* Replace an artifact only when we can prove we wrote it: either it already holds
+* exactly what we are about to write, or our own receipt names that path. The
+* receipt is what makes an upgrade possible at all — an improved definition
+* differs from the stored one by exactly the fix being installed, so
+* byte-equality with the previous rendering can never authorise it.
+*/
+function ensureReplaceable(path, expected, managed) {
 	if (!existsSync(path)) return;
 	let current;
 	try {
@@ -443,13 +237,36 @@ function ensureManagedTarget(path, expected) {
 	} catch {
 		throw new Error(`refusing to replace unreadable existing file: ${path}`);
 	}
-	if (current !== expected) throw new Error(`refusing to overwrite an existing unmanaged service artifact: ${path}`);
+	if (current === expected || managed) return;
+	throw new Error(`refusing to overwrite an existing unmanaged service artifact: ${path}`);
+}
+function receiptOwnsPath(previous, path) {
+	if (previous === void 0) return false;
+	const owned = pathsFor(previous.spec);
+	return owned.definitionFile === path || owned.stateFile === path || owned.wrapperFile === path;
+}
+function receiptTextOf(receipt) {
+	return JSON.stringify(receipt, null, 2) + "\n";
+}
+function samePaths(left, right) {
+	return left.stateFile === right.stateFile && left.definitionFile === right.definitionFile && left.wrapperFile === right.wrapperFile && left.stdoutFile === right.stdoutFile && left.stderrFile === right.stderrFile;
+}
+function readReceiptIfPresent(path, env) {
+	return existsSync(path) ? readReceipt(path, env) : void 0;
 }
-function readReceipt(path) {
+function readReceipt(path, env) {
 	try {
 		const value = JSON.parse(readFileSync(path, "utf8"));
 		if (value.version !== RECEIPT_VERSION || value.managedBy !== "dsh-update-status" || value.spec === void 0 || value.paths === void 0) throw new Error("not a dsh-update-status service receipt");
-		return value;
+		validateSpec(value.spec, "structural", servicePlatform(env.platform), env.home, envValue(env.env, "SYSTEMROOT"));
+		const canonical = pathsFor(value.spec);
+		if (canonical.stateFile !== path || !samePaths(value.paths, canonical)) throw new Error("managed service receipt paths do not match its service spec");
+		return {
+			version: RECEIPT_VERSION,
+			managedBy: "dsh-update-status",
+			spec: value.spec,
+			paths: canonical
+		};
 	} catch (error) {
 		throw new Error(`cannot read managed service receipt ${path}: ${error instanceof Error ? error.message : String(error)}`);
 	}
@@ -462,6 +279,7 @@ async function portIsFree(host, port) {
 	});
 }
 function serialisePlan(plan) {
+	const inheritedWindowsPath = plan.spec.platform === "win32" && plan.spec.servicePath === void 0;
 	return JSON.stringify({
 		platform: plan.spec.platform,
 		label: plan.spec.label,
@@ -471,6 +289,14 @@ function serialisePlan(plan) {
 		workspace: plan.spec.workspace,
 		host: plan.spec.host,
 		port: plan.spec.port,
+		nativeServiceCommand: nativeServiceCommandOf(plan.spec),
+		servicePath: {
+			source: inheritedWindowsPath ? "inherited logon environment (legacy receipt)" : plan.spec.servicePathSource ?? "minimal (legacy receipt)",
+			value: inheritedWindowsPath ? null : servicePathOf(plan.spec),
+			...plan.spec.servicePathCapturedAt === void 0 ? {} : { capturedAt: plan.spec.servicePathCapturedAt },
+			...plan.spec.servicePathExt === void 0 ? {} : { pathExt: plan.spec.servicePathExt },
+			warnings: plan.spec.servicePathWarnings ?? []
+		},
 		definitionFile: plan.paths.definitionFile,
 		wrapperFile: plan.paths.wrapperFile,
 		stateFile: plan.paths.stateFile,
@@ -483,42 +309,14 @@ function serialisePlan(plan) {
 			start: plan.startCommand,
 			status: plan.statusCommand,
 			stop: plan.stopCommand,
-			uninstall: plan.uninstallCommand
+			uninstall: plan.uninstallCommand,
+			recover: plan.recoverCommand
 		}
 	}, null, 2) + "\n";
 }
-function commandsForActivate(plan, uid) {
-	if (plan.spec.platform === "darwin") return [[
-		"launchctl",
-		"bootstrap",
-		`gui/${uid}`,
-		plan.paths.definitionFile
-	]];
-	if (plan.spec.platform === "linux") return [[
-		"systemctl",
-		"--user",
-		"daemon-reload"
-	], [
-		"systemctl",
-		"--user",
-		"enable",
-		"--now",
-		"dsh-update-status-web.service"
-	]];
-	return [[
-		"schtasks.exe",
-		"/Create",
-		"/TN",
-		"DSH Update Status Web",
-		"/XML",
-		plan.paths.definitionFile,
-		"/F"
-	], [
-		"schtasks.exe",
-		"/Run",
-		"/TN",
-		"DSH Update Status Web"
-	]];
+function commandsForActivate(plan, _uid) {
+	if (plan.spec.platform === "darwin") return [plan.installCommand];
+	return [plan.installCommand, plan.startCommand];
 }
 function invoke(command, run) {
 	const [file, ...args] = command;
@@ -540,7 +338,8 @@ function preflight(spec) {
 		env: {
 			HOME: spec.home,
 			...spec.dshHome === void 0 ? {} : { DSH_HOME: spec.dshHome },
-			PATH: `${dirname(spec.nodePath)}${process.platform === "win32" ? ";" : ":"}${process.env.PATH ?? ""}`
+			PATH: servicePathOf(spec),
+			...spec.platform === "win32" && spec.servicePathExt !== void 0 ? { PATHEXT: spec.servicePathExt } : {}
 		}
 	});
 	if (result.status !== 0) {
@@ -548,6 +347,32 @@ function preflight(spec) {
 		throw new Error(`DSH boot-free preflight failed; no service definition was written: ${diagnostic}`);
 	}
 }
+const VALUE_OPTIONS = /* @__PURE__ */ new Set([
+	"--profile",
+	"--workspace",
+	"--dsh-home",
+	"--host",
+	"--port",
+	"--node",
+	"--dsh",
+	"--log-dir",
+	"--path-source",
+	"--service-path",
+	"--service-pathext"
+]);
+function assertKnownOptions(args) {
+	for (let index = 0; index < args.length; index += 1) {
+		const value = args[index];
+		if (value === "--dry-run") continue;
+		if (!VALUE_OPTIONS.has(value)) throw new Error(`unknown option: ${value}`);
+		const next = args[index + 1];
+		if (next === void 0 || next.startsWith("--")) throw new Error(`missing value after ${value}`);
+		index += 1;
+	}
+}
+function warnAboutPath(spec) {
+	for (const warning of spec.servicePathWarnings ?? []) process.stderr.write(`Warning: ${warning}\n`);
+}
 async function main(argv = process.argv.slice(2), env = environment(), run = runner, hooks = {}) {
 	const [action, ...rawArgs] = argv;
 	if (action === void 0 || action === "--help" || action === "-h") {
@@ -565,28 +390,36 @@ async function main(argv = process.argv.slice(2), env = environment(), run = run
 		process.stderr.write(`Unknown command: ${action}\n${usage()}`);
 		return 2;
 	}
+	try {
+		assertKnownOptions(rawArgs);
+	} catch (error) {
+		process.stderr.write(`dsh-update-status-service: ${error instanceof Error ? error.message : String(error)}\n`);
+		return 2;
+	}
 	const dryRun = rawArgs.includes("--dry-run") || action === "plan";
 	const args = rawArgs.filter((value) => value !== "--dry-run");
 	try {
-		const spec = specFromArgs(args, env);
-		validateSpec(spec);
-		const plan = planFor(spec, env.uid ?? 0);
-		if (dryRun) {
-			process.stdout.write(serialisePlan(plan));
-			return 0;
-		}
-		if (action === "install") {
+		if (dryRun || action === "install") {
+			const spec = specFromArgs(args, env);
+			validateSpec(spec, "launch", servicePlatform(env.platform), env.home, envValue(env.env, "SYSTEMROOT"));
+			const plan = planFor(spec, env.uid ?? 0);
+			if (dryRun) {
+				process.stdout.write(serialisePlan(plan));
+				return 0;
+			}
+			process.stdout.write(`Service PATH (${spec.servicePathSource ?? "minimal"}): ${servicePathOf(spec)}\n`);
+			warnAboutPath(spec);
 			(hooks.preflight ?? preflight)(spec);
-			ensureManagedTarget(plan.paths.definitionFile, plan.definition);
-			if (plan.wrapper !== void 0 && plan.paths.wrapperFile !== void 0) ensureManagedTarget(plan.paths.wrapperFile, plan.wrapper);
-			const receipt = {
+			const previous = readReceiptIfPresent(plan.paths.stateFile, env);
+			ensureReplaceable(plan.paths.definitionFile, plan.definition, receiptOwnsPath(previous, plan.paths.definitionFile));
+			if (plan.wrapper !== void 0 && plan.paths.wrapperFile !== void 0) ensureReplaceable(plan.paths.wrapperFile, plan.wrapper, receiptOwnsPath(previous, plan.paths.wrapperFile));
+			const receiptText = receiptTextOf({
 				version: RECEIPT_VERSION,
 				managedBy: "dsh-update-status",
 				spec,
 				paths: plan.paths
-			};
-			const receiptText = JSON.stringify(receipt, null, 2) + "\n";
-			ensureManagedTarget(plan.paths.stateFile, receiptText);
+			});
+			ensureReplaceable(plan.paths.stateFile, receiptText, receiptOwnsPath(previous, plan.paths.stateFile));
 			mkdirSync(spec.logDir, {
 				recursive: true,
 				mode: 448
@@ -597,11 +430,19 @@ async function main(argv = process.argv.slice(2), env = environment(), run = run
 			process.stdout.write(`Staged user service definition: ${plan.paths.definitionFile}\nNo service has started. Stop your terminal-started DSH, then run activate.\n`);
 			return 0;
 		}
-		const receipt = readReceipt(plan.paths.stateFile);
+		const receipt = readReceipt(serviceStateFileFromArgs(args, env), env);
+		const plan = planFor(receipt.spec, env.uid ?? 0);
+		if (action === "activate") validateSpec(receipt.spec, "launch", servicePlatform(env.platform), env.home, envValue(env.env, "SYSTEMROOT"));
 		if (action === "activate") {
 			if (!await portIsFree(receipt.spec.host, receipt.spec.port)) throw new Error(`port ${receipt.spec.host}:${String(receipt.spec.port)} is in use; stop the existing DSH yourself before activate. Nothing was killed.`);
 			for (const command of commandsForActivate(plan, env.uid ?? 0)) invoke(command, run);
-			process.stdout.write("User service activated. Wait for DSH to become ready, then open the existing Web URL.\n");
+			const verification = await (hooks.verify ?? ((installed) => verifyActivatedService(installed, {
+				run,
+				uid: env.uid ?? 0
+			})))(receipt.spec);
+			if (verification.kind === "crash-loop") throw new Error(`the activated service is restarting repeatedly (${String(verification.recentRestarts)} starts within ${String(Math.round(verification.windowMs / 1e3))}s); another process probably holds ${receipt.spec.host}:${String(receipt.spec.port)}. Nothing was killed. Stop that instance, fix the cause, then run activate again.`);
+			if (verification.kind === "not-running") throw new Error(`the activated service reported no running process; check the native status and the logs in ${receipt.spec.logDir}. Nothing was killed.`);
+			process.stdout.write("User service activated and verified to be running. Wait for DSH to become ready, then open the existing Web URL.\n");
 			return 0;
 		}
 		if (action === "status") {
@@ -617,9 +458,9 @@ async function main(argv = process.argv.slice(2), env = environment(), run = run
 		}
 		const result = run(plan.uninstallCommand[0], plan.uninstallCommand.slice(1));
 		if (result.status !== 0) process.stderr.write(`Warning: ${result.stderr || result.stdout || "service was not loaded"}\n`);
-		rmSync(receipt.paths.definitionFile, { force: true });
-		if (receipt.paths.wrapperFile !== void 0) rmSync(receipt.paths.wrapperFile, { force: true });
-		rmSync(receipt.paths.stateFile, { force: true });
+		rmSync(plan.paths.definitionFile, { force: true });
+		if (plan.paths.wrapperFile !== void 0) rmSync(plan.paths.wrapperFile, { force: true });
+		rmSync(plan.paths.stateFile, { force: true });
 		process.stdout.write("Removed the managed user-service definition. Logs were preserved.\n");
 		return 0;
 	} catch (error) {
@@ -631,4 +472,4 @@ if (import.meta.url === new URL(process.argv[1] ?? "", "file:").href) main().the
 	process.exitCode = code;
 });
 //#endregion
-export { main };
+export { main, serialisePlan };