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

package/src/index.js

@@ -15,10 +15,12 @@
 
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { existsSync, readFileSync, realpathSync, mkdirSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, mkdirSync, mkdtempSync, 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";
+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);
@@ -888,7 +889,16 @@ export function resolveRestartLaunchPlan({ profile, config = {}, isWindows }) {
 
   const nodePath = process.execPath;
   const originalDshArgs = process.argv.slice(2);
-  const args = [cliPath, "guard", "launch", "--profile", name, "--", nodePath, dshEntry, ...originalDshArgs];
+  // 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];
+  // 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];
 
   return {
     ok: true,
@@ -897,9 +907,40 @@ export function resolveRestartLaunchPlan({ profile, config = {}, isWindows }) {
     cliPath,
     dshEntry,
     profile: name,
+    suppressedBrowserOpen: suppressOpen,
+    awaitExitPid: process.pid,
   };
 }
 
+/**
+ * Where a restart's output goes. The successor is spawned from a process that
+ * is about to exit, so it cannot inherit anything that outlives the handoff —
+ * and on Windows the console it does get is not attached to its stdio, which
+ * is how `[guard] … rolled back` used to vanish. Append to a per-profile file
+ * instead, so whatever the restart says survives it.
+ */
+export function restartLogPath(profileDir, profile) {
+  // <home>/profiles/<name> → <home>/guard/, beside the pending markers.
+  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;
@@ -1690,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);
       }
@@ -1704,18 +1745,74 @@ 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));
       }
-      const child = spawn(plan.nodePath, plan.args, {
-        shell: false,
-        detached: true,
-        stdio: "ignore",
-        cwd: process.cwd(),
-        windowsHide: true,
+      // Everything the restart prints goes to a file. `stdio: "ignore"` used to
+      // send it to the void — including the one line that explains a rollback —
+      // and the successor inherited those dead handles, which is why the
+      // console Windows allocates for it comes up blank.
+      let logFd;
+      let logPath;
+      try {
+        logPath = restartLogPath(resolveProfileDir(profile), profile);
+        mkdirSync(dirname(logPath), { recursive: true });
+        logFd = openSync(logPath, "a");
+        writeSync(logFd, `\n=== ${new Date().toISOString()} restart requested (pid ${process.pid} → guard launch) ===\n`);
+      } catch (error) {
+        // A log we cannot open is not a reason to refuse the restart.
+        console.error(`[dsh-plugin-mall] restart log unavailable (${error.message}); continuing without it`);
+        logFd = undefined;
+      }
+      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();
-      setTimeout(() => process.exit(0), 1000);
-      return rpcOk({ restarting: true });
+      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 {
@@ -2556,6 +2653,195 @@ export async function runSelfTests() {
     const restartDotPlan = resolveRestartLaunchPlan({ profile: "web.", config: { allowRestart: true }, isWindows: true });
     check("尾随点 profile 重启 plan fail-closed", !restartDotPlan.ok && /dot or space/.test(restartDotPlan.error));
 
+    // 重启 argv 的三条硬约束。真实重启只有完整重启 dsh 才验得到，所以 plan 的
+    // 形状必须在这里钉死：少一条就是那三个现象里的一个回来了。
+    {
+      const argvBefore = process.argv;
+      try {
+        process.argv = [process.execPath, "/x/bin.js", "--profile", "web"];
+        const plan = resolveRestartLaunchPlan({ profile: "web", config: { allowRestart: true } });
+        if (plan.ok) {
+          const dashDash = plan.args.indexOf("--");
+          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");
+
+          // 用户自己已经写了 --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);
+        } else {
+          // 裸检出里解析不到官方 dsh 入口，plan 只能 fail——说清楚，别假装验过。
+          console.log(`  SKIP 重启 argv fixture（${plan.error}）`);
+        }
+      } finally {
+        process.argv = argvBefore;
+      }
+    }
+
+    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/installer.js

@@ -3272,11 +3272,20 @@ async function runTransactionFixtures() {
     const { profileDir, cleanup } = makeTempProfile("remove-success-cleanup", { "pkg-f": "1.0.0" });
     try {
       materializeFakePackage(profileDir, "pkg-f", "1.0.0");
+      // 快照落在 <home>/guard/snapshots/（guard.js 的 snapshotRoot），不在
+      // profile 目录里。第一版查的是 profileDir/.dsh-plugin-guard —— 那个路径
+      // 根本不存在，于是「残留为空」恒成立，这半条断言等于没写。
+      const snapshotDir = join(dirname(dirname(profileDir)), "guard", "snapshots");
+      const listSnapshots = () => (existsSync(snapshotDir) ? readdirSync(snapshotDir) : []);
+      // 只查「结束后为空」还不够：快照压根没被创建也会通过。在 pnpm 在途的
+      // 那一刻取一次，先钉住它确实存在过，再钉住它被提交清理掉。
+      let snapshotsWhileRunning = [];
       const { spawnFn } = scriptedSpawn([{
         code: 0,
         out: "Done\n",
         // pnpm 真正卸掉：清单与目录都拿走，落盘校验才会通过。
         beforeExit: () => {
+          snapshotsWhileRunning = listSnapshots();
           const manifest = JSON.parse(readFileSync(join(profileDir, "package.json"), "utf8"));
           delete manifest.dependencies["pkg-f"];
           writeFileSync(join(profileDir, "package.json"), JSON.stringify(manifest, undefined, 2) + "\n");
@@ -3284,15 +3293,14 @@ async function runTransactionFixtures() {
         },
       }]);
       const outcome = await runRemove({ profile: "p", packageName: "pkg-f", _profileDir: profileDir, _spawn: spawnFn }).done;
-      const snapshotsLeft = existsSync(join(profileDir, ".dsh-plugin-guard"))
-        ? readdirSync(join(profileDir, ".dsh-plugin-guard")).filter((entry) => entry !== "pending.json")
-        : [];
+      const snapshotsLeft = listSnapshots();
       check(
-        "卸载成功 → marker 与 snapshot 都被提交清理，不留残留",
+        "卸载成功 → marker 与 snapshot 都被提交清理（且快照确实创建过）",
         outcome.status === "completed"
+          && snapshotsWhileRunning.length === 1
           && !existsSync(pendingMarkerPath(profileDir))
           && snapshotsLeft.length === 0,
-        `status=${outcome.status} marker=${existsSync(pendingMarkerPath(profileDir))} snapshots=${snapshotsLeft.join(",")} detail=${JSON.stringify(outcome.detail)}`,
+        `status=${outcome.status} 运行中快照=${snapshotsWhileRunning.join(",")} marker=${existsSync(pendingMarkerPath(profileDir))} 残留快照=${snapshotsLeft.join(",")} detail=${JSON.stringify(outcome.detail)}`,
       );
     } finally {
       cleanup();

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,
+  };
+}