@1e0zj/dsh-plugin-mall 0.4.7 → 0.4.14

package/src/index.js

@@ -16,7 +16,7 @@
 import z from "@deepseek-ai/schemastery";
 import { valid as validExactVersion, maxSatisfying } from "semver";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { existsSync, readFileSync, realpathSync, mkdirSync, mkdtempSync, writeFileSync, rmSync, openSync, closeSync, writeSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, realpathSync, mkdirSync, mkdtempSync, utimesSync, writeFileSync, rmSync, openSync, closeSync, writeSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
@@ -29,7 +29,10 @@ import { resolveProfileDir } from "@deepseek-ai/dsh-app-boot";
 import { repoInfo, searchPlugins, verifyPlugins, cachedRepoManifest, fetchRawFile, preferNpmSpec, npmPackageInfo, npmPackageVersions, npmNameOf, 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, isAbortError } from "./guard.js";
-import { createRestartHelperReadyMessage, RESTART_HELPER_READY_TYPE, RESTART_RESPONSE_DRAIN_MS, superviseRestartHelper } from "./restart-protocol.js";
+import {
+  createRestartHelperReadyMessage, RESTART_HELPER_READY_TYPE, RESTART_RESPONSE_DRAIN_MS, superviseRestartHelper,
+  RESTART_PLAN_TYPE, RESTART_PLAN_VERSION, quoteCmdArg, readRestartHelperReadyFile, superviseRestartHelperFile, validateRestartPlanPayload, writeRestartHelperReadyFile,
+} from "./restart-protocol.js";
 
 export const name = "@1e0zj/dsh-plugin-mall";
 // `loader` 用来读装配树、并对单个 entry 做热开关（entry.update）。读法照抄
@@ -1023,13 +1026,12 @@ export function resolveRestartLaunchPlan({ profile, config = {}, isWindows }) {
 
   const nodePath = process.execPath;
   const originalDshArgs = process.argv.slice(2);
-  // A restart is always requested from a page that is open and that reconnects
-  // to the successor on its own, so dsh's start-up browser handoff would only
-  // add a second window onto the one already showing the result. Suppressing it
-  // is safe HERE and nowhere else: this route is gated on a live browser
-  // session. If the flag is already in the original argv, leave it alone.
-  const suppressOpen = !originalDshArgs.includes("--no-open");
-  const dshArgs = suppressOpen ? [...originalDshArgs, "--no-open"] : [...originalDshArgs];
+  // Restart the exact command the user started. `--no-open` belongs to newer
+  // Web profiles, not to the stable dsh launcher contract; adding it here made
+  // older hosts reject the successor with "unknown option '--no-open'" after
+  // the outgoing process had already exited. A duplicate browser tab is less
+  // harmful than inventing an argv capability the running host never proved.
+  const dshArgs = [...originalDshArgs];
   // The outgoing host names itself so `guard launch` can wait for it to be
   // gone before binding the port — see --await-exit in cli.js.
   const args = [cliPath, "guard", "launch", "--profile", name, "--await-exit", String(process.pid), "--", nodePath, dshEntry, ...dshArgs];
@@ -1040,8 +1042,8 @@ export function resolveRestartLaunchPlan({ profile, config = {}, isWindows }) {
     args,
     cliPath,
     dshEntry,
+    dshArgs,
     profile: name,
-    suppressedBrowserOpen: suppressOpen,
     awaitExitPid: process.pid,
   };
 }
@@ -1075,6 +1077,137 @@ function appendRestartDiagnostic(logPath, message) {
   }
 }
 
+// ── visible-console restart (Windows, interactive terminal) ──────────────────
+
+// One handoff at a time, process-wide: two concurrent restart requests (two
+// tabs, or the dialog racing the panel button) would spawn two guards that
+// both wait for this Host and then both start successors — a port collision
+// that probation would misread as "the pending install crashed dsh" and roll
+// back. Reset only on the failure paths; success exits the process.
+let restartHandoffInFlight = false;
+
+/**
+ * The restart goes visible only on an interactive Windows console. Two
+ * spellings of "interactive": the original terminal (stdout is a TTY), or a
+ * dsh that was itself launched by the tee'd visible guard — its stdout is
+ * the tee's PIPE, so the guard marks the chain with
+ * DSH_PLUGIN_MALL_VISIBLE_CONSOLE and the TTY signal survives restarts.
+ */
+export function wantsVisibleConsoleRestart() {
+  if (process.platform !== "win32") return false;
+  if (process.stdout.isTTY === true) return true;
+  return process.env.DSH_PLUGIN_MALL_VISIBLE_CONSOLE === "1";
+}
+
+/**
+ * Best-effort sweep of a previous request's plan/ready leftovers in
+ * <home>/guard. Correctness never depends on it: the file names are
+ * per-request unique, so stale files are inert clutter — EXCEPT cancel
+ * sentinels, which are NEVER swept, however old: a paused/suspended guard
+ * has no visible lifetime ceiling, and deleting a sentinel its guard has
+ * not consumed yet is how a retry resurrects a cancelled guard beside its
+ * own one. A sentinel dies only when its guard consumes it; the price is a
+ * few tiny nonce files left behind when a guard never wakes — cheap next
+ * to two successors colliding on the listening port.
+ */
+function sweepStaleRestartHandoffs(guardDir, profile) {
+  let names;
+  try {
+    names = readdirSync(guardDir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (name.endsWith(".cancel")) continue;
+    if (name.startsWith(`restart-plan-${profile}-`) || name.startsWith(`restart-ready-${profile}-`)) {
+      try { rmSync(join(guardDir, name), { force: true }); } catch { /* inert residue */ }
+    }
+  }
+}
+
+/**
+ * Write the launch plan the visible guard will consume (`--plan-file`). The
+ * wrapped dsh argv travels as JSON — never through the cmd command line, where
+ * spaces, quotes and metacharacters would be re-parsed. The plan does NOT
+ * carry the home dir: the guard inherits DSH_HOME through cmd → start and
+ * resolves it itself, one less path to trust.
+ */
+function writeVisibleRestartPlan({ plan, logPath }) {
+  if (typeof logPath !== "string" || logPath.length === 0) {
+    return { ok: false, error: "restart log path unavailable" };
+  }
+  try {
+    const guardDir = dirname(logPath);
+    mkdirSync(guardDir, { recursive: true });
+    sweepStaleRestartHandoffs(guardDir, plan.profile);
+    const nonce = randomBytes(6).toString("hex");
+    const suffix = `${plan.profile}-${plan.awaitExitPid}-${nonce}`;
+    const planPath = join(guardDir, `restart-plan-${suffix}.json`);
+    const readyFile = join(guardDir, `restart-ready-${suffix}.json`);
+    writeFileSync(planPath, `${JSON.stringify({
+      version: RESTART_PLAN_VERSION,
+      type: RESTART_PLAN_TYPE,
+      profile: plan.profile,
+      awaitExitPid: plan.awaitExitPid,
+      logPath,
+      readyFile,
+      cwd: process.cwd(),
+      command: plan.nodePath,
+      args: [plan.dshEntry, ...plan.dshArgs],
+    }, null, 2)}\n`);
+    return { ok: true, planPath, readyFile };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
+/**
+ * Join the handoff to the plugin lifecycle. Cordis runs the callback
+ * IMMEDIATELY and registers its RETURN VALUE as the disposer — so the
+ * callback must merely build the disposer, never perform the disposal
+ * (a block body here disposed the handoff at registration time and broke
+ * every restart; pinned by fixture). The disposer also releases the
+ * in-flight latch: a disposed handoff is over, the old Host stays.
+ */
+function registerRestartHandoffEffect(ctx, handoff) {
+  return ctx.effect(
+    () => () => { handoff.dispose(); restartHandoffInFlight = false; },
+    "@1e0zj/dsh-plugin-mall: restart handoff",
+  );
+}
+
+/**
+ * Launch the visible guard: a new console window via `cmd /d /s /c start`
+ * (never /b — the window is the feature). cmd returns immediately; the guard
+ * runs as a grandchild with no stdio or IPC link back, which is why the
+ * handoff moves to the ready file. Every token on the line is strictly
+ * quoted — a path cmd cannot digest is a construction failure, and the
+ * caller falls back to the background path rather than mangling the command.
+ */
+function spawnVisibleRestartGuard({ plan, planPath, _spawn = spawn }) {
+  let child;
+  try {
+    const line = [
+      "start",
+      quoteCmdArg(`dsh guard - ${plan.profile}`),
+      [plan.nodePath, plan.cliPath, "guard", "launch", "--plan-file", planPath].map(quoteCmdArg).join(" "),
+    ].join(" ");
+    child = _spawn(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", `"${line}"`], {
+      shell: false,
+      detached: true,
+      stdio: "ignore",
+      cwd: process.cwd(),
+      env: process.env,
+      windowsVerbatimArguments: true,
+      windowsHide: false,
+    });
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+  try { child.unref(); } catch { /* ChildProcess-compatible fakes may omit it */ }
+  return { ok: true, child };
+}
+
 // ── in-process job tracker for browser RPC ───────────────────────────────────
 
 let trackerCounter = 0;
@@ -2152,6 +2285,15 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker, signa
       } catch (error) {
         return rpcFail(error);
       }
+      // One handoff at a time, process-wide, checked BEFORE anything else
+      // opens files or resolves plans: two concurrent requests would spawn
+      // two guards that both wait for this Host and then both start a
+      // successor — a port collision probation would misread as a bad
+      // install. Reset only on the failure paths; success exits the process.
+      if (restartHandoffInFlight) {
+        return rpcFail(new Error("a restart handoff is already in progress — the page reconnects on its own once it completes"));
+      }
+      restartHandoffInFlight = true;
       const plan = resolveRestartLaunchPlan({ profile, config });
       if (!plan.ok) {
         let diagnosticPath;
@@ -2160,6 +2302,7 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker, signa
           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`);
+        restartHandoffInFlight = false;
         return rpcFail(new Error(plan.error));
       }
       // Everything the restart prints goes to a file. `stdio: "ignore"` used to
@@ -2178,40 +2321,104 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker, signa
         console.error(`[dsh-plugin-mall] restart log unavailable (${error.message}); continuing without it`);
         logFd = undefined;
       }
+      let handoff;
+      let mode = "background";
+      let visiblePlan;
+      if (wantsVisibleConsoleRestart()) {
+        // The interactive path: a visible console window runs the guard, its
+        // output is teed to the window and this log, and the handoff travels
+        // through the ready file (cmd /c start leaves no IPC link). Any
+        // CONSTRUCTION failure here falls back to the background path — a
+        // half-built window must never block the restart itself. A handoff
+        // failure after the spawn does NOT retry: re-spawning while the first
+        // guard might just be slow would create two successors.
+        if (logFd !== undefined) {
+          closeSync(logFd); // the visible guard opens the log itself (tee)
+          logFd = undefined;
+        }
+        visiblePlan = writeVisibleRestartPlan({ plan, logPath });
+        if (visiblePlan.ok) {
+          const spawned = spawnVisibleRestartGuard({ plan, planPath: visiblePlan.planPath });
+          if (spawned.ok) {
+            mode = "visible";
+            handoff = superviseRestartHelperFile({
+              readyFile: visiblePlan.readyFile,
+              awaitExitPid: plan.awaitExitPid,
+              onFailure: (message, meta) => {
+                appendRestartDiagnostic(logPath, `${message}; old Host remains running`);
+                // The RPC already answered ok when a post-ready death happens:
+                // the old Host correctly stays, but this handoff is over —
+                // unlock restarts, or one dead helper bricks the button
+                // until a manual restart.
+                if (meta?.afterReady === true) restartHandoffInFlight = false;
+              },
+            });
+            // start makes cmd return immediately and its exit code is
+            // unreliable (a failed start can still exit 0), so this fast-fail
+            // is a bonus, not the mechanism — the handshake timeout is what
+            // actually bounds the wait.
+            spawned.child.once("exit", (code) => {
+              if (code !== 0 && code !== null && handoff.state() === "handshake") {
+                handoff.failFast(`cmd exited with code ${code} before the guard announced itself`);
+              }
+            });
+            spawned.child.once("error", () => {
+              if (handoff.state() === "handshake") {
+                handoff.failFast("cmd failed before the guard announced itself");
+              }
+            });
+          } else {
+            appendRestartDiagnostic(logPath, `visible console unavailable (${spawned.error}); continuing on the background path`);
+            try { rmSync(visiblePlan.planPath, { force: true }); } catch { /* inert residue */ }
+          }
+        } else {
+          appendRestartDiagnostic(logPath, `visible console unavailable (${visiblePlan.error}); continuing on the background path`);
+        }
+      }
+
       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,
+      if (mode === "background") {
+        // A visible→background fallback closed the fd above; reopen it, or
+        // the background helper's output (including any rollback line) would
+        // go nowhere at all.
+        if (logFd === undefined && logPath !== undefined) {
+          try { logFd = openSync(logPath, "a"); } catch { logFd = undefined; }
+        }
+        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);
+          restartHandoffInFlight = false;
+          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
+
+        handoff = superviseRestartHelper(child, {
+          awaitExitPid: plan.awaitExitPid,
+          onFailure: (message, meta) => {
+            appendRestartDiagnostic(logPath, `${message}; old Host remains running`);
+            // Same unlock as the visible path: a helper dying after the RPC
+            // answered must not leave the one-restart-at-a-time latch stuck.
+            if (meta?.afterReady === true) restartHandoffInFlight = false;
+          },
         });
-      } 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`),
-      });
       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",
-        );
+        disposeHandoffEffect = registerRestartHandoffEffect(ctx, handoff);
       } catch (error) {
         handoff.dispose();
+        restartHandoffInFlight = false;
         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"));
       }
@@ -2219,9 +2426,18 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker, signa
       const accepted = await handoff.ready;
       if (!accepted.ok) {
         await disposeHandoffEffect();
+        restartHandoffInFlight = false;
+        if (mode === "visible" && visiblePlan?.ok) {
+          // Cancel sentinel for a guard that may merely be SLOW: we cannot
+          // kill it (cmd /c start hid its pid from us), so before the user
+          // retries, leave a mark the guard checks after its await-exit wait
+          // ends — a second successor next to the retry's one is exactly the
+          // port collision probation misreads as a bad install.
+          try { writeFileSync(`${visiblePlan.readyFile}.cancel`, `cancelled ${new Date().toISOString()}: ${accepted.error}\n`); } catch { /* best effort */ }
+        }
         return rpcFail(new Error(`${accepted.error}; the current dsh is still running${logPath ? ` (see ${logPath})` : ""}`));
       }
-      return rpcOk({ restarting: true, handoffAccepted: true, logPath });
+      return rpcOk({ restarting: true, handoffAccepted: true, logPath, mode });
     }
     case "jobCancel": {
       try {
@@ -3132,14 +3348,15 @@ export async function runSelfTests() {
           const dshArgs = plan.args.slice(dashDash + 3); // -- node <dshEntry> …
           check("重启带 --await-exit 且是本进程 pid", plan.args[plan.args.indexOf("--await-exit") + 1] === String(process.pid) && plan.awaitExitPid === process.pid);
           check("--await-exit 排在 `--` 之前（是 guard 的参数，不是 dsh 的）", plan.args.indexOf("--await-exit") < dashDash);
-          check("重启给 dsh 补 --no-open", dshArgs.includes("--no-open") && plan.suppressedBrowserOpen === true);
-          check("原始 dsh 参数原样保留", dshArgs.slice(0, 2).join(" ") === "--profile web");
+          check("重启不注入宿主版本相关参数", dshArgs.join(" ") === "--profile web" && !dshArgs.includes("--no-open"));
+          check("原始 dsh 参数原样保留", dshArgs.join(" ") === "--profile web");
+          check("plan 附带可见模式所需的 dshArgs", plan.dshArgs.join(" ") === dshArgs.join(" "));
 
-          // 用户自己已经写了 --no-open 时不重复追加。
+          // 用户自己传给宿主的参数仍逐字保留。
           process.argv = [process.execPath, "/x/bin.js", "--profile", "web", "--no-open"];
           const already = resolveRestartLaunchPlan({ profile: "web", config: { allowRestart: true } });
           const alreadyArgs = already.ok ? already.args.slice(already.args.indexOf("--") + 3) : [];
-          check("已有 --no-open 则不重复追加", already.ok && alreadyArgs.filter((a) => a === "--no-open").length === 1 && already.suppressedBrowserOpen === false);
+          check("用户原有 --no-open 原样保留", already.ok && alreadyArgs.filter((a) => a === "--no-open").length === 1);
         } else {
           // 裸检出里解析不到官方 dsh 入口，plan 只能 fail——说清楚，别假装验过。
           console.log(`  SKIP 重启 argv fixture（${plan.error}）`);
@@ -3309,6 +3526,350 @@ export async function runSelfTests() {
       );
     }
 
+    // File-channel handoff (the visible-console path): the ready file replaces
+    // the IPC message while the phase machine must stay equivalent — including
+    // the accepted-phase liveness watch that keeps a post-RPC death from
+    // costing the old Host its exit.
+    {
+      const fileRoot = mkdtempSync(join(tmpdir(), "dsh-mall-restart-file-"));
+      try {
+        const awaitPid = 4711;
+        const pause = (ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+        const basePlan = {
+          version: 1,
+          type: RESTART_PLAN_TYPE,
+          profile: "web",
+          awaitExitPid: awaitPid,
+          logPath: "C:/l/restart-web.log",
+          readyFile: join(fileRoot, "r1.json"),
+          cwd: "C:/w",
+          command: "C:/node/node.exe",
+          args: ["C:/dsh/index.js", "web"],
+        };
+        check("plan payload 校验通过", validateRestartPlanPayload(basePlan).ok === true);
+        for (const [override, needle] of [
+          [{ version: 2 }, "version"],
+          [{ type: "someone-elses-plan" }, "type"],
+          [{ args: ["C:/dsh/index.js", 3] }, "args"],
+          [{ awaitExitPid: 0 }, "awaitExitPid"],
+          [{ logPath: "" }, "logPath"],
+          [{ command: 42 }, "command"],
+        ]) {
+          const badResult = validateRestartPlanPayload({ ...basePlan, ...override });
+          check(
+            `plan payload 拒绝坏 ${needle}`,
+            badResult.ok === false && new RegExp(needle).test(badResult.error),
+          );
+        }
+        check("plan payload 拒绝非对象", validateRestartPlanPayload("nope").ok === false);
+        check(
+          "readRestartHelperReadyFile 对缺失/坏文件读作未就绪",
+          readRestartHelperReadyFile(join(fileRoot, "missing.json")) === undefined
+            && (() => {
+              writeFileSync(join(fileRoot, "garbage.json"), "{ half-written");
+              return readRestartHelperReadyFile(join(fileRoot, "garbage.json")) === undefined;
+            })(),
+        );
+
+        const mkFileSupervise = (name, overrides = {}) => {
+          let hostExits = 0;
+          const failures = [];
+          const kills = [];
+          const handoff = superviseRestartHelperFile({
+            readyFile: join(fileRoot, name),
+            awaitExitPid: awaitPid,
+            handshakeTimeoutMs: 80,
+            stabilityMs: 60,
+            responseDelayMs: 120,
+            pollMs: 2,
+            probe: () => true,
+            kill: (pid) => { kills.push(pid); },
+            onHostExit: () => { hostExits++; },
+            onFailure: (message, meta) => { failures.push({ message, meta }); },
+            ...overrides,
+          });
+          return { handoff, kills, failures, hostExits: () => hostExits };
+        };
+
+        const good = mkFileSupervise("good.json", { stabilityMs: 8, responseDelayMs: 8 });
+        writeRestartHelperReadyFile(join(fileRoot, "good.json"), { awaitExitPid: awaitPid, guardPid: 31337 });
+        const goodReady = await good.handoff.ready;
+        await pause(60);
+        check(
+          "文件握手成功 → ready 文件被父删除、旧 Host 恰退出一次、不 kill",
+          goodReady.ok === true && good.hostExits() === 1
+            && !existsSync(join(fileRoot, "good.json"))
+            && good.kills.length === 0 && good.failures.length === 0,
+        );
+
+        const mismatch = mkFileSupervise("mismatch.json");
+        writeFileSync(join(fileRoot, "mismatch.json"), JSON.stringify({
+          type: RESTART_HELPER_READY_TYPE, protocol: 99, awaitExitPid: awaitPid, guardPid: 31338,
+        }));
+        const mismatchReady = await mismatch.handoff.ready;
+        check(
+          "文件握手协议不匹配 → kill 该 helper 恰一次、旧 Host 不退",
+          mismatchReady.ok === false && /protocol mismatch/.test(mismatchReady.error)
+            && mismatch.kills.length === 1 && mismatch.hostExits() === 0
+            && !existsSync(join(fileRoot, "mismatch.json")),
+        );
+
+        const wrongPid = mkFileSupervise("wrongpid.json");
+        writeRestartHelperReadyFile(join(fileRoot, "wrongpid.json"), { awaitExitPid: 9999, guardPid: 31339 });
+        const wrongPidReady = await wrongPid.handoff.ready;
+        check(
+          "ready 文件 awaitExitPid 不匹配 → fail closed 且 kill 一次",
+          wrongPidReady.ok === false && /protocol mismatch/.test(wrongPidReady.error)
+            && wrongPid.kills.length === 1 && wrongPid.hostExits() === 0,
+        );
+
+        const garbage = mkFileSupervise("garbage2.json", { handshakeTimeoutMs: 30 });
+        writeFileSync(join(fileRoot, "garbage2.json"), "{ still not json");
+        const garbageReady = await garbage.handoff.ready;
+        check(
+          "半截/无关 ready 文件 → 容忍到握手超时、绝不 kill 未知 pid",
+          garbageReady.ok === false && /did not write/.test(garbageReady.error)
+            && garbage.kills.length === 0 && garbage.hostExits() === 0,
+        );
+
+        let midAlive = true;
+        const mid = mkFileSupervise("mid.json", { probe: (pid) => midAlive });
+        writeRestartHelperReadyFile(join(fileRoot, "mid.json"), { awaitExitPid: awaitPid, guardPid: 31340 });
+        await pause(20);
+        midAlive = false;
+        const midReady = await mid.handoff.ready;
+        check(
+          "稳定窗口内 helper 消失 → 取消旧 Host 退出",
+          midReady.ok === false && /stability window/.test(midReady.error) && mid.hostExits() === 0,
+        );
+
+        let lateAlive = true;
+        const late = mkFileSupervise("late.json", { probe: (pid) => lateAlive, responseDelayMs: 150 });
+        writeRestartHelperReadyFile(join(fileRoot, "late.json"), { awaitExitPid: awaitPid, guardPid: 31341 });
+        const lateReady = await late.handoff.ready; // resolves at accepted
+        lateAlive = false;
+        await pause(60);
+        check(
+          "RPC 应答后 helper 死亡 → 仍取消旧 Host 退出（accepted 持续探活）",
+          lateReady.ok === true && late.hostExits() === 0
+            && late.failures.length === 1 && late.failures[0].meta.afterReady === true,
+        );
+
+        const disposed = mkFileSupervise("disp.json", { responseDelayMs: 150 });
+        writeRestartHelperReadyFile(join(fileRoot, "disp.json"), { awaitExitPid: awaitPid, guardPid: 31342 });
+        const disposedReady = await disposed.handoff.ready;
+        disposed.handoff.dispose(); // mirrors the disposer returned from ctx.effect()
+        await pause(200);
+        check(
+          "插件卸载 dispose → 清理 timer、kill helper、旧 Host 不退",
+          disposedReady.ok === true && disposed.hostExits() === 0
+            && disposed.kills.length === 1 && disposed.handoff.state() === "disposed",
+        );
+
+        const fast = mkFileSupervise("fast.json", { handshakeTimeoutMs: 5000 });
+        fast.handoff.failFast("cmd exited with code 1 before the guard started");
+        const fastReady = await fast.handoff.ready;
+        check(
+          "failFast（cmd 先死）→ 提前失败，不等握手超时",
+          fastReady.ok === false && /cmd exited/.test(fastReady.error) && fast.hostExits() === 0,
+        );
+
+        // Every terminal state (success, failure, dispose) must leave no
+        // polling interval behind: a leaked 100ms timer keeps the Host
+        // process from ever exiting naturally.
+        const countTimers = () => process.getActiveResourcesInfo().filter((entry) => entry === "Timeout").length;
+        const timersBefore = countTimers();
+        const leak = mkFileSupervise("leak.json", { handshakeTimeoutMs: 25, pollMs: 2 });
+        const leakReady = await leak.handoff.ready;
+        await pause(60); // any surviving interval would have ticked by now
+        const leaked = countTimers() - timersBefore;
+        check(
+          "握手终态后不残留轮询 interval（进程可自然退出）",
+          leakReady.ok === false && leaked <= 0,
+        );
+      } finally {
+        rmSync(fileRoot, { recursive: true, force: true });
+      }
+    }
+
+    // Visible-console branch (interactive Windows restart): the plan file
+    // carries the wrapped argv as JSON, the cmd line is built from strictly
+    // quoted fixed tokens only, and construction failures fall back to the
+    // background path. The real window is a manual-verification item; these
+    // pin everything up to the spawn.
+    {
+      const visibleRoot = mkdtempSync(join(tmpdir(), "dsh-mall-restart-visible-"));
+      try {
+        const realIsTty = process.stdout.isTTY;
+        const realVisibleEnv = process.env.DSH_PLUGIN_MALL_VISIBLE_CONSOLE;
+        if (process.platform === "win32") {
+          try {
+            Object.defineProperty(process.stdout, "isTTY", { value: true, configurable: true });
+            check("win32 + 交互 stdout → 走可见控制台", wantsVisibleConsoleRestart() === true);
+            Object.defineProperty(process.stdout, "isTTY", { value: undefined, configurable: true });
+            check("win32 + 无 TTY → 保持后台路径", wantsVisibleConsoleRestart() === false);
+            // The tee'd guard pipes the successor's stdout: the TTY signal is
+            // gone, the env flag must carry the chain across restarts.
+            process.env.DSH_PLUGIN_MALL_VISIBLE_CONSOLE = "1";
+            check("win32 + tee 链（stdout 为管道）→ 后续重启保持可见", wantsVisibleConsoleRestart() === true);
+            delete process.env.DSH_PLUGIN_MALL_VISIBLE_CONSOLE;
+          } finally {
+            Object.defineProperty(process.stdout, "isTTY", { value: realIsTty, configurable: true });
+            if (realVisibleEnv === undefined) delete process.env.DSH_PLUGIN_MALL_VISIBLE_CONSOLE;
+            else process.env.DSH_PLUGIN_MALL_VISIBLE_CONSOLE = realVisibleEnv;
+          }
+        } else {
+          check("非 Windows 平台永不走可见控制台", wantsVisibleConsoleRestart() === false);
+        }
+
+        const guardDir = join(visibleRoot, "guard");
+        const logPath = join(guardDir, "restart-web.log");
+        mkdirSync(guardDir, { recursive: true });
+        // stale leftovers from a previous request are swept, not mistaken —
+        // but cancel sentinels are NEVER swept, however old: a paused guard
+        // has no lifetime ceiling, and deleting an unconsumed sentinel is
+        // how a retry resurrects a cancelled guard beside its own one.
+        writeFileSync(join(guardDir, "restart-plan-web-111-old.json"), "{}");
+        writeFileSync(join(guardDir, "restart-ready-web-111-old.json"), "{}");
+        const freshCancel = join(guardDir, "restart-ready-web-112-fresh.json.cancel");
+        const staleCancel = join(guardDir, "restart-ready-web-113-stale.json.cancel");
+        writeFileSync(freshCancel, "just written by a failed handoff\n");
+        writeFileSync(staleCancel, "old sentinel, guard long gone\n");
+        const staleTime = new Date(Date.now() - 24 * 60 * 60 * 1000);
+        utimesSync(staleCancel, staleTime, staleTime);
+        const launchPlan = {
+          ok: true,
+          nodePath: process.execPath,
+          cliPath: join(visibleRoot, "cli.js"),
+          dshEntry: join(visibleRoot, "dsh-entry.js"),
+          dshArgs: ["--profile", "web"],
+          profile: "web",
+          awaitExitPid: 4242,
+        };
+        const written = writeVisibleRestartPlan({ plan: launchPlan, logPath });
+        check("可见重启计划写出成功且清扫旧残留（cancel 哨兵永不清扫）", written.ok === true
+          && !existsSync(join(guardDir, "restart-plan-web-111-old.json"))
+          && !existsSync(join(guardDir, "restart-ready-web-111-old.json"))
+          && existsSync(freshCancel) === true
+          && existsSync(staleCancel) === true);
+        const planPayload = JSON.parse(readFileSync(written.planPath, "utf8"));
+        check(
+          "计划 JSON：wrapped argv 只走 JSON、不走 cmd 行、不带 home",
+          planPayload.type === RESTART_PLAN_TYPE && planPayload.version === RESTART_PLAN_VERSION
+            && planPayload.profile === "web" && planPayload.awaitExitPid === 4242
+            && planPayload.command === process.execPath
+            && planPayload.args.join(" ") === [launchPlan.dshEntry, ...launchPlan.dshArgs].join(" ")
+            && planPayload.logPath === logPath && planPayload.readyFile === written.readyFile
+            && planPayload.home === undefined,
+        );
+
+        let spawned = undefined;
+        const spawnCapture = (command, args, options) => {
+          spawned = { command, args, options };
+          return { unref() {} };
+        };
+        const okSpawn = spawnVisibleRestartGuard({ plan: launchPlan, planPath: written.planPath, _spawn: spawnCapture });
+        const cmdArg = spawned.args[3];
+        check(
+          "cmd 行：/d /s /c verbatim + start 带标题 + 全 token 引用 + 不隐藏 + detached",
+          okSpawn.ok === true
+            && spawned.command === (process.env.ComSpec ?? "cmd.exe")
+            && spawned.args[0] === "/d" && spawned.args[1] === "/s" && spawned.args[2] === "/c"
+            && cmdArg.startsWith('"start "dsh guard - web"')
+            && spawned.options.shell === false && spawned.options.detached === true
+            && spawned.options.windowsVerbatimArguments === true
+            && spawned.options.windowsHide === false
+            && spawned.options.stdio === "ignore",
+        );
+        check(
+          "cmd 行不含任何原始 dsh 参数（只有固定 token 与计划文件路径）",
+          cmdArg.includes("--profile") === false && cmdArg.includes("--no-open") === false
+            && cmdArg.includes("--plan-file"),
+        );
+
+        spawned = undefined; // prove the metacharacter failure never spawns
+        const badPath = spawnVisibleRestartGuard({
+          plan: { ...launchPlan, nodePath: "C:/x&y/node.exe" },
+          planPath: written.planPath,
+          _spawn: spawnCapture,
+        });
+        check("cmd 元字符路径 → 构造失败回退（不 spawn）", badPath.ok === false && spawned === undefined);
+
+        // In-flight guard: a second concurrent request fails fast without
+        // touching spawn — two guards would both await this Host and both
+        // start successors. Checked before plan resolution, so this holds in
+        // a bare checkout (CI) where the plan itself cannot resolve dsh.
+        const realDshHome = process.env.DSH_HOME;
+        const realConsoleError = console.error;
+        restartHandoffInFlight = true;
+        let inFlightResponse;
+        try {
+          process.env.DSH_HOME = visibleRoot;
+          console.error = () => {};
+          inFlightResponse = await rpcDispatch({}, "restart", { profile: "web", session: `sess_${"a".repeat(32)}` }, { defaultProfile: "web", allowRestart: true }, undefined, {});
+        } finally {
+          restartHandoffInFlight = false;
+          console.error = realConsoleError;
+          if (realDshHome === undefined) delete process.env.DSH_HOME;
+          else process.env.DSH_HOME = realDshHome;
+        }
+        check(
+          "已有交接在途 → 第二次请求立即拒绝",
+          inFlightResponse?.ok === false && /already in progress/.test(inFlightResponse.error?.message ?? ""),
+        );
+
+        // ctx.effect runs the callback IMMEDIATELY and registers its return
+        // value as the disposer — a block body that disposes inline (the
+        // third-round review catch) killed every handoff at registration and
+        // broke restarts entirely. Pin the real registration semantics with
+        // a cordis-faithful fake: registering must not dispose, and the
+        // registered disposer must dispose AND release the latch.
+        {
+          const fakeHandoff = { disposeCalls: 0, dispose() { this.disposeCalls += 1; } };
+          const registered = [];
+          const fakeCtx = {
+            effect(callback) {
+              const disposer = callback();
+              registered.push(disposer);
+              return () => disposer();
+            },
+          };
+          restartHandoffInFlight = true;
+          const unregister = registerRestartHandoffEffect(fakeCtx, fakeHandoff);
+          const registrationClean = fakeHandoff.disposeCalls === 0
+            && typeof registered[0] === "function";
+          registered[0]();
+          const disposalWorks = fakeHandoff.disposeCalls === 1 && restartHandoffInFlight === false;
+          restartHandoffInFlight = false;
+          unregister();
+          check(
+            "ctx.effect 注册语义：注册不 dispose、disposer 才 dispose 并解锁",
+            registrationClean && disposalWorks,
+          );
+        }
+      } finally {
+        rmSync(visibleRoot, { recursive: true, force: true });
+      }
+    }
+
+    // On Windows pin the /d /s /c verbatim quoting against the real cmd.exe
+    // (echo, no window): the same shell route the visible restart takes.
+    if (process.platform === "win32") {
+      const echoed = await new Promise((resolvePromise) => {
+        let text = "";
+        const child = spawn(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", '"echo "dsh verbatim check""'], {
+          shell: false,
+          stdio: ["ignore", "pipe", "pipe"],
+          windowsVerbatimArguments: true,
+          windowsHide: true,
+        });
+        child.stdout.on("data", (chunk) => { text += chunk; });
+        child.on("close", () => resolvePromise(text));
+        child.on("error", () => resolvePromise(""));
+      });
+      check("cmd /d /s /c verbatim 引用链路（真 echo：外层引号剥、内层保留）", echoed.trim() === "\"dsh verbatim check\"");
+    }
+
     // ── 7. Tracker isolation: producer.done rejection handling ───────────────
     let settledOutcome = null;
     const rejectingProducer = {