borgmcp 3.11.0 → 3.12.0

package/src/opencode-drone.ts

@@ -1,12 +1,19 @@
 import { appendFileSync, existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
-import { createHash, randomUUID } from 'crypto';
+import { createHash } from 'crypto';
 import { createServer } from 'node:net';
 import { join } from 'path';
 import { tmpdir } from 'os';
 import {
   OPENCODE_INJECTED_ENTRY_METADATA_KEY,
   OPENCODE_WAKE_IDENTITY_METADATA_KEY,
+  OPENCODE_LAUNCH_CORRELATION_METADATA_KEY,
 } from './opencode-plugin.js';
+import {
+  createOpenCodeLaunchTrust,
+  isOpenCode256BitIdentity,
+  OPENCODE_SERVER_USERNAME,
+  type OpenCodeLaunchTrust,
+} from './opencode-launch-trust.js';
 
 const LOG_FILE = join(tmpdir(), 'borg-opencode-drone.log');
 function log(msg: string) {
@@ -16,6 +23,7 @@ function log(msg: string) {
 
 interface OpenCodeDroneState {
   serverUrl: string;
+  apiPassword: string;
   sessionId: string | null;
   sessionCreatedAt: number | null;
   knownRootSessionIds: string[];
@@ -39,6 +47,7 @@ let state: OpenCodeDroneState | null = null;
 
 interface ConnectDeps {
   serverUrl: string;
+  apiPassword: string;
   directory: string;
   droneLabel: string;
   cubeName: string;
@@ -80,6 +89,7 @@ interface OpenCodeDelivery {
   acceptedSubmission: boolean;
   sessionId: string | null;
   settled: boolean;
+  isSourcePending?: () => Promise<boolean>;
   state: Exclude<OpenCodeDeliveryState, 'failed'>;
   resolve: (delivered: boolean) => void;
   promise: Promise<boolean>;
@@ -124,27 +134,23 @@ interface SessionBinding {
 
 export interface OpenCodeLaunchKickoff {
   prompt: string;
-  nonce: string;
+  apiPassword: string;
+  correlationIdentity: string;
 }
 
-// This is correlation metadata, intentionally not an instruction to the
-// launched agent. A markdown comment keeps it benign in the user-visible
-// kickoff while preserving it in OpenCode's stored message text.
-const OPEN_CODE_LAUNCH_NONCE_MARKER = 'borg-opencode-correlation:';
-
 /**
- * Add a launch-unique identity to the OpenCode-only copy of the shared
- * kickoff. The prompt is what OpenCode records as its first user message, so
- * the launcher can later bind the MCP child to this precise launch instead of
- * guessing from a repeated kickoff's text or timestamp.
+ * Create independent launch trust for OpenCode without changing the shared
+ * kickoff text. The plugin writes the correlation identity to hidden metadata
+ * on the first qualifying human TextPart; the API password stays in env.
  */
 export function createOpenCodeLaunchKickoff(
   kickoff: string,
-  nonce: string = randomUUID(),
+  trust: Partial<OpenCodeLaunchTrust> = {},
 ): OpenCodeLaunchKickoff {
+  const launchTrust = createOpenCodeLaunchTrust(trust);
   return {
-    prompt: `${kickoff}\n\n<!-- ${OPEN_CODE_LAUNCH_NONCE_MARKER}${nonce} -->`,
-    nonce,
+    prompt: kickoff,
+    ...launchTrust,
   };
 }
 
@@ -161,9 +167,13 @@ function abandonOpenCodeDeliveries(current: OpenCodeDroneState | null): void {
 }
 
 export async function connectOpenCodeDrone(deps: ConnectDeps): Promise<void> {
+  if (!isOpenCode256BitIdentity(deps.apiPassword)) {
+    throw new Error('OpenCode API password is missing or unverifiable');
+  }
   abandonOpenCodeDeliveries(state);
   state = {
     serverUrl: deps.serverUrl,
+    apiPassword: deps.apiPassword,
     sessionId: null,
     sessionCreatedAt: null,
     knownRootSessionIds: [],
@@ -194,6 +204,17 @@ function apiUrl(path: string): string {
   return `${base}${path}${path.includes('?') ? '&' : '?'}directory=${encodeURIComponent(state!.directory)}`;
 }
 
+function authenticatedHeaders(headers: Record<string, string> = {}): Record<string, string> {
+  const password = state?.apiPassword;
+  if (!isOpenCode256BitIdentity(password)) {
+    throw new Error('OpenCode API password is missing or unverifiable');
+  }
+  return {
+    ...headers,
+    Authorization: `Basic ${Buffer.from(`${OPENCODE_SERVER_USERNAME}:${password}`).toString('base64')}`,
+  };
+}
+
 const FETCH_TIMEOUT = 10_000;
 
 async function rawGet(path: string): Promise<{ status: number; body: string }> {
@@ -201,7 +222,7 @@ async function rawGet(path: string): Promise<{ status: number; body: string }> {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
   try {
-    const res = await fetch(url, { signal: controller.signal });
+    const res = await fetch(url, { headers: authenticatedHeaders(), signal: controller.signal });
     const body = await res.text();
     return { status: res.status, body };
   } finally {
@@ -216,7 +237,7 @@ async function rawPost(path: string, bodyObj: unknown): Promise<{ status: number
   try {
     const res = await fetch(url, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: authenticatedHeaders({ 'Content-Type': 'application/json' }),
       signal: controller.signal,
       body: JSON.stringify(bodyObj),
     });
@@ -453,28 +474,29 @@ async function findUnseenTopLevelSession(knownRootSessionIds: string[]): Promise
   }
 }
 
-function kickoffMessageTime(messages: OCMessage[], nonce: string): number | null {
-  let latest: number | null = null;
+function launchCorrelationMatchCount(messages: OCMessage[], correlationIdentity: string): number {
+  let count = 0;
   for (const message of messages) {
-    if (message.info?.role && message.info.role !== 'user') continue;
-    const matchesLaunchNonce = message.parts?.some(
-      (part) => part.type === 'text' && part.text?.includes(`${OPEN_CODE_LAUNCH_NONCE_MARKER}${nonce}`),
-    );
-    if (!matchesLaunchNonce) continue;
-    const created = message.info?.time?.created ?? 0;
-    latest = latest === null ? created : Math.max(latest, created);
+    if (message.info?.role !== 'user') continue;
+    for (const part of message.parts ?? []) {
+      if (
+        part.type === 'text' &&
+        part.metadata?.[OPENCODE_LAUNCH_CORRELATION_METADATA_KEY] === correlationIdentity
+      ) {
+        count++;
+      }
+    }
   }
-  return latest;
+  return count;
 }
 
 /**
  * The launch process is the only place allowed to discover a session from the
- * server. It chooses the session that contains this launch's unique nonce,
- * rather than choosing by repeated kickoff text or session creation time. A
- * fork is therefore allowed only when it was explicitly selected for this
- * launch and received the nonce-bearing kickoff.
+ * server. It chooses the session containing exactly one hidden metadata match,
+ * never repeated prompt text, timestamps, or newest-session order. A fork is
+ * therefore allowed only when it received this launch's correlation metadata.
  */
-async function findLaunchSession(nonce: string): Promise<{
+async function findLaunchSession(correlationIdentity: string): Promise<{
   session: OCSession;
   knownRootSessionIds: string[];
 } | null> {
@@ -485,25 +507,17 @@ async function findLaunchSession(nonce: string): Promise<{
     const knownRootSessionIds = sessions
       .filter(isTopLevelSession)
       .map((session) => session.id);
-    const candidates = await Promise.all(sessions.map(async (session) => {
-      try {
-        const messageTime = kickoffMessageTime(
-          await listSessionMessages(session.id),
-          nonce,
-        );
-        return messageTime === null ? null : { session, messageTime };
-      } catch {
-        return null;
-      }
-    }));
-    const matched = candidates.filter(
-      (candidate): candidate is { session: OCSession; messageTime: number } => candidate !== null,
-    );
-    if (matched.length === 0) return null;
-    const session = matched.reduce((best, candidate) =>
-      candidate.messageTime > best.messageTime ? candidate : best,
-    ).session;
-    return { session, knownRootSessionIds };
+    const candidates = await Promise.all(sessions.map(async (session) => ({
+      session,
+      matchCount: launchCorrelationMatchCount(
+        await listSessionMessages(session.id),
+        correlationIdentity,
+      ),
+    })));
+    const totalMatches = candidates.reduce((total, candidate) => total + candidate.matchCount, 0);
+    if (totalMatches !== 1) return null;
+    const matched = candidates.find((candidate) => candidate.matchCount === 1);
+    return matched ? { session: matched.session, knownRootSessionIds } : null;
   } catch {
     return null;
   }
@@ -615,6 +629,14 @@ async function deliverOpenCodeEntry(
 ): Promise<OpenCodeDeliveryOutcome> {
   let target: OCSession | null = null;
 
+  const sourcePending = async (): Promise<boolean> => {
+    if (!delivery.isSourcePending) return true;
+    if (await delivery.isSourcePending()) return true;
+    delivery.settled = true;
+    settleOpenCodeEntry(delivery.sourceEntryId);
+    return false;
+  };
+
   // Before the one allowed POST, retries are safe: no submission has happened.
   // OpenCode must generate the message ID: its run loop treats IDs as
   // lexicographically ordered, so arbitrary caller IDs can persist without
@@ -623,6 +645,7 @@ async function deliverOpenCodeEntry(
   for (let attempt = 0; attempt < OPEN_CODE_DELIVERY_RETRY_DELAYS_MS.length; attempt++) {
     if (delivery.settled) return 'delivered';
     if (state !== owner || !owner.connected) return 'failed';
+    if (!(await sourcePending())) return 'delivered';
     if (attempt > 0) {
       delivery.state = 'retried';
       owner.totalEntriesRetried++;
@@ -675,6 +698,7 @@ async function deliverOpenCodeEntry(
       delivery.state = 'delivered-unconfirmed';
     } else {
       if (delivery.settled) return 'delivered';
+      if (!(await sourcePending())) return 'delivered';
       owner.pendingSubmissions.set(delivery.entryId, {
         sourceEntryId: delivery.sourceEntryId,
         sessionId: target.id,
@@ -795,11 +819,15 @@ async function processOpenCodeDeliveries(owner: OpenCodeDroneState): Promise<voi
 
 /**
  * Wait for the OpenCode HTTP server, then capture the session that received
- * this launch's nonce-bearing `--prompt` kickoff. The binding survives the separate
- * MCP-child process, which must never fall back to a newest-session heuristic.
+ * this launch's metadata-correlated `--prompt` kickoff. The binding survives
+ * the separate MCP-child process, which must never fall back to a newest-session heuristic.
  */
 export async function injectInitialKickoff(launch: OpenCodeLaunchKickoff): Promise<boolean> {
   if (!state?.connected) { log('kickoff: not connected'); return false; }
+  if (!isOpenCode256BitIdentity(launch.correlationIdentity)) {
+    log('kickoff: correlation identity missing or unverifiable');
+    return false;
+  }
 
   try {
     // Wait for the server.
@@ -815,9 +843,9 @@ export async function injectInitialKickoff(launch: OpenCodeLaunchKickoff): Promi
     }
 
     // Capture the launch-selected session, including explicit resume/fork
-    // targets. Unrelated sessions do not contain this launch's nonce.
+    // targets. Unrelated sessions do not contain this launch's metadata identity.
     for (let i = 0; i < 30; i++) {
-      const binding = await findLaunchSession(launch.nonce);
+      const binding = await findLaunchSession(launch.correlationIdentity);
       if (binding) {
         saveBinding(binding.session, binding.knownRootSessionIds);
         log(`kickoff: bound session ${binding.session.id.slice(0, 8)}…`);
@@ -847,6 +875,7 @@ export function injectOpenCodeEntry(
   entryId: string = createHash('sha256').update(text).digest('hex'),
   allowSubmit: boolean = true,
   sourceEntryId: string = entryId,
+  isSourcePending?: () => Promise<boolean>,
 ): Promise<boolean> {
   const owner = state;
   if (!owner?.connected) {
@@ -865,7 +894,7 @@ export function injectOpenCodeEntry(
   );
   if (pendingSource) {
     log(`entry ${entryId} reconciles pending source ${sourceEntryId}`);
-    return injectOpenCodeEntry(text, pendingSource[0], false, sourceEntryId);
+    return injectOpenCodeEntry(text, pendingSource[0], false, sourceEntryId, isSourcePending);
   }
   for (const [deliveredEntryId, record] of owner.deliveredEntries) {
     if (deliveredEntryId !== entryId && record.sourceEntryId === sourceEntryId) {
@@ -950,6 +979,7 @@ export function injectOpenCodeEntry(
     acceptedSubmission: false,
     sessionId: null,
     settled: false,
+    isSourcePending,
     state: 'queued',
     resolve: resolveDelivery,
     promise,

package/src/opencode-launch-trust.ts

@@ -0,0 +1,46 @@
+import { randomBytes } from 'node:crypto';
+
+export const OPENCODE_SERVER_USERNAME = 'opencode';
+export const OPENCODE_SERVER_USERNAME_ENV = 'OPENCODE_SERVER_USERNAME';
+export const OPENCODE_SERVER_PASSWORD_ENV = 'OPENCODE_SERVER_PASSWORD';
+export const BORG_OPENCODE_LAUNCH_CORRELATION_ENV = 'BORG_OPENCODE_LAUNCH_CORRELATION';
+export const OPENCODE_SERVER_PASSWORD_REFERENCE = `{env:${OPENCODE_SERVER_PASSWORD_ENV}}`;
+
+export interface OpenCodeLaunchTrust {
+  apiPassword: string;
+  correlationIdentity: string;
+}
+
+function random256BitIdentity(): string {
+  return randomBytes(32).toString('base64url');
+}
+
+export function createOpenCodeLaunchTrust(overrides: Partial<OpenCodeLaunchTrust> = {}): OpenCodeLaunchTrust {
+  const trust = {
+    apiPassword: overrides.apiPassword ?? random256BitIdentity(),
+    correlationIdentity: overrides.correlationIdentity ?? random256BitIdentity(),
+  };
+  if (!isOpenCode256BitIdentity(trust.apiPassword) || !isOpenCode256BitIdentity(trust.correlationIdentity)) {
+    throw new Error('OpenCode launch trust must contain independent 256-bit identities');
+  }
+  if (trust.apiPassword === trust.correlationIdentity) {
+    throw new Error('OpenCode API password and correlation identity must be independent');
+  }
+  return trust;
+}
+
+export function isOpenCode256BitIdentity(value: unknown): value is string {
+  if (typeof value !== 'string' || value.length === 0) return false;
+  try {
+    const decoded = Buffer.from(value, 'base64url');
+    return decoded.length === 32 && decoded.toString('base64url') === value;
+  } catch {
+    return false;
+  }
+}
+
+export function openCodeApiPasswordFromEnv(env: NodeJS.ProcessEnv): string | null {
+  if (env[OPENCODE_SERVER_USERNAME_ENV] !== OPENCODE_SERVER_USERNAME) return null;
+  const password = env[OPENCODE_SERVER_PASSWORD_ENV];
+  return isOpenCode256BitIdentity(password) ? password : null;
+}

package/src/opencode-plugin.ts

@@ -20,6 +20,7 @@ const COMPACT_FALLBACK =
 export const OPENCODE_INJECTED_ENTRY_METADATA_KEY = 'borgOpenCodeInjectedEntry';
 export const OPENCODE_WAKE_IDENTITY_METADATA_KEY = 'borgOpenCodeWakeIdentity';
 export const OPENCODE_RECOVERY_METADATA_KEY = 'borgOpenCodeSessionOrientation';
+export const OPENCODE_LAUNCH_CORRELATION_METADATA_KEY = 'borgOpenCodeLaunchCorrelation';
 const PLUGIN_REL_PATH = path.join('.config', 'opencode', 'plugins', 'borg-orient.js');
 
 export interface OpenCodePluginCoreDeps {
@@ -45,6 +46,8 @@ export interface OpenCodePluginCoreOptions {
   confirmationPollAttempts: number;
   pollDelayMs: number;
   compactFallback: string;
+  launchCorrelationMetadataKey: string;
+  launchCorrelationIdentity: string;
 }
 
 /** Pure, dependency-injected behavior core. Its emitted JavaScript function
@@ -55,6 +58,7 @@ export function createOpenCodePluginCore(
 ) {
   const claimedSessions = new Set<string>();
   const humanPromptSessions = new Set<string>();
+  let launchCorrelationAttached = false;
   const textParts = (message: any): any[] => Array.isArray(message?.parts)
     ? message.parts.filter((part: any) => part?.type === 'text' && typeof part.text === 'string')
     : [];
@@ -129,7 +133,28 @@ export function createOpenCodePluginCore(
       output: { message: unknown; parts: any[] },
     ): Promise<void> => {
       if (!options.enabled) return;
-      const current = { info: { role: 'user' }, parts: [...output.parts] };
+      let current = { info: { role: 'user' }, parts: [...output.parts] };
+      if (
+        !launchCorrelationAttached &&
+        options.launchCorrelationIdentity &&
+        !isInjectedEntry(current) &&
+        !isOwnedRecovery(current)
+      ) {
+        const index = output.parts.findIndex((part) =>
+          part?.type === 'text' && typeof part.text === 'string');
+        if (index >= 0) {
+          const part = output.parts[index];
+          output.parts[index] = {
+            ...part,
+            metadata: {
+              ...(part.metadata && typeof part.metadata === 'object' ? part.metadata : {}),
+              [options.launchCorrelationMetadataKey]: options.launchCorrelationIdentity,
+            },
+          };
+          launchCorrelationAttached = true;
+          current = { info: { role: 'user' }, parts: [...output.parts] };
+        }
+      }
       if (!isInjectedEntry(current) && !isOwnedRecovery(current)) {
         // chat.message fires before the user message is persisted. Record the
         // human turn synchronously so recovery cannot race that short gap.
@@ -165,6 +190,7 @@ export function buildBorgPluginSource(version: string): string {
 const createCore = ${createOpenCodePluginCore.toString()};
 const evaluateAudit = ${evaluateLogAudit.toString()};
 export default async function (ctx) {
+  const launchCorrelationIdentity = process.env.BORG_OPENCODE_LAUNCH_CORRELATION || '';
   const runRegen = async (source) => {
     const input = JSON.stringify({ source });
     const result = await ctx.$\`printf '%s' \${input} | borg-regen\`.quiet().nothrow();
@@ -204,8 +230,12 @@ export default async function (ctx) {
     confirmationPollAttempts: 6,
     pollDelayMs: 200,
     compactFallback: COMPACT_FALLBACK,
+    launchCorrelationMetadataKey: OPENCODE_LAUNCH_CORRELATION_METADATA_KEY,
   })},
     enabled: process.env.BORG_SESSION === '1',
+    launchCorrelationIdentity: /^[A-Za-z0-9_-]{43}$/.test(launchCorrelationIdentity)
+      ? launchCorrelationIdentity
+      : '',
   });
 }
 `;

package/src/remote-client.ts

@@ -16,6 +16,7 @@ import {
 import { randomUUID } from 'node:crypto';
 import {
   createProtocolEnvelope,
+  decodeAppendLogResult,
   decodeDeleteCubeResponse,
   decodeDeleteRoleRequest,
   decodeDeleteRoleResult,
@@ -90,7 +91,7 @@ const UNREAD_CURSOR_MAX_TRANSPORT_RETRIES = 1;
 // Replay is opt-in: most local requests are mutations or have ambiguous
 // delivery, while unread-log reads carry an explicit cursor and are safe to
 // repeat with the exact same request body.
-type AuthedFetchRetryMode = 'unread-cursor';
+type AuthedFetchRetryMode = 'unread-cursor' | 'append-log';
 export const LOCAL_SERVER_RESPONSE_LIMIT_BYTES = 32 * 1024 * 1024;
 // A typed auth-error envelope is tiny; anything larger is hostile and the
 // bounded read throws → the 401 fails closed to non-destructive CREDENTIAL_REJECTED.
@@ -790,17 +791,17 @@ async function authedFetch(
     return res;
   };
 
-  let transportRetriesRemaining = retryMode === 'unread-cursor'
+  let transportRetriesRemaining = retryMode === 'unread-cursor' || retryMode === 'append-log'
     ? UNREAD_CURSOR_MAX_TRANSPORT_RETRIES
     : 0;
   const requestWithRetry = async (): Promise<Response> => {
     try {
       return await buildRequest(token);
     } catch (error) {
-      if (retryMode !== 'unread-cursor' || !isConnectionReset(error)) throw error;
+      if ((retryMode !== 'unread-cursor' && retryMode !== 'append-log') || !isConnectionReset(error)) throw error;
       if (transportRetriesRemaining === 0) throw unreadLogTransportFailure(error);
       transportRetriesRemaining -= 1;
-      debugLog('↻ retrying unread log read after ECONNRESET');
+      debugLog(`↻ retrying ${retryMode === 'append-log' ? 'log append' : 'unread log read'} after ECONNRESET`);
       try {
         return await buildRequest(token);
       } catch (retryError) {
@@ -1334,31 +1335,14 @@ export async function appendLog(
     to?: string[];
     serverTrustIdentity?: string;
   } = {}
-): Promise<{
-  entry: {
-    id: string;
-    cube_id: string;
-    drone_id: string;
-    message: string;
-    visibility: 'broadcast' | 'direct';
-    created_at: string;
-  };
-  routing?: {
-    class: string | null;
-    recipients: string[];
-    fellOpen: boolean;
-    message: string | null;
-  } | null;
-  // gh#534: directed recipients currently unreachable via the wake path
-  // (wake-path:deaf). Empty/absent for broadcast or all-reachable sends.
-  unreachableRecipients?: { id: string; label: string }[];
-}> {
+): Promise<ReturnType<typeof decodeAppendLogResult>> {
   if (opts.visibility === 'broadcast' && (opts.to?.length ?? 0) > 0) {
     throw new Error(
       "Invalid input: visibility:'broadcast' cannot be combined with non-empty to:. " +
       'Remove visibility to direct to recipients, or remove to: to broadcast.',
     );
   }
+  const postId = randomUUID();
   const local = await localAuthorityContext(
     sessionToken,
     apiUrl,
@@ -1386,11 +1370,12 @@ export async function appendLog(
     } else if (visibility === undefined && recipientDroneIds !== undefined) {
       visibility = 'direct';
     }
-    const payload = await localServerRequest<{ entry: any }>(
+    const payload = await localServerRequest<ReturnType<typeof decodeAppendLogResult>>(
       local,
       `/api/cubes/${local.cubeId}/logs`,
       'POST',
       {
+        post_id: postId,
         message,
         ...(visibility ? { visibility } : {}),
         ...(visibility === 'direct' && recipientDroneIds
@@ -1401,9 +1386,10 @@ export async function appendLog(
         // visibility/recipients override it (server resolveMessageRouting).
         ...(opts.class ? { class: opts.class } : {}),
       },
+      { retryMode: 'append-log', decodePayload: decodeAppendLogResult },
     );
     if (!payload) throw new Error('Local Borg server returned an empty log response');
-  return { entry: payload.entry };
+  return payload;
 }
 
 /**

package/src/server-handshake.ts

@@ -211,10 +211,11 @@ export interface ServerAttachResult {
     sessionId: string;
   };
   result: 'created' | 'reused';
+  initial_log_cursor: { id: string; created_at: string } | null;
 }
 
 /**
- * Attach an enrolled client principal to one granted cube/role over protocol v8.
+ * Attach an enrolled client principal to one granted cube/role over protocol v9.
  * The client CSPRNG-generates the session bearer and persists it PENDING in the
  * OS keychain (keyed by the stable per-seat identity) BEFORE this request, so an
  * interrupted/lost response is recovered by re-sending the exact same bearer —
@@ -237,6 +238,7 @@ export interface PreparedServerAttach {
   drone: ServerAttachResult['drone'];
   session: { sessionId: string };
   result: 'created' | 'reused';
+  initialLogCursor: ServerAttachResult['initial_log_cursor'];
   credentialRef: string;
   pendingBearerDigest: string;
   /** The single-store ATOMIC activate+bind (CR#2 collapse): given the worktree
@@ -391,6 +393,7 @@ export async function sendBorgServerAttach(
         sessionId: decoded.session.id,
       },
       result: decoded.result,
+      initialLogCursor: decoded.initial_log_cursor,
       credentialRef,
       pendingBearerDigest,
       // The single-store ATOMIC activate+bind — invoked by FINALIZE with the decided

package/src/setup-confirm.ts

@@ -28,7 +28,7 @@ export interface ConfigMutationTarget {
  * agent CLIs. Paths mirror `config-utils.ts`:
  *   Claude Code: ~/.claude.json (MCP server) + ~/.claude/settings.json (hook)
  *   Codex:       ~/.codex/config.toml (MCP server) + ~/.codex/hooks.json (hooks)
- *   OpenCode:    ~/.config/opencode/opencode.json (MCP server)
+ *   OpenCode:    effective global config under ~/.config/opencode/ (MCP server)
  */
 export function configMutationTargets(deps: {
   claude: boolean;
@@ -58,8 +58,8 @@ export function configMutationTargets(deps: {
   }
   if (deps.opencode) {
     targets.push({
-      file: '~/.config/opencode/opencode.json',
-      change: 'registers the borg MCP server (with BORG_SESSION activation)',
+      file: '~/.config/opencode/',
+      change: 'updates the effective global OpenCode configuration to register the borg MCP server (with BORG_SESSION activation)',
     });
   }
   return targets;