toolroll 0.9.63 → 0.9.65

package/dist/live-terminal.js

@@ -0,0 +1,649 @@
+/**
+ * Live terminals (docs/plans/live-terminal.md): `claude`, `codex` or a shell running interactively in a real
+ * pseudo-terminal, in its own worktree, hosted by the console and streamed to the person's browser.
+ *
+ * The person drives; nothing here is unattended and nothing here spends on Toolroll's behalf. A session lives
+ * while the console runs, attached or not, and ends when its program exits, its owner closes it, or the console
+ * stops. Sessions are in memory; the worktree and its branch outlive them.
+ */
+import { randomBytes } from "node:crypto";
+import { createRequire } from "node:module";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readlinkSync, realpathSync, statSync } from "node:fs";
+import { delimiter, isAbsolute, join } from "node:path";
+import { codingEnvironment } from "./coding-provider.js";
+import { teardownGit, refusal } from "./teardown-git.js";
+export const TERMINAL_PROGRAMS = ["claude", "codex", "shell"];
+/** At most this many running sessions per console, and this many kept at all (ended ones count until removed). */
+export const MAX_LIVE_TERMINALS = 8;
+export const MAX_KEPT_TERMINALS = 16;
+/** At most this many pages attached to one session (a desktop, a phone, a spare tab or two). */
+export const MAX_VIEWERS = 4;
+/** Raw output kept per session for a page that attaches later. */
+export const SCROLLBACK_BYTES = 1024 * 1024;
+/** After SIGHUP, the terminal's processes have this long before SIGKILL. */
+export const CLOSE_GRACE_MS = 2_000;
+/** Typed input not yet read by the program, per terminal: past this, more is refused until it reads. */
+export const MAX_PENDING_INPUT = 1024 * 1024;
+/** How often a running terminal's processes are noted, so ones that outlive their parent are still known. */
+export const CUSTODY_REFRESH_MS = 5_000;
+export const COLS = { min: 2, max: 500 };
+export const ROWS = { min: 1, max: 200 };
+/** A device path as `ps` prints it: /dev/ttys012 → ttys012, /dev/pts/3 → pts/3. */
+export const ttyName = (path) => typeof path === "string" && /^\/dev\/(ttys\d+|pts\/\d+|tty[a-z]?\d+)$/.test(path) ? path.slice(5) : null;
+/**
+ * node-pty's write queue (@lydell/node-pty 1.2.0-beta.15, pinned exactly): typed input waits in its
+ * `_writeStream._writeQueue` until the kernel takes it. A shape this doesn't recognise is unmeasurable: Infinity, so
+ * input is refused rather than queued without bound (a test pins the shape against the installed package).
+ */
+export function pendingInputOf(pty) {
+    const queue = pty?._writeStream?._writeQueue;
+    if (!Array.isArray(queue))
+        return Infinity;
+    let bytes = 0;
+    for (const task of queue) {
+        if (!Buffer.isBuffer(task?.buffer) || typeof task.offset !== "number")
+            return Infinity;
+        bytes += task.buffer.byteLength - task.offset;
+    }
+    return bytes;
+}
+/** node-pty, if this install has it (an optional dependency with prebuilt binaries); null when it doesn't load. */
+export function loadPtySpawn() {
+    try {
+        const pty = createRequire(import.meta.url)("@lydell/node-pty");
+        return (file, args, options) => {
+            const native = pty.spawn(file, args, { name: "xterm-256color", cwd: options.cwd, env: options.env, cols: options.cols, rows: options.rows });
+            return {
+                get pid() { return native.pid; },
+                tty: ttyName(native.ptsName),
+                pendingInput: () => pendingInputOf(native),
+                onData: listener => native.onData(listener),
+                onExit: listener => native.onExit(listener),
+                write: data => native.write(data),
+                resize: (cols, rows) => native.resize(cols, rows),
+                kill: signal => native.kill(signal),
+            };
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Raw output, oldest dropped first, never more than `cap` bytes. */
+export class Scrollback {
+    cap;
+    chunks = [];
+    size = 0;
+    constructor(cap = SCROLLBACK_BYTES) {
+        this.cap = cap;
+    }
+    push(chunk) {
+        if (chunk.length >= this.cap) {
+            this.chunks = [chunk.subarray(chunk.length - this.cap)];
+            this.size = this.cap;
+            return;
+        }
+        this.chunks.push(chunk);
+        this.size += chunk.length;
+        while (this.size > this.cap) {
+            const first = this.chunks[0];
+            const over = this.size - this.cap;
+            if (first.length <= over) {
+                this.chunks.shift();
+                this.size -= first.length;
+            }
+            else {
+                this.chunks[0] = first.subarray(over);
+                this.size -= over;
+            }
+        }
+    }
+    bytes() { return Buffer.concat(this.chunks, this.size); }
+    get length() { return this.size; }
+}
+const NO_LEDGER = { reserve() { }, running() { }, release() { }, forget() { } };
+export class TerminalError extends Error {
+    constructor(message) { super(message); this.name = "TerminalError"; }
+}
+const clamp = (value, range) => Math.min(range.max, Math.max(range.min, Math.trunc(value)));
+/** The executable on PATH, or null. */
+export function onPath(name, env = process.env) {
+    if (isAbsolute(name))
+        return existsSync(name) ? name : null;
+    const extensions = process.platform === "win32" ? (env["PATHEXT"] ?? ".EXE;.CMD;.BAT").split(";") : [""];
+    for (const dir of (env["PATH"] ?? "").split(delimiter)) {
+        if (dir === "")
+            continue;
+        for (const extension of extensions) {
+            const path = join(dir, name + extension);
+            try {
+                if (statSync(path).isFile())
+                    return path;
+            }
+            catch { /* not here */ }
+        }
+    }
+    return null;
+}
+function defaultProgram(program, env) {
+    if (program === "shell") {
+        if (process.platform === "win32")
+            return { file: onPath("pwsh", env) ?? onPath("powershell", env) ?? "cmd.exe", args: [] };
+        const shell = env["SHELL"];
+        const file = shell !== undefined && isAbsolute(shell) && existsSync(shell) ? shell : onPath("bash", env) ?? "/bin/sh";
+        return { file, args: ["-l"] };
+    }
+    const file = onPath(program, env);
+    return file === null ? null : { file, args: [] };
+}
+export class TerminalHost {
+    options;
+    sessions = new Map();
+    starting = 0;
+    stopped = false;
+    clock;
+    env;
+    ledger;
+    processes;
+    custodyTimer = null;
+    constructor(options) {
+        this.options = options;
+        this.clock = options.clock ?? (() => new Date());
+        this.env = options.env ?? codingEnvironment;
+        this.ledger = options.ledger ?? NO_LEDGER;
+        this.processes = options.processes ?? readProcessTable;
+    }
+    summary(session) {
+        const { id, owner, generation, repo, program, branch, worktree, startedAt, endedAt, exit, endedBy, cleanup } = session;
+        return { id, owner, generation, repo, program, branch, worktree, startedAt, endedAt, exit, endedBy, cleanup };
+    }
+    /** This person's sessions, newest first. */
+    list(owner) {
+        return [...this.sessions.values()].filter(one => one.owner === owner).map(one => this.summary(one)).reverse();
+    }
+    get(id) {
+        const session = this.sessions.get(id);
+        return session === undefined ? null : this.summary(session);
+    }
+    running() {
+        return [...this.sessions.values()].filter(one => one.endedAt === null).length;
+    }
+    /**
+     * Make the worktree and start the program in it. `admit` is asked again right before the program starts (after the
+     * slow git work): a person whose access or project went in between starts nothing.
+     */
+    async start({ name: owner, generation }, repoPath, program, size = { cols: 100, rows: 30 }, admit = () => null) {
+        if (this.stopped)
+            throw new TerminalError("The console is stopping.");
+        if (!TERMINAL_PROGRAMS.includes(program))
+            throw new TerminalError("Choose Claude, Codex or a shell.");
+        if (this.running() + this.starting >= (this.options.maxSessions ?? MAX_LIVE_TERMINALS))
+            throw new TerminalError(`At most ${this.options.maxSessions ?? MAX_LIVE_TERMINALS} terminals can run at once. Close one first.`);
+        if (this.sessions.size + this.starting >= MAX_KEPT_TERMINALS)
+            throw new TerminalError(`${MAX_KEPT_TERMINALS} terminals are kept already. Remove an ended one first.`);
+        const env = { ...this.env(), TERM: "xterm-256color", COLORTERM: "truecolor" };
+        const command = this.options.programs?.[program] ?? defaultProgram(program, env);
+        if (command === null)
+            throw new TerminalError(`${program === "claude" ? "Claude Code" : "Codex"} isn't installed on this computer (\`${program}\` is not on PATH).`);
+        const id = randomBytes(16).toString("hex");
+        // The slot is held, here and for the updater, before any slow work.
+        this.starting += 1;
+        let reserved = false;
+        try {
+            try {
+                this.ledger.reserve(id);
+                reserved = true;
+            }
+            catch (error) {
+                throw error instanceof TerminalError ? error : new TerminalError(error instanceof Error ? error.message : "No terminal can start right now.");
+            }
+            let repo;
+            try {
+                repo = realpathSync(repoPath);
+            }
+            catch {
+                throw new TerminalError("That project folder is gone.");
+            }
+            const hardened = this.options.git ?? teardownGit();
+            const git = async (args) => {
+                const result = await hardened(repo, args);
+                if (result.code !== 0)
+                    throw new TerminalError(refusal(result) !== null ? `Toolroll won't run git in this project: ${refusal(result)}.` : "Git couldn't make a worktree for this terminal. Check the project and try again.");
+                return result.stdout.trim();
+            };
+            if (realpathSync(await git(["rev-parse", "--show-toplevel"])) !== repo)
+                throw new TerminalError("Choose the root of a Git project.");
+            const base = await git(["rev-parse", "--verify", "HEAD^{commit}"]);
+            const branch = `toolroll/live-${id.slice(0, 12)}`;
+            const worktree = join(this.options.worktreeRoot, id);
+            mkdirSync(this.options.worktreeRoot, { recursive: true, mode: 0o700 });
+            await git(["worktree", "add", "-b", branch, "--", worktree, base]);
+            const cols = clamp(size.cols, COLS), rows = clamp(size.rows, ROWS);
+            let pty;
+            try {
+                if (this.stopped)
+                    throw new TerminalError("The console is stopping.");
+                const refused = admit();
+                if (refused !== null)
+                    throw new TerminalError(refused);
+                pty = this.options.spawn(command.file, command.args, { cwd: worktree, env, cols, rows });
+            }
+            catch (error) {
+                // Nothing ran in it: take the worktree and branch back.
+                await git(["worktree", "remove", "--force", "--", worktree]).catch(() => { });
+                await git(["branch", "-D", "--", branch]).catch(() => { });
+                throw error instanceof TerminalError ? error : new TerminalError(`The program couldn't start: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            let resolveExited;
+            const session = { id, owner, generation, repo, program, branch, worktree, startedAt: this.clock().toISOString(), endedAt: null, exit: null, endedBy: null, cleanup: null,
+                pty, leader: pty.pid, tty: pty.tty, known: new Map(), exitedAt: null, worktreeReal: realpathSync(worktree), startedMs: Date.now(), residentsOnly: false, residentsSeen: new Map(), cols, rows, scrollback: new Scrollback(this.options.scrollbackBytes), viewers: new Set(), closing: null,
+                exited: new Promise(resolve => { resolveExited = resolve; }) };
+            this.sessions.set(id, session);
+            this.ledger.running(id);
+            reserved = false;
+            this.noteCustody();
+            pty.onData(data => {
+                this.noteSoon();
+                const chunk = Buffer.from(data, "utf8");
+                session.scrollback.push(chunk);
+                for (const viewer of session.viewers) {
+                    try {
+                        viewer.output(chunk);
+                    }
+                    catch { /* the viewer's own close handles it */ }
+                }
+            });
+            pty.onExit(({ exitCode, signal }) => {
+                session.pty = null;
+                session.exitedAt = Date.now();
+                session.endedAt = this.clock().toISOString();
+                session.exit = { code: exitCode ?? null, signal: signal || null };
+                for (const viewer of session.viewers) {
+                    try {
+                        viewer.control({ t: "exit", code: session.exit.code, signal: session.exit.signal });
+                    }
+                    catch { /* gone */ }
+                }
+                this.options.record?.("exit", this.summary(session));
+                resolveExited();
+                // A program that ended on its own takes its jobs with it, as closing a terminal window does.
+                if (session.closing === null)
+                    session.closing = this.sweep(session);
+            });
+            this.options.record?.("start", this.summary(session));
+            return this.summary(session);
+        }
+        finally {
+            this.starting -= 1;
+            if (reserved)
+                this.ledger.release(id, null);
+        }
+    }
+    /** Attach a page: it gets the scrollback, then `hello`, then live output. Returns its detach. */
+    attach(id, viewer) {
+        const session = this.sessions.get(id);
+        if (session === undefined)
+            throw new TerminalError("No such terminal.");
+        if (session.viewers.size >= MAX_VIEWERS)
+            throw new TerminalError(`This terminal is open in ${MAX_VIEWERS} places already. Close one of them.`);
+        const replay = session.scrollback.bytes();
+        if (replay.length > 0)
+            viewer.output(replay);
+        viewer.control({ t: "hello", cols: session.cols, rows: session.rows, program: session.program, ended: session.endedAt !== null });
+        if (session.exit !== null)
+            viewer.control({ t: "exit", code: session.exit.code, signal: session.exit.signal });
+        session.viewers.add(viewer);
+        return () => { session.viewers.delete(viewer); };
+    }
+    /** How many pages are attached now. */
+    viewerCount(id) { return this.sessions.get(id)?.viewers.size ?? 0; }
+    /** Type into the program. False (nothing queued) while it has MAX_PENDING_INPUT unread, or can't be measured. */
+    input(id, data) {
+        const pty = this.sessions.get(id)?.pty;
+        if (pty == null)
+            return true;
+        if (pty.pendingInput() + Buffer.byteLength(data) > MAX_PENDING_INPUT)
+            return false;
+        pty.write(data);
+        this.noteSoon();
+        return true;
+    }
+    resize(id, cols, rows) {
+        const session = this.sessions.get(id);
+        if (session?.pty == null)
+            return;
+        session.cols = clamp(cols, COLS);
+        session.rows = clamp(rows, ROWS);
+        try {
+            session.pty.resize(session.cols, session.rows);
+        }
+        catch { /* it exited between */ }
+    }
+    noteTimer = null;
+    /** Activity (output, typing) usually means a command started: note processes shortly after, at most every 250 ms. */
+    noteSoon() {
+        if (this.noteTimer !== null)
+            return;
+        this.noteTimer = setTimeout(() => { this.noteTimer = null; this.noteCustody(); }, 250);
+        this.noteTimer.unref?.();
+    }
+    /** Note every running terminal's processes now, and keep doing so while any runs. */
+    noteCustody() {
+        const live = [...this.sessions.values()].filter(one => one.endedAt === null);
+        if (live.length > 0) {
+            const table = this.processes();
+            if (table !== null)
+                for (const session of live)
+                    for (const [pid, started] of membersOf(table, session))
+                        session.known.set(pid, started);
+        }
+        if (live.length > 0 && this.custodyTimer === null) {
+            this.custodyTimer = setInterval(() => this.noteCustody(), CUSTODY_REFRESH_MS);
+            this.custodyTimer.unref?.();
+        }
+        else if (live.length === 0 && this.custodyTimer !== null) {
+            clearInterval(this.custodyTimer);
+            this.custodyTimer = null;
+        }
+    }
+    /**
+     * End the program and everything that is its own: SIGHUP to every member (an interactive shell gives each job its own
+     * process group, so the leader's group is not enough), then SIGKILL, re-reading the process table each time so a
+     * child started during the close is caught too. Membership is the leader's descendants, every process with this
+     * terminal as its controlling terminal (started before the program ended), and every one noted while it ran, by pid
+     * and start time. A process that detached itself from the terminal AND its parents before it was noted is not seen —
+     * the same as any terminal. Resolves when the sweep is done; never waits without bound.
+     */
+    close(id, by = "owner") {
+        const session = this.sessions.get(id);
+        if (session === undefined)
+            return Promise.resolve();
+        if (session.closing !== null)
+            return session.closing;
+        session.endedBy = by;
+        this.options.record?.("close", this.summary(session));
+        session.closing = this.sweep(session);
+        return session.closing;
+    }
+    async sweep(session) {
+        const grace = this.options.closeGraceMs ?? CLOSE_GRACE_MS;
+        const pause = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+        const leaderGone = () => session.pty === null;
+        let readable = true;
+        const members = () => {
+            const table = this.processes();
+            if (table === null) {
+                readable = false;
+                return new Map();
+            }
+            const found = membersOf(table, session);
+            for (const [pid, started] of found)
+                session.known.set(pid, started);
+            return found;
+        };
+        const signal = (found, name) => {
+            if (!leaderGone()) {
+                try {
+                    process.kill(-session.leader, name);
+                }
+                catch { /* gone */ }
+                try {
+                    session.pty?.kill(name);
+                }
+                catch { /* gone */ }
+            }
+            for (const pid of found.keys()) {
+                try {
+                    process.kill(pid, name);
+                }
+                catch { /* gone */ }
+            }
+        };
+        let cleanup = "uncertain";
+        try {
+            if (process.platform === "win32") {
+                try {
+                    session.pty?.kill();
+                }
+                catch { /* gone */ }
+                await Promise.race([session.exited, pause(grace)]);
+                cleanup = leaderGone() ? "clean" : "uncertain";
+                return;
+            }
+            signal(members(), "SIGHUP");
+            for (const deadline = Date.now() + grace; Date.now() < deadline;) {
+                await pause(100);
+                if (leaderGone() && members().size === 0 && readable) {
+                    cleanup = "clean";
+                    return;
+                }
+            }
+            for (let round = 0; round < 20; round += 1) {
+                const found = members();
+                if (!readable)
+                    return;
+                if (found.size === 0 && leaderGone()) {
+                    cleanup = "clean";
+                    return;
+                }
+                signal(found, "SIGKILL");
+                await pause(100);
+            }
+        }
+        finally {
+            // The leader's exit is waited for, but never without bound.
+            await Promise.race([session.exited, pause(1_000)]);
+            // Proven members gone is not enough to free the worktree: nothing of this user may still be working in it.
+            if (cleanup === "clean") {
+                const table = this.processes();
+                const residents = table === null ? null : (this.options.residents ?? worktreeResidents)(table, session.worktreeReal, session.startedMs);
+                if (residents === null || residents.size > 0) {
+                    cleanup = "uncertain";
+                    session.residentsOnly = residents !== null;
+                    // Who was there, by pid and start time: removal waits for each to exit, not merely to leave the folder.
+                    for (const pid of residents ?? []) {
+                        const row = table.get(pid);
+                        if (row !== undefined)
+                            session.residentsSeen.set(pid, row.started);
+                    }
+                }
+            }
+            session.cleanup = readable && leaderGone() ? cleanup : "uncertain";
+            if (session.endedAt === null)
+                session.endedAt = this.clock().toISOString();
+            this.ledger.release(session.id, session.cleanup);
+            this.noteCustody();
+        }
+    }
+    /** Drop an ended session and its worktree (the branch stays: the work is there). Only after a clean sweep. */
+    async remove(id) {
+        const session = this.sessions.get(id);
+        if (session === undefined)
+            return;
+        if (session.pty !== null)
+            throw new TerminalError("Close the terminal before removing it.");
+        if (session.closing !== null)
+            await session.closing;
+        const busy = new TerminalError("Something may still be running in this terminal's worktree, so the worktree stays. Stop it (or leave the folder), then remove the worktree with `git worktree remove`.");
+        // Uncertain only because someone else was working in the worktree: it may go once they have left (checked below).
+        if (session.cleanup !== "clean" && !session.residentsOnly)
+            throw busy;
+        // Checked again now: a shell or server may have moved into the worktree since the sweep.
+        const table = this.processes();
+        const residents = table === null ? null : (this.options.residents ?? worktreeResidents)(table, session.worktreeReal, session.startedMs);
+        if (residents === null || residents.size > 0)
+            throw busy;
+        // Each process seen working in it when the sweep ended must have exited (the same pid with the same start time is
+        // the same process, wherever it now works).
+        if ([...session.residentsSeen].some(([pid, started]) => table.get(pid)?.started === started))
+            throw busy;
+        this.sessions.delete(id);
+        this.ledger.forget(id);
+        for (const viewer of session.viewers) {
+            try {
+                viewer.control({ t: "exit", code: session.exit?.code ?? null, signal: session.exit?.signal ?? null });
+            }
+            catch { /* gone */ }
+        }
+        session.viewers.clear();
+        const result = await (this.options.git ?? teardownGit())(session.repo, ["worktree", "remove", "--force", "--", session.worktree]);
+        this.options.record?.("remove", this.summary(session));
+        if (result.code !== 0 && existsSync(session.worktree)) {
+            const why = refusal(result);
+            throw new TerminalError(`The terminal is gone, but its worktree stays${why === null ? "" : ` (${why})`}. Remove it with \`git worktree remove\`.`);
+        }
+    }
+    /** Whether new sessions may start (false once the console is stopping). */
+    get admitting() { return !this.stopped; }
+    /**
+     * The console is stopping: admit nothing more, end every program, and wait (each sweep is bounded) for them.
+     * `clean` is false when any terminal's processes couldn't be proved gone.
+     */
+    async stop() {
+        this.stopped = true;
+        await Promise.all([...this.sessions.keys()].map(id => this.close(id, "console")));
+        if (this.custodyTimer !== null) {
+            clearInterval(this.custodyTimer);
+            this.custodyTimer = null;
+        }
+        if (this.noteTimer !== null) {
+            clearTimeout(this.noteTimer);
+            this.noteTimer = null;
+        }
+        return { clean: [...this.sessions.values()].every(one => one.cleanup === "clean") };
+    }
+}
+/** Every process from `ps` (macOS and Linux take these options); null when it can't be read, never an empty guess. */
+export function readProcessTable() {
+    let text;
+    try {
+        text = execFileSync("ps", ["-A", "-o", "pid=,ppid=,uid=,tty=,lstart="], { encoding: "utf8", timeout: 2_000, maxBuffer: 8 * 1024 * 1024 });
+    }
+    catch {
+        return null;
+    }
+    const table = new Map();
+    for (const line of text.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        // uid -2 is macOS's "nobody".
+        const match = /^\s*(\d+)\s+(\d+)\s+(-?\d+)\s+(\S+)\s+(.+?)\s*$/.exec(line);
+        if (match === null)
+            return null;
+        table.set(Number(match[1]), { ppid: Number(match[2]), uid: Number(match[3]), tty: match[4], started: match[5] });
+    }
+    return table.size === 0 ? null : table;
+}
+/**
+ * A terminal's processes in this table, by pid and start time: what was noted while it ran (still the same process),
+ * the leader, everything whose controlling terminal is its terminal and that started before it ended (a later process
+ * on a reused device is someone else's), and every descendant of those. Never this console itself.
+ */
+export function membersOf(table, session) {
+    const found = new Map();
+    const startedMs = (started) => Date.parse(started);
+    for (const [pid, row] of table) {
+        if (pid === process.pid || pid <= 1)
+            continue;
+        const noted = session.known.get(pid);
+        const ownTty = session.tty !== null && row.tty === session.tty && (session.exitedAt === null || startedMs(row.started) <= session.exitedAt + 1_000);
+        // The leader by pid only while it runs: after it exits its pid may be someone else's (it is noted by start time).
+        if (noted === row.started || (pid === session.leader && session.exitedAt === null) || ownTty)
+            found.set(pid, row.started);
+    }
+    for (let grew = true; grew;) {
+        grew = false;
+        for (const [pid, row] of table)
+            if (!found.has(pid) && pid !== process.pid && found.has(row.ppid)) {
+                found.set(pid, row.started);
+                grew = true;
+            }
+    }
+    return found;
+}
+/**
+ * Each listed process's working directory (Linux: /proc; macOS: lsof), and which ones couldn't be read (a setgid
+ * helper such as ssh-agent is unreadable even to its own user). Null when the lookup itself failed: a timeout, a signal
+ * or partial output is never a smaller answer. A process gone in between is simply absent.
+ */
+export function cwdsOf(pids) {
+    const cwds = new Map(), unreadable = [];
+    if (pids.length === 0)
+        return { cwds, unreadable };
+    if (process.platform === "linux") {
+        for (const pid of pids) {
+            try {
+                cwds.set(pid, readlinkSync(`/proc/${pid}/cwd`));
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === "EACCES" || code === "EPERM")
+                    unreadable.push(pid);
+                else if (code !== "ENOENT")
+                    return null;
+            }
+        }
+        return { cwds, unreadable };
+    }
+    let text;
+    try {
+        text = execFileSync("lsof", ["-a", "-d", "cwd", "-Fpn", "-p", pids.join(",")], { encoding: "utf8", timeout: 10_000, maxBuffer: 16 * 1024 * 1024 });
+    }
+    catch (error) {
+        // lsof exits 1 (and nothing else) when some listed process is gone; a timeout or a signal is unreadable.
+        const failure = error;
+        if (failure.status !== 1 || failure.signal != null || failure.code === "ETIMEDOUT" || typeof failure.stdout !== "string")
+            return null;
+        text = failure.stdout;
+    }
+    let pid = null;
+    for (const line of text.split("\n")) {
+        if (line.startsWith("p"))
+            pid = Number(line.slice(1));
+        else if (line.startsWith("n") && pid !== null)
+            cwds.set(pid, line.slice(1));
+    }
+    return { cwds, unreadable };
+}
+/**
+ * This user's processes working inside a terminal's worktree, whoever started them. They are never signalled (one may
+ * be the person's own shell or a server they started from elsewhere); while any remains, the terminal's cleanup is
+ * uncertain and its worktree stays. Null when that can't be known: the lookup failed, or a process whose working
+ * directory can't be read started after the terminal did (one from before — a login's ssh-agent — can't be its own).
+ */
+export function worktreeResidents(table, worktreeReal, terminalStartedMs = 0) {
+    const uid = process.getuid?.() ?? -1;
+    const candidates = [...table].filter(([pid, row]) => pid !== process.pid && row.uid === uid).map(([pid]) => pid);
+    const read = cwdsOf(candidates);
+    if (read === null)
+        return null;
+    if (read.unreadable.some(pid => { const started = table.get(pid)?.started; return started === undefined || !(Date.parse(started) < terminalStartedMs - 1_000); }))
+        return null;
+    return new Set([...read.cwds].filter(([, cwd]) => cwd === worktreeReal || cwd.startsWith(`${worktreeReal}/`)).map(([pid]) => pid));
+}
+export const MAX_FRAME_BYTES = 64 * 1024;
+export function parseTerminalFrame(text) {
+    if (Buffer.byteLength(text) > MAX_FRAME_BYTES)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const frame = value;
+    const keys = Object.keys(frame).sort().join(",");
+    if (frame["t"] === "in" && keys === "d,t" && typeof frame["d"] === "string")
+        return { t: "in", d: frame["d"] };
+    if (frame["t"] === "resize" && keys === "cols,rows,t") {
+        const cols = frame["cols"], rows = frame["rows"];
+        if (Number.isSafeInteger(cols) && Number.isSafeInteger(rows) && cols >= COLS.min && cols <= COLS.max && rows >= ROWS.min && rows <= ROWS.max) {
+            return { t: "resize", cols: cols, rows: rows };
+        }
+    }
+    return null;
+}