borgmcp 2.11.0 → 2.13.0

package/src/claude.ts

@@ -81,13 +81,63 @@ import {
 } from './config-utils.js';
 import { ensureCliMcpConfigured } from './ensure-mcp-config.js';
 import { installBorgPlugin } from './opencode-plugin.js';
-import { connectOpenCodeDrone, computeOpenCodePort, createOpenCodeLaunchKickoff, injectInitialKickoff } from './opencode-drone.js';
+import { allocateOpenCodePort, connectOpenCodeDrone, createOpenCodeLaunchKickoff, injectInitialKickoff, openCodeLaunchBinding } from './opencode-drone.js';
 import { buildOpenCodeLaunchArgs, defaultApprovalIo, resolveLaunchBorgApprovals } from './cli-tool-approval.js';
 import { isClientOwnedCubeInitArgv, runEarlyServerFacade } from './server-facade.js';
 import { runEarlyUpdate } from './update-cmd.js';
 
 export type AssimilateDepsBuilder = typeof buildDefaultAssimilateDeps;
 
+export function createOpenCodeLaunchPlan(
+  cwd: string,
+  port: number,
+  prompt: string,
+  passthroughArgs: string[] = [],
+): { launchArgs: string[]; envPort: string; serverUrl: string } {
+  const binding = openCodeLaunchBinding(port);
+  return {
+    launchArgs: buildOpenCodeLaunchArgs(cwd, Number(binding.cliPort), prompt, passthroughArgs),
+    envPort: binding.envPort,
+    serverUrl: binding.serverUrl,
+  };
+}
+
+export function launchOpenCodeProcess(options: {
+  cwd: string;
+  port: number;
+  prompt: string;
+  passthroughArgs: string[];
+  env: NodeJS.ProcessEnv;
+  droneLabel: string;
+  cubeName: string;
+  kickoff: ReturnType<typeof createOpenCodeLaunchKickoff>;
+  spawnProcess?: typeof spawn;
+  connect?: typeof connectOpenCodeDrone;
+}): {
+  launchArgs: string[];
+  launchEnv: NodeJS.ProcessEnv;
+  process: ReturnType<typeof spawn>;
+} {
+  const plan = createOpenCodeLaunchPlan(options.cwd, options.port, options.prompt, options.passthroughArgs);
+  const launchEnv = { ...options.env, BORG_OPENCODE_PORT: plan.envPort };
+  // OpenCode's bind can still race this allocation; client#298 tracks the
+  // residual pre-bind window outside this slice.
+  const child = (options.spawnProcess ?? spawn)('opencode', plan.launchArgs, {
+    stdio: 'inherit',
+    shell: false,
+    env: launchEnv,
+  });
+  (options.connect ?? connectOpenCodeDrone)({
+    serverUrl: plan.serverUrl,
+    directory: options.cwd,
+    droneLabel: options.droneLabel,
+    cubeName: options.cubeName,
+  })
+    .then(() => injectInitialKickoff(options.kickoff))
+    .catch(() => {});
+  return { launchArgs: plan.launchArgs, launchEnv, process: child };
+}
+
 export async function runAssimilateEntry(
   args: readonly string[],
   buildDeps: AssimilateDepsBuilder = buildDefaultAssimilateDeps,
@@ -346,8 +396,8 @@ async function main() {
   }
 
   // client#20: inspect only the SELECTED harness after the one-shot launch
-  // menu choice. Explicit consent enables a narrow per-process override;
-  // Borg never rewrites the user's approval policy here.
+  // menu choice. A narrow per-process override is applied by default; Borg
+  // never rewrites the user's approval policy here.
   const approvalCwd = cli === 'codex'
     ? resolveCodexLaunchCwd(parsedCli.rest, process.cwd())
     : process.cwd();
@@ -357,7 +407,8 @@ async function main() {
       cwd: approvalCwd,
       env: process.env,
       codexArgs: parsedCli.rest,
-    })
+    }),
+    { skipOverride: parsedCli.noBorgApprovalOverride }
   );
   if (launchApproval.warning) {
     console.error(`${consolePrefix()}${chalk.yellow(`warning: ${launchApproval.warning}`)}`);
@@ -464,6 +515,7 @@ async function main() {
   // their existing launch prompts. OpenCode records this nonce-bearing copy
   // and later uses the nonce to bind its separately spawned MCP child.
   let openCodeKickoff: ReturnType<typeof createOpenCodeLaunchKickoff> | null = null;
+  let openCodePort: number | undefined;
   let launchArgs: string[];
   if (cli === 'codex') {
     // gh#673 P1-codex: codex MCP children only see the pinned
@@ -485,14 +537,12 @@ async function main() {
   } else if (cli === 'opencode') {
     // OpenCode launch: start TUI with the kickoff passed via --prompt
     // (auto-submits it as the first message). BORG_SESSION is pinned in
-    // opencode.json. A unique port is assigned so the MCP child can connect
-    // to OpenCode's local HTTP API for durable entry injection.
-    const dronePort = active
-      ? computeOpenCodePort(active.droneId)
-      : 14096;
+    // opencode.json. The OS-selected loopback port lets the MCP child connect
+    // to OpenCode's local HTTP API without a shared deterministic collision space.
+    openCodePort = await allocateOpenCodePort();
     installBorgPlugin();
     openCodeKickoff = createOpenCodeLaunchKickoff(kickoff);
-    launchArgs = buildOpenCodeLaunchArgs(process.cwd(), dronePort, openCodeKickoff.prompt, passthroughArgs);
+    launchArgs = [];
   } else {
     // gh#702: borg-launched claude drones auto-allow ONLY mcp__borg__* so they
     // never prompt on borg coordination calls; Bash/file/web still prompt.
@@ -502,26 +552,18 @@ async function main() {
   const cliDisplayName = cli === 'claude' ? 'Claude Code' : cli === 'codex' ? 'Codex' : 'OpenCode';
   console.error(`${consolePrefix()}${chalk.blue(`◼ Launching ${cliDisplayName}…`)}`);
 
-  const agentProcess = spawn(cli, launchArgs, {
-    stdio: 'inherit',
-    shell: false,
-    env: launchEnv,
-  });
-
-  // gh#opencode: find the opened session after launch. The kickoff was already
-  // submitted via --prompt, so we just discover the session ID for inbox
-  // entry injection. Fire-and-forget; never delay the launch.
-  if (cli === 'opencode' && openCodeKickoff) {
-    const launchKickoff = openCodeKickoff;
-    const dronePort = active
-      ? computeOpenCodePort(active.droneId)
-      : 14096;
-    const serverUrl = `http://127.0.0.1:${dronePort}`;
-    // Fire-and-forget; never delay the launch or crash on failure.
-    connectOpenCodeDrone({ serverUrl, directory: process.cwd(), droneLabel: active?.droneLabel ?? 'opencode', cubeName: active?.name ?? 'borg' })
-      .then(() => injectInitialKickoff(launchKickoff))
-      .catch(() => {});
-  }
+  const agentProcess = cli === 'opencode' && openCodeKickoff && openCodePort !== undefined
+    ? launchOpenCodeProcess({
+        cwd: process.cwd(),
+        port: openCodePort,
+        prompt: openCodeKickoff.prompt,
+        passthroughArgs,
+        env: launchEnv,
+        droneLabel: active?.droneLabel ?? 'opencode',
+        cubeName: active?.name ?? 'borg',
+        kickoff: openCodeKickoff,
+      }).process
+    : spawn(cli, launchArgs, { stdio: 'inherit', shell: false, env: launchEnv });
 
   // gh#857 WI-2: wake-target recording is codex-only (app-server bridge).
   // OpenCode uses HTTP entry injection; Claude uses the inbox Monitor.

package/src/cli-platform.ts

@@ -101,10 +101,17 @@ export function defaultCliChoiceDeps(prompt: (message: string) => Promise<string
 
 const VALID_CLIS: readonly BorgCli[] = ['claude', 'codex', 'opencode'];
 
-export function parseCliFlag(args: string[]): { cli?: BorgCli; force?: boolean; rest: string[]; error?: string } {
+export function parseCliFlag(args: string[]): {
+  cli?: BorgCli;
+  force?: boolean;
+  noBorgApprovalOverride?: boolean;
+  rest: string[];
+  error?: string;
+} {
   const rest: string[] = [];
   let cli: BorgCli | undefined;
   let force = false;
+  let noBorgApprovalOverride = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--cli') {
@@ -122,9 +129,16 @@ export function parseCliFlag(args: string[]): { cli?: BorgCli; force?: boolean;
       cli = value as BorgCli;
     } else if (arg === '--force') {
       force = true;
+    } else if (arg === '--no-borg-approval-override') {
+      noBorgApprovalOverride = true;
     } else {
       rest.push(arg);
     }
   }
-  return { ...(cli ? { cli } : {}), ...(force ? { force: true } : {}), rest };
+  return {
+    ...(cli ? { cli } : {}),
+    ...(force ? { force: true } : {}),
+    ...(noBorgApprovalOverride ? { noBorgApprovalOverride: true } : {}),
+    rest,
+  };
 }

package/src/cli-tool-approval.ts

@@ -581,13 +581,10 @@ export function defaultApprovalIo(
   };
 }
 
-function accepted(answer: string): boolean {
-  return /^(?:y|yes)$/i.test(answer.trim());
-}
-
 export async function resolveLaunchBorgApprovals(
   cli: BorgCli,
-  io: ApprovalIo
+  io: ApprovalIo,
+  options: { skipOverride?: boolean } = {}
 ): Promise<LaunchApprovalDecision> {
   if (cli === 'claude') return { codexArgs: [] };
 
@@ -611,18 +608,10 @@ export async function resolveLaunchBorgApprovals(
   const intro =
     `${cli === 'codex' ? 'Codex' : 'OpenCode'} requires approval for ${inspection.restrictiveTools.length} Borg tool${inspection.restrictiveTools.length === 1 ? '' : 's'}. ` +
     BORG_DISPATCHER_APPROVAL_DISCLOSURE;
-  if (!io.isTTY()) {
+  if (options.skipOverride) {
     return {
       codexArgs: [],
-      warning: `${intro} Re-run in a terminal to approve a launch-only fix, or add:\n${inspection.repairSnippet}`,
-    };
-  }
-
-  const answer = await io.confirm(`${intro} Apply this launch-only Borg approval set? [y/N] `);
-  if (!accepted(answer)) {
-    return {
-      codexArgs: [],
-      warning: `${intro} Continuing without the launch-only fix. To repair it globally, add:\n${inspection.repairSnippet}`,
+      warning: `${intro} Continuing without the launch-only fix because --no-borg-approval-override was supplied. To repair it globally, add:\n${inspection.repairSnippet}`,
     };
   }
 
@@ -645,7 +634,10 @@ export async function resolveLaunchBorgApprovals(
         warning: `Codex managed policy prevents the launch-only Borg approval override. Ask your Codex administrator to allow these tools:\n${effectiveWithOverride.repairSnippet}`,
       };
     }
-    return { codexArgs };
+    return {
+      codexArgs,
+      warning: `${intro} Applied a launch-only approval override. Pass --no-borg-approval-override to opt out.`,
+    };
   }
   const openCodePermission = JSON.stringify(mergeOpenCodePermission(
     openCodeConfig && typeof openCodeConfig === 'object'
@@ -673,6 +665,7 @@ export async function resolveLaunchBorgApprovals(
   return {
     codexArgs: [],
     openCodePermission,
+    warning: `${intro} Applied a launch-only approval override. Pass --no-borg-approval-override to opt out.`,
   };
 }
 

package/src/index.ts

@@ -41,6 +41,7 @@ import {
   createRole,
   updateRole,
   patchRoleSection,
+  sanitizeServerAdvisory,
   patchTaxonomyClass,
   deleteRole,
   getCube,
@@ -132,7 +133,9 @@ import { resolveReportableSessionAgentKind } from './agent-runtime.js';
 import {
   connectOpenCodeDrone,
   injectOpenCodeEntry,
-  computeOpenCodePort,
+  configuredOpenCodePort,
+  OPEN_CODE_PORT_MISSING_DIAGNOSTIC,
+  openCodeLaunchBinding,
 } from './opencode-drone.js';
 import { installBorgPlugin } from './opencode-plugin.js';
 import { setModuleInjectOpenCode } from './log-stream.js';
@@ -216,6 +219,57 @@ async function requireActiveCube() {
   return active;
 }
 
+export function appendServerAdvisory(text: string, advisory: unknown): string {
+  const sanitized = sanitizeServerAdvisory(advisory);
+  return sanitized === undefined ? text : `${text}\n\nAdvisory: ${sanitized}`;
+}
+
+export function formatUpdatedCubeResult(cube: { name: string; id: string }, advisory?: unknown): string {
+  return appendServerAdvisory(`Updated cube **${cube.name}** (id: ${cube.id}).`, advisory);
+}
+
+export function formatUpdatedRoleResult(role: { name: string; id: string; role_class?: string; is_human_seat?: boolean; is_default?: boolean; is_mandatory?: boolean }, advisory?: unknown): string {
+  const tags = [
+    role.role_class === 'queen' ? 'Queen' : null,
+    role.is_human_seat ? 'human-seat' : null,
+    role.is_default ? 'default' : null,
+    role.is_mandatory ? 'mandatory' : null,
+  ].filter(Boolean).join(', ');
+  const tag = tags ? ` (${tags})` : '';
+  return appendServerAdvisory(`Updated role **${role.name}**${tag} (id: ${role.id}).`, advisory);
+}
+
+export function formatPatchedRoleSectionResult(action: 'replace' | 'insert' | 'delete', heading: string, role: { name: string; id: string }, advisory?: unknown): string {
+  const verb = action === 'replace' ? 'Replaced' : action === 'insert' ? 'Inserted' : 'Deleted';
+  return appendServerAdvisory(`${verb} section **${heading}** in role **${role.name}** (id: ${role.id}).`, advisory);
+}
+
+export async function connectOpenCodeRuntime(
+  active: {
+    worktree?: string;
+    droneLabel: string;
+    name: string;
+  },
+  env: NodeJS.ProcessEnv = process.env,
+  deps: {
+    connect?: typeof connectOpenCodeDrone;
+  } = {},
+): Promise<boolean> {
+  const configuredPort = configuredOpenCodePort(env);
+  if (configuredPort === null) {
+    console.error(OPEN_CODE_PORT_MISSING_DIAGNOSTIC);
+    return false;
+  }
+  const binding = openCodeLaunchBinding(configuredPort);
+  await (deps.connect ?? connectOpenCodeDrone)({
+    serverUrl: binding.serverUrl,
+    directory: active.worktree ?? findProjectRoot(),
+    droneLabel: active.droneLabel,
+    cubeName: active.name,
+  });
+  return true;
+}
+
 /**
  * Main entry point - MCP stdio server
  */
@@ -266,15 +320,7 @@ export async function main() {
       installBorgPlugin();
       const active = await getActiveCube();
       if (active && openCodeRuntime) {
-        const port = computeOpenCodePort(active.droneId);
-        const serverUrl = `http://127.0.0.1:${port}`;
-        await connectOpenCodeDrone({
-          serverUrl,
-          directory: active.worktree ?? findProjectRoot(),
-          droneLabel: active.droneLabel,
-          cubeName: active.name,
-        });
-        setModuleInjectOpenCode(injectOpenCodeEntry);
+        if (await connectOpenCodeRuntime(active)) setModuleInjectOpenCode(injectOpenCodeEntry);
       }
     },
   };
@@ -1018,8 +1064,8 @@ export async function main() {
           if (typeof args?.cube_directive === 'string') updates.cube_directive = args.cube_directive as string;
           if (Array.isArray(args?.message_taxonomy)) updates.message_taxonomy = args.message_taxonomy as MessageTaxonomy;
           if (Object.keys(updates).length === 0) throw new Error('Pass at least one of: cube_directive, message_taxonomy.');
-          const { cube } = await updateCube(cubeId, updates);
-          return { content: [{ type: 'text', text: `Updated cube **${cube.name}** (id: ${cube.id}).` }] };
+          const { cube, advisory } = await updateCube(cubeId, updates);
+          return { content: [{ type: 'text', text: formatUpdatedCubeResult(cube, advisory) }] };
         }
 
         case 'borg_patch-taxonomy-class': {
@@ -1108,15 +1154,8 @@ export async function main() {
           if (typeof args?.receives_all_direct === 'boolean') updates.receives_all_direct = args.receives_all_direct as boolean;
           if (typeof args?.default_model === 'string') updates.default_model = args.default_model as string;
           if (Object.keys(updates).length === 0) throw new Error('Pass at least one of: name, short_description, detailed_description, is_default, is_mandatory, is_human_seat, can_broadcast, receives_all_direct.');
-          const { role } = await updateRole(roleId, updates);
-          const tags = [
-            role.role_class === 'queen' ? 'Queen' : null,
-            role.is_human_seat ? 'human-seat' : null,
-            role.is_default ? 'default' : null,
-            role.is_mandatory ? 'mandatory' : null,
-          ].filter(Boolean).join(', ');
-          const tag = tags ? ` (${tags})` : '';
-          return { content: [{ type: 'text', text: `Updated role **${role.name}**${tag} (id: ${role.id}).` }] };
+          const { role, advisory } = await updateRole(roleId, updates);
+          return { content: [{ type: 'text', text: formatUpdatedRoleResult(role, advisory) }] };
         }
 
         case 'borg_patch-role-section': {
@@ -1129,8 +1168,9 @@ export async function main() {
           const heading = args?.heading as string;
           if (!heading) throw new Error('heading is required');
           let role: any;
+          let advisory: unknown;
           if (action === 'delete') {
-            ({ role } = await patchRoleSection(roleId, { action, heading }));
+            ({ role, advisory } = await patchRoleSection(roleId, { action, heading }));
           } else {
             const body = args?.body as string;
             if (typeof body !== 'string') {
@@ -1138,13 +1178,12 @@ export async function main() {
             }
             if (action === 'insert') {
               const after = (typeof args?.after === 'string' ? args.after : null) as string | null;
-              ({ role } = await patchRoleSection(roleId, { action, heading, body, after }));
+              ({ role, advisory } = await patchRoleSection(roleId, { action, heading, body, after }));
             } else {
-              ({ role } = await patchRoleSection(roleId, { action, heading, body }));
+              ({ role, advisory } = await patchRoleSection(roleId, { action, heading, body }));
             }
           }
-          const verb = action === 'replace' ? 'Replaced' : action === 'insert' ? 'Inserted' : 'Deleted';
-          return { content: [{ type: 'text', text: `${verb} section **${heading}** in role **${role.name}** (id: ${role.id}).` }] };
+          return { content: [{ type: 'text', text: formatPatchedRoleSectionResult(action, heading, role, advisory) }] };
         }
 
         case 'borg_delete-role': {

package/src/opencode-drone.ts

@@ -1,5 +1,6 @@
 import { appendFileSync, existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
 import { createHash, randomUUID } from 'crypto';
+import { createServer } from 'node:net';
 import { join } from 'path';
 import { tmpdir } from 'os';
 
@@ -749,6 +750,62 @@ export function computeOpenCodePort(droneId: string, base: number = 14096): numb
   return base + (Math.abs(hash) % 1024);
 }
 
+/**
+ * Ask the OS for an available loopback port. The old deterministic hash is
+ * retained above only for compatibility fixtures; launch paths must not use a
+ * bounded shared port space where two drones can collide.
+ */
+async function canBindOpenCodePort(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const probe = createServer();
+    probe.once('error', () => resolve(false));
+    probe.listen(port, '127.0.0.1', () => {
+      probe.close(() => resolve(true));
+    });
+  });
+}
+
+export function configuredOpenCodePort(env: NodeJS.ProcessEnv = process.env): number | null {
+  const port = Number(env.BORG_OPENCODE_PORT);
+  return Number.isInteger(port) && port > 0 && port <= 65_535 ? port : null;
+}
+
+export const OPEN_CODE_PORT_MISSING_DIAGNOSTIC =
+  'OpenCode launch port is missing; skipping OpenCode entry injection. Relaunch through borg.';
+
+export function openCodeLaunchBinding(port: number): {
+  cliPort: string;
+  envPort: string;
+  serverUrl: string;
+} {
+  const value = String(port);
+  return { cliPort: value, envPort: value, serverUrl: `http://127.0.0.1:${value}` };
+}
+
+export async function allocateOpenCodePort(
+  isPortAvailable: (port: number) => Promise<boolean> = canBindOpenCodePort,
+): Promise<number> {
+  for (let attempt = 0; attempt < 8; attempt++) {
+    const port = await new Promise<number>((resolve, reject) => {
+      const probe = createServer();
+      const fail = (error: Error) => {
+        probe.close(() => reject(error));
+      };
+      probe.once('error', fail);
+      probe.listen(0, '127.0.0.1', () => {
+        const address = probe.address();
+        if (address === null || typeof address === 'string') {
+          fail(new Error('OpenCode port allocation returned no TCP address'));
+          return;
+        }
+        probe.close((error) => error ? reject(error) : resolve(address.port));
+      });
+    });
+    if (await isPortAvailable(port)) return port;
+  }
+  throw new Error('OpenCode port allocation could not claim an available loopback port');
+}
+
 /** Test-only cleanup for module state and the local cross-process binding. */
 export function __resetOpenCodeDroneForTests(): void {
   abandonOpenCodeDeliveries(state);

package/src/parse-assimilate-args.ts

@@ -16,7 +16,7 @@ export type ParseResult =
 
 /**
  * Parse argv for `borg assimilate [role] [--worktree <n>] [--template <n>]
- * [--no-template] [--cube-name <n>] [--host <host>] [--enroll] [--here] [--force] [--yes]`. The `assimilate`
+ * [--no-template] [--cube-name <n>] [--host <host>] [--enroll] [--here] [--force] [--yes] [--no-borg-approval-override]`. The `assimilate`
  * subcommand token must already be stripped by the caller.
  */
 export function parseAssimilateArgs(rawArgs: string[]): ParseResult {
@@ -53,6 +53,8 @@ export function parseAssimilateArgs(rawArgs: string[]): ParseResult {
       flags.here = true;
     } else if (arg === '--force') {
       flags.force = true;
+    } else if (arg === '--no-borg-approval-override') {
+      flags.noBorgApprovalOverride = true;
     } else if (arg === '--host') {
       const next = rawArgs[i + 1];
       if (typeof next !== 'string' || next.length === 0 || next.startsWith('-')) {
@@ -106,7 +108,7 @@ export function parseAssimilateArgs(rawArgs: string[]): ParseResult {
     } else if (arg.startsWith('--')) {
       return {
         ok: false,
-        error: `unknown flag: ${arg}. Supported: --worktree, --template, --no-template, --cube-name, --host, --enroll, --here, --force, --yes, --cli, --model`,
+        error: `unknown flag: ${arg}. Supported: --worktree, --template, --no-template, --cube-name, --host, --enroll, --here, --force, --yes, --cli, --model, --no-borg-approval-override`,
       };
     } else {
       if (role !== undefined) {

package/src/remote-client.ts

@@ -85,10 +85,27 @@ export const LOCAL_SERVER_RESPONSE_LIMIT_BYTES = 32 * 1024 * 1024;
 // bounded read throws → the 401 fails closed to non-destructive CREDENTIAL_REJECTED.
 const AUTH_ERROR_ENVELOPE_LIMIT_BYTES = 64 * 1024;
 const ROLE_SECTION_CONFLICT_CODE = 'ROLE_SECTION_CONFLICT';
+const CAPACITY_EXCEEDED_CODE = 'CAPACITY_EXCEEDED';
 export const LOCAL_SERVER_REQUEST_TIMEOUT_MS = 5_000;
 const LOCAL_SERVER_RESPONSE_LIMIT_MESSAGE =
   'Local Borg server response exceeded the response limit';
 
+function sanitizeServerMessage(message: string): string {
+  return message
+    .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, '')
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+    .replace(/[\u0000-\u001f\u007f-\u009f]/g, '')
+    .replace(/\\u(?:000[0-9a-f]|001[0-9a-f]|007f|008[0-9a-f]|009[0-9a-f])/gi, '');
+}
+
+export const SERVER_ADVISORY_MAX_CHARS = 512;
+
+export function sanitizeServerAdvisory(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const sanitized = sanitizeServerMessage(value).trim();
+  return sanitized.length > 0 ? sanitized.slice(0, SERVER_ADVISORY_MAX_CHARS) : undefined;
+}
+
 /**
  * Parse a `Retry-After` header (delta-seconds form, which the worker
  * emits — mcp-server.ts:382/583) into milliseconds. Returns null when
@@ -725,11 +742,11 @@ async function authedFetch(
   }
 
   if (!response.ok) {
-    // Do not copy a server response body into errors or debug output: a malicious or
-    // misconfigured server could reflect bearer/invitation material or inject
-    // terminal controls. Decode only the bounded protocol error code for typed
-    // branching; never surface the server-provided message or details.
+    // Decode only the bounded protocol error envelope. Its message is the
+    // server's operator-facing action guidance; details and unrecognized bodies
+    // remain excluded from the client error.
     let code: ErrorCode | undefined;
+    let serverMessage: string | undefined;
     let protocolMismatch = false;
     try {
       const body = await readBoundedResponseBody(
@@ -739,7 +756,11 @@ async function authedFetch(
       );
       const parsed = JSON.parse(body);
       try {
-        code = decodeProtocolErrorEnvelope(parsed).error.code;
+        const decoded = decodeProtocolErrorEnvelope(parsed);
+        code = decoded.error.code;
+        serverMessage = response.status === 404
+          ? undefined
+          : sanitizeServerMessage(decoded.error.message);
       } catch (error) {
         if (
           error instanceof ProtocolContractError &&
@@ -750,21 +771,25 @@ async function authedFetch(
         if (
           parsed !== null && typeof parsed === 'object' &&
           parsed.error !== null && typeof parsed.error === 'object' &&
-          parsed.error.code === ROLE_SECTION_CONFLICT_CODE
+          (parsed.error.code === ROLE_SECTION_CONFLICT_CODE
+            || parsed.error.code === CAPACITY_EXCEEDED_CODE)
         ) {
           // The shared protocol intentionally omits this server-local code. Re-validate the whole
           // envelope through the strict shared decoder with only the recognized
-          // code substituted; no server-provided diagnostic is ever surfaced.
-          decodeProtocolErrorEnvelope({
+          // code substituted. The original message remains in place so the
+          // shared decoder validates its length and diagnostic shape.
+          const decoded = decodeProtocolErrorEnvelope({
             ...parsed,
             error: {
               ...parsed.error,
               code: ErrorCode.INVALID_INPUT,
-              message: 'Role section conflict.',
               ...(Object.hasOwn(parsed.error, 'details') ? { details: 'Redacted.' } : {}),
             },
           });
-          code = ROLE_SECTION_CONFLICT_CODE as ErrorCode;
+          code = parsed.error.code as ErrorCode;
+          serverMessage = response.status === 404
+            ? undefined
+            : sanitizeServerMessage(decoded.error.message);
         }
       }
     } catch {
@@ -782,7 +807,9 @@ async function authedFetch(
     }
     throw new BorgServerHttpError(
       response.status,
-      `Borg server request failed (HTTP ${response.status})`,
+      serverMessage
+        ? `Borg server request failed (HTTP ${response.status}): ${serverMessage}`
+        : `Borg server request failed (HTTP ${response.status})`,
       code,
     );
   }
@@ -1302,7 +1329,7 @@ export async function updateCube(
   updates: { name?: string; cube_directive?: string; message_taxonomy?: MessageTaxonomy | null },
   activeOverride?: ActiveCube,
   connectionOverride?: RemoteConnection,
-): Promise<{ cube: any }> {
+): Promise<{ cube: any; advisory?: unknown }> {
   assertUuidShape(cubeId, 'cube_id');
   const active = activeOverride ?? await getActiveCube();
   if (!active?.serverTrustIdentity) throw new Error('Selected Borg server authority state is missing or unreadable');
@@ -1438,7 +1465,7 @@ export async function updateRole(
   targetCubeId?: string,
   activeOverride?: ActiveCube,
   connectionOverride?: RemoteConnection,
-): Promise<{ role: any }> {
+): Promise<{ role: any; advisory?: unknown }> {
   assertUuidShape(roleId, 'role_id');
   const active = activeOverride ?? await getActiveCube();
   if (!active?.serverTrustIdentity) throw new Error('Selected Borg server authority state is missing or unreadable');
@@ -1514,7 +1541,7 @@ export async function patchRoleSection(
   targetCubeId?: string,
   activeOverride?: ActiveCube,
   connectionOverride?: RemoteConnection,
-): Promise<{ role: any }> {
+): Promise<{ role: any; advisory?: unknown }> {
   assertUuidShape(roleId, 'role_id');
   const active = activeOverride ?? await getActiveCube();
   if (!active?.serverTrustIdentity) throw new Error('Selected Borg server authority state is missing or unreadable');