borgmcp 2.5.0 → 2.6.1

package/src/index.ts

@@ -90,10 +90,10 @@ import { filterToolsForRole } from './tool-scope.js';
 import { getPackageVersion, getOnDiskVersion, handleVersionFlag } from './version.js';
 import {
   renderStreamStatus,
-  checkInboxMonitorHealthy,
   formatWakePathPrefix,
   shouldShowWakePathWarning,
 } from './stream-status.js';
+import { inspectWakePath } from './wake-path-health.js';
 import {
   RUNTIME_METADATA_ADVISORY,
   renderRoster,
@@ -128,7 +128,6 @@ import {
   connectOpenCodeDrone,
   injectOpenCodeEntry,
   computeOpenCodePort,
-  getOpenCodeConnectionState,
 } from './opencode-drone.js';
 import { installBorgPlugin } from './opencode-plugin.js';
 import { setModuleInjectOpenCode } from './log-stream.js';
@@ -401,31 +400,28 @@ export async function main() {
             await refreshActiveCubeMetadata(freshActive);
           }
 
-          // Wake-path self-heal (gh#43): SSE delivery to the inbox file
-          // is independent from Claude Code waking on file writes. The
-          // latter requires a `tail -F` Monitor against the inbox path;
-          // if that Monitor dies (or was never armed across a session
-          // boundary), the drone misses every incoming entry until the
-          // /loop fallback heartbeat. Because regen runs on every /loop
-          // iteration, surfacing the breakage here gives self-healing at
-          // worst-case latency = the heartbeat interval. Mirrors the
-          // State-5 self-arm instruction in stream-status.ts.
+          // Wake-path self-heal (gh#43): SSE delivery to the durable inbox
+          // is distinct from the runtime-specific mechanism that wakes the
+          // agent. Inspect that real mechanism for Claude, Codex, or OpenCode
+          // and surface a runtime-specific recovery prefix when it is broken.
           const streamStatus = getStreamStatus();
           const inboxPath = inboxPathForDrone(freshActive.cubeId, freshActive.droneId);
           const monitorStateRoot = monitorStateRootForWorktree(findProjectRoot());
-          // Non-Claude CLIs do not use the Claude inbox Monitor. Keep the
-          // agent CLI distinction independent from whether Codex's optional
-          // remote-wake transport is currently armed.
           const agentKind = resolveSessionAgentKind();
-          const inboxMonitorHealthy = agentKind === 'claude'
-            ? checkInboxMonitorHealthy(inboxPath, monitorStateRoot)
-            : true;
+          const wakePath = await inspectWakePath({
+            agentKind,
+            active: freshActive,
+            inboxPath,
+            monitorStateRoot,
+          });
+          const inboxMonitorHealthy = wakePath.healthy;
           const prefix = shouldShowWakePathWarning(streamStatus, inboxMonitorHealthy)
             ? formatWakePathPrefix({
                 inboxPath,
                 monitorStateRoot,
                 droneLabel: regenWakePathDroneLabel(displayedResult, displayIdentity.droneLabel),
                 cubeName: displayIdentity.cubeName,
+                wakePath,
               })
             : '';
 
@@ -686,9 +682,9 @@ export async function main() {
           // Probe the in-process SSE consumer state. Does NOT require
           // an active cube — if the consumer hasn't started or is
           // between cubes, the snapshot still reports current values.
-          // Also probes wake-path completeness (T1.2): is anyone tailing
-          // the inbox file? Without that, SSE delivery still works but
-          // the harness `/loop` never wakes on the file write.
+          // Also probes runtime-specific wake-path completeness: Claude's
+          // inbox Monitor, Codex's remote-control bridge, or OpenCode's
+          // durable injection delivery state.
           const status = getStreamStatus();
           const active = await getActiveCube();
           const inboxPath = active
@@ -697,14 +693,13 @@ export async function main() {
           const monitorStateRoot = active
             ? monitorStateRootForWorktree(findProjectRoot())
             : null;
-          // Non-Claude CLIs have their own wake mechanism, so this Claude-only
-          // Monitor diagnostic must not be inferred from Codex transport state.
-          const nonClaudeSession = active && resolveSessionAgentKind() !== 'claude';
-          const inboxMonitorHealthy = active
-            ? nonClaudeSession
-              ? true
-              : checkInboxMonitorHealthy(inboxPath, monitorStateRoot)
-            : null;
+          const wakePath = await inspectWakePath({
+            agentKind: resolveSessionAgentKind(),
+            active,
+            inboxPath,
+            monitorStateRoot,
+          });
+          const inboxMonitorHealthy = wakePath.healthy;
           let silentInertWarning = '';
           if (status.runLoopHealth === 'silent-inert') {
             silentInertWarning = '## ⚠ SSE stream loop silent-inert — run /mcp and reconnect to restart\n\n' +
@@ -713,6 +708,7 @@ export async function main() {
           const text = renderStreamStatus({
             status,
             inboxMonitorHealthy,
+            wakePath,
             inboxPath,
             monitorStateRoot,
             droneLabel: active?.droneLabel ?? null,

package/src/log-stream.ts

@@ -120,9 +120,13 @@ function isProcessAlive(pid: number): boolean {
  * startup (from index.ts) once the opencode drone module is initialized.
  * Used by defaultDeps when no explicit injectOpenCode is supplied.
  */
-let _moduleInjectOpenCode: ((text: string) => Promise<boolean>) | undefined;
+let _moduleInjectOpenCode:
+  | ((text: string, entryId: string, allowSubmit: boolean) => Promise<boolean>)
+  | undefined;
 
-export function setModuleInjectOpenCode(fn: (text: string) => Promise<boolean>): void {
+export function setModuleInjectOpenCode(
+  fn: (text: string, entryId: string, allowSubmit: boolean) => Promise<boolean>
+): void {
   _moduleInjectOpenCode = fn;
 }
 
@@ -387,13 +391,12 @@ export interface StreamDeps {
   ownerDeps?: import('./stream-owner.js').StreamOwnerDeps;
   /** Override owner stale threshold in focused duplicate-process tests. */
   ownerStaleMs?: number;
-  /**
-   * Optional opencode entry injector for autonomous drone processing.
-   * When provided AND the injection succeeds, the inbox file write is skipped
-   * (the drone processes the entry autonomously). On failure, falls through
-   * to the inbox write for backup.
-   */
-  injectOpenCode?: (text: string) => Promise<boolean>;
+  /** Optional OpenCode wake delivery after the durable inbox append. */
+  injectOpenCode?: (
+    text: string,
+    entryId: string,
+    allowSubmit: boolean
+  ) => Promise<boolean>;
 }
 
 const defaultDeps: Required<StreamDeps> = {
@@ -408,7 +411,10 @@ const defaultDeps: Required<StreamDeps> = {
   abortSignal: new AbortController().signal,
   ownerDeps: {},
   ownerStaleMs: 70_000,
-  injectOpenCode: (text) => _moduleInjectOpenCode ? _moduleInjectOpenCode(text) : Promise.resolve(false),
+  injectOpenCode: (text, entryId, allowSubmit) =>
+    _moduleInjectOpenCode
+      ? _moduleInjectOpenCode(text, entryId, allowSubmit)
+      : Promise.resolve(false),
 };
 
 // ------------------------------------------------------------------
@@ -814,24 +820,24 @@ export async function streamOnce(
     ev: Extract<ParsedEvent, { type: 'log' }>
   ): Promise<'persisted-skip' | 'written'> => {
     const line = formatInboxLine(withSseEventId(ev.data, ev.id));
-    if (
-      isCatchingUp &&
+    const alreadyPersisted = 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))
-    ) {
+      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);
       markEventPersisted(ev.id, ev.data?.created_at ?? '');
       return 'persisted-skip';
     }
-    // gh#opencode: try autonomous opencode injection first. When the drone's
-    // child session processes entries directly, skip the inbox write (the
-    // Monitor/tail-F path is unused for opencode). Falls through to inbox on
-    // failure so the entry is never lost.
-    if (await injectOpenCode(line)) {
-      return 'written';
-    }
+    // 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);
-    wakeCodex(formatCodexWakePrompt(line));
+    if (!(await injectOpenCode(line, ev.id, true))) {
+      wakeCodex(formatCodexWakePrompt(line));
+    }
     return 'written';
   };
 
@@ -978,11 +984,16 @@ export async function streamOnce(
       if (event.type === 'eviction') {
         streamState.lastContentEventAt = nowIso;
         try {
+          const line = formatEvictionSentinelLine(event.reason);
           await appendLine(
             active.cubeId,
             active.droneId,
-            formatEvictionSentinelLine(event.reason)
+            line
           );
+          const entryId =
+            event.id ??
+            `control:eviction:${active.cubeId}:${active.droneId}:${event.reason ?? ''}`;
+          await injectOpenCode(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.
@@ -1178,7 +1189,7 @@ export type ParsedEvent =
   | { 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).
-  | { type: 'eviction'; cube_id: string | null; reason: string | null }
+  | { type: 'eviction'; id: string | null; cube_id: string | null; reason: string | null }
   | { type: 'unknown'; raw: string };
 
 /**
@@ -1336,7 +1347,7 @@ function parseEventBlock(block: string): ParsedEvent | null {
     } catch {
       // fall through with nulls
     }
-    return { type: 'eviction', cube_id, reason };
+    return { type: 'eviction', id: id || null, cube_id, reason };
   }
   return { type: 'unknown', raw: block };
 }

package/src/opencode-drone.ts

@@ -19,6 +19,13 @@ interface OpenCodeDroneState {
   cubeName: string;
   connected: boolean;
   totalEntriesInjected: number;
+  totalEntriesRetried: number;
+  deliveryQueue: OpenCodeDelivery[];
+  activeDeliveries: Map<string, OpenCodeDelivery>;
+  deliveredEntries: Map<string, string>;
+  unconfirmedEntries: Map<string, string>;
+  failedEntries: Map<string, string>;
+  processingDeliveries: boolean;
 }
 
 let state: OpenCodeDroneState | null = null;
@@ -41,6 +48,7 @@ interface OCSession {
 
 interface OCMessage {
   info?: {
+    id?: string;
     role?: string;
     time?: { created?: number };
   };
@@ -50,6 +58,26 @@ interface OCMessage {
   }>;
 }
 
+export type OpenCodeDeliveryState =
+  | 'queued'
+  | 'delivered-unconfirmed'
+  | 'retried'
+  | 'failed';
+
+interface OpenCodeDelivery {
+  entryId: string;
+  text: string;
+  allowSubmit: boolean;
+  state: Exclude<OpenCodeDeliveryState, 'failed'>;
+  resolve: (delivered: boolean) => void;
+  promise: Promise<boolean>;
+}
+
+type OpenCodeDeliveryOutcome = 'delivered' | 'delivered-unconfirmed' | 'failed';
+
+const OPEN_CODE_DELIVERY_RETRY_DELAYS_MS = [0, 250, 1_000, 3_000] as const;
+const OPEN_CODE_DELIVERY_HISTORY_LIMIT = 256;
+
 interface SessionBinding {
   version: 2;
   sessionId: string;
@@ -89,7 +117,18 @@ export function createOpenCodeLaunchKickoff(
 
 const bindingPathsForTests = new Set<string>();
 
+function abandonOpenCodeDeliveries(current: OpenCodeDroneState | null): void {
+  if (!current) return;
+  current.connected = false;
+  for (const delivery of current.activeDeliveries.values()) {
+    delivery.resolve(false);
+  }
+  current.activeDeliveries.clear();
+  current.deliveryQueue.length = 0;
+}
+
 export async function connectOpenCodeDrone(deps: ConnectDeps): Promise<void> {
+  abandonOpenCodeDeliveries(state);
   state = {
     serverUrl: deps.serverUrl,
     sessionId: null,
@@ -100,6 +139,13 @@ export async function connectOpenCodeDrone(deps: ConnectDeps): Promise<void> {
     cubeName: deps.cubeName,
     connected: true,
     totalEntriesInjected: 0,
+    totalEntriesRetried: 0,
+    deliveryQueue: [],
+    activeDeliveries: new Map(),
+    deliveredEntries: new Map(),
+    unconfirmedEntries: new Map(),
+    failedEntries: new Map(),
+    processingDeliveries: false,
   };
   log(`connected url=${deps.serverUrl} dir=${deps.directory}`);
 }
@@ -153,13 +199,10 @@ async function listSessions(): Promise<OCSession[]> {
 }
 
 async function getSession(id: string): Promise<OCSession | null> {
-  try {
-    const { status, body } = await rawGet(`/session/${id}`);
-    if (status !== 200) return null;
-    return JSON.parse(body);
-  } catch {
-    return null;
-  }
+  const { status, body } = await rawGet(`/session/${id}`);
+  if (status === 404) return null;
+  if (status !== 200) throw new Error(`OpenCode session request failed (${status})`);
+  return JSON.parse(body);
 }
 
 async function listSessionMessages(id: string): Promise<OCMessage[]> {
@@ -168,9 +211,21 @@ async function listSessionMessages(id: string): Promise<OCMessage[]> {
   return JSON.parse(body);
 }
 
-async function promptSession(id: string, bodyObj: Record<string, unknown>): Promise<boolean> {
+async function findInjectedMessage(sessionId: string, text: string): Promise<string | null> {
+  const messages = await listSessionMessages(sessionId);
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const message = messages[index];
+    if (message?.info?.role !== 'user' || typeof message.info.id !== 'string') continue;
+    if (message.parts?.some((part) => part.type === 'text' && part.text === text)) {
+      return message.info.id;
+    }
+  }
+  return null;
+}
+
+async function promptSession(id: string, bodyObj: Record<string, unknown>): Promise<number> {
   const { status } = await rawPost(`/session/${id}/prompt_async`, bodyObj);
-  return status === 200 || status === 204;
+  return status;
 }
 
 // ---------------------------------------------------------------------------
@@ -381,11 +436,151 @@ async function resolveInjectionSession(): Promise<OCSession | null> {
   return bound;
 }
 
-async function rebindAfterFailure(knownRootSessionIds: string[]): Promise<OCSession | null> {
-  const replacement = await findUnseenTopLevelSession(knownRootSessionIds);
-  if (!replacement) return null;
-  saveBinding(replacement.session, replacement.knownRootSessionIds);
-  return replacement.session;
+function rememberBounded(
+  entries: Map<string, string>,
+  entryId: string,
+  text: string,
+): void {
+  entries.delete(entryId);
+  entries.set(entryId, text);
+  while (entries.size > OPEN_CODE_DELIVERY_HISTORY_LIMIT) {
+    const oldest = entries.keys().next().value;
+    if (typeof oldest !== 'string') break;
+    entries.delete(oldest);
+  }
+}
+
+function waitForDeliveryRetry(attempt: number): Promise<void> {
+  const delay = OPEN_CODE_DELIVERY_RETRY_DELAYS_MS[attempt] ?? 0;
+  return delay > 0
+    ? new Promise((resolve) => setTimeout(resolve, delay))
+    : Promise.resolve();
+}
+
+async function deliverOpenCodeEntry(
+  owner: OpenCodeDroneState,
+  delivery: OpenCodeDelivery,
+): Promise<OpenCodeDeliveryOutcome> {
+  let target: OCSession | null = null;
+
+  // 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
+  // ever becoming the active user turn. The unique inbox text correlates the
+  // generated message across confirmation and process-replay instead.
+  for (let attempt = 0; attempt < OPEN_CODE_DELIVERY_RETRY_DELAYS_MS.length; attempt++) {
+    if (state !== owner || !owner.connected) return 'failed';
+    if (attempt > 0) {
+      delivery.state = 'retried';
+      owner.totalEntriesRetried++;
+      await waitForDeliveryRetry(attempt);
+      if (state !== owner || !owner.connected) return 'failed';
+    }
+
+    if (!target) {
+      try {
+        target = await resolveInjectionSession();
+      } catch (err) {
+        log(`entry ${delivery.entryId} target unavailable: ${err}`);
+        continue;
+      }
+      if (!target) return 'failed';
+    }
+
+    try {
+      if (await findInjectedMessage(target.id, delivery.text)) {
+        return 'delivered';
+      }
+    } catch (err) {
+      log(`entry ${delivery.entryId} confirmation unavailable: ${err}`);
+      continue;
+    }
+
+    if (!delivery.allowSubmit) {
+      continue;
+    }
+
+    // prompt_async is not idempotent. Submit at most once, then only poll for
+    // the exact text. A transport failure is ambiguous and follows the same
+    // confirmation-only path.
+    let status: number | null = null;
+    try {
+      status = await promptSession(target.id, {
+        parts: [{ type: 'text', text: delivery.text }],
+      });
+    } catch (err) {
+      log(`entry ${delivery.entryId} submission outcome unavailable: ${err}`);
+    }
+
+    delivery.state = 'delivered-unconfirmed';
+    if (status !== null && status !== 200 && status !== 204) {
+      if (status === 404) clearBinding();
+      return 'failed';
+    }
+
+    for (
+      let confirmationAttempt = 0;
+      confirmationAttempt < OPEN_CODE_DELIVERY_RETRY_DELAYS_MS.length;
+      confirmationAttempt++
+    ) {
+      if (confirmationAttempt > 0) {
+        delivery.state = 'retried';
+        owner.totalEntriesRetried++;
+        await waitForDeliveryRetry(confirmationAttempt);
+        if (state !== owner || !owner.connected) return 'delivered-unconfirmed';
+        delivery.state = 'delivered-unconfirmed';
+      }
+      try {
+        if (await findInjectedMessage(target.id, delivery.text)) {
+          return 'delivered';
+        }
+      } catch (err) {
+        log(`entry ${delivery.entryId} post-acceptance confirmation unavailable: ${err}`);
+      }
+    }
+
+    return 'delivered-unconfirmed';
+  }
+
+  // A replay begins from a durable inbox record but cannot know whether the
+  // prior process stopped before or after submission. Missing confirmation
+  // therefore remains unknown, not a definite delivery failure.
+  return delivery.allowSubmit ? 'failed' : 'delivered-unconfirmed';
+}
+
+async function processOpenCodeDeliveries(owner: OpenCodeDroneState): Promise<void> {
+  if (owner.processingDeliveries) return;
+  owner.processingDeliveries = true;
+  try {
+    while (state === owner && owner.deliveryQueue.length > 0) {
+      const delivery = owner.deliveryQueue.shift()!;
+      let outcome: OpenCodeDeliveryOutcome = 'failed';
+      try {
+        outcome = await deliverOpenCodeEntry(owner, delivery);
+      } catch (err) {
+        log(`entry ${delivery.entryId} delivery error: ${err}`);
+      }
+
+      owner.activeDeliveries.delete(delivery.entryId);
+      if (outcome === 'delivered') {
+        owner.unconfirmedEntries.delete(delivery.entryId);
+        owner.failedEntries.delete(delivery.entryId);
+        rememberBounded(owner.deliveredEntries, delivery.entryId, delivery.text);
+        owner.totalEntriesInjected++;
+        delivery.resolve(true);
+      } else if (outcome === 'delivered-unconfirmed') {
+        owner.failedEntries.delete(delivery.entryId);
+        rememberBounded(owner.unconfirmedEntries, delivery.entryId, delivery.text);
+        delivery.resolve(false);
+      } else {
+        owner.unconfirmedEntries.delete(delivery.entryId);
+        rememberBounded(owner.failedEntries, delivery.entryId, delivery.text);
+        delivery.resolve(false);
+      }
+    }
+  } finally {
+    owner.processingDeliveries = false;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -434,42 +629,67 @@ export async function injectInitialKickoff(launch: OpenCodeLaunchKickoff): Promi
 }
 
 /**
- * Inject a silent context entry (noReply) into our session.
- * Falls through silently — caller falls back to inbox write.
+ * 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.
  */
-export async function injectOpenCodeEntry(text: string): Promise<boolean> {
-  if (!state?.connected) return false;
-
-  try {
-    const target = await resolveInjectionSession();
-    if (!target) return false;
+export function injectOpenCodeEntry(
+  text: string,
+  entryId: string = createHash('sha256').update(text).digest('hex'),
+  allowSubmit: boolean = true,
+): Promise<boolean> {
+  const owner = state;
+  if (!owner?.connected) return Promise.resolve(false);
+
+  const deliveredText = owner.deliveredEntries.get(entryId);
+  if (deliveredText !== undefined) {
+    if (deliveredText !== text) {
+      log(`entry ${entryId} replay text mismatch`);
+      rememberBounded(owner.failedEntries, entryId, text);
+      return Promise.resolve(false);
+    }
+    return Promise.resolve(true);
+  }
 
-    const body = {
-      parts: [{ type: 'text', text }],
-    };
-    if (await promptSession(target.id, body)) {
-      state.totalEntriesInjected++;
-      return true;
+  const unconfirmedText = owner.unconfirmedEntries.get(entryId);
+  if (unconfirmedText !== undefined) {
+    if (unconfirmedText !== text) {
+      log(`entry ${entryId} unconfirmed replay text mismatch`);
+      rememberBounded(owner.failedEntries, entryId, text);
+      return Promise.resolve(false);
     }
+    return Promise.resolve(false);
+  }
 
-    // A failed prompt means the cached target is no longer trustworthy. Clear
-    // it before considering only a newer root created by `/new`; never fall
-    // through to a child or arbitrary newest session.
-    const knownRootSessionIds = [...state.knownRootSessionIds];
-    clearBinding();
-    const replacement = await rebindAfterFailure(knownRootSessionIds);
-    if (!replacement) return false;
-    if (await promptSession(replacement.id, body)) {
-      state.totalEntriesInjected++;
-      return true;
+  const active = owner.activeDeliveries.get(entryId);
+  if (active) {
+    if (active.text !== text) {
+      log(`entry ${entryId} active text mismatch`);
+      rememberBounded(owner.failedEntries, entryId, text);
+      return Promise.resolve(false);
     }
-    clearBinding();
-    return false;
-  } catch (err) {
-    log(`entry error: ${err}`);
-    clearBinding();
-    return false;
+    return active.promise;
   }
+
+  let resolveDelivery!: (delivered: boolean) => void;
+  const promise = new Promise<boolean>((resolve) => {
+    resolveDelivery = resolve;
+  });
+  const delivery: OpenCodeDelivery = {
+    entryId,
+    text,
+    allowSubmit,
+    state: 'queued',
+    resolve: resolveDelivery,
+    promise,
+  };
+  owner.unconfirmedEntries.delete(entryId);
+  owner.failedEntries.delete(entryId);
+  owner.activeDeliveries.set(entryId, delivery);
+  owner.deliveryQueue.push(delivery);
+  void processOpenCodeDeliveries(owner);
+  return promise;
 }
 
 export async function probeOpenCodeDroneArmed(): Promise<boolean | null> {
@@ -483,24 +703,39 @@ export async function probeOpenCodeDroneArmed(): Promise<boolean | null> {
     clearBinding();
     return false;
   } catch {
-    clearBinding();
     return false;
   }
 }
 
 export function disconnectOpenCodeDrone(): void {
+  abandonOpenCodeDeliveries(state);
   state = null;
 }
 
-export function getOpenCodeConnectionState(): {
+export interface OpenCodeConnectionState {
   connected: boolean;
   sessionId: string | null;
   totalEntriesInjected: number;
-} {
+  totalEntriesRetried: number;
+  deliveryStates: Record<OpenCodeDeliveryState, number>;
+}
+
+export function getOpenCodeConnectionState(): OpenCodeConnectionState {
+  const deliveryStates: Record<OpenCodeDeliveryState, number> = {
+    queued: 0,
+    'delivered-unconfirmed': state?.unconfirmedEntries.size ?? 0,
+    retried: 0,
+    failed: state?.failedEntries.size ?? 0,
+  };
+  for (const delivery of state?.activeDeliveries.values() ?? []) {
+    deliveryStates[delivery.state]++;
+  }
   return {
     connected: state?.connected ?? false,
     sessionId: state?.sessionId ?? null,
     totalEntriesInjected: state?.totalEntriesInjected ?? 0,
+    totalEntriesRetried: state?.totalEntriesRetried ?? 0,
+    deliveryStates,
   };
 }
 
@@ -516,6 +751,7 @@ export function computeOpenCodePort(droneId: string, base: number = 14096): numb
 
 /** Test-only cleanup for module state and the local cross-process binding. */
 export function __resetOpenCodeDroneForTests(): void {
+  abandonOpenCodeDeliveries(state);
   state = null;
   for (const path of bindingPathsForTests) {
     try {

package/src/opencode-wake-copy.ts

@@ -0,0 +1,8 @@
+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 ' +
+  'confirms delivery by the unique persisted entry text; no inbox Monitor or secondary wake loop is used. ' +
+  '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.';