borgmcp 2.12.1 → 2.14.0

package/src/codex-app-wake.ts

@@ -21,12 +21,16 @@ import {
   shouldFireHeartbeat,
   type CodexThreadInfo,
 } from './codex-wake-resolve.js';
+import {
+  CUBE_ACTIVITY_RESUME_WAKE_MESSAGE,
+  formatCubeActivityWakeMessage,
+} from './cube-activity-wake-copy.js';
 
 export const CODEX_WAKE_PROMPT =
-  'New Borg cube-log activity arrived.';
+  CUBE_ACTIVITY_RESUME_WAKE_MESSAGE;
 
 export function formatCodexWakePrompt(inboxLine: string): string {
-  return `New Borg cube-log activity arrived:\n${inboxLine}`;
+  return formatCubeActivityWakeMessage(inboxLine);
 }
 
 // gh#708: STATIC catch-up/drain prompt (zero interpolation — no token/secret/PII/
@@ -36,7 +40,8 @@ export function formatCodexWakePrompt(inboxLine: string): string {
 // fire the already-shipped drain so no entry is skipped. gh#857 WI-2 reuses it as
 // the periodic heartbeat prompt.
 export const CODEX_CATCHUP_PROMPT =
-  'Borg cube activity arrived while you were busy. Wake triage: run `borg_read-log unread_only=true` and DRAIN — repeat until the returned page is under the limit and behind_by is 0 — so no entries are skipped. Then handle actionable entries; if none, resume the prior interrupted work.';
+  `${formatCubeActivityWakeMessage('Wake triage: repeat the drain until the returned page is under the limit and behind_by is 0 so no entries are skipped.')} ` +
+  'If there are no actionable entries, resume the prior interrupted work.';
 
 export function isCodexRemoteWakeEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
   return env[BORG_CODEX_REMOTE_WAKE_ENV] === '1';
@@ -92,6 +97,7 @@ export async function probeCodexBridgeArmed(
 let wakeInFlight = false;
 const pendingWakeRequests: Array<{
   reason: string;
+  deliveryIdentity?: string;
   deps: CodexWakeDeps;
 }> = [];
 const deliveredWakeKeys = new Set<string>();
@@ -272,11 +278,12 @@ async function maybePersistWakeTarget(
 export function wakeCodexViaAppServer(
   reason: string = CODEX_WAKE_PROMPT,
   env: NodeJS.ProcessEnv = process.env,
-  deps: CodexWakeDeps = {}
+  deps: CodexWakeDeps = {},
+  deliveryIdentity?: string,
 ): void {
   const target = resolveCodexWakeTarget(env);
   if (!target.enabled) return;
-  pendingWakeRequests.push({ reason, deps });
+  pendingWakeRequests.push({ reason, deliveryIdentity, deps });
   if (wakeInFlight) return;
 
   wakeInFlight = true;
@@ -288,11 +295,11 @@ export function wakeCodexViaAppServer(
 async function drainCodexWakeQueue(): Promise<void> {
   while (pendingWakeRequests.length > 0) {
     const request = pendingWakeRequests.shift()!;
-    await wakeCodexTargeted(request.reason, request.deps);
+    await wakeCodexTargeted(request.reason, request.deliveryIdentity, request.deps);
   }
 }
 
-async function wakeCodexTargeted(reason: string, deps: CodexWakeDeps): Promise<void> {
+async function wakeCodexTargeted(reason: string, deliveryIdentity: string | undefined, deps: CodexWakeDeps): Promise<void> {
   // gh#861 finding 1: another path (heartbeat/retry-drain) is mid-inject into the
   // same thread — defer to the retry-drain so this entry isn't double-injected nor
   // lost (the drain re-syncs the whole burst via the server read-cursor).
@@ -308,7 +315,7 @@ async function wakeCodexTargeted(reason: string, deps: CodexWakeDeps): Promise<v
     const resolved = await resolveFreshCodexWakeTarget(active, deps);
     if (!resolved) return;
     const { socketPath, threadId } = resolved;
-    const wakeKey = `${threadId}\0${reason}`;
+    const wakeKey = `${threadId}\0${deliveryIdentity ?? reason}`;
     if (deliveredWakeKeys.has(wakeKey)) return; // dedup before opening the wake socket
     const client = makeCodexClient(socketPath, deps);
     await client.connect();

package/src/cube-activity-wake-copy.ts

@@ -0,0 +1,6 @@
+export const CUBE_ACTIVITY_RESUME_WAKE_MESSAGE =
+  'Borg cube activity arrived while you were busy. Reading cube messages does not end your current task. Drain `borg_read-log unread_only=true` until caught up, handle actionable entries, then RESUME the interrupted work.';
+
+export function formatCubeActivityWakeMessage(detail: string): string {
+  return `${CUBE_ACTIVITY_RESUME_WAKE_MESSAGE}\n${detail}`;
+}

package/src/inbox-monitor.ts

@@ -36,6 +36,7 @@ import { chmodSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync,
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { createInterface } from 'node:readline';
 import { fileURLToPath } from 'node:url';
+import { formatCubeActivityWakeMessage } from './cube-activity-wake-copy.js';
 
 const ENTRY_LINE_RE =
   /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\S*)\s+(\S+)\s+\(([^)]+)\):\s*(.*)$/;
@@ -87,11 +88,14 @@ export function formatEventLine(inboxLine: string): string | null {
 
 export function formatFreshEventLine(
   inboxLine: string,
-  deduper: RecentLineDeduper
+  deduper: RecentLineDeduper,
+  includeWakeMessage = false,
 ): string | null {
   const pretty = formatEventLine(inboxLine);
   if (pretty === null) return null;
-  return deduper.remember(inboxLine) ? pretty : null;
+  return deduper.remember(inboxLine)
+    ? includeWakeMessage ? formatCubeActivityWakeMessage(pretty) : pretty
+    : null;
 }
 
 export function seedDeduperFromInboxTail(
@@ -914,7 +918,7 @@ function main(): void {
 
     const rl = createInterface({ input: tail.stdout, crlfDelay: Infinity });
     rl.on('line', (line) => {
-      const pretty = formatFreshEventLine(line, deduper);
+      const pretty = formatFreshEventLine(line, deduper, true);
       if (pretty !== null) {
         console.log(pretty);
         // Delivered → the tail is current; re-anchor the offset to the live

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/log-stream.ts

@@ -55,6 +55,7 @@ import {
   startCodexHeartbeat,
   wakeCodexViaAppServer,
 } from './codex-app-wake.js';
+import { formatCubeActivityWakeMessage } from './cube-activity-wake-copy.js';
 import { readBoundedResponseBody } from './server-response.js';
 import { BorgServerError } from './server-errors.js';
 import { markSeatRejected } from './seats.js';
@@ -140,6 +141,14 @@ export function setModuleInjectOpenCode(
  * ring buffer.
  */
 const RECENT_IDS_CAP = 50;
+
+function formatOpenCodeWakePrompt(line: string, wakeNonce?: string): string {
+  const prompt = formatCubeActivityWakeMessage(line);
+  return wakeNonce === undefined
+    ? prompt
+    : `${prompt}\n\n<!-- borg-wake-nonce:${wakeNonce} -->`;
+}
+
 export const INBOX_TAIL_LINES_CAP = 512;
 export const INBOX_TAIL_TRIM_THRESHOLD_LINES = INBOX_TAIL_LINES_CAP * 2;
 
@@ -382,7 +391,7 @@ export interface StreamDeps {
     renderedLine: string
   ) => Promise<boolean>;
   /** Optional Codex app-server wake sink; tests inject a spy. */
-  wakeCodex?: (reason: string) => void;
+  wakeCodex?: (reason: string, deliveryIdentity?: string) => void;
   /** Override the heartbeat watchdog timeout. */
   heartbeatTimeoutMs?: number;
   /** Override HWM divergence grace for focused tests. */
@@ -407,7 +416,8 @@ const defaultDeps: Required<StreamDeps> = {
   getCursor: getLocalServerCursor,
   appendLine: defaultAppendLine,
   hasInboxEntryId: defaultHasInboxEntryId,
-  wakeCodex: wakeCodexViaAppServer,
+  wakeCodex: (reason, deliveryIdentity) =>
+    wakeCodexViaAppServer(reason, process.env, {}, deliveryIdentity),
   heartbeatTimeoutMs: HEARTBEAT_TIMEOUT_MS,
   hwmDivergenceGraceMs: HWM_DIVERGENCE_GRACE_MS,
   abortSignal: new AbortController().signal,
@@ -830,23 +840,27 @@ export async function streamOnce(
     ev: Extract<ParsedEvent, { type: 'log' }>
   ): Promise<'persisted-skip' | 'written'> => {
     const line = formatInboxLine(withSseEventId(ev.data, ev.id));
-    const alreadyPersisted = isCatchingUp && (
+    const deliveryId = ev.wake_nonce ?? ev.id;
+    const isReping = ev.wake_nonce !== undefined;
+    const alreadyPersisted = (ev.wake_nonce !== undefined || isCatchingUp) && (
       // gh#441: pass the rendered line so the dedup can also recognize LEGACY
       // (no-entry_id-prefix) on-disk lines, not just the [entry_id:] marker.
       await hasInboxEntryId(active.cubeId, active.droneId, ev.id, line)
     );
     if (alreadyPersisted) {
-      // Replay still re-enters the OpenCode delivery queue with the same entry
-      // ID. The queue confirms/deduplicates it by the unique persisted entry text.
-      await injectOpenCode(line, ev.id, false);
+      // Replay still re-enters the OpenCode delivery queue. Ordinary entries
+      // correlate by canonical inbox text; re-pings add a stable nonce marker
+      // to the injected text so each distinct nonce submits exactly once.
+      await injectOpenCode(formatOpenCodeWakePrompt(line, ev.wake_nonce), deliveryId, isReping);
       markEventPersisted(ev.id, ev.data?.created_at ?? '');
       return 'persisted-skip';
     }
     // The inbox append is the durable record. OpenCode injection is only the
     // wake attempt and may return before the agent finishes processing.
     await appendLine(active.cubeId, active.droneId, line);
-    if (!(await injectOpenCode(line, ev.id, true))) {
-      wakeCodex(formatCodexWakePrompt(line));
+    if (!(await injectOpenCode(formatOpenCodeWakePrompt(line, ev.wake_nonce), deliveryId, true))) {
+      if (ev.wake_nonce === undefined) wakeCodex(formatCodexWakePrompt(line));
+      else wakeCodex(formatCodexWakePrompt(line), ev.wake_nonce);
     }
     return 'written';
   };
@@ -1007,7 +1021,7 @@ export async function streamOnce(
           const entryId =
             event.id ??
             `control:eviction:${active.cubeId}:${active.droneId}:${event.reason ?? ''}`;
-          await injectOpenCode(line, entryId, true);
+          await injectOpenCode(formatCubeActivityWakeMessage(line), entryId, true);
         } catch {
           // Inbox write failed — the Path-B 410 backstop still tears the drone
           // down on its next authed call. Best-effort wake only.
@@ -1064,6 +1078,10 @@ export async function streamOnce(
         continue;
       }
       if (event.type === 'log') {
+        const isHeartbeatPing =
+          typeof event.data?.message === 'string' &&
+          event.data.message.startsWith('[HEARTBEAT-PING]');
+
         // DEDUP per §(3) recent-ids contract: an out-of-order DO
         // broadcast followed by reconnect+catchup can replay an entry
         // we already persisted. The entry IS on disk from an earlier
@@ -1073,10 +1091,14 @@ export async function streamOnce(
         // Last-Event-ID on the next reconnect reflects the highest
         // id we've actually got persisted). UUIDs are not ordinally
         // comparable with created_at, so set membership is the check.
+        const isRecentWakeReplay = recentIds.has(event.id) && event.wake_nonce !== undefined;
         if (recentIds.has(event.id)) {
+          // Nonce replays continue through every ordinary routing filter below;
+          // only their durable append is skipped. Other duplicates retain the
+          // historical fast path.
           markEventPersisted(event.id, event.data?.created_at ?? '');
           markBroadcastPersisted(broadcastHwmFromLogEvent(event));
-          continue;
+          if (!isRecentWakeReplay) continue;
         }
 
         // OWN-DRONE FILTER: restore the silent-self property — parity
@@ -1103,10 +1125,6 @@ export async function streamOnce(
         // drone through the disk-write path; the existing rate-limit
         // in the server heartbeat contract (max 1 ping per drone per ~1h)
         // bounds the silent-self property's relaxation.
-        const isHeartbeatPing =
-          typeof event.data?.message === 'string' &&
-          event.data.message.startsWith('[HEARTBEAT-PING]');
-
         // Sprint 26 ack-fan-out: ack events have `kind: 'ack'` plus an
         // `author_drone_id` field naming the recipient (the author of
         // the entry that got acked). Only the author writes the ack
@@ -1117,6 +1135,10 @@ export async function streamOnce(
         // here BEFORE the legacy own-drone filter so the ack-specific
         // semantic takes precedence.
         if (event.data?.kind === 'ack') {
+          if (isRecentWakeReplay) {
+            await recordSeen(event);
+            continue;
+          }
           if (event.data?.author_drone_id === active.droneId) {
             if ((await writeInboxLine(event)) === 'persisted-skip') continue;
           }
@@ -1151,6 +1173,15 @@ export async function streamOnce(
           continue;
         }
 
+        if (isRecentWakeReplay) {
+          const line = formatInboxLine(withSseEventId(event.data, event.id));
+          const wakeNonce = event.wake_nonce;
+          if (wakeNonce !== undefined && !(await injectOpenCode(formatOpenCodeWakePrompt(line, wakeNonce), wakeNonce, true))) {
+            wakeCodex(formatCodexWakePrompt(line), wakeNonce);
+          }
+          continue;
+        }
+
         // Regular inbound entry: write the inbox line (catchup-dedup aware),
         // then advance both cursors.
         if ((await writeInboxLine(event)) === 'persisted-skip') continue;
@@ -1206,7 +1237,7 @@ export async function streamOnceIfOwner(
 // ------------------------------------------------------------------
 
 export type ParsedEvent =
-  | { type: 'log'; id: string; data: any; cursor?: LocalServerCursor }
+  | { type: 'log'; id: string; data: any; wake_nonce?: string; cursor?: LocalServerCursor }
   | { type: 'heartbeat'; ts: string | null; hwm: BroadcastHwm | null }
   | { type: 'bookmark'; as_of: string | null }
   // gh#877 Path-A: terminal eviction control frame (wake hint, zero authority).
@@ -1327,10 +1358,12 @@ function parseEventBlock(block: string): ParsedEvent | null {
     const validCursor = cursor &&
       typeof cursor.id === 'string' &&
       typeof cursor.created_at === 'string';
+    const entry = parsed?.entry ?? parsed;
     return {
       type: 'log',
       id,
-      data: parsed?.entry ?? parsed,
+      data: entry,
+      ...(typeof entry?.wake_nonce === 'string' ? { wake_nonce: entry.wake_nonce } : {}),
       ...(validCursor ? { cursor } : {}),
     };
   }

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';
 
@@ -484,11 +485,15 @@ async function deliverOpenCodeEntry(
         log(`entry ${delivery.entryId} target unavailable: ${err}`);
         continue;
       }
-      if (!target) return 'failed';
+      if (!target) {
+        log(`entry ${delivery.entryId} target unavailable: no bound session`);
+        return 'failed';
+      }
     }
 
     try {
       if (await findInjectedMessage(target.id, delivery.text)) {
+        log(`entry ${delivery.entryId} already present in session ${target.id}`);
         return 'delivered';
       }
     } catch (err) {
@@ -630,9 +635,10 @@ export async function injectInitialKickoff(launch: OpenCodeLaunchKickoff): Promi
 
 /**
  * Queue one durable inbox entry for delivery into the bound OpenCode session.
- * The durable inbox text identifies the OpenCode-generated user message, so
- * retries and replay can confirm an earlier ambiguous submission without
- * supplying an ordering-breaking caller message ID or running it twice.
+ * The injected text identifies the OpenCode-generated user message, so retries
+ * and replay can confirm an earlier ambiguous submission without supplying an
+ * ordering-breaking caller message ID or running it twice. Normal delivery uses
+ * canonical inbox text; wake re-pings include their stable nonce marker.
  */
 export function injectOpenCodeEntry(
   text: string,
@@ -640,7 +646,10 @@ export function injectOpenCodeEntry(
   allowSubmit: boolean = true,
 ): Promise<boolean> {
   const owner = state;
-  if (!owner?.connected) return Promise.resolve(false);
+  if (!owner?.connected) {
+    log(`entry ${entryId} rejected: OpenCode is not connected`);
+    return Promise.resolve(false);
+  }
 
   const deliveredText = owner.deliveredEntries.get(entryId);
   if (deliveredText !== undefined) {
@@ -649,6 +658,7 @@ export function injectOpenCodeEntry(
       rememberBounded(owner.failedEntries, entryId, text);
       return Promise.resolve(false);
     }
+    log(`entry ${entryId} replay already delivered`);
     return Promise.resolve(true);
   }
 
@@ -659,6 +669,7 @@ export function injectOpenCodeEntry(
       rememberBounded(owner.failedEntries, entryId, text);
       return Promise.resolve(false);
     }
+    log(`entry ${entryId} replay remains unconfirmed`);
     return Promise.resolve(false);
   }
 
@@ -669,6 +680,7 @@ export function injectOpenCodeEntry(
       rememberBounded(owner.failedEntries, entryId, text);
       return Promise.resolve(false);
     }
+    log(`entry ${entryId} replay joined active delivery`);
     return active.promise;
   }
 
@@ -749,6 +761,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/opencode-wake-copy.ts

@@ -1,3 +1,5 @@
+import { CUBE_ACTIVITY_RESUME_WAKE_MESSAGE } from './cube-activity-wake-copy.js';
+
 export const OPENCODE_WAKE_PATH_GUIDANCE =
   'OpenCode wakes through HTTP entry injection into its session through the local HTTP API. ' +
   'Borg writes each entry to the durable inbox before one injection attempt and ' +
@@ -5,4 +7,5 @@ export const OPENCODE_WAKE_PATH_GUIDANCE =
   'If injection is rejected or cannot be ' +
   'confirmed, the durable entry remains available and `borg_stream-status` reports ' +
   'it as failed or delivered-unconfirmed; run `borg_read-log unread_only=true` and ' +
-  'drain the unread log to recover.';
+  'drain the unread log to recover. ' +
+  CUBE_ACTIVITY_RESUME_WAKE_MESSAGE;