@moondeck/station 1.0.1 → 1.0.2

package/images/standard/Dockerfile

@@ -51,6 +51,7 @@ ENV DEBIAN_FRONTEND=noninteractive
 RUN apt-get update \
  && apt-get install -y --no-install-recommends \
       build-essential \
+      avahi-utils \
       ca-certificates \
       curl \
       direnv \
@@ -71,6 +72,7 @@ RUN apt-get update \
       openssh-client \
       pkg-config \
       procps \
+      python3-minimal \
       ripgrep \
       tk-dev \
       tmux \
@@ -89,7 +91,7 @@ RUN apt-get update \
 # uai-playwright volume (downloaded once per host); these are its deps.
 RUN apt-get update \
  && apt-get install -y --no-install-recommends \
-      libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
+      libnss3 libnss3-tools libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
       libxkbcommon0 libatspi2.0-0 libxcomposite1 libxdamage1 libxfixes3 \
       libxrandr2 libgbm1 libasound2 libpango-1.0-0 libcairo2 \
       fonts-liberation fonts-unifont \
@@ -119,7 +121,9 @@ RUN curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/b
 # ---------------------------------------------------------------------------
 
 RUN groupadd --gid 1000 node \
- && useradd --uid 1000 --gid 1000 --create-home --home-dir /home/node --shell /bin/bash node
+ && useradd --uid 1000 --gid 1000 --create-home --home-dir /home/node --shell /bin/bash node \
+ && install -d -o node -g node -m 0755 /home/node/.local \
+ && install -d -o node -g node -m 0700 /home/node/.local/state
 
 # ---------------------------------------------------------------------------
 # 3. asdf.

package/images/standard/container/uai-create-node-data

@@ -0,0 +1,6 @@
+#!/bin/sh
+# Run only as node. Only allowlisted legacy root-owned children can be repaired separately.
+umask 077
+for path in /home/node/.local /home/node/.local/share /home/node/.local/share/opencode /home/node/.local/state; do
+  /bin/mkdir -p -m 0700 -- "$path" || printf 'node data setup: could not create %s; checking existing directory metadata\n' "$path" >&2
+done

package/images/standard/container/uai-repair-node-data.py

@@ -0,0 +1,93 @@
+# Root only: never create directories or follow a task-controlled symlink.
+import errno
+import os
+import pwd
+import stat
+import sys
+
+flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC
+node = pwd.getpwnam("node")
+
+def repair(parent, name, display, mode):
+    try:
+        fd = os.open(name, flags, dir_fd=parent)
+    except OSError as error:
+        if error.errno in (errno.ELOOP, errno.ENOTDIR, errno.ENOENT):
+            print("node data repair: skipped " + display + " (missing, symlink or not a directory)", file=sys.stderr)
+            return None
+        raise
+    try:
+        current = os.fstat(fd)
+        if current.st_uid != node.pw_uid:
+            owner = os.fstat(parent)
+            # Node already controls entries in this parent. Transfer only
+            # these legacy application directories, never their contents.
+            legacy = (
+                current.st_uid == 0
+                and owner.st_uid == node.pw_uid
+                and current.st_dev == owner.st_dev
+                and display in (
+                    "/home/node/.local/state",
+                    "/home/node/.local/share",
+                    "/home/node/.local/share/opencode",
+                )
+            )
+            if not legacy:
+                print("node data repair: skipped " + display + " (directory ownership or filesystem is not eligible; operator inspection required)", file=sys.stderr)
+                os.close(fd)
+                return None
+        os.fchown(fd, node.pw_uid, node.pw_gid)
+        os.fchmod(fd, mode)
+    except BaseException:
+        os.close(fd)
+        raise
+    return fd
+
+fds = []
+try:
+    root = os.open("/", flags)
+    fds.append(root)
+    # Pin the root-owned home chain too; no absolute-path traversal below it.
+    parent = root
+    for component in ("home", "node"):
+        try:
+            parent = os.open(component, flags, dir_fd=parent)
+        except OSError as error:
+            if error.errno not in (errno.ELOOP, errno.ENOTDIR, errno.ENOENT):
+                raise
+            print("node data repair: skipped home anchor (missing or redirected)", file=sys.stderr)
+            sys.exit(0)
+        fds.append(parent)
+    local = repair(parent, ".local", "/home/node/.local", 0o755)
+    if local is not None:
+        fds.append(local)
+        share = repair(local, "share", "/home/node/.local/share", 0o755)
+        if share is not None:
+            fds.append(share)
+            opencode = repair(share, "opencode", "/home/node/.local/share/opencode", 0o755)
+            if opencode is not None:
+                fds.append(opencode)
+                # docker cp creates root-owned credential files. Repair only
+                # these regular files through the pinned directory, never -R.
+                for name in ("auth.json", "config.json"):
+                    try:
+                        fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | os.O_CLOEXEC, dir_fd=opencode)
+                    except OSError as error:
+                        if error.errno in (errno.ELOOP, errno.ENOTDIR, errno.ENOENT, errno.ENXIO):
+                            continue
+                        raise
+                    try:
+                        current = os.fstat(fd)
+                        if stat.S_ISREG(current.st_mode) and current.st_nlink == 1 and current.st_uid in (0, node.pw_uid):
+                            os.fchown(fd, node.pw_uid, node.pw_gid)
+                            os.fchmod(fd, 0o600)
+                        else:
+                            print("node data repair: skipped OpenCode " + name + " (not a single-link root/node regular file)", file=sys.stderr)
+                    finally:
+                        os.close(fd)
+        state = repair(local, "state", "/home/node/.local/state", 0o700)
+        if state is not None:
+            fds.append(state)
+finally:
+    for fd in reversed(fds):
+        os.close(fd)

package/lib/agent-cli.ts

@@ -1272,12 +1272,30 @@ async function main() {
       out(action + " #" + t.shortId + ": " + t.text);
       break;
     }
-    case "preview add": {
+    case "preview add":
+    case "preview update": {
       const name = pos[0] || flags.name;
       const port = Number(pos[1] || flags.port);
-      if (!name || !Number.isInteger(port)) { console.error("moondeck: preview add <name> <containerPort>"); process.exit(1); }
-      const r = await api("POST", "/api/agent/previews", { name, containerPort: port });
-      out("preview '" + r.name + "' on port " + r.containerPort + " — turn it on with: moondeck preview enable " + r.name);
+      if (!name || !Number.isInteger(port) || port < 1 || port > 65535) { console.error("moondeck: preview " + action + " <name> <containerPort>"); process.exit(1); }
+      if (Object.keys(flags).some(k => !["name", "port", "upstream-host", "https"].includes(k)) || (flags.https !== undefined && flags.https !== "true") || (flags["upstream-host"] !== undefined && !flagValue(flags["upstream-host"]))) {
+        console.error("moondeck: preview " + action + " <name> <port> [--upstream-host <hostname>] [--https]"); process.exit(1);
+      }
+      const upstream = {
+        ...(flags["upstream-host"] !== undefined ? { upstreamHost: flags["upstream-host"] } : {}),
+        ...(flags.https === "true" ? { upstreamTls: true } : {}),
+      };
+      const r = action === "add"
+        ? await api("POST", "/api/agent/previews", { name, containerPort: port, ...upstream })
+        : await api("PATCH", "/api/agent/previews/" + encodeURIComponent(name), { containerPort: port, ...upstream });
+      out("preview '" + r.name + "' on port " + r.containerPort + (action === "add" ? " — turn it on with: moondeck preview enable " + r.name : " — updated"));
+      if (upstream.upstreamHost || upstream.upstreamTls) console.error("Portless users: outside self tasks, start with portless proxy start --lan (or PORTLESS_LAN=1; enables mDNS). Check for LAN mode disabled; if printed, use an updated Moondeck image with avahi-utils, or ask the operator to install it and fix any reported LAN-IP problem, then restart. Use its printed LAN hostname (usually mta.local) and proxy port: HTTPS 443, HTTP 80, or your explicit -p port (e.g. 1355).");
+      break;
+    }
+    case "preview remove": {
+      const name = pos[0] || flags.name;
+      if (!name) { console.error("moondeck: preview remove <name>"); process.exit(1); }
+      await api("DELETE", "/api/agent/previews/" + encodeURIComponent(name));
+      out("removed preview '" + name + "'");
       break;
     }
     case "preview enable":
@@ -1465,7 +1483,10 @@ async function main() {
         "  moondeck review report --pr <number|URL> --head <full-sha> --must <n> --should <n> --nits <n> --verdict approve|changes [--summary text] [--assignment id] [--revision n]",
         "  moondeck crew outcome @agent accepted|reworked|failed [--note text] [--assignment id] [--revision n]",
         "      Review reports require an authorized exact-head assignment. Outcomes are Secretary assessments, never human acceptance.",
-        "  moondeck preview add <name> <containerPort>",
+        "  moondeck preview add <name> <containerPort> [--upstream-host <h>] [--https]",
+        "  moondeck preview update <name> <containerPort> [--upstream-host <h>] [--https]",
+        "  moondeck preview remove <name>",
+        "    Portless outside self: portless proxy start --lan or PORTLESS_LAN=1 (mDNS); use printed *.local Host and proxy port 443/80, or explicit -p 1355. Check for LAN mode disabled; update the image/install avahi-utils and resolve the reported LAN issue, then restart.",
         "  moondeck preview enable|disable <name>      (turn it on; prints its URL)",
         "  moondeck preview public|private <name>      (public: a link anyone can open)",
         "  moondeck project list | show <id|slug>",

package/lib/browser-testing.ts

@@ -1472,6 +1472,9 @@ export async function setupBrowserTesting(
 
     const rootWorkerEnv = {
       ...authorityEnv,
+      // HOME remains node's for asdf resolution; root-run tools must keep
+      // their XDG state out of the task user's home.
+      XDG_STATE_HOME: "/root/.local/state",
       NPM_CONFIG_CACHE: "/tmp/uai-root-npm-cache",
       npm_config_cache: "/tmp/uai-root-npm-cache",
       NPM_CONFIG_LOGS_DIR: "/tmp/uai-root-npm-cache/_logs",
@@ -1505,6 +1508,8 @@ export async function setupBrowserTesting(
           // both cases aligned so npm's case-insensitive config lookup cannot
           // fall back to node's private cache or logs directory.
           "-e",
+          "XDG_STATE_HOME=/root/.local/state",
+          "-e",
           "NPM_CONFIG_CACHE=/tmp/uai-root-npm-cache",
           "-e",
           "npm_config_cache=/tmp/uai-root-npm-cache",

package/lib/machine-provider-local.ts

@@ -197,6 +197,8 @@ export function createLocalMachineProvider(
       const args = [
         "run",
         "-d",
+        "--sysctl",
+        "net.ipv4.ip_unprivileged_port_start=80",
         "--name",
         name,
         "--label",

package/lib/node-state.ts

@@ -0,0 +1,17 @@
+import { readFileSync } from "node:fs";
+
+// Task-up.sh loads these same packaged assets: no inline repair copies.
+export const NODE_STATE_SETUP_SCRIPT = readFileSync(new URL("../images/standard/container/uai-repair-node-data.py", import.meta.url), "utf8");
+export const NODE_DATA_CREATE_SCRIPT = readFileSync(new URL("../images/standard/container/uai-create-node-data", import.meta.url), "utf8");
+
+/** Normalize node-owned parents, create as node, then normalize new metadata. */
+export async function prepareNodeData(exec: (user: "root" | "node", argv: [string, ...string[]]) => Promise<number | null>): Promise<boolean> {
+  for (const [user, argv] of [
+    ["root", ["/usr/bin/python3", "-I", "-c", NODE_STATE_SETUP_SCRIPT]],
+    ["node", ["/bin/sh", "-c", NODE_DATA_CREATE_SCRIPT]],
+    ["root", ["/usr/bin/python3", "-I", "-c", NODE_STATE_SETUP_SCRIPT]],
+  ] as const) {
+    if (await exec(user, [...argv]) !== 0) return false;
+  }
+  return true;
+}

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.1",
+  "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/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,
@@ -2072,8 +2073,15 @@ export const hostCommands: HostCommands = {
     }
   },
 
-  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();
@@ -2117,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.
@@ -2135,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,7 @@
 #!/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";
@@ -1553,6 +1555,7 @@ 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,
@@ -4064,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
@@ -4114,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! } : {}),
@@ -4152,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`
@@ -4175,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",
@@ -4207,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));
     });
   }
@@ -4243,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",
@@ -4505,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;
     }
 
@@ -4709,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] : "");
@@ -5014,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,
@@ -5024,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,
     };

package/src/preview-upstream.ts

@@ -0,0 +1,41 @@
+/** Optional preview behavior, negotiated per live Station connection. */
+export const PREVIEW_UPSTREAM_PROTOCOL_FEATURE = "preview-upstream-v1";
+
+export interface PreviewUpstream {
+  upstreamHost?: string;
+  upstreamTls?: boolean;
+}
+
+/** DNS spelling only. URL parsing here detects numeric/hex/octal IP aliases;
+ * it never resolves a name. No URL, authority, port or header syntax is allowed. */
+export function isPreviewUpstreamHost(value: unknown): value is string {
+  if (typeof value !== "string" || value.length < 1 || value.length > 253) return false;
+  if (!value.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(label))) return false;
+  try {
+    return !/^\d+\.\d+\.\d+\.\d+$/.test(new URL(`http://${value}`).hostname);
+  } catch { return false; }
+}
+
+export function hasPreviewUpstream(value: PreviewUpstream): boolean {
+  return value.upstreamHost !== undefined || value.upstreamTls === true;
+}
+
+/** Read only these fields from a frame or declaration; reject malformed values. */
+export function parsePreviewUpstream(value: unknown): PreviewUpstream | null {
+  if (value === undefined) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const { upstreamHost, upstreamTls } = value as Record<string, unknown>;
+  if (upstreamHost !== undefined && !isPreviewUpstreamHost(upstreamHost)) return null;
+  if (upstreamTls !== undefined && typeof upstreamTls !== "boolean") return null;
+  return {
+    ...(typeof upstreamHost === "string" ? { upstreamHost: upstreamHost.toLowerCase() } : {}),
+    ...(typeof upstreamTls === "boolean" ? { upstreamTls } : {}),
+  };
+}
+
+export function tunnelPreviewUpstream(frame: { target: string; containerPort?: number } & PreviewUpstream): PreviewUpstream | null {
+  const settings = parsePreviewUpstream(frame);
+  if (!settings) return null;
+  if (hasPreviewUpstream(settings) && (frame.target !== "preview" || !Number.isInteger(frame.containerPort) || frame.containerPort! < 1 || frame.containerPort! > 65535)) return null;
+  return settings;
+}

package/src/protocol.ts

@@ -1,4 +1,6 @@
 export * from "./custom-connections";
+export * from "./preview-upstream";
+import type { PreviewUpstream } from "./preview-upstream";
 import type { AccountBinding, EngineConnectCustomDiscoverFrame, EngineConnectCustomDiscoveredFrame, EngineConnectCustomSaveFrame, EngineConnectCustomManualSaveFrame, EngineConnectCustomSavedFrame, OpenRouterBudgetFrame } from "./custom-connections";
 import type { TaskSecretApplied, TaskSecretStagingPut, TaskSecretStagingAck } from "./task-secrets";
 import { isNeverProxiedDomain } from "./never-proxied-domains";
@@ -4835,6 +4837,7 @@ export interface HostCommands {
     taskId: string,
     name: string,
     containerPort: number,
+    upstream?: PreviewUpstream,
   ): Promise<HostCommandResult<{ hostPort: number | null }>>;
   /** ADR-116: remove a labeled engine account by id. Refuses `default:*`
    * exactly like the local API; re-advertises capabilities on success. */
@@ -4997,6 +5000,8 @@ export type CloudToHost =
       // proxies to <container-ip>:<containerPort> over the Docker network.
       // Absent for the editor target (which uses the published codeServerPort).
       containerPort?: number;
+      upstreamHost?: string;
+      upstreamTls?: boolean;
       reqLine: TunnelReqLine;
       upgrade: boolean;
     }