teapot-coding-agent 0.37.59 → 0.37.61

package/dist/server/image-resize.js

@@ -1,45 +1,14 @@
-/**
- * Downscale an uploaded background image with a NATIVE binary, if one exists.
- *
- * ## Why this is not done in the browser
- *
- * A wallpaper is displayed with `background-size: cover` at the window's size — a 6000x4000 phone
- * photo is never shown at more than ~2000x1200, but the browser still decodes the full thing and
- * keeps it decoded. Reported as "背景画像が大きいとブラウザがリサイズでかなり重くなっちゃう".
- * Resizing once on the server costs a few hundred milliseconds at upload and makes every later
- * repaint cheap.
- *
- * `ffmpeg.wasm` would avoid the external dependency at the cost of tens of MB of wasm to do work
- * that a native binary does in one call. So: use whatever native tool is present, and when none
- * is, keep the original. A missing optimiser must never fail an upload — the image still works,
- * it is just as heavy as before.
- *
- * ## Why execFile and not a shell
- *
- * The source path is derived from a server-generated `randomUUID`, but it still reaches a `-i`
- * argument, so arguments are passed as an ARRAY with no shell in between. Nothing about an
- * uploaded file can be read as a flag or a command.
- */
 import { execFile } from "node:child_process";
 import { existsSync, promises as fs } from "node:fs";
 import path from "node:path";
 import { promisify } from "node:util";
 const run = promisify(execFile);
-/** long edge, in pixels. Deliberately above any realistic window: `cover` on a 4K display at
- *  devicePixelRatio 2 still lands near this, so this is a quality floor, not a UX cap. */
 export const MAX_EDGE = 2560;
 const CANDIDATES = [
-    // ffmpeg first: it is the one most likely to be on a machine that has neither imagemagick nor
-    // a package manager, and `-vf scale` is a single pass.
     { name: "ffmpeg", kind: "ffmpeg", probe: ["-version"] },
     { name: "magick", kind: "magick", probe: ["-version"] },
-    // ImageMagick 6 ships `convert` only; same invocation, different binary name
     { name: "convert", kind: "convert", probe: ["-version"] },
 ];
-/**
- * Which image tools exist? Probing runs them, so the answer is what actually works here rather
- * than what a PATH scan suggests — a broken symlink or a stub shim is not a usable optimiser.
- */
 export async function detectImageTools() {
     const found = [];
     let tool = null;
@@ -53,35 +22,19 @@ export async function detectImageTools() {
             present = false;
         }
         found.push({ name: c.name, present });
-        // `convert` is a common name for unrelated programs; only take it after the two specific
-        // ones, which is what the CANDIDATES order already does.
         if (present && !tool)
             tool = { name: c.name, kind: c.kind };
     }
     return { tool, found };
 }
-/**
- * build the argv for a downscale into `out`.
- *
- * `width` is the LONG EDGE to fit within — the same meaning as `srcset`'s `w` descriptors, which
- * is what lets the client's chosen width be honoured directly.
- */
 export function resizeArgs(tool, src, out, width = MAX_EDGE) {
     const scale = `scale='min(${width},iw)':'min(${width},ih)':force_original_aspect_ratio=decrease`;
     if (tool.kind === "ffmpeg") {
-        // `-y` overwrite, `-frames:v 1` in case the input is an animated GIF (we want a still)
         return ["-y", "-loglevel", "error", "-i", src, "-vf", scale, "-frames:v", "1", out];
     }
-    const geometry = `${width}x${width}>`; // only shrink, never enlarge
+    const geometry = `${width}x${width}>`;
     return [`${src}[0]`, "-resize", geometry, "-strip", out];
 }
-/**
- * Downscale `src` into `out`. Returns whether it did anything, and never throws.
- *
- * "Did nothing" is a normal outcome: no tool installed, an image already small enough, or a tool
- * that failed on this particular file. The caller keeps the original in every one of those cases,
- * so an upload is never lost to an optimiser problem.
- */
 export async function downscaleImage(src, out, tool, width = MAX_EDGE) {
     if (!tool)
         return { resized: false, reason: "no image tool installed" };
@@ -101,32 +54,16 @@ export async function downscaleImage(src, out, tool, width = MAX_EDGE) {
     if (!existsSync(out))
         return { resized: false, reason: `${tool.name} produced no output` };
     const bytesAfter = (await fs.stat(out)).size;
-    /**
-     * Keep whichever is SMALLER, and delete the other.
-     *
-     * A re-encode can GROW a file — an already-optimised WebP fed through a lossy JPEG encoder is
-     * the usual way. Shipping the larger of the two would be strictly worse in both transfer and
-     * decode, so the comparison decides and the loser is removed.
-     */
     if (bytesAfter >= bytesBefore) {
         await fs.rm(out, { force: true }).catch(() => { });
         return { resized: false, reason: "re-encode was not smaller", bytesBefore, bytesAfter };
     }
     return { resized: true, bytesBefore, bytesAfter };
 }
-/** the scaled filename for an asset: same stem, `-w` suffix, same extension */
 export function scaledName(name) {
     const ext = path.extname(name);
     return `${path.basename(name, ext)}-w${ext}`;
 }
-/**
- * The cached filename for a specific width: `<stem>-w<width>.<ext>`.
- *
- * Kept within `assetName()`'s grammar (`[a-f0-9]{32}\.(ext)`) is NOT possible with a width in the
- * name, so these derived files are never served through `/api/assets/:name` directly — they are
- * read internally and their bytes returned. That is deliberate: the public route only accepts the
- * 32-hex form, so a derived name can never be requested as if it were an original.
- */
 export function widthName(name, width) {
     const ext = path.extname(name);
     return `${path.basename(name, ext)}-w${width}${ext}`;

package/dist/server/term-size.js

@@ -1,106 +1,18 @@
-/**
- * Terminal resize plumbing for the web terminal (#20).
- *
- * A resize is a property of the TTY, not a command. `TermSizeTracker` decides
- * WHEN to apply one; `resolvePtySlave` finds the device to apply it TO.
- *
- * ## How the size is applied now
- *
- * `stty -F <pty-slave> rows R cols C` — an ioctl(TIOCSWINSZ) on the pty DEVICE.
- * Nothing is written to the child's stdin, so nothing can be typed into a
- * foreground program. MEASURED with `script -qec`:
- *
- *     stty -F /dev/pts/0 rows 55 cols 190
- *     readback:        55 190
- *     foreground trap: WINCH fired, no command text in the output stream
- *
- * which is the same mechanism VS Code (node-pty, native ioctl) and Alacritty
- * (owns the pty) use — neither ever issues `stty` as TEXT.
- *
- * Before this, the size was applied by WRITING `stty rows R cols C\n` into the
- * child's stdin. That is only safe when a shell is reading: when an interactive
- * program owns the tty (vim, less, a python REPL) stdin belongs to the PROGRAM,
- * so the line arrived as keystrokes and landed in the operator's document. With
- * the device ioctl that text is gone entirely, so the machinery here is only
- * about avoiding redundant syscalls on a drag — a debounce and a no-op skip.
- *
- * It used to ALSO defer while the child was producing output (`markBusy`). That
- * existed solely to make the text path rarer, and it became a bug once the ioctl
- * removed the hazard: a full-screen program redraws continuously, so the busy
- * window never expired and the resize never applied at all (#172 — "nanoとか
- * 開いたらリサイズ効いてない"). Deferring is now wrong for every path.
- *
- * ## Why the slave path has to be discovered
- *
- * `script` is spawned by us, so we hold a pipe to its stdin/stdout, not the pty
- * master. The pty slave it created is reachable as our CHILD's fd 0 on Linux
- * (/proc/<pid>/fd/0 → /dev/pts/N). Where that cannot be resolved — macOS has no
- * /proc — the caller falls back to the stdin write, so no platform loses resize;
- * it only loses the improvement.
- *
- * `TermSizeTracker` still:
- *   - debounces to the trailing edge of a drag (one ioctl per drag, not per pixel)
- *   - remembers the applied size and skips no-op resizes entirely
- *   - keys state by CHILD, not agent: one agent may hold up to 10 terminals,
- *     each with its own size and its own foreground program
- */
 import { readFileSync, readdirSync, readlinkSync } from "node:fs";
 import { spawn, spawnSync } from "node:child_process";
-/**
- * The pty slave device behind a child, or null when it cannot be determined.
- *
- * ## Why this walks to a GRANDCHILD
- *
- * The child we spawn is `script -qec <shell> /dev/null` with piped stdio (we must
- * read its output), so the child's OWN fd 0 is a PIPE, not the pty. `script`
- * creates the pty and forks the shell onto the slave, so the device we want is
- * fd 0 of one of its children. MEASURED on util-linux 2.42:
- *
- *     script  fd0 -> pipe:[…]      (our pipes)
- *     script  fd3 -> /dev/ptmx     (the master)
- *     script  fd4 -> /dev/pts/0    (the slave, but script's own fd)
- *     shell   fd0 -> /dev/pts/0    (the shell's controlling tty — what we want)
- *
- * Any of `/dev/pts/N` found this way identifies the same pty, so the first match
- * wins. Returns null on any failure — non-Linux (no /proc), an exited child, the
- * plain-pipe fallback spawn where there is no pty at all — because a resize must
- * never throw out of a socket handler.
- */
 export function resolvePtySlave(child) {
     const pid = child?.pid;
     if (!pid)
         return null;
-    // the slave may sit on the spawned child or on ITS child (script forks the
-    // shell onto the pty), so try both before giving up
     for (const candidate of [pid, ...childrenOf(pid), ...childrenOf(pid).flatMap(childrenOf)]) {
         const found = ptySlaveOf(candidate);
         if (found)
             return found;
     }
-    // No /proc (macOS): ask `ps` which tty the child's descendants are on. This is what makes
-    // it safe to drop the old "type `stty` into stdin" fallback — that path put a command line
-    // into the terminal itself, so a foreground program (vim, less, a REPL) received it as
-    // KEYSTROKES and it landed in the operator's buffer. A tty name from `ps` can be resized
-    // with `stty -F`, which emits nothing into the stream.
     return ptySlaveViaPs(pid);
 }
-/**
- * The controlling tty of `pid` or any descendant, via `ps` (for hosts without /proc).
- *
- * `ps -o tty=` prints "ttys003" or "pts/3"; both name a device under /dev. A process with no
- * controlling terminal prints "??" (Linux) or "-", and those are skipped.
- */
 function ptySlaveViaPs(pid) {
     try {
-        /**
-         * Only the child's OWN tty, never one inherited from our process.
-         *
-         * `ps -o tty=` reports the CONTROLLING terminal, which a plain-pipe child still inherits
-         * from whoever started the server — so naively taking it returns the tty of the shell that
-         * launched teapot, and a resize would then ioctl THAT. Measured: a piped `/bin/sh` "resolved"
-         * to the test runner's own tty. So require that the process has a tty which is NOT ours and
-         * NOT our parent's, or report nothing.
-         */
         const self = process.pid;
         const out = spawnSync("ps", ["-e", "-o", "pid=,ppid=,tty="], { encoding: "utf8" }).stdout ?? "";
         const rows = out
@@ -109,7 +21,6 @@ function ptySlaveViaPs(pid) {
             .filter((c) => c.length >= 3 && Number.isInteger(Number(c[0])))
             .map((c) => ({ pid: Number(c[0]), ppid: Number(c[1]), tty: c[2] }));
         const ttyOf = (p) => rows.find((r) => r.pid === p)?.tty;
-        // the tty we and our own shell are on is inherited by children and proves nothing
         const inherited = new Set([ttyOf(self), ttyOf(process.ppid)].filter(Boolean));
         const seen = new Set();
         const stack = [pid];
@@ -132,7 +43,6 @@ function ptySlaveViaPs(pid) {
         return null;
     }
 }
-/** pids whose parent is `pid` (empty on a host without /proc) */
 function childrenOf(pid) {
     try {
         return readFileSync(`/proc/${pid}/task/${pid}/children`, "utf8")
@@ -145,7 +55,6 @@ function childrenOf(pid) {
         return [];
     }
 }
-/** `/dev/pts/N` behind any fd of `pid`, or null */
 function ptySlaveOf(pid) {
     try {
         for (const fd of readdirSync(`/proc/${pid}/fd`)) {
@@ -154,27 +63,19 @@ function ptySlaveOf(pid) {
                 target = readlinkSync(`/proc/${pid}/fd/${fd}`);
             }
             catch {
-                continue; // fd closed between readdir and readlink — normal
+                continue;
             }
-            // only a real pty device: a pipe readlinks as `pipe:[123]` and an anon
-            // inode as `anon_inode:[…]`, neither of which accepts TIOCSWINSZ
             if (target.startsWith("/dev/pts/"))
                 return target;
         }
     }
     catch {
-        /* process gone, or no /proc (macOS) */
     }
     return null;
 }
-/** debounce window: long enough to collapse a drag, short enough to feel instant */
 export const TERM_RESIZE_DEBOUNCE_MS = 250;
 export class TermSizeTracker {
     states = new Map();
-    /**
-     * Request a resize; the sink write happens on the trailing edge of the
-     * debounce.
-     */
     request(child, rows, cols, write) {
         const st = this.states.get(child) ?? { rows: 0, cols: 0, timer: null };
         this.states.set(child, st);
@@ -182,7 +83,6 @@ export class TermSizeTracker {
             clearTimeout(st.timer);
             st.timer = null;
         }
-        // already the applied size → nothing a shell could act on
         if (st.rows === rows && st.cols === cols)
             return;
         const apply = () => {
@@ -193,24 +93,20 @@ export class TermSizeTracker {
                 write(rows, cols);
             }
             catch {
-                /* child exited mid-debounce */
             }
         };
         st.timer = setTimeout(apply, TERM_RESIZE_DEBOUNCE_MS);
     }
-    /** forget a child; cancels its pending resize so we can't write to a corpse */
     forget(child) {
         const st = this.states.get(child);
         if (st?.timer)
             clearTimeout(st.timer);
         this.states.delete(child);
     }
-    /** test/diagnostic: the size currently applied for a child */
     applied(child) {
         const st = this.states.get(child);
         return st ? { rows: st.rows, cols: st.cols } : null;
     }
-    /** test: cancel everything (keeps suites from leaking timers) */
     disposeAll() {
         for (const st of this.states.values())
             if (st.timer)
@@ -218,21 +114,6 @@ export class TermSizeTracker {
         this.states.clear();
     }
 }
-/**
- * Apply a size to a child's pty — the ONLY way this codebase resizes a terminal.
- *
- * It shells out to `stty -F <slave>`, which is ioctl(TIOCSWINSZ) on the pty DEVICE. Nothing is
- * written to the child's stdin, so nothing can be typed into a foreground program.
- *
- * That distinction is the whole point (reported twice): writing `stty rows R cols C\n` into
- * stdin only works while a SHELL is reading it. When vim, less or a REPL owns the tty, the
- * PROGRAM reads, so the line arrives as KEYSTROKES and lands in the operator's document.
- *
- * When the slave cannot be resolved this does NOTHING. A resize that cannot be applied is
- * strictly better than one that types into somebody's buffer.
- *
- * `spawnFn` is injectable so a test can observe what would have been executed.
- */
 export function applyPtySize(child, rows, cols, spawnFn = spawn) {
     if (!child || rows <= 0 || cols <= 0)
         return false;

package/dist/server/terminals.js

@@ -1,68 +1,19 @@
-/**
- * Server-side terminals.
- *
- * ## Why this exists
- *
- * A terminal used to live entirely in one browser tab: the tab owned the list, the WebSocket
- * owned the pty, and `onClose` sent SIGHUP. So a reload destroyed the shells — reported as
- * "タブをリロードしたらターミナル消失したのがちょっと嬉しくない" — and two clients could never
- * see the same terminal.
- *
- * Now the SERVER owns them, keyed by an id, exactly as it owns agents: a terminal outlives any
- * one connection, several clients can attach to the same one, and a reload re-attaches and
- * replays what it missed.
- *
- * ## The three decisions that make sharing work
- *
- * 1. **A ring buffer of output.** A client that attaches late (a reload, a second window) needs
- *    the screen as it is NOW, not a raw byte stream from the beginning. The buffer keeps the
- *    last N bytes, which is enough to repaint a terminal after any realistic scrollback.
- * 2. **A disconnect is not a close.** `onClose` detaches; the pty keeps running. Only an
- *    explicit close (or the idle reaper) ends it — otherwise a reload would still kill the
- *    shell, just one step later.
- * 3. **One pty, many writers, last-resize-wins.** Input from any client is forwarded (that is
- *    what "shared" means); a resize takes the SMALLEST attached client's geometry, because a
- *    pty has one size and shrinking to the smallest keeps every viewer readable rather than
- *    letting one large window force horizontal scrolling on the others.
- */
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { toolShellFor } from "../agent/tools.js";
-/**
- * Which shell an interactive terminal should spawn.
- *
- * Exported so a test can call it: an earlier version of this rule lived inline in `open()`, and
- * the obvious unit test could only pin `toolShellFor`, which is shared with the `bash` tool — so
- * reverting THIS file to the buggy order left that test green. The rule has to be callable for
- * its own failure to be observable.
- *
- * Only the file name is taken from `toolShellFor` (a terminal is spawned with no `-c`, so the
- * args builder does not apply), but the "which shell" question is answered in one place so the
- * two cannot drift.
- */
 export function terminalShellFor(platform, env, exists = existsSync) {
     return toolShellFor(platform, env, exists).file;
 }
 let resizeFn = null;
 let slaveFn = null;
-/** wire the size applier once, at server construction */
 export function setTerminalResize(fn, slave) {
     resizeFn = fn;
     slaveFn = slave;
 }
-/**
- * The size a pty is seeded with before any client reports one.
- *
- * Only a placeholder: `script` starts the pty at 0x0, so the shell would print its first prompt
- * wrapped at zero columns. Chosen to be a plausible terminal so that prompt looks normal.
- */
 const SEED_ROWS = 30;
 const SEED_COLS = 100;
-/** keep this much recent output — enough for a full repaint after a reload */
 const BUFFER_BYTES = 200_000;
-/** how many terminals one agent may hold, matching the UI's 10-tab cap */
 const MAX_PER_AGENT = 10;
-/** an idle terminal with no client attached is reaped after this long */
 const IDLE_REAP_MS = 6 * 60 * 60_000;
 const terms = new Map();
 let seq = 0;
@@ -73,59 +24,22 @@ function emit(id, msg) {
             s(msg);
         }
         catch {
-            /* that client is gone; onClose will unsubscribe it */
         }
     }
 }
-/** append to the ring buffer, keeping the newest BUFFER_BYTES */
 function append(t, chunk) {
     t.buffer += chunk;
     if (t.buffer.length > BUFFER_BYTES)
         t.buffer = t.buffer.slice(-BUFFER_BYTES);
 }
-/**
- * Start a terminal in an agent's workspace.
- *
- * Returns `null` (with a reason) instead of throwing, so the HTTP layer can answer 400/409
- * rather than 500 — a refused request is not a server fault.
- */
 export function createTerminal(agentId, workspace, title) {
     const live = [...terms.values()].filter((t) => t.agentId === agentId && !t.exited);
     if (live.length >= MAX_PER_AGENT) {
         return { ok: false, error: `too many terminals for this agent (max ${MAX_PER_AGENT})` };
     }
-    /**
-     * The shell to run, per platform.
-     *
-     * `process.env.SHELL || "/bin/bash"` was the whole story, which on Windows spawns a path that
-     * does not exist — a terminal tab that opens and immediately dies, on a platform this package
-     * claims to support. Windows also has no `script` and no pty (see `hasScript` below), so it
-     * gets the plain-pipe path with `cmd.exe` (or `%COMSPEC%`), which is what the fallback branch
-     * was always for.
-     *
-     * `%TEAPOT_SHELL%` overrides on both platforms, so an operator who wants `pwsh` or a specific
-     * bash does not have to change their login shell.
-     */
-    /**
-     * The SAME choice the `bash` tool makes — deliberately shared, not re-derived.
-     *
-     * `$SHELL` used to be consulted before the platform check. On Windows that is a trap: Git
-     * Bash / MSYS / some CI images export `SHELL=/usr/bin/bash`, which `spawn()` cannot execute
-     * there, so the tab opened and died with ENOENT. MEASURED: `SHELL=/usr/bin/bash` with
-     * `COMSPEC=C:\Windows\system32\cmd.exe` resolved to `/usr/bin/bash` under the old chain.
-     *
-     * A terminal needs an INTERACTIVE shell (spawned with no `-c`), so only the file name is taken
-     * from `toolShellFor`; the two answer the "which shell" question in one place so a fix to one
-     * cannot leave the other broken.
-     */
     const shell = terminalShellFor(process.platform, process.env);
     const hasScript = process.platform !== "win32" && existsSync("/usr/bin/script");
-    // `script` reports a 0x0 winsize, so the shell falls back to these until a client resizes
     const env = { ...process.env, TERM: "xterm-256color", COLUMNS: "100", LINES: "30" };
-    // `detached` puts the pty provider and the shell it forks into their OWN process group, so
-    // closing the terminal can signal the GROUP. Signalling only `script` leaves the shell (and
-    // anything running inside it) alive and holding the pipes open — which kept a test file from
-    // exiting for a full minute after its work was done.
     const child = hasScript
         ? spawn("script", ["-qec", shell, "/dev/null"], { cwd: workspace, env, detached: true })
         : spawn(shell, [], { cwd: workspace, env: { ...env, TERM: "dumb" }, detached: true });
@@ -157,35 +71,10 @@ export function createTerminal(agentId, workspace, title) {
         t.code = code;
         emit(id, { kind: "exit", code });
     });
-    /**
-     * SEED the size.
-     *
-     * `script` gives the pty a 0x0 winsize, so a shell genuinely reports "0 0" and wraps at zero
-     * columns until something sets it. A client resize would, but the shell prints its prompt
-     * first — so the very first thing the operator sees is garbage wrapping. That is why the size
-     * is seeded here rather than waiting for the socket.
-     *
-     * The slave does not exist until `script` has forked, so poll briefly; `script` forks within a
-     * few ms and the fallback (no seed at all) is harmless if it never appears.
-     */
     const seed = (tries) => {
         if (t.exited)
             return;
         if (slaveFn?.(child)) {
-            /**
-             * Seed the size ONLY if no client has reported one yet (#172).
-             *
-             * MEASURED bug: "稼働中のnanoにリサイズが効かない、閉じて再度開けば効く". The seed runs at
-             * ~30ms, applying 30x100 to the pty. A client that had already attached and sent its real
-             * size lost that race — and because the seed went through the same tracker, the client's
-             * size was then deduped as "already applied" if it happened to equal the seed, or simply
-             * overwritten by it. The program opened at the seed's geometry and only a NEW size (which
-             * arrives when the tab is re-attached, i.e. "close and reopen nano") fixed it.
-             *
-             * The seed exists for one reason: `script` starts the pty at 0x0, so a shell prints its
-             * prompt wrapped at zero columns before any client speaks. Once a client HAS spoken, its
-             * size is the truth and seeding must stand down.
-             */
             if (t.sizes.size === 0)
                 resizeFn?.(child, SEED_ROWS, SEED_COLS);
             return;
@@ -206,21 +95,12 @@ function infoOf(t) {
         createdAt: t.createdAt,
     };
 }
-/** every live terminal, oldest first — the list the UI renders */
 export function listTerminals() {
     return [...terms.values()]
         .filter((t) => !t.exited)
         .sort((a, b) => a.createdAt - b.createdAt)
         .map(infoOf);
 }
-/**
- * Attach a client.
- *
- * The `replay` string is the buffered backlog, so the caller can paint the screen as it is now
- * before forwarding live output. Ordering matters: the sink is registered FIRST so nothing
- * produced between "snapshot the buffer" and "start forwarding" is lost; a duplicate line is
- * harmless, a missing one leaves the terminal visibly wrong.
- */
 export function attachTerminal(id, sink, size) {
     const t = terms.get(id);
     if (!t || t.exited)
@@ -237,7 +117,6 @@ export function attachTerminal(id, sink, size) {
     }
     return { ok: true, replay: t.buffer, terminal: infoOf(t) };
 }
-/** drop a client; the pty keeps running (a reload must not kill the shell) */
 export function detachTerminal(id, sink) {
     const set = sinks.get(id);
     if (!set)
@@ -246,15 +125,12 @@ export function detachTerminal(id, sink) {
     if (set.size === 0)
         sinks.delete(id);
 }
-/** one client's view of the size; the pty gets the SMALLEST of them */
 export function resizeTerminal(id, sink, rows, cols) {
     const t = terms.get(id);
     if (!t || t.exited)
         return;
     if (rows <= 0 || cols <= 0)
         return;
-    // keyed by the SINK: that is the per-client identity, so two windows can each report their
-    // own size without overwriting one another
     t.sizes.set(sink, { rows, cols });
     applySize(t);
 }
@@ -271,7 +147,6 @@ function applySize(t) {
         return;
     resizeFn?.(t.child, rows, cols);
 }
-/** close one terminal for good, reporting whether it existed */
 export function closeTerminal(id) {
     const t = terms.get(id);
     if (!t)
@@ -283,7 +158,6 @@ export function closeTerminal(id) {
     console.log(`[teapot] ⌨ terminal closed: ${id}`);
     return true;
 }
-/** close everything for one agent — used when the agent is archived or the master stops */
 export function closeTerminalsFor(agentId) {
     let n = 0;
     for (const t of [...terms.values()]) {
@@ -292,7 +166,6 @@ export function closeTerminalsFor(agentId) {
     }
     return n;
 }
-/** close every terminal (harness shutdown / dispose) */
 export function closeAllTerminals() {
     let n = 0;
     for (const id of [...terms.keys()])
@@ -300,14 +173,6 @@ export function closeAllTerminals() {
             n++;
     return n;
 }
-/**
- * Reap terminals nobody has attached to for a long time.
- *
- * Without this, every abandoned tab keeps a shell alive for the life of the process: the whole
- * point of making terminals outlive a disconnect is that a reload re-attaches, but a closed tab
- * never will. The window is deliberately long (6h) — a terminal is the operator's workspace,
- * and reaping one they meant to come back to is much worse than holding a sleeping pty.
- */
 export function reapIdleTerminals(now = Date.now()) {
     let n = 0;
     for (const t of [...terms.values()]) {
@@ -321,14 +186,6 @@ export function reapIdleTerminals(now = Date.now()) {
     }
     return n;
 }
-/** test seam: forget everything without touching processes */
-/**
- * Signal the whole pty process group, not just `script`.
- *
- * `script` execs/forks the shell onto the pty; killing only the process we spawned orphans the
- * shell, which then keeps running with nobody attached and keeps the parent's pipes open. The
- * group is negative-pid, which is why the spawn is `detached`.
- */
 function killGroup(t) {
     const pid = t.child.pid;
     const signal = (sig) => {
@@ -343,19 +200,10 @@ function killGroup(t) {
                 t.child.kill(sig);
             }
             catch {
-                /* already gone */
             }
         }
     };
     signal("SIGHUP");
-    /**
-     * SIGHUP alone is not enough to release the pty.
-     *
-     * `script` holds the pty MASTER open; while it does, this process cannot exit because its
-     * pipes are still attached — measured as a test file sitting idle for a full minute after
-     * its work was done. Escalating to SIGKILL after a short grace is what actually reaps it.
-     * `unref` on the timer keeps this from being a reason to stay alive itself.
-     */
     const t2 = setTimeout(() => signal("SIGKILL"), 300);
     t2.unref?.();
 }
@@ -366,7 +214,6 @@ export function _resetTerminalsForTest() {
     sinks.clear();
     seq = 0;
 }
-/** forward keystrokes to a terminal; a dead pty simply drops them */
 export function writeTerminal(id, data) {
     const t = terms.get(id);
     if (!t || t.exited)
@@ -381,12 +228,6 @@ export function writeTerminal(id, data) {
         return false;
     }
 }
-/**
- * Stop letting one client's window size constrain the pty.
- *
- * A detaching client must be forgotten, or its (now stale) small geometry would keep forcing
- * every remaining attached client into a narrow pty forever.
- */
 export function forgetTerminalSize(id, sink) {
     const t = terms.get(id);
     if (!t)