@runuai/host 0.4.2 → 0.4.3

package/lib/mcp-gateway.ts

@@ -0,0 +1,315 @@
+/**
+ * MCP gateway (ADR-057) — the host-side proxy that puts the owner's MCP
+ * connections in front of task containers WITHOUT the credentials ever
+ * entering them.
+ *
+ * Containers call `http://host.docker.internal:<port>/t/<token>/<slug>`; the
+ * gateway resolves the per-task token to an ACL file written at session
+ * ensure (which connections this task may use), attaches the connection's
+ * Authorization header host-side (refreshing OAuth tokens as needed), and
+ * streams the MCP traffic through (streamable HTTP + SSE). Every request
+ * lands in an audit JSONL. Disconnecting a connection kills its secrets in
+ * the host store, so the gateway 401s instantly — the kill switch.
+ *
+ * VERIFY-ON-MAC: OrbStack forwards host.docker.internal to loopback-bound
+ * host services; if not, set UAI_MCP_GATEWAY_BIND=0.0.0.0 (the unguessable
+ * per-task token stays the auth).
+ */
+
+import { appendFileSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { Readable } from "node:stream";
+import { resolve } from "node:path";
+
+import { env } from "./env";
+import { dockerCli } from "./docker-exec";
+import { authHeaderFor, getConnection } from "./mcp-connections";
+
+export const MCP_GATEWAY_PORT = Number(process.env.UAI_MCP_GATEWAY_PORT ?? 5877);
+const BIND = process.env.UAI_MCP_GATEWAY_BIND ?? "127.0.0.1";
+/** MCP request bodies are small JSON-RPC frames; cap so audit parsing (and a
+ *  hostile container) can't balloon host memory. Responses stream freely. */
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+const UPSTREAM_TIMEOUT_MS = 120_000;
+
+export interface TaskMcpConnection {
+  id: string;
+  slug: string;
+}
+
+interface TaskAcl {
+  token: string;
+  connections: TaskMcpConnection[];
+}
+
+function aclDir(): string {
+  return resolve(env.dataDir, "mcp-gateway");
+}
+
+function aclPath(taskId: string): string {
+  return resolve(aclDir(), `${taskId}.json`);
+}
+
+function readAcl(taskId: string): TaskAcl | null {
+  try {
+    return JSON.parse(readFileSync(aclPath(taskId), "utf8")) as TaskAcl;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write/refresh the task's gateway ACL (the connection set snapshots the
+ * cloud's latest ensure input). The token is minted once per task and
+ * survives re-ensures so already-written .mcp.json files stay valid.
+ */
+export function ensureTaskGatewayAcl(
+  taskId: string,
+  connections: TaskMcpConnection[],
+): TaskAcl {
+  const existing = readAcl(taskId);
+  const acl: TaskAcl = {
+    token: existing?.token ?? `${taskId}.${randomBytes(24).toString("base64url")}`,
+    connections,
+  };
+  mkdirSync(aclDir(), { recursive: true, mode: 0o700 });
+  writeFileSync(aclPath(taskId), JSON.stringify(acl), { mode: 0o600 });
+  return acl;
+}
+
+export function clearTaskGatewayAcl(taskId: string): void {
+  try {
+    rmSync(aclPath(taskId));
+  } catch {
+    // already gone
+  }
+}
+
+function audit(entry: Record<string, unknown>): void {
+  try {
+    const dir = resolve(env.dataDir, "logs");
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(
+      resolve(dir, "mcp-audit.jsonl"),
+      `${JSON.stringify({ ts: Date.now(), ...entry })}\n`,
+    );
+  } catch {
+    // audit is best-effort
+  }
+}
+
+function deny(res: ServerResponse, status: number, message: string): void {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify({ error: message }));
+}
+
+async function readBody(req: IncomingMessage): Promise<Buffer | null> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buf = chunk as Buffer;
+    size += buf.length;
+    if (size > MAX_BODY_BYTES) return null;
+    chunks.push(buf);
+  }
+  return Buffer.concat(chunks);
+}
+
+/** JSON-RPC method (+ tool name for tools/call) out of a request body. */
+function rpcSummary(body: Buffer): { method?: string; tool?: string } {
+  try {
+    const json = JSON.parse(body.toString("utf8")) as {
+      method?: string;
+      params?: { name?: string };
+    };
+    return {
+      method: typeof json.method === "string" ? json.method : undefined,
+      tool:
+        json.method === "tools/call" && typeof json.params?.name === "string"
+          ? json.params.name
+          : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+const FORWARD_REQ_HEADERS = [
+  "content-type",
+  "accept",
+  "mcp-session-id",
+  "last-event-id",
+  "mcp-protocol-version",
+];
+const FORWARD_RES_HEADERS = ["content-type", "mcp-session-id"];
+
+async function handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  const match = /^\/t\/([^/]+)\/([^/?]+)\/?(?:\?.*)?$/.exec(req.url ?? "");
+  if (!match) return deny(res, 404, "not found");
+  const [, token, slug] = match as unknown as [string, string, string];
+
+  const taskId = token.split(".")[0] ?? "";
+  const acl = readAcl(taskId);
+  const expected = acl ? Buffer.from(acl.token) : null;
+  const provided = Buffer.from(token);
+  if (
+    !acl ||
+    !expected ||
+    expected.length !== provided.length ||
+    !timingSafeEqual(expected, provided)
+  ) {
+    return deny(res, 401, "unknown task token");
+  }
+  const entry = acl.connections.find((c) => c.slug === slug);
+  if (!entry) return deny(res, 404, `no connection "${slug}" for this task`);
+  const conn = getConnection(entry.id);
+  if (!conn || conn.status !== "connected") {
+    // Disconnected since the task started — the kill switch answering.
+    return deny(res, 401, `connection "${slug}" is no longer available`);
+  }
+
+  const body =
+    req.method === "POST" || req.method === "PUT" ? await readBody(req) : null;
+  if ((req.method === "POST" || req.method === "PUT") && body === null) {
+    return deny(res, 413, "request body too large");
+  }
+
+  const headers: Record<string, string> = {};
+  for (const name of FORWARD_REQ_HEADERS) {
+    const v = req.headers[name];
+    if (typeof v === "string") headers[name] = v;
+  }
+
+  const attempt = async (forceRefresh: boolean): Promise<Response> => {
+    const auth = await authHeaderFor(conn, forceRefresh);
+    if (auth) headers[auth.name] = auth.value;
+    return fetch(conn.url, {
+      method: req.method,
+      headers,
+      body: body ?? undefined,
+      signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
+    });
+  };
+
+  let upstream: Response;
+  try {
+    upstream = await attempt(false);
+    if (upstream.status === 401 && conn.authKind === "oauth") {
+      upstream = await attempt(true);
+    }
+  } catch (err) {
+    audit({ taskId, slug, method: req.method, error: String(err) });
+    return deny(res, 502, "upstream unreachable");
+  }
+
+  const summary = body ? rpcSummary(body) : {};
+  audit({
+    taskId,
+    slug,
+    method: req.method,
+    rpc: summary.method,
+    tool: summary.tool,
+    status: upstream.status,
+  });
+
+  const resHeaders: Record<string, string> = {};
+  for (const name of FORWARD_RES_HEADERS) {
+    const v = upstream.headers.get(name);
+    if (v) resHeaders[name] = v;
+  }
+  res.writeHead(upstream.status, resHeaders);
+  if (upstream.body) {
+    Readable.fromWeb(upstream.body as Parameters<typeof Readable.fromWeb>[0]).pipe(
+      res,
+    );
+  } else {
+    res.end();
+  }
+}
+
+/** Start the gateway listener. Idempotent-ish: call once from main. */
+export function startMcpGateway(): void {
+  const server = createServer((req, res) => {
+    void handle(req, res).catch(() => deny(res, 500, "gateway error"));
+  });
+  server.on("error", (err) => {
+    console.warn(`[mcp-gateway] listener error: ${err.message}`);
+  });
+  server.listen(MCP_GATEWAY_PORT, BIND, () => {
+    console.log(`[mcp-gateway] listening on ${BIND}:${MCP_GATEWAY_PORT}`);
+  });
+}
+
+// --- task container wiring (ADR-057 task-up writers) -------------------------
+
+/** Idempotent node -e merge of entries into /workspace/.mcp.json. */
+const MERGE_MCP_JSON = `
+const fs = require("fs");
+const p = "/workspace/.mcp.json";
+let j = {};
+try { j = JSON.parse(fs.readFileSync(p, "utf8")); } catch {}
+j.mcpServers = j.mcpServers || {};
+let changed = false;
+for (const [k, v] of Object.entries(JSON.parse(process.argv[1]))) {
+  if (JSON.stringify(j.mcpServers[k]) !== JSON.stringify(v)) { j.mcpServers[k] = v; changed = true; }
+}
+if (changed) fs.writeFileSync(p, JSON.stringify(j, null, 2) + "\\n");
+`.trim();
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * Write the task's MCP configs inside the container: gateway-URL entries per
+ * connection for Claude (/workspace/.mcp.json, merged — coexists with the
+ * ADR-053 browser server) and mcp-remote shims for Codex (config.toml,
+ * append-once per slug). Safe to re-run every ensure.
+ */
+export async function setupMcpTaskConfig(
+  taskId: string,
+  containerName: string,
+  connections: TaskMcpConnection[],
+  hasCodex: boolean,
+): Promise<void> {
+  if (connections.length === 0) return;
+  try {
+    const acl = ensureTaskGatewayAcl(taskId, connections);
+    const urlFor = (slug: string): string =>
+      `http://host.docker.internal:${MCP_GATEWAY_PORT}/t/${acl.token}/${slug}`;
+
+    const claudeEntries: Record<string, unknown> = {};
+    for (const c of connections) {
+      claudeEntries[c.slug] = { type: "http", url: urlFor(c.slug) };
+    }
+    const steps = [
+      "mkdir -p /workspace/.claude",
+      `[ -f /workspace/.claude/settings.json ] || printf '%s\\n' ${shellQuote(
+        JSON.stringify({ enableAllProjectMcpServers: true }, null, 2),
+      )} > /workspace/.claude/settings.json`,
+      `node -e ${shellQuote(MERGE_MCP_JSON)} ${shellQuote(JSON.stringify(claudeEntries))}`,
+      ...(hasCodex
+        ? connections.map(
+            (c) =>
+              `grep -q "mcp_servers.${c.slug}]" /home/node/.codex/config.toml 2>/dev/null || printf '%s' ${shellQuote(
+                `\n[mcp_servers.${c.slug}]\ncommand = "npx"\nargs = ["-y", "mcp-remote", "${urlFor(c.slug)}", "--allow-http"]\n`,
+              )} >> /home/node/.codex/config.toml`,
+          )
+        : []),
+    ].join(" && ");
+    const result = await dockerCli(
+      ["exec", containerName, "sh", "-lc", steps],
+      { timeoutMs: 20_000 },
+    );
+    if (result.status !== 0) {
+      console.warn(
+        `[mcp-gateway] task ${taskId}: config write failed: ${result.stderr.slice(0, 300)}`,
+      );
+    }
+  } catch (err) {
+    console.warn(
+      `[mcp-gateway] task ${taskId}: setup failed: ${err instanceof Error ? err.message : err}`,
+    );
+  }
+}

package/lib/orchestrator.ts

@@ -50,8 +50,14 @@ import {
   loadTaskCliSecret,
   writeAgentCli,
 } from "./agent-cli";
+import { setupBrowserTesting } from "./browser-testing";
+import { setupMcpTaskConfig } from "./mcp-gateway";
 import { env } from "./env";
-import type { ChannelEnsureInput, HostEvent } from "../src/protocol";
+import type {
+  ChannelEnsureInput,
+  ChannelHuman,
+  HostEvent,
+} from "../src/protocol";
 
 export type HostEventSubscriber = (event: HostEvent) => void;
 
@@ -86,6 +92,19 @@ interface Channel {
   /** Per-agent respawn counter — bounded so a broken agent can't
    *  loop forever rewriting its config. */
   respawns: Map<string, number>;
+  /** ADR-049: humans in the chat (from the latest channel spec). */
+  humans: ChannelHuman[];
+  /** ADR-053: wire the Playwright MCP browser at session start. */
+  browserTesting: boolean;
+  /** ADR-057: the owner's MCP connections exposed through the host gateway. */
+  mcpConnections: Array<{ id: string; slug: string }>;
+  /** Last connection set written into the container (skip repeat execs —
+   *  ensure runs on every message). Live sessions read MCP config at spawn,
+   *  so a mid-task write takes effect on the next (re)spawn. */
+  mcpConfigFingerprint?: string;
+  /** Agents with a reconcile-spawn in flight (ADR-049 mid-task adds) — guards
+   *  against a concurrent ensure double-spawning the same new agent. */
+  spawning: Set<string>;
 }
 
 /** Hard cap on automatic respawns per agent per channel lifetime. */
@@ -133,6 +152,44 @@ class Orchestrator {
 
   registerChannelSpec(spec: ChannelEnsureInput): void {
     this.channelSpecs.set(spec.taskId, spec);
+    // ADR-049: the cloud re-sends the spec on every message AND right after a
+    // mid-task roster/participant change. If the channel is already live,
+    // fold the fresh spec in: append new roster agents (their sessions spawn
+    // in the reconcile pass of ensureSessions) and rebuild every preamble so
+    // a later respawn briefs agents with the CURRENT roster + humans.
+    const channel = this.channels.get(spec.taskId);
+    if (channel) this.refreshChannel(channel, spec);
+  }
+
+  /** Fold a fresh channel spec into a live channel (ADR-049). */
+  private refreshChannel(channel: Channel, spec: ChannelEnsureInput): void {
+    const known = new Set(channel.roster.map((a) => a.id));
+    for (const agent of spec.agents) {
+      if (!known.has(agent.id)) {
+        channel.roster.push(agent);
+        // Per-agent link/document skills, like getOrCreateChannel does at
+        // channel birth. Best-effort.
+        writeAgentSkills(channel.taskId, agent);
+      }
+    }
+    channel.humans = spec.humans ?? [];
+    channel.browserTesting = spec.browserTesting === true;
+    channel.mcpConnections = spec.mcpConnections ?? [];
+    for (const agent of channel.roster) {
+      channel.preambles.set(
+        agent.id,
+        buildSystemPreamble(
+          channel.roster,
+          agent,
+          spec.projects,
+          spec.globalContext,
+          spec.workspacePath,
+          spec.branch,
+          channel.humans,
+          channel.browserTesting,
+        ),
+      );
+    }
   }
 
   private async getOrCreateChannel(taskId: string): Promise<Channel | null> {
@@ -155,6 +212,8 @@ class Orchestrator {
           spec.globalContext,
           spec.workspacePath,
           spec.branch,
+          spec.humans,
+          spec.browserTesting,
         ),
       );
       // ADR-046: materialise this agent's skills to its per-agent SKILL.md in
@@ -181,6 +240,10 @@ class Orchestrator {
       openTurns: new Set(),
       interrupted: new Set(),
       respawns: new Map(),
+      humans: spec.humans ?? [],
+      browserTesting: spec.browserTesting === true,
+      mcpConnections: spec.mcpConnections ?? [],
+      spawning: new Set(),
     };
     this.channels.set(taskId, channel);
     return channel;
@@ -197,7 +260,7 @@ class Orchestrator {
    *
    * Returns whether sessions are ready.
    */
-  private ensureSessions(channel: Channel): Promise<boolean> {
+  private async ensureSessions(channel: Channel): Promise<boolean> {
     // Memoized: every caller awaits the SAME in-flight start, so a concurrent
     // deliver() can't observe "ready" while the sessions map is still empty
     // (startSessions awaits docker work before populating it — the old boolean
@@ -215,7 +278,86 @@ class Orchestrator {
         },
       );
     }
-    return channel.sessionsReady;
+    const ready = await channel.sessionsReady;
+    // ADR-049 reconcile pass: spawn any roster agent that has no live session
+    // yet — the initial batch, host-restart recovery, and mid-task adds all
+    // converge here. No-op when every roster agent has a session.
+    if (ready) {
+      await this.reconcileSessions(channel);
+      // ADR-057: keep the container's MCP configs current so a connection
+      // added mid-task lands (effective at each session's next spawn).
+      await this.ensureMcpConfig(channel);
+    }
+    return ready;
+  }
+
+  /** Write the task's MCP configs when the connection set changed. */
+  private async ensureMcpConfig(channel: Channel): Promise<void> {
+    const fingerprint = JSON.stringify(channel.mcpConnections.map((c) => c.id));
+    if (channel.mcpConfigFingerprint === fingerprint) return;
+    channel.mcpConfigFingerprint = fingerprint;
+    await setupMcpTaskConfig(
+      channel.taskId,
+      channel.containerName,
+      channel.mcpConnections,
+      channel.roster.some((a) => a.kind === "codex"),
+    );
+  }
+
+  /** Spawn sessions for roster agents added after the initial start. */
+  private async reconcileSessions(channel: Channel): Promise<void> {
+    const missing = channel.roster.filter(
+      (agent) =>
+        !channel.sessions.has(agent.id) &&
+        !channel.spawning.has(agent.id) &&
+        // Crash-loop budget: an agent whose session keeps dying stops being
+        // respawned after MAX_RESPAWNS_PER_AGENT (the exit paths increment).
+        (channel.respawns.get(agent.id) ?? 0) <= MAX_RESPAWNS_PER_AGENT,
+    );
+    if (missing.length === 0) return;
+
+    const task = getHostTask(channel.taskId);
+    if (!task || task.statusMirror !== "running") return;
+
+    for (const agent of missing) channel.spawning.add(agent.id);
+    try {
+      // Same per-agent materialisation the initial start does: package
+      // skills (idempotent — only the new agents' installs run), and the
+      // shared `uai` CLI rewritten for the full roster.
+      await installPackageSkills(channel.taskId, missing);
+      if (channel.browserTesting) {
+        await setupBrowserTesting(
+          channel.taskId,
+          channel.containerName,
+          channel.roster.some((a) => a.kind === "codex"),
+        );
+      }
+      const apiUrl = apiUrlFromCloudUrl(env.UAI_CLOUD_URL);
+      const cliSecret = loadTaskCliSecret(channel.taskId);
+      writeAgentCli(channel.taskId, channel.roster, apiUrl);
+
+      for (const agent of missing) {
+        const session = await this.factory.create({
+          taskId: channel.taskId,
+          agent,
+          containerName: channel.containerName,
+          systemPreamble: channel.preambles.get(agent.id) ?? "",
+          agentEnv: agentCliEnv(
+            channel.taskId,
+            agent,
+            task.ownerUserId,
+            apiUrl,
+            cliSecret,
+          ),
+        });
+        channel.sessions.set(agent.id, session);
+        session.onEvent((event) => {
+          void this.handleAgentEvent(channel, agent.id, event);
+        });
+      }
+    } finally {
+      for (const agent of missing) channel.spawning.delete(agent.id);
+    }
   }
 
   private async startSessions(channel: Channel): Promise<boolean> {
@@ -246,6 +388,21 @@ class Orchestrator {
     // tasks. Never throws.
     await installPackageSkills(channel.taskId, channel.roster);
 
+    // ADR-053: wire the Playwright MCP browser (configs + backgrounded
+    // Chromium install) before agents spawn. Idempotent + best-effort.
+    if (channel.browserTesting) {
+      await setupBrowserTesting(
+        channel.taskId,
+        channel.containerName,
+        channel.roster.some((a) => a.kind === "codex"),
+      );
+    }
+
+    // ADR-057: the owner's MCP connections, reached through the host gateway
+    // (tokens never enter the container) — written BEFORE agents spawn so
+    // first sessions load them.
+    await this.ensureMcpConfig(channel);
+
     // ADR-048: write the in-container `uai` CLI (apiUrl only, no token) into the
     // workspace. Each agent's OWN task token — carrying only ITS permissions — is
     // injected per-agent via its docker exec env below, so per-persona permissions
@@ -449,6 +606,14 @@ class Orchestrator {
           agentId,
           reason: event.message,
         });
+        // The session is DEAD — drop it so the reconciling ensureSessions
+        // respawns it on the next delivery/ensure. Without this the agent
+        // becomes a zombie: the map still holds the dead session and every
+        // later deliver "succeeds" into a closed pipe (found live 2026-07-08
+        // after a double SIGKILL). Bounded by the respawn budget, checked in
+        // reconcileSessions.
+        channel.respawns.set(agentId, (channel.respawns.get(agentId) ?? 0) + 1);
+        channel.sessions.delete(agentId);
         break;
       }
       case "turn_complete": {
@@ -467,6 +632,10 @@ class Orchestrator {
         break;
       }
       case "exit":
+        // Same zombie hazard as the error path — a session whose process
+        // ended (even cleanly) can never carry another turn.
+        channel.respawns.set(agentId, (channel.respawns.get(agentId) ?? 0) + 1);
+        channel.sessions.delete(agentId);
         break;
     }
   }
@@ -754,12 +923,49 @@ export function buildSystemPreamble(
   globalContext: string | undefined,
   workspacePath: string,
   taskBranch: string,
+  humans?: ChannelHuman[],
+  browserTesting?: boolean,
 ): string {
   const channelList = roster
     .map((a) =>
       a.id === agent.id ? `@${a.id} (${a.label}, you)` : `@${a.id} (${a.label})`,
     )
     .join(", ");
+  // ADR-049: with several humans in the chat, brief the agent on who they are
+  // and how to address one specifically. Single-human tasks keep the original
+  // wording byte-identical.
+  const multiHuman = (humans?.length ?? 0) > 1;
+  const humanList = (humans ?? [])
+    .map((h) => `@${h.handle} (${h.name}${h.isOwner ? ", task owner" : ""})`)
+    .join(", ");
+  const humanIntro = multiHuman
+    ? [
+        `SEVERAL humans share this channel: ${humanList}. Their messages`,
+        "arrive prefixed with the sender's name so you can tell them apart.",
+        "`@you` still works and reaches the human you're currently talking",
+        "to (whoever last addressed you); to reach a SPECIFIC human, mention",
+        "their handle instead (e.g. `@" +
+          (humans?.[0]?.handle ?? "name") +
+          "`). Mentioning a human 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 everything else —",
+        "status updates, thinking out loud, a direct reply to something they",
+        "just asked, acknowledgments — post in the channel WITHOUT",
+        "@-mentioning; they can read the channel and don't need a ping for",
+        "every message.",
+      ]
+    : [
+        "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.",
+      ];
   const projectLines =
     projects.length === 0
       ? ["(none mounted)"]
@@ -781,15 +987,7 @@ export function buildSystemPreamble(
     "",
     `Agents in this channel: ${channelList}.`,
     "",
-    "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.",
+    ...humanIntro,
     "",
     "An agent only receives a message when it is explicitly @-mentioned",
     "(or addressed by the human) — so always @-mention the agent (or @you)",
@@ -827,6 +1025,15 @@ export function buildSystemPreamble(
     "context (e.g. the human shared a file or instruction with another",
     "agent); it's appended live, so re-read it for the latest.",
     "",
+    "Two channel conventions (ADR-050): (1) If your reply @-mentions nobody,",
+    "uai hands it back to whoever prompted you — so when you're ANSWERING,",
+    "just answer plainly; you don't need to re-mention the asker. Mention",
+    "someone only to bring them in or hand work off. (2) You may occasionally",
+    "receive a `[channel check-in]` asking you to catch up on the channel.",
+    "Read the transcript, and speak ONLY if you have something substantive to",
+    "add; otherwise reply with exactly `PASS` — a PASS reply is discarded and",
+    "never shown to anyone, so it is always a safe way to decline a turn.",
+    "",
     "Hand off when you finish your part of the work. When you've made",
     "and committed your changes, or completed a review, end your reply by",
     "@-mentioning the agent who should act next and telling them what you",
@@ -886,6 +1093,28 @@ export function buildSystemPreamble(
           "",
         ]
       : []),
+    // ADR-053: the in-container browser, when the project opted in.
+    ...(browserTesting
+      ? [
+          "## Browser",
+          "",
+          "This container has a headless Chromium available through the",
+          "`browser` MCP server (Playwright). Use it to VERIFY UI work",
+          "end-to-end — the dev server you're building runs in this same",
+          "container, so navigate to `http://localhost:<port>` directly.",
+          "Prefer accessibility snapshots for navigation and assertions;",
+          "take an actual screenshot only when rendering matters (vision",
+          "input is expensive). To show a screenshot in the chat, save it",
+          "under `/workspace/.uai/attachments/<name>.png` and reference it",
+          "in your reply as `[image: /workspace/.uai/attachments/<name>.png]`.",
+          "Your browser runs on a virtual display the humans can WATCH live",
+          "(the \"browser\" preview) — nothing for you to do about that.",
+          "The first browser launch in a fresh container may take a minute",
+          "while Chromium's system deps finish installing — retry once if",
+          "it fails immediately after task start.",
+          "",
+        ]
+      : []),
     // ADR-048: tell agents with permissions about their `uai` CLI.
     ...((agent.permissions?.length ?? 0) > 0
       ? [
@@ -904,7 +1133,12 @@ export function buildSystemPreamble(
             (agent.permissions?.includes("memory.read")
               ? ", `memory search <query>`"
               : "") +
-            ".",
+            ", `react <heart|check|x> [--msg #id]`.",
+          "**Reacting:** `uai react check` is a lightweight ack of the message",
+          "you were last handed — use it to acknowledge an instruction or",
+          "approve a proposal without spending a whole reply (❌ = disagree,",
+          "❤️ = appreciation). Messages in chat.md carry their `#id` if you",
+          "want to react to an older one. Reactions wake nobody.",
           ...(agent.permissions?.includes("tasks.create")
             ? [
                 "**Creating a task in Uai:** when a human asks you to create/file/",