termdock 1.4.322 → 1.4.325

package/dist/server/utils/autoUpdate.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { compareVersions, updateTermdockFromOfficialRegistry, } from './npmUpdate.js';
+import { compareVersions, verifyRunningTermdockInstallation, updateTermdockFromOfficialRegistry, } from './npmUpdate.js';
 export const AUTO_UPDATE_INITIAL_DELAY_MS = 15_000;
 export const AUTO_UPDATE_INTERVAL_MS = 6 * 60 * 60 * 1_000;
 function initialState(currentVersion) {
@@ -44,11 +44,11 @@ export class TermdockAutoUpdateManager {
             return;
         this.initialTimer = setTimeout(() => {
             this.initialTimer = null;
-            void this.checkNow();
+            void this.checkNow(false);
         }, AUTO_UPDATE_INITIAL_DELAY_MS);
         this.initialTimer.unref?.();
         this.intervalTimer = setInterval(() => {
-            void this.checkNow();
+            void this.checkNow(false);
         }, AUTO_UPDATE_INTERVAL_MS);
         this.intervalTimer.unref?.();
     }
@@ -60,12 +60,24 @@ export class TermdockAutoUpdateManager {
         this.initialTimer = null;
         this.intervalTimer = null;
     }
-    checkNow() {
+    checkNow(explicit = true) {
+        // Failed installation validation requires a user-requested check, not a timer retry.
+        if (!explicit && this.state.status === 'error' && hasPendingTermdockUpdate(this.state))
+            return Promise.resolve(this.getState());
         // Once an installed update is waiting for explicit confirmation, periodic
         // checks must never turn any external state change into implicit consent.
         // Keep the reminder until the user confirms or restarts manually.
         if (this.state.status === 'ready' && hasPendingTermdockUpdate(this.state)) {
-            return Promise.resolve(this.getState());
+            try {
+                this.verifyInstalled(this.state.latestVersion);
+                return Promise.resolve(this.getState());
+            }
+            catch (error) {
+                this.installationError(error);
+                if (!explicit)
+                    return Promise.resolve(this.getState());
+            }
+            // Only the explicit check repairs an invalid pending installation; never restart here.
         }
         if (this.checkPromise)
             return this.checkPromise;
@@ -78,10 +90,33 @@ export class TermdockAutoUpdateManager {
         if (this.state.status !== 'ready' || !hasPendingTermdockUpdate(this.state)) {
             throw new Error('No installed Termdock update is waiting for restart.');
         }
+        try {
+            this.verifyInstalled(this.state.latestVersion);
+            if (process.env.TERMDOCK_SUPERVISED !== '1' || !process.connected)
+                throw new Error('Automatic restart requires the verified supervised Termdock entry; restart manually.');
+            this.dependencies.verifyRestartEntry?.();
+        }
+        catch (error) {
+            this.installationError(error);
+            throw error;
+        }
         this.setState({ ...this.state, status: 'restarting', error: null });
-        this.dependencies.requestRestart();
+        try {
+            this.dependencies.requestRestart();
+        }
+        catch (error) {
+            this.installationError(error);
+            throw error;
+        }
         return this.getState();
     }
+    verifyInstalled(version) {
+        (this.dependencies.verifyInstalled ?? verifyRunningTermdockInstallation)(version);
+    }
+    installationError(error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        this.setState({ ...this.state, status: 'error', error: detail });
+    }
     async runCheck() {
         this.setState({ ...this.state, status: 'checking', checkedAt: Date.now(), error: null });
         try {
@@ -110,6 +145,7 @@ export class TermdockAutoUpdateManager {
                 });
                 return this.getState();
             }
+            this.verifyInstalled(result.latestVersion);
             this.setState({
                 status: 'ready',
                 currentVersion: result.currentVersion,
@@ -145,13 +181,24 @@ export class TermdockAutoUpdateManager {
                 return fallback;
             if (value.status !== 'ready' && value.status !== 'restarting' && value.status !== 'error')
                 return fallback;
+            let restoredStatus = value.status === 'restarting' ? 'ready' : value.status;
+            let restoredError = typeof value.error === 'string' ? value.error : null;
+            if (restoredStatus === 'ready') {
+                try {
+                    this.verifyInstalled(value.latestVersion);
+                }
+                catch (error) {
+                    restoredStatus = 'error';
+                    restoredError = error instanceof Error ? error.message : String(error);
+                }
+            }
             return {
-                status: value.status === 'restarting' ? 'ready' : value.status,
+                status: restoredStatus,
                 currentVersion: this.dependencies.currentVersion,
                 latestVersion: value.latestVersion,
                 source: value.source === 'configured' ? 'configured' : 'official',
                 checkedAt: typeof value.checkedAt === 'number' ? value.checkedAt : null,
-                error: typeof value.error === 'string' ? value.error : null,
+                error: restoredError,
             };
         }
         catch {

package/dist/server/utils/hostResources.js

@@ -0,0 +1,128 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { detectAgentFromCommand } from '../agent/registry.js';
+const execFileAsync = promisify(execFile);
+function parseMemAvailable(contents) {
+    const match = contents.match(/^MemAvailable:\s+(\d+)\s+kB$/m);
+    return match ? Number(match[1]) * 1024 : null;
+}
+function parsePressure(contents) {
+    const parse = (kind) => {
+        const line = contents.split('\n').find(item => item.startsWith(`${kind} `));
+        const value = line?.match(/\bavg10=([\d.]+)/)?.[1];
+        return value === undefined ? null : Number(value);
+    };
+    const someAvg10 = parse('some');
+    const fullAvg10 = parse('full');
+    return someAvg10 === null && fullAvg10 === null ? null : { someAvg10, fullAvg10 };
+}
+function parseProcesses(contents, customCommands = {}) {
+    return contents.split('\n').flatMap(line => {
+        const match = line.trim().match(/^(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(\d+)\s+(.*)$/);
+        if (!match)
+            return [];
+        const [, pidRaw, pgidRaw, state, ttyRaw, rssRaw, commandRaw] = match;
+        const pid = Number(pidRaw), processGroupId = Number(pgidRaw), rssKb = Number(rssRaw);
+        if (!Number.isSafeInteger(pid) || pid <= 0 || !Number.isSafeInteger(processGroupId) || processGroupId <= 0 || !Number.isFinite(rssKb))
+            return [];
+        const command = commandRaw ?? '';
+        const comm = (command.split(/\s+/, 1)[0] ?? '').toLowerCase().split('/').at(-1) ?? '';
+        return [{
+                pid, processGroupId, state: state ?? '?', tty: ttyRaw === '?' ? '' : ttyRaw, command,
+                rssBytes: Math.max(0, rssKb) * 1024,
+                agent: Boolean(detectAgentFromCommand(command, customCommands)),
+                browser: /^(chrome|chromium|firefox|webkit|agent-browser)(-|$)/.test(comm),
+                kswapd: /^\[?kswapd\d*\]?$/.test(comm),
+            }];
+    });
+}
+export async function collectHostResourceSnapshot(customCommands = {}) {
+    let memoryAvailableBytes = os.freemem();
+    let memorySnapshotAvailable = false;
+    let memoryPressure = null;
+    if (process.platform === 'linux') {
+        const [meminfo, pressure] = await Promise.all([
+            fs.readFile('/proc/meminfo', 'utf8').catch(() => ''),
+            fs.readFile('/proc/pressure/memory', 'utf8').catch(() => ''),
+        ]);
+        const parsedAvailable = parseMemAvailable(meminfo);
+        if (parsedAvailable !== null) {
+            memoryAvailableBytes = parsedAvailable;
+            memorySnapshotAvailable = true;
+        }
+        memoryPressure = parsePressure(pressure);
+    }
+    else {
+        memorySnapshotAvailable = Number.isFinite(memoryAvailableBytes);
+    }
+    let processRows = [];
+    let processSnapshotAvailable = false;
+    try {
+        const { stdout } = await execFileAsync('ps', ['-e', '-o', 'pid=,pgid=,stat=,tty=,rss=,args='], { timeout: 5000, maxBuffer: 8 * 1024 * 1024 });
+        processRows = parseProcesses(stdout, customCommands);
+        processSnapshotAvailable = processRows.length > 0;
+    }
+    catch { /* process metrics are diagnostic; memory admission remains fail-closed below */ }
+    const groupRss = new Map();
+    const agentGroupIds = new Set();
+    for (const row of processRows) {
+        groupRss.set(row.processGroupId, (groupRss.get(row.processGroupId) ?? 0) + row.rssBytes);
+        if (row.agent)
+            agentGroupIds.add(row.processGroupId);
+    }
+    const agentRss = [...agentGroupIds].reduce((sum, id) => sum + (groupRss.get(id) ?? 0), 0);
+    return {
+        sampledAt: Date.now(), platform: process.platform, memoryAvailableBytes, memoryTotalBytes: os.totalmem(), memoryPressure,
+        dStateProcessCount: processRows.filter(row => row.state.includes('D')).length,
+        kswapd: processRows.filter(row => row.kswapd).map(({ pid, state }) => ({ pid, state })),
+        residentAgentCount: agentGroupIds.size,
+        residentAgentRssBytes: agentRss,
+        browserProcessCount: processRows.filter(row => row.browser).length,
+        memorySnapshotAvailable,
+        processSnapshotAvailable,
+        processRows,
+    };
+}
+export function configuredAgentResourceBudget(env = process.env) {
+    const readMb = (key, fallback, min, max) => {
+        const raw = env[key];
+        if (raw === undefined || raw.trim() === '')
+            return fallback * 1024 ** 2;
+        const value = Number(raw);
+        if (!Number.isInteger(value) || value < min || value > max)
+            throw new Error(`${key} must be an integer from ${min} to ${max} MiB`);
+        return value * 1024 ** 2;
+    };
+    const readCount = (key, fallback, max) => {
+        const raw = env[key];
+        if (raw === undefined || raw.trim() === '')
+            return fallback;
+        const value = Number(raw);
+        if (!Number.isInteger(value) || value < 1 || value > max)
+            throw new Error(`${key} must be an integer from 1 to ${max}`);
+        return value;
+    };
+    return {
+        minAvailableBytes: readMb('TD_AGENT_MIN_AVAILABLE_MB', 2048, 256, 131072),
+        estimatedRssBytes: readMb('TD_AGENT_ESTIMATED_RSS_MB', 512, 64, 32768),
+        maxResidentAgents: readCount('TD_MAX_RESIDENT_AGENTS', 48, 10000),
+        maxAgentsPerGroup: readCount('TD_MAX_AGENTS_PER_GROUP', 32, 1000),
+    };
+}
+export function assessAgentResourceBudget(input) {
+    if (input.snapshot.memorySnapshotAvailable === false || input.snapshot.processSnapshotAvailable === false)
+        return { admitted: false, reason: 'RESOURCE_SNAPSHOT_UNAVAILABLE' };
+    const required = input.budget.minAvailableBytes + input.budget.estimatedRssBytes;
+    if (input.snapshot.memoryAvailableBytes < required)
+        return { admitted: false, reason: 'MEMORY_BUDGET_LOW' };
+    if (input.snapshot.residentAgentCount >= input.budget.maxResidentAgents)
+        return { admitted: false, reason: 'MAX_RESIDENT_AGENTS' };
+    if (input.residentAgentsInGroup >= input.budget.maxAgentsPerGroup)
+        return { admitted: false, reason: 'MAX_GROUP_AGENTS' };
+    return { admitted: true };
+}
+export function parseHostResourcesForTest(contents) {
+    return { memAvailableBytes: parseMemAvailable(contents.meminfo), pressure: parsePressure(contents.pressure), processes: parseProcesses(contents.ps) };
+}

package/dist/server/utils/npmUpdate.js

@@ -1,5 +1,8 @@
 import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 const execFileAsync = promisify(execFile);
 export const OFFICIAL_NPM_REGISTRY = 'https://registry.npmjs.org';
 const TERMDOCK_PACKAGE = 'termdock';
@@ -41,7 +44,7 @@ export function buildNpmViewArgs(registry = OFFICIAL_NPM_REGISTRY) {
         args.push('--registry', registry);
     return args;
 }
-export function buildNpmInstallArgs(version, registry = OFFICIAL_NPM_REGISTRY) {
+export function buildNpmInstallArgs(version, registry = OFFICIAL_NPM_REGISTRY, prefix) {
     if (!parseVersion(version))
         throw new Error(`Invalid Termdock version from npm: ${version}`);
     const args = [
@@ -49,11 +52,56 @@ export function buildNpmInstallArgs(version, registry = OFFICIAL_NPM_REGISTRY) {
         '--global',
         `${TERMDOCK_PACKAGE}@${version}`,
     ];
+    if (prefix)
+        args.push('--prefix', prefix);
     if (registry)
         args.push('--registry', registry);
     args.push('--foreground-scripts');
     return args;
 }
+function installedVersion(installation) {
+    // Fresh filesystem reads: npm replaces this package while this process keeps
+    // running old JS. Neither require/import caches nor TERMDOCK_VERSION attest it.
+    if (fs.realpathSync(installation.packageRoot) !== installation.packageRoot) {
+        throw new Error('Running Termdock installation changed location; check for updates again.');
+    }
+    const value = JSON.parse(fs.readFileSync(path.join(installation.packageRoot, 'package.json'), 'utf8'));
+    if (!value || typeof value !== 'object' || !('name' in value) || value.name !== TERMDOCK_PACKAGE
+        || !('version' in value) || typeof value.version !== 'string' || !parseVersion(value.version)) {
+        throw new Error('Running Termdock installation has invalid package metadata.');
+    }
+    return value.version;
+}
+/** Resolve the module which is actually running, never PATH's unrelated npm root. */
+export function resolveRunningTermdockInstallation(moduleUrl = import.meta.url, runningEntry = process.argv[1]) {
+    const moduleFile = fs.realpathSync(fileURLToPath(moduleUrl));
+    const packageRoot = path.resolve(path.dirname(moduleFile), '../../..');
+    const nodeModules = path.dirname(packageRoot);
+    if (path.basename(packageRoot) !== TERMDOCK_PACKAGE || path.basename(nodeModules) !== 'node_modules') {
+        throw new Error('Automatic updates require a supported global Termdock installation.');
+    }
+    const parent = path.dirname(nodeModules);
+    let prefix;
+    if (process.platform === 'win32')
+        prefix = parent;
+    else if (path.basename(parent) === 'lib')
+        prefix = path.dirname(parent);
+    else
+        throw new Error('Automatic updates require a supported global Termdock installation.');
+    const installation = { packageRoot, prefix };
+    // supervisor resolves and reuses this child's argv entry. A module loaded
+    // from another installation must never approve that different restart root.
+    if (!runningEntry || fs.realpathSync(runningEntry) !== path.join(packageRoot, 'dist/server/cli.js')) {
+        throw new Error('Running Termdock entry does not match its update installation.');
+    }
+    installedVersion(installation);
+    return installation;
+}
+export function verifyRunningTermdockInstallation(version, installation = resolveRunningTermdockInstallation()) {
+    if (compareVersions(installedVersion(installation), version) < 0) {
+        throw new Error('Running Termdock installation has not completed this update; check for updates again.');
+    }
+}
 export function parseNpmVersionOutput(output) {
     let value;
     try {
@@ -67,6 +115,26 @@ export function parseNpmVersionOutput(output) {
     }
     return value;
 }
+export function npmRuntimeEnvironment(execPath = process.execPath, env = process.env, platform = process.platform) {
+    const systemBins = platform === 'darwin' ? ['/opt/homebrew/bin', '/usr/local/bin'] : [];
+    return { ...env, PATH: [path.dirname(execPath), ...systemBins, env.PATH].filter(Boolean).join(path.delimiter) };
+}
+async function installEnvironment() {
+    const env = npmRuntimeEnvironment();
+    if (process.platform === 'darwin') {
+        // New CLT releases can leave node-gyp's implicit libc++ search path stale.
+        // Use the SDK selected by xcrun without changing the user's global setup.
+        const { stdout } = await execFileAsync('/usr/bin/xcrun', ['--show-sdk-path'], { timeout: 5000, env });
+        const sdk = stdout.trim();
+        const headers = path.join(sdk, 'usr/include/c++/v1');
+        if (!path.isAbsolute(sdk) || !fs.existsSync(path.join(headers, 'functional'))) {
+            throw new Error('macOS C++ SDK headers are unavailable. Install or repair Command Line Tools, then retry.');
+        }
+        env.SDKROOT = sdk;
+        env.CPLUS_INCLUDE_PATH = [headers, env.CPLUS_INCLUDE_PATH].filter(Boolean).join(path.delimiter);
+    }
+    return env;
+}
 function npmExecutable() {
     return process.platform === 'win32' ? 'npm.cmd' : 'npm';
 }
@@ -76,7 +144,7 @@ async function fetchLatestVersion(registry) {
         const result = await execFileAsync(npmExecutable(), buildNpmViewArgs(registry), {
             timeout: NPM_QUERY_TIMEOUT_MS,
             maxBuffer: 256 * 1024,
-            env: process.env,
+            env: npmRuntimeEnvironment(),
         });
         stdout = result.stdout;
     }
@@ -87,11 +155,15 @@ async function fetchLatestVersion(registry) {
     }
     return parseNpmVersionOutput(stdout);
 }
-function installVersion(version, registry) {
-    return new Promise((resolve, reject) => {
-        const child = spawn(npmExecutable(), buildNpmInstallArgs(version, registry), {
+export async function installTermdockVersion(version, registry, installation, executable = npmExecutable()) {
+    if (compareVersions(installedVersion(installation), version) > 0) {
+        throw new Error('Running Termdock location already contains a newer version; restart that installation manually.');
+    }
+    const env = await installEnvironment();
+    await new Promise((resolve, reject) => {
+        const child = spawn(executable, buildNpmInstallArgs(version, registry, installation.prefix), {
             stdio: 'inherit',
-            env: process.env,
+            env,
         });
         child.once('error', reject);
         child.once('exit', (code, signal) => {
@@ -103,6 +175,9 @@ function installVersion(version, registry) {
             reject(new Error(`npm failed to install Termdock (${reason}).`));
         });
     });
+    if (installedVersion(installation) !== version) {
+        throw new Error('npm did not install the requested version at the running Termdock location.');
+    }
 }
 export async function updateTermdockFromOfficialRegistry(currentVersion, onFallback, onLatest) {
     if (!parseVersion(currentVersion))
@@ -124,8 +199,9 @@ export async function updateTermdockFromOfficialRegistry(currentVersion, onFallb
         return { status: 'current', currentVersion, latestVersion, source };
     if (comparison > 0)
         return { status: 'newer-than-registry', currentVersion, latestVersion, source };
+    const installation = resolveRunningTermdockInstallation();
     try {
-        await installVersion(latestVersion, source === 'official' ? OFFICIAL_NPM_REGISTRY : null);
+        await installTermdockVersion(latestVersion, source === 'official' ? OFFICIAL_NPM_REGISTRY : null, installation);
     }
     catch (error) {
         if (source === 'configured')
@@ -133,7 +209,7 @@ export async function updateTermdockFromOfficialRegistry(currentVersion, onFallb
         const cause = error instanceof Error ? error : new Error(String(error));
         onFallback?.('install', cause);
         source = 'configured';
-        await installVersion(latestVersion, null);
+        await installTermdockVersion(latestVersion, null, installation);
     }
     return { status: 'updated', currentVersion, latestVersion, source };
 }

package/dist/server/utils/terminalPasteBuffer.js

@@ -0,0 +1,66 @@
+const START = '\x1b[200~';
+const END = '\x1b[201~';
+const MAX_BYTES = 1024 * 1024;
+const TIMEOUT_MS = 10_000;
+const INCOMPLETE = '粘贴内容未完整送达，已取消，请重新粘贴。';
+/** A socket owns its pending paste. Never expose its opening delimiter to the
+ * PTY until the closing delimiter has arrived, even across input records.
+ * Ordinary keyboard/mouse records remain synchronous and unbuffered. */
+export class TerminalPasteBuffer {
+    onTimeout;
+    pending = '';
+    startedAt = 0;
+    timer;
+    constructor(onTimeout) {
+        this.onTimeout = onTimeout;
+    }
+    push(data) {
+        const previousStart = this.startedAt;
+        const continuing = this.pending.length > 0;
+        const input = this.pending + data;
+        const output = [];
+        this.clear();
+        let offset = 0;
+        while (offset < input.length) {
+            const start = input.indexOf(START, offset);
+            if (start < 0) {
+                output.push(input.slice(offset));
+                break;
+            }
+            if (start > offset)
+                output.push(input.slice(offset, start));
+            const end = input.indexOf(END, start + START.length);
+            const nested = input.indexOf(START, start + START.length);
+            if (nested >= 0 && (end < 0 || nested < end))
+                throw new Error(INCOMPLETE);
+            const paste = input.slice(start, end < 0 ? undefined : end + END.length);
+            if (Buffer.byteLength(paste) > MAX_BYTES)
+                throw new Error('粘贴内容超过 1 MiB，请分段粘贴。');
+            if (end < 0) {
+                this.pending = paste;
+                this.startedAt = continuing && start === 0 ? previousStart : Date.now();
+                this.timer = setTimeout(() => { this.clear(); this.onTimeout(INCOMPLETE); }, Math.max(0, this.startedAt + TIMEOUT_MS - Date.now()));
+                this.timer.unref();
+                break;
+            }
+            output.push(paste);
+            offset = end + END.length;
+        }
+        return output;
+    }
+    /** HTTP input has no continuation stream. Reject its entire body on failure. */
+    complete(data) {
+        const output = this.push(data);
+        if (this.pending) {
+            this.clear();
+            throw new Error(INCOMPLETE);
+        }
+        return output;
+    }
+    clear() {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.pending = '';
+        this.startedAt = 0;
+    }
+}

package/dist/server/utils/tmuxClientCapabilities.js

@@ -15,6 +15,10 @@ export async function supportsTmuxClientFeatures(binary) {
 }
 export function buildTmuxAttachArgs(sessionName, supportsFeatures) {
     return [
+        // The Web/native terminal consumes UTF-8 regardless of the server launcher's
+        // locale. GUI-launched services may inherit C; tmux otherwise emits _ for
+        // non-ASCII cells before the encrypted output ever reaches the renderer.
+        '-u',
         ...(supportsFeatures ? ['-T', 'RGB,sync'] : []),
         'attach-session', '-t', sessionName,
     ];

package/dist/server/utils/tmuxCopySelection.js

@@ -0,0 +1,94 @@
+import { randomUUID } from 'node:crypto';
+export const TMUX_COPY_MAX_BYTES = 256 * 1024;
+const FORMAT = '#{session_id}\t#{pane_id}\t#{pane_in_mode}\t#{selection_present}';
+function state(value) {
+    const parts = value.replace(/\r?\n$/, '').split('\t');
+    if (parts.length !== 4 || !/^\$\d+$/.test(parts[0]) || !/^%\d+$/.test(parts[1]) || !/^[01]$/.test(parts[2]) || !/^[01]?$/.test(parts[3]))
+        throw new Error('Tmux selection state was not confirmed');
+    return { session: parts[0], pane: parts[1], inMode: parts[2] === '1', selected: parts[3] === '1' };
+}
+/** Read this session's current selection through a unique, self-owned buffer.
+ * No global last-buffer read, shell copy command, clipboard write or mode exit. */
+export async function copyTmuxSelection(target, run) {
+    if (!target.trim() || /[\0\r\n]/.test(target))
+        throw new Error('Invalid tmux selection target');
+    const exact = `=${target}:`;
+    const read = () => run(['display-message', '-t', exact, '-p', FORMAT], { maxBuffer: 1024 }).then(state);
+    const before = await read();
+    const empty = () => ({ status: 'empty', paneId: before.pane, text: '', bytes: 0 });
+    if (!before.inMode || !before.selected)
+        return empty();
+    const prefix = `termdock-copy-${randomUUID()}-`;
+    const own = new RegExp(`^${prefix}[0-9]+$`);
+    const buffers = [];
+    let failed = false;
+    let primaryError;
+    const listArgs = ['list-buffers', '-f', `#{m:${prefix}*,#{buffer_name}}`, '-F', '#{buffer_name}\t#{buffer_size}'];
+    try {
+        await run(['send-keys', '-t', before.pane, '-X', 'copy-selection-no-clear', prefix], { maxBuffer: 1024 });
+        const metadata = await run(listArgs, { maxBuffer: 64 * 1024 });
+        for (const line of metadata.split('\n').filter(Boolean)) {
+            const [name, count] = line.split('\t');
+            if (!own.test(name))
+                throw new Error('Tmux returned an unowned selection buffer');
+            buffers.push({ name, bytes: Number(count) });
+            if (!/^\d+$/.test(count) || !Number.isSafeInteger(Number(count)))
+                throw new Error('Invalid owned tmux buffer metadata');
+        }
+        if (!buffers.length)
+            return empty();
+        if (buffers.length !== 1)
+            throw new Error('Tmux produced ambiguous selection buffers');
+        const buffer = buffers[0];
+        if (buffer.bytes > TMUX_COPY_MAX_BYTES)
+            throw new Error('Tmux selection exceeds the 256 KiB copy limit');
+        const text = await run(['save-buffer', '-b', buffer.name, '-'], { maxBuffer: TMUX_COPY_MAX_BYTES + 1 });
+        const after = await read();
+        if (after.session !== before.session || after.pane !== before.pane || !after.inMode || !after.selected)
+            throw new Error('Tmux selection target changed while copying');
+        const bytes = Buffer.byteLength(text, 'utf8');
+        if (bytes !== buffer.bytes || bytes > TMUX_COPY_MAX_BYTES)
+            throw new Error('Tmux selection was not read completely');
+        return bytes ? { status: 'copied', paneId: before.pane, text, bytes } : empty();
+    }
+    catch (error) {
+        failed = true;
+        primaryError = error;
+        throw error;
+    }
+    finally {
+        // A command may create its buffer before its reply fails. Enumerate only
+        // this UUID prefix even after metadata failure and attempt every own delete.
+        const names = new Set(buffers.map(buffer => buffer.name));
+        const cleanupErrors = [];
+        try {
+            const remaining = await run(listArgs, { maxBuffer: 64 * 1024 });
+            for (const line of remaining.split('\n').filter(Boolean)) {
+                const name = line.split('\t')[0];
+                if (!own.test(name)) {
+                    cleanupErrors.push(new Error('Tmux cleanup returned an unowned buffer'));
+                    continue;
+                }
+                names.add(name);
+            }
+        }
+        catch (error) {
+            cleanupErrors.push(error);
+        }
+        for (const name of names) {
+            try {
+                await run(['delete-buffer', '-b', name], { maxBuffer: 1024 });
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+        }
+        if (cleanupErrors.length) {
+            const error = new AggregateError(cleanupErrors, 'Owned tmux copy buffer cleanup failed');
+            if (!failed)
+                throw error;
+            if (primaryError instanceof Error)
+                primaryError.cause = error;
+        }
+    }
+}

package/dist/server/utils/tmuxEmptyServerProbe.js

@@ -0,0 +1,15 @@
+/** A has-session failure is not evidence that tmux itself is unavailable.
+ * Confirm this one empty-server case without changing generic error handling. */
+export async function isConfirmedEmptyTmuxServer(error, target, run) {
+    if (!target.trim() || !error || typeof error !== 'object')
+        return false;
+    const value = error;
+    if (value.code !== 1 || typeof value.stderr !== 'string' || value.stderr.trim() !== 'no current target')
+        return false;
+    try {
+        return (await run(['list-sessions', '-F', '#{session_id}'])).trim() === '';
+    }
+    catch {
+        return false;
+    }
+}