toolroll 0.9.104 → 0.9.105

package/dist/live-terminal.js

@@ -1,11 +1,3 @@
-/**
- * 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";
@@ -15,26 +7,15 @@ import { codingEnvironment } from "./coding-provider.js";
 import { teardownGit, refusal } from "./teardown-git.js";
 import { sleep } from "./sleep.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;
-/** 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))
@@ -47,7 +28,6 @@ export function pendingInputOf(pty) {
     }
     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");
@@ -69,15 +49,8 @@ export function loadPtySpawn() {
         return null;
     }
 }
-/** How many lines above the screen a terminal keeps for a page that attaches later. */
 export const SCREEN_SCROLLBACK_LINES = 5000;
 const require = createRequire(import.meta.url);
-/**
- * The terminal as a page would see it now: every byte the program writes is parsed by a headless xterm here, so a page
- * that attaches later gets the screen, its scrollback and its modes (the alternate screen of a full-screen program, the
- * cursor, colours, bracketed paste, mouse reporting) — never a replay of raw output cut at an arbitrary byte, which
- * could split an escape sequence or redraw a full-screen program garbled.
- */
 export class ScreenMirror {
     lines;
     terminal;
@@ -94,8 +67,7 @@ export class ScreenMirror {
     resize(cols, rows) { try {
         this.terminal.resize(cols, rows);
     }
-    catch { /* sizes are clamped before this */ } }
-    /** The screen as of this call (after everything written before it), handed to `done` once parsed. */
+    catch { } }
     snapshot(done) {
         this.terminal.write("", () => { let screen = ""; try {
             screen = this.serializer.serialize({ scrollback: this.lines });
@@ -107,14 +79,13 @@ export class ScreenMirror {
     dispose() { try {
         this.terminal.dispose();
     }
-    catch { /* already */ } }
+    catch { } }
 }
 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;
@@ -128,7 +99,7 @@ export function onPath(name, env = process.env) {
                 if (statSync(path).isFile())
                     return path;
             }
-            catch { /* not here */ }
+            catch { }
         }
     }
     return null;
@@ -165,7 +136,6 @@ export class TerminalHost {
         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();
     }
@@ -176,10 +146,6 @@ export class TerminalHost {
     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.");
@@ -194,7 +160,6 @@ export class TerminalHost {
         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 {
@@ -237,7 +202,6 @@ export class TerminalHost {
                 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)}`);
@@ -258,7 +222,7 @@ export class TerminalHost {
                     try {
                         viewer.output(chunk);
                     }
-                    catch { /* the viewer's own close handles it */ }
+                    catch { }
                 }
             });
             pty.onExit(({ exitCode, signal }) => {
@@ -270,11 +234,10 @@ export class TerminalHost {
                     try {
                         viewer.control({ t: "exit", code: session.exit.code, signal: session.exit.signal });
                     }
-                    catch { /* gone */ }
+                    catch { }
                 }
                 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);
             });
@@ -287,10 +250,6 @@ export class TerminalHost {
                 this.ledger.release(id, null);
         }
     }
-    /**
-     * Attach a page: it gets the screen as it is now (ScreenMirror), then `hello`, then live output — what the program
-     * writes meanwhile is held and sent after the screen, in order. Returns its detach.
-     */
     attach(id, viewer) {
         const session = this.sessions.get(id);
         if (session === undefined)
@@ -326,15 +285,13 @@ export class TerminalHost {
                         viewer.control(one.control);
                 }
             }
-            catch { /* the viewer's own close handles it */ }
+            catch { }
             held.length = 0;
             live = true;
         });
         return () => { session.viewers.delete(gate); };
     }
-    /** 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)
@@ -354,18 +311,16 @@ export class TerminalHost {
         try {
             session.pty.resize(session.cols, session.rows);
         }
-        catch { /* it exited between */ }
+        catch { }
         session.screen.resize(session.cols, session.rows);
     }
     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) {
@@ -384,16 +339,6 @@ export class TerminalHost {
             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 while the program runs, and every one noted while it ran, by pid and start
-     * time (membersOf). Each signal goes only to a process still that pid and start time; a process on the terminal after
-     * the program ended that was never noted, or a pid now someone else's, is never signalled and leaves the close
-     * uncertain. 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)
@@ -410,7 +355,6 @@ export class TerminalHost {
         const pause = sleep;
         const leaderGone = () => session.pty === null;
         let readable = true;
-        // Processes on its terminal after it ended that were never noted: maybe someone else's, never signalled.
         const ambiguous = new Set();
         const members = () => {
             const table = this.processes();
@@ -423,11 +367,6 @@ export class TerminalHost {
                 session.known.set(pid, started);
             return found;
         };
-        // Each signal goes only to the process it was meant for: the table is read again right before, and a pid whose
-        // start time is no longer the one recorded (gone, or a pid used again) is skipped, and the close is uncertain. The
-        // leader's group only while it runs: its pid is our unreaped child until the pty reports its exit, and, where the
-        // table reads, still the leader that started. A table that can't be read signals the leader alone (the close is
-        // uncertain then anyway).
         const signal = (found, name) => {
             const table = this.processes();
             if (table === null)
@@ -437,11 +376,11 @@ export class TerminalHost {
                 try {
                     process.kill(-session.leader, name);
                 }
-                catch { /* gone */ }
+                catch { }
                 try {
                     session.pty?.kill(name);
                 }
-                catch { /* gone */ }
+                catch { }
             }
             if (table === null)
                 return;
@@ -456,7 +395,7 @@ export class TerminalHost {
                 try {
                     process.kill(pid, name);
                 }
-                catch { /* gone */ }
+                catch { }
             }
         };
         let cleanup = "uncertain";
@@ -465,7 +404,7 @@ export class TerminalHost {
                 try {
                     session.pty?.kill();
                 }
-                catch { /* gone */ }
+                catch { }
                 await Promise.race([session.exited, pause(grace)]);
                 cleanup = leaderGone() ? "clean" : "uncertain";
                 return;
@@ -486,9 +425,6 @@ export class TerminalHost {
                     cleanup = "clean";
                     return;
                 }
-                // Stopped first, then read again until nothing new appears: a stopped process can't fork, so a child one started
-                // just before it stopped is still its descendant here and is killed with it. Killed while running, a parent can
-                // fork between the read and the kill, and its child goes to launchd unnoted.
                 for (let settle = 0; settle < 5; settle += 1) {
                     signal(found, "SIGSTOP");
                     const again = members();
@@ -504,16 +440,13 @@ export class TerminalHost {
             }
         }
         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)
@@ -528,7 +461,6 @@ export class TerminalHost {
             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)
@@ -538,16 +470,12 @@ export class TerminalHost {
         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);
@@ -556,7 +484,7 @@ export class TerminalHost {
             try {
                 viewer.control({ t: "exit", code: session.exit?.code ?? null, signal: session.exit?.signal ?? null });
             }
-            catch { /* gone */ }
+            catch { }
         }
         session.viewers.clear();
         session.screen.dispose();
@@ -567,12 +495,7 @@ export class TerminalHost {
             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")));
@@ -587,7 +510,6 @@ export class TerminalHost {
         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 {
@@ -600,7 +522,6 @@ export function readProcessTable() {
     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;
@@ -608,13 +529,6 @@ export function readProcessTable() {
     }
     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 while it runs, everything whose controlling terminal is its terminal while it runs, and every descendant
- * of those. Never this console itself. Once the program has ended its terminal's name is no one's proof: the device
- * may already be someone else's, so a process on it that wasn't noted is not a member; it goes in `ambiguous` (when
- * given), and the close that meets one says it is uncertain rather than signal it.
- */
 export function membersOf(table, session, ambiguous) {
     const found = new Map();
     const live = session.exitedAt === null;
@@ -623,7 +537,6 @@ export function membersOf(table, session, ambiguous) {
         if (pid === process.pid || pid <= 1)
             continue;
         const noted = session.known.get(pid);
-        // 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 && live) || (live && onTerminal(row.tty)))
             found.set(pid, row.started);
     }
@@ -641,11 +554,6 @@ export function membersOf(table, session, ambiguous) {
                 ambiguous.add(pid);
     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)
@@ -670,7 +578,6 @@ export function cwdsOf(pids) {
         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;
@@ -685,12 +592,6 @@ export function cwdsOf(pids) {
     }
     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);