viewable-one 0.0.0-stage → 0.12.1

package/lib/devserver.mjs

@@ -0,0 +1,659 @@
+// THE DEV SERVER A SESSION LEFT RUNNING ON PURPOSE, and how it is stopped later.
+//
+// The ruling, 2026-09-06, option A of three. Since brief 19's addendum a
+// finished session EXITS the moment its result envelope lands ("the worktree
+// is the session's life"), and the 2026-09-06 test pass caught what that costs
+// a browser frame: the session ran `npx serve -l 8765` in the background, filed
+// the frame with that URL, finished, and the server died with the child
+// seconds later. The frame on the board pointed at a dead port - curl to
+// 127.0.0.1:8765 got nothing, no listener (evidence:
+// ~/Projects/glytch-e2e/.glytch/inbox/spawn/spawn-mtq5kdpg-9d7131.log).
+//
+// Two other options were on the table and he rejected both: keeping the child
+// alive while a frame exists (it walks back the addendum) and greying the
+// frame out at DONE (it makes the feature a screenshot). So the server is
+// started DETACHED from the session's own process, it outlives the session,
+// and something later stops it. This file is the "later".
+//
+// THE RECORD IS THE WHOLE CONTRACT. The session writes ONE file in the root of
+// its worktree, `.glytch-server.json`:
+//
+//   { "pid": 41231, "port": 8765, "cmd": "npx serve -l 8765",
+//     "startedAt": "2026-09-06T21:03:11.412Z" }
+//
+// The runner mirrors it into the spawn channel as `<id>.server` when the child
+// ends, because the worktree can be deleted (merge, delete, cleanWorktree) and
+// a record that dies with the tree cannot stop anything. `.server` does not end
+// in `.json` on purpose: the request scan lists `*.json` and would otherwise
+// read it as a spawn request, which is the exact bug SESSION_SIDECAR_SUFFIX
+// exists to remember (47 sidecars refused as requests). The sweep's `${id}.`
+// rule removes it with everything else the request owns.
+//
+// AND THE PID IS NEVER TRUSTED ON ITS OWN. A record can outlive its process by
+// days, and pids are reused: SIGTERM to a stale pid is a SIGTERM to whatever
+// the machine handed that number next, which on his Mac is as likely to be his
+// editor as anything. So `verifyRecordedServer` has to find POSITIVE evidence
+// that the process alive under that pid is the one the record describes, and
+// anything short of that is logged and left alone. Nothing here ever kills on
+// doubt.
+
+import { execFile, spawn as spawnProcess } from "node:child_process";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { killTree } from "./kill.mjs";
+import { devServerEnv } from "./child.mjs";
+import { runnableCommand } from "./windows-command.mjs";
+import { resolveContainedCwd } from "./worktree.mjs";
+
+/** The file a session writes in the root of its worktree. Named in the spawn
+ * instruction (src/store/spawnPayload.ts) and in bridge/SPAWN.md; both have to
+ * say the same string, so it is spelled once here. */
+export const SERVER_RECORD_FILE = ".glytch-server.json";
+
+/** How far a process's real start time may sit from the record's `startedAt`
+ * before the record is treated as describing a different process. The session
+ * writes the record right after starting the server, so the honest gap is
+ * seconds; ten minutes is slack for a slow start, a clock nudge and a session
+ * that wrote the file late. */
+export const START_SLACK_MS = 10 * 60_000;
+
+/** The record a session left in its worktree, or null. Never throws: no file,
+ * a half-written one and a session that never started a server are all "there
+ * is nothing to stop", which is the ordinary case. */
+export async function readWorktreeRecord(sessionDir) {
+  if (!sessionDir) return null;
+  try {
+    const parsed = JSON.parse(await readFile(join(sessionDir, SERVER_RECORD_FILE), "utf8"));
+    return Number.isFinite(Number(parsed?.pid)) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+const run = (bin, args, timeout = 5_000) =>
+  new Promise((resolve) => {
+    execFile(bin, args, { timeout, windowsHide: true, env: { ...process.env, LC_ALL: "C" } }, (error, stdout) => {
+      if (error) return resolve("");
+      resolve(String(stdout ?? ""));
+    });
+  });
+
+/** `{ startedAt, command }` for a live pid, or null when there is no such
+ * process. `lstart` is a fixed-width local time ("Sun Sep  6 22:01:47 2026",
+ * the C locale's spelling: `run` sets LC_ALL=C, since en_NZ prints "Sun  6 Sep")
+ * padded before the command, so the split is a regex. A start time that will
+ * not parse is null, never a number: the caller says "cannot check". */
+export function parsePsRow(row) {
+  const line = String(row ?? "").trim();
+  if (line === "") return null;
+  const match = line.match(/^(\w{3}\s+\w{3}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s+(.*)$/);
+  if (!match) return { startedAt: null, command: line };
+  const parsed = Date.parse(match[1]);
+  return { startedAt: Number.isFinite(parsed) ? parsed : null, command: match[2].trim() };
+}
+
+const psRowFor = async (pid) => parsePsRow(await run("ps", ["-p", String(pid), "-o", "lstart=,command="]));
+
+/** The pids listening on a TCP port right now, as a Set. An absent or failing
+ * `lsof` is an empty set, never an exception: this is corroboration, and the
+ * caller has a second way to find it. */
+const lsofListeners = async (port) => {
+  const out = await run("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"]);
+  return new Set(
+    out
+      .trim()
+      .split("\n")
+      .map((n) => parseInt(n, 10))
+      .filter((n) => Number.isFinite(n) && n > 1),
+  );
+};
+
+// ---------- the same two pieces of evidence, on Windows ----------
+//
+// Brief 21, ruling 4A (2026-09-07). The guard above is the whole reason
+// this file exists - never a kill on a bare pid - and on Windows neither of
+// its two sources exists: no `ps -o lstart`, no `lsof`. The Windows pair he
+// ruled for is `netstat -ano` for the pid listening on the recorded port, and
+// `Get-CimInstance Win32_Process` (through `ConvertTo-Json`) for the start
+// time and the command line. Both are parsed by pure functions with their own
+// tests, and both are injected into `verifyRecordedServer` exactly the way
+// `ps` and `listeners` already were: option B of the ruling - kill with no
+// verification - was rejected on its face.
+
+/** The pids listening on `port`, read out of `netstat -ano`.
+ *
+ * A row is `  TCP    0.0.0.0:8765    0.0.0.0:0    LISTENING    41231`, and the
+ * IPv6 form puts the port after a bracketed address (`[::]:8765`), so the port
+ * is taken from after the LAST colon of the local address rather than by
+ * splitting on ":". UDP rows have no state column and are skipped: only a
+ * listening TCP socket is evidence that this is the recorded server. */
+export function parseNetstatListeners(output, port) {
+  const wanted = Number(port);
+  const pids = new Set();
+  if (!Number.isFinite(wanted) || wanted <= 0) return pids;
+  for (const line of String(output ?? "").split(/\r?\n/)) {
+    const cols = line.trim().split(/\s+/);
+    if (cols.length < 5) continue;
+    if (cols[0].toUpperCase() !== "TCP") continue;
+    if (cols[3].toUpperCase() !== "LISTENING") continue;
+    const local = cols[1];
+    const colon = local.lastIndexOf(":");
+    if (colon < 0) continue;
+    if (parseInt(local.slice(colon + 1), 10) !== wanted) continue;
+    const pid = parseInt(cols[4], 10);
+    if (Number.isFinite(pid) && pid > 1) pids.add(pid);
+  }
+  return pids;
+}
+
+/** `{ startedAt, command }` out of `Get-CimInstance Win32_Process | ConvertTo-Json`,
+ * or null when the process is gone (PowerShell prints nothing, or `null`).
+ *
+ * Three shapes have to be read, because ConvertTo-Json does not spell a
+ * DateTime the same way twice across PowerShell versions:
+ *
+ *   "/Date(1757192507412)/"      Windows PowerShell 5.1, milliseconds since epoch
+ *   "2026-09-06T22:01:47.412+03:00"   PowerShell 7, ISO 8601
+ *   "20260906220147.412000+180"  the raw CIM_DATETIME, if the property arrives
+ *                                as a string rather than as a date
+ *
+ * A start time that will not parse is null, never a number, so the caller says
+ * "cannot check" rather than guessing - the same contract parsePsRow has. */
+export function parseCimProcess(json) {
+  const text = String(json ?? "").trim();
+  if (text === "" || text === "null") return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const row = Array.isArray(parsed) ? parsed[0] : parsed;
+  if (!row || typeof row !== "object") return null;
+  return {
+    startedAt: parseCimDate(row.CreationDate),
+    command: String(row.CommandLine ?? row.Name ?? "").trim(),
+  };
+}
+
+/** The three spellings above, as a millisecond epoch or null. */
+export function parseCimDate(value) {
+  if (value == null) return null;
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  const text = String(value).trim();
+  if (text === "") return null;
+
+  const dotNet = text.match(/^\/Date\((-?\d+)\)\/$/);
+  if (dotNet) {
+    const ms = Number(dotNet[1]);
+    return Number.isFinite(ms) ? ms : null;
+  }
+
+  // CIM_DATETIME: yyyymmddHHMMSS.mmmmmm{+|-}UUU, offset in MINUTES from UTC.
+  const cim = text.match(/^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})\.(\d{6})([+-]\d{3})$/);
+  if (cim) {
+    const [, y, mo, d, h, mi, s, us, off] = cim;
+    const minutes = Number(off);
+    const utc = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s), Math.round(Number(us) / 1000));
+    return Number.isFinite(utc) && Number.isFinite(minutes) ? utc - minutes * 60_000 : null;
+  }
+
+  const iso = Date.parse(text);
+  return Number.isFinite(iso) ? iso : null;
+}
+
+/** The PowerShell one-liner asked for a pid. Spelled here so the test can
+ * assert the argv rather than a string built somewhere else. */
+export const cimProcessArgs = (pid) => [
+  "-NoProfile",
+  "-NonInteractive",
+  "-Command",
+  `Get-CimInstance Win32_Process -Filter "ProcessId=${Number(pid)}" | Select-Object ProcessId,CreationDate,CommandLine | ConvertTo-Json -Compress`,
+];
+
+const cimRowFor = async (pid) => parseCimProcess(await run("powershell.exe", cimProcessArgs(pid), 15_000));
+
+const netstatListeners = async (port) => parseNetstatListeners(await run("netstat", ["-ano"], 15_000), port);
+
+const defaultPs = (pid) => (process.platform === "win32" ? cimRowFor(pid) : psRowFor(pid));
+const defaultListeners = (port) => (process.platform === "win32" ? netstatListeners(port) : lsofListeners(port));
+
+const parentPidFor = async (pid) => {
+  const output = process.platform === "win32"
+    ? await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command",
+      `(Get-CimInstance Win32_Process -Filter "ProcessId=${Number(pid)}").ParentProcessId`], 15_000)
+    : await run("ps", ["-p", String(pid), "-o", "ppid="]);
+  const value = Number(output.trim());
+  return Number.isInteger(value) && value > 1 ? value : null;
+};
+
+/** Publishing a socket needs stronger evidence than identifying a process to
+ * stop. A live npm/shell wrapper can survive its server, while another service
+ * takes its port. Every listener must belong to this recorded process tree;
+ * missing process inspection is a refusal, never a command-line fallback. */
+export async function verifyPreviewServer(record, {
+  ps = defaultPs, listeners = defaultListeners, parentPid = parentPidFor,
+} = {}) {
+  const pid = Number(record?.pid);
+  const port = Number(record?.port);
+  if (!Number.isInteger(pid) || pid <= 1 || !Number.isInteger(port) || port < 1 || port > 65535) {
+    return { ours: false, reason: "no usable preview pid/port in the record" };
+  }
+  const row = await ps(pid);
+  const startedAt = Date.parse(record?.startedAt ?? "");
+  // The record is written after launch (including the relaunch settle wait).
+  // An older OS start can therefore be legitimate, but a newer start means
+  // PID reuse. Allow only the one-second resolution of POSIX process times.
+  if (!row || !Number.isFinite(startedAt) || !Number.isFinite(row.startedAt) ||
+      row.startedAt > startedAt + 1000 || row.startedAt < startedAt - START_SLACK_MS) {
+    return { ours: false, reason: "preview process start time could not be verified" };
+  }
+  const owners = await listeners(port);
+  if (!owners.size) return { ours: false, reason: "preview port has no verified listener" };
+  for (const owner of owners) {
+    let current = owner;
+    const seen = new Set();
+    while (current !== pid && Number.isInteger(current) && current > 1 && seen.size < 32 && !seen.has(current)) {
+      seen.add(current);
+      current = await parentPid(current);
+    }
+    if (current !== pid) return { ours: false, reason: `preview port ${port} has an unrelated or unverified listener` };
+  }
+  return { ours: true, reason: `recorded process tree owns every listener on ${port}` };
+}
+
+/** Two strings that name the same command, allowing for how differently a
+ * command is spelled by the person who typed it and by `ps`. `npx serve -l
+ * 8765` runs as `node .../serve/build/main.js -l 8765`, so a containment test
+ * either way is as far as this can honestly go - and it is only ever one of
+ * two pieces of evidence, never the deciding one on its own. */
+export function commandsAgree(recorded, running) {
+  const a = normaliseCommand(recorded);
+  const b = normaliseCommand(running);
+  if (a === "" || b === "") return false;
+  return a === b || a.includes(b) || b.includes(a);
+}
+
+/** Whitespace collapsed, and DOUBLE QUOTES DROPPED.
+ *
+ * 2026-09-07, brief 21, the first windows-latest run. Win32_Process's
+ * CommandLine hands back the line as Windows stores it, with the executable
+ * and every argument containing a space wrapped in quotes:
+ * `"C:\...\node.exe" -e "setInterval(...)"`. The record is written from
+ * `process.execPath` and an argv array, so it carries none of them, and the
+ * containment test below could not see that the two were the same line - a
+ * real detached server was therefore reported as "neither its port nor its
+ * command line matches the record" and left running. Quoting is the shell's
+ * punctuation, not part of the command, and this comparison was already
+ * deliberately fuzzy in both directions; dropping quotes on BOTH sides makes
+ * it no fuzzier about anything a person would call a different command. */
+const normaliseCommand = (value) =>
+  String(value ?? "").replace(/"/g, "").replace(/\s+/g, " ").trim();
+
+/** Is the process under `record.pid` the server this record describes?
+ *
+ * Returns `{ ours, reason }`. `ours` is true only when the pid is alive, its
+ * start time is inside START_SLACK_MS of the record's `startedAt` (or cannot
+ * be read at all), and there is positive evidence it is the same server:
+ * either it is listening on the recorded port, or its command line agrees with
+ * the recorded one. Everything else is a reason, and a reason means the caller
+ * logs and leaves the process alone.
+ *
+ * `ps` and `listeners` are injected so the decision can be tested without a
+ * machine's process table under it. */
+export async function verifyRecordedServer(record, { ps = defaultPs, listeners = defaultListeners } = {}) {
+  const pid = Number(record?.pid);
+  if (!Number.isFinite(pid) || pid <= 1) return { ours: false, reason: "no usable pid in the record" };
+
+  const row = await ps(pid);
+  if (!row) return { ours: false, reason: "gone" };
+
+  const recordedStart = Date.parse(record?.startedAt ?? "");
+  if (Number.isFinite(recordedStart) && row.startedAt !== null) {
+    const drift = Math.abs(row.startedAt - recordedStart);
+    if (drift > START_SLACK_MS) {
+      return {
+        ours: false,
+        reason: `pid ${pid} started ${Math.round(drift / 60_000)} min from the recorded time: a different process has this pid now`,
+      };
+    }
+  }
+
+  const port = Number(record?.port);
+  if (Number.isFinite(port) && port > 0) {
+    const pids = await listeners(port);
+    if (pids.has(pid)) return { ours: true, reason: `listening on ${port}` };
+  }
+  if (commandsAgree(record?.cmd, row.command)) return { ours: true, reason: "command line matches the record" };
+
+  return { ours: false, reason: `pid ${pid} is alive but neither its port nor its command line matches the record` };
+}
+
+/** Stop a recorded server: SIGTERM, then SIGKILL after a short grace - and on
+ * Windows `taskkill /pid <pid> /t` then `/t /f`, which is the same pair of
+ * steps (brief 21, ruling 4A). BEHIND THE SAME GUARD either way: the kill
+ * is only reached once `verifyRecordedServer` found positive evidence that
+ * this pid is the recorded server, and `killTree` decides nothing about that.
+ *
+ * Refuses on anything the verify step could not establish, and says why. The
+ * caller logs ONE line either way - a sweep that kills silently is a sweep
+ * nobody can debug at the moment a port is mysteriously free.
+ *
+ * `process.kill(pid, 0)` is kept for the liveness check between the two
+ * passes: signal 0 is the one signal use in this package that means the same
+ * thing on Windows as it does on a Mac. */
+export async function stopRecordedServer(record, { graceMs = 3_000, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), kill = killTree, ...deps } = {}) {
+  const check = await verifyRecordedServer(record, deps);
+  if (!check.ours) return { stopped: false, reason: check.reason };
+
+  const pid = Number(record.pid);
+  try {
+    await kill(pid, { force: false });
+  } catch {
+    return { stopped: false, reason: "gone" };
+  }
+  await sleep(graceMs);
+  try {
+    process.kill(pid, 0);
+    await kill(pid, { force: true });
+    return { stopped: true, reason: `forced after ${graceMs}ms: it ignored the first stop` };
+  } catch {
+    return { stopped: true, reason: "stopped on the first ask" };
+  }
+}
+
+// ---------- RELAUNCHING ONE, on a button in the terminal ----------
+//
+// The ask, 2026-09-06: "When a dev server gets detached, add a button in
+// terminal to relaunch dev server in this branch. Allows me to test browser."
+//
+// The sweep above is the reason the button has to exist: a server started
+// detached is stopped later, so a session card that finished this morning has
+// a browser frame beside it pointing at a port that stopped answering at
+// lunchtime. Nothing on the board can start a process, so the RUNNER does it -
+// the same actor that spawns sessions.
+//
+// OVER ROWS, 2026-09-11 (brief 30 Move 2b): the app asks with a `run_ops` row
+// of `kind:"relaunch"` now, surfaced by `heartbeat`'s `ops`, claimed with
+// `opTake`, answered with `opResult` (updatable - the button can be pressed
+// again) - `bridge/lib/runner.mjs`'s `serviceRowOps` is the runner's half.
+// `relaunchServer` below is the pure core, unchanged in what it decides;
+// what moved is where the RECORD comes from and where the OUTCOME goes.
+// Before this pass both were the mailbox: `<id>.server` (a mirror of the
+// session's own `.glytch-server.json`) was the record a `<id>.relaunch`
+// signal file read, and `<id>.relaunch.result.txt` was the answer. Now the
+// record is the run row's own `server` column (mirrored there by
+// `runnerCompletion.mjs` when the child exits, exactly as before except the
+// destination), falling back to the worktree's own `.glytch-server.json`
+// (`readWorktreeRecord`, unchanged - local scratch, not a mailbox) when the
+// row has none yet; the outcome is the `run_ops` row's own `result`,
+// written by `opResult`, not a second file.
+//
+// NO LLM TURN, and that is the design rather than an economy. Relaunching is
+// re-running a command that is already written down; a session would cost real
+// credits to read a record and type a line the runner can read and type
+// itself, and it could not do it at all once its worktree stopped being a
+// session's home.
+//
+// THE RECORDED COMMAND, AND NOTHING ELSE. `cmd` comes from the record the
+// session wrote (the run row's `server`, or `.glytch-server.json` in the
+// tree), never from the op's own payload, and a missing record is a refusal
+// rather than a prompt for one. A relaunch that could carry its own command
+// line would be a way to run arbitrary shell from the canvas through a row
+// the app wrote without a human ever seeing that particular string.
+
+/** How long to wait after spawning before believing the server started. A
+ * command that is missing, mistyped or instantly fatal is gone well inside
+ * this; a real dev server is still starting up and that is fine - the check
+ * is "did it die immediately", not "is it serving yet". */
+export const RELAUNCH_SETTLE_MS = 700;
+
+const defaultExists = async (path) => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// A RECORD IS DATA SOMEONE ELSE WROTE (#324). The session that wrote
+// `.glytch-server.json` is an agent, and anything in the linked folder can
+// write that file too, so its `cmd` is never handed to a shell. It is read
+// as plain words (a program and its arguments), run with no shell, with the
+// environment a dev server needs and nothing more (`devServerEnv`: no model
+// keys, no cloud credentials), and only inside the linked folder.
+
+/** One word of a command a relaunch will run: letters, digits and the
+ * punctuation a path, a flag or a version carries. Anything a shell would
+ * act on (`;|&$<>` quotes, backticks, globs, `~`) is not in it. */
+const PLAIN_WORD = /^[A-Za-z0-9_@%+=:,./\\-]+$/;
+const ENV_WORD = /^([A-Za-z_][A-Za-z0-9_]*)=([A-Za-z0-9_@%+:,./\\-]*)$/;
+
+/** `{ env, argv }` for a recorded command, or null when it is not plain words.
+ *
+ * The spawn instruction tells a session to start its server inside a detach
+ * wrapper (`setsid <cmd> >/dev/null 2>&1 &`, `nohup <cmd> ... & disown`), and
+ * some write that whole line down. The wrapper is how it was started, not
+ * what it ran, so it is taken off first; the relaunch detaches on its own.
+ * Leading `NAME=value` words (`PORT=5273 npm run dev`) become environment. */
+export function relaunchCommand(cmd) {
+  let line = String(cmd ?? "").trim();
+  line = line.replace(/\s*>\s*\/dev\/null\s+2>&1\s*&\s*(?:disown\s*)?$/, "").trim();
+  line = line.replace(/^(?:(?:setsid|nohup)\s+)+/, "").trim();
+  const words = line.split(/\s+/).filter(Boolean);
+  const env = {};
+  while (words.length > 0 && ENV_WORD.test(words[0])) {
+    const [, name, value] = words.shift().match(ENV_WORD);
+    env[name] = value;
+  }
+  if (words.length === 0 || !words.every((w) => PLAIN_WORD.test(w)) || words[0].includes("=")) return null;
+  return { env, argv: words };
+}
+
+/** Start the command in `cwd`, detached, with nothing attached to it - the
+ * same shape the spawn instruction tells a session to use
+ * (store/spawnPayload.ts), for the same reason: it has to outlive the process
+ * that started it, and the runner is no more permanent than a session. No
+ * shell on any platform: `runnableCommand` resolves a Windows npm shim to
+ * its own entry point rather than going through cmd.exe. */
+const defaultSpawn = ({ env, argv }, cwd) => {
+  const fullEnv = { ...devServerEnv(process.env), ...env };
+  const run = runnableCommand(argv[0], argv.slice(1), { env: fullEnv });
+  const child = spawnProcess(run.file, run.args, { cwd, env: fullEnv, shell: false, detached: true, stdio: "ignore" });
+  // A missing program is an async 'error' on the child; without a listener
+  // it would take the runner down. The settle check reports it instead.
+  child.on("error", () => {});
+  child.unref();
+  return child;
+};
+
+const stillAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Re-run the recorded dev server for one run.
+ *
+ * `record` is the run row's own `server` column, or `null` when the row has
+ * none yet (a session that started no server) - the caller
+ * (`bridge/lib/runner.mjs`'s `serviceRowOps`) falls back to
+ * `readWorktreeRecord(hinted)` when the row is empty but the op's payload
+ * carries a `worktreePath` hint, exactly as the file-based signal used to.
+ *
+ * Returns `{ ok, detail, record? }`. Every refusal names what was missing,
+ * because the detail is what the human reads on the run's card (DATED
+ * REWRITE 2026-09-07, brief 26 ruling 4: was "in the frame"):
+ *
+ *   - no record at all (the session never started a server, or none has
+ *     been mirrored onto the run row yet);
+ *   - a record with no usable `cmd`, or one that is not plain words
+ *     (`relaunchCommand`, #324);
+ *   - a directory outside the linked folder `root`, or no `root` to check;
+ *   - the worktree it ran in is gone, so there is nowhere to run it;
+ *   - the port is already held by something that is not this record;
+ *   - the command exited inside RELAUNCH_SETTLE_MS.
+ *
+ * A server that is STILL RUNNING is not a refusal: the answer is the pid and
+ * port it is already on, and nothing is started twice.
+ *
+ * Every dependency is injected so the decision is testable without a machine's
+ * process table or a real dev server under it. */
+export async function relaunchServer(
+  record,
+  {
+    spawn = defaultSpawn,
+    exists = defaultExists,
+    listeners = defaultListeners,
+    ps = defaultPs,
+    settleMs = RELAUNCH_SETTLE_MS,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    now = () => new Date(),
+    // The linked folder. A record may only run inside it (#324).
+    root,
+  } = {},
+) {
+  if (!record) {
+    return {
+      ok: false,
+      detail:
+        `No dev server record for this run. Only a session that started one and wrote ` +
+        `${SERVER_RECORD_FILE} can be relaunched: the runner re-runs the command that was ` +
+        `recorded and never invents one.`,
+    };
+  }
+
+  const cmd = typeof record.cmd === "string" ? record.cmd.trim() : "";
+  if (cmd === "") {
+    return { ok: false, detail: `The dev server record has no cmd, so there is nothing to re-run.` };
+  }
+
+  const command = relaunchCommand(cmd);
+  if (!command) {
+    return {
+      ok: false,
+      detail:
+        `The dev server record's command \`${cmd}\` is not a plain command, so it is not run. A relaunch ` +
+        `runs one program and its arguments, with no shell: no pipes, \`&&\`, quotes or \`$\`. Start it ` +
+        `by hand in the session's folder instead.`,
+    };
+  }
+
+  const recordedPath = typeof record.worktreePath === "string" && record.worktreePath !== "" ? record.worktreePath : null;
+  if (!recordedPath) {
+    return { ok: false, detail: `The dev server record does not say which directory it ran in.` };
+  }
+  const contained = typeof root === "string" && root !== "" ? resolveContainedCwd(root, recordedPath, "a relaunched dev server") : null;
+  if (!contained?.ok) {
+    return {
+      ok: false,
+      detail: `The dev server record names ${recordedPath} as its directory, and ${contained?.reason ?? "there is no linked folder to check it against."}`,
+    };
+  }
+  // THE COPY IS GONE (#485). Keep changes merges the branch and deletes the
+  // separate copy, so the recorded directory is not there any more. The app
+  // then starts again from the linked folder, which now holds the kept code.
+  // Nothing else changes: the recorded command still runs as one program, and
+  // the folder is the one the record was already checked against.
+  let worktreePath = contained.path;
+  // A record written by an earlier start from the folder says so: its path is
+  // the linked folder now, which a path check alone cannot tell from a session
+  // that ran there itself.
+  let fromFolder = record.fromFolder === true;
+  if (!(await exists(worktreePath))) {
+    if (typeof root === "string" && root !== "" && (await exists(root))) {
+      worktreePath = root;
+      fromFolder = true;
+    } else {
+      return {
+        ok: false,
+        detail:
+          `The worktree ${worktreePath} is gone, so \`${cmd}\` has nowhere to run. Merging or ` +
+          `deleting a branch takes its dev server with it.`,
+      };
+    }
+  }
+
+  // ALREADY UP. The button sits on the frame whether or not the server died,
+  // so pressing it on a live one must not start a second copy on the same
+  // port. Same evidence the sweep demands before it kills anything.
+  const standing = await verifyRecordedServer(record, { ps, listeners });
+  if (standing.ours) {
+    return {
+      ok: true,
+      record,
+      detail: `The dev server is already running: pid ${record.pid}${record.port ? ` on port ${record.port}` : ""} (${standing.reason}).`,
+    };
+  }
+
+  const port = Number(record.port);
+  const hasPort = Number.isFinite(port) && port > 0;
+  if (hasPort) {
+    const holding = await listeners(port);
+    if (holding.size > 0) {
+      return {
+        ok: false,
+        detail:
+          `Port ${port} is already held by pid ${[...holding].join(", ")}, which is not the server this ` +
+          `record describes. Stop whatever is on that port and press it again.`,
+      };
+    }
+  }
+
+  let child;
+  try {
+    child = spawn(command, worktreePath);
+  } catch (error) {
+    return {
+      ok: false,
+      detail: `\`${cmd}\` could not be started: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  const pid = Number(child?.pid);
+  if (!Number.isFinite(pid) || pid <= 1) {
+    return {
+      ok: false,
+      detail: `\`${cmd}\` was started but the operating system gave back no pid, so nothing can be recorded for it.`,
+    };
+  }
+
+  await sleep(settleMs);
+  if (!stillAlive(pid)) {
+    return {
+      ok: false,
+      detail:
+        `\`${cmd}\` exited within ${settleMs}ms of starting. A detached server has no terminal, so its ` +
+        `output went nowhere - run it by hand in ${worktreePath} to see why.`,
+    };
+  }
+
+  // A FRESH RECORD. The old one names a pid that is not this process any
+  // more, so the worktree's own copy is rewritten - `runnerCompletion.mjs`
+  // has no session left to mirror it off, but the caller (`serviceRowOps`)
+  // reads THIS return value straight back into the run row's own `server`
+  // column via `runnerApi.update`, which is what used to be the second file
+  // write (`<id>.server`) and is a row now.
+  const stamp = now().toISOString();
+  const fresh = { ...record, pid, cmd, startedAt: stamp, worktreePath, relaunchedAt: stamp, ...(fromFolder ? { fromFolder: true } : {}) };
+  try {
+    // Not into the person's own folder: only a session's copy carries the file.
+    if (!fromFolder) await writeFile(join(worktreePath, SERVER_RECORD_FILE), `${JSON.stringify(fresh, null, 2)}\n`, "utf8");
+  } catch {
+    /* the tree may be read-only or on its way out; the run row is what a
+       later relaunch and the sweep both read, and it is the copy that has
+       to land - this write is a courtesy to anyone looking at the tree. */
+  }
+
+  return {
+    ok: true,
+    record: fresh,
+    detail:
+      `Started \`${cmd}\` in ${worktreePath}: pid ${pid}${hasPort ? ` on port ${port}` : ""}. It is ` +
+      `detached, so it outlives this runner and the daily sweep stops it.`,
+  };
+}