@runuai/host 0.9.98 → 0.9.100

package/lib/orchestrator.ts

@@ -106,14 +106,14 @@ import {
 } from "./browser-testing";
 import { injectCodexIntoContainer } from "./codex-auth";
 import {
+  codexHomeIsolatable,
+  codexHomeSeedCommand,
+  codexPerAgentHome,
   cooldownEngineAccount,
   noteEngineAccountUsed,
   pickEngineAccount,
   provisionEngineAccounts,
   resolveEngineAccounts,
-  codexHomeIsolatable,
-  codexPerAgentHome,
-  codexHomeSeedCommand,
   type ResolvedEngineAccount,
 } from "./engine-accounts";
 import { clearTaskGatewayAcl, setupMcpTaskConfig } from "./mcp-gateway";
@@ -133,6 +133,7 @@ import type {
   HostEvent,
 } from "../src/protocol";
 import {
+  HOST_ACCOUNT_SCOPE,
   MAX_AGENT_ID_CHARS,
   MAX_SECRETARY_DISPATCH_ID_CHARS,
   SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE,
@@ -155,6 +156,9 @@ const RESTRICTED_SECRETARY_SESSION_ATTACH_KEY =
 interface Channel {
   taskId: string;
   roster: Roster;
+  /** ADR-131 D3: the engine-account scope this task's agents resolve
+   *  credentials from. `host` unless the cloud scoped the task to a workspace. */
+  engineAccountScope: string;
   /** ADR-083: host-derived role assignment for execution-profile enforcement. */
   mode: "open" | "secretary";
   secretaryAgentId?: string;
@@ -527,6 +531,7 @@ export class Orchestrator {
     channel.browserTesting = spec.browserTesting === true;
     channel.sharedFiles = spec.sharedFiles ?? "ro";
     channel.mcpConnections = spec.mcpConnections ?? [];
+    if (spec.engineAccountScope) channel.engineAccountScope = spec.engineAccountScope;
     const nextMcpShape = JSON.stringify({
       connections: channel.mcpConnections,
       kinds: [...new Set(channel.roster.map((agent) => agent.kind))].sort(),
@@ -640,6 +645,10 @@ export class Orchestrator {
     const channel: Channel = {
       taskId,
       roster,
+      engineAccountScope:
+        spec.engineAccountScope ??
+        getHostTask(taskId)?.engineAccountScope ??
+        HOST_ACCOUNT_SCOPE,
       mode: spec.mode === "secretary" ? "secretary" : "open",
       secretaryAgentId: spec.secretaryAgentId,
       sessions: new Map(),
@@ -797,9 +806,9 @@ export class Orchestrator {
    * copies use this gate: a false→true toggle queues migration after the older
    * copy, so that copy cannot land last and erase the managed browser block.
    */
-  private codexHomes(hasCodex: boolean): string[] {
+  private codexHomes(hasCodex: boolean, scope: string): string[] {
     if (!hasCodex) return [];
-    const homes = resolveEngineAccounts("codex")
+    const homes = resolveEngineAccounts("codex", {}, scope)
       .map((account) => account.configDir?.containerDir)
       .filter((home): home is string => Boolean(home));
     return [...new Set([DEFAULT_CODEX_HOME, ...homes])];
@@ -825,9 +834,9 @@ export class Orchestrator {
     if (this.isActiveChannel(channel)) channel.configGeneration += 1;
   }
 
-  private provisionFingerprint(kinds: readonly string[]): string {
+  private provisionFingerprint(kinds: readonly string[], scope: string): string {
     const accounts = kinds.flatMap((kind) =>
-      resolveEngineAccounts(kind)
+      resolveEngineAccounts(kind, {}, scope)
         .filter((account) => !account.isDefault && account.configDir)
         .map((account) => ({
           kind,
@@ -864,15 +873,15 @@ export class Orchestrator {
     const requestedHasCodex =
       hasCodex || channel.roster.some((agent) => agent.kind === "codex");
     const requestedHomes = requestedBrowser
-      ? this.codexHomes(requestedHasCodex)
+      ? this.codexHomes(requestedHasCodex, channel.engineAccountScope)
       : [];
     const requestedKinds = [
       ...new Set(channel.roster.map((agent) => agent.kind)),
     ];
     const requestedProvisionFingerprint =
-      this.provisionFingerprint(requestedKinds);
+      this.provisionFingerprint(requestedKinds, channel.engineAccountScope);
     const mayProvisionConfig = requestedKinds.some((kind) =>
-      resolveEngineAccounts(kind).some(
+      resolveEngineAccounts(kind, {}, channel.engineAccountScope).some(
         (account) => !account.isDefault && Boolean(account.configDir),
       ),
     );
@@ -891,13 +900,13 @@ export class Orchestrator {
         requestedHasCodex ||
         channel.roster.some((agent) => agent.kind === "codex");
       const latestHomes = latestBrowser
-        ? this.codexHomes(latestHasCodex)
+        ? this.codexHomes(latestHasCodex, channel.engineAccountScope)
         : [];
       const latestKinds = [
         ...new Set(channel.roster.map((agent) => agent.kind)),
       ];
       const latestProvisionFingerprint =
-        this.provisionFingerprint(latestKinds);
+        this.provisionFingerprint(latestKinds, channel.engineAccountScope);
       if (
         (latestBrowser &&
           coverage?.browserAttempted !== true &&
@@ -949,10 +958,14 @@ export class Orchestrator {
                   requestedKinds,
                   {},
                   channel.agentHandle,
+                  channel.engineAccountScope,
                 )
               : await provisionEngineAccounts(
                   channel.containerName,
                   requestedKinds,
+                  {},
+                  undefined,
+                  channel.engineAccountScope,
                 );
             copiedOrUnknown =
               provisioned.copied > 0 || provisioned.mayHaveMutated;
@@ -1075,12 +1088,15 @@ export class Orchestrator {
       requestedHasCodex ||
       channel.roster.some((agent) => agent.kind === "codex");
     const latestHomes = latestBrowser
-      ? this.codexHomes(latestHasCodex)
+      ? this.codexHomes(latestHasCodex, channel.engineAccountScope)
       : [];
     const latestKinds = [
       ...new Set(channel.roster.map((agent) => agent.kind)),
     ];
-    const latestProvisionFingerprint = this.provisionFingerprint(latestKinds);
+    const latestProvisionFingerprint = this.provisionFingerprint(
+      latestKinds,
+      channel.engineAccountScope,
+    );
     if (
       (latestBrowser &&
         !coverage.browserAttempted &&
@@ -1169,7 +1185,7 @@ export class Orchestrator {
       ...new Set(channel.roster.map((agent) => agent.kind)),
     ].sort();
     const codexHomes = engineKinds.includes("codex")
-      ? this.codexHomes(true)
+      ? this.codexHomes(true, channel.engineAccountScope)
       : [];
     const fingerprint = JSON.stringify({
       connections,
@@ -1529,7 +1545,9 @@ export class Orchestrator {
     agent: RosterAgent,
     base: Record<string, string>,
   ): Record<string, string> {
-    const account = pickEngineAccount(agent.kind);
+    const account = pickEngineAccount(agent.kind, {
+      scope: channel.engineAccountScope,
+    });
     if (!account) {
       channel.accountByAgent.delete(agent.id);
       return base;
@@ -2598,7 +2616,7 @@ export class Orchestrator {
       );
       const boundAccountId = channel.accountByAgent.get(agentId);
       const boundAccount = boundAccountId
-        ? resolveEngineAccounts(agent.kind).find(
+        ? resolveEngineAccounts(agent.kind, {}, channel.engineAccountScope).find(
             (account) => account.id === boundAccountId,
           )
         : undefined;
@@ -2667,7 +2685,9 @@ export class Orchestrator {
     // A concurrent terminal event for the same session is already being
     // handled by the path that owns this spawn slot.
     if (channel.spawning.has(agentId)) return true;
-    if (resolveEngineAccounts(agent.kind).length < 2) return false;
+    if (resolveEngineAccounts(agent.kind, {}, channel.engineAccountScope).length < 2) {
+      return false;
+    }
 
     const budget = (channel.rotations.get(agentId) ?? 0) + 1;
     channel.rotations.set(agentId, budget);
@@ -2676,6 +2696,7 @@ export class Orchestrator {
     const current = channel.accountByAgent.get(agentId);
     if (current) cooldownEngineAccount(current);
     const next = pickEngineAccount(agent.kind, {
+      scope: channel.engineAccountScope,
       exclude: current ? new Set([current]) : undefined,
     });
     if (!next) return false;
@@ -2918,7 +2939,7 @@ export class Orchestrator {
       return;
     }
 
-    const accounts = resolveEngineAccounts(agent.kind);
+    const accounts = resolveEngineAccounts(agent.kind, {}, channel.engineAccountScope);
     const account =
       accounts.find((a) => a.id === channel.accountByAgent.get(agentId)) ??
       accounts[0];

package/lib/runtime-state.ts

@@ -231,12 +231,14 @@ export function recordTaskOwner(
   ownerEmail: string | null,
   ownerName: string | null,
   projectSlugs: string[],
+  engineAccountScope: string | null = null,
 ): void {
   upsertHostTask(taskId, {
     ownerUserId,
     ownerEmail,
     ownerName,
     projectSlugs: JSON.stringify(projectSlugs),
+    engineAccountScope,
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.98",
+  "version": "0.9.100",
   "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/index.ts

@@ -768,6 +768,8 @@ export const hostCommands: HostCommands = {
         input.ownerEmail ?? null,
         input.ownerName ?? null,
         input.projects.map((p) => p.slug),
+        // ADR-131 D3: persisted so recovery re-provisions the same scope.
+        input.task.engineAccountScope ?? null,
       );
       // ADR-048: persist the cloud-issued per-task cli secret (host-private) so the
       // `uai` CLI's per-agent tokens can be minted now + after a host restart.
@@ -1227,7 +1229,7 @@ export const hostCommands: HostCommands = {
   async engineAccountRemove(ctx, input) {
     logCommand(ctx, "engineAccountRemove", input.id);
     try {
-      const result = removeEngineAccount(input.id);
+      const result = removeEngineAccount(input.id, input.scope);
       if (!result.ok) {
         return ok({ removed: false, message: result.message });
       }

package/src/machine-tunnel-route.ts

@@ -19,10 +19,14 @@
  * (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) hangs on the OS connect
- * timeout instead — machine dials carry no connect timeout of their own,
- * which predates this module — so the TTL is the real bound there.
+ * 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 =
@@ -52,6 +56,20 @@ export const MACHINE_ROUTE_TTL_MS = 45_000;
  * 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>();
@@ -66,7 +84,7 @@ export async function resolveMachineTunnelRoute<
   request: MachineTunnelRouteRequest,
   task: Task,
   deps: MachineTunnelRouteDeps<Task>,
-): Promise<{ host: string; port: number } | null> {
+): Promise<MachineTunnelRouteTarget | null> {
   // The cheap refusal first: an unroutable request never costs an API call.
   const port =
     request.target === "editor"
@@ -74,7 +92,9 @@ export async function resolveMachineTunnelRoute<
       : (request.containerPort ?? null);
   if (!port) return null;
   const host = await machineAddress(request.taskId, task, deps);
-  return host === null ? null : { host, port };
+  return host === null
+    ? null
+    : { host, port, connectTimeoutMs: MACHINE_DIAL_CONNECT_TIMEOUT_MS };
 }
 
 async function machineAddress<Task>(