@runuai/host 0.5.0 → 0.6.1

package/lib/agents/claude.ts

@@ -187,6 +187,16 @@ const CLAUDE_ARGS = [
   // sandbox. Without this, stream-json has no interactive approver and
   // every Write/Bash silently self-denies.
   "--dangerously-skip-permissions",
+  // MCP servers come from the uai-managed file, EXPLICITLY (ADR-057/061).
+  // Discovered project .mcp.json servers sit behind a per-server approval
+  // that headless --print can never answer ("⏸ Pending approval"), which
+  // silently loaded a stale subset. --mcp-config bypasses the approval
+  // gate; --strict-mcp-config keeps stray host-copied user configs out.
+  // setupMcpTaskConfig always writes this file (empty when no connections)
+  // before sessions spawn.
+  "--mcp-config",
+  "/workspace/.mcp.json",
+  "--strict-mcp-config",
 ];
 
 export class ClaudeSession implements AgentSession {

package/lib/agents/transport.ts

@@ -155,7 +155,24 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
   // before this feature (the workspace is mounted at its host path) and
   // never skews against the host version.
   const runnerInSession = join(sessionDir, "runner.mjs");
-  copyFileSync(runnerScriptPath(), runnerInSession);
+  try {
+    copyFileSync(runnerScriptPath(), runnerInSession);
+  } catch (err) {
+    // Runner asset missing (a packaging miss — the 0.3.0/0.3.1 desktop
+    // builds vendored the agent without runner/). Degrade to legacy pipes:
+    // sessions work, they just don't survive host restarts.
+    console.warn(
+      `[transport] runner unavailable (${err instanceof Error ? err.message : err}) — falling back to direct pipes for ${opts.agentId}`,
+    );
+    const { command, args } = dockerExecArgs(
+      opts.containerName,
+      opts.cli,
+      opts.cliArgs,
+      opts.passEnv ?? [],
+      opts.explicitEnv ?? {},
+    );
+    return new LineProcess({ command, args, debugLabel: opts.debugLabel });
+  }
 
   const envArgs: string[] = [];
   for (const name of opts.passEnv ?? []) {

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,
-      preview_env, locked_at, started_at, ended_at
+      preview_env, owner_org_id, shared_files, 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,
-      @preview_env, @locked_at, @started_at, @ended_at
+      @preview_env, @owner_org_id, @shared_files, @locked_at, @started_at, @ended_at
     )`,
   ).run(task);
 }
@@ -167,6 +167,8 @@ interface CommandTaskRow {
   code_server_port: number | null;
   preview_ports: string;
   preview_env: string | null;
+  owner_org_id: string | null;
+  shared_files: string | null;
   locked_at: number | null;
   started_at: number | null;
   ended_at: number | null;
@@ -195,6 +197,8 @@ function withRuntime(
     code_server_port: runtime?.codeServerPort ?? null,
     preview_ports: runtime?.previewPorts ?? "[]",
     preview_env: task.previewEnv ? JSON.stringify(task.previewEnv) : null,
+    owner_org_id: task.ownerOrgId ?? null,
+    shared_files: task.sharedFiles ?? null,
     locked_at: runtime?.lockedAt ?? null,
     started_at: runtime?.startedAt ?? null,
     ended_at: runtime?.endedAt ?? null,
@@ -219,6 +223,8 @@ function runtimeTask(taskId: string, runtime: HostTask | null): CommandTaskRow {
     code_server_port: runtime?.codeServerPort ?? null,
     preview_ports: runtime?.previewPorts ?? "[]",
     preview_env: null,
+    owner_org_id: null,
+    shared_files: null,
     locked_at: runtime?.lockedAt ?? null,
     started_at: runtime?.startedAt ?? null,
     ended_at: runtime?.endedAt ?? null,
@@ -266,6 +272,8 @@ CREATE TABLE IF NOT EXISTS uai_tasks (
   code_server_port integer,
   preview_ports text NOT NULL DEFAULT '[]',
   preview_env text,
+  owner_org_id text,
+  shared_files text,
   pr_url text,
   locked_at integer,
   started_at integer,

package/lib/mcp-gateway.ts

@@ -275,13 +275,14 @@ const MERGE_MCP_JSON = `
 const fs = require("fs");
 const p = "/workspace/.mcp.json";
 let j = {};
-try { j = JSON.parse(fs.readFileSync(p, "utf8")); } catch {}
+let existed = true;
+try { j = JSON.parse(fs.readFileSync(p, "utf8")); } catch { existed = false; }
 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");
+if (changed || !existed) fs.writeFileSync(p, JSON.stringify(j, null, 2) + "\\n");
 `.trim();
 
 function shellQuote(value: string): string {
@@ -300,7 +301,9 @@ export async function setupMcpTaskConfig(
   connections: TaskMcpConnection[],
   hasCodex: boolean,
 ): Promise<void> {
-  if (connections.length === 0) return;
+  // No early return on empty: the claude adapter passes
+  // `--mcp-config /workspace/.mcp.json` unconditionally (ADR-057), so the
+  // file must exist — an empty mcpServers map — even with no connections.
   try {
     const acl = ensureTaskGatewayAcl(taskId, connections);
     const urlFor = (slug: string): string =>

package/lib/orchestrator.ts

@@ -100,6 +100,8 @@ interface Channel {
   humans: ChannelHuman[];
   /** ADR-053: wire the Playwright MCP browser at session start. */
   browserTesting: boolean;
+  /** ADR-062: shared-files mount mode ("off" | "ro" | "rw") for the preamble. */
+  sharedFiles: string;
   /** 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 —
@@ -180,6 +182,7 @@ class Orchestrator {
     }
     channel.humans = spec.humans ?? [];
     channel.browserTesting = spec.browserTesting === true;
+    channel.sharedFiles = spec.sharedFiles ?? "ro";
     channel.mcpConnections = spec.mcpConnections ?? [];
     for (const agent of channel.roster) {
       channel.preambles.set(
@@ -193,6 +196,7 @@ class Orchestrator {
           spec.branch,
           channel.humans,
           channel.browserTesting,
+          channel.sharedFiles,
         ),
       );
     }
@@ -220,6 +224,7 @@ class Orchestrator {
           spec.branch,
           spec.humans,
           spec.browserTesting,
+          spec.sharedFiles ?? "ro",
         ),
       );
       // ADR-046: materialise this agent's skills to its per-agent SKILL.md in
@@ -249,6 +254,7 @@ class Orchestrator {
       respawnLastAt: new Map(),
       humans: spec.humans ?? [],
       browserTesting: spec.browserTesting === true,
+      sharedFiles: spec.sharedFiles ?? "ro",
       mcpConnections: spec.mcpConnections ?? [],
       spawning: new Set(),
     };
@@ -309,6 +315,7 @@ class Orchestrator {
   private async ensureMcpConfig(channel: Channel): Promise<void> {
     const fingerprint = JSON.stringify(channel.mcpConnections.map((c) => c.id));
     if (channel.mcpConfigFingerprint === fingerprint) return;
+    const hadPrevious = channel.mcpConfigFingerprint !== undefined;
     channel.mcpConfigFingerprint = fingerprint;
     await setupMcpTaskConfig(
       channel.taskId,
@@ -316,6 +323,41 @@ class Orchestrator {
       channel.mcpConnections,
       channel.roster.some((a) => a.kind === "codex"),
     );
+    // Agent CLIs read MCP servers once, at process start — and durable
+    // sessions (ADR-061) make processes long-lived, so without this a
+    // connection added mid-task stays invisible indefinitely. Recycle IDLE
+    // sessions so the change actually reaches the agents; busy agents keep
+    // their turn (and in-memory context) and pick it up on a later change or
+    // natural respawn. Trade-off: a recycled agent loses its in-memory
+    // context and is re-briefed from chat — same as any respawn, and better
+    // than never seeing the connection the user just added. Skipped on the
+    // channel's first fingerprint (sessions just spawned with this config).
+    if (hadPrevious) await this.recycleIdleSessions(channel);
+  }
+
+  /** Close + respawn every session with no open turn (MCP set changed). */
+  private async recycleIdleSessions(channel: Channel): Promise<void> {
+    let recycled = 0;
+    for (const [agentId, session] of [...channel.sessions]) {
+      if (channel.openTurns.has(agentId)) continue; // never mid-turn
+      if (channel.spawning.has(agentId)) continue;
+      channel.sessions.delete(agentId);
+      try {
+        // close() flips the adapter's `closed` flag first, so the session's
+        // exit is suppressed — no budget increment, no agent.exit noise, no
+        // race with the respawn below (recoverClaudeAgent's pattern).
+        await session.close();
+      } catch {
+        // Already dead — close is idempotent for our adapters.
+      }
+      recycled += 1;
+    }
+    if (recycled > 0) {
+      console.log(
+        `[orchestrator] ${channel.taskId}: recycled ${recycled} idle session(s) for MCP config change`,
+      );
+      await this.reconcileSessions(channel);
+    }
   }
 
   /** Spawn sessions for roster agents added after the initial start. */
@@ -951,6 +993,7 @@ export function buildSystemPreamble(
   taskBranch: string,
   humans?: ChannelHuman[],
   browserTesting?: boolean,
+  sharedFiles?: string,
 ): string {
   const channelList = roster
     .map((a) =>
@@ -1091,6 +1134,31 @@ 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-062: shared files — only when this container actually carries the
+    // mounts (task-up drops a marker; pre-feature containers have none).
+    ...(sharedFiles &&
+    sharedFiles !== "off" &&
+    existsSync(join(workspacePath, ".uai", "files-mounted"))
+      ? [
+          "## Shared files",
+          "",
+          `Non-code files (${sharedFiles === "rw" ? "read-write" : "READ-ONLY"} for this task):`,
+          "- `/workspace/files/org` — the org's shared files (logos, specs,",
+          "  datasets), visible to every task in the org on this host.",
+          "- `/workspace/files/me` — the task owner's personal files, shared",
+          "  across their tasks on this host.",
+          ...(sharedFiles === "rw"
+            ? [
+                "When producing artifacts for humans, write them here (use a",
+                "subdirectory named after the task to avoid collisions).",
+              ]
+            : [
+                "Read-only here: to hand a file back, use the chat attachment",
+                "flow instead.",
+              ]),
+          "",
+        ]
+      : []),
     // 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")

package/lib/shared-files.ts

@@ -0,0 +1,156 @@
+/**
+ * ADR-062 shared files — host-side handler for the `filesOp` bridge command.
+ * Two roots per host: org files (per host+org) and personal files (per
+ * host+user), both under <workspaceRoot>/shared/. The cloud is a window
+ * only; this module is the sole writer host-side.
+ *
+ * SECURITY: the cloud relays paths from browsers, and containers mount these
+ * same dirs — every path is treated as hostile. Two gates on every op:
+ * `resolveInsideRoot` (relative-only, ".."-free, resolved-prefix check) and
+ * `assertRealInsideRoot` (realpath containment, so a symlink the container
+ * planted inside a rw mount cannot point ops outside the root).
+ */
+
+import { promises as fsp } from "node:fs";
+import { dirname, join, normalize, resolve, sep } from "node:path";
+
+import type { FilesEntry, FilesOpInput, FilesOpValue } from "../src/protocol";
+import { env } from "./env";
+
+/** Max bytes returned per read chunk (base64 expands ~4/3; WS cap is 16MB). */
+const MAX_READ_CHUNK = 4 * 1024 * 1024;
+/** Max bytes accepted per write chunk. */
+const MAX_WRITE_CHUNK = 8 * 1024 * 1024;
+/** Max entries returned by a single list. */
+const MAX_LIST_ENTRIES = 2_000;
+
+/**
+ * Filesystem-safe directory name for an org/user id. Personal org ids are
+ * `personal:<userId>` — the colon breaks docker's short-syntax bind spec
+ * (src:dst:mode), so it is mapped to "_". MUST stay in lockstep with the
+ * identical mapping in scripts/agent/task-up.sh (shared_fs_name).
+ */
+export function sharedDirName(id: string): string {
+  return id.replace(/:/g, "_");
+}
+
+export function sharedRoot(scope: "org" | "me", orgId: string, userId: string): string {
+  return scope === "org"
+    ? resolve(env.workspaceRoot, "shared", "orgs", sharedDirName(orgId))
+    : resolve(env.workspaceRoot, "shared", "users", sharedDirName(userId));
+}
+
+function resolveInsideRoot(root: string, relPath: string): string {
+  // Relative paths only — an absolute path is rejected, never reinterpreted.
+  if (/^[/\\]/.test(relPath) || /^[A-Za-z]:/.test(relPath)) {
+    throw new Error("invalid path");
+  }
+  const cleaned = normalize(relPath);
+  if (
+    cleaned.split(/[/\\]/).some((seg) => seg === "..") ||
+    cleaned.includes("\0")
+  ) {
+    throw new Error("invalid path");
+  }
+  const target = resolve(root, cleaned);
+  if (target !== root && !target.startsWith(root + sep)) {
+    throw new Error("invalid path");
+  }
+  return target;
+}
+
+/**
+ * String containment (resolveInsideRoot) can't see symlinks the container
+ * planted inside a rw mount — `root/evil → /` would pass it. Walk up from
+ * the target to its deepest EXISTING ancestor, realpath it, and require the
+ * REAL location to stay inside the real root (ADR-062 "no symlink escapes").
+ */
+async function assertRealInsideRoot(root: string, target: string): Promise<void> {
+  const realRoot = await fsp.realpath(root);
+  let probe = target;
+  for (;;) {
+    try {
+      const real = await fsp.realpath(probe);
+      if (real !== realRoot && !real.startsWith(realRoot + sep)) {
+        throw new Error("invalid path");
+      }
+      return;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+      const parent = dirname(probe);
+      if (parent === probe) throw new Error("invalid path");
+      probe = parent;
+    }
+  }
+}
+
+export async function handleFilesOp(input: FilesOpInput): Promise<FilesOpValue> {
+  if (!input.orgId && input.scope === "org") throw new Error("missing orgId");
+  if (!input.userId && input.scope === "me") throw new Error("missing userId");
+  const root = sharedRoot(input.scope, input.orgId, input.userId);
+  await fsp.mkdir(root, { recursive: true });
+  const target = resolveInsideRoot(root, input.path ?? "");
+  await assertRealInsideRoot(root, target);
+
+  switch (input.op) {
+    case "list": {
+      const names = await fsp.readdir(target);
+      const entries: FilesEntry[] = [];
+      for (const name of names.slice(0, MAX_LIST_ENTRIES)) {
+        try {
+          const st = await fsp.lstat(join(target, name));
+          entries.push({
+            name,
+            dir: st.isDirectory(),
+            size: st.isDirectory() ? 0 : st.size,
+            mtimeMs: st.mtimeMs,
+          });
+        } catch {
+          // Raced deletion — skip.
+        }
+      }
+      entries.sort((a, b) =>
+        a.dir === b.dir ? a.name.localeCompare(b.name) : a.dir ? -1 : 1,
+      );
+      return { entries };
+    }
+    case "read": {
+      const st = await fsp.stat(target);
+      if (st.isDirectory()) throw new Error("is a directory");
+      const offset = Math.max(0, input.offset ?? 0);
+      const length = Math.min(input.length ?? MAX_READ_CHUNK, MAX_READ_CHUNK);
+      const fh = await fsp.open(target, "r");
+      try {
+        const buf = Buffer.alloc(Math.min(length, Math.max(0, st.size - offset)));
+        const { bytesRead } = await fh.read(buf, 0, buf.length, offset);
+        return {
+          dataBase64: buf.subarray(0, bytesRead).toString("base64"),
+          size: st.size,
+          eof: offset + bytesRead >= st.size,
+        };
+      } finally {
+        await fh.close();
+      }
+    }
+    case "write": {
+      if (target === root) throw new Error("invalid path");
+      const data = Buffer.from(input.dataBase64 ?? "", "base64");
+      if (data.length > MAX_WRITE_CHUNK) throw new Error("chunk too large");
+      await fsp.mkdir(resolve(target, ".."), { recursive: true });
+      await fsp.writeFile(target, data, { flag: input.append ? "a" : "w" });
+      return {};
+    }
+    case "mkdir": {
+      if (target === root) throw new Error("invalid path");
+      await fsp.mkdir(target, { recursive: true });
+      return {};
+    }
+    case "delete": {
+      if (target === root) throw new Error("invalid path");
+      await fsp.rm(target, { recursive: true, force: true });
+      return {};
+    }
+    default:
+      throw new Error(`unknown op: ${String(input.op)}`);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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

@@ -121,6 +121,28 @@ fi
 
 mkdir -p "$task_workspace"
 
+# ADR-062 shared files: two host-resident roots mounted into the container
+# when the task's mode isn't "off". Created here so Docker doesn't create
+# them root-owned at mount time. Mode defaults to ro; org mount only when
+# the cloud sent an org id (older clouds won't).
+shared_files_mode=$(jq -r '.[0].shared_files // "ro"' <<<"$task_json")
+shared_owner_org=$(jq -r '.[0].owner_org_id // ""' <<<"$task_json")
+shared_owner_user=$(jq -r '.[0].owner_user_id // ""' <<<"$task_json")
+# Colons break docker's src:dst:mode bind syntax, and personal org ids are
+# "personal:<userId>" — map ":" to "_". MUST match sharedDirName() in
+# host-agent/lib/shared-files.ts.
+shared_owner_org=$(printf '%s' "$shared_owner_org" | tr ':' '_')
+shared_owner_user=$(printf '%s' "$shared_owner_user" | tr ':' '_')
+shared_root="$UAI_WORKSPACE_ROOT/shared"
+if [ "$shared_files_mode" != "off" ]; then
+  [ -n "$shared_owner_org" ] && mkdir -p "$shared_root/orgs/$shared_owner_org"
+  [ -n "$shared_owner_user" ] && mkdir -p "$shared_root/users/$shared_owner_user"
+  # Marker for the preamble: only containers that actually carry the mounts
+  # get the "## Shared files" briefing (pre-feature containers don't).
+  mkdir -p "$task_workspace/.uai"
+  : > "$task_workspace/.uai/files-mounted"
+fi
+
 # Iterate using jq -c so each project is a single JSON object per line.
 # Bash 3.2 friendly: a while-read loop rather than mapfile/readarray.
 while IFS= read -r project_obj; do
@@ -313,6 +335,20 @@ fi
   # ADR-053: host-wide Playwright browser cache. Always mounted (harmless
   # when browser testing is off); Chromium downloads once per HOST.
   printf '      - "%s:/opt/pw-browsers"\n' "$PW_VOLUME"
+  # ADR-062 shared files (org + personal) at /workspace/files/{org,me};
+  # ro/rw fixed here for the container's lifetime.
+  if [ "$shared_files_mode" != "off" ]; then
+    shared_suffix=""
+    [ "$shared_files_mode" = "ro" ] && shared_suffix=":ro"
+    if [ -n "$shared_owner_org" ]; then
+      printf '      - "%s/orgs/%s:/workspace/files/org%s"\n' \
+        "$shared_root" "$shared_owner_org" "$shared_suffix"
+    fi
+    if [ -n "$shared_owner_user" ]; then
+      printf '      - "%s/users/%s:/workspace/files/me%s"\n' \
+        "$shared_root" "$shared_owner_user" "$shared_suffix"
+    fi
+  fi
   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) —

package/src/index.ts

@@ -1,5 +1,6 @@
 import { agent, AgentError } from "../lib/agent";
 import { cloneRepo } from "../lib/repo-clone";
+import { handleFilesOp } from "../lib/shared-files";
 import { getOrchestrator } from "../lib/orchestrator";
 import { storeTaskCliSecret } from "../lib/agent-cli";
 import { setupTaskGithub, clearRefresh } from "../lib/github-tokens";
@@ -308,6 +309,15 @@ export const hostCommands: HostCommands = {
     }
   },
 
+  async filesOp(ctx, input) {
+    logCommand(ctx, "filesOp", input.op, `${input.scope}:${input.path}`);
+    try {
+      return ok(await handleFilesOp(input));
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
   async channelInterrupt(ctx, taskId, agentId) {
     logCommand(ctx, "channelInterrupt", taskId, agentId);
     try {

package/src/main.ts

@@ -84,6 +84,7 @@ import {
   type TaskDiffInput,
   type TaskDownInput,
   type TaskLaunchInput,
+  FilesOpInput,
 } from "./protocol";
 
 const PING_INTERVAL_MS = 15_000;
@@ -875,6 +876,8 @@ function dispatchCommand(
         ctx,
         expectAttachmentReadInput(args, 0),
       );
+    case "filesOp":
+      return hostCommands.filesOp(ctx, expectFilesOpInput(args, 0));
     case "channelInterrupt":
       return hostCommands.channelInterrupt(
         ctx,
@@ -1123,6 +1126,7 @@ function isHostCommand(command: string): command is keyof HostCommands {
     "taskDiff",
     "attachmentWrite",
     "attachmentRead",
+    "filesOp",
     "channelInterrupt",
     "appendTranscript",
     "previewEnsure",
@@ -1277,6 +1281,37 @@ function expectAttachmentReadInput(
   };
 }
 
+/** ADR-062: the THIRD whitelist for filesOp — op/scope enums, relative path
+ *  only (containment is re-checked in lib/shared-files.ts, the final gate). */
+function expectFilesOpInput(args: unknown[], index: number): FilesOpInput {
+  const input = expectRecord(args[index], "files op input");
+  const op = expectStringValue(input.op, "op");
+  if (!["list", "read", "write", "mkdir", "delete"].includes(op)) {
+    throw new Error(`invalid files op: ${op}`);
+  }
+  const scope = expectStringValue(input.scope, "scope");
+  if (scope !== "org" && scope !== "me") {
+    throw new Error(`invalid files scope: ${scope}`);
+  }
+  const out: FilesOpInput = {
+    op: op as FilesOpInput["op"],
+    hostId: typeof input.hostId === "string" ? input.hostId : "",
+    scope,
+    orgId: typeof input.orgId === "string" ? input.orgId : "",
+    userId: typeof input.userId === "string" ? input.userId : "",
+    path: typeof input.path === "string" ? input.path : "",
+  };
+  if (typeof input.offset === "number" && Number.isFinite(input.offset)) {
+    out.offset = input.offset;
+  }
+  if (typeof input.length === "number" && Number.isFinite(input.length)) {
+    out.length = input.length;
+  }
+  if (typeof input.dataBase64 === "string") out.dataBase64 = input.dataBase64;
+  if (input.append === true) out.append = true;
+  return out;
+}
+
 function expectChannelEnsureInput(
   args: unknown[],
   index: number,
@@ -1334,6 +1369,14 @@ function expectChannelEnsureInput(
     });
     if (connections.length > 0) out.mcpConnections = connections;
   }
+  // ADR-062: shared-files mode for the preamble "## Files" section.
+  if (
+    input.sharedFiles === "off" ||
+    input.sharedFiles === "ro" ||
+    input.sharedFiles === "rw"
+  ) {
+    out.sharedFiles = input.sharedFiles;
+  }
   return out;
 }
 
@@ -1373,6 +1416,14 @@ function expectTaskCommandTask(value: unknown): TaskCommandTask {
     }
     if (Object.keys(pe).length > 0) out.previewEnv = pe;
   }
+  if (typeof row.ownerOrgId === "string") out.ownerOrgId = row.ownerOrgId;
+  if (
+    row.sharedFiles === "off" ||
+    row.sharedFiles === "ro" ||
+    row.sharedFiles === "rw"
+  ) {
+    out.sharedFiles = row.sharedFiles;
+  }
   return out;
 }
 

package/src/protocol.ts

@@ -144,6 +144,10 @@ export interface TaskCommandTask {
    * `urlEnv` and the cloud has a preview base domain configured.
    */
   previewEnv?: Record<string, string>;
+  /** ADR-062: owning org — locates the org shared-files root on the host. */
+  ownerOrgId?: string;
+  /** ADR-062: shared-files mount mode ("off" | "ro" | "rw"; default "ro"). */
+  sharedFiles?: string;
 }
 
 /**
@@ -203,6 +207,9 @@ export interface ChannelEnsureInput {
   /** ADR-057: the owner's usable MCP connections (policy "on", connected,
    *  remote). The host writes gateway-URL MCP configs at session start. */
   mcpConnections?: Array<{ id: string; slug: string }>;
+  /** ADR-062: shared-files mount mode — drives the preamble "## Files"
+   *  section ("off" | "ro" | "rw"). */
+  sharedFiles?: string;
   globalContext?: string;
   projects: Array<{ slug: string; defaultPrompt: string }>;
   branch: string;
@@ -256,6 +263,39 @@ export interface TaskDiffResult {
   repos: TaskDiffRepo[];
 }
 
+/** ADR-062 shared-files op (cloud → host). Scope picks the root:
+ *  "org" → <workspaceRoot>/shared/orgs/<orgId>, "me" → shared/users/<userId>. */
+export interface FilesOpInput {
+  op: "list" | "read" | "write" | "mkdir" | "delete";
+  /** Routing only (cloud→bridge): which host's roots to touch. */
+  hostId: string;
+  scope: "org" | "me";
+  orgId: string;
+  userId: string;
+  /** Relative path inside the scope root ("" = root). */
+  path: string;
+  /** read: byte offset; default 0. */
+  offset?: number;
+  /** read: max bytes per chunk (host caps it regardless). */
+  length?: number;
+  /** write: base64 chunk. */
+  dataBase64?: string;
+  /** write: append to existing (true) or truncate/create (false/absent). */
+  append?: boolean;
+}
+
+export interface FilesEntry {
+  name: string;
+  dir: boolean;
+  size: number;
+  mtimeMs: number;
+}
+
+export type FilesOpValue =
+  | { entries: FilesEntry[] } // list
+  | { dataBase64: string; size: number; eof: boolean } // read
+  | Record<string, never>; // write / mkdir / delete
+
 export interface HostCommands {
   taskUp(
     ctx: CommandContext,
@@ -321,6 +361,13 @@ export interface HostCommands {
     ctx: CommandContext,
     input: { taskId: string; filename: string },
   ): Promise<HostCommandResult<{ dataBase64: string }>>;
+  /** ADR-062 shared files — list/read/write/mkdir/delete inside the host's
+   *  org or personal shared root. Paths are RELATIVE; the host normalizes and
+   *  rejects escapes. Reads/writes are chunked base64 (offset/append). */
+  filesOp(
+    ctx: CommandContext,
+    input: FilesOpInput,
+  ): Promise<HostCommandResult<FilesOpValue>>;
   channelInterrupt(
     ctx: CommandContext,
     taskId: string,