v0.102.1: agents adversarial-test pass + doc accuracy fixes

Adversarial whitebox test of v0.102.0's STM + agent surfaces
(Clojure-level, C-API, and combinations) uncovered a misleading
thread-budget message: agent_worker_ensure said embedders need
">= 2 to allow one agent worker plus the embedder thread", but
the embedder thread does NOT count against thread_limit. Correct
wording: >= 1 for one worker; >= 2 if both send and send-off are
used concurrently.

The corresponding STM page, Compatibility Matrix, Intentional
Divergences, Coming-from-Clojure page, mino_send docstring, and
the C-API agents cookbook example are updated separately
(downstream-repo commits).

A pre-existing future-worker thread_count starvation issue
identified during the run is filed as NEEDS-DESIGN in
.local/BUGS.md (fix requires a threading-model refactor).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: leifericf

CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## Unreleased
 
+## v0.102.1 — Agents adversarial-test pass: doc accuracy fixes
+
+Adversarial whitebox test of the v0.102.0 STM + Agent surfaces
+(both Clojure-level and the new C-API perimeter, individually and
+in combination) ran 70+ probes. All real findings are
+documentation accuracy issues -- no behavior changed.
+
+- Fix the misleading thread-budget message in `agent_worker_ensure`
+  (and the corresponding mino-site / `mino.h` / Coming-from-Clojure
+  copy). The embedder thread does NOT count against
+  `thread_limit`, so the previous wording (">= 2 to allow one
+  agent worker plus the embedder thread") was wrong. Correct
+  wording: ">= 1 for one agent worker; >= 2 if both send and
+  send-off are used concurrently". The cookbook's `agents.c`,
+  the STM page, the Compatibility Matrix, the Intentional
+  Divergences page, and the Coming-from-Clojure page all updated
+  to match.
+- Coming-from-Clojure previously said `agent / send / send-off
+  / pmap are not provided` when `thread_limit <= 1`. Updated:
+  `agent` itself ships and constructors work; `send` /
+  `send-off` throw MTH001 when their pool's worker can't spawn;
+  only `pmap` is genuinely absent.
+- Compatibility Matrix's `send-via` row said "send and send-off
+  share the same per-state worker." Stale -- v0.102.0 split them
+  into POOLED + SOLO. Updated.
+- STM page intro paragraph said "a worker thread drains the queue."
+  Updated to reflect both pools.
+- New adversarial probes added under `.local/adversarial/` for
+  future regression coverage of the agent surfaces.
+
+A pre-existing thread-count bookkeeping issue (`(future ...)`
+worker decrements lag the embedder under tight-loop contention,
+so a subsequent `(send ...)` may throw MTH001 even when fire-
+and-forget futures have logically completed) was identified and
+filed as NEEDS-DESIGN in `.local/BUGS.md`. The fix requires a
+non-trivial threading-model refactor; deferred to a dedicated
+cycle. Workaround: deref the last future or await an agent before
+spawning more workers.
+
 ## v0.102.0 — Agents finish MVP: async dispatch + pool split + C-API
 
 Agent execution model removes the synchronous-on-the-calling-thread
@@ -64,9 +103,9 @@ public C-API perimeter for embedders.
   pools still serialize, so the user-visible effect is the same
   as before, but the queues are independent: a long-running
   send-off action does not stall pending sends, and vice versa.
-  Each pool's worker counts against `thread_limit`, so embedders
-  that want both shapes alive concurrently must raise the limit
-  to at least 3 (embedder + POOLED + SOLO worker). The split is
+  Each pool's worker counts against `thread_limit` (the embedder
+  thread does not). Embedders that want both shapes alive
+  concurrently must raise the limit to at least 2. The split is
   also a clean seam for a future SOLO-yields-eval-lock-during-
   blocking-IO design without further user-facing churn.
 - Public C-API entries: `mino_send`, `mino_send_off`, `mino_await`,

src/mino.h

@@ -28,7 +28,7 @@
  */
 #define MINO_VERSION_MAJOR 0
 #define MINO_VERSION_MINOR 102
-#define MINO_VERSION_PATCH 0
+#define MINO_VERSION_PATCH 1
 
 /*
  * Human-readable version string of the *linked* runtime, e.g. "0.48.0".
@@ -588,8 +588,11 @@ int         mino_is_agent(const mino_val_t *v);
  *   - agent was created in a different state (MST007),
  *   - agents have been shut down (MST008),
  *   - the agent is failed and its error mode is :fail (MST002),
- *   - the host has not granted enough threads to spawn the worker
- *     (MTH001) -- raise via mino_set_thread_limit (>= 2).
+ *   - the host has not granted enough thread budget to spawn the
+ *     pool's worker (MTH001) -- the embedder thread does not count
+ *     against the limit; raise via mino_set_thread_limit (>= 1 for
+ *     one agent worker; >= 2 if both send and send-off are used
+ *     concurrently; more if mixing with futures / host threads).
  *
  * Inside a transaction, the action is queued and only fires after a
  * successful commit, matching JVM canon. */

src/prim/agent.c

@@ -11,13 +11,15 @@
  *
  * Threading contract:
  *
- *  - Each pool's worker counts against S->thread_limit, so a host
- *    that has granted only one thread (default thread_limit == 1)
- *    can have only one shape of send alive at a time. send /
- *    send-off throw MTH001 if the host hasn't granted enough threads
- *    to spawn the requested pool's worker; embedders that want both
- *    shapes concurrently must raise the limit to >= 2 (in addition
- *    to the embedder thread). Standalone `./mino` raises thread_limit
+ *  - Each pool's worker counts against S->thread_limit (the embedder
+ *    thread does NOT). Default thread_limit is 1, so a host that
+ *    hasn't called mino_set_thread_limit can have one agent worker
+ *    OR one future OR one host thread alive at a time. send /
+ *    send-off throw MTH001 if the host hasn't granted enough thread
+ *    budget to spawn the requested pool's worker. Embedders that
+ *    want both POOLED and SOLO alive concurrently must raise the
+ *    limit to >= 2; mixing with futures / host threads requires
+ *    correspondingly more. Standalone `./mino` raises thread_limit
  *    to cpu_count after install_all so the REPL works out of the box.
  *
  *  - Each worker is lazy-spawned on the first send/send-off into its
@@ -573,9 +575,10 @@ static int agent_worker_ensure(mino_state_t *S, agent_pool_kind_t kind)
     if (S->thread_count >= S->thread_limit) {
         prim_throw_classified(S, "mino/thread-limit-exceeded", "MTH001",
             "agent dispatch requires a host-granted worker thread; "
-            "raise via mino_set_thread_limit (>= 2 to allow one agent "
-            "worker plus the embedder thread; >= 3 if both send and "
-            "send-off are used concurrently)");
+            "raise via mino_set_thread_limit (>= 1 for one agent "
+            "worker; >= 2 if both send and send-off are used "
+            "concurrently). The embedder thread does not count "
+            "against the limit -- only spawned workers do.");
         return 1;
     }
     S->multi_threaded = 1;