@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/ui/ratatui/index.d.ts

@@ -10,6 +10,7 @@ export type { RatatuiRendererOptions } from './adapter.js';
 export { TuiProcess, NullTuiProcess, getTuiProcess, getNullTuiProcess, isTTY, isZmuxAvailable, isZtermAvailable, launchZtermDesktop, isRatatuiBinaryAvailable } from './process.js';
 export type { TuiEventHandler } from './process.js';
 export type { RustCommand, RustEvent } from './protocol.js';
+export type { DesktopTaskControlState, DesktopTaskControlEntry, DesktopTaskControlAttachment, DesktopTaskAction, DesktopTaskActionResult } from './protocol.js';
 export { PaneRelayServer, PaneRelayClient, generateRelaySocketPath } from './pane_relay.js';
 export type { PaneCommandTransport } from './pane_relay.js';
 export { HeadlessPaneManager, encodeZtcPaneInput, decodeZtcPaneInput } from './headless_pane_manager.js';

package/dist/ui/ratatui/input.d.ts

@@ -0,0 +1,4 @@
+import { type InputKey } from '../core/input.js';
+export type ClipboardPastePreference = 'text' | 'image' | 'image-only';
+/** Identify a clipboard gesture while keeping terminal paste payloads literal. */
+export declare function clipboardPastePreference(input: string, key: InputKey, paste?: boolean): ClipboardPastePreference | null;

package/dist/ui/ratatui/input.js

@@ -0,0 +1,15 @@
+import { isControlKey } from '../core/input.js';
+/** Identify a clipboard gesture while keeping terminal paste payloads literal. */
+export function clipboardPastePreference(input, key, paste = false) {
+    if (paste)
+        return null;
+    const command = key.super === true || (key.meta === true && key.alt !== true);
+    const isV = input.toLowerCase() === 'v';
+    if (isV && (command || (key.ctrl && key.shift)))
+        return 'text';
+    if (isV && key.ctrl)
+        return 'image';
+    if (isControlKey(input, key, 'i'))
+        return 'image-only';
+    return null;
+}

package/dist/ui/ratatui/ipc_path.d.ts

@@ -14,6 +14,8 @@
  * than only whichever one the host happens to run.
  */
 export declare function generateIpcPath(prefix: string, platformName?: string): string;
+/** Retire only directories allocated by this host, without recursive removal. */
+export declare function removeOwnedIpcPath(endpoint: string): void;
 /**
  * True when the path names a Windows pipe rather than a filesystem entry.
  *

package/dist/ui/ratatui/ipc_path.js

@@ -7,8 +7,10 @@
  * `\\.\pipe\<name>` form: libuv maps a bare path into the pipe namespace itself,
  * so a filesystem-style path can never reach an AF_UNIX socket there.
  */
+import { chmodSync, mkdtempSync, rmdirSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
+const ownedEndpoints = new Map();
 /**
  * Build a unique IPC endpoint name for the current process.
  *
@@ -20,7 +22,33 @@ export function generateIpcPath(prefix, platformName = process.platform) {
     if (platformName === 'win32') {
         return `\\\\.\\pipe\\${prefix}-${unique}`;
     }
-    return join(tmpdir(), `${prefix}-${unique}.sock`);
+    const requested = join(tmpdir(), `${prefix}-${unique}.sock`);
+    // Darwin reserves one of its 104 address bytes for NUL. A long TMPDIR
+    // must not truncate distinct endpoints onto the same kernel address.
+    if (Buffer.byteLength(requested, 'utf8') <= 103)
+        return requested;
+    const channel = prefix.replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 16) || 'ztc-ipc';
+    const directory = mkdtempSync(join('/tmp', `${channel}-`));
+    chmodSync(directory, 0o700);
+    const endpoint = join(directory, 'socket');
+    ownedEndpoints.set(endpoint, directory);
+    return endpoint;
+}
+/** Retire only directories allocated by this host, without recursive removal. */
+export function removeOwnedIpcPath(endpoint) {
+    const directory = ownedEndpoints.get(endpoint);
+    if (!directory)
+        return;
+    // The listener retires its endpoint first. Never delete anything a failed
+    // bind might have found in the allocated directory.
+    try {
+        rmdirSync(directory);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    ownedEndpoints.delete(endpoint);
 }
 /**
  * True when the path names a Windows pipe rather than a filesystem entry.

package/dist/ui/ratatui/mux_persistence.d.ts

@@ -4,5 +4,7 @@ export interface MuxPersistenceOptions {
 }
 export declare function resolveMuxPersistenceOptions(env?: NodeJS.ProcessEnv): MuxPersistenceOptions;
 export declare function shouldPersistMuxPaneType(paneType: string, options: MuxPersistenceOptions): boolean;
-export declare function isMuxPaneRestorable(pane: Pick<MuxPaneState, 'id' | 'pane_type'>, options: MuxPersistenceOptions): boolean;
+export declare function isMuxPaneRestorable(pane: Pick<MuxPaneState, 'id' | 'pane_type' | 'agent_session'>, options: MuxPersistenceOptions): boolean;
 export declare function sanitizeMuxSessionState(state: MuxSessionState, options: MuxPersistenceOptions): MuxSessionState;
+/** Decode/admit a bounded checkpoint before traversing it or changing live panes. */
+export declare function validateWorkspaceState(value: unknown): asserts value is MuxSessionState;

package/dist/ui/ratatui/mux_persistence.js

@@ -16,6 +16,9 @@ export function isMuxPaneRestorable(pane, options) {
     if (pane.id === 0) {
         return false;
     }
+    // A canonical session link is descriptive; restoration never launches its saved argv.
+    if (pane.pane_type === 'ztc' && pane.agent_session)
+        return true;
     return shouldPersistMuxPaneType(pane.pane_type, options);
 }
 function pruneMuxLayoutNode(node, allowedPaneIds) {
@@ -30,13 +33,14 @@ function pruneMuxLayoutNode(node, allowedPaneIds) {
     return first || second;
 }
 export function sanitizeMuxSessionState(state, options) {
+    validateWorkspaceState(state);
     const panes = state.panes.filter((pane) => isMuxPaneRestorable(pane, options));
     const allowedPaneIds = new Set([0, ...panes.map((pane) => pane.id)]);
     const layout = pruneMuxLayoutNode(state.layout, allowedPaneIds) || { type: 'leaf', pane_id: 0 };
     const layoutPaneIds = new Set(collectMuxLayoutPaneIds(layout));
     const focused_pane_id = layoutPaneIds.has(state.focused_pane_id)
         ? state.focused_pane_id
-        : 0;
+        : collectMuxLayoutPaneIds(layout)[0];
     const zoomed_pane_id = state.zoomed_pane_id !== undefined
         && layoutPaneIds.has(state.zoomed_pane_id)
         ? state.zoomed_pane_id
@@ -47,8 +51,142 @@ export function sanitizeMuxSessionState(state, options) {
         zoomed_pane_id,
         layout,
         panes,
+        ...(state.windows ? { windows: state.windows.map(window => {
+                const windowLayout = pruneMuxLayoutNode(window.layout, allowedPaneIds) || { type: 'leaf', pane_id: 0 };
+                const ids = new Set(collectMuxLayoutPaneIds(windowLayout));
+                return { ...window, layout: windowLayout,
+                    focused_pane_id: ids.has(window.focused_pane_id) ? window.focused_pane_id : collectMuxLayoutPaneIds(windowLayout)[0],
+                    zoomed_pane_id: window.zoomed_pane_id !== undefined && ids.has(window.zoomed_pane_id) ? window.zoomed_pane_id : undefined };
+            }) } : {}),
     };
 }
+/** Decode/admit a bounded checkpoint before traversing it or changing live panes. */
+export function validateWorkspaceState(value) {
+    const object = (v) => {
+        if (!v || typeof v !== 'object' || Array.isArray(v))
+            throw new Error('Workspace requires an object');
+        return v;
+    };
+    const id = (v) => {
+        if (typeof v !== 'number' || !Number.isInteger(v) || v < 0 || v > 0xffffffff)
+            throw new Error('Workspace identity must be an unsigned integer');
+        return v;
+    };
+    const text = (v, max) => {
+        if (typeof v !== 'string' || Buffer.byteLength(v) > max)
+            throw new Error('Workspace metadata exceeds its bounds');
+    };
+    const saved = object(value);
+    if (saved.schema_version !== undefined && saved.schema_version !== 1)
+        throw new Error(`Unsupported workspace schema version ${String(saved.schema_version)}`);
+    if (!Array.isArray(saved.panes) || saved.panes.length > 256)
+        throw new Error('Workspace requires at most 256 panes');
+    const paneIds = new Set();
+    for (const entry of saved.panes) {
+        const pane = object(entry);
+        const paneId = id(pane.id);
+        if (paneIds.has(paneId))
+            throw new Error(`Duplicate workspace pane ID ${paneId}`);
+        paneIds.add(paneId);
+        text(pane.title, 4096);
+        text(pane.pane_type, 64);
+        for (const key of ['command', 'cwd'])
+            if (pane[key] !== undefined && pane[key] !== null)
+                text(pane[key], 65536);
+        if (pane.content !== undefined && pane.content !== null)
+            text(pane.content, 4 * 1024 * 1024);
+        if (pane.args !== undefined) {
+            if (!Array.isArray(pane.args) || pane.args.length > 256)
+                throw new Error('Workspace arguments exceed their bounds');
+            pane.args.forEach(arg => text(arg, 65536));
+        }
+        if (pane.agent_session !== undefined && pane.agent_session !== null) {
+            const ref = object(pane.agent_session);
+            text(ref.session_id, 256);
+            text(ref.project_path, 65536);
+            if (!ref.session_id || !ref.project_path)
+                throw new Error('Workspace agent session requires a bounded session ID and project path');
+        }
+        if (pane.restoration_status !== undefined && pane.restoration_status !== null
+            && (typeof pane.restoration_status !== 'string' || !['not_started', 'missing_command', 'missing_directory', 'session_missing', 'session_active_elsewhere', 'session_unreadable'].includes(pane.restoration_status)))
+            throw new Error('Unknown workspace restoration status');
+    }
+    paneIds.add(0);
+    const layout = (v, depth = 0) => {
+        if (depth > 64)
+            throw new Error('Workspace layout exceeds depth 64');
+        const node = object(v);
+        if (node.type === 'leaf') {
+            const paneId = id(node.pane_id);
+            if (!paneIds.has(paneId))
+                throw new Error(`Workspace layout names missing pane ${paneId}`);
+            return new Set([paneId]);
+        }
+        if (node.type !== 'split' || typeof node.direction !== 'string' || !['horizontal', 'vertical'].includes(node.direction))
+            throw new Error('Workspace requires a valid layout node');
+        if (typeof node.ratio !== 'number' || !Number.isFinite(node.ratio) || node.ratio <= 0 || node.ratio >= 1)
+            throw new Error('Workspace split ratio must be between 0 and 1');
+        const ids = layout(node.first, depth + 1);
+        for (const second of layout(node.second, depth + 1)) {
+            if (ids.has(second))
+                throw new Error(`Duplicate workspace layout pane ID ${second}`);
+            ids.add(second);
+        }
+        return ids;
+    };
+    layout(saved.layout);
+    if (!paneIds.has(id(saved.focused_pane_id)) || (saved.zoomed_pane_id !== undefined && saved.zoomed_pane_id !== null && !paneIds.has(id(saved.zoomed_pane_id))))
+        throw new Error('Workspace focus names a missing pane');
+    const windows = saved.windows ?? [];
+    if (!Array.isArray(windows) || windows.length > 64)
+        throw new Error('Workspace requires at most 64 windows');
+    const windowIds = new Set();
+    const paneWindows = new Map();
+    for (const entry of windows) {
+        const window = object(entry);
+        const windowId = id(window.id);
+        if (windowIds.has(windowId))
+            throw new Error(`Duplicate workspace window ID ${windowId}`);
+        windowIds.add(windowId);
+        text(window.title, 4096);
+        for (const key of ['color', 'pattern'])
+            if (window[key] !== undefined && window[key] !== null)
+                text(window[key], 64);
+        const ids = layout(window.layout);
+        for (const paneId of ids) {
+            if (paneId === 0)
+                continue;
+            if (paneWindows.has(paneId))
+                throw new Error(`Workspace pane ${paneId} appears in multiple windows`);
+            paneWindows.set(paneId, windowId);
+        }
+        if (!ids.has(id(window.focused_pane_id)) || (window.zoomed_pane_id !== undefined && window.zoomed_pane_id !== null && !ids.has(id(window.zoomed_pane_id))))
+            throw new Error('Workspace window focus names a missing pane');
+    }
+    if (windows.length) {
+        for (const entry of saved.panes) {
+            const pane = object(entry);
+            const paneId = id(pane.id);
+            if (paneId !== 0 && pane.window_id !== undefined && pane.window_id !== null
+                && paneWindows.has(paneId) && paneWindows.get(paneId) !== id(pane.window_id))
+                throw new Error(`Workspace pane ${paneId} window assignment contradicts its layout`);
+        }
+    }
+    if (windows.length && ((saved.active_window_id !== undefined && saved.active_window_id !== null && !windowIds.has(id(saved.active_window_id)))
+        || saved.panes.some(entry => { const pane = object(entry); return pane.window_id !== undefined && pane.window_id !== null && !windowIds.has(id(pane.window_id)); })))
+        throw new Error('Workspace names a missing window');
+    if (saved.geometry !== undefined && saved.geometry !== null) {
+        const geometry = object(saved.geometry);
+        for (const key of ['cols', 'rows', 'pixel_width', 'pixel_height']) {
+            const v = geometry[key];
+            if (v === undefined || v === null)
+                continue;
+            const cells = key === 'cols' || key === 'rows';
+            if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0 || v > (cells ? 10000 : 32768) || (cells && !Number.isInteger(v)))
+                throw new Error('Workspace geometry must be positive and bounded');
+        }
+    }
+}
 function collectMuxLayoutPaneIds(node) {
     if (node.type === 'leaf') {
         return [node.pane_id];

package/dist/ui/ratatui/pane_relay.d.ts

@@ -25,7 +25,7 @@ export declare class PaneRelayServer {
     private tuiUnsubscribe;
     constructor(transport: PaneCommandTransport, socketPath: string);
     /** Start listening for child connections */
-    start(): void;
+    start(): Promise<void>;
     /** Broadcast a pane event to all connected children */
     private broadcast;
     /** Stop the relay server and clean up */

package/dist/ui/ratatui/pane_relay.js

@@ -11,9 +11,9 @@
  */
 import { createServer, createConnection } from 'net';
 import { createInterface } from 'readline';
-import { unlinkSync } from 'fs';
-import { serializeCommand, parseEvent, CAPABILITY_PANE_DELIVERY_ACK } from './protocol.js';
-import { generateIpcPath, isNamedPipePath } from './ipc_path.js';
+import { serializeCommand, parseEvent, CAPABILITY_PANE_DELIVERY_ACK, CAPABILITY_DESKTOP_TASK_CONTROLS, CAPABILITY_DESKTOP_RUNTIME_CONTROLS, CAPABILITY_DESKTOP_SESSION_SHARE } from './protocol.js';
+import { runtimeDiag } from '../../utils/debug_log.js';
+import { generateIpcPath, removeOwnedIpcPath } from './ipc_path.js';
 // ============================================================================
 // PaneRelayServer — runs in parent ZTC (--mux mode)
 // ============================================================================
@@ -27,6 +27,9 @@ const PANE_EVENT_TYPES = new Set([
     'pane_state',
     'pane_output',
     'error',
+    'desktop_task_action',
+    'desktop_runtime_action',
+    'desktop_session_share_action',
 ]);
 export class PaneRelayServer {
     transport;
@@ -39,7 +42,9 @@ export class PaneRelayServer {
         this.socketPath = socketPath;
     }
     /** Start listening for child connections */
-    start() {
+    async start() {
+        if (this.server !== null)
+            throw new Error('Pane relay is already started.');
         // Subscribe to pane events from the parent's TuiProcess
         this.tuiUnsubscribe = this.transport.on((event) => {
             if (PANE_EVENT_TYPES.has(event.type)) {
@@ -49,9 +54,15 @@ export class PaneRelayServer {
         this.server = createServer((client) => {
             this.clients.add(client);
             client.write(JSON.stringify({ type: 'ready', version: 'pane-relay', cols: 0, rows: 0,
-                capabilities: this.transport.hasCapability?.(CAPABILITY_PANE_DELIVERY_ACK) ? [CAPABILITY_PANE_DELIVERY_ACK] : [],
+                capabilities: [CAPABILITY_PANE_DELIVERY_ACK, 'pane_labels_v1', CAPABILITY_DESKTOP_TASK_CONTROLS, CAPABILITY_DESKTOP_RUNTIME_CONTROLS, CAPABILITY_DESKTOP_SESSION_SHARE]
+                    .filter(capability => this.transport.hasCapability?.(capability)),
             }) + '\n');
             const rl = createInterface({ input: client, crlfDelay: Infinity });
+            // Readline re-emits input errors; one failed peer must not terminate its parent.
+            rl.on('error', () => {
+                this.clients.delete(client);
+                client.destroy();
+            });
             rl.on('line', (line) => {
                 const parsed = parseEvent(line);
                 if (!parsed)
@@ -68,21 +79,29 @@ export class PaneRelayServer {
                 rl.close();
             });
         });
-        this.server.on('error', (err) => {
-            // If socket file already exists from a crash, unlink and retry once.
-            // Named pipes leave no file behind, so there is nothing to clear.
-            if (err.code === 'EADDRINUSE') {
-                if (!isNamedPipePath(this.socketPath)) {
-                    try {
-                        unlinkSync(this.socketPath);
-                    }
-                    catch { /* ignore */ }
-                }
-                this.server.listen(this.socketPath);
-                return;
-            }
-        });
-        this.server.listen(this.socketPath);
+        const server = this.server;
+        try {
+            await new Promise((resolve, reject) => {
+                const failed = (error) => reject(error);
+                server.once('error', failed);
+                server.once('listening', () => {
+                    server.off('error', failed);
+                    server.on('error', error => {
+                        runtimeDiag('error', `Pane relay stopped: ${error.message}`);
+                        this.stop();
+                    });
+                    resolve();
+                });
+                server.listen(this.socketPath);
+            });
+        }
+        catch (error) {
+            // An occupied address is not proof that its owner crashed. Never unlink
+            // another listener or spin in a repeated listen/error retry cycle.
+            this.stop();
+            const cause = error instanceof Error ? error : new Error(String(error));
+            throw new Error(`Pane relay could not listen: ${cause.message}`, { cause });
+        }
     }
     /** Broadcast a pane event to all connected children */
     broadcast(event) {
@@ -110,15 +129,18 @@ export class PaneRelayServer {
         }
         this.clients.clear();
         if (this.server) {
-            this.server.close();
+            this.server.close(() => {
+                try {
+                    removeOwnedIpcPath(this.socketPath);
+                }
+                catch (error) {
+                    runtimeDiag('error', `Pane relay IPC cleanup failed: ${String(error)}`);
+                }
+            });
             this.server = null;
         }
-        if (!isNamedPipePath(this.socketPath)) {
-            try {
-                unlinkSync(this.socketPath);
-            }
-            catch { /* ignore */ }
-        }
+        // Node closes its own bound endpoint. A failed bind never owns a path
+        // and must not unlink a file belonging to an existing listener.
     }
 }
 // ============================================================================
@@ -194,6 +216,12 @@ export class PaneRelayClient {
             this.ready = false;
             this.cleanup();
         });
+        // readline forwards input errors independently of the socket listener.
+        // A stale write after the parent closes must retire this transport too.
+        this.readline.on('error', () => {
+            this.ready = false;
+            this.cleanup();
+        });
         this.socket.on('error', () => {
             this.ready = false;
             this.cleanup();

package/dist/ui/ratatui/process.d.ts

@@ -9,6 +9,7 @@
  * a fullscreen multiplexer with split panes (alternate screen mode).
  */
 import type { RustCommand, RustEvent } from './protocol.js';
+import { type DesktopRuntime } from '../../desktop/runtime.js';
 export type TuiEventHandler = (event: RustEvent) => void;
 /**
  * Get the path to the zmux binary
@@ -32,7 +33,7 @@ export declare function isZmuxAvailable(): boolean;
  * Check if zterm is available. Unlike zmux, zterm is a desktop process and
  * does not require the current process to have a TTY.
  */
-export declare function isZtermAvailable(): boolean;
+export declare function isZtermAvailable(admission?: DesktopRuntime | null): boolean;
 /**
  * Launch the native zterm desktop binary and resolve with its exit code.
  */
@@ -83,6 +84,11 @@ export declare function isTransientSocketConnectError(code: string | undefined):
  * Manages the Rust TUI process with Unix socket communication
  */
 export declare class TuiProcess {
+    private readonly options;
+    /** Host-selected unmanaged renderer; validated bundle admission takes precedence. */
+    constructor(options?: {
+        desktopBinaryPath?: string;
+    });
     private process;
     private socket;
     private readline;
@@ -98,6 +104,9 @@ export declare class TuiProcess {
     private _muxMode;
     /** Whether zterm is being used as the native desktop renderer */
     private _desktopMode;
+    private desktopCompatibility;
+    /** Retained across socket cleanup so an admitted renderer can request owner exit. */
+    private desktopStartupAdmitted;
     private stopping;
     /** Whether zmux was detected from the ready event version string */
     private _isZmux;
@@ -123,6 +132,7 @@ export declare class TuiProcess {
      */
     private clipboardRequests;
     private clipboardRequestSeq;
+    private clipboardTextRequests;
     /**
      * Subscribe to zmux's mirror-socket path. The callback runs exactly once:
      * synchronously if the path is already known, otherwise as soon as zmux
@@ -151,6 +161,9 @@ export declare class TuiProcess {
      */
     readClipboardImage(timeoutMs?: number): Promise<Buffer | null>;
     private settleClipboardRequest;
+    /** Read exact text through the renderer; null means unavailable, '' means empty. */
+    readClipboardText(timeoutMs?: number): Promise<string | null>;
+    private settleClipboardTextRequest;
     /**
      * Mirror socket path this zmux is exposing, or null if unavailable
      * (non-zmux mode, bind failed, or announcement not received yet).
@@ -167,6 +180,8 @@ export declare class TuiProcess {
         mux?: boolean;
         headless?: boolean;
         desktop?: boolean;
+        /** Admission from this host's CLI bootstrap, never an environment cache. */
+        desktopRuntime?: DesktopRuntime | null;
         desktopUpdateRelaunch?: string;
         /** Extra environment for the renderer process (e.g. the zmux keymap). */
         env?: Record<string, string>;
@@ -218,6 +233,7 @@ export declare class NullTuiProcess {
     get zmuxMirrorSocketPath(): string | null;
     hasCapability(_name: string): boolean;
     readClipboardImage(): Promise<Buffer | null>;
+    readClipboardText(): Promise<string | null>;
     /** NullTuiProcess never has a mirror socket; callback never fires. */
     onZmuxMirrorSocketReady(_cb: (path: string) => void): () => void;
     on(handler: TuiEventHandler): () => void;

package/dist/ui/ratatui/process.js

@@ -15,8 +15,9 @@ import { join, dirname, resolve } from 'path';
 import { homedir, platform, arch, tmpdir } from 'os';
 import { fileURLToPath } from 'url';
 import { createConnection } from 'net';
-import { serializeCommand, parseEvent, CAPABILITY_CLIPBOARD_IMAGE } from './protocol.js';
-import { generateIpcPath } from './ipc_path.js';
+import { serializeCommand, parseEvent, CAPABILITY_CLIPBOARD_IMAGE, CAPABILITY_CLIPBOARD_TEXT } from './protocol.js';
+import { generateIpcPath, removeOwnedIpcPath } from './ipc_path.js';
+import { loadDesktopRuntime, validateDesktopRendererReady } from '../../desktop/runtime.js';
 // Debug log file - use a file to avoid interfering with TUI
 const DEBUG_LOG_FILE = join(tmpdir(), `ztc-debug-${process.pid}.log`);
 function debugLog(message) {
@@ -203,7 +204,10 @@ export function resolveZtermBinaryPath(dependencies) {
     return dependencies.resolveFallback();
 }
 /** Get the path to the zterm desktop binary. */
-function getZtermBinaryPath() {
+function getZtermBinaryPath(admission) {
+    const runtime = admission === undefined ? loadDesktopRuntime() : admission;
+    if (runtime)
+        return runtime.rendererPath;
     const binaryName = getZtermBinaryName();
     return resolveZtermBinaryPath({
         operatingSystem: platform(),
@@ -222,8 +226,8 @@ export function isZmuxAvailable() {
  * Check if zterm is available. Unlike zmux, zterm is a desktop process and
  * does not require the current process to have a TTY.
  */
-export function isZtermAvailable() {
-    return getZtermBinaryPath() !== null;
+export function isZtermAvailable(admission) {
+    return getZtermBinaryPath(admission) !== null;
 }
 /**
  * Launch the native zterm desktop binary and resolve with its exit code.
@@ -314,6 +318,11 @@ export function isTransientSocketConnectError(code) {
  * Manages the Rust TUI process with Unix socket communication
  */
 export class TuiProcess {
+    options;
+    /** Host-selected unmanaged renderer; validated bundle admission takes precedence. */
+    constructor(options = {}) {
+        this.options = options;
+    }
     process = null;
     socket = null;
     readline = null;
@@ -329,6 +338,9 @@ export class TuiProcess {
     _muxMode = false;
     /** Whether zterm is being used as the native desktop renderer */
     _desktopMode = false;
+    desktopCompatibility = null;
+    /** Retained across socket cleanup so an admitted renderer can request owner exit. */
+    desktopStartupAdmitted = false;
     stopping = false;
     /** Whether zmux was detected from the ready event version string */
     _isZmux = false;
@@ -354,6 +366,7 @@ export class TuiProcess {
      */
     clipboardRequests = new Map();
     clipboardRequestSeq = 0;
+    clipboardTextRequests = new Map();
     /**
      * Subscribe to zmux's mirror-socket path. The callback runs exactly once:
      * synchronously if the path is already known, otherwise as soon as zmux
@@ -436,6 +449,26 @@ export class TuiProcess {
         this.clipboardRequests.delete(requestId);
         pending.resolve(png);
     }
+    /** Read exact text through the renderer; null means unavailable, '' means empty. */
+    readClipboardText(timeoutMs = 4000) {
+        if (!this.hasCapability(CAPABILITY_CLIPBOARD_TEXT))
+            return Promise.resolve(null);
+        const requestId = `clip-text-${++this.clipboardRequestSeq}-${Date.now().toString(36)}`;
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => this.settleClipboardTextRequest(requestId, null), timeoutMs);
+            this.clipboardTextRequests.set(requestId, { resolve, timer });
+            if (!this.send({ type: 'read_clipboard_text', request_id: requestId }))
+                this.settleClipboardTextRequest(requestId, null);
+        });
+    }
+    settleClipboardTextRequest(requestId, text) {
+        const pending = this.clipboardTextRequests.get(requestId);
+        if (!pending)
+            return;
+        clearTimeout(pending.timer);
+        this.clipboardTextRequests.delete(requestId);
+        pending.resolve(text);
+    }
     /**
      * Mirror socket path this zmux is exposing, or null if unavailable
      * (non-zmux mode, bind failed, or announcement not received yet).
@@ -456,12 +489,21 @@ export class TuiProcess {
         }
         this._muxMode = options?.mux ?? false;
         this._desktopMode = options?.desktop ?? false;
+        this.desktopCompatibility = null;
+        this.desktopStartupAdmitted = false;
+        this._capabilities.clear();
+        this.stopping = false;
         let binaryPath;
         if (this._desktopMode) {
-            binaryPath = getZtermBinaryPath();
+            const runtime = options?.desktopRuntime === undefined ? loadDesktopRuntime() : options.desktopRuntime;
+            binaryPath = runtime?.rendererPath ?? this.options.desktopBinaryPath ?? getZtermBinaryPath(runtime);
             if (!binaryPath) {
                 throw new Error('zterm binary not found. Build with: cd packages/zterm && cargo build --release');
             }
+            if (runtime)
+                this.desktopCompatibility = { version: runtime.rendererVersion, requiredCapabilities: runtime.requiredCapabilities };
+            else if (binaryPath === resolveInstalledZtermExecutable())
+                this.desktopCompatibility = {};
         }
         else if (this._muxMode) {
             binaryPath = getZmuxBinaryPath();
@@ -576,7 +618,7 @@ export class TuiProcess {
             this.process.on('close', (code, signal) => {
                 debugLog(`[TuiProcess] Process closed: code=${code}, signal=${signal}`);
                 debugLog(`[TuiProcess] stderr buffer at close: ${stderrBuffer || '(empty)'}`);
-                const shouldExitOwner = this._desktopMode && this.readyReject === null && !this.stopping;
+                const shouldExitOwner = this._desktopMode && this.desktopStartupAdmitted && !this.stopping;
                 this.cleanup();
                 if (shouldExitOwner) {
                     this.emit({ type: 'quit_requested' });
@@ -734,7 +776,24 @@ export class TuiProcess {
                 this.settleClipboardRequest(event.request_id, event.png_base64 ? Buffer.from(event.png_base64, 'base64') : null);
                 return;
             }
+            if (event.type === 'clipboard_text') {
+                this.settleClipboardTextRequest(event.request_id, !event.error && typeof event.text === 'string' ? event.text : null);
+                return;
+            }
             if (event.type === 'ready' && this.readyResolve) {
+                if (this.desktopCompatibility) {
+                    try {
+                        validateDesktopRendererReady(event, this.desktopCompatibility.version, this.desktopCompatibility.requiredCapabilities);
+                    }
+                    catch (error) {
+                        this.readyReject?.(error);
+                        this.readyResolve = null;
+                        this.readyReject = null;
+                        this.cleanup();
+                        return;
+                    }
+                }
+                this.desktopStartupAdmitted = this._desktopMode;
                 this.ready = true;
                 this._isZmux = event.version.startsWith('zmux-') || event.version.startsWith('zterm-');
                 if (event.capabilities) {
@@ -783,6 +842,11 @@ export class TuiProcess {
             pending.resolve(null);
         }
         this.clipboardRequests.clear();
+        for (const pending of this.clipboardTextRequests.values()) {
+            clearTimeout(pending.timer);
+            pending.resolve(null);
+        }
+        this.clipboardTextRequests.clear();
         if (this.connectRetryTimer) {
             clearTimeout(this.connectRetryTimer);
             this.connectRetryTimer = null;
@@ -802,6 +866,12 @@ export class TuiProcess {
             catch {
                 // Ignore
             }
+            try {
+                removeOwnedIpcPath(this.socketPath);
+            }
+            catch (error) {
+                debugLog(`[TuiProcess] IPC directory cleanup failed: ${String(error)}`);
+            }
             this.socketPath = null;
         }
         // Tearing down without signalling a still-running child orphans the native
@@ -884,6 +954,9 @@ export class NullTuiProcess {
     readClipboardImage() {
         return Promise.resolve(null);
     }
+    readClipboardText() {
+        return Promise.resolve(null);
+    }
     /** NullTuiProcess never has a mirror socket; callback never fires. */
     onZmuxMirrorSocketReady(_cb) {
         return () => { };