@tt-a1i/hive 1.4.2 → 1.4.4

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, }: {

package/dist/src/server/agent-run-bootstrap.js

@@ -1,4 +1,4 @@
-import { delimiter, dirname, resolve, sep } from 'node:path';
+import { dirname, posix, resolve, sep, win32 } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { buildAgentLegacyIdentityMarker, buildAgentSessionBindingMarker, } from './agent-startup-instructions.js';
 import { withPresetResumeArgs } from './preset-launch-support.js';
@@ -12,6 +12,34 @@ const resolveHiveBinDir = () => {
 };
 const HIVE_BIN_DIR = resolveHiveBinDir();
 const SESSION_CAPTURE_TIMEOUT_MS = 30_000;
+/**
+ * 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 const buildSpawnPathEnvEntry = (parentEnv, hiveBinDir, platform) => {
+    const existingKey = platform === 'win32'
+        ? Object.keys(parentEnv).find((key) => key.toLowerCase() === 'path')
+        : undefined;
+    const key = existingKey ?? 'PATH';
+    const existingValue = existingKey ? parentEnv[existingKey] : parentEnv.PATH;
+    // Target platform's delimiter — Windows uses `;`, POSIX `:` — independent
+    // of where this function is running (tests on macOS verify the win32 path).
+    const platformDelimiter = platform === 'win32' ? win32.delimiter : posix.delimiter;
+    const value = existingValue ? `${hiveBinDir}${platformDelimiter}${existingValue}` : hiveBinDir;
+    return { [key]: value };
+};
 const resolveLaunchPreset = (config, getCommandPreset) => {
     if (config.presetAugmentationDisabled)
         return undefined;
@@ -52,7 +80,7 @@ export const buildAgentRunBootstrap = (workspace, agentId, config, sessionStore,
             HIVE_PROJECT_ID: workspace.id,
             HIVE_AGENT_ID: agentId,
             HIVE_AGENT_TOKEN: '',
-            PATH: `${HIVE_BIN_DIR}${delimiter}${process.env.PATH ?? ''}`,
+            ...buildSpawnPathEnvEntry(process.env, HIVE_BIN_DIR, process.platform),
         },
     };
 };

package/dist/src/server/agent-startup-instructions.js

@@ -18,7 +18,7 @@ export const buildAgentStartupInstructions = ({ agent, workspace, }) => {
         lines.push('你的职责：', '- 直接响应 user，澄清需求并拆解任务', `- 维护 ${TASKS_RELATIVE_PATH}`, '- 按 worker 名称派单，并根据汇报推进下一步', '', '可用 team 命令：', '- team list', '- team send <worker-name> "<task>"', '- team cancel --dispatch <id> "<reason>"', '', '派单时必须使用 worker name，不要使用 worker id。', '取消未完成派单时必须使用 dispatch id。', '', 'Hive worker 派单规则：', ...getHiveTeamRules(agent));
     }
     else {
-        lines.push('可用 team 命令：', '- team report "<完整汇报>" [--dispatch <id>] [--artifact <path>]    完成/失败/阻塞汇报', '- team report --stdin [--dispatch <id>] [--artifact <path>]         同上，从 stdin 读正文（适合多行/含引号/特殊字符）', '- team status "<当前状态>" [--artifact <path>]                       中段进度/待命/接入状态', '- team status --stdin [--artifact <path>]                          同上，从 stdin 读正文', '- team list                                                        查看 workspace 内的 worker（含状态）', '- team --help                                                      仅查命令用法；**不是**汇报手段', '', '语法要点：', '- 正文是第一个 positional argument，flag 顺序任意：`team report "结论" --dispatch X` 和 `team report --dispatch X "结论"` 都成立。', "- 长正文（多行 / 含引号 / shell 特殊字符 / heredoc）一律走 `--stdin`，并用 *quoted* heredoc（`<<'EOF'`）防止 shell 展开 $vars / 反引号 / 命令替换：", "  例：`team report --stdin --dispatch <id> <<'EOF'`", '       `... 长报告（含 $VAR、`backtick`、"引号" 都按字面量保留）...`', '       `EOF`', '- CLI 报错会同时打印 USAGE，可直接对照修正参数。', '', '完成任务后必须执行 `team report "<结论>"`。', '失败、阻塞或部分完成也用 `team report "<当前状态与原因>"` 汇报。', '没有进行中的任务时，用 `team status "<当前状态>"` 汇报接入、待命或阻塞状态。', '不要调用 team send；worker 之间不能直接派单。', '', 'Hive worker 边界：', ...getHiveTeamRules(agent));
+        lines.push('可用 team 命令：', '- team report "<完整汇报>" [--dispatch <id>] [--artifact <path>]    完成/失败/阻塞汇报', '- team report --stdin [--dispatch <id>] [--artifact <path>]         同上，从 stdin 读正文（适合多行/含引号/特殊字符）', '- team status "<当前状态>" [--artifact <path>]                       中段进度/待命/接入状态', '- team status --stdin [--artifact <path>]                          同上，从 stdin 读正文', '- team list                                                        查看 workspace 内的 worker（含状态）', '- team --help                                                      仅查命令用法；**不是**汇报手段', '', '语法要点：', '- 正文是第一个 positional argument，flag 顺序任意：`team report "结论" --dispatch X` 和 `team report --dispatch X "结论"` 都成立。', '- 长正文（多行 / 含引号 / shell 特殊字符）一律走 `--stdin`，通过你所在 shell 的管道喂给它（POSIX 用 quoted heredoc `<<\'EOF\' … EOF` 防止 $var/反引号展开，Windows cmd 用 `type body.txt |` 或临时文件 `< body.txt`）。`--stdin` 自己只负责"从 stdin 读"，不依赖任何 shell 语法。', '- CLI 报错会同时打印 USAGE，可直接对照修正参数。', '', '完成任务后必须执行 `team report "<结论>"`。', '失败、阻塞或部分完成也用 `team report "<当前状态与原因>"` 汇报。', '没有进行中的任务时，用 `team status "<当前状态>"` 汇报接入、待命或阻塞状态。', '不要调用 team send；worker 之间不能直接派单。', '', 'Hive worker 边界：', ...getHiveTeamRules(agent));
     }
     lines.push('');
     return lines.join('\n');

package/dist/src/server/app.d.ts

@@ -15,5 +15,6 @@ interface CreateAppOptions {
 export declare const createApp: ({ store, pickFolderService, openWorkspaceService, packageVersionReader, tasksFileService, versionService, }: CreateAppOptions) => {
     server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
     store: RuntimeStore;
+    closeWebSockets: () => void;
 };
 export type { CreateAppOptions };

package/dist/src/server/app.js

@@ -196,6 +196,16 @@ export const createApp = ({ store, pickFolderService = pickFolder, openWorkspace
             sendJson(response, 500, { error: message });
         }
     });
-    createTerminalWebSocketServer(server, store, tasksFileService);
-    return { server, store };
+    const wsServer = createTerminalWebSocketServer(server, store, tasksFileService);
+    return {
+        server,
+        store,
+        // Tear-down for the WebSocket layer. Callers must invoke this
+        // BEFORE awaiting `server.close()` if they want a prompt return:
+        // `server.close()` waits on every existing socket, and Node's
+        // `closeAllConnections()` does NOT terminate already-upgraded
+        // WebSocket clients. Without this hook a Ctrl+C in the Hive
+        // runtime hangs as long as any browser tab is connected.
+        closeWebSockets: wsServer.close,
+    };
 };

package/dist/src/server/fs-browse.d.ts

@@ -22,4 +22,17 @@ export interface FsProbeResponse {
     suggested_name: string;
 }
 export declare const browseDirectory: (requestedPath: string) => Promise<FsBrowseResponse>;
-export declare const probeDirectory: (requestedPath: string) => Promise<FsProbeResponse>;
+export interface ProbeDirectoryOptions {
+    /**
+     * When `true` (default), probe rejects paths outside `$HOME` so the
+     * in-browser FS tree can't be tricked into revealing arbitrary disk
+     * contents via a hand-crafted path string.
+     *
+     * When `false`, the sandbox check is skipped — callers who already
+     * have a user-authorized path (e.g. paths returned by the OS-native
+     * folder picker) must use this so a Windows user picking `D:\projects`
+     * isn't rejected just because their `$HOME` lives on `C:`.
+     */
+    enforceSandbox?: boolean;
+}
+export declare const probeDirectory: (requestedPath: string, options?: ProbeDirectoryOptions) => Promise<FsProbeResponse>;

package/dist/src/server/fs-browse.js

@@ -5,6 +5,29 @@ import { promisify } from 'node:util';
 import { getFsBrowseRoot, isPathWithinRoot } from './fs-sandbox.js';
 const execFileP = promisify(execFile);
 const GIT_BRANCH_TIMEOUT_MS = 800;
+/**
+ * Map a filesystem rejection (from `readdir`, `stat`, etc.) to a string
+ * suitable for surfacing in the browse response. The common Windows
+ * failure paths — System Volume Information / $Recycle.Bin (EACCES),
+ * dangling junctions (EBUSY / EINVAL), paths past MAX_PATH on systems
+ * without long-path support (ENAMETOOLONG) — each get a recognizable
+ * prefix so the UI does not just show the raw errno.
+ */
+const formatFilesystemError = (error) => {
+    if (!(error instanceof Error))
+        return 'Failed to read directory';
+    const code = error.code;
+    if (code === 'EACCES' || code === 'EPERM') {
+        return `Permission denied: ${error.message}`;
+    }
+    if (code === 'ENAMETOOLONG') {
+        return `Path is too long for this filesystem: ${error.message}`;
+    }
+    if (code === 'EBUSY' || code === 'EINVAL') {
+        return `Path is busy or unavailable: ${error.message}`;
+    }
+    return error.message;
+};
 const detectGitRepository = async (entryPath) => {
     try {
         const info = await stat(resolve(entryPath, '.git'));
@@ -49,7 +72,7 @@ export const browseDirectory = async (requestedPath) => {
         return {
             current_path: candidate,
             entries: [],
-            error: error instanceof Error ? error.message : 'Failed to stat directory',
+            error: formatFilesystemError(error),
             ok: false,
             parent_path: null,
             root_path: rootPath,
@@ -65,7 +88,24 @@ export const browseDirectory = async (requestedPath) => {
             root_path: rootPath,
         };
     }
-    const rawEntries = await readdir(candidate, { withFileTypes: true });
+    let rawEntries;
+    try {
+        rawEntries = await readdir(candidate, { withFileTypes: true });
+    }
+    catch (error) {
+        // Windows hits this for System Volume Information, $Recycle.Bin,
+        // broken junctions, and long paths on hosts without long-path
+        // support. Returning ok:false lets the picker surface a readable
+        // message instead of crashing the HTTP handler.
+        return {
+            current_path: candidate,
+            entries: [],
+            error: formatFilesystemError(error),
+            ok: false,
+            parent_path: null,
+            root_path: rootPath,
+        };
+    }
     const directoryEntries = rawEntries
         .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
         .sort((a, b) => a.name.localeCompare(b.name));
@@ -91,9 +131,12 @@ export const browseDirectory = async (requestedPath) => {
         root_path: rootPath,
     };
 };
-export const probeDirectory = async (requestedPath) => {
+export const probeDirectory = async (requestedPath, options = {}) => {
+    const enforceSandbox = options.enforceSandbox ?? true;
     const rootPath = getFsBrowseRoot();
-    const candidate = resolve(rootPath, requestedPath.trim());
+    const candidate = enforceSandbox
+        ? resolve(rootPath, requestedPath.trim())
+        : resolve(requestedPath.trim());
     const base = {
         current_branch: null,
         exists: false,
@@ -103,7 +146,7 @@ export const probeDirectory = async (requestedPath) => {
         path: candidate,
         suggested_name: candidate.split(/[\\/]/).filter(Boolean).pop() ?? '',
     };
-    if (!isPathWithinRoot(rootPath, candidate)) {
+    if (enforceSandbox && !isPathWithinRoot(rootPath, candidate)) {
         return base;
     }
     try {

package/dist/src/server/fs-pick-folder.js

@@ -5,6 +5,13 @@ import { probeDirectory } from './fs-browse.js';
 const MACOS_CANCEL_PATTERNS = [/-128/, /-1743/, /user canceled/i, /execution error/i];
 // zenity documents exit code 1 on Cancel. kdialog uses exit code 1 as well.
 const LINUX_CANCEL_EXIT_CODES = new Set([1]);
+// Cap how long we'll wait for a single picker invocation. A reasonable
+// modal-dialog dwell time is well under this — the cap exists to catch
+// genuinely wedged pickers (PowerShell startup hang under restricted
+// execution policy, zenity hung on a missing DBus, osascript blocked on
+// the macOS Accessibility prompt) so the HTTP request returns instead
+// of pinning a connection forever.
+const PICKER_TIMEOUT_MS = 5 * 60 * 1000;
 const defaultRunCommand = (command, args, options) => new Promise((resolve) => {
     const child = execFile(command, args, options, (error, stdout, stderr) => {
         const errno = error;
@@ -30,10 +37,15 @@ const emptyResponse = (overrides = {}) => ({
     ...overrides,
 });
 const finalizeWithProbe = async (path) => {
-    const probe = await probeDirectory(path);
+    // The OS-native folder picker is itself a user-authorization surface
+    // — sandboxing again here would reject any drive other than the one
+    // hosting `$HOME` (a common Windows case: `D:\projects`, `E:\code`).
+    // The in-browser FS tree (fs-browse.ts:browseDirectory) keeps its
+    // own sandbox; only the native picker bypasses it.
+    const probe = await probeDirectory(path, { enforceSandbox: false });
     if (!probe.ok || !probe.is_dir) {
         return emptyResponse({
-            error: 'Selected path is outside the Hive browse sandbox or is not a directory.',
+            error: 'Selected path is not a directory.',
             path,
             probe,
         });
@@ -42,7 +54,7 @@ const finalizeWithProbe = async (path) => {
 };
 const macOsPick = async (run) => {
     const script = 'POSIX path of (choose folder with prompt "Select Hive workspace")';
-    const result = await run('osascript', ['-e', script], {});
+    const result = await run('osascript', ['-e', script], { timeout: PICKER_TIMEOUT_MS });
     if (result.spawnError?.code === 'ENOENT') {
         return emptyResponse({ error: 'osascript is unavailable on this host.', supported: false });
     }
@@ -65,7 +77,7 @@ const macOsPick = async (run) => {
     return finalizeWithProbe(picked);
 };
 const linuxPick = async (run) => {
-    const result = await run('zenity', ['--file-selection', '--directory', '--title=Select Hive workspace'], {});
+    const result = await run('zenity', ['--file-selection', '--directory', '--title=Select Hive workspace'], { timeout: PICKER_TIMEOUT_MS });
     if (result.spawnError?.code === 'ENOENT') {
         return emptyResponse({
             error: 'zenity not installed. Install zenity or use Advanced: paste path.',
@@ -84,16 +96,47 @@ const linuxPick = async (run) => {
     return finalizeWithProbe(picked);
 };
 const windowsPick = async (run) => {
+    /* Hive's PowerShell child has no visible main window, so a bare
+       `$dialog.ShowDialog()` inherits the desktop as IWin32Window parent —
+       and ends up below the foreground browser in z-order. To the user
+       that looks like a hang ("Add Workspace pops up then nothing"); the
+       picker is open, just occluded.
+  
+       Fix: build a TopMost invisible owner Form, `Show()` it so it has a
+       real HWND (an unshown Form has none, and ShowDialog silently falls
+       back to desktop-parent), then pass the owner to `ShowDialog($owner)`.
+       The owner inherits TopMost z-order onto the dialog. The owner itself
+       stays invisible — Opacity 0, parked at (-32000, -32000), 1x1 size,
+       no taskbar entry — so the user only sees the picker. Dispose in
+       `finally` to release the HWND each invocation.
+  
+       `Add-Type -AssemblyName System.Drawing` is required because Point /
+       Size live in System.Drawing.dll, not System.Windows.Forms.dll. */
     const script = [
         'Add-Type -AssemblyName System.Windows.Forms',
-        '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
-        '$dialog.Description = "Select Hive workspace"',
-        '$dialog.ShowNewFolderButton = $false',
-        '$result = $dialog.ShowDialog()',
-        'if ($result -eq [System.Windows.Forms.DialogResult]::OK) { [Console]::Out.WriteLine($dialog.SelectedPath); exit 0 }',
-        'exit 1',
+        'Add-Type -AssemblyName System.Drawing',
+        '$owner = New-Object System.Windows.Forms.Form',
+        "$owner.FormBorderStyle = 'None'",
+        '$owner.Opacity = 0',
+        '$owner.ShowInTaskbar = $false',
+        "$owner.StartPosition = 'Manual'",
+        '$owner.Location = New-Object System.Drawing.Point(-32000, -32000)',
+        '$owner.Size = New-Object System.Drawing.Size(1, 1)',
+        '$owner.TopMost = $true',
+        '$owner.Show()',
+        'try {',
+        '  $dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
+        '  $dialog.Description = "Select Hive workspace"',
+        '  $dialog.ShowNewFolderButton = $false',
+        '  $result = $dialog.ShowDialog($owner)',
+        '  if ($result -eq [System.Windows.Forms.DialogResult]::OK) { [Console]::Out.WriteLine($dialog.SelectedPath); exit 0 }',
+        '  exit 1',
+        '} finally {',
+        '  $owner.Close()',
+        '  $owner.Dispose()',
+        '}',
     ].join('; ');
-    const result = await run('powershell.exe', ['-NoProfile', '-STA', '-ExecutionPolicy', 'Bypass', '-Command', script], {});
+    const result = await run('powershell.exe', ['-NoProfile', '-STA', '-ExecutionPolicy', 'Bypass', '-Command', script], { timeout: PICKER_TIMEOUT_MS });
     if (result.spawnError?.code === 'ENOENT') {
         return emptyResponse({
             error: 'PowerShell is unavailable on this host. Use Advanced: paste path.',

package/dist/src/server/hive-team-guidance.js

@@ -14,7 +14,7 @@
  * abstract identity restatement.
  */
 export const ORCHESTRATOR_REMINDER_TAIL = '<hive-system-reminder>\n' +
-    'You are the Hive Orchestrator. Reply by either: (a) `team send "<worker-name>" "<task>"` to dispatch follow-up work to a Hive worker, (b) `team cancel --dispatch <id> "<reason>"` to cancel an obsolete dispatch, or (c) plain text to the user. Never call your CLI\'s built-in subagent tools (Task / Explore / etc.) — they bypass Hive and will not appear in the UI.\n' +
+    'You are the Hive Orchestrator. Reply by either: (a) `team send "<worker-name>" "<task>"` to dispatch follow-up work to a Hive worker — run `team list` first when the roster may have changed since your last view (Hive does not push membership changes; stale names fail dispatch), (b) `team cancel --dispatch <id> "<reason>"` to cancel an obsolete dispatch, or (c) plain text to the user. Never call your CLI\'s built-in subagent tools (Task / Explore / etc.) — they bypass Hive and will not appear in the UI.\n' +
     '</hive-system-reminder>';
 /**
  * Tail reminder appended to dispatches sent TO a worker. Reinforces the
@@ -27,7 +27,7 @@ export const buildWorkerReminderTail = (dispatchId) => '<hive-system-reminder>\n
     '</hive-system-reminder>';
 const ORCHESTRATOR_RULES = [
     'Hive worker 是右侧卡片里的真实 CLI agent，不是你所在 CLI 的内置 subagent / 子代理工具。',
-    '当 user 要你“让 worker ... / 给 worker 找活 / 让成员处理”时，先执行 `team list` 确认真实 Hive worker。',
+    '派单前必须以最新 roster 为准：每次 `team send` 之前，如果距上一次 `team list` 之后发生过 user 回复或你自己的派单/取消，重新跑一次 `team list` 拿当前成员名单。Hive 不主动推送成员变更——别按对会话早期 roster 的记忆派单，否则容易派到已改名或已删除的 worker。',
     '普通、低风险、几分钟内能直接完成的小任务可以自己做；不要为了形式感派 worker。需要并行、长时间执行、独立 review/test、专门角色，或 user 明确要求 worker/成员处理时，再用 `team send`。',
     '如果只有一个可用 worker，直接用 `team send <worker-name> "<task>"` 派给它；不要把选择题丢回给 user。',
     '当 user 要你“让 worker ...”时，必须用 `team send <worker-name> "<task>"` 派给 Hive worker。',
@@ -58,7 +58,8 @@ export const buildProtocolDoc = () => [
     '',
     'This file is auto-generated by Hive on every workspace open. If you',
     '(the agent) lost context after `/compact` or an internal summarization,',
-    '`cat .hive/PROTOCOL.md` to re-anchor.',
+    're-read `.hive/PROTOCOL.md` (POSIX: `cat`, Windows cmd: `type`, PowerShell:',
+    '`Get-Content`) to re-anchor.',
     '',
     '## You are running inside Hive',
     '',
@@ -81,7 +82,7 @@ export const buildProtocolDoc = () => [
     '## `team` CLI — worker',
     '',
     '- `team report "<result>" --dispatch <id>` — report task outcome',
-    "- `team report --stdin --dispatch <id>` — same, body from stdin (use `<<'EOF'` heredoc for long bodies)",
+    '- `team report --stdin --dispatch <id>` — same, body from stdin (pipe content in via your shell — POSIX heredoc, `type file |`, or whatever your environment supports)',
     '- `team status "<state>"` — update orchestrator when no dispatch is active',
     '',
     '## Orchestrator rules',

package/dist/src/server/open-target-commands.js

@@ -44,18 +44,37 @@ const linuxAttempts = (targetId, path) => {
             return [{ command: 'xdg-open', args: [path] }];
     }
 };
+/**
+ * Wrap a PATHEXT-dependent shim (`code.cmd`, `cursor.cmd`, etc.) in cmd.exe
+ * so Windows resolves the `.cmd` extension. `execFile` does not consult
+ * PATHEXT and cannot launch `.cmd` files directly, so a bare `code` argv
+ * returns ENOENT even when VSCode is installed.
+ *
+ * `cmd.exe /d /s /c` parses the trailing command line. We pass the binary
+ * name and path as separate argv elements; node's child_process quotes the
+ * path when it contains whitespace, and cmd's `/s` quote-stripping does NOT
+ * fire because the command line starts with the binary name (e.g. `code`),
+ * not a `"`.
+ */
+const cmdExeShimAttempt = (bin, path) => ({
+    command: 'cmd.exe',
+    args: ['/d', '/s', '/c', bin, path],
+});
 const windowsAttempts = (targetId, path) => {
     switch (targetId) {
         case 'finder':
+            // explorer.exe is a real PE binary; the existing exit-code-1 success
+            // heuristic in classifyFailure depends on the spawn going directly to
+            // explorer, so do NOT wrap this in cmd.exe.
             return [{ command: 'explorer', args: [path] }];
         case 'vscode':
-            return [{ command: 'code', args: [path] }];
+            return [cmdExeShimAttempt('code', path)];
         case 'vscode-insiders':
-            return [{ command: 'code-insiders', args: [path] }];
+            return [cmdExeShimAttempt('code-insiders', path)];
         case 'cursor':
-            return [{ command: 'cursor', args: [path] }];
+            return [cmdExeShimAttempt('cursor', path)];
         case 'zed':
-            return [{ command: 'zed', args: [path] }];
+            return [cmdExeShimAttempt('zed', path)];
         default:
             return [{ command: 'explorer', args: [path] }];
     }
@@ -94,6 +113,13 @@ const APP_NOT_INSTALLED_PATTERNS = [
     /can'?t find/i,
     /not authorized to send keystrokes/i,
     /application can'?t be found/i,
+    // Windows: when cmd.exe can't resolve the .cmd shim (e.g. VSCode not
+    // installed), it prints this message to stderr and exits non-zero. We
+    // wrap editor invocations in `cmd /d /s /c` so the spawn itself always
+    // succeeds (cmd.exe is always present); the missing-binary signal is in
+    // the stderr text, not in spawn ENOENT.
+    /is not recognized as an internal or external command/i,
+    /不是内部或外部命令/, // zh-CN Windows localization of the above
 ];
 const classifyFailure = (result) => {
     if (result.spawnError?.code === 'ENOENT')

package/dist/src/server/post-start-input-writer.js

@@ -1,4 +1,4 @@
-import { basename } from 'node:path';
+import { normalizeExecutableToken } from './startup-command-parser.js';
 const INTERACTIVE_COMMANDS = new Set(['claude', 'codex', 'gemini', 'opencode']);
 const READY_CHECK_INTERVAL_MS = 50;
 const READY_TIMEOUT_MS = 3000;
@@ -11,8 +11,11 @@ const PASTE_ACK_TIMEOUT_MS = 3000;
 const COMMANDS_WITH_BRACKETED_PASTE = new Set(['claude', 'codex', 'opencode']);
 export const toBracketedPasteSubmission = (text) => `\u001b[200~${text}\u001b[201~`;
 const getSubmitAfterPasteDelayMs = (text) => Math.min(MAX_SUBMIT_AFTER_PASTE_DELAY_MS, Math.max(MIN_SUBMIT_AFTER_PASTE_DELAY_MS, Math.ceil(text.length / PASTE_CHARS_PER_DELAY_MS)));
-export const isInteractiveAgentCommand = (command) => INTERACTIVE_COMMANDS.has(basename(command).toLowerCase());
-const getCommandName = (command) => basename(command).toLowerCase();
+export const isInteractiveAgentCommand = (command) => {
+    const brand = normalizeExecutableToken(command);
+    return brand !== null && INTERACTIVE_COMMANDS.has(brand);
+};
+const getCommandName = (command) => normalizeExecutableToken(command) ?? '';
 const hasGeminiPromptReady = (output) => /\bType your message\b/u.test(output);
 export const hasInteractivePromptReady = (output, command = '') => {
     const commandName = getCommandName(command);

package/dist/src/server/routes-team.js

@@ -27,7 +27,16 @@ export const teamRoutes = [
             fromAgentId,
             hivePort: String(request.socket.localPort ?? ''),
         });
-        sendJson(response, 202, { dispatch_id: dispatch.id, ok: true });
+        /* `restarted_worker` makes the silent auto-wake transparent — when
+           the worker had no active run at dispatch time, ensureWorkerRun
+           spawned a fresh PTY for it. The orchestrator's CLI prints a
+           stderr notice on this flag so the agent can explain the wake-up
+           to the user instead of being out of sync with worker state. */
+        sendJson(response, 202, {
+            dispatch_id: dispatch.id,
+            ok: true,
+            restarted_worker: dispatch.restartedWorker,
+        });
     }),
     route('POST', '/api/team/cancel', async ({ request, response, store }) => {
         const body = await readJsonBody(request);

package/dist/src/server/runtime-store.d.ts

@@ -19,7 +19,9 @@ interface RuntimeStore {
     renameWorker: (workspaceId: string, workerId: string, name: string) => AgentSummary;
     recordUserInput: (workspaceId: string, orchestratorId: string, text: string) => void;
     dispatchTask: (workspaceId: string, workerId: string, text: string, input?: DispatchTaskInput) => Promise<DispatchRecord>;
-    dispatchTaskByWorkerName: (workspaceId: string, workerName: string, text: string, input?: DispatchTaskInput) => Promise<DispatchRecord>;
+    dispatchTaskByWorkerName: (workspaceId: string, workerName: string, text: string, input?: DispatchTaskInput) => Promise<DispatchRecord & {
+        restartedWorker: boolean;
+    }>;
     reportTask: (workspaceId: string, workerId: string, input?: ReportTaskInput) => ReportTaskResult;
     statusTask: (workspaceId: string, workerId: string, input?: StatusTaskInput) => ReportTaskResult;
     cancelTask: (workspaceId: string, dispatchId: string, input: CancelTaskInput) => ReportTaskResult;

package/dist/src/server/session-capture-claude.d.ts

@@ -1,4 +1,27 @@
 export declare const getClaudeProjectsRoot: (pattern?: string) => string;
+/**
+ * Match the directory-name encoding Claude Code itself uses for its project
+ * metadata under `~/.claude/projects/`. Empirically (probed via `claude
+ * --print "x"` in directories named with each character) Claude Code
+ * replaces *every* character outside `[A-Za-z0-9-]` with a single `-`,
+ * one-for-one, preserving literal hyphens.
+ *
+ * The previous regex `[\\/:\s]` only matched `\`, `/`, `:`, and whitespace —
+ * leaving `_`, `.`, parens, brackets, `@`, `#`, `&`, `+`, and any non-ASCII
+ * character (including CJK usernames) intact, while Claude Code's own
+ * encoder replaced them. The mismatch meant Hive looked for sessions under
+ * a different directory than the one Claude Code wrote to, so session
+ * resume silently failed for any workspace path containing those chars.
+ * Windows + CJK Windows usernames (`C:\Users\张三\project`) and
+ * underscored Windows project paths (`C:\my_project`) are the most common
+ * triggers, but the bug is cross-platform.
+ *
+ * Backward compatibility: workspaces whose path contains ONLY chars that
+ * the old regex already matched (`/\:` + whitespace) get the same encoded
+ * dirname as before — no behavior change. Workspaces with any other
+ * special chars previously had broken session resume; the fix moves them
+ * to the correct (working) directory.
+ */
 export declare const encodeClaudeProjectPath: (cwd: string) => string;
 interface ClaudeSessionCaptureDiscriminator {
     contentIncludes?: string | readonly string[];

package/dist/src/server/session-capture-claude.js

@@ -18,7 +18,30 @@ export const getClaudeProjectsRoot = (pattern) => {
     }
     return root;
 };
-export const encodeClaudeProjectPath = (cwd) => cwd.replace(/[\\/:\s]/g, '-');
+/**
+ * Match the directory-name encoding Claude Code itself uses for its project
+ * metadata under `~/.claude/projects/`. Empirically (probed via `claude
+ * --print "x"` in directories named with each character) Claude Code
+ * replaces *every* character outside `[A-Za-z0-9-]` with a single `-`,
+ * one-for-one, preserving literal hyphens.
+ *
+ * The previous regex `[\\/:\s]` only matched `\`, `/`, `:`, and whitespace —
+ * leaving `_`, `.`, parens, brackets, `@`, `#`, `&`, `+`, and any non-ASCII
+ * character (including CJK usernames) intact, while Claude Code's own
+ * encoder replaced them. The mismatch meant Hive looked for sessions under
+ * a different directory than the one Claude Code wrote to, so session
+ * resume silently failed for any workspace path containing those chars.
+ * Windows + CJK Windows usernames (`C:\Users\张三\project`) and
+ * underscored Windows project paths (`C:\my_project`) are the most common
+ * triggers, but the bug is cross-platform.
+ *
+ * Backward compatibility: workspaces whose path contains ONLY chars that
+ * the old regex already matched (`/\:` + whitespace) get the same encoded
+ * dirname as before — no behavior change. Workspaces with any other
+ * special chars previously had broken session resume; the fix moves them
+ * to the correct (working) directory.
+ */
+export const encodeClaudeProjectPath = (cwd) => cwd.replace(/[^A-Za-z0-9-]/g, '-');
 const listSessionIds = (cwd, projectsRoot = getDefaultProjectsRoot()) => {
     const projectDir = join(projectsRoot, encodeClaudeProjectPath(cwd));
     try {