create-opentray 0.27.1 → 0.27.3

package/dist/{bin-2M6ud0DS.mjs → bin-DgadYsE1.mjs}

@@ -11,8 +11,8 @@ import { execFile, spawn, spawnSync } from "node:child_process";
 import net from "node:net";
 import { fileURLToPath } from "node:url";
 import { getSvgPath } from "figma-squircle";
-import { resolveDefaultDarwinAppBundlePath, sanitizeAppBundleName } from "@opentray/packaging";
 import { promisify } from "node:util";
+import { resolveDefaultDarwinAppBundlePath, sanitizeAppBundleName } from "@opentray/packaging";
 import { createServer } from "node:http";
 //#region packages/core/src/app-id.ts
 /** A token that looks like a command option, e.g. `--xx`, `-p`, or `--port=8080`. */
@@ -7517,7 +7517,7 @@ const killProcessTree$1 = async (child) => {
 				child.kill("SIGTERM");
 			}
 			await sweepDescendants(pid, "SIGTERM");
-			await waitForExit(child, 3e3).then((exited) => {
+			await waitForExit$1(child, 3e3).then((exited) => {
 				if (!exited) {
 					try {
 						process.kill(-pid, "SIGKILL");
@@ -7555,7 +7555,7 @@ const sweepDescendants = async (pid, signal) => {
 		}
 	}
 };
-const waitForExit = (child, timeoutMs) => new Promise((resolve) => {
+const waitForExit$1 = (child, timeoutMs) => new Promise((resolve) => {
 	if (child.exitCode !== null || child.signalCode !== null) {
 		resolve(true);
 		return;
@@ -7581,6 +7581,8 @@ const runExecFileCapture = (command, args) => new Promise((resolve, reject) => {
 });
 //#endregion
 //#region packages/core/src/toolbar-carrier.ts
+/** Debounce window that collapses a reload's close burst into one rebuild. */
+const TOOLBAR_CHANNEL_REBUILD_DEBOUNCE_MS = 300;
 /**
 * The generated-entry helper source. The embedding template supplies
 * `column`/`fixed`/`grow` (imported from "@opentray/ext-webview" beside
@@ -7592,6 +7594,8 @@ const toolbarCarrierSource = () => `// Toolbar navigation carrier (add-webview-o
 // it through the create-private message channel. Channel failure is an
 // exposed bug (D12: no fallback path) — errors land in app.log through
 // options.log instead of being silently swallowed.
+const TOOLBAR_CHANNEL_REBUILD_DEBOUNCE_MS = ${TOOLBAR_CHANNEL_REBUILD_DEBOUNCE_MS};
+
 const attachToolbarCarrier = async (shell, options) => {
   // Per-child bridge policy (D2): the toolbar page is trusted shell UI and
   // gets exactly the channel surface; the content webview gets NO policy, so
@@ -7605,11 +7609,21 @@ const attachToolbarCarrier = async (shell, options) => {
   // Declarative layered layout (D8 sugar): toolbar pinned at a fixed 44px
   // height, content filling the remainder; resize is recomputed natively.
   await shell.setLayout(column([fixed("toolbar", 44), grow("content")]));
-  const channel = await shell.createMessageChannel({ target: "toolbar" });
   const note = (error) => {
     const message = error instanceof Error ? error.message : String(error);
     void options.log("toolbar carrier: " + message);
   };
+
+  // Channel self-heal state (P1-3): the toolbar page's document owns its
+  // endpoint half, so a document death (manual ⌘R reload) closes the channel
+  // (D11 document_navigated semantics). The host half heals itself: debounced
+  // recreate → reinstall command surface → re-seed the address bar. Posts
+  // always flow through the CURRENT channel, so a dead document's last
+  // in-flight pushes fail into app.log instead of a zombie endpoint.
+  let channel = null;
+  let stopped = false;
+  let rebuildTimer = null;
+
   // Address-bar truth (D13): the content webview's urlChange events ARE the
   // address bar's source of truth — pushed over the channel, never scraped
   // from a wrapper document.
@@ -7653,37 +7667,86 @@ const attachToolbarCarrier = async (shell, options) => {
       projectTitle(event.title);
     });
   }
+
   // Command surface (D12): instructions and state queries arrive as channel
   // payloads; back/forward drive the content webview's NATIVE history and
   // reload re-navigates to the current URL through the native navigate
-  // command (never evaluate(location.reload()) on a wrapper).
-  channel.onMessage((payload) => {
-    const message = typeof payload === "object" && payload !== null ? payload : {};
-    const kind = message.kind;
-    if (kind === "navigate" && typeof message.url === "string" && message.url.length > 0) {
-      void content.navigate(message.url).catch(note);
-      return;
-    }
-    if (kind === "back") {
-      void content.back().catch(note);
-      return;
-    }
-    if (kind === "forward") {
-      void content.forward().catch(note);
-      return;
-    }
-    if (kind === "reload") {
-      void content.getUrl().then((state) => content.navigate(state.url)).catch(note);
+  // command (never evaluate(location.reload()) on a wrapper). Installed as
+  // one function so every rebuilt channel gets the identical surface.
+  const installChannelCommandSurface = () => {
+    channel.onMessage((payload) => {
+      const message = typeof payload === "object" && payload !== null ? payload : {};
+      const kind = message.kind;
+      if (kind === "navigate" && typeof message.url === "string" && message.url.length > 0) {
+        void content.navigate(message.url).catch(note);
+        return;
+      }
+      if (kind === "back") {
+        void content.back().catch(note);
+        return;
+      }
+      if (kind === "forward") {
+        void content.forward().catch(note);
+        return;
+      }
+      if (kind === "reload") {
+        void content.getUrl().then((state) => content.navigate(state.url)).catch(note);
+        return;
+      }
+      if (kind === "get-url") {
+        void content.getUrl().then((state) => pushUrl(state.url)).catch(note);
+      }
+    });
+  };
+  // Seed the address bar with the current truth (pre-subscription buffering
+  // on both endpoints covers the race before the toolbar page registers).
+  const seedAddressBar = () => {
+    void content.getUrl().then((state) => pushUrl(state.url)).catch(note);
+  };
+
+  // One channel lifecycle: create, install the surface, observe the single
+  // onClose (D11), and drop the replaced channel's tombstone (destroy is
+  // best-effort cleanup of already-closed state).
+  const openChannel = async () => {
+    const next = await shell.createMessageChannel({ target: "toolbar" });
+    if (stopped) {
+      try { await next.destroy(); } catch { /* raced teardown */ }
       return;
     }
-    if (kind === "get-url") {
-      void content.getUrl().then((state) => pushUrl(state.url)).catch(note);
+    const replaced = channel;
+    channel = next;
+    installChannelCommandSurface();
+    channel.onClose(() => scheduleChannelRebuild());
+    if (replaced !== null) {
+      try { await replaced.destroy(); } catch { /* already closed */ }
     }
-  });
-  // Seed the address bar with the current truth (pre-subscription buffering
-  // on both endpoints covers the race before the toolbar page registers).
-  void content.getUrl().then((state) => pushUrl(state.url)).catch(note);
-  return { content, channel };
+    seedAddressBar();
+  };
+  // Debounced self-heal (P1-3): a reload can emit several closes (both
+  // endpoints observe one each, plus repeated reloads); exactly one rebuild
+  // serves the burst. After stop() the carrier never rebuilds — a teardown
+  // close (window destroyed / session closed) must not resurrect a channel
+  // against a dying session.
+  const scheduleChannelRebuild = () => {
+    if (stopped || rebuildTimer !== null) return;
+    rebuildTimer = setTimeout(() => {
+      rebuildTimer = null;
+      if (stopped) return;
+      void openChannel().catch(note);
+    }, TOOLBAR_CHANNEL_REBUILD_DEBOUNCE_MS);
+  };
+
+  await openChannel();
+  return {
+    content,
+    stop: () => {
+      stopped = true;
+      if (rebuildTimer !== null) {
+        clearTimeout(rebuildTimer);
+        rebuildTimer = null;
+      }
+    },
+  };
 };
 `;
 //#endregion
@@ -7879,29 +7942,48 @@ const main = async () => {
       ? { "darwin-icon-only": { type: "file", path: resolve(PROJECT_DIR, trayIcon.path), isTemplate: true } }
       : { "icon-only": { type: "file", path: resolve(PROJECT_DIR, trayIcon.path) } };
 
-  const tray = await createTray({
-    id: config.appId,
-    tooltip: { title: config.appName, description: \`\${config.appName} (OpenTray)\` },
-    icon: Object.keys(trayIconCandidates).length > 0
-      ? trayIconCandidates
-      : { "text-only": "${config.appName.replace(/['"\\]/gu, "").slice(0, 2) || "A"}" },
-    menu: { items: [
-      { type: "item", id: 1, title: \`Show \${config.appName}\`, primaryEvent: true },
-      { type: "separator" },
-      { type: "item", id: 2, title: "Quit" },
-    ] },
-  }, {
-    appId: config.appId,
-    appName: config.appName,
-    ...(appIcon === undefined ? {} : { appIcon }),
-    appLaunch: {
-      // The generated entry embeds a native PTY (@lydell/node-pty), which
-      // requires a Node host — cold launches must not inherit a Bun execPath.
-      command: nodeRuntime(),
-      args: [resolve(PROJECT_DIR, "main.mjs")],
-      cwd: PROJECT_DIR,
-    },
-  });
+  const tray = await (async () => {
+    try {
+      return await createTray({
+        id: config.appId,
+        tooltip: { title: config.appName, description: \`\${config.appName} (OpenTray)\` },
+        icon: Object.keys(trayIconCandidates).length > 0
+          ? trayIconCandidates
+          : { "text-only": "${config.appName.replace(/['"\\]/gu, "").slice(0, 2) || "A"}" },
+        menu: { items: [
+          { type: "item", id: 1, title: \`Show \${config.appName}\`, primaryEvent: true },
+          { type: "separator" },
+          { type: "item", id: 2, title: "Quit" },
+        ] },
+      }, {
+        appId: config.appId,
+        appName: config.appName,
+        ...(appIcon === undefined ? {} : { appIcon }),
+        appLaunch: {
+          // The generated entry embeds a native PTY (@lydell/node-pty), which
+          // requires a Node host — cold launches must not inherit a Bun execPath.
+          command: nodeRuntime(),
+          args: [resolve(PROJECT_DIR, "main.mjs")],
+          cwd: PROJECT_DIR,
+        },
+      });
+    } catch (error) {
+      // Carrier-resurrection yield: a Dock-pinned carrier can cold-start this
+      // entry while another instance already owns the broker session. The
+      // owner keeps the app open; this launcher exits cleanly (no retry, no
+      // empty tray shell, no orphaned command supervision) and the evidence
+      // lands in app.log. The supervised command started BEFORE createTray,
+      // so the yield takes it down (direct kill; the closing PTY master adds
+      // SIGHUP) — the shell server dies with this process.
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.includes("OPENTRAY_BROKER_SINGLE_SESSION")) {
+        await logSink("[create-opentray] broker session already owned by another instance of this app; this cold-started launcher exits (yield)\\n", "utf8");
+        try { command.killDirect(); } catch { /* already dead */ }
+        process.exit(0);
+      }
+      throw error;
+    }
+  })();
 
   const baseTitle = config.appName;
   // v1 developerMode maps ONLY to per-window DevTools admission. When false it
@@ -7962,12 +8044,15 @@ const main = async () => {
         ...devtools,
       });
       await win.show().catch(() => {});
-      await attachToolbarCarrier(win, {
+      const carrier = await attachToolbarCarrier(win, {
         toolbarUrl: \`http://127.0.0.1:\${shellPort}/toolbar.html\`,
         contentUrl: direct,
         titleFollows,
         log: logNote,
       });
+      // P1-3 exit race: teardown closes the channel; the carrier must never
+      // rebuild against a dying session. Stop before the window goes down.
+      process.once("exit", carrier.stop);
       serviceWindows.set(port, { win, detached: false });
       return;
     }
@@ -8203,28 +8288,43 @@ ${toolbarCarrierSource()}const main = async () => {
       ? { "darwin-icon-only": { type: "file", path: resolve(PROJECT_DIR, trayIcon.path), isTemplate: true } }
       : { "icon-only": { type: "file", path: resolve(PROJECT_DIR, trayIcon.path) } };
 
-  const tray = await createTray({
-    id: config.appId,
-    tooltip: { title: config.appName, description: \`\${config.appName} (OpenTray)\` },
-    icon: Object.keys(trayIconCandidates).length > 0
-      ? trayIconCandidates
-      : { "text-only": "${config.appName.replace(/['"\\]/gu, "").slice(0, 2) || "A"}" },
-    menu: { items: [
-      { type: "item", id: 1, title: \`Show \${config.appName}\`, primaryEvent: true },
-      { type: "item", id: 3, title: "Reload" },
-      { type: "separator" },
-      { type: "item", id: 2, title: "Quit" },
-    ] },
-  }, {
-    appId: config.appId,
-    appName: config.appName,
-    ...(appIcon === undefined ? {} : { appIcon }),
-    appLaunch: {
-      command: nodeRuntime(),
-      args: [resolve(PROJECT_DIR, "main.mjs")],
-      cwd: PROJECT_DIR,
-    },
-  });
+  const tray = await (async () => {
+    try {
+      return await createTray({
+        id: config.appId,
+        tooltip: { title: config.appName, description: \`\${config.appName} (OpenTray)\` },
+        icon: Object.keys(trayIconCandidates).length > 0
+          ? trayIconCandidates
+          : { "text-only": "${config.appName.replace(/['"\\]/gu, "").slice(0, 2) || "A"}" },
+        menu: { items: [
+          { type: "item", id: 1, title: \`Show \${config.appName}\`, primaryEvent: true },
+          { type: "item", id: 3, title: "Reload" },
+          { type: "separator" },
+          { type: "item", id: 2, title: "Quit" },
+        ] },
+      }, {
+        appId: config.appId,
+        appName: config.appName,
+        ...(appIcon === undefined ? {} : { appIcon }),
+        appLaunch: {
+          command: nodeRuntime(),
+          args: [resolve(PROJECT_DIR, "main.mjs")],
+          cwd: PROJECT_DIR,
+        },
+      });
+    } catch (error) {
+      // Carrier-resurrection yield: a Dock-pinned carrier can cold-start this
+      // entry while another instance already owns the broker session. The
+      // owner keeps the app open; this launcher exits cleanly (no retry, no
+      // empty tray shell) and the evidence lands in app.log.
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.includes("OPENTRAY_BROKER_SINGLE_SESSION")) {
+        await logSink("[create-opentray] broker session already owned by another instance of this app; this cold-started launcher exits (yield)\\n", "utf8");
+        process.exit(0);
+      }
+      throw error;
+    }
+  })();
 
   // v1 developerMode maps ONLY to per-window DevTools admission. When false it
   // must not request devtools at all — default windows are not inspectable.
@@ -8265,12 +8365,16 @@ ${toolbarCarrierSource()}const main = async () => {
 
   let content = null;
   if (toolbarReady) {
-    ({ content } = await attachToolbarCarrier(window, {
+    const carrier = await attachToolbarCarrier(window, {
       toolbarUrl: \`http://127.0.0.1:\${shellPort}/toolbar.html\`,
       contentUrl: config.url,
       titleFollows,
       log: logNote,
-    }));
+    });
+    ({ content } = carrier);
+    // P1-3 exit race: teardown closes the channel; the carrier must never
+    // rebuild against a dying session. Stop before the window goes down.
+    process.once("exit", carrier.stop);
   }
 
   // Tray reload (D11): toolbar mode reloads the CONTENT webview natively
@@ -8831,6 +8935,182 @@ const runPackageManagerInstall = async (options) => {
 	});
 };
 //#endregion
+//#region packages/core/src/errors.ts
+const ok = (value) => ({
+	ok: true,
+	value
+});
+const err = (code, message, details) => ({
+	ok: false,
+	error: {
+		code,
+		message,
+		...details === void 0 ? {} : { details }
+	}
+});
+//#endregion
+//#region packages/core/src/runtime-record.ts
+const execFileAsync$1 = promisify(execFile);
+const RUNTIME_FILENAME = "runtime.json";
+const readRuntimeRecord = async (registrationDir) => {
+	try {
+		const raw = JSON.parse(await readFile(join(registrationDir, RUNTIME_FILENAME), "utf8"));
+		if (typeof raw === "object" && raw !== null && typeof raw.pid === "number" && typeof raw.token === "string") {
+			const record = raw;
+			return {
+				pid: record.pid,
+				token: record.token,
+				startedAt: typeof record.startedAt === "number" ? record.startedAt : null,
+				launchedAt: typeof record.launchedAt === "number" ? record.launchedAt : Date.now()
+			};
+		}
+		return;
+	} catch {
+		return;
+	}
+};
+const clearRuntimeRecord = async (registrationDir) => {
+	await rm(join(registrationDir, RUNTIME_FILENAME), { force: true });
+};
+const isPidAlive$1 = (pid) => {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+};
+/** Linux: /proc/<pid>/stat field 22 (starttime in clock ticks since boot). */
+const linuxStartTicks = async (pid) => {
+	try {
+		const stat = await readFile(`/proc/${pid}/stat`, "utf8");
+		const close = stat.lastIndexOf(")");
+		if (close < 0) return void 0;
+		const fields = stat.slice(close + 2).split(" ");
+		const ticks = Number.parseInt(fields[19] ?? "", 10);
+		return Number.isInteger(ticks) ? ticks : void 0;
+	} catch {
+		return;
+	}
+};
+const bootEpochMs = async () => {
+	try {
+		const stat = await readFile("/proc/stat", "utf8");
+		const btime = /btime (\d+)/u.exec(stat);
+		return btime === null ? void 0 : Number.parseInt(btime[1], 10) * 1e3;
+	} catch {
+		return;
+	}
+};
+/** macOS: `ps -o lstart= -p <pid>` prints the absolute start timestamp. */
+const macosStartEpochMs = async (pid) => {
+	try {
+		const { stdout } = await execFileAsync$1("ps", [
+			"-o",
+			"lstart=",
+			"-p",
+			String(pid)
+		], {
+			timeout: 5e3,
+			env: {
+				...process.env,
+				LC_ALL: "C",
+				LANG: "C"
+			}
+		});
+		const parsed = Date.parse(stdout.trim());
+		return Number.isNaN(parsed) ? void 0 : parsed;
+	} catch {
+		return;
+	}
+};
+/** Windows: PowerShell Get-Process StartTime for the pid. */
+const windowsStartEpochMs = async (pid) => {
+	try {
+		const { stdout } = await execFileAsync$1("powershell.exe", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			`(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CreationDate`
+		], {
+			timeout: 1e4,
+			windowsHide: true
+		});
+		const trimmed = stdout.trim();
+		const dmtf = /^(\d{14})(?:\.(\d+))?(?:([+-]\d+))?$/u.exec(trimmed);
+		if (dmtf !== null) {
+			const stamp = dmtf[1] ?? "";
+			const fraction = dmtf[2];
+			const offset = dmtf[3];
+			const iso = `${stamp.slice(0, 4)}-${stamp.slice(4, 6)}-${stamp.slice(6, 8)}T${stamp.slice(8, 10)}:${stamp.slice(10, 12)}:${stamp.slice(12, 14)}${fraction === void 0 ? "" : `.${fraction.slice(0, 3)}`}${offset ?? "Z"}`;
+			const parsed = Date.parse(iso);
+			if (!Number.isNaN(parsed)) return parsed;
+		}
+		const parsed = Date.parse(trimmed);
+		return Number.isNaN(parsed) ? void 0 : parsed;
+	} catch {
+		return;
+	}
+};
+/**
+* Read a process's start fingerprint (epoch ms) on the current platform;
+* undefined when the platform cannot report it.
+*/
+const readProcessStartEpochMs = async (pid, platform = process.platform) => {
+	if (platform === "linux") {
+		const [ticks, boot] = await Promise.all([linuxStartTicks(pid), bootEpochMs()]);
+		if (ticks !== void 0 && boot !== void 0) return boot + Math.floor(ticks / 100 * 1e3);
+		return;
+	}
+	if (platform === "darwin") return macosStartEpochMs(pid);
+	if (platform === "win32") return windowsStartEpochMs(pid);
+};
+/**
+* Inspect a recorded PID against its recorded start fingerprint.
+*
+* - `dead`: the process does not exist (stale record).
+* - `reused`: a different process now owns the PID (start mismatch).
+* - `live`: alive and (when the platform reports start times) the same launch.
+* - `unverified`: alive but identity cannot be verified on this platform.
+*/
+const inspectProcess = async (pid, expectedStartedAt, platform = process.platform) => {
+	if (!isPidAlive$1(pid)) return "dead";
+	if (expectedStartedAt === null) return "unverified";
+	const toleranceMs = 2e3;
+	const observed = await readProcessStartEpochMs(pid, platform);
+	if (observed === void 0) return "unverified";
+	return Math.abs(observed - expectedStartedAt) <= toleranceMs ? "live" : "reused";
+};
+/** Terminate a verified process tree (never called for unverified PIDs). */
+const killProcessTree = async (pid, platform = process.platform) => {
+	try {
+		if (platform === "win32") await execFileAsync$1("taskkill", [
+			"/PID",
+			String(pid),
+			"/T",
+			"/F"
+		], {
+			timeout: 15e3,
+			windowsHide: true
+		});
+		else {
+			const { stdout } = await execFileAsync$1("pgrep", ["-P", String(pid)], { timeout: 5e3 }).catch(() => ({ stdout: "" }));
+			const children = stdout.split("\n").map((line) => Number.parseInt(line.trim(), 10)).filter((value) => Number.isInteger(value) && value > 0);
+			process.kill(pid, "SIGTERM");
+			for (const child of children) try {
+				process.kill(child, "SIGTERM");
+			} catch {}
+			await new Promise((resolve) => setTimeout(resolve, 300));
+			for (const target of [pid, ...children]) if (isPidAlive$1(target)) try {
+				process.kill(target, "SIGKILL");
+			} catch {}
+		}
+		return ok({ pid });
+	} catch (error) {
+		return err("process_unverified", `failed to terminate process tree for pid ${pid}: ${error instanceof Error ? error.message : String(error)}`, { pid });
+	}
+};
+//#endregion
 //#region packages/core/src/user-messages.ts
 const UI_LOCALES = [
 	"zh-CN",
@@ -8957,6 +9237,7 @@ const userMessages = (locale) => CATALOGS[locale];
 const ptyUnavailableMessage = (code, locale) => code === "pty_bun_terminal_missing" ? CATALOGS[locale].ptyBunTerminalMissing : CATALOGS[locale].ptyNodePtyMissing;
 //#endregion
 //#region packages/core/src/open-app.ts
+const execFileAsync = promisify(execFile);
 /** The generated entry embeds a native PTY: it needs Node, never a Bun host. */
 const nodeExecutable = () => {
 	if (process.versions.bun === void 0 && process.execPath.includes("node")) return process.execPath;
@@ -8997,14 +9278,100 @@ const spawnEntryCold = (projectDir) => {
 		detail: `launched app entry (pid ${child.pid})`
 	};
 };
+const isPidAlive = (pid) => {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+};
+/**
+* Live entry pids for one payload by argv identity: the entry is always
+* `node <projectDir>/main.mjs` (the carrier's opentray-launch.json vector and
+* the cold-start spawn both use the absolute script path), so matching the
+* script path is exact identity — never a name-based guess. POSIX uses
+* `pgrep -f`; Windows a bounded CIM CommandLine query (best effort — a probe
+* failure reports no live instances instead of guessing).
+*/
+const defaultFindEntryPids = async (projectDir, platform) => {
+	const scriptPath = join(projectDir, "main.mjs");
+	const own = process.pid;
+	if (platform === "win32") try {
+		const { stdout } = await execFileAsync("powershell.exe", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			`Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -like '*${scriptPath.replaceAll("'", "''")}*' } | Select-Object -ExpandProperty ProcessId`
+		], {
+			timeout: 1e4,
+			windowsHide: true
+		});
+		return stdout.split(/\r?\n/u).map((line) => Number.parseInt(line.trim(), 10)).filter((pid) => Number.isInteger(pid) && pid > 0 && pid !== own);
+	} catch {
+		return [];
+	}
+	try {
+		const { stdout } = await execFileAsync("pgrep", ["-f", scriptPath], { timeout: 5e3 });
+		return stdout.split("\n").map((line) => Number.parseInt(line.trim(), 10)).filter((pid) => Number.isInteger(pid) && pid > 0 && pid !== own);
+	} catch {
+		return [];
+	}
+};
+/** Bounded wait for every stopped pid to actually exit (100ms cadence). */
+const waitForExit = async (pids, budgetMs) => {
+	const deadline = Date.now() + budgetMs;
+	for (;;) {
+		if (!pids.some(isPidAlive)) return true;
+		if (Date.now() >= deadline) return false;
+		await new Promise((resolve) => {
+			setTimeout(resolve, 100);
+		});
+	}
+};
+/**
+* Replace-semantics stop for one payload's live entry instances (Dev Launch
+* Law): probe by argv identity, terminate each tree, and wait bounded for the
+* pids (and behind them the broker session) to release before a new start may
+* claim the endpoint. A probe that finds nothing is a no-op.
+*/
+const stopLiveAppInstances = async (projectDir, options = {}) => {
+	const platform = options.platform ?? process.platform;
+	const findPids = options.probe?.findPids ?? defaultFindEntryPids;
+	const killTree = options.probe?.killTree ?? ((pid) => killProcessTree(pid, platform));
+	const pids = [...new Set(await findPids(projectDir, platform))].filter(isPidAlive);
+	if (pids.length === 0) return {
+		stoppedPids: [],
+		hung: false
+	};
+	for (const pid of pids) await killTree(pid);
+	if (!await waitForExit(pids, options.waitBudgetMs ?? 5e3)) return {
+		stoppedPids: pids,
+		hung: true
+	};
+	await new Promise((resolve) => {
+		setTimeout(resolve, 300);
+	});
+	return {
+		stoppedPids: pids,
+		hung: false
+	};
+};
 const openMaterializedApp = async (input) => {
-	if ((input.platform ?? process.platform) === "darwin") {
+	const platform = input.platform ?? process.platform;
+	const replaced = await stopLiveAppInstances(input.projectDir, {
+		platform,
+		probe: input.probe,
+		waitBudgetMs: input.stopWaitBudgetMs
+	});
+	const replacedNote = replaced.stoppedPids.length === 0 ? "" : `replaced live instance (pid ${replaced.stoppedPids.join(", ")})${replaced.hung ? " — WARNING: pid still alive after stop" : ""}; `;
+	if (platform === "darwin") {
 		const bundlePath = input.bundlePath ?? await expectedBundleForProject(input.projectDir);
-		if (bundlePath === void 0) return spawnEntryCold(input.projectDir);
+		if (bundlePath === void 0) return withNote(spawnEntryCold(input.projectDir), replacedNote);
 		try {
 			await stat(bundlePath);
 		} catch {
-			return spawnEntryCold(input.projectDir);
+			return withNote(spawnEntryCold(input.projectDir), replacedNote);
 		}
 		const child = spawn("open", [bundlePath], {
 			stdio: "ignore",
@@ -9016,14 +9383,18 @@ const openMaterializedApp = async (input) => {
 		});
 		if (status === 0) return {
 			ok: true,
-			detail: `opened ${bundlePath}`
+			detail: `${replacedNote}opened ${bundlePath}`
 		};
 		return {
 			ok: false,
-			detail: `open ${bundlePath} failed with ${status ?? "spawn error"}`
+			detail: `${replacedNote}open ${bundlePath} failed with ${status ?? "spawn error"}`
 		};
 	}
-	return spawnEntryCold(input.projectDir);
+	return withNote(spawnEntryCold(input.projectDir), replacedNote);
+};
+const withNote = (result, note) => note === "" ? result : {
+	...result,
+	detail: `${note}${result.detail}`
 };
 /**
 * Platform-truthful pinning hint; makes no persistence claim before first
@@ -9037,20 +9408,6 @@ const pinningHint = (platform = process.platform, locale = "zh-CN") => {
 	return messages.pinHintOther;
 };
 //#endregion
-//#region packages/core/src/errors.ts
-const ok = (value) => ({
-	ok: true,
-	value
-});
-const err = (code, message, details) => ({
-	ok: false,
-	error: {
-		code,
-		message,
-		...details === void 0 ? {} : { details }
-	}
-});
-//#endregion
 //#region ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/core/core.js
 var _a$1;
 function $constructor(name, initializer, params) {
@@ -13602,168 +13959,6 @@ const listRegistrations = async (homeDir) => {
 	return records;
 };
 //#endregion
-//#region packages/core/src/runtime-record.ts
-const execFileAsync = promisify(execFile);
-const RUNTIME_FILENAME = "runtime.json";
-const readRuntimeRecord = async (registrationDir) => {
-	try {
-		const raw = JSON.parse(await readFile(join(registrationDir, RUNTIME_FILENAME), "utf8"));
-		if (typeof raw === "object" && raw !== null && typeof raw.pid === "number" && typeof raw.token === "string") {
-			const record = raw;
-			return {
-				pid: record.pid,
-				token: record.token,
-				startedAt: typeof record.startedAt === "number" ? record.startedAt : null,
-				launchedAt: typeof record.launchedAt === "number" ? record.launchedAt : Date.now()
-			};
-		}
-		return;
-	} catch {
-		return;
-	}
-};
-const clearRuntimeRecord = async (registrationDir) => {
-	await rm(join(registrationDir, RUNTIME_FILENAME), { force: true });
-};
-const isPidAlive = (pid) => {
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch (error) {
-		return error.code === "EPERM";
-	}
-};
-/** Linux: /proc/<pid>/stat field 22 (starttime in clock ticks since boot). */
-const linuxStartTicks = async (pid) => {
-	try {
-		const stat = await readFile(`/proc/${pid}/stat`, "utf8");
-		const close = stat.lastIndexOf(")");
-		if (close < 0) return void 0;
-		const fields = stat.slice(close + 2).split(" ");
-		const ticks = Number.parseInt(fields[19] ?? "", 10);
-		return Number.isInteger(ticks) ? ticks : void 0;
-	} catch {
-		return;
-	}
-};
-const bootEpochMs = async () => {
-	try {
-		const stat = await readFile("/proc/stat", "utf8");
-		const btime = /btime (\d+)/u.exec(stat);
-		return btime === null ? void 0 : Number.parseInt(btime[1], 10) * 1e3;
-	} catch {
-		return;
-	}
-};
-/** macOS: `ps -o lstart= -p <pid>` prints the absolute start timestamp. */
-const macosStartEpochMs = async (pid) => {
-	try {
-		const { stdout } = await execFileAsync("ps", [
-			"-o",
-			"lstart=",
-			"-p",
-			String(pid)
-		], {
-			timeout: 5e3,
-			env: {
-				...process.env,
-				LC_ALL: "C",
-				LANG: "C"
-			}
-		});
-		const parsed = Date.parse(stdout.trim());
-		return Number.isNaN(parsed) ? void 0 : parsed;
-	} catch {
-		return;
-	}
-};
-/** Windows: PowerShell Get-Process StartTime for the pid. */
-const windowsStartEpochMs = async (pid) => {
-	try {
-		const { stdout } = await execFileAsync("powershell.exe", [
-			"-NoProfile",
-			"-NonInteractive",
-			"-Command",
-			`(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CreationDate`
-		], {
-			timeout: 1e4,
-			windowsHide: true
-		});
-		const trimmed = stdout.trim();
-		const dmtf = /^(\d{14})(?:\.(\d+))?(?:([+-]\d+))?$/u.exec(trimmed);
-		if (dmtf !== null) {
-			const stamp = dmtf[1] ?? "";
-			const fraction = dmtf[2];
-			const offset = dmtf[3];
-			const iso = `${stamp.slice(0, 4)}-${stamp.slice(4, 6)}-${stamp.slice(6, 8)}T${stamp.slice(8, 10)}:${stamp.slice(10, 12)}:${stamp.slice(12, 14)}${fraction === void 0 ? "" : `.${fraction.slice(0, 3)}`}${offset ?? "Z"}`;
-			const parsed = Date.parse(iso);
-			if (!Number.isNaN(parsed)) return parsed;
-		}
-		const parsed = Date.parse(trimmed);
-		return Number.isNaN(parsed) ? void 0 : parsed;
-	} catch {
-		return;
-	}
-};
-/**
-* Read a process's start fingerprint (epoch ms) on the current platform;
-* undefined when the platform cannot report it.
-*/
-const readProcessStartEpochMs = async (pid, platform = process.platform) => {
-	if (platform === "linux") {
-		const [ticks, boot] = await Promise.all([linuxStartTicks(pid), bootEpochMs()]);
-		if (ticks !== void 0 && boot !== void 0) return boot + Math.floor(ticks / 100 * 1e3);
-		return;
-	}
-	if (platform === "darwin") return macosStartEpochMs(pid);
-	if (platform === "win32") return windowsStartEpochMs(pid);
-};
-/**
-* Inspect a recorded PID against its recorded start fingerprint.
-*
-* - `dead`: the process does not exist (stale record).
-* - `reused`: a different process now owns the PID (start mismatch).
-* - `live`: alive and (when the platform reports start times) the same launch.
-* - `unverified`: alive but identity cannot be verified on this platform.
-*/
-const inspectProcess = async (pid, expectedStartedAt, platform = process.platform) => {
-	if (!isPidAlive(pid)) return "dead";
-	if (expectedStartedAt === null) return "unverified";
-	const toleranceMs = 2e3;
-	const observed = await readProcessStartEpochMs(pid, platform);
-	if (observed === void 0) return "unverified";
-	return Math.abs(observed - expectedStartedAt) <= toleranceMs ? "live" : "reused";
-};
-/** Terminate a verified process tree (never called for unverified PIDs). */
-const killProcessTree = async (pid, platform = process.platform) => {
-	try {
-		if (platform === "win32") await execFileAsync("taskkill", [
-			"/PID",
-			String(pid),
-			"/T",
-			"/F"
-		], {
-			timeout: 15e3,
-			windowsHide: true
-		});
-		else {
-			const { stdout } = await execFileAsync("pgrep", ["-P", String(pid)], { timeout: 5e3 }).catch(() => ({ stdout: "" }));
-			const children = stdout.split("\n").map((line) => Number.parseInt(line.trim(), 10)).filter((value) => Number.isInteger(value) && value > 0);
-			process.kill(pid, "SIGTERM");
-			for (const child of children) try {
-				process.kill(child, "SIGTERM");
-			} catch {}
-			await new Promise((resolve) => setTimeout(resolve, 300));
-			for (const target of [pid, ...children]) if (isPidAlive(target)) try {
-				process.kill(target, "SIGKILL");
-			} catch {}
-		}
-		return ok({ pid });
-	} catch (error) {
-		return err("process_unverified", `failed to terminate process tree for pid ${pid}: ${error instanceof Error ? error.message : String(error)}`, { pid });
-	}
-};
-//#endregion
 //#region packages/core/src/scan.ts
 const exists$1 = async (path) => {
 	try {
@@ -18421,4 +18616,4 @@ if (isMainModule()) main(process.argv.slice(2)).then((code) => {
 //#endregion
 export { resolveLaunchVector as A, parseLsofPorts as C, verifyHttpService as D, serviceUrl as E, isValidAppId as F, toProjectDirectoryName as I, tokenizeCommandLine as M, deriveDefaultAppId as N, waitForTcpPort as O, deriveDefaultAppName as P, createPortDiscovery as S, parsePowerShellPorts as T, extractTitle as _, createWizardServer as a, resolveFaviconUrl as b, createWizardSession as c, detectPackageManager as d, expectedDarwinBundlePath as f, extractFaviconCandidates as g, writeScaffold as h, parseWizardCli as i, resolveOnPath as j, parseShebangInterpreter as k, openMaterializedApp as l, materialize as m, normalizeDraftForm as n, isAuthorized as o, isDirectoryOccupied$1 as p, openBrowser as r, isLoopbackHost as s, main as t, pinningHint as u, faviconCandidateSize as v, parseNetstatPorts as w, scrapeService as x, rankFaviconCandidates as y };
 
-//# sourceMappingURL=bin-2M6ud0DS.mjs.map
+//# sourceMappingURL=bin-DgadYsE1.mjs.map