hivehq 2.0.0

package/dist/src/server/workspace-store-mutations.d.ts

@@ -0,0 +1,14 @@
+import type { AgentSummary, WorkerRole } from '../shared/types.js';
+import type { WorkspaceRecord } from './workspace-store-contract.js';
+type WorkspaceMap = Map<string, WorkspaceRecord>;
+export declare const getAgentRecord: (workspaces: WorkspaceMap, workspaceId: string, agentId: string) => AgentSummary;
+export declare const getWorkerRecord: (workspaces: WorkspaceMap, workspaceId: string, workerId: string) => AgentSummary & {
+    role: WorkerRole;
+};
+export declare const getWorkerByNameRecord: (workspaces: WorkspaceMap, workspaceId: string, workerName: string) => AgentSummary;
+export declare const markAgentStarted: (workspaces: WorkspaceMap, workspaceId: string, agentId: string) => void;
+export declare const markAgentStopped: (workspaces: WorkspaceMap, workspaceId: string, agentId: string) => void;
+export declare const markTaskDispatched: (workspaces: WorkspaceMap, workspaceId: string, workerId: string) => void;
+export declare const markTaskReported: (workspaces: WorkspaceMap, workspaceId: string, workerId: string) => void;
+export declare const markTaskCancelled: (workspaces: WorkspaceMap, workspaceId: string, workerId: string) => void;
+export {};

package/dist/src/server/workspace-store-mutations.js

@@ -0,0 +1,48 @@
+import { getStatusFromPendingCount, isWorkerAgent } from './workspace-store-support.js';
+const getWorkspaceRecord = (workspaces, workspaceId) => {
+    const workspace = workspaces.get(workspaceId);
+    if (!workspace)
+        throw new Error(`Workspace not found: ${workspaceId}`);
+    return workspace;
+};
+export const getAgentRecord = (workspaces, workspaceId, agentId) => {
+    const agent = getWorkspaceRecord(workspaces, workspaceId).agents.find((item) => item.id === agentId);
+    if (!agent)
+        throw new Error(`Agent not found: ${agentId}`);
+    return agent;
+};
+export const getWorkerRecord = (workspaces, workspaceId, workerId) => {
+    const worker = getAgentRecord(workspaces, workspaceId, workerId);
+    if (!isWorkerAgent(worker))
+        throw new Error(`Worker not found: ${workerId}`);
+    return worker;
+};
+export const getWorkerByNameRecord = (workspaces, workspaceId, workerName) => {
+    const worker = getWorkspaceRecord(workspaces, workspaceId).agents.find((item) => item.name === workerName && isWorkerAgent(item));
+    if (!worker)
+        throw new Error(`Worker not found: ${workerName}`);
+    return worker;
+};
+export const markAgentStarted = (workspaces, workspaceId, agentId) => {
+    const agent = getAgentRecord(workspaces, workspaceId, agentId);
+    agent.status = isWorkerAgent(agent) ? getStatusFromPendingCount(agent.pendingTaskCount) : 'idle';
+};
+export const markAgentStopped = (workspaces, workspaceId, agentId) => {
+    getAgentRecord(workspaces, workspaceId, agentId).status = 'stopped';
+};
+export const markTaskDispatched = (workspaces, workspaceId, workerId) => {
+    const worker = getWorkerRecord(workspaces, workspaceId, workerId);
+    worker.pendingTaskCount += 1;
+    // spec §3.6.4: a stopped worker may accumulate queued tasks; PTY isn't
+    // running so it can't be `working`. Stay stopped until restart (mirrors
+    // markTaskReported's stopped guard below).
+    if (worker.status !== 'stopped')
+        worker.status = getStatusFromPendingCount(worker.pendingTaskCount);
+};
+export const markTaskReported = (workspaces, workspaceId, workerId) => {
+    const worker = getWorkerRecord(workspaces, workspaceId, workerId);
+    worker.pendingTaskCount = Math.max(0, worker.pendingTaskCount - 1);
+    if (worker.status !== 'stopped')
+        worker.status = getStatusFromPendingCount(worker.pendingTaskCount);
+};
+export const markTaskCancelled = markTaskReported;

package/dist/src/server/workspace-store-support.d.ts

@@ -0,0 +1,33 @@
+import type { AgentStatus, AgentSummary, WorkerRole } from '../shared/types.js';
+export interface MessageKindRecord {
+    type: 'send' | 'report';
+    worker_id: string;
+    workspace_id: string;
+}
+export interface WorkspaceRow {
+    id: string;
+    name: string;
+    path: string;
+}
+export interface WorkerRow {
+    id: string;
+    workspace_id: string;
+    name: string;
+    description: string | null;
+    role: WorkerRole;
+    ephemeral: number;
+    spawned_by: string | null;
+}
+export interface WorkspaceSummaryRow extends WorkspaceRow {
+}
+export declare const getOrchestratorId: (workspaceId: string) => string;
+export declare const createOrchestrator: (workspaceId: string) => AgentSummary;
+export declare const getWorkflowAgentId: (workspaceId: string) => string;
+export declare const createWorkflowAgent: (workspaceId: string) => AgentSummary;
+export declare const isWorkerAgent: (agent: AgentSummary) => agent is AgentSummary & {
+    role: WorkerRole;
+};
+export declare const getStatusFromPendingCount: (pendingTaskCount: number) => AgentStatus;
+export declare const applyPendingTaskCount: (worker: AgentSummary & {
+    role: WorkerRole;
+}, type: MessageKindRecord["type"], preserveStoppedStatus: boolean) => void;

package/dist/src/server/workspace-store-support.js

@@ -0,0 +1,36 @@
+import { getDefaultRoleDescription } from './role-templates.js';
+export const getOrchestratorId = (workspaceId) => `${workspaceId}:orchestrator`;
+export const createOrchestrator = (workspaceId) => ({
+    id: getOrchestratorId(workspaceId),
+    workspaceId,
+    name: 'Orchestrator',
+    description: getDefaultRoleDescription('orchestrator'),
+    role: 'orchestrator',
+    status: 'stopped',
+    pendingTaskCount: 0,
+});
+export const getWorkflowAgentId = (workspaceId) => `${workspaceId}:__workflow__`;
+// In-memory pseudo-agent (no DB row, no PTY) that gives the deterministic
+// workflow runner a dispatch identity — mirrors the orchestrator pseudo-agent.
+export const createWorkflowAgent = (workspaceId) => ({
+    id: getWorkflowAgentId(workspaceId),
+    workspaceId,
+    name: 'Workflow',
+    description: 'Hive workflow runner — deterministic multi-agent orchestration driver.',
+    role: 'workflow',
+    status: 'stopped',
+    pendingTaskCount: 0,
+});
+export const isWorkerAgent = (agent) => {
+    return agent.role !== 'orchestrator' && agent.role !== 'workflow';
+};
+export const getStatusFromPendingCount = (pendingTaskCount) => {
+    return pendingTaskCount > 0 ? 'working' : 'idle';
+};
+export const applyPendingTaskCount = (worker, type, preserveStoppedStatus) => {
+    worker.pendingTaskCount =
+        type === 'send' ? worker.pendingTaskCount + 1 : Math.max(0, worker.pendingTaskCount - 1);
+    if (!preserveStoppedStatus) {
+        worker.status = getStatusFromPendingCount(worker.pendingTaskCount);
+    }
+};

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

@@ -0,0 +1,5 @@
+import type { Database } from 'better-sqlite3';
+import type { WorkerInput, WorkspaceRecord, WorkspaceStore } from './workspace-store-contract.js';
+import { type MessageKindRecord } from './workspace-store-support.js';
+export type { WorkerInput, WorkspaceRecord, WorkspaceStore };
+export declare const createWorkspaceStore: (db: Database, messageKinds: MessageKindRecord[]) => WorkspaceStore;

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

@@ -0,0 +1,153 @@
+import { randomUUID } from 'node:crypto';
+import { ConflictError } from './http-errors.js';
+import { sameFilesystemPath } from './path-canonicalization.js';
+import { getDefaultRoleDescription } from './role-templates.js';
+import { hydrateWorkspaceFromDb, seedWorkspacesFromDb } from './workspace-store-hydration.js';
+import { getAgentRecord, getWorkerByNameRecord, getWorkerRecord, markAgentStarted, markAgentStopped, markTaskCancelled, markTaskDispatched, markTaskReported, } from './workspace-store-mutations.js';
+import { createOrchestrator, createWorkflowAgent, isWorkerAgent, } from './workspace-store-support.js';
+const normalizeWorkerName = (name) => {
+    const trimmed = name.trim();
+    if (!trimmed)
+        throw new Error('Worker name must not be empty');
+    if (trimmed.length > 64)
+        throw new Error('Worker name must be 64 characters or fewer');
+    return trimmed;
+};
+export const createWorkspaceStore = (db, messageKinds) => {
+    const workspaces = new Map();
+    seedWorkspacesFromDb(db, workspaces, messageKinds);
+    const getWorkspace = (workspaceId) => {
+        hydrateWorkspaceFromDb(db, workspaces, messageKinds, workspaceId);
+        const workspace = workspaces.get(workspaceId);
+        if (!workspace)
+            throw new Error(`Workspace not found: ${workspaceId}`);
+        return workspace;
+    };
+    return {
+        addWorker(workspaceId, input) {
+            const workspace = getWorkspace(workspaceId);
+            const name = normalizeWorkerName(input.name);
+            if (workspace.agents.some((agent) => agent.name === name && isWorkerAgent(agent))) {
+                throw new ConflictError(`Worker name already exists: ${name}`);
+            }
+            const worker = {
+                id: randomUUID(),
+                workspaceId,
+                name,
+                description: input.description ?? getDefaultRoleDescription(input.role),
+                role: input.role,
+                status: 'stopped',
+                pendingTaskCount: 0,
+                ephemeral: input.ephemeral ?? false,
+                spawnedBy: input.spawnedBy ?? null,
+            };
+            db.prepare('INSERT INTO workers (id, workspace_id, name, description, role, ephemeral, spawned_by, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)').run(worker.id, workspaceId, worker.name, worker.description, worker.role, worker.ephemeral ? 1 : 0, worker.spawnedBy, Date.now());
+            workspace.agents.push(worker);
+            return worker;
+        },
+        createWorkspace(path, name) {
+            const existing = Array.from(workspaces.values()).find((workspace) => sameFilesystemPath(workspace.summary.path, path));
+            if (existing)
+                throw new ConflictError(`Workspace path already exists: ${path}`);
+            const summary = { id: randomUUID(), name, path };
+            db.prepare('INSERT INTO workspaces (id, name, path, created_at) VALUES (?, ?, ?, ?)').run(summary.id, name, path, Date.now());
+            workspaces.set(summary.id, {
+                summary,
+                agents: [createOrchestrator(summary.id), createWorkflowAgent(summary.id)],
+            });
+            return summary;
+        },
+        deleteWorkspace(workspaceId) {
+            const workspace = getWorkspace(workspaceId);
+            const agentIds = workspace.agents.map((agent) => agent.id);
+            db.transaction(() => {
+                db.prepare('DELETE FROM messages WHERE workspace_id = ?').run(workspaceId);
+                db.prepare('DELETE FROM agent_launch_configs WHERE workspace_id = ?').run(workspaceId);
+                db.prepare('DELETE FROM agent_sessions WHERE workspace_id = ?').run(workspaceId);
+                const deleteAgentRuns = db.prepare('DELETE FROM agent_runs WHERE agent_id = ?');
+                for (const agentId of agentIds)
+                    deleteAgentRuns.run(agentId);
+                db.prepare('DELETE FROM workers WHERE workspace_id = ?').run(workspaceId);
+                // TIER 1 #4 — cascade workflow tables. Without this, the scheduler's
+                // listDueSchedules keeps firing schedules for the dead workspace
+                // every minute (the startWorkflow then crashes in
+                // getWorkflowAgentId / addWorkerWithLaunch and `nextRunAt` is
+                // rewritten to fire again next tick — a permanent error-spam
+                // loop). Orphan workflow_runs / dispatches would otherwise also
+                // accumulate forever. The dispatches DELETE in particular hits the
+                // workflow-tagged subset; non-workflow dispatches were already
+                // cleared via the deleteWorker cascade above.
+                db.prepare('DELETE FROM workflow_schedules WHERE workspace_id = ?').run(workspaceId);
+                // TIER 2 #3 — also wipe the log table; FK is on run_id, so we
+                // have to clear it BEFORE deleting workflow_runs (the lookup
+                // would otherwise miss the rows we're about to delete).
+                db.prepare(`DELETE FROM workflow_run_logs
+           WHERE run_id IN (SELECT id FROM workflow_runs WHERE workspace_id = ?)`).run(workspaceId);
+                db.prepare('DELETE FROM workflow_runs WHERE workspace_id = ?').run(workspaceId);
+                db.prepare('DELETE FROM dispatches WHERE workspace_id = ?').run(workspaceId);
+                db.prepare('DELETE FROM workspaces WHERE id = ?').run(workspaceId);
+            })();
+            workspaces.delete(workspaceId);
+        },
+        renameWorker(workspaceId, workerId, name) {
+            const worker = getWorkerRecord(workspaces, workspaceId, workerId);
+            const trimmed = normalizeWorkerName(name);
+            if (trimmed === worker.name)
+                return worker;
+            const workspace = getWorkspace(workspaceId);
+            if (workspace.agents.some((agent) => agent.id !== workerId && agent.name === trimmed && isWorkerAgent(agent))) {
+                throw new ConflictError(`Worker name already exists: ${trimmed}`);
+            }
+            db.prepare('UPDATE workers SET name = ? WHERE workspace_id = ? AND id = ?').run(trimmed, workspaceId, workerId);
+            worker.name = trimmed;
+            return worker;
+        },
+        deleteWorker(workspaceId, workerId) {
+            const workspace = getWorkspace(workspaceId);
+            getWorkerRecord(workspaces, workspaceId, workerId);
+            db.transaction(() => {
+                db.prepare('DELETE FROM messages WHERE workspace_id = ? AND worker_id = ?').run(workspaceId, workerId);
+                db.prepare('DELETE FROM agent_launch_configs WHERE workspace_id = ? AND agent_id = ?').run(workspaceId, workerId);
+                db.prepare('DELETE FROM agent_sessions WHERE workspace_id = ? AND agent_id = ?').run(workspaceId, workerId);
+                db.prepare('DELETE FROM agent_runs WHERE agent_id = ?').run(workerId);
+                db.prepare('DELETE FROM workers WHERE workspace_id = ? AND id = ?').run(workspaceId, workerId);
+            })();
+            workspace.agents = workspace.agents.filter((agent) => agent.id !== workerId);
+        },
+        getAgent: (workspaceId, agentId) => getAgentRecord(workspaces, workspaceId, agentId),
+        getWorker: (workspaceId, workerId) => getWorkerRecord(workspaces, workspaceId, workerId),
+        getWorkerByName: (workspaceId, workerName) => getWorkerByNameRecord(workspaces, workspaceId, workerName),
+        getWorkspaceSnapshot: getWorkspace,
+        hasAgent(workspaceId, agentId) {
+            hydrateWorkspaceFromDb(db, workspaces, messageKinds, workspaceId);
+            return workspaces.get(workspaceId)?.agents.some((agent) => agent.id === agentId) ?? false;
+        },
+        listWorkers(workspaceId) {
+            return getWorkspace(workspaceId)
+                .agents.filter(isWorkerAgent)
+                .map(({ id, name, role, status, pendingTaskCount, ephemeral, spawnedBy }) => ({
+                id,
+                name,
+                role,
+                status,
+                pendingTaskCount,
+                // Carry the lifecycle marker through to the team panel so workflow-
+                // spawned ephemeral workers can be visually distinguished from the
+                // user's persistent team (M10).
+                ...(ephemeral === true ? { ephemeral: true } : {}),
+                ...(spawnedBy ? { spawnedBy } : {}),
+            }));
+        },
+        listWorkspaces() {
+            return Array.from(workspaces.values(), (workspace) => workspace.summary);
+        },
+        hasWorkspace(workspaceId) {
+            return workspaces.has(workspaceId);
+        },
+        markAgentStarted: (workspaceId, agentId) => markAgentStarted(workspaces, workspaceId, agentId),
+        markAgentStopped: (workspaceId, agentId) => markAgentStopped(workspaces, workspaceId, agentId),
+        markTaskDispatched: (workspaceId, workerId) => markTaskDispatched(workspaces, workspaceId, workerId),
+        markTaskCancelled: (workspaceId, workerId) => markTaskCancelled(workspaces, workspaceId, workerId),
+        markTaskReported: (workspaceId, workerId) => markTaskReported(workspaces, workspaceId, workerId),
+    };
+};

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

@@ -0,0 +1 @@
+export declare const WINDOWS_DRIVES_ROOT = "hive://windows-drives";

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

@@ -0,0 +1 @@
+export const WINDOWS_DRIVES_ROOT = 'hive://windows-drives';

package/dist/src/shared/open-targets.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Cross-cutting types for the "Open workspace in editor/app" feature.
+ * Both the server (command construction in `src/server/open-target-commands.ts`)
+ * and the web client (button + preference store in `web/src/workspace/open-targets.ts`)
+ * pull the union and platform whitelist from here so they cannot drift.
+ */
+export type OpenTargetId = 'vscode' | 'vscode-insiders' | 'cursor' | 'finder' | 'terminal' | 'ghostty' | 'zed';
+export type OpenTargetPlatform = 'mac' | 'windows' | 'linux' | 'other';
+export declare const OPEN_TARGET_IDS_BY_PLATFORM: Record<OpenTargetPlatform, readonly OpenTargetId[]>;
+export declare const isOpenTargetId: (value: unknown) => value is OpenTargetId;
+export declare const isOpenTargetSupported: (targetId: OpenTargetId, platform: OpenTargetPlatform) => boolean;
+/**
+ * The id the server will actually attempt to launch. If the user's saved
+ * preference is unsupported on the current platform (e.g. they picked iTerm2
+ * on a Mac, then opened Hive on Windows), fall back to the platform default
+ * rather than erroring out — a stale preference shouldn't break the button.
+ */
+export declare const getEffectiveOpenTargetId: (targetId: OpenTargetId, platform: OpenTargetPlatform) => OpenTargetId;
+export declare const getDefaultOpenTargetIdForPlatform: (platform: OpenTargetPlatform) => OpenTargetId;
+export type OpenWorkspaceErrorCode = 'invalid-path' | 'invalid-target' | 'app-not-installed' | 'command-not-in-path' | 'unknown';

package/dist/src/shared/open-targets.js

@@ -0,0 +1,36 @@
+/**
+ * Cross-cutting types for the "Open workspace in editor/app" feature.
+ * Both the server (command construction in `src/server/open-target-commands.ts`)
+ * and the web client (button + preference store in `web/src/workspace/open-targets.ts`)
+ * pull the union and platform whitelist from here so they cannot drift.
+ */
+// Note: there is no `cursor-insiders` here. Cursor stopped shipping a separate
+// Nightly bundle / `cursor-nightly` binary in March 2024; the pre-release
+// channel is now an in-app toggle on the regular Cursor.app.
+//
+// IntelliJ IDEA, Windsurf, and iTerm2 were intentionally dropped after 1.3.0:
+// IntelliJ users typically launch from JetBrains Toolbox rather than a folder
+// picker; Windsurf overlaps with Cursor/VS Code; iTerm2 overlaps with the
+// built-in macOS Terminal entry.
+export const OPEN_TARGET_IDS_BY_PLATFORM = {
+    mac: ['vscode', 'vscode-insiders', 'cursor', 'finder', 'terminal', 'ghostty', 'zed'],
+    windows: ['vscode', 'vscode-insiders', 'cursor', 'finder', 'zed'],
+    linux: ['vscode', 'vscode-insiders', 'cursor', 'finder', 'zed'],
+    other: ['vscode', 'vscode-insiders', 'finder'],
+};
+const ALL_TARGET_IDS = new Set(OPEN_TARGET_IDS_BY_PLATFORM.mac);
+export const isOpenTargetId = (value) => typeof value === 'string' && ALL_TARGET_IDS.has(value);
+export const isOpenTargetSupported = (targetId, platform) => OPEN_TARGET_IDS_BY_PLATFORM[platform].includes(targetId);
+/**
+ * The id the server will actually attempt to launch. If the user's saved
+ * preference is unsupported on the current platform (e.g. they picked iTerm2
+ * on a Mac, then opened Hive on Windows), fall back to the platform default
+ * rather than erroring out — a stale preference shouldn't break the button.
+ */
+export const getEffectiveOpenTargetId = (targetId, platform) => isOpenTargetSupported(targetId, platform) ? targetId : getDefaultOpenTargetIdForPlatform(platform);
+export const getDefaultOpenTargetIdForPlatform = (platform) => {
+    // `finder` exists for every platform and never fails closed.
+    if (platform === 'mac' || platform === 'windows' || platform === 'linux')
+        return 'finder';
+    return 'vscode';
+};

package/dist/src/shared/path-input.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Normalize a path pasted into a workspace input. Windows Explorer's
+ * "Copy as path" wraps the value in double quotes (e.g. `"C:\\Users\\me"`);
+ * shell-style paste from a terminal sometimes uses single quotes. Resolving
+ * the quoted form with `realpathSync` fails even though the unquoted path is
+ * valid.
+ *
+ * The heuristic is intentionally conservative: only a symmetric outer pair
+ * of identical quote characters is removed. Asymmetric or interior quotes
+ * survive so legitimately quote-containing paths still reach the server.
+ */
+export declare const sanitizePastedPath: (raw: string) => string;

package/dist/src/shared/path-input.js

@@ -0,0 +1,22 @@
+/**
+ * Normalize a path pasted into a workspace input. Windows Explorer's
+ * "Copy as path" wraps the value in double quotes (e.g. `"C:\\Users\\me"`);
+ * shell-style paste from a terminal sometimes uses single quotes. Resolving
+ * the quoted form with `realpathSync` fails even though the unquoted path is
+ * valid.
+ *
+ * The heuristic is intentionally conservative: only a symmetric outer pair
+ * of identical quote characters is removed. Asymmetric or interior quotes
+ * survive so legitimately quote-containing paths still reach the server.
+ */
+export const sanitizePastedPath = (raw) => {
+    const trimmed = raw.trim();
+    if (trimmed.length < 2)
+        return trimmed;
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    if ((first === '"' || first === "'") && first === last) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+};

package/dist/src/shared/remote-bridge-routing.d.ts

@@ -0,0 +1,19 @@
+import { type StreamMeta } from './remote-protocol.js';
+export declare const ALLOWED_HTTP_PREFIX: "/api/";
+export type BridgeRejectReason = 'path_not_whitelisted' | 'path_not_canonical' | 'path_denied' | 'bad_method' | 'malformed_meta';
+export type RouteDecision = {
+    ok: true;
+    transport: 'http';
+    method: string;
+    path: string;
+} | {
+    ok: true;
+    transport: 'ws';
+    path: string;
+    query?: [string, string][];
+} | {
+    ok: false;
+    reason: BridgeRejectReason;
+};
+export declare function isCanonicalPath(path: string): boolean;
+export declare function classifyOpen(meta: StreamMeta): RouteDecision;

package/dist/src/shared/remote-bridge-routing.js

@@ -0,0 +1,141 @@
+// The loopback bridge whitelist — the "not a general localhost proxy" gate.
+//
+// Runs in BOTH node and browser (pure, no I/O): the daemon runs it on the
+// OPENED Open-frame StreamMeta, AFTER the frame authenticates (M1 openNext) and
+// BEFORE any loopback socket exists. A { ok: false } decision => the tunnel
+// sends Reset(StreamRefused) + emits a `reject` audit row, and NEVER makes a
+// loopback request. Removing or weakening any check here turns the tunnel into
+// an arbitrary localhost proxy — that is exactly what these checks forbid.
+//
+// Invariant 1 (binding): the bridge forwards ONLY /api/* and /ws/* (terminal +
+// tasks). Everything else — traversal, encoded tricks, absolute URLs, the UI
+// session cookie route — is refused here.
+import { StreamTransport } from './remote-protocol.js';
+export const ALLOWED_HTTP_PREFIX = '/api/';
+// Exact terminal io/control + tasks ws paths — mirrors terminal-ws-server's
+// matchTerminalPath regex and the /ws/tasks/<id> match in that file. Path-only:
+// the WS query (clientId/cols/rows) rides separate StreamMeta fields, never the
+// path, so we gate the bare path and reject any query smuggled into it.
+const WS_TERMINAL_RE = /^\/ws\/terminal\/[^/]+\/(?:io|control)$/;
+const WS_TASKS_RE = /^\/ws\/tasks\/[^/]+$/;
+const ALLOWED_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
+// HARDEN: /api/ui/session is UNAUTHENTICATED and unconditionally responds with
+// Set-Cookie: hive_ui_token=<the master UI token>. The tunnel is authorized by
+// the per-boot secret, so the phone has zero need for the UI cookie. Forwarding
+// it would let a paired phone harvest the single credential that authenticates
+// every /api/* route + WS upgrade. Hard-deny by exact pathname (case-folded),
+// before prefix matching can let it through. This is layer (1) of the fix; the
+// bridge's response-header sanitizer (remote-loopback-auth) is layer (2), and
+// routes-ui refusing tunnel-tagged requests is layer (3).
+const DENIED_HTTP_PATHS = new Set(['/api/ui/session']);
+// HARDEN (trust-root defense-in-depth): the device-pairing TRUST-ROOT actions — begin a pairing,
+// confirm/approve a device, reject a pending one — are desktop-only at the route layer
+// (routes-remote.gateLocalDesktopOnly). The Authority Model says a phone can NEVER self-approve a
+// new device, so we mirror /api/ui/session's layered defense: layer 1 hard-denies these here on the
+// bridge (a forwarded frame is Reset(StreamRefused) + audited path_denied), layer 3 is the route gate.
+// `/api/remote/pairings` (begin, POST) collides with the collection path, and confirm/reject carry a
+// :pairingId segment, so we deny by matcher rather than an exact-set entry. A phone still uses the
+// EQUAL-AUTHORITY remote routes (list devices, revoke, status, audit) — only the trust root is denied.
+const isDeniedPairingPath = (pathname) => {
+    if (pathname === '/api/remote/pairings')
+        return true; // begin a pairing (POST)
+    // confirm/reject under /api/remote/pairings/:id — match the action suffix on a pairings path.
+    return (pathname.startsWith('/api/remote/pairings/') &&
+        (pathname.endsWith('/confirm') || pathname.endsWith('/reject')));
+};
+// Canonicalization gate for the path SHAPE (no query handling — that is the
+// caller's policy). Reject anything non-canonical so an encoded or traversal
+// path can never reach a route that later decodes it.
+//
+// A query string is allowed structurally (it is not traversal); whether a query
+// is *permitted* on a given transport is decided in classifyOpen.
+export function isCanonicalPath(path) {
+    if (typeof path !== 'string' || path.length === 0)
+        return false;
+    if (path[0] !== '/')
+        return false; // no absolute URLs, no authority-relative
+    if (path.includes('\0') || path.includes('\\'))
+        return false;
+    if (/%2e|%2f/i.test(path))
+        return false; // encoded . or / — refuse outright
+    if (path.includes('..'))
+        return false; // any traversal segment
+    if (path.startsWith('//'))
+        return false; // protocol-relative / authority
+    // URL parse must round-trip the pathname (ignoring any query) unchanged and
+    // not surface an injected host.
+    let u;
+    try {
+        u = new URL(path, 'http://x');
+    }
+    catch {
+        return false;
+    }
+    if (u.host !== 'x')
+        return false;
+    // pathname + search must reconstruct the input byte-for-byte: this rejects a
+    // space or any char the URL parser would normalize/strip, while still
+    // permitting a legitimate ?query.
+    return u.pathname + u.search === path;
+}
+// True if s contains any C0 control char (charCode 0..31). Used to keep a WS query pair from
+// smuggling a NUL/CR/LF past the loopback-URL reattach.
+function hasControlChar(s) {
+    for (let i = 0; i < s.length; i++) {
+        if (s.charCodeAt(i) <= 0x1f)
+            return true;
+    }
+    return false;
+}
+export function classifyOpen(meta) {
+    if (meta.transport === StreamTransport.Http) {
+        const m = meta.http;
+        if (!m)
+            return { ok: false, reason: 'malformed_meta' };
+        if (!isCanonicalPath(m.path))
+            return { ok: false, reason: 'path_not_canonical' };
+        // Split off the query: the prefix/deny checks run on the pathname only, so a
+        // query string can neither bypass the deny set nor break a legit /api route.
+        const queryStart = m.path.indexOf('?');
+        const pathname = queryStart === -1 ? m.path : m.path.slice(0, queryStart);
+        const lowered = pathname.toLowerCase();
+        if (DENIED_HTTP_PATHS.has(lowered) || isDeniedPairingPath(lowered)) {
+            return { ok: false, reason: 'path_denied' };
+        }
+        if (!pathname.startsWith(ALLOWED_HTTP_PREFIX)) {
+            return { ok: false, reason: 'path_not_whitelisted' };
+        }
+        if (!ALLOWED_METHODS.has(m.method))
+            return { ok: false, reason: 'bad_method' };
+        return { ok: true, transport: 'http', method: m.method, path: m.path };
+    }
+    if (meta.transport === StreamTransport.Ws) {
+        const w = meta.ws;
+        if (!w)
+            return { ok: false, reason: 'malformed_meta' };
+        if (!isCanonicalPath(w.path))
+            return { ok: false, reason: 'path_not_canonical' };
+        // WS path is path-only — a query here is non-canonical (it must ride the
+        // separate `query` meta field, reattached on the loopback URL).
+        if (w.path.includes('?'))
+            return { ok: false, reason: 'path_not_canonical' };
+        if (!WS_TERMINAL_RE.test(w.path) && !WS_TASKS_RE.test(w.path)) {
+            return { ok: false, reason: 'path_not_whitelisted' };
+        }
+        // The WS query rides separate [name,value] pairs. Reject any pair whose key/value carries a
+        // control char that could break out of the query when we URL-encode it back (defense in depth —
+        // even though we encodeURIComponent on reattach, a NUL/control char has no business in
+        // clientId/cols/rows). An empty key is also nonsense.
+        if (w.query !== undefined) {
+            for (const [k, v] of w.query) {
+                if (k.length === 0 || hasControlChar(k) || hasControlChar(v)) {
+                    return { ok: false, reason: 'malformed_meta' };
+                }
+            }
+        }
+        return w.query !== undefined
+            ? { ok: true, transport: 'ws', path: w.path, query: w.query }
+            : { ok: true, transport: 'ws', path: w.path };
+    }
+    return { ok: false, reason: 'malformed_meta' };
+}