dsh-update-status 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project are documented here.
 
+## 0.4.1 — 2026-10-09
+
+Verified DeepSeek Harness: `0.2.1-alpha.1` (the current release, and the one this profile runs), also `0.2.0-rc.2`, `0.2.0-rc.1`, `0.1.7-rc.2`, `0.1.7-rc.1` and `0.1.7-alpha.2`. Release notes: [`docs/releases/v0.4.1.md`](docs/releases/v0.4.1.md).
+
+- **The service definition now uses one audited, cross-platform PATH instead of package-manager guesses.** `install` snapshots its current PATH by default, puts the selected Node directory first, removes empty/relative/duplicate entries, keeps missing absolute directories with warnings, and persists the final value, source, capture time, PATHEXT (Windows) and warnings in the receipt. `--path-source minimal` preserves a fixed deployment, while `--service-path` supplies an explicit value. macOS launchd, Linux systemd and the Windows wrapper consume that same persisted result; preflight uses it too, and later actions locate the receipt from DSH_HOME instead of recapturing a different terminal environment. `plan --dry-run` prints the exact PATH and warnings. Old receipts retain their historical behaviour (macOS/Linux minimal PATH; Windows Task Scheduler login environment). Tests cover POSIX/Windows separators, drive/UNC/Unicode/quoted paths, PATHEXT, systemd percent escaping, warnings, length limits, native command discovery and lifecycle persistence; only macOS receives native service verification in this environment.
+- **Receipt-backed lifecycle operations are safer and independent of the invoking terminal.** The receipt persists an absolute launchctl/systemctl/schtasks path; later actions never search the caller's PATH. Status, stop and uninstall need only DSH_HOME and continue to work after the old Node/DSH/workspace was moved or deleted, while activate still requires usable launch files. Stored artifact paths must exactly match paths re-derived from the fixed service identity, platform and current home; uninstall deletes only those canonical paths, so a modified receipt cannot nominate an arbitrary file. Unknown options are rejected, XML-illegal control characters and overlong PATH/PATHEXT values are refused, and legacy Windows status honestly reports its inherited logon environment.
+
 ## 0.4.0 — 2026-10-09
 
 Verified DeepSeek Harness: `0.2.1-alpha.1` (the current release, and the one this profile runs), also `0.2.0-rc.2`, `0.2.0-rc.1`, `0.1.7-rc.2`, `0.1.7-rc.1` and `0.1.7-alpha.2`. Release notes: [`docs/releases/v0.4.0.md`](docs/releases/v0.4.0.md).

package/README.md

@@ -142,8 +142,7 @@ dsh plugin --profile web exec dsh-update-status-service install \
   --workspace "$PWD"
 
 # 3. Stop the terminal-started dsh web yourself, then activate the service.
-dsh plugin --profile web exec dsh-update-status-service activate \
-  --workspace "$PWD"
+dsh plugin --profile web exec dsh-update-status-service activate
 ```
 
 `activate` stops if the port is still busy instead of killing anything, so the DSH you are already using is never taken down by surprise. It also checks afterwards that the service it just started really took over; a service that begins failing immediately is reported as a failure, not as a success. From then on, **Restart** lists what is running, asks for a second confirmation when something is, and lets DSH exit; the service starts it again and the page comes back on its own.
@@ -156,7 +155,7 @@ Only one thing may start DSH Web on that port. If another tool starts its own `d
 | Linux | `systemd --user` | at user login | Implemented; verify on your host | `loginctl enable-linger` is optional for running after logout and is never enabled automatically. The unit template is render-tested but has not been run on a real Linux host yet. |
 | Windows | Task Scheduler + current-user wrapper | at user logon | Template supplied; verify on Windows before production use | No administrator account required. |
 
-The generated service files contain absolute paths and **no secrets** — never your API keys, npm tokens, cookies or proxy credentials. Native files, logs, status and removal: [user-service supervision](docs/service-supervision.md). To check Linux or Windows on your own machine: [platform acceptance](docs/platform-acceptance.md).
+The generated service files contain absolute paths, one audited `PATH`, and **no secrets** — never your API keys, npm tokens, cookies or proxy credentials. By default `install` saves the PATH of the terminal that ran it, so Homebrew, MacPorts, Nix, asdf, Conda, Cargo and hand-installed tools all follow the same rule; `--path-source minimal` keeps a fixed environment and `--service-path` supplies an explicit one. `plan --dry-run` shows the final value and every warning before anything is written. Native files, logs, status and removal: [user-service supervision](docs/service-supervision.md). To check Linux or Windows on your own machine: [platform acceptance](docs/platform-acceptance.md).
 
 A restart interrupts running work and does not save it. If DSH cannot list what is running, cannot verify that your service owns the current process, or was started by hand or by the desktop app, it refuses to restart at all — a web page cannot talk it into it.
 
@@ -173,13 +172,14 @@ If you want DSH's stock policy instead (a non-loopback page never persists setti
 
 ## Compatibility
 
-Current release: plugin **`0.3.2`** is verified against DeepSeek Harness **`0.2.1-alpha.1`** (the current release), **`0.2.0-rc.2`**, **`0.2.0-rc.1`**, **`0.1.7-rc.2`**, **`0.1.7-rc.1`** and **`0.1.7-alpha.2`**.
+Current release: plugin **`0.4.1`** is verified against DeepSeek Harness **`0.2.1-alpha.1`** (the current release), **`0.2.0-rc.2`**, **`0.2.0-rc.1`**, **`0.1.7-rc.2`**, **`0.1.7-rc.1`** and **`0.1.7-alpha.2`**.
 
 ### Which plugin version goes with which DeepSeek Harness version
 
 | Plugin | Verified DeepSeek Harness | On npm | What that version is |
 | --- | --- | --- | --- |
-| **`0.4.0`** | `0.2.1-alpha.1`, `0.2.0-rc.2`, `0.2.0-rc.1`, `0.1.7-rc.2`, `0.1.7-rc.1`, `0.1.7-alpha.2` | `latest` | Restart you can trust: the service stops instead of restarting forever, the button needs the service to really own the process, and a disabled button shows the two commands that recover it. Settings also shows when the service started |
+| **`0.4.1`** | `0.2.1-alpha.1`, `0.2.0-rc.2`, `0.2.0-rc.1`, `0.1.7-rc.2`, `0.1.7-rc.1`, `0.1.7-alpha.2` | `latest` | The service saves the PATH used during installation, so tools installed by any package manager stay available after DSH is supervised |
+| **`0.4.0`** | `0.2.1-alpha.1`, `0.2.0-rc.2`, `0.2.0-rc.1`, `0.1.7-rc.2`, `0.1.7-rc.1`, `0.1.7-alpha.2` | published | Restart you can trust: the service stops instead of restarting forever, the button needs the service to really own the process, and a disabled button shows the two commands that recover it. Settings also shows when the service started |
 | **`0.3.2`** | `0.2.1-alpha.1`, `0.2.0-rc.2`, `0.2.0-rc.1`, `0.1.7-rc.2`, `0.1.7-rc.1`, `0.1.7-alpha.2` | published | Documentation only: the version table and every past release note are now plain language. Behaves exactly like `0.3.1` |
 | **`0.3.1`** | `0.2.1-alpha.1`, `0.2.0-rc.2`, `0.2.0-rc.1`, `0.1.7-rc.2`, `0.1.7-rc.1`, `0.1.7-alpha.2` | published | Small polish: the settings page explains Restart too, and a long job name can no longer push the buttons away. |
 | **`0.3.0`** | `0.2.1-alpha.1`, `0.2.0-rc.2`, `0.2.0-rc.1`, `0.1.7-rc.2`, `0.1.7-rc.1`, `0.1.7-alpha.2` | published | Adds **Restart** to the panel, plus the one-command service setup it needs. Without that service the button stays disabled and says why. |

package/README.zh.md

@@ -141,8 +141,7 @@ dsh plugin --profile web exec dsh-update-status-service install \
   --workspace "$PWD"
 
 # 3. 由你自己在旧终端停止直启的 dsh web，再激活服务。
-dsh plugin --profile web exec dsh-update-status-service activate \
-  --workspace "$PWD"
+dsh plugin --profile web exec dsh-update-status-service activate
 ```
 
 `activate` 发现端口还被占着就停手，绝不去杀进程，所以你正在用的 DSH 不会被突然掐掉；激活之后它还会确认服务真的接管了——一启动就不停失败的服务会被当作失败报出来，而不是假装成功。这之后就交给**重启**按钮：它先列出正在跑的东西，有东西在跑时再问一次，然后才让 DSH 退出；服务把新的拉起来，页面自己回来。
@@ -155,7 +154,7 @@ dsh plugin --profile web exec dsh-update-status-service activate \
 | Linux | `systemd --user` | 用户登录 | 已实现；请在你自己机器上验证 | 想在登出后继续运行，可自行开启 `loginctl enable-linger`（本插件不会替你开）。 |
 | Windows | 任务计划程序 + 当前用户 wrapper | 用户登录 | 已实现；请在你自己机器上验证 | 不需要管理员。 |
 
-生成的服务文件里只有绝对路径，**没有密钥**——不会带上你终端里的 API key、npm token、cookie 或代理凭据。原生文件、日志、状态与卸载见[用户服务监督说明](docs/service-supervision.md)；想在 Linux 或 Windows 上自己确认，见[跨平台验收步骤](docs/platform-acceptance.md)。
+生成的服务文件里只有绝对路径、一条可审计的 `PATH`，以及**没有密钥**——不会带上你终端里的 API key、npm token、cookie 或代理凭据。默认情况下，`install` 会保存执行安装命令的终端 PATH，因此 Homebrew、MacPorts、Nix、asdf、Conda、Cargo 和手工安装走的是同一套规则；`--path-source minimal` 保留固定环境，`--service-path` 则使用你明确给出的完整 PATH。`plan --dry-run` 会在写文件前列出最终值和全部提示。原生文件、日志、状态与卸载见[用户服务监督说明](docs/service-supervision.md)；想在 Linux 或 Windows 上自己确认，见[跨平台验收步骤](docs/platform-acceptance.md)。
 
 重启会中断正在跑的工作，且不会保存。如果 DSH 列不出正在跑什么、无法确认当前进程确实由你装的服务拥有，或者它本来就是终端直启、桌面应用托管的，它会直接拒绝重启——网页端说什么都没用。
 
@@ -172,13 +171,14 @@ DSH 对来源不是 loopback（`localhost` / `127.0.0.1`）的页面会关闭 Ho
 
 ## 兼容性
 
-当前发布：插件 **`0.3.2`** 已针对 DeepSeek Harness **`0.2.1-alpha.1`**（当前发布版）、**`0.2.0-rc.2`**、**`0.2.0-rc.1`**、**`0.1.7-rc.2`**、**`0.1.7-rc.1`** 与 **`0.1.7-alpha.2`** 验证。
+当前发布：插件 **`0.4.1`** 已针对 DeepSeek Harness **`0.2.1-alpha.1`**（当前发布版）、**`0.2.0-rc.2`**、**`0.2.0-rc.1`**、**`0.1.7-rc.2`**、**`0.1.7-rc.1`** 与 **`0.1.7-alpha.2`** 验证。
 
 ### 插件版本与 DeepSeek Harness 版本的对应关系
 
 | 插件版本 | 已验证的 DeepSeek Harness | npm 发布状态 | 该版本是什么 |
 | --- | --- | --- | --- |
-| **`0.4.0`** | `0.2.1-alpha.1`、`0.2.0-rc.2`、`0.2.0-rc.1`、`0.1.7-rc.2`、`0.1.7-rc.1`、`0.1.7-alpha.2` | `latest` | 重启变得靠得住：服务连续失败会停下而不是无限重启；按钮要求系统服务真正托管当前进程；禁用时会给出两条可复制的恢复命令。设置页还能看到服务启动时间 |
+| **`0.4.1`** | `0.2.1-alpha.1`、`0.2.0-rc.2`、`0.2.0-rc.1`、`0.1.7-rc.2`、`0.1.7-rc.1`、`0.1.7-alpha.2` | `latest` | 安装服务时保存当时使用的 PATH，不论工具由哪种包管理器安装，受托管后仍能找到 |
+| **`0.4.0`** | `0.2.1-alpha.1`、`0.2.0-rc.2`、`0.2.0-rc.1`、`0.1.7-rc.2`、`0.1.7-rc.1`、`0.1.7-alpha.2` | 已发布 | 重启变得靠得住：服务连续失败会停下而不是无限重启；按钮要求系统服务真正托管当前进程；禁用时会给出两条可复制的恢复命令。设置页还能看到服务启动时间 |
 | **`0.3.2`** | `0.2.1-alpha.1`、`0.2.0-rc.2`、`0.2.0-rc.1`、`0.1.7-rc.2`、`0.1.7-rc.1`、`0.1.7-alpha.2` | 已发布 | 只改文档：版本对照表和历史发布说明都改成人话。功能与 `0.3.1` 完全一样 |
 | **`0.3.1`** | `0.2.1-alpha.1`、`0.2.0-rc.2`、`0.2.0-rc.1`、`0.1.7-rc.2`、`0.1.7-rc.1`、`0.1.7-alpha.2` | 已发布 | 小补丁：设置页也说明了重启前提，长任务名不再把按钮挤走。 |
 | **`0.3.0`** | `0.2.1-alpha.1`、`0.2.0-rc.2`、`0.2.0-rc.1`、`0.1.7-rc.2`、`0.1.7-rc.1`、`0.1.7-alpha.2` | 已发布 | 面板新增**重启**，以及它需要的那条服务安装命令；没装服务时按钮保持禁用并说明原因。 |

package/docs/platform-acceptance.md

@@ -10,7 +10,7 @@ Three steps, each one safe to stop at. If a step fails, the section below says w
 dsh plugin --profile web exec dsh-update-status-service plan --workspace "$PWD" --dry-run
 ```
 
-Check the printed Node path, DSH path and port against what you actually run. Override any of them with `--node`, `--dsh`, `--port`.
+Check the printed Node path, DSH path, absolute native-service command, port and **servicePath** against what you actually run. The default `current` value should contain the directories where your terminal finds the tools you need; warnings are visible before anything is written. Override launch facts with `--node`, `--dsh`, `--port`; use `--path-source minimal` for a fixed PATH, or `--service-path` (plus `--service-pathext` on Windows when needed) for an explicit one.
 
 ## 2. Write the service definition — still starts nothing
 
@@ -18,12 +18,12 @@ Check the printed Node path, DSH path and port against what you actually run. Ov
 dsh plugin --profile web exec dsh-update-status-service install --workspace "$PWD"
 ```
 
-It runs a boot precheck that does not bind the port. If that precheck fails, nothing is written.
+It runs a boot precheck that does not bind the port and uses the exact same PATH that will be written into the service. If that precheck fails, nothing is written. The receipt keeps that PATH, its source, capture time, PATHEXT on Windows and all warnings; later commands reuse it instead of reading the shell that happens to invoke them.
 
 ## 3. Stop your terminal's `dsh web` yourself, then
 
 ```sh
-dsh plugin --profile web exec dsh-update-status-service activate --workspace "$PWD"
+dsh plugin --profile web exec dsh-update-status-service activate
 ```
 
 It refuses to start while the port is still busy — that is deliberate, so the DSH you are using is never pushed aside.
@@ -44,7 +44,7 @@ If **Restart** stays greyed out after activating, the running process was not re
 ## Removing it again
 
 ```sh
-dsh plugin --profile web exec dsh-update-status-service uninstall --workspace "$PWD"
+dsh plugin --profile web exec dsh-update-status-service uninstall
 ```
 
 That removes only the definition this tool created. Logs are kept.

package/docs/service-supervision.md

@@ -25,15 +25,14 @@ This document describes the explicit, opt-in setup. The plugin never installs a
 5. Activate the staged service:
 
    ```sh
-   dsh plugin --profile web exec dsh-update-status-service activate \
-     --workspace "$PWD"
+   dsh plugin --profile web exec dsh-update-status-service activate
    ```
 
    `activate` refuses to run while the requested port is occupied, and it never kills an existing process. After starting the service it also verifies that the service really owns a running process: a service that begins crash-looping makes `activate` fail with that reason instead of reporting success.
 
 6. Reopen the normal Web URL. The update panel should report a restart-capable supervised process. Perform the first real page restart yourself while present, then confirm that the page reconnects.
 
-Use `status`, `stop`, and `uninstall` with the same `--workspace` argument for later maintenance. `uninstall` preserves logs.
+After `install`, the receipt under `DSH_HOME` is the source of truth. `activate`, `status`, `stop`, and `uninstall` need no workspace/profile/PATH arguments; use only `--dsh-home` when the receipt is outside the default `~/.dsh`. Unknown options are rejected instead of silently falling back to another receipt. The receipt also stores an absolute launchctl/systemctl/schtasks path, so these actions do not depend on the shell that invokes them. Status, stop and uninstall remain available even if the old Node/DSH path or workspace no longer exists; activate still checks all launch files before it starts anything. `uninstall` preserves logs and re-derives every deletion path from the validated fixed service identity, platform and current home — mutable receipt paths are never trusted.
 
 > `dsh plugin --profile web exec` is pnpm's profile-local executable runner. Do not assume `dsh-update-status-service` is globally installed.
 
@@ -45,9 +44,12 @@ The staged definition contains only explicit, non-secret launch facts:
 - profile, workspace, host, port, and `--no-open`;
 - `DSH_HOME` when explicitly configured;
 - an explicit `DSH_WEB_SUPERVISOR=dsh-update-status` marker;
-- private stdout/stderr log paths.
+- private stdout/stderr log paths;
+- one final `PATH`, its source (`current`, `minimal`, or `explicit`), capture time, Windows `PATHEXT` when applicable, and any warnings produced while resolving it.
+
+It intentionally does **not** copy the full terminal environment. The default `current` mode snapshots only the PATH of the process that runs `plan`/`install`; no login or interactive shell startup file is executed. The selected Node directory is placed first, empty and relative entries are ignored, duplicates are removed in order, and missing absolute directories are preserved with a warning because a mount or tool directory may appear later. The result is persisted in the receipt and reused by preflight, the native definition, activation and status — later commands never recapture a different terminal PATH.
 
-It intentionally does **not** inherit the full terminal environment. If your DSH startup requires secret environment variables, configure them through your operating system's secret-management mechanism before activating the service; do not paste secrets into this plugin's configuration or issue tracker.
+For a fixed deployment use `--path-source minimal`; to supply the exact value yourself use `--service-path "..."` (which implies the `explicit` source). On Windows `--service-pathext` can pin command extensions as well. `plan --dry-run` prints the final PATH, source, capture time, PATHEXT and every warning before anything is written; `install` repeats the final PATH before preflight, so running the two commands from different terminals cannot hide a changed input. A too-long value or a value containing NUL/line breaks is rejected rather than silently shortened. If your DSH startup requires other environment variables or secrets, configure them through your operating system's secret-management mechanism before activating the service; do not paste secrets into this plugin's configuration or issue tracker.
 
 ## macOS — LaunchAgent
 
@@ -57,6 +59,8 @@ The CLI stages a current-user plist at:
 ~/Library/LaunchAgents/com.idoall.dsh-update-status.web.plist
 ```
 
+The plist receives the one PATH resolved above. This is package-manager-neutral: Homebrew, MacPorts, pkgsrc, Nix, asdf, Conda, Cargo and hand-installed tools work when their directory was already in the terminal PATH used for `install`; no prefix is hardcoded into the macOS renderer.
+
 It runs at login (`RunAtLoad`) and starts a small wrapper, also staged by the CLI:
 
 ```text
@@ -89,6 +93,8 @@ The CLI stages:
 ~/.config/systemd/user/dsh-update-status-web.service
 ```
 
+The unit receives the persisted POSIX PATH, with literal `%` escaped so systemd cannot treat a directory as a specifier. WSL reports itself as Linux and therefore uses the same colon-separated rules; a Windows semicolon PATH is never written into the unit.
+
 It uses `Restart=on-failure`, so DSH's restart exit code causes systemd to relaunch it, and it bounds the loop with `StartLimitIntervalSec=300` / `StartLimitBurst=10`: ten starts inside five minutes stops the unit instead of respawning forever. It is a **user** service: normally it starts after that user logs in.
 
 ```sh
@@ -119,6 +125,8 @@ The CLI stages a current-user Task Scheduler definition and a PowerShell wrapper
 %LOCALAPPDATA%\dsh-update-status\
 ```
 
+New receipts pin both the semicolon-separated PATH and PATHEXT in the PowerShell wrapper, including drive paths, UNC shares, spaces and Unicode; PATH keys are read case-insensitively. Old receipts preserve their historical Task Scheduler logon environment instead of being narrowed during an upgrade.
+
 The task starts at user logon with least privilege. The wrapper owns the long-running DSH child, restarts it after an intentional restart or unexpected exit, and stops after five starts that each die within 30 seconds (the same ceiling as macOS) instead of respawning forever. Use Task Scheduler to inspect the task named **DSH Update Status Web**.
 
 Windows behavior must be verified on a Windows host before it is described as production-supported; use `plan --dry-run` to inspect the generated XML and wrapper first.
@@ -152,8 +160,7 @@ Node/NVM upgrades can change the absolute Node path captured in a service defini
 To remove supervision without deleting DSH profiles, sessions, or plugin preferences:
 
 ```sh
-dsh plugin --profile web exec dsh-update-status-service uninstall \
-  --workspace "$PWD"
+dsh plugin --profile web exec dsh-update-status-service uninstall
 ```
 
 The command removes only the definition and receipt created by this installer. It preserves logs for diagnosis.

package/lib/index.js

@@ -1,4 +1,4 @@
-import { c as parseSystemdMainPid, d as bootStampFile, f as countRecentRestarts, h as serviceLogDir, i as SYSTEMD_UNIT, m as recordBootStamp, p as dshHomeOf, r as LAUNCHD_LABEL, s as parseLaunchdTrackedPid, t as planFor, u as RESTART_STORM_WINDOW_MS } from "./plan-BornHBEZ.js";
+import { C as recordBootStamp, S as dshHomeOf, _ as parseSystemdMainPid, a as planFor, b as bootStampFile, f as LAUNCHD_LABEL, g as parseLaunchdTrackedPid, p as SYSTEMD_UNIT, w as serviceLogDir, x as countRecentRestarts, y as RESTART_STORM_WINDOW_MS } from "./plan-D9Ybaj-3.js";
 import { createRequire } from "node:module";
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, join, normalize, sep } from "node:path";

package/lib/{plan-BornHBEZ.js → plan-D9Ybaj-3.js}

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, posix, resolve, win32 } from "node:path";
 import { homedir } from "node:os";
 //#region src/shared/restart-evidence.ts
 /**
@@ -165,15 +165,135 @@ function parseWindowsTaskRunning(output) {
 	return /(?:^|\W)running(?:\W|$)/i.test(output);
 }
 //#endregion
+//#region src/service/service-path.ts
+/** Resolve one audited PATH that preflight and the native service both consume. */
+/** A service definition must stay inspectable; never silently truncate it. */
+const MAX_SERVICE_PATH_LENGTH = 8192;
+const MINIMAL_POSIX = {
+	darwin: [
+		"/usr/local/bin",
+		"/usr/bin",
+		"/bin",
+		"/usr/sbin",
+		"/sbin"
+	],
+	linux: [
+		"/usr/local/bin",
+		"/usr/bin",
+		"/bin"
+	]
+};
+const DEFAULT_WINDOWS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+function normalizeServicePathExt(value) {
+	const raw = value?.trim() || DEFAULT_WINDOWS_PATHEXT;
+	validateText(raw);
+	const seen = /* @__PURE__ */ new Set();
+	const extensions = [];
+	for (const original of raw.split(";")) {
+		const extension = original.trim();
+		if (extension === "") continue;
+		if (!/^\.[A-Za-z0-9]+$/.test(extension)) throw new Error(`invalid PATHEXT entry: ${extension}`);
+		const key = extension.toUpperCase();
+		if (seen.has(key)) continue;
+		seen.add(key);
+		extensions.push(extension);
+	}
+	if (extensions.length === 0) throw new Error("PATHEXT has no usable extension");
+	return extensions.join(";");
+}
+function delimiter(platform) {
+	return platform === "win32" ? ";" : ":";
+}
+function nodeDirectory(platform, nodePath) {
+	return platform === "win32" ? win32.dirname(nodePath) : posix.dirname(nodePath);
+}
+function isAbsolute$1(platform, value) {
+	return platform === "win32" ? win32.isAbsolute(value) : posix.isAbsolute(value);
+}
+function minimalEntries(platform, nodePath, override) {
+	const node = nodeDirectory(platform, nodePath);
+	if (override !== void 0 && override.trim() !== "") return [node, ...override.split(delimiter(platform))];
+	if (platform === "win32") return [node];
+	return [node, ...MINIMAL_POSIX[platform]];
+}
+function sourceValue(options) {
+	if (options.source === "minimal") return minimalEntries(options.platform, options.nodePath, options.minimalPath).join(delimiter(options.platform));
+	if (options.source === "explicit") {
+		if (options.explicitPath === void 0 || options.explicitPath.trim() === "") throw new Error("`--service-path` is required when `--path-source explicit` is used");
+		return options.explicitPath;
+	}
+	if (options.currentPath === void 0 || options.currentPath.trim() === "") throw new Error("current PATH is empty; use `--path-source minimal` or `--service-path`");
+	return options.currentPath;
+}
+function validateText(value) {
+	if (/[\u0000-\u0008\u000A-\u001F\u007F]/.test(value)) throw new Error("service PATH must not contain control characters or line breaks");
+	if (value.length > 8192) throw new Error(`service PATH is too long (maximum ${String(MAX_SERVICE_PATH_LENGTH)} characters); use --service-path with a shorter value`);
+}
+/**
+* Resolve at install/plan time — no user rc file is executed. Missing absolute
+* directories are preserved (they may be mounted or created later) and reported.
+*/
+function resolveServicePath(options) {
+	const split = delimiter(options.platform);
+	const raw = sourceValue(options);
+	validateText(raw);
+	if (options.platform !== "win32" && /(?:^|;)[A-Za-z]:[\\/]/.test(raw)) throw new Error("Windows-style PATH cannot be used for Linux/WSL; provide a colon-separated PATH");
+	const exists = options.exists ?? existsSync;
+	const warnings = [];
+	const values = [nodeDirectory(options.platform, options.nodePath), ...raw.split(split)];
+	const seen = /* @__PURE__ */ new Set();
+	const entries = [];
+	let warnedEmpty = false;
+	for (const rawEntry of values) {
+		if (rawEntry === "") {
+			if (!warnedEmpty) warnings.push("ignored empty PATH entry (current-directory lookup)");
+			warnedEmpty = true;
+			continue;
+		}
+		const entry = options.platform === "win32" && rawEntry.length >= 2 && rawEntry.startsWith("\"") && rawEntry.endsWith("\"") ? rawEntry.slice(1, -1) : rawEntry;
+		if (!isAbsolute$1(options.platform, entry)) {
+			warnings.push(`ignored relative PATH entry: ${entry}`);
+			continue;
+		}
+		const key = options.platform === "win32" ? entry.toLowerCase() : entry;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		entries.push(entry);
+		if (!exists(entry)) warnings.push(`PATH directory does not exist yet: ${entry}`);
+	}
+	const value = entries.join(split);
+	if (value === "") throw new Error("service PATH has no absolute directory");
+	validateText(value);
+	const pathExt = options.platform === "win32" ? normalizeServicePathExt(options.currentPathExt) : void 0;
+	return {
+		source: options.source,
+		value,
+		...pathExt === void 0 ? {} : { pathExt },
+		warnings
+	};
+}
+/** Old receipts had no PATH fields; keep their exact historical minimal shape. */
+function servicePathOf(spec) {
+	return spec.servicePath ?? minimalEntries(spec.platform, spec.nodePath).join(delimiter(spec.platform));
+}
+//#endregion
 //#region src/service/plan.ts
 /** Build transparent per-OS user-service definitions; do not install them here. */
 const SERVICE_LABEL = LAUNCHD_LABEL;
 const SUPERVISOR_MARKER = "dsh-update-status";
+function nativeServiceCommandCandidates(platform, systemRoot) {
+	if (platform === "darwin") return ["/bin/launchctl"];
+	if (platform === "linux") return ["/usr/bin/systemctl", "/bin/systemctl"];
+	return [`${systemRoot ?? "C:\\Windows"}\\System32\\schtasks.exe`];
+}
+function nativeServiceCommandOf(spec) {
+	return spec.nativeServiceCommand ?? nativeServiceCommandCandidates(spec.platform)[0];
+}
 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, "\\\"");
+	return value.replace(/%/g, "%%").replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
 }
 function powerShell(value) {
 	return value.replace(/'/g, "''");
@@ -216,6 +336,24 @@ function servicePlatform(value) {
 	if (value === "darwin" || value === "linux" || value === "win32") return value;
 	throw new Error(`unsupported platform: ${value}; supported: macOS, Linux, Windows`);
 }
+function envValue(env, key, platform) {
+	if (platform !== "win32") return env[key];
+	return Object.entries(env).find(([name]) => name.toLowerCase() === key.toLowerCase())?.[1];
+}
+function pathSourceOf(args) {
+	const explicit = valueAfter(args, "--service-path");
+	const raw = valueAfter(args, "--path-source");
+	if (raw === void 0) return explicit === void 0 ? "current" : "explicit";
+	if (raw !== "current" && raw !== "minimal" && raw !== "explicit") throw new Error("`--path-source` must be current, minimal, or explicit");
+	if (explicit !== void 0 && raw !== "explicit") throw new Error("`--service-path` requires `--path-source explicit` (or omit --path-source)");
+	return raw;
+}
+function serviceStateFileFromArgs(args, env) {
+	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");
+	return join(dshHome ?? join(home, ".dsh"), "dsh-update-status-service.json");
+}
 function specFromArgs(args, env) {
 	const platform = servicePlatform(env.platform);
 	const profile = valueAfter(args, "--profile") ?? env.env.DSH_PROFILE ?? "web";
@@ -233,6 +371,20 @@ function specFromArgs(args, env) {
 	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");
+	const systemRoot = envValue(env.env, "SYSTEMROOT", platform);
+	const pathExtOverride = valueAfter(args, "--service-pathext");
+	if (pathExtOverride !== void 0 && platform !== "win32") throw new Error("`--service-pathext` is supported only on Windows");
+	const candidates = nativeServiceCommandCandidates(platform, systemRoot);
+	const nativeServiceCommand = platform === "linux" ? candidates.find((candidate) => existsSync(candidate)) ?? candidates[0] : candidates[0];
+	const servicePath = resolveServicePath({
+		platform,
+		nodePath,
+		source: pathSourceOf(args),
+		currentPath: env.path ?? envValue(env.env, "PATH", platform),
+		currentPathExt: pathExtOverride ?? envValue(env.env, "PATHEXT", platform),
+		explicitPath: valueAfter(args, "--service-path"),
+		minimalPath: platform === "win32" && systemRoot !== void 0 ? `${systemRoot}\\System32;${systemRoot}` : void 0
+	});
 	return {
 		schemaVersion: 1,
 		platform,
@@ -246,6 +398,12 @@ function specFromArgs(args, env) {
 		home,
 		...dshHome === void 0 ? {} : { dshHome },
 		logDir,
+		servicePath: servicePath.value,
+		servicePathSource: servicePath.source,
+		servicePathCapturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		...servicePath.pathExt === void 0 ? {} : { servicePathExt: servicePath.pathExt },
+		...servicePath.warnings.length === 0 ? {} : { servicePathWarnings: servicePath.warnings },
+		nativeServiceCommand,
 		supervisorMarker: SUPERVISOR_MARKER
 	};
 }
@@ -292,7 +450,7 @@ function webArguments(spec) {
 }
 function launchdWrapper(spec, paths, uid) {
 	const args = [spec.nodePath, ...webArguments(spec)].map(shQuote).join(" ");
-	const kickstart = `launchctl kickstart -k gui/${String(uid)}/${spec.label}`;
+	const kickstart = `${shQuote(nativeServiceCommandOf(spec))} kickstart -k gui/${String(uid)}/${spec.label}`;
 	return `#!/bin/sh
 # Managed by dsh-update-status. This wrapper, not launchd, owns the restart loop.
 #
@@ -349,7 +507,7 @@ function launchdDefinition(spec, paths) {
 	const args = ["/bin/sh", wrapper].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`],
+		["PATH", servicePathOf(spec)],
 		["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");
@@ -383,7 +541,7 @@ 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="PATH=${systemd(servicePathOf(spec))}"`,
 		`Environment="DSH_WEB_SUPERVISOR=${spec.supervisorMarker}"`,
 		...spec.dshHome === void 0 ? [] : [`Environment="DSH_HOME=${systemd(spec.dshHome)}"`]
 	].join("\n");
@@ -418,7 +576,7 @@ function windowsWrapper(spec, paths) {
 	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}'
+${spec.servicePath === void 0 ? "" : `$env:PATH = '${powerShell(spec.servicePath)}'\n$env:PATHEXT = '${powerShell(spec.servicePathExt ?? ".COM;.EXE;.BAT;.CMD")}'\n`}$env:DSH_WEB_SUPERVISOR = '${spec.supervisorMarker}'
 ${dshHome}Set-Location -LiteralPath '${workspace}'
 $rapidWindowSeconds = ${String(30)}
 $rapidLimit = ${String(5)}
@@ -463,6 +621,7 @@ function windowsDefinition(spec, paths) {
 /** Generate a service plan without writing, starting, or stopping anything. */
 function planFor(spec, uid = 0) {
 	const paths = pathsFor(spec);
+	const control = nativeServiceCommandOf(spec);
 	if (spec.platform === "darwin") {
 		const domain = `gui/${uid}`;
 		return {
@@ -471,30 +630,30 @@ function planFor(spec, uid = 0) {
 			definition: launchdDefinition(spec, paths),
 			wrapper: launchdWrapper(spec, paths, uid),
 			installCommand: [
-				"launchctl",
+				control,
 				"bootstrap",
 				domain,
 				paths.definitionFile
 			],
 			startCommand: [
-				"launchctl",
+				control,
 				"kickstart",
 				"-k",
 				`${domain}/${spec.label}`
 			],
-			recoverCommand: `launchctl kickstart -k ${domain}/${spec.label}`,
+			recoverCommand: `${shQuote(control)} kickstart -k ${domain}/${spec.label}`,
 			statusCommand: [
-				"launchctl",
+				control,
 				"print",
 				`${domain}/${spec.label}`
 			],
 			stopCommand: [
-				"launchctl",
+				control,
 				"bootout",
 				`${domain}/${spec.label}`
 			],
 			uninstallCommand: [
-				"launchctl",
+				control,
 				"bootout",
 				`${domain}/${spec.label}`
 			]
@@ -505,33 +664,33 @@ function planFor(spec, uid = 0) {
 		paths,
 		definition: systemdDefinition(spec),
 		installCommand: [
-			"systemctl",
+			control,
 			"--user",
 			"daemon-reload"
 		],
 		startCommand: [
-			"systemctl",
+			control,
 			"--user",
 			"enable",
 			"--now",
 			"dsh-update-status-web.service"
 		],
-		recoverCommand: `systemctl --user reset-failed ${SYSTEMD_UNIT} && systemctl --user enable --now ${SYSTEMD_UNIT}`,
+		recoverCommand: `${shQuote(control)} --user reset-failed ${SYSTEMD_UNIT} && ${shQuote(control)} --user enable --now ${SYSTEMD_UNIT}`,
 		statusCommand: [
-			"systemctl",
+			control,
 			"--user",
 			"status",
 			"dsh-update-status-web.service"
 		],
 		stopCommand: [
-			"systemctl",
+			control,
 			"--user",
 			"disable",
 			"--now",
 			"dsh-update-status-web.service"
 		],
 		uninstallCommand: [
-			"systemctl",
+			control,
 			"--user",
 			"disable",
 			"--now",
@@ -544,7 +703,7 @@ function planFor(spec, uid = 0) {
 		definition: windowsDefinition(spec, paths),
 		wrapper: windowsWrapper(spec, paths),
 		installCommand: [
-			"schtasks.exe",
+			control,
 			"/Create",
 			"/TN",
 			"DSH Update Status Web",
@@ -553,14 +712,14 @@ function planFor(spec, uid = 0) {
 			"/F"
 		],
 		startCommand: [
-			"schtasks.exe",
+			control,
 			"/Run",
 			"/TN",
 			"DSH Update Status Web"
 		],
-		recoverCommand: "schtasks.exe /Run /TN \"DSH Update Status Web\"",
+		recoverCommand: `"${control}" /Run /TN "DSH Update Status Web"`,
 		statusCommand: [
-			"schtasks.exe",
+			control,
 			"/Query",
 			"/TN",
 			"DSH Update Status Web",
@@ -569,13 +728,13 @@ function planFor(spec, uid = 0) {
 			"LIST"
 		],
 		stopCommand: [
-			"schtasks.exe",
+			control,
 			"/End",
 			"/TN",
 			"DSH Update Status Web"
 		],
 		uninstallCommand: [
-			"schtasks.exe",
+			control,
 			"/Delete",
 			"/TN",
 			"DSH Update Status Web",
@@ -584,4 +743,4 @@ function planFor(spec, uid = 0) {
 	};
 }
 //#endregion
-export { WINDOWS_TASK_NAME as a, parseSystemdMainPid as c, bootStampFile as d, countRecentRestarts as f, serviceLogDir as h, SYSTEMD_UNIT as i, parseWindowsTaskRunning as l, recordBootStamp as m, specFromArgs as n, WINDOWS_WRAPPER_BASENAME as o, dshHomeOf as p, LAUNCHD_LABEL as r, parseLaunchdTrackedPid as s, planFor as t, RESTART_STORM_WINDOW_MS as u };
+export { recordBootStamp as C, dshHomeOf as S, parseSystemdMainPid as _, planFor as a, bootStampFile as b, specFromArgs as c, servicePathOf as d, LAUNCHD_LABEL as f, parseLaunchdTrackedPid as g, WINDOWS_WRAPPER_BASENAME as h, pathsFor as i, MAX_SERVICE_PATH_LENGTH as l, WINDOWS_TASK_NAME as m, nativeServiceCommandCandidates as n, servicePlatform as o, SYSTEMD_UNIT as p, nativeServiceCommandOf as r, serviceStateFileFromArgs as s, SERVICE_LABEL as t, normalizeServicePathExt as u, parseWindowsTaskRunning as v, serviceLogDir as w, countRecentRestarts as x, RESTART_STORM_WINDOW_MS as y };

package/lib/service-cli.d.ts

@@ -16,9 +16,44 @@ interface ServiceSpec {
   readonly home: string;
   readonly dshHome?: string;
   readonly logDir: string;
+  /** Final audited PATH persisted by install and reused by every later action. */
+  readonly servicePath?: string;
+  readonly servicePathSource?: 'current' | 'minimal' | 'explicit';
+  readonly servicePathCapturedAt?: string;
+  /** Windows command extension lookup, persisted alongside PATH. */
+  readonly servicePathExt?: string;
+  /** Human-readable warnings retained in the receipt and dry-run output. */
+  readonly servicePathWarnings?: readonly string[];
+  /** Absolute launchctl/systemctl/schtasks path; later actions never search PATH. */
+  readonly nativeServiceCommand?: string;
   /** Written by the user-service definition, never inferred from a TTY. */
   readonly supervisorMarker: 'dsh-update-status';
 }
+interface ServicePaths {
+  readonly stateFile: string;
+  readonly definitionFile: string;
+  /** macOS and Windows: the wrapper that owns the restart loop. */
+  readonly wrapperFile?: string;
+  readonly stdoutFile: string;
+  readonly stderrFile: string;
+}
+interface ServicePlan {
+  readonly spec: ServiceSpec;
+  readonly paths: ServicePaths;
+  readonly definition: string;
+  readonly wrapper?: string;
+  readonly installCommand: readonly string[];
+  readonly startCommand: readonly string[];
+  /**
+   * One copy-only line that lets the service take over again after it stopped
+   * (a tripped start limit, a given-up wrapper). Displayed only — never run by
+   * the plugin.
+   */
+  readonly recoverCommand: string;
+  readonly statusCommand: readonly string[];
+  readonly stopCommand: readonly string[];
+  readonly uninstallCommand: readonly string[];
+}
 interface CliEnvironment {
   readonly platform: NodeJS.Platform;
   readonly home: string;
@@ -49,6 +84,7 @@ type ServiceVerification = {
 };
 //#endregion
 //#region src/service/cli.d.ts
+export declare function serialisePlan(plan: ServicePlan): string;
 export interface CliHooks {
   readonly preflight?: (spec: ServiceSpec) => void;
   /** Injected in tests; defaults to the real post-activation verification. */

package/lib/service-cli.js

@@ -1,6 +1,6 @@
-import { a as WINDOWS_TASK_NAME, c as parseSystemdMainPid, d as bootStampFile, f as countRecentRestarts, h as serviceLogDir, i as SYSTEMD_UNIT, l as parseWindowsTaskRunning, n as specFromArgs, s as parseLaunchdTrackedPid, t as planFor, u as RESTART_STORM_WINDOW_MS } from "./plan-BornHBEZ.js";
+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 } from "node:path";
+import { dirname, isAbsolute } from "node:path";
 import { spawnSync } from "node:child_process";
 import { createServer } from "node:net";
 async function observeServiceState(spec, run, uid) {
@@ -103,8 +103,15 @@ 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.
 
@@ -114,7 +121,7 @@ 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);
@@ -135,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), {
@@ -182,19 +242,31 @@ function ensureReplaceable(path, expected, managed) {
 }
 function receiptOwnsPath(previous, path) {
 	if (previous === void 0) return false;
-	return previous.paths.definitionFile === path || previous.paths.stateFile === path || previous.paths.wrapperFile === path;
+	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 readReceiptIfPresent(path) {
-	return existsSync(path) ? readReceipt(path) : void 0;
+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)}`);
 	}
@@ -207,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,
@@ -216,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,
@@ -233,38 +314,9 @@ function serialisePlan(plan) {
 		}
 	}, 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;
@@ -286,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) {
@@ -294,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") {
@@ -311,19 +390,27 @@ 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);
-			const previous = readReceiptIfPresent(plan.paths.stateFile);
+			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({
@@ -343,7 +430,9 @@ 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);
@@ -369,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) {
@@ -383,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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-update-status",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "DeepSeek Harness Web plugin for version status, copy-only upgrade guidance, and safe restart when an explicit user-level supervisor is installed.",
   "type": "module",
   "main": "lib/index.js",