Add multi-base chain modelling, fix price-band-aware demand/supply, tranche-split sell tool

- puga/network.py + tools/network.py: model a multi-base chain (e.g. mine LST at one base,
  ship it, consume it at another). Simulates each base independently, nets a transferred
  material's producer-surplus against consumer-need, charges real freight only on what's
  moved, cm_free for a founding covered by a Core Module Kit. Worked example in plans/chains/.
- puga/saturation.py: real price-band filtering. FIO's order_book NarrowPriceBandLow/High and
  WidePriceBandLow/High match APEX's own displayed Price Band exactly (verified live) - an
  order outside it is a stale artifact, not just uncompetitive. Added in_band() and
  effective_demand(); effective_supply() gained the same hard band filter alongside its
  existing soft vwap-proximity filter (renamed that param mult to free up `band`). Wired into
  tools/scan.py stage 2 in place of the raw, unfiltered demand figure. Was flagged as an
  unimplemented refinement in saturation-design.md since the original design review.
- tools/sell.py: self-contained tranche split (aggressive tranche capped at a volume quantile,
  median normally or 80th pct with --tight when a payment is imminent and stockout risk
  outweighs margin; patient tranche priced under the next competitor tier). Instant-bid
  comparison moved behind --show-bid (off by default).
- Docs and roadmap updated accordingly.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

tests/test_saturation.py

@@ -38,3 +38,22 @@ def test_effective_supply_ignores_stale_far_asks():
     asks = [(100, 10), (110, 20), (150, 1500)]
     assert s.effective_supply(asks, 100) == 30          # 1500 units at 1.5x are not competition
     assert s.effective_supply(asks, None) == 1530
+
+
+def test_effective_supply_hard_filters_out_of_band_asks():
+    asks = [(100, 10), (110, 20), (150, 1500)]
+    # band excludes the 150 tier outright, even though ref_price=None would otherwise count it
+    assert s.effective_supply(asks, None, band=(50, 120)) == 30
+
+
+def test_in_band():
+    assert s.in_band(700, (663, 16575)) is True
+    assert s.in_band(334, (663, 16575)) is False
+    assert s.in_band(20000, (663, 16575)) is False
+    assert s.in_band(1, None) is True                   # no band given: nothing excluded
+
+
+def test_effective_demand_excludes_stale_bids_below_the_band():
+    bids = [(4550, 8), (4200, 250), (2810, 8), (334, 19)]
+    assert s.effective_demand(bids, band=(663, 16575)) == 8 + 250 + 8   # the 334 bid is stale, excluded
+    assert s.effective_demand(bids, band=None) == 8 + 250 + 8 + 19