| name | nw-throughput |
| description | Evidence-led orchestration for maximizing delivery throughput with causal fan-out, associative boundary composition, one heavy local box, and concise terminal evidence. |
| user-invocable | true |
nw-throughput
Constraint
The bottleneck is usually the shared machine or a causal boundary, not the
number of available agents. Keep cloud reasoning busy while allowing at most
one heavy local build/test/install workload. Measure load and stop adding lanes
when contention increases end-to-end wall time.
Fan out only independent work
Freeze the shared interface first, then assign disjoint file ownership in
worktrees created only by des worktree-admit --repo <root> --lane <name>;
its sole stdout path is the lane execution root. Never use Agent
isolation: "worktree" or raw git worktree add: both choose residence before
nWave can admit it. Good parallel work includes independent RCA hypotheses,
architecture reviews, oracle reviews, documentation projections and separate
delivery segments whose dependencies are explicit. Never parallelize two
writers over the same authority or an implementation before its oracle exists.
Compose boundaries as a segment tree
For ordered boundaries A -> B -> C -> D, validate disjoint pairs in parallel:
(A+B) || (C+D)
->
(A+B+C+D)
Each pair returns a compact certificate containing input/output identities,
preserved obligations, terminal observations and verdict. Compose certificates
associatively only when identities join. PASS is identity, FAIL is
absorbing and INDETERMINATE prevents global PASS. Pairwise PASS never implies
global PASS without the composition check.
Delivery scheduling
- Find the nearest measurable constraint and its shortest falsifier.
- Run several independent candidate probes when they answer the same question
without sharing mutable files or the heavy box.
- Stop losing candidates early; integrate only the best falsified survivor.
- Serialize exact command execution, release-shaped installation and other
heavy box work.
- Run one whole-delivery source-blind EXAMINE and one finalize after the
composed candidate, not once per internal segment.
- Record wall, processed tokens and cost from terminal telemetry. Setup,
waiting and retries are friction evidence but do not replace end-to-end
delivery time.
Long-session loops
Loops are opt-in and off by default. Explain WHAT they monitor, WHY the long
session benefits and HOW to stop them before asking consent. Arm only after
explicit acceptance and verify the scheduler actually registered them. Use
event-driven or sparse checks; never inject a large recurring prompt. A loop
suggests the next falsifier and consolidates evidence but cannot override the
durable authority or DeliveryContract.
Hygiene
An idle agent is not a completed artifact. Verify diff and terminal evidence,
then integrate or explicitly reject it.
An idle_notification with no terminal report within two minutes is
TERMINATED, not "alive". The root watcher's move is to read the lane's own
transcript and either consume the result found there or re-dispatch — never
probe "are you alive?" more than once (2026-08-21: two crafter PASS results
sat unread in idle lanes, 133 minutes lost on "it is still working").
Reinstall the runtime ONLY from the integrating lane, serialized, and NEVER
while an examiner lane or a dispatch is in flight on the shared box: a
reinstall rewrites the installed roster under every running role
(2026-08-21: seven concurrent reinstalls from fix lanes — three examiners died
silently, one dispatch crashed, 72 minutes lost). At each convergence point inventory
worktrees, reconcile every valuable diff, remove completed temporary worktrees
and leave no unowned WIP. The lifecycle owner releases only through
des worktree-release after terminal integration; absence or deletion of its
marker is never release. A finalized lane counts complete only after satisfying
nw-deliver's HAND OFF cleanup postcondition; do not duplicate its command or
verdict rules here. Never trade disk/process hygiene for apparent lane count.
