docs: note that mock-endoify voids guard-refusal assertions

AGENTS.md

@@ -60,6 +60,10 @@ Testing:
 - Prefer `it.each()` for parameterized tests
 - Test titles should use concise verb forms without "should" (e.g., `it('creates and starts libp2p node', ...)` not `it('should create and start libp2p node', ...)`)
 - Use `vi.useFakeTimers()` for tests that rely on timers
+- Do not assert an exo guard refusal with `rejects.toThrow`: under `mock-endoify` a
+  guard violation rejects with `undefined`, which satisfies every matcher, so the
+  assertion passes with the guard removed too. Assert an observable consequence
+  instead, such as the guarded method never running
 
 TypeScript:
 

packages/repo-tools/src/test-utils/env/mock-endoify.ts

@@ -8,6 +8,12 @@ import { makePromiseKitMock } from '../promise-kit.ts';
 globalThis.lockdown = vi.fn((): void => undefined);
 globalThis.harden = vi.fn(<Value>(value: Value): Readonly<Value> => value);
 
+// Nothing `assert` guards throws under this shim. `@endo/exo` rejects a guard
+// violation through `assert.Fail`, so such a rejection carries `undefined`, and
+// `rejects.toThrow` counts an `undefined` rejection as matching anything —
+// assert a guard refusal by an observable consequence instead. Making `Fail`
+// throw does not fix that on its own: `@endo/patterns` calls `assert.fail`
+// while initializing, so a throwing stub stops test files from loading.
 const assertFn = vi.fn((): void => undefined);
 Object.assign(assertFn, {
   typeof: vi.fn(),