@svenroth-ai/shipwright 0.24.1-next.0

package/lib/version-check.mjs

@@ -0,0 +1,76 @@
+/**
+ * version-check.mjs — AC6, the npx-cache "stale copy" self-check.
+ *
+ * A plain `npx <pkg>` can silently reuse a CACHED OLD version and the user
+ * never knows they ran yesterday's build. Two mitigations (both required, the
+ * second lives here): every printed command says `@latest`, AND on start we
+ * ask the registry what `latest` is and warn when we are behind.
+ *
+ * Hard rule: this is a courtesy, never a gate. Offline, a slow registry, a
+ * 500, a garbled body — all degrade to "no banner, keep going". A machine with
+ * no internet must still be able to boot the Command Center against its cache.
+ */
+
+import { compareSemver } from "./util.mjs";
+
+const REGISTRY_URL = "https://registry.npmjs.org/@svenroth-ai/shipwright/latest";
+const DEFAULT_TIMEOUT_MS = 2000;
+
+/**
+ * Fetch the registry's `latest` version. Never throws — resolves to `null` on
+ * any failure (offline, timeout, non-200, non-JSON, missing field).
+ * @param {{ fetchImpl?: typeof fetch, url?: string, timeoutMs?: number }} [deps]
+ * @returns {Promise<string | null>}
+ */
+export async function fetchLatestVersion(deps = {}) {
+  const {
+    fetchImpl = typeof fetch === "function" ? fetch : undefined,
+    url = REGISTRY_URL,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+  } = deps;
+  if (!fetchImpl) return null;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(url, { signal: ctrl.signal });
+    if (!res || !res.ok) return null;
+    const body = await res.json();
+    const v = body && typeof body.version === "string" ? body.version : null;
+    return v && /^\d+\.\d+\.\d+/.test(v) ? v : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Decide whether a stale-copy banner should show.
+ * @param {string} selfVersion  this package's own version
+ * @param {string | null} latest  the registry's `latest` (null = unknown)
+ * @returns {{ stale: boolean, selfVersion: string, latest: string | null }}
+ */
+export function evaluateStaleness(selfVersion, latest) {
+  const stale = latest != null && compareSemver(selfVersion, latest) < 0;
+  return { stale, selfVersion, latest };
+}
+
+/**
+ * Full self-check: fetch latest, compare, return a verdict. Offline-safe.
+ * @param {string} selfVersion
+ * @param {{ fetchImpl?: typeof fetch, url?: string, timeoutMs?: number }} [deps]
+ */
+export async function checkForStaleCopy(selfVersion, deps = {}) {
+  const latest = await fetchLatestVersion(deps);
+  return evaluateStaleness(selfVersion, latest);
+}
+
+/** Human line for a stale verdict, or `null` when up to date / unknown. */
+export function staleBanner(verdict) {
+  if (!verdict.stale) return null;
+  return (
+    `You are running a stale cached copy (${verdict.selfVersion}); ` +
+    `${verdict.latest} is available. Re-run with:\n` +
+    `  npx @svenroth-ai/shipwright@latest`
+  );
+}

package/lib/win32-spawn.mjs

@@ -0,0 +1,253 @@
+/**
+ * win32-spawn.mjs — resolve a command to argv that `child_process` can run with
+ * `shell: false`, including Windows `.cmd`/`.bat` shims.
+ *
+ * WHY THIS EXISTS. On Windows the tools this package probes are shims, not
+ * executables: `claude` is often `claude.cmd`, `npm`/`npx` always are. Node's
+ * CVE-2024-27980 hardening EINVAL-blocks a direct `.cmd` spawn under
+ * `shell: false`, and `CreateProcess` only ever appends `.exe` — so a bare
+ * `claude` simply is not found. The historical workaround was `shell: true`,
+ * which buys shim resolution at the price of handing a command line to cmd.exe.
+ * This module buys the same resolution without the shell: find the real file via
+ * PATHEXT, then invoke `.cmd`/`.bat` through an explicit `cmd.exe /d /s /c`
+ * with DISCRETE argv.
+ *
+ * MIRROR — this is a deliberate copy of `server/src/core/win32-spawn.ts`
+ * (ADR-044, reviewed there; audit findings F03 + F31). It is duplicated rather
+ * than imported because `bootstrapper/` is a separately published npm package
+ * and DO-NOT #7 forbids cross-package imports.
+ *
+ * DIVERGENCES from the server original — the COMPLETE list, so a future drift
+ * reviewer diffing the two files knows what is intentional:
+ *   1. Failure SHAPE for an unresolvable BARE name. The server core returns
+ *      `null` and its thin `preview-win32-spawn.ts` wrapper converts that into
+ *      `PreviewProfileInvalidError`; this file returns a bare-name plan instead
+ *      — see divergence 5, which is the real behaviour and SUPERSEDES what this
+ *      entry used to claim. **Corrected 2026-08-01**: it read "returns `null`
+ *      here", which stopped being true when the App-Execution-Alias fix landed
+ *      (iterate-2026-07-31) and added the bare-name fallback. `resolveSpawn`
+ *      below can no longer return `null` on any path. The callers'
+ *      `if (!plan)` branches are therefore currently UNREACHABLE; they are kept
+ *      deliberately as cheap contract insurance, and are annotated as such at
+ *      their own sites rather than left implying a live code path.
+ *   2. Signature. Here: `resolveSpawn(argv, { platform, env })`, both injectable
+ *      (the bootstrapper has no DI container, and its tests must reach the win32
+ *      branch from Linux). Server: `resolveSpawn(argv, cwd)`, reading the process
+ *      globals directly.
+ *   3. No `cwd` parameter. A path-like name resolves against `process.cwd()`
+ *      here; the server resolves against the caller-supplied previewed-project
+ *      cwd, because it is handling an UNTRUSTED repo and this is not. The
+ *      security-relevant half is identical: a BARE name resolves from PATH only,
+ *      never cwd, in both.
+ *   4. `win32ComSpec` is exported and env-parameterised here (server: private).
+ *   5. An unresolvable BARE name falls back to spawning the bare name itself
+ *      (`{command: name}`) instead of giving up. The server refuses — its Guard 6
+ *      is a FROZEN security guard and stays. Safe here, and NOT a hole, because
+ *      verified on Windows 11: a bare-name spawn under `shell: false` is
+ *      PATH-only — a planted `.\swplantedexe.exe` with `cwd` set to its own
+ *      directory returns ENOENT, so cmd.exe's cwd-first lookup is still not in
+ *      play. It is REQUIRED because `realpathSync.native` cannot follow an
+ *      App-Execution-Alias reparse point at all, so PATHEXT resolution fails for
+ *      a genuinely INSTALLED Microsoft-Store Python exactly as it does for the
+ *      stub — and refusing would hard-fail the installer on a machine with a
+ *      working Python. `CreateProcess` follows the alias fine (verified: the
+ *      bare spawn reaches it and it answers).
+ *
+ * WHAT GUARDS THE PARITY. `test/win32-spawn.test.mjs` pins THIS file's contract
+ * only — it cannot observe the server original changing. The cross-file guard is
+ * `server/src/test/win32-spawn-mirror-parity.test.ts`, which reads both files and
+ * fails if a security-load-bearing invariant is present in one and not the other.
+ * It lives in the SERVER package on purpose: CI runs vitest for `client` and
+ * `server` only, so a guard placed here would not gate anything.
+ *
+ * SECURITY posture, inherited verbatim from the original:
+ *   - A bare EXTENSION-LESS name resolves from PATH **only**, never the current
+ *     directory, so a planted `.\npm.cmd` cannot shadow the real tool. cmd.exe's
+ *     own lookup WOULD search cwd first, which is why an unresolved bare name is
+ *     never delegated to `cmd /c <bare>`; it goes to CreateProcess, which is
+ *     PATH-only (verified on Windows 11). NOTE the narrow wording: a bare name
+ *     that already CARRIES a `.cmd`/`.bat` extension skips resolution and is
+ *     wrapped as given, so `resolveSpawn(["npm.cmd"])` would reach cmd.exe's
+ *     cwd-first lookup. No caller does that (all three pass extension-less names
+ *     or absolute paths), and the case is pinned by a test so the gap cannot be
+ *     re-opened silently.
+ *   - Candidates are realpath-verified before use (same posture as
+ *     `server/src/core/path-guard.ts`).
+ *   - `resolveSpawn` never sets `options.shell`. cmd.exe gets discrete argv when
+ *     no token needs quoting; a spaced token produces the canonical verbatim
+ *     `cmd /d /s /c ""<quoted>" <args>"` line instead.
+ *
+ * PATH-FLAVOUR DISCIPLINE (iterate-2026-08-01-win32-spawn-followups). `platform`
+ * is injected, but `path` follows the REAL host — so on Linux the win32 branch
+ * used to parse `C:\…` with POSIX rules. Every `path.*` call is classified:
+ *   (a) win32 command-STRING semantics -> `path.win32` (`extname` x2, the
+ *       ComSpec `join`). No filesystem involved, so pinning the flavour is free
+ *       on Windows and makes the injected branch faithful on Linux.
+ *   (b) HOST-filesystem addressing -> the host `path` (`resolve` + `join` in
+ *       `resolveViaPathExt`), because those candidates are handed to
+ *       `realpathSync`/`statSync` and must name a file on the host actually
+ *       running. `PATH` splits on the hardcoded win32 `;`, already
+ *       host-independent. The server original carries the identical audit; the
+ *       parity guard pins both halves.
+ */
+
+import path from "node:path";
+import { statSync, realpathSync } from "node:fs";
+
+const WIN32_EXECUTABLE_EXTS = new Set([".exe", ".com"]);
+const WIN32_SHIM_EXTS = new Set([".cmd", ".bat"]);
+
+/** Absolute path to cmd.exe, preferring the environment's own ComSpec. */
+export function win32ComSpec(env = process.env) {
+  const fromEnv = env.ComSpec ?? env.COMSPEC;
+  if (fromEnv && fromEnv.trim()) return fromEnv;
+  const root = env.SystemRoot ?? env.windir ?? "C:\\Windows";
+  // (a) pure string — win32 flavour pinned, so an injected win32 platform on a
+  // POSIX host emits `…\System32\cmd.exe`, not the mixed `…/System32/cmd.exe`.
+  return path.win32.join(root, "System32", "cmd.exe");
+}
+
+function looksPathLike(name) {
+  return name.includes("\\") || name.includes("/") || /^[a-zA-Z]:/.test(name);
+}
+
+/**
+ * Resolve `name` to a concrete on-disk file via PATHEXT, realpath-verified.
+ * Returns undefined when nothing resolves.
+ *
+ * Every fs error is swallowed and the search continues — NOT only ENOENT.
+ * Verified 2026-07-31 on Windows 11: `realpathSync.native` on the Microsoft
+ * Store App-Execution-Alias `…\WindowsApps\python3.EXE` throws **EACCES**, not
+ * ENOENT. Treating that as fatal would abandon the scan and report a machine
+ * with a perfectly good `python` as having no Python at all.
+ */
+function resolveViaPathExt(name, env) {
+  const exts = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
+    .split(";")
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  const firstFile = (base, withBare) => {
+    for (const ext of withBare ? ["", ...exts] : exts) {
+      try {
+        const real = realpathSync.native(base + ext);
+        if (statSync(real).isFile()) return real;
+      } catch {
+        // no usable file at this candidate (ENOENT, EACCES on a Store alias,
+        // ELOOP on a broken reparse point) — keep searching
+      }
+    }
+    return undefined;
+  };
+
+  if (looksPathLike(name)) {
+    // Explicit path — honour an exact match first, then PATHEXT.
+    // (b) HOST flavour on purpose — this candidate goes straight to realpath.
+    return firstFile(path.resolve(name), true);
+  }
+  // Bare command — PATH only, never cwd. The empty ext is excluded so an
+  // extensionless POSIX shim is not matched. `;` is the win32 PATH delimiter,
+  // hardcoded and therefore already host-independent.
+  for (const dir of (env.PATH ?? env.Path ?? "").split(";")) {
+    const trimmed = dir.trim();
+    if (!trimmed) continue;
+    // (b) HOST flavour on purpose — see the classification in the header.
+    const hit = firstFile(path.join(trimmed, name), false);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+/**
+ * Characters cmd.exe would otherwise INTERPRET, and which a surrounding pair of
+ * double quotes makes literal. A token carrying one of these must therefore be
+ * quoted even when it has no whitespace — otherwise a PATH directory such as
+ * `C:\tools&more\` turns `…\tools&more\claude.cmd` into two commands.
+ *
+ * DELIBERATELY NOT IN THIS SET, because quoting does not fix them:
+ *   `%`  — `%VAR%` expands inside double quotes too. No caller can supply one
+ *          (`SAFE_ARG` in claude-cli.mjs rejects `%`, preflight's args are fixed
+ *          literals), and the server original refuses `%` in its upstream fence.
+ *   `"`  — a token containing a quote cannot be wrapped safely by this scheme at
+ *          all; the callers' charset gates are what keep one from arriving.
+ * Both limits are stated rather than papered over.
+ */
+const WIN32_CMD_SPECIAL = /[&|<>^]/;
+
+function win32NeedsQuote(token) {
+  return token === "" || /\s/.test(token) || WIN32_CMD_SPECIAL.test(token);
+}
+
+export function win32CmdWrap(target, rest, env = process.env) {
+  const parts = [target, ...rest];
+  const command = win32ComSpec(env);
+  // No token has a space → discrete argv: cmd.exe /d /s /c runs each token
+  // literally and the caller keeps shell:false.
+  if (!parts.some(win32NeedsQuote)) {
+    return { command, args: ["/d", "/s", "/c", ...parts] };
+  }
+  // A token has a space (e.g. `C:\Program Files\nodejs\npm.cmd`). Under `cmd /s`
+  // Node's own arg-quoting is stripped, so build the canonical
+  // `cmd /d /s /c ""<quoted-shim>" <args>"` line and pass it verbatim: `/s`
+  // strips ONLY the outer quote pair, leaving the inner quotes intact.
+  const inner = parts.map((p) => (win32NeedsQuote(p) ? `"${p}"` : p)).join(" ");
+  return {
+    command,
+    args: ["/d", "/s", "/c", `"${inner}"`],
+    windowsVerbatimArguments: true,
+  };
+}
+
+/**
+ * Compute the `{command, args, windowsVerbatimArguments?}` to hand to
+ * child_process with `shell: false`. POSIX is a pass-through.
+ *
+ *   - argv0 is a real `.exe`/`.com`  → spawn it directly (no cmd.exe).
+ *   - argv0 is a `.cmd`/`.bat` shim  → run through `cmd.exe /d /s /c`.
+ *   - argv0 is a bare name           → resolve via PATH+PATHEXT, then as above.
+ *   - nothing resolves for a bare name → the BARE name itself, for CreateProcess
+ *     to resolve PATH-only (divergence 5). This function does NOT return `null`
+ *     on any path; the `@returns` below said `| null` until 2026-08-01 and was
+ *     stale. Callers keep their `if (!plan)` guard as contract insurance.
+ *
+ * @param {string[]} argv command followed by its arguments
+ * @param {{ platform?: string, env?: Record<string, string | undefined> }} [opts]
+ *        injected for tests; defaults read the live process
+ * @returns {{ command: string, args: string[], windowsVerbatimArguments?: boolean }}
+ */
+export function resolveSpawn(argv, opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  const env = opts.env ?? process.env;
+  if (platform !== "win32") {
+    return { command: argv[0], args: argv.slice(1) };
+  }
+  const name = argv[0];
+  const rest = argv.slice(1);
+  // (a) pure string — win32 segment rules, so a POSIX host with an injected
+  // win32 platform classifies `C:\a.b\tool` the way Windows does.
+  const ext = path.win32.extname(name).toLowerCase();
+
+  if (WIN32_EXECUTABLE_EXTS.has(ext)) {
+    return { command: name, args: rest };
+  }
+  if (!WIN32_SHIM_EXTS.has(ext)) {
+    const resolved = resolveViaPathExt(name, env);
+    if (resolved) {
+      // (a) `resolved` is a host realpath; `path.win32` reads `/` as a
+      // separator too, so this is correct on either host.
+      if (WIN32_EXECUTABLE_EXTS.has(path.win32.extname(resolved).toLowerCase())) {
+        return { command: resolved, args: rest };
+      }
+      return win32CmdWrap(resolved, rest, env);
+    }
+    // Unresolved BARE name. Never DELEGATE it to `cmd /d /s /c <bare>` — that is
+    // cmd.exe's own cwd-first lookup and a planted `.\claude.cmd` would win it.
+    // Hand it to CreateProcess directly instead: verified PATH-only (a planted
+    // `.\x.exe` is ENOENT even with cwd set to its directory), and the only way
+    // to reach an App-Execution-Alias, which realpath cannot follow — that is
+    // how a real Store-installed Python stays detectable. A truly absent tool
+    // comes back ENOENT and the callers turn that into their "not found" verdict.
+    if (!looksPathLike(name)) return { command: name, args: rest };
+  }
+  return win32CmdWrap(name, rest, env);
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@svenroth-ai/shipwright",
+  "version": "0.24.1-next.0",
+  "description": "One command to install AND update Shipwright — the /shipwright-* SDLC plugins and the Command Center. Run `npx @svenroth-ai/shipwright@latest`.",
+  "type": "module",
+  "bin": {
+    "shipwright": "bin/shipwright.mjs"
+  },
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/deploy-swap.mjs",
+    "scripts/deploy-procs.mjs",
+    "scripts/repair-claude-json.mjs",
+    "scripts/kill-targets.js",
+    "server/dist/",
+    "server/profiles/",
+    "server/package.json",
+    "client/dist/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build-package.mjs",
+    "prepack": "node scripts/build-package.mjs",
+    "test": "vitest run",
+    "lint": "oxlint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "shipwright",
+    "claude-code",
+    "sdlc",
+    "installer",
+    "bootstrapper"
+  ],
+  "author": "svenroth.ai",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/svenroth-ai/shipwright-webui.git",
+    "directory": "bootstrapper"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.14.0",
+    "@hono/node-ws": "^1.3.1",
+    "@lydell/node-pty": "^1.1.0",
+    "@xterm/addon-serialize": "0.14.0",
+    "@xterm/headless": "6.0.0",
+    "hono": "^4.12.34",
+    "ignore": "^5.3.2",
+    "p-queue": "^9.2.0",
+    "proper-lockfile": "^4.1.0",
+    "shell-quote": "^1.8.4"
+  },
+  "devDependencies": {
+    "oxlint": "^1.66.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.8"
+  },
+  "overrides": {
+    "ws": "^8.21.0"
+  }
+}

package/scripts/deploy-procs.mjs

@@ -0,0 +1,208 @@
+/**
+ * deploy-procs.mjs — OS process discovery + termination for the production deploy.
+ *
+ * The impure twin of kill-targets.js (which is pure parsing, unit-tested, shared
+ * with dev-restart.js). Split out of deploy-swap.mjs to keep both files inside the
+ * 300-line convention; the swapper owns the deploy CHOREOGRAPHY, this file owns
+ * "which processes, and how do we end them".
+ *
+ * The one rule that must never be broken here: KILL ONE PROCESS, NEVER ITS TREE.
+ * See killPid().
+ */
+
+import { execSync, spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+// Audited kill-scope helpers: state-filtered, exact-port, IPv6-aware.
+const { parseWindowsListenerPids, buildLsofCommand } = require('./kill-targets.js');
+
+const isWin = process.platform === 'win32';
+const CAPTURE = { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] };
+
+/**
+ * The kill scope is EXACTLY the Hono port — never Vite. Deliberately NOT
+ * kill-targets.computeKillTargets(), which returns [PORT, VITE_PORT] for
+ * `dev:fresh` (that restarts both halves): a production deploy which swept the
+ * Vite port too would kill the operator's dev server as a side effect.
+ *
+ * @param {number} port
+ * @returns {number[]}
+ */
+export function killPortsFor(port) {
+  return [Number(port)];
+}
+
+/**
+ * Can we enumerate listeners at all? Windows always has netstat; POSIX needs lsof.
+ * Without it findListenerPids() returns [] for "nothing is listening" AND for "I
+ * cannot see listeners" — which would report a perfectly healthy server as a failed
+ * deploy. The pre-fix .sh had this fallback ("no lsof: settle for the process still
+ * being alive"); callers must keep it rather than lie about the outcome.
+ */
+export function canDiscoverListeners() {
+  if (isWin) return true;
+  try {
+    execSync('command -v lsof', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** PIDs LISTENING on the port (state-filtered + exact-port on both platforms). */
+export function findListenerPids(port) {
+  const ports = killPortsFor(port);
+  try {
+    if (isWin) {
+      // Plain `netstat -ano` (NOT `-p TCP`, which drops IPv6 listeners).
+      return parseWindowsListenerPids(execSync('netstat -ano', CAPTURE), ports);
+    }
+    const cmd = buildLsofCommand(ports);
+    if (!cmd) return [];
+    return execSync(cmd, CAPTURE).split(/\s+/).filter(Boolean);
+  } catch {
+    // netstat/lsof missing, or lsof exits 1 when nothing matches — nothing to kill.
+    return [];
+  }
+}
+
+/**
+ * PIDs of a `tsx watch` dev server on a webui server entry.
+ *
+ * Why this exists at all: killing only the port listener is not enough when the
+ * server runs under `tsx watch` — the watch PARENT would immediately respawn the
+ * child and re-take the port. The parent has to go too.
+ *
+ * KNOWN over-broad scope (inherited verbatim from the pre-fix inline sweep, kept
+ * for behavior parity): the match is `tsx` + `src/index.ts`, which also hits a
+ * *different* project's dev server, because a `tsx watch` command line carries the
+ * entry path relatively (`src/index.ts`) and not the repo it belongs to. Narrowing
+ * it needs per-PID cwd resolution — deliberately out of scope for the self-kill fix
+ * (see the iterate's decision drop).
+ */
+export function findTsxServerPids() {
+  try {
+    if (isWin) {
+      // spawnSync with shell:false — the argument reaches powershell.exe verbatim.
+      // An execSync string would cross JS -> cmd.exe -> powershell, three escaping
+      // layers deep, where one added quote silently turns the sweep into a no-op.
+      const script =
+        "Get-CimInstance Win32_Process -Filter \"Name='node.exe'\" | " +
+        "Where-Object { $_.CommandLine -match 'tsx' -and $_.CommandLine -match 'src[\\\\/]index\\.ts' } | " +
+        'Select-Object -ExpandProperty ProcessId';
+      const r = spawnSync('powershell', ['-NoProfile', '-Command', script], {
+        encoding: 'utf-8',
+        shell: false,
+      });
+      return String(r.stdout ?? '').split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+    }
+    return execSync("pgrep -f 'tsx.*src/index\\.ts'", CAPTURE).split(/\s+/).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Kill ONE process — never its tree.
+ *
+ * LOAD-BEARING: `taskkill /F /T` (what dev-restart.js uses) kills the target's
+ * DESCENDANTS too — and when the deploy runs from an embedded terminal, the swapper
+ * *is* a descendant of the Hono server it is about to kill. A /T sweep would
+ * therefore kill the swapper itself and re-create the very outage the swapper
+ * exists to prevent. Same on POSIX: signal the PID, never the process group.
+ */
+export function killPid(pid) {
+  try {
+    if (isWin) {
+      execSync(`taskkill /F /PID ${Number(pid)}`, { stdio: 'ignore' });
+    } else {
+      process.kill(Number(pid), 'SIGTERM');
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** SIGKILL escalation for anything still alive after the grace period (POSIX only). */
+export function killPidHard(pid) {
+  try {
+    if (!isWin) process.kill(Number(pid), 'SIGKILL');
+  } catch { /* already gone */ }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Stop whatever serves the port and WAIT FOR EVIDENCE that it is free.
+ *
+ * The pre-fix scripts slept a flat 700 ms and started regardless. If the kill did
+ * not land (a PID the user may not touch, a wedged process), the new server walks
+ * straight into EADDRINUSE and dies — leaving the machine with NO server. A stale
+ * old server is a bad outcome; no server at all is a far worse one. So when the
+ * port refuses to free, the caller must NOT start: `freed: false` means "leave the
+ * old server alone and report it".
+ *
+ * POSIX gets a real grace period first (SIGTERM), because the server flushes
+ * terminal snapshots on shutdown (ADR-092/096) and an immediate axe truncates that;
+ * SIGKILL follows only if it is still there. Windows has no graceful signal —
+ * taskkill /F was immediate before this change too.
+ *
+ * @returns {Promise<{freed: boolean, killed: string[], survivor: string|null}>}
+ */
+export async function stopOldServer(port, { timeoutMs = 5000 } = {}) {
+  const killed = [...new Set([...findListenerPids(port), ...findTsxServerPids()])];
+  for (const pid of killed) killPid(pid);
+
+  // Cannot observe listeners (no lsof) — fall back to the pre-fix behavior.
+  if (!canDiscoverListeners()) {
+    await sleep(700);
+    return { freed: true, killed, survivor: null };
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  let escalated = false;
+  while (Date.now() < deadline) {
+    await sleep(250);
+    const still = findListenerPids(port);
+    if (still.length === 0) return { freed: true, killed, survivor: null };
+    if (!escalated && Date.now() > deadline - timeoutMs / 2) {
+      for (const pid of still) killPidHard(pid);
+      escalated = true;
+    }
+  }
+  return { freed: false, killed, survivor: findListenerPids(port)[0] ?? null };
+}
+
+/**
+ * Ready = a listener on the port owned by OUR child. A stale listener (an old
+ * server that survived the kill) can therefore never fake success. Fails fast when
+ * the child exits (EADDRINUSE, missing dist, crash on boot), and degrades to a
+ * liveness check where listeners are not observable.
+ *
+ * @returns {Promise<{ok: boolean, readiness: 'listener'|'process-alive', exited: boolean, exitCode: number|null}>}
+ */
+export async function waitForServerUp(port, child, { timeoutMs = 12000 } = {}) {
+  let exited = false;
+  let exitCode = null;
+  child.on('exit', (code) => {
+    exited = true;
+    exitCode = code;
+  });
+
+  if (!canDiscoverListeners()) {
+    await sleep(2500);
+    return { ok: !exited, readiness: 'process-alive', exited, exitCode };
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await sleep(500);
+    if (exited) return { ok: false, readiness: 'listener', exited, exitCode };
+    if (findListenerPids(port).includes(String(child.pid))) {
+      return { ok: true, readiness: 'listener', exited: false, exitCode: null };
+    }
+  }
+  return { ok: false, readiness: 'listener', exited, exitCode };
+}