@runuai/host 0.9.97 → 0.9.99

package/package.json

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

package/scripts/install/darwin.ts

@@ -35,9 +35,21 @@ import {
 
 export const LABEL = "com.runuai.host";
 
-const uid = process.getuid?.() ?? 0;
-const domain = `gui/${uid}`;
-const target = `${domain}/${LABEL}`;
+/** The per-user launchd domain the LaunchAgent is bootstrapped into. */
+export function launchdDomain(uid: number = process.getuid?.() ?? 0): string {
+  return `gui/${uid}`;
+}
+
+/** The job as `launchctl` addresses it — `gui/<uid>/com.runuai.host`. The
+ * service's own activation respawn (`src/activation-respawn.ts`) targets the
+ * same string, so the label and domain cannot drift between the CLI and the
+ * running host. */
+export function launchdJobTarget(uid: number = process.getuid?.() ?? 0): string {
+  return `${launchdDomain(uid)}/${LABEL}`;
+}
+
+const domain = launchdDomain();
+const target = launchdJobTarget();
 const logDir = resolve(homedir(), "Library", "Logs", "Uai");
 
 export function plistPath(): string {
@@ -934,12 +946,82 @@ export async function restartDarwinService(
   }
 }
 
+/** What `launchctl print gui/<uid>/com.runuai.host` says about the job. */
+export interface LaunchdJobState {
+  readonly loaded: boolean;
+  /** `state = …` verbatim: `running`, `not running`, `waiting`, … */
+  readonly state: string | null;
+  readonly pid: number | null;
+  /** `last exit code = …` verbatim, e.g. `75: EX_TEMPFAIL` or `(never exited)`. */
+  readonly lastExitCode: string | null;
+  /** `pended nondemand spawn = …` — launchd holds a spawn it has not executed
+   * (live 2026-09-06: `inefficient`, with the job `not running` after an
+   * exit-75 activation restart that KeepAlive never honoured). */
+  readonly pendedNondemandSpawn: string | null;
+  /** Why the probe failed, when it did not confirm a loaded job. */
+  readonly detail: string | null;
+}
+
+function launchdPrintField(stdout: string, name: string): string | null {
+  // Top-level keys are indented by exactly one tab; nested dicts (endpoints,
+  // event triggers) reuse names like `state = active` two tabs deep, so the
+  // job's own key is preferred and the loose match is only a fallback. The
+  // whitespace class is horizontal only, so `state` never matches the tail
+  // of `spawn type` or another longer key.
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const value = `(.+?)[ \\t]*(?:\\r?\\n|$)`;
+  return (
+    new RegExp(`(?:^|\\n)\\t${escaped} = ${value}`).exec(stdout)?.[1] ??
+    new RegExp(`(?:^|\\n)[ \\t]*${escaped} = ${value}`).exec(stdout)?.[1] ??
+    null
+  );
+}
+
+export function parseLaunchdJobPrint(stdout: string): LaunchdJobState {
+  const pid = launchdPrintField(stdout, "pid");
+  return {
+    loaded: true,
+    state: launchdPrintField(stdout, "state"),
+    pid: pid !== null && /^\d+$/.test(pid) ? Number(pid) : null,
+    lastExitCode: launchdPrintField(stdout, "last exit code"),
+    pendedNondemandSpawn: launchdPrintField(stdout, "pended nondemand spawn"),
+    detail: null,
+  };
+}
+
+/** One `launchctl print` of the host job, parsed. Read-only: safe to call
+ * from the running service (a boot after an activation logs it so a pended
+ * respawn is visible in the service log rather than only in `launchctl`). */
+export function describeLaunchdJob(execute: StepExecutor = executeStep): LaunchdJobState {
+  const result = execute(false, "launchctl", ["print", target]);
+  if (result.status !== 0) {
+    return {
+      loaded: false,
+      state: null,
+      pid: null,
+      lastExitCode: null,
+      pendedNondemandSpawn: null,
+      detail: resultDetail(result) || null,
+    };
+  }
+  return parseLaunchdJobPrint(result.stdout);
+}
+
+export function formatLaunchdJobState(job: LaunchdJobState): string {
+  if (!job.loaded) return `not loaded${job.detail ? ` (${job.detail})` : ""}`;
+  const parts = [`state = ${job.state ?? "unknown"}`];
+  if (job.pid !== null) parts.push(`pid = ${job.pid}`);
+  if (job.lastExitCode !== null) parts.push(`last exit code = ${job.lastExitCode}`);
+  if (job.pendedNondemandSpawn !== null) {
+    parts.push(`pended nondemand spawn = ${job.pendedNondemandSpawn}`);
+  }
+  return parts.join(", ");
+}
+
 async function status(): Promise<string> {
-  const out = step(false, "launchctl", ["print", target], { ignoreError: true });
-  if (!out) return "not installed / not loaded";
-  const state = /state = (\S+)/.exec(out)?.[1] ?? "unknown";
-  const pid = /pid = (\d+)/.exec(out)?.[1];
-  return `${state}${pid ? ` (pid ${pid})` : ""}`;
+  const job = describeLaunchdJob();
+  if (!job.loaded) return "not installed / not loaded";
+  return `${job.state ?? "unknown"}${job.pid !== null ? ` (pid ${job.pid})` : ""}`;
 }
 
 export const installer: Installer = {

package/src/activation-respawn.ts

@@ -0,0 +1,155 @@
+/**
+ * The macOS activation restart must not depend on launchd KeepAlive.
+ *
+ * A staged runtime activation (the in-app Update, `uai-host update`, the
+ * remote hostRestart) drains in-flight work and exits with
+ * MANAGED_UPDATE_RESTART_EXIT_CODE (75) so the service supervisor relaunches
+ * `runtime/current`. On Linux `Restart=on-failure` does exactly that. On
+ * macOS the LaunchAgent is `KeepAlive: true` — and twice on 2026-09-06 launchd
+ * did NOT respawn the job: `launchctl print gui/501/com.runuai.host` sat at
+ * `state = not running`, `last exit code = 75: EX_TEMPFAIL`,
+ * `pended nondemand spawn = inefficient` until the operator ran
+ * `uai-host start` (a plain `launchctl kickstart` of the job), which recovered
+ * it instantly.
+ *
+ * So the exiting process schedules that kickstart itself, from a child that
+ * survives it: a detached (`setsid`, so it leaves the job's process group and
+ * launchd's exit-time group cleanup cannot reach it), unref'd, stdio-less
+ * shell that sleeps a few seconds and then kickstarts the job. Plain
+ * `kickstart` first — a no-op when KeepAlive did respawn, so a fresh instance
+ * is never killed mid-boot — and `kickstart -k` as the fallback should launchd
+ * refuse the plain one (kill whatever is there and start again; by then
+ * nothing of ours should be running).
+ *
+ * It is scheduled only where it can matter: darwin, not under the desktop
+ * app's supervisor (which relaunches the agent on exit itself), and only when
+ * launchd is this process's parent — a `uai-host run` in a terminal, or a test
+ * spawning the CLI, has nothing to kick and must never touch a live service.
+ */
+
+import { spawn as nodeSpawn } from "node:child_process";
+
+import { launchdJobTarget } from "../scripts/install/darwin";
+
+/** Long enough for a KeepAlive respawn, if launchd honours it, to have
+ * happened first (so the plain kickstart is a no-op); short enough that the
+ * host is back within seconds when it does not. */
+export const ACTIVATION_RESPAWN_DELAY_SECONDS = 5;
+
+export const ACTIVATION_RESPAWN_SHELL = "/bin/sh";
+/** Absolute: the detached shell inherits the service environment, and a
+ * launchd-spawned job's PATH is whatever the plist captured at install. */
+export const ACTIVATION_RESPAWN_LAUNCHCTL = "/bin/launchctl";
+/** `$1` = delay in seconds, `$2` = the launchd job target. Positional, never
+ * interpolated, so the command line stays inert whatever the inputs. */
+export const ACTIVATION_RESPAWN_SCRIPT = `sleep "$1"; ${ACTIVATION_RESPAWN_LAUNCHCTL} kickstart "$2" || exec ${ACTIVATION_RESPAWN_LAUNCHCTL} kickstart -k "$2"`;
+
+export interface ActivationRespawnChild {
+  on(event: "error", listener: (error: Error) => void): unknown;
+  unref(): void;
+}
+
+export interface ActivationRespawnSpawnOptions {
+  readonly detached: true;
+  readonly stdio: "ignore";
+}
+
+export type ActivationRespawnSpawn = (
+  command: string,
+  args: readonly string[],
+  options: ActivationRespawnSpawnOptions,
+) => ActivationRespawnChild;
+
+export interface ActivationRespawnSeams {
+  platform?: NodeJS.Platform;
+  /** `process.ppid`; launchd is pid 1 and the parent of every job it runs. */
+  parentPid?: number;
+  /** `process.getuid()`; `undefined` models a platform without uids. */
+  uid?: number | undefined;
+  /** `process.versions.electron` — the desktop app runs the agent as a
+   * supervised child and restarts it on exit itself. */
+  underElectron?: boolean;
+  delaySeconds?: number;
+  spawn?: ActivationRespawnSpawn;
+}
+
+export type ActivationRespawnPlan =
+  | {
+      readonly scheduled: true;
+      readonly target: string;
+      readonly command: string;
+      readonly args: readonly string[];
+      readonly delaySeconds: number;
+    }
+  | { readonly scheduled: false; readonly reason: string };
+
+/**
+ * Call immediately before `process.exit(MANAGED_UPDATE_RESTART_EXIT_CODE)`:
+ * the drain is complete, so the delay counts from the moment the old process
+ * is gone. `spawn` forks synchronously, so the child exists when this returns
+ * and the caller may exit at once.
+ */
+export function scheduleActivationRespawn(
+  seams: ActivationRespawnSeams = {},
+): ActivationRespawnPlan {
+  const platform = seams.platform ?? process.platform;
+  if (platform !== "darwin") {
+    return {
+      scheduled: false,
+      reason: `${platform} relies on its service supervisor's restart policy`,
+    };
+  }
+  if (seams.underElectron ?? Boolean(process.versions.electron)) {
+    return {
+      scheduled: false,
+      reason: "the desktop app's supervisor relaunches the agent",
+    };
+  }
+  const parentPid = seams.parentPid ?? process.ppid;
+  if (parentPid !== 1) {
+    return {
+      scheduled: false,
+      reason: `not launchd-spawned (parent pid ${parentPid}); nothing to kick`,
+    };
+  }
+  const uid = "uid" in seams ? seams.uid : process.getuid?.();
+  if (uid === undefined) {
+    return { scheduled: false, reason: "no uid to address the launchd domain" };
+  }
+  const delaySeconds = seams.delaySeconds ?? ACTIVATION_RESPAWN_DELAY_SECONDS;
+  const target = launchdJobTarget(uid);
+  const args = [
+    "-c",
+    ACTIVATION_RESPAWN_SCRIPT,
+    "uai-host-activation-respawn",
+    String(delaySeconds),
+    target,
+  ];
+  const spawn = seams.spawn ?? (nodeSpawn as unknown as ActivationRespawnSpawn);
+  let child: ActivationRespawnChild;
+  try {
+    child = spawn(ACTIVATION_RESPAWN_SHELL, args, {
+      detached: true,
+      stdio: "ignore",
+    });
+  } catch (error) {
+    return {
+      scheduled: false,
+      reason: `could not spawn the respawn shell: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    };
+  }
+  // A spawn that fails after the fork leaves KeepAlive as the only respawn —
+  // the pre-0.9.99 behaviour — and must not become an uncaught 'error' in a
+  // process that is about to exit anyway.
+  child.on("error", () => {});
+  child.unref();
+  return {
+    scheduled: true,
+    target,
+    command: ACTIVATION_RESPAWN_SHELL,
+    args,
+    delaySeconds,
+  };
+}

package/src/cli.ts

@@ -250,6 +250,7 @@ async function cmdRun(): Promise<void> {
     installState !== "live" &&
     installState !== "unknown"
   ) {
+    const activationWasPending = existsSync(managedPaths.activationPending);
     try {
       if (!(await acknowledgeManagedRuntimeActivation(runningVersion))) {
         // Selection changed while the service module was loading. Its task
@@ -258,6 +259,12 @@ async function cmdRun(): Promise<void> {
         host.requestManagedHostRestart();
         return;
       }
+      if (activationWasPending) {
+        console.log(
+          `[host-agent] managed runtime ${runningVersion} activated (pending activation acknowledged)`,
+        );
+        await logLaunchdJobAfterActivation();
+      }
     } catch (error) {
       // A malformed or concurrently changed marker must not leave an imported
       // service running indefinitely. Admission is still closed, so request a
@@ -305,6 +312,32 @@ async function cmdRun(): Promise<void> {
   }
 }
 
+/**
+ * The boot after an activation is the moment a launchd respawn problem is
+ * visible — `last exit code = 75: EX_TEMPFAIL` with a `pended nondemand
+ * spawn` is what the 2026-09-06 stalls looked like in `launchctl print`, and
+ * nothing in the service log said so. Read-only, macOS, and only when launchd
+ * actually spawned this process (pid 1 is its parent): a terminal `uai-host
+ * run`, the desktop supervisor, or a test spawning the CLI never runs
+ * `launchctl` here.
+ */
+async function logLaunchdJobAfterActivation(): Promise<void> {
+  if (process.platform !== "darwin" || process.ppid !== 1) return;
+  try {
+    const { describeLaunchdJob, formatLaunchdJobState, launchdJobTarget } =
+      await import("../scripts/install/darwin");
+    console.log(
+      `[host-agent] launchd job ${launchdJobTarget()} after activation: ${formatLaunchdJobState(describeLaunchdJob())}`,
+    );
+  } catch (error) {
+    console.warn(
+      `[host-agent] could not read the launchd job state after activation: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}
+
 async function waitForManagedInstaller(): Promise<"live" | "restart" | "stopped"> {
   console.error(
     red(

package/src/machine-tunnel-route.ts

@@ -0,0 +1,156 @@
+/**
+ * ADR-121 machine tunnel routing, extracted from main.ts so its one expensive
+ * step is bounded and testable. Resolving a machine's address is a cloud API
+ * call — `aws ec2 describe-instances` through a spawned CLI, 0.5–1.5 s on the
+ * default t4g.medium host — and the cloud opens one tunnel per HTTP request,
+ * so a browser pane (noVNC ships dozens of unbundled modules) or the editor
+ * (code-server, more) paid that call dozens of times per load. Live
+ * 2026-09-06: "connecting, but very slow" on every AWS machine task, while
+ * Docker and apple-container hosts, whose routes are a local inspect, felt
+ * instant.
+ *
+ * The memo is per task, short (MACHINE_ROUTE_TTL_MS), and holds only a proven
+ * `running` route: a stopped or unknown machine is asked again on every open
+ * so a wake is seen promptly; a dial failure drops the entry so a machine that
+ * moved (a fresh public IP after stop/start) is re-described on the next open;
+ * a stop/down command drops it too — and bumps a per-task generation, so a
+ * description that was already in flight when the stop landed cannot
+ * re-memoise the pre-stop address. Concurrent cold opens share one resolution
+ * (the pane's first burst is half a dozen parallel requests), and a machine
+ * seen not running is not asked again for a few seconds (noVNC retries every
+ * couple of seconds against a stopped machine; without that, each retry was
+ * a CLI spawn). A refused dial invalidates at once. An address that
+ * black-holes (an instance stopped while memoised) answers nothing, so the
+ * route carries its own connect bound, MACHINE_DIAL_CONNECT_TIMEOUT_MS: both
+ * dial paths in main.ts arm it (`tunnel-dial.ts`) and the timeout surfaces as
+ * an ordinary dial error, which invalidates the entry exactly like a refusal.
+ * Before host 0.9.99 machine dials had no timeout of their own and a
+ * black-holed address hung on the kernel's SYN budget (~75 s macOS, ~127 s
+ * Linux) — longer than the memo TTL, so the TTL was never the real bound.
+ */
+
+export type MachineTunnelRoute =
+  | { kind: "running"; ipv4Address: string }
+  | { kind: "unavailable" }
+  | { kind: "unknown"; detail: string };
+
+export interface MachineTunnelRouteDeps<Task> {
+  reconstruct(task: Task): Promise<{
+    inspectRoute?: () => Promise<MachineTunnelRoute>;
+  } | null>;
+  now(): number;
+  ttlMs?: number;
+}
+
+export interface MachineTunnelRouteRequest {
+  taskId: string;
+  target: string;
+  containerPort?: number;
+}
+
+/** Long enough to cover a pane or editor load (dozens of opens inside a few
+ * seconds), short enough that a machine's address is never trusted past the
+ * next stop/start cycle by much; a failed dial drops it sooner. */
+export const MACHINE_ROUTE_TTL_MS = 45_000;
+/** How long a not-running answer is trusted before the machine is asked
+ * again — long enough to absorb a reconnecting pane, short enough that a wake
+ * is seen within seconds. */
+export const MACHINE_ROUTE_NEGATIVE_TTL_MS = 5_000;
+/** Connect-phase bound for a dial to a memoised machine address. An
+ * in-region machine answers a SYN in milliseconds; the cloud waits 30 s for
+ * the tunnel ack and the forward hop 45 s for the head, so 10 s is generous
+ * to a live machine and still leaves the caller a real answer (a 502 and a
+ * dropped memo) instead of the kernel's SYN retry budget. */
+export const MACHINE_DIAL_CONNECT_TIMEOUT_MS = 10_000;
+
+/** A resolved machine route: where to dial, and the connect bound the dial
+ * must carry because the address is memoised. */
+export interface MachineTunnelRouteTarget {
+  host: string;
+  port: number;
+  connectTimeoutMs: number;
+}
+
+const memo = new Map<string, { ipv4Address: string; expiresAt: number }>();
+const negative = new Map<string, number>();
+const inFlight = new Map<string, Promise<string | null>>();
+/** Bumped by every invalidation; a resolution only writes the memo if the
+ * generation it started under is still current. */
+const generation = new Map<string, number>();
+
+export async function resolveMachineTunnelRoute<
+  Task extends { codeServerPort?: number | null },
+>(
+  request: MachineTunnelRouteRequest,
+  task: Task,
+  deps: MachineTunnelRouteDeps<Task>,
+): Promise<MachineTunnelRouteTarget | null> {
+  // The cheap refusal first: an unroutable request never costs an API call.
+  const port =
+    request.target === "editor"
+      ? (task.codeServerPort ?? null)
+      : (request.containerPort ?? null);
+  if (!port) return null;
+  const host = await machineAddress(request.taskId, task, deps);
+  return host === null
+    ? null
+    : { host, port, connectTimeoutMs: MACHINE_DIAL_CONNECT_TIMEOUT_MS };
+}
+
+async function machineAddress<Task>(
+  taskId: string,
+  task: Task,
+  deps: MachineTunnelRouteDeps<Task>,
+): Promise<string | null> {
+  const now = deps.now();
+  const hit = memo.get(taskId);
+  if (hit && hit.expiresAt > now) return hit.ipv4Address;
+  memo.delete(taskId);
+  const notRunningUntil = negative.get(taskId);
+  if (notRunningUntil !== undefined && notRunningUntil > now) return null;
+  negative.delete(taskId);
+  const pending = inFlight.get(taskId);
+  if (pending) return pending;
+  const startedUnder = generation.get(taskId) ?? 0;
+  const resolution = (async (): Promise<string | null> => {
+    const environment = await deps.reconstruct(task);
+    const route = environment?.inspectRoute
+      ? await environment.inspectRoute()
+      : null;
+    const settledAt = deps.now();
+    const stillCurrent = (generation.get(taskId) ?? 0) === startedUnder;
+    if (!route || route.kind !== "running") {
+      if (stillCurrent) {
+        negative.set(taskId, settledAt + MACHINE_ROUTE_NEGATIVE_TTL_MS);
+      }
+      return null;
+    }
+    if (stillCurrent) {
+      memo.set(taskId, {
+        ipv4Address: route.ipv4Address,
+        expiresAt: settledAt + (deps.ttlMs ?? MACHINE_ROUTE_TTL_MS),
+      });
+    }
+    return route.ipv4Address;
+  })().finally(() => {
+    inFlight.delete(taskId);
+  });
+  inFlight.set(taskId, resolution);
+  return resolution;
+}
+
+/** A dial to the memoised address failed, or the task was stopped, started or
+ * torn down: the next open must describe the machine again, and a description
+ * already in flight must not write what it learned before this point. */
+export function invalidateMachineTunnelRoute(taskId: string): void {
+  memo.delete(taskId);
+  negative.delete(taskId);
+  generation.set(taskId, (generation.get(taskId) ?? 0) + 1);
+}
+
+export function resetMachineTunnelRoutesForTesting(): void {
+  memo.clear();
+  negative.clear();
+  inFlight.clear();
+  generation.clear();
+}

package/src/main.ts

@@ -112,6 +112,12 @@ import {
 import { reconstructPersistedTaskEnvironment } from "../lib/task-environment";
 import { logVnodePressure } from "../lib/vnode-pressure";
 import { resolveAppleTunnelRoute } from "./apple-tunnel-route";
+import {
+  invalidateMachineTunnelRoute,
+  resolveMachineTunnelRoute,
+} from "./machine-tunnel-route";
+import { armConnectTimeout } from "./tunnel-dial";
+import { scheduleActivationRespawn } from "./activation-respawn";
 import {
   configureBundledContainerRuntime,
   selectedRuntimeMatchesPersistedTaskEnvironments,
@@ -554,9 +560,16 @@ async function startLocalUi(): Promise<void> {
       stopTask: async (taskId) => {
         const runtimeProblem = containerRuntimeProblem();
         if (runtimeProblem) return { ok: false, error: runtimeProblem };
-        const result = await getOrchestrator().stopTask(taskId);
-        if (result.ok) queueStoppedTaskStatus(taskId);
-        return result;
+        // ADR-121: a stopped machine loses its memoised address (same
+        // before-and-after discipline as the cloud's taskStop command).
+        invalidateMachineTunnelRoute(taskId);
+        try {
+          const result = await getOrchestrator().stopTask(taskId);
+          if (result.ok) queueStoppedTaskStatus(taskId);
+          return result;
+        } finally {
+          invalidateMachineTunnelRoute(taskId);
+        }
       },
     });
     console.log(`[host-agent] local UI on http://127.0.0.1:${handle.port}`);
@@ -1852,6 +1865,18 @@ function handleHttpTunnelOpen(
     },
   );
 
+  // ADR-121: a memoised machine address may black-hole (instance stopped
+  // while memoised), and a black-holed dial neither errors nor answers for
+  // the kernel's SYN budget. Bound the connect phase only — never `timeout`
+  // on the request, which is idle semantics and would cut quiet streams. A
+  // socket the agent reuses arrives connected and is left alone.
+  if (target.connectTimeoutMs !== undefined && !target.socket) {
+    const connectTimeoutMs = target.connectTimeoutMs;
+    upstream.once("socket", (socket: Socket) => {
+      armConnectTimeout(socket, target, connectTimeoutMs);
+    });
+  }
+
   // Registering replays anything that arrived while the target resolved — for a
   // bodyless GET that is the `requestEnd` this request cannot reply without.
   tunnels.register(frame.tunnelId, upstream);
@@ -1861,6 +1886,9 @@ function handleHttpTunnelOpen(
     // ADR-043: if this was an ad-hoc preview sidecar, drop its cached port so
     // the next request recreates it (no-op for published / container-IP targets).
     invalidatePreviewSidecar(target.port);
+    // ADR-121: a memoised machine address that no longer answers is stale —
+    // a refused dial and a connect timeout (tunnel-dial.ts) both land here.
+    invalidateMachineTunnelRoute(frame.taskId);
     if (!acked) {
       send(wsSocket, {
         kind: "tunnel.ack",
@@ -1927,6 +1955,8 @@ function handleRawTunnelOpen(
     // ADR-043: if this was an ad-hoc preview sidecar, drop its cached port so
     // the next request recreates it (no-op for published / container-IP targets).
     invalidatePreviewSidecar(target.port);
+    // ADR-121: a memoised machine address that no longer answers is stale.
+    invalidateMachineTunnelRoute(frame.taskId);
     if (!acked) {
       send(wsSocket, {
         kind: "tunnel.ack",
@@ -1954,7 +1984,16 @@ function handleRawTunnelOpen(
     });
   });
 
-  if (!target.socket) upstream.connect(target.port, target.host);
+  if (!target.socket) {
+    upstream.connect(target.port, target.host);
+    // ADR-121: a memoised machine address may black-hole; bound the connect
+    // phase (tunnel-dial.ts) so the 'error' handler above runs and drops the
+    // memo instead of the pane hanging on the kernel's SYN budget. Armed
+    // after connect() so the socket is `connecting`; disarmed on 'connect'.
+    if (target.connectTimeoutMs !== undefined) {
+      armConnectTimeout(upstream, target, target.connectTimeoutMs);
+    }
+  }
   // AFTER `connect`, not before: replaying a queued write onto a socket that
   // has not started connecting errors, while node buffers writes made once it
   // is connecting. An upgrade's own request goes out from the `connect`
@@ -1988,6 +2027,12 @@ interface UpstreamAddr {
    * (ADR-106 apple routing). An established TCP peer cannot be retargeted by
    * later IP reuse, so consumers must use this socket instead of redialing. */
   socket?: Socket;
+  /** Connect-phase bound for a dial to this address, set only by the ADR-121
+   * machine branch: its address is memoised and may black-hole after an
+   * external stop, and a black-holed dial neither errors nor answers for the
+   * kernel's SYN budget. Loopback, sidecar and pre-established (`socket`)
+   * targets carry none — their dials fail fast or are already connected. */
+  connectTimeoutMs?: number;
 }
 
 async function resolveTunnelTarget(
@@ -2004,17 +2049,23 @@ async function resolveTunnelTarget(
     // the container runtime's health. macOS-local machines need a published
     // fallback (bridge IPs are not host-routable there) — recorded ADR-121
     // follow-up, not silently misrouted: the connect simply fails.
-    const environment = await reconstructPersistedTaskEnvironment(machineTask);
-    const route = environment?.inspectRoute
-      ? await environment.inspectRoute()
-      : null;
-    if (!route || route.kind !== "running") return null;
-    const port =
-      frame.target === "editor"
-        ? (machineTask.codeServerPort ?? null)
-        : (frame.containerPort ?? null);
-    if (!port) return null;
-    return { host: route.ipv4Address, port };
+    // The address resolution is a cloud API call and the cloud opens one
+    // tunnel per request, so it is memoised per task for a short TTL and
+    // dropped on a failed dial or a stop — see machine-tunnel-route.ts.
+    return resolveMachineTunnelRoute(
+      {
+        taskId: frame.taskId,
+        target: frame.target,
+        ...(frame.containerPort !== undefined
+          ? { containerPort: frame.containerPort }
+          : {}),
+      },
+      machineTask,
+      {
+        reconstruct: (task) => reconstructPersistedTaskEnvironment(task),
+        now: Date.now,
+      },
+    );
   }
   if (containerRuntimeProblem()) return null;
   const task = getHostTask(frame.taskId);
@@ -2275,18 +2326,36 @@ async function dispatchCommand(
   args: unknown[],
 ): Promise<HostCommandResult<unknown>> {
   switch (command) {
-    case "taskUp":
-      return hostCommands.taskUp(ctx, expectTaskLaunchInput(args, 0));
+    case "taskUp": {
+      const launchInput = expectTaskLaunchInput(args, 0);
+      // A (re)started machine may come back on a new address, and one just
+      // seen as not-running is about to run: forget both, before and after.
+      invalidateMachineTunnelRoute(launchInput.task.id);
+      return hostCommands
+        .taskUp(ctx, launchInput)
+        .finally(() => invalidateMachineTunnelRoute(launchInput.task.id));
+    }
     case "taskDown": {
       const downInput = expectTaskDownInput(args, 0);
-      return hostCommands.taskDown(ctx, downInput);
+      // A torn-down machine loses its address: drop the memo before (opens in
+      // flight must not re-memoise) and after (opens that raced the command).
+      invalidateMachineTunnelRoute(downInput.taskId);
+      return hostCommands
+        .taskDown(ctx, downInput)
+        .finally(() => invalidateMachineTunnelRoute(downInput.taskId));
+    }
+    case "taskStop": {
+      const stopTaskId = typeof args[0] === "string" ? args[0] : "";
+      // A stopped machine loses its address; same before-and-after discipline.
+      invalidateMachineTunnelRoute(stopTaskId);
+      return hostCommands
+        .taskStop(
+          ctx,
+          stopTaskId,
+          (args[1] ?? { reason: "manual" }) as { reason: "idle" | "manual" },
+        )
+        .finally(() => invalidateMachineTunnelRoute(stopTaskId));
     }
-    case "taskStop":
-      return hostCommands.taskStop(
-        ctx,
-        typeof args[0] === "string" ? args[0] : "",
-        (args[1] ?? { reason: "manual" }) as { reason: "idle" | "manual" },
-      );
     case "taskStatus":
       return hostCommands.taskStatus(ctx, expectString(args, 0));
     case "channelEnsure":
@@ -3330,13 +3399,27 @@ function maybeExit(): void {
     }
     if (ws.readyState === WebSocket.CLOSING) return;
   }
+  if (shutdownExitCode === MANAGED_UPDATE_RESTART_EXIT_CODE) {
+    // The drain is complete: this is the last thing the old generation does.
+    // On a launchd host the respawn is scheduled from here rather than left
+    // to KeepAlive — see activation-respawn.ts for the two 2026-09-06 stalls.
+    const plan = scheduleActivationRespawn();
+    console.log(
+      plan.scheduled
+        ? `[host-agent] exiting ${shutdownExitCode} for the supervisor to relaunch runtime/current; launchctl kickstart ${plan.target} is scheduled in ${plan.delaySeconds}s in case KeepAlive does not respawn the job`
+        : `[host-agent] exiting ${shutdownExitCode} for the supervisor to relaunch runtime/current (no launchctl kickstart scheduled: ${plan.reason})`,
+    );
+  }
   process.exit(shutdownExitCode);
 }
 
 /**
  * Finish any in-flight bridge command, then let the service supervisor exec
  * the newly activated `runtime/current`. The non-zero status is intentional:
- * Linux uses Restart=on-failure, while launchd KeepAlive also respawns it.
+ * Linux uses Restart=on-failure and the desktop supervisor restarts on any
+ * exit. launchd's KeepAlive is supposed to respawn it too but has been seen
+ * not to (2026-09-06, twice), so maybeExit() also schedules an explicit
+ * `launchctl kickstart` on macOS before the process exits.
  */
 export function requestManagedHostRestart(): void {
   shutdownExitCode = MANAGED_UPDATE_RESTART_EXIT_CODE;

package/src/tunnel-dial.ts

@@ -0,0 +1,102 @@
+/**
+ * Connect-phase timeout for tunnel upstream dials to a memoised address.
+ *
+ * An ADR-121 machine task's `{host, port}` comes from a 45 s memo
+ * (`machine-tunnel-route.ts`) that is dropped when a dial fails. A machine
+ * stopped or terminated while its address is memoised does not refuse the
+ * dial — it black-holes it: no SYN answer, so neither `connect` nor `error`
+ * fires until the kernel gives up on retransmits (~75 s macOS, ~127 s Linux).
+ * The memo's failure-driven invalidation never runs in that window and the
+ * pane or editor hangs on every open. An in-region machine answers a SYN in
+ * milliseconds, the cloud waits 30 s for the ack (`TUNNEL_ACK_TIMEOUT_MS`)
+ * and the forward hop 45 s for the head, so a 10 s connect bound is generous
+ * to a live machine and well inside what the caller will still accept.
+ *
+ * Only the connect phase is timed: the deadline is armed while the socket is
+ * `connecting` and disarmed by `connect` (or by the dial failing on its own).
+ * It is NOT an idle timeout — a quiet VNC/SSE/code-server stream after the
+ * handshake must live forever (see the tunnel rules in docs/agent-notes.md).
+ * A timeout destroys the socket with an error carrying `code = "ETIMEDOUT"`
+ * and `syscall = "connect"`, so the dial path's existing `'error'` handler
+ * runs unchanged: it acks the cloud with the same 502 shape as any other
+ * dial failure and invalidates the machine route memo.
+ */
+
+export interface DialTarget {
+  readonly host: string;
+  readonly port: number;
+}
+
+/** The slice of `net.Socket` the timeout needs; tests pass a fake. */
+export interface DialSocket {
+  /** True from `connect()` until the handshake completes. False on a socket
+   * handed over already connected (an agent's reused keep-alive socket, an
+   * ADR-106 pre-established apple route) — those are never armed. */
+  readonly connecting: boolean;
+  once(event: "connect" | "error" | "close", listener: () => void): unknown;
+  destroy(error?: Error): unknown;
+}
+
+export interface DialTimers {
+  setTimeout(callback: () => void, delayMs: number): NodeJS.Timeout;
+  clearTimeout(timer: NodeJS.Timeout): void;
+}
+
+export const CONNECT_TIMEOUT_ERROR_CODE = "ETIMEDOUT" as const;
+
+export interface ConnectTimeoutError extends Error {
+  readonly code: typeof CONNECT_TIMEOUT_ERROR_CODE;
+  readonly syscall: "connect";
+  readonly address: string;
+  readonly port: number;
+}
+
+export function connectTimeoutError(
+  target: DialTarget,
+  timeoutMs: number,
+): ConnectTimeoutError {
+  return Object.assign(
+    new Error(
+      `connect ETIMEDOUT ${target.host}:${target.port} (no answer within ${timeoutMs} ms)`,
+    ),
+    {
+      code: CONNECT_TIMEOUT_ERROR_CODE,
+      syscall: "connect" as const,
+      address: target.host,
+      port: target.port,
+    },
+  );
+}
+
+export function isConnectTimeoutError(error: unknown): error is ConnectTimeoutError {
+  return (
+    error instanceof Error &&
+    (error as Partial<ConnectTimeoutError>).code === CONNECT_TIMEOUT_ERROR_CODE &&
+    (error as Partial<ConnectTimeoutError>).syscall === "connect"
+  );
+}
+
+/**
+ * Arm a connect deadline on a socket that has started (or is about to be
+ * handed a started) connect. Returns whether a deadline was armed — false for
+ * a socket that is already connected, which has nothing to time.
+ */
+export function armConnectTimeout(
+  socket: DialSocket,
+  target: DialTarget,
+  timeoutMs: number,
+  timers: DialTimers = { setTimeout, clearTimeout },
+): boolean {
+  if (!socket.connecting) return false;
+  const deadline = timers.setTimeout(() => {
+    socket.destroy(connectTimeoutError(target, timeoutMs));
+  }, timeoutMs);
+  deadline.unref?.();
+  const disarm = (): void => {
+    timers.clearTimeout(deadline);
+  };
+  socket.once("connect", disarm);
+  socket.once("error", disarm);
+  socket.once("close", disarm);
+  return true;
+}