@tt-a1i/hive 1.1.5 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,107 @@
 
 All notable user-facing changes will be documented in this file.
 
+## 1.3.0 - 2026-05-20
+
+Installable Hive: turns the web shell into a real PWA so Chrome / Edge can
+launch it from a dock icon, in its own window, without a visible browser
+chrome.
+
+- Adds a web app manifest with icons (192, 512, maskable 512, apple-touch 180),
+  a wide screenshot, and shortcuts for "Add Workspace" and "Try Demo" so
+  right-clicking the dock icon jumps straight to those flows.
+- Installation is driven entirely by the browser's omnibox install icon
+  (Chrome / Edge / Brave); Hive deliberately does not add a redundant topbar
+  button.
+- Ships a service worker (`/sw.js`) that caches the SPA shell + hashed asset
+  chunks + static icons / sounds / cli-icons, but never intercepts `/api/*`,
+  `/ws/*`, or non-GET requests — auth cookies and WebSockets keep their
+  native paths. Each release writes to its own cache bucket and older buckets
+  are kept so tabs still controlled by the previous SW can resolve their
+  lazy-imported chunks.
+- Surfaces shell updates as a bottom-right toast (`Web UI updated — Reload to
+  activate`) instead of forcing a refresh. The Reload button stays disabled
+  while any terminal run is still working so updates never interrupt an
+  in-flight agent.
+- Routes service-worker auto-reloads through the same silent reload helper used
+  elsewhere in the app, so browser updates do not trip the close-confirmation
+  guard.
+- Replaces the workspace area with a dedicated `Hive runtime is not running`
+  page when the initial bootstrap fails. The page pings `/api/version` every
+  three seconds and reloads automatically once the daemon comes back; a manual
+  Retry button is offered alongside.
+- Hardens the server: `/sw.js` is served with `Cache-Control: no-store` and the
+  manifest with `Cache-Control: max-age=0, must-revalidate`, so SW updates
+  propagate the next time the browser checks instead of waiting on a stale
+  HTTP cache.
+- Notes for first-time installers: the SW activates after the first reload
+  following install. On separate ports (`hive --port 4011` vs `--port 3000`)
+  Chrome treats Hive as two distinct PWAs because the install scope is keyed
+  by origin. To fully remove a PWA install, use
+  `chrome://apps` → right-click the Hive tile → Remove.
+- Always asks the browser to confirm before closing the tab or PWA window so
+  Cmd-W on an installed app never closes silently. Modern browsers gate the
+  prompt on prior page interaction — opening the window and immediately
+  pressing Cmd-W still closes cleanly by browser policy.
+- Open Workspace dropdown now uses each app's brand color for its icon
+  instead of the previous monochrome white treatment, and visually separates
+  VS Code from VS Code Insiders so users can tell their installed targets
+  apart at a glance.
+- Workspace avatars in the sidebar stay the same size when the user drags
+  the sidebar wider. Previously the wide layout used a 22px avatar while the
+  collapsed layout used 32px, so expanding the sidebar made the avatars
+  smaller; both modes now render at 32px.
+- Drops IntelliJ IDEA, Windsurf, and iTerm2 from the Open Workspace dropdown.
+  IntelliJ users typically launch from JetBrains Toolbox rather than a folder
+  picker; Windsurf overlaps with the existing Cursor / VS Code entries;
+  iTerm2 overlaps with the built-in macOS Terminal entry. macOS now exposes
+  seven targets (VS Code, VS Code Insiders, Cursor, Finder, Terminal,
+  Ghostty, Zed); Windows / Linux expose five (VS Code, VS Code Insiders,
+  Cursor, File Explorer / File Manager, Zed). A stored preference for any
+  removed target silently falls back to the platform default at load time.
+- Swaps the Zed, Ghostty, and Finder dropdown icons for the apps' official
+  brand marks (Finder uses the macOS app icon, Ghostty 96×96 / Zed 64×64
+  raster) so each entry reads as the real application rather than an
+  abstract glyph. Ghostty's mark renders inside a generous safe-zone so its
+  display size is bumped 20% via CSS scale to balance the row visually.
+- Replaces the Worker detail modal and Workspace shell dialog with a docked,
+  resizable, VSCode-style terminal panel inside the right column (under the
+  team members pane). Worker tabs and shell tabs share the strip; clicking a
+  member card opens that worker as a tab; the panel hides when no tabs are
+  open. Closing a worker tab keeps the underlying PTY running — worker
+  lifecycle is owned by the card hover cluster. Tab list, active tab, and
+  panel height all persist (height globally, tabs + active per-workspace).
+  Cmd-W (Ctrl-W on Windows / Linux) closes the active tab; a "+" button in
+  the tab strip starts a new shell. Start failures and shell-start failures
+  now surface as toasts instead of inline modal/dialog banners.
+- Moves "Save as template" into the role-instructions toolbar in the Add Member
+  flow, keeping template actions closer to the prompt editor instead of adding
+  another standalone control in the dialog body.
+
+## 1.2.0 - 2026-05-18
+
+Opens the active workspace in your editor, terminal, or file manager from
+Hive's topbar.
+
+- Adds an "Open" split button to the topbar that launches the active workspace
+  in a chosen application. Ten targets on macOS (VS Code, VS Code Insiders,
+  Cursor, Windsurf, Finder, Terminal, iTerm2, Ghostty, IntelliJ IDEA, Zed) and
+  six on Windows / Linux (VS Code, VS Code Insiders, Cursor, Windsurf, File
+  Explorer / File Manager, Zed).
+- Persists the preferred target per browser via `localStorage` so the next
+  click jumps to the same app. Stale preferences for apps that aren't valid on
+  the current platform fall back to the OS file manager instead of erroring.
+- Surfaces failures as localized toast notifications. Distinguishes
+  "app not installed", "launcher not on PATH", and other failure modes so a
+  missing Cursor install reads differently from a misconfigured `code` CLI.
+- Backend launches each command via `execFile` with an argv array — no shell
+  is involved, so workspace paths containing spaces, Unicode, or quotes pass
+  through verbatim. Paths containing newlines or NUL bytes are rejected before
+  dispatch.
+- Special-cases Windows `explorer.exe`, which returns exit code 1 even on
+  success: spawn-errors are still surfaced, but a non-zero exit no longer
+  shows a spurious toast.
+
 ## 1.1.5 - 2026-05-18
 
 Custom startup command and close-guard fixes.

package/README.en.md

@@ -71,6 +71,39 @@ hive
 Open the printed local URL, usually `http://127.0.0.1:3000/`. Use
 `hive --port 4010` when you need a specific local port.
 
+To upgrade in place:
+
+```bash
+hive update
+```
+
+`hive update` runs `npm install -g @tt-a1i/hive@latest` in place. Restart any
+in-flight Hive process to pick up the new version. If you installed Hive with
+pnpm or yarn, upgrade through the same package manager — otherwise the new
+npm copy will shadow your existing install.
+
+Install Hive as an app (optional):
+
+Open `http://127.0.0.1:3000/` in Chrome, Edge, or Brave and click the install
+icon at the right edge of the browser's omnibox. The PWA launches in its own
+dock-anchored window without browser chrome and shows **Add Workspace** /
+**Try Demo** shortcuts from the dock right-click menu. Firefox and Safari
+currently don't implement the install-prompt protocol, so the omnibox icon
+only appears in Chromium-based browsers.
+
+The Hive daemon must still be running for the PWA to do anything; if the
+runtime isn't reachable when you launch the app, you'll see a "Hive runtime
+is not running" page that auto-reloads once `hive` is back on `127.0.0.1`.
+The PWA install scope is keyed by origin, so `hive --port 4011` installs as
+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.
+
 First-run flow:
 
 1. Create a workspace from a project folder.

package/README.md

@@ -52,6 +52,22 @@ hive
 
 打开终端打印出来的本机地址，通常是 `http://127.0.0.1:3000/`。如果你想指定端口，可以用 `hive --port 4010`。
 
+升级到最新版本：
+
+```bash
+hive update
+```
+
+`hive update` 会在原位运行 `npm install -g @tt-a1i/hive@latest`，完事后重启 Hive 就能用上新版。如果当初是用 pnpm / yarn 装的 Hive，请用同一个包管理器升级，避免装出第二份。
+
+把 Hive 装为应用（可选）：
+
+在 Chrome / Edge / Brave 里打开 `http://127.0.0.1:3000/`，点浏览器地址栏右侧的安装图标即可。装好后 Hive 会以独立窗口启动、有自己的 dock 图标，且 dock 右键菜单上会显示 **添加 Workspace** / **试用演示** 两个快捷入口。Firefox 和 Safari 暂未实现 PWA install-prompt 协议，浏览器地址栏的安装图标只在 Chromium 系浏览器里出现。
+
+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。
+
 首次使用流程：
 
 1. 选择一个项目目录作为 workspace。

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

@@ -0,0 +1,15 @@
+export declare const HIVE_UPDATE_USAGE: string;
+export interface RunUpdateResult {
+    exitCode: number;
+    spawnError?: Error;
+}
+export type RunUpdate = (command: string, args: readonly string[]) => Promise<RunUpdateResult>;
+export declare const defaultRunUpdate: RunUpdate;
+interface RunHiveUpdateOptions {
+    /** Inject a fake spawn for tests. */
+    runUpdate?: RunUpdate;
+    /** Override platform detection for tests. */
+    platform?: NodeJS.Platform;
+}
+export declare const runHiveUpdateCommand: (argv: string[], options?: RunHiveUpdateOptions) => Promise<number>;
+export {};

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

@@ -0,0 +1,81 @@
+import { spawn } from 'node:child_process';
+import { getNpmCommand, INSTALL_COMMAND_ARGS, INSTALL_COMMAND_DISPLAY, } from '../server/package-version.js';
+export const HIVE_UPDATE_USAGE = [
+    'Usage:',
+    '  hive update',
+    '',
+    `Runs \`${INSTALL_COMMAND_DISPLAY}\` to upgrade Hive in place.`,
+    'Restart any running Hive process afterwards to pick up the new version.',
+    '',
+    'Note: only npm-installed Hive can be upgraded this way. If you installed',
+    'Hive via pnpm or yarn, upgrade through the same package manager instead;',
+    'otherwise the npm copy will shadow your existing install.',
+    '',
+    'Options:',
+    '  -h, --help      Print this help.',
+].join('\n');
+export const defaultRunUpdate = (command, args) => new Promise((resolve) => {
+    const child = spawn(command, [...args], { stdio: 'inherit' });
+    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);
+    const finalize = (result) => {
+        if (resolved)
+            return;
+        resolved = true;
+        process.off('SIGINT', handleSigint);
+        process.off('SIGTERM', handleSigterm);
+        resolve(result);
+    };
+    child.on('error', (error) => {
+        finalize({ exitCode: 1, spawnError: error });
+    });
+    child.on('close', (code) => {
+        finalize({ exitCode: typeof code === 'number' ? code : 1 });
+    });
+});
+const printManualFallback = () => {
+    console.error(`You can run the upgrade manually: ${INSTALL_COMMAND_DISPLAY}`);
+};
+export const runHiveUpdateCommand = async (argv, options = {}) => {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        console.log(HIVE_UPDATE_USAGE);
+        return 0;
+    }
+    // Reject unknown flags rather than silently ignoring them — keeps behavior
+    // consistent with how `parsePort` validates `hive` itself.
+    const extra = argv.find((arg) => arg !== '--help' && arg !== '-h');
+    if (extra !== undefined) {
+        console.error(`Unknown argument: ${extra}`);
+        console.error(HIVE_UPDATE_USAGE);
+        return 1;
+    }
+    const run = options.runUpdate ?? defaultRunUpdate;
+    const command = getNpmCommand(options.platform);
+    console.log(`Running: ${INSTALL_COMMAND_DISPLAY}`);
+    const result = await run(command, INSTALL_COMMAND_ARGS);
+    if (result.spawnError) {
+        console.error(`Failed to spawn npm: ${result.spawnError.message}`);
+        printManualFallback();
+        return 1;
+    }
+    if (result.exitCode === 0) {
+        console.log('Hive updated. Restart any running Hive process to pick up the new version.');
+        return 0;
+    }
+    console.error(`npm install exited with code ${result.exitCode}.`);
+    // Permission failures (EACCES on root-owned /usr/bin/npm) and other
+    // non-spawn errors leave the user with copy-paste recovery either way.
+    printManualFallback();
+    return result.exitCode;
+};

package/dist/src/cli/hive.js

@@ -9,14 +9,19 @@ import { createApp } from '../server/app.js';
 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';
 export const HIVE_USAGE = [
     'Usage:',
     '  hive [--port <port>]',
+    '  hive update',
     '',
     'Options:',
     '  --port <port>   Bind the local runtime to a specific port (default: 3000).',
     '  -h, --help      Print this help.',
     '  -v, --version   Print the installed Hive version.',
+    '',
+    'Commands:',
+    '  update          Upgrade Hive in place via `npm install -g`.',
 ].join('\n');
 export const handleHiveInfoCommand = (argv) => {
     if (argv.includes('--help') || argv.includes('-h')) {
@@ -128,10 +133,21 @@ const isMainModule = process.argv[1]
     : false;
 if (isMainModule) {
     const argv = process.argv.slice(2);
-    if (handleHiveInfoCommand(argv))
+    if (argv[0] === 'update') {
+        runHiveUpdateCommand(argv.slice(1))
+            .then((code) => process.exit(code))
+            .catch((error) => {
+            console.error(error);
+            process.exit(1);
+        });
+    }
+    else if (handleHiveInfoCommand(argv)) {
         process.exit(0);
-    runHiveCommand(argv).catch((error) => {
-        console.error(error);
-        process.exit(1);
-    });
+    }
+    else {
+        runHiveCommand(argv).catch((error) => {
+            console.error(error);
+            process.exit(1);
+        });
+    }
 }

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

@@ -27,7 +27,7 @@ export declare const createAgentRunStore: (db: Database) => {
         runId: string;
         agentId: string;
         pid: number | null;
-        status: "starting" | "running" | "exited" | "error";
+        status: "error" | "starting" | "running" | "exited";
         exitCode: number | null;
         startedAt: number;
         endedAt: number | null;

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

@@ -1,15 +1,17 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import { type PickFolderResponse } from './fs-pick-folder.js';
+import type { OpenWorkspaceService } from './route-types.js';
 import type { RuntimeStore } from './runtime-store.js';
 import { type TasksFileService } from './tasks-file.js';
 import { type VersionService } from './version-service.js';
 interface CreateAppOptions {
     store: RuntimeStore;
     pickFolderService?: () => Promise<PickFolderResponse>;
+    openWorkspaceService?: OpenWorkspaceService;
     tasksFileService?: TasksFileService;
     versionService?: VersionService;
 }
-export declare const createApp: ({ store, pickFolderService, tasksFileService, versionService, }: CreateAppOptions) => {
+export declare const createApp: ({ store, pickFolderService, openWorkspaceService, tasksFileService, versionService, }: CreateAppOptions) => {
     server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
     store: RuntimeStore;
 };

package/dist/src/server/app.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { pickFolder } from './fs-pick-folder.js';
 import { HttpError } from './http-errors.js';
 import { assertLocalRequest } from './local-request-guard.js';
+import { openWorkspace } from './open-target-commands.js';
 import { matchRoute } from './routes.js';
 import { createTasksFileService } from './tasks-file.js';
 import { createTerminalWebSocketServer } from './terminal-ws-server.js';
@@ -53,6 +54,14 @@ const CONTENT_TYPES = {
     '.webp': 'image/webp',
     '.woff2': 'font/woff2',
 };
+// PWA boot files must bypass HTTP caching: `sw.js` because the browser does its
+// own byte-diff update check, and the manifest because Chrome consults it on
+// every install/uninstall transition. Without these, SW updates can stall on a
+// stale cached copy and the install prompt won't reflect a renamed app.
+const PWA_BOOT_CACHE_CONTROL = {
+    '/manifest.webmanifest': 'max-age=0, must-revalidate',
+    '/sw.js': 'no-store',
+};
 const sendStatic = async (response, staticDir, pathname, request) => {
     if (request.method !== 'GET' && request.method !== 'HEAD')
         return false;
@@ -62,6 +71,9 @@ const sendStatic = async (response, staticDir, pathname, request) => {
     try {
         const content = await readFile(filePath);
         response.setHeader('content-type', CONTENT_TYPES[extname(filePath)] ?? 'application/octet-stream');
+        const cacheControl = PWA_BOOT_CACHE_CONTROL[pathname];
+        if (cacheControl !== undefined)
+            response.setHeader('cache-control', cacheControl);
         response.statusCode = 200;
         response.end(request.method === 'HEAD' ? undefined : content);
         return true;
@@ -75,7 +87,7 @@ const sendJson = (response, statusCode, body) => {
     response.setHeader('content-type', 'application/json; charset=utf-8');
     response.end(JSON.stringify(body));
 };
-export const createApp = ({ store, pickFolderService = pickFolder, tasksFileService = createTasksFileService(), versionService = createVersionService(), }) => {
+export const createApp = ({ store, pickFolderService = pickFolder, openWorkspaceService = (input) => openWorkspace(input), tasksFileService = createTasksFileService(), versionService = createVersionService(), }) => {
     const staticDir = process.env.HIVE_STATIC_DIR ?? getDefaultStaticDir();
     const staticAvailablePromise = canServeStatic(staticDir);
     const server = createServer(async (request, response) => {
@@ -91,6 +103,7 @@ export const createApp = ({ store, pickFolderService = pickFolder, tasksFileServ
                     store,
                     tasksFileService,
                     pickFolderService,
+                    openWorkspaceService,
                     versionService,
                     params: match.params,
                 });

package/dist/src/server/open-target-commands.d.ts

@@ -0,0 +1,53 @@
+import { type ExecFileOptions } from 'node:child_process';
+import { type OpenTargetId, type OpenTargetPlatform, type OpenWorkspaceErrorCode } from '../shared/open-targets.js';
+export type { OpenTargetId, OpenTargetPlatform, OpenWorkspaceErrorCode, } from '../shared/open-targets.js';
+export { getEffectiveOpenTargetId, isOpenTargetId, isOpenTargetSupported, OPEN_TARGET_IDS_BY_PLATFORM, } from '../shared/open-targets.js';
+export declare const resolveOpenTargetPlatform: (platform: NodeJS.Platform) => OpenTargetPlatform;
+export interface OpenAttempt {
+    command: string;
+    args: string[];
+}
+/**
+ * Returns the ordered list of commands to try. First success wins; remaining
+ * entries are fallbacks (e.g. IntelliJ IDEA → IntelliJ IDEA CE on older Macs).
+ * Empty list means the requested target is unsupported on this platform —
+ * callers should have already routed through `getEffectiveOpenTargetId` to
+ * fall back, so this should never happen in practice.
+ */
+export declare const buildOpenAttempts: (targetId: OpenTargetId, path: string, platform: OpenTargetPlatform) => OpenAttempt[];
+export interface OpenCommandSuccess {
+    ok: true;
+    effectiveTargetId: OpenTargetId;
+}
+export interface OpenCommandFailure {
+    ok: false;
+    effectiveTargetId: OpenTargetId;
+    errorCode: OpenWorkspaceErrorCode;
+    stderr: string;
+}
+export type OpenCommandResult = OpenCommandSuccess | OpenCommandFailure;
+interface SpawnResult {
+    stderr: string;
+    stdout: string;
+    status: number | null;
+    signal: string | null;
+    spawnError: NodeJS.ErrnoException | null;
+}
+export type RunOpenCommand = (command: string, args: string[], options: ExecFileOptions) => Promise<SpawnResult>;
+export interface OpenWorkspaceInput {
+    path: string;
+    targetId: OpenTargetId;
+}
+export interface OpenWorkspaceOptions {
+    platform?: NodeJS.Platform;
+    runCommand?: RunOpenCommand;
+}
+/**
+ * Workspace paths originate from the OS folder picker or from manual paste;
+ * the picker output is sandbox-validated at create time, but a path stored
+ * before path-validation existed (or one pasted into a hypothetical migration
+ * future) could contain `\n` / `\0`. Reject those here so we never hand an
+ * ambiguous path to `xdg-open`, where shell wrappers split on newline.
+ */
+export declare const isOpenWorkspacePathSafe: (path: string) => boolean;
+export declare const openWorkspace: (input: OpenWorkspaceInput, options?: OpenWorkspaceOptions) => Promise<OpenCommandResult>;

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

@@ -0,0 +1,176 @@
+import { execFile } from 'node:child_process';
+import { getDefaultOpenTargetIdForPlatform, getEffectiveOpenTargetId, isOpenTargetId, } from '../shared/open-targets.js';
+export { getEffectiveOpenTargetId, isOpenTargetId, isOpenTargetSupported, OPEN_TARGET_IDS_BY_PLATFORM, } from '../shared/open-targets.js';
+export const resolveOpenTargetPlatform = (platform) => {
+    if (platform === 'darwin')
+        return 'mac';
+    if (platform === 'win32')
+        return 'windows';
+    if (platform === 'linux')
+        return 'linux';
+    return 'other';
+};
+const macAttempts = (targetId, path) => {
+    switch (targetId) {
+        case 'finder':
+            return [{ command: 'open', args: [path] }];
+        case 'vscode':
+            return [{ command: 'open', args: ['-a', 'Visual Studio Code', path] }];
+        case 'vscode-insiders':
+            return [{ command: 'open', args: ['-a', 'Visual Studio Code - Insiders', path] }];
+        case 'cursor':
+            return [{ command: 'open', args: ['-a', 'Cursor', path] }];
+        case 'terminal':
+            return [{ command: 'open', args: ['-a', 'Terminal', path] }];
+        case 'ghostty':
+            return [{ command: 'open', args: ['-a', 'Ghostty', path] }];
+        case 'zed':
+            return [{ command: 'open', args: ['-a', 'Zed', path] }];
+    }
+};
+const linuxAttempts = (targetId, path) => {
+    switch (targetId) {
+        case 'finder':
+            return [{ command: 'xdg-open', args: [path] }];
+        case 'vscode':
+            return [{ command: 'code', args: [path] }];
+        case 'vscode-insiders':
+            return [{ command: 'code-insiders', args: [path] }];
+        case 'cursor':
+            return [{ command: 'cursor', args: [path] }];
+        case 'zed':
+            return [{ command: 'zed', args: [path] }];
+        default:
+            return [{ command: 'xdg-open', args: [path] }];
+    }
+};
+const windowsAttempts = (targetId, path) => {
+    switch (targetId) {
+        case 'finder':
+            return [{ command: 'explorer', args: [path] }];
+        case 'vscode':
+            return [{ command: 'code', args: [path] }];
+        case 'vscode-insiders':
+            return [{ command: 'code-insiders', args: [path] }];
+        case 'cursor':
+            return [{ command: 'cursor', args: [path] }];
+        case 'zed':
+            return [{ command: 'zed', args: [path] }];
+        default:
+            return [{ command: 'explorer', args: [path] }];
+    }
+};
+/**
+ * Returns the ordered list of commands to try. First success wins; remaining
+ * entries are fallbacks (e.g. IntelliJ IDEA → IntelliJ IDEA CE on older Macs).
+ * Empty list means the requested target is unsupported on this platform —
+ * callers should have already routed through `getEffectiveOpenTargetId` to
+ * fall back, so this should never happen in practice.
+ */
+export const buildOpenAttempts = (targetId, path, platform) => {
+    const effectiveTargetId = getEffectiveOpenTargetId(targetId, platform);
+    if (platform === 'mac')
+        return macAttempts(effectiveTargetId, path);
+    if (platform === 'linux')
+        return linuxAttempts(effectiveTargetId, path);
+    if (platform === 'windows')
+        return windowsAttempts(effectiveTargetId, path);
+    return [{ command: 'open', args: [path] }];
+};
+const defaultRunOpenCommand = (command, args, options) => new Promise((resolve) => {
+    const child = execFile(command, args, options, (error, stdout, stderr) => {
+        const errno = error;
+        resolve({
+            stderr: String(stderr ?? ''),
+            stdout: String(stdout ?? ''),
+            status: typeof errno?.code === 'number' ? errno.code : (child.exitCode ?? 0),
+            signal: typeof errno?.signal === 'string' ? errno.signal : null,
+            spawnError: errno && typeof errno.code === 'string' ? errno : null,
+        });
+    });
+});
+const APP_NOT_INSTALLED_PATTERNS = [
+    /unable to find application/i,
+    /can'?t find/i,
+    /not authorized to send keystrokes/i,
+    /application can'?t be found/i,
+];
+const classifyFailure = (result) => {
+    if (result.spawnError?.code === 'ENOENT')
+        return 'command-not-in-path';
+    const stderr = result.stderr.toLowerCase();
+    if (APP_NOT_INSTALLED_PATTERNS.some((re) => re.test(stderr)))
+        return 'app-not-installed';
+    return 'unknown';
+};
+/**
+ * Workspace paths originate from the OS folder picker or from manual paste;
+ * the picker output is sandbox-validated at create time, but a path stored
+ * before path-validation existed (or one pasted into a hypothetical migration
+ * future) could contain `\n` / `\0`. Reject those here so we never hand an
+ * ambiguous path to `xdg-open`, where shell wrappers split on newline.
+ */
+export const isOpenWorkspacePathSafe = (path) => {
+    if (path.length === 0)
+        return false;
+    for (let i = 0; i < path.length; i++) {
+        const code = path.charCodeAt(i);
+        if (code === 0 || code === 10 || code === 13)
+            return false;
+    }
+    return true;
+};
+export const openWorkspace = async (input, options = {}) => {
+    const platform = resolveOpenTargetPlatform(options.platform ?? process.platform);
+    const run = options.runCommand ?? defaultRunOpenCommand;
+    if (!isOpenTargetId(input.targetId)) {
+        return {
+            ok: false,
+            effectiveTargetId: getDefaultOpenTargetIdForPlatform(platform),
+            errorCode: 'invalid-target',
+            stderr: `Unknown open target: ${String(input.targetId)}`,
+        };
+    }
+    if (!isOpenWorkspacePathSafe(input.path)) {
+        return {
+            ok: false,
+            effectiveTargetId: input.targetId,
+            errorCode: 'invalid-path',
+            stderr: 'Workspace path contains newline or null byte and was rejected.',
+        };
+    }
+    const effectiveTargetId = getEffectiveOpenTargetId(input.targetId, platform);
+    const attempts = buildOpenAttempts(input.targetId, input.path, platform);
+    let lastFailure = null;
+    for (const attempt of attempts) {
+        const result = await run(attempt.command, attempt.args, {});
+        // Windows `explorer.exe` returns exit code 1 even on success — checking
+        // exit code here would surface a spurious error to the user on every
+        // File Explorer open. spawnError still catches the "explorer not on PATH"
+        // case, which is the only real failure mode worth surfacing.
+        if (attempt.command === 'explorer') {
+            if (result.spawnError?.code === 'ENOENT') {
+                lastFailure = result;
+                continue;
+            }
+            return { ok: true, effectiveTargetId };
+        }
+        if (!result.spawnError && (result.status === 0 || result.status === null)) {
+            return { ok: true, effectiveTargetId };
+        }
+        lastFailure = result;
+    }
+    const fallback = lastFailure ?? {
+        stderr: 'No command attempts were made.',
+        stdout: '',
+        status: null,
+        signal: null,
+        spawnError: null,
+    };
+    return {
+        ok: false,
+        effectiveTargetId,
+        errorCode: classifyFailure(fallback),
+        stderr: fallback.stderr.trim() || fallback.stdout.trim() || 'Failed to open workspace.',
+    };
+};

package/dist/src/server/package-version.d.ts

@@ -1,2 +1,17 @@
 export declare const PACKAGE_NAME = "@tt-a1i/hive";
+/**
+ * Canonical argv for the upgrade command. Sharing one source between the
+ * server's install hint (`version-service.ts`) and the CLI upgrade path
+ * (`hive-update.ts`) keeps the two from drifting if the package name ever
+ * moves.
+ */
+export declare const INSTALL_COMMAND_ARGS: readonly ["install", "-g", "@tt-a1i/hive@latest"];
+export declare const INSTALL_COMMAND_DISPLAY: string;
+/**
+ * Windows ships npm as `npm.cmd` (a batch shim); Node's `child_process.spawn`
+ * will not resolve `.cmd` without `shell: true` or an explicit suffix, so the
+ * default `'npm'` produces ENOENT on Windows. Use this helper any time you
+ * spawn npm directly.
+ */
+export declare const getNpmCommand: (platform?: NodeJS.Platform) => string;
 export declare const readPackageVersion: () => string;