hivehq 2.0.0

package/dist/src/server/live-run-registry.js

@@ -0,0 +1,52 @@
+export const createLiveRunRegistry = () => {
+    const liveRuns = new Map();
+    const pendingExitCodes = new Map();
+    const runExitPromises = new Map();
+    return {
+        add(run) {
+            liveRuns.set(run.runId, run);
+        },
+        createExitEntry(runId) {
+            let resolve = () => { };
+            const promise = new Promise((nextResolve) => {
+                resolve = nextResolve;
+            });
+            runExitPromises.set(runId, { promise, resolve, runId });
+        },
+        deleteExitEntry(runId) {
+            runExitPromises.delete(runId);
+        },
+        clearPendingExitCode(runId) {
+            pendingExitCodes.delete(runId);
+        },
+        get(runId) {
+            return liveRuns.get(runId);
+        },
+        getExitEntry(runId) {
+            return runExitPromises.get(runId);
+        },
+        getPendingExitCode(runId) {
+            return pendingExitCodes.get(runId);
+        },
+        hasPendingExitCode(runId) {
+            return pendingExitCodes.has(runId);
+        },
+        list() {
+            return Array.from(liveRuns.values());
+        },
+        listExitEntries() {
+            return Array.from(runExitPromises.values());
+        },
+        remove(runId) {
+            liveRuns.delete(runId);
+            pendingExitCodes.delete(runId);
+            runExitPromises.delete(runId);
+        },
+        resolveExit(runId) {
+            runExitPromises.get(runId)?.resolve();
+        },
+        setPendingExitCode(runId, exitCode) {
+            pendingExitCodes.set(runId, exitCode);
+        },
+    };
+};

package/dist/src/server/local-request-guard.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage } from 'node:http';
+export declare const getLocalRequestRejection: (request: IncomingMessage) => string | null;
+export declare const assertLocalRequest: (request: IncomingMessage) => void;

package/dist/src/server/local-request-guard.js

@@ -0,0 +1,41 @@
+import { ForbiddenError } from './http-errors.js';
+const LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1']);
+const LOCAL_REMOTE_ADDRESSES = new Set(['127.0.0.1', '::1']);
+const firstHeader = (value) => Array.isArray(value) ? value[0] : value;
+const normalizeHostname = (hostname) => hostname.replace(/^\[|\]$/g, '').toLowerCase();
+const isLocalHostname = (hostname) => LOCAL_HOSTNAMES.has(normalizeHostname(hostname));
+const normalizeRemoteAddress = (address) => normalizeHostname(address).replace(/^::ffff:/, '');
+const isLocalRemoteAddress = (address) => LOCAL_REMOTE_ADDRESSES.has(normalizeRemoteAddress(address));
+const isLocalAuthority = (authority) => {
+    try {
+        return isLocalHostname(new URL(`http://${authority}`).hostname);
+    }
+    catch {
+        return false;
+    }
+};
+const isLocalOrigin = (origin) => {
+    try {
+        return isLocalHostname(new URL(origin).hostname);
+    }
+    catch {
+        return false;
+    }
+};
+export const getLocalRequestRejection = (request) => {
+    const remoteAddress = request.socket.remoteAddress;
+    if (remoteAddress && !isLocalRemoteAddress(remoteAddress))
+        return 'non-local remote address';
+    const host = firstHeader(request.headers.host);
+    if (host && !isLocalAuthority(host))
+        return 'non-local Host header';
+    const origin = firstHeader(request.headers.origin);
+    if (origin && !isLocalOrigin(origin))
+        return 'non-local Origin header';
+    return null;
+};
+export const assertLocalRequest = (request) => {
+    const reason = getLocalRequestRejection(request);
+    if (reason)
+        throw new ForbiddenError(`Local runtime rejected ${reason}`);
+};

package/dist/src/server/machine-name.d.ts

@@ -0,0 +1,2 @@
+export declare function cleanMachineName(raw: string): string | null;
+export declare function getMachineName(): string | null;

package/dist/src/server/machine-name.js

@@ -0,0 +1,13 @@
+import { hostname } from 'node:os';
+const MAX_LEN = 64;
+// Trim surrounding whitespace, strip a trailing '.local' suffix (common on macOS),
+// and cap at 64 chars. Returns null if the result is empty.
+export function cleanMachineName(raw) {
+    const cleaned = raw.trim().replace(/\.local$/i, '');
+    if (cleaned.length === 0)
+        return null;
+    return cleaned.slice(0, MAX_LEN);
+}
+export function getMachineName() {
+    return cleanMachineName(hostname());
+}

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

@@ -0,0 +1,38 @@
+export type MarketplaceLanguage = 'en' | 'zh';
+export interface MarketplaceAgentEntry {
+    path: string;
+    category: string;
+    name: string;
+    displayName?: string;
+    nameOverflows?: boolean;
+    description: string;
+    emoji: string | null;
+    color: string | null;
+    vibe: string | null;
+}
+export interface MarketplaceManifest {
+    source: {
+        repo: string;
+        commit: string;
+        fetched_at: string;
+    };
+    language: MarketplaceLanguage;
+    categories: string[];
+    agents: MarketplaceAgentEntry[];
+}
+export interface MarketplaceAgentDetail {
+    path: string;
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+export declare class MarketplaceNotFoundError extends Error {
+    constructor(message: string);
+}
+export declare const isMarketplaceLanguage: (value: unknown) => value is MarketplaceLanguage;
+/**
+ * Where on disk the bundled marketplace lives. Tests inject a fixture via
+ * `HIVE_MARKETPLACE_VENDOR_ROOT` (mirrors fs-sandbox's HIVE_FS_BROWSE_ROOT).
+ */
+export declare const getMarketplaceVendorRoot: () => string;
+export declare const loadManifest: (language: MarketplaceLanguage) => MarketplaceManifest;
+export declare const readAgent: (language: MarketplaceLanguage, relativePath: string) => MarketplaceAgentDetail;

package/dist/src/server/marketplace-store.js

@@ -0,0 +1,85 @@
+// Marketplace store — read-only access to the bundled `vendor/marketplace/`
+// snapshot of upstream agent prompt repos (one per UI language).
+//
+// **Vendor path invariant**: `new URL('../../vendor/marketplace', import.meta.url)`
+// resolves the same in dev and dist because `tsconfig.json` has `rootDir: "."`.
+//   - dev: this file is `src/server/marketplace-store.ts` → repo-root `vendor/`
+//   - dist: this file is `dist/src/server/marketplace-store.js` → `dist/vendor/`
+//
+// The build hook (`scripts/prepare-build-artifacts.mjs`) copies the source-of-
+// truth `vendor/marketplace/` into `dist/vendor/marketplace/` at pack time. If
+// either the `rootDir` setting or the build hook changes, that invariant must
+// be re-verified — there is no fallback path.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import matter from 'gray-matter';
+import { isPathWithinRoot } from './fs-sandbox.js';
+export class MarketplaceNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MarketplaceNotFoundError';
+    }
+}
+const SUPPORTED_LANGUAGES = new Set(['en', 'zh']);
+export const isMarketplaceLanguage = (value) => typeof value === 'string' && SUPPORTED_LANGUAGES.has(value);
+const defaultVendorRoot = () => fileURLToPath(new URL('../../vendor/marketplace', import.meta.url));
+/**
+ * Where on disk the bundled marketplace lives. Tests inject a fixture via
+ * `HIVE_MARKETPLACE_VENDOR_ROOT` (mirrors fs-sandbox's HIVE_FS_BROWSE_ROOT).
+ */
+export const getMarketplaceVendorRoot = () => {
+    const override = process.env.HIVE_MARKETPLACE_VENDOR_ROOT;
+    return override && override.length > 0 ? resolve(override) : defaultVendorRoot();
+};
+const languageRoot = (language, vendorRoot = getMarketplaceVendorRoot()) => resolve(vendorRoot, language);
+const manifestCache = new Map();
+const agentCache = new Map();
+export const loadManifest = (language) => {
+    const vendorRoot = getMarketplaceVendorRoot();
+    const cacheKey = `${vendorRoot}\0${language}`;
+    const cached = manifestCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const manifestPath = resolve(languageRoot(language, vendorRoot), 'manifest.json');
+    if (!existsSync(manifestPath)) {
+        throw new MarketplaceNotFoundError(`Marketplace manifest missing for language: ${language}`);
+    }
+    const raw = readFileSync(manifestPath, 'utf8');
+    const manifest = JSON.parse(raw);
+    manifestCache.set(cacheKey, manifest);
+    return manifest;
+};
+export const readAgent = (language, relativePath) => {
+    if (!relativePath.endsWith('.md')) {
+        throw new MarketplaceNotFoundError(`Marketplace agent path must end with .md: ${relativePath}`);
+    }
+    const vendorRoot = getMarketplaceVendorRoot();
+    const root = languageRoot(language, vendorRoot);
+    const candidate = resolve(root, relativePath);
+    if (!isPathWithinRoot(root, candidate)) {
+        throw new MarketplaceNotFoundError(`Marketplace agent path escapes language root: ${relativePath}`);
+    }
+    if (!existsSync(candidate)) {
+        throw new MarketplaceNotFoundError(`Marketplace agent not found: ${language}/${relativePath}`);
+    }
+    // Guard against upstream pushing a directory whose name ends in `.md` —
+    // the suffix check would pass, existsSync would pass, but readFileSync
+    // would throw EISDIR. Surface as a 404 instead of a 500.
+    if (!statSync(candidate).isFile()) {
+        throw new MarketplaceNotFoundError(`Marketplace agent not a file: ${language}/${relativePath}`);
+    }
+    const cacheKey = `${vendorRoot}\0${language}\0${relativePath}`;
+    const cached = agentCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const raw = readFileSync(candidate, 'utf8');
+    const parsed = matter(raw);
+    const detail = {
+        path: relativePath,
+        frontmatter: parsed.data,
+        body: parsed.content,
+    };
+    agentCache.set(cacheKey, detail);
+    return detail;
+};

package/dist/src/server/message-log-store.d.ts

@@ -0,0 +1,51 @@
+import type { Database } from 'better-sqlite3';
+export interface MessageLogRecord {
+    artifacts?: string[];
+    createdAt: number;
+    fromAgentId?: string;
+    status?: string;
+    text: string;
+    toAgentId?: string;
+    type: 'user_input' | 'send' | 'report' | 'status' | 'system_env_sync' | 'system_recovery_summary';
+    workerId: string;
+    workspaceId: string;
+}
+export interface MessageLogHandle {
+    sequence: number;
+}
+interface RecoveryMessageBase {
+    createdAt: number;
+    text: string;
+}
+interface UserInputRecoveryMessage extends RecoveryMessageBase {
+    type: 'user_input';
+}
+interface SendRecoveryMessage extends RecoveryMessageBase {
+    type: 'send';
+    from?: string;
+    to: string;
+}
+interface ReportRecoveryMessage extends RecoveryMessageBase {
+    artifacts: string[];
+    from: string;
+    status?: string;
+    type: 'report';
+}
+interface StatusRecoveryMessage extends RecoveryMessageBase {
+    artifacts: string[];
+    from: string;
+    type: 'status';
+}
+export type RecoveryMessage = UserInputRecoveryMessage | SendRecoveryMessage | ReportRecoveryMessage | StatusRecoveryMessage;
+interface MessageKindRow {
+    type: 'send' | 'report';
+    worker_id: string;
+    workspace_id: string;
+}
+export declare const createMessageLogStore: (db: Database) => {
+    deleteMessage: (handle: MessageLogHandle) => void;
+    insertMessage: (input: MessageLogRecord) => MessageLogHandle;
+    listMessageKinds: () => MessageKindRow[];
+    listMessagesForRecovery: (workspaceId: string, sinceMs: number) => RecoveryMessage[];
+};
+export {};

package/dist/src/server/message-log-store.js

@@ -0,0 +1,90 @@
+export const createMessageLogStore = (db) => {
+    const listMessageKinds = () => {
+        return db
+            .prepare(`SELECT workspace_id, worker_id, type
+         FROM messages
+         WHERE type IN ('send', 'report')
+         ORDER BY sequence ASC`)
+            .all();
+    };
+    const insertMessage = (input) => {
+        const result = db
+            .prepare(`INSERT INTO messages (
+         workspace_id,
+         worker_id,
+         type,
+         from_agent_id,
+         to_agent_id,
+         text,
+         status,
+         artifacts,
+         created_at
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(input.workspaceId, input.workerId, input.type, input.fromAgentId ?? null, input.toAgentId ?? null, input.text, input.status ?? null, input.artifacts ? JSON.stringify(input.artifacts) : null, input.createdAt);
+        return { sequence: Number(result.lastInsertRowid) };
+    };
+    const deleteMessage = (handle) => {
+        db.prepare('DELETE FROM messages WHERE sequence = ?').run(handle.sequence);
+    };
+    const parseArtifacts = (value) => {
+        if (!value) {
+            return [];
+        }
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed)
+            ? parsed.filter((item) => typeof item === 'string')
+            : [];
+    };
+    const listMessagesForRecovery = (workspaceId, sinceMs) => {
+        return db
+            .prepare(`SELECT worker_id, type, from_agent_id, to_agent_id, text, status, artifacts, created_at
+         FROM messages
+         WHERE workspace_id = ? AND created_at >= ?
+         ORDER BY sequence ASC`)
+            .all(workspaceId, sinceMs)
+            .map((row) => {
+            const typedRow = row;
+            if (typedRow.type === 'user_input') {
+                return {
+                    createdAt: typedRow.created_at,
+                    text: typedRow.text ?? '',
+                    type: 'user_input',
+                };
+            }
+            if (typedRow.type === 'send') {
+                const message = {
+                    createdAt: typedRow.created_at,
+                    text: typedRow.text ?? '',
+                    to: typedRow.to_agent_id ?? typedRow.worker_id,
+                    type: 'send',
+                };
+                if (typedRow.from_agent_id) {
+                    message.from = typedRow.from_agent_id;
+                }
+                return message;
+            }
+            if (typedRow.type !== 'report' && typedRow.type !== 'status') {
+                return null;
+            }
+            const recoveryMessage = {
+                artifacts: parseArtifacts(typedRow.artifacts),
+                createdAt: typedRow.created_at,
+                from: typedRow.from_agent_id ?? typedRow.worker_id,
+                text: typedRow.text ?? '',
+                type: typedRow.type,
+            };
+            if (typedRow.type === 'report' && typedRow.status) {
+                ;
+                recoveryMessage.status = typedRow.status;
+            }
+            return recoveryMessage;
+        })
+            .filter((message) => message !== null);
+    };
+    return {
+        deleteMessage,
+        insertMessage,
+        listMessageKinds,
+        listMessagesForRecovery,
+    };
+};

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

@@ -0,0 +1,54 @@
+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[];
+    options?: ExecFileOptions;
+}
+/**
+ * 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,204 @@
+import { execFile } from 'node:child_process';
+import { getDefaultOpenTargetIdForPlatform, getEffectiveOpenTargetId, isOpenTargetId, } from '../shared/open-targets.js';
+import { buildCmdCallCommand } from './windows-command-line.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] }];
+    }
+};
+/**
+ * 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. Build that command
+ * with cmd-aware escaping instead of separate argv entries so path metachars
+ * (`&`, `|`, `%`, etc.) remain data rather than syntax.
+ */
+const cmdExeShimAttempt = (bin, path) => ({
+    command: 'cmd.exe',
+    args: ['/d', '/s', '/c', buildCmdCallCommand(bin, [path])],
+    options: { windowsHide: true },
+});
+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 [cmdExeShimAttempt('code', path)];
+        case 'vscode-insiders':
+            return [cmdExeShimAttempt('code-insiders', path)];
+        case 'cursor':
+            return [cmdExeShimAttempt('cursor', path)];
+        case 'zed':
+            return [cmdExeShimAttempt('zed', 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,
+    // 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')
+        return 'command-not-in-path';
+    if (result.status === 9009)
+        return 'app-not-installed';
+    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, attempt.options ?? {});
+        // 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.',
+    };
+};