claw-store/src/claw_cargo.rs

@@ -220,12 +220,15 @@ struct BuildArgs {
     /// Skip capture + upload on a miss. Useful for read-only cache use.
     #[arg(long)]
     no_upload: bool,
-    /// Field finding 2026-07-12: parallel chunk fetch on cache HIT.
-    /// Sequential BlobGetStream restore of 947 MiB on Pi 5 took 18s
-    /// (~53 MiB/s); parallel chunk fetches stack their per-stream
-    /// throughputs. Set to 1 to force sequential (matches pre-fix
-    /// behavior).
-    #[arg(long, default_value_t = 8)]
+    /// Field finding 2026-07-12/13: parallel chunk fetch on cache
+    /// HIT. Default `1` (sequential BlobGetStream) — measured on Pi 5
+    /// loopback, sequential beats parallel=8 by 70% (20s vs 34s)
+    /// because per-stream QUIC congestion control is more efficient
+    /// than N-way stream contention when the connection has no
+    /// per-stream ceiling. Opt in with `--parallel-restore N` on
+    /// cross-node connections where the per-stream cap actually bites
+    /// (WAN, tunneled links).
+    #[arg(long, default_value_t = 1)]
     parallel_restore: usize,
     /// Extra args passed verbatim to `cargo build` (after `--`).
     #[arg(last = true)]