borgmcp 4.3.0 → 4.5.0

package/src/opencode-drone.ts

@@ -1,8 +1,26 @@
-import { appendFileSync, existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
-import { createHash } from 'crypto';
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fchmodSync,
+  fstatSync,
+  openSync,
+  readFileSync,
+  readSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+  writeSync,
+} from 'fs';
+import { createHash, randomUUID } from 'crypto';
 import { createServer } from 'node:net';
 import { join } from 'path';
 import { tmpdir } from 'os';
+import {
+  borgConfigRoot,
+  ensurePrivateBorgConfigRoot,
+  ensurePrivateBorgConfigRootSync,
+} from './private-root.js';
 import {
   OPENCODE_INJECTED_ENTRY_METADATA_KEY,
   OPENCODE_WAKE_IDENTITY_METADATA_KEY,
@@ -14,11 +32,129 @@ import {
   OPENCODE_SERVER_USERNAME,
   type OpenCodeLaunchTrust,
 } from './opencode-launch-trust.js';
+import {
+  OpenCodeAuthenticationError,
+  OpenCodeHttpError,
+  OpenCodeResponseError,
+  OpenCodeUnreachableError,
+  type OpenCodeFailureCode,
+} from './server-errors.js';
+
+const OPEN_CODE_DIAGNOSTIC_LOG_MAX_BYTES = 64 * 1024;
+const diagnosticLogPathsForTests = new Set<string>();
+
+function stateIdentityDigest(current: OpenCodeDroneState): string {
+  const key = [current.serverUrl, current.directory, current.cubeName, current.droneLabel].join('\0');
+  return createHash('sha256').update(key).digest('hex').slice(0, 24);
+}
 
-const LOG_FILE = join(tmpdir(), 'borg-opencode-drone.log');
-function log(msg: string) {
+export function openCodeStartupDiagnosticLogPath(): string {
+  return join(borgConfigRoot(), 'opencode-drone-startup.log');
+}
+
+function diagnosticLogPath(owner: OpenCodeDroneState | null): string {
+  const root = borgConfigRoot();
+  const path = owner
+    ? join(root, `opencode-drone-${stateIdentityDigest(owner)}.log`)
+    : openCodeStartupDiagnosticLogPath();
+  diagnosticLogPathsForTests.add(path);
+  return path;
+}
+
+function log(msg: string, owner: OpenCodeDroneState | null = state, throwOnFailure = false) {
   const line = `[${new Date().toISOString()}] ${msg}\n`;
-  try { appendFileSync(LOG_FILE, line); } catch {}
+  let descriptor: number | null = null;
+  let temporaryDescriptor: number | null = null;
+  let temporary: string | null = null;
+  try {
+    ensurePrivateBorgConfigRootSync(borgConfigRoot());
+    const path = diagnosticLogPath(owner);
+    // The private root is the primary boundary. Where available, no-follow also
+    // closes the final replacement gap between root verification and this open.
+    const noFollow = constants.O_NOFOLLOW ?? 0;
+    descriptor = openSync(
+      path,
+      constants.O_RDWR |
+        constants.O_APPEND |
+        constants.O_CREAT |
+        noFollow,
+      0o600,
+    );
+    if (!fstatSync(descriptor).isFile()) {
+      throw Object.assign(new Error('OpenCode diagnostic log is not a regular file'), { code: 'EINVAL' });
+    }
+    fchmodSync(descriptor, 0o600);
+    writeSync(descriptor, line, null, 'utf8');
+
+    const size = fstatSync(descriptor).size;
+    if (size <= OPEN_CODE_DIAGNOSTIC_LOG_MAX_BYTES) return;
+    const tail = Buffer.allocUnsafe(OPEN_CODE_DIAGNOSTIC_LOG_MAX_BYTES);
+    let bytesRead = 0;
+    while (bytesRead < tail.length) {
+      const count = readSync(
+        descriptor,
+        tail,
+        bytesRead,
+        tail.length - bytesRead,
+        size - tail.length + bytesRead,
+      );
+      if (count === 0) break;
+      bytesRead += count;
+    }
+    const completeTail = tail.subarray(0, bytesRead);
+    const firstNewline = completeTail.indexOf(0x0a);
+    const bounded = firstNewline >= 0 ? completeTail.subarray(firstNewline + 1) : completeTail;
+
+    temporary = `${path}.${randomUUID()}.tmp`;
+    temporaryDescriptor = openSync(
+      temporary,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollow,
+      0o600,
+    );
+    if (!fstatSync(temporaryDescriptor).isFile()) {
+      throw Object.assign(new Error('OpenCode diagnostic temporary is not a regular file'), { code: 'EINVAL' });
+    }
+    fchmodSync(temporaryDescriptor, 0o600);
+    let bytesWritten = 0;
+    while (bytesWritten < bounded.length) {
+      const count = writeSync(
+        temporaryDescriptor,
+        bounded,
+        bytesWritten,
+        bounded.length - bytesWritten,
+      );
+      if (count === 0) throw Object.assign(new Error('OpenCode diagnostic temporary write stalled'), { code: 'EIO' });
+      bytesWritten += count;
+    }
+    closeSync(temporaryDescriptor);
+    temporaryDescriptor = null;
+    closeSync(descriptor);
+    descriptor = null;
+    renameSync(temporary, path);
+    temporary = null;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException | null)?.code ?? 'unknown';
+    process.stderr.write(`OpenCode diagnostic log write failed (${code})\n`);
+    if (throwOnFailure) throw error;
+  } finally {
+    if (temporaryDescriptor !== null) {
+      try { closeSync(temporaryDescriptor); } catch { /* The primary write error is already reported. */ }
+    }
+    if (descriptor !== null) {
+      try { closeSync(descriptor); } catch { /* The primary write error is already reported. */ }
+    }
+    if (temporary !== null) {
+      try {
+        unlinkSync(temporary);
+      } catch {
+        // Already absent or inaccessible; the randomized name cannot be reused.
+      }
+    }
+  }
+}
+
+export function writeOpenCodeStartupDiagnostic(message: string): void {
+  log(message, null, true);
 }
 
 interface OpenCodeDroneState {
@@ -41,8 +177,25 @@ interface OpenCodeDroneState {
   pendingSubmissions: Map<string, PendingOpenCodeSubmission>;
   reconcilingEntryIds: Set<string>;
   processingDeliveries: boolean;
+  nextObservationSequence: number;
+  lastObservation: OpenCodeLastObservation;
 }
 
+interface OpenCodeLastObservation {
+  injectionSequence: number;
+  acceptedSequence: number;
+  failureSequence: number;
+  lastInjectionAt: number | null;
+  lastInjectionResult: OpenCodeInjectionResult | null;
+  lastAcceptedEntryId: string | null;
+  lastFailureCode: string | null;
+}
+
+type OpenCodeLastFields = Pick<
+  OpenCodeLastObservation,
+  'lastInjectionAt' | 'lastInjectionResult' | 'lastAcceptedEntryId' | 'lastFailureCode'
+>;
+
 let state: OpenCodeDroneState | null = null;
 
 interface ConnectDeps {
@@ -63,12 +216,12 @@ interface OCSession {
 }
 
 interface OCMessage {
-  info?: {
+  info: {
     id?: string;
-    role?: string;
+    role: string;
     time?: { created?: number };
   };
-  parts?: Array<{
+  parts: Array<{
     type?: string;
     text?: string;
     metadata?: Record<string, unknown>;
@@ -82,6 +235,7 @@ export type OpenCodeDeliveryState =
   | 'failed';
 
 interface OpenCodeDelivery {
+  sequence: number;
   entryId: string;
   sourceEntryId: string;
   text: string;
@@ -107,6 +261,7 @@ interface PendingOpenCodeSubmission {
 }
 
 type OpenCodeDeliveryOutcome = 'delivered' | 'delivered-unconfirmed' | 'failed';
+type OpenCodeInjectionResult = OpenCodeDeliveryOutcome;
 
 const OPEN_CODE_DELIVERY_RETRY_DELAYS_MS = [0, 250, 1_000, 3_000] as const;
 const OPEN_CODE_RECONCILIATION_DELAY_MS = 3_000;
@@ -168,8 +323,9 @@ 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');
+    throw new OpenCodeAuthenticationError('OpenCode API password is missing or unverifiable');
   }
+  await ensurePrivateBorgConfigRoot(borgConfigRoot());
   abandonOpenCodeDeliveries(state);
   state = {
     serverUrl: deps.serverUrl,
@@ -191,8 +347,18 @@ export async function connectOpenCodeDrone(deps: ConnectDeps): Promise<void> {
     pendingSubmissions: new Map(),
     reconcilingEntryIds: new Set(),
     processingDeliveries: false,
+    nextObservationSequence: 0,
+    lastObservation: {
+      injectionSequence: 0,
+      acceptedSequence: 0,
+      failureSequence: 0,
+      lastInjectionAt: null,
+      lastInjectionResult: null,
+      lastAcceptedEntryId: null,
+      lastFailureCode: null,
+    },
   };
-  log(`connected url=${deps.serverUrl} dir=${deps.directory}`);
+  log(`connected url=${deps.serverUrl} dir=${deps.directory}`, state);
 }
 
 // ---------------------------------------------------------------------------
@@ -207,7 +373,7 @@ function apiUrl(path: string): string {
 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');
+    throw new OpenCodeAuthenticationError('OpenCode API password is missing or unverifiable');
   }
   return {
     ...headers,
@@ -225,6 +391,13 @@ async function rawGet(path: string): Promise<{ status: number; body: string }> {
     const res = await fetch(url, { headers: authenticatedHeaders(), signal: controller.signal });
     const body = await res.text();
     return { status: res.status, body };
+  } catch (error) {
+    if (error instanceof OpenCodeAuthenticationError) throw error;
+    throw new OpenCodeUnreachableError(
+      controller.signal.aborted ? 'timeout' : 'transient',
+      controller.signal.aborted ? 'OpenCode request timed out' : 'OpenCode request failed',
+      { cause: error },
+    );
   } finally {
     clearTimeout(timer);
   }
@@ -243,28 +416,111 @@ async function rawPost(path: string, bodyObj: unknown): Promise<{ status: number
     });
     const body = await res.text();
     return { status: res.status, body };
+  } catch (error) {
+    if (error instanceof OpenCodeAuthenticationError) throw error;
+    throw new OpenCodeUnreachableError(
+      controller.signal.aborted ? 'timeout' : 'transient',
+      controller.signal.aborted ? 'OpenCode request timed out' : 'OpenCode request failed',
+      { cause: error },
+    );
   } finally {
     clearTimeout(timer);
   }
 }
 
+function openCodeHttpError(status: number, operation: string): OpenCodeHttpError {
+  const code: OpenCodeFailureCode = status === 401
+    ? 'unauthorized'
+    : status === 404
+      ? 'not-found'
+      : status >= 500 || status === 429
+        ? 'transient'
+        : 'incompatible-api';
+  return new OpenCodeHttpError(status, code, `OpenCode ${operation} request failed (${status})`);
+}
+
+function parseOpenCodeJson(body: string): unknown {
+  try {
+    return JSON.parse(body);
+  } catch (error) {
+    throw new OpenCodeResponseError('OpenCode returned malformed JSON', { cause: error });
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function decodeSession(value: unknown): OCSession {
+  if (
+    !isRecord(value)
+    || typeof value.id !== 'string'
+    || value.id.length === 0
+    || typeof value.directory !== 'string'
+    || !isRecord(value.time)
+    || typeof value.time.created !== 'number'
+    || !Number.isFinite(value.time.created)
+    || (value.parentID !== undefined && typeof value.parentID !== 'string')
+    || (value.agent !== undefined && typeof value.agent !== 'string')
+    || (value.model !== undefined && (
+      !isRecord(value.model)
+      || typeof value.model.providerID !== 'string'
+      || typeof value.model.modelID !== 'string'
+    ))
+  ) {
+    throw new OpenCodeResponseError();
+  }
+  return value as unknown as OCSession;
+}
+
+function decodeSessions(body: string): OCSession[] {
+  const value = parseOpenCodeJson(body);
+  if (!Array.isArray(value)) throw new OpenCodeResponseError();
+  return value.map(decodeSession);
+}
+
+function decodeMessages(body: string): OCMessage[] {
+  const value = parseOpenCodeJson(body);
+  if (!Array.isArray(value)) throw new OpenCodeResponseError();
+  return value.map((message) => {
+    if (!isRecord(message)) throw new OpenCodeResponseError();
+    if (
+      !isRecord(message.info)
+      || typeof message.info.role !== 'string'
+      || (message.info.id !== undefined && typeof message.info.id !== 'string')
+      || (message.info.time !== undefined && (
+        !isRecord(message.info.time)
+        || (message.info.time.created !== undefined && typeof message.info.time.created !== 'number')
+      ))
+    ) throw new OpenCodeResponseError();
+    if (
+      !Array.isArray(message.parts)
+      || message.parts.some((part) => !isRecord(part)
+        || (part.type !== undefined && typeof part.type !== 'string')
+        || (part.text !== undefined && typeof part.text !== 'string')
+        || (part.metadata !== undefined && !isRecord(part.metadata)))
+    ) throw new OpenCodeResponseError();
+    return message as unknown as OCMessage;
+  });
+}
+
 async function listSessions(): Promise<OCSession[]> {
   const { status, body } = await rawGet('/session');
-  if (status !== 200) throw new Error(`OpenCode sessions request failed (${status})`);
-  return JSON.parse(body);
+  if (status !== 200) throw openCodeHttpError(status, 'sessions');
+  return decodeSessions(body);
 }
 
 async function getSession(id: string): Promise<OCSession | 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);
+  if (status !== 200) throw openCodeHttpError(status, 'session');
+  return decodeSession(parseOpenCodeJson(body));
 }
 
 async function listSessionMessages(id: string): Promise<OCMessage[]> {
   const { status, body } = await rawGet(`/session/${id}/message`);
-  if (status !== 200) throw new Error(`OpenCode session messages request failed (${status})`);
-  return JSON.parse(body);
+  if (status !== 200) throw openCodeHttpError(status, 'session messages');
+  return decodeMessages(body);
 }
 
 async function findInjectedMessage(
@@ -298,9 +554,7 @@ async function promptSession(id: string, bodyObj: Record<string, unknown>): Prom
 
 function bindingPath(): string {
   const current = state!;
-  const key = [current.serverUrl, current.directory, current.cubeName, current.droneLabel].join('\0');
-  const digest = createHash('sha256').update(key).digest('hex').slice(0, 24);
-  const path = join(tmpdir(), `borg-opencode-session-${digest}.json`);
+  const path = join(tmpdir(), `borg-opencode-session-${stateIdentityDigest(current)}.json`);
   bindingPathsForTests.add(path);
   return path;
 }
@@ -446,32 +700,28 @@ function restoreBinding(): SessionBinding | null {
 }
 
 function isBoundSession(session: OCSession, binding: SessionBinding): boolean {
-  return session.id === binding.sessionId && session.directory === state!.directory;
+  return session.id === binding.sessionId && session.directory === binding.directory;
 }
 
 function isTopLevelSession(session: OCSession): boolean {
   return !session.parentID;
 }
 
-async function findUnseenTopLevelSession(knownRootSessionIds: string[]): Promise<{
+async function findUnseenTopLevelSession(knownRootSessionIds: string[], directory: string): Promise<{
   session: OCSession;
   knownRootSessionIds: string[];
 } | null> {
-  try {
-    const sessions = await listSessions();
-    const roots = sessions.filter(
-      (session) => session.directory === state!.directory
-        && isTopLevelSession(session),
-    );
-    const matched = roots.filter((session) => !knownRootSessionIds.includes(session.id));
-    if (matched.length === 0) return null;
-    const best = matched.reduce((a, b) =>
-      a.time.created > b.time.created ? a : b,
-    );
-    return { session: best, knownRootSessionIds: roots.map((session) => session.id) };
-  } catch {
-    return null;
-  }
+  const sessions = await listSessions();
+  const roots = sessions.filter(
+    (session) => session.directory === directory
+      && isTopLevelSession(session),
+  );
+  const matched = roots.filter((session) => !knownRootSessionIds.includes(session.id));
+  if (matched.length === 0) return null;
+  const best = matched.reduce((a, b) =>
+    a.time.created > b.time.created ? a : b,
+  );
+  return { session: best, knownRootSessionIds: roots.map((session) => session.id) };
 }
 
 function launchCorrelationMatchCount(messages: OCMessage[], correlationIdentity: string): number {
@@ -500,9 +750,13 @@ async function findLaunchSession(correlationIdentity: string): Promise<{
   session: OCSession;
   knownRootSessionIds: string[];
 } | null> {
+  const owner = state!;
+  const observationSequence = ++owner.nextObservationSequence;
   try {
-    const sessions = (await listSessions()).filter(
-      (session) => session.directory === state!.directory,
+    const listedSessions = await listSessions();
+    if (state !== owner) return null;
+    const sessions = listedSessions.filter(
+      (session) => session.directory === owner.directory,
     );
     const knownRootSessionIds = sessions
       .filter(isTopLevelSession)
@@ -514,23 +768,31 @@ async function findLaunchSession(correlationIdentity: string): Promise<{
         correlationIdentity,
       ),
     })));
+    if (state !== owner) return null;
     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 {
+  } catch (error) {
+    if (state === owner) recordOpenCodeFailure(owner, error, observationSequence);
     return null;
   }
 }
 
-async function resolveInjectionSession(): Promise<OCSession | null> {
+async function resolveInjectionSession(
+  owner: OpenCodeDroneState,
+  observationSequence: number,
+): Promise<OCSession | null> {
+  if (state !== owner) return null;
   const binding = restoreBinding();
   if (!binding) return null;
 
   const bound = await getSession(binding.sessionId);
+  if (state !== owner) return null;
   if (!bound || !isBoundSession(bound, binding)) {
     clearBinding();
-    const replacement = await findUnseenTopLevelSession(binding.knownRootSessionIds);
+    const replacement = await findUnseenTopLevelSession(binding.knownRootSessionIds, owner.directory);
+    if (state !== owner) return null;
     if (!replacement) return null;
     saveBinding(replacement.session, replacement.knownRootSessionIds);
     return replacement.session;
@@ -539,7 +801,13 @@ async function resolveInjectionSession(): Promise<OCSession | null> {
   // `/new` creates an unseen top-level session. Keep the launch-time root
   // snapshot so an old, unrelated root is never mistaken for a user switch.
   // Children never supersede the bound root.
-  const switched = await findUnseenTopLevelSession(binding.knownRootSessionIds);
+  let switched: Awaited<ReturnType<typeof findUnseenTopLevelSession>> = null;
+  try {
+    switched = await findUnseenTopLevelSession(binding.knownRootSessionIds, owner.directory);
+  } catch (error) {
+    recordOpenCodeFailure(owner, error, observationSequence);
+  }
+  if (state !== owner) return null;
   if (switched) {
     saveBinding(switched.session, switched.knownRootSessionIds);
     return switched.session;
@@ -562,6 +830,64 @@ function rememberBounded(
   }
 }
 
+function openCodeFailureCode(error: unknown): string {
+  const code = (error as { code?: unknown } | null)?.code;
+  if (typeof code === 'string' && code.length > 0) return code;
+  return error instanceof Error && error.name ? error.name : 'unknown';
+}
+
+function updateLastOpenCodeObservation(
+  owner: OpenCodeDroneState,
+  sequence: number,
+  update: Partial<OpenCodeLastFields>,
+): void {
+  // Attempts, acceptances, and failures resolve independently; an observation
+  // may be stale for one field without being stale for the others.
+  const current = owner.lastObservation;
+  const updatesInjection = 'lastInjectionAt' in update || 'lastInjectionResult' in update;
+  const updatesAccepted = 'lastAcceptedEntryId' in update;
+  const updatesFailure = 'lastFailureCode' in update;
+  owner.lastObservation = {
+    ...current,
+    ...(updatesInjection && sequence >= current.injectionSequence
+      ? {
+        injectionSequence: sequence,
+        ...('lastInjectionAt' in update
+          ? { lastInjectionAt: update.lastInjectionAt as number | null }
+          : {}),
+        ...('lastInjectionResult' in update
+          ? { lastInjectionResult: update.lastInjectionResult as OpenCodeInjectionResult | null }
+          : {}),
+      }
+      : {}),
+    ...(updatesAccepted && sequence >= current.acceptedSequence
+      ? { acceptedSequence: sequence, lastAcceptedEntryId: update.lastAcceptedEntryId as string | null }
+      : {}),
+    ...(updatesFailure && sequence >= current.failureSequence
+      ? { failureSequence: sequence, lastFailureCode: update.lastFailureCode as string | null }
+      : {}),
+  };
+}
+
+function recordOpenCodeFailure(
+  owner: OpenCodeDroneState,
+  error: unknown,
+  observationSequence: number,
+): void {
+  updateLastOpenCodeObservation(owner, observationSequence, {
+    lastFailureCode: openCodeFailureCode(error),
+  });
+}
+
+function recordOpenCodeAcceptance(
+  owner: OpenCodeDroneState,
+  delivery: Pick<OpenCodeDelivery, 'sequence' | 'entryId'>,
+): void {
+  updateLastOpenCodeObservation(owner, delivery.sequence, {
+    lastAcceptedEntryId: delivery.entryId,
+  });
+}
+
 function clearPendingSubmission(owner: OpenCodeDroneState, entryId: string): void {
   if (!owner.pendingSubmissions.delete(entryId)) return;
   if (state === owner) persistCurrentBinding();
@@ -569,7 +895,7 @@ function clearPendingSubmission(owner: OpenCodeDroneState, entryId: string): voi
 
 function confirmOpenCodeDelivery(
   owner: OpenCodeDroneState,
-  delivery: Pick<OpenCodeDelivery, 'entryId' | 'sourceEntryId' | 'text'>,
+  delivery: Pick<OpenCodeDelivery, 'sequence' | 'entryId' | 'sourceEntryId' | 'text'>,
 ): void {
   const unconfirmed = owner.unconfirmedEntries.get(delivery.entryId);
   if (unconfirmed && unconfirmed.text !== delivery.text) return;
@@ -583,6 +909,11 @@ function confirmOpenCodeDelivery(
     delivery.sourceEntryId,
   );
   owner.totalEntriesInjected++;
+  updateLastOpenCodeObservation(owner, delivery.sequence, {
+    lastAcceptedEntryId: delivery.entryId,
+    lastInjectionResult: 'delivered',
+    lastFailureCode: null,
+  });
 }
 
 function scheduleOpenCodeReconciliation(
@@ -607,7 +938,8 @@ function scheduleOpenCodeReconciliation(
             return;
           }
         } catch (err) {
-          log(`entry ${delivery.entryId} reconciliation unavailable: ${err}`);
+          recordOpenCodeFailure(owner, err, delivery.sequence);
+          log(`entry ${delivery.entryId} reconciliation unavailable: ${err}`, owner);
         }
       }
     } finally {
@@ -656,13 +988,15 @@ async function deliverOpenCodeEntry(
 
     if (!target) {
       try {
-        target = await resolveInjectionSession();
+        target = await resolveInjectionSession(owner, delivery.sequence);
       } catch (err) {
-        log(`entry ${delivery.entryId} target unavailable: ${err}`);
+        recordOpenCodeFailure(owner, err, delivery.sequence);
+        log(`entry ${delivery.entryId} target unavailable: ${err}`, owner);
         continue;
       }
       if (!target) {
-        log(`entry ${delivery.entryId} target unavailable: no bound session`);
+        recordOpenCodeFailure(owner, openCodeHttpError(404, 'session'), delivery.sequence);
+        log(`entry ${delivery.entryId} target unavailable: no bound session`, owner);
         return 'failed';
       }
       delivery.sessionId = target.id;
@@ -679,12 +1013,13 @@ async function deliverOpenCodeEntry(
           : await findInjectedMessage(confirmationSessionId, delivery.sourceEntryId)
       );
       if (deliveredIdentity) {
-        log(`entry ${delivery.entryId} already present in session ${confirmationSessionId}`);
+        log(`entry ${delivery.entryId} already present in session ${confirmationSessionId}`, owner);
         clearPendingSubmission(owner, delivery.entryId);
         return 'delivered';
       }
     } catch (err) {
-      log(`entry ${delivery.entryId} confirmation unavailable: ${err}`);
+      recordOpenCodeFailure(owner, err, delivery.sequence);
+      log(`entry ${delivery.entryId} confirmation unavailable: ${err}`, owner);
       continue;
     }
 
@@ -705,7 +1040,7 @@ async function deliverOpenCodeEntry(
       });
       if (!persistCurrentBinding()) {
         owner.pendingSubmissions.delete(delivery.entryId);
-        log(`entry ${delivery.entryId} submission skipped: pending intent was not durable`);
+        log(`entry ${delivery.entryId} submission skipped: pending intent was not durable`, owner);
         return 'failed';
       }
 
@@ -724,16 +1059,19 @@ async function deliverOpenCodeEntry(
           }],
         });
       } catch (err) {
-        log(`entry ${delivery.entryId} submission outcome unavailable: ${err}`);
+        recordOpenCodeFailure(owner, err, delivery.sequence);
+        log(`entry ${delivery.entryId} submission outcome unavailable: ${err}`, owner);
       }
 
       delivery.state = 'delivered-unconfirmed';
       if (status !== null && status !== 200 && status !== 204) {
+        recordOpenCodeFailure(owner, openCodeHttpError(status, 'prompt'), delivery.sequence);
         clearPendingSubmission(owner, delivery.entryId);
         if (status === 404) clearBinding();
         return 'failed';
       }
       delivery.acceptedSubmission = true;
+      if (status === 200 || status === 204) recordOpenCodeAcceptance(owner, delivery);
     }
 
     for (
@@ -755,7 +1093,8 @@ async function deliverOpenCodeEntry(
           return 'delivered';
         }
       } catch (err) {
-        log(`entry ${delivery.entryId} post-acceptance confirmation unavailable: ${err}`);
+        recordOpenCodeFailure(owner, err, delivery.sequence);
+        log(`entry ${delivery.entryId} post-acceptance confirmation unavailable: ${err}`, owner);
       }
     }
 
@@ -774,12 +1113,26 @@ async function processOpenCodeDeliveries(owner: OpenCodeDroneState): Promise<voi
   try {
     while (state === owner && owner.deliveryQueue.length > 0) {
       const delivery = owner.deliveryQueue.shift()!;
+      updateLastOpenCodeObservation(owner, delivery.sequence, {
+        lastInjectionAt: Date.now(),
+        lastInjectionResult: null,
+        lastFailureCode: null,
+      });
       let outcome: OpenCodeDeliveryOutcome = 'failed';
       try {
         outcome = await deliverOpenCodeEntry(owner, delivery);
       } catch (err) {
-        log(`entry ${delivery.entryId} delivery error: ${err}`);
+        recordOpenCodeFailure(owner, err, delivery.sequence);
+        log(`entry ${delivery.entryId} delivery error: ${err}`, owner);
       }
+      updateLastOpenCodeObservation(owner, delivery.sequence, {
+        lastInjectionResult: outcome,
+        lastFailureCode: outcome === 'delivered'
+          ? null
+          : outcome === 'failed'
+            ? (owner.lastObservation.lastFailureCode ?? 'unknown')
+            : owner.lastObservation.lastFailureCode,
+      });
 
       owner.activeDeliveries.delete(delivery.entryId);
       if (delivery.settled) {
@@ -823,9 +1176,10 @@ async function processOpenCodeDeliveries(owner: OpenCodeDroneState): Promise<voi
  * 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; }
+  const owner = state;
+  if (!owner?.connected) { log('kickoff: not connected', owner); return false; }
   if (!isOpenCode256BitIdentity(launch.correlationIdentity)) {
-    log('kickoff: correlation identity missing or unverifiable');
+    log('kickoff: correlation identity missing or unverifiable', owner);
     return false;
   }
 
@@ -834,7 +1188,7 @@ export async function injectInitialKickoff(launch: OpenCodeLaunchKickoff): Promi
     for (let i = 0; i < 30; i++) {
       try {
         await listSessions();
-        log(`kickoff: server ready (attempt ${i + 1})`);
+        log(`kickoff: server ready (attempt ${i + 1})`, owner);
         break;
       } catch {
         // not ready yet
@@ -847,17 +1201,18 @@ export async function injectInitialKickoff(launch: OpenCodeLaunchKickoff): Promi
     for (let i = 0; i < 30; i++) {
       const binding = await findLaunchSession(launch.correlationIdentity);
       if (binding) {
+        if (state !== owner) return false;
         saveBinding(binding.session, binding.knownRootSessionIds);
-        log(`kickoff: bound session ${binding.session.id.slice(0, 8)}…`);
+        log(`kickoff: bound session ${binding.session.id.slice(0, 8)}…`, owner);
         return true;
       }
       await new Promise((r) => setTimeout(r, 1000));
     }
 
-    log('kickoff: no session found');
+    log('kickoff: no session found', owner);
     return false;
   } catch (err) {
-    log(`kickoff error: ${err}`);
+    log(`kickoff error: ${err}`, owner);
     return false;
   }
 }
@@ -879,7 +1234,7 @@ export function injectOpenCodeEntry(
 ): Promise<boolean> {
   const owner = state;
   if (!owner?.connected) {
-    log(`entry ${entryId} rejected: OpenCode is not connected`);
+    log(`entry ${entryId} rejected: OpenCode is not connected`, owner);
     return Promise.resolve(false);
   }
 
@@ -893,27 +1248,27 @@ export function injectOpenCodeEntry(
       pendingEntryId !== entryId && pending.sourceEntryId === sourceEntryId,
   );
   if (pendingSource) {
-    log(`entry ${entryId} reconciles pending source ${sourceEntryId}`);
+    log(`entry ${entryId} reconciles pending source ${sourceEntryId}`, owner);
     return injectOpenCodeEntry(text, pendingSource[0], false, sourceEntryId, isSourcePending);
   }
   for (const [deliveredEntryId, record] of owner.deliveredEntries) {
     if (deliveredEntryId !== entryId && record.sourceEntryId === sourceEntryId) {
       if (record.text !== text) return Promise.resolve(false);
-      log(`entry ${entryId} source ${sourceEntryId} already delivered`);
+      log(`entry ${entryId} source ${sourceEntryId} already delivered`, owner);
       return Promise.resolve(true);
     }
   }
   for (const [unconfirmedEntryId, record] of owner.unconfirmedEntries) {
     if (unconfirmedEntryId !== entryId && record.sourceEntryId === sourceEntryId) {
       if (record.text !== text) return Promise.resolve(false);
-      log(`entry ${entryId} source ${sourceEntryId} remains unconfirmed`);
+      log(`entry ${entryId} source ${sourceEntryId} remains unconfirmed`, owner);
       return Promise.resolve(true);
     }
   }
   for (const active of owner.activeDeliveries.values()) {
     if (active.entryId !== entryId && active.sourceEntryId === sourceEntryId) {
       if (active.text !== text) return Promise.resolve(false);
-      log(`entry ${entryId} joined active source ${sourceEntryId}`);
+      log(`entry ${entryId} joined active source ${sourceEntryId}`, owner);
       return active.promise;
     }
   }
@@ -921,26 +1276,27 @@ export function injectOpenCodeEntry(
   const delivered = owner.deliveredEntries.get(entryId);
   if (delivered !== undefined) {
     if (delivered.text !== text || delivered.sourceEntryId !== sourceEntryId) {
-      log(`entry ${entryId} replay text mismatch`);
+      log(`entry ${entryId} replay text mismatch`, owner);
       rememberBounded(owner.failedEntries, entryId, text, sourceEntryId);
       return Promise.resolve(false);
     }
-    log(`entry ${entryId} replay already delivered`);
+    log(`entry ${entryId} replay already delivered`, owner);
     return Promise.resolve(true);
   }
 
   const unconfirmed = owner.unconfirmedEntries.get(entryId);
   if (unconfirmed !== undefined) {
     if (unconfirmed.text !== text || unconfirmed.sourceEntryId !== sourceEntryId) {
-      log(`entry ${entryId} unconfirmed replay text mismatch`);
+      log(`entry ${entryId} unconfirmed replay text mismatch`, owner);
       rememberBounded(owner.failedEntries, entryId, text, sourceEntryId);
       return Promise.resolve(false);
     }
-    log(`entry ${entryId} replay remains unconfirmed`);
+    log(`entry ${entryId} replay remains unconfirmed`, owner);
     const pending = owner.pendingSubmissions.get(entryId);
     const accepted = pending !== undefined;
     if (pending) {
       scheduleOpenCodeReconciliation(owner, {
+        sequence: ++owner.nextObservationSequence,
         entryId,
         sourceEntryId,
         text,
@@ -959,11 +1315,11 @@ export function injectOpenCodeEntry(
   const active = owner.activeDeliveries.get(entryId);
   if (active) {
     if (active.text !== text || active.sourceEntryId !== sourceEntryId) {
-      log(`entry ${entryId} active text mismatch`);
+      log(`entry ${entryId} active text mismatch`, owner);
       rememberBounded(owner.failedEntries, entryId, text, sourceEntryId);
       return Promise.resolve(false);
     }
-    log(`entry ${entryId} replay joined active delivery`);
+    log(`entry ${entryId} replay joined active delivery`, owner);
     return active.promise;
   }
 
@@ -972,6 +1328,7 @@ export function injectOpenCodeEntry(
     resolveDelivery = resolve;
   });
   const delivery: OpenCodeDelivery = {
+    sequence: ++owner.nextObservationSequence,
     entryId,
     sourceEntryId,
     text,
@@ -1017,16 +1374,21 @@ export function settleOpenCodeEntry(sourceEntryId: string): void {
 }
 
 export async function probeOpenCodeDroneArmed(): Promise<boolean | null> {
-  if (!state?.connected) return null;
+  const owner = state;
+  if (!owner?.connected) return null;
+  const observationSequence = ++owner.nextObservationSequence;
   const binding = restoreBinding();
   if (!binding) return false;
 
   try {
     const session = await getSession(binding.sessionId);
+    if (state !== owner) return null;
     if (session && isBoundSession(session, binding)) return true;
+    recordOpenCodeFailure(owner, openCodeHttpError(404, 'session'), observationSequence);
     clearBinding();
     return false;
-  } catch {
+  } catch (error) {
+    if (state === owner) recordOpenCodeFailure(owner, error, observationSequence);
     return false;
   }
 }
@@ -1041,6 +1403,10 @@ export interface OpenCodeConnectionState {
   sessionId: string | null;
   totalEntriesInjected: number;
   totalEntriesRetried: number;
+  lastInjectionAt: number | null;
+  lastInjectionResult: OpenCodeInjectionResult | null;
+  lastAcceptedEntryId: string | null;
+  lastFailureCode: string | null;
   deliveryStates: Record<OpenCodeDeliveryState, number>;
 }
 
@@ -1059,10 +1425,24 @@ export function getOpenCodeConnectionState(): OpenCodeConnectionState {
     sessionId: state?.sessionId ?? null,
     totalEntriesInjected: state?.totalEntriesInjected ?? 0,
     totalEntriesRetried: state?.totalEntriesRetried ?? 0,
+    lastInjectionAt: state?.lastObservation.lastInjectionAt ?? null,
+    lastInjectionResult: state?.lastObservation.lastInjectionResult ?? null,
+    lastAcceptedEntryId: state?.lastObservation.lastAcceptedEntryId ?? null,
+    lastFailureCode: state?.lastObservation.lastFailureCode ?? null,
     deliveryStates,
   };
 }
 
+export function __getOpenCodeDiagnosticLogPathForTests(): string {
+  if (!state) throw new Error('OpenCode drone is not connected');
+  return diagnosticLogPath(state);
+}
+
+export function __getOpenCodeLastObservationForTests(): OpenCodeLastObservation {
+  if (!state) throw new Error('OpenCode drone is not connected');
+  return { ...state.lastObservation };
+}
+
 export function computeOpenCodePort(droneId: string, base: number = 14096): number {
   let hash = 0;
   for (let i = 0; i < droneId.length; i++) {
@@ -1141,4 +1521,12 @@ export function __resetOpenCodeDroneForTests(): void {
     }
   }
   bindingPathsForTests.clear();
+  for (const path of diagnosticLogPathsForTests) {
+    try {
+      unlinkSync(path);
+    } catch {
+      // Already removed.
+    }
+  }
+  diagnosticLogPathsForTests.clear();
 }