hivehq 2.0.0

package/dist/src/server/agent-command-resolver.d.ts

@@ -0,0 +1,17 @@
+interface ResolvedSpawnCommand {
+    /**
+     * `args` is a `string[]` for plain executables (node-pty's serializer is
+     * fine for them) and a verbatim `string` for Windows `.cmd`/`.bat` shim
+     * launches. The verbatim form bypasses node-pty's `argsToCommandLine`,
+     * because that function backslash-escapes any embedded `"` and cmd.exe
+     * does NOT recognize `\"` as an escape — it treats `\` as literal, which
+     * leaves cmd looking up a program name containing literal quote chars.
+     * See `node-pty/src/windowsPtyAgent.ts` `argsToCommandLine` for the rule.
+     */
+    args: string | string[];
+    command: string;
+}
+export declare const resolveCommandPath: (command: string, cwd: string, env: NodeJS.ProcessEnv, platform?: NodeJS.Platform) => string;
+export declare const resolveSpawnCommand: (command: string, cwd: string, env: NodeJS.ProcessEnv, args?: string[], platform?: NodeJS.Platform) => ResolvedSpawnCommand;
+export declare const assertCommandIsExecutable: (command: string, cwd: string, env: NodeJS.ProcessEnv) => void;
+export type { ResolvedSpawnCommand };

package/dist/src/server/agent-command-resolver.js

@@ -0,0 +1,106 @@
+import { accessSync, constants } from 'node:fs';
+import { basename, delimiter, extname, isAbsolute, join } from 'node:path';
+import { buildCmdCallCommand } from './windows-command-line.js';
+const hasPathSeparator = (command) => command.includes('/') || command.includes('\\');
+const canExecute = (path, platform = process.platform) => {
+    try {
+        accessSync(path, platform === 'win32' ? constants.F_OK : constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const createCommandNotFoundError = (command) => Object.assign(new Error(`${command} CLI not found in PATH`), {
+    code: 'ENOENT',
+    path: command,
+});
+const getEnvValue = (env, key, platform = process.platform) => {
+    if (platform !== 'win32')
+        return env[key];
+    if (Object.hasOwn(env, key))
+        return env[key];
+    const matchedKey = Object.keys(env)
+        .filter((item) => item.toLowerCase() === key.toLowerCase())
+        .at(-1);
+    return matchedKey ? env[matchedKey] : undefined;
+};
+const getWindowsExecutableNames = (command, env, platform = process.platform) => {
+    if (extname(command))
+        return [command];
+    const extensions = (getEnvValue(env, 'PATHEXT', platform) ?? '.COM;.EXE;.BAT;.CMD')
+        .split(';')
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return extensions.map((extension) => `${command}${extension}`);
+};
+const getExecutableNames = (command, env, platform = process.platform) => platform === 'win32' ? getWindowsExecutableNames(command, env, platform) : [command];
+export const resolveCommandPath = (command, cwd, env, platform = process.platform) => {
+    if (hasPathSeparator(command)) {
+        for (const name of getExecutableNames(command, env, platform)) {
+            const candidate = isAbsolute(name) ? name : join(cwd, name);
+            if (canExecute(candidate, platform))
+                return candidate;
+        }
+        throw createCommandNotFoundError(command);
+    }
+    for (const pathEntry of (getEnvValue(env, 'PATH', platform) ?? '').split(delimiter)) {
+        if (!pathEntry)
+            continue;
+        for (const name of getExecutableNames(command, env, platform)) {
+            const candidate = join(pathEntry, name);
+            if (canExecute(candidate, platform))
+                return candidate;
+        }
+    }
+    throw createCommandNotFoundError(command);
+};
+const isWindowsBatchFile = (command) => {
+    const extension = extname(command).toLowerCase();
+    return extension === '.cmd' || extension === '.bat';
+};
+const buildWindowsBatchCommandLine = (command, args) => {
+    // `call` is cmd's built-in batch invocation; it handles quoted .cmd / .bat
+    // paths reliably (this is the same pattern Node.js's child_process uses
+    // internally on Windows since the CVE-2024-27980 fix).
+    // Most Windows agent CLIs are npm .cmd shims. Set the console code page to
+    // UTF-8 before launching them so Hive's injected CJK startup guidance is not
+    // interpreted through the machine's OEM code page.
+    return `/d /s /c chcp 65001 >nul && ${buildCmdCallCommand(command, args)}`;
+};
+/**
+ * Recognize the exact shape that `createStartupCommandLaunch` produces on
+ * Windows: `cmd.exe` with args `['/d', '/s', '/c', '<raw user command>']`.
+ * Pinned to length 4 so this branch only fires for that single contract;
+ * any other cmd.exe invocation (e.g. someone explicitly composing custom
+ * shell args via the launch config) keeps the default node-pty path.
+ *
+ * We need this repackaging because the user's raw command often contains `"`
+ * (Windows users habitually wrap paths) and node-pty's `argsToCommandLine`
+ * backslash-escapes those — cmd.exe then sees `\"...\"` and looks up a
+ * program whose name starts with `\`.
+ */
+const isCmdExeShellLaunch = (resolvedCommand, args) => basename(resolvedCommand).toLowerCase() === 'cmd.exe' &&
+    args.length === 4 &&
+    args[0] === '/d' &&
+    args[1] === '/s' &&
+    (args[2] === '/c' || args[2] === '/k');
+export const resolveSpawnCommand = (command, cwd, env, args = [], platform = process.platform) => {
+    const resolvedCommand = resolveCommandPath(command, cwd, env, platform);
+    if (platform === 'win32' && isWindowsBatchFile(resolvedCommand)) {
+        return {
+            args: buildWindowsBatchCommandLine(resolvedCommand, args),
+            command: getEnvValue(env, 'ComSpec', platform) ?? 'cmd.exe',
+        };
+    }
+    if (platform === 'win32' && isCmdExeShellLaunch(resolvedCommand, args)) {
+        return {
+            args: args.join(' '),
+            command: resolvedCommand,
+        };
+    }
+    return { args, command: resolvedCommand };
+};
+export const assertCommandIsExecutable = (command, cwd, env) => {
+    resolveCommandPath(command, cwd, env);
+};

package/dist/src/server/agent-exit-classification.d.ts

@@ -0,0 +1,6 @@
+import type { PersistedAgentRun } from './agent-run-store.js';
+export declare const WINDOWS_CONTROL_C_EXIT_CODE = 3221225786;
+export declare const isUserInterruptExitCode: (exitCode: number | null) => boolean;
+export declare const isCleanRunExitCode: (exitCode: number | null) => boolean;
+export declare const classifyCompletedRunStatus: (exitCode: number | null) => PersistedAgentRun["status"];
+export declare const shouldClearResumedSessionOnExit: (exitCode: number | null) => boolean;

package/dist/src/server/agent-exit-classification.js

@@ -0,0 +1,6 @@
+export const WINDOWS_CONTROL_C_EXIT_CODE = 0xc000013a;
+const USER_INTERRUPT_EXIT_CODES = new Set([130, 143, WINDOWS_CONTROL_C_EXIT_CODE]);
+export const isUserInterruptExitCode = (exitCode) => exitCode !== null && USER_INTERRUPT_EXIT_CODES.has(exitCode);
+export const isCleanRunExitCode = (exitCode) => exitCode === 0 || isUserInterruptExitCode(exitCode);
+export const classifyCompletedRunStatus = (exitCode) => isCleanRunExitCode(exitCode) ? 'exited' : 'error';
+export const shouldClearResumedSessionOnExit = (exitCode) => !isCleanRunExitCode(exitCode);

package/dist/src/server/agent-launch-cache.d.ts

@@ -0,0 +1,20 @@
+import type { AgentLaunchConfigInput } from './agent-run-store.js';
+export interface AgentLaunchConfigRow {
+    agentId: string;
+    config: AgentLaunchConfigInput;
+    workspaceId: string;
+}
+interface AgentLaunchCacheStore {
+    deleteLaunchConfig: (workspaceId: string, agentId: string) => void;
+    listLaunchConfigs: () => AgentLaunchConfigRow[];
+    saveLaunchConfig: (workspaceId: string, agentId: string, input: AgentLaunchConfigInput) => void;
+}
+export declare const createAgentLaunchCache: (store: AgentLaunchCacheStore) => {
+    get(workspaceId: string, agentId: string): AgentLaunchConfigInput;
+    peek(workspaceId: string, agentId: string): AgentLaunchConfigInput | undefined;
+    getWorkspaceId(agentId: string): string | undefined;
+    save(workspaceId: string, agentId: string, input: AgentLaunchConfigInput): void;
+    remove(workspaceId: string, agentId: string): void;
+    setWorkspaceId(agentId: string, workspaceId: string): void;
+};
+export {};

package/dist/src/server/agent-launch-cache.js

@@ -0,0 +1,75 @@
+export const createAgentLaunchCache = (store) => {
+    const launchConfigs = new Map();
+    const workspaceByAgentId = new Map();
+    const missingLaunchConfigs = new Set();
+    const cacheKey = (workspaceId, agentId) => `${workspaceId}:${agentId}`;
+    const load = () => {
+        launchConfigs.clear();
+        workspaceByAgentId.clear();
+        for (const row of store.listLaunchConfigs()) {
+            launchConfigs.set(cacheKey(row.workspaceId, row.agentId), row.config);
+            workspaceByAgentId.set(row.agentId, row.workspaceId);
+        }
+    };
+    load();
+    return {
+        get(workspaceId, agentId) {
+            const key = cacheKey(workspaceId, agentId);
+            const config = launchConfigs.get(key);
+            if (config)
+                return config;
+            if (missingLaunchConfigs.has(key)) {
+                throw new Error(`Agent launch config not found: ${agentId}`);
+            }
+            load();
+            const reloadedConfig = launchConfigs.get(key);
+            if (reloadedConfig)
+                return reloadedConfig;
+            missingLaunchConfigs.add(key);
+            throw new Error(`Agent launch config not found: ${agentId}`);
+        },
+        peek(workspaceId, agentId) {
+            const key = cacheKey(workspaceId, agentId);
+            const config = launchConfigs.get(key);
+            if (config)
+                return config;
+            if (missingLaunchConfigs.has(key))
+                return undefined;
+            load();
+            const reloadedConfig = launchConfigs.get(key);
+            if (reloadedConfig)
+                return reloadedConfig;
+            missingLaunchConfigs.add(key);
+            return undefined;
+        },
+        getWorkspaceId(agentId) {
+            return workspaceByAgentId.get(agentId);
+        },
+        save(workspaceId, agentId, input) {
+            const normalized = {
+                command: input.command,
+                args: input.args ?? [],
+                commandPresetId: input.commandPresetId ?? null,
+                interactiveCommand: input.interactiveCommand ?? null,
+                presetAugmentationDisabled: input.presetAugmentationDisabled ?? false,
+                resumeArgsTemplate: input.resumeArgsTemplate ?? null,
+                sessionIdCapture: input.sessionIdCapture ?? null,
+            };
+            store.saveLaunchConfig(workspaceId, agentId, normalized);
+            const key = cacheKey(workspaceId, agentId);
+            launchConfigs.set(key, normalized);
+            missingLaunchConfigs.delete(key);
+            workspaceByAgentId.set(agentId, workspaceId);
+        },
+        remove(workspaceId, agentId) {
+            store.deleteLaunchConfig(workspaceId, agentId);
+            const key = cacheKey(workspaceId, agentId);
+            launchConfigs.delete(key);
+            missingLaunchConfigs.add(key);
+            workspaceByAgentId.delete(agentId);
+        },
+        setWorkspaceId(agentId, workspaceId) {
+            workspaceByAgentId.set(agentId, workspaceId);
+        },
+    };
+};

package/dist/src/server/agent-launch-resolver.d.ts

@@ -0,0 +1,4 @@
+import type { AgentLaunchConfigInput } from './agent-run-store.js';
+import type { SettingsStore } from './settings-store.js';
+export declare const resolveCommandPresetLaunchConfig: (settings: SettingsStore, commandPresetId: string) => AgentLaunchConfigInput | undefined;
+export declare const resolveStartupCommandLaunchConfig: (settings: SettingsStore, startupCommand: string, commandPresetId?: string | null) => AgentLaunchConfigInput | undefined;

package/dist/src/server/agent-launch-resolver.js

@@ -0,0 +1,38 @@
+import { createStartupCommandLaunch, getStartupCommandExecutable, normalizeExecutableToken, } from './startup-command-parser.js';
+export const resolveCommandPresetLaunchConfig = (settings, commandPresetId) => {
+    const preset = settings.getCommandPreset(commandPresetId);
+    if (!preset)
+        return undefined;
+    return {
+        args: preset.args,
+        command: preset.command,
+        commandPresetId: preset.id,
+    };
+};
+const findPresetForStartupCommand = (settings, startupCommand, commandPresetId) => {
+    if (commandPresetId)
+        return settings.getCommandPreset(commandPresetId);
+    // Reduce the raw token (which may be a bare command, an absolute path,
+    // or a Windows path with spaces and a .cmd suffix) to the canonical
+    // brand id before looking up the preset. Without this normalization
+    // step `getCommandPreset` only matched bare command names — Windows
+    // users typing the full nvm4w path lost CLI brand identification,
+    // session capture, and post-start input strategy in one swoop.
+    const brandId = normalizeExecutableToken(getStartupCommandExecutable(startupCommand));
+    return brandId ? settings.getCommandPreset(brandId) : undefined;
+};
+export const resolveStartupCommandLaunchConfig = (settings, startupCommand, commandPresetId = null) => {
+    const trimmedStartupCommand = startupCommand.trim();
+    if (!trimmedStartupCommand)
+        return undefined;
+    const parsed = createStartupCommandLaunch(trimmedStartupCommand);
+    const preset = findPresetForStartupCommand(settings, trimmedStartupCommand, commandPresetId);
+    return {
+        command: parsed.command,
+        args: parsed.args,
+        commandPresetId: null,
+        interactiveCommand: preset?.command ?? getStartupCommandExecutable(trimmedStartupCommand),
+        presetAugmentationDisabled: true,
+        sessionIdCapture: preset?.sessionIdCapture ?? null,
+    };
+};

package/dist/src/server/agent-manager-support.d.ts

@@ -0,0 +1,36 @@
+import type { IPty } from 'node-pty';
+import type { AgentRunRecord, AgentRunSnapshot } from './agent-manager.js';
+import type { PtyOutputBus } from './pty-output-bus.js';
+export declare const MAX_RUN_OUTPUT_LENGTH = 1000000;
+type ExecRunner = (cmd: string, args: readonly string[], done: (success: boolean) => void) => void;
+export declare const withSilencedConptyConsoleListAgent: <T>(platform: NodeJS.Platform, action: () => T) => T;
+/**
+ * Windows analogue of POSIX `process.kill(-pgid, SIGKILL)`. node-pty on
+ * Windows hands `pty.kill()` to TerminateProcess against the PTY's main
+ * process only — children that the worker spawned (npm install, build
+ * scripts, custom tooling) become orphans and keep writing to the
+ * filesystem after the worker card flips to stopped.
+ *
+ * `taskkill /pid <pid> /t /f` walks the process tree (`/t`) and forces
+ * termination (`/f`), matching what task manager would do.
+ *
+ * IMPORTANT — call this BEFORE any other termination of the parent
+ * process. taskkill /T builds the tree by querying the parent for its
+ * descendants; if the parent is already gone (e.g. pty.kill() ran
+ * first) the enumeration returns empty and the children become
+ * orphans. /F also terminates the parent itself, so a parent-kill
+ * after this call is only useful as a fallback when taskkill itself
+ * failed (taskkill missing from PATH, restricted PowerShell, etc.).
+ *
+ * Best-effort: non-zero exits (process already gone, taskkill missing
+ * from PATH, access denied) are swallowed and surface as a `false`
+ * return. The caller is expected to fall back to pty.kill().
+ *
+ * Exported for unit testing — the `runner` parameter lets tests assert
+ * the exact argv without mocking node:child_process.
+ */
+export declare const taskkillProcessTree: (pid: number, platform?: NodeJS.Platform, runner?: ExecRunner, onFailure?: () => void) => boolean;
+export declare const toAgentRunSnapshot: (run: AgentRunRecord) => AgentRunSnapshot;
+export declare const finishAgentRun: (run: AgentRunRecord, exitCode: number | null, ptyOutputBus: PtyOutputBus) => void;
+export declare const attachAgentPty: (run: AgentRunRecord, pty: IPty, ptyOutputBus: PtyOutputBus, platform?: NodeJS.Platform, execRunner?: ExecRunner) => void;
+export {};

package/dist/src/server/agent-manager-support.js

@@ -0,0 +1,318 @@
+import { execFile, execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { classifyCompletedRunStatus } from './agent-exit-classification.js';
+export const MAX_RUN_OUTPUT_LENGTH = 1_000_000;
+const FORCE_KILL_DELAY_MS = 750;
+const TASKKILL_TIMEOUT_MS = 3000;
+const PTY_READ_EOF_EXIT_GRACE_MS = 1000;
+const require = createRequire(import.meta.url);
+const childProcess = require('node:child_process');
+const isConptyConsoleListAgentPath = (modulePath) => {
+    const normalized = String(modulePath).replaceAll('\\', '/');
+    return (normalized.endsWith('/conpty_console_list_agent') ||
+        normalized.endsWith('/conpty_console_list_agent.js'));
+};
+export const withSilencedConptyConsoleListAgent = (platform, action) => {
+    if (platform !== 'win32')
+        return action();
+    const originalFork = childProcess.fork;
+    const patchedFork = (modulePath, argsOrOptions, options) => {
+        if (!isConptyConsoleListAgentPath(modulePath)) {
+            return Array.isArray(argsOrOptions)
+                ? originalFork.call(childProcess, modulePath, argsOrOptions, options)
+                : originalFork.call(childProcess, modulePath, argsOrOptions);
+        }
+        const forkOptions = Array.isArray(argsOrOptions) ? options : argsOrOptions;
+        const silentOptions = { ...(forkOptions ?? {}), silent: true };
+        const child = Array.isArray(argsOrOptions)
+            ? originalFork.call(childProcess, modulePath, argsOrOptions, silentOptions)
+            : originalFork.call(childProcess, modulePath, silentOptions);
+        child.stderr?.resume();
+        child.stdout?.resume();
+        return child;
+    };
+    childProcess.fork = patchedFork;
+    try {
+        return action();
+    }
+    finally {
+        childProcess.fork = originalFork;
+    }
+};
+const isPtyReadEofError = (error, platform = process.platform) => {
+    const candidate = error;
+    return platform !== 'win32' && candidate?.code === 'EIO' && candidate.syscall === 'read';
+};
+const serializePtyInput = (input) => Buffer.isBuffer(input) ? input.toString('latin1') : input;
+const defaultExecRunner = (cmd, args, done) => {
+    let settled = false;
+    const settle = (success) => {
+        if (settled)
+            return;
+        settled = true;
+        done(success);
+    };
+    const child = execFile(cmd, [...args], { maxBuffer: 64 * 1024, timeout: TASKKILL_TIMEOUT_MS, windowsHide: true }, (error) => settle(!error));
+    child.once('error', () => settle(false));
+};
+/**
+ * Windows analogue of POSIX `process.kill(-pgid, SIGKILL)`. node-pty on
+ * Windows hands `pty.kill()` to TerminateProcess against the PTY's main
+ * process only — children that the worker spawned (npm install, build
+ * scripts, custom tooling) become orphans and keep writing to the
+ * filesystem after the worker card flips to stopped.
+ *
+ * `taskkill /pid <pid> /t /f` walks the process tree (`/t`) and forces
+ * termination (`/f`), matching what task manager would do.
+ *
+ * IMPORTANT — call this BEFORE any other termination of the parent
+ * process. taskkill /T builds the tree by querying the parent for its
+ * descendants; if the parent is already gone (e.g. pty.kill() ran
+ * first) the enumeration returns empty and the children become
+ * orphans. /F also terminates the parent itself, so a parent-kill
+ * after this call is only useful as a fallback when taskkill itself
+ * failed (taskkill missing from PATH, restricted PowerShell, etc.).
+ *
+ * Best-effort: non-zero exits (process already gone, taskkill missing
+ * from PATH, access denied) are swallowed and surface as a `false`
+ * return. The caller is expected to fall back to pty.kill().
+ *
+ * Exported for unit testing — the `runner` parameter lets tests assert
+ * the exact argv without mocking node:child_process.
+ */
+export const taskkillProcessTree = (pid, platform = process.platform, runner = defaultExecRunner, onFailure) => {
+    if (platform !== 'win32' || pid <= 0)
+        return false;
+    try {
+        runner('taskkill', ['/pid', String(pid), '/t', '/f'], (success) => {
+            if (!success)
+                onFailure?.();
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const toAgentRunSnapshot = (run) => ({
+    runId: run.runId,
+    agentId: run.agentId,
+    pid: run.process.pid,
+    status: run.process.isStopped() && run.status !== 'exited' && run.status !== 'error'
+        ? 'error'
+        : run.status,
+    output: run.output,
+    exitCode: run.exitCode,
+});
+export const finishAgentRun = (run, exitCode, ptyOutputBus) => {
+    if (run.status === 'exited' || run.status === 'error')
+        return;
+    run.status = classifyCompletedRunStatus(exitCode);
+    run.exitCode = exitCode;
+    try {
+        run.onExit?.({ runId: run.runId, exitCode });
+    }
+    finally {
+        ptyOutputBus.clear(run.runId);
+    }
+};
+export const attachAgentPty = (run, pty, ptyOutputBus, platform = process.platform, execRunner = defaultExecRunner) => {
+    let stdinClosed = false;
+    let forceKillTimer;
+    let ptyReadEofTimer;
+    const resolveProcessGroupId = () => {
+        if (platform === 'win32' || pty.pid <= 0)
+            return null;
+        try {
+            const value = execFileSync('ps', ['-o', 'pgid=', '-p', String(pty.pid)], {
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+            const groupId = Number(value);
+            if (Number.isInteger(groupId) && groupId > 0)
+                return groupId;
+        }
+        catch {
+            return pty.pid;
+        }
+        return pty.pid;
+    };
+    const processGroupId = resolveProcessGroupId();
+    const stopped = () => run.status === 'exited' || run.status === 'error';
+    const ignoreMissingProcess = (error) => {
+        if (error?.code !== 'ESRCH')
+            throw error;
+    };
+    const ignoreBestEffortGroupKillError = (error) => {
+        const code = error?.code;
+        if (code !== 'ESRCH' && code !== 'EPERM')
+            throw error;
+    };
+    const killProcessGroup = (signal) => {
+        if (platform === 'win32' || processGroupId === null)
+            return;
+        try {
+            process.kill(-processGroupId, signal);
+        }
+        catch (error) {
+            ignoreBestEffortGroupKillError(error);
+        }
+    };
+    const killPtyDirect = (signal) => {
+        try {
+            if (platform === 'win32')
+                withSilencedConptyConsoleListAgent(platform, () => pty.kill());
+            else
+                pty.kill(signal);
+        }
+        catch (error) {
+            ignoreMissingProcess(error);
+        }
+    };
+    const killPty = (signal) => {
+        if (platform === 'win32') {
+            // taskkill /pid <pid> /t /f walks the parent's process tree
+            // BEFORE terminating it — so we have to run it while the parent
+            // is still alive. Calling pty.kill() first (the previous
+            // ordering) detaches the children: taskkill /T then fails with
+            // "process not found" and the npm-installs / build scripts
+            // become orphans. taskkill /f also terminates the parent, so
+            // pty.kill() is the fallback for the rare case where taskkill
+            // is missing from PATH or refused (e.g. restricted PowerShell).
+            if (!taskkillProcessTree(pty.pid, platform, execRunner, () => killPtyDirect()))
+                killPtyDirect();
+        }
+        else
+            killPtyDirect(signal);
+        killProcessGroup(signal);
+    };
+    const clearForceKillTimer = () => {
+        if (!forceKillTimer)
+            return;
+        clearTimeout(forceKillTimer);
+        forceKillTimer = undefined;
+    };
+    const clearPtyReadEofTimer = () => {
+        if (!ptyReadEofTimer)
+            return;
+        clearTimeout(ptyReadEofTimer);
+        ptyReadEofTimer = undefined;
+    };
+    const schedulePtyReadEofExitGuard = (error) => {
+        if (ptyReadEofTimer)
+            return;
+        ptyReadEofTimer = setTimeout(() => {
+            ptyReadEofTimer = undefined;
+            if (stopped())
+                return;
+            console.error(`[hive] PTY read EOF without exit for run ${run.runId}`, error);
+            finishAgentRun(run, null, ptyOutputBus);
+            try {
+                killPty('SIGTERM');
+                scheduleForceKill();
+            }
+            catch (killError) {
+                ignoreMissingProcess(killError);
+            }
+        }, PTY_READ_EOF_EXIT_GRACE_MS);
+        ptyReadEofTimer.unref?.();
+    };
+    const cleanupProcessGroup = () => {
+        clearForceKillTimer();
+        clearPtyReadEofTimer();
+        killProcessGroup('SIGKILL');
+    };
+    const scheduleForceKill = () => {
+        if (forceKillTimer)
+            return;
+        forceKillTimer = setTimeout(() => {
+            forceKillTimer = undefined;
+            try {
+                if (platform === 'win32') {
+                    // Same ordering as killPty(): tree-kill before terminating the
+                    // parent, so taskkill /T can still enumerate the process tree.
+                    // pty.kill() is the cleanup fallback for taskkill-missing hosts;
+                    // its noisy dependency helper is silenced in killPtyDirect().
+                    if (!taskkillProcessTree(pty.pid, platform, execRunner, () => killPtyDirect()))
+                        killPtyDirect();
+                }
+                else
+                    killPtyDirect('SIGKILL');
+            }
+            catch (error) {
+                ignoreMissingProcess(error);
+            }
+            killProcessGroup('SIGKILL');
+        }, FORCE_KILL_DELAY_MS);
+        forceKillTimer.unref?.();
+    };
+    run.process = {
+        isStopped() {
+            return stopped();
+        },
+        pause() {
+            pty.pause();
+        },
+        pid: pty.pid,
+        resize(cols, rows) {
+            if (!Number.isInteger(cols) || !Number.isInteger(rows) || cols <= 0 || rows <= 0) {
+                throw new Error(`Invalid terminal size for run: ${run.runId}`);
+            }
+            pty.resize(cols, rows);
+        },
+        resume() {
+            pty.resume();
+        },
+        stop() {
+            if (stopped()) {
+                cleanupProcessGroup();
+                return;
+            }
+            clearPtyReadEofTimer();
+            killPty('SIGTERM');
+            stdinClosed = true;
+            scheduleForceKill();
+        },
+        write(text) {
+            if (stdinClosed || run.status === 'exited' || run.status === 'error') {
+                throw new Error(`PTY is not active for run: ${run.runId}`);
+            }
+            pty.write(serializePtyInput(text));
+        },
+    };
+    pty.onData((chunk) => {
+        if (run.status === 'starting')
+            run.status = 'running';
+        run.output += chunk;
+        if (run.output.length > MAX_RUN_OUTPUT_LENGTH)
+            run.output = run.output.slice(-MAX_RUN_OUTPUT_LENGTH);
+        ptyOutputBus.publish(run.runId, chunk);
+    });
+    pty.on?.('error', (error) => {
+        if (stopped())
+            return;
+        if (isPtyReadEofError(error, platform)) {
+            // Unix PTYs can surface a closed slave as read/EIO just before
+            // node-pty delivers the real onExit event. Treat it as EOF, not
+            // as the run's terminal status.
+            stdinClosed = true;
+            schedulePtyReadEofExitGuard(error);
+            return;
+        }
+        console.error(`[hive] PTY error for run ${run.runId}`, error);
+        stdinClosed = true;
+        finishAgentRun(run, null, ptyOutputBus);
+        try {
+            killPty('SIGTERM');
+        }
+        catch (killError) {
+            ignoreMissingProcess(killError);
+        }
+    });
+    pty.onExit((event) => {
+        stdinClosed = true;
+        clearPtyReadEofTimer();
+        cleanupProcessGroup();
+        finishAgentRun(run, event.exitCode, ptyOutputBus);
+    });
+};