@1e0zj/dsh-plugin-mall 0.4.0 → 0.4.1

package/README.md

@@ -16,7 +16,7 @@ Curated lists only show what has been reviewed and merged. This marketplace is o
 - **npm-first installs** — registry tarballs are smaller than whole-repo GitHub downloads and come with integrity checks. Lookups follow the registry pnpm actually installs from (profile `.npmrc` → `pnpm config get registry` → npmjs), so a mirror user keeps npm-first instead of silently falling back to whole-repo clones.
 - **Update management** — installed plugins are compared against the registry `latest`; one-click update per plugin.
 - **Conflict guard** — every install runs an isolated preflight first: the candidate is installed with scripts disabled into a throwaway directory and scanned against the live profile for loader-id collisions, double mounts, host-module shadowing and version/OS/peer ranges. A patch layer is not read entry by entry but composed the way the loader applies it — the profile is assembled with and without the candidate's layer, in the position dsh would apply it, and the two trees are diffed. That composition is checked against the loader's own `applyEntryPatches` on every test run, over fixed shapes and 300 generated patch combinations, so "what dsh would boot" is not a guess. What gets reported is what would actually change: disabling, re-enabling or replacing the config of someone else's rows warns and names them, past ten such rows the candidate is a rival composition rather than an addition and is blocked, and a bundle that is itself another front door (own `bin`, terminal peers, no browser half) is blocked once it switches rows on or off or rewrites a protection row — the fingerprint corroborates, it never blocks on its own. A hard conflict is blocked, warnings require explicit confirmation. The profile's load-bearing files are snapshotted before `pnpm` touches them and restored on failure. A pending install is resolved on the next start, however you start it: this plugin runs recovery as it loads, which only happens because dsh booted far enough to compose the profile. Starting through `guard launch` adds a grace window on top, so a plugin that boots and then crashes seconds later is rolled back and restarted once (see [Startup protection](#startup-protection-guard-cli)).
-- **Resilience** — rate-limit circuit breaker, GitHub's 1000-result search window handled gracefully, `corepack enable pnpm` self-heal when pnpm is missing, one-click dsh restart (loopback-only, `allowRestart: false` to disable). The successor waits for the outgoing host to be gone before it binds — starting into an occupied port would read as "the pending plugin crashed dsh" and roll back an install that was fine. It leaves no stray console behind and does not re-open the browser, because the page that asked for the restart is still there and reconnects on its own; whatever the restart prints lands in `<home>/guard/restart-<profile>.log`.
+- **Resilience** — rate-limit circuit breaker, GitHub's 1000-result search window handled gracefully, `corepack enable pnpm` self-heal when pnpm is missing, one-click dsh restart (loopback-only, `allowRestart: false` to disable). The outgoing Host exits only after the on-disk helper explicitly acknowledges the current handoff protocol and stays alive through a stability window; a missing, stale or incompatible helper leaves the existing Web service running. The successor then waits for the outgoing host to be gone before it binds — starting into an occupied port would read as "the pending plugin crashed dsh" and roll back an install that was fine. It leaves no stray console behind and does not re-open the browser, because the page that asked for the restart is still there and reconnects on its own; whatever the restart prints lands in `<home>/guard/restart-<profile>.log`.
 
 ## Install
 
@@ -154,7 +154,7 @@ pnpm --dir <profile> add "github:omdsh-dev/dsh-at-file" --ignore-scripts
 - **npm 优先安装**：registry tarball 比整仓库下载更小且带完整性校验；查询用的 registry 跟随 pnpm 实际安装源（profile `.npmrc` → `pnpm config get registry` → npmjs），换了镜像也不会退化成整仓库克隆
 - **更新管理**：已装插件与 registry `latest` 比对，逐个一键更新
 - **冲突防护**：每次安装先跑隔离预检——候选包在一次性目录里以禁用脚本的方式装好后，对照 live profile 扫描 loader-id 冲突、重复挂载、宿主模块遮蔽和版本/OS/peer 范围。补丁不是逐条读，而是**按 loader 的方式组装**——把候选包的层放进 dsh 会放的位置，装前装后各组装一棵树再逐行比对。这套组装每次跑测试都会和 loader 自己的 `applyEntryPatches` 对拍（固定形状 + 300 组随机生成的补丁组合），所以「dsh 会装出什么树」不是猜的。报出来的是真正会变的东西：停用、重新启用、或替换别人整块 config，都点名是哪几条 id 并警告；超过十条就不是叠加而是另一套组合，直接拦截；候选包本身就是另一套门面（自带 bin、依赖终端栈、没有浏览器半边）时，只要它停用/启用了行、或改了沙箱审批这类保护行，就直接拦截——指纹只做佐证，单凭它不拦。硬冲突直接拦截，警告需显式确认。安装前给 profile 的承重文件拍快照、失败即回滚；pending 安装在下次启动时自动了结，**不挑启动方式**：本插件加载时就跑恢复，而能加载本身就证明 dsh 已经组装好 profile、活到了这一步。经 `guard launch` 启动则多一层观察期——插件启动几秒后才崩的情况也能回滚并原样重启一次（见下方「启动保护」）。
-- **工程韧性**：限流熔断、GitHub 5xx/超时退避重试（504 瞬时故障不再直达用户）、GitHub 1000 条搜索上限优雅处理、pnpm 缺失时 `corepack` 自愈、一键重启 dsh（仅 loopback，可 `allowRestart: false` 关闭）。重启会**等旧进程真正退出**再绑端口——抢在端口没释放时启动，会被判成「新装的插件把 dsh 搞崩了」，把一次本来正常的安装回滚掉。重启后不留控制台窗口、也不再重开浏览器：发起重启的那个页面还在，会自己重连；重启过程的输出写进 `<home>/guard/restart-<profile>.log`（想停 dsh 用任务管理器结束 node 进程）
+- **工程韧性**：限流熔断、GitHub 5xx/超时退避重试（504 瞬时故障不再直达用户）、GitHub 1000 条搜索上限优雅处理、pnpm 缺失时 `corepack` 自愈、一键重启 dsh（仅 loopback，可 `allowRestart: false` 关闭）。旧 Host 只有在磁盘上的 helper 明确回报当前交接协议、并活过稳定窗口后才退出；helper 缺失、过旧或协议不兼容时，现有 Web 服务继续运行。之后 successor 会**等旧进程真正退出**再绑端口——抢在端口没释放时启动，会被判成「新装的插件把 dsh 搞崩了」，把一次本来正常的安装回滚掉。重启后不留控制台窗口、也不再重开浏览器：发起重启的那个页面还在，会自己重连；重启过程的输出写进 `<home>/guard/restart-<profile>.log`（想停 dsh 用任务管理器结束 node 进程）
 
 ## 安装
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1e0zj/dsh-plugin-mall",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "dsh 插件市场：搜索 GitHub dsh-plugin 话题下的插件仓库，一键安装到本地 dsh profile（agent 工具 + 设置页插件市场 tab）",
   "type": "module",
   "main": "src/index.js",

package/src/cli.js

@@ -62,6 +62,7 @@ import {
 // github.js imports node builtins only — the host-independence of this CLI is
 // preserved (it must keep working when the dsh host itself is broken).
 import { npmPackageInfo } from "./github.js";
+import { createRestartHelperReadyMessage } from "./restart-protocol.js";
 
 /**
  * Pin a bare package name to name@latest: pnpm's minimumReleaseAge policy
@@ -79,6 +80,24 @@ export async function pinSpecToLatest(spec, npmInfo = npmPackageInfo) {
   return spec;
 }
 
+/**
+ * Tell the outgoing Web Host that this exact CLI understands its handoff
+ * protocol and has finished parsing --await-exit. A normal terminal launch has
+ * no IPC channel and simply skips the announcement.
+ */
+export async function announceRestartHelperReady(awaitExitPid, send = process.send?.bind(process)) {
+  if (awaitExitPid === undefined || typeof send !== "function") return false;
+  const message = createRestartHelperReadyMessage(awaitExitPid);
+  await new Promise((resolvePromise, rejectPromise) => {
+    try {
+      send(message, (error) => error ? rejectPromise(error) : resolvePromise());
+    } catch (error) {
+      rejectPromise(error);
+    }
+  });
+  return true;
+}
+
 // ── small helpers ────────────────────────────────────────────────────────────
 
 // Same shell-metacharacter blocklist as installer.assertSafeSpec. The install
@@ -884,7 +903,15 @@ function markerLooksValid(marker, profileDir, home) {
  * A corrupt or legacy (pre-v2) marker, or a failed static-recovery step, fails
  * closed: the command is NOT launched and no unvalidated path is deleted.
  */
-async function cmdLaunch({ profile, home, graceMs, commandArgv, awaitExitPid, _waitForExit = waitForProcessExit }) {
+async function cmdLaunch({
+  profile,
+  home,
+  graceMs,
+  commandArgv,
+  awaitExitPid,
+  _waitForExit = waitForProcessExit,
+  _onAwaitExit = announceRestartHelperReady,
+}) {
   const profileDir = profileDirOf(home, profile);
   const grace = graceMs ?? DEFAULT_GRACE_MS;
   const [command, ...args] = commandArgv;
@@ -899,6 +926,10 @@ async function cmdLaunch({ profile, home, graceMs, commandArgv, awaitExitPid, _w
   // the outcome that costs the user their install; not starting leaves the old
   // host running and the marker pending, which the next launch resolves.
   if (awaitExitPid !== undefined) {
+    // This is the exact handoff boundary: arguments and profile are valid, and
+    // the helper is about to block on the outgoing Host. The Web parent waits
+    // for this IPC acknowledgement before it allows itself to exit.
+    await _onAwaitExit(awaitExitPid);
     if (!await _waitForExit(awaitExitPid, AWAIT_EXIT_TIMEOUT_MS)) {
       throw new Error(`process ${awaitExitPid} was still running after ${AWAIT_EXIT_TIMEOUT_MS}ms — refusing to start a second host that would collide with it on the listening port (the old one is still up; nothing was changed)`);
     }
@@ -1184,6 +1215,18 @@ async function selfTest() {
       // A pid after `--` belongs to the wrapped command, not to us.
       const p6 = parseArgs(["launch", "--profile", "web", "--", "dsh", "--await-exit", "7"]);
       if (p6.awaitExit !== undefined || p6.commandArgv.join(" ") !== "dsh --await-exit 7") throw new Error("--await-exit after `--` must stay with the wrapped command");
+
+      let announced;
+      const didAnnounce = await announceRestartHelperReady(4321, (message, callback) => {
+        announced = message;
+        callback();
+      });
+      if (!didAnnounce || announced?.awaitExitPid !== 4321 || announced?.protocol !== 1) {
+        throw new Error("restart helper must announce the parsed pid and protocol over IPC");
+      }
+      if (await announceRestartHelperReady(undefined, () => { throw new Error("must not send"); }) !== false) {
+        throw new Error("a normal launch without --await-exit must not announce a restart handoff");
+      }
     }
 
     // `--await-exit`: the successor must not start while the outgoing host is
@@ -1199,6 +1242,7 @@ async function selfTest() {
 
       let launched = false;
       const neverExits = async () => false;
+      let announcedPid;
       let refused = false;
       try {
         await cmdLaunch({
@@ -1207,11 +1251,13 @@ async function selfTest() {
           commandArgv: [process.execPath, "-e", "launched=1"],
           awaitExitPid: 999999,
           _waitForExit: neverExits,
+          _onAwaitExit: async (pid) => { announcedPid = pid; },
         });
       } catch (error) {
         refused = /still running after/.test(error.message);
       }
       if (!refused) throw new Error("a pid that outlives the timeout must refuse the launch, not race it");
+      if (announcedPid !== 999999) throw new Error("launch must announce readiness immediately before waiting for the outgoing pid");
 
       // …and a pid that does go away lets the command through.
       const exitsPromptly = async () => true;

package/src/client.js

@@ -661,6 +661,25 @@ window.__ModuleLoader__.load({
       // No boolean warning-consent map is kept.
       var sessionNonce = useRef(generateSessionNonce()).current;
       var approvalTokensRef = useRef({});
+      var restartControlRef = useRef({ mounted: true, ping: null });
+      var clearRestartPing = useCallback(function () {
+        var control = restartControlRef.current;
+        if (control.ping !== null) {
+          clearInterval(control.ping);
+          control.ping = null;
+        }
+      }, []);
+      useEffect(function () {
+        var control = restartControlRef.current;
+        control.mounted = true;
+        return function () {
+          control.mounted = false;
+          if (control.ping !== null) {
+            clearInterval(control.ping);
+            control.ping = null;
+          }
+        };
+      }, []);
 
       var call = useCallback(function (endpoint, payload) {
         var body = Object.assign({ session: sessionNonce }, payload || {});
@@ -887,28 +906,49 @@ window.__ModuleLoader__.load({
         if (typeof window !== "undefined" && typeof window.confirm === "function") {
           if (window.confirm("重启 dsh？正在进行的任务会中断。") !== true) return;
         }
+        clearRestartPing();
         setRestarting(true);
         setError(null);
+        var requestedAt = Date.now();
+        var previousHostStartedAt = Number(hostStartedAt);
         call("restart", {}).then(function () {
+          if (restartControlRef.current.mounted !== true) return;
           var tries = 0;
           var ping = setInterval(function () {
+            if (restartControlRef.current.mounted !== true) {
+              clearRestartPing();
+              return;
+            }
             tries++;
             if (tries > 40) {
-              clearInterval(ping);
+              clearRestartPing();
               setRestarting(false);
               setError("2 分钟内未检测到 dsh 重启完成，请手动检查 dsh 状态后刷新页面。");
               return;
             }
-            rpc.call("/market", "installed", {}).then(function () {
-              clearInterval(ping);
+            // Prefer identity change over wall-clock ordering: NTP may move the
+            // successor's timeOrigin backwards. If initial restore did not
+            // provide an identity, retain the stricter requestedAt fallback.
+            call("jobs", {}).then(function (value) {
+              if (restartControlRef.current.mounted !== true) return;
+              var observedHostStartedAt = Number(value.hostStartedAt);
+              if (!Number.isFinite(observedHostStartedAt) || observedHostStartedAt <= 0) return;
+              var hadPreviousIdentity = Number.isFinite(previousHostStartedAt) && previousHostStartedAt > 0;
+              if (hadPreviousIdentity
+                ? observedHostStartedAt === previousHostStartedAt
+                : observedHostStartedAt <= requestedAt) return;
+              clearRestartPing();
               window.location.reload();
             }).catch(function () { /* host restarting */ });
           }, 3000);
+          restartControlRef.current.ping = ping;
         }).catch(function (e) {
+          if (restartControlRef.current.mounted !== true) return;
+          clearRestartPing();
           setRestarting(false);
           setError(errorText(e));
         });
-      }, [call, rpc]);
+      }, [call, clearRestartPing, hostStartedAt]);
 
       var doUninstall = useCallback(function (name) {
         delete approvalTokensRef.current[name];

package/src/index.js

@@ -19,6 +19,8 @@ import { existsSync, readFileSync, realpathSync, mkdirSync, mkdtempSync, writeFi
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { performance } from "node:perf_hooks";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
@@ -26,6 +28,7 @@ import { resolveProfileDir } from "@deepseek-ai/dsh-app-boot";
 import { repoInfo, searchPlugins, verifyPlugins, cachedRepoManifest, fetchRawFile, preferNpmSpec, npmPackageInfo, compareVersions, assertSafeToInstall, mapLimit, NETWORK_CONCURRENCY } from "./github.js";
 import { ensureProfile, listInstalled, normalizeSpec, runInstall, runRemove, assertSafeSpec, resolveRegistry, serializeCanonicalProof, persistPluginDisabled } from "./installer.js";
 import { preflightInstall, inspectRemoteCandidate, recoverProfile, describeRollbackRebuild } from "./guard.js";
+import { createRestartHelperReadyMessage, RESTART_HELPER_READY_TYPE, RESTART_RESPONSE_DRAIN_MS, superviseRestartHelper } from "./restart-protocol.js";
 
 export const name = "@1e0zj/dsh-plugin-mall";
 // `loader` 用来读装配树、并对单个 entry 做热开关（entry.update）。读法照抄
@@ -288,12 +291,10 @@ export function computeProfileFingerprint(profileDir) {
 const compatCache = new Map();
 const COMPAT_TTL = 600000;
 
-// When this plugin instance loaded — for a host process this is effectively the
-// host's start time (the loader mounts plugins at boot). Sent with `jobs` so a
-// remounted client can tell "completed, restart still pending" from "completed
-// and the restart already happened": a finishedAt older than this value means
-// the task's Restart-dsh button has already done its job.
-const pluginLoadedAt = Date.now();
+// Node captures performance.timeOrigin once at process startup. It therefore
+// stays byte-for-byte stable across Cordis remounts/HMR while still changing
+// for a successor process, even if the wall clock is corrected backwards.
+const hostProcessStartedAt = Math.floor(performance.timeOrigin);
 
 function compatCacheGet(key) {
   const cached = compatCache.get(key);
@@ -923,6 +924,23 @@ export function restartLogPath(profileDir, profile) {
   return join(dirname(dirname(profileDir)), "guard", `restart-${profile}.log`);
 }
 
+function appendRestartDiagnostic(logPath, message) {
+  const line = `[dsh-plugin-mall] ${message}\n`;
+  console.error(line.trimEnd());
+  if (logPath === undefined) return;
+  let fd;
+  try {
+    fd = openSync(logPath, "a");
+    writeSync(fd, line);
+  } catch {
+    /* the console diagnostic is still useful */
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* already closed */ }
+    }
+  }
+}
+
 // ── in-process job tracker for browser RPC ───────────────────────────────────
 
 let trackerCounter = 0;
@@ -1713,7 +1731,7 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker) {
       // dropping all React state. The task records live here.
       try {
         const session = requireBrowserSession(payload?.session);
-        return rpcOk({ jobs: tracker.list(session), hostStartedAt: pluginLoadedAt });
+        return rpcOk({ jobs: tracker.list(session), hostStartedAt: hostProcessStartedAt });
       } catch (error) {
         return rpcFail(error);
       }
@@ -1727,6 +1745,12 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker) {
       }
       const plan = resolveRestartLaunchPlan({ profile, config });
       if (!plan.ok) {
+        let diagnosticPath;
+        try {
+          diagnosticPath = restartLogPath(resolveProfileDir(profile), profile);
+          mkdirSync(dirname(diagnosticPath), { recursive: true });
+        } catch { /* invalid profile/home: console remains the diagnostic sink */ }
+        appendRestartDiagnostic(diagnosticPath, `restart plan rejected: ${plan.error}; old Host remains running`);
         return rpcFail(new Error(plan.error));
       }
       // Everything the restart prints goes to a file. `stdio: "ignore"` used to
@@ -1745,17 +1769,50 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker) {
         console.error(`[dsh-plugin-mall] restart log unavailable (${error.message}); continuing without it`);
         logFd = undefined;
       }
-      const child = spawn(plan.nodePath, plan.args, {
-        shell: false,
-        detached: true,
-        stdio: logFd === undefined ? "ignore" : ["ignore", logFd, logFd],
-        cwd: process.cwd(),
-        windowsHide: true,
+      let child;
+      try {
+        child = spawn(plan.nodePath, plan.args, {
+          shell: false,
+          detached: true,
+          // fd 3 is an IPC channel used only for the readiness handshake. An
+          // old/incompatible CLI either exits on --await-exit or times out; it
+          // can never make the current Host leave merely by spawning.
+          stdio: ["ignore", logFd ?? "ignore", logFd ?? "ignore", "ipc"],
+          cwd: process.cwd(),
+          windowsHide: true,
+        });
+      } catch (error) {
+        if (logFd !== undefined) closeSync(logFd);
+        appendRestartDiagnostic(logPath, `restart helper could not be spawned: ${error.message}; old Host remains running`);
+        return rpcFail(new Error(`automatic restart helper could not be spawned; the current dsh is still running${logPath ? ` (see ${logPath})` : ""}`));
+      }
+      if (logFd !== undefined) closeSync(logFd); // the child holds its own duplicates
+
+      const handoff = superviseRestartHelper(child, {
+        awaitExitPid: plan.awaitExitPid,
+        onFailure: (message) => appendRestartDiagnostic(logPath, `${message}; old Host remains running`),
       });
-      child.unref();
-      if (logFd !== undefined) closeSync(logFd); // the child holds its own duplicate
-      setTimeout(() => process.exit(0), 1000);
-      return rpcOk({ restarting: true, logPath });
+      let disposeHandoffEffect;
+      try {
+        // Cordis runs this disposer on HMR/config unload. In particular, the
+        // process-exit timer can no longer outlive the plugin instance that
+        // created it and kill the Host one second later.
+        disposeHandoffEffect = ctx.effect(
+          () => handoff.dispose,
+          "@1e0zj/dsh-plugin-mall: restart handoff",
+        );
+      } catch (error) {
+        handoff.dispose();
+        appendRestartDiagnostic(logPath, `restart handoff could not join the plugin lifecycle: ${error.message}; old Host remains running`);
+        return rpcFail(new Error("automatic restart was cancelled because the marketplace plugin is unloading; the current dsh is still running"));
+      }
+
+      const accepted = await handoff.ready;
+      if (!accepted.ok) {
+        await disposeHandoffEffect();
+        return rpcFail(new Error(`${accepted.error}; the current dsh is still running${logPath ? ` (see ${logPath})` : ""}`));
+      }
+      return rpcOk({ restarting: true, handoffAccepted: true, logPath });
     }
     case "jobCancel": {
       try {
@@ -2627,6 +2684,164 @@ export async function runSelfTests() {
 
     check("重启日志落在 <home>/guard/ 下", restartLogPath(join("/h", "profiles", "web"), "web").replace(/\\/g, "/").endsWith("/h/guard/restart-web.log"));
 
+    {
+      const dshHomeBefore = process.env.DSH_HOME;
+      const consoleErrorBefore = console.error;
+      const diagnostics = [];
+      const fixtureHome = join(root, "restart-plan-home");
+      let response;
+      let logged = "";
+      try {
+        process.env.DSH_HOME = fixtureHome;
+        console.error = (...args) => { diagnostics.push(args.join(" ")); };
+        response = await rpcDispatch(
+          {},
+          "restart",
+          { profile: "web", session: `sess_${"a".repeat(32)}` },
+          { defaultProfile: "web", allowRestart: false },
+          undefined,
+          {},
+        );
+        logged = readFileSync(join(fixtureHome, "guard", "restart-web.log"), "utf8");
+      } finally {
+        console.error = consoleErrorBefore;
+        if (dshHomeBefore === undefined) delete process.env.DSH_HOME;
+        else process.env.DSH_HOME = dshHomeBefore;
+      }
+      check(
+        "重启 plan 失败 → 页面返回原错误且诊断同时落盘",
+        response?.ok === false && /restart disabled/.test(response.error?.message)
+          && /restart plan rejected: restart disabled/.test(logged)
+          && diagnostics.some((line) => /restart plan rejected/.test(line)),
+      );
+    }
+
+    // The restart helper is a protocol peer, not merely a spawned pid. These
+    // fixtures pin the fail-safe: every pre-handoff failure keeps the old Host
+    // alive, while only an explicit, stable readiness message permits exit.
+    {
+      class FakeRestartChild extends EventEmitter {
+        constructor() {
+          super();
+          this.connected = true;
+          this.exitCode = null;
+          this.signalCode = null;
+          this.killed = false;
+          this.killCalls = 0;
+          this.unrefCalls = 0;
+          this.disconnectCalls = 0;
+        }
+        kill() { this.killed = true; this.killCalls++; }
+        unref() { this.unrefCalls++; }
+        disconnect() { this.connected = false; this.disconnectCalls++; }
+        exit(code, signal = null) {
+          this.exitCode = code;
+          this.signalCode = signal;
+          this.emit("exit", code, signal);
+        }
+      }
+      const wait = (ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+      const supervise = (child, overrides = {}) => {
+        let hostExits = 0;
+        const failures = [];
+        const handoff = superviseRestartHelper(child, {
+          awaitExitPid: 4242,
+          handshakeTimeoutMs: 30,
+          stabilityMs: 4,
+          responseDelayMs: 4,
+          onHostExit: () => { hostExits++; },
+          onFailure: (message, meta) => { failures.push({ message, meta }); },
+          ...overrides,
+        });
+        return { handoff, failures, hostExits: () => hostExits };
+      };
+
+      const spawnErrorChild = new FakeRestartChild();
+      const spawnError = supervise(spawnErrorChild);
+      spawnErrorChild.emit("error", new Error("ENOENT"));
+      const spawnErrorReady = await spawnError.handoff.ready;
+      await wait(10);
+      check(
+        "重启 helper spawn error → 旧 Host 不退出且 error listener 已清理",
+        !spawnErrorReady.ok && /ENOENT/.test(spawnErrorReady.error)
+          && spawnError.hostExits() === 0
+          && spawnErrorChild.listenerCount("error") === 0,
+      );
+
+      const usageChild = new FakeRestartChild();
+      const usage = supervise(usageChild);
+      usageChild.exit(2);
+      const usageReady = await usage.handoff.ready;
+      await wait(10);
+      check(
+        "旧 CLI 因 --await-exit 以 code 2 快速退出 → 旧 Host 保持运行",
+        !usageReady.ok && /code 2/.test(usageReady.error) && usage.hostExits() === 0,
+      );
+
+      const silentChild = new FakeRestartChild();
+      const silent = supervise(silentChild, { handshakeTimeoutMs: 8 });
+      const silentReady = await silent.handoff.ready;
+      check(
+        "helper 建立后静默至握手超时 → 终止 helper 且旧 Host 保持运行",
+        !silentReady.ok && /did not acknowledge/.test(silentReady.error)
+          && silentChild.killCalls === 1 && silent.hostExits() === 0
+          && silentChild.listenerCount("message") === 0,
+      );
+
+      const mismatchChild = new FakeRestartChild();
+      const mismatch = supervise(mismatchChild);
+      mismatchChild.emit("message", { type: RESTART_HELPER_READY_TYPE, protocol: 99, awaitExitPid: 4242 });
+      const mismatchReady = await mismatch.handoff.ready;
+      check(
+        "同版本不同内容/协议不匹配 → fail closed，不靠 package version 放行",
+        !mismatchReady.ok && /protocol mismatch/.test(mismatchReady.error)
+          && mismatchChild.killCalls === 1 && mismatch.hostExits() === 0,
+      );
+
+      const unstableChild = new FakeRestartChild();
+      const unstable = supervise(unstableChild, { stabilityMs: 20 });
+      unstableChild.emit("message", createRestartHelperReadyMessage(4242));
+      unstableChild.exit(1);
+      const unstableReady = await unstable.handoff.ready;
+      check(
+        "helper 握手后在稳定窗口内退出 → 取消旧 Host 退出",
+        !unstableReady.ok && unstable.hostExits() === 0,
+      );
+
+      const healthyChild = new FakeRestartChild();
+      const healthy = supervise(healthyChild);
+      healthyChild.emit("message", createRestartHelperReadyMessage(4242));
+      const healthyReady = await healthy.handoff.ready;
+      await wait(12);
+      check(
+        "helper 明确握手并活过稳定窗口 → 旧 Host 只退出一次",
+        healthyReady.ok && healthy.hostExits() === 1
+          && healthyChild.disconnectCalls === 1 && healthyChild.unrefCalls === 1,
+      );
+
+      const disposedChild = new FakeRestartChild();
+      const disposed = supervise(disposedChild, { responseDelayMs: 40 });
+      disposedChild.emit("message", createRestartHelperReadyMessage(4242));
+      const disposedReady = await disposed.handoff.ready;
+      disposed.handoff.dispose(); // mirrors the disposer returned from ctx.effect()
+      await wait(50);
+      check(
+        "插件卸载/HMR disposer → 清理退出 timer、结束 helper、旧 Host 不退出",
+        disposedReady.ok && disposed.hostExits() === 0 && disposedChild.killCalls === 1
+          && disposedChild.listenerCount("exit") === 0,
+      );
+
+      check(
+        "默认保留旧实现的一秒 RPC 响应排空窗口",
+        RESTART_RESPONSE_DRAIN_MS === 1000,
+      );
+      check(
+        "进程启动标识来自稳定的 performance.timeOrigin",
+        Number.isFinite(hostProcessStartedAt)
+          && hostProcessStartedAt > 0 && hostProcessStartedAt <= Date.now(),
+      );
+    }
+
     // ── 7. Tracker isolation: producer.done rejection handling ───────────────
     let settledOutcome = null;
     const rejectingProducer = {

package/src/restart-protocol.js

@@ -0,0 +1,144 @@
+// Host-independent restart handoff protocol shared by the Web plugin and the
+// standalone guard CLI.  The parent must not infer readiness from a child pid:
+// an incompatible CLI can spawn successfully and then die on argument parsing.
+
+export const RESTART_HELPER_READY_TYPE = "@1e0zj/dsh-plugin-mall:restart-helper-ready";
+export const RESTART_HELPER_PROTOCOL_VERSION = 1;
+export const RESTART_RESPONSE_DRAIN_MS = 1000;
+
+export function createRestartHelperReadyMessage(awaitExitPid) {
+  return {
+    type: RESTART_HELPER_READY_TYPE,
+    protocol: RESTART_HELPER_PROTOCOL_VERSION,
+    awaitExitPid,
+  };
+}
+
+function describeExit(code, signal) {
+  if (typeof code === "number") return ` with code ${code}`;
+  if (signal) return ` from signal ${signal}`;
+  return "";
+}
+
+/**
+ * Keep the outgoing Host alive until the detached helper explicitly confirms
+ * that it parsed the current protocol and is waiting for that Host's pid.
+ *
+ * The returned disposer is suitable for ctx.effect(): unloading the plugin
+ * cancels every timer, removes listeners, and terminates the waiting helper.
+ */
+export function superviseRestartHelper(child, {
+  awaitExitPid,
+  handshakeTimeoutMs = 2000,
+  stabilityMs = 600,
+  responseDelayMs = RESTART_RESPONSE_DRAIN_MS,
+  onHostExit = () => process.exit(0),
+  onFailure = () => {},
+} = {}) {
+  let phase = "handshake";
+  let timer;
+  let readySettled = false;
+  let resolveReady;
+  const ready = new Promise((resolvePromise) => { resolveReady = resolvePromise; });
+
+  const clearTimer = () => {
+    if (timer === undefined) return;
+    clearTimeout(timer);
+    timer = undefined;
+  };
+  const removeListeners = () => {
+    child.removeListener("message", onMessage);
+    child.removeListener("error", onError);
+    child.removeListener("exit", onExit);
+  };
+  const terminateChild = () => {
+    if (child.exitCode !== null && child.exitCode !== undefined) return;
+    if (child.signalCode !== null && child.signalCode !== undefined) return;
+    if (child.killed === true) return;
+    try { child.kill(); } catch { /* already gone */ }
+  };
+  const settleReady = (result) => {
+    if (readySettled) return;
+    readySettled = true;
+    resolveReady(result);
+  };
+  const fail = (message, { terminate = false } = {}) => {
+    if (phase === "failed" || phase === "disposed" || phase === "committed") return;
+    const afterReady = readySettled;
+    phase = "failed";
+    clearTimer();
+    removeListeners();
+    if (terminate) terminateChild();
+    settleReady({ ok: false, error: message });
+    try { onFailure(message, { afterReady }); } catch { /* diagnostics are best effort */ }
+  };
+
+  function onError(error) {
+    fail(`restart helper failed to start: ${error?.message ?? String(error)}`);
+  }
+  function onExit(code, signal) {
+    fail(`restart helper exited before handoff${describeExit(code, signal)}`);
+  }
+  function onMessage(message) {
+    if (phase !== "handshake" || message?.type !== RESTART_HELPER_READY_TYPE) return;
+    if (message.protocol !== RESTART_HELPER_PROTOCOL_VERSION || message.awaitExitPid !== awaitExitPid) {
+      fail(
+        `restart helper protocol mismatch (expected v${RESTART_HELPER_PROTOCOL_VERSION} for pid ${awaitExitPid})`,
+        { terminate: true },
+      );
+      return;
+    }
+    phase = "stability";
+    clearTimer();
+    // A successful helper is blocked in --await-exit until this Host leaves.
+    // Observe it briefly so a parse/startup failure cannot masquerade as an
+    // accepted handoff merely because the IPC message won a scheduling race.
+    timer = setTimeout(() => {
+      if (phase !== "stability") return;
+      phase = "accepted";
+      try {
+        if (child.connected === true) child.disconnect();
+      } catch { /* the ready message already proved the channel worked */ }
+      try { child.unref(); } catch { /* ChildProcess-compatible fakes may omit it */ }
+      settleReady({ ok: true });
+      // Preserve the old implementation's one-second response-drain window.
+      // The RPC layer does not expose a response-flushed callback. The exit
+      // listener remains active: if the helper dies here, the timer is
+      // cancelled and the old Host stays.
+      timer = setTimeout(() => {
+        if (phase !== "accepted") return;
+        phase = "committed";
+        timer = undefined;
+        removeListeners();
+        try {
+          onHostExit();
+        } catch (error) {
+          phase = "failed";
+          try { onFailure(`could not exit old Host: ${error?.message ?? String(error)}`, { afterReady: true }); } catch { /* best effort */ }
+        }
+      }, responseDelayMs);
+    }, stabilityMs);
+  }
+
+  child.on("message", onMessage);
+  child.once("error", onError);
+  child.once("exit", onExit);
+  timer = setTimeout(() => {
+    fail(`restart helper did not acknowledge protocol v${RESTART_HELPER_PROTOCOL_VERSION} within ${handshakeTimeoutMs}ms`, { terminate: true });
+  }, handshakeTimeoutMs);
+
+  const dispose = () => {
+    if (phase === "failed" || phase === "disposed" || phase === "committed") return;
+    phase = "disposed";
+    clearTimer();
+    removeListeners();
+    terminateChild();
+    settleReady({ ok: false, error: "restart handoff cancelled because the plugin unloaded" });
+  };
+
+  return {
+    ready,
+    dispose,
+    state: () => phase,
+  };
+}