@moondeck/station 1.0.0 → 1.0.2

package/lib/orchestrator.ts

@@ -1,4 +1,5 @@
 import { isOwnedInternalConnectionRuntime } from "./internal-connections";
+import { prepareNodeData } from "./node-state";
 import { registerConnectionSecret } from "./connection-secret-redaction";
 import { buildCustomConnectionLaunch, tomlString, connectionNativeBlanks, connectionHomePreparation, newConnectionHome, connectionDnsLookupArgv, validateConnectionAddresses, connectionConnectArgv, CustomConnectionLaunchError, launchRefusal, CONNECTION_CONNECT_TIMEOUT_MS } from "./custom-connection-launch";
 import { connectionFailureReason, ConnectionEventSanitizer } from "./custom-connection-runtime";
@@ -9554,37 +9555,15 @@ async function quarantineRunningContainer(
   return "failed";
 }
 
-/**
- * Repair the shared node data root before any recovered-container init.
- * Older task-up versions created the OpenCode leaf as root and accidentally
- * left this parent root-owned, which prevented code-server from creating its
- * managed User profile. `install -d` creates or repairs the exact directory
- * without recursively changing unrelated application state beneath it.
- */
+/** Heal only pinned node directory descriptors; task code may still be running. */
 async function repairNodeDataRoot(containerName: string): Promise<boolean> {
-  const res = await dockerCli([
-    "exec",
-    "-u",
-    "root",
-    ...runtimeAuthorityDockerExecArgs(),
-    containerName,
-    "/usr/bin/install",
-    "-d",
-    "-o",
-    "node",
-    "-g",
-    "node",
-    "-m",
-    "0755",
-    "/home/node/.local/share",
-  ]);
-  if (res.status !== 0) {
-    console.error(
-      `[orchestrator] recovery: ${containerName} could not repair /home/node/.local/share ownership: ${res.stderr.trim() || `docker exec exited ${String(res.status)}`}`,
-    );
-    return false;
-  }
-  return true;
+  const ok = await prepareNodeData(async (user, argv) => {
+    const result = await dockerCli(["exec", "-u", user, ...runtimeAuthorityDockerExecArgs(), containerName, ...argv]);
+    if (result.stderr.trim()) console.warn(result.stderr.trim());
+    return result.status;
+  });
+  if (!ok) console.error(`[orchestrator] recovery: ${containerName} could not repair application directory metadata`);
+  return ok;
 }
 
 interface DockerPortResult {
@@ -10581,7 +10560,8 @@ export async function recoverAppleTaskEnvironment(
       // effective mount at the merged path and the lower, comma-delimited
       // option tokens (substring matching accepted a -evil suffix), a
       // read-only lower, and a real node-owned upper.
-      "set -e; /bin/mkdir -p /var/lib/uai/asdf-upper /var/lib/uai/asdf-work /opt/asdf-data; " +
+      "set -e; { printf '80\\n' > /proc/sys/net/ipv4/ip_unprivileged_port_start; } || echo 'could not set low-port boundary to 80; continuing recovery' >&2; " +
+        "/bin/mkdir -p /var/lib/uai/asdf-upper /var/lib/uai/asdf-work /opt/asdf-data; " +
         "/bin/chown node:node /var/lib/uai/asdf-upper; " +
         'if ! /bin/grep -q "^overlay /opt/asdf-data overlay " /proc/mounts; then ' +
         "/bin/mount -t overlay overlay -o lowerdir=/run/uai/asdf-lower,upperdir=/var/lib/uai/asdf-upper,workdir=/var/lib/uai/asdf-work /opt/asdf-data; fi; " +
@@ -10644,6 +10624,13 @@ export async function recoverAppleTaskEnvironment(
     );
     return settleFromStatus(afterOverlay);
   }
+  const nodeDataReady = await prepareNodeData(async (user, argv) => {
+    const result = await environment.exec({ user, argv, projectEnvProfile: "maintenance", timeoutMs: 10_000, maxOutputBytes: 64 * 1024 });
+    const diagnostics = Buffer.from(result.stderr).toString("utf8").trim();
+    if (diagnostics) console.warn(diagnostics);
+    return result.exitCode;
+  });
+  if (!nodeDataReady) return { outcome: "deferred", detail: "could not repair application directory metadata" };
   // The dependency worker inside uai-init performs its one loader sync. Its
   // root forwarder and authenticated generation must be live first, while
   // public agent admission remains quarantined until initialization ends.

package/lib/preview-ports.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { isPreviewUpstreamHost } from "../src/preview-upstream";
 
 export const PREVIEW_PORT_NAME_RE = /^[a-z0-9][a-z0-9_-]{0,62}$/;
 
@@ -13,6 +14,8 @@ export const PreviewPortDeclarationSchema = z.object({
       "name must be lowercase letters, digits, _ or -, starting with a letter or digit",
     ),
   containerPort: z.coerce.number().int().min(1).max(65535),
+  upstreamHost: z.string().refine(isPreviewUpstreamHost).transform((host) => host.toLowerCase()).optional(),
+  upstreamTls: z.boolean().optional(),
 });
 
 export const PreviewPortRuntimeSchema = z.object({

package/lib/preview-upstream.ts

@@ -0,0 +1,61 @@
+import { connect as tcpConnect, type Socket } from "node:net";
+import { connect as tlsConnect } from "node:tls";
+import { parsePreviewUpstream, type PreviewUpstream } from "../src/preview-upstream";
+
+export interface PreviewUpstreamTarget {
+  host: string;
+  port: number;
+  socket?: Socket;
+  connectTimeoutMs?: number;
+}
+
+class PreviewConnectFailure extends Error {}
+export function isPreviewConnectFailure(error: unknown): boolean {
+  return error instanceof PreviewConnectFailure;
+}
+
+/** A resolved task route is the only destination authority. Host/SNI is never
+ * passed to connect() or DNS. Wrapping an Apple-proven socket preserves its peer. */
+export async function preparePreviewUpstream<T extends PreviewUpstreamTarget>(target: T, input: PreviewUpstream): Promise<T> {
+  const settings = parsePreviewUpstream(input);
+  if (!settings) throw new Error("invalid preview upstream settings");
+  if (!settings.upstreamTls) return target;
+  return new Promise((resolve, reject) => {
+    const tcp = target.socket ?? tcpConnect(target.port, target.host);
+    // Task-generated dev CAs are deliberately not system-trusted. The caller
+    // already proved this exact task route, just as for plaintext previews.
+    // This option applies only to this socket, never external HTTPS or WSS.
+    const secure = tlsConnect({ socket: tcp, servername: settings.upstreamHost, rejectUnauthorized: false });
+    let connected = Boolean(target.socket) || !tcp.connecting;
+    tcp.once("connect", () => { connected = true; });
+    const fail = (error: Error) => {
+      clearTimeout(timer);
+      secure.destroy();
+      tcp.destroy();
+      reject(connected ? error : new PreviewConnectFailure(error.message, { cause: error }));
+    };
+    const closed = () => fail(new Error("preview TLS handshake closed"));
+    const timer = setTimeout(() => fail(new Error("preview TLS handshake timed out")), target.connectTimeoutMs ?? 10_000);
+    timer.unref?.();
+    tcp.once("error", fail);
+    secure.once("error", fail);
+    secure.once("close", closed);
+    secure.once("secureConnect", () => {
+      clearTimeout(timer);
+      tcp.removeListener("error", fail);
+      tcp.on("error", (error) => secure.destroy(error));
+      secure.removeListener("error", fail);
+      secure.removeListener("close", closed);
+      // Keep errors handled until the HTTP/upgrade consumer attaches its own
+      // listeners on the continuation. It still receives every error event.
+      secure.on("error", () => {});
+      resolve({ ...target, socket: secure });
+    });
+  });
+}
+
+export function previewRequestHeaders(headers: [string, string][], settings: PreviewUpstream): [string, string][] {
+  if (settings.upstreamHost === undefined) return headers;
+  if (!parsePreviewUpstream(settings)) throw new Error("invalid preview upstream settings");
+  return [...headers.filter(([name]) => name.toLowerCase() !== "host"), ["host", settings.upstreamHost.toLowerCase()]];
+}

package/lib/runtime-archive.ts

@@ -64,8 +64,10 @@ const STANDARD_IMAGE_ASSETS = Object.freeze([
   Object.freeze({ path: "README.md", mode: 0o644 as const }),
   Object.freeze({ path: "container/code-server-settings.json", mode: 0o644 as const }),
   Object.freeze({ path: "container/corepack-version", mode: 0o644 as const }),
+  Object.freeze({ path: "container/uai-create-node-data", mode: 0o644 as const }),
   Object.freeze({ path: "container/uai-init", mode: 0o755 as const }),
   Object.freeze({ path: "container/uai-materialize-runtimes", mode: 0o755 as const }),
+  Object.freeze({ path: "container/uai-repair-node-data.py", mode: 0o644 as const }),
   Object.freeze({ path: "container/uai-task-forwarder.mjs", mode: 0o644 as const }),
   Object.freeze({ path: "tool-versions", mode: 0o644 as const }),
 ]);

package/lib/task-environment/machine-task-up.ts

@@ -16,6 +16,7 @@
  * key). Consumers that need the workspace go through the environment handle.
  */
 import { execFile } from "node:child_process";
+import { prepareNodeData } from "../node-state";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -1055,6 +1056,32 @@ export function createMachineHostTaskEnvironmentProvider(
 
       try {
         if (clone?.signal.aborted) throw withdrawal();
+        // Local Docker machines receive the sysctl at create time (their
+        // /proc/sys is read-only). Dedicated machine kernels can set it here,
+        // covering preserved AMIs as well as the image's sysctl.d default.
+        const nodeDataReady = await stage(prepareNodeData(async (user, argv) => {
+          const result = await own.exec({ user, argv, projectEnvProfile: "maintenance", env: { HOME: user === "root" ? "/root" : "/home/node", PATH: "/usr/sbin:/usr/bin:/bin" }, timeoutMs: GIT_STEP_TIMEOUT_MS, maxOutputBytes: STEP_OUTPUT_BYTES });
+          const diagnostics = Buffer.from(result.stderr).toString("utf8").trim();
+          if (diagnostics) console.warn(diagnostics);
+          return result.exitCode;
+        }));
+        if (!nodeDataReady) throw new Error("could not repair task machine application directory metadata");
+        const workbench = await stage(own.exec({
+          argv: ["/bin/sh", "-c",
+            'if [ "$(cat /proc/sys/net/ipv4/ip_unprivileged_port_start)" != 80 ]; then printf "80\\n" > /proc/sys/net/ipv4/ip_unprivileged_port_start; fi'],
+          user: "root",
+          projectEnvProfile: "maintenance",
+          env: { HOME: "/root", PATH: "/usr/sbin:/usr/bin:/bin" },
+          timeoutMs: GIT_STEP_TIMEOUT_MS,
+          maxOutputBytes: STEP_OUTPUT_BYTES,
+        }));
+        // Reused local Docker machines keep their creation-time sysctl and
+        // mount /proc/sys read-only. Preserve their work and allow Resume;
+        // the lower port boundary can wait until the machine is recreated.
+        if (workbench.exitCode !== 0) {
+          const diagnostics = Buffer.from(workbench.stderr).toString("utf8").trim();
+          console.warn(`could not set low-port boundary to 80; recreate this machine for ports 80–1023${diagnostics ? `: ${diagnostics}` : ""}`);
+        }
         // ADR-154 §12: the runtime exists and nothing in it has run yet: the
         // runner's writes (the owner's GitHub configuration and SSH key,
         // recorded for cleanup) come first, so the clones below authenticate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moondeck/station",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Moondeck Station: runs Moondeck tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Moondeck <team@moondeck.io>",

package/scripts/agent/task-up.sh

@@ -1917,6 +1917,9 @@ mv -f "$managed_env_keys_tmp" "$managed_env_keys_file"
     printf '    pull_policy: never\n'
   fi
   printf '    init: true\n'
+  # Confined to this task's network namespace; no host-wide sysctl changes.
+  printf '    sysctls:\n'
+  printf '      net.ipv4.ip_unprivileged_port_start: "80"\n'
   # Keep the host MCP gateway reachable through Docker's ordinary
   # host-gateway address. (The Apple runtime has no extra_hosts equivalent
   # and none is rendered for it; its gateway route is the vmnet gateway IP.)
@@ -2876,6 +2879,9 @@ if [ "$TASK_RUNTIME_MODE" = "apple-container" ]; then
   overlay_rc=0
   "$CONTAINER_CLI" exec -u root "$app_container" /bin/sh -c '
     set -e
+    # Apple has no run --sysctl option. This guest has its own kernel and
+    # CAP_NET_ADMIN, so set the equivalent before any task process starts.
+    { printf "80\n" > /proc/sys/net/ipv4/ip_unprivileged_port_start; } || echo '"'"'could not set low-port boundary to 80; continuing'"'"' >&2
     /bin/mkdir -p /var/lib/uai/asdf-upper /var/lib/uai/asdf-work /opt/asdf-data
     # The merged root inherits the UPPER directory'"'"'s metadata; without this
     # the node user cannot write the merged view at all (live 2026-08-18).
@@ -3364,20 +3370,24 @@ if [ "$secrets_proxy_trust" = "installed" ]; then
   secrets_proxy_report pins "$secrets_proxy_pins"
 fi
 
-# OpenCode and code-server share ~/.local/share. OpenCode credentials are
-# copied as root below, so creating only its leaf with `mkdir -p` can leave the
-# shared parent root-owned (live 2026-08-04). Then node cannot create
-# code-server's User profile and the editor silently falls back to its light,
-# full-chrome defaults. Repair both explicitly on every start/resume; GNU
-# `install -d` also corrects an existing directory with the wrong owner.
-if ! crt exec -u root "${managed_exec_env[@]}" "$app_container" \
-  /usr/bin/install -d -o node -g node -m 0755 \
-    /home/node/.local/share \
-    /home/node/.local/share/opencode >/dev/null; then
-  emit_err "CONTAINER_INIT_FAILED" \
-    "Moondeck could not prepare the task's node-owned application data directory. Retry the task; the editor cannot load its settings until this succeeds." \
-    "prepare container application data"
-fi
+# The same packaged scripts are consumed by lib/node-state.ts. Root only
+# changes metadata through no-follow directory descriptors; creation is node's.
+NODE_STATE_SETUP_SCRIPT=$(cat "$STANDARD_CONTAINER_DIR/uai-repair-node-data.py")
+NODE_DATA_CREATE_SCRIPT=$(cat "$STANDARD_CONTAINER_DIR/uai-create-node-data")
+for node_data_phase in repair create repair; do
+  if [ "$node_data_phase" = create ]; then
+    node_data_user=node
+    node_data_argv=( /bin/sh -c "$NODE_DATA_CREATE_SCRIPT" )
+  else
+    node_data_user=root
+    node_data_argv=( /usr/bin/python3 -I -c "$NODE_STATE_SETUP_SCRIPT" )
+  fi
+  if ! crt exec -u "$node_data_user" "${managed_exec_env[@]}" "$app_container" "${node_data_argv[@]}" >/dev/null; then
+    emit_err "CONTAINER_INIT_FAILED" \
+      "Moondeck could not prepare node-owned application data directory metadata." \
+      "prepare container application data"
+  fi
+done
 
 # Git rejects a repository owned by another uid even when its shared group is
 # writable. Trust only the selected worktrees in this task container—never `*`
@@ -3606,7 +3616,7 @@ for oc_item in auth.json config.json; do
   fi
 done
 crt exec -u root "${managed_exec_env[@]}" "$app_container" \
-  /usr/bin/chown -R node:node /home/node/.local/share/opencode >/dev/null 2>&1 || true
+  /usr/bin/python3 -I -c "$NODE_STATE_SETUP_SCRIPT" >/dev/null || log "warning: opencode metadata repair failed"
 
 # Copy the resolved SSH identity into the container for commit/tag signing and
 # as the no-GitHub-connection transport fallback. Connected users clone, fetch,

package/src/bridge-diagnostics.ts

@@ -0,0 +1,39 @@
+/**
+ * What station.log says about a lost cloud connection, so its cause can be
+ * read off the log. The previous MacBook Air station showed 599 reconnects
+ * over about 18 hours as bare "disconnected; reconnecting in ~1s" lines:
+ * neither who closed the socket nor why was logged, and nothing showed that
+ * the Mac had been asleep (2026-11-03).
+ */
+
+/** The close code and reason in words: who closed it, and why if known. */
+export function describeClose(code: number, reason: string): string {
+  const why = reason.trim();
+  const known: Record<number, string> = {
+    1000: "closed normally",
+    1001: "the cloud went away (restart or deploy)",
+    1006: "the connection dropped without a close frame (network, sleep or a proxy)",
+    1011: "the cloud hit an internal error",
+    1012: "the cloud is restarting",
+    1013: "the cloud asked to try again later",
+    4000: "closed by the cloud or this station",
+    4001: "authentication refused",
+  };
+  const label = known[code] ?? "closed";
+  return `code ${code}, ${label}${why ? `: ${why}` : ""}`;
+}
+
+/** How far past its due time a periodic timer may fire before the gap counts
+ *  as a suspension (system sleep, a stopped process) rather than load. */
+export const SUSPEND_SLACK_MS = 20_000;
+
+/**
+ * The time this process was suspended, when a timer due every `intervalMs`
+ * fires `now - previousTick` later; null when it fired on time. A sleeping
+ * Mac stops every timer; on wake the gap shows, the cloud has long dropped
+ * the silent socket (it closes one silent for 45 s), and a reconnect follows.
+ */
+export function suspendedFor(previousTick: number, now: number, intervalMs: number): number | null {
+  const gap = now - previousTick;
+  return gap > intervalMs + SUSPEND_SLACK_MS ? gap : null;
+}

package/src/cli.ts

@@ -91,6 +91,7 @@ import { PINNED_RELEASE_MANIFEST_KEYS } from "../lib/release-trust";
 import { sidecarMode } from "../lib/sidecar";
 import { systemUserBusProbe } from "../lib/user-bus-env";
 import { LEGACY_HOST, STATION, STATION_DEFAULT_CLOUD_URL } from "./station-identity";
+import { enrollmentNextSteps } from "./enrollment-next-steps";
 import {
   inspectLegacyHost,
   legacyHostRunningReason,
@@ -1729,10 +1730,11 @@ async function cmdSetup(rest: string[]): Promise<void> {
     console.log(green("✓ enrolled") + dim(` — config written to ${envLocalPath()}`));
   }
   printTelemetryNotice();
-  console.log("");
-  console.log("Start the host:");
-  console.log(cyan("  moondeck-station install && moondeck-station start") + dim("   (first time)"));
-  console.log(cyan("  moondeck-station restart") + dim("                     (already installed)"));
+  const steps = enrollmentNextSteps();
+  if (steps.length > 0) console.log("");
+  for (const step of steps) {
+    console.log(step.command ? cyan(step.command) + dim(step.note ?? "") : step.text);
+  }
 }
 
 // --- enroll (attach an org, ADR-098) -----------------------------------------

package/src/enrollment-next-steps.ts

@@ -0,0 +1,24 @@
+/**
+ * What `moondeck-station enroll` / `setup` tells the person to do once the
+ * machine is enrolled. Run by hand, the next step is theirs: install and
+ * start the service, or restart it. Run by the installer (which exports
+ * UAI_FROM_INSTALLER=1 for its enrollment call), the installer registers and
+ * starts the service itself right after, so telling the person to do it was
+ * a stale instruction (the owner's public-install test, 2026-11-03).
+ *
+ * An environment variable rather than a flag: the installer the cloud serves
+ * may run a station runtime older than this one, which ignores an unknown
+ * variable but would refuse an unknown flag.
+ */
+import { STATION } from "./station-identity";
+
+export const FROM_INSTALLER_ENV = "UAI_FROM_INSTALLER";
+
+export function enrollmentNextSteps(env: NodeJS.ProcessEnv = process.env): Array<{ text: string; command?: string; note?: string }> {
+  if (env[FROM_INSTALLER_ENV] === "1") return [];
+  return [
+    { text: "Start the station:" },
+    { text: "", command: `  ${STATION.command} install && ${STATION.command} start`, note: "   (first time)" },
+    { text: "", command: `  ${STATION.command} restart`, note: "                     (already installed)" },
+  ];
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 import { assertShareablePath, normalizedWorkspacePath } from "./workspace-path-policy";
+import { hasPreviewUpstream, parsePreviewUpstream, tunnelPreviewUpstream } from "./preview-upstream";
 import { readBoundedFile } from "../lib/task-environment/workspace-files";
 import {
   agent,
@@ -18,6 +19,7 @@ import {
   type LegacyStartPermit,
 } from "../lib/cloud-credential-host";
 import type { TaskAssignment } from "../lib/cloud-credential-leases";
+import { deliverFirstTurnOnce } from "../lib/first-turn-receipts";
 import {
   StartInterruptedError,
   type CloudCredentialRuntime,
@@ -2039,7 +2041,7 @@ export const hostCommands: HostCommands = {
     });
   },
 
-  async channelDeliver(ctx, taskId, agentId, text, origin, assignment) {
+  async channelDeliver(ctx, taskId, agentId, text, origin, assignment, firstTurnId) {
     logCommand(ctx, "channelDeliver", taskId, agentId);
     if (credentialsMode() === "pending") {
       return switchingToCloudCredentials();
@@ -2050,22 +2052,36 @@ export const hostCommands: HostCommands = {
       // An inbound turn is activity: the idle veto must cover the gap between
       // this delivery landing and the agent's first output event.
       getOrchestrator().markChannelActivity(taskId);
-      const result = await getOrchestrator().deliver(taskId, agentId, text, origin, assignment);
-      if (!result.ok) {
-        return {
-          ok: false,
-          code: mapDeliverError(result.error),
-          message: result.error,
-        };
-      }
-      return ok(undefined);
+      const deliverOnce = async (): Promise<HostCommandResult<void>> => {
+        const result = await getOrchestrator().deliver(taskId, agentId, text, origin, assignment);
+        if (!result.ok) {
+          return {
+            ok: false,
+            code: mapDeliverError(result.error),
+            message: result.error,
+          };
+        }
+        return ok(undefined);
+      };
+      // A first-turn id is accepted at most once: a cloud that crashed before
+      // recording its ack redelivers the same id and is acknowledged here.
+      return firstTurnId
+        ? await deliverFirstTurnOnce(taskId, firstTurnId, deliverOnce, () => ok(undefined))
+        : await deliverOnce();
     } catch (err) {
       return failFromUnknown(err);
     }
   },
 
-  async previewEnsure(ctx, taskId, name, containerPort) {
+  async previewEnsure(ctx, taskId, name, containerPort, upstream) {
     logCommand(ctx, "previewEnsure", taskId, name);
+    const settings = parsePreviewUpstream(upstream);
+    if (!settings || !tunnelPreviewUpstream({ target: "preview", containerPort, ...settings })) return { ok: false, code: HostErrorCode.Internal, message: "invalid preview upstream settings" };
+    const configured = hasPreviewUpstream(settings);
+    // Machine/Apple routes need no published local port or TCP sidecar.
+    // Their tunnel still applies the same Host/TLS layer after route proof.
+    const provider = getHostTask(taskId)?.environmentProvider;
+    if (configured && (isEnvironmentTransportProvider(provider) || provider === "apple-container")) return ok({ hostPort: null });
     const runtimeFailure = runtimeUnavailable();
     if (runtimeFailure) return runtimeFailure;
     const orchestrator = getOrchestrator();
@@ -2109,7 +2125,7 @@ export const hostCommands: HostCommands = {
         // Task-up published port (preview enabled at launch) wins, but use the
         // mapping Docker just proved rather than the persisted hostPort.
         if (declared) {
-          return ok({ hostPort: appProof.published?.port ?? null });
+          return ok({ hostPort: configured ? null : appProof.published?.port ?? null });
         }
         // Else start (or find) the node-proxy sidecar NOW — the same one the
         // tunnel lazy-starts on first access — and hand back its host port.
@@ -2127,7 +2143,9 @@ export const hostCommands: HostCommands = {
           );
           if (unavailable) return unavailable;
         }
-        return ok({ hostPort });
+        // The raw published port cannot translate Host/TLS. Only the cloud
+        // preview URL applies those settings; don't offer a broken local URL.
+        return ok({ hostPort: configured ? null : hostPort });
       } catch (err) {
         return failFromUnknown(err);
       }

package/src/main.ts

@@ -1,5 +1,8 @@
 #!/usr/bin/env tsx
 import { stationAgentCliAdvertisable } from "../lib/agent-cli";
+import { PREVIEW_UPSTREAM_PROTOCOL_FEATURE, parsePreviewUpstream, tunnelPreviewUpstream } from "./preview-upstream";
+import { preparePreviewUpstream, previewRequestHeaders, isPreviewConnectFailure } from "../lib/preview-upstream";
+import { describeClose, suspendedFor } from "./bridge-diagnostics";
 import { internalHostGatewayAdvertisable } from "../lib/custom-connection-launch";
 import "./load-env";
 import { discoverCustomConnection, saveCustomConnection, saveCustomConnectionManual } from "../lib/custom-connection-capture";
@@ -335,6 +338,7 @@ import {
   MCP_GATEWAY_HEALTH_PROTOCOL_FEATURE,
   SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE,
   ASSIGNMENT_EVIDENCE_PROTOCOL_FEATURE,
+  FIRST_TURN_DEDUP_PROTOCOL_FEATURE,
   LEAD_EVIDENCE_PROTOCOL_FEATURE,
   TRANSCRIPT_TARGETS_PROTOCOL_FEATURE,
   type CloudToHost,
@@ -1551,8 +1555,10 @@ function buildCapabilities(): HostCapabilities {
     internalConnections: isOwnedInternalConnectionRuntime(internalRuntimeProvider()),
     ...(diskSnapshot ? { disk: diskSnapshot } : {}),
     protocolFeatures: [
+      PREVIEW_UPSTREAM_PROTOCOL_FEATURE,
       "host-workspace-file-read-v1",
       ASSIGNMENT_EVIDENCE_PROTOCOL_FEATURE,
+      FIRST_TURN_DEDUP_PROTOCOL_FEATURE,
   LEAD_EVIDENCE_PROTOCOL_FEATURE,
       TRANSCRIPT_TARGETS_PROTOCOL_FEATURE,
       EVENT_REPLAY_PROTOCOL_FEATURE,
@@ -3096,8 +3102,18 @@ async function connect(): Promise<void> {
       }
     }, PING_INTERVAL_MS);
 
+    let lastTick = Date.now();
     deadTimer = setInterval(() => {
-      if (Date.now() - lastTraffic > DEAD_AFTER_MS) {
+      const now = Date.now();
+      const suspended = suspendedFor(lastTick, now, 5_000);
+      lastTick = now;
+      if (suspended !== null) {
+        console.warn(
+          `[host-agent] this process was suspended for ~${Math.round(suspended / 1000)}s (system sleep?); ` +
+            "the cloud drops a connection that is silent for 45s",
+        );
+      }
+      if (now - lastTraffic > DEAD_AFTER_MS) {
         console.warn("[host-agent] bridge heartbeat timed out");
         socket.close(4000, "heartbeat timeout");
       }
@@ -3970,7 +3986,7 @@ async function connect(): Promise<void> {
     const delay = reconnectDelay();
     markReconnecting(text || `disconnected${ready ? "" : " before auth"}`);
     console.warn(
-      `[host-agent] disconnected${ready ? "" : " before auth"}; reconnecting in ${Math.round(delay)}ms`,
+      `[host-agent] disconnected${ready ? "" : " before auth"} (${describeClose(code, text)}); reconnecting in ${Math.round(delay)}ms`,
     );
     addHostBreadcrumb("bridge", "disconnected", {
       code,
@@ -4051,10 +4067,16 @@ async function handleTunnelOpen(
   wsSocket: WebSocket,
   frame: Extract<CloudToHost, { kind: "tunnel.open" }>,
 ): Promise<void> {
-  let target: UpstreamAddr | null;
+  let target: UpstreamAddr | null = null;
   try {
+    const settings = tunnelPreviewUpstream(frame);
+    if (!settings) throw new Error("invalid preview upstream settings");
+    frame = { ...frame, reqLine: { ...frame.reqLine, headers: previewRequestHeaders(frame.reqLine.headers, settings) } };
     target = await resolveTunnelTarget(frame);
+    if (target) target = await preparePreviewUpstream(target, settings);
   } catch (error) {
+    if (target) invalidatePreviewSidecar(target.port);
+    if (isPreviewConnectFailure(error)) invalidateMachineTunnelRoute(frame.taskId);
     // 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
@@ -4101,12 +4123,13 @@ function handleHttpTunnelOpen(
   target: UpstreamAddr,
 ): void {
   let acked = false;
+  let connected = Boolean(target.socket);
   const requestOptions = {
     host: target.host,
     port: target.port,
     method: frame.reqLine.method,
     path: frame.reqLine.url,
-    headers: requestHeaders(frame.reqLine.headers),
+    headers: requestHeaders(frame.reqLine.headers, frame.upstreamHost),
     // 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! } : {}),
@@ -4139,6 +4162,11 @@ function handleHttpTunnelOpen(
     },
   );
 
+  upstream.once("socket", (socket: Socket) => {
+    if (!socket.connecting) connected = true;
+    else socket.once("connect", () => { connected = true; });
+  });
+
   // 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`
@@ -4162,7 +4190,7 @@ function handleHttpTunnelOpen(
     invalidatePreviewSidecar(target.port);
     // ADR-121: a memoised machine address that no longer answers is stale —
     // a refused dial and a connect timeout (tunnel-dial.ts) both land here.
-    invalidateMachineTunnelRoute(frame.taskId);
+    if (!connected) invalidateMachineTunnelRoute(frame.taskId);
     if (!acked) {
       send(wsSocket, {
         kind: "tunnel.ack",
@@ -4194,10 +4222,12 @@ function handleRawTunnelOpen(
   const upstream = target.socket ?? new Socket();
 
   let acked = false;
+  let connected = Boolean(target.socket);
   let responseBuffer = Buffer.alloc(0);
 
   if (!target.socket) {
     upstream.on("connect", () => {
+      connected = true;
       upstream.write(serializeRequest(frame.reqLine));
     });
   }
@@ -4230,7 +4260,7 @@ function handleRawTunnelOpen(
     // the next request recreates it (no-op for published / container-IP targets).
     invalidatePreviewSidecar(target.port);
     // ADR-121: a memoised machine address that no longer answers is stale.
-    invalidateMachineTunnelRoute(frame.taskId);
+    if (!connected) invalidateMachineTunnelRoute(frame.taskId);
     if (!acked) {
       send(wsSocket, {
         kind: "tunnel.ack",
@@ -4492,13 +4522,13 @@ function serializeRequest(reqLine: {
   return Buffer.from(`${lines.join("\r\n")}\r\n\r\n`, "latin1");
 }
 
-function requestHeaders(headers: [string, string][]): OutgoingHttpHeaders {
+function requestHeaders(headers: [string, string][], upstreamHost?: string): OutgoingHttpHeaders {
   const out: OutgoingHttpHeaders = {};
   for (const [name, value] of headers) {
     const lower = name.toLowerCase();
     if (isHopByHopHeader(lower)) continue;
     if (lower === "host") {
-      out.host = "127.0.0.1";
+      out.host = upstreamHost?.toLowerCase() ?? "127.0.0.1";
       continue;
     }
 
@@ -4639,8 +4669,9 @@ async function dispatchCommand(
         expectString(args, 0),
         expectString(args, 1),
         expectString(args, 2),
-        args[3] as DeliveryOrigin | undefined,
-        args[4] as AssignmentDelivery | undefined,
+        typeof args[3] === "string" ? (args[3] as DeliveryOrigin) : undefined,
+        (args[4] ?? undefined) as AssignmentDelivery | undefined,
+        typeof args[5] === "string" && args[5] ? args[5] : undefined,
       );
     case "channelResolvePermission":
       return hostCommands.channelResolvePermission(
@@ -4695,11 +4726,13 @@ async function dispatchCommand(
         parseTranscriptTargets(args[3]),
       );
     case "previewEnsure":
+      if (parsePreviewUpstream(args[3]) === null) throw new Error("invalid preview upstream settings");
       return hostCommands.previewEnsure(
         ctx,
         expectString(args, 0),
         expectString(args, 1),
         expectNumberArg(args, 2),
+        parsePreviewUpstream(args[3])!,
       );
     case "hostUpdate":
       return hostCommands.hostUpdate(ctx, typeof args[0] === "string" ? args[0] : "");
@@ -5000,6 +5033,8 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
     isReqLine(frame.reqLine) &&
     typeof frame.upgrade === "boolean"
   ) {
+    const upstream = tunnelPreviewUpstream(frame as Extract<CloudToHost, { kind: "tunnel.open" }>);
+    if (!upstream) return null;
     return {
       kind: "tunnel.open",
       tunnelId: frame.tunnelId,
@@ -5010,6 +5045,7 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
       // node-proxy sidecar (NOT the unreachable bridge IP — see resolveTunnelTarget).
       containerPort:
         typeof frame.containerPort === "number" ? frame.containerPort : undefined,
+      ...upstream,
       reqLine: frame.reqLine,
       upgrade: frame.upgrade,
     };