WIP: executor — pool TypeScript runner processes per harness module

[akrentsel]

Draft / WIP — opening for early review of the approach.

Problem

TypeScriptExecutor kept one Node runner process per module_path and held its mutex for the whole turn (model latency included), serializing every turn that shares a harness module — across all conversations and agents. The agent-scale eval measured this as the dominant throughput ceiling and worked around it with K module-path symlinks round-robin'd by the driver (multiplies the map key rather than fixing the executor; round-robin also idles a slow turn's slot).

Change

Replace the per-runner mutex with a per-module RunnerPool: a semaphore budget over a LIFO free-list of warm runners.

• Checkout by ownership — acquire hands the runner to the turn; the mutex is gone. A clean turn checks it back in warm; a failed turn drops it (the guest already exits on error, so "turn failed" == "process dead").
• Free assignment, LIFO reuse — any idle runner serves any turn; load concentrates on hot processes, the rest age out.
• Lazy spawn, TTL drain — spawn only when a turn arrives and no idle runner exists; idle runners expire after RUNNER_IDLE_TTL (5 min) via a one-shot per-check-in timer holding a Weak to the pool, so dropping the executor reaps them immediately and a quiescent pool drains to zero.
• Size via EXO_TS_RUNNER_POOL (default 4, clamped to 256).
• No protocol / guest (runner.ts) / exoharness changes.

Design + semantics: docs/ts-runner-pool-design.md.

Not in scope (deliberate)

• Multiplexing turns over one process (exec-id protocol) — later, and wants PR Turn coordination spec #113's redelivery first.
• Cross-process work distribution — PR Turn coordination spec #113's coordinator.
• Ordering/exclusion — stays above the executor (conversation send lock today, Turn coordination spec #113 leases after); the pool guarantees none.

Tests

• 6 unit tests (fake spawner, paused clock): LIFO reuse, drop-discards-and-frees-capacity, saturated-acquire-blocks-then-reuses, TTL expiry, checkout-invalidates-stale-timer, Weak-not-pinned-on-drop.
• Ignored end-to-end test driving real Node runners (--ignored): 4 concurrent turns on one module → 4 distinct runner PIDs, overlapping, + warm reuse.

Measured (agent-scale, synthetic mock model, single box)

• vs old serialized executor: ~6× throughput, ~5× lower p50 latency (batch, 8-way).
• vs the symlink workaround at equal 8-way: +19% throughput, −23% p50, ~equal peak memory.
• Under light/bursty load: ~40% lower mean memory (lazy spawn + reuse vs 8 pinned runners).

Open / follow-ups

• Per-module runners map entry is never removed (minor; module set normally fixed).
• No global ceiling across modules (only per-module pinned + env clamp).

🤖 Draft generated with assistance from Claude.

[akrentsel]

Please don't review yet – am editing still.