@prohost/cli 0.13.3 → 0.15.0

package/dist/codehost/terminals.js

@@ -0,0 +1,1027 @@
+/**
+ * The Mac's Code-thread terminals: one tmux window per thread, attached
+ * through a pty per viewer.
+ *
+ * - {@link CodeTerminals.start} handles `code_thread.start_requested`: a
+ *   worktree for the thread, then a window running the agent (`claude`,
+ *   `codex` or a shell) with `PROHOST_TERMINAL_ID` / `PROHOST_CODE_THREAD_ID`
+ *   in its environment — what makes the hooks fire for it and for nothing
+ *   else. When the agent exits, the window becomes a shell in the worktree; it
+ *   never just disappears under a viewer.
+ * - {@link CodeTerminals.input} handles `code_thread.input_requested`: the text
+ *   typed into a composer that isn't attached to the terminal, sent to the
+ *   pane as one paste plus Enter.
+ * - {@link CodeTerminals.attach} gives a viewer (relay or desktop) a byte
+ *   stream to one of a thread's windows.
+ * - {@link CodeTerminals.adopt} finds the threads a previous daemon started:
+ *   tmux owns their processes, so a daemon restart costs nothing.
+ *
+ * Every start and input is idempotent under redelivery: a window that exists
+ * is the thread already started.
+ */
+import { execFile } from 'node:child_process';
+import { closeSync, openSync, utimesSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { shellQuote } from '../agent/shell.js';
+import { worktreesRoot } from '../agent/worktrees.js';
+import { markTurn } from './activity.js';
+import { missingAgentReason } from './agents.js';
+import { claudeConfigDir, claudeTrusts, trustClaudeWorkspace } from './claude_trust.js';
+import { event } from './events.js';
+import { readHistory } from './history.js';
+import { CODE_THREAD_ID_ENV, TERMINAL_ID_ENV } from './hooks.js';
+import { MAX_OPEN_PTYS } from './pty.js';
+import { claudeSessionSince, isReady, markReady } from './ready.js';
+import { defaultSizeArgs, HOLD_OPTION, holdChannel, holdCommand, resizeWindowArgs, TerminalSizing } from './sizing.js';
+import { noteInputTakeover } from './sizing.js';
+import { attachArgs, baseArgs, clampDim, DEFAULT_COLS, DEFAULT_ROWS, hasSessionArgs, isCopyModeExitKey, isHumanInput, isTypedText, isInterruptInput, isScrollGesture, leaveCopyModeArgs, mayEnterCopyMode, paneInModeArgs, isValidId, killSessionArgs, listWindowsArgs, newSessionArgs, newWindowArgs, parseListWindows, sendTextCommands, setWindowMetaArgs, TERMINAL_WINDOWS, DAEMON_ONLY_ENV, paneEnv, viewSessionName, windowName, windowTarget, } from './tmux.js';
+export const CODE_AGENTS = ['claude_code', 'codex', 'shell'];
+export const GOAL_ENV = 'PROHOST_CODE_THREAD_GOAL';
+/** Window option set when the agent exits and its window becomes a shell. */
+export const EXITED_OPTION = '@prohost_exited';
+/**
+ * Window option that marks a relayed reply as possibly sitting in the agent's
+ * input unsubmitted. It is set before the reply's first keystroke reaches the
+ * pane and cleared only once its Enter went through, so a reply stopped half
+ * way — a revocation or `remote off` between the steps, a tmux error, the
+ * daemon dying — leaves it set. Relayed text is refused while it is set, so
+ * the next reply can't append to the leftover and submit both; the owner
+ * typing in a terminal attached to that window (where they see the input box)
+ * clears it.
+ */
+export const STAGED_OPTION = '@prohost_staged';
+/** Output held for a viewer whose socket isn't connected yet (tmux's first redraw). */
+const MAX_EARLY_OUTPUT_BYTES = 1024 * 1024;
+const MAX_GOAL_CHARS = 32_000;
+const MAX_INPUT_CHARS = 32_000;
+/** One Esc or Ctrl+C burst reports one interrupt. */
+const INTERRUPT_DEBOUNCE_MS = 2_000;
+/** Between a paste and its Enter, so the agent has taken the paste in. */
+const PASTE_SETTLE_MS = 150;
+export function execTmux(binary = 'tmux') {
+    return (args, stdin, timeoutMs = 10_000) => new Promise((resolve) => {
+        // The first call starts the server, whose panes inherit this env.
+        // Room for a viewer's scroll-back (`capture-pane`, up to 10,000 lines with their colours).
+        const options = { timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024, env: paneEnv(process.env) };
+        const child = execFile(binary, args, options, (error, stdout, stderr) => {
+            resolve({
+                ok: error === null,
+                stdout: String(stdout),
+                stderr: String(stderr) || (error?.message ?? ''),
+                ...(error && (error.killed || error.signal) ? { uncertain: true } : {}),
+            });
+        });
+        if (stdin !== undefined) {
+            child.stdin?.end(stdin);
+        }
+    });
+}
+/**
+ * Whether an event post's status settles it (see {@link StartResult}): the
+ * server applied it (2xx) or will refuse it the same way every time (404, 409,
+ * 422…). A 401 / 403 is the token — expired, or minted before a reconnect —
+ * and the next control-socket connect brings a fresh one, so like no answer
+ * at all (0, 408, 429, 5xx) it is retried.
+ */
+export function isDefinitive(status) {
+    if (status >= 200 && status < 300)
+        return true;
+    return status >= 400 && status < 500 && ![401, 403, 408, 429].includes(status);
+}
+/** Claude Code's flag for a thread started with `skipPermissions`: no permission prompt, ever. */
+export const CLAUDE_SKIP_PERMISSIONS_FLAG = '--dangerously-skip-permissions';
+/**
+ * Codex's (`codex --help`, 0.146): no approval prompt and no sandbox, as Claude Code's flag. Its
+ * `-a never` alone would keep the sandbox, where a command needing the network fails instead of asking.
+ */
+export const CODEX_SKIP_PERMISSIONS_FLAG = '--dangerously-bypass-approvals-and-sandbox';
+/** The shell command line a thread's agent window runs. */
+export function agentCommandLine(agent, options) {
+    // `--` first: a goal is the agent's prompt, never an option, however it
+    // starts (`--dangerously-skip-permissions`, or a word Codex would read as a
+    // subcommand).
+    const goal = options.hasGoal ? ` -- "$${GOAL_ENV}"` : '';
+    const skip = options.skipPermissions === true;
+    const shell = 'exec "${SHELL:-/bin/zsh}" -l';
+    if (agent === 'shell')
+        return shell;
+    const label = agent === 'codex' ? 'Codex' : 'Claude Code';
+    // Marks the window first: from here on it is a plain shell, and a reply
+    // relayed from ProhostAI must never be typed into it as a command
+    // (`input` and `approve` refuse a window carrying the mark).
+    const after = `tmux set-option -w ${EXITED_OPTION} 1 2>/dev/null; ` +
+        `printf '\\n[${label} exited — this window is now a shell in the thread worktree]\\n'; ${shell}`;
+    if (agent === 'codex') {
+        const flags = skip ? ` ${CODEX_SKIP_PERMISSIONS_FLAG}` : '';
+        return `codex${flags} -c ${shellQuote(options.codexNotify, 'darwin')}${goal}; ${after}`;
+    }
+    const claude = `command claude${skip ? ` ${CLAUDE_SKIP_PERMISSIONS_FLAG}` : ''} --settings`;
+    // A window that skips prompts reads the documents that also accept Claude Code's bypass warning.
+    const settings = (skip && options.claudeSkipSettings) || options.claudeSettings;
+    const invocationSettings = (skip && options.claudeInvocationSkipSettings) || options.claudeInvocationSettings;
+    if (invocationSettings && options.hookShim) {
+        const check = `${shellQuote(options.hookShim, 'darwin')} claude CheckInvocationProtocol`;
+        return `if ${check}; then PROHOST_INVOCATION_PROTOCOL=1 ${claude} ${shellQuote(invocationSettings, 'darwin')}${goal}; ` +
+            `else PROHOST_INVOCATION_PROTOCOL=0 ${claude} ${shellQuote(settings, 'darwin')}${goal}; fi; ${after}`;
+    }
+    return `PROHOST_INVOCATION_PROTOCOL=0 ${claude} ${shellQuote(settings, 'darwin')}${goal}; ${after}`;
+}
+/**
+ * A phrase as a first-run screen shows it: Claude Code wraps its own text inside a bordered box (a
+ * narrow window breaks it anywhere, and `capture-pane -J` joins only tmux's wraps), so words may be
+ * apart by any whitespace or the box's border.
+ */
+function screenPhrase(...phrases) {
+    const gap = String.raw `[\s│┃|]+`;
+    const escape = (word) => word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(phrases.map((phrase) => phrase.split(' ').map(escape).join(gap)).join('|'), 'i');
+}
+/** Claude Code's workspace trust dialog, as its first screen shows it. */
+const TRUST_SCREEN = screenPhrase('Is this a project you created or one you trust', 'Do you trust the files in this folder');
+/** How many times after launch the host looks for that dialog, and how far apart. */
+const TRUST_WATCH_ATTEMPTS = 30;
+/**
+ * A thread that skips prompts, once the trust dialog was said: how long (polls) it still looks for
+ * the bypass warning, which comes up only after that dialog is answered, however long that takes.
+ */
+const BYPASS_WATCH_ATTEMPTS = 600;
+const TRUST_POLL_MS = 1_000;
+/** What the thread says while Claude Code waits on its trust dialog. */
+export const TRUST_PROMPT_NOTE = 'Claude Code is asking whether to trust this folder before it starts. Answer in the terminal.';
+/**
+ * Claude Code's one-time warning before its first `--dangerously-skip-permissions` run on a login
+ * that never accepted it. A skipping window's `--settings` document accepts it (`hooks.ts`,
+ * `skipDangerousModePermissionPrompt`); this is the fallback for a Claude Code that shows it anyway:
+ * the thread says it waits on the person.
+ */
+const BYPASS_SCREEN = screenPhrase('In Bypass Permissions mode, Claude Code will not ask');
+/** What the thread says while Claude Code waits on that warning. */
+export const BYPASS_PROMPT_NOTE = 'Claude Code asks once to confirm it may run commands without asking. Answer in the terminal.';
+/**
+ * The environment a Code thread's Claude Code starts with, beyond its account's:
+ * no Claude in Chrome. A thread runs where nobody may be watching, and the
+ * "use your browser?" offer on first run would hold the goal back unseen.
+ */
+const CLAUDE_THREAD_ENV = { CLAUDE_CODE_ENABLE_CFC: '0' };
+/**
+ * The agent's own part of a thread window's environment: its account's login (`CLAUDE_CONFIG_DIR`
+ * and the like), then the thread's overrides, which a login's environment never undoes. The one
+ * builder for it: `startOnce` launches with it, and `adoptReadiness` reads the config dir from it.
+ */
+function agentWindowEnv(agent, accountEnv) {
+    return { ...stringEnv(accountEnv), ...(agent === 'claude_code' ? CLAUDE_THREAD_ENV : {}) };
+}
+export class CodeTerminals {
+    options;
+    records = new Map();
+    starting = new Map();
+    /**
+     * Older windows are adopted past trust by one pass that succeeds once per daemon start
+     * (`adoptReadiness`); a failed pass is forgotten and tried again by the next `adopt()`, or by a
+     * reply it would have let through. The pass in flight or done, so every `adopt()` (a concurrent
+     * one too) returns only once it has finished.
+     */
+    readinessAdoption;
+    lastInterrupt = new Map();
+    /** Per terminal: the tail of its typing queue (see {@link serialize}). */
+    typing = new Map();
+    openPtys = 0;
+    /** Who sizes each window, and what its viewers are told (`sizing.ts`). */
+    sizing;
+    log;
+    now;
+    sleep;
+    constructor(options) {
+        this.options = options;
+        this.log = options.log ?? (() => { });
+        this.now = options.now ?? Date.now;
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.sizing = new TerminalSizing({
+            tmux: (args) => this.tmux(args),
+            setTimer: options.setTimer,
+            now: this.now,
+            defaultSize: { cols: DEFAULT_COLS, rows: DEFAULT_ROWS },
+        });
+    }
+    isReady(terminalId) {
+        return this.options.ready ? this.options.ready(terminalId) : isReady(terminalId, { PROHOST_HOME: this.options.home });
+    }
+    isAuthorized() {
+        return this.options.authorized?.() ?? true;
+    }
+    canType() {
+        return this.isAuthorized() && (this.options.remoteControlAllowed?.() ?? true);
+    }
+    tmux(args, stdin, timeoutMs) {
+        return this.options.tmux([...baseArgs(this.options.socket, this.options.confPath), ...args], stdin, timeoutMs);
+    }
+    /** Threads this host knows about right now. */
+    list() {
+        // What a thread is, never how this host tracks its trust (`readyMark`, its Claude config dir).
+        return [...this.records.values()].map(({ terminalId, codeThreadId, agent, cwd, windows }) => ({
+            terminalId,
+            codeThreadId,
+            agent,
+            cwd,
+            windows: [...windows],
+        }));
+    }
+    /** Ptys open right now. Exposed for assertions. */
+    openPtyCount() {
+        return this.openPtys;
+    }
+    /** Re-read the windows tmux holds. Returns how many threads are known after. */
+    /**
+     * Run `work` after every earlier typing job for this terminal. A paste and
+     * its Enter (or an approval's keys) are one unit: two deliveries for one
+     * terminal never interleave into "first, second, Enter, Enter".
+     */
+    serialize(terminalId, work) {
+        const previous = this.typing.get(terminalId) ?? Promise.resolve();
+        const next = previous.then(work, work);
+        const tail = next.catch(() => undefined);
+        this.typing.set(terminalId, tail);
+        void tail.then(() => {
+            if (this.typing.get(terminalId) === tail)
+                this.typing.delete(terminalId);
+        });
+        return next;
+    }
+    /**
+     * Mark a thread's worktree lane as in use (`.last-used`, the marker every
+     * {@link WorktreeManager} prunes by), so a long-lived terminal's checkout is
+     * never removed as idle while its window lives — whichever lane's prepare
+     * happens to run the prune.
+     */
+    touchLane(record) {
+        // Only a lane this host made (`worktrees/<lane>/…`): a thread running in place in a folder
+        // has none, and nothing is ever written beside a folder of the owner's.
+        const root = worktreesRoot({ PROHOST_HOME: this.options.home });
+        const relative = path.relative(root, record.cwd);
+        const lane = relative.split(path.sep)[0];
+        if (!relative || path.isAbsolute(relative) || !lane || lane === '..' || lane === relative)
+            return;
+        const marker = path.join(root, lane, '.last-used');
+        const stamp = new Date(this.now());
+        try {
+            closeSync(openSync(marker, 'a'));
+            utimesSync(marker, stamp, stamp);
+        }
+        catch {
+            /* a lane that no longer exists has nothing to keep */
+        }
+    }
+    /** Refresh the lanes of threads whose windows tmux still has (adopt reconciles first). */
+    touchLiveLanes() {
+        for (const record of this.records.values())
+            this.touchLane(record);
+    }
+    /**
+     * The hourly keeper: re-read tmux, then mark only the threads it still holds
+     * as in use. A window or server that went away is dropped by the re-read, so
+     * its lane is left to age out and be pruned as usual.
+     */
+    async refreshLiveLanes() {
+        await this.adopt();
+    }
+    /**
+     * Apply the config just written to a server that is already running: tmux
+     * reads `-f` only when a server starts, and the persistent session keeps an
+     * upgraded host's old server (and its old settings) alive. With no server
+     * there is nothing to apply, and the next one starts with the file.
+     */
+    async reloadConfig() {
+        const reloaded = (await this.tmux(['source-file', this.options.confPath])).ok;
+        // A server started before `paneEnv` (by a daemon the desktop app ran on Electron) holds those
+        // in its global environment and copies them into every new window: taken out of it too.
+        if (reloaded)
+            for (const key of DAEMON_ONLY_ENV)
+                await this.tmux(['set-environment', '-g', '-u', key]);
+        return reloaded;
+    }
+    async adopt() {
+        const listed = await this.tmux(listWindowsArgs());
+        if (!listed.ok) {
+            // No server or no session: nothing survived, and nothing is wrong.
+            this.records.clear();
+            return 0;
+        }
+        const names = new Set();
+        const found = new Map();
+        const panes = new Map();
+        for (const window of parseListWindows(listed.stdout)) {
+            names.add(window.name);
+            // Left by an earlier daemon, perhaps still holding its shell: released in time all the same.
+            this.sizing.adopted(window.name);
+            if (window.meta && window.name === windowName(window.meta.terminalId, 'agent')) {
+                found.set(window.meta.terminalId, { ...window.meta, windows: ['agent'] });
+                if (window.panePid)
+                    panes.set(window.meta.terminalId, window.panePid);
+            }
+        }
+        for (const record of found.values()) {
+            if (names.has(windowName(record.terminalId, 'shell')))
+                record.windows.push('shell');
+        }
+        this.records.clear();
+        for (const [id, record] of found)
+            this.records.set(id, record);
+        // Once per daemon start: the windows an older build left behind are all there now. Started by
+        // the first call; every call waits for it, so none returns before those windows are marked. A
+        // pass that fails (a keychain still locked right after login) never fails an adopt: it is
+        // logged and forgotten, so the next adopt tries once more, rather than leaving those windows'
+        // replies refused until a restart.
+        if (!this.readinessAdoption) {
+            const attempt = this.adoptReadinessAll([...found.values()], panes).catch((err) => {
+                this.log(`    ! older code threads not checked for readiness: ${err instanceof Error ? err.message : String(err)}`);
+                if (this.readinessAdoption === attempt)
+                    this.readinessAdoption = undefined;
+            });
+            this.readinessAdoption = attempt;
+        }
+        await this.readinessAdoption;
+        this.touchLiveLanes();
+        return this.records.size;
+    }
+    /**
+     * The environment a Claude Code thread starts with: what `startOnce` hands its window, and so
+     * the only source of where that window's Claude Code keeps its sessions (`adoptReadiness`).
+     */
+    claudeLaunchEnv() {
+        const account = this.options.accountEnv?.('claude_code') ?? { ok: true, env: {} };
+        if (!account.ok)
+            return account;
+        return { ok: true, env: { ...(this.options.processEnv ?? process.env), ...agentWindowEnv('claude_code', account.env) } };
+    }
+    /**
+     * Older windows, all at once: one `ps` for every candidate's start (bounded, never one call per
+     * window), then the evidence check for each (`adoptReadiness`).
+     */
+    async adoptReadinessAll(records, panes) {
+        const candidates = records.filter((record) => record.agent === 'claude_code' && !record.readyMark && this.isReady(record.terminalId) === false);
+        const pids = candidates.map((record) => panes.get(record.terminalId)).filter((pid) => pid !== undefined);
+        if (pids.length === 0)
+            return;
+        // That window's Claude Code runs on the config this host launches Claude threads with: the
+        // same function builds the launch env, so the dir looked in can't drift from the dir used.
+        // Read before `ps`, which a pass that can't go on never needs to run.
+        const launch = this.claudeLaunchEnv();
+        // A failure, not "nothing to adopt": the pass is tried again (`adopt`), and says why.
+        if (!launch.ok)
+            throw new Error(`the Claude account's environment isn't available (${launch.reason})`);
+        const dir = claudeConfigDir(launch.env);
+        const starts = await (this.options.paneStarts ?? paneStarts)(pids);
+        for (const record of candidates) {
+            const pid = panes.get(record.terminalId);
+            const startedAtMs = pid === undefined ? undefined : starts.get(pid);
+            if (startedAtMs !== undefined)
+                this.adoptReadiness(record, dir, startedAtMs);
+        }
+    }
+    /**
+     * A Claude window from a build before the ready mark (an upgrade): its Claude Code may be long
+     * past trust, but no hook runs to say so until a reply types, which the missing mark refuses.
+     * Only such a window (no `readyMark` in its meta: this build's windows get the mark from their
+     * first hook, never from here), by a pass that succeeds once per daemon start (and is tried
+     * again after a failure; each try judges afresh), and only on evidence tied to it: a
+     * transcript in that window's Claude config dir (`claudeLaunchEnv`), naming its exact folder,
+     * written since the window's process started (`claudeSessionSince`). A window still at its
+     * trust dialog has none and stays refused. Never judged from the screen.
+     */
+    adoptReadiness(record, configDir, startedAtMs) {
+        if (!(this.options.claudeSessionSince ?? claudeSessionSince)(record.cwd, configDir, startedAtMs))
+            return;
+        if (markReady(record.terminalId, { PROHOST_HOME: this.options.home })) {
+            this.log(`    ⚙ code thread ${record.codeThreadId.slice(0, 12)}: adopted past Claude Code's trust dialog (its session exists)`);
+        }
+    }
+    async ensureSession() {
+        if ((await this.tmux(hasSessionArgs())).ok)
+            return true;
+        const created = await this.tmux(newSessionArgs(this.options.home));
+        // Another start may have created it a moment ago.
+        return created.ok || (await this.tmux(hasSessionArgs())).ok;
+    }
+    async start(request) {
+        if (!isValidId(request.terminalId) || !isValidId(request.codeThreadId)) {
+            // Nothing to report to, and a redelivery would be the same: settled.
+            return { ok: false, reason: 'invalid terminal or thread id', reported: true };
+        }
+        const pending = this.starting.get(request.terminalId);
+        if (pending)
+            return pending;
+        const work = this.startOnce(request).finally(() => this.starting.delete(request.terminalId));
+        this.starting.set(request.terminalId, work);
+        return work;
+    }
+    async startOnce(request) {
+        const reportStart = async () => isDefinitive(await this.options.events.post(request.codeThreadId, event('start', { terminalId: request.terminalId, agent: request.agent, branch: request.branch ?? null }, this.now())));
+        await this.adopt();
+        // A redelivery (the first outcome never reached the server) reports again.
+        if (this.records.has(request.terminalId))
+            return { ok: true, adopted: true, reported: await reportStart() };
+        const fail = async (reason) => {
+            this.log(`    ✗ code thread ${request.codeThreadId.slice(0, 12)} could not start: ${reason}`);
+            const status = await this.options.events.post(request.codeThreadId, event('failed', { reason }, this.now()));
+            return { ok: false, reason, reported: isDefinitive(status) };
+        };
+        if (!CODE_AGENTS.includes(request.agent))
+            return fail(`unknown agent ${JSON.stringify(request.agent)}`);
+        // Its binary isn't here: refused with why (the thread shows it), never a window saying
+        // `command not found`. A server that read this Mac's `code_thread_agent_*` never asks.
+        if (request.agent !== 'shell' && this.options.agentInstalled && !this.options.agentInstalled(request.agent)) {
+            return fail(missingAgentReason(request.agent));
+        }
+        // A raw shell is remote control of this Mac: never opened with the switch off. Reported as a
+        // failed start (never acked unhandled), so its thread doesn't wait in `starting` for good.
+        // A folder start's shell is the exception: it opens in a folder this Mac's owner opened here,
+        // and with the switch off nothing from ProhostAI types into it (replies refuse a shell, the
+        // relay refuses every viewer); only the desktop app on this Mac attaches (`local_server.ts`).
+        if (request.agent === 'shell' && request.folder === undefined && !this.canType()) {
+            return fail('remote terminal access is off on this Mac (prohost agent code-host remote on)');
+        }
+        // Never a silent fall back to another login: a thread spends the
+        // subscription this agent reports, or it doesn't start.
+        const account = this.options.accountEnv?.(request.agent) ?? { ok: true, env: {} };
+        if (!account.ok)
+            return fail(account.reason);
+        const checkouts = this.options.checkouts;
+        const checkout = request.folder === undefined
+            ? await checkouts.prepare(request.repo, request.terminalId, request.branch)
+            : checkouts.prepareFolder
+                ? await checkouts.prepareFolder(request.folder, request.terminalId, {
+                    separateCopy: request.separateCopy === true,
+                    branch: request.branch,
+                })
+                : { ok: false, reason: 'This Mac can’t start Code threads in a folder.' };
+        if (!checkout.ok)
+            return fail(checkout.reason);
+        if (!(await this.ensureSession()))
+            return fail('tmux is not available on this Mac (brew install tmux)');
+        const goal = request.goal.slice(0, MAX_GOAL_CHARS);
+        const name = windowName(request.terminalId, 'agent');
+        if (!this.isAuthorized())
+            return fail('ProhostAI no longer authorizes this pairing');
+        if (request.agent === 'claude_code')
+            await this.trustOwnWorktree(checkout, account.env);
+        // Started at the size it will most likely be viewed at (the last one a viewer sized a window
+        // to), not tmux's 80x24: every resize after it makes a shell redraw its prompt, and a TUI its screen.
+        const size = this.sizing.lastSize();
+        await this.tmux(defaultSizeArgs(size.cols, size.rows));
+        // Never with remote control off: then nothing from ProhostAI may run a command here unasked
+        // (a goal is the agent's first instruction). The server only asks; the Mac decides.
+        const skips = request.skipPermissions === true && request.agent !== 'shell' && this.canType();
+        const command = agentCommandLine(request.agent, { ...this.options.hookFiles, hasGoal: goal.length > 0, skipPermissions: skips });
+        // A shell thread's shell waits for its first viewer's size to settle (`sizing.ts`): one prompt.
+        const held = request.agent === 'shell';
+        const created = await this.tmux(newWindowArgs({
+            name,
+            cwd: checkout.path,
+            env: {
+                ...agentWindowEnv(request.agent, account.env),
+                PROHOST_HOME: this.options.home,
+                [TERMINAL_ID_ENV]: request.terminalId,
+                [CODE_THREAD_ID_ENV]: request.codeThreadId,
+                ...(goal ? { [GOAL_ENV]: goal } : {}),
+            },
+            command: held ? holdCommand(name, command) : command,
+        }));
+        if (!created.ok)
+            return fail(`tmux could not open the thread's window (${created.stderr.trim()})`);
+        // At that size whatever is attached (tmux sizes a new window from the viewer active last), and
+        // manual from now on: resize-window sets `window-size manual` on the window.
+        await this.tmux(resizeWindowArgs(name, size.cols, size.rows));
+        this.sizing.created(name, { held: held && (await this.markHeld(name)) });
+        const meta = {
+            terminalId: request.terminalId,
+            codeThreadId: request.codeThreadId,
+            agent: request.agent,
+            cwd: checkout.path,
+            // This build tracks trust with the ready mark: this window is never adopted past trust.
+            readyMark: true,
+        };
+        for (const args of setWindowMetaArgs(name, meta))
+            await this.tmux(args);
+        this.records.set(request.terminalId, { ...meta, windows: ['agent'] });
+        this.log(`    ▶ code thread ${request.codeThreadId.slice(0, 12)}: ${request.agent} in ${checkout.path}`);
+        if (checkout.folder)
+            checkouts.folderStarted?.(checkout.folder);
+        // Started on a goal, Codex is working from its first second (keep-awake, `activity.ts`); its hook
+        // says only when a turn ends. Claude Code's own prompt hook marks its turns.
+        if (goal && request.agent === 'codex')
+            markTurn(request.terminalId, true, { PROHOST_HOME: this.options.home });
+        const reported = await reportStart();
+        // Claude Code may ask first (not pre-trusted, or the record didn't hold), and no hook says
+        // so: every new Claude window is watched, and the thread is told when it waits on it.
+        if (request.agent === 'claude_code')
+            void this.watchTrustPrompt(request.codeThreadId, request.terminalId, name, skips);
+        return { ok: true, adopted: false, reported };
+    }
+    /**
+     * A worktree this host made for the thread opens without Claude Code's trust dialog: no hook
+     * fires for it, so the thread would read `Working` while it waits for someone at the Mac.
+     * Only a worktree under this home's own `worktrees/`, never a checkout it was handed.
+     */
+    async trustOwnWorktree(checkout, accountEnv) {
+        const root = worktreesRoot({ ...process.env, PROHOST_HOME: this.options.home });
+        const relative = path.relative(root, checkout.path);
+        if (!relative || relative.startsWith('..') || path.isAbsolute(relative))
+            return false;
+        const env = { ...process.env, ...stringEnv(accountEnv) };
+        // Only what the owner already trusts: their checkout (they accepted Claude Code's dialog
+        // there), and nothing it doesn't already have (`fromLocalHistory`, from the commit checked
+        // out): no remote branch's `.claude/` hooks that nobody here has seen.
+        if (checkout.fromLocalHistory !== true || !(this.options.trusts ?? claudeTrusts)(checkout.source, env))
+            return false;
+        const trusted = await (this.options.trustWorkspace ?? trustClaudeWorkspace)(checkout.path, env);
+        if (!trusted)
+            this.log(`    ! could not pre-trust ${checkout.path} for Claude Code — it will ask on first run`);
+        return trusted;
+    }
+    /**
+     * Watch a new Claude Code window for its first-run screens, only to tell the thread it waits on
+     * one (needs-you, not Working): the folder's trust dialog, and, for a thread that skips permission
+     * prompts, Claude Code's one-time bypass warning (it comes up after the trust dialog is answered,
+     * so it is looked for longer once that was said). Each is said once. It never decides whether a
+     * reply types: the ready mark does.
+     */
+    async watchTrustPrompt(codeThreadId, terminalId, name, skips = false) {
+        const screens = [
+            { screen: TRUST_SCREEN, note: TRUST_PROMPT_NOTE, log: 'asks whether to trust its folder' },
+            ...(skips
+                ? [{ screen: BYPASS_SCREEN, note: BYPASS_PROMPT_NOTE, log: 'asks to confirm running without permission prompts' }]
+                : []),
+        ];
+        const said = new Set();
+        let attempts = this.options.trustWatchAttempts ?? TRUST_WATCH_ATTEMPTS;
+        for (let attempt = 0; attempt < attempts; attempt += 1) {
+            // A hook ran: it is past every first-run screen, whatever the screen shows.
+            if (this.isReady(terminalId) !== false)
+                return;
+            const pane = await this.tmux(['capture-pane', '-p', '-J', '-t', windowTarget(name)]);
+            if (!pane.ok)
+                return;
+            const shown = screens.find((entry) => !said.has(entry.note) && entry.screen.test(pane.stdout));
+            // Re-checked after the capture: a hook that ran meanwhile means the screen was just answered.
+            if (shown && this.isReady(terminalId) === false) {
+                this.log(`    ! code thread ${codeThreadId.slice(0, 12)}: Claude Code ${shown.log}`);
+                await this.options.events.post(codeThreadId, event('stop', { finalText: shown.note, question: true }, this.now()));
+                said.add(shown.note);
+                if (said.size === screens.length)
+                    return;
+                // The next screen waits on this one's answer: look for it from now, for longer.
+                attempts = attempt + 1 + Math.max(attempts, BYPASS_WATCH_ATTEMPTS);
+            }
+            await this.sleep(TRUST_POLL_MS);
+        }
+    }
+    async known(terminalId) {
+        if (!isValidId(terminalId))
+            return undefined;
+        if (!this.records.has(terminalId))
+            await this.adopt();
+        return this.records.get(terminalId);
+    }
+    /**
+     * Whether the thread's agent window runs an agent that composer text and
+     * approval keys may reach. A Claude Code or Codex that exited left a shell
+     * behind (see {@link agentCommandLine}); a `shell` thread is a shell from
+     * the start. Neither ever takes relayed text.
+     */
+    async agentRunning(record) {
+        // A shell thread's window IS a shell: text relayed into it would run as a
+        // command. Remote typing into a shell happens only over an attached
+        // terminal (owner-only, remote switch on), never through composer relay.
+        if (record.agent === 'shell')
+            return false;
+        const shown = await this.tmux(['show-options', '-wqv', '-t', windowTarget(windowName(record.terminalId, 'agent')), EXITED_OPTION]);
+        return shown.ok && shown.stdout.trim() !== '1';
+    }
+    /** Send composer text to the thread's agent. False when the thread isn't here or its agent has exited. */
+    async input(request, outcome = {}) {
+        if (!isValidId(request.terminalId))
+            return false;
+        return this.serialize(request.terminalId, () => this.inputNow(request, outcome));
+    }
+    async inputNow(request, outcome) {
+        const record = await this.known(request.terminalId);
+        if (!record || record.codeThreadId !== request.codeThreadId) {
+            // Its window is gone (the Mac restarted, the session was closed): handed back, never "done".
+            this.log(`    ! reply for code thread ${request.codeThreadId.slice(0, 12)} not typed: its terminal is gone`);
+            outcome.refused = 'terminal_gone';
+            return false;
+        }
+        this.touchLane(record);
+        if (!(await this.agentRunning(record))) {
+            this.log(`    ! reply for code thread ${request.codeThreadId.slice(0, 12)} not typed: its window is a shell, not an agent`);
+            outcome.refused = 'shell_window';
+            return false;
+        }
+        if (record.agent === 'claude_code') {
+            // Typed only once a hook has run in the window (`ready.ts`): before that its trust dialog
+            // is up or about to be drawn, and an Enter would answer it. Never judged from the screen.
+            let ready = this.isReady(record.terminalId);
+            if (ready === false && !record.readyMark) {
+                // A window an older build started: its readiness pass may be running, or have failed
+                // (then this tries it once more, now, rather than at the next adopt).
+                await (this.readinessAdoption ?? this.adopt());
+                ready = this.isReady(record.terminalId);
+            }
+            if (ready === undefined) {
+                outcome.retry = true;
+                return false;
+            }
+            if (!ready) {
+                this.log(`    ! reply for code thread ${request.codeThreadId.slice(0, 12)} not typed: no Claude Code hook has run in its ` +
+                    'window yet (still starting, or a question in its terminal; if hooks are off in Claude Code\'s settings, ' +
+                    'replies from ProhostAI can\'t be typed here)');
+                outcome.refused = 'trust_prompt';
+                return false;
+            }
+        }
+        const target = windowTarget(windowName(record.terminalId, 'agent'));
+        const leftover = await this.tmux(['show-options', '-wqv', '-t', target, STAGED_OPTION]);
+        if (leftover.ok && leftover.stdout.trim() === '1') {
+            this.log(`    ! reply for code thread ${request.codeThreadId.slice(0, 12)} not typed: an earlier reply was left ` +
+                'unsent in its input — type in its terminal to continue');
+            outcome.refused = 'reply_interrupted';
+            return false;
+        }
+        const commands = sendTextCommands(windowName(record.terminalId, 'agent'), request.text.slice(0, MAX_INPUT_CHARS));
+        /** The window carries {@link STAGED_OPTION} for this reply. */
+        let staged = false;
+        /** A step that can reach the agent's input box was sent (its outcome may be unknown). */
+        let reached = false;
+        for (const command of commands) {
+            if (command.args[0] === 'send-keys' && command.args.includes('Enter') && commands.length > 2) {
+                await this.sleep(PASTE_SETTLE_MS);
+            }
+            const touchesPane = command.args[0] !== 'load-buffer';
+            if (touchesPane && !staged) {
+                // Staged before the first keystroke, never after a failure: whatever
+                // stops this reply from here on leaves the window refusing relays.
+                if (!this.canType()) {
+                    outcome.refused = 'remote_terminal_disabled';
+                    return false;
+                }
+                staged = (await this.tmux(['set-option', '-w', '-t', target, STAGED_OPTION, '1'])).ok;
+                if (!staged) {
+                    outcome.retry = true;
+                    return false;
+                }
+                // Scrolled back, the pane would read the reply as copy-mode keys: it leaves copy mode first.
+                // Best effort; nothing typed yet.
+                if ((await this.tmux(leaveCopyModeArgs(windowName(record.terminalId, 'agent')))).ok) {
+                    this.sizing.leftCopyMode(windowName(record.terminalId, 'agent'));
+                }
+            }
+            // Before every step, not once: a revocation during a paste or its settle
+            // delay stops the rest (no Enter submits what was pasted).
+            const result = this.canType() ? await this.tmux(command.args, command.stdin) : undefined;
+            // Reached the pane only if the step ran: it succeeded, or was killed after it started. A clean
+            // failure (tmux exited with an error, or never started) touched nothing, so it is retried.
+            if (touchesPane && result && (result.ok || result.uncertain))
+                reached = true;
+            if (!result?.ok) {
+                if (reached) {
+                    this.leaveStaged(request);
+                    outcome.refused = 'reply_interrupted';
+                }
+                else if (staged) {
+                    // Nothing was sent to the pane: the input box is as it was.
+                    await this.tmux(['set-option', '-wu', '-t', target, STAGED_OPTION]);
+                    if (!result)
+                        outcome.refused = 'remote_terminal_disabled';
+                    else
+                        outcome.retry = true;
+                }
+                else {
+                    outcome.retry = true;
+                }
+                return false;
+            }
+        }
+        // Submitted: the agent took the input box's contents as a turn.
+        if (staged)
+            await this.tmux(['set-option', '-wu', '-t', target, STAGED_OPTION]);
+        // A reply submitted to Codex is a turn begun (its hook says only when one ends) — unless it is a
+        // slash command (`/status`, `/diff`), which starts no turn and would never be ended.
+        if (commands.length > 0 && record.agent === 'codex' && !request.text.trimStart().startsWith('/')) {
+            markTurn(record.terminalId, true, { PROHOST_HOME: this.options.home });
+        }
+        return commands.length > 0;
+    }
+    /**
+     * A reply stopped after a step that can reach the agent's input box, before
+     * its Enter went through. Nothing is pressed to take it back: no keystroke
+     * from out here can tell the reply apart from what was in the box already —
+     * a draft typed before, or one the agent put back — so clearing it would
+     * erase that too. The window stays staged until the owner types in a
+     * terminal attached to it, where they see the input box. The delivery is reported unhandled (acked 204), never
+     * retried blind.
+     */
+    leaveStaged(request) {
+        this.log(`    ! reply for code thread ${request.codeThreadId.slice(0, 12)} stopped before it was sent and may be ` +
+            'left in its input; type in its terminal to continue');
+    }
+    /**
+     * Mark a window just created with {@link holdCommand} as held, so its release signals it. When
+     * the mark can't be set, nothing would ever signal it: its shell is released now, unheld.
+     */
+    async markHeld(name) {
+        if ((await this.tmux(['set-option', '-w', '-t', windowTarget(name), HOLD_OPTION, '1'])).ok)
+            return true;
+        await this.tmux(['wait-for', '-S', holdChannel(name)]);
+        return false;
+    }
+    /** The thread's shell window, made at `size` (its first viewer's) the first time someone asks. */
+    async ensureShellWindow(record, size) {
+        if (record.windows.includes('shell'))
+            return true;
+        const name = windowName(record.terminalId, 'shell');
+        await this.tmux(defaultSizeArgs(size.cols, size.rows));
+        const created = await this.tmux(newWindowArgs({
+            name,
+            cwd: record.cwd,
+            env: { PROHOST_HOME: this.options.home },
+            // Its first prompt waits for this viewer's size to settle (`sizing.ts`).
+            command: holdCommand(name, 'exec "${SHELL:-/bin/zsh}" -l'),
+        }));
+        if (created.ok) {
+            await this.tmux(resizeWindowArgs(name, size.cols, size.rows));
+            this.sizing.created(name, { held: await this.markHeld(name) });
+        }
+        // "duplicate window": a concurrent attach made it.
+        if (!created.ok)
+            await this.adopt();
+        const current = this.records.get(record.terminalId);
+        if (created.ok && current && !current.windows.includes('shell'))
+            current.windows.push('shell');
+        return created.ok || Boolean(current?.windows.includes('shell'));
+    }
+    noteInterrupt(record) {
+        // Esc / Ctrl+C ends a turn without Claude Code's Stop hook: no longer working (keep-awake).
+        markTurn(record.terminalId, false, { PROHOST_HOME: this.options.home });
+        const now = this.now();
+        // tmux may consume these bytes itself; only agent hook progress clears a menu guard.
+        if (now - (this.lastInterrupt.get(record.terminalId) ?? 0) < INTERRUPT_DEBOUNCE_MS)
+            return;
+        this.lastInterrupt.set(record.terminalId, now);
+        void this.options.events.post(record.codeThreadId, event('interrupted', {}, now));
+    }
+    async attach(request) {
+        if (!TERMINAL_WINDOWS.has(request.window))
+            return { ok: false, reason: 'invalid_window' };
+        const record = await this.known(request.terminalId);
+        if (!record)
+            return { ok: false, reason: 'unknown_terminal' };
+        this.touchLane(record);
+        const spawn = this.options.spawnPty();
+        if (!spawn)
+            return { ok: false, reason: 'pty_unavailable' };
+        if (this.openPtys >= MAX_OPEN_PTYS)
+            return { ok: false, reason: 'busy' };
+        const size = { cols: clampDim(request.cols, DEFAULT_COLS), rows: clampDim(request.rows, DEFAULT_ROWS) };
+        if (request.window === 'shell' && !(await this.ensureShellWindow(record, size))) {
+            return { ok: false, reason: 'unknown_terminal' };
+        }
+        const name = windowName(record.terminalId, request.window);
+        const view = viewSessionName();
+        let pty;
+        try {
+            pty = spawn(this.options.tmuxBinary ?? 'tmux', [...baseArgs(this.options.socket, this.options.confPath), ...attachArgs(name, view)], {
+                name: 'xterm-256color',
+                cols: size.cols,
+                rows: size.rows,
+                cwd: os.homedir(),
+                env: paneEnv({ ...stringEnv(process.env), TERM: 'xterm-256color' }),
+            });
+        }
+        catch (err) {
+            this.log(`    ! terminal attach failed: ${err instanceof Error ? err.message : String(err)}`);
+            return { ok: false, reason: 'pty_unavailable' };
+        }
+        this.openPtys += 1;
+        const watchOnly = request.mode === 'watch';
+        const sizer = this.sizing.join(name, { ...size, watch: watchOnly });
+        let closed = false;
+        const exitListeners = [];
+        // Listen from the first byte: tmux draws the screen as it attaches, and a
+        // relay viewer's socket connects only after this returns. Held (bounded)
+        // until the stream's consumer subscribes, then replayed in order.
+        let consumer;
+        let early = [];
+        let earlyBytes = 0;
+        pty.onData((data) => {
+            if (closed)
+                return;
+            const chunk = Buffer.from(data, 'utf8');
+            if (consumer) {
+                consumer(chunk);
+                return;
+            }
+            earlyBytes += chunk.length;
+            early.push(chunk);
+            while (earlyBytes > MAX_EARLY_OUTPUT_BYTES && early.length > 1)
+                earlyBytes -= early.shift().length;
+        });
+        const close = () => {
+            if (closed)
+                return;
+            closed = true;
+            this.openPtys -= 1;
+            sizer.leave();
+            try {
+                pty.kill();
+            }
+            catch {
+                /* already gone */
+            }
+            // destroy-unattached normally reaps it; this covers a pty killed before tmux attached.
+            void this.tmux(killSessionArgs(view));
+        };
+        pty.onExit(() => {
+            close();
+            for (const listener of exitListeners)
+                listener();
+        });
+        const isAgent = request.window === 'agent';
+        let tookOver = false;
+        /** A clear is queued and its result not yet known. */
+        let takingOver = false;
+        /** A person typed while that clear was in flight. */
+        let typedWhileTaking = false;
+        /** One chunk of a person's (or their emulator's) input, into the pane. */
+        const deliver = (data) => {
+            if (closed)
+                return;
+            if (isAgent && !tookOver && !takingOver && isHumanInput(data)) {
+                // The first keystroke from a person typing in the agent's window takes over whatever
+                // a half-sent reply left in its input box: they are at it, so relays may resume. Not
+                // an attach that fails, a socket that never connects, a viewer who leaves without
+                // typing, or the emulator's own reports (focus, size, mouse, replies); those leave the
+                // guard in place. Queued behind the reply in flight, if any, so one that stops after
+                // this still stages the window. Taken over only once the clear went through: a failed
+                // one is tried again at the next keystroke.
+                takingOver = true;
+                const target = windowTarget(windowName(record.terminalId, 'agent'));
+                void this.serialize(record.terminalId, async () => {
+                    try {
+                        // Typed again while a clear was in flight and it failed: try again in this same
+                        // queued job, never behind later replies (a retry there could lift a newer guard).
+                        for (;;) {
+                            typedWhileTaking = false;
+                            tookOver = (await this.tmux(['set-option', '-wu', '-t', target, STAGED_OPTION])).ok;
+                            if (tookOver || !typedWhileTaking || closed)
+                                break;
+                        }
+                    }
+                    finally {
+                        takingOver = false;
+                    }
+                });
+            }
+            else if (isAgent && !tookOver && takingOver && isHumanInput(data)) {
+                typedWhileTaking = true;
+            }
+            // A wheel step, a drag or the prefix key: the pane may be in (or have left) copy mode. While
+            // it may be, a keystroke moves it too; an emulator report (focus, a reply) only re-reads it.
+            // Only a scroll (or a keystroke in the scrollback) makes this viewer the one who scrolled; a
+            // click or a report just re-reads the mode.
+            if (mayEnterCopyMode(data))
+                sizer.scrolled(isScrollGesture(data));
+            else if (this.sizing.mayBeScrolled(name))
+                sizer.scrolled(isHumanInput(data));
+            pty.write(Buffer.from(data).toString('utf8'));
+            if (isAgent && isInterruptInput(data))
+                this.noteInterrupt(record);
+        };
+        /** Input held while the pane leaves copy mode, in order; `undefined` when none is. */
+        let held;
+        const stream = {
+            onData: (listener) => {
+                consumer = listener;
+                const buffered = early;
+                early = [];
+                earlyBytes = 0;
+                for (const chunk of buffered)
+                    listener(chunk);
+            },
+            onExit: (listener) => exitListeners.push(listener),
+            write: (data) => {
+                if (closed || watchOnly || data.length === 0)
+                    return;
+                if (held) {
+                    held.push(data);
+                    return;
+                }
+                // Navigation keys (arrows, paging, other escape sequences and control keys) still move
+                // through the scrollback of the viewer who scrolled; only text leaves copy mode on its way
+                // to the agent. Anything another viewer types leaves someone else's copy mode first.
+                const scrolled = this.sizing.mayBeScrolled(name);
+                const othersScroll = scrolled && !sizer.isScroller() && isHumanInput(data);
+                if (!scrolled || (!othersScroll && !(isTypedText(data) || isCopyModeExitKey(data)))) {
+                    // Focusing this terminal sizes the window to it; typing does once the sizing viewer is idle (`sizing.ts`).
+                    noteInputTakeover(sizer, data);
+                    deliver(data);
+                    return;
+                }
+                // Someone scrolled back since the last keystroke: in copy mode, text typed would be read
+                // as copy-mode keys and never reach the agent. Leave it first; q / Esc / Ctrl+C pressed in
+                // it only leave it, as they always did. The claim waits until then: a handover leaves copy
+                // mode too, and would turn that q into a keystroke.
+                held = [data];
+                void (async () => {
+                    const read = await this.tmux(paneInModeArgs(name));
+                    const inMode = read.stdout.trim() === '1';
+                    // Out of copy mode only once tmux says so: a read or a cancel it refused leaves it as it was.
+                    const left = read.ok && (!inMode || (await this.tmux(['send-keys', '-X', '-t', windowTarget(name), 'cancel'])).ok);
+                    if (left)
+                        this.sizing.leftCopyMode(name);
+                    noteInputTakeover(sizer, data);
+                    const pending = held ?? [];
+                    held = undefined;
+                    pending.forEach((chunk, index) => {
+                        if (index === 0 && inMode && isCopyModeExitKey(chunk))
+                            return;
+                        if (index > 0)
+                            noteInputTakeover(sizer, chunk);
+                        deliver(chunk);
+                    });
+                })();
+            },
+            resize: (cols, rows) => {
+                if (closed)
+                    return;
+                const next = { cols: clampDim(cols, DEFAULT_COLS), rows: clampDim(rows, DEFAULT_ROWS) };
+                try {
+                    pty.resize(next.cols, next.rows);
+                }
+                catch {
+                    /* pty gone */
+                }
+                sizer.resize(next.cols, next.rows);
+            },
+            close,
+            hello: (client) => {
+                if (!closed)
+                    sizer.hello(client);
+            },
+            claim: () => {
+                if (!closed)
+                    sizer.claim();
+            },
+            onSizer: (listener) => sizer.onSizer(listener),
+            history: (lines) => closed ? Promise.resolve({ ok: false, error: 'unavailable' }) : readHistory((args) => this.tmux(args), name, lines),
+        };
+        return { ok: true, stream };
+    }
+}
+function stringEnv(env) {
+    const out = {};
+    for (const [key, value] of Object.entries(env))
+        if (typeof value === 'string')
+            out[key] = value;
+    return out;
+}
+/** `[[dd-]hh:]mm:ss` from `ps -o etime` as seconds, or `undefined`. */
+function etimeSeconds(etime) {
+    const match = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(etime.trim());
+    if (!match)
+        return undefined;
+    const [, days = '0', hours = '0', minutes = '0', seconds = '0'] = match;
+    return ((Number(days) * 24 + Number(hours)) * 60 + Number(minutes)) * 60 + Number(seconds);
+}
+/**
+ * When each of `pids` started, from one `ps -o pid=,etime=` (bounded, asynchronous: the daemon
+ * keeps serving meanwhile). From elapsed time, which no timezone can shift, a second early since
+ * `etime` drops the part of the current second already gone. A pid `ps` doesn't list is left out
+ * (`ps` exits 1 with nothing on stderr when none of them run). Rejects on any other outcome (it
+ * timed out, was killed, couldn't start, exited with another status, or wrote an error such as a
+ * bad option's usage, which also exits 1), so the caller tries again rather than taking "none
+ * started".
+ */
+export function paneStarts(pids, now = Date.now(), run = execFile) {
+    return new Promise((resolve, reject) => {
+        run('ps', ['-o', 'pid=,etime=', '-p', pids.join(',')], { timeout: 2_000 }, (error, stdout, stderr) => {
+            // `code` is the exit status (a number) when ps ran, or an errno string when it couldn't start.
+            const failure = error;
+            // Exit 1 with a silent stderr is `ps -p` finding none of the pids running. Nothing else is
+            // an answer: a bad option exits 1 too, but prints its usage.
+            if (failure && (failure.code !== 1 || String(stderr ?? '').trim() !== '')) {
+                reject(new Error(`ps did not answer: ${failure.message}`));
+                return;
+            }
+            const starts = new Map();
+            for (const line of String(stdout ?? '').split('\n')) {
+                const [pid, etime] = line.trim().split(/\s+/);
+                const seconds = etime ? etimeSeconds(etime) : undefined;
+                if (pid && /^\d+$/.test(pid) && seconds !== undefined) {
+                    starts.set(Number(pid), Math.floor(now / 1000) * 1000 - (seconds + 1) * 1000);
+                }
+            }
+            resolve(starts);
+        });
+    });
+}