handmux 0.26.0 → 0.27.2

package/dist/src/codexAppServer.js

@@ -15,6 +15,7 @@ const MAX_SUBMISSION_RECEIPTS = 256;
 const SUBMISSION_RECEIPT_TTL_MS = 24 * 60 * 60 * 1_000;
 const MAX_STREAM_EVENTS = 512;
 const MAX_STREAM_MESSAGE_IDS = 100;
+const MAX_COMPACTOR_ITEM_KEYS = 128;
 const MAX_OBSERVATION_SETUP_EVENTS = 512;
 const MAX_GOAL_READ_ATTEMPTS = 3;
 const CONTROL_TURN_LIMIT = 2;
@@ -41,6 +42,20 @@ const RESUME_SNAPSHOT_INVALIDATING_METHODS = new Set([
     'thread/compacted',
     'thread/started',
 ]);
+function compactorItemKey(turnId, itemId) {
+    return `${turnId}\0${itemId}`;
+}
+function rememberCompactorItem(state, turnId, itemId) {
+    const key = compactorItemKey(turnId, itemId);
+    state.compactorItemKeys.delete(key);
+    state.compactorItemKeys.add(key);
+    while (state.compactorItemKeys.size > MAX_COMPACTOR_ITEM_KEYS) {
+        const oldest = state.compactorItemKeys.values().next().value;
+        if (typeof oldest !== 'string')
+            break;
+        state.compactorItemKeys.delete(oldest);
+    }
+}
 function recordOf(value) {
     return value != null && typeof value === 'object' && !Array.isArray(value)
         ? value
@@ -788,6 +803,9 @@ class CodexAppConnection {
                 state.compacting = false;
             }
             if (params.item.type === 'agentMessage') {
+                if (state.compacting && params.turnId && params.item.id) {
+                    rememberCompactorItem(state, params.turnId, params.item.id);
+                }
                 const itemKey = `${params.turnId}\0${params.item.id}`;
                 if (message.method === 'item/completed')
                     state.completedAgentItemIds.add(itemKey);
@@ -991,7 +1009,8 @@ class CodexAppConnection {
                 activePrompt: '', contextUsage: null, lastTurn: null, loadedOnly: false, liveItemIds: new Map(),
                 completedAgentItemIds: new Set(), plans: new Map(), goal: undefined,
                 goalRevision: 0, goalEvent: null, goalTurnId: null,
-                compacting: false, deliveryHistorySafe: true, deliveryProofClientIds: new Set(),
+                compacting: false, compactorItemKeys: new Set(),
+                deliveryHistorySafe: true, deliveryProofClientIds: new Set(),
             });
         return this.threadState.get(threadId);
     }
@@ -2995,10 +3014,20 @@ export function createCodexAppServer({ home, connect = connectUnixWebSocket, exi
             return { client, thread: await client.readThread(threadId) };
         },
         async discover(pane) {
-            const observed = await observe(pane);
-            if (!observed)
+            // Absence of the pane-owned socket is the only authoritative unmanaged verdict. If the
+            // socket exists but its App Server is still starting or reconnecting, ownership is unknown;
+            // callers must not offer to replace that Codex process as though it were native/unmanaged.
+            if (!exists(codexAppSocketPath(pane, home)))
                 return { managed: false, threadId: null };
-            return { managed: true, threadId: observed.threadId };
+            try {
+                const observed = await observe(pane);
+                return observed
+                    ? { managed: true, threadId: observed.threadId }
+                    : { managed: null, threadId: null };
+            }
+            catch {
+                return { managed: null, threadId: null };
+            }
         },
         async inboxStates(livePanes = []) {
             const out = {};
@@ -3052,6 +3081,14 @@ export function createCodexAppServer({ home, connect = connectUnixWebSocket, exi
                 revision: state.revision,
             };
         },
+        async compactorItemKeys(pane, threadId) {
+            const client = await connection(pane);
+            if (!client)
+                throw new Error('Codex session is not managed by Handmux');
+            await client.assertCurrentThread(threadId);
+            const state = await client.ensureThread(threadId);
+            return [...state.compactorItemKeys];
+        },
         async subscribe(pane, threadId, listener, afterSequence = null) {
             const client = await connection(pane);
             if (!client)

package/dist/src/routes/agents.js

@@ -160,7 +160,11 @@ export function agentRoutes({ runtime }) {
         const status = error.code === 'unsupported' ? 409
             : error.code === 'in_progress' ? 409
                 : error.code === 'contract_violation' ? 502 : 503;
-        res.status(status).json({ error: error.message, code: error.code });
+        res.status(status).json({
+            error: error.message,
+            code: error.code,
+            ...(error.recovery === undefined ? {} : { recovery: error.recovery }),
+        });
         return true;
     };
     router.get('/agents/conversation-activation', async (req, res, next) => {
@@ -193,21 +197,54 @@ export function agentRoutes({ runtime }) {
                     error: ref ? 'stale agent run' : 'invalid agent run',
                     ...(ref ? { code: 'stale_run' } : {}),
                 });
-            const operation = new AbortController();
-            const cancel = () => {
-                if (!res.writableEnded)
-                    operation.abort(new Error('Activation request disconnected'));
-            };
-            req.once('aborted', cancel);
-            res.once('close', cancel);
-            try {
-                await runtime.conversationActivation.activate(lease, operation.signal);
+            // The user already confirmed a destructive process replacement. Once accepted, C-c → managed
+            // resume is one bounded server operation: a mobile navigation or dropped HTTP connection must not
+            // strand the pane at the intermediate shell. AgentConversationActivationService still owns its
+            // hard timeout and the controller revalidates the process before every irreversible step.
+            const result = await runtime.conversationActivation.activate(lease);
+            return res.status(202).json({
+                accepted: true,
+                ...(result?.recovery === undefined ? {} : { recovery: result.recovery }),
+            });
+        }
+        catch (error) {
+            if (activationError(error, res))
+                return;
+            return next(error);
+        }
+    });
+    router.get('/agents/conversation-activation-recovery', async (req, res, next) => {
+        try {
+            if (!runtime.conversationActivation) {
+                return res.status(409).json({ error: 'conversation recovery unsupported', code: 'unsupported' });
             }
-            finally {
-                req.removeListener('aborted', cancel);
-                res.removeListener('close', cancel);
+            const paneId = typeof req.query.paneId === 'string' ? req.query.paneId : '';
+            if (!/^%\d+$/.test(paneId)) {
+                return res.status(400).json({ error: 'invalid conversation recovery pane' });
             }
-            return res.status(202).json({ accepted: true });
+            return res.json({ receipt: await runtime.conversationActivation.recovery(paneId) });
+        }
+        catch (error) {
+            if (activationError(error, res))
+                return;
+            return next(error);
+        }
+    });
+    router.post('/agents/conversation-activation-recovery', async (req, res, next) => {
+        try {
+            if (!runtime.conversationActivation) {
+                return res.status(409).json({ error: 'conversation recovery unsupported', code: 'unsupported' });
+            }
+            const paneId = typeof req.body?.paneId === 'string' ? req.body.paneId : '';
+            const operationId = typeof req.body?.operationId === 'string' ? req.body.operationId : '';
+            if (!/^%\d+$/.test(paneId) || !/^[0-9a-f]{64}$/.test(operationId)) {
+                return res.status(400).json({ error: 'invalid conversation recovery request' });
+            }
+            const result = await runtime.conversationActivation.recover(paneId, operationId);
+            return res.status(202).json({
+                accepted: true,
+                ...(result?.recovery === undefined ? {} : { recovery: result.recovery }),
+            });
         }
         catch (error) {
             if (activationError(error, res))

package/dist/src/routes/system.js

@@ -6,20 +6,29 @@ import { dirname, resolve as resolvePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readFileSync } from 'node:fs';
 import { isSessionId } from '../tmux/commands.js';
-import { buildIatSignedUrl } from '../asr/iflySign.js';
-import { asrConfig, isAsrConfigured } from '../asr/iflyConfig.js';
+import { asrConfig } from '../asr/config.js';
+import { voiceProviderRegistry } from '../asr/providerRegistry.js';
 import { hooksStatus, installHooks } from '../cli/claudeHooks.js';
 import { agentIntegrationStatus, defaultAgentIntegrationContext, enableAgentIntegration, } from '../cli/agentIntegration.js';
 import { scanOrphans, takeoverOrphan, defaultProjectsDir } from '../orphans.js';
 import { readCache, isNewer, shouldRefresh, refreshLatestAsync } from '../cli/updateCheck.js';
 import { normalizeShortcuts } from '../shortcutConfig.js';
 import { projectLegacyInboxStates } from '../agent-runtime/legacyInboxProjection.js';
+import { PublicApiError } from '../apiErrors.js';
+export const MAX_SENTENCE_PCM_BYTES = 2 * 1024 * 1024;
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 const here = dirname(fileURLToPath(import.meta.url));
 const HOOKS_SRC = resolvePath(here, '../../hooks'); // server/hooks (bundled scripts)
 const PI_ENTRY = resolvePath(here, '../../connectors/pi/index.js');
 const WEB_AGENT_INTEGRATIONS = ['claude', 'pi'];
+const FILLER_FILTER_LEVELS = ['low', 'medium', 'high'];
+const requestFillerFilter = (value) => {
+    if (value === undefined)
+        return 'medium';
+    return typeof value === 'string' && FILLER_FILTER_LEVELS.includes(value)
+        ? value : null;
+};
 // The installed CLI version (server/package.json) — read once. The phone compares this against the cached
 // npm "latest" to surface an update hint ("run `handmux update` on your computer"); see the /version route.
 const PKG_VERSION = (() => {
@@ -47,8 +56,13 @@ export function systemRoutes({ commands, claudeEvents, agentRuntime, asrEnv, sho
     // `claudeHooks` is intentionally Claude-only. Codex is always App Server-backed and never affects
     // this setup prompt or endpoint.
     r.get('/config', (_req, res) => {
+        const voice = asrConfig(asrEnv);
+        const voiceAdapter = voice ? voiceProviderRegistry.get(voice.provider) : undefined;
         return res.json({
-            asr: isAsrConfigured(asrEnv),
+            asr: voice !== null,
+            asrProvider: voice?.provider ?? null,
+            asrMode: voice?.mode ?? null,
+            asrFillerFilter: voiceAdapter?.capabilities?.fillerFilter === true,
             claudeHooks: hooksStatus(home),
             managedCodex: true,
             shortcuts: activeShortcuts,
@@ -131,14 +145,99 @@ export function systemRoutes({ commands, claudeEvents, agentRuntime, asrEnv, sho
             return next(error);
         }
     });
-    // --- Voice input: iFlytek IAT signed-URL handoff -------------------------------------------
-    // The browser connects to iFlytek directly; we only mint a short-lived signed wss URL so the
-    // apiSecret never reaches the phone. 503 if creds aren't configured (front-end hides the mic).
-    r.get('/asr/sign', (_req, res) => {
-        if (!isAsrConfigured(asrEnv))
+    // --- Voice input: provider-neutral, short-lived session handoff -----------------------------
+    r.get('/asr/session', (req, res) => {
+        const config = asrConfig(asrEnv);
+        if (!config)
             return res.status(503).json({ error: 'asr not configured' });
-        const { appId, apiKey, apiSecret } = asrConfig(asrEnv);
-        return res.json(buildIatSignedUrl({ appId, apiKey, apiSecret, date: new Date().toUTCString() }));
+        if (config.mode !== 'streaming') {
+            return res.status(503).json({ error: 'streaming asr is not selected' });
+        }
+        const adapter = voiceProviderRegistry.get(config.provider);
+        if (!adapter?.createStreamingSession) {
+            return res.status(503).json({ error: 'streaming asr is unsupported by the selected provider' });
+        }
+        const fillerFilter = requestFillerFilter(req.query.fillerFilter);
+        if (!fillerFilter)
+            return res.status(400).json({ error: 'invalid filler filter level' });
+        return res.json(adapter.createStreamingSession(config, { fillerFilter }));
+    });
+    const rawSentenceAudio = express.raw({
+        type: 'application/octet-stream', limit: MAX_SENTENCE_PCM_BYTES,
+    });
+    const parseSentenceAudio = (req, res, next) => {
+        if (!req.is('application/octet-stream')) {
+            res.status(415).json({
+                error: 'audio must use application/octet-stream',
+                code: 'unsupported_audio_type', requestId: res.locals.requestId,
+            });
+            return;
+        }
+        rawSentenceAudio(req, res, (error) => {
+            const bodyError = error && typeof error === 'object'
+                ? error : null;
+            if (bodyError?.status === 413 || bodyError?.type === 'entity.too.large') {
+                res.status(413).json({
+                    error: `audio exceeds ${MAX_SENTENCE_PCM_BYTES} bytes`,
+                    code: 'audio_too_large', requestId: res.locals.requestId,
+                });
+                return;
+            }
+            next(error);
+        });
+    };
+    r.post('/asr/sentence', parseSentenceAudio, async (req, res, next) => {
+        const config = asrConfig(asrEnv);
+        const adapter = config ? voiceProviderRegistry.get(config.provider) : undefined;
+        if (!config || config.mode !== 'sentence' || !adapter?.recognizeSentence) {
+            return res.status(503).json({
+                error: 'sentence ASR is not selected',
+                code: 'sentence_asr_not_selected', requestId: res.locals.requestId,
+            });
+        }
+        const audio = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
+        if (audio.byteLength === 0)
+            return res.status(400).json({
+                error: 'audio is empty', code: 'audio_empty', requestId: res.locals.requestId,
+            });
+        const fillerFilter = requestFillerFilter(req.query.fillerFilter);
+        if (!fillerFilter)
+            return res.status(400).json({
+                error: 'invalid filler filter level', code: 'invalid_filler_filter', requestId: res.locals.requestId,
+            });
+        try {
+            const result = await adapter.recognizeSentence(config, audio, { fillerFilter });
+            return res.json({ text: result.text });
+        }
+        catch (error) {
+            const publicError = adapter.publicError?.(error);
+            if (publicError) {
+                if (publicError.logFields) {
+                    return next(new PublicApiError(502, publicError.code, publicError.message, undefined, {
+                        ...(publicError.providerRequestId
+                            ? { providerRequestId: publicError.providerRequestId } : {}),
+                        logFields: publicError.logFields,
+                    }));
+                }
+                return res.status(502).json({
+                    error: publicError.message,
+                    code: publicError.code,
+                    requestId: res.locals.requestId,
+                    ...(publicError.providerRequestId
+                        ? { providerRequestId: publicError.providerRequestId } : {}),
+                });
+            }
+            return next(error);
+        }
+    });
+    // Historical endpoint retained for already-loaded Web clients. It can only describe XFYUN's protocol.
+    r.get('/asr/sign', (_req, res) => {
+        const config = asrConfig(asrEnv);
+        if (!config || config.provider !== 'xfyun')
+            return res.status(503).json({ error: 'xfyun asr not configured' });
+        const session = voiceProviderRegistry.get(config.provider)?.createStreamingSession?.(config, { fillerFilter: 'medium' });
+        return session ? res.json({ url: session.url, appId: session.appId })
+            : res.status(503).json({ error: 'xfyun asr not configured' });
     });
     // ?sessions=a,b scopes the roster to the session NAMES this device subscribed to (per-device inbox
     // isolation). Omitted → null → all (back-compat); present-but-empty → [] → nothing.

package/dist/src/server.js

@@ -39,6 +39,9 @@ import { InboxPushProjection } from './agent-runtime/inboxPushProjection.js';
 import { defaultGit } from './git.js';
 import { createProjectTaskRuntime } from './projectTask/runtime.js';
 import { clearCodexConversationThroughTui } from './agents/codexTerminalControl.js';
+import { sessionsDir as codexSessionsDir } from './agents/codex.js';
+import { inspectCodexOpenRootSession } from './agents/codexOpenSession.js';
+import { CodexActivationReceiptStore } from './agents/codexActivationReceipt.js';
 import { ApiAccountService, apiAccountsPath } from './apiAccounts.js';
 import { ClaudeHookBridgeConnector } from '../connectors/claude/index.js';
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -82,6 +85,7 @@ const observeEnvironment = createEnvironmentProvider({
 const stateFile = process.env.CLAUDE_STATE_FILE || claudeStatePath(home);
 let codexApp = null;
 const agentRuntimeDirectory = agentRuntimeDirectoryPath(home);
+const codexActivationReceipts = new CodexActivationReceiptStore(path.join(agentRuntimeDirectory, 'codex-activation-receipts.json'));
 const legacyCodexOutbox = codexOutboxPath(home);
 let conversationStartupBlockReason;
 try {
@@ -150,9 +154,14 @@ const agentRuntime = createBuiltinAgentRuntime({
         pendingKind: (paneId) => events?.paneKind(paneId) ?? null,
     },
     codexApp,
+    codexActivationReceipts,
     codexActivationCommands: {
-        sendKey: (pane, key) => commands.sendKey(pane, key),
-        capturePlain: (pane) => commands.capturePlain(pane),
+        openOutputCapture: (pane) => commands.openPaneOutputCapture(pane),
+        paneEpoch: async () => {
+            const environment = await workspaceTmux.observeEnvironment();
+            return environment.status === 'present' ? environment.tmuxServerId : null;
+        },
+        inspectOpenSession: (pid) => inspectCodexOpenRootSession(pid, codexSessionsDir(home)),
         runPaneCommand: (pane, command) => commands.runPaneCommand(pane, command),
     },
     codexClear: async (pane, threadId) => {

package/dist/src/terminalStream.js

@@ -3,6 +3,8 @@ import { WebSocketServer } from 'ws';
 import { tokenEquals } from './auth.js';
 import { isPaneId } from './tmux/commands.js';
 import { restoreCaptureBackgrounds } from './captureBackground.js';
+import { decodeControlData } from './tmux/controlProtocol.js';
+export { decodeControlData } from './tmux/controlProtocol.js';
 const MAX_BUFFERED_BYTES = 1024 * 1024;
 const MAX_CLIENT_MESSAGE_BYTES = 16 * 1024;
 const START_TIMEOUT_MS = 5000;
@@ -23,7 +25,7 @@ export function echoTerminalProbe(ws, message) {
 export function startSubscribeDeadline(ws, timeoutMs = SUBSCRIBE_TIMEOUT_MS) {
     const timer = setTimeout(() => {
         if (ws.readyState < 2)
-            ws.close(4001, 'authentication timeout');
+            ws.close(4000, 'subscribe timeout');
     }, timeoutMs);
     timer.unref?.();
     return () => clearTimeout(timer);
@@ -36,32 +38,6 @@ function parsePaneInfo(infoLines) {
     }
     return values;
 }
-export function decodeControlData(data) {
-    const bytes = [];
-    for (let i = 0; i < data.length;) {
-        const current = data[i];
-        if (current === 0x5c && data[i + 1] === 0x5c) {
-            bytes.push(0x5c);
-            i += 2;
-            continue;
-        }
-        if (current === 0x5c && i + 3 < data.length) {
-            const a = data[i + 1];
-            const b = data[i + 2];
-            const c = data[i + 3];
-            if (a !== undefined && b !== undefined && c !== undefined
-                && a >= 0x30 && a <= 0x37 && b >= 0x30 && b <= 0x37 && c >= 0x30 && c <= 0x37) {
-                bytes.push(((a - 0x30) << 6) | ((b - 0x30) << 3) | (c - 0x30));
-                i += 4;
-                continue;
-            }
-        }
-        if (current !== undefined)
-            bytes.push(current);
-        i += 1;
-    }
-    return Buffer.from(bytes);
-}
 export class PaneControlStream {
     ws;
     pane;
@@ -383,9 +359,11 @@ export function createTerminalStream({ token, commands, spawnControl, }) {
             }
             if (authenticating)
                 return;
-            if (message.type !== 'subscribe'
-                || !tokenEquals(message.token ?? '', token)
-                || !isPaneId(message.pane)) {
+            if (message.type !== 'subscribe' || !isPaneId(message.pane)) {
+                ws.close(1003, 'bad subscribe message');
+                return;
+            }
+            if (!tokenEquals(message.token ?? '', token)) {
                 ws.close(4001, 'unauthorized');
                 return;
             }

package/dist/src/tmux/commands.js

@@ -1,6 +1,7 @@
 import { execFile } from 'node:child_process';
 import os from 'node:os';
 import { parseTmuxRows, tmuxFormat } from './format.js';
+import { TmuxPaneOutputCapture } from './paneOutputCapture.js';
 export const isPaneId = (value) => typeof value === 'string' && /^%\d+$/.test(value);
 export const isWindowId = (value) => typeof value === 'string' && /^@\d+$/.test(value);
 export const isSessionId = (value) => typeof value === 'string' && /^\$\d+$/.test(value);
@@ -165,6 +166,19 @@ export async function paneSession(paneId) {
         throw new Error('pane session not found');
     return id;
 }
+export async function openPaneOutputCapture(paneId) {
+    if (!isPaneId(paneId))
+        throw new TypeError('invalid pane id');
+    const capture = new TmuxPaneOutputCapture({ pane: paneId, session: await paneSession(paneId) });
+    try {
+        await capture.start();
+        return capture;
+    }
+    catch (error) {
+        capture.close();
+        throw error;
+    }
+}
 // Exit tmux copy/scroll mode if the pane is currently in it. Called before any user input so
 // text and keys reach the shell instead of being swallowed by tmux's mode key-bindings.
 export async function exitCopyModeIfActive(paneId) {

package/dist/src/tmux/controlProtocol.js

@@ -0,0 +1,26 @@
+export function decodeControlData(data) {
+    const bytes = [];
+    for (let i = 0; i < data.length;) {
+        const current = data[i];
+        if (current === 0x5c && data[i + 1] === 0x5c) {
+            bytes.push(0x5c);
+            i += 2;
+            continue;
+        }
+        if (current === 0x5c && i + 3 < data.length) {
+            const a = data[i + 1];
+            const b = data[i + 2];
+            const c = data[i + 3];
+            if (a !== undefined && b !== undefined && c !== undefined
+                && a >= 0x30 && a <= 0x37 && b >= 0x30 && b <= 0x37 && c >= 0x30 && c <= 0x37) {
+                bytes.push(((a - 0x30) << 6) | ((b - 0x30) << 3) | (c - 0x30));
+                i += 4;
+                continue;
+            }
+        }
+        if (current !== undefined)
+            bytes.push(current);
+        i += 1;
+    }
+    return Buffer.from(bytes);
+}

package/dist/src/tmux/paneOutputCapture.js

@@ -0,0 +1,180 @@
+import { spawn } from 'node:child_process';
+import { decodeControlData } from './controlProtocol.js';
+const START_TIMEOUT_MS = 5_000;
+const DEFAULT_MAX_BYTES = 256 * 1024;
+const defaultSpawnControl = (command, args, options) => (spawn(command, [...args], options));
+export class TmuxPaneOutputCapture {
+    #pane;
+    #maxBytes;
+    #child;
+    #attached;
+    #startTimer;
+    #resolveAttached;
+    #rejectAttached;
+    #buffer = Buffer.alloc(0);
+    #response;
+    #pending = null;
+    #chunks = [];
+    #bytes = 0;
+    #armed = false;
+    #overflow = false;
+    #failed = false;
+    #closed = false;
+    #lastError = '';
+    constructor({ pane, session, maxBytes = DEFAULT_MAX_BYTES, spawnControl = defaultSpawnControl, }) {
+        if (!/^%\d+$/.test(pane) || !/^\$\d+$/.test(session)) {
+            throw new TypeError('invalid tmux pane output capture target');
+        }
+        this.#pane = pane;
+        this.#maxBytes = Math.max(1, Math.trunc(maxBytes));
+        this.#attached = new Promise((resolve, reject) => {
+            this.#resolveAttached = resolve;
+            this.#rejectAttached = reject;
+        });
+        this.#startTimer = setTimeout(() => this.#fail(new Error('tmux control mode attach timed out')), START_TIMEOUT_MS);
+        this.#startTimer.unref?.();
+        this.#child = spawnControl('tmux', ['-C', 'attach-session', '-E', '-t', session], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.#child.stdout.on('data', (chunk) => this.#onChunk(chunk));
+        this.#child.stderr.on('data', (chunk) => { this.#lastError += chunk.toString('utf8'); });
+        this.#child.stdin.on('error', (error) => this.#fail(error));
+        this.#child.on('error', (error) => this.#fail(error));
+        this.#child.on('exit', (code) => {
+            if (!this.#closed)
+                this.#fail(new Error(this.#lastError || `tmux control mode exited (${code ?? 'unknown'})`));
+        });
+    }
+    async start() {
+        await this.#attached;
+    }
+    async sendKey(key) {
+        if (!/^[A-Za-z0-9-]+$/.test(key))
+            throw new TypeError('invalid tmux key');
+        await this.#attached;
+        await this.#request(`send-keys -t ${this.#pane} ${key}`);
+    }
+    output() {
+        if (!this.#armed || this.#failed || this.#overflow)
+            return null;
+        return Buffer.concat(this.#chunks, this.#bytes);
+    }
+    outputFrames() {
+        if (!this.#armed || this.#failed || this.#overflow)
+            return null;
+        return this.#chunks.map((chunk) => Buffer.from(chunk));
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        clearTimeout(this.#startTimer);
+        const error = new Error('tmux control output capture closed');
+        this.#rejectAttached(error);
+        this.#pending?.reject(error);
+        this.#response?.reject(error);
+        this.#pending = null;
+        this.#response = undefined;
+        try {
+            this.#child.kill();
+        }
+        catch { /* already gone */ }
+    }
+    #onChunk(chunk) {
+        this.#buffer = Buffer.concat([this.#buffer, chunk]);
+        for (;;) {
+            const newline = this.#buffer.indexOf(0x0a);
+            if (newline < 0)
+                return;
+            const line = this.#buffer.subarray(0, newline);
+            this.#buffer = this.#buffer.subarray(newline + 1);
+            this.#onLine(line.at(-1) === 0x0d ? line.subarray(0, -1) : line);
+        }
+    }
+    #onLine(line) {
+        if (line.subarray(0, 8).toString('ascii') === '%output ') {
+            const split = line.indexOf(0x20, 8);
+            if (!this.#armed || split < 0
+                || line.subarray(8, split).toString('ascii') !== this.#pane)
+                return;
+            const output = decodeControlData(line.subarray(split + 1));
+            if (this.#bytes + output.length > this.#maxBytes) {
+                this.#overflow = true;
+                this.#chunks = [];
+                this.#bytes = 0;
+                return;
+            }
+            if (!this.#overflow) {
+                this.#chunks.push(output);
+                this.#bytes += output.length;
+            }
+            return;
+        }
+        if (line.subarray(0, 7).toString('ascii') === '%begin ') {
+            this.#response = this.#pending;
+            this.#pending = null;
+            return;
+        }
+        const ended = line.subarray(0, 5).toString('ascii') === '%end ';
+        const errored = line.subarray(0, 7).toString('ascii') === '%error ';
+        if (ended || errored) {
+            const response = this.#response;
+            this.#response = undefined;
+            if (response) {
+                if (errored)
+                    response.reject(new Error('tmux control command failed'));
+                else {
+                    // tmux never inserts notifications inside a command output block. Arming synchronously at
+                    // this %end makes every subsequently parsed %output byte provably newer than this C-c.
+                    this.#chunks = [];
+                    this.#bytes = 0;
+                    this.#overflow = false;
+                    this.#armed = true;
+                    response.resolve();
+                }
+            }
+            return;
+        }
+        if (line.subarray(0, 17).toString('ascii') === '%session-changed ') {
+            clearTimeout(this.#startTimer);
+            this.#resolveAttached();
+            return;
+        }
+        if (line.subarray(0, 5).toString('ascii') === '%exit') {
+            this.#fail(new Error('tmux control mode detached'));
+        }
+    }
+    #fail(error) {
+        if (this.#failed || this.#closed)
+            return;
+        this.#failed = true;
+        this.#closed = true;
+        clearTimeout(this.#startTimer);
+        this.#rejectAttached(error);
+        this.#pending?.reject(error);
+        this.#response?.reject(error);
+        this.#pending = null;
+        this.#response = undefined;
+        this.#chunks = [];
+        this.#bytes = 0;
+        try {
+            this.#child.kill();
+        }
+        catch { /* already gone */ }
+    }
+    #request(command) {
+        if (this.#closed || this.#failed) {
+            return Promise.reject(new Error('tmux control output capture is unavailable'));
+        }
+        if (this.#pending || this.#response) {
+            return Promise.reject(new Error('tmux control command already pending'));
+        }
+        return new Promise((resolve, reject) => {
+            this.#pending = { resolve, reject };
+            this.#child.stdin.write(`${command}\n`, (error) => {
+                if (error)
+                    this.#fail(error);
+            });
+        });
+    }
+}