@volter/supercode-terminal 0.2.30

package/substrate/session-roll.d.ts

@@ -0,0 +1,14 @@
+export type HeadScan = {
+    firstTimestampMs?: number;
+    isClearRoll: boolean;
+};
+export type SessionRollTracker = {
+    gather(currentSessionIds: string[]): Promise<Map<string, string>>;
+};
+export declare function createSessionRollTracker(options?: {
+    home?: string;
+    claudeConfigDir?: string;
+    scanIntervalMs?: number;
+}): SessionRollTracker;
+export declare function scanTranscriptHead(head: string): HeadScan;
+export declare function clearRollHeadVerdict(head: string): boolean;

package/substrate/session-roll.js

@@ -0,0 +1,407 @@
+import { open, readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+// Detects a claude session ROLL. `/clear` inside a live claude process ends the
+// current conversation and starts a NEW session id — a new transcript file in
+// the same project dir — while the process (and the `--session-id`/`--resume`
+// pin in its argv) stays the same. The lifecycle derives a pane's session from
+// that argv pin, so without correction it attributes the pane to the launch-time
+// id forever: the live board claims the OLD id is running while every durable
+// surface (the conversation index behind `sessions search` and the Chats panel)
+// correctly reports that id's transcript as frozen — a "live but 26h idle,
+// stuck" contradiction (see test/session-roll.test.mjs for the shape).
+//
+// The tracker gathers roll evidence OFF the pure observe pass (async fs only —
+// it runs on the provider event loop, so nothing here may block) and hands
+// `observeLifecycle` a map of prefixed agentSessionId → successor to apply.
+// All ordering gates run on the transcripts' CONTENT timestamps (the entries'
+// `timestamp` fields), never on file mtimes: mtimes move without conversation
+// activity (observed live — indexing/backup touches, in-place snapshot
+// rewrites), and an mtime-based gate both missed the real roll and would have
+// flapped revocation. A successor must clear four gates, deliberately
+// conservative because adopting a wrong id would misroute session-keyed input:
+//   1. same project dir — claude writes a roll's transcript beside its
+//      predecessor's;
+//   2. its first entry timestamp is at/after the predecessor's LAST entry
+//      timestamp — a conversation that was already running in parallel is never
+//      adopted;
+//   3. its head BEGINS with the `/clear` local-command turn — the roll marker.
+//      The `/clear` turn is recorded in the file it CREATES (never in the file
+//      it ends), so a head-of-file `/clear` identifies a rolled-from-something
+//      transcript, while a fresh session or a `--resume` fork (copied history)
+//      starts with a real first message instead;
+//   4. not claimed by another pane (enforced store-side in observeLifecycle,
+//      which sees all panes).
+// A successor eligible for MORE THAN ONE tracked predecessor in the dir is
+// adopted by none — two co-located panes' rolls are indistinguishable by
+// transcript evidence alone, and the ambiguity clears once the other candidate
+// writes again. A mapping self-heals: if the predecessor transcript gains a
+// LATER entry the roll was wrong (that session is demonstrably still live) and
+// the mapping is revoked; a vanished successor transcript revokes it too. All
+// state is derived and in-memory — a provider restart re-derives it.
+// Ordering slack: a predecessor flush that lands moments after the successor's
+// first entry must not hide a genuine roll behind the ordering gate.
+const ORDER_SLACK_MS = 15_000;
+// A session id whose transcript is not on disk yet (just launched) is re-searched
+// at most this often, so a missing file never costs a projects walk per tick.
+const MISSING_PATH_TTL_MS = 15_000;
+// Successor scans re-walk a project dir at most this often: eligibility can
+// change without the dir changing (a co-located session writing again un-blurs
+// an ambiguous successor), so the cadence is time-based, not dir-mtime-based.
+const SCAN_INTERVAL_MS = 15_000;
+const EDGE_BYTES = 16 * 1024;
+const HEAD_SCAN_MAX_ENTRIES = 50;
+const EDGE_CACHE_MAX = 500;
+export function createSessionRollTracker(options = {}) {
+    const scanIntervalMs = options.scanIntervalMs ?? SCAN_INTERVAL_MS;
+    const configDir = options.claudeConfigDir ?? (options.home === undefined ? process.env.CLAUDE_CONFIG_DIR : undefined) ?? join(options.home ?? homedir(), ".claude");
+    let pending = Promise.resolve();
+    const mappings = new Map();
+    const revokedTargetByFrom = new Map();
+    const pathBySessionId = new Map();
+    const missingPathCheckedAtMs = new Map();
+    const scannedAtMsByDir = new Map();
+    // Bounded-edge read caches, keyed by size (appends always grow a transcript;
+    // a positive head verdict is immutable since the head of an append-only file
+    // never changes).
+    const headScanByPath = new Map();
+    const lastActivityByPath = new Map();
+    async function resolveTranscriptPath(sessionId) {
+        const cached = pathBySessionId.get(sessionId);
+        if (cached && await statOrUndefined(cached))
+            return cached;
+        const checkedAtMs = missingPathCheckedAtMs.get(sessionId);
+        if (checkedAtMs !== undefined && Date.now() - checkedAtMs < MISSING_PATH_TTL_MS)
+            return undefined;
+        const fileName = `${sessionId.slice("claude:".length)}.jsonl`;
+        const projectsRoot = join(configDir, "projects");
+        let projectDirs;
+        try {
+            projectDirs = await readdir(projectsRoot);
+        }
+        catch {
+            projectDirs = [];
+        }
+        const hits = [];
+        for (const projectDir of projectDirs) {
+            const candidate = join(projectsRoot, projectDir, fileName);
+            if (await statOrUndefined(candidate))
+                hits.push(candidate);
+            if (hits.length > 1)
+                break;
+        }
+        const found = hits.length === 1 ? hits[0] : undefined;
+        if (!found) {
+            missingPathCheckedAtMs.set(sessionId, Date.now());
+            return undefined;
+        }
+        missingPathCheckedAtMs.delete(sessionId);
+        pathBySessionId.set(sessionId, found);
+        return found;
+    }
+    async function headScanFor(transcriptPath, size) {
+        const cached = headScanByPath.get(transcriptPath);
+        if (cached && (cached.scan.isClearRoll || cached.size === size))
+            return cached.scan;
+        const head = await readSlice(transcriptPath, 0, EDGE_BYTES);
+        if (head === undefined)
+            return { isClearRoll: false };
+        const scan = scanTranscriptHead(head);
+        if (headScanByPath.size >= EDGE_CACHE_MAX)
+            headScanByPath.clear();
+        headScanByPath.set(transcriptPath, { scan, size });
+        return scan;
+    }
+    // The predecessor's conversation clock: the max entry timestamp in the tail.
+    // Content-derived on purpose — file mtimes move without conversation activity.
+    async function lastActivityFor(transcriptPath, size) {
+        const cached = lastActivityByPath.get(transcriptPath);
+        if (cached && cached.size === size)
+            return cached.lastTimestampMs;
+        const tail = await readSlice(transcriptPath, Math.max(0, size - EDGE_BYTES), EDGE_BYTES);
+        if (tail === undefined)
+            return undefined;
+        let lastTimestampMs;
+        for (const line of tail.split("\n")) {
+            const entry = parseLine(line);
+            if (!entry)
+                continue;
+            const timestampMs = entryTimestampMs(entry);
+            if (timestampMs !== undefined && (lastTimestampMs === undefined || timestampMs > lastTimestampMs)) {
+                lastTimestampMs = timestampMs;
+            }
+        }
+        if (lastActivityByPath.size >= EDGE_CACHE_MAX)
+            lastActivityByPath.clear();
+        lastActivityByPath.set(transcriptPath, { lastTimestampMs, size });
+        return lastTimestampMs;
+    }
+    // One scan covers every tracked session in a project dir, so a successor is
+    // matched against ALL of its potential predecessors at once (the ambiguity
+    // gate — see the module comment).
+    async function detectRollsInDir(projectDir, tracked) {
+        let entries;
+        try {
+            entries = await readdir(projectDir);
+        }
+        catch {
+            return [];
+        }
+        const trackedPaths = new Set(tracked.map((session) => session.transcriptPath));
+        const claimedPaths = new Set([...mappings.values()].map((mapping) => mapping.toPath));
+        const oldestActivityMs = Math.min(...tracked.map((session) => session.lastActivityMs));
+        const siblings = entries.filter((entry) => {
+            const candidatePath = join(projectDir, entry);
+            return /^[a-zA-Z0-9_-]+\.jsonl$/.test(entry) && !trackedPaths.has(candidatePath) && !claimedPaths.has(candidatePath);
+        });
+        // Cheap fs-level pre-filter before any content read: a file CREATED before
+        // every tracked session's last activity cannot be anyone's successor. Only
+        // applied when the filesystem reports a real birthtime.
+        const candidates = [];
+        for (const entry of siblings) {
+            const candidatePath = join(projectDir, entry);
+            const stats = await statOrUndefined(candidatePath);
+            if (!stats)
+                continue;
+            if (stats.birthtimeMs > 0 && stats.birthtimeMs < oldestActivityMs - ORDER_SLACK_MS)
+                continue;
+            const scan = await headScanFor(candidatePath, stats.size);
+            if (!scan.isClearRoll || scan.firstTimestampMs === undefined)
+                continue;
+            candidates.push({ firstTimestampMs: scan.firstTimestampMs, path: candidatePath });
+            if (candidates.length > EDGE_CACHE_MAX)
+                return []; // Ambiguous overload: adopt none.
+        }
+        // Earliest successor first: the immediate next conversation is the roll; a
+        // later one (a chained /clear) is reached tick by tick.
+        candidates.sort((a, b) => a.firstTimestampMs - b.firstTimestampMs);
+        const rolls = [];
+        const consumed = new Set();
+        for (const candidate of candidates) {
+            const predecessors = tracked.filter((session) => !consumed.has(session.sessionId) && candidate.firstTimestampMs >= session.lastActivityMs - ORDER_SLACK_MS);
+            if (predecessors.length !== 1)
+                continue;
+            const predecessor = predecessors[0];
+            if (!predecessor)
+                continue;
+            if (revokedTargetByFrom.get(predecessor.sessionId) === candidate.path)
+                continue;
+            const predecessorStats = await statOrUndefined(predecessor.transcriptPath);
+            if (!predecessorStats)
+                continue;
+            consumed.add(predecessor.sessionId);
+            rolls.push({
+                from: predecessor.sessionId,
+                fromLastActivityMs: predecessor.lastActivityMs,
+                fromPath: predecessor.transcriptPath,
+                fromSize: predecessorStats.size,
+                to: `claude:${basename(candidate.path).replace(/\.jsonl$/, "")}`,
+                toPath: candidate.path
+            });
+        }
+        return rolls;
+    }
+    async function gather(currentSessionIds) {
+        // Retain only live chains, never an unbounded history of closed panes.
+        const reachable = new Set(currentSessionIds);
+        for (const id of reachable) {
+            const next = mappings.get(id)?.to;
+            if (next && reachable.size <= EDGE_CACHE_MAX)
+                reachable.add(next);
+        }
+        for (const id of mappings.keys())
+            if (!reachable.has(id))
+                mappings.delete(id);
+        for (const id of revokedTargetByFrom.keys())
+            if (!reachable.has(id))
+                revokedTargetByFrom.delete(id);
+        for (const id of pathBySessionId.keys())
+            if (!reachable.has(id))
+                pathBySessionId.delete(id);
+        for (const id of missingPathCheckedAtMs.keys())
+            if (!reachable.has(id))
+                missingPathCheckedAtMs.delete(id);
+        if (reachable.size > EDGE_CACHE_MAX) {
+            mappings.clear();
+            revokedTargetByFrom.clear();
+            pathBySessionId.clear();
+            missingPathCheckedAtMs.clear();
+            return new Map(); // Evidence capacity exhaustion is fail-closed.
+        }
+        if (scannedAtMsByDir.size >= EDGE_CACHE_MAX)
+            scannedAtMsByDir.clear();
+        for (const [from, mapping] of mappings) {
+            if (!await statOrUndefined(mapping.toPath)) {
+                mappings.delete(from);
+                continue;
+            }
+            const fromStats = await statOrUndefined(mapping.fromPath);
+            // A vanished predecessor doesn't invalidate the roll (the transcript may
+            // have been reaped); an unchanged size can't have new entries.
+            if (!fromStats || fromStats.size === mapping.fromSize)
+                continue;
+            const lastActivityMs = await lastActivityFor(mapping.fromPath, fromStats.size);
+            if (lastActivityMs !== undefined && lastActivityMs > mapping.fromLastActivityMs) {
+                // The predecessor gained a LATER entry after the roll was recorded —
+                // that session is still live, so the roll was wrong. Revoke; the
+                // ordering gate keeps the same successor from being re-adopted.
+                mappings.delete(from);
+                revokedTargetByFrom.set(from, mapping.toPath);
+            }
+            else {
+                // Content changed without a later timestamp (e.g. a snapshot line):
+                // remember the new size so the tail isn't re-read every tick.
+                mappings.set(from, { ...mapping, fromSize: fromStats.size });
+            }
+        }
+        // Group the tracked claude sessions by project dir and scan each dir once,
+        // on a time cadence.
+        const trackedByDir = new Map();
+        for (const sessionId of reachable) {
+            if (mappings.has(sessionId))
+                continue;
+            if (!/^claude:[a-zA-Z0-9_-]+$/.test(sessionId))
+                continue;
+            try {
+                const transcriptPath = await resolveTranscriptPath(sessionId);
+                if (!transcriptPath)
+                    continue;
+                const stats = await statOrUndefined(transcriptPath);
+                if (!stats)
+                    continue;
+                const lastActivityMs = await lastActivityFor(transcriptPath, stats.size);
+                if (lastActivityMs === undefined)
+                    continue;
+                const projectDir = dirname(transcriptPath);
+                const tracked = trackedByDir.get(projectDir) ?? [];
+                tracked.push({ lastActivityMs, sessionId, transcriptPath });
+                trackedByDir.set(projectDir, tracked);
+            }
+            catch {
+                // Evidence gathering is best-effort; a failed resolve just retries later.
+            }
+        }
+        for (const [projectDir, tracked] of trackedByDir) {
+            const scannedAtMs = scannedAtMsByDir.get(projectDir);
+            if (scannedAtMs !== undefined && Date.now() - scannedAtMs < scanIntervalMs)
+                continue;
+            scannedAtMsByDir.set(projectDir, Date.now());
+            try {
+                for (const roll of await detectRollsInDir(projectDir, tracked)) {
+                    mappings.set(roll.from, roll);
+                }
+            }
+            catch {
+                // Best-effort; the next cadence retries.
+            }
+        }
+        const rolls = new Map();
+        for (const [from, mapping] of mappings)
+            rolls.set(from, mapping.to);
+        return rolls;
+    }
+    return {
+        gather(currentSessionIds) {
+            // Serialize reads of mutable evidence, including concurrent host refreshes.
+            const ids = [...currentSessionIds];
+            const result = pending.then(() => gather(ids));
+            pending = result.catch(() => undefined);
+            return result;
+        },
+    };
+}
+// Pure scan of a transcript head: does this file BEGIN with the `/clear`
+// local-command turn (the roll marker), and what is its first entry timestamp
+// (the successor's conversation birth)? Claude records the `/clear` turn in the
+// transcript it creates, so it can only ever sit at the head of a rolled-from
+// file; any real first message means a fresh session (or a --resume fork's
+// copied history) and vetoes the verdict.
+export function scanTranscriptHead(head) {
+    let firstTimestampMs;
+    let isClearRoll = false;
+    let decided = false;
+    let inspected = 0;
+    for (const line of head.split("\n")) {
+        if (inspected >= HEAD_SCAN_MAX_ENTRIES)
+            break;
+        const entry = parseLine(line);
+        if (!entry)
+            continue;
+        inspected += 1;
+        const timestampMs = entryTimestampMs(entry);
+        if (timestampMs !== undefined && (firstTimestampMs === undefined || timestampMs < firstTimestampMs)) {
+            firstTimestampMs = timestampMs;
+        }
+        if (decided || entry.type !== "user")
+            continue;
+        const message = entry.message;
+        const content = message && typeof message === "object" && !Array.isArray(message)
+            ? message.content
+            : undefined;
+        // A non-text user turn (tool_result blocks) is mid-conversation shape, never
+        // the head of a fresh roll.
+        if (typeof content !== "string") {
+            decided = true;
+            continue;
+        }
+        const text = content.trimStart();
+        if (text.startsWith("<command-name>")) {
+            isClearRoll = /^<command-name>\s*\/clear\s*<\/command-name>/.test(text);
+            decided = true;
+            continue;
+        }
+        // The caveat/stdout wrappers around a local command precede the command turn
+        // itself in file order — skip them, they don't decide either way.
+        if (text.startsWith("<local-command-"))
+            continue;
+        decided = true;
+    }
+    return { ...(firstTimestampMs === undefined ? {} : { firstTimestampMs }), isClearRoll };
+}
+export function clearRollHeadVerdict(head) {
+    return scanTranscriptHead(head).isClearRoll;
+}
+function parseLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        const value = JSON.parse(trimmed);
+        return value !== null && typeof value === "object" && !Array.isArray(value)
+            ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function entryTimestampMs(entry) {
+    if (typeof entry.timestamp !== "string")
+        return undefined;
+    const parsed = Date.parse(entry.timestamp);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+async function statOrUndefined(path) {
+    try {
+        return await stat(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readSlice(path, position, bytes) {
+    let handle;
+    try {
+        handle = await open(path, "r");
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const buffer = Buffer.alloc(bytes);
+        const { bytesRead } = await handle.read(buffer, 0, bytes, position);
+        return buffer.toString("utf8", 0, bytesRead);
+    }
+    finally {
+        await handle.close();
+    }
+}

package/substrate/tmux-stream.d.ts

@@ -0,0 +1,32 @@
+import type { WebSocket } from "ws";
+import pty from "@homebridge/node-pty-prebuilt-multiarch";
+export type TerminalAttachment = {
+    dispose(): void;
+};
+export declare class TmuxTerminalAttachError extends Error {
+    readonly phase: "resolve" | "spawn";
+    constructor(phase: "resolve" | "spawn", cause: unknown);
+}
+export type TmuxTerminalSocketOptions<TAuthorization = void> = {
+    authorizeInput?: () => Promise<TAuthorization> | TAuthorization;
+    cols?: number;
+    cwd?: string;
+    errorLabel?: string;
+    onInput?: (data: string, authorization: TAuthorization | undefined) => Promise<void> | void;
+    readOnly?: boolean;
+    rows?: number;
+    socket: WebSocket;
+    terminalId: string;
+    tmuxSocket?: string;
+    window?: number;
+};
+export declare function attachTmuxTerminalSocket<TAuthorization = void>(options: TmuxTerminalSocketOptions<TAuthorization>): TerminalAttachment;
+type ReconciledPty = {
+    child: ReturnType<typeof pty.spawn>;
+    orphanPtmxFds: number[];
+};
+export declare function spawnReconciledPty(file: string, args: string[], options: Parameters<typeof pty.spawn>[2]): ReconciledPty;
+export declare function releasePtyMaster(child: {
+    destroy(): void;
+}, orphanPtmxFds?: number[]): void;
+export {};

package/substrate/tmux-stream.js

@@ -0,0 +1,212 @@
+import pty from "@homebridge/node-pty-prebuilt-multiarch";
+import fs from "node:fs";
+import { assertSession, getStatusLineCount, getWindowSize } from "./tmux.js";
+export class TmuxTerminalAttachError extends Error {
+    phase;
+    constructor(phase, cause) {
+        super(errorMessage(cause), { cause });
+        this.name = "TmuxTerminalAttachError";
+        this.phase = phase;
+    }
+}
+// Attach one ephemeral PTY client to a durable tmux session. The returned
+// attachment owns every listener and descriptor it creates; dispose is
+// idempotent and never terminates the tmux session itself.
+export function attachTmuxTerminalSocket(options) {
+    const window = options.window ?? 0;
+    if (!Number.isInteger(window) || window < 0) {
+        throw new Error("window must be a non-negative integer");
+    }
+    let tmuxSize;
+    try {
+        assertSession(options.terminalId, options.tmuxSocket);
+        tmuxSize = getWindowSize({ name: options.terminalId, socket: options.tmuxSocket, window });
+    }
+    catch (error) {
+        throw new TmuxTerminalAttachError("resolve", error);
+    }
+    // Observers inherit the durable pane dimensions exactly. Even an ignore-size tmux client can
+    // become the size source when it is the only attached client, so accepting the browser viewport
+    // here would silently reflow someone else's terminal merely by opening a read-only mirror.
+    const cols = options.readOnly ? tmuxSize.width : options.cols ?? tmuxSize.width;
+    const rows = options.readOnly
+        ? tmuxSize.height + getStatusLineCount(options.terminalId, options.tmuxSocket)
+        : options.rows ?? tmuxSize.height;
+    let reconciledPty;
+    try {
+        reconciledPty = spawnReconciledPty("tmux", [
+            ...(options.tmuxSocket ? ["-L", options.tmuxSocket] : []),
+            "-T",
+            "RGB",
+            "attach-session",
+            ...(options.readOnly ? ["-r"] : []),
+            "-t",
+            options.terminalId
+        ], {
+            cols,
+            cwd: options.cwd ?? process.cwd(),
+            env: {
+                ...process.env,
+                TERM: "screen-256color"
+            },
+            rows
+        });
+    }
+    catch (error) {
+        throw new TmuxTerminalAttachError("spawn", error);
+    }
+    const { child, orphanPtmxFds } = reconciledPty;
+    let disposed = false;
+    let outputSubscription;
+    let exitSubscription;
+    const onClose = () => dispose();
+    let controlQueue = Promise.resolve();
+    const runControl = (operation) => {
+        controlQueue = controlQueue
+            .then(async () => {
+            const authorization = await options.authorizeInput?.();
+            if (!disposed)
+                await operation(authorization);
+        })
+            .catch((error) => {
+            sendTerminalSocketError(options.socket, error, options.errorLabel);
+            options.socket.close(1008, "terminal access ended");
+        });
+    };
+    const onMessage = (raw) => {
+        try {
+            const message = JSON.parse(raw.toString());
+            if (message.type === "resize") {
+                if (options.readOnly)
+                    throw new Error("Read-only terminal attachments cannot resize the pane.");
+                assertTerminalDimension(message.cols, "cols");
+                assertTerminalDimension(message.rows, "rows");
+                runControl(() => child.resize(message.cols, message.rows));
+                return;
+            }
+            if (message.type !== "input") {
+                throw new Error(`Unsupported websocket message type: ${message.type}`);
+            }
+            if (typeof message.data !== "string") {
+                throw new Error("Input message did not include string data.");
+            }
+            runControl(async (authorization) => {
+                await options.onInput?.(message.data, authorization);
+                if (!disposed)
+                    child.write(message.data);
+            });
+        }
+        catch (error) {
+            sendTerminalSocketError(options.socket, error, options.errorLabel);
+        }
+    };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        options.socket.off("close", onClose);
+        options.socket.off("message", onMessage);
+        outputSubscription?.dispose();
+        exitSubscription?.dispose();
+        releasePtyMaster(child, orphanPtmxFds);
+    };
+    options.socket.send(JSON.stringify({ cols, rows, type: "hello" }));
+    outputSubscription = child.onData((data) => {
+        if (!disposed && options.socket.readyState === options.socket.OPEN) {
+            options.socket.send(JSON.stringify({ data: wellFormedTerminalText(data), type: "output" }));
+        }
+    });
+    exitSubscription = child.onExit(({ exitCode, signal }) => {
+        if (!disposed && options.socket.readyState === options.socket.OPEN) {
+            options.socket.send(JSON.stringify({ exitCode, signal, type: "exit" }));
+            options.socket.close(1000, "tmux client exited");
+        }
+        dispose();
+    });
+    options.socket.on("close", onClose);
+    options.socket.on("message", onMessage);
+    return { dispose };
+}
+export function spawnReconciledPty(file, args, options) {
+    if (process.platform !== "darwin") {
+        return { child: pty.spawn(file, args, options), orphanPtmxFds: [] };
+    }
+    const before = listCharacterDeviceFds();
+    const child = pty.spawn(file, args, options);
+    const masterFd = child._fd;
+    const masterMajor = characterDeviceMajor(masterFd);
+    const orphanPtmxFds = [];
+    if (typeof masterFd === "number" && masterMajor !== null) {
+        for (const fd of listCharacterDeviceFds()) {
+            if (!before.has(fd) && fd !== masterFd && characterDeviceMajor(fd) === masterMajor) {
+                orphanPtmxFds.push(fd);
+            }
+        }
+    }
+    return { child, orphanPtmxFds };
+}
+export function releasePtyMaster(child, orphanPtmxFds = []) {
+    try {
+        child.destroy();
+    }
+    catch {
+        // Child already gone; destroy is best-effort.
+    }
+    for (const fd of orphanPtmxFds) {
+        if (characterDeviceMajor(fd) === null)
+            continue;
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            // Already closed.
+        }
+    }
+}
+function characterDeviceMajor(fd) {
+    if (typeof fd !== "number")
+        return null;
+    try {
+        const stat = fs.fstatSync(fd);
+        return stat.isCharacterDevice() ? (stat.rdev >> 24) & 0xff : null;
+    }
+    catch {
+        return null;
+    }
+}
+function listCharacterDeviceFds() {
+    const fds = new Set();
+    try {
+        for (const entry of fs.readdirSync("/dev/fd")) {
+            const fd = Number(entry);
+            if (Number.isInteger(fd) && characterDeviceMajor(fd) !== null)
+                fds.add(fd);
+        }
+    }
+    catch {
+        // No /dev/fd (for example Windows conpty).
+    }
+    return fds;
+}
+function assertTerminalDimension(value, label) {
+    if (!Number.isInteger(value) || value < 1 || value > 1_000) {
+        throw new Error(`Terminal ${label} must be an integer between 1 and 1000.`);
+    }
+}
+function sendTerminalSocketError(socket, error, label = "terminal") {
+    if (socket.readyState !== socket.OPEN)
+        return;
+    socket.send(JSON.stringify({
+        message: `\r\n[${label}] ${errorMessage(error)}\r\n`,
+        type: "error"
+    }));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function wellFormedTerminalText(value) {
+    const maybeWellFormed = value;
+    if (typeof maybeWellFormed.toWellFormed === "function")
+        return maybeWellFormed.toWellFormed();
+    return value.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "\uFFFD");
+}