borgmcp 4.2.1 → 4.2.3

package/src/codex-app-wake.ts

@@ -123,8 +123,116 @@ export function getLastDeliveredAt(): number | null {
   return lastDeliveredAt;
 }
 
+// client#89: delivery-state observability. The Codex wake-path health surface
+// must distinguish "bridge armed" from "delivery healthy" — a wake deferred
+// (mid-turn) or failed and being retried is NOT a healthy wake path, even
+// though the app-server socket is alive. These module-scoped fields track the
+// last injection attempt/result and the last failure (a secret-free error
+// code/class only — never message contents); the deferred-queue state is read
+// live from the existing retry-drain fields. Same process as the health probe
+// (the wake path and stream-status run in the same MCP-client child), so the
+// snapshot is directly visible. NONE of this changes the wake mechanism.
+type CodexInjectionResult = 'delivered' | 'deferred' | 'failed';
+// HISTORICAL reporting — the last injection attempt/result/failure. These are
+// surfaced on the status surface for diagnosis; they are NOT used to decide
+// health, because a historical result does not self-clear when work is drained
+// by another path (manual read, server read-cursor recovery). Health keys off
+// the LIVE signals below.
+let lastInjectionAt: number | null = null;
+let lastInjectionResult: CodexInjectionResult | null = null;
+let lastInjectionFailureCode: string | null = null;
+let lastTargetThreadId: string | null = null;
+// client#89: a LIVE marker for undelivered directed wakes NOT tracked by the
+// retry-drain queue (retryDrainActive / deferredEntryCount cover that queue and
+// self-clear on prune/deliver). SET at every injection exit where an
+// authoritatively-pending wake could not be delivered and is not queued: the
+// heartbeat mid-turn skip / no-target return / transient failure, the per-entry
+// no-target return for a still-pending scoped entry, and the retry-drain age-out
+// hand-off. CLEARED when any delivery lands (markDelivered) and when the
+// heartbeat authoritatively finds no pending work. It is a LIVE signal, not a
+// historical result, so a seat that recovers by any path returns to healthy.
+let deliveryDeferred = false;
+
+export interface CodexDeliveryState {
+  /** Opaque thread id of the last-resolved wake target (never a socket path). */
+  lastTargetThreadId: string | null;
+  /** HISTORICAL last attempt time (reporting only; not a health input). */
+  lastInjectionAt: number | null;
+  /** HISTORICAL last attempt result (reporting only; not a health input). */
+  lastInjectionResult: CodexInjectionResult | null;
+  /** Secret-free error code/class of the last failed injection; never contents. */
+  lastInjectionFailureCode: string | null;
+  /** LIVE: entries currently deferred/retrying (not yet confirmed delivered). */
+  deferredEntryCount: number;
+  /** LIVE: a coalesced retry-drain loop is currently retrying deferred/missed wakes. */
+  retryDrainActive: boolean;
+  /** LIVE: an undelivered directed wake not tracked by the retry-drain queue. */
+  deliveryDeferred: boolean;
+  lastDeliveredAt: number | null;
+}
+
+/** Snapshot of the Codex wake-path delivery state for the health/status surface. */
+export function getCodexDeliveryState(): CodexDeliveryState {
+  return {
+    lastTargetThreadId,
+    lastInjectionAt,
+    lastInjectionResult,
+    lastInjectionFailureCode,
+    deferredEntryCount: retryDrainSourceEntryIds.size + (retryDrainHasUnscopedWork ? 1 : 0),
+    retryDrainActive: retryDrainInFlight,
+    deliveryDeferred,
+    lastDeliveredAt,
+  };
+}
+
+/** Reduce a caught error to a secret-free code/class — never its message. */
+function injectionFailureCode(err: unknown): string {
+  const code = (err as { code?: unknown } | null)?.code;
+  if (typeof code === 'string' && code.length > 0) return code;
+  if (err instanceof Error && err.name) return err.name;
+  return 'unknown';
+}
+
+function recordInjectionResult(
+  result: CodexInjectionResult,
+  now: () => number,
+  failureCode?: string,
+): void {
+  lastInjectionAt = now();
+  lastInjectionResult = result;
+  lastInjectionFailureCode = result === 'failed' ? (failureCode ?? 'unknown') : null;
+}
+
+/**
+ * client#89: pure wake-path health for Codex, folding the LIVE delivery state
+ * into the raw "bridge armed" probe. A wake still pending redelivery — a live
+ * retry-drain, a non-empty deferred queue, or an undelivered heartbeat pending
+ * — is NOT a confirmed-healthy path (returns null = degraded). A positively-
+ * dead bridge dominates (false). Historical last-attempt results are NOT used
+ * here: they do not self-clear when work is drained by another path, so keying
+ * health off them would leave a recovered seat permanently degraded.
+ */
+export function codexWakePathHealthy(
+  armed: boolean | null,
+  state: CodexDeliveryState,
+): boolean | null {
+  if (armed === false) return false; // positively-dead bridge
+  if (armed === null) return null; // could not probe → indeterminate
+  // Bridge armed. Degraded while any LIVE signal shows an unconfirmed delivery.
+  if (
+    state.retryDrainActive ||
+    state.deferredEntryCount > 0 ||
+    state.deliveryDeferred
+  ) {
+    return null;
+  }
+  return true;
+}
+
 function markDelivered(deps: CodexWakeDeps): void {
   lastDeliveredAt = (deps.now ?? Date.now)();
+  // client#89: any confirmed delivery clears the live heartbeat-pending marker.
+  deliveryDeferred = false;
 }
 
 // gh#857 WI-2: a single-in-flight guard for the heartbeat tick (mirrors
@@ -327,8 +435,18 @@ async function wakeCodexTargeted(
     // gh#855: resolve FRESH (live env socket + re-resolved thread), falling back
     // to the launch-recorded file only when the env socket is absent.
     const resolved = await resolveFreshCodexWakeTarget(active, deps);
-    if (!resolved) return;
+    if (!resolved) {
+      // client#89: a scoped entry passed the pending check above but no target
+      // resolves — undeliverable, and this path does NOT schedule a retry-drain
+      // (the design leaves it to the next wake / the heartbeat backstop). Mark
+      // the deferral live so health reads degraded rather than armed. An
+      // unscoped wake carries no authoritative pending signal, so it does not
+      // set the marker. Retry behavior is unchanged.
+      if (sourceEntryId) deliveryDeferred = true;
+      return;
+    }
     const { socketPath, threadId } = resolved;
+    lastTargetThreadId = threadId; // client#89: record the selected target
     const wakeKey = `${threadId}\0${deliveryIdentity ?? reason}`;
     if (deliveredWakeKeys.has(wakeKey)) return; // dedup before opening the wake socket
     const client = makeCodexClient(socketPath, deps);
@@ -340,21 +458,24 @@ async function wakeCodexTargeted(
         // now. Schedule the retry-drain (coalesced, retried-until-delivered) so
         // the burst's entries are drained once the thread goes idle; codex has no
         // on-disk tail fallback like Claude's borg-inbox-monitor.
+        recordInjectionResult('deferred', deps.now ?? Date.now); // client#89
         scheduleRetryDrain(deps, sourceEntryId);
         return;
       }
       if (sourceEntryId && !(await pendingEntry(active, sourceEntryId))) return;
       await client.startTurn(threadId, reason);
       rememberDeliveredWake(wakeKey);
+      recordInjectionResult('delivered', deps.now ?? Date.now); // client#89
       markDelivered(deps);
     } finally {
       client.close();
     }
-  } catch {
+  } catch (err) {
     // gh#857: a transient connect/read/startTurn failure must NOT be silently
     // swallowed (the old best-effort drop let a single blip lose an entry).
     // Schedule the retry-drain so the wake is retried-until-delivered; the SSE
     // stream is never broken (this is fire-and-forget).
+    recordInjectionResult('failed', deps.now ?? Date.now, injectionFailureCode(err)); // client#89
     scheduleRetryDrain(deps, sourceEntryId);
   } finally {
     releaseInjectLock();
@@ -414,11 +535,13 @@ async function runRetryDrainLoop(deps: CodexWakeDeps): Promise<void> {
       const resolved = await resolveFreshCodexWakeTarget(active, deps);
       if (!resolved) continue; // thread not loaded yet → retry (age-capped)
       const { socketPath, threadId } = resolved;
+      lastTargetThreadId = threadId; // client#89: record the selected target
       const client = makeCodexClient(socketPath, deps);
       await client.connect();
       try {
         const thread = await client.readThread(threadId);
         if (thread?.status?.type === 'active') {
+          recordInjectionResult('deferred', now); // client#89
           continue; // re-defer: still mid-turn (backoff before next poll)
         }
         for (const entryId of retryDrainSourceEntryIds) {
@@ -428,19 +551,31 @@ async function runRetryDrainLoop(deps: CodexWakeDeps): Promise<void> {
         await client.startTurn(threadId, CODEX_CATCHUP_PROMPT);
         retryDrainSourceEntryIds.clear();
         retryDrainHasUnscopedWork = false;
+        recordInjectionResult('delivered', now); // client#89
         markDelivered(deps);
         return; // drain delivered → server read-cursor drains all unread → done
       } finally {
         client.close();
       }
-    } catch {
+    } catch (err) {
       // transient socket/read error must not abort the loop — keep retrying with
       // backoff until reachable+idle or the age cap; never throws into SSE.
+      recordInjectionResult('failed', now, injectionFailureCode(err)); // client#89
     } finally {
       releaseInjectLock();
     }
   }
   // aged out: the gh#857 WI-2 periodic heartbeat is the ultimate backstop.
+  // client#89: if obligations remain unfinished (the thread stayed mid-turn
+  // through the age cap), the loop is gone but the entries are still pending.
+  // Hand off to the live marker and clear the retry-drain set, so health stays
+  // degraded (not stuck via a stale deferredEntryCount after the loop exits)
+  // and clears when a delivery lands or the unread authoritatively empties.
+  if (retryDrainSourceEntryIds.size > 0 || retryDrainHasUnscopedWork) {
+    retryDrainSourceEntryIds.clear();
+    retryDrainHasUnscopedWork = false;
+    deliveryDeferred = true;
+  }
 }
 
 /**
@@ -484,16 +619,41 @@ export async function fireCodexHeartbeatTick(
     // authoritative unread state without advancing its cursor; only then touch
     // the app-server socket or resolve a thread.
     const hasPendingWork = deps.hasPendingWork ?? hasPendingWakeActivity;
-    if (!(await hasPendingWork(active))) return;
+    if (!(await hasPendingWork(active))) {
+      // client#89: authoritative unread is empty → no undelivered wake remains.
+      // Clear the live heartbeat-pending marker so a seat that recovered by any
+      // path (manual read, server read-cursor drain) returns to healthy.
+      deliveryDeferred = false;
+      return;
+    }
     const resolved = await resolveFreshCodexWakeTarget(active, deps);
-    if (!resolved) return; // thread not loaded yet → next tick retries
+    if (!resolved) {
+      // client#89: authoritative pending work exists but no fresh target/thread
+      // resolves — the wake is UNDELIVERABLE this tick. The persisted-target
+      // probe can still read armed, so mark the deferral live (health degraded)
+      // until a target resolves and delivers, or the unread authoritatively
+      // clears. Cadence/retry behavior is unchanged (the next tick still tries).
+      deliveryDeferred = true;
+      return; // thread not loaded yet → next tick retries
+    }
+    lastTargetThreadId = resolved.threadId; // client#89: record the selected target
     const client = makeCodexClient(resolved.socketPath, deps);
     await client.connect();
     try {
       const thread = await client.readThread(resolved.threadId);
-      if (thread?.status?.type === 'active') return; // mid-turn → skip; next tick retries
+      if (thread?.status?.type === 'active') {
+        // client#89: we passed hasPendingWork above, so a mid-turn thread here
+        // means a directed entry is deferred. Mark it LIVE-pending (the heartbeat
+        // does not queue into the retry-drain) so the health surface reads
+        // degraded until a delivery lands or the unread authoritatively clears.
+        // Skip semantics are unchanged — the next tick still retries.
+        recordInjectionResult('deferred', deps.now ?? Date.now);
+        deliveryDeferred = true;
+        return; // mid-turn → skip; next tick retries
+      }
       await client.startTurn(resolved.threadId, CODEX_CATCHUP_PROMPT);
-      // markDelivered updates local heartbeat-gating state only.
+      // markDelivered clears the live heartbeat-pending marker.
+      recordInjectionResult('delivered', deps.now ?? Date.now); // client#89
       markDelivered(deps);
     } finally {
       client.close();
@@ -503,6 +663,11 @@ export async function fireCodexHeartbeatTick(
     // path is gone; signal teardown so the timer stops ticking against a dead
     // socket (re-armed when an active cube returns). Other (transient) errors are
     // best-effort skips — never break the SSE stream; next tick retries.
+    // client#89: we passed hasPendingWork, so a failure here leaves pending work
+    // undelivered → mark it live-pending (a dead bridge is separately false via
+    // the armed probe). Clears on the next authoritative-empty tick or delivery.
+    recordInjectionResult('failed', deps.now ?? Date.now, injectionFailureCode(err)); // client#89
+    deliveryDeferred = true;
     if (isAppServerDeadError(err)) deps.onAppServerSocketDead?.();
   } finally {
     heartbeatInFlight = false;
@@ -552,6 +717,12 @@ export function resetCodexWakeForTests(): void {
   lastDeliveredAt = null;
   heartbeatInFlight = false;
   injectInFlight = false;
+  // client#89 delivery-state observability
+  lastInjectionAt = null;
+  lastInjectionResult = null;
+  lastInjectionFailureCode = null;
+  lastTargetThreadId = null;
+  deliveryDeferred = false;
 }
 
 function rememberDeliveredWake(key: string): void {

package/src/index.ts

@@ -253,6 +253,18 @@ export function formatUpdatedRoleResult(role: { name: string; id: string; role_c
   return appendServerAdvisory(`Updated role **${role.name}**${tag} (id: ${role.id}).`, advisory);
 }
 
+// gh#501: the borg_tool dispatcher only requires its inner arguments to be an
+// object, so the direct-tool enum schema does not guard borg_ack.kind. Resolve
+// it explicitly: ONLY a missing kind (undefined) defaults to 'ack' (the
+// documented default). A valid kind passes through; every present value —
+// including an explicit null — that is not 'ack'/'claim' is REFUSED rather
+// than silently coerced into a state-changing acknowledgement.
+export function resolveAckKind(raw: unknown): 'ack' | 'claim' {
+  if (raw === undefined) return 'ack';
+  if (raw === 'ack' || raw === 'claim') return raw;
+  throw new Error('kind must be "ack" or "claim" when provided');
+}
+
 // gh#496: the unread drain runs on every wake, so its structured payload must
 // stay proportional to the entries it returns. Rosters are deliberately NOT
 // included — entries already carry drone_label/role_name, and borg_roster
@@ -1082,10 +1094,10 @@ export async function main() {
           if (!entryId || typeof entryId !== 'string') {
             throw new Error('entry_id is required');
           }
-          // gh#418: default 'ack'. Only 'claim' is the other allowed kind; the
-          // worker re-validates at the Zod boundary so an unknown value is
-          // rejected server-side, but normalize here to keep the wire clean.
-          const kind: 'ack' | 'claim' = args?.kind === 'claim' ? 'claim' : 'ack';
+          // gh#418/gh#501: absent kind defaults to 'ack'; a present invalid
+          // value is refused here (not coerced) so a dispatcher call cannot
+          // turn a typo into a state-changing acknowledgement.
+          const kind: 'ack' | 'claim' = resolveAckKind(args?.kind);
           const active = await requireActiveCube();
           await ackLogEntry(
             active.sessionToken,

package/src/stream-status.ts

@@ -277,6 +277,20 @@ export function renderStreamStatus(inputs: RenderInputs): string {
     );
   }
 
+  // client#89: Codex remote-control delivery state — distinct from SSE health.
+  // Surfaces the selected target, last bounded injection attempt/result,
+  // deferred-queue state, and last failure (a secret-free code/class only).
+  if (wakePath.agentKind === 'codex' && wakePath.codex) {
+    const d = wakePath.codex;
+    lines.push(`- **Codex wake target thread**: ${d.lastTargetThreadId ?? '_(none resolved yet)_'}`);
+    lines.push(`- **Codex last injection**: ${d.lastInjectionResult ?? '_(none yet)_'}${d.lastInjectionAt ? ` at ${new Date(d.lastInjectionAt).toISOString()}` : ''}`);
+    lines.push(`- **Codex deferred/retrying entries**: ${d.deferredEntryCount}${d.retryDrainActive ? ' (retry-drain active)' : ''}${d.deliveryDeferred ? ' — undelivered wake pending' : ''}`);
+    lines.push(`- **Codex last failure code**: ${d.lastInjectionFailureCode ?? '_(none)_'}`);
+    lines.push(
+      '- **Codex delivery-state meaning**: a deferred or retrying wake means a directed entry has not yet been confirmed delivered to the model — the wake path reads degraded (not healthy) until the wake is delivered or the unread log is drained, even though the app-server bridge is armed.'
+    );
+  }
+
   // Runtime-specific wake-path warning. The wire-down case takes
   // precedence above; an indeterminate signal remains honest and silent.
   if (status.connected && wakePathHealthy === false) {

package/src/tool-manifest.ts

@@ -7,7 +7,7 @@
  * CONTRACT-BACKED DATA — imports only published scalar contract constants, with
  * no client runtime side effects.
  */
-import { DECISION_TEXT_MAX_BYTES, DOCUMENT_CONTENT_TYPES } from 'borgmcp-shared/protocol';
+import { DECISION_TEXT_MAX_BYTES, DEFAULT_MAX_LOG_ENTRY_BYTES, DOCUMENT_CONTENT_TYPES } from 'borgmcp-shared/protocol';
 
 /**
  * gh#492: JSON Schema contract for a tool's `structuredContent`. Success
@@ -420,7 +420,7 @@ const BASE_TOOL_MANIFEST: ToolManifestEntry[] = [
           inputSchema: {
             type: 'object',
             properties: {
-              message: { type: 'string', description: 'The log message (max 10KB).' },
+              message: { type: 'string', description: `The log message. Default limit ${DEFAULT_MAX_LOG_ENTRY_BYTES} bytes (server-configurable); a longer post is refused — store the detail as a document and cite it.` },
               // Keep this required value schema combinator-free for flat tool
               // serializers. normalizeLogAudience remains the strict boundary.
               to: {
@@ -879,7 +879,9 @@ export const TOOL_OUTPUT_SCHEMAS: Record<string, OutputSchema> = {
         },
       },
       wake_path: { type: 'object', description: 'Runtime-specific wake-path inspection.' },
-      inbox_monitor_healthy: { type: 'boolean' },
+      // gh#500: null when wake-path health is indeterminate (a real state,
+      // distinct from false=determined-unhealthy); the source is boolean|null.
+      inbox_monitor_healthy: { type: ['boolean', 'null'] },
       inbox_path: { type: ['string', 'null'] },
       monitor_state_root: { type: ['string', 'null'] },
       drone_label: { type: ['string', 'null'] },
@@ -1173,7 +1175,8 @@ export const TOOL_OUTPUT_SCHEMAS: Record<string, OutputSchema> = {
       decision_topics: { type: 'array', items: { type: 'string' } },
       running_version: { type: 'string' },
       on_disk_version: { type: ['string', 'null'] },
-      wake_path_healthy: { type: 'boolean' },
+      // gh#500: null when wake-path health is indeterminate (boolean|null source).
+      wake_path_healthy: { type: ['boolean', 'null'] },
     },
     required: ['connected'],
   },

package/src/wake-path-health.ts

@@ -1,4 +1,9 @@
-import { probeCodexBridgeArmed } from './codex-app-wake.js';
+import {
+  probeCodexBridgeArmed,
+  getCodexDeliveryState,
+  codexWakePathHealthy,
+  type CodexDeliveryState,
+} from './codex-app-wake.js';
 import { checkInboxMonitorHealthy } from './stream-status.js';
 import {
   getOpenCodeConnectionState,
@@ -10,6 +15,8 @@ export interface WakePathSnapshot {
   agentKind: AgentKind;
   healthy: boolean | null;
   openCode: OpenCodeConnectionState | null;
+  // client#89: Codex remote-control delivery state, distinct from SSE health.
+  codex?: CodexDeliveryState | null;
 }
 
 interface InspectWakePathInputs {
@@ -22,6 +29,7 @@ interface InspectWakePathInputs {
 interface InspectWakePathDeps {
   checkClaudeMonitor?: typeof checkInboxMonitorHealthy;
   probeCodex?: typeof probeCodexBridgeArmed;
+  getCodexDelivery?: typeof getCodexDeliveryState;
   getOpenCodeState?: typeof getOpenCodeConnectionState;
 }
 
@@ -67,11 +75,18 @@ export async function inspectWakePath(
   }
 
   if (inputs.agentKind === 'codex') {
+    // client#89: fold the delivery state into health so a deferred, retrying,
+    // or failed injection surfaces as degraded — never as armed/healthy — even
+    // while the app-server socket is alive. SSE health is not the discriminator.
     const probe = deps.probeCodex ?? probeCodexBridgeArmed;
+    const getDelivery = deps.getCodexDelivery ?? getCodexDeliveryState;
+    const armed = await probe(inputs.active);
+    const codex = getDelivery();
     return {
       agentKind: inputs.agentKind,
-      healthy: await probe(inputs.active),
+      healthy: codexWakePathHealthy(armed, codex),
       openCode: null,
+      codex,
     };
   }