@runuai/host 0.2.8 → 0.4.0

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/lib/task-token.ts

@@ -0,0 +1,40 @@
+/**
+ * Task-token minting (ADR-048) — the host mints the token the in-container `uai`
+ * CLI uses; the cloud verifies it (lib/task-token.ts). The signing key is the
+ * TASK's ephemeral `cliSecret`, issued by the cloud at task-up (not a static
+ * shared secret). Algorithm MUST stay identical to the cloud side.
+ */
+import { createHmac } from "node:crypto";
+
+export interface TaskTokenPayload {
+  taskId: string;
+  userId: string;
+  permissions: string[];
+  agentId?: string;
+}
+
+const PREFIX = "uai_";
+
+function b64url(buf: Buffer): string {
+  return buf
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+export function signTaskToken(payload: TaskTokenPayload, secret: string): string {
+  const body = b64url(
+    Buffer.from(
+      JSON.stringify({
+        t: payload.taskId,
+        u: payload.userId,
+        p: payload.permissions,
+        ...(payload.agentId ? { a: payload.agentId } : {}),
+        iat: Math.floor(Date.now() / 1000),
+      }),
+    ),
+  );
+  const sig = b64url(createHmac("sha256", secret).update(body).digest());
+  return `${PREFIX}${body}.${sig}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.2.8",
+  "version": "0.4.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/index.ts

@@ -1,6 +1,7 @@
 import { agent, AgentError } from "../lib/agent";
 import { cloneRepo } from "../lib/repo-clone";
 import { getOrchestrator } from "../lib/orchestrator";
+import { storeTaskCliSecret } from "../lib/agent-cli";
 import { setupTaskGithub, clearRefresh } from "../lib/github-tokens";
 import { readAttachment, writeAttachment } from "../lib/attachments";
 import { appendTranscript as writeTranscript } from "../lib/transcript";
@@ -107,6 +108,11 @@ export const hostCommands: HostCommands = {
       input.ownerName ?? null,
       input.projects.map((p) => p.slug),
     );
+    // ADR-048: persist the cloud-issued per-task cli secret (host-private) so the
+    // `uai` CLI's per-agent tokens can be minted now + after a host restart.
+    if (input.task.cliSecret) {
+      storeTaskCliSecret(input.task.id, input.task.cliSecret);
+    }
     recordHostEvent(input.task.id, "task.created");
     const result = await wrapAgent(ctx, "taskUp", () => agent.taskUp(input));
     if (result.ok) {

package/src/main.ts

@@ -49,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,
@@ -262,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;
@@ -417,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,
@@ -434,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),
@@ -485,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",
@@ -511,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);
@@ -547,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",
@@ -574,7 +591,7 @@ function handleRawTunnelOpen(
     });
   });
 
-  upstream.connect(port, "127.0.0.1");
+  upstream.connect(target.port, target.host);
 }
 
 function closeTunnel(
@@ -588,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: {
@@ -727,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":
@@ -821,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,
     };
@@ -987,12 +1080,35 @@ function expectTaskAgents(value: unknown): TaskAgent[] {
       kind: expectStringValue(row.kind, "agent.kind"),
     };
     if (typeof row.model === "string") out.model = row.model;
+    // effort was previously dropped here even though the protocol + adapters
+    // carry it — fixed alongside skills (ADR-046).
+    if (typeof row.effort === "string") out.effort = row.effort;
     if (typeof row.defaultPrompt === "string") {
       out.defaultPrompt = row.defaultPrompt;
     }
     if (typeof row.initialPrompt === "string") {
       out.initialPrompt = row.initialPrompt;
     }
+    if (Array.isArray(row.skills)) {
+      const skills = row.skills
+        .filter(
+          (s): s is Record<string, unknown> =>
+            typeof s === "object" && s !== null,
+        )
+        .map((s) => ({
+          name: typeof s.name === "string" ? s.name : "",
+          type: typeof s.type === "string" ? s.type : "",
+          value: typeof s.value === "string" ? s.value : "",
+          source: typeof s.source === "string" ? s.source : null,
+          subpath: typeof s.subpath === "string" ? s.subpath : null,
+        }))
+        .filter((s) => s.name && s.type);
+      if (skills.length > 0) out.skills = skills;
+    }
+    if (Array.isArray(row.permissions)) {
+      const perms = row.permissions.filter((p): p is string => typeof p === "string");
+      if (perms.length > 0) out.permissions = perms;
+    }
     return out;
   });
 }
@@ -1139,6 +1255,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;
 }
 

package/src/protocol.ts

@@ -48,6 +48,17 @@ export interface TaskAgent {
   effort?: string;
   defaultPrompt?: string;
   initialPrompt?: string;
+  /** ADR-046 reference material resolved from the agent's persona + team.
+   *  ADR-047: `type: "package"` carries `source` ('git'|'cli') + `subpath`. */
+  skills?: Array<{
+    name: string;
+    type: string;
+    value: string;
+    source?: string | null;
+    subpath?: string | null;
+  }>;
+  /** ADR-048: the source persona's flat permission list for the `uai` CLI. */
+  permissions?: string[];
 }
 
 /**
@@ -112,9 +123,20 @@ export interface TaskCommandTask {
   slug: string;
   branch: string;
   status: string;
+  /** ADR-048: the task's ephemeral `uai` CLI secret — the host signs per-agent
+   *  tokens with it. Cloud-issued at task-up; never a static shared secret. */
+  cliSecret?: string;
   globalContext?: string;
   reviewerOrder?: string[];
   agents: TaskAgent[];
+  /**
+   * Cloud-computed PUBLIC preview URLs to inject into the container env at
+   * task-up, keyed by the operator-chosen var name (e.g.
+   * `EXPO_PACKAGER_PROXY_URL`). Non-secret — written literally into the task's
+   * compose file. Only present on task-up commands, when a preview port set
+   * `urlEnv` and the cloud has a preview base domain configured.
+   */
+  previewEnv?: Record<string, string>;
 }
 
 /**
@@ -299,6 +321,11 @@ export type CloudToHost =
       target: TunnelTarget;
       taskId: string;
       name?: string;
+      // The in-container port to reach for a preview (ADR-036). The cloud
+      // resolves it from the task's declared + ad-hoc preview ports; the host
+      // proxies to <container-ip>:<containerPort> over the Docker network.
+      // Absent for the editor target (which uses the published codeServerPort).
+      containerPort?: number;
       reqLine: TunnelReqLine;
       upgrade: boolean;
     }