@runuai/host 0.9.98 → 0.9.100

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,
@@ -148,7 +150,7 @@ import {
   patchHostConfig,
   type HostConfigResult,
 } from "../lib/host-config";
-import { listEngineAccounts } from "../lib/engine-accounts";
+import { listEngineAccountsAllScopes } from "../lib/engine-accounts";
 import { createEngineConnectManager } from "../lib/engine-connect";
 import { createEngineLoginManager } from "../lib/engine-login";
 import {
@@ -180,7 +182,9 @@ import {
   HOST_TASK_STOP_PROTOCOL_FEATURE,
   HOST_ENGINE_ACCOUNTS_PROTOCOL_FEATURE,
   HOST_ENGINE_CONNECT_PROTOCOL_FEATURE,
+  HOST_ENGINE_ACCOUNT_SCOPES_PROTOCOL_FEATURE,
   HOST_ENGINE_LOGIN_PROTOCOL_FEATURE,
+  isEngineAccountScope,
   HOST_LOGS_PROTOCOL_FEATURE,
   HOST_TASK_INVENTORY_PROTOCOL_FEATURE,
   MAX_ENGINE_ACCOUNT_LABEL_CHARS,
@@ -599,6 +603,7 @@ function buildCapabilities(): HostCapabilities {
       HOST_TASK_STOP_PROTOCOL_FEATURE,
       HOST_ENGINE_ACCOUNTS_PROTOCOL_FEATURE,
       HOST_ENGINE_CONNECT_PROTOCOL_FEATURE,
+      HOST_ENGINE_ACCOUNT_SCOPES_PROTOCOL_FEATURE,
       // The echo adapter cannot execute the in-task CLI. Advertising typed
       // dispatch in mock mode would let the composer create a Secretary that
       // has no way to wake crew.
@@ -694,13 +699,15 @@ function engineAccountSummaries(): EngineAccountSummary[] {
   const summaries: EngineAccountSummary[] = [];
   for (const kind of ["claude", "codex", "opencode"] as const) {
     try {
-      for (const account of listEngineAccounts(kind)) {
+      // ADR-131 D3: every scope — the cloud filters per caller.
+      for (const account of listEngineAccountsAllScopes(kind)) {
         summaries.push({
           id: account.id,
           kind,
           label: account.label.slice(0, MAX_ENGINE_ACCOUNT_LABEL_CHARS),
           authKind: account.authKind,
           isDefault: account.isDefault,
+          scope: account.scope,
         });
       }
     } catch (error) {
@@ -1225,6 +1232,7 @@ async function connect(): Promise<void> {
           frame.engine,
           emitEngineLoginEvent,
           frame.label,
+          frame.scope,
         );
         break;
       case "engine.login.input":
@@ -1245,6 +1253,7 @@ async function connect(): Promise<void> {
           frame.secret,
           frame.label,
           (event) => sendRemoteOperationFrame(event),
+          frame.scope,
         );
         break;
       case "engine.connect.stop":
@@ -1863,6 +1872,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 +1893,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 +1991,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 +2034,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(
@@ -2404,7 +2441,7 @@ async function dispatchCommand(
 function expectEngineAccountRemoveInput(
   args: unknown[],
   index: number,
-): { id: string } {
+): { id: string; scope?: string } {
   const value = args[index];
   if (
     !value ||
@@ -2415,7 +2452,14 @@ function expectEngineAccountRemoveInput(
   ) {
     throw new Error(`invalid command args: expected account id at ${index}`);
   }
-  return { id: (value as { id: string }).id };
+  const scope = (value as { scope?: unknown }).scope;
+  if (scope !== undefined && !isEngineAccountScope(scope)) {
+    throw new Error(`invalid command args: bad account scope at ${index}`);
+  }
+  return {
+    id: (value as { id: string }).id,
+    ...(scope !== undefined ? { scope } : {}),
+  };
 }
 
 function expectNumberArg(args: unknown[], index: number): number {
@@ -3369,13 +3413,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/protocol.ts

@@ -102,6 +102,25 @@ export const MAX_ENGINE_ACCOUNTS_ADVERTISED = 48;
 /** ADR-117: one-shot engine credentials over the bridge + the full engine
  * catalog in capabilities, so every engine renders on the cloud pane. */
 export const HOST_ENGINE_CONNECT_PROTOCOL_FEATURE = "host-engine-connect-v1";
+/** ADR-131 Decision 3: engine accounts carry a scope — `host` (the owner's)
+ * or `org:<orgId>` (a workspace's account on a shared host). A host that
+ * advertises this accepts `scope` on engine.login.start / engine.connect.start
+ * / engineAccountRemove, `engineAccountScope` on channelEnsure and task-up,
+ * and stamps `scope` on every EngineAccountSummary it advertises. The cloud
+ * sends none of those to a host without the feature (the v1 exact-shape
+ * guards would reject the frames). */
+export const HOST_ENGINE_ACCOUNT_SCOPES_PROTOCOL_FEATURE =
+  "host-engine-account-scopes-v1";
+/** The owner-level account scope; every pre-scope account lives here. */
+export const HOST_ACCOUNT_SCOPE = "host";
+const ORG_ACCOUNT_SCOPE_RE = /^org:[A-Za-z0-9_-]{1,128}$/;
+/** `host` or `org:<orgId>` — bounded, single-token, safe in every surface. */
+export function isEngineAccountScope(value: unknown): value is string {
+  return (
+    value === HOST_ACCOUNT_SCOPE ||
+    (typeof value === "string" && ORG_ACCOUNT_SCOPE_RE.test(value))
+  );
+}
 export const MAX_ENGINE_CONNECT_SECRET_CHARS = 8_192;
 export const MAX_ENGINE_CONNECT_LINE_CHARS = 512;
 export const MAX_ENGINE_CATALOG_ENTRIES = 8;
@@ -307,6 +326,10 @@ export interface EngineLoginStartFrame {
    * slot. Only sent to hosts advertising `host-engine-accounts-v1`; the v1
    * exact-shape guard on older hosts rejects frames carrying it. */
   label?: string;
+  /** ADR-131 D3: capture into this account scope (`org:<orgId>` on a shared
+   * host). Only sent to hosts advertising `host-engine-account-scopes-v1`;
+   * absent = the host scope. An org scope requires a label. */
+  scope?: string;
 }
 
 /** The only generic one-time response channel. Long-lived tokens must never
@@ -379,6 +402,9 @@ export interface EngineAccountSummary {
   label: string;
   authKind: "env" | "config-dir";
   isDefault: boolean;
+  /** ADR-131 D3: `host` or `org:<orgId>`. Absent from hosts that predate
+   * scopes — read as `host`. */
+  scope?: string;
 }
 
 /** ADR-117 engine kinds — every engine the host's descriptor table knows. */
@@ -416,6 +442,8 @@ export interface EngineConnectStartFrame {
   engine: EngineConnectKind;
   secret?: string;
   label?: string;
+  /** ADR-131 D3: see EngineLoginStartFrame.scope. */
+  scope?: string;
 }
 
 export interface EngineConnectStopFrame {
@@ -454,13 +482,14 @@ export function isEngineConnectStartFrame(
   const frame = exactWireObject(
     value,
     ["kind", "opId", "engine"],
-    ["secret", "label"],
+    ["secret", "label", "scope"],
   );
   if (
     !frame ||
     frame.kind !== "engine.connect.start" ||
     !isHostOpId(frame.opId) ||
-    !isEngineConnectKind(frame.engine)
+    !isEngineConnectKind(frame.engine) ||
+    (frame.scope !== undefined && !isEngineAccountScope(frame.scope))
   ) {
     return false;
   }
@@ -705,13 +734,18 @@ export function isHostLogsEndFrame(value: unknown): value is HostLogsEndFrame {
 export function isEngineLoginStartFrame(
   value: unknown,
 ): value is EngineLoginStartFrame {
-  const frame = exactWireObject(value, ["kind", "opId", "engine"], ["label"]);
+  const frame = exactWireObject(
+    value,
+    ["kind", "opId", "engine"],
+    ["label", "scope"],
+  );
   return Boolean(
     frame &&
       frame.kind === "engine.login.start" &&
       isHostOpId(frame.opId) &&
       isEngineLoginKind(frame.engine) &&
-      (frame.label === undefined || isEngineAccountLabel(frame.label)),
+      (frame.label === undefined || isEngineAccountLabel(frame.label)) &&
+      (frame.scope === undefined || isEngineAccountScope(frame.scope)),
   );
 }
 
@@ -1087,6 +1121,9 @@ export interface TaskCommandTask {
   previewEnv?: Record<string, string>;
   /** ADR-062: owning org — locates the org shared-files root on the host. */
   ownerOrgId?: string;
+  /** ADR-131 D3: the engine-account scope the task's agents resolve
+   *  credentials from (`org:<orgId>` on a shared host). Absent = `host`. */
+  engineAccountScope?: string;
   /** ADR-062: shared-files mount mode ("off" | "ro" | "rw"; default "ro"). */
   sharedFiles?: string;
 }
@@ -1188,6 +1225,10 @@ export interface ChannelEnsureInput {
   /** ADR-053: any joined project opted into browser testing — the host wires
    *  the Playwright MCP browser at session start. */
   browserTesting?: boolean;
+  /** ADR-131 D3: see TaskCommandTask.engineAccountScope — the channel's
+   *  agents pick accounts from this scope. Absent = the task's persisted
+   *  scope, else `host`. */
+  engineAccountScope?: string;
   /** ADR-057: the owner's usable MCP connections (policy "on", connected,
    *  remote). The host writes gateway-URL MCP configs at session start. */
   mcpConnections?: Array<{ id: string; slug: string }>;
@@ -1358,7 +1399,7 @@ export interface HostCommands {
    * exactly like the local API; re-advertises capabilities on success. */
   engineAccountRemove(
     ctx: CommandContext,
-    input: { id: string },
+    input: { id: string; scope?: string },
   ): Promise<HostCommandResult<{ removed: boolean; message?: string }>>;
   cloneRepo(
     ctx: CommandContext,

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;
+}