@tt-a1i/hive 1.4.3 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable user-facing changes will be documented in this file.
 
+## 1.5.0 - 2026-05-31
+
+Workflow runtime, experimental team automation, and Codex reliability.
+
+- Adds the experimental Hive workflow runtime: Orchestrators can author
+  multi-agent workflow scripts that fan out across real Hive PTY workers, show
+  runs in the Workflows drawer, stop runs, inspect run details, schedule
+  recurring workflows, and route workflow reports back into the Orchestrator.
+- Adds workflow agent CLI policy settings so users can choose which CLI
+  workflow-created agents use by default and which CLIs are allowed.
+- Adds the experimental auto-staff setting, letting the Orchestrator size the
+  worker roster to the task and prefer task-scoped ephemeral workers when it
+  needs temporary coders, testers, or reviewers.
+- Adds an in-app What's New dialog so future upgrades can surface curated
+  release highlights without requiring users to read the changelog manually.
+- Improves Codex reliability by waiting for pasted-content acknowledgements on
+  long dispatches while submitting short report/status injections quickly,
+  avoiding the several-second delay before reports reach the Orchestrator.
+- Hardens Windows and runtime edge cases, including malformed WebSocket frames,
+  stale nvm4w Codex node entrypoints, workflow worker exits, and additional
+  workflow/runtime cleanup paths.
+
+## 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。
 
 首次使用流程：
 
@@ -241,6 +241,14 @@ pnpm release:dry
 
 Hive 目前处于 alpha 阶段，核心流程已可用。当前重点是继续打磨多 Agent 协作体验、Windows 支持和更清晰的调度可观测性。欢迎试用、提 issue——反馈会直接影响后续节奏。
 
+## 交流群
+
+有问题、想反馈，或者就想聊聊 Agent 协作，欢迎进 QQ 群：**Ai Native 交流群**（群号 `1098836554`）。
+
+<p align="center">
+  <img src="./assets/qq-group.jpg" width="240" alt="Ai Native 交流群 QQ 群二维码，群号 1098836554" />
+</p>
+
 ## 在路上：跨 Agent 的长时记忆
 
 <p align="center">

package/dist/bin/team.cmd

@@ -1,2 +1,3 @@
 @echo off
+setlocal DisableDelayedExpansion
 node "%~dp0..\src\cli\team.js" %*

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

@@ -4,6 +4,63 @@ export interface RunUpdateResult {
     spawnError?: Error;
 }
 export type RunUpdate = (command: string, args: readonly string[]) => Promise<RunUpdateResult>;
+export interface SpawnInvocationPlan {
+    command: string;
+    args: string[];
+    options: {
+        stdio: 'inherit';
+        windowsHide?: boolean;
+    };
+}
+/**
+ * Plan how `defaultRunUpdate` should hand the npm invocation to
+ * `child_process.spawn`. Two non-obvious cases collapse here.
+ *
+ * 1. Node 22+ refuses to spawn `.cmd` / `.bat` files directly after
+ *    CVE-2024-27980 unless `shell: true` is passed. We do not want
+ *    `shell: true` though — its arg-stringification path joins argv
+ *    without quoting, so an install prefix containing spaces (the
+ *    common Windows case `C:\Program Files\nodejs`) gets word-split
+ *    by cmd.exe and `--prefix` only sees the first token, so npm
+ *    silently installs hive to the wrong directory.
+ * 2. Wrapping with `cmd.exe /d /s /c <npm.cmd> <args>` solves both:
+ *    spawning `cmd.exe` (a native exe) avoids the .cmd refusal, and
+ *    Node's own argv-quoting builds an lpCommandLine where each
+ *    space-containing arg is wrapped in double quotes that cmd.exe
+ *    then re-parses correctly. `/d` skips AutoRun, `/s` keeps the
+ *    quote-handling consistent with `/c`.
+ *
+ * Detect by filename suffix instead of `process.platform` so unit
+ * tests can inject `platform: 'win32'` and exercise the wrap.
+ */
+export declare const planSpawnInvocation: (command: string, args: readonly string[], platform?: NodeJS.Platform) => SpawnInvocationPlan;
+/**
+ * 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[];
+/**
+ * Forward a parent-process signal to the spawned npm child. On POSIX
+ * we hand the signal straight to the child; on Windows there are no
+ * real signals, so `child.kill(SIGTERM)` resolves to TerminateProcess
+ * against cmd.exe (our wrapper) only — npm itself, plus any install
+ * scripts it spawned, become orphans. `taskkill /pid <pid> /t /f`
+ * walks the wrapper's process tree so the whole branch dies together.
+ * If taskkill is unavailable (restricted PATH, locked-down policy)
+ * we fall back to `child.kill` so the wrapper at least exits.
+ *
+ * Exported so the win32 path can be unit-tested by injecting a stub
+ * `killTree` runner — the real `taskkillProcessTree` shells out, and
+ * we don't want that running during the test suite.
+ */
+export declare const killUpdateChild: (child: {
+    pid?: number | undefined;
+    kill: (signal: NodeJS.Signals) => boolean;
+}, signal: NodeJS.Signals, platform?: NodeJS.Platform, killTree?: (pid: number, onFailure?: () => void) => boolean) => void;
 export declare const defaultRunUpdate: RunUpdate;
 export declare const resolveHiveUpdateInstallArgs: (moduleUrl?: string) => string[];
 interface RunHiveUpdateOptions {

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

@@ -2,7 +2,9 @@ import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { taskkillProcessTree } from '../server/agent-manager-support.js';
 import { getNpmCommand, INSTALL_COMMAND_ARGS, INSTALL_COMMAND_DISPLAY, PACKAGE_NAME, } from '../server/package-version.js';
+import { buildCmdCallCommand } from '../server/windows-command-line.js';
 export const HIVE_UPDATE_USAGE = [
     'Usage:',
     '  hive update',
@@ -19,27 +21,102 @@ export const HIVE_UPDATE_USAGE = [
     'Options:',
     '  -h, --help      Print this help.',
 ].join('\n');
+/**
+ * Plan how `defaultRunUpdate` should hand the npm invocation to
+ * `child_process.spawn`. Two non-obvious cases collapse here.
+ *
+ * 1. Node 22+ refuses to spawn `.cmd` / `.bat` files directly after
+ *    CVE-2024-27980 unless `shell: true` is passed. We do not want
+ *    `shell: true` though — its arg-stringification path joins argv
+ *    without quoting, so an install prefix containing spaces (the
+ *    common Windows case `C:\Program Files\nodejs`) gets word-split
+ *    by cmd.exe and `--prefix` only sees the first token, so npm
+ *    silently installs hive to the wrong directory.
+ * 2. Wrapping with `cmd.exe /d /s /c <npm.cmd> <args>` solves both:
+ *    spawning `cmd.exe` (a native exe) avoids the .cmd refusal, and
+ *    Node's own argv-quoting builds an lpCommandLine where each
+ *    space-containing arg is wrapped in double quotes that cmd.exe
+ *    then re-parses correctly. `/d` skips AutoRun, `/s` keeps the
+ *    quote-handling consistent with `/c`.
+ *
+ * Detect by filename suffix instead of `process.platform` so unit
+ * tests can inject `platform: 'win32'` and exercise the wrap.
+ */
+export const planSpawnInvocation = (command, args, platform = process.platform) => {
+    if (platform === 'win32' && /\.(cmd|bat)$/i.test(command)) {
+        return {
+            command: 'cmd.exe',
+            args: ['/d', '/s', '/c', buildCmdCallCommand(command, args)],
+            options: { stdio: 'inherit', windowsHide: false },
+        };
+    }
+    return { command, args: [...args], options: { 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',
+];
+/**
+ * Forward a parent-process signal to the spawned npm child. On POSIX
+ * we hand the signal straight to the child; on Windows there are no
+ * real signals, so `child.kill(SIGTERM)` resolves to TerminateProcess
+ * against cmd.exe (our wrapper) only — npm itself, plus any install
+ * scripts it spawned, become orphans. `taskkill /pid <pid> /t /f`
+ * walks the wrapper's process tree so the whole branch dies together.
+ * If taskkill is unavailable (restricted PATH, locked-down policy)
+ * we fall back to `child.kill` so the wrapper at least exits.
+ *
+ * Exported so the win32 path can be unit-tested by injecting a stub
+ * `killTree` runner — the real `taskkillProcessTree` shells out, and
+ * we don't want that running during the test suite.
+ */
+export const killUpdateChild = (child, signal, platform = process.platform, killTree = (pid, onFailure) => taskkillProcessTree(pid, platform, undefined, onFailure)) => {
+    const fallback = () => {
+        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.
+        }
+    };
+    if (platform === 'win32' && typeof child.pid === 'number' && child.pid > 0) {
+        if (killTree(child.pid, fallback))
+            return;
+    }
+    fallback();
+};
 export const defaultRunUpdate = (command, args) => new Promise((resolve) => {
-    const child = spawn(command, [...args], { stdio: 'inherit' });
+    const plan = planSpawnInvocation(command, args);
+    const child = spawn(plan.command, plan.args, plan.options);
     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 = () => {
+            killUpdateChild(child, signal);
+        };
+        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,64 @@ 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;
+/**
+ * Resolve the directory where Hive persists its SQLite DB and supporting
+ * state. Platform-aware because `~/.config/hive` is a hidden dot-directory
+ * convention that Windows Explorer treats as second-class — Windows users
+ * can't navigate there from the address bar without typing the full path,
+ * and the standard roaming-profile location is `%APPDATA%\<app>` instead.
+ *
+ * Resolution order:
+ *   1. HIVE_DATA_DIR override (any platform, for tests / opinionated users).
+ *   2. Windows: %APPDATA%\hive — roaming user state, follows the user
+ *      across machines on a domain profile. APPDATA, not LOCALAPPDATA,
+ *      because Hive's DB is user data, not a machine-local cache.
+ *      Falls back to homedir()\AppData\Roaming\hive when APPDATA is
+ *      stripped from the env (some Windows Task Scheduler configs do this).
+ *   3. POSIX: $XDG_CONFIG_HOME/hive, falling back to ~/.config/hive.
+ *
+ * Migration: pre-fix Windows installs wrote to ~/.config/hive. When that
+ * legacy directory exists but the new %APPDATA%\hive does not, prefer the
+ * legacy path so an upgrade does not surface as an empty workspace list.
+ * This is a one-way ratchet — once the new location is populated, it wins.
+ *
+ * Exported so the resolution rules are unit-testable without touching env
+ * or the real filesystem.
+ */
+export declare const resolveDataDir: (platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, pathExists?: (path: string) => boolean) => string;
+/**
+ * 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

@@ -1,15 +1,38 @@
 #!/usr/bin/env node
 import { once } from 'node:events';
-import { realpathSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createAgentManager } from '../server/agent-manager.js';
 import { createApp } from '../server/app.js';
 import { readPackageVersion } from '../server/package-version.js';
+import { sameFilesystemPath } from '../server/path-canonicalization.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>]',
@@ -58,7 +81,44 @@ const parsePort = (argv) => {
     }
     return parsedPort ?? 3000;
 };
-const resolveDataDir = () => process.env.HIVE_DATA_DIR || join(homedir(), '.config', 'hive');
+/**
+ * Resolve the directory where Hive persists its SQLite DB and supporting
+ * state. Platform-aware because `~/.config/hive` is a hidden dot-directory
+ * convention that Windows Explorer treats as second-class — Windows users
+ * can't navigate there from the address bar without typing the full path,
+ * and the standard roaming-profile location is `%APPDATA%\<app>` instead.
+ *
+ * Resolution order:
+ *   1. HIVE_DATA_DIR override (any platform, for tests / opinionated users).
+ *   2. Windows: %APPDATA%\hive — roaming user state, follows the user
+ *      across machines on a domain profile. APPDATA, not LOCALAPPDATA,
+ *      because Hive's DB is user data, not a machine-local cache.
+ *      Falls back to homedir()\AppData\Roaming\hive when APPDATA is
+ *      stripped from the env (some Windows Task Scheduler configs do this).
+ *   3. POSIX: $XDG_CONFIG_HOME/hive, falling back to ~/.config/hive.
+ *
+ * Migration: pre-fix Windows installs wrote to ~/.config/hive. When that
+ * legacy directory exists but the new %APPDATA%\hive does not, prefer the
+ * legacy path so an upgrade does not surface as an empty workspace list.
+ * This is a one-way ratchet — once the new location is populated, it wins.
+ *
+ * Exported so the resolution rules are unit-testable without touching env
+ * or the real filesystem.
+ */
+export const resolveDataDir = (platform = process.platform, env = process.env, pathExists = existsSync) => {
+    const override = env.HIVE_DATA_DIR;
+    if (override)
+        return override;
+    if (platform === 'win32') {
+        const appData = env.APPDATA ?? join(homedir(), 'AppData', 'Roaming');
+        const target = join(appData, 'hive');
+        const legacy = join(homedir(), '.config', 'hive');
+        if (!pathExists(target) && pathExists(legacy))
+            return legacy;
+        return target;
+    }
+    return join(env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'hive');
+};
 const maybePrintUpdateHint = async (versionService) => {
     const info = await versionService.getVersionInfo();
     if (!info.update_available)
@@ -66,19 +126,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 +199,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 +236,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 {
@@ -155,7 +248,7 @@ export const runHiveCommand = async (argv, options = {}) => {
     };
 };
 const isMainModule = process.argv[1]
-    ? fileURLToPath(import.meta.url) === realpathSync(process.argv[1])
+    ? sameFilesystemPath(fileURLToPath(import.meta.url), process.argv[1])
     : false;
 if (isMainModule) {
     const argv = process.argv.slice(2);

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

@@ -10,6 +10,7 @@ export interface ParsedReportArgs {
 }
 export declare const parseReportArgs: (args: string[], command?: string) => ParsedReportArgs;
 export declare const parseCancelArgs: (args: string[]) => ParsedCancelArgs;
+export declare const decodeStdinBuffer: (buffer: Buffer) => string;
 export declare const readStdinToString: (command?: string) => Promise<string>;
 export declare const runTeamCommand: (argv: string[]) => Promise<void>;
 export {};