@runuai/host 0.9.77 → 0.9.79

package/images/standard/container/uai-init

@@ -419,9 +419,25 @@ install_folder_deps() {
 
 reject_workspace_runtime_shadow || exit 78
 
-if [ -d "$WORKSPACE" ] && [ -f "$RUNTIME_PROJECTS" ] \
-   && [ ! -L "$RUNTIME_PROJECTS" ]; then
-  seen_runtime_projects="|"
+# ADR-122: dependency installs leave the task-start critical path. The loop
+# below runs in a DETACHED background process so uai-init (and with it
+# task-up) returns as soon as the cheap, provable work is done — the editor
+# and the agents start immediately, warm or cold. Progress is observable in
+# the workspace itself:
+#
+#   $WORKSPACE/.uai/init/deps-status   running | done | failed | authority-violation
+#   $WORKSPACE/.uai/init/deps.log      the full install transcript
+#
+# The runtime-authority posture narrows deliberately: the synchronous
+# workspace-shadow proofs above and below still exit 78 (task-up
+# quarantines), but a shadow that APPEARS MID-INSTALL can no longer stop the
+# task — agents are already running by then, and an agent could author the
+# same shadow a second later anyway. The runner still refuses to run any
+# further dependency command under a shadowed root and records
+# `authority-violation`; the shared asdf volume stays read-only-proven
+# regardless.
+run_workspace_installs() {
+  local seen_runtime_projects="|" project_slug folder git_marker
   while IFS= read -r project_slug || [ -n "$project_slug" ]; do
     if [[ ! "$project_slug" =~ ^[a-z0-9-]{1,64}$ ]]; then
       log "warning: unsafe runtime-project allowlist entry — skipping"
@@ -441,11 +457,67 @@ if [ -d "$WORKSPACE" ] && [ -f "$RUNTIME_PROJECTS" ] \
       log "warning: allowlisted project $project_slug is not a safe Git worktree — skipping"
       continue
     fi
-    reject_workspace_runtime_shadow || exit 78
+    if ! reject_workspace_runtime_shadow; then
+      printf 'authority-violation\n' > "$deps_status_file"
+      return 78
+    fi
     # Run in a subshell so a `cd` (or a failing command under the relaxed
     # error mode) in one folder never leaks into the next.
     ( install_folder_deps "$folder" )
   done < "$RUNTIME_PROJECTS"
+  return 0
+}
+
+if [ -d "$WORKSPACE" ] && [ -f "$RUNTIME_PROJECTS" ] \
+   && [ ! -L "$RUNTIME_PROJECTS" ]; then
+  deps_state_dir="$WORKSPACE/.uai/init"
+  deps_status_file="$deps_state_dir/deps-status"
+  deps_log_file="$deps_state_dir/deps.log"
+  deps_lock_dir="$deps_state_dir/deps.lock.d"
+  mkdir -p "$deps_state_dir"
+
+  # One runner at a time. uai-init is re-runnable (task-up retry, recovery),
+  # and each re-run SHOULD refresh dependencies — but never concurrently.
+  # mkdir is the portable atomic lock; a pid that no longer answers marks a
+  # crashed runner whose lock is stale and may be stolen.
+  deps_spawn=1
+  if mkdir "$deps_lock_dir" 2>/dev/null; then
+    # Hold the lock as ourselves until the runner's pid replaces it, so a
+    # concurrent uai-init never reads an empty pid file as a stale lock.
+    printf '%s\n' "$$" > "$deps_lock_dir/pid"
+  else
+    deps_holder=$(cat "$deps_lock_dir/pid" 2>/dev/null || true)
+    if [ -n "$deps_holder" ] && kill -0 "$deps_holder" 2>/dev/null; then
+      log "dependency install already running (pid $deps_holder) — leaving it be"
+      deps_spawn=0
+    else
+      rm -rf "$deps_lock_dir"
+      if mkdir "$deps_lock_dir" 2>/dev/null; then
+        printf '%s\n' "$$" > "$deps_lock_dir/pid"
+      else
+        log "warning: could not acquire the dependency install lock — skipping installs"
+        deps_spawn=0
+      fi
+    fi
+  fi
+  if [ "$deps_spawn" -eq 1 ]; then
+    printf 'running\n' > "$deps_status_file"
+    log "installing workspace dependencies in the background (status: $deps_status_file, log: $deps_log_file)"
+    (
+      trap 'rm -rf "$deps_lock_dir"' EXIT
+      deps_rc=0
+      run_workspace_installs || deps_rc=$?
+      if [ "$deps_rc" -eq 0 ]; then
+        printf 'done\n' > "$deps_status_file"
+        log "workspace dependency install complete"
+      elif [ "$deps_rc" -ne 78 ]; then
+        printf 'failed\n' > "$deps_status_file"
+        log "workspace dependency install failed (exit $deps_rc)"
+      fi
+    ) >>"$deps_log_file" 2>&1 </dev/null &
+    printf '%s\n' "$!" > "$deps_lock_dir/pid"
+    disown
+  fi
 elif [ ! -d "$WORKSPACE" ]; then
   log "workspace $WORKSPACE missing — scratchpad/no-project task, skipping installs"
 else

package/lib/machine-gateway-tunnel.ts

@@ -0,0 +1,166 @@
+/**
+ * ADR-121: the MCP gateway reverse tunnel for machine tasks.
+ *
+ * Containers reach the host's MCP gateway via container topology
+ * (host.docker.internal, the vmnet gateway IP). A machine — an EC2
+ * instance behind its own network — can never route to the host, so the
+ * host pushes the gateway TO the machine instead: one persistent
+ * `ssh -N -R 127.0.0.1:<port>:127.0.0.1:<port>` per machine task, using
+ * the same per-task key every other machine operation rides. Task configs
+ * then point MCP servers at the machine's own loopback
+ * (setupMcpTaskConfig's machine branch).
+ *
+ * Supervision: the tunnel respawns with a short backoff while ensured —
+ * re-resolving the machine address each spawn, since it changes across
+ * stop/start — and stops when the task stops, tears down, or the process
+ * exits. Failure is quiet-but-logged: MCP servers failing to connect is
+ * the visible symptom, and the agent-facing degradation is already
+ * per-server.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+
+import { MCP_GATEWAY_PORT } from "./mcp-gateway";
+
+const RESPAWN_DELAY_MS = 3_000;
+/** After this many consecutive sub-5s deaths, slow the respawn cadence so a
+ * permanently unreachable machine does not spin ssh forever. */
+const FAST_DEATH_THRESHOLD = 5;
+const SLOW_RESPAWN_DELAY_MS = 60_000;
+
+export interface MachineTunnelSource {
+  gatewayTunnelSshArgs(
+    machinePort: number,
+    hostPort: number,
+  ): Promise<string[]>;
+}
+
+interface TunnelState {
+  generation: number;
+  child: ChildProcess | null;
+  timer: ReturnType<typeof setTimeout> | null;
+  fastDeaths: number;
+  spawnedAt: number;
+}
+
+const tunnels = new Map<string, TunnelState>();
+
+/** Idempotently keep a gateway tunnel alive for this machine task. */
+export function ensureMachineGatewayTunnel(
+  taskId: string,
+  source: MachineTunnelSource,
+): void {
+  const existing = tunnels.get(taskId);
+  if (existing && (existing.child !== null || existing.timer !== null)) {
+    return; // live or already scheduled
+  }
+  const state: TunnelState = existing ?? {
+    generation: 0,
+    child: null,
+    timer: null,
+    fastDeaths: 0,
+    spawnedAt: 0,
+  };
+  state.generation += 1;
+  tunnels.set(taskId, state);
+  if (existing === undefined) {
+    console.log(`[machine-tunnel] ${taskId}: ensuring gateway tunnel`);
+  }
+  void spawnTunnel(taskId, source, state, state.generation);
+}
+
+async function spawnTunnel(
+  taskId: string,
+  source: MachineTunnelSource,
+  state: TunnelState,
+  generation: number,
+): Promise<void> {
+  if (tunnels.get(taskId) !== state || state.generation !== generation) return;
+  let args: string[];
+  try {
+    args = await source.gatewayTunnelSshArgs(
+      MCP_GATEWAY_PORT,
+      MCP_GATEWAY_PORT,
+    );
+  } catch (err) {
+    // Machine not reachable right now (stopped, address settling) — retry
+    // on the slow cadence; a stop/teardown clears us before it matters.
+    scheduleRespawn(taskId, source, state, generation, SLOW_RESPAWN_DELAY_MS);
+    if (state.fastDeaths === 0) {
+      console.warn(
+        `[machine-tunnel] ${taskId}: target unavailable (${err instanceof Error ? err.message : err}) — retrying`,
+      );
+    }
+    state.fastDeaths += 1;
+    return;
+  }
+  state.spawnedAt = Date.now();
+  const child = spawn("ssh", args, { stdio: ["ignore", "ignore", "pipe"] });
+  state.child = child;
+  let stderrTail = "";
+  child.stderr?.setEncoding("utf8");
+  child.stderr?.on("data", (chunk: string) => {
+    stderrTail = (stderrTail + chunk).slice(-2048);
+  });
+  child.once("exit", (code) => {
+    if (tunnels.get(taskId) !== state || state.generation !== generation) {
+      return;
+    }
+    state.child = null;
+    const lifetimeMs = Date.now() - state.spawnedAt;
+    if (lifetimeMs < 5_000) state.fastDeaths += 1;
+    else state.fastDeaths = 0;
+    const slow = state.fastDeaths >= FAST_DEATH_THRESHOLD;
+    if (state.fastDeaths === FAST_DEATH_THRESHOLD) {
+      console.warn(
+        `[machine-tunnel] ${taskId}: tunnel keeps dying (exit ${code ?? "signal"}${
+          stderrTail.trim() ? `: ${stderrTail.trim().slice(0, 200)}` : ""
+        }) — slowing retries`,
+      );
+    }
+    scheduleRespawn(
+      taskId,
+      source,
+      state,
+      generation,
+      slow ? SLOW_RESPAWN_DELAY_MS : RESPAWN_DELAY_MS,
+    );
+  });
+  child.once("error", () => {
+    // exit fires too; the handler above owns respawn.
+  });
+}
+
+function scheduleRespawn(
+  taskId: string,
+  source: MachineTunnelSource,
+  state: TunnelState,
+  generation: number,
+  delayMs: number,
+): void {
+  if (tunnels.get(taskId) !== state || state.generation !== generation) return;
+  state.timer = setTimeout(() => {
+    state.timer = null;
+    void spawnTunnel(taskId, source, state, generation);
+  }, delayMs);
+  state.timer.unref?.();
+}
+
+/** Tear the tunnel down (task stop/teardown/GC). Idempotent. */
+export function stopMachineGatewayTunnel(taskId: string): void {
+  const state = tunnels.get(taskId);
+  if (!state) return;
+  tunnels.delete(taskId);
+  state.generation += 1; // invalidate in-flight spawns
+  if (state.timer) clearTimeout(state.timer);
+  if (state.child) {
+    state.child.kill("SIGTERM");
+    state.child = null;
+  }
+}
+
+/** Test-only view. */
+export function machineGatewayTunnelActive(taskId: string): boolean {
+  const state = tunnels.get(taskId);
+  return Boolean(state && (state.child !== null || state.timer !== null));
+}

package/lib/mcp-gateway.ts

@@ -854,11 +854,14 @@ function gatewayIdentity(value, slug) {
 }
 
 function sameTaskGateway(oldUrl, desiredUrl, slug) {
+  // Ownership is proven by the /t/<taskId>.<token>/<slug> path, not the
+  // origin: the gateway host is topology-dependent (container gateway IP,
+  // host.docker.internal, machine loopback behind a reverse tunnel) and
+  // migrating a task across topologies is exactly when the rewrite runs.
   const oldIdentity = gatewayIdentity(oldUrl, slug);
   const desiredIdentity = gatewayIdentity(desiredUrl, slug);
   return oldIdentity !== null &&
     desiredIdentity !== null &&
-    oldIdentity.origin === desiredIdentity.origin &&
     oldIdentity.taskId === desiredIdentity.taskId;
 }
 
@@ -1063,7 +1066,8 @@ export async function setupMcpTaskConfig(
   connections: TaskMcpConnection[],
   engineKinds: string[],
   codexHomes: readonly string[] = ["/home/node/.codex"],
-  environment?: Pick<TaskEnvironmentHandle, "exec">,
+  environment?: Pick<TaskEnvironmentHandle, "exec"> &
+    Partial<Pick<TaskEnvironmentHandle, "descriptor">>,
 ): Promise<boolean> {
   // No early return on empty: the claude adapter passes
   // `--mcp-config /workspace/.mcp.json` unconditionally (ADR-057), so the
@@ -1084,7 +1088,14 @@ export async function setupMcpTaskConfig(
       throw new Error("invalid Codex MCP connection slug");
     }
     const acl = ensureTaskGatewayAcl(taskId, connections);
-    const gatewayHost = await taskGatewayHost();
+    // ADR-121: a machine dials the gateway through its ssh REVERSE tunnel —
+    // the host's loopback appears at the machine's own 127.0.0.1:PORT
+    // (machine-gateway-tunnel.ts). host.docker.internal / vmnet addresses
+    // are container topology a machine can never route.
+    const gatewayHost =
+      environment?.descriptor?.locator.provider === "machine"
+        ? "127.0.0.1"
+        : await taskGatewayHost();
     const urlFor = (slug: string): string =>
       `http://${gatewayHost}:${MCP_GATEWAY_PORT}/t/${acl.token}/${slug}`;
 

package/lib/orchestrator.ts

@@ -90,6 +90,7 @@ import {
   type SkillExec,
   writeAgentSkills,
 } from "./skills";
+import { ensureMachineGatewayTunnel } from "./machine-gateway-tunnel";
 import {
   CONTAINER_CLI_PATH,
   agentCliEnv,
@@ -1655,7 +1656,14 @@ export class Orchestrator {
       return environment;
     })();
     const tracked = created.then((environment) => {
-      if (this.isActiveChannel(channel)) channel.agentHandle = environment;
+      if (this.isActiveChannel(channel)) {
+        channel.agentHandle = environment;
+        // Every path that touches a machine workspace settles the handle
+        // here — including durable-session reattach after a host restart,
+        // which spawns no sessions and runs no config writers. Ensuring the
+        // gateway tunnel at the funnel keeps it alive across all of them.
+        ensureMachineGatewayTunnelFor(channel.taskId, environment);
+      }
       return environment;
     });
     channel.agentEnvironment = tracked;
@@ -5641,6 +5649,20 @@ async function quarantineWritableAppleRuntimeContainers(options: {
  * machine tasks (their workspace is not host-reachable). Best-effort like the
  * host-side writer.
  */
+/** Keep the MCP gateway reverse tunnel alive for a machine channel. The
+ * handle exposes tunnel argv only on the machine provider; anything else is
+ * a quiet no-op. */
+function ensureMachineGatewayTunnelFor(
+  taskId: string,
+  handle: TaskEnvironmentHandle<unknown> | null,
+): void {
+  const argv = handle?.gatewayTunnelSshArgs;
+  if (!argv) return;
+  ensureMachineGatewayTunnel(taskId, {
+    gatewayTunnelSshArgs: argv.bind(handle),
+  });
+}
+
 async function materializeAgentCli(
   task: typeof schema.hostTasks.$inferSelect,
   roster: RosterAgent[],

package/lib/task-environment/machine-task-up.ts

@@ -448,6 +448,12 @@ function withTaskDownResult(
     ...(handle.inspectRoute
       ? { inspectRoute: () => handle.inspectRoute!() }
       : {}),
+    ...(handle.gatewayTunnelSshArgs
+      ? {
+          gatewayTunnelSshArgs: (machinePort: number, hostPort: number) =>
+            handle.gatewayTunnelSshArgs!(machinePort, hostPort),
+        }
+      : {}),
   };
 }
 

package/lib/task-environment/machine.ts

@@ -504,6 +504,31 @@ class MachineTaskEnvironmentHandle implements TaskEnvironmentHandle {
     };
   }
 
+  /** Full ssh argv for the persistent REVERSE gateway tunnel: the host's
+   * loopback gateway appears at the machine's own 127.0.0.1:<machinePort>.
+   * Resolved per call — cloud machines change address across stop/start, so
+   * each (re)spawn of the tunnel re-resolves the dial target. */
+  async gatewayTunnelSshArgs(
+    machinePort: number,
+    hostPort: number,
+  ): Promise<string[]> {
+    const target = await this.#target();
+    return [
+      "-o", "BatchMode=yes",
+      "-o", "StrictHostKeyChecking=accept-new",
+      "-o", "ConnectTimeout=10",
+      "-o", "ExitOnForwardFailure=yes",
+      "-o", "ServerAliveInterval=15",
+      "-o", "ServerAliveCountMax=3",
+      "-i", target.keyPath,
+      "-p", String(target.port ?? 22),
+      "-l", this.#value.sshUser,
+      target.address,
+      "-N",
+      "-R", `127.0.0.1:${machinePort}:127.0.0.1:${hostPort}`,
+    ];
+  }
+
   async status(): Promise<TaskEnvironmentStatus> {
     const info = await this.#describeOwn();
     switch (info.state) {

package/lib/task-environment/types.ts

@@ -220,6 +220,14 @@ export interface TaskEnvironmentHandle<TTeardownResult = void>
     | { kind: "unavailable" }
     | { kind: "unknown"; detail: string }
   >;
+  /** ADR-121, machine provider only: full ssh argv for the persistent
+   * REVERSE gateway tunnel that makes the host's MCP gateway answer on the
+   * environment's own loopback. Container providers omit it — their tasks
+   * route to the gateway via container topology instead. */
+  gatewayTunnelSshArgs?(
+    machinePort: number,
+    hostPort: number,
+  ): Promise<string[]>;
 }
 
 export interface TaskEnvironmentProvisionRequest<TInput, TCredentials> {

package/lib/vnode-pressure.ts

@@ -0,0 +1,103 @@
+/**
+ * ADR-118 follow-up: the macOS vnode-table pressure sensor.
+ *
+ * Apple's Virtualization.framework virtiofs pins one host vnode per distinct
+ * guest-touched file for the life of the task VM (~12k per task after
+ * ADR-118 moved the pnpm store off virtiofs; ~130k+ before it). The table
+ * ceiling (`kern.maxvnodes`) is a boot-time default the host cannot raise
+ * without root, and AT the ceiling unrelated host software starts failing
+ * with ENFILE — the suspected 2026-08-24 kernel-panic precursor.
+ *
+ * Three surfaces ride this module:
+ *  - `readVnodePressure()` — the sensor (cached; null off-macOS).
+ *  - `vnodeAdmissionProblem()` — task-up guard: refuse to start ANOTHER
+ *    apple-container VM above the threshold instead of letting the kernel
+ *    hit the wall. Existing tasks keep running.
+ *  - `logVnodePressure()` — periodic observability, warn-level near the
+ *    ceiling so host logs explain refusals before they happen.
+ *
+ * Raising the ceiling needs root once: `sudo uai-host tune` (see cli.ts)
+ * installs a LaunchDaemon that reasserts the sysctls at every boot —
+ * sysctl writes alone are ephemeral.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const exec = promisify(execFile);
+
+/** Refuse NEW apple task VMs above this fraction of the vnode ceiling. */
+const ADMISSION_THRESHOLD = 0.9;
+/** Warn-log above this fraction. */
+const WARN_THRESHOLD = 0.8;
+const CACHE_MS = 15_000;
+
+export interface VnodePressure {
+  current: number;
+  max: number;
+  ratio: number;
+}
+
+let cached: { at: number; value: VnodePressure | null } | null = null;
+
+export async function readVnodePressure(): Promise<VnodePressure | null> {
+  if (process.platform !== "darwin") return null;
+  if (cached && Date.now() - cached.at < CACHE_MS) return cached.value;
+  let value: VnodePressure | null = null;
+  try {
+    const { stdout } = await exec(
+      "/usr/sbin/sysctl",
+      ["-n", "kern.num_vnodes", "kern.maxvnodes"],
+      { timeout: 5_000 },
+    );
+    const parts = stdout.trim().split(/\s+/).map(Number);
+    const current = parts[0] ?? Number.NaN;
+    const max = parts[1] ?? Number.NaN;
+    if (Number.isFinite(current) && Number.isFinite(max) && max > 0) {
+      value = { current, max, ratio: current / max };
+    }
+  } catch {
+    // Sensor failure is never a task failure; admission simply has no data.
+  }
+  cached = { at: Date.now(), value };
+  return value;
+}
+
+/** Non-null = refuse to start another apple-container task VM right now. */
+export async function vnodeAdmissionProblem(): Promise<string | null> {
+  const pressure = await readVnodePressure();
+  if (!pressure || pressure.ratio < ADMISSION_THRESHOLD) return null;
+  return (
+    `the macOS vnode table is at ${Math.round(pressure.ratio * 100)}% ` +
+    `(${pressure.current}/${pressure.max}); starting another task VM risks ` +
+    "system-wide file-table exhaustion. Close a running task, or raise the " +
+    "ceiling once with: sudo uai-host tune"
+  );
+}
+
+let lastLoggedBand: "ok" | "warn" | "critical" = "ok";
+
+/** Log on band TRANSITIONS only, so a host sitting near the ceiling does not
+ * spam its own log every interval. */
+export async function logVnodePressure(): Promise<void> {
+  const pressure = await readVnodePressure();
+  if (!pressure) return;
+  const band =
+    pressure.ratio >= ADMISSION_THRESHOLD
+      ? "critical"
+      : pressure.ratio >= WARN_THRESHOLD
+        ? "warn"
+        : "ok";
+  if (band === lastLoggedBand) return;
+  lastLoggedBand = band;
+  const detail = `${pressure.current}/${pressure.max} (${Math.round(pressure.ratio * 100)}%)`;
+  if (band === "critical") {
+    console.warn(
+      `[vnode] table at ${detail} — new apple task VMs will be refused; run: sudo uai-host tune`,
+    );
+  } else if (band === "warn") {
+    console.warn(`[vnode] table filling: ${detail}`);
+  } else {
+    console.log(`[vnode] table pressure back to normal: ${detail}`);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.77",
+  "version": "0.9.79",
   "description": "Uai host — runs ephemeral AI tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Uai Tech <team@runuai.com>",

package/src/cli.ts

@@ -22,7 +22,7 @@ import "./load-env";
 
 import { spawn, spawnSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
@@ -137,6 +137,8 @@ async function main(): Promise<void> {
       return cmdLogs(follow);
     case "runtime":
       return cmdRuntime(rest);
+    case "tune":
+      return cmdTune();
     case "update":
       return cmdUpdate(rest);
     case "rollback":
@@ -498,6 +500,139 @@ async function boundedResponseJson(
 
 // --- runtime ---------------------------------------------------------------
 
+// --- tune (ADR-118 follow-up: vnode/file-table ceilings) ---------------------
+
+const TUNE_DAEMON_LABEL = "com.runuai.tune";
+const TUNE_DAEMON_PLIST = `/Library/LaunchDaemons/${TUNE_DAEMON_LABEL}.plist`;
+/** Floors, not targets — an operator-raised ceiling is never lowered. Each
+ * apple-container task VM pins host vnodes for its life (~12k after ADR-118,
+ * far more during dependency churn), and the boot defaults sit low enough
+ * that two heavy tasks have filled the table live (2026-08-25). ~2M vnodes
+ * is roughly half a GB of kernel memory IF fully populated. */
+const TUNE_MAXVNODES_FLOOR = 2_097_152;
+const TUNE_MAXFILES_FLOOR = 2_097_152;
+const TUNE_MAXFILESPERPROC_FLOOR = 1_048_576;
+
+function readSysctlNumber(name: string): number | null {
+  const res = spawnSync("/usr/sbin/sysctl", ["-n", name], {
+    encoding: "utf8",
+  });
+  const value = Number((res.stdout ?? "").trim());
+  return res.status === 0 && Number.isFinite(value) ? value : null;
+}
+
+function tunePlistContent(settings: Array<[string, number]>): string {
+  const args = ["/usr/sbin/sysctl", ...settings.map(([k, v]) => `${k}=${v}`)]
+    .map((a) => `    <string>${a}</string>`)
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${TUNE_DAEMON_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+</dict>
+</plist>
+`;
+}
+
+async function cmdTune(): Promise<void> {
+  if (process.platform !== "darwin") {
+    console.error(red("tune is macOS-only (apple-container task VMs)"));
+    process.exitCode = 1;
+    return;
+  }
+  const current = {
+    maxvnodes: readSysctlNumber("kern.maxvnodes"),
+    maxfiles: readSysctlNumber("kern.maxfiles"),
+    maxfilesperproc: readSysctlNumber("kern.maxfilesperproc"),
+  };
+  if (
+    current.maxvnodes === null ||
+    current.maxfiles === null ||
+    current.maxfilesperproc === null
+  ) {
+    console.error(red("could not read the current kernel limits via sysctl"));
+    process.exitCode = 1;
+    return;
+  }
+  // Order matters at apply time: maxfilesperproc must stay <= maxfiles.
+  const settings: Array<[string, number]> = [
+    ["kern.maxfiles", Math.max(current.maxfiles, TUNE_MAXFILES_FLOOR)],
+    [
+      "kern.maxfilesperproc",
+      Math.max(current.maxfilesperproc, TUNE_MAXFILESPERPROC_FLOOR),
+    ],
+    ["kern.maxvnodes", Math.max(current.maxvnodes, TUNE_MAXVNODES_FLOOR)],
+  ];
+  const desiredPlist = tunePlistContent(settings);
+  const plistCurrent = existsSync(TUNE_DAEMON_PLIST)
+    ? readFileSync(TUNE_DAEMON_PLIST, "utf8")
+    : null;
+  const changes = settings.filter(
+    ([key, value]) => value !== current[key.slice("kern.".length) as keyof typeof current],
+  );
+  if (changes.length === 0 && plistCurrent === desiredPlist) {
+    const summary = settings.map(([k, v]) => `${k}=${v}`).join(" ");
+    console.log(`already tuned (${summary}); boot persistence in place`);
+    return;
+  }
+
+  if (typeof process.getuid !== "function" || process.getuid() !== 0) {
+    console.log(`${bold("uai-host tune")} will (needs sudo):`);
+    for (const [key, value] of changes) {
+      console.log(
+        `  raise ${key}: ${current[key.slice("kern.".length) as keyof typeof current]} -> ${value}`,
+      );
+    }
+    console.log(
+      `  install ${TUNE_DAEMON_PLIST} so the limits survive reboots`,
+    );
+    console.log(`\nrun: ${cyan("sudo uai-host tune")}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  for (const [key, value] of settings) {
+    const res = spawnSync("/usr/sbin/sysctl", [`${key}=${value}`], {
+      encoding: "utf8",
+    });
+    if (res.status !== 0) {
+      console.error(
+        red(`sysctl ${key}=${value} failed: ${(res.stderr ?? "").trim()}`),
+      );
+      process.exitCode = 1;
+      return;
+    }
+  }
+  writeFileSync(TUNE_DAEMON_PLIST, desiredPlist, { mode: 0o644 });
+  spawnSync("/usr/sbin/chown", ["root:wheel", TUNE_DAEMON_PLIST]);
+  // Re-bootstrap so launchd owns the daemon under its current definition.
+  spawnSync("/bin/launchctl", ["bootout", `system/${TUNE_DAEMON_LABEL}`]);
+  const bootstrap = spawnSync(
+    "/bin/launchctl",
+    ["bootstrap", "system", TUNE_DAEMON_PLIST],
+    { encoding: "utf8" },
+  );
+  if (bootstrap.status !== 0) {
+    console.error(
+      red(
+        `limits applied, but launchctl bootstrap failed (${(bootstrap.stderr ?? "").trim()}) — they will not survive a reboot`,
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const summary = settings.map(([k, v]) => `${k}=${v}`).join(" ");
+  console.log(`tuned: ${summary} (persisted via ${TUNE_DAEMON_PLIST})`);
+}
+
 async function cmdRuntime(rest: string[]): Promise<void> {
   if (rest[0] === "begin-install") {
     return cmdBeginRuntimeInstall(rest.slice(1));
@@ -1882,6 +2017,8 @@ function printHelp(): void {
   status               connection, service info, active tasks (same as the UI)
   logs [--follow]      tail the service log
   runtime recheck      probe Docker again and refresh cloud capabilities
+  tune                 (macOS, sudo) raise kernel vnode/file-table ceilings for
+                       apple-container task VMs and persist them across boots
   setup --cloud <wss-url> --enroll <token>
                        claim this machine via an enrollment token from the web
                        app (mints + writes the host credential); on an

package/src/index.ts

@@ -17,6 +17,7 @@ import {
   removeTaskCliSecretStrict,
   storeTaskCliSecret,
 } from "../lib/agent-cli";
+import { stopMachineGatewayTunnel } from "../lib/machine-gateway-tunnel";
 import {
   clearRefresh,
   injectIntoContainer,
@@ -69,10 +70,12 @@ import {
   containerRuntimeTeardownProblem,
   ensureContainerRuntimeForTask,
   initializeContainerRuntime,
+  pinnedContainerRuntimeProvider,
   reprobeContainerRuntimeMachineIdentity,
   suspendContainerRuntime,
   waitForContainerRuntimeOperational,
 } from "../lib/container-runtime";
+import { vnodeAdmissionProblem } from "../lib/vnode-pressure";
 import {
   provisionTaskEnvironment,
   reconstructPersistedTaskEnvironment,
@@ -263,6 +266,21 @@ export const hostCommands: HostCommands = {
     if (readyAdmissionFailure) return readyAdmissionFailure;
     const readyRuntimeFailure = runtimeUnavailable();
     if (readyRuntimeFailure) return readyRuntimeFailure;
+    // ADR-118 follow-up: each apple-container task is its own VM, and each
+    // VM pins host vnodes for its life. Refuse to start ANOTHER one when the
+    // table is nearly full — a clear, retryable refusal now beats ENFILE
+    // storms (and the suspected panic path) for the whole machine later.
+    if (pinnedContainerRuntimeProvider() === "apple-container") {
+      const vnodeProblem = await vnodeAdmissionProblem();
+      if (vnodeProblem) {
+        return {
+          ok: false,
+          code: HostErrorCode.HostUnavailable,
+          message: vnodeProblem,
+          retryable: true,
+        };
+      }
+    }
     const orchestrator = getOrchestrator();
     return orchestrator.runTaskLifecycle(input.task.id, async () => {
       // A direct duplicate teardown may still be draining operations that
@@ -966,9 +984,13 @@ export const hostCommands: HostCommands = {
           !orphanGc &&
           environment.descriptor.locator.provider === "machine"
         ) {
+          stopMachineGatewayTunnel(input.taskId);
           await environment.stop();
           return taskDownResultForInput(input, { status: "stopped" });
         }
+        if (environment.descriptor.locator.provider === "machine") {
+          stopMachineGatewayTunnel(input.taskId);
+        }
         return taskDownResultForInput(input, await environment.teardown());
       });
       if (result.ok) {

package/src/main.ts

@@ -110,6 +110,7 @@ import {
   publishActivationPhase,
 } from "../lib/container-runtime";
 import { reconstructPersistedTaskEnvironment } from "../lib/task-environment";
+import { logVnodePressure } from "../lib/vnode-pressure";
 import { resolveAppleTunnelRoute } from "./apple-tunnel-route";
 import {
   configureBundledContainerRuntime,
@@ -516,6 +517,11 @@ void connect();
 // Local browser UI (ADR-028) — same single process, alongside the WSS client.
 // Best-effort: a UI bind failure must not take the host service down.
 void startLocalUi();
+// ADR-118 follow-up: vnode-pressure observability (macOS/apple-container
+// hosts). Logs only on band transitions; the sensor caches its sysctl read.
+const vnodePressureTimer = setInterval(() => void logVnodePressure(), 60_000);
+vnodePressureTimer.unref?.();
+void logVnodePressure();
 
 async function startLocalUi(): Promise<void> {
   try {