Docs: capture test performance guardrails

src/agents/AGENTS.md

@@ -14,6 +14,14 @@ signals, not just runner noise.
 - Keep expensive bootstrap, embedded runner, provider, plugin, and channel
   runtime work behind dependency injection or narrow helpers so tests can cover
   behavior without starting the whole runtime.
+- Treat channel/plugin lookups inside agent hot paths as suspect. If the code
+  only needs target parsing, peer-kind inference, setup hints, or static
+  descriptors, use a local pure helper or lightweight public artifact before
+  reaching for `getChannelPlugin()` / bundled runtime fallback.
+- In spawn/session/requester-origin logic, keep routing and delivery-context
+  normalization deterministic and runtime-free. Add explicit parser coverage for
+  channel-specific prefixes instead of loading a channel plugin just to classify
+  a target.
 - If moving coverage out of a slow integration test, preserve the exact
   production composition in a named helper and test that helper. Do not remove
   the behavior proof just because the old proof was slow.

src/channels/AGENTS.md

@@ -32,6 +32,17 @@ import from this tree directly.
 - For core discovery paths used by Gateway or agent tools, prefer lightweight
   bundled-plugin artifacts first and full channel plugin loading only as a
   fallback.
+- When a caller only needs already-registered plugin fixtures in a test, offer a
+  loaded-plugin-only mode instead of silently falling back to bundled runtime
+  materialization.
+- Put target parsing, thread-binding hints, native command descriptors, message
+  tool descriptors, gateway auth bypass paths, and setup-promotion hints in
+  small plugin-owned helpers reused by both the full channel plugin and any
+  lightweight artifact.
+- If a helper is called repeatedly by tests, install/reset the test plugin
+  registry in the same lifecycle scope as the runtime reset. A `beforeAll`
+  registry with `afterEach` runtime reset is a signal that later tests may fall
+  through to bundled/default runtime loading.
 - Do not mix static and dynamic imports for the same heavy module family across
   a channel boundary change. If the path should stay lazy, keep it lazy end to
   end.

src/gateway/AGENTS.md

@@ -14,6 +14,13 @@ runtime when they only need plugin-owned static descriptors.
   just to answer static questions.
 - If adding a new plugin-owned Gateway descriptor, add the core resolver,
   plugin artifact, and mirrored full-plugin export in the same change.
+- In Gateway server tests, reuse suite-level servers, authenticated contexts,
+  and clients when the behavior under test does not require a fresh
+  connect/auth handshake. Reset runtime state explicitly instead of restarting
+  the whole server per case.
+- Keep schedulers, pollers, and background loops disabled in manual-RPC tests
+  unless the test is specifically proving automatic scheduling or lifecycle
+  behavior.
 
 ## Verification
 

src/infra/outbound/AGENTS.md

@@ -0,0 +1,27 @@
+# Outbound Test Performance
+
+Outbound helpers sit on hot reply, action, media, and channel contract paths.
+Keep argument and payload tests narrow unless they are intentionally exercising
+real delivery.
+
+## Guardrails
+
+- Prefer pure param/spec/normalization helpers for send-argument, media-source,
+  alias, and payload-shape coverage. Do not import real delivery runtimes when
+  the test only asserts normalized arguments.
+- Avoid partial-real mocks with `importActual()` around broad outbound delivery
+  modules. Mock the exact seam under test, then cover the real delivery runtime
+  in a focused integration test.
+- Before discovering plugin-owned media/action metadata, first check whether the
+  call actually includes plugin-owned params. Standard send params should not
+  trigger bundled channel message-tool discovery.
+- Contract tests should reuse SDK/public helpers or narrow plugin-owned route
+  modules. Do not deep-load `runtime-api.ts` or `test-api.ts` barrels just to
+  access chunking, target parsing, or payload formatting helpers.
+
+## Verification
+
+- Benchmark the affected outbound test file before/after with
+  `pnpm test <file>`.
+- Run the closest media/action/payload contract test when changing a shared
+  outbound helper.

test/helpers/channels/AGENTS.md

@@ -18,6 +18,13 @@ This file adds channel-specific rules on top of `test/helpers/AGENTS.md`.
 - If `vi.mock(...)` hoisting would evaluate the module id too early, use
   `vi.doMock(...)` with the resolved module id instead of falling back to a
   hardcoded path.
+- For contract helpers, prefer minimal in-memory channel/plugin fixtures when
+  the contract only needs capabilities, session binding hooks, routing metadata,
+  or outbound payload helpers. Do not load broad `api.ts`, `runtime-api.ts`, or
+  `test-api.ts` barrels for incidental setup.
+- If a bundled plugin parser is the contract under test, load the narrow module
+  that owns that parser or promote a small public artifact. Avoid pulling a full
+  extension barrel just to parse a target id.
 
 ## Intent