@runuai/host 0.9.5 → 0.9.7

package/lib/orchestrator.ts

@@ -73,9 +73,22 @@ import type {
   ChannelHuman,
   HostEvent,
 } from "../src/protocol";
+import {
+  MAX_AGENT_ID_CHARS,
+  MAX_SECRETARY_DISPATCH_ID_CHARS,
+  SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE,
+} from "../src/protocol";
 
 export type HostEventSubscriber = (event: HostEvent) => void;
 
+// Rolling upgrade fence: v0 Secretary runners were launched under the
+// communicator tool-denial profile and may survive a host restart. Durable
+// attach is otherwise keyed only by task+agent, so give the new normal-tools
+// policy an explicit generation and replace any legacy null-key runner once.
+const SECRETARY_SESSION_ATTACH_KEY = "secretary-normal-tools-v1";
+const RESTRICTED_SECRETARY_SESSION_ATTACH_KEY =
+  "secretary-communicator-v1";
+
 // ---------------------------------------------------------------------------
 // Channel — one task's live conversation.
 // ---------------------------------------------------------------------------
@@ -154,6 +167,11 @@ interface Channel {
   /** Agents with a delivered turn that has not reached a terminal event yet.
    *  Unlike openTurns, this covers thinking/tool/permission time before text. */
   activeTurns: Map<string, number>;
+  /** Crew replies waiting for the designated Secretary's current turn
+   *  boundary. Adapters do not share one mid-turn input contract, so only this
+   *  cross-lane role is serialized at the host boundary; open mode keeps its
+   *  legacy immediate-concurrent delivery behavior. */
+  pendingPrompts: Map<string, string[]>;
   /** Agents whose current turn was interrupted (ESC) — their next
    *  turn_complete is flagged `aborted` so the cloud DISCARDS the buffered
    *  half-turn instead of delivering it to @-mentioned peers. */
@@ -330,14 +348,12 @@ 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.
+    // Host-side fail closed. The cloud validates this too, but routing must not
+    // depend on every caller spelling the id correctly: an unmatched
+    // designation would otherwise create Secretary mode with no secretary.
     if (!hasValidSecretarySelection(spec)) {
       throw new Error(
-        "secretary mode requires exactly one roster agent matching secretaryAgentId",
+        "secretary mode requires typed-dispatch negotiation and exactly one roster agent matching secretaryAgentId",
       );
     }
     const channel = this.channels.get(spec.taskId);
@@ -352,7 +368,7 @@ export class Orchestrator {
       // 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.
+      // advertise a different role/routing boundary than the running process.
       throw new Error(
         "a live channel cannot change secretary mode or designation",
       );
@@ -531,6 +547,7 @@ export class Orchestrator {
       closed: false,
       openTurns: new Set(),
       activeTurns: new Map(),
+      pendingPrompts: new Map(),
       interrupted: new Set(),
       respawns: new Map(),
       respawnLastAt: new Map(),
@@ -616,6 +633,19 @@ export class Orchestrator {
       if (!this.isActiveChannel(channel)) return false;
       await this.reconcileSessions(channel);
     }
+    // The initial-start promise stays memoized after a healthy boot. A later
+    // fatal exit can therefore leave the designated Secretary missing even
+    // when reconciliation could not recreate it (for example because CLI
+    // materialization now fails). Secretary mode must report that degraded
+    // state rather than reuse the old `true` forever.
+    if (
+      ready &&
+      channel.mode === "secretary" &&
+      (!channel.secretaryAgentId ||
+        !channel.sessions.has(channel.secretaryAgentId))
+    ) {
+      return false;
+    }
     return ready;
   }
 
@@ -1213,7 +1243,21 @@ export class Orchestrator {
 
         const apiUrl = apiUrlFromCloudUrl(env.UAI_CLOUD_URL);
         const cliSecret = loadTaskCliSecret(channel.taskId);
-        writeAgentCli(channel.taskId, roster, apiUrl);
+        const cliWritten = writeAgentCli(
+          channel.taskId,
+          roster,
+          apiUrl,
+          channel.mode === "secretary",
+        );
+        if (
+          this.hasPromptLevelSecretary(channel) &&
+          (!cliWritten || !task.ownerUserId || !apiUrl || !cliSecret)
+        ) {
+          console.warn(
+            `[orchestrator] ${channel.taskId}: prompt-level Secretary CLI/token materialization failed`,
+          );
+          return;
+        }
 
         for (const agent of missing) {
           if (!this.isActiveChannel(channel)) return;
@@ -1229,6 +1273,10 @@ export class Orchestrator {
               containerName: channel.containerName,
               systemPreamble: channel.preambles.get(agent.id) ?? "",
               executionProfile: this.executionProfileFor(channel, agent.id),
+              attachCompatibilityKey: this.attachCompatibilityKeyFor(
+                channel,
+                agent.id,
+              ),
               agentEnv: this.accountAgentEnv(
                 channel,
                 agent,
@@ -1238,11 +1286,13 @@ export class Orchestrator {
                   task.ownerUserId,
                   apiUrl,
                   cliSecret,
+                  this.isPromptLevelSecretary(channel, agent.id),
                 ),
               ),
             },
           );
           if (!session) return;
+          this.startNextPendingPrompt(channel, agent.id);
         }
       } finally {
         for (const agent of missing) channel.spawning.delete(agent.id);
@@ -1252,19 +1302,49 @@ 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.
-   */
+  /** Reserved seam for a future explicit restricted-role control. */
   private executionProfileFor(
+    _channel: Channel,
+    _agentId: string,
+  ): "communicator" | undefined {
+    // Secretary is an organisational role, not a sandbox. The communicator
+    // profile remains implemented by adapters for a future explicit opt-in,
+    // but no task gets tool denial merely by selecting Secretary mode.
+    return undefined;
+  }
+
+  private attachCompatibilityKeyFor(
     channel: Channel,
     agentId: string,
-  ): "communicator" | undefined {
-    return channel.mode === "secretary" &&
-      channel.secretaryAgentId === agentId
-      ? "communicator"
-      : undefined;
+  ): string | undefined {
+    if (!this.isSecretary(channel, agentId)) return undefined;
+    // Key the durable runner to the policy actually passed to the adapter.
+    // The restricted profile is dormant today, but giving it the normal-tools
+    // generation would make a future opt-out able to attach a runner launched
+    // under tool denial.
+    return this.executionProfileFor(channel, agentId) === "communicator"
+      ? RESTRICTED_SECRETARY_SESSION_ATTACH_KEY
+      : SECRETARY_SESSION_ATTACH_KEY;
+  }
+
+  private isSecretary(channel: Channel, agentId: string): boolean {
+    return (
+      channel.mode === "secretary" && channel.secretaryAgentId === agentId
+    );
+  }
+
+  private isPromptLevelSecretary(channel: Channel, agentId: string): boolean {
+    return (
+      this.isSecretary(channel, agentId) &&
+      this.executionProfileFor(channel, agentId) === undefined
+    );
+  }
+
+  private hasPromptLevelSecretary(channel: Channel): boolean {
+    return Boolean(
+      channel.secretaryAgentId &&
+        this.isPromptLevelSecretary(channel, channel.secretaryAgentId),
+    );
   }
 
   /**
@@ -1448,7 +1528,21 @@ export class Orchestrator {
     // 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);
+    const cliWritten = writeAgentCli(
+      channel.taskId,
+      channel.roster,
+      apiUrl,
+      channel.mode === "secretary",
+    );
+    if (
+      this.hasPromptLevelSecretary(channel) &&
+      (!cliWritten || !task.ownerUserId || !apiUrl || !cliSecret)
+    ) {
+      console.warn(
+        `[orchestrator] ${channel.taskId}: prompt-level Secretary CLI/token materialization failed`,
+      );
+      return false;
+    }
 
     for (const agent of initialRoster) {
       if (!this.isActiveChannel(channel)) return false;
@@ -1468,6 +1562,10 @@ export class Orchestrator {
           containerName: channel.containerName,
           systemPreamble: channel.preambles.get(agent.id) ?? "",
           executionProfile: this.executionProfileFor(channel, agent.id),
+          attachCompatibilityKey: this.attachCompatibilityKeyFor(
+            channel,
+            agent.id,
+          ),
           agentEnv: this.accountAgentEnv(
               channel,
               agent,
@@ -1477,11 +1575,13 @@ export class Orchestrator {
                 task.ownerUserId,
                 apiUrl,
                 cliSecret,
+                this.isPromptLevelSecretary(channel, agent.id),
               ),
             ),
           },
         );
         if (!session) return false;
+        this.startNextPendingPrompt(channel, agent.id);
       } finally {
         channel.spawning.delete(agent.id);
       }
@@ -1503,9 +1603,9 @@ export class Orchestrator {
    * calls this so agents auto-start the moment the task is running,
    * without the human having to send a message first.
    */
-  async ensureStarted(taskId: string): Promise<void> {
+  async ensureStarted(taskId: string): Promise<boolean> {
     const channel = await this.getOrCreateChannel(taskId);
-    if (channel) await this.ensureSessions(channel);
+    return channel ? this.ensureSessions(channel) : false;
   }
 
   private incrementActiveTurns(channel: Channel, agentId: string): void {
@@ -1534,6 +1634,77 @@ export class Orchestrator {
     return remaining;
   }
 
+  /** Retire turn-local state owned by a runner generation before replacement. */
+  private retireRunnerGeneration(channel: Channel, agentId: string): void {
+    channel.activeTurns.delete(agentId);
+    channel.openTurns.delete(agentId);
+    channel.interrupted.delete(agentId);
+  }
+
+  private startPrompt(
+    channel: Channel,
+    agentId: string,
+    session: AgentSession,
+    prompt: string,
+  ): void {
+    // ADR-076: this is the prompt actually in flight. A queued follow-up must
+    // not replace it or account rotation would replay the wrong turn.
+    channel.lastPrompt.set(agentId, prompt);
+    this.incrementActiveTurns(channel, agentId);
+    void session.send(prompt).catch((err: unknown) => {
+      if (channel.sessions.get(agentId) === session) {
+        const remaining = this.decrementActiveTurns(channel, agentId);
+        if (
+          remaining === 0 &&
+          channel.lastPrompt.get(agentId) === prompt
+        ) {
+          channel.lastPrompt.delete(agentId);
+        }
+        this.startNextPendingPrompt(channel, agentId);
+      }
+      console.warn(
+        `[orchestrator] ${channel.taskId}/${agentId}: send failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    });
+  }
+
+  /** Start at most one queued prompt after the previous turn is terminal. */
+  private startNextPendingPrompt(channel: Channel, agentId: string): boolean {
+    if (
+      !this.isActiveChannel(channel) ||
+      !this.isSecretary(channel, agentId) ||
+      (channel.activeTurns.get(agentId) ?? 0) > 0
+    ) {
+      return false;
+    }
+    const queue = channel.pendingPrompts.get(agentId);
+    const session = channel.sessions.get(agentId);
+    if (!queue || queue.length === 0 || !session) return false;
+    const prompt = queue.shift()!;
+    if (queue.length === 0) channel.pendingPrompts.delete(agentId);
+    this.startPrompt(channel, agentId, session, prompt);
+    return true;
+  }
+
+  /** A dead Secretary session must not strand already-accepted crew replies. */
+  private reconcilePendingSecretary(channel: Channel, agentId: string): void {
+    if (
+      !this.isSecretary(channel, agentId) ||
+      (channel.pendingPrompts.get(agentId)?.length ?? 0) === 0
+    ) {
+      return;
+    }
+    void this.reconcileSessions(channel).catch((err: unknown) => {
+      console.warn(
+        `[orchestrator] ${channel.taskId}/${agentId}: pending-prompt reconcile failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    });
+  }
+
   // -- inbound: a human (or routed peer) message ----------------------------
 
   /**
@@ -1563,20 +1734,23 @@ export class Orchestrator {
     if (!session) return { ok: false, error: `no such agent: ${agentId}` };
 
     const prompt = rewriteAttachmentRefs(text);
-    // ADR-076: remember the in-flight prompt so an account rotation on a
-    // rate-limit can re-deliver it to the fresh session.
-    channel.lastPrompt.set(agentId, prompt);
-    this.incrementActiveTurns(channel, agentId);
-    void session.send(prompt).catch((err: unknown) => {
-      if (channel.sessions.get(agentId) === session) {
-        this.decrementActiveTurns(channel, agentId);
+    if (this.isSecretary(channel, agentId)) {
+      const queue = channel.pendingPrompts.get(agentId) ?? [];
+      if ((channel.activeTurns.get(agentId) ?? 0) > 0 || queue.length > 0) {
+        queue.push(prompt);
+        channel.pendingPrompts.set(agentId, queue);
+        // A replacement session may have bound after the queue was observed
+        // but before this delivery. Preserve FIFO by starting the oldest item.
+        this.startNextPendingPrompt(channel, agentId);
+      } else {
+        this.startPrompt(channel, agentId, session, prompt);
       }
-      console.warn(
-        `[orchestrator] ${channel.taskId}/${agentId}: send failed: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-    });
+    } else {
+      // Preserve the legacy open-room contract: adapters receive concurrent
+      // deliveries immediately. Only the designated Secretary needs the hard
+      // turn boundary because crew replies can arrive during its dispatch turn.
+      this.startPrompt(channel, agentId, session, prompt);
+    }
     return { ok: true };
   }
 
@@ -1663,6 +1837,24 @@ export class Orchestrator {
         });
         break;
       }
+      case "dispatch": {
+        this.markActiveTurn(channel, agentId);
+        this.emitHost({
+          kind: "agent.dispatch",
+          taskId: channel.taskId,
+          agentId,
+          // Optional trace metadata must never make the action undeliverable.
+          // Provider tool ids have no useful product-level length guarantee;
+          // omit an oversized one while preserving the dispatch itself.
+          ...(event.dispatchId.length > 0 &&
+          event.dispatchId.length <= MAX_SECRETARY_DISPATCH_ID_CHARS
+            ? { dispatchId: event.dispatchId }
+            : {}),
+          recipients: event.recipients,
+          instruction: event.instruction,
+        });
+        break;
+      }
       case "permission_request": {
         this.markActiveTurn(channel, agentId);
         this.emitHost({
@@ -1692,9 +1884,7 @@ export class Orchestrator {
       case "error": {
         // The turn died with the session — drop its turn-state flags so a
         // respawned session starts clean.
-        channel.activeTurns.delete(agentId);
-        channel.openTurns.delete(agentId);
-        channel.interrupted.delete(agentId);
+        this.retireRunnerGeneration(channel, agentId);
         // Claude under load (especially Docker Desktop macOS) occasionally
         // unlinks ~/.claude.json mid-write during atomic config rewrites,
         // and a concurrent claude spawn lands during the gap and exits 0
@@ -1725,9 +1915,14 @@ export class Orchestrator {
           re.test(event.message),
         );
         if (isClaude && configMissing) {
+          // This recovery path deliberately starts the next queued turn rather
+          // than replaying the failed one. Do not leave it looking in-flight to
+          // a later account refresh.
+          channel.lastPrompt.delete(agentId);
           await this.recoverClaudeAgent(channel, agentId);
           break;
         }
+        channel.lastPrompt.delete(agentId);
         this.emitHost({
           kind: "agent.exit",
           taskId: channel.taskId,
@@ -1749,6 +1944,7 @@ export class Orchestrator {
         channel.sessions.delete(agentId);
         channel.browserStaleSessions.delete(agentId);
         channel.browserPendingStaleSessions.delete(agentId);
+        this.reconcilePendingSecretary(channel, agentId);
         break;
       }
       case "turn_complete": {
@@ -1769,10 +1965,14 @@ export class Orchestrator {
           aborted,
           usage: event.usage,
         });
+        if (remainingTurns === 0) {
+          channel.lastPrompt.delete(agentId);
+          this.startNextPendingPrompt(channel, agentId);
+        }
         // A config repair never interrupts a turn. The stale id remains queued
         // until this exact boundary, then reconcile closes and replaces it.
         if (
-          remainingTurns === 0 &&
+          (channel.activeTurns.get(agentId) ?? 0) === 0 &&
           channel.browserStaleSessions.has(agentId)
         ) {
           void this.reconcileSessions(channel).catch((err: unknown) => {
@@ -1788,14 +1988,14 @@ export class Orchestrator {
       case "exit":
         // Same zombie hazard as the error path — a session whose process
         // ended (even cleanly) can never carry another turn.
-        channel.activeTurns.delete(agentId);
-        channel.openTurns.delete(agentId);
-        channel.interrupted.delete(agentId);
+        this.retireRunnerGeneration(channel, agentId);
+        channel.lastPrompt.delete(agentId);
         channel.respawns.set(agentId, (channel.respawns.get(agentId) ?? 0) + 1);
         channel.respawnLastAt.set(agentId, Date.now());
         channel.sessions.delete(agentId);
         channel.browserStaleSessions.delete(agentId);
         channel.browserPendingStaleSessions.delete(agentId);
+        this.reconcilePendingSecretary(channel, agentId);
         break;
     }
   }
@@ -1845,6 +2045,7 @@ export class Orchestrator {
       channel.sessions.delete(agentId);
       channel.browserStaleSessions.delete(agentId);
       channel.browserPendingStaleSessions.delete(agentId);
+      this.retireRunnerGeneration(channel, agentId);
       if (old) {
         try {
           await old.close();
@@ -1866,6 +2067,7 @@ export class Orchestrator {
         task.ownerUserId,
         apiUrl,
         cliSecret,
+        this.isPromptLevelSecretary(channel, agent.id),
       );
       const boundAccountId = channel.accountByAgent.get(agentId);
       const boundAccount = boundAccountId
@@ -1879,11 +2081,16 @@ export class Orchestrator {
         containerName: channel.containerName,
         systemPreamble: channel.preambles.get(agentId) ?? "",
         executionProfile: this.executionProfileFor(channel, agentId),
+        attachCompatibilityKey: this.attachCompatibilityKeyFor(
+          channel,
+          agentId,
+        ),
         agentEnv: boundAccount
           ? { ...base, ...boundAccount.execEnv }
           : this.accountAgentEnv(channel, agent, base),
       });
       if (!session) return;
+      this.startNextPendingPrompt(channel, agentId);
 
       const message = restored
         ? `${agentId} restarted — config file was missing in the container, restored from the host.`
@@ -1896,6 +2103,9 @@ export class Orchestrator {
       });
     } finally {
       channel.spawning.delete(agentId);
+      if (!channel.sessions.has(agentId)) {
+        this.reconcilePendingSecretary(channel, agentId);
+      }
       // A concurrent config writer can mark the newly-bound recovery stale
       // while this spawn slot is still held. Reconciliation skips spawning
       // ids by design, so release must explicitly give that mark another turn.
@@ -1957,6 +2167,7 @@ export class Orchestrator {
       channel.sessions.delete(agentId);
       channel.browserStaleSessions.delete(agentId);
       channel.browserPendingStaleSessions.delete(agentId);
+      this.retireRunnerGeneration(channel, agentId);
       if (old) {
         try {
           await old.close();
@@ -1985,6 +2196,7 @@ export class Orchestrator {
         task.ownerUserId,
         apiUrl,
         cliSecret,
+        this.isPromptLevelSecretary(channel, agent.id),
       );
       channel.accountByAgent.set(agentId, next.id);
       noteEngineAccountUsed(next.id);
@@ -1998,6 +2210,10 @@ export class Orchestrator {
           containerName: channel.containerName,
           systemPreamble: channel.preambles.get(agentId) ?? "",
           executionProfile: this.executionProfileFor(channel, agentId),
+          attachCompatibilityKey: this.attachCompatibilityKeyFor(
+            channel,
+            agentId,
+          ),
           agentEnv: { ...base, ...next.execEnv },
         },
       );
@@ -2011,20 +2227,15 @@ export class Orchestrator {
       // Re-deliver the in-flight prompt so the interrupted turn resumes.
       const prompt = channel.lastPrompt.get(agentId);
       if (prompt) {
-        this.incrementActiveTurns(channel, agentId);
-        void replacement.send(prompt).catch((err: unknown) => {
-          if (channel.sessions.get(agentId) === replacement) {
-            this.decrementActiveTurns(channel, agentId);
-          }
-          console.warn(
-            `[orchestrator] ${channel.taskId}/${agentId}: rotated send failed: ${
-              err instanceof Error ? err.message : String(err)
-            }`,
-          );
-        });
+        this.startPrompt(channel, agentId, replacement, prompt);
+      } else {
+        this.startNextPendingPrompt(channel, agentId);
       }
     } finally {
       channel.spawning.delete(agentId);
+      if (!replacement) {
+        this.reconcilePendingSecretary(channel, agentId);
+      }
     }
 
     // Browser/config setup may have marked other live generations stale. Run
@@ -2073,6 +2284,10 @@ export class Orchestrator {
       channel.sessions.delete(agentId);
       channel.browserStaleSessions.delete(agentId);
       channel.browserPendingStaleSessions.delete(agentId);
+      // The old runner can no longer complete any of its turns. The prompt
+      // itself remains in lastPrompt for the replacement to replay, but its
+      // counters belong to the retired generation and must start over.
+      this.retireRunnerGeneration(channel, agentId);
       if (old) {
         try {
           await old.close();
@@ -2099,6 +2314,7 @@ export class Orchestrator {
         task.ownerUserId,
         apiUrl,
         cliSecret,
+        this.isPromptLevelSecretary(channel, agent.id),
       );
       channel.accountByAgent.set(agentId, account.id);
       noteEngineAccountUsed(account.id);
@@ -2108,6 +2324,11 @@ export class Orchestrator {
         agent,
         containerName: channel.containerName,
         systemPreamble: channel.preambles.get(agentId) ?? "",
+        executionProfile: this.executionProfileFor(channel, agentId),
+        attachCompatibilityKey: this.attachCompatibilityKeyFor(
+          channel,
+          agentId,
+        ),
         agentEnv: { ...base, ...account.execEnv },
       });
       if (!replacement) return true;
@@ -2117,20 +2338,15 @@ export class Orchestrator {
       // Re-deliver the in-flight prompt so the interrupted turn resumes.
       const prompt = channel.lastPrompt.get(agentId);
       if (prompt) {
-        this.incrementActiveTurns(channel, agentId);
-        void replacement.send(prompt).catch((err: unknown) => {
-          if (channel.sessions.get(agentId) === replacement) {
-            this.decrementActiveTurns(channel, agentId);
-          }
-          console.warn(
-            `[orchestrator] ${channel.taskId}/${agentId}: respawn send failed: ${
-              err instanceof Error ? err.message : String(err)
-            }`,
-          );
-        });
+        this.startPrompt(channel, agentId, replacement, prompt);
+      } else {
+        this.startNextPendingPrompt(channel, agentId);
       }
     } finally {
       channel.spawning.delete(agentId);
+      if (!replacement) {
+        this.reconcilePendingSecretary(channel, agentId);
+      }
     }
 
     if (
@@ -2252,6 +2468,7 @@ export class Orchestrator {
     ch.browserStaleSessions.clear();
     ch.browserPendingStaleSessions.clear();
     ch.activeTurns.clear();
+    ch.pendingPrompts.clear();
     ch.openTurns.clear();
     ch.interrupted.clear();
     ch.reconcileAgain = false;
@@ -2367,10 +2584,22 @@ export class Orchestrator {
 
 /** Exact host-wire role validation; never trims or canonicalises agent ids. */
 export function hasValidSecretarySelection(
-  spec: Pick<ChannelEnsureInput, "mode" | "secretaryAgentId" | "agents">,
+  spec: Pick<
+    ChannelEnsureInput,
+    "mode" | "secretaryAgentId" | "secretaryDispatchProtocol" | "agents"
+  >,
 ): boolean {
   if (spec.mode !== "secretary") return true;
+  if (
+    spec.secretaryDispatchProtocol !==
+    SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE
+  ) {
+    return false;
+  }
   if (!spec.secretaryAgentId) return false;
+  if (spec.agents.some((agent) => agent.id.length > MAX_AGENT_ID_CHARS)) {
+    return false;
+  }
   return (
     spec.agents.filter((agent) => agent.id === spec.secretaryAgentId).length ===
     1
@@ -2628,6 +2857,14 @@ export function buildSystemPreamble(
         );
   const isSecretary =
     mode === "secretary" && secretaryAgentId === agent.id;
+  const dispatchActionBrief = [
+    "When crew work is needed, run the Secretary CLI action:",
+    `\`node ${CONTAINER_CLI_PATH} dispatch @agent [@agent…] \"instruction\"\``,
+    "using exact crew @ids and one concrete, self-contained instruction.",
+    "The command prints a refusal if Uai did not accept the dispatch. Your",
+    "prose stays frontstage: it is not delivered to the crew or written to their",
+    "normal transcript, and naming an agent there does NOT wake them.",
+  ];
   const transcriptBrief =
     mode !== "secretary"
       ? [
@@ -2660,15 +2897,17 @@ export function buildSystemPreamble(
         "## 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",
+        "directly when the transcripts and your own inspection are sufficient.",
+        ...dispatchActionBrief,
+        "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.",
+        "Your Secretary role is prompt-guided, not tool-restricted. You have the",
+        "same normal tools, approved MCP connections, model choice, and persona",
+        "permissions as any other task agent. Your default job is to communicate,",
+        "coordinate, and dispatch implementation work rather than doing it yourself.",
+        "If the human explicitly asks YOU to make a change, you may use those tools",
+        "and do it directly; otherwise hand mutations to a crew agent.",
         "",
       ]
     : [];
@@ -2676,7 +2915,9 @@ export function buildSystemPreamble(
     ? [
         "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",
+        `work is actually needed, then run \`node ${CONTAINER_CLI_PATH} dispatch …\``,
+        "with a concrete",
+        "instruction for each",
         "crew member you need. Do not merely say that someone else will answer.",
       ]
     : [
@@ -2723,14 +2964,15 @@ export function buildSystemPreamble(
     ? [
         "## Workspace layout",
         "",
-        `Your read-only workspace root is \`${workspacePath}\`. It contains one`,
+        `Your shell starts in \`${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.",
+        "you answer or scope a dispatch.",
+        "By default, send edits, commits, pushes, and PR work to a crew agent.",
+        "You may do that work yourself when the human explicitly asks you to.",
         "",
         "The `.uai/` directory is Uai scaffolding. Read the two transcript files",
         "there as described above; do not treat the rest as project content.",
@@ -2759,13 +3001,65 @@ export function buildSystemPreamble(
         "treat it as ignored, even though git may show it as untracked.",
         "",
       ];
+  const channelRoutingBrief = isSecretary
+    ? [
+        "You are the designated Secretary in a uai task chat channel shared with",
+        "the human and the crew. Your normal prose is frontstage: it is not",
+        "delivered to the crew or shown in their normal feed/transcript. Naming",
+        "or @-mentioning a crew agent in prose does NOT wake them.",
+        "The only way to hand crew work off is the structured `dispatch` action.",
+      ]
+    : [
+        "You are one agent in a uai task chat channel, shared with the human",
+        "and the other agents. To hand work to or ask another agent, mention",
+        "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.",
+      ];
+  const collaborationBrief = isSecretary
+    ? [
+        "Collaborate through deliberate dispatches. Each dispatch wakes a crew",
+        "agent and costs a turn, so make every instruction concrete, self-contained,",
+        "and necessary. Never dispatch greetings, thanks, or acknowledgments.",
+      ]
+    : [
+        "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.",
+      ];
+  const channelConventionsBrief = isSecretary
+    ? [
+        "Your prose always goes to the human-facing lane; answer plainly without",
+        "re-mentioning the asker. Crew @mentions in prose are labels only. Use",
+        "the structured dispatch action when a crew agent must actually act.",
+        "You may occasionally receive a `[channel check-in]` asking you to catch",
+        "up on the channel.",
+      ]
+    : [
+        "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.",
+      ];
   const comms = [
     "## uai task channel",
     "",
-    "You are one agent in a uai task chat channel, shared with the human",
-    "and the other agents. To hand work to or ask another agent, mention",
-    "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.",
+    ...channelRoutingBrief,
     "",
     `**You are @${agent.id}** — your name in this channel is **${agent.label}**.`,
     `Introduce and refer to yourself as ${agent.label}, not as a generic`,
@@ -2775,35 +3069,14 @@ export function buildSystemPreamble(
     "",
     ...humanIntro,
     "",
-    "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.",
+    ...collaborationBrief,
     "",
     ...groupMessageBrief,
     "",
     ...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.",
+    ...channelConventionsBrief,
     ...checkInTranscriptBrief,
     "",
     ...handoffBrief,
@@ -2817,12 +3090,12 @@ export function buildSystemPreamble(
       ? [
           "## Shared files",
           "",
-          `Non-code files (${sharedFiles === "rw" && !isSecretary ? "read-write" : "READ-ONLY"} for this task):`,
+          `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" && !isSecretary
+          ...(sharedFiles === "rw"
             ? [
                 "When producing artifacts for humans, write them here (use a",
                 "subdirectory named after the task to avoid collisions).",
@@ -2849,8 +3122,7 @@ 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.
-    ...(!isSecretary &&
-    agent.kind === "claude" &&
+    ...(agent.kind === "claude" &&
     (agent.skills ?? []).some((s) => s.type === "package")
       ? [
           "## Installed skills",
@@ -2864,7 +3136,7 @@ export function buildSystemPreamble(
         ]
       : []),
     // ADR-053: the in-container browser, when the project opted in.
-    ...(browserTesting && !isSecretary
+    ...(browserTesting
       ? [
           "## Browser",
           "",
@@ -2886,12 +3158,10 @@ export function buildSystemPreamble(
           "",
         ]
       : []),
-    // ADR-048: tell agents with permissions about their `uai` CLI.
-    // 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
+    // ADR-048: tell every agent with persona-granted permissions about its
+    // `uai` CLI. Secretary mode adds dispatch but does not invent any other
+    // permission: an empty persona permission set remains empty.
+    ...((agent.permissions?.length ?? 0) > 0
       ? [
           "## The uai CLI",
           "",
@@ -2981,19 +3251,15 @@ export function buildSystemPreamble(
           "",
         ]
       : []),
-    ...(!isSecretary
-      ? [
-          "## Commit policy",
-          "",
-          "When this task has an optional SSH signing key configured, Git signs",
-          "commits automatically; do not disable or override it. 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.",
-        ]
-      : []),
+    "## Commit policy",
+    "",
+    "When this task has an optional SSH signing key configured, Git signs",
+    "commits automatically; do not disable or override it. 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:
@@ -3172,6 +3438,38 @@ async function dockerStart(containerName: string): Promise<boolean> {
   return true;
 }
 
+/**
+ * Repair the shared node data root before any recovered-container init.
+ * Older task-up versions created the OpenCode leaf as root and accidentally
+ * left this parent root-owned, which prevented code-server from creating its
+ * managed User profile. `install -d` creates or repairs the exact directory
+ * without recursively changing unrelated application state beneath it.
+ */
+async function repairNodeDataRoot(containerName: string): Promise<boolean> {
+  const res = await dockerCli([
+    "exec",
+    "-u",
+    "root",
+    containerName,
+    "/usr/bin/install",
+    "-d",
+    "-o",
+    "node",
+    "-g",
+    "node",
+    "-m",
+    "0755",
+    "/home/node/.local/share",
+  ]);
+  if (res.status !== 0) {
+    console.error(
+      `[orchestrator] recovery: ${containerName} could not repair /home/node/.local/share ownership: ${res.stderr.trim() || `docker exec exited ${String(res.status)}`}`,
+    );
+    return false;
+  }
+  return true;
+}
+
 async function dockerPort(
   containerName: string,
   containerPort: number,
@@ -3372,6 +3670,9 @@ async function recoverOneTask(
     });
     return true;
   }
+  // uai-init seeds code-server's profile beneath this shared data root. Heal
+  // containers created by older hosts before running it as node.
+  await repairNodeDataRoot(containerName);
   // Correctly-owned Codex creds BEFORE uai-init / any agent respawn: the boot
   // reinject sweep only targets containers already running, so a container
   // recovered here would otherwise keep whatever it held when it exited —