@runuai/host 0.2.8 → 0.3.0

package/lib/agents/claude.ts

@@ -338,6 +338,14 @@ register({
   defaultModel: CLAUDE_DEFAULT_MODEL,
   supportedEfforts: () => [...CLAUDE_EFFORTS],
   defaultEffort: CLAUDE_DEFAULT_EFFORT,
+  // Usable only when a Claude credential is in the env (injected into task
+  // containers at task-up). Gates advertisement (ADR-044 P2).
+  available: () =>
+    Boolean(
+      process.env.CLAUDE_CODE_OAUTH_TOKEN ||
+        process.env.ANTHROPIC_API_KEY ||
+        process.env.ANTHROPIC_AUTH_TOKEN,
+    ),
   create: async ({ agent, containerName, systemPreamble }) =>
     new ClaudeSession({ agent, containerName, systemPreamble }),
 });

package/lib/agents/codex.ts

@@ -28,6 +28,10 @@
  * namespaces inside it anyway.
  */
 
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
 import { newId } from "../ulid";
 import { dockerExecArgs, LineProcess } from "./proc";
 import { register } from "./registry";
@@ -517,6 +521,13 @@ register({
   defaultModel: CODEX_DEFAULT_MODEL,
   supportedEfforts: () => [...CODEX_EFFORTS],
   defaultEffort: CODEX_DEFAULT_EFFORT,
+  // Usable only when the owner's ~/.codex login exists — task-up copies it into
+  // each container from UAI_OWNER_HOME (default $HOME). Gates advertisement
+  // (ADR-044 P2).
+  available: () =>
+    existsSync(
+      join(process.env.UAI_OWNER_HOME?.trim() || homedir(), ".codex", "auth.json"),
+    ),
   create: async ({ agent, containerName, systemPreamble }) =>
     new CodexSession({ agent, containerName, systemPreamble }),
 });

package/lib/agents/registry.ts

@@ -32,6 +32,14 @@ export interface RegisteredAdapter {
   supportedEfforts(): string[];
   /** Preferred effort when the user doesn't pick one. */
   defaultEffort?: string;
+  /**
+   * Whether this kind is usable on THIS host right now — i.e. its credentials
+   * are present (ADR-044 P2). Gates advertisement: an unavailable kind is left
+   * out of `capabilities()` so the cloud's task picker doesn't offer an LLM the
+   * host can't actually run. Omit (or return true) to always advertise; the
+   * session factory stays permissive regardless.
+   */
+  available?: () => boolean;
   /** Builds an AgentSession for a roster entry of this kind. */
   create: AgentSessionFactory["create"];
 }
@@ -76,7 +84,9 @@ export function factoryFor(kind: string): AgentSessionFactory | undefined {
  * Each adapter's `supportedModels()` / `supportedEfforts()` is evaluated here.
  */
 export function capabilities(): AgentKindCapability[] {
-  return list().map((adapter) => {
+  return list()
+    .filter((adapter) => adapter.available?.() ?? true)
+    .map((adapter) => {
     const out: AgentKindCapability = {
       kind: adapter.kind,
       label: adapter.label,

package/lib/command-db.ts

@@ -135,12 +135,12 @@ function insertTask(db: Database.Database, task: CommandTaskRow): void {
       id, owner_user_id, host_id, name, slug, branch, status,
       global_context, reviewer_order, agents, pr_context,
       worktree_path, compose_project, code_server_port, preview_ports,
-      locked_at, started_at, ended_at
+      preview_env, locked_at, started_at, ended_at
     ) VALUES (
       @id, @owner_user_id, @host_id, @name, @slug, @branch, @status,
       @global_context, @reviewer_order, @agents, @pr_context,
       @worktree_path, @compose_project, @code_server_port, @preview_ports,
-      @locked_at, @started_at, @ended_at
+      @preview_env, @locked_at, @started_at, @ended_at
     )`,
   ).run(task);
 }
@@ -166,6 +166,7 @@ interface CommandTaskRow {
   compose_project: string | null;
   code_server_port: number | null;
   preview_ports: string;
+  preview_env: string | null;
   locked_at: number | null;
   started_at: number | null;
   ended_at: number | null;
@@ -193,6 +194,7 @@ function withRuntime(
     compose_project: runtime?.composeProject ?? null,
     code_server_port: runtime?.codeServerPort ?? null,
     preview_ports: runtime?.previewPorts ?? "[]",
+    preview_env: task.previewEnv ? JSON.stringify(task.previewEnv) : null,
     locked_at: runtime?.lockedAt ?? null,
     started_at: runtime?.startedAt ?? null,
     ended_at: runtime?.endedAt ?? null,
@@ -216,6 +218,7 @@ function runtimeTask(taskId: string, runtime: HostTask | null): CommandTaskRow {
     compose_project: runtime?.composeProject ?? null,
     code_server_port: runtime?.codeServerPort ?? null,
     preview_ports: runtime?.previewPorts ?? "[]",
+    preview_env: null,
     locked_at: runtime?.lockedAt ?? null,
     started_at: runtime?.startedAt ?? null,
     ended_at: runtime?.endedAt ?? null,
@@ -262,6 +265,7 @@ CREATE TABLE IF NOT EXISTS uai_tasks (
   compose_project text,
   code_server_port integer,
   preview_ports text NOT NULL DEFAULT '[]',
+  preview_env text,
   pr_url text,
   locked_at integer,
   started_at integer,

package/lib/git-diff.ts

@@ -1,9 +1,10 @@
 /**
  * Parse `git diff` unified output into structured per-file patches.
  *
- * Input is whatever `git diff origin/<base>..HEAD` produces — multi-file,
- * with headers, mode/rename/binary annotations, and `@@` hunks. The
- * output is a list of `DiffFile`s the UI can render per-file with
+ * Input is whatever `git diff <merge-base>` (committed + uncommitted) plus
+ * appended `--no-index` new-file patches for untracked files produce —
+ * multi-file, with headers, mode/rename/binary annotations, and `@@` hunks.
+ * The output is a list of `DiffFile`s the UI can render per-file with
  * collapse/expand and syntax-highlighted hunks.
  *
  * Hand-rolled rather than pulled in as a dep — the unified-diff grammar
@@ -98,34 +99,84 @@ export function runGitDiffInContainer(
   containerName: string,
   cwd: string,
   range: string,
+): Promise<string> {
+  return runDiffCommand(
+    "docker",
+    [...dockerExecPrefix(containerName, cwd), "git", ...GIT_DIFF_ARGS, range],
+    "docker exec git diff",
+    process.env,
+  );
+}
+
+/**
+ * Render a single untracked file as a new-file patch by diffing it against
+ * `/dev/null` with `--no-index`. `git diff <commit>` omits untracked files
+ * entirely, so this is how they reach the "all changes vs base" view.
+ *
+ * `--no-index` exits 1 when the inputs differ (the normal "there is a diff"
+ * case for a new file) and 0 when identical — both are success here; only
+ * code > 1 is a real error.
+ */
+export function runGitDiffUntracked(
+  cwd: string,
+  relPath: string,
+): Promise<string> {
+  return runDiffCommand(
+    "git",
+    ["-C", cwd, ...GIT_DIFF_ARGS, "--no-index", "--", "/dev/null", relPath],
+    "git diff --no-index",
+    { ...process.env, ...NON_INTERACTIVE_GIT_ENV },
+    true,
+  );
+}
+
+/** In-container variant of {@link runGitDiffUntracked}. */
+export function runGitDiffUntrackedInContainer(
+  containerName: string,
+  cwd: string,
+  relPath: string,
 ): Promise<string> {
   return runDiffCommand(
     "docker",
     [
-      "exec",
-      "-e",
-      `GIT_TERMINAL_PROMPT=${NON_INTERACTIVE_GIT_ENV.GIT_TERMINAL_PROMPT}`,
-      "-e",
-      `GCM_INTERACTIVE=${NON_INTERACTIVE_GIT_ENV.GCM_INTERACTIVE}`,
-      "-e",
-      `GIT_SSH_COMMAND=${NON_INTERACTIVE_GIT_ENV.GIT_SSH_COMMAND}`,
-      "-w",
-      cwd,
-      containerName,
+      ...dockerExecPrefix(containerName, cwd),
       "git",
       ...GIT_DIFF_ARGS,
-      range,
+      "--no-index",
+      "--",
+      "/dev/null",
+      relPath,
     ],
-    "docker exec git diff",
+    "docker exec git diff --no-index",
     process.env,
+    true,
   );
 }
 
+/** `docker exec` argv prefix with the non-interactive git env + working dir. */
+function dockerExecPrefix(containerName: string, cwd: string): string[] {
+  return [
+    "exec",
+    "-e",
+    `GIT_TERMINAL_PROMPT=${NON_INTERACTIVE_GIT_ENV.GIT_TERMINAL_PROMPT}`,
+    "-e",
+    `GCM_INTERACTIVE=${NON_INTERACTIVE_GIT_ENV.GCM_INTERACTIVE}`,
+    "-e",
+    `GIT_SSH_COMMAND=${NON_INTERACTIVE_GIT_ENV.GIT_SSH_COMMAND}`,
+    "-w",
+    cwd,
+    containerName,
+  ];
+}
+
 function runDiffCommand(
   command: string,
   args: string[],
   label: string,
   env: NodeJS.ProcessEnv,
+  /** Treat exit code 1 as success — `git diff --no-index` returns 1 when the
+   *  compared inputs differ, which for a new-file patch is the expected case. */
+  allowExitOne = false,
 ): Promise<string> {
   return new Promise((res, rej) => {
     // Force ASCII paths and pull a generous unified context so the UI
@@ -144,7 +195,7 @@ function runDiffCommand(
     });
     child.on("error", rej);
     child.on("close", (code) => {
-      if (code === 0) {
+      if (code === 0 || (allowExitOne && code === 1)) {
         res(stdout);
         return;
       }

package/lib/orchestrator.ts

@@ -235,14 +235,13 @@ class Orchestrator {
       });
     }
 
-    // Container is ready: deliver each agent's first-turn prompt (ADR-022).
-    // Only agents whose `initialPrompt` was non-empty have an entry.
-    for (const agent of channel.roster) {
-      const firstTurn = channel.firstTurns.get(agent.id);
-      if (firstTurn === undefined) continue;
-      const session = channel.sessions.get(agent.id);
-      if (session) void session.send(firstTurn);
-    }
+    // First-turn delivery is owned by the CLOUD (channel-router.ensureStarted),
+    // which fires each agent's initialPrompt exactly once per task — guarded by
+    // a non-empty message history (its durable "already started" check). The
+    // host must NOT deliver it here: this path re-runs on every session spawn,
+    // so it both duplicated the opening turn AND re-injected it on a host
+    // restart, making agents redo the first turn mid-task. The persona/mission
+    // an agent needs live in the always-on system preamble, so nothing is lost.
     return true;
   }
 
@@ -723,7 +722,11 @@ export function buildSystemPreamble(
   workspacePath: string,
   taskBranch: string,
 ): string {
-  const others = roster.map((a) => `@${a.id} (${a.label})`).join(", ");
+  const channelList = roster
+    .map((a) =>
+      a.id === agent.id ? `@${a.id} (${a.label}, you)` : `@${a.id} (${a.label})`,
+    )
+    .join(", ");
   const projectLines =
     projects.length === 0
       ? ["(none mounted)"]
@@ -739,19 +742,51 @@ export function buildSystemPreamble(
     "it by id at the start of a line — e.g. `@codex please review the",
     "diff`. uai routes that message into that agent's input.",
     "",
-    `Agents in this channel: ${others}.`,
+    `**You are @${agent.id}** — your name in this channel is **${agent.label}**.`,
+    `Introduce and refer to yourself as ${agent.label}, not as a generic`,
+    "assistant or model name.",
+    "",
+    `Agents in this channel: ${channelList}.`,
     "",
-    "The human you're working with is **@you**. When you need their",
-    "input, a decision, or their attention — a question, a blocker, an",
-    "approval, or you've finished and are handing back to them — end your",
-    "message by @-mentioning **@you** (e.g. `@you which approach do you`",
-    "`prefer?` or `@you done — PR is up for review`). That notifies them.",
+    "The human you're working with is **@you**. @-mentioning them sends a",
+    "NOTIFICATION, so use it sparingly — only when you actually need them: a",
+    "decision you can't make, a blocker, an approval, or you've finished your",
+    "work and are handing it back for them to act on (e.g. `@you which`",
+    "`approach do you prefer?` or `@you done — PR is up for review`). For",
+    "everything else — status updates, thinking out loud, a direct reply to",
+    "something they just asked, acknowledgments — post in the channel WITHOUT",
+    "@-mentioning @you; they can read the channel and don't need a ping for",
+    "every message. Do NOT reflexively end messages with @you.",
     "",
     "An agent only receives a message when it is explicitly @-mentioned",
     "(or addressed by the human) — so always @-mention the agent (or @you)",
     "you mean. There is NO `peer` command and no shared tmux session;",
     "hand-offs are just @-mentions in your replies.",
     "",
+    "Collaborate with your peers — divide up the work, review each other's",
+    "changes, share concrete ideas, and debate approach decisions by",
+    "@-mentioning them. That is how the team gets things done, and you",
+    "should do it freely whenever it moves the work forward. But mentioning",
+    "a peer WAKES it and costs a turn, so make each one count: a message to",
+    "a peer should ADVANCE the work — a real proposal, a question you need",
+    "answered, a hand-off, or a review with specific findings. Do NOT",
+    "@-mention a peer just to greet, thank, agree, acknowledge, or say",
+    "you're ready — content-free replies wake them for nothing and spiral",
+    "into endless back-and-forth. If you have nothing substantive to add,",
+    "don't @-mention back. And when there's no active task yet (intros, or",
+    "you're waiting on the human), answer briefly and then wait — you don't",
+    "need to @-mention anyone (including @you); they can see the channel.",
+    "",
+    "When a message already @-mentions several participants at once (the",
+    "human asking the whole group, or a peer addressing multiple agents),",
+    "it's a group broadcast — this is a GROUP CHAT and everyone named has",
+    "ALREADY been notified and will answer for themselves. Just answer for",
+    "YOUR part. Do NOT re-@-mention the others to prompt them, hand the",
+    "question to them, or wait on them — no `I'll let @x speak`, `@x your",
+    "turn`, or `still waiting on @x`. Re-mentioning someone who already got",
+    "the message only wakes them again and spirals into duplicate replies.",
+    "Say your piece and stop.",
+    "",
     "Because your input is only what you're addressed, you may be missing",
     "context from messages between the human and the other agents. The full",
     "channel transcript — every message + who wrote it (no tool calls) — is",
@@ -763,9 +798,11 @@ export function buildSystemPreamble(
     "and committed your changes, or completed a review, end your reply by",
     "@-mentioning the agent who should act next and telling them what you",
     "did and what you need (e.g. `@codex changes committed on <branch> —",
-    "please review`, or `@claude review done, N issues to fix`). Never",
-    "stop silently — if genuinely no agent needs to act, say so to the",
-    "human.",
+    "please review`, or `@claude review done, N issues to fix`). Don't",
+    "abandon unfinished work silently — but once your part is done and no",
+    "peer needs to act, it's fine to stop; only @-mention @you if you need",
+    "their input or are handing back finished work for them to act on. Don't",
+    "prolong an agent-to-agent exchange just to fill silence.",
     "",
     "## Workspace layout",
     "",

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.8",
+  "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

@@ -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,
     };
@@ -1139,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;
 }
 

package/src/protocol.ts

@@ -115,6 +115,14 @@ export interface TaskCommandTask {
   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 +307,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;
     }