@shogo-ai/worker 1.9.9 → 1.10.1

package/src/lib/db-doctor.ts

@@ -0,0 +1,355 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+//
+// Local SQLite migration "doctor" for the Shogo desktop app.
+//
+// The packaged desktop app stores its database at
+// `<userData>/data/shogo.db` and applies schema with
+// `prisma migrate deploy` on every launch. When a migration throws
+// mid-way it leaves a row in `_prisma_migrations` with
+// `finished_at = NULL`, and Prisma's P3009 check then refuses to run
+// ANY further migrations — the app is wedged until that ledger row is
+// cleared. The desktop app surfaces a recovery dialog when this happens
+// on boot (see apps/desktop/src/db-recovery.ts), but a user whose app
+// won't open, or who is being walked through a fix by support, has no
+// way to trigger that repair from a terminal.
+//
+// `shogo doctor` (this module) is that terminal entry point. It performs
+// the SAME safe, dependency-free repair the desktop dialog does:
+//
+//   1. detectFailedMigrations()  — find stuck `_prisma_migrations` rows.
+//   2. backupDatabase()          — snapshot `shogo.db` (+ -wal/-shm)
+//                                  before touching anything.
+//   3. repairFailedMigrations()  — delete the stuck rows (equivalent to
+//                                  `prisma migrate resolve --rolled-back`).
+//
+// It deliberately does NOT re-run `prisma migrate deploy` itself — the
+// CLI doesn't ship the Prisma schema/migration history that lives inside
+// the desktop app bundle. Instead it clears the wedge and tells the user
+// to relaunch Shogo, which re-applies migrations on its next boot.
+//
+// Why shell out to bun rather than link a SQLite driver
+// -----------------------------------------------------
+// The worker CLI runs under Node (npm install) OR Bun (tarball release),
+// and we don't want a native `better-sqlite3` build step. The desktop
+// app already ships a `bun` binary with `bun:sqlite` statically linked,
+// and that's the exact SQLite version Prisma's bun-sqlite adapter uses at
+// runtime — so running `bun -e "<small script>"` against it is both
+// dependency-free and driver-version-matched. This mirrors
+// apps/desktop/src/db-recovery.ts (kept as a separate copy there because
+// the Electron main process is bundled in a different runtime context).
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, copyFileSync } from 'node:fs';
+import path from 'node:path';
+import { homedir, platform } from 'node:os';
+
+export interface FailedMigration {
+  name: string;
+  /** Epoch milliseconds the migration was attempted. */
+  startedAt: number;
+  /** First 600 chars of the Prisma error log row, for display. */
+  errorExcerpt: string;
+}
+
+/**
+ * Run a one-shot bun script against the given DB and parse its stdout
+ * as JSON. The script reads the DB path from `process.env.DBP` so we
+ * don't have to escape paths (which can contain spaces) through shell
+ * quoting. Throws if bun isn't usable or the script bails — we do NOT
+ * swallow these, since a broken recovery layer should surface its own
+ * defect rather than a misleading "database looks fine".
+ */
+function runBunScript<T>(bunPath: string, dbPath: string, script: string): T {
+  const out = execFileSync(bunPath, ['-e', script], {
+    env: { ...process.env, DBP: dbPath },
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 5000,
+  });
+  const trimmed = out.trim();
+  if (!trimmed) {
+    throw new Error(`bun script returned empty output for ${dbPath}`);
+  }
+  return JSON.parse(trimmed) as T;
+}
+
+/**
+ * Return `_prisma_migrations` rows that are still failed (`finished_at`
+ * NULL) and not yet recovered (`rolled_back_at` NULL). Returns an empty
+ * array when the DB doesn't exist, the table hasn't been created, or no
+ * failures are present.
+ */
+export function detectFailedMigrations(bunPath: string, dbPath: string): FailedMigration[] {
+  if (!existsSync(dbPath)) return [];
+
+  const script = `
+    import { Database } from 'bun:sqlite';
+    try {
+      const db = new Database(process.env.DBP, { readonly: true });
+      const hasTable = db.query("SELECT name FROM sqlite_master WHERE type='table' AND name='_prisma_migrations'").get();
+      if (!hasTable) { console.log('[]'); process.exit(0); }
+      const rows = db
+        .query("SELECT migration_name as name, started_at as startedAt, substr(coalesce(logs, ''), 1, 600) as errorExcerpt FROM _prisma_migrations WHERE finished_at IS NULL AND rolled_back_at IS NULL ORDER BY started_at")
+        .all();
+      console.log(JSON.stringify(rows));
+    } catch (e) {
+      console.error(String(e?.stack || e));
+      process.exit(2);
+    }
+  `;
+
+  return runBunScript<FailedMigration[]>(bunPath, dbPath, script);
+}
+
+/**
+ * Snapshot `shogo.db` (plus `-wal`/`-shm` sidecars if present) to a
+ * timestamped sibling file. Returns the backup path of the main DB.
+ * Uses plain copies (not SQLite's online backup) because the DB is not
+ * open at this point and `copyFileSync` works even on a DB SQLite would
+ * refuse to open. Throws on any I/O failure — the caller MUST treat that
+ * as "do not proceed with repair".
+ */
+export function backupDatabase(dbPath: string): string {
+  if (!existsSync(dbPath)) {
+    throw new Error(`Database does not exist at ${dbPath} — refusing to back up nothing`);
+  }
+  const dir = path.dirname(dbPath);
+  const base = path.basename(dbPath);
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = path.join(dir, `${base}.bak-${stamp}`);
+  copyFileSync(dbPath, backupPath);
+
+  for (const suffix of ['-wal', '-shm']) {
+    const sidecar = `${dbPath}${suffix}`;
+    if (existsSync(sidecar)) {
+      copyFileSync(sidecar, `${backupPath}${suffix}`);
+    }
+  }
+  return backupPath;
+}
+
+/**
+ * Delete the named failed-migration rows from `_prisma_migrations`. This
+ * is the equivalent of `prisma migrate resolve --rolled-back <name>` for
+ * each, but without needing the schema-engine binary. Only deletes rows
+ * that are actually still failed (defends against a stale name list).
+ * Returns the number of rows deleted.
+ *
+ * The caller is expected to have run `backupDatabase()` first. After this,
+ * the next `prisma migrate deploy` (on the desktop app's next launch)
+ * re-attempts the migration.
+ */
+export function repairFailedMigrations(
+  bunPath: string,
+  dbPath: string,
+  migrationNames: string[],
+): number {
+  if (migrationNames.length === 0) return 0;
+  if (!existsSync(dbPath)) {
+    throw new Error(`Cannot repair: database does not exist at ${dbPath}`);
+  }
+
+  const namesJson = JSON.stringify(migrationNames);
+  const script = `
+    import { Database } from 'bun:sqlite';
+    const names = ${namesJson};
+    if (!Array.isArray(names) || names.some(n => typeof n !== 'string')) {
+      console.error('Invalid migration name list');
+      process.exit(2);
+    }
+    try {
+      const db = new Database(process.env.DBP, { create: false, readwrite: true });
+      const placeholders = names.map(() => '?').join(',');
+      const stmt = db.prepare(
+        \`DELETE FROM _prisma_migrations WHERE migration_name IN (\${placeholders}) AND finished_at IS NULL AND rolled_back_at IS NULL\`
+      );
+      const result = stmt.run(...names);
+      console.log(JSON.stringify({ deleted: Number(result.changes) }));
+    } catch (e) {
+      console.error(String(e?.stack || e));
+      process.exit(3);
+    }
+  `;
+
+  const out = runBunScript<{ deleted: number }>(bunPath, dbPath, script);
+  return out.deleted;
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+
+export type DoctorStatus = 'healthy' | 'no-database' | 'repaired' | 'failed';
+
+export interface DoctorResult {
+  status: DoctorStatus;
+  /** Migrations found in a failed state before repair. */
+  detected: FailedMigration[];
+  /** Path of the backup written before repair, if any. */
+  backupPath?: string;
+  /** Names of migration rows actually cleared. */
+  cleared: string[];
+  /** Migrations still failed after the repair attempt (should be empty on success). */
+  remaining: FailedMigration[];
+  /** Human-readable summary of what happened. */
+  message: string;
+}
+
+export interface DoctorOptions {
+  bunPath: string;
+  dbPath: string;
+  /** Skip the pre-repair backup (default: false). Discouraged. */
+  skipBackup?: boolean;
+  /** Logger for progress lines (default: no-op). */
+  log?: (line: string) => void;
+}
+
+/**
+ * Run the full safe repair sequence against a local SQLite DB:
+ * detect → backup → clear stuck ledger rows → re-detect. Idempotent:
+ * a healthy DB is a no-op. Never re-runs `migrate deploy` (that's the
+ * desktop app's job on next launch).
+ */
+export function runDatabaseDoctor(opts: DoctorOptions): DoctorResult {
+  const log = opts.log ?? (() => {});
+  const { bunPath, dbPath } = opts;
+
+  if (!existsSync(dbPath)) {
+    return {
+      status: 'no-database',
+      detected: [],
+      cleared: [],
+      remaining: [],
+      message: `No database found at ${dbPath}. Nothing to repair — launch Shogo once to create it.`,
+    };
+  }
+
+  const detected = detectFailedMigrations(bunPath, dbPath);
+  if (detected.length === 0) {
+    return {
+      status: 'healthy',
+      detected: [],
+      cleared: [],
+      remaining: [],
+      message: 'No failed migrations detected — the local database looks healthy.',
+    };
+  }
+
+  log(`Found ${detected.length} failed migration(s): ${detected.map((m) => m.name).join(', ')}`);
+
+  let backupPath: string | undefined;
+  if (!opts.skipBackup) {
+    backupPath = backupDatabase(dbPath);
+    log(`Backed up database to ${backupPath}`);
+  }
+
+  const names = detected.map((m) => m.name);
+  const deleted = repairFailedMigrations(bunPath, dbPath, names);
+  log(`Cleared ${deleted} failed migration row(s).`);
+
+  const remaining = detectFailedMigrations(bunPath, dbPath);
+  const status: DoctorStatus = remaining.length === 0 ? 'repaired' : 'failed';
+  const message =
+    status === 'repaired'
+      ? 'Cleared the failed migration record. Relaunch Shogo to re-apply migrations cleanly.'
+      : `Repair incomplete — ${remaining.length} migration(s) still failed: ${remaining
+          .map((m) => m.name)
+          .join(', ')}.`;
+
+  return {
+    status,
+    detected,
+    backupPath,
+    cleared: names.slice(0, deleted),
+    remaining,
+    message,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Path / binary resolution (for the standalone CLI)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the desktop app's per-user data directory, mirroring
+ * Electron's `app.getPath('userData')` + the `data/` subdir used by
+ * apps/desktop/src/paths.ts. `productName` is "Shogo".
+ *
+ *   macOS:   ~/Library/Application Support/Shogo/data
+ *   Windows: %APPDATA%/Shogo/data        (Roaming)
+ *   Linux:   $XDG_CONFIG_HOME/Shogo/data  (or ~/.config/Shogo/data)
+ */
+export function resolveDesktopDataDir(): string {
+  const home = homedir();
+  const plat = platform();
+  let appData: string;
+  if (plat === 'darwin') {
+    appData = path.join(home, 'Library', 'Application Support');
+  } else if (plat === 'win32') {
+    appData = process.env.APPDATA ?? path.join(home, 'AppData', 'Roaming');
+  } else {
+    appData = process.env.XDG_CONFIG_HOME ?? path.join(home, '.config');
+  }
+  return path.join(appData, 'Shogo', 'data');
+}
+
+/** Default path of the desktop app's local SQLite database. */
+export function resolveDesktopDbPath(): string {
+  return path.join(resolveDesktopDataDir(), 'shogo.db');
+}
+
+/**
+ * Candidate locations of the `bun` binary the installed desktop app
+ * ships in its `resources/bun/` directory. Best-effort and
+ * platform-specific; missing entries are filtered out by the caller.
+ */
+function bundledBunCandidates(): string[] {
+  const plat = platform();
+  const exe = plat === 'win32' ? 'bun.exe' : 'bun';
+  const home = homedir();
+  const candidates: string[] = [];
+  if (plat === 'darwin') {
+    candidates.push(
+      path.join('/Applications', 'Shogo.app', 'Contents', 'Resources', 'bun', exe),
+      path.join(home, 'Applications', 'Shogo.app', 'Contents', 'Resources', 'bun', exe),
+    );
+  } else if (plat === 'linux') {
+    candidates.push(
+      path.join('/opt', 'Shogo', 'resources', 'bun', exe),
+      path.join('/usr', 'lib', 'shogo', 'resources', 'bun', exe),
+    );
+  }
+  // Windows installs under a version-stamped Squirrel dir
+  // (%LOCALAPPDATA%/shogo/app-<ver>/resources/bun/bun.exe) which we can't
+  // resolve without globbing; rely on --bun / PATH there.
+  return candidates;
+}
+
+/** True if the given binary can be executed and reports a version. */
+function bunIsUsable(bunPath: string): boolean {
+  try {
+    execFileSync(bunPath, ['--version'], { stdio: 'ignore', timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve a usable `bun` binary for the repair scripts, in priority order:
+ *   1. explicit `override` (the `--bun` flag)
+ *   2. the bun currently running this CLI (tarball release)
+ *   3. the desktop app's bundled bun
+ *   4. `bun` on PATH
+ * Returns null if none are usable.
+ */
+export function resolveBunBinary(override?: string): string | null {
+  if (override) return bunIsUsable(override) ? override : null;
+  if (process.versions.bun && process.execPath) return process.execPath;
+  for (const candidate of bundledBunCandidates()) {
+    if (existsSync(candidate) && bunIsUsable(candidate)) return candidate;
+  }
+  if (bunIsUsable('bun')) return 'bun';
+  return null;
+}

package/src/lib/process-manager.ts

@@ -20,7 +20,7 @@ import { PID_FILE, WORKER_LOG, WORKER_ERR, ensureHome } from './paths.ts';
 
 export interface SpawnOpts {
   entry: string;
-  runner: 'bun' | 'node';
+  runner: 'bun' | 'node' | 'tsx';
   env: NodeJS.ProcessEnv;
   cwd: string;
   detach?: boolean;

package/src/lib/runtime-install.ts

@@ -60,7 +60,7 @@ export type Channel = 'stable' | 'beta' | 'nightly';
  * Layout assumed by `buildAssetUrls()`:
  *   ${baseUrl}/v${version}/${assetName}
  */
-export const DEFAULT_RELEASES_BASE_URL = 'https://github.com/shogo-ai/shogo/releases/download';
+export const DEFAULT_RELEASES_BASE_URL = 'https://github.com/shogo-labs/shogo-ai/releases/download';
 
 export interface InstallOptions {
   /** Specific version to install (e.g. "0.1.0"). Default: latest in channel. */

package/src/lib/runtime-manager.ts

@@ -48,9 +48,43 @@ const PORT_RANGE_START = 37100;
 const PORT_RANGE_END = 37900;
 const API_PORT_OFFSET = 1; // API server port = agentPort + 1.
 
+/**
+ * Offset (from the agent port) of the workspace preview sidecar base.
+ *
+ * A workspace runtime serves N attached projects, each with its own preview
+ * sidecar (`server.tsx`) on `WORKSPACE_API_PORT_BASE + projectIndex`. We anchor
+ * that base at `agentPort + 2` (agentPort=+0, its API/skill server=+1) so every
+ * runtime gets a DISTINCT sidecar range. Before warm-multiple, only one runtime
+ * ran at a time and all of them could share the fixed default base (3101); now
+ * that several runtimes stay warm concurrently they were all binding 3101 and
+ * crash-looping (force-killing each other's leaked sidecars), which SIGKILLed
+ * the agent-runtime and restart-looped it.
+ */
+const PREVIEW_API_BASE_OFFSET = 2;
+
+/**
+ * Contiguous ports reserved per runtime: agent(+0), API/skill server(+1) and
+ * the preview sidecars (+2 … +RUNTIME_PORT_BLOCK-1). Reserving the whole block
+ * (rather than just the two eagerly-bound ports) guarantees no OTHER runtime's
+ * block overlaps this one's sidecar range. 16 supports up to 14 attached
+ * projects per workspace; the 800-port range still fits 50 such blocks (>> the
+ * default maxRuntimes of 10).
+ */
+const RUNTIME_PORT_BLOCK = 16;
+
 /** Default idle eviction window — unused runtimes get killed after this. */
 const RUNTIME_IDLE_MS = 15 * 60 * 1000;
 
+/**
+ * A runtime touched within this window is treated as "actively in use"
+ * (likely mid-stream — the agent-proxy/ai-proxy refresh `lastUsedAt` on
+ * every forwarded chunk) and is never picked as an LRU eviction victim
+ * by {@link WorkerRuntimeManager.enforceMaxRuntimes}, even when the cap
+ * is exceeded. Better to briefly run one over the cap than to SIGKILL a
+ * live chat stream out from under the user.
+ */
+const STREAM_ACTIVE_WINDOW_MS = 30 * 1000;
+
 /** Restart backoff bounds. */
 const RESTART_BACKOFF_BASE_MS = 1_000;
 const RESTART_BACKOFF_MAX_MS = 60_000;
@@ -222,6 +256,16 @@ export interface WorkerRuntimeManagerOptions {
    * Cloud workers leave this unset so the default still fires.
    */
   idleMs?: number;
+  /**
+   * Hard ceiling on the number of concurrently-running runtimes. Once
+   * exceeded, `ensureRunning` LRU-evicts the least-recently-used slot
+   * that has not been touched within {@link STREAM_ACTIVE_WINDOW_MS}
+   * (i.e. is not mid-stream). Pass `0`, a negative number, or a
+   * non-finite value to disable the cap (the historical behaviour —
+   * runtimes were then bounded only by idle eviction). Defaults to
+   * disabled when unset.
+   */
+  maxRuntimes?: number;
   /** Optional logger. Defaults to console. */
   logger?: Pick<Console, 'log' | 'warn' | 'error'>;
   /** Working directory for spawned runtimes. Defaults to OS tmpdir/shogo-runtime. */
@@ -629,12 +673,71 @@ export class WorkerRuntimeManager implements RuntimeResolver {
     slot.startPromise = this.doStart(slot);
     try {
       const r = await slot.startPromise;
+      // We just brought a (possibly new) runtime up — enforce the hard
+      // ceiling now so a busy multi-project session can't accumulate
+      // runtimes without bound. Never evicts the one we just started.
+      this.enforceMaxRuntimes(projectId);
       return this.snapshot(r);
     } finally {
       slot.startPromise = null;
     }
   }
 
+  /**
+   * Enforce {@link WorkerRuntimeManagerOptions.maxRuntimes} by LRU-evicting
+   * the least-recently-used running slot until the count is at/under the
+   * cap. Skips:
+   *   - the slot we just started (`keepProjectId`),
+   *   - any slot touched within {@link STREAM_ACTIVE_WINDOW_MS} (treated as
+   *     mid-stream — we never cut a live chat),
+   *   - non-running slots (starting/restarting/stopping/failed don't count
+   *     against the cap and aren't safe to tear down here).
+   *
+   * If every over-cap slot is actively streaming we stop early and let the
+   * count ride briefly over the cap rather than killing a live stream — the
+   * next ensureRunning (or idle eviction) reclaims it once it goes quiet.
+   *
+   * Fire-and-forget: eviction `stop()` is async (process-group kill +
+   * grace window) but we don't await it — the caller shouldn't block its
+   * own spawn on tearing down someone else's idle runtime.
+   */
+  private enforceMaxRuntimes(keepProjectId: string): void {
+    const cap = this.opts.maxRuntimes;
+    if (cap == null || !Number.isFinite(cap) || cap <= 0) return;
+
+    const now = Date.now();
+    const running = Array.from(this.runtimes.values()).filter((r) => r.status === 'running');
+    if (running.length <= cap) return;
+
+    // LRU order: oldest lastUsedAt first.
+    const candidates = running
+      .filter((r) => r.projectId !== keepProjectId && now - r.lastUsedAt >= STREAM_ACTIVE_WINDOW_MS)
+      .sort((a, b) => a.lastUsedAt - b.lastUsedAt);
+
+    let overBy = running.length - cap;
+    for (const victim of candidates) {
+      if (overBy <= 0) break;
+      const idleMs = now - victim.lastUsedAt;
+      this.log.log(
+        `[WorkerRuntimeManager] maxRuntimes=${cap} exceeded (${running.length} running) — ` +
+          `LRU-evicting ${victim.projectId} (idle ${Math.round(idleMs / 1000)}s)`,
+      );
+      void this.stop(victim.projectId).catch((err: any) => {
+        this.log.warn(
+          `[WorkerRuntimeManager] maxRuntimes eviction of ${victim.projectId} failed: ${err?.message ?? err}`,
+        );
+      });
+      overBy--;
+    }
+
+    if (overBy > 0) {
+      this.log.log(
+        `[WorkerRuntimeManager] maxRuntimes=${cap} still exceeded by ${overBy} after eviction pass — ` +
+          `remaining over-cap slots are mid-stream; will retry on next spawn / idle reap`,
+      );
+    }
+  }
+
   /**
    * Public entry point for tests + the `worker start` command to pre-warm
    * a project's workspace without spawning anything. Internally idempotent.
@@ -1170,6 +1273,12 @@ export class WorkerRuntimeManager implements RuntimeResolver {
       PORT: String(slot.agentPort),
       API_SERVER_PORT: String(slot.apiServerPort),
       SKILL_SERVER_PORT: String(slot.apiServerPort),
+      // Per-runtime base for workspace preview sidecars (server.tsx). Anchored
+      // at agentPort+2 so each warm runtime owns a distinct sidecar range and
+      // they can't all collide on the fixed default (3101) — the cause of the
+      // preview-manager crash-loop / agent-runtime SIGKILL restart storm when
+      // multiple projects are kept warm at once.
+      WORKSPACE_API_PORT_BASE: String(slot.agentPort + PREVIEW_API_BASE_OFFSET),
       NODE_ENV: 'production',
       SHOGO_CLOUD_URL: cfg.cloudUrl,
       SHOGO_API_URL: cfg.cloudUrl,
@@ -1355,12 +1464,23 @@ export class WorkerRuntimeManager implements RuntimeResolver {
     const maxAttempts = Math.min(range, 50);
     for (let i = 0; i < maxAttempts; i++) {
       const candidate = PORT_RANGE_START + Math.floor(Math.random() * range);
-      if (this.usedPorts.has(candidate) || this.usedPorts.has(candidate + API_PORT_OFFSET)) continue;
+      // Reserve a contiguous per-runtime block so the agent port, its API
+      // server AND every preview sidecar (WORKSPACE_API_PORT_BASE + idx) live
+      // in a range that no other warm runtime can overlap.
+      if (candidate + RUNTIME_PORT_BLOCK - 1 > PORT_RANGE_END) continue;
+      let blockFree = true;
+      for (let off = 0; off < RUNTIME_PORT_BLOCK; off++) {
+        if (this.usedPorts.has(candidate + off)) { blockFree = false; break; }
+      }
+      if (!blockFree) continue;
+      // Liveness-probe only the two ports we bind eagerly (agent + its API
+      // server). The sidecar ports are bound lazily by the agent-runtime and
+      // guarded by its own leaked-process force-kill, so probing the whole
+      // block here would just slow allocation down.
       const agentInUse = await this.isPortListening(candidate);
       const apiInUse = await this.isPortListening(candidate + API_PORT_OFFSET);
       if (agentInUse || apiInUse) continue;
-      this.usedPorts.add(candidate);
-      this.usedPorts.add(candidate + API_PORT_OFFSET);
+      for (let off = 0; off < RUNTIME_PORT_BLOCK; off++) this.usedPorts.add(candidate + off);
       return candidate;
     }
     throw new Error(
@@ -1370,8 +1490,7 @@ export class WorkerRuntimeManager implements RuntimeResolver {
 
   private releasePort(port: number): void {
     if (!port) return;
-    this.usedPorts.delete(port);
-    this.usedPorts.delete(port + API_PORT_OFFSET);
+    for (let off = 0; off < RUNTIME_PORT_BLOCK; off++) this.usedPorts.delete(port + off);
   }
 
   private async isPortListening(port: number): Promise<boolean> {

package/src/lib/tunnel.ts

@@ -102,7 +102,7 @@ type TunnelWebSocketConstructor = new (url: string, init: TunnelWebSocketInit) =
 
 type RuntimeWithBunWebSocketHeaders = typeof globalThis & {
   Bun?: unknown;
-  process?: { versions?: { bun?: string } };
+  process?: { versions?: { bun?: string; node?: string } };
 };
 
 interface HeartbeatResponse {
@@ -116,8 +116,8 @@ export class TunnelWebSocketHeaderSupportError extends Error {
   code = 'TUNNEL_WS_HEADERS_UNSUPPORTED' as const;
   constructor() {
     super(
-      'Tunnel WebSocket auth requires Bun WebSocket header support. ' +
-        'This runtime does not advertise Bun, so Authorization headers may be dropped.',
+      'Tunnel WebSocket auth requires a runtime with WebSocket header support (Bun or Node >= 21). ' +
+        'Current runtime does not support WebSocket constructor headers.',
     );
     this.name = 'TunnelWebSocketHeaderSupportError';
   }
@@ -231,7 +231,15 @@ export class WorkerTunnel {
   private supportsWebSocketConstructorHeaders(
     runtime: RuntimeWithBunWebSocketHeaders = globalThis as RuntimeWithBunWebSocketHeaders,
   ): boolean {
-    return typeof runtime.Bun !== 'undefined' || typeof runtime.process?.versions?.bun === 'string';
+    if (typeof runtime.Bun !== 'undefined' || typeof runtime.process?.versions?.bun === 'string') return true;
+    // Node 21+ ships WebSocket (via undici) with header support in the constructor.
+    // Detect by checking for Node >= 21 (the version that made WebSocket a global).
+    const nodeVersion = runtime.process?.versions?.node;
+    if (nodeVersion) {
+      const major = parseInt(nodeVersion.split('.')[0] ?? '0', 10);
+      if (major >= 21) return true;
+    }
+    return false;
   }
 
   private createTunnelWebSocket(