@shogo-ai/worker 2.3.12 → 2.4.0

package/src/lib/resource-limits.ts

@@ -26,8 +26,13 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 export interface RuntimeResourceLimits {
-  /** Per-project RAM ceiling in MB. Always > 0 when limits are active. */
+  /** Per-project RAM ceiling in MB for the runtime's OWN processes. Always > 0
+   *  when limits are active. Not the budget for the commands an agent runs. */
   memoryMB: number;
+  /** Hard OS cap for the whole process tree in MB: {@link memoryMB} plus the
+   *  agent-command budget. The exec guard (which writes a note) must trip before
+   *  the kernel (which writes nothing), so the kernel cap has to sit above it. */
+  osMemoryMB: number;
   /** CPU ceiling as percent of ONE core (100 = one full core). 0 = no cap. */
   cpuPercent: number;
   /** Max tasks/pids in the group (cgroup pids.max). */
@@ -39,10 +44,47 @@ type Logger = Pick<Console, 'log' | 'warn' | 'error'>;
 /** cgroup CPU period in microseconds (100ms), the systemd/cgroup default. */
 const CPU_PERIOD_US = 100_000;
 
+/** `host-limits.json`, as published by the desktop app (SHO-203). */
+export interface HostLimitsFile {
+  /** MB the agent's `exec` commands may use. */
+  execMemoryMB?: number;
+  /** Total physical RAM of the machine, for messages. */
+  totalMemMB?: number;
+  source?: 'auto' | 'settings';
+}
+
+/** Parse `host-limits.json`. Missing or malformed reads as `null`. */
+export function readHostLimitsFile(path: string): HostLimitsFile | null {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as HostLimitsFile;
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The command budget from the environment: an explicit `SHOGO_EXEC_MEMORY_MB`
+ * (headless worker, tests) wins, otherwise the watched `host-limits.json`.
+ * 0 = no budget known.
+ */
+export function resolveExecMemoryMB(env: NodeJS.ProcessEnv): number {
+  const explicit = parseInt(env.SHOGO_EXEC_MEMORY_MB || '', 10);
+  if (Number.isFinite(explicit) && explicit > 0) return explicit;
+  if (!env.SHOGO_HOST_LIMITS_FILE) return 0;
+  const mb = readHostLimitsFile(env.SHOGO_HOST_LIMITS_FILE)?.execMemoryMB;
+  return typeof mb === 'number' && Number.isFinite(mb) && mb > 0 ? Math.floor(mb) : 0;
+}
+
 /**
  * Resolve the active resource limits from the environment. Returns `null` when
  * no ceiling is configured (`RUNTIME_MEMORY_MB` unset or <= 0), which disables
  * all enforcement for backwards compatibility.
+ *
+ * `memoryMB` stays the runtime's own leak ceiling (the RSS watchdog and the heap
+ * cap use it). `osMemoryMB` is the kernel-level cap for the whole tree, raised
+ * by the agent-command budget so a big `exec` command is stopped by the guard —
+ * which writes an actionable note — instead of silently OOM-killed (SHO-203).
  */
 export function resolveResourceLimits(env: NodeJS.ProcessEnv): RuntimeResourceLimits | null {
   const mb = parseInt(env.RUNTIME_MEMORY_MB || '', 10);
@@ -54,7 +96,7 @@ export function resolveResourceLimits(env: NodeJS.ProcessEnv): RuntimeResourceLi
   const tasksRaw = parseInt(env.RUNTIME_TASKS_MAX || '', 10);
   const tasksMax = Number.isFinite(tasksRaw) && tasksRaw > 0 ? tasksRaw : 4096;
 
-  return { memoryMB: mb, cpuPercent, tasksMax };
+  return { memoryMB: mb, osMemoryMB: mb + resolveExecMemoryMB(env), cpuPercent, tasksMax };
 }
 
 /**
@@ -98,6 +140,11 @@ export function hasSystemdRun(): boolean {
  * command untouched (`wrapped: false`) on non-Linux or when systemd-run is
  * absent — the caller then falls back to {@link attachDirectCgroup} or the
  * watchdog.
+ *
+ * The cap is `limits.osMemoryMB` (runtime ceiling + agent-command budget): the
+ * scope holds the runtime's own processes *and* the `exec` shells it spawns, so
+ * sized to the runtime ceiling alone it killed a 22.5 GB command on a 128 GB
+ * machine with no message (SHO-203).
  */
 export function wrapSpawnForCgroup(opts: {
   command: string;
@@ -112,10 +159,10 @@ export function wrapSpawnForCgroup(opts: {
   }
 
   const props = [
-    '-p', `MemoryMax=${limits.memoryMB}M`,
+    '-p', `MemoryMax=${limits.osMemoryMB}M`,
     // MemoryHigh throttles + reclaims before the hard OOM at MemoryMax, so a
     // spiky build is slowed rather than instantly killed.
-    '-p', `MemoryHigh=${Math.max(128, Math.floor(limits.memoryMB * 0.9))}M`,
+    '-p', `MemoryHigh=${memoryHighMB(limits.osMemoryMB)}M`,
     '-p', `TasksMax=${limits.tasksMax}`,
   ];
   if (limits.cpuPercent > 0) props.push('-p', `CPUQuota=${limits.cpuPercent}%`);
@@ -131,10 +178,20 @@ export function wrapSpawnForCgroup(opts: {
     command,
     ...args,
   ];
-  logger?.log(`[resource-limits] wrapping spawn in systemd scope ${scopeName} (MemoryMax=${limits.memoryMB}M)`);
+  logger?.log(`[resource-limits] wrapping spawn in systemd scope ${scopeName} (MemoryMax=${limits.osMemoryMB}M)`);
   return { command: 'systemd-run', args: wrappedArgs, wrapped: true };
 }
 
+/** Soft cap for a hard cap: 10% below, so reclaim starts before the OOM. */
+function memoryHighMB(memoryMB: number): number {
+  return Math.max(128, Math.floor(memoryMB * 0.9));
+}
+
+/** The cgroup v2 directory {@link attachDirectCgroup} puts a runtime in. */
+export function directCgroupDir(pid: number): string {
+  return join('/sys/fs/cgroup', 'shogo', `rt-${pid}`);
+}
+
 /**
  * Fallback for Linux hosts without systemd: write a cgroup v2 directly and move
  * `pid` (plus its future children) into it. Best-effort — returns `false` when
@@ -153,10 +210,10 @@ export function attachDirectCgroup(opts: {
   // cgroup v2 unified hierarchy exposes cgroup.controllers at the root.
   if (!existsSync(join(root, 'cgroup.controllers'))) return false;
 
-  const dir = join(root, 'shogo', `rt-${pid}`);
+  const dir = directCgroupDir(pid);
   try {
     mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, 'memory.max'), String(limits.memoryMB * 1024 * 1024));
+    writeFileSync(join(dir, 'memory.max'), String(limits.osMemoryMB * 1024 * 1024));
     if (limits.cpuPercent > 0) {
       const quota = Math.floor((limits.cpuPercent / 100) * CPU_PERIOD_US);
       writeFileSync(join(dir, 'cpu.max'), `${quota} ${CPU_PERIOD_US}`);
@@ -164,7 +221,7 @@ export function attachDirectCgroup(opts: {
     try { writeFileSync(join(dir, 'pids.max'), String(limits.tasksMax)); } catch { /* controller may be absent */ }
     // Moving the pid in also captures children forked after this point.
     writeFileSync(join(dir, 'cgroup.procs'), String(pid));
-    logger?.log(`[resource-limits] attached pid ${pid} to cgroup ${dir} (memory.max=${limits.memoryMB}M)`);
+    logger?.log(`[resource-limits] attached pid ${pid} to cgroup ${dir} (memory.max=${limits.osMemoryMB}M)`);
     return true;
   } catch (err: any) {
     logger?.warn(`[resource-limits] direct cgroup attach failed for pid ${pid}: ${err?.message ?? err}`);
@@ -172,6 +229,92 @@ export function attachDirectCgroup(opts: {
   }
 }
 
+// ─── Live re-apply (SHO-203) ─────────────────────────────────────────
+
+export interface LiveMemoryCapOptions {
+  /** Runtime process group id, used for a direct cgroup. */
+  pid?: number | null;
+  /** `systemd-run --scope` unit name, when the spawn was cgroup-wrapped. */
+  scopeName?: string | null;
+  limits: RuntimeResourceLimits;
+  logger?: Logger;
+}
+
+/** Swappable effects, so the generated `systemctl` args / file write are testable. */
+export interface LiveMemoryCapDeps {
+  platform?: NodeJS.Platform;
+  run?: (command: string, args: string[]) => void;
+  writeFile?: (path: string, data: string) => void;
+  exists?: (path: string) => boolean;
+}
+
+/**
+ * Re-apply the memory cap to a runtime that is already running, after the
+ * agent-command budget changed. Without this a raised budget would only land
+ * on the next spawn — an app restart — which is exactly the complaint in
+ * SHO-203.
+ *
+ *   - Linux + systemd scope: `systemctl --user set-property --runtime`.
+ *   - Linux + direct cgroup: rewrite `memory.max` (and `memory.high`).
+ *   - Windows: the Job Object's limit is fixed at assign time; there is no API
+ *     to change it in place, so it lands on the next spawn (the RSS watchdog
+ *     covers the gap).
+ *   - macOS: the watchdog reads the budget from the limits file itself, so
+ *     nothing to do here.
+ */
+export function applyLiveMemoryCap(
+  opts: LiveMemoryCapOptions,
+  deps: LiveMemoryCapDeps = {},
+): boolean {
+  const platform = deps.platform ?? process.platform;
+  const { limits, logger } = opts;
+  if (platform === 'win32') {
+    logger?.log('[resource-limits] Job Object memory limit applies on the next runtime spawn');
+    return false;
+  }
+  if (platform !== 'linux') return false;
+
+  if (opts.scopeName) {
+    const args = [
+      '--user',
+      'set-property',
+      '--runtime',
+      opts.scopeName,
+      `MemoryMax=${limits.osMemoryMB}M`,
+      `MemoryHigh=${memoryHighMB(limits.osMemoryMB)}M`,
+    ];
+    if (deps.run) {
+      deps.run('systemctl', args);
+      return true;
+    }
+    execFile('systemctl', args, { timeout: 5000 }, (err) => {
+      if (err) {
+        logger?.warn(`[resource-limits] set-property ${opts.scopeName} failed: ${err.message}`);
+      } else {
+        logger?.log(`[resource-limits] ${opts.scopeName} MemoryMax=${limits.osMemoryMB}M`);
+      }
+    });
+    return true;
+  }
+
+  if (!opts.pid) return false;
+  const dir = directCgroupDir(opts.pid);
+  const exists = deps.exists ?? existsSync;
+  const write = deps.writeFile ?? writeFileSync;
+  try {
+    if (!exists(join(dir, 'memory.max'))) return false;
+    write(join(dir, 'memory.max'), String(limits.osMemoryMB * 1024 * 1024));
+    if (exists(join(dir, 'memory.high'))) {
+      write(join(dir, 'memory.high'), String(memoryHighMB(limits.osMemoryMB) * 1024 * 1024));
+    }
+    logger?.log(`[resource-limits] raised cgroup ${dir} memory.max to ${limits.osMemoryMB}M`);
+    return true;
+  } catch (err: any) {
+    logger?.warn(`[resource-limits] live cgroup update failed for ${dir}: ${err?.message ?? err}`);
+    return false;
+  }
+}
+
 // ─── Windows: Job Object (optional native helper) ────────────────────
 
 /**
@@ -203,11 +346,11 @@ export function tryAttachJobObject(opts: {
     };
     if (typeof helper.limitProcess !== 'function') return false;
     const ok = helper.limitProcess(pid, {
-      memoryBytes: limits.memoryMB * 1024 * 1024,
+      memoryBytes: limits.osMemoryMB * 1024 * 1024,
       killOnClose: true,
     });
     if (ok) {
-      logger?.log(`[resource-limits] attached pid ${pid} to Job Object (${limits.memoryMB}M)`);
+      logger?.log(`[resource-limits] attached pid ${pid} to Job Object (${limits.osMemoryMB}M)`);
     }
     return ok;
   } catch {

package/src/lib/runtime-manager.ts

@@ -33,7 +33,7 @@
  */
 import { type ChildProcess, spawn, spawnSync } from './child-process.ts';
 import { createHmac, randomBytes } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, rmSync, unwatchFile, watchFile } from 'node:fs';
 import { createConnection } from 'node:net';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -41,6 +41,7 @@ import { resolveRuntime, type ResolvedRuntime } from './runtime-resolver.ts';
 import {
   RssWatchdog,
   applyHeapEnvCap,
+  applyLiveMemoryCap,
   attachDirectCgroup,
   readExecPidsFile,
   resolveResourceLimits,
@@ -538,6 +539,9 @@ interface InternalRuntime {
    * or when no limit is configured. Stopped on exit/stop.
    */
   limitWatchdog: RssWatchdog | null;
+  /** `systemd-run --scope` unit name when the spawn was cgroup-wrapped, so a
+   *  later budget change can be re-applied to the live scope (SHO-203). */
+  cgroupScope?: string | null;
   lastError?: string;
   spawnConfig: ProjectSpawnConfig;
   /**
@@ -688,6 +692,9 @@ export class WorkerRuntimeManager implements RuntimeResolver {
   /** Timer that refreshes every running runtime's cached activity sample. */
   private activityTimer: ReturnType<typeof setInterval> | null = null;
 
+  /** `host-limits.json` this manager watches for live limit changes (SHO-203). */
+  private hostLimitsFile: string | null = null;
+
   constructor(opts: WorkerRuntimeManagerOptions = {}) {
     this.opts = opts;
     this.log = opts.logger ?? console;
@@ -697,6 +704,7 @@ export class WorkerRuntimeManager implements RuntimeResolver {
     // time — see runtime-activity.ts. Unref'd so it never holds the process
     // open.
     this.ensureActivitySampler();
+    this.watchHostLimits();
   }
 
   /**
@@ -1339,6 +1347,7 @@ export class WorkerRuntimeManager implements RuntimeResolver {
 
   async stopAll(signal: NodeJS.Signals = 'SIGTERM'): Promise<void> {
     this.stopped = true;
+    this.unwatchHostLimits();
     if (this.activityTimer) {
       clearInterval(this.activityTimer);
       this.activityTimer = null;
@@ -1420,18 +1429,22 @@ export class WorkerRuntimeManager implements RuntimeResolver {
     let command = baseSpawn.command;
     let args = baseSpawn.args;
     let cgroupWrapped = false;
+    let cgroupScope: string | null = null;
     if (limits) {
+      const scopeName = `shogo-rt-${slot.projectId.slice(0, 8)}-${Date.now().toString(36)}`;
       const wrapped = wrapSpawnForCgroup({
         command: baseSpawn.command,
         args: baseSpawn.args,
         limits,
-        scopeName: `shogo-rt-${slot.projectId.slice(0, 8)}-${Date.now().toString(36)}`,
+        scopeName,
         logger: this.log,
       });
       command = wrapped.command;
       args = wrapped.args;
       cgroupWrapped = wrapped.wrapped;
+      cgroupScope = wrapped.wrapped ? scopeName : null;
     }
+    slot.cgroupScope = cgroupScope;
 
     this.log.log(
       `[WorkerRuntimeManager] Spawning agent-runtime for ${slot.projectId} ` +
@@ -1605,6 +1618,60 @@ export class WorkerRuntimeManager implements RuntimeResolver {
     return this.resolvedLimits;
   }
 
+  /**
+   * Watch `host-limits.json` so a Settings change to the agent-command budget
+   * lands on the app that is already running (SHO-203). An env var can only
+   * change at spawn; a file can change now. `fs.watchFile` polls, which is why
+   * it also picks the file up on a fresh install — no IPC plumbing needed.
+   */
+  private watchHostLimits(): void {
+    const file = (this.opts.env ?? process.env).SHOGO_HOST_LIMITS_FILE;
+    if (!file || this.hostLimitsFile) return;
+    this.hostLimitsFile = file;
+    watchFile(file, { interval: 2000 }, () => this.applyHostLimitsChange());
+  }
+
+  /** Re-resolve the limits and push the new OS cap onto every live runtime. */
+  private applyHostLimitsChange(): void {
+    const env = this.opts.env ?? process.env;
+    let limits: RuntimeResourceLimits | null;
+    try {
+      limits = resolveResourceLimits(env);
+    } catch (err: any) {
+      this.log.warn(`[WorkerRuntimeManager] host limits re-read failed: ${err?.message ?? err}`);
+      return;
+    }
+    // Future spawns read the memo, so keep it in step with the file.
+    this.resolvedLimits = limits;
+    if (!limits) return;
+    const live = [...this.runtimes.values()].filter((slot) => slot.pid && slot.status !== 'stopped');
+    if (live.length === 0) return;
+    this.log.log(
+      `[WorkerRuntimeManager] agent-command budget changed — memory cap now ${limits.osMemoryMB}M ` +
+        `(${limits.memoryMB}M runtime + ${limits.osMemoryMB - limits.memoryMB}M commands)`,
+    );
+    for (const slot of live) {
+      try {
+        applyLiveMemoryCap({
+          pid: slot.pid,
+          scopeName: slot.cgroupScope ?? null,
+          limits,
+          logger: this.log,
+        });
+      } catch (err: any) {
+        this.log.warn(
+          `[WorkerRuntimeManager] live memory cap for ${slot.projectId} failed: ${err?.message ?? err}`,
+        );
+      }
+    }
+  }
+
+  private unwatchHostLimits(): void {
+    if (!this.hostLimitsFile) return;
+    unwatchFile(this.hostLimitsFile);
+    this.hostLimitsFile = null;
+  }
+
   /**
    * Apply the strongest available OS-level cap to a freshly-spawned runtime,
    * or start the RSS watchdog as a fallback. Called right after spawn so most
@@ -1803,7 +1870,15 @@ export class WorkerRuntimeManager implements RuntimeResolver {
       // the runtime publishes their PIDs so the watchdog leaves them out, and
       // budgets them itself, stopping the largest command instead of the turn.
       env.SHOGO_EXEC_PIDS_FILE = this.execPidsFile(slot);
-      env.SHOGO_EXEC_MEMORY_MB ??= String(limits.memoryMB);
+      const limitSource = this.opts.env ?? process.env;
+      if (limitSource.SHOGO_HOST_LIMITS_FILE) {
+        // Desktop: the budget is the user's setting, published in a file the
+        // runtime watches, so it changes on a running app (SHO-203). Never
+        // default it to the runtime ceiling — that is the bug this fixed.
+        env.SHOGO_HOST_LIMITS_FILE = limitSource.SHOGO_HOST_LIMITS_FILE;
+      } else {
+        env.SHOGO_EXEC_MEMORY_MB ??= String(limits.memoryMB);
+      }
     }
 
     return env;

package/src/lib/tunnel-host.ts

@@ -0,0 +1,253 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Main-thread side of the tunnel Worker (SHO-185 §5)
+ *
+ * `startTunnelInWorker()` puts `WorkerTunnel` on its own thread and answers the
+ * questions it cannot answer itself: which local URL a path maps to, the runtime
+ * token for a project, and — once per heartbeat — which runtimes are up. The
+ * socket, its timers and its local `fetch`es never touch this thread, so a busy
+ * local API cannot cost the machine its connection any more.
+ */
+
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import type { ResolveRejection, RuntimeResolver } from './tunnel'
+import type { HostProjectStatus, HostReply, WorkerEvent, WorkerRequest } from './tunnel-worker'
+
+/**
+ * How long the worker gets to answer `ready` before it is written off.
+ *
+ * The worker posts `ready` from its `init` handler, before it touches the
+ * network, so this is only ever spent on a worker that never came up at all
+ * (crashed on load, wrong entry file, a runtime that quietly refuses to spawn
+ * one). A tunnel that is slow to connect is not slow to be ready.
+ */
+const READY_TIMEOUT_MS = 10_000
+
+/** This module's directory: `resources/bundle/` once packaged, `src/lib/` in a checkout. */
+const HOST_DIR = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * The Worker entry file that sits next to this module.
+ *
+ * A source checkout has only `tunnel-worker.ts`; the desktop ships the compiled
+ * `resources/bundle/tunnel-worker.js` (see `apps/desktop/scripts/bundle-api.mjs`)
+ * and no source tree at all. Relative to `import.meta.url` — which inside
+ * `resources/bundle/api.js` is the bundle itself — `new URL('./tunnel-worker.ts')`
+ * could only ever name the checkout, so the packaged app asked for a `.ts` file
+ * that was never shipped, the worker never started, and the tunnel vanished.
+ *
+ * `SHOGO_TUNNEL_WORKER_PATH` overrides the search for packagers that relocate
+ * the bundle.
+ */
+export function resolveTunnelWorkerEntry(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.SHOGO_TUNNEL_WORKER_PATH?.trim()
+  if (override) return override
+
+  const candidates = [join(HOST_DIR, 'tunnel-worker.js'), join(HOST_DIR, 'tunnel-worker.ts')]
+  const found = candidates.find((candidate) => existsSync(candidate))
+  if (found) return found
+
+  throw new Error(
+    `no tunnel worker entry next to ${HOST_DIR} (looked for ${candidates.join(', ')}); ` +
+      `packaging must ship the tunnel-worker build output beside the API bundle`,
+  )
+}
+
+export interface TunnelHostOptions {
+  apiKey: string
+  cloudUrl: string
+  name?: string
+  kind?: string
+  wsUrlOverride?: string
+  /** Everything the tunnel asks about the local machine. */
+  resolver: RuntimeResolver
+  logger?: Pick<Console, 'log' | 'warn' | 'error'>
+  onAuthRevoked?: (reason: string) => void
+  /** Called when the cloud tells us this machine's instance id (or forgets it). */
+  onInstanceId?: (instanceId: string | null) => void
+  /** Called when the socket's connected state changes. */
+  onConnection?: (connected: boolean) => void
+  /** The worker died (on load or later). The host is not usable after this. */
+  onWorkerError?: (error: Error) => void
+  /** Overrides the readiness deadline. Tests only. */
+  readyTimeoutMs?: number
+}
+
+export interface TunnelHost {
+  stop(): void
+  instanceId(): string | null
+  isConnected(): boolean
+  /** Resolves once the worker has the tunnel running. */
+  ready(): Promise<void>
+}
+
+/**
+ * Start the tunnel on its own thread.
+ *
+ * Throws if the worker cannot be created (a bundle without the entry file, a
+ * runtime that will not spawn one), which is the caller's cue to fall back to an
+ * in-process tunnel rather than lose remote control entirely. A worker that is
+ * created but never answers `ready` rejects `ready()` for the same reason — the
+ * throw alone is not enough, because a missing entry file does not always fail
+ * synchronously.
+ */
+export function startTunnelInWorker(options: TunnelHostOptions): TunnelHost {
+  const log = options.logger ?? console
+  const entry = resolveTunnelWorkerEntry()
+  // The web Worker API, which is what Bun implements (and what the worker file
+  // uses on its side with `self.postMessage`). `node:worker_threads` needs
+  // `parentPort` instead, and mixing the two silently never delivers a message.
+  const worker = new Worker(pathToFileURL(entry))
+
+  const readyTimeoutMs = options.readyTimeoutMs ?? READY_TIMEOUT_MS
+  let instanceId: string | null = null
+  let connected = false
+  let stopped = false
+  let readySettled = false
+  let settleReady: () => void = () => {}
+  let failReady: (error: Error) => void = () => {}
+  const ready = new Promise<void>((resolve, reject) => {
+    settleReady = resolve
+    failReady = reject
+  })
+  // Nobody is obliged to await `ready()`; an unobserved rejection would take the
+  // process down instead of letting the caller fall back.
+  void ready.catch(() => {})
+
+  const readyTimer = setTimeout(() => {
+    failReady(new Error(`tunnel worker (${entry}) did not answer ready within ${readyTimeoutMs}ms`))
+  }, readyTimeoutMs)
+  void ready.then(
+    () => {
+      readySettled = true
+      clearTimeout(readyTimer)
+    },
+    () => {
+      readySettled = true
+      clearTimeout(readyTimer)
+    },
+  )
+
+  /** What the last `resolve` decided, so a rejection needs no extra round trip. */
+  const rejections = new Map<string, ResolveRejection>()
+
+  worker.onmessage = (event: MessageEvent) => {
+    const data = event.data as any
+    if (!data || typeof data !== 'object') return
+
+    if (data.type === 'ready') {
+      settleReady()
+      return
+    }
+
+    if (data.type === 'log') {
+      const sink = data.level === 'error' ? log.error : data.level === 'warn' ? log.warn : log.log
+      sink.call(log, data.message)
+      return
+    }
+
+    if (data.type === 'event') {
+      if (data.name === 'instance') {
+        instanceId = data.instanceId ?? null
+        options.onInstanceId?.(instanceId)
+      } else if (data.name === 'connection') {
+        connected = Boolean(data.connected)
+        options.onConnection?.(connected)
+      } else if (data.name === 'auth-revoked') {
+        options.onAuthRevoked?.(String(data.reason ?? 'auth revoked'))
+      }
+      return
+    }
+
+    void answer(data as WorkerRequest)
+  }
+
+  worker.onerror = (event: any) => {
+    const message = event?.message ?? event
+    log.error(`[TunnelHost] worker error: ${message}`)
+    const error = new Error(`tunnel worker failed: ${message}`)
+    // A worker that dies on load never posts `ready`. Reject now so the caller
+    // can fall back instead of waiting out the whole deadline.
+    if (!readySettled) failReady(error)
+    // A worker that dies later leaves a socket nobody is watching, which looks
+    // exactly like an offline machine. Same answer: hand it back to the caller.
+    options.onWorkerError?.(error)
+  }
+
+  async function answer(request: WorkerRequest): Promise<void> {
+    const resolver = options.resolver
+    try {
+      if (request.type === 'resolve') {
+        const url = await resolver.resolveLocalUrl(request.path, request.projectId)
+        const rejection =
+          url === null
+            ? await Promise.resolve(resolver.describeRejection?.(request.path, request.projectId))
+            : undefined
+        if (rejection) rejections.set(`${request.path}|${request.projectId ?? ''}`, rejection)
+        reply({ type: 'resolved', id: request.id, url, rejection })
+        return
+      }
+
+      if (request.type === 'token') {
+        const token = await resolver.deriveRuntimeToken(request.projectId)
+        reply({ type: 'token-result', id: request.id, token })
+        return
+      }
+
+      if (request.type === 'refresh') {
+        const projects: HostProjectStatus[] = resolver.getActiveProjects().map((projectId) => {
+          const status = resolver.status(projectId)
+          return { projectId, status: status?.status ?? 'unknown', agentPort: status?.agentPort }
+        })
+        reply({
+          type: 'refresh-result',
+          id: request.id,
+          projects,
+          rejections: Object.fromEntries(rejections),
+        })
+        return
+      }
+
+      if (request.type === 'machineSnapshot') {
+        const snapshot = (await resolver.machineSnapshot?.()) ?? null
+        reply({ type: 'machine-snapshot-result', id: request.id, snapshot })
+      }
+    } catch (error: any) {
+      log.warn(`[TunnelHost] ${request.type} failed: ${error?.message ?? error}`)
+      if (request.type === 'resolve') reply({ type: 'resolved', id: request.id, url: null })
+      else if (request.type === 'token') reply({ type: 'token-result', id: request.id, token: null })
+      else if (request.type === 'refresh') reply({ type: 'refresh-result', id: request.id, projects: [] })
+      else reply({ type: 'machine-snapshot-result', id: request.id, snapshot: null })
+    }
+  }
+
+  function reply(message: HostReply): void {
+    if (stopped) return
+    worker.postMessage(message)
+  }
+
+  worker.postMessage({
+    type: 'init',
+    config: {
+      apiKey: options.apiKey,
+      cloudUrl: options.cloudUrl,
+      name: options.name,
+      kind: options.kind,
+      wsUrlOverride: options.wsUrlOverride,
+    },
+  })
+
+  return {
+    stop() {
+      stopped = true
+      clearTimeout(readyTimer)
+      void worker.terminate()
+    },
+    instanceId: () => instanceId,
+    isConnected: () => connected,
+    ready: () => ready,
+  }
+}