@runuai/host 0.2.8 → 0.4.0

package/lib/orchestrator.ts

@@ -37,6 +37,20 @@ import { getHostTask, upsertHostTask } from "./runtime-state";
 import { setupTaskGithub } from "./github-tokens";
 import { setupTaskGitIdentity } from "./git-identity";
 import { dockerCli } from "./docker-exec";
+import {
+  containerSkillFile,
+  installedSkillPath,
+  installPackageSkills,
+  writeAgentSkills,
+} from "./skills";
+import {
+  CONTAINER_CLI_PATH,
+  agentCliEnv,
+  apiUrlFromCloudUrl,
+  loadTaskCliSecret,
+  writeAgentCli,
+} from "./agent-cli";
+import { env } from "./env";
 import type { ChannelEnsureInput, HostEvent } from "../src/protocol";
 
 export type HostEventSubscriber = (event: HostEvent) => void;
@@ -143,6 +157,9 @@ class Orchestrator {
           spec.branch,
         ),
       );
+      // ADR-046: materialise this agent's skills to its per-agent SKILL.md in
+      // the workspace (bind-mounted into the container). Best-effort.
+      writeAgentSkills(taskId, agent);
       // ADR-022: any agent with a non-empty initialPrompt opens a first
       // turn at container-ready. The rest stay silent until addressed.
       const firstTurn = assembleFirstTurnPrompt(
@@ -222,12 +239,28 @@ class Orchestrator {
       void setupTaskGithub(channel.taskId, task.ownerUserId);
     }
 
+    // ADR-047: install any package skills (native Claude Agent Skills) into the
+    // container BEFORE spawning agents, so they're discoverable on the first
+    // turn. Idempotent + best-effort (returns fast when there are none); a slow
+    // clone/install briefly delays start, which is acceptable for skill-bearing
+    // tasks. Never throws.
+    await installPackageSkills(channel.taskId, channel.roster);
+
+    // 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
+    // are actually enforced. Best-effort, host-side.
+    const apiUrl = apiUrlFromCloudUrl(env.UAI_CLOUD_URL);
+    const cliSecret = loadTaskCliSecret(channel.taskId);
+    writeAgentCli(channel.taskId, channel.roster, apiUrl);
+
     for (const agent of channel.roster) {
       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) => {
@@ -235,14 +268,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 +755,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 +775,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 +831,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",
     "",
@@ -788,6 +858,71 @@ export function buildSystemPreamble(
     "part of the project. Never review, edit, stage, commit, or flag it;",
     "treat it as ignored, even though git may show it as untracked.",
     "",
+    // ADR-046: link/document skills are materialised to a per-agent SKILL.md.
+    // Point the agent at its own file (package skills are handled below).
+    ...((agent.skills ?? []).some((s) => s.type !== "package")
+      ? [
+          "## Your skills",
+          "",
+          "Reference material (links + documents) has been prepared for you at",
+          `\`${containerSkillFile(agent.id)}\`. Read it when a task touches what`,
+          "it covers. It's yours — other agents have their own.",
+          "",
+        ]
+      : []),
+    // ADR-047: package skills are native Claude Agent Skills installed into the
+    // container's skills dir (Claude-only). List them so the agent knows they're
+    // available even if headless auto-discovery is unreliable.
+    ...(agent.kind === "claude" &&
+    (agent.skills ?? []).some((s) => s.type === "package")
+      ? [
+          "## Installed skills",
+          "",
+          "These Claude Agent Skills are installed for this task — invoke them",
+          "when a task touches what they cover:",
+          ...(agent.skills ?? [])
+            .filter((s) => s.type === "package")
+            .map((s) => `- **${s.name}** (\`${installedSkillPath(s)}\`)`),
+          "",
+        ]
+      : []),
+    // ADR-048: tell agents with permissions about their `uai` CLI.
+    ...((agent.permissions?.length ?? 0) > 0
+      ? [
+          "## The uai CLI",
+          "",
+          `You can query and plan through Uai by running \`node ${CONTAINER_CLI_PATH}`,
+          "<command>` in the shell. Your permissions:",
+          `\`${(agent.permissions ?? []).join(", ")}\`. Commands: \`projects list\`,`,
+          "`people list`, `task list`" +
+            (agent.permissions?.includes("tasks.create")
+              ? ", `task create --name <n> --prompt <p> [--projects id,id] [--team id] [--agents handle,handle]`"
+              : "") +
+            (agent.permissions?.includes("memory.write")
+              ? ", `memory save <text>`"
+              : "") +
+            (agent.permissions?.includes("memory.read")
+              ? ", `memory search <query>`"
+              : "") +
+            ".",
+          ...(agent.permissions?.includes("tasks.create")
+            ? [
+                "Tasks you create are DRAFTS — a human reviews and starts them;",
+                "nothing runs (or spends) until then.",
+              ]
+            : []),
+          ...(agent.permissions?.includes("memory.read") ||
+          agent.permissions?.includes("memory.write")
+            ? [
+                `Your memory handle is \`${agent.id}\` — pass \`--as ${agent.id}\` so`,
+                "memories are attributed to you. Recall relevant past work with",
+                "`memory search` before you start; save durable learnings with",
+                "`memory save` when you finish something worth remembering.",
+              ]
+            : []),
+          "",
+        ]
+      : []),
     "## Commit policy",
     "",
     "Commits are SSH-signed automatically (git is configured for it) — do",

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/skills.ts

@@ -0,0 +1,263 @@
+/**
+ * Per-agent skills materialisation (ADR-046).
+ *
+ * A task agent's skills (reference links + documents, resolved cloud-side from
+ * its persona + team) are written to a per-agent `SKILL.md` inside the task
+ * workspace. The workspace is bind-mounted into the container at `/workspace`
+ * (ADR-014), so writing on the host makes the file appear in the container —
+ * no `docker cp`/`exec` needed (same mechanism as attachments).
+ *
+ * Each agent gets its OWN file under `.uai/agents/<id>/` so agents in a shared
+ * container don't see each other's material; the agent's system preamble points
+ * at its file (buildSystemPreamble), which is the reliable cross-CLI delivery
+ * (no dependency on Claude's project-skill auto-discovery in headless mode).
+ *
+ * ADR-047 adds a `package` skill type — a native Claude Agent Skill (folder +
+ * scripts) installed into the container's Claude skills dir via `docker exec`
+ * (git clone or an install command), so Claude discovers it natively. Package
+ * skills are Claude-only and task-level (shared by the container's agents),
+ * NOT written into the flat per-agent SKILL.md.
+ */
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { taskWorkspaceDir } from "./env";
+import { dockerCli } from "./docker-exec";
+import type { RosterAgent, RosterSkill } from "./agents/types";
+
+/** Skills that go into the flat per-agent SKILL.md — link/document only. The
+ *  ADR-047 `package` skills install into the container's skills dir instead. */
+function flatSkills(agent: RosterAgent): RosterSkill[] {
+  return (agent.skills ?? []).filter((s) => s.type !== "package");
+}
+
+/** The container path of an agent's SKILL.md — what the preamble points at. */
+export function containerSkillFile(agentId: string): string {
+  return `/workspace/.uai/agents/${agentId}/SKILL.md`;
+}
+
+/** Render an agent's skills into SKILL.md markdown ("everything in one file"). */
+export function renderSkillMd(agent: RosterAgent): string {
+  const skills = flatSkills(agent);
+  const lines = [
+    `# ${agent.label} — skills`,
+    "",
+    "Reference material prepared for you (links and documents). Consult it when",
+    "a task touches what it covers.",
+    "",
+  ];
+  for (const s of skills) {
+    lines.push(`## ${s.name}`, "");
+    if (s.type === "link") lines.push(`Link: ${s.value}`, "");
+    else lines.push(s.value.trim(), "");
+  }
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+/**
+ * Write an agent's SKILL.md into the task workspace (idempotent: overwrites,
+ * or removes the file when the agent has no skills). Returns the container path
+ * when written, else null. Best-effort — a write failure is swallowed so a
+ * skills problem never blocks the agent from running.
+ */
+export function writeAgentSkills(taskId: string, agent: RosterAgent): string | null {
+  const dir = resolve(taskWorkspaceDir(taskId), ".uai", "agents", agent.id);
+  const file = resolve(dir, "SKILL.md");
+  try {
+    if (flatSkills(agent).length === 0) {
+      rmSync(file, { force: true });
+      return null;
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(file, renderSkillMd(agent));
+    return containerSkillFile(agent.id);
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ADR-047 package skills — native Claude Agent Skills installed in-container.
+// ---------------------------------------------------------------------------
+
+const SKILL_EXEC_TIMEOUT_MS = 180_000; // clones / npx installs can be slow
+
+/**
+ * In-container git-skill installer. Shallow-clones a repo, then works out where
+ * the actual skill(s) live and copies each into `~/.claude/skills/<name>/`:
+ *
+ *   - `$2` (subpath) given → that folder is the skill.
+ *   - else repo root has a SKILL.md → the whole repo is the skill.
+ *   - else search the clone for SKILL.md files → install every skill folder it
+ *     finds (a "collection" repo), each under its own folder name.
+ *   - else exit 3 → the repo isn't a ready skill (needs a build; use cli mode).
+ *
+ * Params are positional argv ($1=url, $2=subpath, $3=name) — never interpolated
+ * into this text — so a repo URL / subpath can't shell-inject. `.git` is
+ * stripped and the temp clone removed; existing skill dirs are left untouched.
+ */
+const GIT_INSTALL_SCRIPT = `
+set -eu
+url="$1"; sub="$2"; name="$3"
+skills="$HOME/.claude/skills"
+mkdir -p "$skills"
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+git clone --depth 1 --quiet "$url" "$tmp/repo"
+repo="$tmp/repo"
+install_one() {
+  src="$1"; dest="$skills/$2"
+  if [ -e "$dest" ]; then echo "skip $2"; return 0; fi
+  if [ ! -f "$src/SKILL.md" ]; then echo "no-skill-md: $src"; return 1; fi
+  rm -rf "$src/.git"
+  cp -R "$src" "$dest"
+  echo "installed $2"
+}
+if [ -n "$sub" ]; then
+  install_one "$repo/$sub" "$name"
+elif [ -f "$repo/SKILL.md" ]; then
+  install_one "$repo" "$name"
+else
+  n=0
+  while IFS= read -r -d '' md; do
+    d="$(dirname "$md")"
+    if install_one "$d" "$(basename "$d")"; then n=$((n+1)); fi
+  done < <(find "$repo" -maxdepth 4 -name SKILL.md -not -path '*/.git/*' -print0)
+  if [ "$n" -eq 0 ]; then echo "no-skills-found"; exit 3; fi
+fi
+`;
+
+/** A url-safe folder name for a skill (the dir under ~/.claude/skills/). */
+export function skillSlug(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9._-]+/g, "-")
+      .replace(/^[-.]+|[-.]+$/g, "")
+      .slice(0, 64) || "skill"
+  );
+}
+
+/** A short label for an installed package skill (for the preamble note). */
+export function installedSkillPath(s: RosterSkill): string {
+  return s.source === "git"
+    ? `~/.claude/skills/${skillSlug(s.name)}/`
+    : `${s.name} (install command)`;
+}
+
+/**
+ * Package skills across the Claude agents in a roster, deduped by folder slug.
+ * Package skills are a Claude Code capability (ADR-047), so Codex agents are
+ * skipped; the install is task-level (one container, shared skills dir).
+ */
+export function collectPackageSkills(agents: RosterAgent[]): RosterSkill[] {
+  const seen = new Set<string>();
+  const out: RosterSkill[] = [];
+  for (const a of agents) {
+    if (a.kind !== "claude") continue;
+    for (const s of a.skills ?? []) {
+      if (s.type !== "package" || !s.value) continue;
+      const key = skillSlug(s.name);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(s);
+    }
+  }
+  return out;
+}
+
+/** Injectable docker-exec seam (mocked in tests). Runs `cmd` in `container` as
+ *  the `node` user, optionally with a working dir. Values are argv, never a
+ *  shell string — a URL/subpath can't shell-inject (cli mode is the exception:
+ *  it runs the author's command via `bash -lc` by design). */
+export type SkillExec = (
+  container: string,
+  cmd: string[],
+  cwd?: string,
+) => Promise<{ status: number | null; stderr: string }>;
+
+const dockerExec: SkillExec = async (container, cmd, cwd) => {
+  const full = ["exec", "-u", "node", ...(cwd ? ["-w", cwd] : []), container, ...cmd];
+  const res = await dockerCli(full, { timeoutMs: SKILL_EXEC_TIMEOUT_MS });
+  return { status: res.status, stderr: res.stderr };
+};
+
+/**
+ * Install a roster's package skills into the task container (ADR-047). Runs at
+ * task-up (after the container is running), mirroring the git-identity/github
+ * `docker exec` setup: best-effort, idempotent, never blocks the agents.
+ *
+ * Returns the human-readable paths of skills that are now present (for the
+ * agents' preamble note). `exec` is injectable for tests.
+ */
+export async function installPackageSkills(
+  taskId: string,
+  agents: RosterAgent[],
+  exec: SkillExec = dockerExec,
+): Promise<string[]> {
+  const pkgs = collectPackageSkills(agents);
+  if (pkgs.length === 0) return [];
+  const container = `task-${taskId}-app-1`;
+  const done: string[] = [];
+
+  for (const s of pkgs) {
+    const slug = skillSlug(s.name);
+    try {
+      if (s.source === "git") {
+        // Idempotent across ensureSessions re-runs: a marker records that the
+        // clone+install already ran, so reconnects don't re-clone.
+        const marker = `/home/node/.claude/skills/.uai-git-${slug}.done`;
+        if ((await exec(container, ["test", "-e", marker])).status === 0) {
+          done.push(installedSkillPath(s));
+          continue;
+        }
+        // subpath is de-fanged against traversal; url/subpath/name reach the
+        // installer as positional argv (never interpolated) — no shell inject.
+        const sub = (s.subpath ?? "").replace(/^[/.]+/, "").replace(/\.\.+/g, "");
+        const r = await exec(container, [
+          "bash",
+          "-lc",
+          GIT_INSTALL_SCRIPT,
+          "uai-skill", // $0
+          s.value, // $1 url
+          sub, // $2 subpath
+          slug, // $3 name
+        ]);
+        if (r.status !== 0) {
+          const why =
+            r.status === 3
+              ? "no SKILL.md found — the repo may need a build (try cli mode)"
+              : r.stderr.trim();
+          console.warn(`[skills] ${taskId}: git skill ${s.name} failed: ${why}`);
+          continue;
+        }
+        await exec(container, ["mkdir", "-p", "/home/node/.claude/skills"]);
+        await exec(container, ["touch", marker]);
+        console.log(`[skills] ${taskId}: installed git skill ${s.name}`);
+        done.push(installedSkillPath(s));
+      } else if (s.source === "cli") {
+        // Idempotent across ensureSessions re-runs (reconnects): a marker file
+        // records that the command already ran, since a CLI install isn't
+        // self-idempotent like `git clone` into an existing dir.
+        const marker = `/home/node/.claude/skills/.uai-cli-${slug}.done`;
+        if ((await exec(container, ["test", "-e", marker])).status === 0) {
+          done.push(installedSkillPath(s));
+          continue;
+        }
+        // The author's CLI drops files into .claude/skills; run it in the repo.
+        const c = await exec(container, ["bash", "-lc", s.value], "/workspace");
+        if (c.status !== 0) {
+          console.warn(`[skills] ${taskId}: install cmd for ${s.name} failed: ${c.stderr.trim()}`);
+          continue;
+        }
+        await exec(container, ["mkdir", "-p", "/home/node/.claude/skills"]);
+        await exec(container, ["touch", marker]);
+        console.log(`[skills] ${taskId}: ran install command for ${s.name}`);
+        done.push(installedSkillPath(s));
+      }
+    } catch (e) {
+      console.warn(`[skills] ${taskId}: package skill ${s.name} errored: ${String(e)}`);
+    }
+  }
+  return done;
+}