@runuai/host 0.9.98 → 0.9.99

package/package.json

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

@@ -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>(

package/src/main.ts

@@ -116,6 +116,8 @@ import {
   invalidateMachineTunnelRoute,
   resolveMachineTunnelRoute,
 } from "./machine-tunnel-route";
+import { armConnectTimeout } from "./tunnel-dial";
+import { scheduleActivationRespawn } from "./activation-respawn";
 import {
   configureBundledContainerRuntime,
   selectedRuntimeMatchesPersistedTaskEnvironments,
@@ -1863,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);
@@ -1872,7 +1886,8 @@ 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.
+    // 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, {
@@ -1969,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`
@@ -2003,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(
@@ -3369,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;
+}