herdr-remote 0.2.25 → 0.2.26

package/README.md

@@ -32,11 +32,19 @@ herdr-remote start | stop | restart
 herdr-remote status [--json]
 herdr-remote pair [--json]
 herdr-remote url
+herdr-remote admin-broker install | uninstall | status # Windows
 herdr-remote keepalive install | uninstall | restart | status
 herdr-remote plugin link | unlink | status
 herdr-remote --lang zh|en
 ```
 
+On Windows, the TUI's **Keep-alive** page can register a per-user Task Scheduler broker with highest
+privileges and start it for the signed-in account. Choose **Set up admin terminal access** and
+approve the one-time Windows prompt under the same account as Herdr Remote; paired WebUI windows
+can then open a standalone elevated PowerShell without another UAC prompt. The CLI
+`admin-broker install` and `admin-broker uninstall` commands are also available for administrators.
+Use `admin-broker status` to check the broker.
+
 ## Herdr Plugin
 
 Register as a native Herdr plugin:

package/README.zh-CN.md

@@ -32,11 +32,14 @@ herdr-remote start | stop | restart
 herdr-remote status [--json]
 herdr-remote pair [--json]
 herdr-remote url
+herdr-remote admin-broker install | uninstall | status # Windows
 herdr-remote keepalive install | uninstall | restart | status
 herdr-remote plugin link | unlink | status
 herdr-remote --lang zh|en
 ```
 
+在 Windows 上，可在 TUI 的「保活」页面注册以当前账户最高权限运行的计划任务并启动 broker。选择「设置管理员终端」，使用运行 Herdr Remote 的同一账户批准一次 Windows 提权提示；之后，已配对的 WebUI 窗口可以新建独立的管理员 PowerShell，不再重复弹出 UAC。也可以使用 `admin-broker install` 和 `admin-broker uninstall` 命令管理任务，使用 `admin-broker status` 检查 broker。
+
 ## Herdr 插件
 
 注册为 Herdr 插件：

package/dist/cli.js

@@ -26,6 +26,7 @@ Commands:
   pair [--json]        Create pairing code
   url                  Print browser access URL
   run [--daemon]       Run services in foreground (keep-alive)
+  admin-broker install | uninstall | status (Windows)
   keepalive <action>   install | uninstall | restart | status
   plugin <action>      link | unlink | status  (Herdr plugin)
 
@@ -222,6 +223,25 @@ async function main(argv = process.argv.slice(2)) {
             await runForeground({ logToFiles: Boolean(flags.daemon) });
             return;
         }
+        case 'admin-broker': {
+            const broker = await import('./connector/admin-broker.js');
+            const action = positional[1] || 'status';
+            if (action === 'install') {
+                broker.installAdminBroker(t);
+                printJson({ installed: true, available: await broker.adminBrokerStatus() });
+            }
+            else if (action === 'uninstall') {
+                broker.uninstallAdminBroker(t);
+                printJson({ installed: false });
+            }
+            else if (action === 'status') {
+                printJson({ available: await broker.adminBrokerStatus() });
+            }
+            else {
+                throw new Error(`unknown administrator broker action: ${action}`);
+            }
+            return;
+        }
         case 'keepalive': {
             const keepalive = await import('./keepalive/index.js');
             const action = positional[1] || 'status';

package/dist/connector/admin-broker-setup.js

@@ -0,0 +1,40 @@
+import { spawn } from 'node:child_process';
+import { cliEntryPoint } from '../keepalive/environment.js';
+import { encodePowerShellCommand, escapePowerShellSingleQuoted, } from '../keepalive/windows-service.js';
+function waitForChild(child) {
+    return new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('close', (code) => resolve(code ?? 1));
+    });
+}
+export function renderAdminBrokerElevationScript({ action, nodePath, entryPoint, }) {
+    const quote = escapePowerShellSingleQuoted;
+    const args = `"${entryPoint}" admin-broker ${action} --elevated`;
+    return `$ErrorActionPreference = 'Stop'
+try {
+  $process = Start-Process -FilePath '${quote(nodePath)}' -ArgumentList '${quote(args)}' -Verb RunAs -Wait -PassThru -WindowStyle Hidden
+} catch {
+  if (($_.Exception.HResult -band 65535) -eq 1223) { exit 1223 }
+  exit 1
+}
+exit $process.ExitCode`;
+}
+function elevatedErrorCode(message, code) {
+    return Object.assign(new Error(message), { code });
+}
+/** Register the per-user task from the Windows TUI, requesting elevation once. */
+export async function configureAdminBroker(action, t) {
+    if (process.platform !== 'win32')
+        throw new Error(t('adminBroker.windowsOnly'));
+    const script = renderAdminBrokerElevationScript({
+        action,
+        nodePath: process.execPath,
+        entryPoint: cliEntryPoint(),
+    });
+    const child = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', encodePowerShellCommand(script)], { windowsHide: true, stdio: 'ignore' });
+    const exitCode = await waitForChild(child);
+    if (exitCode === 1223)
+        throw elevatedErrorCode(t('adminBroker.elevationCancelled'), 'ELEVATION_CANCELLED');
+    if (exitCode !== 0)
+        throw new Error(t('adminBroker.setupFailed'));
+}

package/dist/connector/admin-broker.js

@@ -0,0 +1,208 @@
+import { execFileSync } from 'node:child_process';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PtySession } from '../pty-session.js';
+import { PACKAGE_ROOT } from '../paths.js';
+import { ADMIN_BROKER_MAX_MESSAGE_BYTES, adminBrokerPipePath, adminBrokerTaskName, sendAdminBrokerMessage, } from './adminBrokerPipe.js';
+const BROKER_PING_TIMEOUT_MS = 1_000;
+function powershellQuote(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function runPowerShell(script, t) {
+    try {
+        execFileSync('powershell.exe', [
+            '-NoProfile',
+            '-NonInteractive',
+            '-EncodedCommand',
+            Buffer.from(script, 'utf16le').toString('base64'),
+        ], {
+            stdio: 'pipe',
+            windowsHide: true,
+            timeout: 15_000,
+        });
+    }
+    catch {
+        throw new Error(t('adminBroker.needsElevation'));
+    }
+}
+export function installAdminBroker(t) {
+    if (process.platform !== 'win32')
+        throw new Error(t('adminBroker.windowsOnly'));
+    const brokerPath = fileURLToPath(import.meta.url);
+    const brokerCommand = `& ${powershellQuote(process.execPath)} ${powershellQuote(brokerPath)}`;
+    const encodedBrokerCommand = Buffer.from(brokerCommand, 'utf16le').toString('base64');
+    const powershell = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+    const script = `
+$ErrorActionPreference = 'Stop'
+$taskName = ${powershellQuote(adminBrokerTaskName())}
+$user = [Security.Principal.WindowsIdentity]::GetCurrent().Name
+$action = New-ScheduledTaskAction -Execute ${powershellQuote(powershell)} -Argument ${powershellQuote(`-NoProfile -NonInteractive -WindowStyle Hidden -EncodedCommand ${encodedBrokerCommand}`)} -WorkingDirectory ${powershellQuote(PACKAGE_ROOT)}
+$trigger = New-ScheduledTaskTrigger -AtLogOn -User $user
+$principal = New-ScheduledTaskPrincipal -UserId $user -LogonType Interactive -RunLevel Highest
+$settings = New-ScheduledTaskSettingsSet -MultipleInstances IgnoreNew -StartWhenAvailable -ExecutionTimeLimit (New-TimeSpan -Seconds 0)
+Stop-ScheduledTask -TaskName $taskName -ErrorAction SilentlyContinue
+Register-ScheduledTask -TaskName $taskName -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Force | Out-Null
+Start-ScheduledTask -TaskName $taskName
+`;
+    runPowerShell(script, t);
+}
+export function uninstallAdminBroker(t) {
+    if (process.platform !== 'win32')
+        throw new Error(t('adminBroker.windowsOnly'));
+    runPowerShell(`
+$ErrorActionPreference = 'Stop'
+$taskName = ${powershellQuote(adminBrokerTaskName())}
+Stop-ScheduledTask -TaskName $taskName -ErrorAction SilentlyContinue
+Unregister-ScheduledTask -TaskName $taskName -Confirm:$false -ErrorAction SilentlyContinue
+`, t);
+}
+export function adminBrokerStatus() {
+    if (process.platform !== 'win32')
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        let settled = false;
+        let response = '';
+        const socket = net.createConnection(adminBrokerPipePath());
+        const finish = (available) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(available);
+        };
+        socket.setTimeout(BROKER_PING_TIMEOUT_MS, () => finish(false));
+        socket.setEncoding('utf8');
+        socket.on('connect', () => sendAdminBrokerMessage(socket, { type: 'ping' }));
+        socket.on('data', (chunk) => {
+            response += chunk;
+            if (response.includes('\n'))
+                finish(response.includes('"type":"pong"'));
+        });
+        socket.on('error', () => finish(false));
+    });
+}
+function writeError(socket, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    sendAdminBrokerMessage(socket, { type: 'error', message });
+    socket.end();
+}
+function startBrokerPty(socket, message) {
+    if (typeof message.command !== 'string' || !message.command || message.command.length > 4096)
+        throw new Error('Invalid administrator terminal command.');
+    if (path.basename(message.command).toLowerCase() !== 'powershell.exe')
+        throw new Error('The administrator broker only starts PowerShell.');
+    if (!Array.isArray(message.args) ||
+        message.args.length > 128 ||
+        !message.args.every((arg) => typeof arg === 'string'))
+        throw new Error('Invalid administrator terminal arguments.');
+    if (message.args.length !== 2 ||
+        message.args[0] !== '-NoLogo' ||
+        message.args[1] !== '-NoProfile')
+        throw new Error('The administrator broker only starts an interactive PowerShell prompt.');
+    if (typeof message.cwd !== 'string' || message.cwd.length > 4096)
+        throw new Error('Invalid administrator terminal working directory.');
+    if (message.socketPath !== null && message.socketPath !== undefined)
+        throw new Error('An administrator PowerShell session does not use a Herdr socket.');
+    const pty = new PtySession({
+        command: message.command,
+        args: message.args,
+        cwd: message.cwd,
+        socketPath: message.socketPath,
+        platform: 'win32',
+        // A plain PowerShell prompt does not need the Herdr UI's Kitty or mouse modes.
+        fastWindowsPty: true,
+    });
+    pty.start({
+        cols: PtySession.clampDimension(message.cols, PtySession.DEFAULT_COLS),
+        rows: PtySession.clampDimension(message.rows, PtySession.DEFAULT_ROWS),
+        onData: (data) => {
+            if (socket.writable)
+                sendAdminBrokerMessage(socket, {
+                    type: 'data',
+                    dataBase64: Buffer.from(data).toString('base64'),
+                });
+        },
+        onExit: ({ exitCode, signal }) => {
+            if (socket.writable)
+                sendAdminBrokerMessage(socket, { type: 'exit', exitCode, signal });
+            socket.end();
+        },
+    });
+    sendAdminBrokerMessage(socket, { type: 'started', pid: pty.terminal?.pid ?? 0 });
+    return pty;
+}
+function runAdminBroker() {
+    if (process.platform !== 'win32')
+        throw new Error('Administrator PTYs are only supported on Windows.');
+    const server = net.createServer((socket) => {
+        socket.setEncoding('utf8');
+        let pending = '';
+        let pty = null;
+        let firstMessage = true;
+        socket.on('data', (chunk) => {
+            pending += chunk;
+            if (Buffer.byteLength(pending, 'utf8') > ADMIN_BROKER_MAX_MESSAGE_BYTES) {
+                socket.destroy(new Error('Administrator terminal message exceeded the limit.'));
+                return;
+            }
+            while (true) {
+                const newline = pending.indexOf('\n');
+                if (newline < 0)
+                    return;
+                const line = pending.slice(0, newline);
+                pending = pending.slice(newline + 1);
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    writeError(socket, new Error('Invalid administrator terminal message.'));
+                    return;
+                }
+                if (firstMessage) {
+                    firstMessage = false;
+                    if (message.type === 'ping') {
+                        sendAdminBrokerMessage(socket, { type: 'pong' });
+                        socket.end();
+                        return;
+                    }
+                    if (message.type !== 'start') {
+                        writeError(socket, new Error('Expected an administrator terminal start request.'));
+                        return;
+                    }
+                    try {
+                        pty = startBrokerPty(socket, message);
+                    }
+                    catch (error) {
+                        writeError(socket, error);
+                        return;
+                    }
+                    continue;
+                }
+                if (!pty)
+                    return;
+                if (message.type === 'input' && typeof message.dataBase64 === 'string') {
+                    if (message.dataBase64.length <= ADMIN_BROKER_MAX_MESSAGE_BYTES)
+                        pty.write(Buffer.from(message.dataBase64, 'base64'));
+                }
+                else if (message.type === 'resize') {
+                    pty.resize(message.cols, message.rows);
+                }
+                else if (message.type === 'kill') {
+                    pty.kill();
+                    socket.end();
+                    return;
+                }
+            }
+        });
+        socket.on('close', () => pty?.kill());
+        socket.on('error', () => pty?.kill());
+    });
+    server.listen(adminBrokerPipePath());
+    server.on('error', (error) => {
+        process.stderr.write(`herdr-remote administrator broker: ${error.message}\n`);
+    });
+}
+if (path.basename(process.argv[1] || '') === 'admin-broker.js')
+    runAdminBroker();

package/dist/connector/adminBrokerPipe.js

@@ -0,0 +1,16 @@
+import { createHash } from 'node:crypto';
+const ADMIN_BROKER_TASK_NAME = 'HerdrRemoteAdminBroker';
+export const ADMIN_BROKER_MAX_MESSAGE_BYTES = 2 * 1_024 * 1_024;
+function adminBrokerAccountId() {
+    const account = `${process.env.USERDOMAIN || ''}\\${process.env.USERNAME || process.env.USERPROFILE || 'default'}`;
+    return createHash('sha256').update(account.toLowerCase()).digest('hex').slice(0, 24);
+}
+export function adminBrokerPipePath() {
+    return `\\\\.\\pipe\\herdr-remote-admin-${adminBrokerAccountId()}`;
+}
+export function adminBrokerTaskName() {
+    return `${ADMIN_BROKER_TASK_NAME}-${adminBrokerAccountId()}`;
+}
+export function sendAdminBrokerMessage(socket, message) {
+    socket.write(`${JSON.stringify(message)}\n`);
+}

package/dist/connector/elevatedPty.js

@@ -0,0 +1,145 @@
+import net from 'node:net';
+import { ADMIN_BROKER_MAX_MESSAGE_BYTES, adminBrokerPipePath, sendAdminBrokerMessage, } from './adminBrokerPipe.js';
+const BROKER_CONNECT_TIMEOUT_MS = 5_000;
+export class ElevatedPty {
+    pid = 0;
+    cols;
+    rows;
+    socket = null;
+    input = '';
+    connected = false;
+    started = false;
+    finished = false;
+    killed = false;
+    dataListener = null;
+    exitListener = null;
+    readyListener = null;
+    errorListener = null;
+    options;
+    constructor(options, cols, rows) {
+        this.options = options;
+        this.cols = cols;
+        this.rows = rows;
+    }
+    onData(listener) {
+        this.dataListener = listener;
+    }
+    onExit(listener) {
+        this.exitListener = listener;
+    }
+    start({ cols, rows, onData, onExit, onReady, onError }) {
+        this.cols = cols;
+        this.rows = rows;
+        this.dataListener = onData;
+        this.exitListener = onExit;
+        this.readyListener = onReady || null;
+        this.errorListener = onError || null;
+        const socket = net.createConnection(adminBrokerPipePath());
+        this.socket = socket;
+        socket.setEncoding('utf8');
+        socket.setTimeout(BROKER_CONNECT_TIMEOUT_MS, () => {
+            socket.destroy(new Error('Administrator terminal broker connection timed out'));
+        });
+        socket.on('connect', () => {
+            this.connected = true;
+            socket.setTimeout(0);
+            sendAdminBrokerMessage(socket, {
+                type: 'start',
+                ...this.options,
+                cols: this.cols,
+                rows: this.rows,
+            });
+        });
+        socket.on('data', (chunk) => this.receive(chunk));
+        socket.on('error', (error) => this.fail(error));
+        socket.on('close', () => {
+            if (this.started && !this.finished && !this.killed) {
+                this.finished = true;
+                this.exitListener?.({ exitCode: 1 });
+            }
+        });
+    }
+    write(data) {
+        if (this.started && !this.finished && this.socket?.writable) {
+            sendAdminBrokerMessage(this.socket, {
+                type: 'input',
+                dataBase64: Buffer.from(data).toString('base64'),
+            });
+        }
+    }
+    resize(cols, rows) {
+        this.cols = cols;
+        this.rows = rows;
+        if (this.started && this.socket?.writable) {
+            sendAdminBrokerMessage(this.socket, { type: 'resize', cols, rows });
+        }
+    }
+    kill() {
+        this.killed = true;
+        this.pid = 0;
+        if (!this.socket)
+            return;
+        if (this.connected && this.socket.writable) {
+            sendAdminBrokerMessage(this.socket, { type: 'kill' });
+            this.socket.end();
+        }
+        else {
+            this.socket.destroy();
+        }
+    }
+    receive(chunk) {
+        this.input += chunk;
+        if (Buffer.byteLength(this.input, 'utf8') > ADMIN_BROKER_MAX_MESSAGE_BYTES) {
+            this.socket?.destroy(new Error('Administrator terminal broker message exceeded the limit'));
+            return;
+        }
+        while (true) {
+            const newline = this.input.indexOf('\n');
+            if (newline < 0)
+                return;
+            const line = this.input.slice(0, newline);
+            this.input = this.input.slice(newline + 1);
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                this.socket?.destroy(new Error('Administrator terminal broker sent invalid JSON'));
+                return;
+            }
+            if (message.type === 'started') {
+                this.started = true;
+                this.pid = Number(message.pid) || 0;
+                this.readyListener?.();
+            }
+            else if (message.type === 'data' && typeof message.dataBase64 === 'string') {
+                this.dataListener?.(Buffer.from(message.dataBase64, 'base64').toString('utf8'));
+            }
+            else if (message.type === 'exit') {
+                this.finished = true;
+                this.pid = 0;
+                this.exitListener?.({
+                    exitCode: Number(message.exitCode) || 0,
+                    ...(typeof message.signal === 'number' ? { signal: message.signal } : {}),
+                });
+                this.socket?.end();
+            }
+            else if (message.type === 'error') {
+                this.fail(new Error(typeof message.message === 'string' ? message.message : 'Admin PTY failed'));
+            }
+        }
+    }
+    fail(error) {
+        if (this.started) {
+            if (!this.finished && !this.killed) {
+                this.finished = true;
+                this.exitListener?.({ exitCode: 1 });
+            }
+            return;
+        }
+        if (this.finished || this.killed)
+            return;
+        this.finished = true;
+        this.errorListener?.(error);
+    }
+}

package/dist/connector/host-connector.js

@@ -185,10 +185,19 @@ export class HostConnector {
                 password: this.relayPassword || null,
                 hostname: os.hostname(),
                 platform: process.platform,
+                ...(process.platform === 'win32' &&
+                    (process.env.MSYSTEM || /(?:^|[\\/])(?:bash|sh)(?:\.exe)?$/i.test(process.env.SHELL || ''))
+                    ? { shellProfile: 'git-bash' }
+                    : {}),
                 arch: process.arch,
                 terminalPalette: this.terminalPalette || null,
                 terminalFont: this.font.publicFont(),
-                capabilities: [CAPABILITY.hostHandoff, CAPABILITY.idleHeartbeat, CAPABILITY.binaryFrameV2],
+                capabilities: [
+                    CAPABILITY.hostHandoff,
+                    CAPABILITY.idleHeartbeat,
+                    CAPABILITY.binaryFrameV2,
+                    ...(process.platform === 'win32' ? [CAPABILITY.adminSessions] : []),
+                ],
             });
             // The relay sends host_ready with the current browser count. No business
             // heartbeat is started until that message says somebody is watching.

package/dist/connector/sessions.js

@@ -11,6 +11,8 @@ import { streamOf } from './wire.js';
  * session the user actually used and then left.
  */
 const FAST_FAILURE_MS = 1500;
+/** Coalesce Windows ConPTY's many small output chunks before they reach the relay. */
+const WINDOWS_OUTPUT_BATCH_MS = 4;
 /** How many broken starts in a row before we stop calling them exits. */
 export const FAST_FAILURE_LIMIT = 3;
 export class Sessions {
@@ -103,6 +105,10 @@ export class Sessions {
         if (!streamId)
             return undefined;
         this.stop(streamId);
+        if (message.adminTerminal) {
+            this.spawn(message);
+            return undefined;
+        }
         const missingHerdr = this.ensureHerdrCommand();
         if (missingHerdr) {
             process.stderr.write(`herdr-remote host connector: ${missingHerdr}\n`);
@@ -198,11 +204,15 @@ export class Sessions {
     spawn(message) {
         const streamId = streamOf(message);
         const streamIndex = typeof message.streamIndex === 'number' ? message.streamIndex : null;
+        const adminTerminal = message.adminTerminal === true;
+        // The normal Herdr server keeps its original token, so admin mode needs its own shell.
         const pty = new this.Pty({
-            command: this.herdrCommand,
-            args: this.herdrArgs,
+            command: adminTerminal ? 'powershell.exe' : this.herdrCommand,
+            args: adminTerminal ? ['-NoLogo', '-NoProfile'] : this.herdrArgs,
             cwd: this.cwd,
-            socketPath: this.socketPath,
+            socketPath: adminTerminal ? null : this.socketPath,
+            adminTerminal,
+            fastWindowsPty: adminTerminal,
         });
         const session = {
             id: streamId,
@@ -214,12 +224,17 @@ export class Sessions {
             startedAtMs: Date.now(),
             pendingOutput: [],
             flushImmediate: null,
+            flushTimeout: null,
         };
         const flushOutput = () => {
             if (session.flushImmediate) {
                 clearImmediate(session.flushImmediate);
                 session.flushImmediate = null;
             }
+            if (session.flushTimeout) {
+                clearTimeout(session.flushTimeout);
+                session.flushTimeout = null;
+            }
             if (session.pendingOutput.length === 0)
                 return;
             const payload = Buffer.concat(session.pendingOutput);
@@ -228,6 +243,29 @@ export class Sessions {
                 ? packStreamFrameV2(FRAME_TYPE_OUTPUT, session.streamIndex, payload)
                 : packStreamFrame('output', streamId, payload));
         };
+        let readySent = false;
+        const reportReady = () => {
+            if (readySent || this.byStream.get(streamId) !== session)
+                return;
+            readySent = true;
+            this.link.send({ type: 'session_ready', clientId: streamId });
+        };
+        const reportStartError = (error) => {
+            if (this.byStream.get(streamId) !== session)
+                return;
+            this.forget(session);
+            session.pty.kill();
+            const code = error.code;
+            const brokerUnavailable = session.pty.adminTerminal &&
+                (code === 'ENOENT' || code === 'ECONNREFUSED' || code === 'ETIMEDOUT');
+            this.sendError(streamId, brokerUnavailable ? 'admin_broker_unavailable' : 'pty_start_failed', brokerUnavailable
+                ? 'Run herdr-remote admin-broker install once from an administrator terminal.'
+                : error.message);
+            this.link.changed();
+        };
+        this.byStream.set(streamId, session);
+        if (streamIndex !== null)
+            this.streamIndexToId.set(streamIndex, streamId);
         try {
             pty.start({
                 cols: session.cols,
@@ -237,10 +275,14 @@ export class Sessions {
                     if (chunk.length === 0)
                         return;
                     session.pendingOutput.push(chunk);
-                    // Coalesce burst output from the same tick into a single frame to reduce
-                    // packet overhead without introducing timer latency.
-                    if (!session.flushImmediate)
-                        session.flushImmediate = setImmediate(flushOutput);
+                    if (!session.flushImmediate && !session.flushTimeout) {
+                        if (process.platform === 'win32') {
+                            session.flushTimeout = setTimeout(flushOutput, WINDOWS_OUTPUT_BATCH_MS);
+                        }
+                        else {
+                            session.flushImmediate = setImmediate(flushOutput);
+                        }
+                    }
                 },
                 onExit: ({ exitCode }) => {
                     if (this.byStream.get(streamId) !== session)
@@ -249,18 +291,16 @@ export class Sessions {
                     this.reportExit(session, exitCode);
                     this.link.changed();
                 },
+                onReady: reportReady,
+                onError: reportStartError,
             });
+            if (!adminTerminal)
+                reportReady();
         }
         catch (error) {
-            discardOutput(session);
-            this.sendError(streamId, 'pty_start_failed', error.message);
-            pty.kill();
+            reportStartError(error);
             return;
         }
-        this.byStream.set(streamId, session);
-        if (streamIndex !== null)
-            this.streamIndexToId.set(streamIndex, streamId);
-        this.link.send({ type: 'session_ready', clientId: streamId });
         this.link.changed();
     }
     /**
@@ -362,5 +402,9 @@ function discardOutput(session) {
         clearImmediate(session.flushImmediate);
         session.flushImmediate = null;
     }
+    if (session.flushTimeout) {
+        clearTimeout(session.flushTimeout);
+        session.flushTimeout = null;
+    }
     session.pendingOutput = [];
 }

package/dist/i18n/en.js

@@ -84,6 +84,19 @@ const en = {
     'services.logEmpty': 'No logs.',
     'services.logRelay': 'Relay',
     'services.logHost': 'Host connector',
+    'adminBroker.windowsOnly': 'The administrator terminal broker only runs on Windows.',
+    'adminBroker.needsElevation': 'Open the Windows TUI and choose Set up admin terminal access. Approve the one-time Windows prompt under the same account as Herdr Remote.',
+    'adminBroker.title': 'Admin terminal broker',
+    'adminBroker.checking': 'Checking…',
+    'adminBroker.ready': 'Ready',
+    'adminBroker.notReady': 'Not configured or stopped',
+    'adminBroker.install': 'Set up admin terminal access',
+    'adminBroker.uninstall': 'Remove admin terminal access',
+    'adminBroker.installDone': 'Admin terminal broker setup task registered.',
+    'adminBroker.uninstallDone': 'Admin terminal broker setup task removed.',
+    'adminBroker.elevationCancelled': 'Administrator approval was declined; no changes were made.',
+    'adminBroker.setupFailed': 'Could not configure the administrator terminal broker.',
+    'adminBroker.tuiHint': 'Set this up once. Windows asks for administrator approval; later WebUI admin terminals open without UAC.',
     'relay.title': 'Relay settings',
     'relay.settings': 'Settings',
     'relay.locked': 'fixed',

package/dist/i18n/zh.js

@@ -83,6 +83,19 @@ const zh = {
     'services.logEmpty': '暂无日志。',
     'services.logRelay': 'Relay',
     'services.logHost': '主机连接器',
+    'adminBroker.windowsOnly': '管理员终端 broker 只支持 Windows。',
+    'adminBroker.needsElevation': '请打开 Windows TUI 并选择“设置管理员终端”，使用运行 Herdr Remote 的同一账户批准一次 Windows 提权提示。',
+    'adminBroker.title': '管理员终端 broker',
+    'adminBroker.checking': '正在检查…',
+    'adminBroker.ready': '已就绪',
+    'adminBroker.notReady': '尚未设置或未运行',
+    'adminBroker.install': '设置管理员终端',
+    'adminBroker.uninstall': '移除管理员终端设置',
+    'adminBroker.installDone': '管理员终端 broker 任务已注册。',
+    'adminBroker.uninstallDone': '管理员终端 broker 任务已移除。',
+    'adminBroker.elevationCancelled': '未批准管理员权限，未进行更改。',
+    'adminBroker.setupFailed': '管理员终端 broker 设置失败。',
+    'adminBroker.tuiHint': '只需设置一次。Windows 会请求管理员授权；之后 WebUI 新建管理员终端不再弹出 UAC。',
     'relay.title': 'Relay 设置',
     'relay.settings': '设置',
     'relay.locked': '固定',

package/dist/pty-session.js

@@ -1,5 +1,6 @@
 import os from 'node:os';
 import pty from 'node-pty';
+import { ElevatedPty } from './connector/elevatedPty.js';
 class PtySession {
     static DEFAULT_COLS = 100;
     static DEFAULT_ROWS = 30;
@@ -10,10 +11,12 @@ class PtySession {
     cwd;
     socketPath;
     platform;
+    adminTerminal;
+    fastWindowsPty;
     spawnPty;
     terminal;
     startedAt;
-    constructor({ command, args = [], cwd = os.homedir(), socketPath, platform = process.platform, spawn: spawnPty = pty.spawn, } = {}) {
+    constructor({ command, args = [], cwd = os.homedir(), socketPath, platform = process.platform, spawn: spawnPty = pty.spawn, adminTerminal = false, fastWindowsPty = false, } = {}) {
         if (typeof command !== 'string' || command.length === 0)
             throw new TypeError('command must be a non-empty string');
         if (!Array.isArray(args) || !args.every((arg) => typeof arg === 'string'))
@@ -23,6 +26,8 @@ class PtySession {
         this.cwd = cwd;
         this.socketPath = socketPath;
         this.platform = platform;
+        this.adminTerminal = adminTerminal;
+        this.fastWindowsPty = fastWindowsPty;
         this.spawnPty = spawnPty;
         this.terminal = null;
         this.startedAt = null;
@@ -45,19 +50,43 @@ class PtySession {
             return fallback;
         return Math.min(PtySession.MAX_DIMENSION, Math.max(PtySession.MIN_DIMENSION, numeric));
     }
-    start({ cols, rows, onData, onExit }) {
+    start({ cols, rows, onData, onExit, onReady, onError }) {
         if (this.terminal)
             throw new Error('PTY session already started');
-        // The bundled ConPTY preserves Kitty sequences older system ConPTY drops,
-        // which is why Herdr embeds it too. System ConPTY's kill() forks a
-        // console-list helper without windowsHide, which flashes a window here.
+        if (this.adminTerminal) {
+            if (this.platform !== 'win32')
+                throw new Error('Administrator PTYs are only supported on Windows');
+            const terminal = new ElevatedPty({ command: this.command, args: this.args, cwd: this.cwd, socketPath: this.socketPath }, PtySession.clampDimension(cols, PtySession.DEFAULT_COLS), PtySession.clampDimension(rows, PtySession.DEFAULT_ROWS));
+            this.terminal = terminal;
+            this.startedAt = new Date().toISOString();
+            terminal.start({
+                cols: terminal.cols,
+                rows: terminal.rows,
+                onData: onData || (() => { }),
+                onExit: (event) => {
+                    this.terminal = null;
+                    onExit?.(event);
+                },
+                onReady,
+                onError: (error) => {
+                    this.terminal = null;
+                    onError?.(error);
+                },
+            });
+            return this;
+        }
+        // The Herdr UI needs the bundled ConPTY's Kitty and mouse reporting.
         this.terminal = this.spawnPty(this.command, this.args, {
             name: 'xterm-256color',
             cols: PtySession.clampDimension(cols, PtySession.DEFAULT_COLS),
             rows: PtySession.clampDimension(rows, PtySession.DEFAULT_ROWS),
             cwd: this.cwd,
             env: PtySession.childEnv(this.socketPath),
-            ...(this.platform === 'win32' ? { useConptyDll: true } : {}),
+            ...(this.platform === 'win32'
+                ? this.fastWindowsPty
+                    ? { useConpty: false }
+                    : { useConptyDll: true }
+                : {}),
         });
         this.startedAt = new Date().toISOString();
         const terminal = this.terminal;
@@ -69,6 +98,7 @@ class PtySession {
                 onExit(event);
             });
         }
+        onReady?.();
         return this;
     }
     write(data) {

package/dist/tui/api.js

@@ -19,6 +19,16 @@ import * as keepalive from '../keepalive/index.js';
 import { canSelfUpdate, checkForUpdate, compareVersions, currentVersion, updateChecksEnabled, installKind, performUpdate, } from '../updater.js';
 import { checkForRelayUpdate, installedRelayVersion, performRelayUpdate, } from '../relay-updater.js';
 export { detectLocale, listReachableAddresses, MIN_HERDR_VERSION, OFFICIAL_RELAY_URL, isOfficialRelay, selectedMode, canSelfUpdate, checkForUpdate, compareVersions, currentVersion, updateChecksEnabled, installKind, performUpdate, checkForRelayUpdate, installedRelayVersion, performRelayUpdate, runsLocalRelay, bindAddress, configExists, configPath, createDraft, createTranslator, ensureRuntime, extractPairingCode, fieldsForMode, fullStatus, getField, getFieldPlaceholder, herdrVersion, keepalive, loadConfig, pair, readLogTail, regenerateHostIdentity, requiresRestart, restartAll, saveDraft, setField, setRelayPassword, startAll, stateDir, stopAll, whileServicesStopped, };
+export async function adminBrokerStatus() {
+    if (process.platform !== 'win32')
+        return false;
+    const broker = await import('../connector/admin-broker.js');
+    return broker.adminBrokerStatus();
+}
+export async function configureAdminBroker(action, t) {
+    const setup = await import('../connector/admin-broker-setup.js');
+    return setup.configureAdminBroker(action, t);
+}
 /** The command that starts a matching relay, ready to paste on the server. */
 export function relayStartCommand(config, password) {
     const publicUrl = config.relay.remoteUrl

package/dist/tui/screens/Keepalive.js

@@ -1,13 +1,31 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from 'react';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
 import { Box, Text, useInput } from 'ink';
 import { theme } from '../theme.js';
 import { Message, Panel, Row, Selectable, StatusDot } from '../components/common.js';
 import { ChoiceList } from './Relay.js';
-import { KEEPALIVE_MANAGERS, keepalive, saveDraft, setField } from '../api.js';
+import { KEEPALIVE_MANAGERS, adminBrokerStatus, configureAdminBroker, keepalive, saveDraft, setField, } from '../api.js';
 export function Keepalive({ ctx }) {
     const { t, status, draft, editingId } = ctx;
     const [selected, setSelected] = useState('install');
+    const [brokerReady, setBrokerReady] = useState(null);
+    useEffect(() => {
+        if (process.platform !== 'win32')
+            return undefined;
+        let cancelled = false;
+        adminBrokerStatus()
+            .then((available) => {
+            if (!cancelled)
+                setBrokerReady(available);
+        })
+            .catch(() => {
+            if (!cancelled)
+                setBrokerReady(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
     const current = status?.keepalive;
     const entries = [
         { id: 'install', label: t('keepalive.install') },
@@ -17,12 +35,38 @@ export function Keepalive({ ctx }) {
         ...(process.platform === 'linux' && current?.manager === 'systemd' && !current?.linger
             ? [{ id: 'linger', label: t('keepalive.enableLinger') }]
             : []),
+        ...(process.platform === 'win32'
+            ? [
+                { id: 'adminBrokerInstall', label: t('adminBroker.install') },
+                { id: 'adminBrokerUninstall', label: t('adminBroker.uninstall') },
+            ]
+            : []),
     ];
     const activate = (id) => {
         if (id === 'manager') {
             ctx.setEditing('keepaliveManager');
             return;
         }
+        if (id === 'adminBrokerInstall' || id === 'adminBrokerUninstall') {
+            const action = id === 'adminBrokerInstall' ? 'install' : 'uninstall';
+            ctx.run(async () => {
+                let ready = false;
+                try {
+                    await configureAdminBroker(action, t);
+                    ready = action === 'install' && (await adminBrokerStatus());
+                }
+                catch (error) {
+                    if (error.code === 'ELEVATION_CANCELLED') {
+                        ctx.notify((t) => t('adminBroker.elevationCancelled'), 'info');
+                        return;
+                    }
+                    throw error;
+                }
+                setBrokerReady(ready);
+                ctx.notify((t) => t(`adminBroker.${action}Done`), 'success');
+            });
+            return;
+        }
         ctx.run(async () => {
             if (id === 'install') {
                 if (keepalive.detectManager(ctx.config.keepalive.manager) === 'windows-service')
@@ -88,7 +132,9 @@ export function Keepalive({ ctx }) {
                                     ? t('common.running')
                                     : current?.installed
                                         ? t('common.installed')
-                                        : t('common.notInstalled')] })] }) }), current?.unitPath ? (_jsx(Row, { label: t('keepalive.unitPath'), children: _jsx(Text, { color: theme.muted, children: current.unitPath }) })) : null, _jsx(Box, { marginTop: 1, flexDirection: "column", children: entries.map((entry) => (_jsx(Selectable, { selected: selected === entry.id, onSelect: () => {
+                                        : t('common.notInstalled')] })] }) }), process.platform === 'win32' ? (_jsxs(_Fragment, { children: [_jsx(Row, { label: t('adminBroker.title'), children: _jsx(Text, { color: brokerReady ? theme.ok : theme.warn, children: brokerReady === null
+                                ? t('adminBroker.checking')
+                                : t(brokerReady ? 'adminBroker.ready' : 'adminBroker.notReady') }) }), _jsx(Text, { color: theme.muted, children: t('adminBroker.tuiHint') })] })) : null, current?.unitPath ? (_jsx(Row, { label: t('keepalive.unitPath'), children: _jsx(Text, { color: theme.muted, children: current.unitPath }) })) : null, _jsx(Box, { marginTop: 1, flexDirection: "column", children: entries.map((entry) => (_jsx(Selectable, { selected: selected === entry.id, onSelect: () => {
                         setSelected(entry.id);
                         activate(entry.id);
                     }, onHover: () => setSelected(entry.id), children: entry.label }, entry.id))) }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [current?.manager === 'systemd' ? (_jsx(Text, { color: current.linger ? theme.muted : theme.warn, children: current.linger ? t('keepalive.lingerEnabled') : t('keepalive.lingerDisabled') })) : null, current?.manager === 'supervisor' ? (_jsx(Text, { color: theme.warn, children: t('keepalive.fallbackNote') })) : null, current?.manager === 'windows-task' ? (_jsx(Text, { color: theme.muted, children: t('keepalive.windowsTaskNote') })) : null, current?.manager === 'windows-service' ? (_jsx(Text, { color: theme.warn, children: t('keepalive.serviceNote') })) : null, _jsx(Text, { color: theme.muted, children: t('keepalive.logsHint', { command: status?.logsHint ?? '' }) })] }), _jsx(Message, { text: ctx.message?.text ?? null, level: ctx.message?.level ?? 'info' })] }));

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "herdr.remote.web"
 name = "Herdr Remote Web"
-version = "0.2.25"
+version = "0.2.26"
 min_herdr_version = "0.9.1"
 description = "Browser access to Herdr workspaces via local or self-hosted relay"
 platforms = ["linux", "macos", "windows"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-remote",
-  "version": "0.2.25",
+  "version": "0.2.26",
   "description": "Browser access to Herdr workspaces: plugin, host connector, and configuration TUI",
   "license": "MIT",
   "type": "module",