portless-studio 0.1.3 → 0.1.5

package/dist/server/application/terminals.js

@@ -1,5 +1,6 @@
 import { err, ok } from "../../core/result.js";
 import { OutputBuffer } from "../../core/terminals/output-buffer.js";
+import { rememberCommand, } from "../../core/terminals/terminal-history.js";
 import { appError } from "./app-error.js";
 const DEFAULT_MAX_OUTPUT = 2 * 1024 * 1024;
 const DEFAULT_GRACE_MS = 3_000;
@@ -9,6 +10,13 @@ const DEFAULT_COLS = 120;
 const DEFAULT_ROWS = 30;
 const MAX_COMMAND_CHARS = 8 * 1024;
 const MAX_TITLE_CHARS = 60;
+const DEFAULT_PERSIST_DELAY_MS = 300;
+/**
+ * A command that ended this shortly before Studio stopped counts as running then: a service
+ * manager stops Studio's commands together with Studio, and their exits can arrive first.
+ */
+const RECENT_EXIT_MS = 2_000;
+const RESTART_NOTE = "\r\n[Studio] Stopped by a Studio restart. Run it again to start it.\r\n";
 /**
  * The terminals Studio runs. Each keeps its last `maxOutputChars` of output, numbered so a client
  * can resume where it stopped. From a page, commands run only in folders Studio shows; a local
@@ -25,6 +33,11 @@ export class TerminalManager {
     #namingTimeoutMs;
     #processTree;
     #homeDir;
+    #history;
+    #persistDelayMs;
+    #recent = null;
+    #persistTimer;
+    #closing = false;
     #entries = new Map();
     #watchers = new Set();
     /** Folders a local program ran a terminal in. */
@@ -45,6 +58,8 @@ export class TerminalManager {
         this.#namingTimeoutMs = options.namingTimeoutMs ?? DEFAULT_NAMING_TIMEOUT_MS;
         this.#processTree = options.processTree;
         this.#homeDir = options.homeDir;
+        this.#history = options.history;
+        this.#persistDelayMs = options.persistDelayMs ?? DEFAULT_PERSIST_DELAY_MS;
     }
     get mode() {
         return this.#spawner.mode;
@@ -73,6 +88,7 @@ export class TerminalManager {
         const wanted = title.trim().slice(0, MAX_TITLE_CHARS);
         entry.info = { ...entry.info, title: wanted || entry.defaultTitle };
         this.#publishStatus(entry);
+        this.#schedulePersist();
         return ok({ ...entry.info });
     }
     async create(request, origin) {
@@ -87,69 +103,97 @@ export class TerminalManager {
             return cwd;
         if (origin.trusted)
             this.#trustedFolders.add(cwd.value);
-        const id = `t${this.#nextId++}`;
-        const cols = readSize(request.cols, DEFAULT_COLS);
-        const rows = readSize(request.rows, DEFAULT_ROWS);
         const naming = readNaming(request.name);
-        const defaultTitle = (command.value || this.#spawner.shellName || "shell").slice(0, MAX_TITLE_CHARS);
-        const title = request.title?.trim().slice(0, MAX_TITLE_CHARS) || defaultTitle;
         const project = await this.#projectOf(cwd.value);
-        const entry = {
-            defaultTitle,
-            info: {
-                id,
-                title,
-                cwd: cwd.value,
-                command: command.value ?? "",
-                project: project?.name ?? null,
-                worktree: project?.worktree ?? null,
-                branch: project?.branch ?? null,
-                ports: [],
-                status: "running",
-                exitCode: null,
-                startedAt: this.#now(),
-                endedAt: null,
-                pid: null,
-                mode: this.#spawner.mode,
-                cols,
-                rows,
-                nextSeq: 0,
-                naming,
-            },
-            request: {
-                command: command.value,
-                cwd: cwd.value,
-                cols,
-                rows,
-                env: {
-                    TERM: "xterm-256color",
-                    COLUMNS: String(cols),
-                    LINES: String(rows),
-                    PORTLESS_STUDIO_TERMINAL: id,
-                },
-            },
-            buffer: new OutputBuffer(this.#maxOutput),
-            process: null,
-            stopTimers: [],
-            watchers: new Set(),
-            baseline: null,
-            namingTimer: undefined,
-        };
+        const entry = this.#newEntry({
+            id: `t${this.#nextId++}`,
+            command: command.value,
+            cwd: cwd.value,
+            title: request.title,
+            cols: readSize(request.cols, DEFAULT_COLS),
+            rows: readSize(request.rows, DEFAULT_ROWS),
+            naming,
+            project,
+            startedBy: origin.trusted ? "program" : "person",
+            startedAt: this.#now(),
+        });
         if (naming)
             entry.baseline = await this.#portsInUse();
         const started = await this.#spawn(entry);
         if (!started.ok)
             return started;
-        this.#entries.set(id, entry);
+        this.#entries.set(entry.info.id, entry);
+        if (command.value) {
+            this.#recent = rememberCommand(this.#recentCommands(), cwd.value, command.value);
+        }
         if (naming)
             this.#startNaming(entry);
         else
             this.#updateWorkspaceWatch();
         this.#changed();
+        this.#schedulePersist();
         if (this.#watchers.size > 0)
             void this.#refreshPorts();
         return ok({ ...entry.info });
     }
+    /** The last commands run in each folder, newest first. */
+    recentCommands() {
+        return Object.fromEntries(Object.entries(this.#recentCommands()).map(([folder, list]) => [folder, [...list]]));
+    }
+    /**
+     * Brings back the terminals that were running when Studio last stopped: listed as stopped by a
+     * restart (`ask`), started again unless they are a plain shell (`always`), or forgotten
+     * (`never`). Folders that no longer exist are skipped. Call it once, on start.
+     */
+    async restore(mode) {
+        if (this.#closing)
+            return;
+        const saved = this.#history?.read().running ?? [];
+        if (mode === "never" || saved.length === 0) {
+            if (saved.length > 0)
+                this.#persistNow();
+            return;
+        }
+        const restored = [];
+        for (const item of saved) {
+            if (this.#entries.size >= this.#maxTerminals)
+                break;
+            const cwd = this.#folders.directory(item.cwd);
+            if (cwd === null)
+                continue;
+            if (item.startedBy === "program")
+                this.#trustedFolders.add(cwd);
+            const entry = this.#newEntry({
+                id: `t${this.#nextId++}`,
+                command: item.command || null,
+                cwd,
+                title: item.title,
+                cols: DEFAULT_COLS,
+                rows: DEFAULT_ROWS,
+                naming: null,
+                project: { name: item.project ?? "", worktree: item.worktree, branch: item.branch },
+                startedBy: item.startedBy,
+                startedAt: item.startedAt,
+            });
+            if (item.project === null) {
+                entry.info = { ...entry.info, project: null, worktree: null, branch: null };
+            }
+            entry.info = { ...entry.info, status: "exited", stoppedByRestart: true };
+            this.#append(entry, RESTART_NOTE);
+            this.#entries.set(entry.info.id, entry);
+            restored.push(entry);
+        }
+        this.#changed();
+        this.#persistNow();
+        if (mode !== "always")
+            return;
+        for (const entry of restored) {
+            if (this.#closing)
+                return;
+            if (entry.info.command !== "")
+                await this.restart(entry.info.id);
+        }
+    }
     input(id, text) {
         const entry = this.#entries.get(id);
         if (!entry)
@@ -164,29 +208,86 @@ export class TerminalManager {
         const entry = this.#entries.get(id);
         if (!entry)
             return notFound(id);
+        entry.restartGeneration += 1;
         if (!entry.process || entry.info.status !== "running")
             return ok({ ...entry.info });
+        entry.stoppedOnPurpose = true;
         this.#escalate(entry, entry.process);
         return ok({ ...entry.info });
     }
     /** Runs the same command again; stops the current one first and waits for it to end. */
-    async restart(id) {
+    restart(id) {
         const entry = this.#entries.get(id);
         if (!entry)
-            return notFound(id);
+            return Promise.resolve(notFound(id));
+        if (this.#closing)
+            return Promise.resolve(err(appError("command_failed", "Studio is stopping.")));
+        if (entry.restartPromise)
+            return entry.restartPromise;
+        let resolve;
+        let reject;
+        const pending = new Promise((done, failed) => {
+            resolve = done;
+            reject = failed;
+        });
+        // Register before interrupting: an exit callback can synchronously request another restart.
+        entry.restartPromise = pending;
+        void this.#restartEntry(entry, entry.restartGeneration).then((result) => {
+            entry.restartPromise = null;
+            resolve(result);
+        }, (error) => {
+            entry.restartPromise = null;
+            reject(error);
+        });
+        return pending;
+    }
+    async #restartEntry(entry, generation) {
+        const stillWanted = () => !this.#closing &&
+            this.#entries.get(entry.info.id) === entry &&
+            entry.restartGeneration === generation;
+        const cancelled = () => err(appError("terminal_not_running", "The restart was cancelled."));
         const current = entry.process;
         if (current && entry.info.status === "running") {
             const ended = new Promise((resolve) => current.onExit(() => resolve()));
+            entry.stoppedOnPurpose = true;
             this.#escalate(entry, current);
             await ended;
         }
+        if (!stillWanted())
+            return cancelled();
         this.#append(entry, `\r\n[Studio] restarted: ${entry.info.command || "shell"}\r\n`);
-        const started = await this.#spawn(entry);
+        if (entry.info.project === null) {
+            const project = await this.#projectOf(entry.info.cwd);
+            if (project) {
+                entry.info = {
+                    ...entry.info,
+                    project: project.name,
+                    worktree: project.worktree ?? null,
+                    branch: project.branch ?? null,
+                };
+            }
+        }
+        if (!stillWanted())
+            return cancelled();
+        const started = await this.#spawn(entry, stillWanted);
         if (!started.ok)
             return started;
-        entry.info = { ...entry.info, status: "running", exitCode: null, endedAt: null };
+        if (!stillWanted()) {
+            entry.process?.kill();
+            entry.process = null;
+            return cancelled();
+        }
+        entry.stoppedOnPurpose = false;
+        entry.info = {
+            ...entry.info,
+            status: "running",
+            exitCode: null,
+            endedAt: null,
+            stoppedByRestart: false,
+        };
         entry.info.startedAt = this.#now();
         this.#publishStatus(entry);
+        this.#schedulePersist();
         this.#updateWorkspaceWatch();
         if (this.#watchers.size > 0)
             void this.#refreshPorts();
@@ -205,6 +306,7 @@ export class TerminalManager {
         entry.watchers.clear();
         this.#updateWorkspaceWatch();
         this.#changed();
+        this.#schedulePersist();
         return ok(undefined);
     }
     read(id, from, maxChars) {
@@ -225,8 +327,16 @@ export class TerminalManager {
         entry.watchers.add(watcher);
         return ok(() => entry.watchers.delete(watcher));
     }
-    /** Studio is stopping: every command gets SIGTERM and SIGKILL right away. */
+    /**
+     * Studio is stopping: the terminals still running are written down for the next start, then
+     * every command gets SIGTERM and SIGKILL right away.
+     */
     closeAll() {
+        if (!this.#closing) {
+            this.#persistNow(true);
+            this.#closing = true;
+            clearTimeout(this.#persistTimer);
+        }
         for (const entry of this.#entries.values()) {
             this.#clearTimers(entry);
             if (entry.process && entry.info.status === "running") {
@@ -237,7 +347,7 @@ export class TerminalManager {
         this.#stopWorkspaceWatch?.();
         this.#stopWorkspaceWatch = undefined;
     }
-    async #spawn(entry) {
+    async #spawn(entry, stillWanted) {
         let child;
         try {
             child = await this.#spawner.spawn(entry.request);
@@ -245,6 +355,10 @@ export class TerminalManager {
         catch (error) {
             return err(appError("command_failed", `Could not start it: ${error.message}`));
         }
+        if (stillWanted && !stillWanted()) {
+            child.kill();
+            return err(appError("terminal_not_running", "The restart was cancelled."));
+        }
         entry.process = child;
         entry.info.pid = child.pid;
         entry.info.mode = this.#spawner.mode;
@@ -267,10 +381,110 @@ export class TerminalManager {
             }
             entry.info.ports = [];
             this.#publishStatus(entry);
+            this.#schedulePersist();
             this.#updateWorkspaceWatch();
         });
         return ok(undefined);
     }
+    #newEntry(fields) {
+        const defaultTitle = (fields.command || this.#spawner.shellName || "shell").slice(0, MAX_TITLE_CHARS);
+        const title = fields.title?.trim().slice(0, MAX_TITLE_CHARS) || defaultTitle;
+        const { id, cols, rows } = fields;
+        return {
+            defaultTitle,
+            info: {
+                id,
+                title,
+                cwd: fields.cwd,
+                command: fields.command ?? "",
+                project: fields.project?.name ?? null,
+                worktree: fields.project?.worktree ?? null,
+                branch: fields.project?.branch ?? null,
+                ports: [],
+                status: "running",
+                exitCode: null,
+                startedAt: fields.startedAt,
+                endedAt: null,
+                pid: null,
+                mode: this.#spawner.mode,
+                cols,
+                rows,
+                nextSeq: 0,
+                naming: fields.naming,
+                startedBy: fields.startedBy,
+                stoppedByRestart: false,
+            },
+            request: {
+                command: fields.command,
+                cwd: fields.cwd,
+                cols,
+                rows,
+                env: {
+                    TERM: "xterm-256color",
+                    COLUMNS: String(cols),
+                    LINES: String(rows),
+                    PORTLESS_STUDIO_TERMINAL: id,
+                },
+            },
+            buffer: new OutputBuffer(this.#maxOutput),
+            process: null,
+            stopTimers: [],
+            watchers: new Set(),
+            baseline: null,
+            namingTimer: undefined,
+            stoppedOnPurpose: false,
+            restartPromise: null,
+            restartGeneration: 0,
+        };
+    }
+    #recentCommands() {
+        this.#recent ??= this.#history?.read().recentCommands ?? {};
+        return this.#recent;
+    }
+    #schedulePersist() {
+        if (!this.#history || this.#closing || this.#persistTimer)
+            return;
+        this.#persistTimer = setTimeout(() => {
+            this.#persistTimer = undefined;
+            this.#persistNow();
+        }, this.#persistDelayMs);
+        this.#persistTimer.unref?.();
+    }
+    /**
+     * Writes the terminals that run and the recent commands. When Studio stops, commands that just
+     * ended without anyone asking count as running too.
+     */
+    #persistNow(stopping = false) {
+        const history = this.#history;
+        if (!history || this.#closing)
+            return;
+        clearTimeout(this.#persistTimer);
+        this.#persistTimer = undefined;
+        const now = this.#now();
+        const running = [...this.#entries.values()]
+            .filter((entry) => entry.info.status === "running" ||
+            entry.info.stoppedByRestart === true ||
+            (stopping &&
+                !entry.stoppedOnPurpose &&
+                entry.info.endedAt !== null &&
+                now - entry.info.endedAt <= RECENT_EXIT_MS))
+            .map(({ info }) => ({
+            command: info.command,
+            cwd: info.cwd,
+            title: info.title,
+            startedAt: info.startedAt,
+            startedBy: info.startedBy ?? "person",
+            project: info.project,
+            worktree: info.worktree,
+            branch: info.branch,
+        }));
+        try {
+            history.write({ running, recentCommands: this.#recentCommands() });
+        }
+        catch {
+            // A full disk or a read-only config folder: terminals keep working, they just are not kept.
+        }
+    }
     #escalate(entry, child) {
         this.#clearTimers(entry);
         child.interrupt();

package/dist/server/infrastructure/config/json-terminal-history-store.js

@@ -0,0 +1,30 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseTerminalHistory, } from "../../../core/terminals/terminal-history.js";
+import { writeFileAtomic } from "./atomic-write.js";
+const FILE_NAME = "terminals.json";
+/** `terminals.json` in the config file's folder. */
+export function terminalHistoryPathFor(configPath) {
+    return path.join(path.dirname(configPath), FILE_NAME);
+}
+/**
+ * The terminals running when Studio stopped and the recent commands per folder, as
+ * `{ "running": [...], "recentCommands": { "<folder>": [...] } }`. Studio writes it on its own.
+ */
+export class JsonTerminalHistoryStore {
+    path;
+    constructor(filePath) {
+        this.path = filePath;
+    }
+    read() {
+        try {
+            return parseTerminalHistory(JSON.parse(fs.readFileSync(this.path, "utf8")));
+        }
+        catch {
+            return parseTerminalHistory(null);
+        }
+    }
+    write(history) {
+        writeFileAtomic(this.path, `${JSON.stringify(history, null, 2)}\n`);
+    }
+}

package/dist/server/infrastructure/system/dev-process-tree.js

@@ -0,0 +1,70 @@
+function devRunner(command) {
+    const words = command.match(/"[^"]*"|'[^']*'|[^\s]+/g) ?? [];
+    const basename = (word) => word
+        .replace(/^['"]|['"]$/g, "")
+        .split(/[/\\]/)
+        .pop() ?? "";
+    const executable = basename(words[0] ?? "");
+    const script = /^(?:node|node.exe|bun|bun.exe)$/.test(executable)
+        ? basename(words[1] ?? "")
+        : executable;
+    return /^(?:pnpm|npm(?:-cli)?|npx(?:-cli)?|yarn|bun|bunx|turbo|vite|next|astro|wrangler|ng|nuxt|remix|nodemon|tsx)(?:\.(?:c?js|mjs|exe|cmd))?$/i.test(script);
+}
+function commandShell(command) {
+    const words = command.match(/"[^"]*"|'[^']*'|[^\s]+/g) ?? [];
+    const name = (words[0] ?? "")
+        .replace(/^['"]|['"]$/g, "")
+        .split(/[/\\]/)
+        .pop()
+        ?.toLowerCase();
+    if (name === "cmd.exe" || name === "cmd") {
+        const commandAt = words.findIndex((word) => /^\/c$/i.test(word));
+        return (commandAt > 0 &&
+            commandAt < words.length - 1 &&
+            words.slice(1, commandAt).every((word) => /^\/[dsq]$/i.test(word)));
+    }
+    return /^(?:sh|bash|zsh|dash)$/.test(name ?? "") && words[1] === "-c";
+}
+/** Root first prevents supervisors restarting children; the remaining children are deepest first. */
+export function devProcessTree(pid, table) {
+    const byPid = new Map(table.map((entry) => [entry.pid, entry]));
+    let root = byPid.get(pid);
+    if (!root)
+        return [];
+    const seen = new Set([pid]);
+    for (let depth = 0; depth < 64; depth++) {
+        let parent = byPid.get(root.parent);
+        if (!parent || parent.pid <= 1 || seen.has(parent.pid))
+            break;
+        seen.add(parent.pid);
+        if (commandShell(parent.command)) {
+            parent = byPid.get(parent.parent);
+            if (!parent || parent.pid <= 1 || seen.has(parent.pid))
+                break;
+            seen.add(parent.pid);
+        }
+        if (!devRunner(parent.command))
+            break;
+        root = parent;
+    }
+    const descendants = new Set([root.pid]);
+    const ordered = [root.pid];
+    for (let depth = 0; depth < 64; depth++) {
+        const added = table.filter((entry) => !descendants.has(entry.pid) && descendants.has(entry.parent));
+        if (!added.length)
+            break;
+        for (const entry of added) {
+            descendants.add(entry.pid);
+            ordered.push(entry.pid);
+        }
+    }
+    return [root.pid, ...ordered.slice(1).reverse()];
+}
+export function parseProcessTable(output) {
+    return output.split(/\r?\n/).flatMap((line) => {
+        const match = /^\s*(\d+)\s+(\d+)\s+(.+)$/.exec(line);
+        return match
+            ? [{ pid: Number(match[1]), parent: Number(match[2]), command: match[3] ?? "" }]
+            : [];
+    });
+}

package/dist/server/infrastructure/system/linux-ports.js

@@ -19,22 +19,51 @@ export function parseProcNetTcp(text) {
     }
     return sockets;
 }
+/** Clock ticks per second, the unit of `/proc/<pid>/stat` times; 100 on every common kernel. */
+export const DEFAULT_CLOCK_TICKS = 100;
+/**
+ * When a process started, in epoch milliseconds, from field 22 of `/proc/<pid>/stat` (clock ticks
+ * since boot) and `btime` in `/proc/stat` (boot time in epoch seconds). Null when unreadable.
+ */
+export function processStartTime(stat, procStat, ticksPerSecond) {
+    if (stat === null || procStat === null || ticksPerSecond <= 0)
+        return null;
+    // The command name in field 2 may hold spaces and parentheses, so count fields after the last ")".
+    const fields = stat
+        .slice(stat.lastIndexOf(")") + 1)
+        .trim()
+        .split(/\s+/);
+    const ticks = Number(fields[19]);
+    const boot = Number(/^btime\s+(\d+)$/m.exec(procStat)?.[1]);
+    if (!Number.isFinite(ticks) || !Number.isFinite(boot) || boot <= 0)
+        return null;
+    return Math.round(boot * 1000 + (ticks * 1000) / ticksPerSecond);
+}
+/** `getconf CLK_TCK`, or the usual 100 when it cannot run. */
+export async function readClockTicks(io) {
+    const answer = await io.run("getconf", ["CLK_TCK"]).catch(() => null);
+    const ticks = Number(answer?.stdout.trim());
+    return Number.isInteger(ticks) && ticks > 0 ? ticks : DEFAULT_CLOCK_TICKS;
+}
 /**
  * Lists listening ports from `/proc`. A socket is linked to its process through the
  * `/proc/<pid>/fd/*` links; processes of other users cannot be read and stay unknown.
  */
-export async function listLinuxPorts(io) {
+export async function listLinuxPorts(io, ticksPerSecond = async () => DEFAULT_CLOCK_TICKS) {
     const sockets = [
         ...parseProcNetTcp(io.readFile("/proc/net/tcp") ?? ""),
         ...parseProcNetTcp(io.readFile("/proc/net/tcp6") ?? ""),
     ];
     const pids = pidsByInode(io, new Set(sockets.map((socket) => socket.inode)));
+    const ticks = pids.size > 0 ? await ticksPerSecond() : DEFAULT_CLOCK_TICKS;
+    const procStat = pids.size > 0 ? io.readFile("/proc/stat") : null;
     const byPort = new Map();
     for (const socket of sockets) {
         const known = byPort.get(socket.port);
         if (known?.pid != null)
             continue;
         const pid = pids.get(socket.inode) ?? null;
+        const startedAt = pid === null ? null : processStartTime(io.readFile(`/proc/${pid}/stat`), procStat, ticks);
         byPort.set(socket.port, {
             port: socket.port,
             pid,
@@ -43,6 +72,7 @@ export async function listLinuxPorts(io) {
             executable: pid === null
                 ? null
                 : (io.readLink(`/proc/${pid}/exe`)?.replace(DELETED_SUFFIX, "") ?? null),
+            ...(startedAt === null ? {} : { startedAt }),
         });
     }
     return [...byPort.values()].sort((a, b) => a.port - b.port);

package/dist/server/infrastructure/system/macos-ports.js

@@ -48,28 +48,57 @@ export function parsePsExecutables(text) {
     }
     return executables;
 }
+/**
+ * Reads `ps -o pid=,etime= -p ...` into pid -> start in epoch milliseconds. `etime` is the time
+ * since the process started as `[[dd-]hh:]mm:ss`, which unlike `lstart` reads the same in every
+ * locale.
+ */
+export function parsePsStartTimes(text, now) {
+    const starts = new Map();
+    for (const line of text.split("\n")) {
+        const match = /^\s*(\d+)\s+(?:(\d+)-)?(?:(\d{1,2}):)?(\d{1,2}):(\d{2})\s*$/.exec(line);
+        if (!match)
+            continue;
+        const [, pid, days, hours, minutes, seconds] = match;
+        const elapsed = ((Number(days ?? 0) * 24 + Number(hours ?? 0)) * 60 + Number(minutes)) * 60 + Number(seconds);
+        starts.set(Number(pid), now - elapsed * 1000);
+    }
+    return starts;
+}
 /** Lists listening ports with `lsof` and `ps`, which ship with macOS. */
-export async function listMacosPorts(io) {
+export async function listMacosPorts(io, starts = new Map(), now = Date.now) {
     const listen = await io.run("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN", "-F", "pcn"]);
     const rows = parseLsofListen(listen.stdout);
     if (rows.length === 0)
         return [];
     const pids = [...new Set(rows.map((row) => row.pid))];
-    const [cwd, ps] = await Promise.all([
+    for (const pid of starts.keys())
+        if (!pids.includes(pid))
+            starts.delete(pid);
+    const unknownStarts = pids.filter((pid) => !starts.has(pid));
+    const [cwd, ps, elapsed] = await Promise.all([
         io.run("lsof", ["-a", "-d", "cwd", "-p", pids.join(","), "-F", "pn"]),
         // -ww: without it ps cuts long paths at the terminal width.
         io.run("ps", ["-ww", "-o", "pid=,comm=", "-p", pids.join(",")]),
+        unknownStarts.length === 0
+            ? null
+            : io.run("ps", ["-o", "pid=,etime=", "-p", unknownStarts.join(",")]),
     ]);
+    const read = parsePsStartTimes(elapsed?.stdout ?? "", now());
+    for (const pid of unknownStarts)
+        starts.set(pid, read.get(pid) ?? null);
     const cwds = parseLsofCwds(cwd.stdout);
     const executables = parsePsExecutables(ps.stdout);
     const byPort = new Map();
     for (const row of rows) {
         if (byPort.has(row.port))
             continue;
+        const startedAt = starts.get(row.pid) ?? null;
         byPort.set(row.port, {
             ...row,
             cwd: cwds.get(row.pid) ?? null,
             executable: executables.get(row.pid) ?? null,
+            ...(startedAt === null ? {} : { startedAt }),
         });
     }
     return [...byPort.values()].sort((a, b) => a.port - b.port);

package/dist/server/infrastructure/system/port-closed.js

@@ -0,0 +1,15 @@
+import { createConnection } from "node:net";
+/** A refused TCP connection confirms closure; timeouts and unexpected errors do not. */
+export async function portClosed(port) {
+    const answers = await Promise.all(["127.0.0.1", "::1"].map((host) => new Promise((resolve) => {
+        const socket = createConnection({ host, port });
+        const finish = (closed) => {
+            socket.destroy();
+            resolve(closed);
+        };
+        socket.once("connect", () => finish(false));
+        socket.once("error", (error) => finish(error.code === "ECONNREFUSED" || error.code === "EAFNOSUPPORT"));
+        socket.setTimeout(800, () => finish(false));
+    })));
+    return answers.every(Boolean);
+}