borgmcp 4.2.2 → 4.3.0

package/dist/wake-path-health.js

@@ -1,4 +1,4 @@
-import { probeCodexBridgeArmed } from './codex-app-wake.js';
+import { probeCodexBridgeArmed, getCodexDeliveryState, codexWakePathHealthy, } from './codex-app-wake.js';
 import { checkInboxMonitorHealthy } from './stream-status.js';
 import { getOpenCodeConnectionState, } from './opencode-drone.js';
 export function openCodeWakePathHealthy(state) {
@@ -33,11 +33,18 @@ export async function inspectWakePath(inputs, deps = {}) {
         };
     }
     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,
         };
     }
     const getState = deps.getOpenCodeState ?? getOpenCodeConnectionState;

package/dist/wake-path-health.js.map

@@ -1 +1 @@
-{"version":3,"file":"wake-path-health.js","sourceRoot":"","sources":["../src/wake-path-health.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EACL,0BAA0B,GAE3B,MAAM,qBAAqB,CAAC;AAsB7B,MAAM,UAAU,uBAAuB,CACrC,KAA8B;IAE9B,IAAI,CAAC,KAAK,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IACnC,IACE,KAAK,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAC/B,KAAK,CAAC,cAAc,CAAC,uBAAuB,CAAC,GAAG,CAAC,EACjD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IACE,KAAK,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAC/B,KAAK,CAAC,cAAc,CAAC,OAAO,GAAG,CAAC,EAChC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAA6B,EAC7B,OAA4B,EAAE;IAE9B,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO;YACL,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,kBAAkB,IAAI,wBAAwB,CAAC;QAClE,OAAO;YACL,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,gBAAgB,CAAC;YACzD,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,IAAI,qBAAqB,CAAC;QACvD,OAAO;YACL,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,OAAO,EAAE,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;YACnC,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,IAAI,0BAA0B,CAAC;IACrE,MAAM,QAAQ,GAAG,QAAQ,EAAE,CAAC;IAC5B,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,uBAAuB,CAAC,QAAQ,CAAC;QAC1C,QAAQ;KACT,CAAC;AACJ,CAAC"}
+{"version":3,"file":"wake-path-health.js","sourceRoot":"","sources":["../src/wake-path-health.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,GAErB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EACL,0BAA0B,GAE3B,MAAM,qBAAqB,CAAC;AAyB7B,MAAM,UAAU,uBAAuB,CACrC,KAA8B;IAE9B,IAAI,CAAC,KAAK,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IACnC,IACE,KAAK,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAC/B,KAAK,CAAC,cAAc,CAAC,uBAAuB,CAAC,GAAG,CAAC,EACjD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IACE,KAAK,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAC/B,KAAK,CAAC,cAAc,CAAC,OAAO,GAAG,CAAC,EAChC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAA6B,EAC7B,OAA4B,EAAE;IAE9B,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO;YACL,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,kBAAkB,IAAI,wBAAwB,CAAC;QAClE,OAAO;YACL,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,gBAAgB,CAAC;YACzD,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC;QACjC,0EAA0E;QAC1E,2EAA2E;QAC3E,6EAA6E;QAC7E,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,IAAI,qBAAqB,CAAC;QACvD,MAAM,WAAW,GAAG,IAAI,CAAC,gBAAgB,IAAI,qBAAqB,CAAC;QACnE,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,KAAK,GAAG,WAAW,EAAE,CAAC;QAC5B,OAAO;YACL,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,OAAO,EAAE,oBAAoB,CAAC,KAAK,EAAE,KAAK,CAAC;YAC3C,QAAQ,EAAE,IAAI;YACd,KAAK;SACN,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,IAAI,0BAA0B,CAAC;IACrE,MAAM,QAAQ,GAAG,QAAQ,EAAE,CAAC;IAC5B,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,uBAAuB,CAAC,QAAQ,CAAC;QAC1C,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "4.2.2",
+  "version": "4.3.0",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",

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

@@ -38,6 +38,7 @@ import {
   regen,
   listCubes,
   createCube,
+  normalizeExplicitRepository,
   updateCube,
   deleteCube,
   createRole,
@@ -1243,19 +1244,37 @@ export async function main() {
             }
           }
 
+          // client#499: the cube binds to an EXPLICIT repository (no cwd
+          // inference). Normalize the argument client-side and fail with a
+          // clear message when it is absent/malformed — no working-directory
+          // fallback.
+          const { repository, workingRepoName } = normalizeExplicitRepository(
+            args?.repository,
+            args?.working_repo_name,
+          );
+
           // Sprint 14: template cube_directive fills empty operator input.
           // Operator-supplied text takes precedence — templates fill
           // the blank, never stomp.
           const resolvedCubeDirective = resolveCubeDirectiveForCreate(cubeDirective, template);
-
-          // v0.9.2: createCube now returns the flat shape directly
-          // (see remote-client unwrap). `cube.id` / `cube.name` work
-          // verbatim on the returned object.
           const resolvedMessageTaxonomy = resolveMessageTaxonomyForCreate(undefined, template);
-          const cube = await createCube(name, resolvedCubeDirective, {
+          const { result, cube } = await createCube(name, resolvedCubeDirective, {
             message_taxonomy: resolvedMessageTaxonomy,
+            repository,
+            workingRepoName,
           });
 
+          // client#499: the server homed this repository to an EXISTING cube —
+          // report it honestly, apply no template, and leave its directive
+          // untouched.
+          if (result === 'resolved') {
+            const text = `A cube already exists for this repository: **${cube.name}** (id: ${cube.id}). The local Borg server homes one cube per repository; its directive was left unchanged. Use borg_assimilate ${cube.name} to join it, or borg_update-cube to change its settings.`;
+            return {
+              content: [{ type: 'text', text }],
+              structuredContent: { cube, result: 'resolved', template: null, roles_created: null, roles_updated: null },
+            };
+          }
+
           // Apply template roles if requested. Merges by name: any role the
           // server auto-seeded (e.g. "Drone") that the template doesn't
           // also include stays put; templated roles upsert.
@@ -1269,6 +1288,7 @@ export async function main() {
               content: [{ type: 'text', text }],
               structuredContent: {
                 cube,
+                result: 'created',
                 template: templateName,
                 roles_created: summary.created,
                 roles_updated: summary.updated,
@@ -1278,7 +1298,7 @@ export async function main() {
           const text = `Created cube **${cube.name}** (id: ${cube.id}). A default "Drone" role was seeded — rename or replace it via borg_update-role / borg_create-role / borg_delete-role. Use borg_assimilate ${cube.name} to join as a drone.`;
           return {
             content: [{ type: 'text', text }],
-            structuredContent: { cube, template: null, roles_created: null, roles_updated: null },
+            structuredContent: { cube, result: 'created', template: null, roles_created: null, roles_updated: null },
           };
         }
 

package/src/remote-client.ts

@@ -51,11 +51,15 @@ import {
   type EvictDroneResult,
   type ReassignDroneResult,
   type RoleRationaleResult,
+  decodeCreateCubeResponse,
   type PutDocumentResult,
   type GetDocumentResult,
   type ListDocumentsResult,
   type RemoveDocumentResult,
+  type CreateCubeRepository,
 } from 'borgmcp-shared/protocol';
+import { Buffer } from 'node:buffer';
+import { canonicalizeWorkingRepoIdentity } from './working-repo.js';
 import { consolePrefix } from './console-prefix.js';
 import { debugLog } from './debug.js';
 import { assertUuidShape } from './evict-drone.js';
@@ -1526,31 +1530,116 @@ export async function listCubes(connection?: RemoteConnection): Promise<{ cubes:
  * orchestrator pick a default role without a follow-up `getCube` call.
  * Existing callers that read `body.cube` keep working (forward-compat).
  */
+const REPOSITORY_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// The wire's working_repo_name rule (borgmcp-shared decodeWorkingRepositoryName,
+// which the package does not export): 1-120 UTF-8 bytes, must start with a
+// letter or digit, then letters/digits/spaces/dots/underscores/hyphens.
+const WORKING_REPO_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/;
+
+function assertValidWorkingRepoName(name: string): string {
+  const bytes = Buffer.byteLength(name, 'utf8');
+  if (bytes < 1 || bytes > 120 || !WORKING_REPO_NAME_RE.test(name)) {
+    throw new Error(
+      'working_repo_name must start with a letter or digit and contain only letters, digits, spaces, dots, underscores, or hyphens (1-120 UTF-8 bytes).',
+    );
+  }
+  return name;
+}
+
+export interface NormalizedCreateCubeRepository {
+  repository: CreateCubeRepository;
+  workingRepoName: string;
+}
+
+/**
+ * client#499: normalize the EXPLICIT repository argument into the wire's
+ * `{ repository, working_repo_name }` pair — no cwd inference. A canonical git
+ * remote URL becomes an `origin` identity (reusing the shared canonicalizer,
+ * the same encoding the CLI create path uses); a UUID becomes a `local`
+ * identity (the server requires a UUID for local repositories). The optional
+ * working-repo display name defaults to the origin's repository segment.
+ */
+export function normalizeExplicitRepository(
+  repositoryArg: unknown,
+  workingRepoNameArg?: unknown,
+): NormalizedCreateCubeRepository {
+  if (typeof repositoryArg !== 'string' || repositoryArg.trim().length === 0) {
+    throw new Error(
+      'repository is required: pass a canonical git remote URL (e.g. https://github.com/owner/repo) or a UUID identifying a local repository.',
+    );
+  }
+  // client#499 CR: a PRESENT working_repo_name must be a string; reject a
+  // present non-string rather than silently coercing it to the derived name.
+  if (workingRepoNameArg !== undefined && workingRepoNameArg !== null && typeof workingRepoNameArg !== 'string') {
+    throw new Error('working_repo_name must be a string when provided.');
+  }
+  const repoInput = repositoryArg.trim();
+  const nameArg = typeof workingRepoNameArg === 'string' ? workingRepoNameArg.trim() : '';
+
+  const canonical = canonicalizeWorkingRepoIdentity(repoInput);
+  if (canonical?.origin && canonical.name) {
+    const derivedName = canonical.name.split('/').pop() || canonical.name;
+    // Validate the FINAL name (explicit or derived) against the wire rule
+    // before any network use, for both repository kinds — fail closed.
+    return {
+      repository: { kind: 'origin', value: canonical.origin },
+      workingRepoName: assertValidWorkingRepoName(nameArg || derivedName),
+    };
+  }
+  if (REPOSITORY_UUID_RE.test(repoInput)) {
+    if (!nameArg) {
+      throw new Error(
+        'working_repo_name is required when repository is a local UUID — there is no origin URL to derive a name from.',
+      );
+    }
+    return { repository: { kind: 'local', value: repoInput }, workingRepoName: assertValidWorkingRepoName(nameArg) };
+  }
+  throw new Error(
+    'repository must be a canonical git remote URL (e.g. https://github.com/owner/repo) or a UUID identifying a local repository.',
+  );
+}
+
 export async function createCube(
   name: string | undefined,
   cubeDirective: string,
-  opts?: { template?: string; message_taxonomy?: MessageTaxonomy | null },
+  opts?: {
+    template?: string;
+    message_taxonomy?: MessageTaxonomy | null;
+    // client#499: the explicit repository binding (no cwd inference). Required.
+    repository?: CreateCubeRepository;
+    workingRepoName?: string;
+  },
   connection?: RemoteConnection,
-): Promise<{ id: string; name: string; cube_directive?: string; roles: any[]; drones?: any[]; [k: string]: any }> {
+): Promise<{ result: 'created' | 'resolved'; cube: { id: string; name: string; cube_directive?: string; roles: any[]; drones?: any[]; [k: string]: any } }> {
   if (!name?.trim()) throw new Error('Local Borg server cube creation requires a cube name');
   if (opts?.template !== undefined && opts.template !== 'default') {
     throw new Error('Local Borg server supports only the default cube seed');
   }
+  if (!opts?.repository || !opts?.workingRepoName) {
+    throw new Error('Local Borg server cube creation requires an explicit repository identity');
+  }
   const resolved = await localOwnerConnection(connection);
-  const created = await localConnectionMutation<{
-    cube_id: string;
-    human_seat_role_id: string;
-    default_worker_role_id: string;
-  }>(resolved, '/api/cubes', 'POST', {
+  // client#499 CR: strictly decode the response against the shared
+  // CreateCubeResponse contract — `result` MUST be 'created' or 'resolved'. A
+  // missing/unknown result FAILS CLOSED (throws) rather than falling through to
+  // 'created' and PATCHing an existing cube's directive.
+  const created = decodeCreateCubeResponse(await localConnectionMutation<unknown>(resolved, '/api/cubes', 'POST', {
     retry_key: randomUUID(),
     name: name.trim(),
+    working_repo_name: opts.workingRepoName,
+    repository: opts.repository,
     template: 'default',
-  });
-  if (!created?.cube_id) throw new Error('Local Borg server returned an invalid cube creation response');
+  }));
+  // client#499: the server homes one cube per repository. A 'resolved' result
+  // means this repository already has a cube — report it honestly and DO NOT
+  // PATCH its directive over the existing settings (the round-1 stomp defect).
+  if (created.result === 'resolved') {
+    return { result: 'resolved', cube: await getCube(created.cube_id, resolved) };
+  }
   const patch: Record<string, unknown> = { cube_directive: cubeDirective };
   if (opts?.message_taxonomy !== undefined) patch.message_taxonomy = opts.message_taxonomy;
   await localConnectionMutation(resolved, `/api/cubes/${created.cube_id}`, 'PATCH', patch);
-  return getCube(created.cube_id, resolved);
+  return { result: 'created', cube: await getCube(created.cube_id, resolved) };
 }
 
 /**

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

@@ -452,7 +452,7 @@ const BASE_TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_create-cube',
           description:
-            'Create a new cube. The server seeds a default "Drone" role atomically so the cube is assimilatable immediately. ' +
+            'Create a new cube bound to an explicit repository. The server homes ONE cube per repository: if the given repository already has a cube, this reports that existing cube and leaves its directive unchanged (it never overwrites it). The server seeds a default "Drone" role atomically so a newly-created cube is assimilatable immediately. ' +
             'Pass an optional `template` name to apply a richer role set instead (see borg_list-templates / borg_apply-template).',
           inputSchema: {
             type: 'object',
@@ -464,12 +464,22 @@ const BASE_TOOL_MANIFEST: ToolManifestEntry[] = [
                 maxLength: 120,
               },
               cube_directive: { type: 'string', description: 'Project-specific Markdown shown to every drone when it refreshes cube context.' },
+              repository: {
+                type: 'string',
+                description: 'The repository this cube binds to (explicit — not inferred from the working directory). Pass a canonical git remote URL (e.g. https://github.com/owner/repo) for a hosted repository, or a UUID identifying a local (no-remote) repository. The cube is homed to this repository; if it already has one, that existing cube is reported and its directive is left unchanged.',
+              },
+              working_repo_name: {
+                type: 'string',
+                description: 'Optional short display name for the repository (starts with a letter or digit; letters, digits, spaces, dots, underscores, or hyphens; max 120 bytes). Defaults to the repository segment of the URL; required when `repository` is a local UUID.',
+                pattern: '^[A-Za-z0-9][A-Za-z0-9 ._-]*$',
+                maxLength: 120,
+              },
               template: {
                 type: 'string',
-                description: 'Optional template name to apply after cube creation (e.g. "software-dev"). Roles are merged by name; the default Drone role gets overwritten by the template if a same-named role is in the template.',
+                description: 'Optional template name to apply after cube creation (e.g. "software-dev"). Roles are merged by name; the default Drone role gets overwritten by the template if a same-named role is in the template. Only applied when a cube is newly created — never to an already-existing repository cube.',
               },
             },
-            required: ['name', 'cube_directive'],
+            required: ['name', 'cube_directive', 'repository'],
           },
         },
         {
@@ -1063,11 +1073,14 @@ export const TOOL_OUTPUT_SCHEMAS: Record<string, OutputSchema> = {
     type: 'object',
     properties: {
       cube: CUBE_OUTPUT,
+      // client#499: 'created' = a new cube; 'resolved' = the repository already
+      // had a cube (reported, directive left unchanged).
+      result: { type: 'string', enum: ['created', 'resolved'] },
       template: { type: ['string', 'null'] },
       roles_created: { type: ['number', 'null'] },
       roles_updated: { type: ['number', 'null'] },
     },
-    required: ['cube', 'template'],
+    required: ['cube', 'result', 'template'],
   },
   'borg_update-cube': {
     type: 'object',

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,
     };
   }