@tt-a1i/hive 1.4.3 → 1.4.4

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable user-facing changes will be documented in this file.
 
+## 1.4.4 - 2026-05-29
+
+Windows portability and team protocol hardening.
+
+- Fixes Windows `.cmd` / `.bat` launch handling for built-in and custom startup
+  commands, including quoted paths from nvm4w and `Program Files`.
+- Improves Windows runtime shutdown by tearing down WebSocket connections before
+  closing the HTTP server and killing worker process trees with `taskkill /T /F`
+  before falling back to PTY termination.
+- Makes `hive update`, open-in-editor commands, folder picking, filesystem
+  browsing, and port-in-use recovery friendlier on Windows.
+- Preserves CRLF line endings in `.hive/tasks.md` mutations and makes the tasks
+  watcher more tolerant of atomic-save editors.
+- Resolves OpenCode session data under `%LOCALAPPDATA%` on Windows and aligns
+  Claude session path encoding with Claude Code's project directory format.
+- Hardens `team send` against stale worker names by returning a 409 with the
+  current roster and updates orchestrator guidance to refresh the member list
+  before dispatching.
+- Expands Windows-focused unit and integration coverage across startup command
+  parsing, CLI shims, stdin protocol help, terminal profiles, filesystem
+  browsing, process cleanup, and path rendering.
+
 ## 1.4.3 - 2026-05-28
 
 Update hardening for multi-Node installs.

package/README.en.md

@@ -107,10 +107,11 @@ a separate app from `hive --port 3000`. To uninstall, visit `chrome://apps`,
 right-click the Hive tile, and choose **Remove from Chrome…**.
 
 Hive asks the browser to confirm before closing the tab or PWA window so an
-accidental Cmd-W doesn't drop your session. Modern browsers gate that prompt
-on prior page interaction — if you open the PWA and immediately press Cmd-W
-without clicking or typing anywhere first, it still closes cleanly. That's a
-browser policy, not a Hive bug.
+accidental close shortcut (Cmd-W on macOS, Ctrl-W on Windows/Linux) doesn't
+drop your session. Modern browsers gate that prompt on prior page interaction
+— if you open the PWA and immediately press the close shortcut without
+clicking or typing anywhere first, it still closes cleanly. That's a browser
+policy, not a Hive bug.
 
 First-run flow:
 

package/README.md

@@ -74,7 +74,7 @@ hive update
 
 PWA 只是 UI 壳，Hive 后端仍需要在终端里跑着。如果启动 PWA 时后端没起，会看到 “Hive 后端未启动” 页面，等你跑起 `hive` 后会自动刷新。PWA 的 install scope 按 origin（含端口）划分，所以 `hive --port 4011` 跟 `hive --port 3000` 在浏览器看来是两个独立应用。卸载方法：浏览器地址栏访问 `chrome://apps`，右键 Hive 图标，选 **从 Chrome 中移除…**。
 
-关闭 PWA 窗口或 tab 时 Hive 会主动请求浏览器弹原生确认对话框，避免 Cmd+W 误关丢失会话。但现代浏览器要求你跟页面"交互过"（点击 / 滚动 / 输入）才会真的弹这个对话框——刚打开 PWA 立刻按 Cmd+W 仍会直接关闭，这是浏览器策略，不是 Hive 的 bug。
+关闭 PWA 窗口或 tab 时 Hive 会主动请求浏览器弹原生确认对话框，避免关闭快捷键（macOS 上是 Cmd+W、Windows / Linux 上是 Ctrl+W）误关丢失会话。但现代浏览器要求你跟页面"交互过"（点击 / 滚动 / 输入）才会真的弹这个对话框——刚打开 PWA 立刻按关闭快捷键仍会直接关闭，这是浏览器策略，不是 Hive 的 bug。
 
 首次使用流程：
 

package/dist/src/cli/hive-update.d.ts

@@ -4,6 +4,35 @@ export interface RunUpdateResult {
     spawnError?: Error;
 }
 export type RunUpdate = (command: string, args: readonly string[]) => Promise<RunUpdateResult>;
+/**
+ * Build the spawn options for the upgrade child. The non-obvious part is
+ * Windows: npm ships as `npm.cmd` (a batch shim), and Node 22+ refuses to
+ * spawn `.cmd` / `.bat` files without `shell: true` after CVE-2024-27980.
+ * Detect by file extension rather than by `process.platform` so the same
+ * code path works for both real Windows runs and our cross-platform unit
+ * tests (which inject `platform: 'win32'` so that `getNpmCommand` returns
+ * `npm.cmd`).
+ *
+ * Known limitation: with `shell: true` the args are stringified through
+ * cmd.exe without quoting, so an install prefix containing spaces (e.g.
+ * `C:\Program Files\nodejs`) will be tokenized incorrectly. The common
+ * Windows prefix `%APPDATA%\npm` does not have this problem; fixing the
+ * spaces case requires a verbatim `cmd.exe /d /s /c call npm.cmd …`
+ * wrapper similar to `agent-command-resolver` and is tracked separately.
+ */
+export declare const buildSpawnOptionsForCommand: (command: string) => {
+    shell: boolean;
+    stdio: "inherit";
+};
+/**
+ * Signals the upgrade child should receive when the parent runtime is
+ * interrupted. Beyond the POSIX-only SIGTERM/SIGINT, SIGHUP is what
+ * libuv synthesises from Windows CTRL_CLOSE_EVENT (window X close),
+ * and SIGBREAK comes from Windows Ctrl+Break. Without forwarding
+ * those two the npm child outlives the runtime on the most common
+ * Windows exit paths.
+ */
+export declare const FORWARDED_UPDATE_SIGNALS: readonly NodeJS.Signals[];
 export declare const defaultRunUpdate: RunUpdate;
 export declare const resolveHiveUpdateInstallArgs: (moduleUrl?: string) => string[];
 interface RunHiveUpdateOptions {

package/dist/src/cli/hive-update.js

@@ -19,27 +19,66 @@ export const HIVE_UPDATE_USAGE = [
     'Options:',
     '  -h, --help      Print this help.',
 ].join('\n');
+/**
+ * Build the spawn options for the upgrade child. The non-obvious part is
+ * Windows: npm ships as `npm.cmd` (a batch shim), and Node 22+ refuses to
+ * spawn `.cmd` / `.bat` files without `shell: true` after CVE-2024-27980.
+ * Detect by file extension rather than by `process.platform` so the same
+ * code path works for both real Windows runs and our cross-platform unit
+ * tests (which inject `platform: 'win32'` so that `getNpmCommand` returns
+ * `npm.cmd`).
+ *
+ * Known limitation: with `shell: true` the args are stringified through
+ * cmd.exe without quoting, so an install prefix containing spaces (e.g.
+ * `C:\Program Files\nodejs`) will be tokenized incorrectly. The common
+ * Windows prefix `%APPDATA%\npm` does not have this problem; fixing the
+ * spaces case requires a verbatim `cmd.exe /d /s /c call npm.cmd …`
+ * wrapper similar to `agent-command-resolver` and is tracked separately.
+ */
+export const buildSpawnOptionsForCommand = (command) => ({
+    shell: /\.(cmd|bat)$/i.test(command),
+    stdio: 'inherit',
+});
+/**
+ * Signals the upgrade child should receive when the parent runtime is
+ * interrupted. Beyond the POSIX-only SIGTERM/SIGINT, SIGHUP is what
+ * libuv synthesises from Windows CTRL_CLOSE_EVENT (window X close),
+ * and SIGBREAK comes from Windows Ctrl+Break. Without forwarding
+ * those two the npm child outlives the runtime on the most common
+ * Windows exit paths.
+ */
+export const FORWARDED_UPDATE_SIGNALS = [
+    'SIGINT',
+    'SIGTERM',
+    'SIGHUP',
+    'SIGBREAK',
+];
 export const defaultRunUpdate = (command, args) => new Promise((resolve) => {
-    const child = spawn(command, [...args], { stdio: 'inherit' });
+    const child = spawn(command, [...args], buildSpawnOptionsForCommand(command));
     let resolved = false;
-    // Forward Ctrl+C / SIGTERM to the npm child so it can clean up rather
-    // than getting orphaned mid-install. The handlers are registered with
-    // `once` so they don't accumulate across invocations, and we also
-    // explicitly remove them when the child exits in case the user only
-    // sent one signal (Node would otherwise keep the handler alive).
-    const handleSignal = (signal) => () => {
-        child.kill(signal);
-    };
-    const handleSigint = handleSignal('SIGINT');
-    const handleSigterm = handleSignal('SIGTERM');
-    process.once('SIGINT', handleSigint);
-    process.once('SIGTERM', handleSigterm);
+    // Handlers are registered with `once` so they don't accumulate
+    // across invocations and explicitly removed at finalize().
+    const handlers = new Map();
+    for (const signal of FORWARDED_UPDATE_SIGNALS) {
+        const handler = () => {
+            try {
+                child.kill(signal);
+            }
+            catch {
+                // child.kill on Windows throws if the signal name isn't
+                // implemented; we forward what we can and ignore the rest.
+            }
+        };
+        handlers.set(signal, handler);
+        process.once(signal, handler);
+    }
     const finalize = (result) => {
         if (resolved)
             return;
         resolved = true;
-        process.off('SIGINT', handleSigint);
-        process.off('SIGTERM', handleSigterm);
+        for (const [signal, handler] of handlers) {
+            process.off(signal, handler);
+        }
         resolve(result);
     };
     child.on('error', (error) => {

package/dist/src/cli/hive.d.ts

@@ -9,7 +9,39 @@ interface RunHiveCommandResult {
 type RunHiveCommandOptions = {
     versionService?: VersionService;
 };
+/**
+ * Signals that should drive a graceful shutdown. The interesting ones:
+ *
+ *   SIGINT  — Ctrl+C in the runtime terminal (all platforms).
+ *   SIGTERM — `kill <pid>` on POSIX. Never delivered on Windows.
+ *   SIGHUP  — POSIX: parent shell exits. On Windows libuv synthesises
+ *             SIGHUP from `CTRL_CLOSE_EVENT`, i.e. the user clicking
+ *             the X on the runtime's cmd / Terminal window. Without
+ *             this listener that close path skips the graceful path
+ *             entirely on Windows.
+ *   SIGBREAK — Windows: Ctrl+Break. Less common than Ctrl+C but kit
+ *             scripts and CI hosts still send it.
+ *
+ * Stale agent_runs from a non-graceful exit are reconciled at next
+ * startup via `agentRunStore.markUnfinishedRunsStale()`
+ * (runtime-store-helpers.ts), so a dropped signal does not leave the
+ * database in an inconsistent state — only the PTY children miss the
+ * forwarded SIGTERM. On Windows there's no graceful equivalent for
+ * those children anyway (pty.kill is TerminateProcess), so this
+ * registration is mostly about giving SQLite a chance to checkpoint.
+ */
+export declare const SHUTDOWN_SIGNALS: readonly ["SIGINT", "SIGTERM", "SIGHUP", "SIGBREAK"];
 export declare const HIVE_USAGE: string;
 export declare const handleHiveInfoCommand: (argv: string[]) => boolean;
+/**
+ * Recovery hint formatter for the "port already in use" error. Platform-aware
+ * because the lsof / xargs / kill pipeline is POSIX-only; on Windows a user
+ * pasting that command into cmd or PowerShell gets nothing useful. The
+ * Windows path swaps in `netstat -ano | findstr` + `taskkill /F /PID` which
+ * is the documented Microsoft workflow for the same problem.
+ *
+ * Exported for unit testing.
+ */
+export declare const formatPortInUseMessage: (port: number, platform?: NodeJS.Platform) => string;
 export declare const runHiveCommand: (argv: string[], options?: RunHiveCommandOptions) => Promise<RunHiveCommandResult>;
 export type { RunHiveCommandResult };

package/dist/src/cli/hive.js

@@ -10,6 +10,28 @@ import { readPackageVersion } from '../server/package-version.js';
 import { createRuntimeStore } from '../server/runtime-store.js';
 import { createVersionService } from '../server/version-service.js';
 import { runHiveUpdateCommand } from './hive-update.js';
+/**
+ * Signals that should drive a graceful shutdown. The interesting ones:
+ *
+ *   SIGINT  — Ctrl+C in the runtime terminal (all platforms).
+ *   SIGTERM — `kill <pid>` on POSIX. Never delivered on Windows.
+ *   SIGHUP  — POSIX: parent shell exits. On Windows libuv synthesises
+ *             SIGHUP from `CTRL_CLOSE_EVENT`, i.e. the user clicking
+ *             the X on the runtime's cmd / Terminal window. Without
+ *             this listener that close path skips the graceful path
+ *             entirely on Windows.
+ *   SIGBREAK — Windows: Ctrl+Break. Less common than Ctrl+C but kit
+ *             scripts and CI hosts still send it.
+ *
+ * Stale agent_runs from a non-graceful exit are reconciled at next
+ * startup via `agentRunStore.markUnfinishedRunsStale()`
+ * (runtime-store-helpers.ts), so a dropped signal does not leave the
+ * database in an inconsistent state — only the PTY children miss the
+ * forwarded SIGTERM. On Windows there's no graceful equivalent for
+ * those children anyway (pty.kill is TerminateProcess), so this
+ * registration is mostly about giving SQLite a chance to checkpoint.
+ */
+export const SHUTDOWN_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGBREAK'];
 export const HIVE_USAGE = [
     'Usage:',
     '  hive [--port <port>]',
@@ -66,19 +88,39 @@ const maybePrintUpdateHint = async (versionService) => {
     console.log(`Hive update available: ${info.current_version} -> ${info.latest_version}. Run: ${info.install_hint}`);
 };
 const isListenError = (error) => error instanceof Error && typeof error.code === 'string';
-const formatPortInUseMessage = (port) => [
-    `Hive could not start because port ${port} is already in use.`,
-    '',
-    'Another Hive instance may already be running:',
-    `  http://127.0.0.1:${port}`,
-    '',
-    'Options:',
-    '  - Open the existing Hive window.',
-    '  - Stop the process using that port:',
-    `      lsof -tiTCP:${port} -sTCP:LISTEN | xargs kill`,
-    '  - Start Hive on another port:',
-    `      hive --port ${port + 1}`,
-].join('\n');
+/**
+ * Recovery hint formatter for the "port already in use" error. Platform-aware
+ * because the lsof / xargs / kill pipeline is POSIX-only; on Windows a user
+ * pasting that command into cmd or PowerShell gets nothing useful. The
+ * Windows path swaps in `netstat -ano | findstr` + `taskkill /F /PID` which
+ * is the documented Microsoft workflow for the same problem.
+ *
+ * Exported for unit testing.
+ */
+export const formatPortInUseMessage = (port, platform = process.platform) => {
+    const stopHint = platform === 'win32'
+        ? [
+            '  - Stop the process using that port:',
+            `      netstat -ano | findstr ":${port}"`,
+            '      taskkill /PID <pid> /F',
+        ]
+        : [
+            '  - Stop the process using that port:',
+            `      lsof -tiTCP:${port} -sTCP:LISTEN | xargs kill`,
+        ];
+    return [
+        `Hive could not start because port ${port} is already in use.`,
+        '',
+        'Another Hive instance may already be running:',
+        `  http://127.0.0.1:${port}`,
+        '',
+        'Options:',
+        '  - Open the existing Hive window.',
+        ...stopHint,
+        '  - Start Hive on another port:',
+        `      hive --port ${port + 1}`,
+    ].join('\n');
+};
 const formatListenError = (error, requestedPort) => {
     if (isListenError(error) && error.code === 'EADDRINUSE') {
         return new Error(formatPortInUseMessage(error.port ?? requestedPort));
@@ -119,8 +161,20 @@ export const runHiveCommand = async (argv, options = {}) => {
             return closePromise;
         }
         closePromise = (async () => {
-            process.off('SIGTERM', gracefulShutdown);
-            process.off('SIGINT', gracefulShutdown);
+            for (const signal of SHUTDOWN_SIGNALS) {
+                process.off(signal, gracefulShutdown);
+            }
+            // Tear down the WebSocket layer FIRST. `app.server.close()` waits
+            // on every existing socket, including upgraded WebSocket clients
+            // that never go idle on their own; `server.closeAllConnections()`
+            // alone does NOT terminate already-upgraded WS — only sockets
+            // still in the HTTP request/response state machine. The Windows
+            // symptom of skipping this step is Ctrl+C in the runtime cmd
+            // window hanging the process as long as any browser tab is
+            // connected to /ws/terminal/<runId> or /ws/tasks/<workspaceId>.
+            app.closeWebSockets();
+            // Then force-close any remaining plain-HTTP keep-alive sockets.
+            app.server.closeAllConnections();
             await new Promise((resolve, reject) => {
                 app.server.close((error) => {
                     if (error) {
@@ -144,8 +198,9 @@ export const runHiveCommand = async (argv, options = {}) => {
             process.exit(1);
         });
     };
-    process.once('SIGTERM', gracefulShutdown);
-    process.once('SIGINT', gracefulShutdown);
+    for (const signal of SHUTDOWN_SIGNALS) {
+        process.once(signal, gracefulShutdown);
+    }
     console.log(`Hive running at http://127.0.0.1:${address.port}`);
     void maybePrintUpdateHint(versionService).catch(() => { });
     return {

package/dist/src/cli/team.js

@@ -17,10 +17,13 @@ const TEAM_USAGE = [
     '  team status --stdin [--artifact <path>]',
     '',
     'Flags can appear in any order. Use --stdin to pipe long bodies and avoid shell-escaping issues.',
-    "Use a quoted heredoc (<<'EOF') so $vars, backticks, and command substitutions stay literal:",
-    "  team report --stdin --dispatch <id> <<'EOF'",
-    '  ... long report ...',
-    '  EOF',
+    'The body comes from stdin — use whatever your shell supports:',
+    "  POSIX:        team report --stdin --dispatch <id> <<'EOF'",
+    '                ... long report ...',
+    '                EOF',
+    '  Windows cmd:  type body.txt | team report --stdin --dispatch <id>',
+    '  PowerShell:   Get-Content body.txt | team report --stdin --dispatch <id>',
+    '  Portable:     team report --stdin --dispatch <id> < body.txt',
     '',
     'For role rules, workflow, and recovery instructions, see .hive/PROTOCOL.md',
 ].join('\n');
@@ -226,7 +229,16 @@ export const runTeamCommand = async (argv) => {
             to: workerName,
             text: task,
         });
-        console.log(JSON.stringify(await response.json()));
+        const payload = (await response.json());
+        /* When the dispatch happened to also auto-wake a stopped worker
+           (PTY had no active run), make the silent restart visible. Stderr
+           is the right channel because the JSON on stdout is the
+           machine-readable payload; the human-readable narration goes
+           beside it so it doesn't corrupt parsers. */
+        if (payload.restarted_worker === true) {
+            console.error(`Hive woke up worker "${workerName}" before dispatching.`);
+        }
+        console.log(JSON.stringify(payload));
         return;
     }
     if (command === 'cancel') {

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

@@ -1,5 +1,14 @@
 interface ResolvedSpawnCommand {
-    args: string[];
+    /**
+     * `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;

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

@@ -1,5 +1,5 @@
 import { accessSync, constants } from 'node:fs';
-import { delimiter, extname, isAbsolute, join } from 'node:path';
+import { basename, delimiter, extname, isAbsolute, join } from 'node:path';
 const hasPathSeparator = (command) => command.includes('/') || command.includes('\\');
 const canExecute = (path, platform = process.platform) => {
     try {
@@ -54,16 +54,60 @@ const isWindowsBatchFile = (command) => {
     const extension = extname(command).toLowerCase();
     return extension === '.cmd' || extension === '.bat';
 };
-const quoteWindowsCommandArgument = (value) => `"${value.replace(/"/g, '\\"')}"`;
-const createWindowsCommandLine = (command, args) => [command, ...args].map(quoteWindowsCommandArgument).join(' ');
+/**
+ * cmd.exe-style escape: doubles inner `"` (cmd's only literal-quote idiom)
+ * and only wraps in `"..."` when the token contains whitespace or a cmd
+ * metachar. Plain alnum/path tokens stay unquoted, which is the form
+ * cmd.exe parses most predictably.
+ *
+ * Crucially, we do NOT use the `\"` form that the previous implementation
+ * used and that node-pty's `argsToCommandLine` produces: cmd doesn't honor
+ * backslash-quote escapes in its own command-line parsing.
+ */
+const escapeCmdToken = (value) => {
+    if (value.length === 0)
+        return '""';
+    const doubled = value.replace(/"/g, '""');
+    return /[\s"&<>|^()]/.test(value) ? `"${doubled}"` : doubled;
+};
+const buildWindowsBatchCommandLine = (command, args) => {
+    const tokens = [command, ...args].map(escapeCmdToken).join(' ');
+    // `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).
+    return `/d /s /c call ${tokens}`;
+};
+/**
+ * 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';
 export const resolveSpawnCommand = (command, cwd, env, args = [], platform = process.platform) => {
     const resolvedCommand = resolveCommandPath(command, cwd, env, platform);
     if (platform === 'win32' && isWindowsBatchFile(resolvedCommand)) {
         return {
-            args: ['/d', '/s', '/c', createWindowsCommandLine(resolvedCommand, args)],
+            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) => {

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

@@ -1,4 +1,4 @@
-import { createStartupCommandLaunch, getStartupCommandExecutable, } from './startup-command-parser.js';
+import { createStartupCommandLaunch, getStartupCommandExecutable, normalizeExecutableToken, } from './startup-command-parser.js';
 export const resolveCommandPresetLaunchConfig = (settings, commandPresetId) => {
     const preset = settings.getCommandPreset(commandPresetId);
     if (!preset)
@@ -12,8 +12,14 @@ export const resolveCommandPresetLaunchConfig = (settings, commandPresetId) => {
 const findPresetForStartupCommand = (settings, startupCommand, commandPresetId) => {
     if (commandPresetId)
         return settings.getCommandPreset(commandPresetId);
-    const executable = getStartupCommandExecutable(startupCommand);
-    return executable ? settings.getCommandPreset(executable) : undefined;
+    // 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();

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

@@ -2,6 +2,34 @@ 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[]) => void;
+/**
+ * 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) => 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) => void;
+export {};

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

@@ -1,6 +1,45 @@
 import { execFileSync } from 'node:child_process';
 export const MAX_RUN_OUTPUT_LENGTH = 1_000_000;
 const FORCE_KILL_DELAY_MS = 750;
+const defaultExecRunner = (cmd, args) => {
+    execFileSync(cmd, [...args], { stdio: 'ignore', windowsHide: true });
+};
+/**
+ * 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) => {
+    if (platform !== 'win32' || pid <= 0)
+        return false;
+    try {
+        runner('taskkill', ['/pid', String(pid), '/t', '/f']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
 export const toAgentRunSnapshot = (run) => ({
     runId: run.runId,
     agentId: run.agentId,
@@ -62,8 +101,18 @@ export const attachAgentPty = (run, pty, ptyOutputBus) => {
     };
     const killPty = (signal) => {
         try {
-            if (process.platform === 'win32')
-                pty.kill();
+            if (process.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))
+                    pty.kill();
+            }
             else
                 pty.kill(signal);
         }
@@ -88,8 +137,13 @@ export const attachAgentPty = (run, pty, ptyOutputBus) => {
         forceKillTimer = setTimeout(() => {
             forceKillTimer = undefined;
             try {
-                if (process.platform === 'win32')
-                    pty.kill();
+                if (process.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 fallback for taskkill-missing hosts.
+                    if (!taskkillProcessTree(pty.pid))
+                        pty.kill();
+                }
                 else
                     pty.kill('SIGKILL');
             }

package/dist/src/server/agent-run-bootstrap.d.ts

@@ -3,6 +3,23 @@ import type { AgentLaunchConfigInput } from './agent-run-store.js';
 import type { AgentSessionStorePort } from './agent-runtime-ports.js';
 import type { CommandPresetRecord } from './command-preset-store.js';
 import { type SessionCaptureSnapshot } from './session-capture.js';
+/**
+ * Builds a `{ <PATH-key>: <new-value> }` object for the spawn env override.
+ * Critical on Windows: the OS env block reports PATH under its native casing
+ * (typically `Path`). Writing to a literal `PATH` key would, after spread
+ * with `process.env`, leave two entries — `Path` carrying the original value
+ * and `PATH` carrying our prepend. CreateProcess then sees both and the
+ * effective lookup order is undefined; in practice the child PTY often falls
+ * back to the original `Path` and never sees `HIVE_BIN_DIR`, breaking every
+ * `team` shim resolution.
+ *
+ * We detect the existing key (case-insensitive on Windows) and overwrite IT,
+ * so the merge produces exactly one PATH entry.
+ *
+ * Exported for unit testing — `buildAgentRunBootstrap` is the only in-tree
+ * caller.
+ */
+export declare const buildSpawnPathEnvEntry: (parentEnv: NodeJS.ProcessEnv, hiveBinDir: string, platform: NodeJS.Platform) => NodeJS.ProcessEnv;
 export declare const buildAgentRunBootstrap: (workspace: WorkspaceSummary, agentId: string, config: AgentLaunchConfigInput, sessionStore: AgentSessionStorePort, getCommandPreset: (id: string) => CommandPresetRecord | undefined, agent?: AgentSummary) => {
     sessionCaptureSnapshot: {
         discriminator?: {
@@ -50,7 +67,6 @@ export declare const buildAgentRunBootstrap: (workspace: WorkspaceSummary, agent
         HIVE_PROJECT_ID: string;
         HIVE_AGENT_ID: string;
         HIVE_AGENT_TOKEN: string;
-        PATH: string;
     };
 };
 export declare const startAgentRunCapture: ({ agentId, sessionCaptureSnapshot, sessionStore, startConfig, workspace, }: {