@runuai/host 0.8.45 → 0.9.1

package/README.md

@@ -18,7 +18,11 @@ One process does two things:
 ## Requirements
 
 - **Docker** (running) — tasks are containers.
-- **Node ≥ 20.**
+- **Node 22, 24, 25 or 26; Node 24 LTS recommended.** Those are the majors the
+  pinned SQLite dependency ships a prebuilt binary for. Tested release majors
+  are 22, 24 and 26; Node 25 warns and continues when the binding loads.
+  Anything else — including Node 20, 21 and 23 — has to compile from source
+  and fails on a machine without a C++ toolchain.
 
 ## Install & enroll
 

package/bin/uai-host.mjs

@@ -5,10 +5,125 @@
  * The host ships TypeScript source and runs it through tsx — no build step —
  * so every runtime path (drizzle migrations, scripts/agent/*.sh, the
  * images/standard build context) resolves off its source file exactly as in
- * dev. This shim registers tsx's ESM loader, then hands off to src/cli.ts.
- * argv passes straight through: src/cli.ts reads process.argv.slice(2).
+ * dev. This shim verifies that the native SQLite dependency can load,
+ * registers tsx's ESM loader, then hands off to src/cli.ts. argv passes
+ * straight through: src/cli.ts reads process.argv.slice(2).
  */
-import { register } from "tsx/esm/api";
 
-register();
-await import(new URL("../src/cli.ts", import.meta.url).href);
+// A builtin — importing it here loads nothing of the app and no tsx.
+import { stripVTControlCharacters } from "node:util";
+
+const minimumNodeMajor = 20;
+const testedNodeMajors = new Set([22, 24, 26]);
+const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "", 10);
+
+/**
+ * The commands that BOOT the agent, and so genuinely need the native module.
+ *
+ * Everything else — `logs`, `status`, `open`, `stop`, `uninstall`, `setup`,
+ * `--help` — only inspects or dismantles an install, and all of them were
+ * verified to run with the module unloadable. Failing them on a broken probe
+ * takes away the diagnostic path (`logs`) and the recovery path (`stop`,
+ * `uninstall`) from precisely the user the probe exists to help: they are told
+ * to reinstall, and cannot remove the wedged service first.
+ *
+ * `start`/`restart`/`install` don't open the database in THIS process — they
+ * hand off to launchd/systemd — but they all end in a running agent, so
+ * failing fast here beats a crash-looping service the user then has to chase
+ * through the log.
+ */
+const commandsNeedingNativeSqlite = new Set([
+  "run",
+  "start",
+  "restart",
+  "install",
+]);
+
+/**
+ * Of those, the ones whose `--dry-run` prints a plan and boots nothing.
+ *
+ * `run` is deliberately absent: it ignores the flag and boots regardless, so
+ * exempting on the flag alone would wave through the one command that really
+ * does need the module.
+ */
+const dryRunnableCommands = new Set(["start", "restart", "install"]);
+
+/** Whether this invocation will actually end in a running agent. */
+function needsNativeSqlite(argv) {
+  const command = argv[2] ?? "";
+  if (!commandsNeedingNativeSqlite.has(command)) return false;
+  return !(dryRunnableCommands.has(command) && argv.includes("--dry-run"));
+}
+
+function errorSummary(error) {
+  // Native loader errors can carry ANSI colour, which lands as escape noise in
+  // a log file or a non-TTY pipe. Strip it before picking the line to show.
+  const message = stripVTControlCharacters(
+    error instanceof Error ? error.message : String(error),
+  );
+  const firstLine = message
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean);
+  if (!firstLine) return "unknown error";
+  return firstLine.length > 240 ? `${firstLine.slice(0, 237)}...` : firstLine;
+}
+
+function nativeRecoveryAdvice() {
+  return process.versions.electron
+    ? "Update or reinstall the Uai Host desktop app and retry."
+    : "Reinstall @runuai/host; if that still fails, switch to Node.js 24 LTS and reinstall.";
+}
+
+async function probeNativeSqlite() {
+  try {
+    const { default: Database } = await import("better-sqlite3");
+    const database = new Database(":memory:");
+    database.close();
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+async function main() {
+  if (!Number.isInteger(nodeMajor) || nodeMajor < minimumNodeMajor) {
+    console.error(
+      `uai-host requires Node.js 20 or newer; found v${process.versions.node}. Install Node.js 24 LTS and retry.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const sqliteProbe = await probeNativeSqlite();
+  if (!sqliteProbe.ok) {
+    const detail =
+      `uai-host could not load its native SQLite module on Node.js v${process.versions.node}. ` +
+      `${nativeRecoveryAdvice()} Cause: ${errorSummary(sqliteProbe.error)}`;
+    if (needsNativeSqlite(process.argv)) {
+      console.error(detail);
+      process.exitCode = 1;
+      return;
+    }
+    // Still say it — a broken module IS why their service is down — but let
+    // the command through so they can read the log and uninstall.
+    console.warn(`${detail} Continuing — this command does not need it.`);
+  }
+
+  // Only when the probe actually succeeded — otherwise this contradicts the
+  // warning just printed, telling the user SQLite loaded right after saying it
+  // could not.
+  if (sqliteProbe.ok && !testedNodeMajors.has(nodeMajor)) {
+    console.warn(
+      `uai-host has not been tested on Node.js v${process.versions.node}; continuing because native SQLite loaded. Node.js 24 LTS is recommended.`,
+    );
+  }
+
+  // Keep this import behind the native probe: the preflight must run in plain
+  // Node before tsx (and the TypeScript application graph) is loaded.
+  const { register } = await import("tsx/esm/api");
+  register();
+  await import(new URL("../src/cli.ts", import.meta.url).href);
+}
+
+await main();

package/lib/agents/claude.ts

@@ -52,6 +52,13 @@ const CLAUDE_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
 // High is the default reasoning level. Update alongside CLAUDE_EFFORTS.
 const CLAUDE_DEFAULT_EFFORT = "high";
 
+// ADR-083: cheap defaults apply at the enforcement boundary as well as in the
+// picker. Explicit per-agent choices still win; an API client that omits them
+// must not accidentally run the communicator on Claude's costly account
+// defaults merely because it bypassed the web recommendation button.
+const CLAUDE_COMMUNICATOR_MODEL = "haiku";
+const CLAUDE_COMMUNICATOR_EFFORT = "low";
+
 // ---------------------------------------------------------------------------
 // Pure protocol mapping — stream-json line → AgentEvent[].
 // ---------------------------------------------------------------------------
@@ -177,7 +184,7 @@ function safeStringify(v: unknown): string {
 // The session.
 // ---------------------------------------------------------------------------
 
-const CLAUDE_ARGS = [
+const CLAUDE_BASE_ARGS = [
   "--print",
   "--input-format",
   "stream-json",
@@ -190,6 +197,10 @@ const CLAUDE_ARGS = [
   // 400s when a later turn sees a changed thinking block, so keep each
   // managed stream-json process in-memory only.
   "--no-session-persistence",
+];
+
+const CLAUDE_FULL_ACCESS_ARGS = [
+  ...CLAUDE_BASE_ARGS,
   // Full tool access, no per-call prompts. Safe here precisely because
   // a uai task runs in a throwaway, isolated container operating on a
   // disposable worktree (ADR-001 / ADR-010) — the container *is* the
@@ -208,6 +219,29 @@ const CLAUDE_ARGS = [
   "--strict-mcp-config",
 ];
 
+/**
+ * ADR-083 communicator profile. This is deliberately an engine-level tool
+ * boundary, not prompt advice: safe mode suppresses project/user extensions,
+ * the explicit tool set contains no shell or mutation primitive, `dontAsk`
+ * denies anything outside it in headless mode, and the empty strict MCP config
+ * prevents a user-installed server from reintroducing a write/deploy tool.
+ */
+const CLAUDE_COMMUNICATOR_ARGS = [
+  ...CLAUDE_BASE_ARGS,
+  "--safe-mode",
+  "--disable-slash-commands",
+  "--no-chrome",
+  "--permission-mode",
+  "dontAsk",
+  "--tools",
+  "Read,Glob,Grep",
+  "--disallowedTools",
+  "Bash,Edit,Write,NotebookEdit,Agent,Task,WebFetch,WebSearch",
+  "--mcp-config",
+  '{"mcpServers":{}}',
+  "--strict-mcp-config",
+];
+
 export class ClaudeSession implements AgentSession {
   readonly agentId: string;
   readonly kind: AgentKind = "claude";
@@ -228,6 +262,7 @@ export class ClaudeSession implements AgentSession {
     agent: RosterAgent;
     containerName: string;
     systemPreamble: string;
+    executionProfile?: "communicator";
     agentEnv?: Record<string, string>;
   }) {
     this.agentId = args.agent.id;
@@ -236,19 +271,31 @@ export class ClaudeSession implements AgentSession {
     // project's defaultPrompt) is passed as a real system prompt via
     // `--append-system-prompt`, so it applies to every turn — not
     // smuggled into the first user message.
-    const cliArgs = [...CLAUDE_ARGS];
+    const cliArgs = [
+      ...(args.executionProfile === "communicator"
+        ? CLAUDE_COMMUNICATOR_ARGS
+        : CLAUDE_FULL_ACCESS_ARGS),
+    ];
     if (process.env.UAI_CLAUDE_INCLUDE_PARTIAL_MESSAGES === "1") {
       cliArgs.push("--include-partial-messages");
     }
-    // The agent's model (when set) selects which Claude model the CLI
-    // drives. Without it the CLI uses the account default.
-    if (args.agent.model) {
-      cliArgs.push("--model", args.agent.model);
+    // Explicit task configuration wins; the communicator uses its declared
+    // fast/cheap defaults when the task left either choice unspecified.
+    const model =
+      args.agent.model ??
+      (args.executionProfile === "communicator"
+        ? CLAUDE_COMMUNICATOR_MODEL
+        : undefined);
+    if (model) {
+      cliArgs.push("--model", model);
     }
-    // The agent's effort (when set) selects the CLI reasoning level. Without
-    // it the CLI uses its own default.
-    if (args.agent.effort) {
-      cliArgs.push("--effort", args.agent.effort);
+    const effort =
+      args.agent.effort ??
+      (args.executionProfile === "communicator"
+        ? CLAUDE_COMMUNICATOR_EFFORT
+        : undefined);
+    if (effort) {
+      cliArgs.push("--effort", effort);
     }
     if (args.systemPreamble.trim().length > 0) {
       cliArgs.push("--append-system-prompt", args.systemPreamble);
@@ -261,7 +308,10 @@ export class ClaudeSession implements AgentSession {
     // ADR-061: durable by default — the CLI is owned by an in-container
     // runner and survives host restarts (attach resumes it); legacy pipes
     // behind UAI_DURABLE_SESSIONS=0. Claude is host-side stateless, so a
-    // live runner can be re-attached (allowAttach).
+    // live runner can be re-attached (allowAttach). The communicator profile
+    // is the exception: attach is keyed only by task + agent identity, not by
+    // execution profile, so a pre-existing full-access runner must be stopped
+    // and replaced rather than inherited across this security boundary.
     this.proc = createAgentTransport({
       taskId: args.taskId,
       agentId: this.agentId,
@@ -270,7 +320,7 @@ export class ClaudeSession implements AgentSession {
       cliArgs,
       passEnv: ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
       explicitEnv: args.agentEnv ?? {},
-      allowAttach: true,
+      allowAttach: args.executionProfile !== "communicator",
       kind: "claude",
       debugLabel: `claude:${this.agentId}`,
     });
@@ -389,6 +439,14 @@ register({
   defaultModel: CLAUDE_DEFAULT_MODEL,
   supportedEfforts: () => [...CLAUDE_EFFORTS],
   defaultEffort: CLAUDE_DEFAULT_EFFORT,
+  executionProfiles: [
+    {
+      id: "communicator",
+      mechanism: "claude-safe-mode-tool-allowlist-v1",
+      defaultModel: CLAUDE_COMMUNICATOR_MODEL,
+      defaultEffort: CLAUDE_COMMUNICATOR_EFFORT,
+    },
+  ],
   // Usable only when a Claude credential is in the env (injected into task
   // containers at task-up). Gates advertisement (ADR-044 P2).
   available: () =>
@@ -397,6 +455,20 @@ register({
         process.env.ANTHROPIC_API_KEY ||
         process.env.ANTHROPIC_AUTH_TOKEN,
     ),
-  create: async ({ taskId, agent, containerName, systemPreamble, agentEnv }) =>
-    new ClaudeSession({ taskId, agent, containerName, systemPreamble, agentEnv }),
+  create: async ({
+    taskId,
+    agent,
+    containerName,
+    systemPreamble,
+    executionProfile,
+    agentEnv,
+  }) =>
+    new ClaudeSession({
+      taskId,
+      agent,
+      containerName,
+      systemPreamble,
+      executionProfile,
+      agentEnv,
+    }),
 });

package/lib/agents/factory.ts

@@ -23,7 +23,7 @@ import "./cursor";
 import "./opencode";
 
 import { agentClisReady } from "../standard-image";
-import { factoryFor } from "./registry";
+import { factoryFor, supportsExecutionProfile } from "./registry";
 import type { AgentSession, AgentSessionFactory } from "./types";
 
 /** Cap the wait on agentClisReady so a spawn can never hang forever if the
@@ -54,6 +54,14 @@ export const realAgentFactory: AgentSessionFactory = {
         `no agent adapter registered for kind "${args.agent.kind}"`,
       );
     }
+    if (
+      args.executionProfile &&
+      !supportsExecutionProfile(args.agent.kind, args.executionProfile)
+    ) {
+      throw new Error(
+        `agent adapter "${args.agent.kind}" cannot enforce execution profile "${args.executionProfile}"`,
+      );
+    }
     // Don't spawn a CLI until the shared-volume agent CLIs are reconciled:
     // at boot the CLI auto-upgrade briefly removes then reinstalls codex/claude,
     // and a resume that races that window dies with "No codex executable found

package/lib/agents/mode.ts

@@ -0,0 +1,57 @@
+/**
+ * Which agent adapters this host runs — `UAI_AGENTS`.
+ *
+ * REAL IS THE DEFAULT. It did not used to be: the check was
+ * `UAI_AGENTS === "real" ? real : mock`, so every value except that one
+ * literal — including unset — silently selected the echo mock. That was a
+ * sane default while the adapters were unproven and the only hosts were the
+ * author's, but it shipped to npm unchanged. A user installs `@runuai/host`,
+ * enrolls, starts a task, and the host looks perfectly healthy while every
+ * agent echoes canned text. Nothing in the logs or `uai-host status` said so.
+ *
+ * The desktop app never hit it because it hardcodes `UAI_AGENTS: "real"`
+ * (apps/host-desktop/src/agent-path.ts) — the npm path had no equivalent, so
+ * the bug was invisible to exactly the people who could reproduce it.
+ *
+ * So: a host runs real agents unless it is explicitly told not to. `mock` is
+ * the opt-in for tests and for dev boxes with no Docker, and an unrecognised
+ * value resolves to `real` with a warning rather than quietly downgrading —
+ * a typo must never cost someone a day of echoed output again.
+ */
+
+export type AgentMode = "real" | "mock";
+
+/** Values that select the in-process echo mock. */
+const MOCK_VALUES = new Set(["mock", "fake", "echo"]);
+/** Values that select the real Claude/Codex adapters (the default). */
+const REAL_VALUES = new Set(["real", "prod", "production"]);
+
+export interface AgentModeResolution {
+  mode: AgentMode;
+  /** Set when the raw value was neither recognised nor empty. */
+  warning?: string;
+}
+
+/**
+ * Resolve `UAI_AGENTS` to a mode. Pure and case/whitespace insensitive so a
+ * stray `UAI_AGENTS=Mock ` from a hand-edited .env.local behaves as written.
+ */
+export function resolveAgentMode(
+  raw: string | undefined = process.env.UAI_AGENTS,
+): AgentModeResolution {
+  const value = (raw ?? "").trim().toLowerCase();
+  if (value === "") return { mode: "real" };
+  if (MOCK_VALUES.has(value)) return { mode: "mock" };
+  if (REAL_VALUES.has(value)) return { mode: "real" };
+  return {
+    mode: "real",
+    warning:
+      `unrecognised UAI_AGENTS=${JSON.stringify(raw)} — running REAL agents. ` +
+      `Use "mock" for the echo agent, or unset it.`,
+  };
+}
+
+/** The mode this process is running in. */
+export function agentMode(): AgentMode {
+  return resolveAgentMode().mode;
+}

package/lib/agents/registry.ts

@@ -32,6 +32,13 @@ export interface RegisteredAdapter {
   supportedEfforts(): string[];
   /** Preferred effort when the user doesn't pick one. */
   defaultEffort?: string;
+  /** Restricted profiles this adapter can enforce by construction. */
+  executionProfiles?: Array<{
+    id: string;
+    mechanism: string;
+    defaultModel?: string;
+    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
@@ -52,6 +59,12 @@ export interface AgentKindCapability {
   defaultModel?: string;
   supportedEfforts: string[];
   defaultEffort?: string;
+  executionProfiles?: Array<{
+    id: string;
+    mechanism: string;
+    defaultModel?: string;
+    defaultEffort?: string;
+  }>;
 }
 
 const adapters = new Map<string, RegisteredAdapter>();
@@ -79,6 +92,15 @@ export function factoryFor(kind: string): AgentSessionFactory | undefined {
   return adapter ? { create: adapter.create } : undefined;
 }
 
+/** Whether the adapter declares an engine-enforced execution profile. */
+export function supportsExecutionProfile(kind: string, profileId: string): boolean {
+  return Boolean(
+    adapters
+      .get(kind)
+      ?.executionProfiles?.some((profile) => profile.id === profileId),
+  );
+}
+
 /**
  * The `agentKinds` capability slice, derived from the registered adapters.
  * Each adapter's `supportedModels()` / `supportedEfforts()` is evaluated here.
@@ -99,6 +121,11 @@ export function capabilities(): AgentKindCapability[] {
     if (adapter.defaultEffort !== undefined) {
       out.defaultEffort = adapter.defaultEffort;
     }
+    if (adapter.executionProfiles && adapter.executionProfiles.length > 0) {
+      out.executionProfiles = adapter.executionProfiles.map((profile) => ({
+        ...profile,
+      }));
+    }
     return out;
   });
 }

package/lib/agents/types.ts

@@ -165,6 +165,9 @@ export interface AgentSessionFactory {
     containerName: string;
     /** Initial briefing — project.defaultPrompt — sent on session start. */
     systemPreamble: string;
+    /** Host-derived restricted execution policy (ADR-083). Never supplied by
+     *  the browser or stored on the roster entry. */
+    executionProfile?: "communicator";
     /** ADR-048: extra per-agent env for the `docker exec` (e.g. this agent's
      *  own UAI_TASK_TOKEN so its `uai` CLI carries only its own permissions). */
     agentEnv?: Record<string, string>;

package/lib/mcp-connections.ts

@@ -98,6 +98,51 @@ async function mcpInitialize(
   });
 }
 
+/** Collapse whitespace and cap length — this text lands in the connect dialog. */
+function oneLine(s: string, max = 300): string {
+  const flat = s.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+/**
+ * The vendor's own explanation for a failed response, so the connect dialog
+ * can show it instead of a bare status code. Vendors bury it in one of a few
+ * shapes — RFC 6750's `error_description`, a bare `error`/`message`, or a
+ * GraphQL-style `errors[]` — so try each, then fall back to the raw body.
+ * Never throws: a missing or unparseable body just means no reason to add.
+ */
+async function failureReason(res: Response): Promise<string | null> {
+  const text = await res.text().catch(() => "");
+  if (!text.trim()) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return oneLine(text);
+  }
+  const body = (parsed ?? {}) as Record<string, unknown>;
+  const errors = body.errors;
+  const first = Array.isArray(errors)
+    ? (errors[0] as Record<string, unknown> | undefined)
+    : undefined;
+  // `error` is a string in some payloads and an object wrapping `message` in
+  // others — New Relic alone returns both shapes plus `errors[]`, depending
+  // on which of its tiers answers. Prefer the descriptive fields; the bare
+  // `error` string ("unauthorized") is the last resort.
+  const nested =
+    typeof body.error === "object" && body.error !== null
+      ? (body.error as Record<string, unknown>)
+      : undefined;
+  const reason = [
+    body.error_description,
+    body.message,
+    first?.message,
+    nested?.message,
+    body.error,
+  ].find((c): c is string => typeof c === "string" && c.trim().length > 0);
+  return oneLine(reason ?? text);
+}
+
 // --- OAuth discovery (RFC 9728 → RFC 8414) -----------------------------------
 
 /** Candidate well-known URLs, path-aware per spec, root fallback last. */
@@ -249,9 +294,25 @@ async function probe(op: Extract<McpOp, { kind: "probe" }>): Promise<McpAck> {
     const header = { headerName: op.headerName, headerValue: op.headerValue };
     const res = await mcpInitialize(op.url, header);
     if (res.status === 401 || res.status === 403) {
-      throw new Error(`the server rejected the token (${res.status})`);
+      // 401 and 403 send you to different fixes, so don't collapse them into
+      // one "rejected" message. 401 is a credential the server did not
+      // recognise — re-check the key. 403 is one it DID recognise and then
+      // refused: the key is fine, but its user lacks permission or the
+      // account is not entitled to this server. Telling someone to re-paste
+      // a working key is the expensive failure here.
+      const lead =
+        res.status === 401
+          ? "the server rejected the token (401)"
+          : "the token was accepted but this server refused the request " +
+            "(403) — the key is likely valid but lacks permission for it";
+      const why = await failureReason(res);
+      throw new Error(why ? `${lead}: ${why}` : lead);
+    }
+    if (!res.ok) {
+      const why = await failureReason(res);
+      const lead = `unexpected response (${res.status})`;
+      throw new Error(why ? `${lead}: ${why}` : lead);
     }
-    if (!res.ok) throw new Error(`unexpected response (${res.status})`);
     db.insert(schema.mcpConnections)
       .values({
         id: op.connectionId,

package/lib/orchestrator.ts

@@ -25,6 +25,7 @@ import { inArray } from "drizzle-orm";
 import { getDb, schema } from "./db";
 import { mockAgentFactory } from "./agents/mock";
 import { realAgentFactory } from "./agents/factory";
+import { resolveAgentMode } from "./agents/mode";
 import {
   type AgentEvent,
   type AgentSession,
@@ -81,6 +82,9 @@ export type HostEventSubscriber = (event: HostEvent) => void;
 interface Channel {
   taskId: string;
   roster: Roster;
+  /** ADR-083: host-derived role assignment for execution-profile enforcement. */
+  mode: "open" | "secretary";
+  secretaryAgentId?: string;
   sessions: Map<string, AgentSession>;
   /** Session-spawn inputs, kept so sessions can be started lazily. */
   containerName: string;
@@ -298,6 +302,33 @@ export class Orchestrator {
   // -- channel lifecycle ----------------------------------------------------
 
   registerChannelSpec(spec: ChannelEnsureInput): void {
+    // Host-side fail closed. The cloud validates this too, but the adapter's
+    // advertised communicator guarantee must not depend on every caller
+    // spelling the id correctly: an unmatched designation would otherwise
+    // make `executionProfileFor` return undefined and spawn a full-access
+    // process in a task explicitly marked Secretary.
+    if (!hasValidSecretarySelection(spec)) {
+      throw new Error(
+        "secretary mode requires exactly one roster agent matching secretaryAgentId",
+      );
+    }
+    const channel = this.channels.get(spec.taskId);
+    const nextMode = spec.mode === "secretary" ? "secretary" : "open";
+    if (
+      channel &&
+      (channel.mode !== nextMode ||
+        (nextMode === "secretary" &&
+          channel.secretaryAgentId !== spec.secretaryAgentId))
+    ) {
+      // v0 makes mode/role creation-time only. More importantly, a live
+      // Open→Secretary rewrite cannot be applied as ordinary roster refresh:
+      // the designated agent may already be a durable full-access process.
+      // Changing these fields without recycling that exact session would
+      // advertise a communicator boundary the running process does not have.
+      throw new Error(
+        "a live channel cannot change secretary mode or designation",
+      );
+    }
     this.channelSpecs.set(spec.taskId, spec);
     if (this.blockedTasks.has(spec.taskId)) return;
     // ADR-049: the cloud re-sends the spec on every message AND right after a
@@ -305,7 +336,6 @@ export class Orchestrator {
     // 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);
   }
 
@@ -334,6 +364,8 @@ export class Orchestrator {
       }
     }
     channel.humans = spec.humans ?? [];
+    channel.mode = spec.mode === "secretary" ? "secretary" : "open";
+    channel.secretaryAgentId = spec.secretaryAgentId;
     channel.browserTesting = spec.browserTesting === true;
     channel.sharedFiles = spec.sharedFiles ?? "ro";
     channel.mcpConnections = spec.mcpConnections ?? [];
@@ -357,6 +389,8 @@ export class Orchestrator {
           channel.humans,
           channel.browserTesting,
           channel.sharedFiles,
+          spec.mode,
+          spec.secretaryAgentId,
         ),
       );
     }
@@ -428,6 +462,8 @@ export class Orchestrator {
           spec.humans,
           spec.browserTesting,
           spec.sharedFiles ?? "ro",
+          spec.mode,
+          spec.secretaryAgentId,
         ),
       );
       // ADR-046: materialise this agent's skills to its per-agent SKILL.md in
@@ -446,6 +482,8 @@ export class Orchestrator {
     const channel: Channel = {
       taskId,
       roster,
+      mode: spec.mode === "secretary" ? "secretary" : "open",
+      secretaryAgentId: spec.secretaryAgentId,
       sessions: new Map(),
       containerName: `task-${taskId.toLowerCase()}-app-1`,
       preambles,
@@ -1162,6 +1200,7 @@ export class Orchestrator {
               agent,
               containerName: channel.containerName,
               systemPreamble: channel.preambles.get(agent.id) ?? "",
+              executionProfile: this.executionProfileFor(channel, agent.id),
               agentEnv: this.accountAgentEnv(
                 channel,
                 agent,
@@ -1185,6 +1224,21 @@ export class Orchestrator {
     }
   }
 
+  /**
+   * The browser stores only the task-level secretary identity. Derive the
+   * restricted adapter profile here so a roster entry can never self-assert a
+   * weaker/stronger execution policy through its JSON payload.
+   */
+  private executionProfileFor(
+    channel: Channel,
+    agentId: string,
+  ): "communicator" | undefined {
+    return channel.mode === "secretary" &&
+      channel.secretaryAgentId === agentId
+      ? "communicator"
+      : undefined;
+  }
+
   /**
    * ADR-076: per-agent exec env = the uai token base + the SELECTED engine
    * account's env. Picks the least-recently-used, non-cooling account for the
@@ -1379,9 +1433,10 @@ export class Orchestrator {
           {
             taskId: channel.taskId,
             agent,
-            containerName: channel.containerName,
-            systemPreamble: channel.preambles.get(agent.id) ?? "",
-            agentEnv: this.accountAgentEnv(
+          containerName: channel.containerName,
+          systemPreamble: channel.preambles.get(agent.id) ?? "",
+          executionProfile: this.executionProfileFor(channel, agent.id),
+          agentEnv: this.accountAgentEnv(
               channel,
               agent,
               agentCliEnv(
@@ -1784,6 +1839,7 @@ export class Orchestrator {
         agent,
         containerName: channel.containerName,
         systemPreamble: channel.preambles.get(agentId) ?? "",
+        executionProfile: this.executionProfileFor(channel, agentId),
         agentEnv: boundAccount
           ? { ...base, ...boundAccount.execEnv }
           : this.accountAgentEnv(channel, agent, base),
@@ -1902,6 +1958,7 @@ export class Orchestrator {
           agent,
           containerName: channel.containerName,
           systemPreamble: channel.preambles.get(agentId) ?? "",
+          executionProfile: this.executionProfileFor(channel, agentId),
           agentEnv: { ...base, ...next.execEnv },
         },
       );
@@ -2095,6 +2152,18 @@ export class Orchestrator {
   }
 }
 
+/** Exact host-wire role validation; never trims or canonicalises agent ids. */
+export function hasValidSecretarySelection(
+  spec: Pick<ChannelEnsureInput, "mode" | "secretaryAgentId" | "agents">,
+): boolean {
+  if (spec.mode !== "secretary") return true;
+  if (!spec.secretaryAgentId) return false;
+  return (
+    spec.agents.filter((agent) => agent.id === spec.secretaryAgentId).length ===
+    1
+  );
+}
+
 // ---------------------------------------------------------------------------
 // `@mention` addressing.
 // ---------------------------------------------------------------------------
@@ -2294,6 +2363,8 @@ export function buildSystemPreamble(
   humans?: ChannelHuman[],
   browserTesting?: boolean,
   sharedFiles?: string,
+  mode?: "open" | "secretary",
+  secretaryAgentId?: string,
 ): string {
   const channelList = roster
     .map((a) =>
@@ -2342,6 +2413,139 @@ export function buildSystemPreamble(
           (p) =>
             `- \`${workspacePath}/${p.slug}\` — git worktree on \`${taskBranch}\``,
         );
+  const isSecretary =
+    mode === "secretary" && secretaryAgentId === agent.id;
+  const transcriptBrief =
+    mode !== "secretary"
+      ? [
+          // Keep open-mode briefing byte-identical to the legacy preamble.
+          "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",
+          "logged at `/workspace/.uai/chat.md`. Read it whenever you need that",
+          "context (e.g. the human shared a file or instruction with another",
+          "agent); it's appended live, so re-read it for the latest.",
+        ]
+      : isSecretary
+        ? [
+            "Because your input is only what you're addressed, you may be missing",
+            "context from messages elsewhere in the channel. Secretary mode keeps",
+            "two live transcripts: the backstage crew conversation is logged at",
+            "`/workspace/.uai/chat.md`, and the frontstage human conversation is",
+            "logged at `/workspace/.uai/chat-front.md`. Read BOTH whenever you need",
+            "to catch up; each is appended live, so re-read them for the latest.",
+          ]
+        : [
+            "Because your input is only what you're addressed, you may be missing",
+            "context from the crew conversation. The backstage transcript — crew",
+            "messages + who wrote them (no tool calls) — is logged at",
+            "`/workspace/.uai/chat.md`. Read it whenever you need that context;",
+            "it's appended live, so re-read it for the latest.",
+          ];
+  const secretaryRoleBrief = isSecretary
+    ? [
+        "## Secretary role",
+        "",
+        "You are the channel's sole human-facing communicator. Answer the human",
+        "directly when the transcripts and read-only inspection are sufficient.",
+        "When crew work is needed, address each recipient by @id with a concrete",
+        "instruction; Uai delivers that instruction backstage. Synthesize the",
+        "crew's replies for the human instead of forwarding a pile of raw updates.",
+        "",
+        "Your communicator execution profile is enforced by the engine: you can",
+        "read and search the workspace, but you cannot edit files, run shell",
+        "commands, write git state, deploy, or invoke arbitrary extensions. Do not",
+        "claim that you performed a mutation; dispatch it to a crew agent instead.",
+        "",
+      ]
+    : [];
+  const groupMessageBrief = isSecretary
+    ? [
+        "When a human message names one or more crew agents, those names are",
+        "routing hints for you — the crew has NOT been notified yet. Decide what",
+        "work is actually needed, then dispatch a concrete @id instruction to each",
+        "crew member you need. Do not merely say that someone else will answer.",
+      ]
+    : [
+        "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.",
+      ];
+  const handoffBrief = isSecretary
+    ? [
+        "When crew work finishes, synthesize the outcome for the human and make",
+        "the next decision or blocker explicit. Do not abandon an unresolved",
+        "request silently, and do not wake a peer for acknowledgments alone.",
+      ]
+    : [
+        "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",
+        "did and what you need (e.g. `@codex changes committed on <branch> —",
+        "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.",
+      ];
+  const checkInTranscriptBrief = isSecretary
+    ? [
+        "Read both transcript files named above, 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.",
+      ]
+    : [
+        "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.",
+      ];
+  const workspaceBrief = isSecretary
+    ? [
+        "## Workspace layout",
+        "",
+        `Your read-only workspace root is \`${workspacePath}\`. It contains one`,
+        "project worktree per repository:",
+        "",
+        ...projectLines,
+        "",
+        `Those worktrees are on \`${taskBranch}\`. Inspect files when that helps`,
+        "you answer or scope a dispatch. Your profile cannot edit, commit, push,",
+        "or open a PR; send that work to a crew agent.",
+        "",
+        "The `.uai/` directory is Uai scaffolding. Read the two transcript files",
+        "there as described above; do not treat the rest as project content.",
+        "",
+      ]
+    : [
+        "## Workspace layout",
+        "",
+        `Your shell starts in \`${workspacePath}\` (the task workspace).`,
+        "That directory is **not** itself a git repo — it holds one git",
+        "worktree per project this task spans. Every project below is on the",
+        "same task branch. To run git commands, **`cd` into one of the",
+        "project directories first**:",
+        "",
+        ...projectLines,
+        "",
+        `The task branch is \`${taskBranch}\`. Push with \`git push -u origin`,
+        `${taskBranch}\` from inside the project, then open a PR with \`gh pr`,
+        "create` (the container has gh authenticated). For multi-project",
+        "tasks, each project's PR is independent — open one per project whose",
+        "worktree you actually changed.",
+        "",
+        "The `.uai/` directory under each task is uai's own scaffolding",
+        "(rendered Dockerfile, compose file, container scripts) — it is NOT",
+        "part of the project. Never review, edit, stage, commit, or flag it;",
+        "treat it as ignored, even though git may show it as untracked.",
+        "",
+      ];
   const comms = [
     "## uai task channel",
     "",
@@ -2377,63 +2581,21 @@ export function buildSystemPreamble(
     "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.",
+    ...groupMessageBrief,
     "",
-    "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",
-    "logged at `/workspace/.uai/chat.md`. Read it whenever you need that",
-    "context (e.g. the human shared a file or instruction with another",
-    "agent); it's appended live, so re-read it for the latest.",
+    ...transcriptBrief,
     "",
+    ...secretaryRoleBrief,
     "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",
-    "did and what you need (e.g. `@codex changes committed on <branch> —",
-    "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.",
+    ...checkInTranscriptBrief,
     "",
-    "## Workspace layout",
-    "",
-    `Your shell starts in \`${workspacePath}\` (the task workspace).`,
-    "That directory is **not** itself a git repo — it holds one git",
-    "worktree per project this task spans. Every project below is on the",
-    "same task branch. To run git commands, **`cd` into one of the",
-    "project directories first**:",
-    "",
-    ...projectLines,
-    "",
-    `The task branch is \`${taskBranch}\`. Push with \`git push -u origin`,
-    `${taskBranch}\` from inside the project, then open a PR with \`gh pr`,
-    "create` (the container has gh authenticated). For multi-project",
-    "tasks, each project's PR is independent — open one per project whose",
-    "worktree you actually changed.",
-    "",
-    "The `.uai/` directory under each task is uai's own scaffolding",
-    "(rendered Dockerfile, compose file, container scripts) — it is NOT",
-    "part of the project. Never review, edit, stage, commit, or flag it;",
-    "treat it as ignored, even though git may show it as untracked.",
+    ...handoffBrief,
     "",
+    ...workspaceBrief,
     // ADR-062: shared files — only when this container actually carries the
     // mounts (task-up drops a marker; pre-feature containers have none).
     ...(sharedFiles &&
@@ -2442,12 +2604,12 @@ export function buildSystemPreamble(
       ? [
           "## Shared files",
           "",
-          `Non-code files (${sharedFiles === "rw" ? "read-write" : "READ-ONLY"} for this task):`,
+          `Non-code files (${sharedFiles === "rw" && !isSecretary ? "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"
+          ...(sharedFiles === "rw" && !isSecretary
             ? [
                 "When producing artifacts for humans, write them here (use a",
                 "subdirectory named after the task to avoid collisions).",
@@ -2474,7 +2636,8 @@ export function buildSystemPreamble(
     // 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" &&
+    ...(!isSecretary &&
+    agent.kind === "claude" &&
     (agent.skills ?? []).some((s) => s.type === "package")
       ? [
           "## Installed skills",
@@ -2488,7 +2651,7 @@ export function buildSystemPreamble(
         ]
       : []),
     // ADR-053: the in-container browser, when the project opted in.
-    ...(browserTesting
+    ...(browserTesting && !isSecretary
       ? [
           "## Browser",
           "",
@@ -2511,7 +2674,11 @@ export function buildSystemPreamble(
         ]
       : []),
     // ADR-048: tell agents with permissions about their `uai` CLI.
-    ...((agent.permissions?.length ?? 0) > 0
+    // The communicator profile deliberately exposes no Bash or arbitrary MCP
+    // tool, so even a persona carrying CLI permissions cannot invoke cli.mjs.
+    // Do not advertise unusable commands; a future typed communicator tool can
+    // surface the safe task/todo subset without widening this boundary.
+    ...((agent.permissions?.length ?? 0) > 0 && !isSecretary
       ? [
           "## The uai CLI",
           "",
@@ -2601,14 +2768,18 @@ export function buildSystemPreamble(
           "",
         ]
       : []),
-    "## Commit policy",
-    "",
-    "Commits are SSH-signed automatically (git is configured for it) — do",
-    "not disable or override signing. Do NOT add any `Co-Authored-By:`",
-    "trailers to commit messages, and do NOT add 'Generated with …' or any",
-    "tool/agent attribution footer to commit messages or PR/issue bodies.",
-    "Write commit messages and PR descriptions plainly, as the author, with",
-    "no agent attribution.",
+    ...(!isSecretary
+      ? [
+          "## Commit policy",
+          "",
+          "Commits are SSH-signed automatically (git is configured for it) — do",
+          "not disable or override signing. Do NOT add any `Co-Authored-By:`",
+          "trailers to commit messages, and do NOT add 'Generated with …' or any",
+          "tool/agent attribution footer to commit messages or PR/issue bodies.",
+          "Write commit messages and PR descriptions plainly, as the author, with",
+          "no agent attribution.",
+        ]
+      : []),
   ].join("\n");
 
   // Persona / mission layers, always-on so they apply to every turn:
@@ -2636,11 +2807,20 @@ const globalForOrchestrator = globalThis as unknown as {
 
 export function getOrchestrator(): Orchestrator {
   if (!globalForOrchestrator.__uaiOrchestrator) {
-    // `UAI_AGENTS=real` drives the real Claude/Codex CLIs inside the
-    // task containers; anything else uses the mock (no Docker / no CLI
-    // needed — the default until the adapters are verified on a host).
-    const factory =
-      process.env.UAI_AGENTS === "real" ? realAgentFactory : mockAgentFactory;
+    // Real Claude/Codex CLIs inside the task containers unless `UAI_AGENTS`
+    // explicitly asks for the echo mock (see ./agents/mode). Mock is loud —
+    // a host that answers every prompt with canned text has to say so, or it
+    // reads as a working host producing nonsense.
+    const { mode, warning } = resolveAgentMode();
+    if (warning) console.warn(`[host-agent] ${warning}`);
+    if (mode === "mock") {
+      console.warn(
+        "[host-agent] ⚠ MOCK AGENTS — every agent echoes canned text and no " +
+          "real CLI runs. Unset UAI_AGENTS (or set it to `real`) for a host " +
+          "that does actual work.",
+      );
+    }
+    const factory = mode === "real" ? realAgentFactory : mockAgentFactory;
     globalForOrchestrator.__uaiOrchestrator = new Orchestrator(factory);
   }
   if (!globalForOrchestrator.__uaiRecoverRan) {

package/lib/transcript.ts

@@ -3,7 +3,10 @@
  * isolated conversations — each only hears what it's addressed. So they can opt
  * into cross-agent awareness, the host maintains a plain-text log of every chat
  * message at `<workspace>/.uai/chat.md` (mounted at /workspace), which any agent
- * can read on demand. Messages only — no tool calls / actions.
+ * can read on demand. Secretary mode adds a frontstage projection at
+ * `chat-front.md`; the cloud decides which projection(s) a row belongs to and
+ * sends an explicit target list. Conversational rows (including dispatch
+ * instructions) only — no tool-call execution traces.
  */
 
 import { appendFileSync, mkdirSync } from "node:fs";
@@ -11,14 +14,23 @@ import { resolve } from "node:path";
 
 import { taskWorkspaceDir } from "./env";
 import { rewriteAttachmentRefs } from "./orchestrator";
+import type { TranscriptTarget } from "../src/protocol";
 
 /** Container path agents are pointed at. */
 export const CONTAINER_TRANSCRIPT_PATH = "/workspace/.uai/chat.md";
+export const CONTAINER_FRONT_TRANSCRIPT_PATH =
+  "/workspace/.uai/chat-front.md";
+
+const TARGET_FILENAME: Record<TranscriptTarget, string> = {
+  chat: "chat.md",
+  "chat-front": "chat-front.md",
+};
 
 export function appendTranscript(
   taskId: string,
   author: string,
   text: string,
+  targets: TranscriptTarget[],
 ): void {
   // Rewrite cloud attachment URLs to the in-container path so an agent reading
   // the transcript can open referenced files directly.
@@ -26,5 +38,8 @@ export function appendTranscript(
   if (!body) return;
   const dir = resolve(taskWorkspaceDir(taskId), ".uai");
   mkdirSync(dir, { recursive: true });
-  appendFileSync(resolve(dir, "chat.md"), `## ${author}\n\n${body}\n\n`);
+  const entry = `## ${author}\n\n${body}\n\n`;
+  for (const target of new Set(targets)) {
+    appendFileSync(resolve(dir, TARGET_FILENAME[target]), entry);
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.8.45",
+  "version": "0.9.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>",
@@ -28,7 +28,7 @@
     "uai-host": "./bin/uai-host.mjs"
   },
   "engines": {
-    "node": ">=20"
+    "node": "22.x || >=24 <27"
   },
   "publishConfig": {
     "access": "public"
@@ -67,7 +67,7 @@
   },
   "dependencies": {
     "@sentry/node": "^10.66.0",
-    "better-sqlite3": "^11.3.0",
+    "better-sqlite3": "12.11.1",
     "dotenv": "^16.4.5",
     "drizzle-orm": "^0.36.0",
     "tsx": "^4.19.2",

package/src/cli.ts

@@ -134,6 +134,13 @@ async function cmdStatus(): Promise<void> {
   );
   if (cloud.lastError) console.log(`           ${dim("last error: " + cloud.lastError)}`);
   console.log(`  service  ${dim(`pid ${status.pid} · up ${fmtDuration(status.uptime * 1000)}`)}`);
+  // Only worth a line when it's the surprising answer. A mock host looks
+  // identical to a real one everywhere else — connected, tasks running, output
+  // streaming — so this is the only place it can be caught before the work is.
+  if (status.agentMode === "mock") {
+    console.log(`  agents   ${yellow("mock")} ${dim("— echo only, no real CLI runs")}`);
+    console.log(`           ${dim("unset UAI_AGENTS in " + envLocalPath() + ", then: uai-host restart")}`);
+  }
   console.log(`  ui       ${dim(`http://127.0.0.1:${port}`)}`);
   console.log(`  log      ${dim(status.logPath)}`);
   console.log(`  tasks    ${tasks.tasks.length === 0 ? dim("none") : tasks.tasks.length}`);

package/src/index.ts

@@ -67,6 +67,7 @@ export {
   factoryFor as agentFactoryFor,
   list as listAgentAdapters,
   register as registerAgentAdapter,
+  supportsExecutionProfile,
 } from "../lib/agents/registry";
 export type {
   AgentKindCapability,
@@ -482,10 +483,10 @@ export const hostCommands: HostCommands = {
     }
   },
 
-  async appendTranscript(_ctx, taskId, author, text) {
+  async appendTranscript(_ctx, taskId, author, text, targets) {
     // Per-message + high-frequency, so no logCommand (avoid log spam).
     try {
-      writeTranscript(taskId, author, text);
+      writeTranscript(taskId, author, text, targets);
       return ok(undefined);
     } catch (err) {
       return failFromUnknown(err);

package/src/main.ts

@@ -72,6 +72,7 @@ import { ensureStandardImage, standardRuntimes } from "../lib/standard-image";
 import { hostCommands, hostEvents } from "./index";
 import {
   HostErrorCode,
+  TRANSCRIPT_TARGETS_PROTOCOL_FEATURE,
   type CloudToHost,
   type McpOp,
   type CommandContext,
@@ -81,6 +82,8 @@ import {
   type HostCommands,
   type HostToCloud,
   type PermissionDecision,
+  parseChannelMode,
+  parseTranscriptTargets,
   type TaskAgent,
   type TaskCommandProject,
   type TaskCommandTask,
@@ -212,6 +215,7 @@ async function startLocalUi(): Promise<void> {
 function buildCapabilities(): HostCapabilities {
   return {
     version: packageVersion(),
+    protocolFeatures: [TRANSCRIPT_TARGETS_PROTOCOL_FEATURE],
     agentKinds: agentKindCapabilities(),
     runtimes: standardRuntimes(),
     githubUsers: connectedUserIds(),
@@ -956,6 +960,7 @@ function dispatchCommand(
         expectString(args, 0),
         expectString(args, 1),
         expectString(args, 2),
+        parseTranscriptTargets(args[3]),
       );
     case "previewEnsure":
       return hostCommands.previewEnsure(
@@ -1402,6 +1407,13 @@ function expectChannelEnsureInput(
   if (typeof input.globalContext === "string") {
     out.globalContext = input.globalContext;
   }
+  // ADR-083: secretary identity drives the role-specific transcript preamble.
+  // Both are optional for wire compatibility with older clouds.
+  const mode = parseChannelMode(input.mode);
+  if (mode !== undefined) out.mode = mode;
+  if (typeof input.secretaryAgentId === "string") {
+    out.secretaryAgentId = input.secretaryAgentId;
+  }
   // ADR-053: browser testing flag (optional; tolerant of absence).
   if (input.browserTesting === true) out.browserTesting = true;
   // ADR-049: humans in the chat (optional; tolerant of absence for older

package/src/protocol.ts

@@ -27,6 +27,10 @@ export type HostCommandResult<T> =
       retryable?: boolean;
     };
 
+/** Capability ids shared by host advertisement and fail-closed cloud gates. */
+export const TRANSCRIPT_TARGETS_PROTOCOL_FEATURE = "transcript-targets-v1";
+export const COMMUNICATOR_EXECUTION_PROFILE = "communicator";
+
 export interface CommandContext {
   commandId: string;
 }
@@ -70,6 +74,9 @@ export interface HostCapabilities {
   /** The host-agent package version — the cloud UI shows it on the host page
    *  and flags when npm has a newer release. Optional (older hosts omit it). */
   version?: string;
+  /** Optional protocol features. Absence means an older host and fails closed
+   *  for features whose fallback would weaken isolation (ADR-083). */
+  protocolFeatures?: string[];
   agentKinds: Array<{
     kind: string;
     label: string;
@@ -77,6 +84,13 @@ export interface HostCapabilities {
     defaultModel?: string;
     supportedEfforts: string[];
     defaultEffort?: string;
+    /** Execution profiles this adapter enforces, not prompt-only claims. */
+    executionProfiles?: Array<{
+      id: string;
+      mechanism: string;
+      defaultModel?: string;
+      defaultEffort?: string;
+    }>;
   }>;
   runtimes: Array<{
     kind: string;
@@ -88,6 +102,34 @@ export interface HostCapabilities {
   githubUsers?: string[];
 }
 
+/** One transcript projection the cloud asks the host to append to (ADR-083). */
+export type TranscriptTarget = "chat" | "chat-front";
+
+/** Parse the optional channel mode without turning malformed-new-cloud input
+ * into legacy Open mode. Absence is the only backwards-compatible fallback. */
+export function parseChannelMode(
+  value: unknown,
+): "open" | "secretary" | undefined {
+  if (value === undefined) return undefined;
+  if (value === "open" || value === "secretary") return value;
+  throw new Error("invalid command args: expected channel mode");
+}
+
+/** Parse the appendTranscript wire argument. `undefined` alone is the legacy
+ * three-argument command and maps to chat.md during a rolling deploy. */
+export function parseTranscriptTargets(value: unknown): TranscriptTarget[] {
+  if (value === undefined) return ["chat"];
+  if (
+    !Array.isArray(value) ||
+    value.length === 0 ||
+    value.length > 2 ||
+    value.some((target) => target !== "chat" && target !== "chat-front")
+  ) {
+    throw new Error("invalid command args: expected transcript targets");
+  }
+  return [...new Set(value)];
+}
+
 export interface TaskUpResult {
   composeProject: string;
   worktreePath: string;
@@ -200,6 +242,10 @@ export interface ChannelHuman {
 export interface ChannelEnsureInput {
   taskId: string;
   agents: TaskAgent[];
+  /** ADR-083: channel projection/routing mode. Optional for older clouds. */
+  mode?: "open" | "secretary";
+  /** The one human-facing communicator in secretary mode. */
+  secretaryAgentId?: string;
   /** ADR-049: the humans in the chat. Optional for wire back-compat; absent
    *  or single-entry behaves exactly like the pre-ADR-049 single-human task. */
   humans?: ChannelHuman[];
@@ -382,6 +428,7 @@ export interface HostCommands {
     taskId: string,
     author: string,
     text: string,
+    targets: TranscriptTarget[],
   ): Promise<HostCommandResult<void>>;
 }
 

package/src/ui/server.ts

@@ -23,6 +23,7 @@ import { join } from "node:path";
 import { desc, isNull } from "drizzle-orm";
 import type { ZodType } from "zod";
 
+import { agentMode } from "../../lib/agents/mode";
 import { schema, type Db } from "../../lib/db";
 import { parsePreviewPortRuntimes } from "../../lib/preview-ports";
 import { getCloudState } from "../../lib/cloud-state";
@@ -186,6 +187,7 @@ async function handle(
           cloudUrl: opts.cloudUrl,
           hostName: hostname(),
           hostId: opts.hostId,
+          agentMode: agentMode(),
         });
       case "/api/cloud":
         return sendJson(res, CloudResponse, getCloudState());

package/src/ui/types.ts

@@ -17,6 +17,11 @@ export const StatusResponse = z.object({
   cloudUrl: z.string(), // UAI_CLOUD_URL
   hostName: z.string(), // os.hostname()
   hostId: z.string(), // UAI_HOST_ID
+  // Which agent adapters this host runs (UAI_AGENTS). Optional: a newer CLI
+  // can query a service that is still on the pre-upgrade build, which had no
+  // such field — `npm i -g` swaps the CLI before `uai-host restart` swaps the
+  // service, so that window is normal, not exotic.
+  agentMode: z.enum(["real", "mock"]).optional(),
 });
 export type StatusResponse = z.infer<typeof StatusResponse>;