@runuai/host 0.2.6 → 0.3.0

package/lib/preview-sidecar.ts

@@ -0,0 +1,157 @@
+/**
+ * ADR-043: per-(task, preview) node-proxy sidecar for ad-hoc preview ports.
+ *
+ * Ad-hoc preview ports aren't Docker-published, and the app container's bridge
+ * IP isn't host-routable on macOS/OrbStack (EHOSTUNREACH). So proxy through a
+ * tiny sidecar: a container on the task's compose network that PUBLISHES a
+ * `127.0.0.1` host port (reachable on every backend) and forwards to
+ * `<app-container>:<containerPort>`. The sidecar runs the task's OWN image
+ * (always local — no registry pull) under `node` with a ~5-line `net` TCP proxy;
+ * node streams give backpressure + handle WebSockets (Metro/HMR).
+ *
+ * Hot path is cache-only (NO docker call per request — that thrashed under a
+ * browser's concurrent requests). The cached port is trusted until a tunnel
+ * connect fails, which invalidates it (mirrors the container-IP cache). Declared
+ * ports keep their published-port path; only ad-hoc ports use a sidecar.
+ */
+import { dockerCli } from "./docker-exec";
+
+/** Port the proxy listens on inside the sidecar (published to a random host port). */
+const INNER_PORT = 9000;
+const LABEL = "com.runuai.preview-sidecar.task";
+
+/** (taskId,name,containerPort) -> published 127.0.0.1 host port of a live sidecar. */
+const cache = new Map<string, number>();
+/** In-flight creates, so concurrent requests for the same key share one sidecar. */
+const inflight = new Map<string, Promise<number | null>>();
+
+function cacheKey(taskId: string, name: string, containerPort: number): string {
+  return `${taskId} ${name} ${containerPort}`;
+}
+
+function sidecarName(taskId: string, name: string): string {
+  return `uai-preview-${taskId}-${name}`;
+}
+
+function proxyScript(appContainer: string, containerPort: number): string {
+  // Bidirectional TCP pipe: 0.0.0.0:INNER_PORT <-> appContainer:containerPort.
+  return (
+    `const net=require('net');` +
+    `net.createServer(c=>{` +
+    `const u=net.connect(${containerPort},${JSON.stringify(appContainer)});` +
+    `c.on('error',()=>u.destroy());u.on('error',()=>c.destroy());` +
+    `c.pipe(u);u.pipe(c);` +
+    `}).listen(${INNER_PORT},'0.0.0.0');`
+  );
+}
+
+async function imageOf(appContainer: string): Promise<string | null> {
+  const r = await dockerCli(
+    ["inspect", "-f", "{{.Config.Image}}", appContainer],
+    { timeoutMs: 5_000 },
+  );
+  return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : null;
+}
+
+/** `docker port <name>` -> the published 127.0.0.1 host port, or null. */
+async function publishedPort(name: string): Promise<number | null> {
+  const r = await dockerCli(["port", name, String(INNER_PORT)], {
+    timeoutMs: 5_000,
+  });
+  const m = r.stdout.match(/127\.0\.0\.1:(\d+)/);
+  return r.status === 0 && m ? Number(m[1]) : null;
+}
+
+async function createSidecar(args: {
+  taskId: string;
+  composeProject: string;
+  name: string;
+  containerPort: number;
+}): Promise<number | null> {
+  const name = sidecarName(args.taskId, args.name);
+  const appContainer = `${args.composeProject}-app-1`;
+
+  // Reuse a still-running sidecar from a previous host process (--rm keeps it up
+  // across a host restart; the in-memory cache was cleared). `docker port` is an
+  // exact-name lookup, so no name-filter regex pitfalls.
+  const existing = await publishedPort(name);
+  if (existing !== null) return existing;
+
+  const image = await imageOf(appContainer);
+  if (!image) return null;
+
+  await dockerCli(["rm", "-f", name], { timeoutMs: 10_000 });
+  const run = await dockerCli(
+    [
+      "run", "-d", "--rm",
+      "--name", name,
+      "--network", `${args.composeProject}_default`,
+      "--label", `${LABEL}=${args.taskId}`,
+      "-p", `127.0.0.1::${INNER_PORT}`,
+      "--entrypoint", "node",
+      image,
+      "-e", proxyScript(appContainer, args.containerPort),
+    ],
+    { timeoutMs: 20_000 },
+  );
+  if (run.status !== 0) return null;
+
+  const hostPort = await publishedPort(name);
+  if (hostPort === null) {
+    await dockerCli(["rm", "-f", name], { timeoutMs: 10_000 });
+    return null;
+  }
+  return hostPort;
+}
+
+/**
+ * Ensure a sidecar is proxying `<app>:<containerPort>` for (taskId, name);
+ * returns the `127.0.0.1` host port it publishes, or null on failure. Cache-only
+ * on the hot path; a cache miss creates the sidecar (deduped across concurrent
+ * callers).
+ */
+export async function ensurePreviewSidecar(args: {
+  taskId: string;
+  composeProject: string;
+  name: string;
+  containerPort: number;
+}): Promise<number | null> {
+  const key = cacheKey(args.taskId, args.name, args.containerPort);
+  const cached = cache.get(key);
+  if (cached !== undefined) return cached;
+
+  let pending = inflight.get(key);
+  if (!pending) {
+    pending = createSidecar(args)
+      .then((port) => {
+        if (port !== null) cache.set(key, port);
+        return port;
+      })
+      .finally(() => inflight.delete(key));
+    inflight.set(key, pending);
+  }
+  return pending;
+}
+
+/** Drop any cached sidecar entry on `hostPort` (a tunnel connect failed). No-op
+ *  for published-declared / container-IP targets, which aren't in this cache. */
+export function invalidatePreviewSidecar(hostPort: number): void {
+  for (const [key, port] of cache) {
+    if (port === hostPort) cache.delete(key);
+  }
+}
+
+/** Stop + remove all preview sidecars for a task (called on task-down). */
+export async function stopPreviewSidecars(taskId: string): Promise<void> {
+  for (const key of [...cache.keys()]) {
+    if (key.startsWith(`${taskId} `)) cache.delete(key);
+  }
+  const r = await dockerCli(
+    ["ps", "-aq", "--filter", `label=${LABEL}=${taskId}`],
+    { timeoutMs: 5_000 },
+  );
+  if (r.status !== 0) return;
+  for (const id of r.stdout.split("\n").map((s) => s.trim()).filter(Boolean)) {
+    await dockerCli(["rm", "-f", id], { timeoutMs: 10_000 });
+  }
+}

package/lib/task-diff.ts

@@ -4,9 +4,20 @@ import { join } from "node:path";
 
 import type { TaskDiffInput, TaskDiffResult } from "../src/protocol";
 import { taskWorkspaceDir } from "./env";
-import { parseGitDiff, runGitDiff, runGitDiffInContainer } from "./git-diff";
+import {
+  parseGitDiff,
+  runGitDiff,
+  runGitDiffInContainer,
+  runGitDiffUntracked,
+  runGitDiffUntrackedInContainer,
+} from "./git-diff";
 import { getHostTask } from "./runtime-state";
 
+// Cap how many untracked files we render as new-file patches. Each is a
+// separate (in-container) git spawn, so a pathological untracked dir that
+// slips past .gitignore shouldn't turn the diff into thousands of execs.
+const MAX_UNTRACKED = 200;
+
 export async function buildTaskDiff(
   input: TaskDiffInput,
 ): Promise<TaskDiffResult> {
@@ -23,15 +34,40 @@ export async function buildTaskDiff(
     const containerCwd = `/workspace/${project.slug}`;
     if (!containerName && !existsSync(cwd)) continue;
 
-    // Base branch is derived from the worktree's upstream (the worktree was
-    // created off `origin/<defaultBranch>` at task-up; ADR-022 derives and
-    // persists the default branch on the worktree, not the project record).
+    // Base branch is the remote's default branch (where task branches are cut
+    // from at task-up) — NOT the worktree's @{upstream}, which flips to
+    // origin/<task-branch> once the branch is pushed and would then hide all
+    // committed work (see resolveBase).
     const base = resolveBase(containerName, cwd, containerCwd, project.slug);
-    const range = `${base}..HEAD`;
+    // Diff the whole branch against base, including UNCOMMITTED work: compare
+    // the merge-base (where the branch diverged) to the WORKING TREE, not HEAD.
+    // The merge-base keeps base's own later commits from showing up reversed if
+    // it advanced; falling back to `base` itself if merge-base can't resolve.
+    const mergeBase =
+      runGitText(containerName, cwd, containerCwd, [
+        "merge-base",
+        base,
+        "HEAD",
+      ]) ?? base;
     try {
-      const text = containerName
-        ? await runGitDiffInContainer(containerName, containerCwd, range)
-        : await runGitDiff(cwd, range);
+      // Tracked changes (committed + staged + unstaged): a commit-ish vs the
+      // working tree, so omitting `..HEAD` is the point.
+      let text = containerName
+        ? await runGitDiffInContainer(containerName, containerCwd, mergeBase)
+        : await runGitDiff(cwd, mergeBase);
+
+      // Untracked files: `git diff <commit>` skips them, so list (honouring
+      // .gitignore) and append each as a /dev/null new-file patch.
+      const untracked = listUntracked(containerName, cwd, containerCwd);
+      for (const file of untracked) {
+        const patch = containerName
+          ? await runGitDiffUntrackedInContainer(containerName, containerCwd, file)
+          : await runGitDiffUntracked(cwd, file);
+        if (patch.trim().length === 0) continue;
+        if (text.length > 0 && !text.endsWith("\n")) text += "\n";
+        text += patch;
+      }
+
       out.push({
         id: project.id,
         name: project.slug,
@@ -55,10 +91,16 @@ export async function buildTaskDiff(
 }
 
 /**
- * Resolve the diff base for a worktree. Prefer the configured upstream
- * (`@{upstream}`); fall back to the remote's default branch
- * (`origin/HEAD`), then `origin/main`. Runs git in-container when the task
- * is live so credential behavior stays inside the sandbox (see git-diff).
+ * Resolve the diff base for a worktree: the remote's default branch
+ * (`origin/HEAD`, set at task-up via `remote set-head`), falling back to
+ * `origin/main`. Runs git in-container when the task is live so credential
+ * behavior stays inside the sandbox (see git-diff).
+ *
+ * We deliberately do NOT use the worktree's `@{upstream}`. At task-up it is
+ * `origin/<defaultBranch>`, but once the task branch is pushed (e.g. a PR is
+ * opened) its upstream flips to `origin/<task-branch>` — then
+ * `merge-base(upstream, HEAD) ≈ HEAD`, so the diff would show only uncommitted
+ * work instead of the whole branch.
  */
 function resolveBase(
   containerName: string | null,
@@ -66,14 +108,6 @@ function resolveBase(
   containerCwd: string,
   _slug: string,
 ): string {
-  const upstream = runGitText(
-    containerName,
-    hostCwd,
-    containerCwd,
-    ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"],
-  );
-  if (upstream) return upstream;
-
   const head = runGitText(
     containerName,
     hostCwd,
@@ -89,6 +123,27 @@ function stripOriginPrefix(ref: string): string {
   return ref.startsWith("origin/") ? ref.slice("origin/".length) : ref;
 }
 
+/**
+ * List untracked files in the worktree, honouring .gitignore
+ * (`--exclude-standard`), capped at {@link MAX_UNTRACKED}. Empty on error.
+ */
+function listUntracked(
+  containerName: string | null,
+  hostCwd: string,
+  containerCwd: string,
+): string[] {
+  const raw = runGitText(containerName, hostCwd, containerCwd, [
+    "ls-files",
+    "--others",
+    "--exclude-standard",
+  ]);
+  if (!raw) return [];
+  return raw
+    .split("\n")
+    .filter((line) => line.length > 0)
+    .slice(0, MAX_UNTRACKED);
+}
+
 /**
  * Run a read-only git command (host or in-container) and return trimmed
  * stdout, or null on any failure. Used for base-branch resolution where a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",

package/scripts/agent/task-up.sh

@@ -309,11 +309,11 @@ fi
   done < <(jq -c '.[]' <<<"$projects_json")
   printf '      - "%s:/opt/asdf-data"\n' "$ASDF_VOLUME"
   printf '    ports:\n'
+  # code-server (the Editor tunnel) is the only auto-published port. Preview
+  # ports are NOT published at task-up (ADR-043 Stage 2: opt-in previews) —
+  # each preview the user enables is reached lazily through a per-(task,preview)
+  # sidecar attached to the compose network, so nothing is exposed by default.
   printf '      - "127.0.0.1::8080"\n'
-  while IFS= read -r cport; do
-    [ -n "$cport" ] || continue
-    printf '      - "127.0.0.1::%s"\n' "$cport"
-  done < <(jq -r '.[].containerPort' <<<"$union_preview_ports_json")
   printf '    environment:\n'
   # Host-resident Claude auth (ADR-021). Headless `claude --print` no longer
   # uses the interactive subscription/keychain path, so it needs a token from
@@ -345,6 +345,19 @@ fi
     esac
     printf '      %s: "${%s:-}"\n' "$ekey" "$ekey"
   done < <(jq -r '.[]' <<<"$union_env_keys_json")
+  # Preview-URL env vars (ADR-025): cloud-computed PUBLIC preview URLs exposed
+  # under operator-chosen names (e.g. EXPO_PACKAGER_PROXY_URL). Non-secret, so
+  # written LITERALLY (unlike the ${KEY:-} pass-throughs above). `preview_env`
+  # is a JSON object {VAR: url} on the task row, one entry per preview port that
+  # set `urlEnv`. Emitted last so it wins over any same-named declared key.
+  preview_env_raw=$(jq -r '.[0].preview_env // "{}"' <<<"$task_json")
+  while IFS= read -r pe_entry; do
+    [ -n "$pe_entry" ] || continue
+    pe_key=$(jq -r '.key' <<<"$pe_entry")
+    pe_val=$(jq -r '.value' <<<"$pe_entry")
+    [ -n "$pe_key" ] || continue
+    printf '      %s: "%s"\n' "$pe_key" "$pe_val"
+  done < <(jq -c 'to_entries[]?' <<<"$preview_env_raw")
   printf 'volumes:\n'
   printf '  %s:\n' "$ASDF_VOLUME"
   printf '    external: true\n'
@@ -441,29 +454,12 @@ if [ -z "$code_server_port" ]; then
   log "warning: could not discover code-server port for ${app_container} (editor pane unavailable)"
 fi
 
+# ADR-043 Stage 2: preview ports are no longer published at task-up, so there is
+# nothing to discover here. `preview_ports` stays empty and every enabled preview
+# is reached through its sidecar (started lazily on first access via the cloud
+# tunnel). `union_preview_ports_json` is still surfaced to the cloud (GET task
+# lists the declared/ad-hoc names the user can turn on).
 preview_ports_runtime_json="[]"
-if [ "$(jq 'length' <<<"$union_preview_ports_json")" -gt 0 ]; then
-  preview_port_lines=""
-  while IFS= read -r preview_obj; do
-    [ -n "$preview_obj" ] || continue
-    preview_name=$(jq -r '.name' <<<"$preview_obj")
-    preview_container_port=$(jq -r '.containerPort' <<<"$preview_obj")
-    preview_host_port=$(mapped_host_port "$app_container" "$preview_container_port")
-    if [ -z "$preview_host_port" ]; then
-      log "warning: could not discover preview port ${preview_name}:${preview_container_port} for ${app_container}"
-      continue
-    fi
-    preview_port_lines="${preview_port_lines}$(jq -nc \
-      --arg name "$preview_name" \
-      --arg hp "$preview_host_port" \
-      '{name:$name,hostPort:($hp|tonumber)}')
-"
-  done < <(jq -c '.[]' <<<"$union_preview_ports_json")
-
-  if [ -n "$preview_port_lines" ]; then
-    preview_ports_runtime_json=$(printf '%s' "$preview_port_lines" | jq -s -c '.')
-  fi
-fi
 
 step "DB_UPDATE_FAILED" "mark task running"
 cs_sql="code_server_port=NULL"

package/src/main.ts

@@ -25,8 +25,10 @@ import {
 import { getHostTask } from "../lib/runtime-state";
 import { getOrchestrator } from "../lib/orchestrator";
 import {
+  connectedUserIds,
   onConnectClear,
   onConnectSet,
+  onGithubChange,
   setAuthExpiredHandler,
 } from "../lib/github-tokens";
 import {
@@ -47,6 +49,12 @@ import {
 } from "./paths";
 import { dockerMemoryBytes, startUiServer } from "./ui/server";
 import { parsePreviewPortRuntimes } from "../lib/preview-ports";
+import { dockerCli } from "../lib/docker-exec";
+import {
+  ensurePreviewSidecar,
+  invalidatePreviewSidecar,
+  stopPreviewSidecars,
+} from "../lib/preview-sidecar";
 import { newId } from "../lib/ulid";
 import {
   capabilities as agentKindCapabilities,
@@ -166,6 +174,7 @@ function buildCapabilities(): HostCapabilities {
   return {
     agentKinds: agentKindCapabilities(),
     runtimes: standardRuntimes(),
+    githubUsers: connectedUserIds(),
   };
 }
 
@@ -181,6 +190,9 @@ function sendCapabilities(): void {
 }
 
 onRegistryChange(() => sendCapabilities());
+// 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 {
   if (stopping || fatal) return;
@@ -256,7 +268,7 @@ function connect(): void {
         void handleCommand(socket, frame);
         break;
       case "tunnel.open":
-        handleTunnelOpen(socket, frame);
+        void handleTunnelOpen(socket, frame);
         break;
       case "tunnel.data":
         pendingBinaryTunnelId = frame.tunnelId;
@@ -284,7 +296,15 @@ function connect(): void {
         break;
       }
       case "gh.connect.clear":
-        onConnectClear(frame.userId);
+        // Delete-then-revoke (ADR-033) is async + best-effort; ack immediately
+        // so the UI isn't gated on the GitHub revoke round-trip. The .catch is
+        // a belt over onConnectClear's own try/catch — a fire-and-forget
+        // rejection must never crash the host.
+        void onConnectClear(frame.userId).catch((err) =>
+          console.warn(
+            `[github] connect.clear failed: ${err instanceof Error ? err.message : err}`,
+          ),
+        );
         send(socket, { kind: "gh.connect.ack", userId: frame.userId, ok: true });
         break;
       case "ssh.key.get":
@@ -403,12 +423,12 @@ async function handleCommand(
   }
 }
 
-function handleTunnelOpen(
+async function handleTunnelOpen(
   wsSocket: WebSocket,
   frame: Extract<CloudToHost, { kind: "tunnel.open" }>,
-): void {
-  const port = resolveTunnelPort(frame);
-  if (!port) {
+): Promise<void> {
+  const target = await resolveTunnelTarget(frame);
+  if (!target) {
     send(wsSocket, {
       kind: "tunnel.ack",
       tunnelId: frame.tunnelId,
@@ -420,23 +440,23 @@ function handleTunnelOpen(
   }
 
   if (!frame.upgrade) {
-    handleHttpTunnelOpen(wsSocket, frame, port);
+    handleHttpTunnelOpen(wsSocket, frame, target);
     return;
   }
 
-  handleRawTunnelOpen(wsSocket, frame, port);
+  handleRawTunnelOpen(wsSocket, frame, target);
 }
 
 function handleHttpTunnelOpen(
   wsSocket: WebSocket,
   frame: Extract<CloudToHost, { kind: "tunnel.open" }>,
-  port: number,
+  target: UpstreamAddr,
 ): void {
   let acked = false;
   const upstream = httpRequest(
     {
-      host: "127.0.0.1",
-      port,
+      host: target.host,
+      port: target.port,
       method: frame.reqLine.method,
       path: frame.reqLine.url,
       headers: requestHeaders(frame.reqLine.headers),
@@ -471,6 +491,13 @@ 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);
     if (!acked) {
       send(wsSocket, {
         kind: "tunnel.ack",
@@ -497,7 +524,7 @@ function handleHttpTunnelOpen(
 function handleRawTunnelOpen(
   wsSocket: WebSocket,
   frame: Extract<CloudToHost, { kind: "tunnel.open" }>,
-  port: number,
+  target: UpstreamAddr,
 ): void {
   const upstream = new Socket();
   tunnels.set(frame.tunnelId, upstream);
@@ -533,6 +560,10 @@ 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);
     if (!acked) {
       send(wsSocket, {
         kind: "tunnel.ack",
@@ -560,7 +591,7 @@ function handleRawTunnelOpen(
     });
   });
 
-  upstream.connect(port, "127.0.0.1");
+  upstream.connect(target.port, target.host);
 }
 
 function closeTunnel(
@@ -574,17 +605,85 @@ function closeTunnel(
   send(wsSocket, { kind: "tunnel.close", tunnelId, reason });
 }
 
-function resolveTunnelPort(
+/** Where a tunnel's bytes go: `127.0.0.1:<published>` for the editor, or a
+ *  container's `<ip>:<containerPort>` for a preview (ADR-036). */
+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);
+  }
+}
+
+async function resolveTunnelTarget(
   frame: Extract<CloudToHost, { kind: "tunnel.open" }>,
-): number | null {
+): Promise<UpstreamAddr | null> {
   const task = getHostTask(frame.taskId);
   if (!task) return null;
-  if (frame.target === "editor") return task.codeServerPort ?? null;
-  if (!frame.name) return null;
-  const preview = parsePreviewPortRuntimes(task.previewPorts).find(
-    (port) => port.name === frame.name,
-  );
-  return preview?.hostPort ?? null;
+  if (frame.target === "editor") {
+    return task.codeServerPort
+      ? { host: "127.0.0.1", port: task.codeServerPort }
+      : 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.
+  // macOS/OrbStack where the container bridge IP is NOT host-routable (ADR-043).
+  if (frame.name) {
+    const declared = parsePreviewPortRuntimes(task.previewPorts).find(
+      (port) => port.name === frame.name,
+    );
+    if (declared) return { host: "127.0.0.1", port: declared.hostPort };
+    // 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 ensurePreviewSidecar({
+        taskId: frame.taskId,
+        composeProject: task.composeProject,
+        name: frame.name,
+        containerPort: frame.containerPort,
+      });
+      if (hostPort) 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 };
+  }
+  return null;
 }
 
 function serializeRequest(reqLine: {
@@ -713,8 +812,12 @@ function dispatchCommand(
   switch (command) {
     case "taskUp":
       return hostCommands.taskUp(ctx, expectTaskLaunchInput(args, 0));
-    case "taskDown":
-      return hostCommands.taskDown(ctx, expectTaskDownInput(args, 0));
+    case "taskDown": {
+      const downInput = expectTaskDownInput(args, 0);
+      // ADR-043: tear down this task's preview sidecars. Best-effort.
+      void stopPreviewSidecars(downInput.taskId).catch(() => {});
+      return hostCommands.taskDown(ctx, downInput);
+    }
     case "taskStatus":
       return hostCommands.taskStatus(ctx, expectString(args, 0));
     case "channelEnsure":
@@ -807,6 +910,10 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
       target: frame.target,
       taskId: frame.taskId,
       name: typeof frame.name === "string" ? frame.name : undefined,
+      // ADR-043: cloud-resolved in-container port for ad-hoc previews; feeds the
+      // node-proxy sidecar (NOT the unreachable bridge IP — see resolveTunnelTarget).
+      containerPort:
+        typeof frame.containerPort === "number" ? frame.containerPort : undefined,
       reqLine: frame.reqLine,
       upgrade: frame.upgrade,
     };
@@ -830,7 +937,9 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
     typeof frame.installationId === "number" &&
     typeof frame.githubLogin === "string" &&
     (frame.targetType === "User" || frame.targetType === "Organization") &&
-    typeof frame.refreshToken === "string"
+    // Exactly one token kind: accessToken (ADR-033) or refreshToken (ADR-027).
+    (typeof frame.accessToken === "string" ||
+      typeof frame.refreshToken === "string")
   ) {
     return {
       kind: "gh.connect.set",
@@ -838,7 +947,10 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
       installationId: frame.installationId,
       githubLogin: frame.githubLogin,
       targetType: frame.targetType,
-      refreshToken: frame.refreshToken,
+      accessToken:
+        typeof frame.accessToken === "string" ? frame.accessToken : undefined,
+      refreshToken:
+        typeof frame.refreshToken === "string" ? frame.refreshToken : undefined,
       refreshTokenExpiresAt:
         typeof frame.refreshTokenExpiresAt === "number"
           ? frame.refreshTokenExpiresAt
@@ -1120,6 +1232,17 @@ function expectTaskCommandTask(value: unknown): TaskCommandTask {
       expectStringValue(id, `task.reviewerOrder[${i}]`),
     );
   }
+  if (
+    row.previewEnv &&
+    typeof row.previewEnv === "object" &&
+    !Array.isArray(row.previewEnv)
+  ) {
+    const pe: Record<string, string> = {};
+    for (const [k, v] of Object.entries(row.previewEnv as Record<string, unknown>)) {
+      if (typeof v === "string") pe[k] = v;
+    }
+    if (Object.keys(pe).length > 0) out.previewEnv = pe;
+  }
   return out;
 }