@timqi/pier 0.0.4 → 0.0.6

package/dist/web/public/index.html

@@ -16,8 +16,8 @@
   <meta name="apple-mobile-web-app-capable" content="yes" />
   <meta name="apple-mobile-web-app-title" content="Pier" />
   <title>Pier</title>
-  <script type="module" crossorigin src="/assets/index-B3MvJUJP.js"></script>
-  <link rel="stylesheet" crossorigin href="/assets/index-CwBoxtXP.css">
+  <script type="module" crossorigin src="/assets/index-QPYgeBhQ.js"></script>
+  <link rel="stylesheet" crossorigin href="/assets/index-BUNGxtMe.css">
 </head>
 <!-- The document never scrolls: this is a fixed-viewport workbench, and every
      scrollable region is an inner pane. h-dvh, not h-screen, because 100vh can
@@ -90,6 +90,13 @@
           <path d="M8 5.5v5M5.5 8h5" stroke-linecap="round" />
         </svg>
       </button>
+      <button type="button" id="open-terminal"
+        class="icon-btn" aria-label="Terminal">
+        <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" class="h-3.5 w-3.5">
+          <rect x="2.25" y="2.25" width="11.5" height="11.5" rx="2.5" />
+          <path d="M4.75 5.75 7 8l-2.25 2.25M8.25 10.75h3" stroke-linecap="round" stroke-linejoin="round" />
+        </svg>
+      </button>
     </div>
     <div id="project-tree" class="flex-1 overflow-y-auto text-[13.5px]"></div>
   </aside>
@@ -113,6 +120,7 @@
     <section id="boards-view" class="hidden min-h-0 flex-1 flex-col"></section>
     <section id="settings-view" class="hidden min-h-0 flex-1 flex-col"></section>
     <section id="files-view" class="hidden min-h-0 flex-1 flex-col"></section>
+    <section id="terminal-view" class="hidden min-h-0 flex-1 flex-col"></section>
     <header id="chat-header" class="flex h-10 flex-none items-center gap-2 border-b border-neutral-200 px-4 max-md:hidden">
       <span id="chat-title" class="truncate font-medium"></span>
       <!-- Right cluster: meta chips sit flush against the ⋯ button. Two

package/dist/web/server.js

@@ -6,6 +6,7 @@ import { join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { Hono } from "hono";
+import { compress } from "hono/compress";
 import { streamSSE } from "hono/streaming";
 import { EventHub } from "../core/hub.js";
 import { logger } from "../log.js";
@@ -18,6 +19,12 @@ import { MAX_INBOUND_BYTES } from "../core/inbound-file.js";
 import { registerInstanceRoutes } from "./instance.js";
 import { registerProviderRoutes } from "./providers.js";
 const log = logger("web");
+/** A transcript without the bytes nobody has asked to see yet. A step's `args`
+ *  and `output` are ~90% of a long session's snapshot and sit inside a
+ *  collapsed group; the client fetches one turn's worth when it is opened. */
+const slim = (turn) => turn.steps
+    ? { ...turn, steps: turn.steps.map(({ args: _args, output: _output, ...step }) => step) }
+    : turn;
 /** What goes in front of `Pier` in the tab: `$PIER_TITLE`, then the machine.
  *  The label leads because a tab is narrow and "which instance is this" is the
  *  question it has to answer before the browser truncates — `staging - g1`. */
@@ -47,7 +54,7 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         }
         if (!runningNow.delete(e.sessionId))
             return;
-        state.set("unread", e.sessionId, true);
+        state.setUnread(e.sessionId, true);
         hub.emitWorkspace({ type: "sessions-changed" });
     });
     /** Background runs this session launched that are still in flight. */
@@ -58,21 +65,49 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     // only once the first assistant message lands. Merged into the list below
     // so every client sees a new session immediately; dropped once Pi lists it.
     const nascent = new Map();
+    // listAll parses every transcript. Concurrent consumers share that work,
+    // but the result is not retained: an explicit All-sessions open stays fresh.
+    let listing;
+    let projectBackfillNeeded = state.needsProjectBackfill();
+    const listSessions = () => listing ??= factory.list()
+        .then((rows) => {
+        state.remember(rows);
+        return rows;
+    })
+        .finally(() => {
+        listing = undefined;
+    });
+    const present = (s, pinned, unread) => ({
+        ...s,
+        state: router.stateOf(s.id) ?? "idle",
+        pinned,
+        unread,
+        activeRuns: activeRuns(s.id),
+    });
+    app.get("/api/projects", async (c) => {
+        // Existing databases have pin booleans but no summaries. Pay one legacy
+        // scan, fill those rows, then every later Projects read is SQLite-only.
+        if (projectBackfillNeeded) {
+            await listSessions();
+            // Do not retry on every request, and do not clear a pin whose transcript
+            // happened to be unreadable. A later explicit full listing can repair it.
+            projectBackfillNeeded = false;
+        }
+        return c.json(state.projects().map((s) => present(s, true, s.unread)));
+    });
     app.get("/api/sessions", async (c) => {
-        const sessions = await factory.list();
+        const sessions = await listSessions();
         for (const s of sessions)
             nascent.delete(s.id);
         // A session created but never prompted would otherwise be listed forever.
         for (const [id, n] of nascent)
             if (Date.now() - n.createdAt > 86_400_000)
                 nascent.delete(id);
-        return c.json([...[...nascent].map(([id, n]) => ({ id, ...n })), ...sessions].map((s) => ({
-            ...s,
-            state: router.stateOf(s.id) ?? "idle",
-            pinned: state.has("pinned", s.id),
-            unread: state.has("unread", s.id),
-            activeRuns: activeRuns(s.id),
-        })));
+        const flags = state.flags();
+        return c.json([...[...nascent].map(([id, n]) => ({ id, ...n })), ...sessions].map((s) => {
+            const row = flags.get(s.id);
+            return present(s, row?.pinned ?? false, row?.unread ?? false);
+        }));
     });
     app.post("/api/sessions", async (c) => {
         const body = await c.req.json().catch(() => ({}));
@@ -80,10 +115,11 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         if (typeof body.cwd !== "string" || !body.cwd)
             return c.json({ error: "cwd required" }, 400);
         const session = await factory.create({ cwd: body.cwd });
-        nascent.set(session.id, { cwd: body.cwd, createdAt: Date.now() });
+        const createdAt = Date.now();
+        nascent.set(session.id, { cwd: body.cwd, createdAt });
         router.attach({ channelId: "web", conversationId: session.id }, session);
         // Created here = part of the workspace; pinning is what Projects lists.
-        state.set("pinned", session.id, true);
+        state.pin({ id: session.id, cwd: body.cwd, createdAt }, true);
         hub.emitWorkspace({ type: "sessions-changed" });
         return c.json({ id: session.id }, 201);
     });
@@ -91,29 +127,43 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     // here; the broadcast moves every other client's dot back to idle.
     app.post("/api/sessions/:id/read", (c) => {
         const id = c.req.param("id");
-        if (state.has("unread", id)) {
-            state.set("unread", id, false);
+        if (state.unread(id)) {
+            state.setUnread(id, false);
             hub.emitWorkspace({ type: "sessions-changed" });
         }
         return c.json({ ok: true });
     });
     app.post("/api/sessions/:id/pin", async (c) => {
         const body = await c.req.json().catch(() => null);
-        if (typeof body?.pinned !== "boolean")
-            return c.json({ error: "pinned required" }, 400);
-        // The id is trusted: checking existence costs a session list per click,
-        // and the surface is operator-authenticated. Worst case is a stray row.
-        state.set("pinned", c.req.param("id"), body.pinned);
+        if (typeof body?.pinned !== "boolean" ||
+            typeof body.cwd !== "string" || !body.cwd ||
+            typeof body.createdAt !== "number" || !Number.isFinite(body.createdAt) ||
+            (body.title !== undefined && typeof body.title !== "string")) {
+            return c.json({ error: "pinned and session summary required" }, 400);
+        }
+        // The summary came from this authenticated surface's own list. Persisting
+        // it here makes the next Projects read independent of Pi's transcript scan.
+        state.pin({
+            id: c.req.param("id"),
+            cwd: body.cwd,
+            createdAt: body.createdAt,
+            ...(body.title ? { title: body.title.slice(0, 80) } : {}),
+        }, body.pinned);
         hub.emitWorkspace({ type: "sessions-changed" });
         return c.json({ pinned: body.pinned });
     });
+    // The two responses big enough to matter: a transcript, and one turn's tool
+    // detail. Scoped to these routes on purpose — compressing the SSE streams
+    // would sit on events until the encoder's buffer filled.
+    app.use("/api/sessions/:id/history", compress());
+    app.use("/api/sessions/:id/turns/:index/steps", compress());
     // Snapshot: everything a fresh client needs before it starts consuming
     // deltas from SSE — transcript, live state, pending queue, model.
     guarded(app, "GET", "/api/sessions/:id/history", 404, async (c) => {
         const id = c.req.param("id");
         const session = await ensure(id);
         return c.json({
-            turns: await session.history(),
+            turns: (await session.history()).map(slim),
             lastSeq: hub.lastSeq(id),
             model: session.model ?? null,
             state: session.state,
@@ -123,6 +173,21 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
             backgroundRuns: backgroundRuns?.(id) ?? [],
         });
     });
+    // One turn's activity in full, for the group the user just opened. Indexed
+    // like the edit route below; the steps carry their own id and tool name so a
+    // client whose snapshot has since been rewound can tell it is looking at a
+    // different turn instead of showing the wrong tool's output.
+    guarded(app, "GET", "/api/sessions/:id/turns/:index/steps", 404, async (c) => {
+        const index = Number(c.req.param("index"));
+        if (!Number.isInteger(index) || index < 0)
+            return c.json({ error: "index required" }, 400);
+        const turn = (await (await ensure(c.req.param("id"))).history())[index];
+        if (!turn)
+            return c.json({ error: `no turn at index ${index}` }, 404);
+        // Already capped at MAX_STEP_OUTPUT by the transcript rebuild: this route
+        // hands back what a surface shows, not the untruncated tool result.
+        return c.json({ steps: turn.steps ?? [] });
+    });
     // Composer attachments: bytes land in the inbox, the message carries the
     // path as a `[name](file:///…)` line the client builds itself — upload
     // first, so the text it sends (and optimistically renders) is final.
@@ -194,6 +259,8 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
             text: body.text,
             mode,
         });
+        if (state.title(id, body.text))
+            hub.emitWorkspace({ type: "sessions-changed" });
         return c.json({ sessionId }, 202);
     });
     // Edit a user turn: rewind the transcript to just before it, then re-send

package/dist/web/session-state.js

@@ -1,39 +1,73 @@
-// Workbench organization state: which sessions show up under Projects (created
-// in Pier means pinned, everything else waits in All sessions) and which have
-// a finished turn no client has looked at yet.
+// Workbench organization state: which sessions show up under Projects, the
+// summaries needed to render them without scanning Pi, and which have a
+// finished turn no client has looked at yet.
 //
 // One row per session rather than two JSON files: the unread flag is written at
 // the end of every turn, and rewriting a whole file on each of those writes
 // loses the entire set when the process dies mid-write — a truncated file reads
 // back as "no pins", which is indistinguishable from a fresh install.
 import { pierDb } from "../db.js";
-// Written out per flag rather than interpolated: the union type only holds at
-// compile time, and a cast at some future route is all it would take to put
-// request text into SQL.
-const SQL = {
-    pinned: {
-        has: "SELECT pinned AS on_ FROM session_state WHERE session_id = ?",
-        set: `INSERT INTO session_state(session_id, pinned) VALUES (?, ?)
-          ON CONFLICT(session_id) DO UPDATE SET pinned = excluded.pinned`,
-    },
-    unread: {
-        has: "SELECT unread AS on_ FROM session_state WHERE session_id = ?",
-        set: `INSERT INTO session_state(session_id, unread) VALUES (?, ?)
-          ON CONFLICT(session_id) DO UPDATE SET unread = excluded.unread`,
-    },
-};
 export class SessionStateStore {
     #db;
     constructor(db = pierDb()) {
         this.#db = db;
     }
-    has(flag, sessionId) {
-        const row = this.#db.prepare(SQL[flag].has).get(sessionId);
-        return row?.on_ === 1;
+    unread(sessionId) {
+        const row = this.#db.prepare("SELECT unread FROM session_state WHERE session_id = ?").get(sessionId);
+        return row?.unread === 1;
     }
-    set(flag, sessionId, on) {
-        // Upsert on the flag alone: the row may already exist for the other one,
-        // and a session's two flags are set from unrelated places.
-        this.#db.prepare(SQL[flag].set).run(sessionId, on ? 1 : 0);
+    setUnread(sessionId, unread) {
+        this.#db.prepare(`INSERT INTO session_state(session_id, unread) VALUES (?, ?)
+       ON CONFLICT(session_id) DO UPDATE SET unread = excluded.unread`).run(sessionId, unread ? 1 : 0);
+    }
+    /** Pin plus the summary Projects needs, atomically in one row. */
+    pin(summary, pinned) {
+        this.#db.prepare(`INSERT INTO session_state(session_id, pinned, cwd, title, created_at)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(session_id) DO UPDATE SET
+         pinned = excluded.pinned,
+         cwd = excluded.cwd,
+         title = COALESCE(excluded.title, session_state.title),
+         created_at = excluded.created_at`).run(summary.id, pinned ? 1 : 0, summary.cwd, summary.title ?? null, summary.createdAt);
+    }
+    /** Project rows only; unlike AgentFactory.list(), this never touches disk. */
+    projects() {
+        const rows = this.#db.prepare(`SELECT session_id AS id, cwd, title, created_at AS createdAt, unread
+       FROM session_state
+       WHERE pinned = 1 AND cwd IS NOT NULL AND created_at IS NOT NULL
+       ORDER BY created_at DESC`).all();
+        return rows.map(({ title, unread, ...row }) => ({
+            ...row,
+            ...(title ? { title } : {}),
+            unread: unread === 1,
+        }));
+    }
+    needsProjectBackfill() {
+        return this.#db.prepare("SELECT 1 FROM session_state WHERE pinned = 1 AND (cwd IS NULL OR created_at IS NULL) LIMIT 1").get() !== undefined;
+    }
+    /** A full listing is rare; use it to repair metadata for rows we already own. */
+    remember(summaries) {
+        const update = this.#db.prepare(`UPDATE session_state SET
+         cwd = ?, title = COALESCE(?, title), created_at = ?
+       WHERE session_id = ?`);
+        this.#db.exec("BEGIN");
+        try {
+            for (const s of summaries)
+                update.run(s.cwd, s.title ?? null, s.createdAt, s.id);
+            this.#db.exec("COMMIT");
+        }
+        catch (err) {
+            this.#db.exec("ROLLBACK");
+            throw err;
+        }
+    }
+    flags() {
+        const rows = this.#db.prepare("SELECT session_id AS id, pinned, unread FROM session_state WHERE pinned = 1 OR unread = 1").all();
+        return new Map(rows.map((r) => [r.id, { pinned: r.pinned === 1, unread: r.unread === 1 }]));
+    }
+    /** The first prompt supplies the title of a newly-created pinned session. */
+    title(sessionId, text) {
+        const result = this.#db.prepare("UPDATE session_state SET title = ? WHERE session_id = ? AND pinned = 1 AND title IS NULL").run(text.trim().slice(0, 80), sessionId);
+        return result.changes > 0;
     }
 }

package/dist/web/terminal.js

@@ -0,0 +1,334 @@
+// Terminal backend: one shell pty per project cwd, mirrored to every attached
+// WebSocket. The pty outlives the page — closing a tab only detaches, and a
+// later attach replays the recent output ring; every attached page sees the
+// same shell, and any of them may type (last resize wins). Detached for an
+// hour → the shell is reaped; a Pier restart kills every pty (run tmux inside
+// to survive that — durability is tmux's job, not ours). This is the one
+// WebSocket surface: a keystroke is a round trip, which SSE cannot carry
+// upstream. Everything else stays on the event stream.
+import { realpath, stat } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { spawn } from "node-pty";
+import { WebSocketServer } from "ws";
+import { logger } from "../log.js";
+import { upgradeAuthorized } from "./auth.js";
+const log = logger("terminal");
+/** Live shells at once — a guard against forgotten spawns, not a quota. */
+const MAX_TERMS = 8;
+/** Recent output kept for reattach. Scrollback beyond it lives in the page. */
+const RING_BYTES = 1024 * 1024;
+const IDLE_MS = 60 * 60_000;
+const SWEEP_MS = 60_000;
+const HEARTBEAT_MS = 30_000;
+/** A slow mirror is detached before its send queue grows without bound; a
+ *  healthy page must never be paused behind it. Reattach replays the ring. */
+const HIGH_WATER = 4 * 1024 * 1024;
+const MAX_FRAME_BYTES = 1024 * 1024;
+// A Web Terminal is a new local tty, not the tmux/SSH client Pier happened to
+// start under. Inheriting these can attach the shell back into Pier's parent
+// tmux session; SSH_AUTH_SOCK deliberately stays so git/ssh keep working.
+const PARENT_TERMINAL_ENV = ["TMUX", "TMUX_PANE", "SSH_TTY", "SSH_CLIENT", "SSH_CONNECTION"];
+const send = (sock, data) => {
+    try {
+        sock.send(data);
+        return true;
+    }
+    catch (err) {
+        log.warn(`terminal socket send failed: ${String(err)}`);
+        return false;
+    }
+};
+const control = (sock, msg) => send(sock, JSON.stringify(msg));
+export class TerminalHub {
+    #terms = new Map();
+    #shell;
+    #idleMs;
+    #maxTerms;
+    #sweeper;
+    #closeListeners = new Set();
+    #closed = false;
+    constructor(opts = {}) {
+        this.#shell = opts.shell ?? process.env.SHELL ?? "/bin/bash";
+        this.#idleMs = opts.idleMs ?? IDLE_MS;
+        this.#maxTerms = opts.maxTerms ?? MAX_TERMS;
+        this.#sweeper = setInterval(() => this.sweep(Date.now()), SWEEP_MS);
+        this.#sweeper.unref();
+    }
+    /** Attach a socket to `cwd`'s shell, spawning one if needed. A refusal is
+     *  never silent: the socket gets a `{t:"error"}` frame and a close, and the
+     *  caller gets `null`. */
+    async attach(cwd, sock) {
+        let key;
+        try {
+            if (!isAbsolute(cwd))
+                throw new Error("cwd must be an absolute directory");
+            key = await realpath(cwd);
+            if (!(await stat(key)).isDirectory())
+                throw new Error("cwd must be an absolute directory");
+        }
+        catch (err) {
+            control(sock, { t: "error", message: String(err) });
+            sock.close(1008, "bad cwd");
+            return null;
+        }
+        if (this.#closed) {
+            control(sock, { t: "error", message: "terminal server is stopping" });
+            sock.close(1012, "server stopping");
+            return null;
+        }
+        let term = this.#terms.get(key);
+        if (!term) {
+            if (this.#terms.size >= this.#maxTerms) {
+                control(sock, { t: "error", message: `${this.#maxTerms} shells already running — close one first` });
+                sock.close(1013, "too many shells");
+                return null;
+            }
+            try {
+                term = this.#spawn(key);
+            }
+            catch (err) {
+                log.error(`spawn ${this.#shell} in ${key} failed`, err);
+                control(sock, { t: "error", message: `could not start ${this.#shell}: ${String(err)}` });
+                sock.close(1011, "spawn failed");
+                return null;
+            }
+        }
+        term.clients.add(sock);
+        term.idleSince = Infinity;
+        const conn = {
+            message: (text) => this.#message(key, sock, text),
+            detach: () => {
+                const t = this.#terms.get(key);
+                if (!t || !t.clients.delete(sock))
+                    return;
+                if (t.clients.size === 0)
+                    t.idleSince = Date.now();
+            },
+        };
+        try {
+            if (term.ringBytes)
+                sock.send(Buffer.concat(term.ring));
+        }
+        catch (err) {
+            conn.detach();
+            throw err;
+        }
+        return conn;
+    }
+    #spawn(cwd) {
+        const env = { ...process.env };
+        for (const key of PARENT_TERMINAL_ENV)
+            delete env[key];
+        const pty = spawn(this.#shell, [], {
+            name: "xterm-256color",
+            cols: 120,
+            rows: 30,
+            cwd,
+            env,
+        });
+        const term = { pty, ring: [], ringBytes: 0, clients: new Set(), idleSince: Infinity };
+        this.#terms.set(cwd, term);
+        log.info(`shell ${pty.pid} for ${cwd}`);
+        pty.onData((data) => {
+            const chunk = Buffer.from(data);
+            term.ring.push(chunk);
+            term.ringBytes += chunk.byteLength;
+            while (term.ringBytes > RING_BYTES && term.ring.length > 1) {
+                term.ringBytes -= term.ring.shift().byteLength;
+            }
+            for (const client of term.clients) {
+                if (client.bufferedAmount <= HIGH_WATER && send(client, chunk))
+                    continue;
+                term.clients.delete(client);
+                client.close(1013, "client too slow");
+                log.warn(`detached slow terminal client for ${cwd}`);
+            }
+            if (term.clients.size === 0 && term.idleSince === Infinity)
+                term.idleSince = Date.now();
+        });
+        pty.onExit(({ exitCode }) => {
+            log.info(`shell ${pty.pid} for ${cwd} exited (${exitCode})`);
+            this.#terms.delete(cwd);
+            for (const c of term.clients) {
+                control(c, { t: "exit", code: exitCode });
+                c.close(1000, "shell exited");
+            }
+            term.clients.clear();
+        });
+        return term;
+    }
+    /** One inbound frame. Malformed input is logged and dropped, never half-run. */
+    #message(cwd, sock, text) {
+        const term = this.#terms.get(cwd);
+        if (!term || !term.clients.has(sock))
+            return;
+        let raw;
+        try {
+            raw = JSON.parse(text);
+        }
+        catch {
+            log.warn(`dropped unparseable frame for ${cwd}`);
+            return;
+        }
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+            log.warn(`dropped malformed frame for ${cwd}: ${text.slice(0, 80)}`);
+            return;
+        }
+        const msg = raw;
+        if (msg.t === "in" && typeof msg.d === "string") {
+            term.pty.write(msg.d);
+            return;
+        }
+        if (msg.t === "resize" &&
+            typeof msg.cols === "number" && typeof msg.rows === "number" &&
+            Number.isInteger(msg.cols) && Number.isInteger(msg.rows) &&
+            msg.cols >= 2 && msg.cols <= 500 && msg.rows >= 2 && msg.rows <= 200) {
+            term.pty.resize(msg.cols, msg.rows); // last resize wins, by design
+            return;
+        }
+        log.warn(`dropped malformed frame for ${cwd}: ${text.slice(0, 80)}`);
+    }
+    /** Reap shells nobody has been attached to for `idleMs`. */
+    sweep(now) {
+        for (const [cwd, term] of this.#terms) {
+            if (now - term.idleSince < this.#idleMs)
+                continue;
+            log.info(`reaping idle shell ${term.pty.pid} for ${cwd}`);
+            term.pty.kill(); // onExit above deletes and notifies
+        }
+    }
+    get size() {
+        return this.#terms.size;
+    }
+    onClose(listener) {
+        this.#closeListeners.add(listener);
+    }
+    /** Shutdown: kill every shell so none outlives the workbench. */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        clearInterval(this.#sweeper);
+        for (const listener of this.#closeListeners) {
+            try {
+                listener();
+            }
+            catch (err) {
+                log.error("terminal shutdown cleanup failed", err);
+            }
+        }
+        this.#closeListeners.clear();
+        for (const term of this.#terms.values())
+            term.pty.kill();
+    }
+}
+/** The upgrade seam: `/api/terminal?cwd=…` behind the same password boundary
+ *  as every route. SameSite=Lax already withholds the cookie cross-site; the
+ *  Origin check is the explicit copy of that fact. */
+export function attachTerminal(server, auth, heartbeatMs = HEARTBEAT_MS) {
+    const hub = new TerminalHub();
+    const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_FRAME_BYTES });
+    const alive = new WeakSet();
+    const heartbeat = setInterval(() => {
+        for (const client of wss.clients) {
+            if (client.readyState !== client.OPEN || !alive.delete(client))
+                client.terminate();
+            else
+                client.ping(); // browsers and proxies both see traffic
+        }
+    }, heartbeatMs);
+    heartbeat.unref();
+    hub.onClose(() => {
+        clearInterval(heartbeat);
+        for (const client of wss.clients)
+            client.terminate();
+        wss.close();
+    });
+    server.once("close", () => hub.close());
+    wss.on("error", (err) => log.error("terminal WebSocket server failed", err));
+    auth.onRotation(() => {
+        log.info("password changed; closing terminal clients");
+        for (const client of wss.clients)
+            client.close(1008, "password changed");
+    });
+    server.on("upgrade", (req, socket, head) => {
+        let url;
+        try {
+            url = new URL(req.url ?? "/", "http://localhost");
+        }
+        catch {
+            log.warn(`refused malformed terminal upgrade target: ${req.url ?? ""}`);
+            socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        if (url.pathname !== "/api/terminal") {
+            socket.destroy();
+            return;
+        }
+        if (!upgradeAuthorized(auth, req)) {
+            log.warn("refused terminal upgrade (unauthorized)");
+            socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        const authKey = auth.cookieKey;
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            alive.add(ws);
+            ws.on("pong", () => alive.add(ws));
+            // Frames can land while attach() is resolving realpath; hold a bounded
+            // handful. Close is registered first so an early disconnect cannot leave
+            // a phantom client that prevents the one-hour reap.
+            let conn = null;
+            let closed = false;
+            let pendingBytes = 0;
+            const pending = [];
+            ws.on("close", () => {
+                closed = true;
+                conn?.detach();
+            });
+            ws.on("message", (data, binary) => {
+                if (closed)
+                    return;
+                if (auth.cookieKey !== authKey) {
+                    closed = true;
+                    ws.close(1008, "password changed");
+                    return;
+                }
+                if (binary) {
+                    closed = true;
+                    ws.close(1003, "text frames only");
+                    return;
+                }
+                const text = String(data);
+                if (conn)
+                    conn.message(text);
+                else if ((pendingBytes += Buffer.byteLength(text)) <= MAX_FRAME_BYTES)
+                    pending.push(text);
+                else {
+                    closed = true;
+                    ws.close(1009, "too much pending input");
+                }
+            });
+            ws.on("error", (err) => log.warn(`terminal socket error: ${String(err)}`));
+            void hub.attach(url.searchParams.get("cwd") ?? "", ws).then((c) => {
+                if (!c)
+                    return;
+                if (closed) {
+                    c.detach();
+                    return;
+                }
+                conn = c;
+                for (const text of pending)
+                    conn.message(text);
+            }).catch((err) => {
+                log.error("terminal attach failed", err);
+                if (closed)
+                    return;
+                control(ws, { t: "error", message: `terminal attach failed: ${String(err)}` });
+                ws.close(1011, "attach failed");
+            });
+        });
+    });
+    return hub;
+}