@runuai/host 0.9.14 → 0.9.43

package/src/main.ts

@@ -22,8 +22,21 @@ import {
   markDisconnected,
   markReconnecting,
 } from "../lib/cloud-state";
-import { getHostTask } from "../lib/runtime-state";
-import { getOrchestrator, recoveryComplete } from "../lib/orchestrator";
+import {
+  applyTerminalHistoryRetention,
+  getHostTask,
+  hasInFlightHostTaskLifecycle,
+} from "../lib/runtime-state";
+import { StoppedTaskStatusQueue } from "../lib/stopped-task-status-queue";
+import {
+  getOrchestrator,
+  quarantineWritableRuntimeContainers,
+  recoveryComplete,
+  requestRuntimeRecovery,
+  resumeRuntimeDeferredAgentWork,
+  runtimeRecoveryVerdict,
+  waitForRuntimeRecovery,
+} from "../lib/orchestrator";
 import {
   claimGithubCredentialGeneration,
   connectedUserIds,
@@ -58,7 +71,9 @@ import { handleMcpOp } from "../lib/mcp-connections";
 import { startMcpGateway } from "../lib/mcp-gateway";
 import { addHostBreadcrumb, initHostObs, setHostObsTag } from "../lib/obs";
 import {
+  hostIdFilePath,
   packageVersion,
+  readPersistedHostId,
   serviceLogPath,
   uiAssetsDir,
   uiPortFilePath,
@@ -66,10 +81,45 @@ import {
 import { dockerMemoryBytes, startUiServer } from "./ui/server";
 import { parsePreviewPortRuntimes } from "../lib/preview-ports";
 import { dockerCli } from "../lib/docker-exec";
+import {
+  hostTaskInventorySnapshots,
+  isSafeHostTaskId,
+  isSafeInventoryScanId,
+} from "../lib/task-inventory";
+import { setContainerRuntimeOperationalCheck } from "../lib/runtime-guard";
+import {
+  RuntimeActivationTail,
+  runMaintainedRuntimeActivation,
+  type RuntimeActivationAttemptResult,
+} from "../lib/runtime-activation-tail";
+import {
+  containerRuntimeActivationRequired,
+  containerRuntimeBecameReady,
+  containerRuntimeCapabilityState,
+  containerRuntimeEpochIsCurrent,
+  containerRuntimeProblem,
+  containerRuntimeReadinessEpoch,
+  containerRuntimeState,
+  forceContainerRuntimeRecheck,
+  initializeContainerRuntime,
+  markContainerRuntimeOperational,
+  onContainerRuntimeChange,
+  startContainerRuntimeAutoRecheck,
+  suspendContainerRuntime,
+  containerRuntimeMachineIdentity,
+  publishActivationPhase,
+} from "../lib/container-runtime";
+import { reconstructPersistedTaskEnvironment } from "../lib/task-environment";
+import { resolveAppleTunnelRoute } from "./apple-tunnel-route";
+import {
+  configureBundledContainerRuntime,
+  selectedRuntimeMatchesPersistedTaskEnvironments,
+} from "./runtime-bootstrap";
 import {
   ensurePreviewSidecar,
   invalidatePreviewSidecar,
 } from "../lib/preview-sidecar";
+import { inspectTunnelContainer } from "../lib/tunnel-runtime";
 import { TunnelRegistry } from "../lib/tunnel-registry";
 import { newId } from "../lib/ulid";
 import {
@@ -77,18 +127,44 @@ import {
   onChange as onRegistryChange,
 } from "../lib/agents/registry";
 import { canAdvertiseTypedSecretaryDispatch } from "../lib/agents/mode";
+import { MANAGED_UPDATE_RESTART_EXIT_CODE } from "../lib/managed-runtime";
+import { ManagedOperationDrain } from "../lib/managed-operation-drain";
+import {
+  createHostLogManager,
+  HostLogStartError,
+  type HostLogsEmit,
+} from "../lib/host-logs";
+import {
+  getHostConfig,
+  patchHostConfig,
+  type HostConfigResult,
+} from "../lib/host-config";
+import { createEngineLoginManager } from "../lib/engine-login";
 // Importing the real factory triggers the built-in adapters' register()
 // calls (claude, codex), so the registry is populated before we advertise.
 import "../lib/agents/factory";
-import { ensureStandardImage, standardRuntimes } from "../lib/standard-image";
+import {
+  areAgentClisReady,
+  configuredOptionalEngines,
+  ensureStandardImage,
+  onAgentClisReady,
+  standardRuntimes,
+} from "../lib/standard-image";
 import { hostCommands, hostEvents } from "./index";
-import { EventOutbox } from "./event-outbox";
+import { EventOutbox, transmitEventOutbox } from "./event-outbox";
 import {
   HostErrorCode,
   EVENT_REPLAY_PROTOCOL_FEATURE,
   GITHUB_CREDENTIAL_GENERATION_PROTOCOL_FEATURE,
   GITHUB_INSTALLATION_VERIFICATION_PROTOCOL_FEATURE,
   GITHUB_REPOSITORY_ACCESS_PROTOCOL_FEATURE,
+  HOST_MAINTENANCE_READINESS_PROTOCOL_FEATURE,
+  HOST_CONFIG_PROTOCOL_FEATURE,
+  HOST_ENGINE_LOGIN_PROTOCOL_FEATURE,
+  HOST_LOGS_PROTOCOL_FEATURE,
+  HOST_TASK_INVENTORY_PROTOCOL_FEATURE,
+  MAX_HOST_TASK_INVENTORY_PAGE_SIZE,
+  MCP_GATEWAY_HEALTH_PROTOCOL_FEATURE,
   SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE,
   TRANSCRIPT_TARGETS_PROTOCOL_FEATURE,
   type CloudToHost,
@@ -103,6 +179,14 @@ import {
   parseGitHubCredentialGeneration,
   parseChannelMode,
   parseTranscriptTargets,
+  isEngineLoginCallbackFrame,
+  isEngineLoginInputFrame,
+  isEngineLoginStartFrame,
+  isEngineLoginStopFrame,
+  isHostConfigGetFrame,
+  isHostConfigSetFrame,
+  isHostLogsStartFrame,
+  isHostLogsStopFrame,
   type TaskAgent,
   type TaskCommandProject,
   type TaskCommandTask,
@@ -112,6 +196,8 @@ import {
   type FilesOpInput,
 } from "./protocol";
 
+setContainerRuntimeOperationalCheck(() => containerRuntimeProblem() === null);
+
 // Crash reporting (ADR-071) — default-ON for installed hosts via the baked
 // DSN (lib/obs.ts); repo checkouts and dev/test never default-activate.
 // UAI_TELEMETRY_DISABLED=1 turns it off; UAI_SENTRY_DSN overrides.
@@ -146,9 +232,70 @@ let ws: WebSocket | null = null;
 let stopping = false;
 let fatal = false;
 let reconnectAttempt = 0;
+let connectionRequestGeneration = 0;
 let inFlight = 0;
 let shutdownRequested = false;
+let shutdownExitCode = 0;
+const managedMutationDrain = new ManagedOperationDrain(maybeExit);
+const hostLogManager = createHostLogManager();
+const pendingRemoteOperationCleanups = new Set<Promise<void>>();
+let stopActiveRemoteOperations = (): Promise<void> => Promise.resolve();
+
+function trackRemoteOperationCleanup(cleanup: Promise<void>): Promise<void> {
+  const tracked = cleanup.catch(() => {
+    // A replacement generation must fail closed if an unforeseen manager bug
+    // escapes its best-effort cleanup contract. Shutdown may still exit after
+    // the failed cleanup settles so the service supervisor can recover.
+    fatal = true;
+    console.warn("[host-agent] remote operation cleanup failed");
+  });
+  pendingRemoteOperationCleanups.add(tracked);
+  void tracked.finally(() => {
+    pendingRemoteOperationCleanups.delete(tracked);
+    maybeExit();
+  });
+  return tracked;
+}
+
+function stopRemoteOperationManagers(): Promise<void> {
+  hostLogManager.stopAll();
+  return trackRemoteOperationCleanup(
+    Promise.all([
+      engineLoginManager.stopAll(),
+      // Tunnel upstreams are generation-scoped resources just like login
+      // containers; a bridge replacement or shutdown must join their
+      // asynchronous release before a new socket/process generation is
+      // admitted.
+      tunnels.abortAll(),
+    ]).then(() => undefined),
+  );
+}
+
+async function waitForRemoteOperationCleanups(): Promise<void> {
+  // A stop admitted just before disconnect may have detached its operation
+  // from the manager map already. Join the globally tracked stop as well as
+  // stopAll(), and loop in case settling one cleanup queues its exact sweep.
+  while (pendingRemoteOperationCleanups.size > 0) {
+    await Promise.all([...pendingRemoteOperationCleanups]);
+  }
+}
+
 let pendingBinaryTunnelId: string | null = null;
+const pendingRuntimeIsolationStatuses = new StoppedTaskStatusQueue(
+  (taskId) => getHostTask(taskId)?.statusMirror,
+);
+let stopRuntimeAutoRecheck = (): void => {};
+const runtimeActivationTail = new RuntimeActivationTail({
+  isCurrent: runtimeActivationIsCurrent,
+  onError: (error) =>
+    console.warn(
+      `[host-agent] container runtime activation failed: ${error instanceof Error ? error.message : String(error)}`,
+    ),
+  onExhausted: (_epoch, attempts) =>
+    console.warn(
+      `[host-agent] container runtime recovery remained unresolved after ${attempts} follow-up attempt(s); leaving the host in checking until the next runtime recheck`,
+    ),
+});
 const tunnels = new TunnelRegistry();
 
 // ADR-103: event outbox. BOOT_ID scopes seqs to this process lifetime; the
@@ -162,7 +309,37 @@ const eventOutbox = new EventOutbox();
 // replay cursor (or the fallback timer concedes the cloud predates ADR-103).
 let eventFlushEnabled = false;
 let resumeFallbackTimer: NodeJS.Timeout | null = null;
+let eventFlushBackpressureTimer: NodeJS.Timeout | null = null;
 const RESUME_FALLBACK_MS = 3_000;
+const EVENT_FLUSH_POLL_MS = 5;
+
+function cancelEventFlushBackpressureTimer(): void {
+  if (!eventFlushBackpressureTimer) return;
+  clearTimeout(eventFlushBackpressureTimer);
+  eventFlushBackpressureTimer = null;
+}
+
+function scheduleEventFlushAfterBackpressure(socket: WebSocket): void {
+  if (eventFlushBackpressureTimer) return;
+  const poll = (): void => {
+    eventFlushBackpressureTimer = null;
+    if (
+      !eventFlushEnabled ||
+      ws !== socket ||
+      socket.readyState !== WebSocket.OPEN
+    ) {
+      return;
+    }
+    if (socket.bufferedAmount > MAX_WS_BUFFERED_BYTES / 2) {
+      eventFlushBackpressureTimer = setTimeout(poll, EVENT_FLUSH_POLL_MS);
+      eventFlushBackpressureTimer.unref?.();
+      return;
+    }
+    flushEvents();
+  };
+  eventFlushBackpressureTimer = setTimeout(poll, EVENT_FLUSH_POLL_MS);
+  eventFlushBackpressureTimer.unref?.();
+}
 
 function flushEvents(): void {
   const socket = ws;
@@ -175,7 +352,16 @@ function flushEvents(): void {
       `[host-agent] event outbox overflowed: ${dropped} unsent event(s) lost`,
     );
   }
-  for (const entry of eventOutbox.drain()) socket.send(entry.raw);
+  const result = transmitEventOutbox(
+    eventOutbox,
+    socket,
+    MAX_WS_BUFFERED_BYTES,
+  );
+  if (result === "backpressured") {
+    scheduleEventFlushAfterBackpressure(socket);
+  } else if (result === "send_failed") {
+    socket.close(1011, "event transmission failed");
+  }
 }
 
 interface PausableSource {
@@ -186,6 +372,38 @@ interface PausableSource {
 
 console.log(`[host-agent] starting host ${hostId}`);
 migrateHostDb();
+// Reconcile a durable retention-off setting before recovery/connect can make
+// crash-left owner-facing terminal history observable again. Correctness
+// tombstones remain intact inside applyTerminalHistoryRetention.
+applyTerminalHistoryRetention();
+try {
+  await configureBundledContainerRuntime();
+} catch {
+  // A malformed/tampered active generation must never fall back to PATH or an
+  // inferred asset layout. Keep Docker-first operation available and surface
+  // the failure through the normal no-runtime capability instead.
+  console.warn(
+    "[host-agent] signed bundled runtime validation failed; the bundled runtime is disabled",
+  );
+}
+const initialRuntime = await initializeContainerRuntime();
+// Do not touch the selected daemon merely because detection succeeded. The
+// activation gate below must first prove that every durable TaskEnvironment
+// belongs to this exact provider/endpoint. The manager's first admitted login
+// performs the same bounded reconciliation after operational publication.
+const engineLoginManager = createEngineLoginManager({
+  refreshEngineAccountAgents: (engine) =>
+    getOrchestrator().refreshEngineAccountAgents(engine),
+  tempRoot: join(env.uaiHome, "engine-login-bind"),
+  reconcileOnCreate: false,
+});
+if (initialRuntime.status === "ready") {
+  console.log(
+    `[host-agent] container runtime ready (${initialRuntime.provider}, ${initialRuntime.preference})`,
+  );
+} else if (initialRuntime.status === "no-runtime") {
+  console.warn(`[host-agent] ${initialRuntime.message}`);
+}
 // Surface a task's GitHub setup failure in its channel (ADR-027). Classify the
 // reason first: a GitHub-side 5xx / network blip (e.g. `gh auth login`
 // validating the token during a github.com outage) is transient and self-heals
@@ -201,9 +419,6 @@ setAuthExpiredHandler((taskId, _userId, reason) => {
       `Account, then run /retry-gh in this task to restore.`;
   getOrchestrator().emitSystemNote(taskId, note);
 });
-// Best-effort: build the standard image + asdf volume if missing. Logs and
-// continues on failure (e.g. docker unavailable) so the host still boots.
-void ensureStandardImage();
 // Codex creds are docker-cp'd into containers at task-up. A re-login (revoked
 // token → `codex login`) otherwise reaches only NEW tasks — re-copy into
 // running tasks on start (covers the desktop "Connect Codex", which restarts
@@ -214,8 +429,12 @@ void ensureStandardImage();
 // files owned by the host uid (macOS 501) that the container's node (1000)
 // can't read, and Codex died at startup. The post-recovery sweep also
 // self-heals such containers: it re-copies and chowns every running task.
-void recoveryComplete().then(() => reinjectCodexRunningTasks());
-watchCodexAuth();
+if (initialRuntime.status === "ready") {
+  void requestContainerRuntimeActivation(
+    recoveryComplete,
+    containerRuntimeReadinessEpoch(),
+  );
+}
 // ADR-103: subscribe ONCE, for the process — not per connection. Every event
 // lands in the outbox regardless of socket state; flushEvents is a no-op
 // while disconnected and the backlog drains after the resume handshake.
@@ -223,12 +442,21 @@ hostEvents.subscribe((event) => {
   eventOutbox.enqueue(event);
   flushEvents();
 });
-connect();
+// Start local health-bearing services before the bridge. The first
+// authenticated capability frame must describe the gateway even when its
+// initial bind is still pending, and both one-way readiness edges re-advertise
+// on the exact live socket generation.
+const mcpGateway = startMcpGateway();
+const stopMcpGatewaySubscription = mcpGateway.subscribe(() =>
+  sendCapabilities(),
+);
+const stopAgentClisReadySubscription = onAgentClisReady(() =>
+  sendCapabilities(),
+);
+void connect();
 // Local browser UI (ADR-028) — same single process, alongside the WSS client.
 // Best-effort: a UI bind failure must not take the host service down.
 void startLocalUi();
-// ADR-057: the MCP gateway task containers reach via host.docker.internal.
-startMcpGateway();
 
 async function startLocalUi(): Promise<void> {
   try {
@@ -241,7 +469,16 @@ async function startLocalUi(): Promise<void> {
       cloudUrl: bridgeUrl,
       hostId,
       logPath: serviceLogPath(),
-      taskMemory: dockerMemoryBytes,
+      taskMemory: async (composeProject) =>
+        containerRuntimeProblem()
+          ? null
+          : dockerMemoryBytes(composeProject),
+      runtimeState: containerRuntimeCapabilityState,
+      recheckRuntime: async () => {
+        await requestForcedContainerRuntimeRecheck();
+        return containerRuntimeCapabilityState();
+      },
+      containersOperational: () => containerRuntimeProblem() === null,
       // Engine connect/disconnect in the local UI re-advertises capabilities so
       // the cloud's task picker reflects a newly-configured engine promptly.
       readvertise: sendCapabilities,
@@ -249,10 +486,10 @@ async function startLocalUi(): Promise<void> {
       // On success, push the status up so the cloud mirrors `stopped` (it has no
       // auto-reconcile trigger); otherwise it would keep showing `running`.
       stopTask: async (taskId) => {
+        const runtimeProblem = containerRuntimeProblem();
+        if (runtimeProblem) return { ok: false, error: runtimeProblem };
         const result = await getOrchestrator().stopTask(taskId);
-        if (result.ok && ws && ws.readyState === WebSocket.OPEN) {
-          send(ws, { kind: "task.status", taskId, status: "stopped" });
-        }
+        if (result.ok) queueStoppedTaskStatus(taskId);
         return result;
       },
     });
@@ -266,6 +503,7 @@ async function startLocalUi(): Promise<void> {
 
 /** Build the current host capability advertisement (ADR-021). */
 function buildCapabilities(): HostCapabilities {
+  const runtime = containerRuntimeCapabilityState();
   return {
     version: packageVersion(),
     protocolFeatures: [
@@ -274,6 +512,12 @@ function buildCapabilities(): HostCapabilities {
       GITHUB_CREDENTIAL_GENERATION_PROTOCOL_FEATURE,
       GITHUB_INSTALLATION_VERIFICATION_PROTOCOL_FEATURE,
       GITHUB_REPOSITORY_ACCESS_PROTOCOL_FEATURE,
+      HOST_TASK_INVENTORY_PROTOCOL_FEATURE,
+      HOST_MAINTENANCE_READINESS_PROTOCOL_FEATURE,
+      MCP_GATEWAY_HEALTH_PROTOCOL_FEATURE,
+      HOST_LOGS_PROTOCOL_FEATURE,
+      HOST_ENGINE_LOGIN_PROTOCOL_FEATURE,
+      HOST_CONFIG_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.
@@ -282,7 +526,13 @@ function buildCapabilities(): HostCapabilities {
         : []),
     ],
     agentKinds: agentKindCapabilities(),
-    runtimes: standardRuntimes(),
+    // Language runtimes live in the standard container image. Do not
+    // advertise them as usable while the machine cannot run a container.
+    runtimes: runtime.status === "ready" ? standardRuntimes() : [],
+    containerRuntime: runtime,
+    maintenanceReady: areAgentClisReady(),
+    mcpGateway: mcpGateway.state(),
+    engineLogins: engineLoginManager.capabilities(),
     githubUsers: connectedUserIds(),
   };
 }
@@ -298,14 +548,291 @@ function sendCapabilities(): void {
   }
 }
 
+/** Keep a rolling-isolation/local-UI stop from remaining cloud-ghost-running
+ * merely because the bridge was between connections at the transition. */
+function queueStoppedTaskStatus(taskId: string): void {
+  pendingRuntimeIsolationStatuses.enqueue(taskId);
+  flushStoppedTaskStatuses();
+}
+
+function flushStoppedTaskStatuses(socket: WebSocket | null = ws): void {
+  if (!socket || socket.readyState !== WebSocket.OPEN) return;
+  pendingRuntimeIsolationStatuses.flush((taskId) => {
+    send(socket, { kind: "task.status", taskId, status: "stopped" });
+  });
+}
+
 onRegistryChange(() => sendCapabilities());
+onContainerRuntimeChange((next, previous) => {
+  if (stopping) return;
+  sendCapabilities();
+  if (next.status === "ready") {
+    stopRuntimeAutoRecheck();
+    stopRuntimeAutoRecheck = () => {};
+  } else if (previous.status === "ready") {
+    stopRuntimeAutoRecheck();
+    stopRuntimeAutoRecheck = startContainerRuntimeAutoRecheck();
+  }
+  if (
+    containerRuntimeBecameReady(next, previous) ||
+    containerRuntimeActivationRequired()
+  ) {
+    void requestContainerRuntimeActivation(
+      requestRuntimeRecovery,
+      containerRuntimeReadinessEpoch(),
+    );
+  }
+});
+stopRuntimeAutoRecheck = startContainerRuntimeAutoRecheck();
 // Re-advertise when a gh token is added/removed (ADR-033) so the host page's
 // per-host connected state updates promptly.
 onGithubChange(() => sendCapabilities());
 
-function connect(): void {
+type RuntimeRecoveryRequest = (
+  isCurrent: () => boolean,
+) => Promise<boolean>;
+/** Serialize activation generations. The promise tail avoids a late-enqueue
+ * gap between a pump's last queue read and its cleanup callback. */
+function requestContainerRuntimeActivation(
+  recover: RuntimeRecoveryRequest,
+  epoch: number,
+): Promise<void> {
+  return runtimeActivationTail.request(epoch, () =>
+    activateContainerRuntime(recover, epoch),
+  );
+}
+
+function scheduleContainerRuntimeActivationRetry(
+  recover: RuntimeRecoveryRequest,
+  epoch: number,
+): void {
+  runtimeActivationTail.scheduleRetry(epoch, () =>
+    activateContainerRuntime(recover, epoch),
+  );
+}
+
+/** Turn a detected daemon into an operational task backend. Until every step
+ * completes, capabilities stay `checking` and Docker-dependent commands fail
+ * retryably instead of racing recovery or mistaking unknown state for death. */
+async function activateContainerRuntime(
+  recover: RuntimeRecoveryRequest,
+  epoch: number,
+): Promise<RuntimeActivationAttemptResult> {
+  publishActivationPhase("joining in-flight recovery");
+  await waitForRuntimeRecovery();
+  return runMaintainedRuntimeActivation({
+    isCurrent: () => runtimeActivationIsCurrent(epoch),
+    beforeMaintenance: async () => {
+      // This is the first selected-daemon operation in activation. Durable
+      // TaskEnvironment locators must match the exact process pin before
+      // quarantine, image/shared-volume writers, or recovery can touch it.
+      publishActivationPhase("fencing persisted task environments");
+      if (!(await selectedRuntimeMatchesPersistedTaskEnvironments())) {
+        publishActivationPhase("fence rejected the selected runtime");
+        return "stale";
+      }
+      if (!runtimeActivationIsCurrent(epoch)) return "stale";
+      publishActivationPhase("quarantining writable runtime containers");
+      const isolated = await quarantineWritableRuntimeContainers({
+        lifecycle: getOrchestrator(),
+        isCurrent: () => runtimeActivationIsCurrent(epoch),
+      });
+      for (const taskId of isolated.stoppedTaskIds) {
+        queueStoppedTaskStatus(taskId);
+      }
+      publishActivationPhase(
+        `writable-container quarantine: ${isolated.verdict}`,
+      );
+      return isolated.verdict;
+    },
+    maintenance: () => {
+      publishActivationPhase(
+        "maintenance: standard image + shared runtime volume",
+      );
+      return reconcileStableStandardImage(epoch);
+    },
+    recover,
+    // A bounded recovery pass can finish with active tasks still unknowable.
+    // Keep the public runtime in `checking`. A real outage becomes
+    // `no-runtime`; a still-ready daemon requests a bounded follow-up only
+    // after this activation promise has left the tail.
+    runtimeReady: async () =>
+      (await initializeContainerRuntime()).status === "ready",
+    afterRecoveryBeforeFinalMaintenance: async () => {
+      try {
+        await reinjectCodexRunningTasks();
+      } catch (error) {
+        console.warn(
+          `[codex] post-recovery reinject failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    },
+    // Credentials can be edited from the local UI during a long recovery. A
+    // final stable pass ensures a newly-enabled optional engine is in the
+    // image before the ready frame reattaches persisted agent sessions.
+    publishOperational: async () => {
+      if (
+        runtimeActivationIsCurrent(epoch) &&
+        markContainerRuntimeOperational(epoch)
+      ) {
+        watchCodexAuth(() => containerRuntimeProblem() === null);
+        resumeRuntimeDeferredAgentWork();
+        sendCapabilities();
+      }
+    },
+  });
+}
+
+function runtimeActivationIsCurrent(epoch: number): boolean {
+  return !stopping && containerRuntimeEpochIsCurrent(epoch);
+}
+
+async function reconcileStableStandardImage(
+  epoch: number,
+): Promise<"ready" | "retry" | "stale"> {
+  while (runtimeActivationIsCurrent(epoch)) {
+    const before = JSON.stringify(configuredOptionalEngines());
+    const result = await ensureStandardImage();
+    if (!runtimeActivationIsCurrent(epoch)) return "stale";
+    if (!result.ok && result.remedy === "stop-volume-holders") {
+      // The shared volume needs a repair the running holder tasks block and
+      // cannot safely use (their agent CLIs fail the probe). Lifecycle-stop
+      // them (resumable) so the retry can attach writable — the non-writer
+      // escape from the review's activation deadlock (2026-08-18 round 2).
+      console.warn(
+        `[host-agent] ${result.error ?? "shared runtime volume needs repair"} — stopping holder tasks (resumable)`,
+      );
+      const swept = await quarantineWritableRuntimeContainers({
+        lifecycle: getOrchestrator(),
+        isCurrent: () => runtimeActivationIsCurrent(epoch),
+        scope: "volume-holders",
+      });
+      for (const taskId of swept.stoppedTaskIds) {
+        queueStoppedTaskStatus(taskId);
+      }
+      if (!runtimeActivationIsCurrent(epoch)) return "stale";
+      return "retry";
+    }
+    if (!result.ok) {
+      // A stale image remains usable only when ensureStandardImage also
+      // completed the shared-volume transaction successfully. A failed
+      // default-Node/CLI/Corepack proof must never release boot recovery or
+      // operational publication: a stopped legacy app could otherwise start
+      // with a partially removed CLI-owning candidate. Re-probe Docker to
+      // choose between this epoch's bounded activation retry and the normal
+      // daemon-loss generation transition.
+      const runtime = await initializeContainerRuntime();
+      if (!runtimeActivationIsCurrent(epoch)) return "stale";
+      return runtime.status === "ready" ? "retry" : "stale";
+    }
+    if (before === JSON.stringify(configuredOptionalEngines())) {
+      return "ready";
+    }
+  }
+  return "stale";
+}
+
+/** The bridge may have been offline while Docker stopped. Gate commands while
+ * every successful socket open performs a cheap daemon proof. A healthy
+ * ready-to-ready proof restores operation without a full recovery sweep;
+ * actual loss/restoration creates a readiness edge and takes the full path. */
+function revalidateContainerRuntimeOnConnect(): void {
+  const runtime = containerRuntimeState();
+  const suspendedEpoch =
+    runtime.status === "ready" ? suspendContainerRuntime() : null;
+  void (async () => {
+    const next = await initializeContainerRuntime();
+    if (
+      suspendedEpoch === null ||
+      next.status !== "ready" ||
+      !containerRuntimeEpochIsCurrent(suspendedEpoch)
+    ) {
+      return;
+    }
+    if (!(await selectedRuntimeMatchesPersistedTaskEnvironments())) return;
+    if (!runtimeActivationIsCurrent(suspendedEpoch)) return;
+    // A healthy daemon can still have restarted while the bridge was offline.
+    // One label scan keeps ordinary cloud/network flaps cheap; only a missing,
+    // exited, or unknowable active app takes the full per-task recovery path.
+    const recovery = await runtimeRecoveryVerdict();
+    let recovered = recovery === "clean";
+    if (!recovered) {
+      recovered = await requestRuntimeRecovery(() =>
+        runtimeActivationIsCurrent(suspendedEpoch),
+      );
+    }
+    if (!runtimeActivationIsCurrent(suspendedEpoch)) return;
+    // Prove the daemon once more after recovery so a mid-sweep loss cannot
+    // reopen commands and tunnels on an unresolved backend.
+    const final = await initializeContainerRuntime();
+    if (
+      final.status !== "ready" ||
+      !containerRuntimeEpochIsCurrent(suspendedEpoch)
+    ) {
+      return;
+    }
+    if (!recovered) {
+      scheduleContainerRuntimeActivationRetry(
+        requestRuntimeRecovery,
+        suspendedEpoch,
+      );
+      return;
+    }
+    if (markContainerRuntimeOperational(suspendedEpoch)) {
+      runtimeActivationTail.resolve(suspendedEpoch);
+      resumeRuntimeDeferredAgentWork();
+      sendCapabilities();
+    }
+  })().catch((error) => {
+    console.warn(
+      `[host-agent] container runtime reconnect validation failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    if (
+      suspendedEpoch !== null &&
+      runtimeActivationIsCurrent(suspendedEpoch)
+    ) {
+      scheduleContainerRuntimeActivationRetry(
+        requestRuntimeRecovery,
+        suspendedEpoch,
+      );
+    }
+  });
+}
+
+/** An operator recheck is an explicit recovery request. Invalidate even a
+ * stale ready verdict so an unseen daemon restart gets image maintenance,
+ * persisted-task recovery, credential reinjection, and channel reattach. */
+async function requestForcedContainerRuntimeRecheck(): Promise<void> {
+  const result = await forceContainerRuntimeRecheck();
+  if (result.epoch === null || !containerRuntimeEpochIsCurrent(result.epoch)) {
+    return;
+  }
+  void requestContainerRuntimeActivation(
+    requestRuntimeRecovery,
+    result.epoch,
+  );
+}
+
+async function remoteOperationsReadyForConnect(
+  requestGeneration: number,
+): Promise<boolean> {
+  await stopActiveRemoteOperations();
+  await waitForRemoteOperationCleanups();
+  return (
+    !stopping &&
+    !fatal &&
+    requestGeneration === connectionRequestGeneration
+  );
+}
+
+async function connect(): Promise<void> {
   if (stopping || fatal) return;
+  const requestGeneration = ++connectionRequestGeneration;
 
+  // A connection owns every interactive remote operation it starts. Tear the
+  // previous generation down before constructing its replacement so a late
+  // file read/child-process event can never escape onto the new socket.
+  if (!(await remoteOperationsReadyForConnect(requestGeneration))) return;
   console.log(`[host-agent] connecting ${bridgeUrl}`);
   const socket = new WebSocket(bridgeUrl, { perMessageDeflate: WS_DEFLATE });
   ws = socket;
@@ -314,19 +841,83 @@ function connect(): void {
   let ready = false;
   let pingTimer: NodeJS.Timeout | null = null;
   let deadTimer: NodeJS.Timeout | null = null;
+  let remoteOperationsActive = true;
+  let remoteOperationCleanup: Promise<void> | null = null;
+
+  const stopRemoteOperations = (): Promise<void> => {
+    if (remoteOperationCleanup) return remoteOperationCleanup;
+    remoteOperationsActive = false;
+    remoteOperationCleanup = stopRemoteOperationManagers();
+    return remoteOperationCleanup;
+  };
+  stopActiveRemoteOperations = stopRemoteOperations;
+
+  // This emitter closes over exactly this socket generation. Returning false
+  // applies the log manager's bounded retry/drop policy while the WS upload
+  // queue is congested; terminal frames remain small and are always attempted.
+  const emitHostLogFrame: HostLogsEmit = (frame) => {
+    if (!remoteOperationsActive || socket.readyState !== WebSocket.OPEN) {
+      return false;
+    }
+    if (
+      frame.kind === "host.logs.chunk" &&
+      socket.bufferedAmount >= MAX_WS_BUFFERED_BYTES
+    ) {
+      return false;
+    }
+    try {
+      send(socket, frame);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const sendRemoteOperationFrame = (frame: HostToCloud): boolean => {
+    if (!remoteOperationsActive || socket.readyState !== WebSocket.OPEN) {
+      return false;
+    }
+    try {
+      send(socket, frame);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const emitEngineLoginEvent = (
+    event: Extract<HostToCloud, { kind: "engine.login.event" }>,
+  ): void => {
+    if (!sendRemoteOperationFrame(event)) return;
+    if (event.phase === "succeeded") {
+      sendRemoteOperationFrame({
+        kind: "host.capabilities",
+        capabilities: buildCapabilities(),
+      });
+    }
+  };
 
   const cleanup = (): void => {
+    void stopRemoteOperations();
     if (pingTimer) clearInterval(pingTimer);
     if (deadTimer) clearInterval(deadTimer);
     eventFlushEnabled = false;
+    cancelEventFlushBackpressureTimer();
     if (resumeFallbackTimer) {
       clearTimeout(resumeFallbackTimer);
       resumeFallbackTimer = null;
     }
-    if (ws === socket) ws = null;
+    if (ws === socket) {
+      hostTaskInventorySnapshots.clear();
+      ws = null;
+    }
   };
 
   socket.on("open", () => {
+    // Suspend synchronously before auth: cloud activation immediately starts
+    // task reconciliation, which must observe `checking` until this proof
+    // finishes instead of treating a dead daemon as an empty one.
+    revalidateContainerRuntimeOnConnect();
     send(socket, { kind: "auth", token, hostId, bootId: BOOT_ID });
     // Advertise capabilities immediately after auth (ADR-021). The bridge
     // rejects with close-code 4001 if auth fails, so sending here is harmless
@@ -336,6 +927,7 @@ function connect(): void {
       kind: "host.capabilities",
       capabilities: buildCapabilities(),
     });
+    flushStoppedTaskStatuses(socket);
     ready = true;
     reconnectAttempt = 0;
     markConnected();
@@ -368,6 +960,10 @@ function connect(): void {
 
   socket.on("message", (data, isBinary) => {
     lastTraffic = Date.now();
+    // A superseded socket is read-dead even if the transport has not emitted
+    // close yet. Never let a late frame recreate work in shared managers or
+    // attach binary data to the replacement connection's pending tunnel.
+    if (!remoteOperationsActive) return;
     if (isBinary) {
       const tunnelId = pendingBinaryTunnelId;
       pendingBinaryTunnelId = null;
@@ -379,6 +975,7 @@ function connect(): void {
 
     const frame = parseCloudFrame(data);
     if (!frame) return;
+    if (stopping && rejectFrameDuringShutdown(socket, frame)) return;
 
     switch (frame.kind) {
       case "pong":
@@ -396,10 +993,109 @@ function connect(): void {
         break;
       case "event.ack":
         eventOutbox.ack(frame.seq);
+        flushEvents();
         break;
       case "command":
         void handleCommand(socket, frame);
         break;
+      case "host.inventory.request":
+        void handleHostInventoryRequest(socket, frame);
+        break;
+      case "host.logs.start":
+        try {
+          hostLogManager.start(
+            frame.opId,
+            frame.lines,
+            frame.follow,
+            emitHostLogFrame,
+          );
+        } catch (error) {
+          const message =
+            error instanceof HostLogStartError
+              ? hostLogStartErrorMessage(error)
+              : "host log operation could not be started";
+          sendRemoteOperationFrame({
+            kind: "host.logs.end",
+            opId: frame.opId,
+            reason: "error",
+            message,
+          });
+        }
+        break;
+      case "host.logs.stop":
+        if (!hostLogManager.stop(frame.opId)) {
+          // Stop is idempotent from the cloud's perspective. A terminal reply
+          // also resolves a stop racing natural completion or reconnect.
+          sendRemoteOperationFrame({
+            kind: "host.logs.end",
+            opId: frame.opId,
+            reason: "stopped",
+          });
+        }
+        break;
+      case "engine.login.start":
+        if (containerRuntimeProblem()) {
+          sendRemoteOperationFrame({
+            kind: "engine.login.event",
+            opId: frame.opId,
+            engine: frame.engine,
+            phase: "failed",
+            errorCode: "unavailable",
+            message: "The container runtime is not ready on this host.",
+          });
+          break;
+        }
+        engineLoginManager.start(
+          frame.opId,
+          frame.engine,
+          emitEngineLoginEvent,
+        );
+        break;
+      case "engine.login.input":
+        engineLoginManager.input(frame.opId, frame.text);
+        break;
+      case "engine.login.callback":
+        void engineLoginManager.callback(frame.opId, frame.query);
+        break;
+      case "engine.login.stop":
+        void trackRemoteOperationCleanup(
+          engineLoginManager.stop(frame.opId).then(() => {}),
+        );
+        break;
+      case "host.config.get":
+        sendHostConfigAck(
+          sendRemoteOperationFrame,
+          frame.opId,
+          getHostConfig(),
+        );
+        break;
+      case "host.config.set":
+        // Count only patches admitted before shutdown. A late set is rejected
+        // synchronously above, so it can never extend the managed drain.
+        inFlight += 1;
+        void Promise.resolve()
+          .then(() => patchHostConfig(frame.patch))
+          .then((result) => {
+            sendHostConfigAck(sendRemoteOperationFrame, frame.opId, result);
+            if (result.ok) {
+              sendRemoteOperationFrame({
+                kind: "host.capabilities",
+                capabilities: buildCapabilities(),
+              });
+            }
+          })
+          .catch(() => {
+            sendHostConfigAck(sendRemoteOperationFrame, frame.opId, {
+              ok: false,
+              errorCode: "persistence_failed",
+              message: "host config could not be persisted",
+            });
+          })
+          .finally(() => {
+            inFlight -= 1;
+            maybeExit();
+          });
+        break;
       case "tunnel.open":
         // Synchronously, BEFORE handleTunnelOpen's first await: the frames that
         // follow this one (a bodyless GET's `requestEnd` arrives on the next
@@ -421,83 +1117,103 @@ function connect(): void {
         closeTunnel(socket, frame.tunnelId, frame.reason);
         break;
       case "gh.connect.set": {
+        const runtimeProblem = containerRuntimeProblem();
+        if (runtimeProblem) {
+          send(socket, {
+            kind: "gh.connect.ack",
+            opId: frame.opId,
+            userId: frame.userId,
+            ok: false,
+            error: runtimeProblem,
+          });
+          break;
+        }
         // Account switches fence every host-side Git operation using the old
         // credential before the replacement grant is stored or reinjected.
-        void runGithubConnectionTransition(frame.userId, async () => {
-          const claim = claimGithubCredentialGeneration(
+        void managedMutationDrain.track(() =>
+          runGithubConnectionTransition(
             frame.userId,
-            frame.generation,
-            "set",
-          );
-          if (!claim) {
-            return {
-              ok: false as const,
-              code: "stale_generation" as const,
-              error: "stale GitHub credential generation",
-            };
-          }
-          const transitionDeps = {
-            invalidateCredentials: invalidateTaskGithubGitCredentials,
-            reconcile: (taskId: string, userId: string) =>
-              getOrchestrator().runTaskLifecycle(taskId, () =>
-                reconcileTaskGitAuth(taskId, userId),
+            async () => {
+              const claim = claimGithubCredentialGeneration(
+                frame.userId,
+                frame.generation,
+                "set",
+              );
+              if (!claim) {
+                return {
+                  ok: false as const,
+                  code: "stale_generation" as const,
+                  error: "stale GitHub credential generation",
+                };
+              }
+              const transitionDeps = {
+                invalidateCredentials: invalidateTaskGithubGitCredentials,
+                reconcile: (taskId: string, userId: string) => {
+                  requireContainerRuntime();
+                  return getOrchestrator().runTaskLifecycle(taskId, () => {
+                    requireContainerRuntime();
+                    return reconcileTaskGitAuth(taskId, userId);
+                  });
+                },
+              };
+              let result: Awaited<ReturnType<typeof onConnectSet>>;
+              try {
+                result = await onConnectSet(
+                  { ...frame, generation: claim.generation },
+                  transitionDeps,
+                );
+              } catch (err) {
+                result = {
+                  ok: false,
+                  error: err instanceof Error ? err.message : String(err),
+                };
+              }
+              if (!result.ok) {
+                // Storage can succeed before live-task reconciliation fails. Never
+                // emit a negative set ack while that untrusted credential remains
+                // active: persist the same-generation clear tombstone first, then
+                // best-effort scrub/revoke under the same serialized transition.
+                await rollbackClaimedGitHubCredentialSet(
+                  frame.userId,
+                  claim.generation,
+                  transitionDeps,
+                );
+              }
+              return result;
+            },
+            requireContainerRuntime,
+          ).then(
+            (result) =>
+              send(
+                socket,
+                result.ok
+                  ? {
+                      kind: "gh.connect.ack",
+                      opId: frame.opId,
+                      userId: frame.userId,
+                      ok: true,
+                    }
+                  : {
+                      kind: "gh.connect.ack",
+                      opId: frame.opId,
+                      userId: frame.userId,
+                      ok: false,
+                      code: "code" in result ? result.code : undefined,
+                      error: result.error ?? "store failed",
+                    },
               ),
-          };
-          let result: Awaited<ReturnType<typeof onConnectSet>>;
-          try {
-            result = await onConnectSet(
-              { ...frame, generation: claim.generation },
-              transitionDeps,
-            );
-          } catch (err) {
-            result = {
-              ok: false,
-              error: err instanceof Error ? err.message : String(err),
-            };
-          }
-          if (!result.ok) {
-            // Storage can succeed before live-task reconciliation fails. Never
-            // emit a negative set ack while that untrusted credential remains
-            // active: persist the same-generation clear tombstone first, then
-            // best-effort scrub/revoke under the same serialized transition.
-            await rollbackClaimedGitHubCredentialSet(
-              frame.userId,
-              claim.generation,
-              transitionDeps,
-            );
-          }
-          return result;
-        }).then(
-          (result) =>
-            send(
-              socket,
-              result.ok
-                ? {
-                    kind: "gh.connect.ack",
-                    opId: frame.opId,
-                    userId: frame.userId,
-                    ok: true,
-                  }
-                : {
-                    kind: "gh.connect.ack",
-                    opId: frame.opId,
-                    userId: frame.userId,
-                    ok: false,
-                    code: "code" in result ? result.code : undefined,
-                    error: result.error ?? "store failed",
-                  },
-            ),
-          (err) => {
-            const error = err instanceof Error ? err.message : String(err);
-            console.warn(`[github] connect.set failed: ${error}`);
-            send(socket, {
-              kind: "gh.connect.ack",
-              opId: frame.opId,
-              userId: frame.userId,
-              ok: false,
-              error,
-            });
-          },
+            (err) => {
+              const error = err instanceof Error ? err.message : String(err);
+              console.warn(`[github] connect.set failed: ${error}`);
+              send(socket, {
+                kind: "gh.connect.ack",
+                opId: frame.opId,
+                userId: frame.userId,
+                ok: false,
+                error,
+              });
+            },
+          ),
         );
         break;
       }
@@ -575,61 +1291,81 @@ function connect(): void {
         break;
       }
       case "gh.connect.clear": {
+        const runtimeProblem = containerRuntimeProblem();
+        if (runtimeProblem) {
+          send(socket, {
+            kind: "gh.connect.ack",
+            opId: frame.opId,
+            userId: frame.userId,
+            ok: false,
+            error: runtimeProblem,
+          });
+          break;
+        }
         // The serialized transition removes the local credential, waits for
         // best-effort remote revocation, and scrubs live containers before it
         // acknowledges. That keeps a delayed revoke from racing a later set.
-        void runGithubConnectionTransition(frame.userId, async () => {
-          const claim = claimGithubCredentialGeneration(
+        void managedMutationDrain.track(() =>
+          runGithubConnectionTransition(
             frame.userId,
-            frame.generation,
-            "clear",
-          );
-          if (!claim) {
-            return {
-              ok: false as const,
-              code: "stale_generation" as const,
-              error: "stale GitHub credential generation",
-            };
-          }
-          await onConnectClear(frame.userId, {
-            invalidateCredentials: invalidateTaskGithubGitCredentials,
-            reconcile: (taskId, userId) =>
-              getOrchestrator().runTaskLifecycle(taskId, () =>
-                reconcileTaskGitAuth(taskId, userId),
+            async () => {
+              const claim = claimGithubCredentialGeneration(
+                frame.userId,
+                frame.generation,
+                "clear",
+              );
+              if (!claim) {
+                return {
+                  ok: false as const,
+                  code: "stale_generation" as const,
+                  error: "stale GitHub credential generation",
+                };
+              }
+              await onConnectClear(frame.userId, {
+                invalidateCredentials: invalidateTaskGithubGitCredentials,
+                reconcile: (taskId, userId) => {
+                  requireContainerRuntime();
+                  return getOrchestrator().runTaskLifecycle(taskId, () => {
+                    requireContainerRuntime();
+                    return reconcileTaskGitAuth(taskId, userId);
+                  });
+                },
+              });
+              return { ok: true as const };
+            },
+            requireContainerRuntime,
+          ).then(
+            (result) =>
+              send(
+                socket,
+                result.ok
+                  ? {
+                      kind: "gh.connect.ack",
+                      opId: frame.opId,
+                      userId: frame.userId,
+                      ok: true,
+                    }
+                  : {
+                      kind: "gh.connect.ack",
+                      opId: frame.opId,
+                      userId: frame.userId,
+                      ok: false,
+                      code: result.code,
+                      error: result.error,
+                    },
               ),
-          });
-          return { ok: true as const };
-        }).then(
-          (result) =>
-            send(
-              socket,
-              result.ok
-                ? {
-                    kind: "gh.connect.ack",
-                    opId: frame.opId,
-                    userId: frame.userId,
-                    ok: true,
-                  }
-                : {
-                    kind: "gh.connect.ack",
-                    opId: frame.opId,
-                    userId: frame.userId,
-                    ok: false,
-                    code: result.code,
-                    error: result.error,
-                  },
-            ),
-          (err) => {
-            const error = err instanceof Error ? err.message : String(err);
-            console.warn(`[github] connect.clear failed: ${error}`);
-            send(socket, {
-              kind: "gh.connect.ack",
-              opId: frame.opId,
-              userId: frame.userId,
-              ok: false,
-              error,
-            });
-          },
+            (err) => {
+              const error = err instanceof Error ? err.message : String(err);
+              console.warn(`[github] connect.clear failed: ${error}`);
+              send(socket, {
+                kind: "gh.connect.ack",
+                opId: frame.opId,
+                userId: frame.userId,
+                ok: false,
+                error,
+              });
+            },
+          ),
         );
         break;
       }
@@ -637,27 +1373,36 @@ function connect(): void {
       case "ssh.key.ensure":
       case "ssh.key.delete": {
         if (frame.kind === "ssh.key.delete") {
-          void deleteUserSshIdentity(frame.userId, {
-            removeFromContainer: (taskId) =>
-              getOrchestrator().runTaskLifecycle(taskId, () =>
-                removeTaskSshIdentityFromContainer(taskId),
-              ),
-          }).then(
-            () =>
-              send(socket, {
-                kind: "ssh.key.ack",
-                userId: frame.userId,
-                ok: true,
-                publicKey: null,
-              }),
-            (err) =>
-              send(socket, {
-                kind: "ssh.key.ack",
-                userId: frame.userId,
-                ok: false,
-                error:
-                  err instanceof Error ? err.message : "ssh key delete failed",
-              }),
+          void managedMutationDrain.track(() =>
+            deleteUserSshIdentity(frame.userId, {
+              // Deletion has no durable cleanup outbox. Do not revoke the
+              // host-side authority unless credential-bearing containers can be
+              // scrubbed in the same attempt.
+              preflight: requireContainerRuntime,
+              removeFromContainer: (taskId) => {
+                requireContainerRuntime();
+                return getOrchestrator().runTaskLifecycle(taskId, () => {
+                  requireContainerRuntime();
+                  return removeTaskSshIdentityFromContainer(taskId);
+                });
+              },
+            }).then(
+              () =>
+                send(socket, {
+                  kind: "ssh.key.ack",
+                  userId: frame.userId,
+                  ok: true,
+                  publicKey: null,
+                }),
+              (err) =>
+                send(socket, {
+                  kind: "ssh.key.ack",
+                  userId: frame.userId,
+                  ok: false,
+                  error:
+                    err instanceof Error ? err.message : "ssh key delete failed",
+                }),
+            ),
           );
           break;
         }
@@ -679,18 +1424,25 @@ function connect(): void {
       }
       case "mcp.op": {
         // Async network work (discovery, DCR, exchange) — ack when done.
-        void handleMcpOp(frame.op)
-          .then((ack) =>
-            send(socket, { kind: "mcp.ack", opId: frame.opId, ok: true, ...ack }),
-          )
-          .catch((err: unknown) =>
-            send(socket, {
-              kind: "mcp.ack",
-              opId: frame.opId,
-              ok: false,
-              error: err instanceof Error ? err.message : "mcp op failed",
-            }),
-          );
+        void managedMutationDrain.track(() =>
+          handleMcpOp(frame.op)
+            .then((ack) =>
+              send(socket, {
+                kind: "mcp.ack",
+                opId: frame.opId,
+                ok: true,
+                ...ack,
+              }),
+            )
+            .catch((err: unknown) =>
+              send(socket, {
+                kind: "mcp.ack",
+                opId: frame.opId,
+                ok: false,
+                error: err instanceof Error ? err.message : "mcp op failed",
+              }),
+            ),
+        );
         break;
       }
       case "env.var.list":
@@ -733,6 +1485,11 @@ function connect(): void {
   socket.on("close", (code, reason) => {
     cleanup();
     const text = reason.toString("utf8");
+    if (stopping) {
+      markDisconnected();
+      maybeExit();
+      return;
+    }
     if (code === 4001) {
       fatal = true;
       markDisconnected(text || "auth rejected by bridge");
@@ -742,11 +1499,6 @@ function connect(): void {
       process.exitCode = 1;
       return;
     }
-    if (stopping) {
-      markDisconnected();
-      maybeExit();
-      return;
-    }
     const delay = reconnectDelay();
     markReconnecting(text || `disconnected${ready ? "" : " before auth"}`);
     console.warn(
@@ -757,7 +1509,9 @@ function connect(): void {
       authed: ready,
       retryInMs: Math.round(delay),
     });
-    setTimeout(connect, delay);
+    setTimeout(() => {
+      void connect();
+    }, delay);
   });
 }
 
@@ -772,6 +1526,17 @@ async function handleCommand(
     if (socket.readyState === WebSocket.OPEN) {
       send(socket, { kind: "result", commandId: frame.commandId, result });
     }
+    // Publish after the command result so a retryable taskUp failure cannot
+    // overwrite the physical stopped truth established while quarantining a
+    // legacy runtime. A closed bridge retains the queue until reconnect.
+    if (
+      pendingRuntimeIsolationStatuses.enqueueStoppedTaskUp(
+        frame.command,
+        frame.args,
+      )
+    ) {
+      flushStoppedTaskStatuses();
+    }
   } catch (err) {
     if (socket.readyState === WebSocket.OPEN) {
       send(socket, {
@@ -790,11 +1555,57 @@ async function handleCommand(
   }
 }
 
+async function handleHostInventoryRequest(
+  socket: WebSocket,
+  frame: Extract<CloudToHost, { kind: "host.inventory.request" }>,
+): Promise<void> {
+  try {
+    const page = await hostTaskInventorySnapshots.page(frame);
+    // A scan belongs to the authenticated socket generation that requested
+    // it. Never leak a late page onto a replacement connection.
+    if (ws !== socket || socket.readyState !== WebSocket.OPEN) return;
+    send(socket, {
+      kind: "host.inventory.page",
+      scanId: frame.scanId,
+      cursor: frame.cursor,
+      ...page,
+    });
+  } catch (error) {
+    console.warn(
+      `[host-agent] inventory request rejected: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}
+
 async function handleTunnelOpen(
   wsSocket: WebSocket,
   frame: Extract<CloudToHost, { kind: "tunnel.open" }>,
 ): Promise<void> {
-  const target = await resolveTunnelTarget(frame);
+  let target: UpstreamAddr | null;
+  try {
+    target = await resolveTunnelTarget(frame);
+  } catch (error) {
+    // A thrown resolution (daemon flap mid-inspect) must settle the
+    // opening entry: abortAll() joins it during bridge replacement, and the
+    // rejection must not escape the `void handleTunnelOpen(...)` call as a
+    // process-fatal unhandled rejection.
+    tunnels.abandon(frame.tunnelId);
+    console.warn(
+      `[tunnel] ${frame.tunnelId}: target resolution failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+    send(wsSocket, {
+      kind: "tunnel.ack",
+      tunnelId: frame.tunnelId,
+      ok: false,
+      status: 503,
+      message: "target port is not available on this host",
+    });
+    return;
+  }
   if (!target) {
     // Nothing will ever service what queued behind this open.
     tunnels.abandon(frame.tunnelId);
@@ -822,14 +1633,18 @@ function handleHttpTunnelOpen(
   target: UpstreamAddr,
 ): void {
   let acked = false;
+  const requestOptions = {
+    host: target.host,
+    port: target.port,
+    method: frame.reqLine.method,
+    path: frame.reqLine.url,
+    headers: requestHeaders(frame.reqLine.headers),
+    // Reuse the connection proven inside the task lifecycle slot; http will
+    // manage (and eventually close) the socket it is handed.
+    ...(target.socket ? { createConnection: () => target.socket! } : {}),
+  };
   const upstream = httpRequest(
-    {
-      host: target.host,
-      port: target.port,
-      method: frame.reqLine.method,
-      path: frame.reqLine.url,
-      headers: requestHeaders(frame.reqLine.headers),
-    },
+    requestOptions,
     (response) => {
       const headers = responseHeaders(response);
       send(wsSocket, {
@@ -862,10 +1677,6 @@ function handleHttpTunnelOpen(
 
   upstream.on("error", (err) => {
     tunnels.delete(frame.tunnelId);
-    // A connect failure to a cached container IP likely means the container was
-    // recreated (resume) and got a new IP — drop the cache so the next request
-    // re-resolves (ADR-036).
-    invalidateContainerIpByAddr(target.host);
     // 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);
@@ -897,14 +1708,16 @@ function handleRawTunnelOpen(
   frame: Extract<CloudToHost, { kind: "tunnel.open" }>,
   target: UpstreamAddr,
 ): void {
-  const upstream = new Socket();
+  const upstream = target.socket ?? new Socket();
 
   let acked = false;
   let responseBuffer = Buffer.alloc(0);
 
-  upstream.on("connect", () => {
-    upstream.write(serializeRequest(frame.reqLine));
-  });
+  if (!target.socket) {
+    upstream.on("connect", () => {
+      upstream.write(serializeRequest(frame.reqLine));
+    });
+  }
 
   upstream.on("data", (chunk) => {
     if (!acked) {
@@ -930,7 +1743,6 @@ function handleRawTunnelOpen(
   });
 
   upstream.on("error", (err) => {
-    invalidateContainerIpByAddr(target.host);
     // 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);
@@ -961,12 +1773,18 @@ function handleRawTunnelOpen(
     });
   });
 
-  upstream.connect(target.port, target.host);
+  if (!target.socket) upstream.connect(target.port, target.host);
   // 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`
   // handler, so only client frames that overtook the open replay here.
-  tunnels.register(frame.tunnelId, upstream);
+  const owned = tunnels.register(frame.tunnelId, upstream);
+  // A preconnected socket writes only once registration has accepted
+  // ownership: a tunnel canceled during resolution is destroyed inside
+  // register(), and an aborted/stale generation must never emit a request.
+  if (target.socket && owned) {
+    upstream.write(serializeRequest(frame.reqLine));
+  }
 }
 
 function closeTunnel(
@@ -985,51 +1803,78 @@ function closeTunnel(
 interface UpstreamAddr {
   host: string;
   port: number;
-}
-
-// Container IP cache (ADR-036): `docker inspect` is too slow for the request
-// hot path, so cache the app container's Docker-network IP per compose project.
-// Short TTL + invalidate-on-connect-error so a resumed container's new IP heals.
-const CONTAINER_IP_TTL_MS = 60_000;
-const containerIpCache = new Map<string, { ip: string; ts: number }>();
-
-async function resolveContainerIp(composeProject: string): Promise<string | null> {
-  const container = `${composeProject}-app-1`;
-  const cached = containerIpCache.get(container);
-  if (cached && Date.now() - cached.ts < CONTAINER_IP_TTL_MS) return cached.ip;
-  const res = await dockerCli(
-    [
-      "inspect",
-      "-f",
-      "{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}",
-      container,
-    ],
-    { timeoutMs: 5_000 },
-  );
-  if (res.status !== 0) return null;
-  const ip = res.stdout.trim();
-  if (!ip) return null;
-  containerIpCache.set(container, { ip, ts: Date.now() });
-  return ip;
-}
-
-/** Drop any cached container IP equal to `addr` (no-op for `127.0.0.1`). */
-function invalidateContainerIpByAddr(addr: string): void {
-  if (addr === "127.0.0.1") return;
-  for (const [key, val] of containerIpCache) {
-    if (val.ip === addr) containerIpCache.delete(key);
-  }
+  /** Connection already established while the identity proof was still held
+   * (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;
 }
 
 async function resolveTunnelTarget(
   frame: Extract<CloudToHost, { kind: "tunnel.open" }>,
 ): Promise<UpstreamAddr | null> {
+  // Persisted ports are meaningful only while the selected runtime is known
+  // operational. After a daemon restart an unrelated local process could bind
+  // a stale port before recovery refreshes the task's mappings.
+  if (containerRuntimeProblem()) return null;
   const task = getHostTask(frame.taskId);
   if (!task) return null;
+  if (containerRuntimeMachineIdentity()?.backend === "apple-container") {
+    // Apple vmnet IPs are host-routable, so editor and every preview resolve
+    // to the same direct route: the label-proven container IP plus the
+    // requested container port. Nothing is published and no sidecar exists.
+    // The proof/connect/epoch discipline lives in apple-tunnel-route.ts,
+    // where it is directly testable.
+    const appleRoute = await resolveAppleTunnelRoute(
+      {
+        taskId: frame.taskId,
+        target: frame.target,
+        ...(frame.containerPort !== undefined
+          ? { containerPort: frame.containerPort }
+          : {}),
+      },
+      {
+        getTask: (taskId) => getHostTask(taskId) ?? undefined,
+        reconstruct: (current) =>
+          reconstructPersistedTaskEnvironment(current as never),
+        runTaskLifecycle: (taskId, work) =>
+          getOrchestrator().runTaskLifecycle(taskId, work),
+        runtimeProblem: () => containerRuntimeProblem(),
+        readinessEpoch: () => containerRuntimeReadinessEpoch(),
+        epochIsCurrent: (epoch) => containerRuntimeEpochIsCurrent(epoch),
+        poison: (detail) => poisonContainerRuntimeFromTunnel(detail),
+        createSocket: () => new Socket(),
+      },
+    );
+    if (appleRoute === null) return null;
+    return {
+      host: appleRoute.host,
+      port: appleRoute.port,
+      socket: appleRoute.socket as Socket,
+    };
+  }
+  const appContainer = task.composeProject
+    ? `${task.composeProject}-app-1`
+    : null;
+  let appProof: Awaited<ReturnType<typeof inspectTunnelContainer>> | null = null;
+  const inspectApp = async (containerPort: number) => {
+    // One frame resolves one target port. Keep a local memo only so a failed
+    // sidecar path can reuse the exact live app proof; no proof survives the
+    // tunnel open that requested it.
+    if (!appContainer) return null;
+    appProof ??= await inspectTunnelContainer(appContainer, containerPort);
+    if (appProof.kind === "daemon-unavailable") {
+      poisonContainerRuntimeFromTunnel(appProof.detail);
+      return null;
+    }
+    // A forced recheck or a different Docker caller can invalidate the runtime
+    // while this inspect is in flight. Do not publish even a successful proof
+    // from an epoch that is no longer operational.
+    if (containerRuntimeProblem()) return null;
+    return appProof.kind === "running" ? appProof : null;
+  };
   if (frame.target === "editor") {
-    return task.codeServerPort
-      ? { host: "127.0.0.1", port: task.codeServerPort }
-      : null;
+    if (!task.codeServerPort) return null;
+    return (await inspectApp(8080))?.published ?? null;
   }
   // Preview. Prefer the PUBLISHED host port for declared previews (published at
   // task-up): a 127.0.0.1 port that's reachable on every backend, incl.
@@ -1038,13 +1883,25 @@ async function resolveTunnelTarget(
     const declared = parsePreviewPortRuntimes(task.previewPorts).find(
       (port) => port.name === frame.name,
     );
-    if (declared) return { host: "127.0.0.1", port: declared.hostPort };
+    if (declared) {
+      // The stored hostPort is authorization/display state, not routing truth.
+      // Docker may remap it after a daemon restart. The cloud supplies the
+      // declaration's containerPort so we can resolve the exact current route.
+      if (!frame.containerPort) return null;
+      const proof = await inspectApp(frame.containerPort);
+      if (proof?.published) return proof.published;
+      if (proof?.containerIp) {
+        return { host: proof.containerIp, port: frame.containerPort };
+      }
+      return null;
+    }
     // Ad-hoc port (not published): proxy via a node-proxy sidecar that publishes
     // a 127.0.0.1 port forwarding to <app>:<containerPort> (ADR-043).
     if (frame.containerPort && task.composeProject) {
       const hostPort = await getOrchestrator().runTaskLifecycle(
         frame.taskId,
         async () => {
+          if (containerRuntimeProblem()) return null;
           const current = getHostTask(frame.taskId);
           if (
             current?.statusMirror !== "running" ||
@@ -1060,19 +1917,39 @@ async function resolveTunnelTarget(
           });
         },
       );
-      if (hostPort) return { host: "127.0.0.1", port: hostPort };
+      if (hostPort && !containerRuntimeProblem()) {
+        return { host: "127.0.0.1", port: hostPort };
+      }
     }
   }
   // Linux fallback (pre-ADR-043 / non-macOS host where bridge IPs route): proxy
   // straight to the container IP. Unreachable on macOS/OrbStack — the
   // connect-error path returns 502 there.
   if (frame.containerPort && task.composeProject) {
-    const ip = await resolveContainerIp(task.composeProject);
-    if (ip) return { host: ip, port: frame.containerPort };
+    const proof = await inspectApp(frame.containerPort);
+    if (proof?.containerIp) {
+      return { host: proof.containerIp, port: frame.containerPort };
+    }
   }
   return null;
 }
 
+function poisonContainerRuntimeFromTunnel(detail: string): void {
+  // Fail closed synchronously: another frame in this event-loop turn must see
+  // `checking`, not route through a stale localhost port. The normal runtime
+  // listener owns bounded recheck, recovery, and the eventual ready advert.
+  if (containerRuntimeProblem()) return;
+  console.warn(`[host-agent] tunnel Docker proof failed: ${detail}`);
+  suspendContainerRuntime(true);
+  sendCapabilities();
+  void initializeContainerRuntime();
+}
+
+function requireContainerRuntime(): void {
+  const problem = containerRuntimeProblem();
+  if (problem) throw new Error(problem);
+}
+
 function serializeRequest(reqLine: {
   method: string;
   url: string;
@@ -1294,6 +2171,33 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
   if (frame.kind === "event.ack" && typeof frame.seq === "number") {
     return { kind: "event.ack", seq: frame.seq };
   }
+  if (
+    frame.kind === "host.inventory.request" &&
+    isSafeInventoryScanId(frame.scanId) &&
+    (frame.cursor === null || isSafeHostTaskId(frame.cursor)) &&
+    typeof frame.limit === "number" &&
+    Number.isSafeInteger(frame.limit) &&
+    frame.limit >= 1 &&
+    frame.limit <= MAX_HOST_TASK_INVENTORY_PAGE_SIZE
+  ) {
+    return {
+      kind: "host.inventory.request",
+      scanId: frame.scanId,
+      cursor: frame.cursor,
+      limit: frame.limit,
+    };
+  }
+  // ADR-100 remote operations are exact-shape parsed in the shared protocol
+  // module. Do not reconstruct them here: doing so could accidentally admit a
+  // secret-bearing or forward-version field that the opposite peer rejects.
+  if (isHostLogsStartFrame(frame)) return frame;
+  if (isHostLogsStopFrame(frame)) return frame;
+  if (isEngineLoginStartFrame(frame)) return frame;
+  if (isEngineLoginInputFrame(frame)) return frame;
+  if (isEngineLoginCallbackFrame(frame)) return frame;
+  if (isEngineLoginStopFrame(frame)) return frame;
+  if (isHostConfigGetFrame(frame)) return frame;
+  if (isHostConfigSetFrame(frame)) return frame;
   if (
     frame.kind === "command" &&
     typeof frame.commandId === "string" &&
@@ -1519,10 +2423,186 @@ function isReqLine(value: unknown): value is {
   );
 }
 
+function hostLogStartErrorMessage(error: HostLogStartError): string {
+  switch (error.code) {
+    case "invalid_op_id":
+      return "invalid host log operation id";
+    case "duplicate_op":
+      return "host log operation is already active";
+    case "too_many_streams":
+      return "too many host log streams are active";
+  }
+}
+
+function sendHostConfigAck(
+  emit: (frame: HostToCloud) => boolean,
+  opId: string,
+  result: HostConfigResult,
+): void {
+  if (result.ok) {
+    emit({
+      kind: "host.config.ack",
+      opId,
+      ok: true,
+      config: result.config,
+      restartRequired: result.restartRequired,
+    });
+    return;
+  }
+  emit({
+    kind: "host.config.ack",
+    opId,
+    ok: false,
+    errorCode: result.errorCode,
+    message: result.message,
+  });
+}
+
 function send(socket: WebSocket, frame: HostToCloud): void {
   socket.send(JSON.stringify(frame));
 }
 
+/**
+ * Once shutdown begins, keep the authenticated socket open only to flush work
+ * that was already admitted. New requests receive a retryable/negative reply
+ * instead of extending the drain or mutating state after teardown was chosen.
+ * Transport housekeeping and frames belonging to an already-open tunnel are
+ * allowed to finish until the socket closes.
+ */
+function rejectFrameDuringShutdown(
+  socket: WebSocket,
+  frame: CloudToHost,
+): boolean {
+  const error = "managed host is restarting; retry the operation";
+  switch (frame.kind) {
+    case "command":
+      send(socket, {
+        kind: "result",
+        commandId: frame.commandId,
+        result: {
+          ok: false,
+          code: HostErrorCode.HostUnavailable,
+          message: error,
+          retryable: true,
+          retryReason: "managed_restart",
+        },
+      });
+      return true;
+    case "host.logs.start":
+      send(socket, {
+        kind: "host.logs.end",
+        opId: frame.opId,
+        reason: "error",
+        message: error,
+      });
+      return true;
+    case "engine.login.start":
+      send(socket, {
+        kind: "engine.login.event",
+        opId: frame.opId,
+        engine: frame.engine,
+        phase: "failed",
+        errorCode: "unavailable",
+        message: error,
+      });
+      return true;
+    case "host.config.get":
+    case "host.config.set":
+      send(socket, {
+        kind: "host.config.ack",
+        opId: frame.opId,
+        ok: false,
+        errorCode: "persistence_failed",
+        message: error,
+      });
+      return true;
+    case "tunnel.open":
+      send(socket, {
+        kind: "tunnel.close",
+        tunnelId: frame.tunnelId,
+        reason: error,
+      });
+      return true;
+    case "gh.connect.set":
+    case "gh.connect.clear":
+      send(socket, {
+        kind: "gh.connect.ack",
+        opId: frame.opId,
+        userId: frame.userId,
+        ok: false,
+        error,
+      });
+      return true;
+    case "gh.installations.list":
+      send(socket, {
+        kind: "gh.installations.ack",
+        opId: frame.opId,
+        ok: false,
+        code: "github_unavailable",
+        error,
+      });
+      return true;
+    case "gh.repositories.list":
+      send(socket, {
+        kind: "gh.repositories.ack",
+        opId: frame.opId,
+        ok: false,
+        code: "github_unavailable",
+        error,
+      });
+      return true;
+    case "ssh.key.get":
+    case "ssh.key.ensure":
+    case "ssh.key.delete":
+      send(socket, {
+        kind: "ssh.key.ack",
+        userId: frame.userId,
+        ok: false,
+        error,
+      });
+      return true;
+    case "env.var.list":
+    case "env.var.set":
+    case "env.var.delete":
+      send(socket, {
+        kind: "env.var.ack",
+        opId: frame.opId,
+        ok: false,
+        error,
+      });
+      return true;
+    case "mcp.op":
+      send(socket, {
+        kind: "mcp.ack",
+        opId: frame.opId,
+        ok: false,
+        error,
+      });
+      return true;
+    case "host.inventory.request":
+      // Read-only and retryable after the replacement process reconnects. A
+      // partial page during shutdown would be tied to a dying generation.
+      return true;
+    case "host.logs.stop":
+    case "engine.login.stop":
+      // Stops remain idempotent during drain and cannot admit new work.
+      return false;
+    case "engine.login.input":
+    case "engine.login.callback":
+      // All login managers were synchronously cancelled when shutdown began.
+      // These single-use artifacts are dropped instead of being retained or
+      // reflected in an event after their operation ceased to exist.
+      return true;
+    case "pong":
+    case "event.resume":
+    case "event.ack":
+    case "tunnel.data":
+    case "tunnel.requestEnd":
+    case "tunnel.close":
+      return false;
+  }
+}
+
 function rawDataToBuffer(data: RawData): Buffer {
   if (Buffer.isBuffer(data)) return data;
   if (data instanceof ArrayBuffer) return Buffer.from(data);
@@ -1655,11 +2735,24 @@ function expectTaskLaunchInput(
 
 function expectTaskDownInput(args: unknown[], index: number): TaskDownInput {
   const input = expectRecord(args[index], "task down input");
-  return {
-    taskId: expectStringValue(input.taskId, "taskId"),
-    task: expectTaskCommandTask(input.task),
+  const taskId = expectStringValue(input.taskId, "taskId");
+  const task = expectTaskCommandTask(input.task);
+  if (!isSafeHostTaskId(taskId) || task.id !== taskId) {
+    throw new Error("invalid task down identity");
+  }
+  const out: TaskDownInput = {
+    taskId,
+    task,
     projects: expectTaskCommandProjects(input.projects),
   };
+  if (Object.prototype.hasOwnProperty.call(input, "cleanup")) {
+    const cleanup = expectRecord(input.cleanup, "task down cleanup");
+    if (cleanup.kind !== "orphan-gc" || cleanup.pruneLocalState !== true) {
+      throw new Error("invalid task down cleanup marker");
+    }
+    out.cleanup = { kind: "orphan-gc", pruneLocalState: true };
+  }
+  return out;
 }
 
 function expectTaskDiffInput(args: unknown[], index: number): TaskDiffInput {
@@ -1905,11 +2998,9 @@ function expectStringValue(value: unknown, label: string): string {
 
 function ensureHostId(): string {
   mkdirSync(env.dataDir, { recursive: true, mode: 0o700 });
-  const path = join(env.dataDir, "host-id");
-  if (existsSync(path)) {
-    const existing = readFileSync(path, "utf8").trim();
-    if (existing) return existing;
-  }
+  const existing = readPersistedHostId();
+  if (existing) return existing;
+  const path = hostIdFilePath();
   const id = newId();
   writeFileSync(path, `${id}\n`, { mode: 0o600 });
   return id;
@@ -1936,16 +3027,68 @@ function reconnectDelay(): number {
 function requestShutdown(signal: NodeJS.Signals): void {
   console.log(`[host-agent] ${signal} received; shutting down`);
   stopping = true;
+  // Cancel human-paced operations without invalidating this socket's exact
+  // generation: already-admitted one-shot config writes may still ack while
+  // the ordinary in-flight drain completes.
+  void stopRemoteOperationManagers();
+  stopMcpGatewaySubscription();
+  stopAgentClisReadySubscription();
+  void mcpGateway.stop();
+  managedMutationDrain.stopAccepting();
+  stopRuntimeAutoRecheck();
+  runtimeActivationTail.stop();
   shutdownRequested = true;
-  if (ws && ws.readyState === WebSocket.OPEN) {
-    ws.close(1001, "host shutting down");
-  }
   maybeExit();
 }
 
 function maybeExit(): void {
-  if (!shutdownRequested || inFlight > 0) return;
-  process.exit(0);
+  if (
+    !shutdownRequested ||
+    inFlight > 0 ||
+    managedMutationDrain.activeCount > 0 ||
+    pendingRemoteOperationCleanups.size > 0
+  ) return;
+  if (ws) {
+    if (ws.readyState === WebSocket.OPEN) {
+      // `ws.close()` queues the close frame after already-queued ack/result
+      // frames. Wait for its close event before terminating the process so
+      // those replies are not truncated by `process.exit`.
+      ws.close(1001, "host shutting down");
+      return;
+    }
+    if (ws.readyState === WebSocket.CONNECTING) {
+      // There is no authenticated transport to drain yet. Termination emits
+      // `close`, whose handler calls maybeExit again with `ws` cleared.
+      ws.terminate();
+      return;
+    }
+    if (ws.readyState === WebSocket.CLOSING) return;
+  }
+  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.
+ */
+export function requestManagedHostRestart(): void {
+  shutdownExitCode = MANAGED_UPDATE_RESTART_EXIT_CODE;
+  requestShutdown("SIGTERM");
+}
+
+/** Automatic host updates wait only for in-flight work to drain. Running
+ * tasks are deliberately not counted: durable sessions survive the service
+ * restart, and gating on their existence made a busy host un-updatable
+ * (live 2026-08-17 — the owner's explicit requirement is update-under-load). */
+export function isIdleForManagedHostUpdate(): boolean {
+  return (
+    !stopping &&
+    !shutdownRequested &&
+    inFlight === 0 &&
+    managedMutationDrain.activeCount === 0 &&
+    !hasInFlightHostTaskLifecycle()
+  );
 }
 
 function requireEnv(name: string): string {