@prohost/cli 0.13.2 → 0.14.0

package/dist/codehost/settings.js

@@ -0,0 +1,114 @@
+/**
+ * This Mac's Code-thread hosting switches, and the private files the host keeps.
+ *
+ * Two switches, both off until the machine's owner turns them on here — the
+ * server can read them (the heartbeat and the relay socket report them) but has
+ * no way to change them:
+ *
+ * - `enabled` — this machine hosts Code threads: it takes
+ *   `code_thread.start_requested` / `code_thread.input_requested` from the
+ *   event stream, keeps their terminals in tmux, and holds the relay's control
+ *   socket open.
+ * - `allowRemoteTerminal` — someone other than a shell on this machine may
+ *   attach to those terminals and type: a relay viewer, or the desktop app
+ *   with any viewer token. Off, the desktop app on this Mac still attaches
+ *   over loopback, but only with a token the relay vouches for as minted for
+ *   this Mac's own app (`local_server.ts`). A remote terminal is remote code
+ *   execution on this machine; it is never on by default.
+ *
+ * Everything lives under `$PROHOST_HOME/code-host/` with owner-only modes.
+ */
+import { randomBytes } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { prohostHome } from '../agent/credentials.js';
+export const DEFAULT_SETTINGS = Object.freeze({
+    version: 1,
+    enabled: false,
+    allowRemoteTerminal: false,
+});
+/** `$PROHOST_HOME/code-host`. */
+export function codeHostDir(env = process.env) {
+    return path.join(prohostHome(env), 'code-host');
+}
+export function settingsPath(env = process.env) {
+    return path.join(codeHostDir(env), 'settings.json');
+}
+/** Create `dir` (and parents) owner-only. Idempotent. */
+export function ensurePrivateDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        /* not ours to fix — the files inside are still 0600 */
+    }
+}
+/**
+ * Write `value` as JSON, atomically (a temp file beside it, then a rename) and
+ * owner-only, so a reader never sees half a file or a moment of wider mode.
+ */
+export function writePrivateJson(file, value, mode = 0o600) {
+    ensurePrivateDir(path.dirname(file));
+    const temp = `${file}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    try {
+        writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode });
+        chmodSync(temp, mode);
+        renameSync(temp, file);
+    }
+    catch (err) {
+        rmSync(temp, { force: true });
+        throw err;
+    }
+}
+/**
+ * This home's Code-host instance id: minted once per `PROHOST_HOME`, kept in
+ * `code-host/instance.json`. The server binds each Mac thread to the instance
+ * that accepted its start (`coding_sessions.host_instance_id`) and sends its
+ * later frames to that instance alone: two harnesses on one pairing each keep
+ * their own tmux windows.
+ */
+export function codeHostInstanceId(env = process.env) {
+    const file = path.join(codeHostDir(env), 'instance.json');
+    const known = readJsonObject(file)?.id;
+    if (typeof known === 'string' && /^[0-9a-f]{32}$/.test(known))
+        return known;
+    const id = randomBytes(16).toString('hex');
+    writePrivateJson(file, { version: 1, id });
+    return id;
+}
+/** Parsed JSON object at `file`, or `undefined` for a missing or unreadable one. */
+export function readJsonObject(file) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The switches as they are on disk now. A missing, unreadable or malformed file
+ * is the default — both off — and only a literal `true` turns a switch on.
+ */
+export function loadSettings(env = process.env) {
+    const raw = readJsonObject(settingsPath(env));
+    if (!raw || raw.version !== 1)
+        return { ...DEFAULT_SETTINGS };
+    const enabled = raw.enabled === true;
+    return {
+        version: 1,
+        enabled,
+        // Remote typing without hosting is meaningless; never report one without the other.
+        allowRemoteTerminal: enabled && raw.allowRemoteTerminal === true,
+    };
+}
+export function saveSettings(settings, env = process.env) {
+    writePrivateJson(settingsPath(env), {
+        version: 1,
+        enabled: settings.enabled,
+        allowRemoteTerminal: settings.enabled && settings.allowRemoteTerminal,
+    });
+}

package/dist/codehost/sizing.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Who sizes a Code-thread window on this Mac, and what each viewer is told about it.
+ *
+ * Every viewer of a window — the relay's (a phone, a browser) and the desktop app's — is its own
+ * tmux client, and tmux would size the window to whichever was active last (`window-size latest`):
+ * a phone opening the thread shrank it for the desktop typing in it. Instead every window is sized
+ * with `resize-window` (which makes that window `window-size manual`; never the server's global
+ * option, which tmux 3.4 can't start with), from its creation on, and this module picks one viewer
+ * per window to size it to (the approved policy, CONTRACTS C3):
+ *
+ * - a viewer that attaches, types, sends `{"type":"claim"}` (a phone on ready / foreground / touch,
+ *   the desktop's "Use this window's size"), or reports focus (`ESC [ I`) takes it — never a
+ *   `watch` viewer, which can't type (it sizes a window only nobody else shows);
+ * - when the sizing viewer leaves, the one active most recently among those left takes over;
+ * - a handover or resize reaches tmux once it has been quiet {@link HANDOVER_DEBOUNCE_MS}, and only
+ *   when the size changes: Claude Code reprints its whole transcript on every width change.
+ *
+ * Copy mode (scrolled back) is the PANE's, so one viewer's scroll freezes everyone's view. The pane
+ * leaves it when the sizing viewer changes and when the viewer that scrolled leaves.
+ *
+ * A viewer that said `{"type":"hello","client":{"kind","label"}}` is sent
+ * `{"type":"sizer","kind","label","cols","rows","you","scrolled"}` on attach and whenever the
+ * sizing viewer, its size or the pane's copy mode changes; one that never said hello (an older
+ * page) is never sent one.
+ *
+ * It also holds a new shell's first prompt until the first viewer's size has settled: zsh redraws
+ * its prompt on every resize, so a shell started detached at tmux's 80x24 and then resized by the
+ * page's fit showed one prompt per resize. A held window runs `tmux wait-for <channel>` before its
+ * shell (see {@link holdCommand}); the first viewer's resizes going quiet signals it.
+ */
+export type ViewerKind = 'phone' | 'tablet' | 'desktop';
+export declare const VIEWER_KINDS: ReadonlySet<string>;
+/** What a viewer said it is (`hello`). `unknown`: it said hello without a kind this host knows. */
+export interface ViewerClient {
+    kind: ViewerKind | 'unknown';
+    label: string | null;
+}
+export interface SizerFrame {
+    type: 'sizer';
+    kind: ViewerKind | 'unknown';
+    label: string | null;
+    cols: number;
+    rows: number;
+    /** The viewer this frame is sent to sizes the window. */
+    you: boolean;
+    /** The pane is in copy mode (someone scrolled back): every viewer's view is frozen on it. */
+    scrolled: boolean;
+}
+/** A `hello` frame's `client`, made safe to repeat to another viewer. */
+export declare function parseViewerClient(raw: unknown): ViewerClient;
+/** Window option set on a window created holding its shell; cleared when it is released. */
+export declare const HOLD_OPTION = "@prohost_held";
+/** Quiet time after the first viewer's last resize before a held shell starts. */
+export declare const SETTLE_MS = 250;
+/** A held shell starts at most this long after its first viewer attached, resizes or not. */
+export declare const SETTLE_MAX_MS = 2000;
+/** A handover or resize is applied once quiet this long (each width change makes Claude Code reprint). */
+export declare const HANDOVER_DEBOUNCE_MS = 300;
+/** After input that may enter or leave copy mode, the pane is asked once it has been quiet this long. */
+export declare const MODE_CHECK_MS = 150;
+/** A held shell nobody attached to starts anyway after this long. */
+export declare const HOLD_FALLBACK_MS = 60000;
+export declare function holdChannel(name: string): string;
+/**
+ * `command`, run once the window's hold is released. Waits on the tmux server the pane runs in
+ * (`$TMUX`); without a reachable tmux the wait fails at once and the shell starts unheld. A
+ * signal sent before the wait began is kept by tmux, so the order can't strand it.
+ */
+export declare function holdCommand(name: string, command: string): string;
+/** Signal the hold, only while the window still carries {@link HOLD_OPTION} (tmux keeps a signal nobody waits for). */
+export declare function releaseHoldArgs(name: string): string[];
+export declare function resizeWindowArgs(name: string, cols: number, rows: number): string[];
+/**
+ * The size a window created next starts at — only while no client is attached to the server
+ * (tmux picks a new window's size from its global `window-size`); {@link resizeWindowArgs} right
+ * after `new-window` is what holds whatever is attached.
+ */
+export declare function defaultSizeArgs(cols: number, rows: number): string[];
+export type SizingTmux = (args: string[]) => Promise<{
+    ok: boolean;
+    stdout?: string;
+}>;
+export interface TerminalSizingOptions {
+    tmux: SizingTmux;
+    setTimer?: (fn: () => void, ms: number) => () => void;
+    now?: () => number;
+    defaultSize?: {
+        cols: number;
+        rows: number;
+    };
+}
+/** One viewer's say in its window's size. */
+export interface SizingViewer {
+    hello(client: ViewerClient): void;
+    resize(cols: number, rows: number): void;
+    /** Size the window to this viewer now: it typed, focused, or asked. A `watch` viewer's is ignored. */
+    claim(): void;
+    /**
+     * This viewer's input may have changed the pane's copy mode. `moved`: it can move copy mode (a
+     * wheel step, a drag, the prefix key, a keystroke), so this viewer is now who scrolled; else
+     * (an emulator report) the mode is only read again.
+     */
+    scrolled(moved?: boolean): void;
+    leave(): void;
+    onSizer(listener: (frame: SizerFrame) => void): void;
+}
+export declare class TerminalSizing {
+    private readonly options;
+    private readonly windows;
+    private nextId;
+    private seq;
+    private last;
+    private readonly setTimer;
+    private readonly now;
+    constructor(options: TerminalSizingOptions);
+    /** The size a window was last sized to: what a window created with nobody watching starts at. */
+    lastSize(): {
+        cols: number;
+        rows: number;
+    };
+    private state;
+    /**
+     * A window was just created (and resized to its first size). `held`: it runs
+     * {@link holdCommand} and carries {@link HOLD_OPTION}; its first viewer settling releases it, or
+     * {@link HOLD_FALLBACK_MS}.
+     */
+    created(name: string, options?: {
+        held?: boolean;
+    }): void;
+    /**
+     * A window an earlier daemon made, found by `adopt`: it may still hold its shell (that daemon's
+     * timer died with it). Released after {@link HOLD_FALLBACK_MS} unless a viewer settles it first;
+     * the release is a no-op on a window that isn't held. Once per window per daemon.
+     */
+    adopted(name: string): void;
+    /** Whether the pane may be in copy mode now (as read, or since input that may have entered it). */
+    mayBeScrolled(name: string): boolean;
+    /** The pane just left copy mode (its keystroke or a relayed reply cancelled it): every viewer hears. */
+    leftCopyMode(name: string): void;
+    join(name: string, size: {
+        cols: number;
+        rows: number;
+        watch?: boolean;
+    }): SizingViewer;
+    /** `viewer` sizes the window from now: copy mode is left (it froze everyone's view), the size follows. */
+    private handOver;
+    private frameFor;
+    /** Only to a viewer that said hello, and only what changed since its last frame. */
+    private send;
+    private broadcast;
+    /** Leave copy mode (if the pane is in it) and tell every viewer. */
+    private leaveCopyMode;
+    /** Read the pane's copy mode once input has been quiet {@link MODE_CHECK_MS}; tell viewers when it changed. */
+    private checkMode;
+    /**
+     * Size the window to its sizing viewer once the asks have been quiet {@link HANDOVER_DEBOUNCE_MS}:
+     * one `resize-window` at a time, the latest size last, none for a size it already has.
+     */
+    private apply;
+    private pump;
+    private settle;
+    private release;
+}

package/dist/codehost/sizing.js

@@ -0,0 +1,394 @@
+/**
+ * Who sizes a Code-thread window on this Mac, and what each viewer is told about it.
+ *
+ * Every viewer of a window — the relay's (a phone, a browser) and the desktop app's — is its own
+ * tmux client, and tmux would size the window to whichever was active last (`window-size latest`):
+ * a phone opening the thread shrank it for the desktop typing in it. Instead every window is sized
+ * with `resize-window` (which makes that window `window-size manual`; never the server's global
+ * option, which tmux 3.4 can't start with), from its creation on, and this module picks one viewer
+ * per window to size it to (the approved policy, CONTRACTS C3):
+ *
+ * - a viewer that attaches, types, sends `{"type":"claim"}` (a phone on ready / foreground / touch,
+ *   the desktop's "Use this window's size"), or reports focus (`ESC [ I`) takes it — never a
+ *   `watch` viewer, which can't type (it sizes a window only nobody else shows);
+ * - when the sizing viewer leaves, the one active most recently among those left takes over;
+ * - a handover or resize reaches tmux once it has been quiet {@link HANDOVER_DEBOUNCE_MS}, and only
+ *   when the size changes: Claude Code reprints its whole transcript on every width change.
+ *
+ * Copy mode (scrolled back) is the PANE's, so one viewer's scroll freezes everyone's view. The pane
+ * leaves it when the sizing viewer changes and when the viewer that scrolled leaves.
+ *
+ * A viewer that said `{"type":"hello","client":{"kind","label"}}` is sent
+ * `{"type":"sizer","kind","label","cols","rows","you","scrolled"}` on attach and whenever the
+ * sizing viewer, its size or the pane's copy mode changes; one that never said hello (an older
+ * page) is never sent one.
+ *
+ * It also holds a new shell's first prompt until the first viewer's size has settled: zsh redraws
+ * its prompt on every resize, so a shell started detached at tmux's 80x24 and then resized by the
+ * page's fit showed one prompt per resize. A held window runs `tmux wait-for <channel>` before its
+ * shell (see {@link holdCommand}); the first viewer's resizes going quiet signals it.
+ */
+import { leaveCopyModeArgs, paneInModeArgs, windowTarget } from './tmux.js';
+export const VIEWER_KINDS = new Set(['phone', 'tablet', 'desktop']);
+const MAX_LABEL_CHARS = 40;
+/** A `hello` frame's `client`, made safe to repeat to another viewer. */
+export function parseViewerClient(raw) {
+    const client = raw && typeof raw === 'object' ? raw : {};
+    const kind = typeof client.kind === 'string' && VIEWER_KINDS.has(client.kind) ? client.kind : 'unknown';
+    const label = typeof client.label === 'string'
+        ? // eslint-disable-next-line no-control-regex
+            client.label.replace(/[\u0000-\u001f\u007f-\u009f]/g, '').trim().slice(0, MAX_LABEL_CHARS)
+        : '';
+    return { kind, label: label || null };
+}
+/** Window option set on a window created holding its shell; cleared when it is released. */
+export const HOLD_OPTION = '@prohost_held';
+/** Quiet time after the first viewer's last resize before a held shell starts. */
+export const SETTLE_MS = 250;
+/** A held shell starts at most this long after its first viewer attached, resizes or not. */
+export const SETTLE_MAX_MS = 2_000;
+/** A handover or resize is applied once quiet this long (each width change makes Claude Code reprint). */
+export const HANDOVER_DEBOUNCE_MS = 300;
+/** After input that may enter or leave copy mode, the pane is asked once it has been quiet this long. */
+export const MODE_CHECK_MS = 150;
+/** A held shell nobody attached to starts anyway after this long. */
+export const HOLD_FALLBACK_MS = 60_000;
+export function holdChannel(name) {
+    return `prohost-hold-${name}`;
+}
+/**
+ * `command`, run once the window's hold is released. Waits on the tmux server the pane runs in
+ * (`$TMUX`); without a reachable tmux the wait fails at once and the shell starts unheld. A
+ * signal sent before the wait began is kept by tmux, so the order can't strand it.
+ */
+export function holdCommand(name, command) {
+    return `tmux wait-for ${holdChannel(name)} 2>/dev/null; ${command}`;
+}
+/** Signal the hold, only while the window still carries {@link HOLD_OPTION} (tmux keeps a signal nobody waits for). */
+export function releaseHoldArgs(name) {
+    const target = windowTarget(name);
+    return ['if-shell', '-F', '-t', target, `#{${HOLD_OPTION}}`, `wait-for -S ${holdChannel(name)} ; set-option -wu -t ${target} ${HOLD_OPTION}`];
+}
+export function resizeWindowArgs(name, cols, rows) {
+    return ['resize-window', '-t', windowTarget(name), '-x', String(cols), '-y', String(rows)];
+}
+/**
+ * The size a window created next starts at — only while no client is attached to the server
+ * (tmux picks a new window's size from its global `window-size`); {@link resizeWindowArgs} right
+ * after `new-window` is what holds whatever is attached.
+ */
+export function defaultSizeArgs(cols, rows) {
+    return ['set-option', '-g', 'default-size', `${cols}x${rows}`];
+}
+function defaultTimer(fn, ms) {
+    const timer = setTimeout(fn, ms);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+}
+const key = (size) => `${size.cols}x${size.rows}`;
+export class TerminalSizing {
+    options;
+    windows = new Map();
+    nextId = 1;
+    seq = 0;
+    last;
+    setTimer;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.setTimer = options.setTimer ?? defaultTimer;
+        this.now = options.now ?? Date.now;
+        this.last = options.defaultSize ?? { cols: 120, rows: 32 };
+    }
+    /** The size a window was last sized to: what a window created with nobody watching starts at. */
+    lastSize() {
+        return { ...this.last };
+    }
+    state(name) {
+        let state = this.windows.get(name);
+        if (!state) {
+            state = { viewers: new Map(), settled: false, scrolled: false, maybeScrolled: false };
+            this.windows.set(name, state);
+        }
+        return state;
+    }
+    /**
+     * A window was just created (and resized to its first size). `held`: it runs
+     * {@link holdCommand} and carries {@link HOLD_OPTION}; its first viewer settling releases it, or
+     * {@link HOLD_FALLBACK_MS}.
+     */
+    created(name, options = {}) {
+        // The same state object: viewers already attached hold it.
+        const state = this.state(name);
+        state.cancelSettle?.();
+        state.cancelFallback?.();
+        state.cancelSettle = undefined;
+        state.cancelFallback = undefined;
+        state.settled = false;
+        state.settleDeadline = undefined;
+        state.scrolled = false;
+        state.maybeScrolled = false;
+        // Not taken as applied: the first owner's resize-window confirms it, a no-op (no SIGWINCH)
+        // when the window already has that size.
+        state.applied = undefined;
+        if (options.held)
+            state.cancelFallback = this.setTimer(() => void this.release(name, state), HOLD_FALLBACK_MS);
+        // Somebody already shows it (a window re-created under them): sized to them, and settled from now.
+        if (state.owner !== undefined) {
+            this.apply(name, state);
+            this.settle(name, state);
+        }
+    }
+    /**
+     * A window an earlier daemon made, found by `adopt`: it may still hold its shell (that daemon's
+     * timer died with it). Released after {@link HOLD_FALLBACK_MS} unless a viewer settles it first;
+     * the release is a no-op on a window that isn't held. Once per window per daemon.
+     */
+    adopted(name) {
+        if (this.windows.has(name))
+            return;
+        const state = this.state(name);
+        state.cancelFallback = this.setTimer(() => void this.release(name, state), HOLD_FALLBACK_MS);
+    }
+    /** Whether the pane may be in copy mode now (as read, or since input that may have entered it). */
+    mayBeScrolled(name) {
+        const state = this.windows.get(name);
+        return Boolean(state && (state.scrolled || state.maybeScrolled));
+    }
+    /** The pane just left copy mode (its keystroke or a relayed reply cancelled it): every viewer hears. */
+    leftCopyMode(name) {
+        const state = this.windows.get(name);
+        if (!state)
+            return;
+        state.cancelModeCheck?.();
+        state.cancelModeCheck = undefined;
+        state.maybeScrolled = false;
+        state.scroller = undefined;
+        if (state.scrolled) {
+            state.scrolled = false;
+            this.broadcast(state);
+        }
+    }
+    join(name, size) {
+        const state = this.state(name);
+        const viewer = { id: this.nextId++, cols: size.cols, rows: size.rows, watch: size.watch === true, activeAt: ++this.seq };
+        state.viewers.set(viewer.id, viewer);
+        // Attaching claims the size, as tmux did (`window-size latest`): a watch viewer only a window
+        // nobody else shows.
+        const ownerHere = state.owner !== undefined && state.viewers.has(state.owner);
+        if (!ownerHere || !viewer.watch)
+            this.handOver(name, state, viewer);
+        // The first viewer this daemon has seen on it: a shell held for it starts once its size settles
+        // (a window an earlier daemon held too: the release is a no-op on a window that isn't).
+        if (!state.settled)
+            this.settle(name, state);
+        let left = false;
+        return {
+            hello: (client) => {
+                if (left)
+                    return;
+                viewer.client = client;
+                viewer.lastSent = undefined;
+                // The sizing viewer's name changed for everyone; anyone else just learns who sizes it.
+                if (state.owner === viewer.id)
+                    this.broadcast(state);
+                else
+                    this.send(state, viewer);
+            },
+            resize: (cols, rows) => {
+                if (left || (viewer.cols === cols && viewer.rows === rows))
+                    return;
+                viewer.cols = cols;
+                viewer.rows = rows;
+                if (state.owner !== viewer.id)
+                    return;
+                this.apply(name, state);
+                this.broadcast(state);
+                if (!state.settled)
+                    this.settle(name, state);
+            },
+            claim: () => {
+                if (left || state.owner === viewer.id || viewer.watch)
+                    return;
+                this.handOver(name, state, viewer);
+            },
+            scrolled: (moved = true) => {
+                if (left)
+                    return;
+                if (moved) {
+                    state.scroller = viewer.id;
+                    state.maybeScrolled = true;
+                }
+                this.checkMode(name, state);
+            },
+            leave: () => {
+                if (left)
+                    return;
+                left = true;
+                viewer.listener = undefined;
+                state.viewers.delete(viewer.id);
+                // The one who scrolled everyone's view back is gone: nobody is left reading that scrollback.
+                if (state.scroller === viewer.id)
+                    void this.leaveCopyMode(name, state);
+                if (state.owner !== viewer.id)
+                    return;
+                let next;
+                for (const other of state.viewers.values())
+                    if (!next || other.activeAt > next.activeAt)
+                        next = other;
+                state.owner = undefined;
+                if (next)
+                    this.handOver(name, state, next);
+            },
+            onSizer: (listener) => {
+                if (left)
+                    return;
+                viewer.listener = listener;
+                viewer.lastSent = undefined;
+                this.send(state, viewer);
+            },
+        };
+    }
+    /** `viewer` sizes the window from now: copy mode is left (it froze everyone's view), the size follows. */
+    handOver(name, state, viewer) {
+        viewer.activeAt = ++this.seq;
+        const changed = state.owner !== viewer.id;
+        state.owner = viewer.id;
+        // Someone else's scroll no longer freezes the new sizing viewer's view; its own stays.
+        if (changed && (state.scrolled || state.maybeScrolled) && state.scroller !== viewer.id) {
+            void this.leaveCopyMode(name, state);
+        }
+        this.apply(name, state);
+        this.broadcast(state);
+    }
+    frameFor(state, viewer) {
+        const owner = state.owner === undefined ? undefined : state.viewers.get(state.owner);
+        if (!owner)
+            return undefined;
+        return {
+            type: 'sizer',
+            kind: owner.client?.kind ?? 'unknown',
+            label: owner.client?.label ?? null,
+            cols: owner.cols,
+            rows: owner.rows,
+            you: owner.id === viewer.id,
+            scrolled: state.scrolled,
+        };
+    }
+    /** Only to a viewer that said hello, and only what changed since its last frame. */
+    send(state, viewer) {
+        if (!viewer.client || !viewer.listener)
+            return;
+        const frame = this.frameFor(state, viewer);
+        if (!frame)
+            return;
+        const text = JSON.stringify(frame);
+        if (text === viewer.lastSent)
+            return;
+        viewer.lastSent = text;
+        try {
+            viewer.listener(frame);
+        }
+        catch {
+            /* a closing socket; its leave follows */
+        }
+    }
+    broadcast(state) {
+        for (const viewer of state.viewers.values())
+            this.send(state, viewer);
+    }
+    /** Leave copy mode (if the pane is in it) and tell every viewer. */
+    async leaveCopyMode(name, state) {
+        state.cancelModeCheck?.();
+        state.cancelModeCheck = undefined;
+        const { scroller, maybeScrolled } = state;
+        state.maybeScrolled = false;
+        state.scroller = undefined;
+        // Not left (tmux failed): who scrolled is kept (their leaving still exits it), and what the
+        // pane is in is read again, never assumed.
+        if (!(await this.options.tmux(leaveCopyModeArgs(name))).ok) {
+            state.scroller ??= scroller;
+            state.maybeScrolled ||= maybeScrolled;
+            this.checkMode(name, state);
+            return;
+        }
+        if (state.scrolled) {
+            state.scrolled = false;
+            this.broadcast(state);
+        }
+    }
+    /** Read the pane's copy mode once input has been quiet {@link MODE_CHECK_MS}; tell viewers when it changed. */
+    checkMode(name, state) {
+        state.cancelModeCheck?.();
+        state.cancelModeCheck = this.setTimer(() => {
+            state.cancelModeCheck = undefined;
+            void (async () => {
+                const read = await this.options.tmux(paneInModeArgs(name));
+                if (!read.ok)
+                    return;
+                const scrolled = (read.stdout ?? '').trim() === '1';
+                state.maybeScrolled = false;
+                if (!scrolled)
+                    state.scroller = undefined;
+                if (scrolled !== state.scrolled) {
+                    state.scrolled = scrolled;
+                    this.broadcast(state);
+                }
+            })();
+        }, MODE_CHECK_MS);
+    }
+    /**
+     * Size the window to its sizing viewer once the asks have been quiet {@link HANDOVER_DEBOUNCE_MS}:
+     * one `resize-window` at a time, the latest size last, none for a size it already has.
+     */
+    apply(name, state) {
+        const owner = state.owner === undefined ? undefined : state.viewers.get(state.owner);
+        if (!owner)
+            return;
+        state.desired = { cols: owner.cols, rows: owner.rows };
+        this.last = { ...state.desired };
+        state.cancelApply?.();
+        state.cancelApply = this.setTimer(() => {
+            state.cancelApply = undefined;
+            this.pump(name, state);
+        }, HANDOVER_DEBOUNCE_MS);
+    }
+    pump(name, state) {
+        if (state.applying)
+            return;
+        const run = async () => {
+            while (state.desired && key(state.desired) !== state.applied) {
+                const want = state.desired;
+                if (!(await this.options.tmux(resizeWindowArgs(name, want.cols, want.rows))).ok)
+                    return;
+                state.applied = key(want);
+            }
+        };
+        state.applying = run().finally(() => {
+            state.applying = undefined;
+        });
+    }
+    settle(name, state) {
+        const now = this.now();
+        state.settleDeadline ??= now + SETTLE_MAX_MS;
+        state.cancelSettle?.();
+        const wait = Math.max(0, Math.min(SETTLE_MS, state.settleDeadline - now));
+        state.cancelSettle = this.setTimer(() => void this.release(name, state), wait);
+    }
+    async release(name, state) {
+        if (state.settled)
+            return;
+        state.settled = true;
+        state.cancelSettle?.();
+        state.cancelFallback?.();
+        // At its size first: a debounced resize goes now, and the shell's first prompt is drawn once,
+        // at the size it keeps.
+        if (state.cancelApply) {
+            state.cancelApply();
+            state.cancelApply = undefined;
+            this.pump(name, state);
+        }
+        await state.applying;
+        await this.options.tmux(releaseHoldArgs(name));
+    }
+}